acstack 0.0.0-stage → 0.47.0

package/hooks/session-start-handoff.sh

@@ -0,0 +1,165 @@
+#!/usr/bin/env bash
+# ACStack handoff reload (consume-once, change-aware).
+#
+# When a session resumes after compaction (SessionStart source == "compact"),
+# re-inject the handoff anchor written by /acstack:compact-and-continue, then
+# retire it so it can never be injected twice.
+#
+# The compaction summary carries the conversation narrative; this anchor carries
+# the load-bearing state the summary may have compressed away (next action, task
+# ledger, agent-team file ownership, blockers).
+#
+# Active (pending) handoff lives at the fixed path acstack/HANDOFF.md, so this
+# hook reads one known file with no CLI call. The file's frontmatter records the
+# change it belongs to. On consume, the file is MOVED into that change's own
+# folder, accumulating a per-change history:
+#
+#   acstack/changes/<change>/handoffs/<timestamp>.md   (when the change dir exists)
+#   acstack/handoffs/<change>/<timestamp>.md           (ad-hoc, or change archived)
+#
+# Storing consumed handoffs inside the change dir means they travel with the
+# change when /acstack:archive moves it. Names are timestamped with a numeric
+# collision suffix (-2, -3, ...) so many handoffs accumulate without overwrite.
+#
+# No-op on a fresh startup, on --resume, on /clear, when no anchor exists, when
+# the anchor is empty, or when the file lacks the acstack_handoff marker (so a
+# user's own unrelated HANDOFF.md is never touched).
+#
+# Runs alongside session-start.sh as a second SessionStart hook. Claude Code
+# aggregates additionalContext from every matching hook, so this adds to the
+# orchestrator instruction injection rather than replacing it.
+
+set -u
+
+command -v python3 >/dev/null 2>&1 || exit 0
+
+# Capture the hook payload from stdin before running python. The heredoc below
+# becomes python's stdin (the program source), so the payload must travel via an
+# env var, not sys.stdin.
+ACSTACK_HOOK_INPUT="$(cat)"
+export ACSTACK_HOOK_INPUT
+
+python3 <<'PY'
+import json, os, re, shutil, sys
+
+try:
+    data = json.loads(os.environ.get("ACSTACK_HOOK_INPUT", ""))
+except Exception:
+    sys.exit(0)
+
+if not isinstance(data, dict):
+    sys.exit(0)
+
+if data.get("source") != "compact":
+    sys.exit(0)
+
+active = os.path.join("acstack", "HANDOFF.md")
+try:
+    with open(active, encoding="utf-8") as f:
+        raw = f.read()
+except OSError:
+    sys.exit(0)
+
+if not raw.strip():
+    sys.exit(0)
+
+
+def parse_frontmatter(text):
+    """Return (meta dict, body) for a simple --- key: value --- header.
+    Returns (None, text) when there is no recognizable frontmatter."""
+    if not text.startswith("---"):
+        return None, text
+    lines = text.split("\n")
+    end = None
+    for i in range(1, len(lines)):
+        if lines[i].strip() == "---":
+            end = i
+            break
+    if end is None:
+        return None, text
+    meta = {}
+    for line in lines[1:end]:
+        if ":" in line:
+            key, _, value = line.partition(":")
+            meta[key.strip()] = value.strip()
+    body = "\n".join(lines[end + 1:]).lstrip("\n")
+    return meta, body
+
+
+meta, body = parse_frontmatter(raw)
+
+# Only consume files this plugin wrote. A bare HANDOFF.md without the marker is
+# left untouched.
+if not meta or "acstack_handoff" not in meta:
+    sys.exit(0)
+
+if not body.strip():
+    sys.exit(0)
+
+# "map" is the current key; "change" is accepted for anchors written by
+# pre-map versions of the handoff skill. The value feeds os.path.join, so
+# sanitize it the same way as the stamp – a name with "/" or ".." must not
+# route the archived handoff outside acstack/.
+change = meta.get("map") or meta.get("change") or "ad-hoc"
+change = re.sub(r"[^A-Za-z0-9._-]", "-", str(change))
+if not change.strip("."):
+    change = "ad-hoc"
+created = meta.get("created") or ""
+
+# Build a filesystem-safe stamp for the archived filename.
+stamp = re.sub(r"[^A-Za-z0-9._-]", "-", created) if created else ""
+if not stamp:
+    from datetime import datetime, timezone
+    stamp = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H-%M-%SZ")
+
+# Route to the change's own folder when that change dir exists, so consumed
+# handoffs travel with the change on /acstack:archive. Otherwise fall back to a
+# neutral top-level handoffs dir (ad-hoc work, or a change already archived).
+change_dir = os.path.join("acstack", "changes", change)
+if change != "ad-hoc" and os.path.isdir(change_dir):
+    archive_dir = os.path.join(change_dir, "handoffs")
+else:
+    archive_dir = os.path.join("acstack", "handoffs", change)
+
+# Find a non-colliding destination: <stamp>.md, then <stamp>-2.md, -3.md, ...
+dest = None
+try:
+    os.makedirs(archive_dir, exist_ok=True)
+    candidate = os.path.join(archive_dir, stamp + ".md")
+    n = 2
+    while os.path.exists(candidate):
+        candidate = os.path.join(archive_dir, "{}-{}.md".format(stamp, n))
+        n += 1
+    dest = candidate
+except OSError:
+    dest = None
+
+# Consume: move the active handoff into the archive. Best-effort - even if the
+# move fails, we still inject below so the resume is not lost.
+if dest:
+    try:
+        shutil.move(active, dest)
+    except OSError:
+        pass
+
+preamble = (
+    "The session was just compacted. The following ACStack handoff captures "
+    "load-bearing work state the summary may have compressed. Treat it as "
+    "authoritative for what to do next.\n\n"
+    "Resume now: when the user's next message is \"continue\" (or any short "
+    "nudge), pick up the work immediately from the Next action below - do not "
+    "wait for further instruction. If anything in this handoff or the "
+    "compaction summary is ambiguous or underspecified, ask the user "
+    "to resolve it before acting rather than guessing. Ask liberally: a "
+    "wrong assumption taken after compaction is expensive to unwind.\n\n"
+)
+
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": preamble + body,
+    }
+}))
+PY
+
+exit 0

package/hooks/session-start.sh

@@ -0,0 +1,214 @@
+#!/usr/bin/env bash
+# ACStack SessionStart hook.
+#
+# Two symlinks get refreshed on every session start:
+#
+#   1. ~/.claude/acstack/bin/acstack – the **agent-facing** invariant path. Every
+#      skill and agent in this plugin invokes the CLI through this exact path.
+#      It is referenced by absolute path (no PATH, no env-var propagation, no
+#      shell-rc setup), and the hook re-resolves it to the current plugin cache
+#      version on every session start. Survives version bumps; survives stale
+#      caches; survives subshell PATH inheritance issues.
+#
+#   2. ~/.local/bin/acstack – the **human convenience** symlink. Lets users type
+#      `acstack` at a terminal if ~/.local/bin is on PATH. Not load-bearing for
+#      agents – if it breaks, nothing in the plugin breaks.
+#
+# Both symlinks point at ${CLAUDE_PLUGIN_ROOT}/cli/bin/acstack.js, which is a
+# tiny node wrapper that loads ../dist/index.js.
+#
+# When a project is initialized (acstack/project.yaml exists), the hook also
+# injects the plugin's orchestrator instructions as additionalContext so installs
+# stay version-agnostic. Otherwise prints a one-line reminder.
+
+set -u
+
+plugin_root="${CLAUDE_PLUGIN_ROOT:-}"
+troubleshoot="${plugin_root}/TROUBLESHOOTING.md"
+cli_wrapper="${plugin_root}/cli/bin/acstack.js"
+cli_dist="${plugin_root}/cli/dist/index.js"
+
+# Symlink $link to point at $src. Reports linked / updated / unchanged.
+# Args: $1 = source target, $2 = link path, $3 = human label for the log message.
+# Echoes a one-line status to stderr when a change happens or a warning fires.
+link_cli() {
+  local src="$1"
+  local link="$2"
+  local label="$3"
+  local dir
+  dir=$(dirname "$link")
+
+  if [ ! -e "$link" ] && [ ! -L "$link" ]; then
+    mkdir -p "$dir" 2>/dev/null
+    if ln -s "$src" "$link" 2>/dev/null; then
+      echo "acstack: linked ${label} at ${link} -> ${src}" >&2
+    else
+      echo "acstack: failed to create symlink at ${link} – see ${troubleshoot} (section: command not found)." >&2
+    fi
+  elif [ -L "$link" ]; then
+    local current
+    current=$(readlink "$link")
+    if [ "$current" != "$src" ]; then
+      if ln -sfn "$src" "$link" 2>/dev/null; then
+        echo "acstack: updated ${label} at ${link} -> ${src}" >&2
+      else
+        echo "acstack: failed to update stale symlink at ${link} (was: ${current}) – see ${troubleshoot} (section: stale cache)." >&2
+      fi
+    fi
+  elif [ -e "$link" ]; then
+    echo "acstack: ${link} exists but is not a symlink – not overwriting. See ${troubleshoot} (section: command not found)." >&2
+  fi
+}
+
+if [ -n "$plugin_root" ] && [ -f "$cli_wrapper" ]; then
+  if [ ! -f "$cli_dist" ]; then
+    echo "acstack: CLI is missing its built output (${cli_dist})." >&2
+    echo "acstack: this should not happen for a published version – see ${troubleshoot} (section: ERR_MODULE_NOT_FOUND)." >&2
+  else
+    # Agent-facing invariant path. Skills/agents invoke this directly.
+    link_cli "$cli_wrapper" "${HOME}/.claude/acstack/bin/acstack" "agent CLI"
+
+    # Human-convenience path. Only useful when ~/.local/bin is on PATH.
+    #
+    # Defer to any other acstack that already owns the name. The usual one is a
+    # global `npm install -g acstack-cli`, which people install to drive a
+    # project from outside Claude Code. Two managers pointing one command name
+    # at different copies is a silent PATH race: whichever directory sorts
+    # first wins, and it can differ per machine. Better to let the one the user
+    # installed deliberately win, and say so.
+    #
+    # The agent path above is never affected. It is absolute, so it always
+    # reaches this plugin's own CLI no matter what is on PATH.
+    human_link="${HOME}/.local/bin/acstack"
+    on_path=$(command -v acstack 2>/dev/null || true)
+    if [ -n "$on_path" ] && [ "$on_path" != "$human_link" ] &&
+       [ "$(readlink -f "$on_path" 2>/dev/null)" != "$(readlink -f "$human_link" 2>/dev/null)" ]; then
+      echo "acstack: \`acstack\` on PATH comes from ${on_path} – leaving it alone." >&2
+      echo "acstack: agents and skills are unaffected – they use ~/.claude/acstack/bin/acstack directly." >&2
+    else
+      link_cli "$cli_wrapper" "$human_link" "human CLI"
+    fi
+
+    if [ -L "$human_link" ]; then
+      case ":${PATH}:" in
+        *":${HOME}/.local/bin:"*) ;;
+        *)
+          # The human symlink exists but PATH won't pick it up. This only affects
+          # humans typing `acstack` at a terminal – agents are unaffected because
+          # they use the absolute ~/.claude/acstack/bin/acstack path.
+          rc_hint="~/.profile"
+          case "${SHELL:-}" in
+            */zsh) rc_hint="~/.zshrc" ;;
+            */bash) rc_hint="~/.bashrc (Linux) or ~/.bash_profile (macOS)" ;;
+            */fish) rc_hint="~/.config/fish/config.fish" ;;
+          esac
+          echo "acstack: ~/.local/bin is not on PATH – typed \`acstack\` won't work. Add this to ${rc_hint} and restart the shell:" >&2
+          echo "  export PATH=\"\$HOME/.local/bin:\$PATH\"" >&2
+          echo "acstack: agents and skills are unaffected – they use ~/.claude/acstack/bin/acstack directly. See ${troubleshoot} for details." >&2
+          ;;
+      esac
+    fi
+  fi
+fi
+
+# --- Codex subagents: keep ~/.codex/agents current with the plugin ---
+# Codex cannot ship agent definitions inside a plugin - its plugin manifest has
+# no agent field - so they have to be installed as files. This reconciles them
+# on every session, the same way the CLI symlink above is reconciled, so a
+# plugin upgrade heals them instead of leaving stale copies behind.
+#
+# Copies rather than symlinks: Codex is known to refuse symlinked skill
+# directories and manifests, and the agent loader's behaviour there is
+# unverified. A copy is boring and works.
+#
+# Only ever overwrites files this generator wrote. A file without the generated
+# marker is someone's own agent that happens to share a name, and clobbering it
+# would be unforgivable.
+if [ -n "$plugin_root" ] && [ -d "${HOME}/.codex" ]; then
+  codex_src="${plugin_root}/agents/codex"
+  codex_dst="${HOME}/.codex/agents"
+  marker="by scripts/gen-codex-agents.mjs"
+
+  if [ -d "$codex_src" ]; then
+    mkdir -p "$codex_dst" 2>/dev/null
+    for src in "$codex_src"/*.toml; do
+      [ -f "$src" ] || continue
+      dst="${codex_dst}/$(basename "$src")"
+
+      if [ -e "$dst" ] && ! grep -qF "$marker" "$dst" 2>/dev/null; then
+        echo "acstack: ${dst} was not written by acstack - leaving it alone." >&2
+        continue
+      fi
+
+      if ! cmp -s "$src" "$dst" 2>/dev/null; then
+        if cp "$src" "$dst" 2>/dev/null; then
+          echo "acstack: installed Codex agent $(basename "$src" .toml)" >&2
+        else
+          echo "acstack: could not write ${dst}" >&2
+        fi
+      fi
+    done
+  fi
+fi
+
+# --- Playwriter bridge: keep deployed scripts current with the plugin cache ---
+# The bridge runs as OS scheduled tasks (Windows) and an on-demand helper (VM)
+# that live outside the plugin, so a plugin update alone never reaches them.
+# Reconcile them here, the same way the CLI symlink above is reconciled. Both
+# branches no-op unless the bridge is actually present on this machine.
+if [ -n "$plugin_root" ]; then
+  case "$(uname -s 2>/dev/null)" in
+    MINGW*|MSYS*|CYGWIN*)
+      # Windows: copy changed bridge scripts out of the cache and restart only
+      # the affected tasks. sync.ps1 self-gates on "bridge installed".
+      sync_ps1="${plugin_root}/assets/playwriter-bridge/sync.ps1"
+      if [ -f "$sync_ps1" ] && command -v powershell.exe >/dev/null 2>&1; then
+        win_root=$(cygpath -w "$plugin_root" 2>/dev/null || printf '%s' "$plugin_root")
+        win_sync=$(cygpath -w "$sync_ps1" 2>/dev/null || printf '%s' "$sync_ps1")
+        powershell.exe -NoProfile -ExecutionPolicy Bypass -File "$win_sync" -PluginRoot "$win_root" >&2 2>&1 || true
+      fi
+      ;;
+    Linux|Darwin)
+      # VM / macOS: vm-free-port.sh is invoked on demand, so a symlink to the
+      # cache copy keeps it current with no copy and no restart - mirrors the
+      # agent-facing CLI symlink. Skips silently if the helper is not shipped.
+      vmfp_src="${plugin_root}/assets/playwriter-bridge/vm-free-port.sh"
+      vmfp_link="${HOME}/.claude/acstack/bin/vm-free-port.sh"
+      if [ -f "$vmfp_src" ]; then
+        link_cli "$vmfp_src" "$vmfp_link" "vm-free-port.sh"
+      fi
+      ;;
+  esac
+fi
+
+if [ ! -f acstack/project.yaml ]; then
+  echo 'acstack: no project config found. Run /acstack:setup to set up.' >&2
+  exit 0
+fi
+
+claude_md="${plugin_root}/orchestrator/AGENTS.md"
+
+if [ -z "$plugin_root" ] || [ ! -r "$claude_md" ]; then
+  echo "acstack: could not read orchestrator/AGENTS.md (CLAUDE_PLUGIN_ROOT=${plugin_root:-unset})" >&2
+  exit 0
+fi
+
+if ! command -v python3 >/dev/null 2>&1; then
+  echo 'acstack: python3 not found; skipping orchestrator injection' >&2
+  exit 0
+fi
+
+python3 - "$claude_md" <<'PY'
+import json, sys
+path = sys.argv[1]
+with open(path, 'r', encoding='utf-8') as f:
+    content = f.read()
+print(json.dumps({
+    "hookSpecificOutput": {
+        "hookEventName": "SessionStart",
+        "additionalContext": content,
+    }
+}))
+PY
+
+exit 0