forgedock 1.1.1 → 1.1.3

package/bin/journey.mjs

@@ -9,7 +9,7 @@
  *   init-detect.mjs, init-enrich-api.mjs, tui.annotatedReviewScreen, registry.mjs
  */
 
-import { existsSync, readFileSync, writeFileSync, renameSync } from "fs";
+import { existsSync, readFileSync, writeFileSync, renameSync, unlinkSync } from "fs";
 import { join, basename } from "path";
 
 // ---------------------------------------------------------------------------
@@ -114,7 +114,17 @@ branches:
 #   health_patterns:
 #     - '"status": "ok"'
 `;
-  writeFileSync(outputPath, content, "utf-8");
+  // Atomic write: write to a temp file first, then rename into place.
+  // If the write fails (e.g. ENOSPC), the original file is untouched and
+  // any partial .tmp is cleaned up — no corrupt or missing forge.yaml.
+  const tmpPath = outputPath + ".tmp";
+  try {
+    writeFileSync(tmpPath, content, "utf-8");
+    renameSync(tmpPath, outputPath);
+  } catch (err) {
+    try { unlinkSync(tmpPath); } catch { /* best-effort cleanup */ }
+    throw err;
+  }
   const todoCount = (content.match(/# TODO\(forgedock:/g) || []).length;
   return { todoCount };
 }
@@ -349,7 +359,12 @@ export async function preflight(ctx) {
 
 import { mkdir, symlink, readlink, lstat, readdir, rename, copyFile, readFile, writeFile, unlink } from "fs/promises";
 import { relative, dirname as pathDirname } from "path";
-import { installSessionStartHook } from "./settings-hook.mjs";
+import {
+  installSessionStartHook,
+  installSubagentStopHook,
+  installPreToolUseHook,
+  removeSubagentStopEnforceHook,
+} from "./settings-hook.mjs";
 
 /**
  * Parse the `install:` tier from a command spec's YAML frontmatter block.
@@ -361,7 +376,7 @@ import { installSessionStartHook } from "./settings-hook.mjs";
  *
  * Tier values:
  *   'core'     — install for all users (default when key is absent or on any error)
- *   'extras'   — opt-in, not yet installed by default (reserved for #1257)
+ *   'extras'   — opt-in, not installed by default; use `npx forgedock install --extras` (#1257)
  *   'internal' — ForgeDock development only; never installed to user machines
  *
  * Fail-open: any read error, malformed frontmatter, or unrecognised value falls
@@ -407,22 +422,27 @@ export function parseInstallTier(filePath) {
  * Files with `install: internal` in their YAML frontmatter are excluded — they
  * are ForgeDock-development-only specs that must never reach user machines.
  * Files with `install: core` (or no `install:` key) are included. Files with
- * `install: extras` are excluded from the default install surface (reserved for
- * the opt-in extras mechanism tracked in #1257).
+ * `install: extras` are excluded from the default install surface; they are
+ * available via `npx forgedock install --extras` (implemented in #1257).
+ *
+ * @param {string} dir - Directory to search recursively.
+ * @param {{ includeExtras?: boolean }} [opts] - Options.
+ *   includeExtras: when true, also include `install: extras` specs (opt-in tier).
  */
-export async function findMarkdownFiles(dir) {
+export async function findMarkdownFiles(dir, opts = {}) {
+  const { includeExtras = false } = opts;
   const results = [];
   const entries = await readdir(dir, { withFileTypes: true });
   for (const entry of entries) {
     const full = join(dir, entry.name);
     if (entry.isDirectory()) {
-      results.push(...(await findMarkdownFiles(full)));
+      results.push(...(await findMarkdownFiles(full, opts)));
     } else if (entry.name.endsWith(".md")) {
       const tier = parseInstallTier(full);
-      if (tier === "core") {
+      if (tier === "core" || (includeExtras && tier === "extras")) {
         results.push(full);
       }
-      // 'internal' and 'extras' are excluded from the default install surface
+      // 'internal' is always excluded from the install surface
     }
   }
   return results.sort();
@@ -473,7 +493,7 @@ export async function forge(ctx) {
   const manifest = await loadCopiedManifest(manifestPath);
   let manifestChanged = false;
 
-  const files = await findMarkdownFiles(commandsDir);
+  const files = await findMarkdownFiles(commandsDir, { includeExtras: !!ctx.includeExtras });
   let installed = 0, updated = 0, skipped = 0, copied = 0;
   const barWidth = 24;
   let barShown = false;
@@ -595,6 +615,23 @@ export async function forge(ctx) {
   const settingsPath = join(ctx.home, ".claude", "settings.json");
   const { status: hookStatus } = installSessionStartHook(settingsPath, hookScript);
 
+  // Install enforcement hooks (#1250): PreToolUse (branch/label validation)
+  // and SubagentStop interactive engine adapter. Both are idempotent and
+  // always installed (fail-open if settings.json is malformed, same
+  // contract as SessionStart hook).
+  const preToolUseScript = join(ctx.forgeHome, "bin", "hooks", "pre-tool-use.mjs");
+  const subagentStopScript = join(ctx.forgeHome, "bin", "hooks", "interactive-engine.mjs");
+  const { status: preToolUseStatus } = installPreToolUseHook(settingsPath, preToolUseScript);
+  installSubagentStopHook(settingsPath, subagentStopScript);
+
+  // SubagentStop annotation-verifier hook (#1250) is NOT installed: its
+  // trigger condition (a `FORGE:PHASE_START` marker in the transcript) is
+  // never emitted anywhere in the pipeline, so it always exits 0 with zero
+  // enforcement effect while still spawning a process + reading the
+  // transcript on every SubagentStop (forge#1527). Actively clean up any
+  // prior installation instead of installing it.
+  const { status: subagentStopEnforceStatus } = removeSubagentStopEnforceHook(settingsPath);
+
   // Housekeeping — must never abort the receipt or the hook.
   let manifestSaveFailed = false;
   if (manifestChanged) {
@@ -624,7 +661,23 @@ export async function forge(ctx) {
     w.write(`  ${glyph(true)} SessionStart hook ${hookStatus === "already" ? "active" : "registered"} ${dimLine(ctx, settingsPath)}\n`);
   }
 
-  return { installed, updated, skipped, copied, total: files.length, hookStatus };
+  // Report enforcement hook status.
+  if (preToolUseStatus !== null) {
+    w.write(`  ${glyph(true)} PreToolUse enforcement hook ${preToolUseStatus === "already" ? "active" : "registered"} ${dimLine(ctx, "(branch/label enforcement)")}\n`);
+  } else {
+    w.write("  " + dimLine(ctx, "PreToolUse hook skipped — requires Claude Code v2.1.163+") + "\n");
+  }
+  // "skipped-malformed" and "absent" are intentionally silent here:
+  // - skipped-malformed: installSessionStartHook() above reads the same
+  //   settingsPath and already prints the malformed-JSON fix-card, so a
+  //   second message would just repeat the same signal.
+  // - absent: the expected steady state (nothing to remove) — this
+  //   function only reports state *changes*, not no-ops.
+  if (subagentStopEnforceStatus === "removed") {
+    w.write(`  ${glyph(true)} SubagentStop enforcement hook removed ${dimLine(ctx, "(non-functional — see forge#1527)")}\n`);
+  }
+
+  return { installed, updated, skipped, copied, total: files.length, hookStatus, preToolUseStatus, subagentStopEnforceStatus };
 }
 
 // ---------------------------------------------------------------------------
@@ -744,11 +797,16 @@ export function celebrate(ctx, summary) {
     w.write(`  ${glyph} ${summary.total} commands · hook ${summary.hookStatus === "skipped-malformed" ? "skipped" : "active"}   ${dimLine(ctx, hookNote)}\n`);
   }
   w.write("\n");
+  if (summary.isMinimal) {
+    w.write("  " + dimLine(ctx, "see docs/CONFIG.md for optional sections") + "\n");
+  }
   w.write(
     box(
       [
-        `  1. open claude in this repo`,
-        `  2. run /work-on next — watch an issue become a merged PR`,
+        `  1. run npx forgedock labels setup — bootstrap GitHub labels`,
+        `  2. run npx forgedock doctor     — verify the install is green`,
+        `  3. open claude in this repo`,
+        `  4. run /issue <title> then /work-on <number>`,
       ],
       { title: "what's next" },
     ),

package/bin/registry.mjs

@@ -376,3 +376,142 @@ export async function clearNudgeSeen(dir) {
     delete registry.nudgeSeen[absDir];
   });
 }
+
+// ---------------------------------------------------------------------------
+// Claude Code version detection and breakpoints resolution (issue #1252)
+// ---------------------------------------------------------------------------
+
+// execFileSync is not imported at the top of this module (it only imports fs
+// builtins). Import it lazily here using createRequire — safe in Node ESM.
+import { createRequire } from "module";
+const _require = createRequire(import.meta.url);
+
+/**
+ * Detect the installed Claude Code version by running `claude --version`.
+ *
+ * Returns the version string (e.g. "2.1.197") or null if Claude Code is not
+ * installed or the version cannot be parsed. Never throws — callers can safely
+ * check for null and degrade gracefully.
+ *
+ * @returns {string | null} Semver-style version string or null.
+ */
+export function detectClaudeVersion() {
+  try {
+    const { execFileSync } = _require("child_process");
+    const raw = execFileSync("claude", ["--version"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"],
+      timeout: 5000,
+    }).trim();
+    // Claude Code outputs e.g. "Claude Code 2.1.197" or just "2.1.197"
+    const m = raw.match(/(\d+\.\d+\.\d+)/);
+    return m ? m[1] : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Compare two semver-style version strings (e.g. "2.1.152" vs "2.1.197").
+ *
+ * Returns:
+ *   -1 if a < b
+ *    0 if a === b
+ *    1 if a > b
+ *
+ * Non-numeric components are compared lexicographically. Handles missing
+ * components by treating them as 0.
+ *
+ * @param {string} a
+ * @param {string} b
+ * @returns {-1 | 0 | 1}
+ */
+export function compareVersions(a, b) {
+  const pa = String(a).split(".").map((s) => parseInt(s, 10) || 0);
+  const pb = String(b).split(".").map((s) => parseInt(s, 10) || 0);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const va = pa[i] ?? 0;
+    const vb = pb[i] ?? 0;
+    if (va < vb) return -1;
+    if (va > vb) return 1;
+  }
+  return 0;
+}
+
+/**
+ * Load and parse docs/claude-breakpoints.json relative to FORGE_HOME.
+ *
+ * Returns the parsed breakpoints array or an empty array on any error (file
+ * missing, malformed JSON, etc.). Consumers must pass the FORGE_HOME path.
+ *
+ * @param {string} forgeHome - Absolute path to the ForgeDock repo root.
+ * @returns {Array<object>} Array of breakpoint objects.
+ */
+export function loadBreakpoints(forgeHome) {
+  try {
+    const bpPath = join(forgeHome, "docs", "claude-breakpoints.json");
+    const raw = readFileSync(bpPath, "utf-8");
+    const parsed = JSON.parse(raw);
+    return Array.isArray(parsed.breakpoints) ? parsed.breakpoints : [];
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Resolve all breakpoints applicable to a given Claude Code version.
+ *
+ * A breakpoint is "applicable" if its version is > the supplied version,
+ * meaning the user is on an older version and will be affected by this
+ * breakpoint. This surfaces the set of features/changes the user is missing.
+ *
+ * If no version is supplied, all breakpoints are returned (useful for
+ * listing the full registry).
+ *
+ * Results are sorted by version ascending.
+ *
+ * @param {Array<object>} breakpoints - Array from loadBreakpoints().
+ * @param {string | null} installedVersion - The user's installed Claude Code version, or null.
+ * @returns {Array<object>} Breakpoints the user is missing or all breakpoints if no version.
+ */
+export function resolveBreakpoints(breakpoints, installedVersion) {
+  if (!installedVersion) return [...breakpoints].sort((a, b) => compareVersions(a.version, b.version));
+  return breakpoints
+    .filter((bp) => compareVersions(bp.version, installedVersion) > 0)
+    .sort((a, b) => compareVersions(a.version, b.version));
+}
+
+/**
+ * Resolve a single breakpoint by feature_key.
+ *
+ * Returns the breakpoint object with the matching `feature_key`, or null
+ * if not found. Useful for conditional logic: "does this install support
+ * effort_levels?" → `resolveBreakpoint(bps, 'effort_levels')`.
+ *
+ * @param {Array<object>} breakpoints - Array from loadBreakpoints().
+ * @param {string} featureKey - The `feature_key` value to look up.
+ * @returns {object | null} The matching breakpoint or null.
+ */
+export function resolveBreakpoint(breakpoints, featureKey) {
+  return breakpoints.find((bp) => bp.feature_key === featureKey) ?? null;
+}
+
+/**
+ * Check whether a detected Claude Code version meets or exceeds the version
+ * required for a given feature_key.
+ *
+ * Returns true if the feature is available, false if not, and null if the
+ * feature_key is unknown or the installed version is not detectable.
+ *
+ * @param {Array<object>} breakpoints - Array from loadBreakpoints().
+ * @param {string} featureKey - Feature to check.
+ * @param {string | null} installedVersion - Detected Claude Code version.
+ * @returns {boolean | null}
+ */
+export function hasFeature(breakpoints, featureKey, installedVersion) {
+  if (!installedVersion) return null;
+  const bp = resolveBreakpoint(breakpoints, featureKey);
+  if (!bp) return null;
+  return compareVersions(installedVersion, bp.version) >= 0;
+}