claude-code-arcane 2.9.9 → 2.11.0

package/skills/worktree-isolation/README.md

@@ -8,22 +8,22 @@ This README explains **how worktree isolation works under the hood**. For usage,
 
 ## Install
 
+Ships with the `infra` and backend profiles. Elsewhere:
+
 ```bash
-npx skills add https://github.com/educabot/team-ai-skills --skill worktree-isolation
+npx claude-code-arcane add worktree-isolation
 ```
 
-> The host repo is private — `npx skills add` clones via Git, so the machine needs GitHub credentials with read access (e.g. `gh auth login` or an SSH key on the account).
-
-After install, invoke with phrases like:
+Then invoke with phrases like:
 
 - `isolate worktree`
 - `regenerate worktree ports`
 - `which ports is this worktree using?`
 
-If you also want a SessionStart hook that runs this automatically on every Claude Code session start, install the companion skill:
+If you also want it to run automatically on every Claude Code session start, install the SessionStart hook once per machine:
 
 ```bash
-npx skills add https://github.com/educabot/team-ai-skills --skill worktree-isolation-setup
+npx claude-code-arcane global
 ```
 
 ---

package/skills/worktree-isolation/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: worktree-isolation
-description: On-demand worktree isolation for the current directory. Regenerates per-worktree docker-compose overrides + .env.worktree so multiple Claude Code worktrees can run their stacks in parallel without port or container-name collisions, and inspects the current allocation. Use when (1) the SessionStart hook didn't fire (new project, hook not installed, fresh clone), (2) docker-compose.yml changed mid-session and overrides need regenerating, (3) the user wants to inspect which host ports this worktree is mapped to. Trigger phrases include "isolate worktree", "regenerate worktree ports", "show worktree ports", "what ports is this worktree using", "worktree didn't isolate", "fix port collision", "aislar worktree".
+description: "Regenerate or show this worktree's Docker ports (.env.worktree + compose overrides) so parallel worktrees don't collide. Leaves repo files alone; to prepare a repo once, use worktree-isolation-setup."
+argument-hint: "[apply | status]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
 ---
 
 # Worktree Isolation — On-Demand
@@ -81,7 +84,7 @@ This skill does not auto-rewrite `CLAUDE.md` or scripts (zero-touch on project f
 
 ## Out of scope
 
-- Does not install the SessionStart hook globally. Use [`worktree-isolation-setup`](../worktree-isolation-setup/) for that.
+- Does not install the SessionStart hook. `npx claude-code-arcane global` does that, once per machine.
 - Does not modify the repo's compose files / `CLAUDE.md` / `.gitignore`. Use [`worktree-isolation-setup`](../worktree-isolation-setup/) for that.
 - Does not clean up orphan stacks from deleted worktrees. For now, `docker compose ls` and `docker compose -p <project-name> down -v` manually.
 - Does not handle non-docker dev servers (Next.js, uvicorn directly on host).

package/skills/worktree-isolation-setup/README.md

@@ -8,13 +8,13 @@ This README explains **what setup does and why**. For step-by-step instructions,
 
 ## Install
 
+Ships with the `infra` and backend profiles, next to `worktree-isolation`. Elsewhere:
+
 ```bash
-npx skills add https://github.com/educabot/team-ai-skills --skill worktree-isolation-setup
+npx claude-code-arcane add worktree-isolation-setup
 ```
 
-> The host repo is private — `npx skills add` clones via Git, so the machine needs GitHub credentials with read access (e.g. `gh auth login` or an SSH key on the account).
-
-After install, run the skill once per repo:
+Then run the skill once per repo:
 
 ```
 setup worktree isolation in this project
@@ -80,7 +80,7 @@ After setup, both work in parallel.
 │                                                                     │
 │    user → "setup worktree isolation in this project"                │
 │      → this skill runs                                              │
-│        ├─ install_hook.py        (one-time per machine; idempotent) │
+│        ├─ arcane global          (one-time per machine; idempotent) │
 │        ├─ rewrites compose files (port + container_name params)     │
 │        ├─ updates .gitignore                                        │
 │        └─ amends CLAUDE.md                                          │
@@ -127,11 +127,7 @@ For deep-dive details on how the runtime script works (port allocation, override
 ```
 skills/worktree-isolation-setup/
 ├── SKILL.md             # entry point — step-by-step setup procedure
-├── README.md            # this file
-└── scripts/
-    ├── install_hook.py  # idempotent installer for the hook + scripts
-    ├── apply.py         # copied into ~/.claude/scripts/ by install_hook.py
-    └── lib.py           # ditto
+└── README.md            # this file
 ```
 
-`apply.py` and `lib.py` are duplicated from the [`worktree-isolation`](../worktree-isolation/) skill so this skill is self-contained. The runtime skill bundles its own copies for direct invocation.
+This skill has no scripts of its own. The runtime scripts live in [`worktree-isolation`](../worktree-isolation/scripts/), and `npx claude-code-arcane global` copies them from there into `~/.claude/scripts/`.

package/skills/worktree-isolation-setup/SKILL.md

@@ -1,6 +1,9 @@
 ---
 name: worktree-isolation-setup
-description: One-time per-repo setup that makes a project natively friendly to the worktree-isolation runtime. Refactors docker-compose port mappings + container_name to use ${VAR-default} substitutions, updates .gitignore, amends CLAUDE.md test commands, and ensures the global SessionStart hook + scripts are installed on the user's machine. Run once per repo. Trigger phrases include "setup worktree isolation in this project", "prepare repo for worktree isolation", "make this repo isolation-aware", "preparar repo para worktrees paralelos". DO NOT use mid-session for routine port regeneration — that is the `worktree-isolation` skill.
+description: "Prepare a repo once for parallel worktrees: parameterize docker-compose ports and container names, update .gitignore and CLAUDE.md, install the SessionStart hook. Edits repo files; to regenerate or show ports, use worktree-isolation."
+argument-hint: ""
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Edit
 ---
 
 # Worktree Isolation — Setup (one-time)
@@ -20,17 +23,23 @@ For an in-depth explanation of how isolation works (hook lifecycle, override gen
 
 ## Step 1 — Ensure the global hook is installed
 
-Run the bundled installer. It is idempotent — safe to re-run.
+The hook is per machine, so check first:
 
 ```bash
-python3 scripts/install_hook.py
+npx claude-code-arcane global --status
+```
+
+If the SessionStart hook is not active, install it. It is idempotent — safe to re-run:
+
+```bash
+npx claude-code-arcane global
 ```
 
 What it does:
-1. Copies `scripts/apply.py` + `scripts/lib.py` into `~/.claude/scripts/worktree-isolation/`
-2. Adds (or confirms) a `SessionStart` hook in `~/.claude/settings.json` that invokes `~/.claude/scripts/worktree-isolation/apply.py --quiet`
+1. Copies `apply.py` + `lib.py` into `~/.claude/scripts/worktree-isolation/`
+2. Adds a `SessionStart` hook in `~/.claude/settings.json` that invokes `~/.claude/scripts/worktree-isolation/apply.py --quiet`
 
-If the hook is already present, it reports "already present" and exits 0.
+It refuses to touch a malformed `settings.json`; if it stops there, tell the user and continue with Step 2 — the repo changes do not depend on the hook.
 
 ---
 

package/skills/worktree-isolation-setup/scripts/apply.py

@@ -1,178 +0,0 @@
-#!/usr/bin/env -S uv run --script --quiet
-# /// script
-# requires-python = ">=3.11"
-# dependencies = ["pyyaml"]
-# ///
-"""Worktree isolation entry point.
-
-Two callers:
-  1. Claude Code SessionStart hook → `apply.py --quiet` (emits hook JSON).
-  2. worktree-isolation skill → `apply.py --verbose --force` or `--status`.
-
-Reads the project's docker-compose*.yml files, generates per-worktree override
-files (sibling .worktree.yml) with deterministic randomized host ports + suffixed
-container_names, writes .env.worktree, and registers the generated files in the
-per-worktree git exclude list.
-"""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent))
-
-import yaml  # noqa: E402
-
-from lib import (  # noqa: E402
-    PortMapping,
-    collect_container_names,
-    collect_port_mappings,
-    ensure_git_exclude,
-    find_compose_files,
-    overrides_up_to_date,
-    override_path_for,
-    render_env_worktree,
-    render_override_yaml,
-    worktree_id,
-)
-
-
-def _build_summary(
-    project_name: str,
-    worktree: str,
-    compose_chain: list[tuple[Path, Path | None]],
-    mappings: list[PortMapping],
-) -> str:
-    lines = [
-        f"Worktree isolation active: project='{project_name}' (id={worktree}).",
-        "",
-        "Port mappings (legacy → worktree host):",
-    ]
-    for m in sorted(mappings, key=lambda x: (x.service, x.container_port)):
-        lines.append(
-            f"  {m.service}  container :{m.container_port}  →  host {m.new_host_port}  "
-            f"(was {m.original_host_port})"
-        )
-    lines += [
-        "",
-        "To bring up the stack from this worktree:",
-        "  set -a; source .env.worktree; set +a",
-        "  docker compose up -d",
-        "(COMPOSE_FILE in .env.worktree auto-chains base + override files.)",
-        "",
-        "When running ad-hoc commands (e.g. test commands in CLAUDE.md) that hardcode",
-        "legacy host ports like " + ", ".join(sorted({str(m.original_host_port) for m in mappings}))
-        + ", substitute the matching new host port from the table above before executing.",
-    ]
-    return "\n".join(lines)
-
-
-def _run(args: argparse.Namespace) -> int:
-    cwd = args.cwd.resolve()
-
-    if args.status:
-        env_file = cwd / ".env.worktree"
-        if not env_file.exists():
-            print(f"No .env.worktree at {cwd}. Run with --force to generate.", file=sys.stderr)
-            return 1
-        print(env_file.read_text())
-        return 0
-
-    compose_files = find_compose_files(cwd)
-    if not compose_files:
-        if args.quiet:
-            print(json.dumps({"continue": True}))
-        elif args.verbose:
-            print(f"No docker-compose files in {cwd}. Nothing to isolate.")
-        return 0
-
-    wid = worktree_id(cwd)
-    project_name = f"{cwd.name}-{wid}"
-    env_file = cwd / ".env.worktree"
-
-    compose_chain: list[tuple[Path, Path | None]] = []
-    all_mappings: list[PortMapping] = []
-    regenerated_any = False
-
-    for base in compose_files:
-        mappings = collect_port_mappings(base, wid)
-        container_names = collect_container_names(base)
-
-        if not mappings and not container_names:
-            # Nothing to override for this file — still include in chain for completeness? No,
-            # if there's nothing to override, the base alone is fine. Skip.
-            continue
-
-        override_path = override_path_for(base)
-
-        if not args.force and overrides_up_to_date(base, override_path, env_file):
-            compose_chain.append((base, override_path))
-            all_mappings.extend(mappings)
-            continue
-
-        override_yaml_data = render_override_yaml(mappings, container_names, project_name, wid)
-        with open(override_path, "w") as f:
-            f.write("# Auto-generated by ~/.claude/scripts/worktree-isolation/apply.py\n")
-            f.write("# DO NOT COMMIT. Regenerate with the worktree-isolation skill.\n")
-            yaml.safe_dump(override_yaml_data, f, sort_keys=False, default_flow_style=False)
-        compose_chain.append((base, override_path))
-        all_mappings.extend(mappings)
-        regenerated_any = True
-
-    if not compose_chain:
-        if args.quiet:
-            print(json.dumps({"continue": True}))
-        elif args.verbose:
-            print(f"No services with ports or container_name in {cwd}. Nothing to isolate.")
-        return 0
-
-    # Always write env file when we have a chain — covers fresh dirs even if overrides exist.
-    env_content = render_env_worktree(project_name, wid, compose_chain, all_mappings)
-    if not env_file.exists() or env_file.read_text() != env_content:
-        env_file.write_text(env_content)
-        regenerated_any = True
-
-    ensure_git_exclude(cwd, [".env.worktree", "*.worktree.yml", "*.worktree.yaml"])
-
-    summary = _build_summary(project_name, wid, compose_chain, all_mappings)
-
-    if args.quiet:
-        out = {
-            "hookSpecificOutput": {
-                "hookEventName": "SessionStart",
-                "additionalContext": summary,
-            }
-        }
-        print(json.dumps(out))
-    else:
-        print(summary)
-        if not regenerated_any:
-            print("\n(no changes — overrides already up to date)")
-    return 0
-
-
-def main() -> int:
-    parser = argparse.ArgumentParser(description="Per-worktree docker-compose isolation.")
-    parser.add_argument("--cwd", type=Path, default=Path.cwd(), help="Working directory")
-    parser.add_argument("--quiet", action="store_true", help="Hook mode: emit JSON only")
-    parser.add_argument("--verbose", action="store_true", help="Skill mode: human output")
-    parser.add_argument("--force", action="store_true", help="Regenerate even if up-to-date")
-    parser.add_argument("--status", action="store_true", help="Print current .env.worktree only")
-    args = parser.parse_args()
-
-    try:
-        return _run(args)
-    except Exception as exc:  # noqa: BLE001 — fail loud; hook captures stderr
-        if args.quiet:
-            # Don't break the session — emit a minimal valid hook response and log to stderr.
-            print(json.dumps({"continue": True}))
-            print(f"worktree-isolation error: {exc}", file=sys.stderr)
-            return 0
-        raise
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/skills/worktree-isolation-setup/scripts/install_hook.py

@@ -1,118 +0,0 @@
-#!/usr/bin/env python3
-"""Install the worktree-isolation SessionStart hook globally.
-
-Idempotent. Safe to re-run.
-
-What it does:
-1. Copies `apply.py` + `lib.py` from this skill's `scripts/` dir into
-   `~/.claude/scripts/worktree-isolation/` (creating the dir if needed).
-2. Ensures `~/.claude/settings.json` has a `SessionStart` hook entry that
-   invokes the copied `apply.py --quiet`.
-
-Re-running is a no-op if the hook + scripts are already in place.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import shutil
-import stat
-import sys
-from pathlib import Path
-
-HOME = Path.home()
-TARGET_DIR = HOME / ".claude" / "scripts" / "worktree-isolation"
-SETTINGS_PATH = HOME / ".claude" / "settings.json"
-HOOK_COMMAND = f"{TARGET_DIR}/apply.py --quiet"
-
-SCRIPTS_TO_COPY = ("apply.py", "lib.py")
-
-
-def copy_scripts(source_dir: Path) -> list[str]:
-    """Copy hook scripts into ~/.claude/scripts/worktree-isolation/. Returns list of actions taken."""
-    TARGET_DIR.mkdir(parents=True, exist_ok=True)
-    actions: list[str] = []
-    for name in SCRIPTS_TO_COPY:
-        src = source_dir / name
-        dst = TARGET_DIR / name
-        if not src.exists():
-            raise FileNotFoundError(f"Source script missing: {src}")
-        if dst.exists() and dst.read_bytes() == src.read_bytes():
-            actions.append(f"  • {name}: already up-to-date")
-            continue
-        shutil.copy2(src, dst)
-        # Ensure apply.py is executable.
-        if name == "apply.py":
-            mode = dst.stat().st_mode
-            dst.chmod(mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
-        actions.append(f"  • {name}: installed → {dst}")
-    return actions
-
-
-def hook_already_installed(settings: dict) -> bool:
-    for entry in settings.get("hooks", {}).get("SessionStart", []):
-        for hook in entry.get("hooks", []):
-            cmd = hook.get("command", "")
-            if "worktree-isolation/apply.py" in cmd and "--quiet" in cmd:
-                return True
-    return False
-
-
-def install_hook() -> str:
-    """Add SessionStart hook to ~/.claude/settings.json. Returns a status string."""
-    if SETTINGS_PATH.exists():
-        try:
-            settings = json.loads(SETTINGS_PATH.read_text())
-        except json.JSONDecodeError as exc:
-            raise SystemExit(
-                f"Refusing to modify malformed {SETTINGS_PATH}: {exc}. Fix manually and re-run."
-            )
-    else:
-        settings = {}
-
-    if hook_already_installed(settings):
-        return "  • SessionStart hook: already present (no change)"
-
-    hooks = settings.setdefault("hooks", {})
-    session_start = hooks.setdefault("SessionStart", [])
-
-    new_entry = {
-        "matcher": "",
-        "hooks": [{"type": "command", "command": HOOK_COMMAND}],
-    }
-
-    # Prefer to attach to an existing matcher="" entry rather than appending a new one.
-    for entry in session_start:
-        if entry.get("matcher", "") == "":
-            entry.setdefault("hooks", []).append(new_entry["hooks"][0])
-            break
-    else:
-        session_start.append(new_entry)
-
-    SETTINGS_PATH.parent.mkdir(parents=True, exist_ok=True)
-    SETTINGS_PATH.write_text(json.dumps(settings, indent=2) + "\n")
-    return f"  • SessionStart hook: added to {SETTINGS_PATH}"
-
-
-def main() -> int:
-    here = Path(__file__).resolve().parent
-    print(f"Installing worktree-isolation hook from {here}")
-    print()
-
-    print("1) Copying hook scripts:")
-    for line in copy_scripts(here):
-        print(line)
-
-    print()
-    print("2) Wiring SessionStart hook:")
-    print(install_hook())
-
-    print()
-    print("Done. Open a new Claude Code session inside any git worktree to verify.")
-    print(f"   .env.worktree should appear in the worktree root automatically.")
-    return 0
-
-
-if __name__ == "__main__":
-    sys.exit(main())