install-script fix

Author: MatrixFounder

System/scripts/install.py

@@ -61,6 +61,8 @@ def _parse_argv(argv: list[str]) -> argparse.Namespace:
     p_update.add_argument("--target", type=Path, default=Path.cwd())
     p_update.add_argument("--prune", action="store_true",
                           help="Remove symlinks whose source no longer exists")
+    p_update.add_argument("--no-gitignore", action="store_true",
+                          help="Re-sync symlinks without touching .gitignore")
 
     p_uninstall = sub.add_parser("uninstall", help="Remove framework artifacts")
     p_uninstall.add_argument("--target", type=Path, default=Path.cwd())

System/scripts/installer/cli.py

@@ -505,18 +505,23 @@ def _cmd_update(args) -> int:
         if args.prune:
             pruned += _prune_stale_symlinks(target_dir, agentic)
 
-    # Refresh the .gitignore block. Two reasons this cannot be skipped: linking
-    # and pruning above change which entries are project-local, so the
-    # `!`-exception list goes stale; and a framework upgrade may change the block
-    # body itself, which is the only way a shipped rule fix reaches an existing
-    # project. `switch` gets this via _cmd_install — `update` used to miss it.
-    try:
-        state["gitignore_block_hash"] = update_gitignore(target, profile, state)
-    except IntegrityError as exc:
-        # The block was hand-edited. The symlink re-sync above already succeeded,
-        # so warn and keep the run green rather than aborting half-done; `install
-        # --force` is the deliberate way to overwrite a customised block.
-        print(f"warning: .gitignore block left untouched — {exc}", flush=True)
+    # Refresh the .gitignore block. Two reasons it is on by default: linking and
+    # pruning above change which entries are project-local, so the `!`-exception
+    # list goes stale; and a framework upgrade may change the block body itself,
+    # which is the only way a shipped rule fix reaches an existing project.
+    # `switch` gets this via _cmd_install — `update` used to miss it. `install`
+    # has always offered an opt-out; `update` now offers the same one, so a
+    # project that manages its own .gitignore is not forced to hand-edit the
+    # block (which costs it every future block fix).
+    if not getattr(args, "no_gitignore", False):
+        try:
+            state["gitignore_block_hash"] = update_gitignore(target, profile, state)
+        except IntegrityError as exc:
+            # The block was hand-edited. The symlink re-sync above already
+            # succeeded, so warn and keep the run green rather than aborting
+            # half-done; `install --force` is the deliberate way to overwrite a
+            # customised block.
+            print(f"warning: .gitignore block left untouched — {exc}", flush=True)
 
     state["managed_paths"] = state_mod.collect_managed_symlinks(target)
     state_mod.save_state(target, state)

System/scripts/installer/gitignore.py

@@ -28,12 +28,30 @@ def _points_into_agentic(entry: Path, target: Path) -> bool:
     return resolves_inside(entry, Path(target) / ".agentic-development")
 
 
+def _survives_a_clone(entry: Path, target: Path) -> bool:
+    """True if a fresh clone of ``target`` would still resolve ``entry``.
+
+    A real file or directory always qualifies. A symlink qualifies only when it
+    resolves back inside the project, because its destination is then part of
+    the same repository. A symlink leaving the project — ``.claude/skills/x`` →
+    ``~/ExternalTools/...`` — names a path that exists on this machine alone, so
+    committing it hands every other clone a dangling link.
+
+    This is the same argument :func:`build_block_body` already makes about the
+    framework's own symlink, which is why that pattern carries no trailing slash.
+    """
+    if not entry.is_symlink():
+        return True
+    return resolves_inside(entry, target)
+
+
 def scan_local_exceptions(target: Path) -> list[str]:
     """Return sorted ``!/path`` lines for project-local (non-framework) entries.
 
     An entry is project-local when it is not a symlink, or is a symlink that
-    does not resolve into ``.agentic-development/``. Dotfiles are skipped.
-    A broken framework symlink is reported as a warning and not emitted.
+    resolves inside the project and not into ``.agentic-development/``. Dotfiles
+    are skipped. Two kinds of entry are reported as a warning and not emitted: a
+    broken framework symlink, and a symlink pointing outside the project.
     """
     target = Path(target)
     exceptions: list[str] = []
@@ -52,6 +70,14 @@ def scan_local_exceptions(target: Path) -> list[str]:
                         flush=True,
                     )
                 continue  # framework symlink — never a project-local exception
+            if not _survives_a_clone(entry, target):
+                print(
+                    f"warning: {entry} resolves outside the project "
+                    f"({Path(entry).resolve()}) — left ignored, because a "
+                    f"committed link to it would dangle on every other clone",
+                    flush=True,
+                )
+                continue
             exceptions.append(f"!/{rel}/{entry.name}")
     return sorted(exceptions)
 

tests/installer/test_gitignore.py

@@ -4,7 +4,10 @@
 """
 from __future__ import annotations
 
+import io
 import os
+from contextlib import redirect_stdout
+from pathlib import Path
 
 from _base import FRAMEWORK_ROOT, InstallerTestCase
 from installer.errors import IntegrityError
@@ -104,6 +107,55 @@ def test_broken_framework_symlink_warned_not_added(self) -> None:
         result = scan_local_exceptions(self.target)
         self.assertEqual(result, [])  # broken framework link is not an exception
 
+    # -- symlinks leaving the project ------------------------------------
+    # A `!` on one of these invites `git add -A` to commit a path that exists on
+    # the author's machine only. Measured on a real project: one `update` added
+    # 15 such lines for skills symlinked out of ~/ExternalTools.
+
+    def _outbound_symlink(self, name: str) -> Path:
+        """Symlink ``name`` at a real directory outside the target project."""
+        outside = self.tmp / "outside" / name
+        outside.mkdir(parents=True)
+        os.symlink(outside, self.skills / name)
+        return outside
+
+    def test_outbound_symlink_not_exception(self) -> None:
+        self._outbound_symlink("external-skill")
+        self.assertEqual(scan_local_exceptions(self.target), [])
+
+    def test_outbound_symlink_warned(self) -> None:
+        self._outbound_symlink("external-skill")
+        with redirect_stdout(io.StringIO()) as out:
+            scan_local_exceptions(self.target)
+        self.assertIn("external-skill", out.getvalue())
+        self.assertIn("resolves outside the project", out.getvalue())
+
+    def test_inbound_symlink_is_exception(self) -> None:
+        # `.claude/skills/x` -> `.agent/skills/x` is relative and in-repo, so a
+        # clone resolves it; it stays trackable.
+        (self.skills / "owned").mkdir()
+        claude_skills = self.target / ".claude" / "skills"
+        claude_skills.mkdir(parents=True)
+        os.symlink("../../.agent/skills/owned", claude_skills / "owned")
+        self.assertEqual(
+            scan_local_exceptions(self.target),
+            ["!/.agent/skills/owned", "!/.claude/skills/owned"],
+        )
+
+    def test_outbound_symlink_stays_out_across_repeated_updates(self) -> None:
+        # The block is regenerated on every `update`, so a one-off correct run
+        # proves nothing: the defect must not come back on the second pass.
+        self._outbound_symlink("external-skill")
+        state: dict = {}
+        with redirect_stdout(io.StringIO()):
+            state["gitignore_block_hash"] = update_gitignore(
+                self.target, _CLAUDE, state)
+            update_gitignore(self.target, _CLAUDE, state)
+        body = extract_block(
+            (self.target / ".gitignore").read_text(encoding="utf-8"),
+            GITIGNORE_MARKERS)
+        self.assertNotIn("external-skill", body)
+
 
 class TestUpdateGitignore(InstallerTestCase):
 

tests/installer/test_subcommands.py

@@ -39,7 +39,7 @@ def _uninstall_ns(target, **kw) -> argparse.Namespace:
 
 
 def _update_ns(target, **kw) -> argparse.Namespace:
-    d = dict(command="update", target=target, prune=False)
+    d = dict(command="update", target=target, prune=False, no_gitignore=False)
     d.update(kw)
     return argparse.Namespace(**d)
 
@@ -190,6 +190,23 @@ def test_update_refreshes_stale_gitignore_block(self) -> None:
         self.assertIn("/.agentic-development", lines)
         self.assertNotIn("/stale-rule", lines)
 
+    def test_update_no_gitignore_leaves_the_file_alone(self) -> None:
+        # `install` has always offered this opt-out; `update` did not, so a
+        # project that manages its own .gitignore had to hand-edit the managed
+        # block — which costs it every future shipped block fix.
+        target = self.make_target()
+        main(_install_ns(target))
+        gi = target / ".gitignore"
+        self._restate_gitignore(target, "/.agentic-development/\n/stale-rule")
+        before = gi.read_text()
+        state_file = target / ".agentic-installer-state.json"
+        hash_before = json.loads(state_file.read_text())["gitignore_block_hash"]
+        self.assertEqual(main(_update_ns(target, no_gitignore=True)), 0)
+        self.assertEqual(gi.read_text(), before)
+        self.assertEqual(
+            json.loads(state_file.read_text())["gitignore_block_hash"],
+            hash_before)
+
     def test_update_survives_hand_edited_gitignore(self) -> None:
         # Block edited by hand => hash mismatch. The symlink re-sync has already
         # succeeded, so update warns and stays green instead of aborting midway,