@moretea-labs/forge 1.5.0-rc.1

package/scripts/canary-global-hook.sh

@@ -0,0 +1,263 @@
+#!/usr/bin/env bash
+# scripts/canary-global-hook.sh
+#
+# Phase 0 canary for forge global hook runtime.
+# Writes a tagged noop hook to ~/.codex/hooks.json AND ~/.claude/settings.json
+# for SessionStart, PreToolUse, PostToolUse, UserPromptSubmit, Stop events.
+# Each fire appends a line to ~/.forge-canary.log with host + event + repo.
+#
+# Goal: verify both hosts load user-level hooks; observe trust UX (Codex) and
+# auto-reload (Claude); confirm trust hash registration in ~/.codex/config.toml
+# under user-level [hooks.state] keys.
+#
+# See: plans/plan-20260528-1436-hook-global-runtime.md (Phase 0)
+#      tasks/notes/hook-global-runtime.notes.md (verification rounds 1+2)
+
+set -euo pipefail
+
+CANARY_LOG="${HOME}/.forge-canary.log"
+CODEX_HOOKS="${HOME}/.codex/hooks.json"
+CLAUDE_SETTINGS="${HOME}/.claude/settings.json"
+CODEX_CONFIG="${HOME}/.codex/config.toml"
+CANARY_TAG="forge-canary"
+
+EVENTS=(SessionStart PreToolUse PostToolUse UserPromptSubmit Stop)
+
+require_jq() {
+  if ! command -v jq >/dev/null 2>&1; then
+    echo "[canary] ERROR: jq is required (install: brew install jq)" >&2
+    exit 1
+  fi
+}
+
+# Build the hook command string that gets stored in JSON.
+# When fired, appends to CANARY_LOG: [tag] host=<X> event=<Y> repo=<path> ts=<iso>
+build_cmd_for() {
+  local host=$1
+  local event=$2
+  printf 'echo "[%s] host=%s event=%s repo=$(git rev-parse --show-toplevel 2>/dev/null || echo none) ts=$(date -Iseconds)" >> %s' \
+    "$CANARY_TAG" "$host" "$event" "$CANARY_LOG"
+}
+
+# Idempotent install: removes any prior entry tagged with CANARY_TAG, then appends fresh.
+install_to_file() {
+  local file=$1
+  local host=$2
+  local backup="${file}.${CANARY_TAG}-backup"
+
+  mkdir -p "$(dirname "$file")"
+  if [[ ! -f "$file" ]]; then
+    echo '{}' > "$file"
+  fi
+
+  # One-time backup
+  if [[ ! -f "$backup" ]]; then
+    cp "$file" "$backup"
+    echo "[canary] Backed up ${file} → ${backup}"
+  fi
+
+  local tmp
+  tmp=$(mktemp)
+  # Ensure .hooks exists
+  jq '.hooks //= {}' "$file" > "$tmp" && mv "$tmp" "$file"
+
+  for event in "${EVENTS[@]}"; do
+    local cmd
+    cmd=$(build_cmd_for "$host" "$event")
+    tmp=$(mktemp)
+    # 1) Remove any existing canary hookset for this event
+    jq --arg event "$event" --arg tag "$CANARY_TAG" '
+      .hooks[$event] = (
+        (.hooks[$event] // [])
+        | map(select(
+            (.hooks // [])
+            | all((.command // "") | contains($tag) | not)
+          ))
+      )
+    ' "$file" > "$tmp" && mv "$tmp" "$file"
+
+    # 2) Append fresh canary hookset
+    tmp=$(mktemp)
+    jq --arg event "$event" --arg cmd "$cmd" '
+      .hooks[$event] = (
+        (.hooks[$event] // [])
+        + [{"hooks":[{"type":"command","command":$cmd}]}]
+      )
+    ' "$file" > "$tmp" && mv "$tmp" "$file"
+  done
+
+  rm -f "$tmp"
+  echo "[canary] Installed ${host} canary hooks into ${file}"
+}
+
+uninstall_from_file() {
+  local file=$1
+  if [[ ! -f "$file" ]]; then
+    echo "[canary] ${file} does not exist, skipping"
+    return
+  fi
+
+  local tmp
+  for event in "${EVENTS[@]}"; do
+    tmp=$(mktemp)
+    jq --arg event "$event" --arg tag "$CANARY_TAG" '
+      .hooks[$event] = (
+        (.hooks[$event] // [])
+        | map(select(
+            (.hooks // [])
+            | all((.command // "") | contains($tag) | not)
+          ))
+      )
+    ' "$file" > "$tmp" && mv "$tmp" "$file"
+  done
+
+  # Drop empty event arrays for cleanliness
+  tmp=$(mktemp)
+  jq '.hooks |= with_entries(select(.value | length > 0))' "$file" > "$tmp" && mv "$tmp" "$file"
+  rm -f "$tmp"
+
+  echo "[canary] Removed canary entries from ${file} (backup preserved if any)"
+}
+
+status() {
+  echo "=== forge canary status ==="
+  echo "Tag: ${CANARY_TAG}"
+  echo "Log: ${CANARY_LOG}"
+  if [[ -f "$CANARY_LOG" ]]; then
+    local lines
+    lines=$(wc -l < "$CANARY_LOG" | tr -d ' ')
+    echo "  Lines: ${lines}"
+    if [[ "$lines" -gt 0 ]]; then
+      echo "  Last 5:"
+      tail -5 "$CANARY_LOG" | sed 's/^/    /'
+    fi
+  else
+    echo "  (not created yet — install + trigger events first)"
+  fi
+  echo ""
+
+  for pair in "codex:${CODEX_HOOKS}" "claude:${CLAUDE_SETTINGS}"; do
+    local host=${pair%%:*}
+    local file=${pair#*:}
+    echo "Host: ${host}"
+    echo "  File: ${file}"
+    if [[ -f "$file" ]]; then
+      local count
+      count=$(jq --arg tag "$CANARY_TAG" '
+        [.hooks // {}
+         | to_entries[]
+         | .value[]
+         | .hooks // []
+         | .[]
+         | select((.command // "") | contains($tag))
+        ] | length
+      ' "$file" 2>/dev/null || echo 0)
+      echo "  Canary hooks installed: ${count} (expected: ${#EVENTS[@]})"
+    else
+      echo "  (file does not exist)"
+    fi
+  done
+  echo ""
+
+  echo "=== Codex trust state (~/.codex/config.toml) ==="
+  if [[ -f "$CODEX_CONFIG" ]]; then
+    local pattern="^\[hooks\.state\.\"${HOME}/\.codex/hooks\.json"
+    local user_level
+    user_level=$(grep -c "$pattern" "$CODEX_CONFIG" 2>/dev/null || true)
+    user_level=${user_level:-0}
+    echo "  User-level trust hash entries (~/.codex/hooks.json:...): ${user_level}"
+    if [[ "$user_level" -gt 0 ]]; then
+      echo "  Sample (first 3):"
+      grep "$pattern" "$CODEX_CONFIG" | head -3 | sed 's/^/    /'
+    else
+      echo "  (none yet — Codex may not have prompted to trust the canary, or you declined)"
+    fi
+  else
+    echo "  (config.toml not found at ${CODEX_CONFIG})"
+  fi
+}
+
+usage() {
+  cat <<EOF
+Usage: $0 <install|uninstall|status|tail>
+
+  install    Add tagged canary hooks to ~/.codex/hooks.json AND ~/.claude/settings.json
+             Events: ${EVENTS[*]}
+             Each fire appends to: ${CANARY_LOG}
+             Backups: <file>.${CANARY_TAG}-backup (first install only)
+
+  uninstall  Remove canary entries from both hook config files (preserves backups + log)
+
+  status     Show canary entry count per host + Codex user-level trust hash registration
+
+  tail       tail -f ${CANARY_LOG}
+
+After install:
+  1. Restart Codex — may show trust prompt (accept to register hash)
+  2. Restart Claude Code OR wait for ConfigChange auto-reload
+  3. Trigger events:
+     - SessionStart: launching the agent
+     - UserPromptSubmit: send any prompt
+     - PreToolUse / PostToolUse: edit a file, run bash, etc.
+     - Stop: end the session
+  4. Run '$0 status' to confirm canary installed + Codex trust registration
+  5. Run '$0 tail' or 'tail ${CANARY_LOG}' to see fires
+  6. Repeat across 2-3 repos (opt-in + non-opt-in) for coverage
+  7. Record findings in docs/architecture/global-hook-runtime.md Host Operational Matrix
+  8. Run '$0 uninstall' to clean up
+
+EOF
+}
+
+main() {
+  case "${1:-}" in
+    install)
+      require_jq
+      install_to_file "$CODEX_HOOKS" "codex"
+      install_to_file "$CLAUDE_SETTINGS" "claude"
+      cat <<EOF
+
+[canary] Install complete. Next steps:
+  1. Restart Codex (you may see a trust prompt — accept it to register the hash)
+  2. Restart Claude Code, OR run any command to trigger ConfigChange auto-reload
+  3. Trigger events: send a prompt, edit a file, run bash, end session
+  4. tail -f ${CANARY_LOG}      # watch fires
+  5. $0 status                  # check hook count + Codex trust hash
+  6. $0 uninstall               # when done
+
+Backups created (first install only): ~/.codex/hooks.json.${CANARY_TAG}-backup
+                                       ~/.claude/settings.json.${CANARY_TAG}-backup
+EOF
+      ;;
+    uninstall)
+      require_jq
+      uninstall_from_file "$CODEX_HOOKS"
+      uninstall_from_file "$CLAUDE_SETTINGS"
+      echo ""
+      echo "[canary] Log preserved at ${CANARY_LOG} (delete manually if not needed)"
+      echo "[canary] Backups preserved at <file>.${CANARY_TAG}-backup (delete manually)"
+      ;;
+    status)
+      require_jq
+      status
+      ;;
+    tail)
+      if [[ ! -f "$CANARY_LOG" ]]; then
+        echo "[canary] Log not yet created at ${CANARY_LOG}"
+        echo "[canary] Run '$0 install' first, then trigger events"
+        exit 1
+      fi
+      exec tail -f "$CANARY_LOG"
+      ;;
+    -h|--help|help|"")
+      usage
+      ;;
+    *)
+      echo "[canary] Unknown command: $1" >&2
+      usage
+      exit 1
+      ;;
+  esac
+}
+
+main "$@"

package/scripts/capability-config.ts

@@ -0,0 +1,394 @@
+#!/usr/bin/env bun
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname, resolve } from "path";
+import { spawnSync } from "child_process";
+
+type ContractFiles = {
+  agents: string;
+  claude: string;
+};
+
+type Capability = {
+  id: string;
+  domain: string;
+  name: string;
+  prefixes: string[];
+  contract_files: ContractFiles;
+  architecture_module: string;
+  workstream_dir: string;
+  lsp_profile: string;
+  verification_hints: string[];
+};
+
+type Registry = {
+  version: number;
+  capabilities: Capability[];
+};
+
+type Format = "text" | "json";
+
+type Args = {
+  command: "add" | "";
+  repo: string;
+  prefix: string;
+  id: string;
+  domain: string;
+  name: string;
+  agents: string;
+  claude: string;
+  architectureModule: string;
+  workstreamDir: string;
+  lspProfile: string;
+  verificationHints: string[];
+  createPrefix: boolean;
+  createArchitectureModule: boolean;
+  createWorkstream: boolean;
+  syncContracts: boolean;
+  dryRun: boolean;
+  format: Format;
+};
+
+const REGISTRY_PATH = ".ai/context/capabilities.json";
+
+function usage(): never {
+  console.error(
+    [
+      "Usage:",
+      "  scripts/capability-config.ts add --prefix <path> [options]",
+      "",
+      "Options:",
+      "  --repo <path>                    Target repo (default: .)",
+      "  --id <id>                        Capability ID (default derived from prefix)",
+      "  --domain <domain>                Architecture domain (default derived from prefix)",
+      "  --name <name>                    Capability name (default derived from prefix)",
+      "  --agents <path>                  AGENTS.md path (default: <prefix>/AGENTS.md)",
+      "  --claude <path>                  CLAUDE.md path (default: <prefix>/CLAUDE.md)",
+      "  --architecture-module <path>     Architecture module path",
+      "  --workstream-dir <path>          Workstream directory path",
+      "  --lsp-profile <profile>          LSP/tooling profile (default: typescript-lsp)",
+      "  --verification-hint <command>    Repeatable local verification hint",
+      "  --create-prefix                  Create the prefix directory when missing",
+      "  --create-architecture-module     Create a minimal architecture module when missing",
+      "  --create-workstream              Create a durable workstream ledger",
+      "  --no-sync-contracts              Only update the registry",
+      "  --dry-run                        Print planned changes without writing",
+      "  --format text|json               Output format (default: text)",
+    ].join("\n")
+  );
+  process.exit(2);
+}
+
+function parseArgs(argv: string[]): Args {
+  const args: Args = {
+    command: (argv[0] as Args["command"]) || "",
+    repo: ".",
+    prefix: "",
+    id: "",
+    domain: "",
+    name: "",
+    agents: "",
+    claude: "",
+    architectureModule: "",
+    workstreamDir: "",
+    lspProfile: "typescript-lsp",
+    verificationHints: [],
+    createPrefix: false,
+    createArchitectureModule: false,
+    createWorkstream: false,
+    syncContracts: true,
+    dryRun: false,
+    format: "text",
+  };
+
+  for (let index = 1; index < argv.length; index += 1) {
+    const arg = argv[index];
+    switch (arg) {
+      case "--repo":
+        args.repo = argv[++index] || usage();
+        break;
+      case "--prefix":
+        args.prefix = argv[++index] || usage();
+        break;
+      case "--id":
+        args.id = argv[++index] || usage();
+        break;
+      case "--domain":
+        args.domain = argv[++index] || usage();
+        break;
+      case "--name":
+        args.name = argv[++index] || usage();
+        break;
+      case "--agents":
+        args.agents = argv[++index] || usage();
+        break;
+      case "--claude":
+        args.claude = argv[++index] || usage();
+        break;
+      case "--architecture-module":
+        args.architectureModule = argv[++index] || usage();
+        break;
+      case "--workstream-dir":
+        args.workstreamDir = argv[++index] || usage();
+        break;
+      case "--lsp-profile":
+        args.lspProfile = argv[++index] || usage();
+        break;
+      case "--verification-hint":
+        args.verificationHints.push(argv[++index] || usage());
+        break;
+      case "--create-prefix":
+        args.createPrefix = true;
+        break;
+      case "--create-architecture-module":
+        args.createArchitectureModule = true;
+        break;
+      case "--create-workstream":
+        args.createWorkstream = true;
+        break;
+      case "--no-sync-contracts":
+        args.syncContracts = false;
+        break;
+      case "--dry-run":
+        args.dryRun = true;
+        break;
+      case "--format": {
+        const format = argv[++index] as Format;
+        if (!["text", "json"].includes(format)) usage();
+        args.format = format;
+        break;
+      }
+      case "--help":
+      case "-h":
+        usage();
+        break;
+      default:
+        console.error(`capability-config: unknown argument: ${arg}`);
+        usage();
+    }
+  }
+
+  if (args.command !== "add" || !args.prefix) usage();
+  return args;
+}
+
+function repoRoot(input: string): string {
+  const cwd = resolve(input);
+  const result = spawnSync("git", ["rev-parse", "--show-toplevel"], {
+    cwd,
+    encoding: "utf-8",
+  });
+  if (result.status === 0 && result.stdout.trim()) return resolve(result.stdout.trim());
+  return cwd;
+}
+
+function normalizeRepoPath(value: string, repo: string): string {
+  let next = value.trim().replace(/^file:\/\//, "").replaceAll("\\", "/");
+  const normalizedRepo = repo.replaceAll("\\", "/");
+
+  if (next.startsWith(`${normalizedRepo}/`)) {
+    next = next.slice(normalizedRepo.length + 1);
+  } else if (next.startsWith("/")) {
+    throw new Error(`absolute path is outside repo: ${value}`);
+  }
+
+  next = next.replace(/^\.\//, "").replace(/\/+$/, "");
+  const parts = next.split("/").filter(Boolean);
+  if (parts.length === 0) throw new Error("path must not be empty");
+  if (parts.some((part) => part === "." || part === "..")) {
+    throw new Error(`path must not contain traversal: ${value}`);
+  }
+  return parts.join("/");
+}
+
+function safeToken(value: string, fallback = "capability"): string {
+  const token = value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .replace(/-{2,}/g, "-");
+  return token || fallback;
+}
+
+function defaultParts(prefix: string) {
+  const parts = prefix.split("/");
+  const domain =
+    parts.length >= 2 ? safeToken(`${parts[0]}-${parts[1]}`, safeToken(prefix)) : safeToken(prefix);
+  const name = parts.length > 2 ? safeToken(parts[parts.length - 1]) : safeToken(parts[parts.length - 1] || domain);
+  const id = parts.length > 2 ? `${domain}-${name}` : domain;
+  return { id, domain, name };
+}
+
+function buildCapability(args: Args, repo: string): Capability {
+  const prefix = normalizeRepoPath(args.prefix, repo);
+  const defaults = defaultParts(prefix);
+  const domain = safeToken(args.domain || defaults.domain);
+  const name = safeToken(args.name || defaults.name);
+  const id = safeToken(args.id || defaults.id);
+
+  return {
+    id,
+    domain,
+    name,
+    prefixes: [prefix],
+    contract_files: {
+      agents: normalizeRepoPath(args.agents || `${prefix}/AGENTS.md`, repo),
+      claude: normalizeRepoPath(args.claude || `${prefix}/CLAUDE.md`, repo),
+    },
+    architecture_module: normalizeRepoPath(
+      args.architectureModule || `docs/architecture/modules/${domain}/${name}.md`,
+      repo
+    ),
+    workstream_dir: normalizeRepoPath(args.workstreamDir || `tasks/workstreams/${domain}/${name}`, repo),
+    lsp_profile: args.lspProfile,
+    verification_hints:
+      args.verificationHints.length > 0 ? args.verificationHints : ["record local commands here before implementation"],
+  };
+}
+
+function readRegistry(repo: string): Registry {
+  const registryPath = resolve(repo, REGISTRY_PATH);
+  if (!existsSync(registryPath)) return { version: 1, capabilities: [] };
+  const parsed = JSON.parse(readFileSync(registryPath, "utf-8")) as Partial<Registry>;
+  return {
+    version: parsed.version ?? 1,
+    capabilities: Array.isArray(parsed.capabilities) ? parsed.capabilities : [],
+  };
+}
+
+function writeRegistry(repo: string, registry: Registry): void {
+  const registryPath = resolve(repo, REGISTRY_PATH);
+  mkdirSync(dirname(registryPath), { recursive: true });
+  writeFileSync(registryPath, `${JSON.stringify(registry, null, 2)}\n`);
+}
+
+function upsertCapability(registry: Registry, capability: Capability): { status: "added" | "existing"; capability: Capability } {
+  const prefix = capability.prefixes[0];
+  const existingById = registry.capabilities.find((entry) => entry.id === capability.id);
+  const existingByPrefix = registry.capabilities.find((entry) => (entry.prefixes || []).includes(prefix));
+
+  if (existingById && existingById !== existingByPrefix) {
+    throw new Error(`capability id already exists with different prefix: ${capability.id}`);
+  }
+  if (existingByPrefix && existingByPrefix.id !== capability.id) {
+    throw new Error(`capability prefix already belongs to ${existingByPrefix.id}: ${prefix}`);
+  }
+  if (existingById) return { status: "existing", capability: existingById };
+
+  registry.capabilities.push(capability);
+  return { status: "added", capability };
+}
+
+function runChecked(repo: string, command: string, args: string[]): string {
+  const result = spawnSync(command, args, {
+    cwd: repo,
+    encoding: "utf-8",
+  });
+  if (result.status !== 0) {
+    throw new Error([`${command} ${args.join(" ")} failed`, result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n"));
+  }
+  return result.stdout.trim();
+}
+
+function validateRegistry(repo: string): void {
+  runChecked(repo, process.execPath, ["scripts/capability-resolver.ts", "validate", "--repo", repo, "--format", "text"]);
+}
+
+function syncContracts(repo: string, capability: Capability): void {
+  const event = {
+    ts: new Date().toISOString(),
+    file_path: capability.prefixes[0],
+    severity: "medium",
+    functional_block: capability.prefixes[0],
+    capability_id: capability.id,
+    matched_prefix: capability.prefixes[0],
+    architecture_domain: capability.domain,
+    architecture_capability: capability.name,
+    architecture_module: capability.architecture_module,
+    workstream_dir: capability.workstream_dir,
+    contract_agents: capability.contract_files.agents,
+    contract_claude: capability.contract_files.claude,
+    lsp_profile: capability.lsp_profile,
+    change_type: "capability-config",
+    request_file: "none",
+    spawn_recommended: false,
+    contract_sync_required: true,
+  };
+
+  runChecked(repo, "bash", ["scripts/context-contract-sync.sh", "sync-event", "--json", JSON.stringify(event)]);
+}
+
+function createArchitectureModule(repo: string, capability: Capability): void {
+  const path = resolve(repo, capability.architecture_module);
+  if (existsSync(path)) return;
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(
+    path,
+    [
+      `# Architecture Module: ${capability.domain}/${capability.name}`,
+      "",
+      `> **Capability ID**: \`${capability.id}\``,
+      `> **Source**: \`${REGISTRY_PATH}\``,
+      "",
+      "## Responsibility",
+      "",
+      `Record stable boundaries, entrypoints, runtime paths, dependency rules, and verification hints for \`${capability.id}\`.`,
+      "",
+      "## Entrypoints",
+      "",
+      `- \`${capability.prefixes[0]}\``,
+      "",
+    ].join("\n")
+  );
+}
+
+function createWorkstream(repo: string, capability: Capability): void {
+  runChecked(repo, "bash", ["scripts/workstream-sync.sh", "ensure", "--block", capability.prefixes[0]]);
+}
+
+function main(): void {
+  const args = parseArgs(process.argv.slice(2));
+  const repo = repoRoot(args.repo);
+  const requestedCapability = buildCapability(args, repo);
+  const prefixPath = resolve(repo, requestedCapability.prefixes[0]);
+  const registry = readRegistry(repo);
+  const actions: string[] = [];
+
+  if (!existsSync(prefixPath)) {
+    if (!args.createPrefix) {
+      throw new Error(`capability prefix does not exist: ${requestedCapability.prefixes[0]} (use --create-prefix to create it)`);
+    }
+    actions.push(`create-prefix:${requestedCapability.prefixes[0]}`);
+    if (!args.dryRun) mkdirSync(prefixPath, { recursive: true });
+  }
+
+  const { status, capability } = upsertCapability(registry, requestedCapability);
+  actions.push(`${status}:${capability.id}`);
+
+  if (args.syncContracts) actions.push(`sync-contracts:${capability.contract_files.agents},${capability.contract_files.claude}`);
+  if (args.createArchitectureModule) actions.push(`create-architecture-module:${capability.architecture_module}`);
+  if (args.createWorkstream) actions.push(`create-workstream:${capability.workstream_dir}`);
+  actions.push("validate:capability-registry");
+
+  if (!args.dryRun) {
+    if (status === "added") writeRegistry(repo, registry);
+    if (args.syncContracts) syncContracts(repo, capability);
+    if (args.createArchitectureModule) createArchitectureModule(repo, capability);
+    if (args.createWorkstream) createWorkstream(repo, capability);
+    validateRegistry(repo);
+  }
+
+  if (args.format === "json") {
+    console.log(JSON.stringify({ repo, status, capability, actions, dry_run: args.dryRun }, null, 2));
+    return;
+  }
+
+  console.log(`[CapabilityConfig] ${status === "added" ? "Added" : "Found existing"} ${capability.id} -> ${capability.prefixes[0]}`);
+  for (const action of actions) console.log(`[CapabilityConfig] ${args.dryRun ? "Would " : ""}${action}`);
+}
+
+try {
+  main();
+} catch (error) {
+  console.error(`capability-config: ${(error as Error).message}`);
+  process.exit(1);
+}