agent-toggle 0.1.0__py3-none-any.whl

agent_toggle/cli.py

@@ -0,0 +1,498 @@
+"""Temporarily disable / re-enable AI-agent resources across harnesses.
+
+Skills, agents, commands, rules, plugins and MCP servers can all be parked and put
+back. Nothing is ever deleted.
+
+Supported harnesses: claude (Claude Code), codex, grok, opencode, openclaw, copilot,
+vibe, devin, agy. Not every harness has every resource type; unsupported pairs fail
+loudly instead of silently doing nothing.
+
+State lives in ONE place ($HOME/.agent-toggle/), never as sidecar files next
+to the targets -- a user's `git status` must not change because of our
+bookkeeping.
+
+Usage:
+    agent_toggle.py ui [--dry-run]             # interactive picker (curses)
+    agent_toggle.py cost [--type T]            # startup token estimates, biggest first
+    agent_toggle.py disable <type> <name>...   [--harness H] [--dry-run]
+    agent_toggle.py enable  <type> <name>...   [--harness H] [--dry-run]
+    agent_toggle.py enable --all [--harness H] [--dry-run]   # restore everything
+    agent_toggle.py undo [--dry-run]           # reverse the last logged batch
+    agent_toggle.py disable|enable <type> <name>... --project <dir>   # a repo's .claude/ + .mcp.json
+    agent_toggle.py enable --all --project <dir> | profile save|apply|diff ... --project <dir>
+    agent_toggle.py list [<type>] [--project D] # what is currently disabled
+    agent_toggle.py status                     # health check
+    agent_toggle.py doctor [--harness H]       # read-only drift + state check; exit 1 on problems
+    agent_toggle.py migrate                    # import old ~/.claude-toggle state
+    agent_toggle.py profile save|apply|diff|list [name|file] [--out F] [--dry-run]
+    agent_toggle.py install-shims [--dry-run]  # write the skill shim into each harness
+
+    <type> = skill | agent | command | rule | plugin | mcp
+    --json prints exactly one JSON document; exit codes: 0 ok, 1 partial
+    failure, 2 usage error, 3 locked, 4 unsupported pair / harness missing.
+"""
+from __future__ import annotations
+
+import argparse
+import contextlib
+import io
+import os
+import sys
+import traceback
+from pathlib import Path
+
+from . import __version__, cost, doctor, fs, ops, profiles, store, undo
+from .backends.plugin_cli import claude_bin
+from .fs import gitignored
+from .harnesses import TYPES, harness_of, harnesses, project_view
+from .mechanisms import dir_view, validate_name
+from .output import COLOR_MODES, CliError, Result, die, scan_color, use_color
+from .store import load_state, save_state
+
+
+def project_of(key: str, entry: dict) -> str | None:
+    """The --project dir of a project-scope entry (`harness@<sha8>:...`), else None.
+    (A claude local-scope mcp entry's `project` is its cwd, not a --project scope.)"""
+    try:
+        scoped = store.parse_key(key)[1]
+    except ValueError:
+        return None
+    return str(entry.get("project")) if scoped else None
+
+
+def _list_of(v: dict, key: str) -> list:
+    """A state entry's list field; a hand-edited non-list counts as empty."""
+    x = v.get(key)
+    return x if isinstance(x, list) else []
+
+
+def cmd_list(type_filter: str | None, state: dict, out: Result,
+             harness: str | None = None, project: str | None = None) -> None:
+    if project is not None:                  # one project's entries only
+        project = str(project_view(project).project)       # exit 4 like disable --project
+        state = store.scope_state(state, project)
+    items = [(project_of(k, v), v) for k, v in state["disabled"].items()
+             if (not type_filter or v.get("type") == type_filter)
+             and (not harness or harness in (v.get("harness"), *_list_of(v, "shared_with")))]
+    if not items:
+        out.say("nothing disabled")
+        return
+    for proj, v in sorted(items, key=lambda x: (str(x[1].get("harness", "")), str(x[1].get("type")),
+                                                 str(x[1].get("name")), x[0] or "")):
+        shared = ", ".join(map(str, _list_of(v, "shared_with")))
+        extra = f"  +{len(_list_of(v, 'companions'))} files" if _list_of(v, "companions") else ""
+        extra += f"  shared with {shared}" if shared else ""
+        extra += f"  project {proj}" if proj else ""
+        at = str(v.get("at", "?"))
+        who = out.paint(f"{v.get('harness', '?')!s:<9}", "cyan")
+        out.say(f"  {who} {v.get('type')!s:<8} {v.get('name')!s:<36} "
+                + out.paint(f"since {at[:10]}{extra}", "dim"))
+        out.row(v.get("harness"), v.get("type"), v.get("name"), "list", "disabled",
+                f"since {at[:10]}", show=False, at=v.get("at"),
+                mechanism=v.get("mechanism"), companions=len(_list_of(v, "companions")),
+                shared_with=_list_of(v, "shared_with"), **({"project": proj} if proj else {}))
+    out.say(f"\n{len(items)} disabled")
+
+
+def cmd_status(state: dict, out: Result, only: str | None = None) -> None:
+    legacy_state_dir = fs.legacy_state_dir()
+    claude = claude_bin()
+    legacy = None
+    out.say(f"state   {fs.state_file()}  ({len(state['disabled'])} disabled)")
+    out.say(f"log     {fs.log_file()}")
+    loose = [p for p in (fs.state_file(), *fs.backup_dir().glob("*.json"))
+             if fs.too_open(p, 0o077)]
+    for p in loose:
+        out.say(f"WARNING {p} is looser than 0600 -- fix: chmod 600 {p}", warn=True)
+    if fs.too_open(fs.state_dir()):
+        out.say(f"WARNING {fs.state_dir()} is group/world readable -- backups may hold "
+                f"auth headers; fix: chmod 700 {fs.state_dir()}", warn=True)
+    out.say(f"claude  {claude or 'NOT FOUND -- plugin/mcp actions will fail'}")
+    if legacy_state_dir.exists():
+        done = any(k.startswith("claude:") for k in state["disabled"])
+        legacy = "imported" if done else "present"
+        out.say(f"legacy  {legacy_state_dir} present -- "
+                + ("already imported; safe to delete once verified" if done
+                   else "run `migrate` to import it"))
+    out.row(None, None, None, "status", "ok", "", show=False,
+            state_file=str(fs.state_file()), log_file=str(fs.log_file()),
+            disabled=len(state["disabled"]), claude_cli=claude, legacy=legacy)
+    table = harnesses()
+    for hname, h in table.items():
+        if only and hname != only:
+            continue
+        home, backend = h.home, h.backend
+        if not home.is_dir():
+            out.say(f"{out.paint(f'{hname:<9}', 'cyan')} {home}  "
+                    + out.paint("(not installed)", "dim"))
+            out.row(hname, None, None, "status", "not-installed", "", show=False,
+                    home=str(home))
+            continue
+        bits = [t for t in h.types
+                if t not in h.dirs or any((home / s).is_dir() for s in h.dirs[t])]
+        shown = ",".join(bits) if h.types else "(found, nothing supported yet)"
+        out.say(f"{out.paint(f'{hname:<9}', 'cyan')} {home}  types: {shown}  mcp: {backend or '-'}")
+        info: dict = {}
+        for t in bits:
+            if t not in h.dirs:
+                continue
+            # any harness's entry: a shared dir's items are tracked under its owner
+            tracked = {e["parked_at"] for e in state["disabled"].values()
+                       if e.get("type") == t and e.get("parked_at")}
+            items: list[Path] = []
+            untracked: list[Path] = []
+            twins: list[str] = []
+            ign = True
+            shared: set[str] = set()
+            for sub in h.dirs[t]:
+                view = dir_view(table, hname, t, home, sub)
+                parked = view.parked
+                shared.update(set(view.sharers) - {hname})
+                if markers := fs.sync_markers(view.live):
+                    out.say(f"                   ! {view.live} carries {', '.join(markers)} -- a "
+                            f"sync job may re-create parked items; park in the source harness",
+                            warn=True)
+                # Skills are directories; agents and commands are files that may
+                # sit one level down. Counting rglob("*") for skills would report
+                # every file inside every skill.
+                if not parked.is_dir():
+                    found = []
+                elif t == "skill":
+                    found = list(parked.iterdir())
+                else:
+                    found = [p for p in parked.rglob("*") if p.is_file()]
+                items += found
+                ign = ign and gitignored(
+                    parked, home if view.owner == hname else table[view.owner].home)
+                u, tw = parked_drift(found, parked, home / sub, tracked)
+                untracked += u
+                twins += tw
+            out.say(f"          {t:<8} {len(items):>3} parked  "
+                    f"[{'gitignored' if ign else 'NOT gitignored'}]")
+            if untracked:
+                out.say(f"                   ! {len(untracked)} untracked (parked outside this tool)"
+                        + (f", {len(twins)} also live: {', '.join(twins)}"
+                           " -- stale copies; `disable` of these names will refuse" if twins else ""),
+                        warn=True)
+            if shared:
+                out.say(f"                   shared dir with: {', '.join(sorted(shared))} "
+                        f"(disable here also affects them)")
+            info[t] = {"parked": len(items), "gitignored": ign, "untracked": len(untracked),
+                       "live_twins": twins, "shared_with": sorted(shared)}
+        out.row(hname, None, None, "status", "installed", "", show=False,
+                home=str(home), types=bits, mcp=backend, parked=info)
+    projects: dict[tuple, int] = {}
+    for k, e in state["disabled"].items():
+        if (proj := project_of(k, e)) is not None:
+            projects[e.get("harness"), proj] = projects.get((e.get("harness"), proj), 0) + 1
+    for (hname, proj), n in sorted(projects.items(), key=str):
+        out.say(f"project {proj}  ({n} parked under {fs.parked_dir()})")
+        out.row(hname, None, None, "status", "project", "", show=False, project=proj, parked=n)
+
+
+def parked_drift(items: list[Path], parked: Path, live: Path,
+                 tracked: set[str]) -> tuple[list[Path], list[str]]:
+    """Parked items with no state entry, and the names among them that also exist live."""
+    untracked = [p for p in items if str(p) not in tracked]
+    twins = sorted(str(p.relative_to(parked)) for p in untracked
+                   if (live / p.relative_to(parked)).exists() or (live / p.relative_to(parked)).is_symlink())
+    return untracked, twins
+
+
+def cmd_cost(state: dict, out: Result, harness: str | None = None,
+             type_: str | None = None) -> None:
+    """Estimated startup tokens per item, biggest first. Read-only."""
+    items = [i for i in cost.inventory(store.scope_state(state), harnesses(), out.warn)
+             if (not harness or harness in (i.harness, *i.shared_with))
+             and (not type_ or i.type == type_)]
+    items.sort(key=lambda i: (-i.tokens, -i.would_save, i.harness, i.type, i.name))
+    for i in items:
+        what = (f"~{i.tokens:>6} tok  {i.basis}" if i.enabled
+                else f"~{0:>6} tok  parked, would save ~{i.would_save} tok  ({i.basis})")
+        extra = f"  shared with {', '.join(i.shared_with)}" if i.shared_with else ""
+        tail = what + extra
+        out.say(f"  {out.paint(f'{i.harness:<9}', 'cyan')} {i.type:<8} {i.name:<36} "
+                + (tail if i.enabled else out.paint(tail, "dim")))
+        out.row(i.harness, i.type, i.name, "cost", "ok", i.basis, show=False,
+                enabled=i.enabled, tokens=i.tokens, would_save=i.would_save,
+                chars=i.chars, shared_with=list(i.shared_with))
+    live = sum(i.tokens for i in items)
+    saved = sum(i.would_save for i in items)
+    out.say(f"\n{len(items)} item(s): ~{live} tok loaded at startup; "
+            f"~{saved} tok already saved by parked items  "
+            f"(chars/{cost.CHARS_PER_TOKEN} estimate, +-25%)")
+    out.row(harness, type_, None, "cost", "ok", "total", show=False, items=len(items),
+            total_tokens=live, saved_tokens=saved, formula=cost.FORMULA)
+
+
+def cmd_ui(state: dict, out: Result, dry_run: bool = False) -> None:
+    try:
+        from .ui import picker as ui
+    except ImportError as e:                 # no curses build (rare)
+        die(f"interactive UI unavailable: {e}")
+    changes = ui.pick(store.scope_state(state), harnesses(), plugins=not dry_run,
+                      color=use_color(sys.stdout, out.color))
+    if changes is None:
+        out.say("cancelled -- nothing changed")
+        return
+    if not changes:
+        out.say("no changes")
+        return
+    plan = sorted((ops.Op(r.harness, r.type, "enable" if r.staged else "disable", r.name)
+                   for r in changes), key=lambda op: op[:3])
+    # the picker's state copy may be stale: apply_plan re-reads it under the lock
+    ops.apply_plan(plan, out, dry_run, batch=store.BATCH, headers=True)
+    if dry_run:
+        out.say("\ndry run -- nothing changed")
+        return
+    if any(r.type in ("mcp", "plugin") for r in changes):
+        out.say("\nMCP/plugin changed -- open a NEW session for it to take effect.")
+
+
+def cmd_toggle(args: argparse.Namespace, out: Result) -> None:
+    action, type_, names, harness = args.command, args.type, args.names, args.harness
+    if not type_ or not names:
+        die(f"{action} needs <type> <name>... (or `enable --all`)", 2)
+    for name in names:
+        validate_name(name)
+    if args.project is not None:
+        # project scope: claude layout dir types only (DESIGN s5.5)
+        if harness != "claude":
+            die(f"--project supports only the claude layout, not {harness}", 4)
+        h = project_view(args.project)
+        if type_ not in h.types:
+            die(f"--project supports {', '.join(h.types)} (not {type_})", 4)
+        ops.apply_plan([ops.Op(harness, type_, action, n, str(h.project)) for n in names],
+                       out, args.dry_run, batch=store.BATCH)
+        return
+    h = harness_of(harness)
+    home, supported = h.home, h.types
+    if not home.is_dir():
+        die(f"{harness} is not installed ({home} does not exist)", 4)
+    if type_ not in supported:
+        have = f"it has: {', '.join(supported)}" if supported else "no supported types"
+        die(f"{harness} has no {type_} support ({have})", 4)
+
+    ops.apply_plan([ops.Op(harness, type_, action, n) for n in names], out, args.dry_run,
+                   batch=store.BATCH)
+
+
+def cmd_migrate(out: Result) -> None:
+    buf = io.StringIO()             # store.migrate prints; fold it into the result
+    with fs.lock():
+        state = load_state()
+        with contextlib.redirect_stdout(buf):
+            store.migrate(state)
+        save_state(state)
+    lines = buf.getvalue().splitlines()
+    out.say(buf.getvalue().rstrip("\n"))
+    out.row(None, None, None, "migrate", "ok", "; ".join(lines), show=False)
+
+
+SHIM_TEMPLATE = Path(__file__).with_name("shims") / "claude.md.tmpl"
+
+
+def cmd_install_shims(args: argparse.Namespace, out: Result) -> None:
+    """Write <home>/skills/agent-toggle/SKILL.md into every installed harness that
+    supports skills; keep park dirs out of an existing harness-home .gitignore."""
+    template = SHIM_TEMPLATE.read_text(encoding="utf-8")
+    root = Path(__file__).resolve().parent.parent
+    if (root / "agent_toggle.py").is_file():
+        # Harness dirs often sync across machines: write `~`-relative under $HOME.
+        try:
+            shown = "~/" + root.relative_to(fs.home()).as_posix()
+        except ValueError:
+            shown = str(root)
+        text = template.replace("__AGENT_TOGGLE_ROOT__", shown)
+    else:                                 # installed package: no checkout to point at
+        text = "".join(ln for ln in template.splitlines(keepends=True)
+                       if "__AGENT_TOGGLE_ROOT__" not in ln)
+    table = harnesses()
+    park = sorted({f"{sub}-disabled" for h in table.values()
+                   for subs in h.dirs.values() for sub in subs
+                   if not Path(sub).is_absolute()})     # skills.paths redirects live elsewhere
+    verb = "would install" if args.dry_run else "installed"
+    installed = 0
+    for hname, h in table.items():
+        home = h.home
+        if args.harness and hname != args.harness:
+            continue
+        if "skill" not in h.dirs or not home.is_dir():
+            out.row(hname, None, None, "install-shims", "skipped",
+                    "not installed" if not home.is_dir() else "no skill support",
+                    show=False, home=str(home))
+            continue
+        dest = home / h.dirs["skill"][0] / "agent-toggle" / "SKILL.md"
+        if not args.dry_run:
+            dest.parent.mkdir(parents=True, exist_ok=True)
+            dest.write_text(text, encoding="utf-8")
+        out.row(hname, None, None, "install-shims", "planned" if args.dry_run else "ok",
+                str(dest), show=False, home=str(home))
+        out.say(f"  {verb}  {dest}")
+        installed += 1
+        # A tracked park dir turns every disable into deletion noise in
+        # `git status`; only touch a .gitignore that already exists.
+        ignore = home / ".gitignore"
+        if ignore.is_file():
+            body = ignore.read_text(encoding="utf-8")
+            missing = [f"{d}/" for d in park if f"{d}/" not in body.splitlines()]
+            if missing and not args.dry_run:
+                with ignore.open("a", encoding="utf-8") as fh:
+                    fh.write(("" if body.endswith("\n") or not body else "\n")
+                             + "".join(f"{m}\n" for m in missing))
+            if missing:
+                out.say(f"  gitignore  {ignore}: {' '.join(missing)}")
+    if not installed:
+        die("no harness found", 4)
+    out.say(f"{installed} harness(es) {'planned' if args.dry_run else 'installed'}")
+
+
+COMMANDS = ("ui", "pick", "status", "list", "cost", "migrate", "disable", "enable",
+            "install-shims", "profile", "undo", "doctor")
+_GLOBAL_FLAGS = ("--json", "-v", "--verbose")
+
+
+def normalize_argv(argv: list[str]) -> list[str]:
+    """Accept `--status` for `status` and bare `help` / `version` for `--help` / `--version`.
+
+    Only the command position is rewritten (after any leading global flags), so a
+    resource that happens to be named `list` or `help` is never touched.
+    """
+    argv = list(argv)
+    i = 0
+    while i < len(argv):
+        a = argv[i]
+        if a in ("--harness", "--color"):
+            i += 2
+        elif a in _GLOBAL_FLAGS or a.startswith(("--harness=", "--color=")):
+            i += 1
+        else:
+            if a.startswith("--") and a[2:] in COMMANDS:
+                argv[i] = a[2:]
+            elif a in ("help", "version"):
+                argv[i] = "--" + a
+            break
+    return argv
+
+
+class _Parser(argparse.ArgumentParser):
+    def error(self, message: str) -> None:
+        die(message, 2)
+
+
+PROJECT_HELP = ("project scope: <dir>/.claude (claude dir types; `.` = cwd) and <dir>/.mcp.json "
+                "(mcp); parks under ~/.agent-toggle/parked, never inside the project")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    # SUPPRESS: a flag given before the subcommand must survive the subparser's
+    # own defaults, so neither level sets a default; main() fills them in.
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--harness", choices=list(harnesses()), default=argparse.SUPPRESS,
+                        help="target harness (default: claude)")
+    common.add_argument("--color", choices=COLOR_MODES, default=argparse.SUPPRESS,
+                        help="colorize output (default: auto; honors NO_COLOR / FORCE_COLOR)")
+    common.add_argument("--json", action="store_true", default=argparse.SUPPRESS,
+                        help="print exactly one JSON document instead of text")
+    common.add_argument("-v", "--verbose", action="store_true", default=argparse.SUPPRESS,
+                        help="print a traceback on unexpected errors")
+    common.add_argument("--version", action="version", default=argparse.SUPPRESS,
+                        version=f"agent-toggle {__version__}")
+    p = _Parser(prog="agent-toggle", parents=[common],
+                description="Temporarily disable / re-enable AI-agent resources.",
+                epilog="exit codes: 0 ok, 1 partial failure, 2 usage error, "
+                       "3 locked, 4 unsupported pair / harness not installed")
+    sub = p.add_subparsers(dest="command", required=True, metavar="command",
+                           parser_class=_Parser)
+    up = sub.add_parser("ui", aliases=["pick"], parents=[common], help="interactive picker")
+    up.add_argument("--dry-run", action="store_true",
+                    help="show the plan for what you stage; change nothing")
+    sub.add_parser("status", parents=[common], help="health check")
+    ls = sub.add_parser("list", parents=[common], help="what is currently disabled")
+    ls.add_argument("type", nargs="?", choices=TYPES)
+    ls.add_argument("--project", metavar="dir", help="only this project's entries")
+    cp = sub.add_parser("cost", parents=[common],
+                        help="estimated startup tokens per item, biggest first")
+    cp.add_argument("--type", choices=TYPES, help="only this resource type")
+    sub.add_parser("migrate", parents=[common], help="import an older ~/.claude-toggle state")
+    sp = sub.add_parser("install-shims", parents=[common],
+                        help="write the skill shim into every installed harness")
+    sp.add_argument("--dry-run", action="store_true", help="show the plan; change nothing")
+    pp = sub.add_parser("profile", parents=[common],
+                        help="save / apply / diff / list named sets of live items")
+    pp.add_argument("action", help="save | apply | diff | list")
+    pp.add_argument("target", nargs="?", metavar="name|file")
+    pp.add_argument("--out", metavar="file", help="save: write the profile here instead")
+    pp.add_argument("--dry-run", action="store_true", help="apply: show the plan; change nothing")
+    pp.add_argument("--project", metavar="dir", help=PROJECT_HELP)
+    sub.add_parser("doctor", parents=[common],
+                   help="read-only check of harness layouts and state against disk")
+    up2 = sub.add_parser("undo", parents=[common], help="reverse the last logged batch")
+    up2.add_argument("--dry-run", action="store_true", help="show the plan; change nothing")
+    for name, verb in (("disable", "park"), ("enable", "restore")):
+        sp = sub.add_parser(name, parents=[common], help=f"{verb} one or more items")
+        sp.add_argument("type", choices=TYPES, nargs="?" if name == "enable" else None)
+        sp.add_argument("names", nargs="*" if name == "enable" else "+", metavar="name")
+        sp.add_argument("--dry-run", action="store_true",
+                        help="show the plan; change nothing")
+        sp.add_argument("--project", metavar="dir", help=PROJECT_HELP)
+        if name == "enable":
+            sp.add_argument("--all", action="store_true",
+                            help="restore every disabled item (optionally --harness H)")
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run one command and return its exit code (the process exit code)."""
+    argv = normalize_argv(sys.argv[1:] if argv is None else argv)
+    out = Result(next((a for a in argv if a in COMMANDS), ""), "--json" in argv,
+                 scan_color(argv))
+    try:
+        args = build_parser().parse_args(argv)
+        out.command = "ui" if args.command == "pick" else args.command
+        out.json_mode = getattr(args, "json", False)
+        args.harness = getattr(args, "harness", None)
+        cmd = out.command
+        if cmd == "ui":
+            if out.json_mode:
+                die("ui is interactive; --json is not supported", 2)
+            cmd_ui(load_state(write_back=False), out, args.dry_run)
+        elif cmd == "cost":
+            cmd_cost(load_state(write_back=False), out, args.harness, args.type)
+        elif cmd == "status":
+            cmd_status(load_state(write_back=False), out, args.harness)
+        elif cmd == "list":
+            cmd_list(args.type, load_state(write_back=False), out, args.harness, args.project)
+        elif cmd == "migrate":
+            cmd_migrate(out)
+        elif cmd == "install-shims":
+            cmd_install_shims(args, out)
+        elif cmd == "profile":
+            profiles.cmd_profile(args, out)
+        elif cmd == "doctor":
+            doctor.cmd_doctor(args.harness, out)
+        elif cmd == "undo":
+            undo.cmd_undo(args.dry_run, args.harness, out)
+        elif cmd == "enable" and args.all:
+            if args.type or args.names:
+                die("enable --all takes no <type> or <name>", 2)
+            undo.cmd_enable_all(args.harness, args.dry_run, out, args.project)
+        else:
+            args.harness = args.harness or "claude"
+            cmd_toggle(args, out)
+        rc = out.exit_code()
+    except fs.Locked as e:
+        out.error(str(e))
+        rc = 3
+    except CliError as e:
+        out.error(e.msg)
+        rc = e.code
+    except SystemExit as e:             # argparse --help / --version
+        return e.code or 0
+    except Exception as e:              # never a bare traceback; --json stays one document
+        out.error(f"{type(e).__name__}: {e}")
+        if os.environ.get("AGENT_TOGGLE_DEBUG") == "1" or {"-v", "--verbose"} & set(argv):
+            traceback.print_exc()
+        rc = 1
+    out.render()
+    return rc

agent_toggle/companions.py

@@ -0,0 +1,160 @@
+"""Companion files: helpers an item references that live outside the item."""
+from __future__ import annotations
+
+import os
+import re
+from pathlib import Path
+
+from . import fs
+from .fs import iter_text_files, read_text, safe_move
+from .output import Result
+
+REF_RE = re.compile(
+    r"""[`'"(\[]?\s*((?:\$HOME|~|\$\{?[A-Za-z_][A-Za-z0-9_]*\}?)?[\w./@-]*"""
+    r"""\.(?:sh|py|mjs|cjs|js|ts|json|ya?ml|toml|txt|md))"""
+)
+
+
+def move(src: Path, dest_dir: Path, dry_run: bool = False) -> Path:
+    """safe_move, or (dry run) the same refusals with nothing written.
+
+    Returns where `src` lands.
+    """
+    if not dry_run:
+        return safe_move(src, dest_dir)
+    if not (src.exists() or src.is_symlink()):
+        raise FileNotFoundError(f"{src} does not exist")
+    if dest_dir.exists() and not dest_dir.is_dir():
+        raise NotADirectoryError(f"{dest_dir} exists but is not a directory")
+    target = dest_dir / src.name
+    if target.exists() or target.is_symlink():
+        raise FileExistsError(f"{target} already exists -- refusing to overwrite")
+    return target
+
+
+def _own_scope(item: Path, source: Path | None) -> tuple[list[Path], list[Path]]:
+    """(dirs, files) that count as the item itself, so they are never companions.
+
+    `item` is where the item lives (real run) or WILL live once parked (dry run).
+    A dry run also passes `source`, where it still sits, so the plan matches
+    what a real run sees after the move.
+    """
+    real = source or item
+    dirs = [item if real.is_dir() else item.parent]
+    files = [item]
+    if source is not None:
+        (dirs if real.is_dir() else files).append(source)
+    return dirs, files
+
+
+def _is_own(p: Path, scope: tuple[list[Path], list[Path]]) -> bool:
+    dirs, files = scope
+    return p in files or any(p.is_relative_to(d) for d in dirs)
+
+
+def find_companions(item: Path, home: Path, source: Path | None = None) -> list[Path]:
+    """Files under `home` that `item` references and that live outside `item`.
+
+    Deliberately a heuristic over file text: a runtime-built path cannot be
+    found by reading source. Everything it finds is REPORTED before anything
+    moves, so a wrong guess is visible rather than silent.
+    """
+    # Resolve everything into one space: ~/.claude is often a symlink, and on
+    # macOS /var itself is one, so an unresolved comparison silently drops
+    # every companion as "outside the harness".
+    home, item = home.resolve(), item.resolve()
+    source = source.resolve() if source else None
+    scope = _own_scope(item, source)
+    item_dir = scope[0][0]
+    user_home = fs.home()
+    found: set[Path] = set()
+    for src in iter_text_files(source or item):
+        for raw in REF_RE.findall(read_text(src)):
+            token = raw.strip("`'\"([ ")
+            # Anchor on fs.home(), the same home the harness table resolves
+            # from, so `~` and $HOME agree with the harness being operated on.
+            if token.startswith("~"):
+                token = str(user_home) + token[1:]
+            token = token.replace("${HOME}", str(user_home)).replace("$HOME", str(user_home))
+            expanded = os.path.expandvars(token)
+            if "$" in expanded:          # unresolved variable -- cannot verify
+                continue
+            cands = ([Path(expanded)] if expanded.startswith("/")
+                     else [home / expanded, item_dir / expanded])
+            for c in cands:
+                try:
+                    c = c.resolve()
+                except OSError:
+                    continue
+                if not c.is_file() or not c.is_relative_to(home):
+                    continue
+                if _is_own(c, scope):
+                    continue             # part of the item itself
+                found.add(c)
+    return sorted(found)
+
+
+def other_users(target: Path, item: Path, home: Path,
+                source: Path | None = None) -> list[Path]:
+    """Live files outside `item` that also reference `target`."""
+    home, item, target = home.resolve(), item.resolve(), target.resolve()
+    scope = _own_scope(item, source.resolve() if source else None)
+    needle = target.name
+    rel = str(target.relative_to(home))
+    users: list[Path] = []
+    for src in iter_text_files(home):
+        if src == target or _is_own(src, scope):
+            continue
+        text = read_text(src)
+        if needle in text or rel in text:
+            users.append(src)
+            if len(users) >= 3:          # enough to prove "shared"
+                break
+    return users
+
+
+def park_companions(item: Path, home: Path, key: str, out: Result | None = None,
+                    dry_run: bool = False, source: Path | None = None) -> list[dict]:
+    """Move companions used ONLY by this item; report the shared ones.
+
+    Dry run: plan the same moves without making them (`source` = where the item
+    still sits).
+
+    Moving a shared helper (tg-send.sh is referenced by five different things)
+    would silently break every other user, so sharing is a veto, not a warning.
+    """
+    out = out or Result()
+    home = home.resolve()
+    moved: list[dict] = []
+    for comp in find_companions(item, home, source):
+        users = other_users(comp, item, home, source)
+        if users:
+            names = ", ".join(u.name for u in users[:2])
+            out.say(f"    - kept {comp.relative_to(home)} (also used by {names})", warn=True)
+            continue
+        dest = fs.companion_dir() / key / comp.relative_to(home).parent
+        try:
+            target = move(comp, dest, dry_run)
+        except (OSError, FileExistsError, NotADirectoryError) as e:
+            out.say(f"    ! companion {comp.name}: {e}", warn=True)
+            continue
+        moved.append({"from": str(comp), "to": str(target)})
+        out.say(f"    + {'would park' if dry_run else 'parked'} "
+                f"{comp.relative_to(home)} (exclusive)")
+    return moved
+
+
+def restore_companions(entry: dict, out: Result | None = None,
+                       dry_run: bool = False) -> None:
+    out = out or Result()
+    for c in entry.get("companions", []):
+        src, dst = Path(c["to"]), Path(c["from"])
+        if not src.exists():
+            out.say(f"    ! companion missing: {src}", warn=True)
+            continue
+        try:
+            move(src, dst.parent, dry_run)
+        except (OSError, FileExistsError, NotADirectoryError) as e:
+            out.say(f"    ! companion {dst.name}: {e}", warn=True)
+        else:
+            out.say(f"    + {'would restore' if dry_run else 'restored'} {dst.name}")