claude-code-arcane 1.0.0

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

@@ -0,0 +1,192 @@
+---
+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.
+---
+
+# Worktree Isolation — Setup (one-time)
+
+This is the **opt-in, project-level** prep that complements the `worktree-isolation` runtime skill. Run it once per repo to make compose files + project docs natively cooperative with the per-worktree port allocator, and to ensure the SessionStart hook is installed on the current machine.
+
+After this runs:
+- `docker-compose*.yml` ports + `container_name` are parameterized with `${VAR-default}`
+- `CLAUDE.md` test commands reference the same env vars
+- `.gitignore` excludes the runtime-generated `.env.worktree` + `*.worktree.yml`
+- `~/.claude/scripts/worktree-isolation/` has `apply.py` + `lib.py` copied
+- `~/.claude/settings.json` has a `SessionStart` hook that runs `apply.py --quiet` on every session start
+
+For an in-depth explanation of how isolation works (hook lifecycle, override generation, port allocation, compose chaining), see [README.md](README.md).
+
+---
+
+## Step 1 — Ensure the global hook is installed
+
+Run the bundled installer. It is idempotent — safe to re-run.
+
+```bash
+python3 scripts/install_hook.py
+```
+
+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`
+
+If the hook is already present, it reports "already present" and exits 0.
+
+---
+
+## Step 2 — Inventory the repo
+
+Read every `docker-compose*.yml` / `compose*.yml` in the repo root. For each service, identify:
+
+- **Hardcoded ports**: e.g. `"54399:5432"` → propose `"${POSTGRES_INTEGRATION_5432_HOST_PORT-54399}:5432"`
+- **Hardcoded `container_name:`**: e.g. `container_name: rr-processing-pg` → propose `container_name: rr-processing-pg${WORKTREE_SUFFIX-}`
+- **Already-substituted ports** (e.g. `"${TEST_DB_PORT-5433}:5432"`) → leave alone, just note them
+
+Env var naming convention (must match the runtime hook's `env_var_name()`):
+
+```
+<SERVICE_UPPERSNAKE>_<CONTAINER_PORT>_HOST_PORT
+```
+
+Examples:
+- service `postgres-integration` + container port `5432` → `POSTGRES_INTEGRATION_5432_HOST_PORT`
+- service `server` + container port `8000` → `SERVER_8000_HOST_PORT`
+- service `db` + container port `5432` → `DB_5432_HOST_PORT`
+
+Then read `CLAUDE.md` (if present) and find lines that hardcode legacy host ports (e.g. `localhost:54399`). Propose substitutions with the matching env var.
+
+Also check `.gitignore`: identify whether `.env.worktree` and `*.worktree.yml` are already listed.
+
+---
+
+## Step 3 — Confirm with the user
+
+Use `AskUserQuestion` (multiSelect: true) listing the proposed changes. Group by file. Example options:
+
+- `docker-compose.processing.yml: parameterize ports + container_name (5 changes)`
+- `docker-compose.integration.yml: parameterize ports + container_name (2 changes)`
+- `CLAUDE.md: replace 6 hardcoded localhost:PORT references with $VAR`
+- `CLAUDE.md: add "Worktree isolation" section`
+- `.gitignore: add .env.worktree and *.worktree.yml`
+
+Default: all selected. Show the actual diffs in your text response before invoking `AskUserQuestion` so the user can decide informed.
+
+---
+
+## Step 4 — Apply
+
+Use the `Edit` tool with surgical replacements that preserve surrounding YAML/Markdown formatting (comments, blank lines, indentation). Do NOT use yaml round-tripping or full-file rewrites — those drop comments and reorder keys.
+
+### Compose port transformation
+
+Find:
+```yaml
+    ports:
+      - "54399:5432"
+```
+
+Replace the port string only:
+```yaml
+    ports:
+      - "${POSTGRES_INTEGRATION_5432_HOST_PORT-54399}:5432"
+```
+
+For port forms with explicit host IP (`"127.0.0.1:54399:5432"`), parameterize only the middle field. For multi-port entries (`["8080:80", "8443:443"]`), parameterize each independently.
+
+### `container_name` transformation
+
+```yaml
+    container_name: rr-processing-pg
+```
+→
+```yaml
+    container_name: rr-processing-pg${WORKTREE_SUFFIX-}
+```
+
+Default empty preserves existing behavior (single-checkout stays unchanged). The runtime hook sets `WORKTREE_SUFFIX=-<worktree_id>` in `.env.worktree`.
+
+### `CLAUDE.md` test-command transformation
+
+Find:
+```bash
+DATABASE_URL=postgresql://rr_test:rr_test_pw@localhost:54399/rr_integration uv run pytest ...
+```
+
+Replace with:
+```bash
+DATABASE_URL=postgresql://rr_test:rr_test_pw@localhost:${POSTGRES_INTEGRATION_5432_HOST_PORT-54399}/rr_integration uv run pytest ...
+```
+
+If commands rely on `source .env.worktree`, surface that in a small preamble:
+```bash
+set -a; source .env.worktree 2>/dev/null; set +a
+```
+
+### `CLAUDE.md` "Worktree isolation" section
+
+Append (or insert near the top of the testing/dev section):
+
+````markdown
+## Worktree isolation
+
+This repo is wired to work with Claude Code's `worktree-isolation` runtime hook. Every worktree gets a deterministic set of host ports + a unique `COMPOSE_PROJECT_NAME` so multiple worktrees can run their stacks in parallel.
+
+The runtime hook generates `.env.worktree` on session start. To bring up the stack:
+
+```bash
+set -a; source .env.worktree; set +a
+docker compose up -d
+```
+
+Test commands above reference worktree-aware env vars (e.g. `${POSTGRES_INTEGRATION_5432_HOST_PORT-54399}`). Source `.env.worktree` once per shell and they Just Work.
+
+If `.env.worktree` is missing, run the `worktree-isolation` skill (it regenerates the file).
+````
+
+### `.gitignore`
+
+Append (only if missing):
+```
+# Worktree isolation (generated per-worktree)
+.env.worktree
+*.worktree.yml
+*.worktree.yaml
+```
+
+---
+
+## Step 5 — Verify
+
+```bash
+docker compose config --services 2>&1 | head
+```
+
+Should succeed. The output won't show env-substitution failures because defaults cover them.
+
+Then re-run the runtime hook to confirm it picks up the new structure:
+```bash
+~/.claude/scripts/worktree-isolation/apply.py --cwd "$PWD" --verbose --force
+```
+
+Confirm:
+- `.env.worktree` is generated
+- The captured `var_name`s match the ones introduced (the hook detects `${VAR-default}` and exports `VAR` automatically)
+
+---
+
+## Edge cases
+
+- **Service with `expose:` only (no `ports:`)** — nothing to do. Internal-only services don't need parameterization.
+- **`docker-compose.override.yml` exists** — leave it alone. The runtime hook generates `*.worktree.yml` siblings, which are different files.
+- **Compose file under `version: '3.x'`** — still works (Compose v2 reads it). The `version` line is obsolete but not harmful.
+- **Repo has its own `.env.example`** — do NOT add the new vars there. Defaults live inline in compose substitutions; `.env.example` is for app-level secrets.
+- **`CLAUDE.md` mentions ports in prose** ("the integration DB listens on port 54399") — leave prose unchanged. Only rewrite executable command examples.
+- **`tests/` hardcodes a port** — out of scope. Surface it to the user as a follow-up.
+
+---
+
+## Out of scope
+
+- Does not run `docker compose up`. Verification stops at `docker compose config`.
+- Does not modify application code or test fixtures.
+- Does not try to be "smart" about which ports are safe to expose — compose port intent is taken at face value from `ports:`.

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

@@ -0,0 +1,178 @@
+#!/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

@@ -0,0 +1,118 @@
+#!/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())