agent-toggle 0.1.0__py3-none-any.whl

agent_toggle/ops.py

@@ -0,0 +1,103 @@
+"""The one apply path: every command that changes things hands a plan to apply_plan.
+
+cmd_toggle, the picker (cmd_ui) and later profile apply / undo / enable --all
+all build a list of Op and call apply_plan, which routes each item by the
+harness MECHANISM table (Harness.mechanisms[type]), never by hard-coded types.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+from typing import NamedTuple
+
+from . import fs
+from .harnesses import harnesses, project_view
+from .mechanisms import (
+    fail_row,
+    toggle_dir_type,
+    toggle_json_mcp,
+    toggle_mcp,
+    toggle_plugin,
+    toggle_project_mcp,
+)
+from .output import CliError, Result
+from .store import BATCH, load_state, save_state
+
+
+class Op(NamedTuple):
+    harness: str
+    type: str
+    action: str           # "disable" | "enable"
+    name: str
+    project: str | None = None   # --project dir: project scope, never user scope
+
+
+def _dispatch(plan: list[Op], state: dict, out: Result, dry_run: bool, batch: str,
+              headers: bool) -> int:
+    """Run the plan, grouped per harness/type/action in first-seen order."""
+    groups: dict[tuple[str, str, str, str | None], list[str]] = {}
+    for op in plan:
+        groups.setdefault((op.harness, op.type, op.action, op.project), []).append(op.name)
+    user = harnesses()
+    fails = 0
+    for (harness, type_, action, project), names in groups.items():
+        table = user
+        if project is not None:
+            # project scope: only the claude dir types, through a project-only table,
+            # so no user-scope dir or entry can be reached (DESIGN s5.5)
+            try:
+                if harness != "claude":
+                    raise CliError(f"{harness} has no --project scope", 4)
+                table = {"claude": project_view(Path(project))}
+            except CliError as e:
+                for name in names:
+                    fails += fail_row(out, dry_run, harness, type_, action, name, e.msg,
+                                      batch=batch, project=project)
+                continue
+        h = table[harness]
+        mech = h.mechanisms.get(type_)
+        if headers:
+            out.say(f"\n{action} {type_} on {out.paint(harness, 'cyan')}"
+                    + (f" (project {h.project}):" if h.project else ":"))
+        if mech == "move":
+            fails += toggle_dir_type(action, type_, names, state, harness, h.home, out,
+                                     dry_run, batch=batch, table=table)
+        elif mech == "native_cli" or (mech == "flag" and type_ == "plugin"):
+            fails += toggle_plugin(action, names, state, harness, out, dry_run, batch=batch)
+        elif mech == "remove_backup" and h.project:      # the repo's own .mcp.json
+            fails += toggle_project_mcp(action, names, state, harness, out, dry_run, table,
+                                        batch=batch)
+        elif mech == "remove_backup" and h.backend == "json":    # user-scope strict JSON file
+            fails += toggle_json_mcp(action, names, state, harness, out, dry_run, table,
+                                     batch=batch)
+        elif mech == "remove_backup" or (mech == "flag" and type_ == "mcp"):
+            fails += toggle_mcp(action, names, state, harness, h.home, h.backend, out,
+                                dry_run, batch=batch)
+        else:
+            for name in names:
+                fails += fail_row(out, dry_run, harness, type_, action, name,
+                               f"{harness} has no {type_} support"
+                               + (" in project scope" if h.project else ""), "unsupported",
+                               batch=batch, project=project)
+    return fails
+
+
+def apply_plan(plan: list[Op], out: Result, dry_run: bool = False, *,
+               batch: str = BATCH, state: dict | None = None,
+               headers: bool = False) -> int:
+    """Apply `plan`; returns the fail count.
+
+    A real run takes ONE fs.lock() for the whole plan, re-reads state under it
+    and saves it in `finally`, so what already moved is kept even if a later
+    item crashes. A dry run plans against a read-only state: no lock, state,
+    log or backup write. A caller that already holds the lock passes `state`.
+    """
+    if state is not None:
+        return _dispatch(plan, state, out, dry_run, batch, headers)
+    if dry_run:
+        return _dispatch(plan, load_state(write_back=False), out, True, batch, headers)
+    with fs.lock():
+        state = load_state()
+        try:
+            return _dispatch(plan, state, out, False, batch, headers)
+        finally:
+            save_state(state)

agent_toggle/output.py

@@ -0,0 +1,153 @@
+"""Command output: one collector that renders as human text OR one JSON document.
+
+Every command builds a `Result`. In human mode lines stream to stdout as they
+happen (diagnostics to stderr); in --json mode nothing is printed until
+`render()` emits the single envelope, so text can never leak into stdout.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+FAILED = ("error", "unsupported")      # row statuses that make the run a failure
+MARK = {"ok": "v", "planned": "~", "skipped": "-"}   # human marker per status; else "x"
+
+
+STYLE = {"green": "32", "red": "31", "yellow": "33", "cyan": "36", "dim": "2"}
+COLOR_MODES = ("auto", "always", "never")
+
+
+def _vt_enable(stream) -> bool:
+    """Windows 10+: make sure the console is in ANSI mode. True iff it is (TTY only)."""
+    try:
+        import ctypes
+        import msvcrt
+        k32 = ctypes.windll.kernel32                       # type: ignore[attr-defined]
+        h = ctypes.c_void_p(msvcrt.get_osfhandle(stream.fileno()))
+        mode = ctypes.c_uint32()
+        if not k32.GetConsoleMode(h, ctypes.byref(mode)):
+            return False
+        return bool(mode.value & 0x0004) or bool(k32.SetConsoleMode(h, mode.value | 0x0004))
+    except Exception:                                      # no console / old Windows: plain text
+        return False
+
+
+def use_color(stream, mode: str = "auto") -> bool:
+    """Decide for ONE stream, at write time -- nothing is cached between calls.
+    --color always|never wins; then NO_COLOR, FORCE_COLOR, TERM=dumb, then isatty.
+    A Windows console that cannot do ANSI stays plain, even for --color always."""
+    if mode == "never":
+        return False
+    env = os.environ
+    try:
+        tty = bool(stream.isatty())
+    except Exception:
+        tty = False
+    if mode != "always":
+        if env.get("NO_COLOR"):
+            return False
+        forced = env.get("FORCE_COLOR", "0") not in ("", "0")    # beats TERM=dumb and non-tty
+        if not forced and (env.get("TERM") == "dumb" or not tty):
+            return False
+    return not (tty and os.name == "nt" and not _vt_enable(stream))
+
+
+def scan_color(argv: list[str]) -> str:
+    """The --color value from raw argv (so even argparse errors honor it); bad -> auto."""
+    mode = "auto"
+    for i, a in enumerate(argv):
+        if a == "--color" and i + 1 < len(argv):
+            mode = argv[i + 1]
+        elif a.startswith("--color="):
+            mode = a[8:]
+    return mode if mode in COLOR_MODES else "auto"
+
+
+class CliError(SystemExit):
+    """A fatal, user-facing error. `code` is the process exit code (a SystemExit,
+    so legacy `except SystemExit` callers keep working); `msg` is for the human."""
+
+    def __init__(self, msg: str, code: int = 1) -> None:
+        super().__init__(code)
+        self.msg = msg
+
+
+def die(msg: str, code: int = 1) -> None:
+    raise CliError(msg, code)
+
+
+class Result:
+    def __init__(self, command: str = "", json_mode: bool = False,
+                 color: str = "auto") -> None:
+        self.command = command
+        self.json_mode = json_mode
+        self.color = color
+        self.rows: list[dict] = []
+        self.warnings: list[str] = []
+
+    def paint(self, text: str, style: str, stream=None) -> str:
+        """`text` in `style` if `stream` (default stdout) takes color; never in --json.
+        Apply AFTER width padding so uncolored output stays byte-identical."""
+        if self.json_mode or not text or not use_color(stream or sys.stdout, self.color):
+            return text
+        return f"\033[{STYLE[style]}m{text}\033[0m"
+
+    def say(self, msg: str, warn: bool = False, style: str | None = None) -> None:
+        """A human line on stdout. warn=True also records it in the envelope."""
+        if warn:
+            self.warnings.append(msg.strip())
+        if not self.json_mode:
+            style = style or ("yellow" if warn else None)
+            print(self.paint(msg, style) if style else msg)
+
+    def warn(self, msg: str) -> None:
+        """A warning: stderr for humans, `warnings` for --json."""
+        self.warnings.append(msg)
+        if not self.json_mode:
+            print(f"{self.paint('WARNING', 'yellow', sys.stderr)}  {msg}", file=sys.stderr)
+
+    def row(self, harness: str | None, type_: str | None, name: str | None,
+            action: str, status: str, text: str = "", show: bool = True,
+            **extra) -> dict:
+        """Record one result; `show=False` records it without a human line."""
+        row = {"harness": harness, "type": type_, "name": name,
+               "action": action, "status": status, "detail": text, **extra}
+        self.rows.append(row)
+        if show and not self.json_mode:
+            if status in MARK:
+                mark = self.paint(MARK[status], "green" if status == "ok" else "dim")
+                print(f"  {mark} {type_} {name} {text}")
+            else:
+                print(self.paint(f"  x {type_} {name}: {text}", "red"))
+        return row
+
+    def error(self, msg: str) -> None:
+        self.rows.append({"harness": None, "type": None, "name": None,
+                          "action": self.command, "status": "error", "detail": msg})
+        if not self.json_mode:
+            print(f"{self.paint('error:', 'red', sys.stderr)} {msg}", file=sys.stderr)
+
+    @property
+    def failed(self) -> int:
+        return sum(r["status"] in FAILED for r in self.rows)
+
+    @property
+    def needs_new_session(self) -> bool:
+        return any(r["status"] == "ok" and r["action"] in ("disable", "enable")
+                   for r in self.rows)
+
+    def exit_code(self) -> int:
+        """0 ok; 4 when every failure was an unsupported pair; else 1 (partial)."""
+        bad = [r for r in self.rows if r["status"] in FAILED]
+        if not bad:
+            return 0
+        return 4 if all(r["status"] == "unsupported" for r in bad) else 1
+
+    def envelope(self) -> dict:
+        return {"ok": self.failed == 0, "command": self.command, "results": self.rows,
+                "warnings": self.warnings, "needs_new_session": self.needs_new_session}
+
+    def render(self) -> None:
+        if self.json_mode:
+            print(json.dumps(self.envelope(), indent=2, ensure_ascii=False))

agent_toggle/profiles.py

@@ -0,0 +1,207 @@
+"""Profiles (DESIGN s5.7): a portable snapshot of which items are live.
+
+A profile holds ONLY {harness, type, name, live} per item -- never a path or a
+secret -- so it can sit in a dotfiles repo. `apply` toggles just the items the
+profile mentions: an item installed after the save is never touched, and an item
+the profile names that this machine lacks is skipped, not failed.
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime
+from pathlib import Path
+
+from . import cost, fs, ops, store
+from .harnesses import TYPES, harnesses, project_view
+from .mechanisms import _valid_name, validate_name
+from .output import Result, die
+
+VERSION = 1
+MAX_BYTES = 1 << 20                      # a real profile is a few KB
+ITEM_KEYS = {"harness", "type", "name", "live"}
+WIN_RESERVED = {"CON", "PRN", "AUX", "NUL", *(f"COM{i}" for i in range(1, 10)),
+                *(f"LPT{i}" for i in range(1, 10))}     # not valid file names on Windows
+ACTIONS = ("save", "apply", "diff", "list")
+
+
+def _is_path(arg: str) -> bool:
+    return arg.endswith(".json") or "/" in arg or "\\" in arg
+
+
+def _file_path(arg: str) -> Path:
+    p = Path(arg).expanduser()
+    if ".." in p.parts:
+        die(f"invalid profile path {arg!r}: `..` is not allowed", 2)
+    return p
+
+
+def _stored_path(name: str) -> Path:
+    validate_name(name)
+    if ":" in name or name.split(".")[0].upper() in WIN_RESERVED or name.endswith("."):
+        die(f"invalid profile name {name!r}", 2)
+    return fs.profiles_dir() / f"{name}.json"
+
+
+def _load(arg: str) -> dict:
+    p = _file_path(arg) if _is_path(arg) else _stored_path(arg)
+    try:
+        with open(p, "rb") as fh:
+            data = fh.read(MAX_BYTES + 1)
+    except OSError as e:
+        die(f"cannot read profile {arg!r}: {e.strerror or e}", 2)
+    if len(data) > MAX_BYTES:
+        die(f"profile {arg!r} is larger than {MAX_BYTES} bytes", 2)
+    try:
+        return _validate(json.loads(data.decode("utf-8")))
+    except (ValueError, RecursionError) as e:    # JSON, UTF-8 and absurd nesting
+        die(f"profile {arg!r} is not valid JSON: {e}", 2)
+
+
+def _validate(doc) -> dict:
+    """Exit 2 on anything but a well-formed v1 profile (it may come from anywhere)."""
+    table = harnesses()
+    if not isinstance(doc, dict) or set(doc) - {"version", "saved_at", "items", "scope"}:
+        die("profile must be an object with version, saved_at, items", 2)
+    if doc.get("scope", "user") not in ("user", "project"):
+        die(f"unknown profile scope {doc['scope']!r} (expected user or project)", 2)
+    v = doc.get("version")
+    if type(v) is not int or v != VERSION:
+        die(f"unsupported profile version {v!r} (expected {VERSION})", 2)
+    if not isinstance(doc.get("items"), list):
+        die("profile items must be a list", 2)
+    seen = set()
+    for it in doc["items"]:
+        if not isinstance(it, dict) or set(it) != ITEM_KEYS:
+            die(f"profile item must have exactly {sorted(ITEM_KEYS)}", 2)
+        if not isinstance(it["harness"], str) or it["harness"] not in table:
+            die(f"profile names unknown harness {it['harness']!r}", 2)
+        if not isinstance(it["type"], str) or it["type"] not in TYPES:
+            die(f"profile names unknown type {it['type']!r}", 2)
+        if not isinstance(it["name"], str):
+            die("profile item name must be a string", 2)
+        validate_name(it["name"])
+        if not isinstance(it["live"], bool):
+            die("profile item live must be true or false", 2)
+        key = (it["harness"], it["type"], it["name"])
+        if key in seen:
+            die(f"profile lists {'/'.join(key)} twice", 2)
+        seen.add(key)
+    return doc
+
+
+def _inventory(out: Result, plugins: bool,
+               project: Path | None = None) -> dict[tuple[str, str, str], bool]:
+    """(harness, type, name) -> live now, in ONE scope: user scope, or (`project`, a
+    resolved --project dir) that project's .claude only -- the two never mix.
+    Reuses the cost inventory (one owner per shared dir)."""
+    state = store.scope_state(store.load_state(write_back=False), project)
+    table = {"claude": project_view(project)} if project else harnesses()
+    # a project dir symlinked out of the project (to ~/.claude/skills) is user scope
+    outside = {t for t, subs in table["claude"].dirs.items()
+               if any(not (table["claude"].home / s).resolve().is_relative_to(project)
+                      for s in subs)} if project else set()
+    return {(i.harness, i.type, i.name): i.enabled
+            for i in cost.inventory(state, table, out.warn, plugins and not project)
+            if i.type not in outside}
+
+
+def _project(arg: str | None, only: str | None) -> Path | None:
+    """The resolved --project dir (claude layout only, exit 4 otherwise), or None."""
+    if arg is None:
+        return None
+    if only not in (None, "claude"):
+        die(f"--project supports only the claude layout, not {only}", 4)
+    return project_view(arg).project
+
+
+def cmd_save(arg: str, out_file: str | None, only: str | None, out: Result,
+             project: Path | None = None) -> None:
+    if _is_path(arg):
+        die(f"{arg!r} looks like a path: save <name> [--out <file>]", 2)
+    path = _file_path(out_file) if out_file else _stored_path(arg)
+    if out_file:
+        validate_name(arg)
+        if path.is_dir() or not path.parent.is_dir():
+            die(f"cannot write {path}: not a file in an existing directory", 2)
+    inv = _inventory(out, plugins=not only or only == "claude", project=project)
+    items = []
+    for (h, t, n), live in sorted(inv.items()):
+        if only and h != only:
+            continue
+        if _valid_name(n):
+            items.append({"harness": h, "type": t, "name": n, "live": live})
+        else:                    # apply/diff would refuse the whole profile over this name
+            out.warn(f"skipped {h} {t} {n!r}: not a name agent-toggle can toggle")
+    doc = {"version": VERSION, "saved_at": datetime.now().astimezone().isoformat(timespec="seconds"),
+           "items": items, **({"scope": "project"} if project else {})}
+    if not out_file:
+        fs.private_dir(fs.profiles_dir())
+    fs.atomic_write(path, json.dumps(doc, indent=2, ensure_ascii=False) + "\n")
+    out.say(f"saved {len(items)} item(s) -> {path}")
+    out.row(None, None, arg, "save", "ok", f"{len(items)} items", show=False,
+            path=str(path), items=len(items))
+
+
+def cmd_apply(arg: str, only: str | None, dry_run: bool, out: Result,
+              project: Path | None = None) -> None:
+    doc = _load(arg)
+    if (doc.get("scope", "user") == "project") != (project is not None):
+        die(f"profile {arg!r} is {doc.get('scope', 'user')}-scope: "
+            + ("pass --project <dir>" if project is None else "drop --project"), 2)
+    inv = _inventory(out, plugins=not dry_run and (not only or only == "claude"),  # dry run: no CLI
+                     project=project)
+    plan, same, skipped = [], 0, 0
+    for it in doc["items"]:
+        h, t, n, live = it["harness"], it["type"], it["name"], it["live"]
+        if only and h != only:
+            continue
+        if (h, t, n) not in inv:
+            skipped += 1
+            why = ("plugin state is not read in a dry run" if dry_run and t == "plugin"
+                   else "not on this machine")
+            out.row(h, t, n, "would-skip" if dry_run else "skip", "skipped", why)
+        elif inv[h, t, n] == live:
+            same += 1
+        else:
+            plan.append(ops.Op(h, t, "enable" if live else "disable", n,
+                               str(project) if project else None))
+    if plan:
+        ops.apply_plan(plan, out, dry_run, batch=store.BATCH, headers=True)
+    out.say(f"\n{len(plan)} {'to change' if dry_run else 'attempted'}, "
+            f"{same} already as profiled, {skipped} skipped")
+
+
+def cmd_list(out: Result) -> None:
+    files = sorted(fs.profiles_dir().glob("*.json")) if fs.profiles_dir().is_dir() else []
+    if not files:
+        out.say("no profiles saved")
+    for p in files:
+        try:
+            doc = json.loads(p.read_text(encoding="utf-8"))
+            detail = f"{len(doc['items'])} items, saved {str(doc.get('saved_at', '?'))[:10]}"
+        except (OSError, ValueError, KeyError, TypeError):
+            detail = "unreadable"
+        out.say(f"  {p.stem:<24} {detail}")
+        out.row(None, None, p.stem, "list", "ok", detail, show=False, path=str(p))
+
+
+def cmd_profile(args, out: Result) -> None:
+    action, target = args.action, args.target
+    if action not in ACTIONS:
+        die(f"unknown profile action {action!r} (expected: {', '.join(ACTIONS)})", 2)
+    if (action == "list") == (target is not None):
+        die("profile list takes no argument" if action == "list"
+            else f"profile {action} needs a <name|file>", 2)
+    if args.out and action != "save":
+        die("--out only applies to `profile save`", 2)
+    if args.dry_run and action not in ("apply", "diff"):
+        die("--dry-run only applies to `profile apply` / `diff`", 2)
+    if args.project is not None and action == "list":
+        die("--project does not apply to `profile list`", 2)
+    project = _project(args.project, args.harness)
+    if action == "save":
+        cmd_save(target, args.out, args.harness, out, project)
+    elif action == "list":
+        cmd_list(out)
+    else:                                  # diff is apply, planned only
+        cmd_apply(target, args.harness, action == "diff" or args.dry_run, out, project)

agent_toggle/shims/claude.md.tmpl

@@ -0,0 +1,45 @@
+---
+name: agent-toggle
+description: Temporarily disable or restore AI-agent resources — skills, agents, commands, rules, plugins, MCP servers — across Claude Code, Codex, Grok CLI, OpenCode, OpenClaw, Copilot and Vibe. Nothing is deleted; everything is parked and reversible. Use when the user wants to turn something off, trim startup context cost, re-enable something previously disabled, or asks "how do I disable X" / "停用這個 skill" / "關掉某個 MCP" / "把它加回來".
+---
+
+# agent-toggle
+
+Parks and restores agent resources (skills, agents, commands, rules, plugins,
+MCP servers). **Never deletes anything**; every change is reversible.
+
+## Run it
+
+```bash
+agent-toggle <command> --json
+python3 __AGENT_TOGGLE_ROOT__/agent_toggle.py <command> --json   # if agent-toggle is not on PATH
+```
+
+Commands: `status` (run first), `doctor` (read-only health check), `list [type]`,
+`cost [--type T]` (startup token estimates, biggest first), `disable <type> <name>...`,
+`enable <type> <name>...`, `enable --all`, `undo` (reverse the last batch),
+`profile save|apply|diff <name>`, `profile list`, `migrate`; add `--harness claude|codex|grok|opencode|openclaw|copilot|vibe|devin|agy`
+(default `claude`) and `--dry-run` to preview (always preview `enable --all`, `undo`,
+`profile apply`). `--project <dir>` targets a repo's own `.claude/` and `.mcp.json`
+(warn the user: git shows the deletion). `<type>` = `skill` / `agent` /
+`command` / `rule` / `plugin` / `mcp`. A colon addresses nesting: `orch:batch`.
+A row with `shared_with` means another harness reads the same directory (OpenCode
+aliasing a skills dir): the change affects them too, so say so.
+`ui` is an interactive picker for the user, not for you.
+
+## Read the result
+
+`--json` prints one envelope on stdout: `ok`, `command`, `results` (one row
+per item: harness, type, name, status, detail), `warnings`,
+`needs_new_session`. Summarise the rows for the user; do not paste the JSON.
+Branch on the exit code:
+
+| code | meaning | do |
+|---|---|---|
+| 0 | ok | report; if `needs_new_session`, tell the user to open a NEW session (MCP changes only apply then) |
+| 1 | partial | list the failed rows and why |
+| 2 | usage error | fix the arguments and retry |
+| 3 | locked | another run is active; retry later |
+| 4 | unsupported pair / harness missing | tell the user; do not retry |
+
+Rollback is `undo` or `enable <type> <name>`. State lives in `~/.agent-toggle/`.