forgedock 1.0.8 → 1.0.9

package/bin/hooks/session-start.mjs

@@ -0,0 +1,317 @@
+#!/usr/bin/env node
+/**
+ * session-start.mjs — ForgeDock SessionStart hook.
+ *
+ * Installed into ~/.claude/settings.json by `forgedock install`.
+ * Removed by `forgedock uninstall`.
+ *
+ * Called by Claude Code at the start of every session. Resolves the
+ * per-directory ForgeDock state and acts accordingly:
+ *
+ *   managed-active   → print ForgeDock context to stdout (forge.yaml summary
+ *                       + available commands). If forge.yaml is missing or
+ *                       stale, offer a one-shot autopilot init suggestion.
+ *   managed-optedout → completely silent (no output, no context injection).
+ *   unmanaged        → print a one-time, suppressible "Enable ForgeDock here?"
+ *                       nudge. Subsequent sessions for the same directory are
+ *                       silent after the nudge is recorded.
+ *
+ * Fail-open contract: any uncaught error is swallowed and the hook exits 0
+ * so that a broken hook never prevents a Claude Code session from starting.
+ *
+ * Environment:
+ *   Claude Code sets the working directory before invoking the hook, so
+ *   process.cwd() reliably returns the session's project directory.
+ *   FORGE_HOME is resolved at install time and baked into the command path,
+ *   so this file's __dirname is always the hooks/ directory inside the
+ *   ForgeDock installation.
+ */
+
+import { fileURLToPath, pathToFileURL } from "url";
+import { dirname, join, resolve } from "path";
+import { existsSync, readFileSync } from "fs";
+
+// ---------------------------------------------------------------------------
+// Bootstrap — resolve paths from the hook's own location, not from cwd
+// ---------------------------------------------------------------------------
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/** Absolute path to the ForgeDock installation root (parent of bin/). */
+const FORGE_HOME = resolve(__dirname, "..", "..");
+
+// ---------------------------------------------------------------------------
+// Registry helpers — populated inside the try block to honour fail-open
+// ---------------------------------------------------------------------------
+
+// Declared at module scope so they are accessible from handler functions
+// (handleUnmanaged) called from within the try block. Assigned inside the
+// try/catch so that any import failure (missing file, permissions error,
+// syntax error) is caught and the hook still exits 0. <!-- fix: forge#383 -->
+let resolveState;
+let nudgeSeen;
+let markNudgeSeen;
+
+// ---------------------------------------------------------------------------
+// forge-utils helpers — populated inside the try block to honour fail-open
+// ---------------------------------------------------------------------------
+
+// Declared at module scope so they are accessible from context-builder
+// functions called from within the try block. Assigned inside the try/catch
+// so that any import failure (missing file, permissions error, syntax error)
+// is caught and the hook still exits 0. <!-- fix: forge#489 -->
+let parseForgeYaml;
+let sanitizeContextValue;
+
+// ---------------------------------------------------------------------------
+// Main — wrapped in try/catch to guarantee fail-open
+// ---------------------------------------------------------------------------
+
+try {
+  // Import registry helpers from the same installation.
+  // Placed inside try/catch to honour the fail-open contract: if registry.mjs
+  // cannot be loaded (broken install, missing file, permissions error) the
+  // catch block below ensures we still exit 0 without blocking Claude Code.
+  //
+  // Use pathToFileURL() to convert the OS-native path to a file:// URL before
+  // passing it to dynamic import(). On Windows, join() produces backslash paths
+  // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
+  /** @type {import('../registry.mjs')} */
+  (
+    { resolveState, nudgeSeen, markNudgeSeen } = await import(
+      pathToFileURL(join(FORGE_HOME, "bin", "registry.mjs")).href
+    )
+  );
+
+  // Import forge-utils helpers from the same installation.
+  // Placed inside try/catch to honour the fail-open contract: if forge-utils.mjs
+  // cannot be loaded (broken install, missing file, permissions error) the
+  // catch block below ensures we still exit 0 without blocking Claude Code.
+  //
+  // Use pathToFileURL() to convert the OS-native path to a file:// URL before
+  // passing it to dynamic import(). On Windows, join() produces backslash paths
+  // that import() rejects with ERR_UNSUPPORTED_ESM_URL_SCHEME.
+  /** @type {import('../forge-utils.mjs')} */
+  (
+    { parseForgeYaml, sanitizeContextValue } = await import(
+      pathToFileURL(join(FORGE_HOME, "bin", "forge-utils.mjs")).href
+    )
+  );
+
+  const cwd = process.cwd();
+  const state = resolveState(cwd);
+
+  switch (state) {
+    case "managed-active":
+      await handleManagedActive(cwd);
+      break;
+
+    case "managed-optedout":
+      // Completely silent — no output, no context injection
+      break;
+
+    case "unmanaged":
+      await handleUnmanaged(cwd);
+      break;
+
+    default:
+      // Unknown state — fail open (silent)
+      break;
+  }
+} catch {
+  // Fail open — never block a Claude Code session
+  process.exit(0);
+}
+
+// Always exit 0 regardless of what happened above
+process.exit(0);
+
+// ---------------------------------------------------------------------------
+// Handlers
+// ---------------------------------------------------------------------------
+
+/**
+ * Emit ForgeDock context for a managed-active directory.
+ *
+ * Prints a concise forge.yaml summary plus the list of available pipeline
+ * commands. If forge.yaml is absent, prints a suggestion to run init instead.
+ *
+ * @param {string} dir - Absolute path to the project directory.
+ */
+async function handleManagedActive(dir) {
+  const forgeYamlPath = join(dir, "forge.yaml");
+
+  if (!existsSync(forgeYamlPath)) {
+    // Directory is managed (has .forgedock marker) but has no forge.yaml yet
+    console.log(buildMissingConfigContext(dir));
+    return;
+  }
+
+  let forgeYaml;
+  try {
+    forgeYaml = readForgeYaml(forgeYamlPath);
+  } catch {
+    // Unreadable or corrupt forge.yaml — suggest init
+    console.log(buildMissingConfigContext(dir));
+    return;
+  }
+
+  console.log(buildActiveContext(dir, forgeYaml));
+}
+
+/**
+ * Show a one-time suppressible nudge for unmanaged directories.
+ *
+ * Uses the registry to ensure the nudge fires at most once per directory.
+ * After showing, records the directory so subsequent sessions are silent.
+ *
+ * @param {string} dir - Absolute path to the project directory.
+ */
+async function handleUnmanaged(dir) {
+  if (nudgeSeen(dir)) {
+    // Nudge already shown — stay silent
+    return;
+  }
+
+  // Show the nudge, then record it so it won't show again
+  console.log(buildNudgeContext(dir));
+
+  // Best-effort — if this fails the nudge may show once more next session
+  await markNudgeSeen(dir).catch(() => {});
+}
+
+// ---------------------------------------------------------------------------
+// Context builders
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the context string injected for a managed-active directory with a
+ * valid forge.yaml.
+ *
+ * @param {string} dir       - Absolute path to the project directory.
+ * @param {object} forgeYaml - Parsed forge.yaml object.
+ * @returns {string}
+ */
+function buildActiveContext(dir, forgeYaml) {
+  // Sanitize the directory path before interpolating it into the context output.
+  // process.cwd() is user-controlled on Linux (directory names may contain <, >,
+  // or sequences that form <!-- -->), so it must be treated like any other
+  // untrusted value. <!-- fix: forge#450 -->
+  const safeDir = sanitizeContextValue(dir, 500) ?? "[project directory]";
+  const project = forgeYaml.project ?? {};
+  const projectName = sanitizeContextValue(project.name ?? null, 200);
+  const owner = sanitizeContextValue(project.owner ?? null, 200);
+  const repoName = sanitizeContextValue(project.repo ?? null, 200);
+  const repo = owner && repoName ? `${owner}/${repoName}` : (repoName ?? null);
+  const description = sanitizeContextValue(project.description ?? null, 400);
+
+  const rawMilestone = sanitizeContextValue(forgeYaml.milestone ?? null, 200);
+  const milestoneNote = rawMilestone
+    ? `\n- **Active milestone**: ${rawMilestone}`
+    : "";
+
+  const nameNote = projectName ? `\n- **Project**: ${projectName}` : "";
+  const repoNote = repo ? `\n- **Repo**: ${repo}` : "";
+  const descNote = description ? `\n- **Description**: ${description}` : "";
+
+  const stagingBranch = sanitizeContextValue(
+    forgeYaml.branches?.staging ?? "staging",
+    200,
+  );
+  const featurePattern = sanitizeContextValue(
+    forgeYaml.branches?.feature_pattern ?? "milestone/{slug}",
+    200,
+  );
+
+  return `\
+<!-- ForgeDock: managed-active -->
+**ForgeDock** is active in this directory (${safeDir}).
+${nameNote}${repoNote}${descNote}${milestoneNote}
+- **Staging branch**: \`${stagingBranch}\`
+- **Feature branch pattern**: \`${featurePattern}\`
+
+### Available pipeline commands
+
+| Command | Purpose |
+|---------|---------|
+| /work-on | Pick up a GitHub issue and run the full pipeline |
+| /orchestrate | Parallel work on multiple issues or a milestone |
+| /review-pr | Context-aware PR review |
+| /quality-gate | Pre-commit quality check |
+| /issue | Create a well-structured GitHub issue |
+| /milestone | Create, manage, and ship milestones |
+| /deploy-info | Show what will deploy next |
+| /analytics | Pull production analytics and create issues |
+| /autopilot | Autonomous platform improvement cycle |
+
+Run \`/help\` to see the full command list.
+To disable ForgeDock in this directory: \`npx forgedock disable\``;
+}
+
+/**
+ * Build the context string shown when a managed directory is missing or has
+ * a corrupt forge.yaml.
+ *
+ * @param {string} dir - Absolute path to the project directory.
+ * @returns {string}
+ */
+function buildMissingConfigContext(dir) {
+  // Sanitize dir before display — see forge#450.
+  const safeDir = sanitizeContextValue(dir, 500) ?? "[project directory]";
+  return `\
+<!-- ForgeDock: managed-active (no forge.yaml) -->
+**ForgeDock** is active in this directory (${safeDir}) but no \`forge.yaml\` was found.
+
+Run autopilot init to generate your configuration automatically:
+  \`npx forgedock init\`
+
+ForgeDock's AI will infer your project structure, GitHub repo, and pipeline settings
+from the codebase — then present a single annotated review screen for you to confirm.`;
+}
+
+/**
+ * Build the one-time nudge shown for unmanaged directories.
+ *
+ * @param {string} dir - Absolute path to the project directory.
+ * @returns {string}
+ */
+function buildNudgeContext(dir) {
+  // Sanitize dir before display — see forge#450.
+  const safeDir = sanitizeContextValue(dir, 500) ?? "[project directory]";
+  return `\
+<!-- ForgeDock: unmanaged nudge -->
+**ForgeDock** is installed but not active in this directory (${safeDir}).
+
+To enable the autonomous development pipeline here:
+  \`npx forgedock enable\`   — mark this directory and stay silent until you run init
+  \`npx forgedock init\`     — immediately generate forge.yaml with AI autopilot
+
+This message will not appear again in this directory.
+To suppress it globally, run: \`npx forgedock disable\``;
+}
+
+// ---------------------------------------------------------------------------
+// forge.yaml reader
+// ---------------------------------------------------------------------------
+
+/**
+ * Read and parse forge.yaml from the given path.
+ *
+ * Uses a minimal YAML parser (key: "value" lines only — sufficient for the
+ * fields we need from forge.yaml). Does NOT pull in a full YAML library so
+ * the hook stays fast and dependency-free.
+ *
+ * The real forge.yaml schema has nested sections; this returns a two-level
+ * object covering the top-level keys that session-start needs.
+ *
+ * @param {string} path - Absolute path to forge.yaml.
+ * @returns {object} Parsed forge.yaml as a plain object.
+ * @throws {Error} If the file cannot be read.
+ */
+function readForgeYaml(path) {
+  const raw = readFileSync(path, "utf-8");
+  return parseForgeYaml(raw);
+}
+
+// parseForgeYaml and sanitizeContextValue are dynamically imported from
+// ../forge-utils.mjs inside the try block to honour the fail-open contract.

package/bin/init-detect.mjs

@@ -0,0 +1,325 @@
+#!/usr/bin/env node
+/**
+ * init-detect.mjs — Pure deterministic config detection for ForgeDock.
+ *
+ * Exports a single function: detectConfig(cwd)
+ *
+ * Returns a ConfigDraft: a structured object mirroring forge.yaml's required
+ * sections (project, paths, branches) where every leaf is:
+ *   { value, confidence, source, why }
+ *
+ * Confidence levels:
+ *   "high"   — verified from a concrete, unambiguous source
+ *   "medium" — inferred from available signals; likely correct
+ *   "low"    — guessed default; no supporting evidence found
+ *
+ * Contract guarantees:
+ *   - Pure: no prompts, no writes; reads only git metadata and the filesystem
+ *   - Safe: every try/catch degrades to "low" confidence defaults, never throws
+ *   - Isolated: imports only Node builtins (child_process, path)
+ *   - Testable: inject `cwd` to point at a fixture repo and assert the draft
+ */
+
+import { execFileSync } from "child_process";
+import { join } from "path";
+
+// ---------------------------------------------------------------------------
+// Field factory helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a high-confidence field.
+ * @param {string} value
+ * @param {string} source
+ * @param {string} why
+ * @returns {{ value: string, confidence: 'high', source: string, why: string }}
+ */
+function high(value, source, why) {
+  return { value, confidence: "high", source, why };
+}
+
+/**
+ * Create a medium-confidence field.
+ * @param {string} value
+ * @param {string} source
+ * @param {string} why
+ * @returns {{ value: string, confidence: 'medium', source: string, why: string }}
+ */
+function medium(value, source, why) {
+  return { value, confidence: "medium", source, why };
+}
+
+/**
+ * Create a low-confidence field (default / guessed).
+ * @param {string} value
+ * @param {string} source
+ * @param {string} why
+ * @returns {{ value: string, confidence: 'low', source: string, why: string }}
+ */
+function low(value, source, why) {
+  return { value, confidence: "low", source, why };
+}
+
+// ---------------------------------------------------------------------------
+// Detection helpers — each returns a field object; never throws
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect GitHub owner and repo from the git remote named "origin".
+ *
+ * Supports both SSH (git@github.com:owner/repo.git) and HTTPS
+ * (https://github.com/owner/repo.git) remote URL formats.
+ *
+ * Uses execFileSync (no shell) so remote URL content cannot be used for
+ * command injection.
+ *
+ * @param {string} cwd - Absolute path to the repo root to inspect.
+ * @returns {{ owner: import('./init-detect.mjs').ConfigField, repo: import('./init-detect.mjs').ConfigField, remoteDetected: boolean }}
+ */
+function detectRemote(cwd) {
+  try {
+    const remoteUrl = execFileSync(
+      "git",
+      ["remote", "get-url", "origin"],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      },
+    ).trim();
+
+    // SSH: git@github.com:owner/repo.git
+    const sshMatch = remoteUrl.match(/^git@[^:]+:([^/]+)\/(.+?)(?:\.git)?$/);
+    // HTTPS: https://github.com/owner/repo.git
+    const httpsMatch = remoteUrl.match(
+      /^https?:\/\/[^/]+\/([^/]+)\/(.+?)(?:\.git)?$/,
+    );
+
+    if (sshMatch) {
+      const [, owner, repo] = sshMatch;
+      const sourceLabel = "git remote origin (SSH)";
+      const why = `Parsed from SSH remote URL: ${remoteUrl}`;
+      return {
+        owner: high(owner, sourceLabel, why),
+        repo: high(repo, sourceLabel, why),
+        remoteDetected: true,
+      };
+    }
+
+    if (httpsMatch) {
+      const [, owner, repo] = httpsMatch;
+      const sourceLabel = "git remote origin (HTTPS)";
+      const why = `Parsed from HTTPS remote URL: ${remoteUrl}`;
+      return {
+        owner: high(owner, sourceLabel, why),
+        repo: high(repo, sourceLabel, why),
+        remoteDetected: true,
+      };
+    }
+
+    // URL not in a recognised format — treat as no remote
+  } catch {
+    // git not available, not a repo, or no remote named "origin"
+  }
+
+  return {
+    owner: low("your-github-org", "default placeholder", "No git remote named 'origin' found"),
+    repo: low("your-repo-name", "default placeholder", "No git remote named 'origin' found"),
+    remoteDetected: false,
+  };
+}
+
+/**
+ * Detect the default branch for the repository.
+ *
+ * Strategy (first success wins):
+ *   1. git symbolic-ref refs/remotes/origin/HEAD  → the authoritative remote default
+ *   2. git rev-parse --abbrev-ref HEAD             → the current local branch
+ *   3. Fall back to "main" at low confidence
+ *
+ * @param {string} cwd
+ * @returns {{ value: string, confidence: 'high'|'medium'|'low', source: string, why: string }}
+ */
+function detectDefaultBranch(cwd) {
+  // Strategy 1: symbolic ref (authoritative)
+  try {
+    const headRef = execFileSync(
+      "git",
+      ["symbolic-ref", "refs/remotes/origin/HEAD"],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      },
+    ).trim();
+    const branch = headRef.replace(/^refs\/remotes\/origin\//, "");
+    if (branch) {
+      return high(
+        branch,
+        "git symbolic-ref refs/remotes/origin/HEAD",
+        `Remote HEAD points to ${branch}`,
+      );
+    }
+  } catch {
+    // symbolic-ref not set — try next strategy
+  }
+
+  // Strategy 2: current local branch
+  try {
+    const cur = execFileSync(
+      "git",
+      ["rev-parse", "--abbrev-ref", "HEAD"],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      },
+    ).trim();
+    if (cur && cur !== "HEAD") {
+      return medium(
+        cur,
+        "git rev-parse --abbrev-ref HEAD",
+        `Current local branch is ${cur}; used as default branch estimate`,
+      );
+    }
+  } catch {
+    // git not available or detached HEAD
+  }
+
+  // Strategy 3: fall back
+  return low("main", "default placeholder", "Could not determine branch from git; defaulting to 'main'");
+}
+
+/**
+ * Detect the staging branch.
+ *
+ * Strategy: check whether a remote branch named "staging" exists in the
+ * remote listing. Falls back to the default branch at medium confidence
+ * when staging is absent (many projects use main as their staging target).
+ *
+ * @param {string} cwd
+ * @param {string} defaultBranch - The already-detected default branch value.
+ * @returns {{ value: string, confidence: 'high'|'medium'|'low', source: string, why: string }}
+ */
+function detectStagingBranch(cwd, defaultBranch) {
+  try {
+    const remoteBranches = execFileSync(
+      "git",
+      ["branch", "-r"],
+      {
+        cwd,
+        encoding: "utf-8",
+        stdio: ["pipe", "pipe", "pipe"],
+        timeout: 5000,
+      },
+    );
+    const branchLines = remoteBranches.split("\n").map((l) => l.trim());
+    if (branchLines.some((l) => l === "origin/staging")) {
+      return high(
+        "staging",
+        "git branch -r",
+        "Found 'origin/staging' in the remote branch listing",
+      );
+    }
+  } catch {
+    // git not available or no remotes
+  }
+
+  return medium(
+    defaultBranch,
+    "derived from default branch",
+    `No 'origin/staging' remote branch found; staging defaults to the default branch '${defaultBranch}'`,
+  );
+}
+
+/**
+ * Derive a human-readable project name from the repository slug.
+ *
+ * Splits on hyphens and underscores, title-cases each word.
+ * E.g. "my-cool-repo" → "My Cool Repo"
+ *
+ * @param {string} repoSlug
+ * @returns {{ value: string, confidence: 'medium', source: string, why: string }}
+ */
+function deriveProjectName(repoSlug) {
+  const name = repoSlug
+    .split(/[-_]/)
+    .filter(Boolean)
+    .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+    .join(" ");
+  return medium(
+    name || repoSlug,
+    "derived from repo slug",
+    `Title-cased version of repo name '${repoSlug}' (split on hyphens/underscores)`,
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * @typedef {{ value: string, confidence: 'high'|'medium'|'low', source: string, why: string }} ConfigField
+ *
+ * @typedef {{
+ *   project: {
+ *     owner: ConfigField,
+ *     repo:  ConfigField,
+ *     name:  ConfigField,
+ *   },
+ *   paths: {
+ *     root:         ConfigField,
+ *     worktreeBase: ConfigField,
+ *   },
+ *   branches: {
+ *     default: ConfigField,
+ *     staging: ConfigField,
+ *   },
+ *   meta: {
+ *     remoteDetected: boolean,
+ *   },
+ * }} ConfigDraft
+ */
+
+/**
+ * Run all deterministic detection steps for a repository rooted at `cwd`.
+ *
+ * Returns a ConfigDraft — never throws. Every field in the draft carries a
+ * confidence level so downstream consumers (init-enrich, review-render) can
+ * decide how to treat each value.
+ *
+ * @param {string} [cwd] - Absolute path to the repo root. Defaults to process.cwd().
+ * @returns {Promise<ConfigDraft>}
+ */
+export async function detectConfig(cwd = process.cwd()) {
+  // Project identity
+  const { owner, repo, remoteDetected } = detectRemote(cwd);
+
+  // Project name derived from the repo slug
+  const name = deriveProjectName(repo.value);
+
+  // Paths — always high confidence (derived from the cwd argument)
+  const root = high(cwd, "process.cwd()", "Absolute path passed to detectConfig — the project root");
+  const worktreeBase = high(
+    join(cwd, ".claude", "worktrees"),
+    "derived from root",
+    `Convention: {root}/.claude/worktrees (root = ${cwd})`,
+  );
+
+  // Branch detection
+  const defaultBranchField = detectDefaultBranch(cwd);
+  const stagingBranchField = detectStagingBranch(cwd, defaultBranchField.value);
+
+  return {
+    project: { owner, repo, name },
+    paths: { root, worktreeBase },
+    branches: {
+      default: defaultBranchField,
+      staging: stagingBranchField,
+    },
+    meta: { remoteDetected },
+  };
+}