@softspark/ai-toolkit 4.17.0 → 4.19.0

package/scripts/plugin.py

@@ -2,14 +2,14 @@
 """ai-toolkit plugin — install, remove, update, clean, and list plugin packs.
 
 Usage:
-    plugin.py list [--editor claude|codex|all]
-    plugin.py status [--editor claude|codex|all]
-    plugin.py install [--editor claude|codex|all] <pack-name> [<pack-name> ...]
-    plugin.py install [--editor claude|codex|all] --all
-    plugin.py remove [--editor claude|codex|all] <pack-name> [<pack-name> ...]
-    plugin.py remove [--editor claude|codex|all] --all
-    plugin.py update [--editor claude|codex|all] <pack-name> [<pack-name> ...]
-    plugin.py update [--editor claude|codex|all] --all
+    plugin.py list [--editor claude|codex|cursor|gemini|all]
+    plugin.py status [--editor claude|codex|cursor|gemini|all]
+    plugin.py install [--editor claude|codex|cursor|gemini|all] <pack-name> [<pack-name> ...]
+    plugin.py install [--editor claude|codex|cursor|gemini|all] --all
+    plugin.py remove [--editor claude|codex|cursor|gemini|all] <pack-name> [<pack-name> ...]
+    plugin.py remove [--editor claude|codex|cursor|gemini|all] --all
+    plugin.py update [--editor claude|codex|cursor|gemini|all] <pack-name> [<pack-name> ...]
+    plugin.py update [--editor claude|codex|cursor|gemini|all] --all
     plugin.py clean <pack-name> [--days N]
 
 Actions:
@@ -64,7 +64,38 @@ HOOKS_DIR = _HOOKS_DIR
 PLUGINS_STATE_FILE = TOOLKIT_DATA_DIR / "plugins.json"
 MEMORY_DB = TOOLKIT_DATA_DIR / "memory.db"
 
-VALID_EDITORS = ("claude", "codex")
+VALID_EDITORS = ("claude", "codex", "cursor", "gemini")
+
+# Runtimes whose hook config is a JSON document we merge a single pack entry
+# into, rather than a surface with its own installer. Everything below is read
+# from the matching scripts/generate_<runtime>_hooks.py.
+#
+# `source_tag` deliberately differs from those generators' own `SOURCE_TAG`
+# ("ai-toolkit"): their strip predicates match that value exactly, so a pack
+# entry tagged `ai-toolkit-plugin-<pack>` survives a core regeneration instead
+# of being deleted as legacy output.
+#
+# Pack hooks are user-scope only. Cursor's project manifest is deliberately
+# self-contained so cloud agents can read it (tests/test_cursor.bats), and a
+# `$HOME/.softspark` command would break that; `~/.cursor/hooks.json` is a local
+# file where a home-relative command is correct.
+JSON_HOOK_RUNTIMES: dict[str, dict] = {
+    "cursor": {
+        "config": Path.home() / ".cursor" / "hooks.json",
+        # Claude event name -> this runtime's event name. An event with no
+        # mapping is skipped loudly rather than guessed at.
+        "events": {"PreToolUse": "beforeShellExecution"},
+        "shape": "flat",      # entry is the command record itself
+        "timeout": 10,
+    },
+    "gemini": {
+        "config": Path.home() / ".gemini" / "settings.json",
+        "events": {"PreToolUse": "BeforeTool", "PostToolUse": "AfterTool"},
+        "shape": "nested",    # entry wraps a hooks[] list, optional matcher
+        "matcher": "run_shell_command",
+        "root_key": "hooks",  # hooks live under a key inside a larger document
+    },
+}
 CODEX_PLUGIN_NAME_PATTERN = re.compile(r"[a-z0-9][a-z0-9-]*")
 CODEX_PLUGIN_ASSET_MARKER = "# ai-toolkit-managed: codex-plugin-hook"
 
@@ -74,12 +105,9 @@ CODEX_PLUGIN_ASSET_MARKER = "# ai-toolkit-managed: codex-plugin-hook"
 # ---------------------------------------------------------------------------
 
 def _empty_state() -> dict:
-    return {
-        "targets": {
-            "claude": {"installed": []},
-            "codex": {"installed": []},
-        }
-    }
+    # Built from VALID_EDITORS so adding a runtime cannot leave load_state()
+    # indexing a key that was never created.
+    return {"targets": {editor: {"installed": [], "versions": {}} for editor in VALID_EDITORS}}
 
 
 def load_state() -> dict:
@@ -103,6 +131,13 @@ def load_state() -> dict:
                     installed = targets.get(editor, {}).get("installed", [])
                     if isinstance(installed, list):
                         state["targets"][editor]["installed"] = sorted(set(installed))
+                    # Absent in state written before versions were tracked, so
+                    # every pack looks stale once and is updated exactly once.
+                    versions = targets.get(editor, {}).get("versions", {})
+                    if isinstance(versions, dict):
+                        state["targets"][editor]["versions"] = {
+                            k: v for k, v in versions.items() if isinstance(v, str)
+                        }
     return state
 
 
@@ -118,6 +153,18 @@ def _installed_for(state: dict, editor: str) -> list[str]:
     return list(state.get("targets", {}).get(editor, {}).get("installed", []))
 
 
+def _installed_version(state: dict, editor: str, name: str) -> str:
+    return state.get("targets", {}).get(editor, {}).get("versions", {}).get(name, "")
+
+
+def _record_version(state: dict, editor: str, name: str, version: str) -> None:
+    state.setdefault("targets", {}).setdefault(editor, {}).setdefault("versions", {})[name] = version
+
+
+def _forget_version(state: dict, editor: str, name: str) -> None:
+    state.get("targets", {}).get(editor, {}).get("versions", {}).pop(name, None)
+
+
 def _set_installed(state: dict, editor: str, names: list[str]) -> None:
     state.setdefault("targets", {}).setdefault(editor, {})
     state["targets"][editor]["installed"] = sorted(set(names))
@@ -264,6 +311,11 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
     for script_file in sorted(plugin_scripts_dir.iterdir()):
         if script_file.name.startswith("__"):
             continue
+        # copy2 on a directory raises IsADirectoryError and aborts the install
+        # halfway with nothing rolled back, so a pack that ships scripts/bin/
+        # or a stray __pycache__ would break it.
+        if not script_file.is_file():
+            continue
         dest = scripts_dest / script_file.name
         shutil.copy2(script_file, dest)
         if script_file.suffix in (".py", ".sh"):
@@ -271,8 +323,13 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
         print(f"    Copied script: {script_file.name}")
         installed_items.append(f"script:{dest}")
 
-    init_script = plugin_scripts_dir / "init_db.py"
-    if init_script.is_file():
+    # `init.py` is the generic name; `init_db.py` predates it and is what
+    # memory-pack ships. A pack whose init script is named anything else is
+    # silently never run, and the install still reports success.
+    for candidate in ("init.py", "init_db.py"):
+        init_script = plugin_scripts_dir / candidate
+        if not init_script.is_file():
+            continue
         result = subprocess.run(
             ["python3", str(init_script)],
             capture_output=True,
@@ -280,8 +337,10 @@ def _copy_plugin_scripts(name: str, pack_dir: Path, installed_items: list[str])
         )
         if result.returncode == 0 and result.stdout.strip():
             print(f"    Init: {result.stdout.strip()}")
-        elif result.returncode != 0 and result.stderr.strip():
-            print(f"    WARN init failed: {result.stderr.strip()}")
+        elif result.returncode != 0:
+            detail = result.stderr.strip() or result.stdout.strip() or "no output"
+            print(f"    WARN init failed: {detail}")
+        break
 
 
 def _copy_plugin_hook_scripts(name: str, hook_specs: list[dict], installed_items: list[str]) -> None:
@@ -305,6 +364,142 @@ def _plugin_hook_command(name: str, spec: dict) -> str:
     return f"\"$HOME/.softspark/ai-toolkit/hooks/plugin-{name}-{spec['name']}\""
 
 
+def _json_runtime_entry(runtime: str, name: str, spec: dict) -> dict:
+    """One hook entry in this runtime's schema, tagged as owned by the pack."""
+    cfg = JSON_HOOK_RUNTIMES[runtime]
+    command = _plugin_hook_command(name, spec)
+    # The hook is one script for every runtime; the target is its first
+    # argument, so a pack can branch on which host is calling rather than
+    # always assuming Claude.
+    command = f"{command} {runtime}"
+    source_tag = f"ai-toolkit-plugin-{name}"
+
+    if cfg["shape"] == "flat":
+        entry = {"_source": source_tag, "command": command}
+        if cfg.get("timeout"):
+            entry["timeout"] = cfg["timeout"]
+        return entry
+
+    entry = {"_source": source_tag, "hooks": [{"type": "command", "command": command}]}
+    if cfg.get("matcher"):
+        entry["matcher"] = cfg["matcher"]
+    return entry
+
+
+def _json_runtime_hooks_block(runtime: str, document: dict) -> dict:
+    cfg = JSON_HOOK_RUNTIMES[runtime]
+    root = cfg.get("root_key")
+    if root:
+        block = document.get(root)
+        return block if isinstance(block, dict) else {}
+    block = document.get("hooks")
+    return block if isinstance(block, dict) else {}
+
+
+def _json_runtime_set_hooks(runtime: str, document: dict, hooks: dict) -> None:
+    cfg = JSON_HOOK_RUNTIMES[runtime]
+    document[cfg.get("root_key") or "hooks"] = hooks
+
+
+def _merge_json_runtime_hooks(runtime: str, name: str, hook_specs: list[dict]) -> bool:
+    """Add this pack's hooks to a JSON-configured runtime. True if anything landed."""
+    cfg = JSON_HOOK_RUNTIMES[runtime]
+    config_path: Path = cfg["config"]
+    if config_path.is_symlink() or config_path.parent.is_symlink():
+        print(f"    WARN refusing symlinked {runtime} config: {config_path}")
+        return False
+
+    source_tag = f"ai-toolkit-plugin-{name}"
+    document = _load_json(config_path, {})
+    hooks = _json_runtime_hooks_block(runtime, document)
+
+    # Drop this pack's previous entries everywhere before appending, so a
+    # re-install cannot duplicate and two hooks on one event both survive.
+    hooks = {
+        event: [e for e in entries if not (isinstance(e, dict) and e.get("_source") == source_tag)]
+        if isinstance(entries, list) else entries
+        for event, entries in hooks.items()
+    }
+
+    landed = 0
+    for spec in hook_specs:
+        if spec["is_core"]:
+            continue
+        target_event = cfg["events"].get(spec["event"])
+        if not target_event:
+            print(
+                f"    WARN {runtime} has no equivalent of {spec['event']} "
+                f"for {spec['name']}, hook not registered"
+            )
+            continue
+        hooks.setdefault(target_event, []).append(_json_runtime_entry(runtime, name, spec))
+        landed += 1
+
+    if not landed:
+        return False
+
+    hooks = {event: entries for event, entries in hooks.items() if entries}
+    _json_runtime_set_hooks(runtime, document, hooks)
+    _write_json(config_path, document)
+    print(f"    Merged hooks into {config_path}")
+    return True
+
+
+def _strip_json_runtime_hooks(runtime: str, name: str) -> None:
+    cfg = JSON_HOOK_RUNTIMES[runtime]
+    config_path: Path = cfg["config"]
+    if not config_path.is_file() or config_path.is_symlink():
+        return
+    source_tag = f"ai-toolkit-plugin-{name}"
+    document = _load_json(config_path, {})
+    hooks = _json_runtime_hooks_block(runtime, document)
+    kept = {}
+    removed = 0
+    for event, entries in hooks.items():
+        if not isinstance(entries, list):
+            kept[event] = entries
+            continue
+        survivors = [
+            e for e in entries
+            if not (isinstance(e, dict) and e.get("_source") == source_tag)
+        ]
+        removed += len(entries) - len(survivors)
+        if survivors:
+            kept[event] = survivors
+    if not removed:
+        return
+    _json_runtime_set_hooks(runtime, document, kept)
+    _write_json(config_path, document)
+    print(f"    Stripped hooks from {config_path}")
+
+
+def install_pack_json_runtime(runtime: str, name: str, pack: dict, pack_dir: Path) -> bool:
+    hook_specs = _resolve_pack_hooks(pack, pack_dir)
+    installed_items: list[str] = []
+    _copy_plugin_scripts(name, pack_dir, installed_items)
+    _copy_plugin_hook_scripts(name, hook_specs, installed_items)
+    if not _merge_json_runtime_hooks(runtime, name, hook_specs):
+        print(f"    WARN nothing registered for {runtime}; pack files are installed but inert")
+    print(f"  Done: {name} for {runtime} ({len(installed_items)} file items)")
+    return True
+
+
+def remove_pack_json_runtime(
+    runtime: str, name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool
+) -> bool:
+    _strip_json_runtime_hooks(runtime, name)
+    if not keep_shared_assets:
+        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
+            hook.unlink()
+            print(f"    Removed hook: {hook.name}")
+        scripts_dir = TOOLKIT_DATA_DIR / "plugin-scripts" / name
+        if scripts_dir.is_dir():
+            shutil.rmtree(scripts_dir)
+            print(f"    Removed scripts: {scripts_dir}")
+    print(f"  Done: removed {name} from {runtime}")
+    return True
+
+
 def _load_json(path: Path, default: dict) -> dict:
     if not path.is_file():
         return json.loads(json.dumps(default))
@@ -399,6 +594,16 @@ def _merge_claude_hooks(name: str, hook_specs: list[dict]) -> None:
     hooks = settings.setdefault("hooks", {})
     source_tag = f"ai-toolkit-plugin-{name}"
 
+    # Drop this pack's previous entries once per event, before appending any.
+    # Stripping inside the loop also removed the entry appended by an earlier
+    # iteration, so a pack shipping two non-core hooks on the same event kept
+    # only the last one. memory-pack does not hit this because its two hooks
+    # sit on different events.
+    events = {spec["event"] for spec in hook_specs if not spec["is_core"]}
+    for event in events:
+        existing = hooks.get(event, [])
+        hooks[event] = [h for h in existing if h.get("_source") != source_tag]
+
     for spec in hook_specs:
         if spec["is_core"]:
             # Base Claude install already owns core hooks.
@@ -413,10 +618,7 @@ def _merge_claude_hooks(name: str, hook_specs: list[dict]) -> None:
                 }
             ],
         }
-        event_hooks = hooks.setdefault(spec["event"], [])
-        event_hooks = [h for h in event_hooks if h.get("_source") != source_tag]
-        event_hooks.append(entry)
-        hooks[spec["event"]] = event_hooks
+        hooks.setdefault(spec["event"], []).append(entry)
 
     _write_json(settings_path, settings)
     print("    Merged hooks into ~/.claude/settings.json")
@@ -482,12 +684,49 @@ def install_pack_claude(name: str, pack: dict, pack_dir: Path) -> bool:
     return True
 
 
+def _remove_claude_pack_links(pack: dict, pack_dir: Path) -> None:
+    """Drop skill/agent symlinks this pack owns.
+
+    Install symlinks both into ~/.claude but removal never did, so every pack
+    left them behind. Ownership is decided by where the link resolves: only a
+    link into the pack's own directory is removed. A link into app/skills or
+    app/agents is a core asset the pack merely referenced, and the base install
+    would have created it anyway, so it stays.
+    """
+    pack_dir = pack_dir.resolve()
+
+    for skill in pack.get("includes", {}).get("skills", []):
+        link = CLAUDE_DIR / "skills" / skill
+        if not link.is_symlink():
+            continue
+        try:
+            target = link.resolve()
+        except OSError:
+            continue
+        if target.is_relative_to(pack_dir):
+            link.unlink()
+            print(f"    Removed skill link: {skill}")
+
+    for agent in pack.get("includes", {}).get("agents", []):
+        link = CLAUDE_DIR / "agents" / f"{agent}.md"
+        if not link.is_symlink():
+            continue
+        try:
+            target = link.resolve()
+        except OSError:
+            continue
+        if target.is_relative_to(pack_dir):
+            link.unlink()
+            print(f"    Removed agent link: {agent}")
+
+
 def remove_pack_claude(name: str, pack: dict, pack_dir: Path, *, keep_shared_assets: bool) -> bool:
     hook_specs = _resolve_pack_hooks(pack, pack_dir)
     rule_specs = _resolve_pack_rules(pack, pack_dir)
+    _remove_claude_pack_links(pack, pack_dir)
 
     if not keep_shared_assets:
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*.sh"):
+        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
             hook.unlink()
             print(f"    Removed hook: {hook.name}")
 
@@ -859,7 +1098,7 @@ def remove_pack_codex(name: str, pack: dict, pack_dir: Path, *, keep_shared_asse
     _strip_codex_hooks(name)
 
     if CODEX_HOOKS_DIR.is_dir():
-        for hook in CODEX_HOOKS_DIR.glob(f"plugin-{name}-*.sh"):
+        for hook in CODEX_HOOKS_DIR.glob(f"plugin-{name}-*"):
             if hook.is_symlink():
                 raise RuntimeError(f"Refusing symlinked Codex plugin hook: {hook}")
             if _is_owned_codex_plugin_asset(hook, name):
@@ -871,7 +1110,7 @@ def remove_pack_codex(name: str, pack: dict, pack_dir: Path, *, keep_shared_asse
     if not keep_shared_assets:
         # Clean paths used by releases before native Codex plugin assets moved
         # under $CODEX_HOME. Claude still owns these when installed for both.
-        for hook in HOOKS_DIR.glob(f"plugin-{name}-*.sh"):
+        for hook in HOOKS_DIR.glob(f"plugin-{name}-*"):
             hook.unlink()
             print(f"    Removed hook: {hook.name}")
 
@@ -896,10 +1135,30 @@ def install_pack(name: str, editor: str) -> bool:
         print(f"  Available: {', '.join(p['name'] for p in list_available())}")
         return False
 
+    # A pack may declare which runtimes it actually works on. Without this a
+    # pack installs everywhere and silently does nothing on the runtimes it was
+    # never built for: a hook that speaks Claude Code's payload format would be
+    # wired into Codex and never fire.
+    supported = pack.get("supported_editors")
+    if isinstance(supported, list) and supported and editor not in supported:
+        print(
+            f"  Skipping: {name} does not support {editor} "
+            f"(supported: {', '.join(supported)})"
+        )
+        return False
+
     pack_dir = Path(pack["_dir"])
     print(f"  Installing: {name} for {editor} ({pack.get('description', '')})")
 
-    ok = install_pack_claude(name, pack, pack_dir) if editor == "claude" else install_pack_codex(name, pack, pack_dir)
+    if editor == "claude":
+        ok = install_pack_claude(name, pack, pack_dir)
+    elif editor == "codex":
+        ok = install_pack_codex(name, pack, pack_dir)
+    elif editor in JSON_HOOK_RUNTIMES:
+        ok = install_pack_json_runtime(editor, name, pack, pack_dir)
+    else:
+        print(f"  ERROR: no installer for runtime '{editor}'")
+        return False
     if not ok:
         return False
 
@@ -908,6 +1167,10 @@ def install_pack(name: str, editor: str) -> bool:
     if name not in installed:
         installed.append(name)
     _set_installed(state, editor, installed)
+    # Recorded so `update --all` can skip a pack whose manifest has not moved.
+    # Without it, update removes and reinstalls every pack every time, which for
+    # a pack that downloads a binary means refetching it on every core update.
+    _record_version(state, editor, name, str(pack.get("version", "")))
     save_state(state)
     return True
 
@@ -931,27 +1194,56 @@ def remove_pack(name: str, editor: str) -> bool:
         for other in VALID_EDITORS
         if other != editor
     )
-    ok = (
-        remove_pack_claude(name, pack, pack_dir, keep_shared_assets=keep_shared_assets)
-        if editor == "claude"
-        else remove_pack_codex(name, pack, pack_dir, keep_shared_assets=keep_shared_assets)
-    )
+    if editor == "claude":
+        ok = remove_pack_claude(name, pack, pack_dir, keep_shared_assets=keep_shared_assets)
+    elif editor == "codex":
+        ok = remove_pack_codex(name, pack, pack_dir, keep_shared_assets=keep_shared_assets)
+    elif editor in JSON_HOOK_RUNTIMES:
+        ok = remove_pack_json_runtime(
+            editor, name, pack, pack_dir, keep_shared_assets=keep_shared_assets
+        )
+    else:
+        print(f"  ERROR: no remover for runtime '{editor}'")
+        return False
     if not ok:
         return False
 
     installed = [p for p in installed if p != name]
     _set_installed(state, editor, installed)
+    _forget_version(state, editor, name)
     save_state(state)
     return True
 
 
-def update_pack(name: str, editor: str) -> bool:
+def pack_update_pending(name: str, editor: str) -> tuple[bool, str, str]:
+    """(needs_update, installed_version, available_version) for one pack."""
+    state = load_state()
+    if name not in _installed_for(state, editor):
+        return False, "", ""
+    pack = find_pack(name)
+    if not pack:
+        return False, _installed_version(state, editor, name), ""
+    available = str(pack.get("version", ""))
+    current = _installed_version(state, editor, name)
+    return current != available, current, available
+
+
+def update_pack(name: str, editor: str, *, force: bool = False) -> bool:
     state = load_state()
     if name not in _installed_for(state, editor):
         print(f"  Plugin '{name}' is not installed for {editor} — use 'install' instead")
         return False
 
-    print(f"  Updating: {name} for {editor}")
+    pending, current, available = pack_update_pending(name, editor)
+    if not pending and not force:
+        # Silent no-op by design: `ai-toolkit update` runs this for every
+        # installed pack on every invocation.
+        return True
+
+    if current and available:
+        print(f"  Updating: {name} for {editor} ({current} -> {available})")
+    else:
+        print(f"  Updating: {name} for {editor}")
     remove_pack(name, editor)
     return install_pack(name, editor)
 
@@ -1090,6 +1382,34 @@ def _show_memory_stats() -> None:
         print(f"    DB: {_human_size(MEMORY_DB.stat().st_size)} (error reading stats)")
 
 
+def _show_pack_status(name: str, pack_dir: Path) -> None:
+    """Let a pack report its own state via scripts/status.py.
+
+    Generic counterpart to the install-time init.py hook. Before this, anything
+    beyond a hook listing meant another hardcoded `if name == ...` branch, which
+    is why memory-pack is the only pack that ever reported anything.
+
+    The script owns its output format; it is indented and shown verbatim.
+    Failure is not an error: status must never be the thing that breaks.
+    """
+    status_script = pack_dir / "scripts" / "status.py"
+    if not status_script.is_file():
+        return
+    try:
+        result = subprocess.run(
+            ["python3", str(status_script)],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+    except (OSError, subprocess.SubprocessError) as exc:
+        print(f"    (status unavailable: {exc})")
+        return
+    stream = result.stdout if result.stdout.strip() else result.stderr
+    for line in stream.strip().splitlines():
+        print(f"    {line}")
+
+
 def cmd_status(editors: list[str]) -> None:
     state = load_state()
     shown = False
@@ -1108,15 +1428,17 @@ def cmd_status(editors: list[str]) -> None:
                 continue
             print(f"  {name}: {pack.get('description', '')}")
             if editor == "claude":
-                hooks = list(HOOKS_DIR.glob(f"plugin-{name}-*.sh"))
+                hooks = list(HOOKS_DIR.glob(f"plugin-{name}-*"))
                 if hooks:
                     print(f"    Hooks: {', '.join(h.name for h in hooks)}")
             elif editor == "codex":
-                hooks = sorted(CODEX_HOOKS_DIR.glob(f"plugin-{name}-*.sh"))
+                hooks = sorted(CODEX_HOOKS_DIR.glob(f"plugin-{name}-*"))
                 if hooks:
                     print(f"    Hooks: {', '.join(h.name for h in hooks)}")
             if name == "memory-pack":
                 _show_memory_stats()
+            else:
+                _show_pack_status(name, Path(pack["_dir"]))
         print()
 
     if not shown and all(not _installed_for(state, editor) for editor in editors):
@@ -1162,8 +1484,8 @@ def _parse_editors(args: list[str]) -> tuple[list[str], list[str]]:
 
 def _cmd_install(args: list[str], editors: list[str]) -> None:
     if not args:
-        print("Usage: ai-toolkit plugin install [--editor claude|codex|all] <pack-name> [...]")
-        print("       ai-toolkit plugin install [--editor claude|codex|all] --all")
+        print("Usage: ai-toolkit plugin install [--editor claude|codex|cursor|gemini|all] <pack-name> [...]")
+        print("       ai-toolkit plugin install [--editor claude|codex|cursor|gemini|all] --all")
         sys.exit(1)
     names = [pack["name"] for pack in list_available()] if "--all" in args else args
     for editor in editors:
@@ -1181,8 +1503,8 @@ def _cmd_install(args: list[str], editors: list[str]) -> None:
 
 def _cmd_remove(args: list[str], editors: list[str]) -> None:
     if not args:
-        print("Usage: ai-toolkit plugin remove [--editor claude|codex|all] <pack-name> [...]")
-        print("       ai-toolkit plugin remove [--editor claude|codex|all] --all")
+        print("Usage: ai-toolkit plugin remove [--editor claude|codex|cursor|gemini|all] <pack-name> [...]")
+        print("       ai-toolkit plugin remove [--editor claude|codex|cursor|gemini|all] --all")
         sys.exit(1)
     state = load_state()
     for editor in editors:
@@ -1198,25 +1520,57 @@ def _cmd_remove(args: list[str], editors: list[str]) -> None:
 
 def _cmd_update(args: list[str], editors: list[str]) -> None:
     if not args:
-        print("Usage: ai-toolkit plugin update [--editor claude|codex|all] <pack-name> [...]")
-        print("       ai-toolkit plugin update [--editor claude|codex|all] --all")
+        print("Usage: ai-toolkit plugin update [--editor claude|codex|cursor|gemini|all] <pack-name> [...]")
+        print("       ai-toolkit plugin update [--editor claude|codex|cursor|gemini|all] --all [--dry-run]")
         sys.exit(1)
+
+    dry_run = "--dry-run" in args or "--list" in args
+    force = "--force" in args
+    everything = "--all" in args
+    explicit = [a for a in args if not a.startswith("--")]
+
     state = load_state()
     for editor in editors:
-        names = list(_installed_for(state, editor)) if "--all" in args else args
+        names = list(_installed_for(state, editor)) if everything else explicit
         if not names:
+            if everything:
+                # Nothing installed is the common case; do not make the core
+                # update noisy about it.
+                continue
             print(f"No plugins installed for {editor}.")
             print()
             continue
-        if "--all" in args:
-            print(f"Updating {len(names)} installed plugin(s) for {editor}...\n")
+
+        if dry_run:
+            pending = []
+            for name in names:
+                needs, current, available = pack_update_pending(name, editor)
+                if needs or force:
+                    pending.append(f"{name} ({current or 'unrecorded'} -> {available or 'unknown'})")
+            if pending:
+                print(f"Would update for {editor}: {', '.join(pending)}")
+            else:
+                print(f"All {len(names)} pack(s) up to date for {editor}")
+            print()
+            continue
+
         ok = 0
+        failed: list[str] = []
         for name in names:
-            if update_pack(name, editor):
-                ok += 1
-            print()
-        if "--all" in args:
+            try:
+                if update_pack(name, editor, force=force):
+                    ok += 1
+                else:
+                    failed.append(name)
+            except Exception as exc:  # noqa: BLE001
+                # A pack failure must never abort the run: `ai-toolkit update`
+                # calls this after the core update has already succeeded.
+                print(f"  WARN update failed for {name}: {exc}")
+                failed.append(name)
+        if everything and (failed or force):
             print(f"Updated: {ok}/{len(names)} packs for {editor}")
+            if failed:
+                print(f"  Failed: {', '.join(failed)}")
             print()