forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/doc-gate.js

@@ -0,0 +1,336 @@
+'use strict';
+
+/**
+ * `forge doc-gate` — repo-structure detector command (thin wrapper).
+ *
+ * Subcommand: `detect [--json]`. Runs the validated doc-gate detector
+ * (lib/doc-gate/detect.js) against the cwd repo and prints a human summary by
+ * default, or a structured JSON object with `--json`.
+ *
+ * Exit non-zero ONLY on a real error (not a git repo / no commits, or an
+ * unknown subcommand). An ESCALATE-TO-AGENT or MANUAL-CONFIG verdict is a valid
+ * detection result and exits 0.
+ *
+ * This is the first PR of the larger "doc-gate" feature; the CI required-gate,
+ * OKF-bundle generation, and agent escalation runtime are deliberately NOT here.
+ *
+ * @module commands/doc-gate
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { detect } = require('../doc-gate/detect');
+const { evaluateGate } = require('../doc-gate/gate');
+const { scaffoldDeclaration, DECLARATION_FILE } = require('../doc-gate/declaration');
+const { loadOkfConfig, setOkfEnabled, isOkfEnabled } = require('../doc-gate/okf-config');
+const { generateBundle, linkAgentsMd } = require('../doc-gate/okf');
+
+/** True when `root` is a git working tree with at least one commit (HEAD). */
+function hasGitHead(root) {
+  try {
+    // NOSONAR S4036 - 'git' is a hardcoded CLI command with no user input; developer-tool context.
+    execFileSync('git', ['-C', root, 'rev-parse', '--verify', 'HEAD'], { // NOSONAR S4036
+      stdio: ['ignore', 'ignore', 'ignore'],
+    });
+    return true;
+  } catch (_err) {
+    // A missing/broken git HEAD simply means "not a usable repo" here. NOSONAR S2486
+    return false;
+  }
+}
+
+/** Format a single field for the human summary. */
+function fieldLine(label, field, valueKey) {
+  let display;
+  if (field.escalate) {
+    display = `ESCALATE→agent (${field.trigger})`;
+  } else {
+    const raw = field[valueKey];
+    if (raw === null || raw === undefined || (Array.isArray(raw) && raw.length === 0)) {
+      display = '(none / abstain)';
+    } else {
+      display = Array.isArray(raw) ? raw.join(', ') : String(raw);
+    }
+  }
+  return `  ${label.padEnd(10)} ${display}  [${field.confidence}]`;
+}
+
+/** Render the detector result as a readable summary. */
+function renderHuman(result) {
+  const lines = [
+    `doc-gate detect — ${result.repo}`,
+    `verdict: ${result.verdict}`,
+    fieldLine('source', result.source, 'value'),
+    fieldLine('toolchain', result.toolchain, 'value'),
+    fieldLine('ci', result.ci, 'provider'),
+    fieldLine('changelog', result.changelog, 'value'),
+    fieldLine('agents', result.agents, 'value'),
+    `code-high-confidence: ${result.codeHighConfidence.length ? result.codeHighConfidence.join(', ') : '(none)'}`,
+  ];
+  if (Array.isArray(result.escalate) && result.escalate.length > 0) {
+    lines.push('escalate:');
+    for (const e of result.escalate) {
+      const detail = e.detail ? ` (${e.detail})` : '';
+      lines.push(`  - ${e.field}: ${e.trigger}${detail}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+const CHECK_USAGE = 'forge doc-gate check --base <ref> --head <ref> [--skip] [--json]';
+const INIT_USAGE = 'forge doc-gate init [--force] [--json]';
+const OKF_USAGE =
+  'forge doc-gate okf <status|enable|disable> [--json]\n' +
+  '       forge doc-gate okf generate [--source <dir>] [--out <dir>] [--json]\n' +
+  '       forge doc-gate okf link [--out <dir>] [--json]';
+const USAGE = `forge doc-gate detect [--json]\n       ${CHECK_USAGE}\n       ${INIT_USAGE}\n       ${OKF_USAGE}`;
+
+/** Standard "not a usable git repo" error result (exit 1). */
+function notAGitRepo(root, sub) {
+  return {
+    success: false,
+    error:
+      `forge doc-gate ${sub} must run inside a git repository with at least one ` +
+      `commit (HEAD). No readable git HEAD was found at ${root}.`,
+    exitCode: 1,
+  };
+}
+
+/** Read a `--name value` or `--name=value` flag from a raw argv array. */
+function readArgValue(argv, name) {
+  const prefix = `${name}=`;
+  const eq = argv.find(a => a.startsWith(prefix));
+  if (eq) return eq.slice(prefix.length);
+  const i = argv.indexOf(name);
+  if (i >= 0 && i + 1 < argv.length && !argv[i + 1].startsWith('-')) return argv[i + 1];
+  return null;
+}
+
+/** Render a gate result as a readable summary. */
+function renderGate(result) {
+  const surface = Array.isArray(result.sourceSurface) && result.sourceSurface.length > 0
+    ? result.sourceSurface.join(', ')
+    : '(unresolved)';
+  const lines = [
+    `doc-gate check — ${result.decision.toUpperCase()}`,
+    `verdict: ${result.verdict}`,
+    `source surface: ${surface}`,
+    `reason: ${result.reason}`,
+  ];
+  if (result.offendingCodeFiles.length > 0) {
+    lines.push('code changes without a doc update:');
+    for (const f of result.offendingCodeFiles) lines.push(`  - ${f}`);
+  }
+  if (result.docChangesSeen.length > 0) {
+    lines.push('doc changes seen:');
+    for (const f of result.docChangesSeen) lines.push(`  - ${f}`);
+  }
+  return lines.join('\n');
+}
+
+/** `detect` subcommand — repo-structure summary (exit 0 on any verdict). */
+function runDetect(argv, flags, root) {
+  if (!hasGitHead(root)) return notAGitRepo(root, 'detect');
+  const json = Boolean(flags?.json) || argv.includes('--json');
+  const result = detect(root);
+  const output = json ? JSON.stringify(result, null, 2) : renderHuman(result);
+  return { success: true, output, json };
+}
+
+/** `check` subcommand — enforce "a code change requires a doc update". */
+function runCheck(argv, flags, root) {
+  if (!hasGitHead(root)) return notAGitRepo(root, 'check');
+  const json = Boolean(flags?.json) || argv.includes('--json');
+  const skip = Boolean(flags?.skip) || argv.includes('--skip');
+  const base = flags?.base ?? readArgValue(argv, '--base');
+  const head = flags?.head ?? readArgValue(argv, '--head');
+  if (!skip && (!base || !head)) {
+    return {
+      success: false,
+      error: `forge doc-gate check requires --base <ref> and --head <ref>.\nUsage: ${CHECK_USAGE}`,
+      exitCode: 1,
+    };
+  }
+
+  const result = evaluateGate({ root, base, head, skip });
+  const output = json ? JSON.stringify(result, null, 2) : renderGate(result);
+  // Exit 1 ONLY on a hard fail; pass and abstain both exit 0.
+  if (result.decision === 'fail') {
+    return { success: false, error: `doc-gate: ${result.reason}`, output, exitCode: 1 };
+  }
+  return { success: true, output, json };
+}
+
+/** Render an init result as a readable summary. */
+function renderInit(payload) {
+  const decl = payload.declaration;
+  const lines = [
+    `doc-gate init — wrote ${payload.path}${payload.overwritten ? ' (overwritten)' : ''}`,
+    `source: ${decl.source.join(', ')}`,
+    `toolchain: ${decl.toolchain ?? '(none)'}`,
+    `Edit ${payload.path} to declare your repo structure, then commit it (tracked-files-only).`,
+  ];
+  return lines.join('\n');
+}
+
+/** `init` subcommand — scaffold a `.docgate.json` from the current detect() result. */
+function runInit(argv, flags, root) {
+  if (!hasGitHead(root)) return notAGitRepo(root, 'init');
+  const json = Boolean(flags?.json) || argv.includes('--json');
+  const force = Boolean(flags?.force) || argv.includes('--force');
+  const target = path.join(root, DECLARATION_FILE);
+  // lstat (does NOT follow symlinks) detects both existence and a symlink target.
+  let stat = null;
+  try { stat = fs.lstatSync(target); } catch { /* absent: stat stays null */ }
+  // Refuse to write THROUGH a symlink — a checked-in symlink could clobber a file
+  // outside the repo. This holds even with --force.
+  if (stat?.isSymbolicLink()) {
+    return {
+      success: false,
+      error: `${DECLARATION_FILE} at ${root} is a symlink; refusing to write through it.`,
+      exitCode: 1,
+    };
+  }
+  const exists = stat !== null;
+  if (exists && !force) {
+    return {
+      success: false,
+      error: `${DECLARATION_FILE} already exists at ${root}. Re-run with --force to overwrite.\nUsage: ${INIT_USAGE}`,
+      exitCode: 1,
+    };
+  }
+
+  const declaration = scaffoldDeclaration(detect(root));
+  try {
+    fs.writeFileSync(target, `${JSON.stringify(declaration, null, 2)}\n`);
+  } catch (err) {
+    // A write failure (permissions / read-only tree) is a real error — surface it.
+    return { success: false, error: `could not write ${DECLARATION_FILE}: ${err.message}`, exitCode: 1 };
+  }
+
+  const payload = { path: DECLARATION_FILE, overwritten: exists, declaration };
+  const output = json ? JSON.stringify(payload, null, 2) : renderInit(payload);
+  return { success: true, output, json };
+}
+
+/** True when JSON output was requested (parsed flag OR raw `--json`). */
+function wantsJson(argv, flags) {
+  return Boolean(flags?.json) || argv.includes('--json');
+}
+
+const OKF_DISABLED_HINT = 'OKF is disabled. Run `forge doc-gate okf enable` to turn it on.';
+
+/** `okf status` — report whether OKF generation is enabled. */
+function okfStatus(argv, flags, root) {
+  const payload = { enabled: loadOkfConfig(root).okf.enabled };
+  const json = wantsJson(argv, flags);
+  const output = json ? JSON.stringify(payload, null, 2) : `doc-gate okf: ${payload.enabled ? 'ENABLED' : 'disabled'}`;
+  return { success: true, output, json };
+}
+
+/** `okf enable|disable` — flip the toggle in `.forge/doc-gate.json`. */
+function okfSetEnabled(argv, flags, root, enabled) {
+  let cfg;
+  try {
+    cfg = setOkfEnabled(root, enabled);
+  } catch (err) {
+    return { success: false, error: `could not update OKF toggle: ${err.message}`, exitCode: 1 };
+  }
+  const payload = { enabled: cfg.okf.enabled };
+  const json = wantsJson(argv, flags);
+  const output = json ? JSON.stringify(payload, null, 2) : `doc-gate okf ${enabled ? 'enabled' : 'disabled'}.`;
+  return { success: true, output, json };
+}
+
+/** Render a bundle-generation result as a readable summary. */
+function renderOkfGenerate(result) {
+  return [
+    `doc-gate okf generate — wrote ${result.count} concept${result.count === 1 ? '' : 's'} to ${result.out}/`,
+    `source: ${result.source}`,
+    `okf_version: ${result.okfVersion}`,
+    `root index: ${result.out}/index.md`,
+  ].join('\n');
+}
+
+/** `okf generate` — build the OKF bundle (refuses unless enabled). */
+function okfGenerate(argv, flags, root) {
+  if (!hasGitHead(root)) return notAGitRepo(root, 'okf generate');
+  if (!isOkfEnabled(root)) return { success: false, error: OKF_DISABLED_HINT, exitCode: 1 };
+  const source = flags?.source ?? readArgValue(argv, '--source');
+  const out = flags?.out ?? readArgValue(argv, '--out');
+  let result;
+  try {
+    result = generateBundle({ root, source: source ?? undefined, out: out ?? undefined });
+  } catch (err) {
+    return { success: false, error: `okf generate failed: ${err.message}`, exitCode: 1 };
+  }
+  if (!result.ok) return { success: false, error: result.error, exitCode: 1 };
+  const json = wantsJson(argv, flags);
+  const output = json ? JSON.stringify(result, null, 2) : renderOkfGenerate(result);
+  return { success: true, output, json };
+}
+
+/** `okf link` — write the thin AGENTS.md nav overlay (refuses unless enabled). */
+function okfLink(argv, flags, root) {
+  if (!isOkfEnabled(root)) return { success: false, error: OKF_DISABLED_HINT, exitCode: 1 };
+  const out = flags?.out ?? readArgValue(argv, '--out');
+  let result;
+  try {
+    result = linkAgentsMd({ root, out: out ?? undefined });
+  } catch (err) {
+    return { success: false, error: `okf link failed: ${err.message}`, exitCode: 1 };
+  }
+  const json = wantsJson(argv, flags);
+  const output = json
+    ? JSON.stringify(result, null, 2)
+    : `doc-gate okf link — ${result.created ? 'created' : 'updated'} ${result.path} nav → ${result.target}`;
+  return { success: true, output, json };
+}
+
+/** `okf` subcommand router. */
+function runOkf(argv, flags, root) {
+  const nonFlags = argv.filter(a => a && !a.startsWith('-'));
+  const action = nonFlags[1] ?? 'status';
+  if (action === 'status') return okfStatus(argv, flags, root);
+  if (action === 'enable') return okfSetEnabled(argv, flags, root, true);
+  if (action === 'disable') return okfSetEnabled(argv, flags, root, false);
+  if (action === 'generate') return okfGenerate(argv, flags, root);
+  if (action === 'link') return okfLink(argv, flags, root);
+  return {
+    success: false,
+    error: `Unknown doc-gate okf action '${action}'. Supported: status, enable, disable, generate, link.\nUsage: ${OKF_USAGE}`,
+    exitCode: 1,
+  };
+}
+
+module.exports = {
+  name: 'doc-gate',
+  description: 'Detect a repository\'s structure, or enforce the doc-update gate on a PR',
+  usage: USAGE,
+  flags: {
+    '--json': 'Emit a structured JSON object instead of the human summary.',
+    '--base': 'check: base ref/SHA of the pull request.',
+    '--head': 'check: head ref/SHA of the pull request.',
+    '--skip': 'check: force a pass (e.g. a no-docs-needed label).',
+    '--force': 'init: overwrite an existing .docgate.json.',
+    '--source': 'okf generate: source docs dir (default: auto — docs/ or tracked markdown).',
+    '--out': 'okf generate/link: bundle output dir (default: .okf).',
+  },
+
+  async handler(args, flags, projectRoot, _opts = {}) {
+    const argv = Array.isArray(args) ? args : [];
+    const sub = argv.find(a => a && !a.startsWith('-')) || 'detect';
+    const root = projectRoot || process.cwd();
+
+    if (sub === 'detect') return runDetect(argv, flags, root);
+    if (sub === 'check') return runCheck(argv, flags, root);
+    if (sub === 'init') return runInit(argv, flags, root);
+    if (sub === 'okf') return runOkf(argv, flags, root);
+    return {
+      success: false,
+      error: `Unknown doc-gate subcommand '${sub}'. Supported subcommands: detect, check, init, okf.\nUsage: ${USAGE}`,
+      exitCode: 1,
+    };
+  },
+};

package/lib/commands/doctor.js

@@ -0,0 +1,156 @@
+'use strict';
+
+// D19 — `forge doctor`: reports the filesystem class of the kernel DB path.
+//
+// Auto-discovered + routed by lib/commands/_registry.js (no bin/forge.js edit).
+// JSON-first, mirrors orient/recap. It is a REPORTER, not the enforcer — the
+// default-on gate lives in broker.initialize(). doctor resolves the exact path
+// the gate guards (via buildLocalBrokerConfig, which does no I/O) and reports
+// whether that path is safe, WITHOUT creating any file.
+
+const { buildLocalBrokerConfig } = require('../kernel/broker');
+const { classifyFilesystem, isUnsafeFsOverrideActive, REMEDIATION } = require('../kernel/fs-class');
+const memoryRouter = require('../memory/router');
+
+const SCHEMA_VERSION = 1;
+
+/**
+ * Best-effort, NON-FATAL memory-backend check. Reports the resolved backend and,
+ * when `graphiti` is selected, whether the opt-in config is coherent and the
+ * configured MCP server path exists locally. It never gates the overall report
+ * (that stays governed by the filesystem-class check) — a memory misconfig warns
+ * but does not make `forge doctor` fail.
+ *
+ * @param {string} projectRoot
+ * @param {object} env
+ * @returns {{ id: string, ok: boolean, backend: string, detail: string }}
+ */
+function buildMemoryCheck(projectRoot, env) {
+	const fs = require('node:fs');
+	try {
+		const { backend, graphiti } = memoryRouter.assertMemoryConfigValid({ projectRoot, env });
+		if (backend !== 'graphiti') {
+			return {
+				id: 'memory-backend',
+				ok: true,
+				backend,
+				detail: `memory backend: ${backend} (local kernel store, FTS5-indexed, offline)`,
+			};
+		}
+		const serverPath = graphiti.mcpServerPath;
+		const serverPathExists = fs.existsSync(serverPath);
+		const reach = serverPathExists
+			? `mcp_server present at ${serverPath}`
+			: `mcp_server path not found locally (${serverPath}); run it before agents can use graph memory`;
+		return {
+			// Reflect reality in the line symbol: a graphiti backend whose MCP server
+			// isn't present yet renders as `!` (warn), not a misleading `✓`. This does
+			// NOT affect the overall doctor exit — report.ok is governed solely by the
+			// filesystem-class check (see buildDoctorReport), so an uninstalled opt-in
+			// memory server warns without failing `forge doctor`.
+			id: 'memory-backend',
+			ok: serverPathExists,
+			backend,
+			serverPathExists,
+			detail: `memory backend: graphiti — served to agents via the graphiti-memory MCP server; ${reach}`,
+		};
+	} catch (err) {
+		const backend = memoryRouter.resolveMemoryBackend({ projectRoot, env, warn: () => {} });
+		return { id: 'memory-backend', ok: false, backend, detail: err.message };
+	}
+}
+
+/**
+ * Build the doctor report. Pure-ish: all I/O-bearing deps are injectable.
+ * @param {string} projectRoot
+ * @param {object} deps - { classifyFilesystem?, env?, gitCommonDir?, execFileSync? }
+ */
+function buildDoctorReport(projectRoot, deps = {}) {
+	const env = deps.env || process.env;
+	const classify = deps.classifyFilesystem || classifyFilesystem;
+
+	// Config build does NO I/O (F1): it never opens/creates the DB.
+	const config = buildLocalBrokerConfig({
+		projectRoot,
+		gitCommonDir: deps.gitCommonDir,
+		execFileSync: deps.execFileSync,
+	});
+	const databasePath = config.databasePath;
+
+	const classification = classify(databasePath, deps);
+	const overrideActive = isUnsafeFsOverrideActive(env);
+	const isRefuse = classification.riskTier === 'refuse';
+	const checkOk = !isRefuse || overrideActive;
+	const remediation = isRefuse
+		? (REMEDIATION[classification.remediationKey] || REMEDIATION.unknown)
+		: null;
+
+	const check = {
+		id: 'filesystem-class',
+		ok: checkOk,
+		databasePath,
+		class: classification.class,
+		riskTier: classification.riskTier,
+		signal: classification.signal,
+		remediation,
+		overrideActive,
+	};
+
+	const memoryCheck = buildMemoryCheck(projectRoot, env);
+
+	return {
+		command: 'doctor',
+		schemaVersion: SCHEMA_VERSION,
+		// Overall ok is governed by the filesystem-class check (the enforcer). The
+		// memory-backend check is a NON-FATAL reporter and never fails doctor.
+		ok: check.ok,
+		checks: [check, memoryCheck],
+	};
+}
+
+function formatCheckLine(check) {
+	if (check.id === 'memory-backend') {
+		return `${check.ok ? '✓' : '!'} ${check.detail}`;
+	}
+	if (check.riskTier === 'safe') {
+		return `✓ filesystem: ${check.class} (safe) — ${check.databasePath}`;
+	}
+	if (check.riskTier === 'warn') {
+		return `! filesystem: ${check.class} (warn) — ${check.databasePath}`;
+	}
+	// refuse
+	const tag = check.overrideActive ? 'REFUSE, override active' : 'REFUSE';
+	return `✗ filesystem: ${check.class} (${tag}) — ${check.databasePath}`;
+}
+
+function formatReportText(report) {
+	const lines = report.checks.map(formatCheckLine);
+	for (const check of report.checks) {
+		if (check.remediation) {
+			lines.push('', check.remediation);
+		}
+	}
+	lines.push('', report.ok ? 'doctor: OK' : 'doctor: FAILED');
+	return `${lines.join('\n')}\n`;
+}
+
+async function handler(args, _flags, projectRoot, deps = {}) {
+	const report = buildDoctorReport(projectRoot, deps);
+	const output = (args || []).includes('--json')
+		? `${JSON.stringify(report, null, 2)}\n`
+		: formatReportText(report);
+
+	const result = { success: report.ok, output };
+	if (!report.ok) {
+		result.error = `forge doctor found a refuse-class filesystem for the kernel database (${report.checks[0].class}).`;
+	}
+	return result;
+}
+
+module.exports = {
+	name: 'doctor',
+	description: 'Report the filesystem class of the kernel database path (cloud/network/local)',
+	usage: 'Usage: forge doctor [--json]',
+	handler,
+	buildDoctorReport,
+};

package/lib/commands/explain.js

@@ -0,0 +1,15 @@
+'use strict';
+
+const optionsCommand = require('./options');
+
+module.exports = {
+  name: 'explain',
+  description: 'Explain a runtime graph primitive',
+  usage: 'forge explain <id> [--json]',
+  flags: {
+    '--json': 'Emit machine-readable JSON output',
+  },
+  async handler(args, flags, projectRoot) {
+    return optionsCommand.handler(['why', ...args], flags, projectRoot);
+  },
+};