forgedock 1.0.8 → 1.0.10

package/bin/init-enrich-api.mjs

@@ -0,0 +1,211 @@
+/**
+ * init-enrich-api.mjs — Anthropic API enrichment backend for ForgeDock init.
+ *
+ * Implements the same enrich(ConfigDraft) contract as the skill backend so the
+ * selection ladder in forgedock.mjs can treat both backends interchangeably.
+ *
+ * Uses Node.js built-in fetch (Node 18+) — no SDK dependency required.
+ * Reads ANTHROPIC_API_KEY from the environment; cleanly skips enrichment with
+ * a helpful message when the key is absent, returning the original draft.
+ */
+
+import { dim, yellow, RESET } from "./tui.mjs";
+
+/** Anthropic API endpoint for Messages. */
+const ANTHROPIC_MESSAGES_URL = "https://api.anthropic.com/v1/messages";
+
+/** Model used for config enrichment — cost-effective, fast, fits the task. */
+const ENRICH_MODEL = "claude-haiku-4-5";
+
+/**
+ * System prompt defining the enrich(ConfigDraft) contract for the API backend.
+ *
+ * IMPORTANT: This prompt is for a stateless Anthropic Messages API call.
+ * The model has NO filesystem access, NO gh CLI, NO shell, and NO external
+ * tool calls of any kind. Enrichment is limited strictly to what can be
+ * reasoned from the ConfigDraft JSON provided in the user message.
+ */
+const SYSTEM_PROMPT =
+  "You are the init-enrich API backend for ForgeDock. " +
+  "You receive a ConfigDraft JSON object and return an enriched version. " +
+  "\n\n" +
+  "EXECUTION ENVIRONMENT CONSTRAINTS:\n" +
+  "- You have NO filesystem access and cannot scan codebases.\n" +
+  "- You have NO gh CLI and cannot query GitHub.\n" +
+  "- You have NO external tool calls of any kind.\n" +
+  "- You may ONLY reason from the ConfigDraft JSON provided.\n" +
+  "\n" +
+  "ENRICHMENT SCOPE (what you MAY improve):\n" +
+  "- review.tech_stack: infer from project.description and paths if recognizable patterns appear.\n" +
+  "- review.context: improve wording or add standard context based on the project description.\n" +
+  "- verification.health_patterns: suggest standard patterns for known frameworks.\n" +
+  "\n" +
+  "STRICTLY PROHIBITED — set confidence to 'low' and do NOT invent values for:\n" +
+  "- project_board.project_id (must match ^PVT_[A-Za-z0-9_=-]+$ — you cannot verify these).\n" +
+  "- project_board.field_ids.* (PVTSSF_ strings — you cannot verify these).\n" +
+  "- project_board.project_number (you cannot query the GitHub Projects API).\n" +
+  "- repos.satellites (you cannot list or verify satellite repositories).\n" +
+  "Never invent a PVT_ or PVTSSF_ string. If you cannot verify a field, set confidence to 'low'.\n" +
+  "\n" +
+  "OUTPUT RULES:\n" +
+  "- Return ONLY the enriched ConfigDraft as a valid JSON object.\n" +
+  "- Every leaf must have shape { value, confidence, source, why }.\n" +
+  "- Do not modify project, paths, branches, or meta sections.\n" +
+  "- Output the JSON object alone with no surrounding prose.";
+
+/**
+ * Extract and parse the enriched ConfigDraft JSON from a backend response string.
+ *
+ * Backends may emit human-readable prose before and/or after the JSON blob.
+ * This function finds the outermost JSON object in the output using a
+ * string-aware balanced-brace scanner: it tracks brace depth while skipping
+ * over string literal contents (including backslash-escaped characters), so
+ * braces inside JSON string values do not affect depth tracking and trailing
+ * prose with braces does not extend the match past the correct closing '}'.
+ * Falls back to the original draft if extraction or parsing fails.
+ *
+ * @param {string} output  - Raw text from the API response content block
+ * @param {object} draft   - Original ConfigDraft (returned on failure)
+ * @returns {object} Enriched ConfigDraft, or original draft on failure
+ */
+export function parseEnrichedDraft(output, draft) {
+  if (!output || typeof output !== "string") return draft;
+
+  // Find the first '{' then walk forward tracking brace depth, skipping over
+  // string literal contents (with backslash-escape handling) so that:
+  //   - Braces inside JSON string values (e.g. Go template syntax in
+  //     project.description, Windows paths) do not affect depth.
+  //   - Trailing prose containing '{' or '}' after the JSON blob does not
+  //     extend the extraction past the correct top-level closing '}'.
+  const start = output.indexOf("{");
+  if (start === -1) return draft;
+
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+
+  for (let i = start; i < output.length; i++) {
+    const ch = output[i];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (ch === "\\" && inString) {
+      escape = true;
+      continue;
+    }
+    if (ch === '"') {
+      inString = !inString;
+      continue;
+    }
+    if (inString) continue;
+    if (ch === "{") {
+      depth++;
+    } else if (ch === "}") {
+      depth--;
+      if (depth === 0) {
+        // Found the closing brace of the top-level object — parse the candidate.
+        try {
+          const enriched = JSON.parse(output.slice(start, i + 1));
+          // Basic sanity check: must have the required top-level sections and
+          // each section must be a plain non-null object. The typeof+null guard
+          // rejects null and primitives; Array.isArray() additionally rejects
+          // arrays since typeof [] === 'object' would otherwise pass them.
+          if (
+            typeof enriched.project !== "object" || enriched.project === null || Array.isArray(enriched.project) ||
+            typeof enriched.paths !== "object" || enriched.paths === null || Array.isArray(enriched.paths) ||
+            typeof enriched.branches !== "object" || enriched.branches === null || Array.isArray(enriched.branches) ||
+            typeof enriched.meta !== "object" || enriched.meta === null || Array.isArray(enriched.meta)
+          ) {
+            return draft;
+          }
+          return enriched;
+        } catch {
+          return draft;
+        }
+      }
+    }
+  }
+
+  // No complete top-level JSON object found.
+  return draft;
+}
+
+/**
+ * Enrich a ConfigDraft by calling the Anthropic Messages API directly.
+ *
+ * This is the api backend for the init-enrich interface. It implements the same
+ * enrich(ConfigDraft) contract as the skill backend so the selection ladder can
+ * treat both interchangeably.
+ *
+ * When ANTHROPIC_API_KEY is absent, logs a helpful message and returns the
+ * original draft unchanged so the caller can fall through to the deterministic
+ * baseline.
+ *
+ * @param {object} draft - ConfigDraft from detectConfig()
+ * @returns {Promise<object>} Enriched ConfigDraft, or the original draft on failure
+ */
+export async function enrich(draft) {
+  const apiKey = process.env.ANTHROPIC_API_KEY;
+
+  if (!apiKey) {
+    console.error(
+      `  ${yellow("[!]")} No ANTHROPIC_API_KEY set — skipping API enrichment.` +
+        ` ${dim("Set ANTHROPIC_API_KEY to enable BYO-key enrichment.")}${RESET}`,
+    );
+    return draft;
+  }
+
+  try {
+    const draftJson = JSON.stringify(draft, null, 2);
+
+    const response = await fetch(ANTHROPIC_MESSAGES_URL, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "x-api-key": apiKey,
+        "anthropic-version": "2023-06-01",
+      },
+      body: JSON.stringify({
+        model: ENRICH_MODEL,
+        max_tokens: 4096,
+        system: SYSTEM_PROMPT,
+        messages: [
+          {
+            role: "user",
+            content: draftJson,
+          },
+        ],
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Anthropic API returned ${response.status}`);
+    }
+
+    const data = await response.json();
+    if (data?.stop_reason === "max_tokens" && process.env.FORGEDOCK_DEBUG) {
+      console.error(
+        `  ${dim("[debug]")} api enrichment: response truncated by max_tokens — JSON parse may fail, falling back to baseline draft.`,
+      );
+    }
+    const text =
+      data?.content?.[0]?.type === "text" ? data.content[0].text : "";
+    return parseEnrichedDraft(text, draft);
+  } catch (err) {
+    const errCategory = err.status
+      ? `HTTP ${err.status}`
+      : err.code
+        ? err.code
+        : err.message;
+    console.error(
+      `  ${yellow("[!]")} API enrichment unavailable: ${errCategory} — falling back to baseline draft.${RESET}`,
+    );
+    if (process.env.FORGEDOCK_DEBUG) {
+      console.error(
+        `  ${dim("[debug]")} api enrichment failed: ${err.message}`,
+      );
+    }
+    return draft;
+  }
+}

package/bin/registry.mjs

@@ -0,0 +1,358 @@
+#!/usr/bin/env node
+/**
+ * registry.mjs — Per-directory ForgeDock state registry.
+ *
+ * Resolves, for any directory, whether ForgeDock is *managed* there
+ * (a forge.yaml or .forgedock marker is present) and whether the user has
+ * explicitly *opted out* via the central registry file.
+ *
+ * Exports:
+ *   resolveState(dir)          → 'managed-active' | 'managed-optedout' | 'unmanaged'
+ *   setOptOut(dir, optedOut)   → Promise<void>  (adds/removes dir from opt-out set)
+ *   nudgeSeen(dir)             → boolean  (true if nudge was already shown for dir)
+ *   markNudgeSeen(dir)         → Promise<void>  (records that nudge was shown for dir)
+ *
+ * Registry file: ~/.claude/forgedock/registry.json
+ * Registry schema:
+ *   {
+ *     "version": 1,
+ *     "optedOut": {
+ *       "/absolute/path/to/dir": { "at": "<ISO-8601 timestamp>" }
+ *     },
+ *     "nudgeSeen": {
+ *       "/absolute/path/to/dir": { "at": "<ISO-8601 timestamp>" }
+ *     }
+ *   }
+ *
+ * State model:
+ *   - A directory is **managed** iff it contains `forge.yaml` OR a `.forgedock` marker file.
+ *   - A directory is **opted-out** iff its resolved absolute path appears in the
+ *     `optedOut` map of the registry.
+ *   - Opt-out wins over managed: a managed+opted-out directory is silenced.
+ *   - Missing or corrupt registry.json is treated as an empty opt-out set — the
+ *     registry always fails open (never blocks a Claude Code session).
+ *   - A nudge is shown at most once per unmanaged directory; `nudgeSeen` tracks
+ *     which directories have already received the nudge.
+ *
+ * Contract guarantees:
+ *   - Safe: every try/catch degrades gracefully; resolveState never throws
+ *   - Isolated: imports only Node builtins (os, path, fs)
+ *   - Atomic writes: registry.json is written via a .tmp file + renameSync
+ *   - Testable: inject `dir` argument to point at fixture directories
+ */
+
+import os from "os";
+import { resolve, join } from "path";
+import {
+  existsSync,
+  readFileSync,
+  writeFileSync,
+  renameSync,
+  realpathSync,
+} from "fs";
+import { mkdir } from "fs/promises";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+/**
+ * Cross-platform user home directory.
+ * Mirrors the HOME resolution pattern used in forgedock.mjs.
+ */
+const HOME = process.env.HOME || process.env.USERPROFILE || os.homedir();
+
+/**
+ * Directory that holds ForgeDock's per-user runtime state files.
+ * Created on first registry write if absent (mode 0o700).
+ */
+const REGISTRY_DIR = join(HOME, ".claude", "forgedock");
+
+/**
+ * Absolute path to the registry JSON file.
+ */
+const REGISTRY_PATH = join(REGISTRY_DIR, "registry.json");
+
+/**
+ * Empty registry structure — returned whenever the file is missing or corrupt.
+ * Using a factory function avoids shared mutable state across calls.
+ *
+ * @returns {{ version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }> }}
+ */
+function emptyRegistry() {
+  return { version: 1, optedOut: {}, nudgeSeen: {} };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve and normalize a directory path for use as a registry key.
+ *
+ * First resolves the path to an absolute path with `resolve()`, then
+ * dereferences any symbolic links with `realpathSync.native()` so that a
+ * project entered via a symlinked path and the same project entered via its
+ * real path produce the same registry key. A try/catch fallback to the
+ * `resolve()` result ensures fail-open behaviour for non-existent or
+ * inaccessible paths (ENOENT, EACCES, EPERM).
+ *
+ * On Windows only, the drive letter of the resulting canonical path is
+ * lowercased (the character before the first `:`). This ensures that
+ * `C:\Users\foo` and `c:\Users\foo` hash to the same key, since NTFS is
+ * case-insensitive but JavaScript string comparison is not.
+ *
+ * On POSIX systems the canonical path is returned as-is; POSIX filesystems
+ * are case-sensitive by convention and no normalization is needed.
+ *
+ * Only the drive letter is lowercased — the rest of the path is preserved
+ * verbatim so that intentional casing in directory names is not altered.
+ *
+ * @param {string} dir - Directory path (absolute or relative).
+ * @returns {string} Normalized canonical absolute path suitable for use as a registry key.
+ */
+function normalizeDir(dir) {
+  const abs = resolve(dir);
+  // Dereference symbolic links so that a symlinked project path and its
+  // real path produce the same registry key. Fall back to the resolve()
+  // result for paths that do not exist yet (e.g. ENOENT) or are not
+  // accessible (EACCES/EPERM) — preserves the fail-open contract.
+  // realpathSync.native uses the OS-native implementation (available since
+  // Node 9.2) and avoids extra JS stat syscalls vs the JS fallback.
+  let canonical;
+  try {
+    canonical = realpathSync.native(abs);
+  } catch {
+    canonical = abs;
+  }
+  // On Windows, drive letters vary in casing (C:\ vs c:\). Normalize to
+  // lowercase so registry lookups are case-insensitive for drive letters.
+  // Detect: canonical[1] === ':' is the Windows drive-letter pattern (e.g. C:\).
+  if (
+    process.platform === "win32" &&
+    canonical.length >= 2 &&
+    canonical[1] === ":"
+  ) {
+    return canonical[0].toLowerCase() + canonical.slice(1);
+  }
+  return canonical;
+}
+
+/**
+ * Read and parse the registry file.
+ *
+ * Fail-open: any read or parse error returns an empty registry rather than
+ * throwing. This ensures that a corrupt or missing file never blocks a
+ * Claude Code session.
+ *
+ * @returns {{ version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }> }}
+ */
+function readRegistry() {
+  try {
+    const raw = readFileSync(REGISTRY_PATH, "utf-8");
+    const parsed = JSON.parse(raw);
+    // Basic schema validation — must be an object with an optedOut map
+    if (
+      parsed &&
+      typeof parsed === "object" &&
+      parsed.optedOut &&
+      typeof parsed.optedOut === "object"
+    ) {
+      // Ensure nudgeSeen is present (may be absent in older registry files)
+      if (!parsed.nudgeSeen || typeof parsed.nudgeSeen !== "object") {
+        parsed.nudgeSeen = {};
+      }
+      return parsed;
+    }
+    // Schema mismatch — treat as empty (fail open)
+    return emptyRegistry();
+  } catch {
+    // File missing, unreadable, or invalid JSON — all treated as empty
+    return emptyRegistry();
+  }
+}
+
+/**
+ * Module-level write queue — serializes concurrent registry mutations so that
+ * two callers (e.g. setOptOut + markNudgeSeen in the same tick) never race and
+ * produce a last-write-wins corruption. Each enqueued mutation waits for the
+ * previous one to resolve before executing. Errors are swallowed per the
+ * existing best-effort contract so a failed write never blocks the next caller.
+ *
+ * The queue serializes the FULL read-modify-write cycle, not just the disk
+ * write. Each task reads the freshest on-disk state inside the critical section,
+ * applies the caller-supplied mutation, then writes atomically. This prevents
+ * the snapshot-before-enqueue race where two concurrent callers both read stale
+ * state and the second enqueued write silently stomps the first one's change.
+ * <!-- fix: forge#438 -->
+ */
+let _writeQueue = Promise.resolve();
+
+/**
+ * Enqueue a read-modify-write mutation against the registry.
+ *
+ * Accepts a `mutate` function rather than a pre-read data snapshot. The
+ * mutation is deferred until it reaches the head of the serial queue, at
+ * which point it reads the freshest on-disk registry state, applies the
+ * mutation, and writes the result atomically. This guarantees that concurrent
+ * callers each see the previous caller's changes rather than racing on a
+ * shared stale snapshot.
+ *
+ * Best-effort: errors inside the mutation or the disk write are silently
+ * suppressed so callers are never blocked.
+ *
+ * @param {(registry: { version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }> }) => void} mutate
+ *   Mutation callback. Called with the current registry object; should
+ *   modify it in place. Return value is ignored. Callbacks may have side
+ *   effects (e.g. reading the clock) — they are not required to be pure.
+ * @returns {Promise<void>}
+ */
+async function writeRegistry(mutate) {
+  // Chain onto the existing queue; swallow errors so callers are never blocked
+  _writeQueue = _writeQueue
+    .then(() => _doWriteRegistryWith(mutate))
+    .catch(() => {});
+  return _writeQueue;
+}
+
+/**
+ * Inner implementation — performs the atomic read-modify-write cycle.
+ * Called exclusively through writeRegistry's queue chain.
+ *
+ * Reads the current registry from disk (fail-open), applies the caller's
+ * mutation function, then writes the result via a .tmp file + renameSync.
+ *
+ * @param {(registry: { version: number, optedOut: Record<string, { at: string }>, nudgeSeen: Record<string, { at: string }> }) => void} mutate
+ *   Mutation callback — same contract as `writeRegistry`. Modifies the
+ *   registry object in place; return value is ignored.
+ * @returns {Promise<void>}
+ */
+async function _doWriteRegistryWith(mutate) {
+  try {
+    await mkdir(REGISTRY_DIR, { recursive: true, mode: 0o700 });
+    // Read the freshest on-disk state inside the critical section so that
+    // concurrent callers each build on the previous caller's committed write.
+    const registry = readRegistry();
+    mutate(registry);
+    const tmp = REGISTRY_PATH + ".tmp";
+    writeFileSync(tmp, JSON.stringify(registry, null, 2) + "\n", {
+      encoding: "utf-8",
+    });
+    renameSync(tmp, REGISTRY_PATH);
+  } catch {
+    // Best-effort — a failed write is non-fatal; the registry remains as-is
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the ForgeDock state for a given directory.
+ *
+ * State matrix:
+ *
+ * | forge.yaml | .forgedock | in optedOut | Result             |
+ * |:----------:|:----------:|:-----------:|:-------------------|
+ * |    true    |    any     |    false    | managed-active     |
+ * |    true    |    any     |    true     | managed-optedout   |
+ * |   false    |    true    |    false    | managed-active     |
+ * |   false    |    true    |    true     | managed-optedout   |
+ * |   false    |   false    |    any      | unmanaged          |
+ *
+ * Opt-out wins over managed: a directory that has a marker but is also listed
+ * in the registry's optedOut map is reported as managed-optedout.
+ *
+ * Missing or corrupt registry.json is treated as an empty opt-out set —
+ * resolveState never throws.
+ *
+ * @param {string} dir - Absolute path to the directory to resolve.
+ * @returns {'managed-active' | 'managed-optedout' | 'unmanaged'}
+ */
+export function resolveState(dir) {
+  const absDir = normalizeDir(dir);
+
+  // Check for managed markers (forge.yaml or .forgedock)
+  const hasForgeYaml = existsSync(join(absDir, "forge.yaml"));
+  const hasMarker = existsSync(join(absDir, ".forgedock"));
+  const isManaged = hasForgeYaml || hasMarker;
+
+  if (!isManaged) {
+    return "unmanaged";
+  }
+
+  // Directory is managed — check if opted out
+  const registry = readRegistry();
+  const isOptedOut = Object.prototype.hasOwnProperty.call(
+    registry.optedOut,
+    absDir,
+  );
+
+  return isOptedOut ? "managed-optedout" : "managed-active";
+}
+
+/**
+ * Add or remove a directory from the opt-out set in the registry.
+ *
+ * The directory path is normalized with normalizeDir() before being stored,
+ * ensuring consistent key lookup regardless of trailing slashes, symlinks, or
+ * drive-letter casing on Windows.
+ *
+ * @param {string} dir        - Absolute path to the directory.
+ * @param {boolean} optedOut  - true to opt out, false to remove from opt-out set.
+ * @returns {Promise<void>}
+ */
+export async function setOptOut(dir, optedOut) {
+  const absDir = normalizeDir(dir);
+  // Pass a mutation closure rather than a pre-read snapshot. The actual
+  // readRegistry() call is deferred to inside the serial queue so that
+  // concurrent mutations each see the previous caller's committed write.
+  await writeRegistry((registry) => {
+    if (optedOut) {
+      registry.optedOut[absDir] = { at: new Date().toISOString() };
+    } else {
+      delete registry.optedOut[absDir];
+    }
+  });
+}
+
+/**
+ * Check whether the one-time "Enable ForgeDock here?" nudge has already been
+ * shown for a given directory.
+ *
+ * Fail-open: returns false on any registry read error, so the nudge fires
+ * once more on the next session rather than never.
+ *
+ * @param {string} dir - Absolute path to the directory.
+ * @returns {boolean} true if the nudge has already been shown for this directory.
+ */
+export function nudgeSeen(dir) {
+  try {
+    const absDir = normalizeDir(dir);
+    const registry = readRegistry();
+    return Object.prototype.hasOwnProperty.call(registry.nudgeSeen, absDir);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Record that the one-time nudge has been shown for a directory so it is not
+ * shown again in future sessions.
+ *
+ * Best-effort: a failed write means the nudge may appear one extra time, which
+ * is acceptable — it never blocks a Claude Code session.
+ *
+ * @param {string} dir - Absolute path to the directory.
+ * @returns {Promise<void>}
+ */
+export async function markNudgeSeen(dir) {
+  const absDir = normalizeDir(dir);
+  // Pass a mutation closure rather than a pre-read snapshot. The actual
+  // readRegistry() call is deferred to inside the serial queue so that
+  // concurrent mutations each see the previous caller's committed write.
+  await writeRegistry((registry) => {
+    registry.nudgeSeen[absDir] = { at: new Date().toISOString() };
+  });
+}