forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/export.js

@@ -0,0 +1,237 @@
+'use strict';
+
+const path = require('node:path');
+const {
+	runJsonlProjectionConsumer,
+	readProjection,
+	resolveProjectionDir,
+	writeProjection,
+	DEFAULT_PROJECTION_TARGET,
+} = require('../kernel/projection-jsonl-writer');
+
+// Full set the consumer may call — including the retry (recordProjectionFailure)
+// and dead-letter (deadLetterProjection) paths — so a partially-implemented
+// broker is skipped cleanly instead of failing mid-run.
+const PROJECTION_BROKER_METHODS = [
+	'listProjectionOutbox',
+	'loadProjectionModel',
+	'markProjectionDelivered',
+	'recordProjectionFailure',
+	'deadLetterProjection',
+];
+
+/**
+ * Parse `forge export` options from positional args (and a parsed flags object
+ * as a fallback). Supported: --import, --dry-run, --json, --dir=<path> / --dir <path>.
+ */
+function parseExportOptions(args = [], flags = {}) {
+	const options = {
+		import: Boolean(flags.import),
+		dryRun: Boolean(flags['dry-run'] || flags.dryRun),
+		json: Boolean(flags.json),
+		dir: flags.dir,
+	};
+
+	for (let i = 0; i < args.length; i += 1) {
+		const arg = args[i];
+		if (arg === '--import') options.import = true;
+		else if (arg === '--dry-run') options.dryRun = true;
+		else if (arg === '--json') options.json = true;
+		else if (arg.startsWith('--dir=')) options.dir = arg.slice('--dir='.length);
+		else if (arg === '--dir') {
+			// only consume the next token when it is a real value, not another flag
+			const next = args[i + 1];
+			if (next && !next.startsWith('--')) {
+				options.dir = next;
+				i += 1;
+			}
+		}
+	}
+
+	return options;
+}
+
+function brokerSupportsProjection(broker) {
+	return Boolean(broker) && PROJECTION_BROKER_METHODS.every(method => typeof broker[method] === 'function');
+}
+
+function resolveDirArg(dirArg, projectRoot) {
+	if (!dirArg) return undefined;
+	return path.resolve(projectRoot || process.cwd(), dirArg);
+}
+
+function renderHuman(payload) {
+	if (payload.error) return `forge export failed: ${payload.error}`;
+	if (payload.imported === true) {
+		const { issues, comments, dependencies } = payload.counts;
+		const skipped = issues.skipped + comments.skipped + dependencies.skipped;
+		// Report "Imported N" ONLY for records actually written; a re-import that
+		// applies nothing (everything already present) must not claim it imported them.
+		if (payload.applied === 0) {
+			return `Kernel projection at ${payload.dir} is already hydrated — nothing new imported`
+				+ ` (${skipped} record${skipped === 1 ? '' : 's'} already present)`;
+		}
+		return `Imported Kernel projection from ${payload.dir}`
+			+ ` (${issues.inserted} issues, ${comments.inserted} comments, ${dependencies.inserted} dependencies`
+			+ (skipped ? `; ${skipped} already present` : '') + ')';
+	}
+	if (payload.imported === false) return payload.message;
+	if (payload.dryRun) return `${payload.pending} pending projection entr${payload.pending === 1 ? 'y' : 'ies'} → ${payload.dir} (dry run, nothing written)`;
+	if (payload.skipped) return payload.message;
+	if (payload.exported) return `Exported Kernel projection to ${payload.dir} (drained ${payload.drained})`;
+	return payload.message || 'Nothing to export';
+}
+
+function finalize(options, payload) {
+	const output = options.json ? JSON.stringify(payload, null, 2) : renderHuman(payload);
+	return { ...payload, output, json: Boolean(options.json) };
+}
+
+/**
+ * Forge Export Command (D16 — Kernel JSONL portability projection).
+ *
+ * Explicit, Kernel-owned projection of issues/comments/dependencies to
+ * deterministic git-tracked JSONL under `.forge/kernel/`. This is NOT auto-run on
+ * mutation/push (D16 forbids that); it is an on-demand portability/bootstrap
+ * surface. The `--import` path reads a committed snapshot back from disk (no
+ * broker required) and verifies its manifest integrity.
+ *
+ * @module commands/export
+ */
+module.exports = {
+	name: 'export',
+	description: 'Export the Kernel backlog to deterministic git-tracked JSONL (D16 portability projection)',
+	usage: 'forge export [--dir <path>] [--dry-run] [--json] [--import]',
+	flags: {},
+
+	/**
+	 * @param {string[]} args - Positional arguments / flags
+	 * @param {object} flags - Parsed CLI flags (fallback source)
+	 * @param {string} projectRoot - Project root path
+	 * @param {object} [opts] - Dependency injection: _broker, _writer, _now, _fs
+	 */
+	async handler(args = [], flags = {}, projectRoot, opts = {}) {
+		const options = parseExportOptions(args, flags || {});
+		const now = opts._now || new Date().toISOString();
+		const writer = opts._writer || writeProjection;
+		const fsImpl = opts._fs;
+		const projectionDir = resolveDirArg(options.dir, projectRoot);
+
+		// --- Import / hydrate (read committed JSONL → write kernel.sqlite) ---
+		// readProjection verifies snapshot integrity (sha256, per-file kind, manifest
+		// counts, and schema_version compatibility) and throws on any mismatch, so an
+		// incompatible/tampered snapshot never reaches the kernel writer.
+		if (options.import) {
+			try {
+				const snapshot = readProjection({ projectionDir, projectRoot, fsImpl });
+				if (!snapshot) {
+					return finalize(options, {
+						success: true,
+						imported: false,
+						dir: resolveProjectionDir(projectionDir, projectRoot),
+						message: 'No projection snapshot found to import',
+					});
+				}
+
+				const read = {
+					issues: snapshot.model.issues.length,
+					comments: snapshot.model.comments.length,
+					dependencies: snapshot.model.dependencies.length,
+				};
+
+				// Hydration requires a projection-capable Kernel broker (importIssues).
+				// The CLI injects one for `export` (a Kernel-tool command); without it we
+				// validated the snapshot but cannot write — say so instead of claiming an
+				// import happened.
+				const importBroker = opts._broker || null;
+				if (!importBroker || typeof importBroker.importIssues !== 'function') {
+					return finalize(options, {
+						success: true,
+						imported: false,
+						dir: snapshot.dir,
+						read,
+						message: `Read ${read.issues} issues from ${snapshot.dir} but no Kernel broker is `
+							+ 'available to import into — nothing was written',
+					});
+				}
+
+				// importIssues requires the schema/migrations to exist; the CLI broker is
+				// pre-initialized, but initialize() is idempotent so calling it is safe.
+				if (typeof importBroker.initialize === 'function') {
+					await importBroker.initialize();
+				}
+
+				// Idempotent + transactional upsert-by-id (ON CONFLICT DO NOTHING).
+				const summary = await importBroker.importIssues(snapshot.model, { now });
+				const applied = summary.issues.inserted + summary.comments.inserted + summary.dependencies.inserted;
+
+				return finalize(options, {
+					success: true,
+					imported: true,
+					dir: snapshot.dir,
+					counts: summary,
+					applied,
+				});
+			} catch (error) {
+				return finalize(options, { success: false, imported: false, error: error.message });
+			}
+		}
+
+		// --- Export (requires a projection-capable Kernel broker) ------------
+		const broker = opts._broker || null;
+		if (!brokerSupportsProjection(broker)) {
+			return finalize(options, {
+				success: true,
+				exported: false,
+				skipped: true,
+				message: 'No Kernel broker available — nothing to export',
+			});
+		}
+
+		if (options.dryRun) {
+			const pending = (await broker.listProjectionOutbox({
+				target: DEFAULT_PROJECTION_TARGET,
+				status: 'pending',
+				now,
+			})) || [];
+			return finalize(options, {
+				success: true,
+				exported: false,
+				dryRun: true,
+				pending: pending.length,
+				dir: resolveProjectionDir(projectionDir, projectRoot),
+			});
+		}
+
+		try {
+			const run = await runJsonlProjectionConsumer({ broker, projectionDir, projectRoot, now, writer });
+
+			// A write failure leaves entries retried/dead-lettered without a snapshot;
+			// surface it as a failure rather than silently reporting success.
+			if (!run.written && run.error) {
+				return finalize(options, {
+					success: false,
+					exported: false,
+					error: run.error,
+					drained: run.drained,
+					retried: run.retried,
+					dead: run.dead,
+					dir: resolveProjectionDir(projectionDir, projectRoot),
+				});
+			}
+
+			return finalize(options, {
+				success: true,
+				exported: run.written,
+				drained: run.drained,
+				delivered: run.delivered,
+				retried: run.retried,
+				dead: run.dead,
+				dir: run.write ? run.write.dir : resolveProjectionDir(projectionDir, projectRoot),
+				files: run.write ? run.write.files : [],
+			});
+		} catch (error) {
+			return finalize(options, { success: false, exported: false, error: error.message });
+		}
+	},
+};

package/lib/commands/gate.js

@@ -0,0 +1,209 @@
+'use strict';
+
+/**
+ * `forge gate <enable|disable|approve|reject|status|check> ...`
+ *
+ * Two families over the same known-gate set:
+ *
+ *  TOGGLE (config surface): `enable|disable <gate-id>` set
+ *  `workflow.gates.<gate-id>.enabled` true/false in `.forge/config.yaml`. The shipped
+ *  resolver (`applyEnabledConfig`) already consumes this field, so `forge options
+ *  gates --json` reflects the flip with zero new read code. Write-time validation:
+ *  an unknown gate id (or a locked gate being disabled) errors BEFORE anything is
+ *  written — never mid-run.
+ *
+ *  EVENTS (gates-as-kernel-events — Fable's insight): `approve|reject <issue> <gate>`
+ *  record a durable `gate.approved` / `gate.rejected` event on the issue; `status`
+ *  lists them (resume-safe after a compaction/crash); `check` exits 0 iff the gate is
+ *  DISABLED or an approval event exists — the reusable enforcement primitive a stage
+ *  skill calls. See lib/gate-events.js and docs/work/2026-07-04-kernel-native-skills/
+ *  decisions.md.
+ */
+
+const path = require('node:path');
+const { setConfigOverride } = require('../config-writer');
+const { getDefaultRuntimeGraph, getResolvedRuntimeGraph } = require('../core/runtime-graph');
+const {
+  recordGateEvent,
+  listGateEvents,
+  isGateApproved,
+} = require('../gate-events');
+
+// The doc-update gate folds under this noun as `gate doc` (P2, kernel issue
+// 6ab3f30c) — it is a gate concern, not a `pr` one. `doc` delegates to the
+// standalone doc-gate command (same code); bare `forge doc-gate` stays registered
+// as a back-compat alias. Required lazily so the module graph has no cycle and the
+// routed handler is resolved at dispatch time.
+const docGate = require('./doc-gate');
+
+const TOGGLE_ACTIONS = new Set(['enable', 'disable']);
+const EVENT_ACTIONS = new Set(['approve', 'reject', 'status', 'check']);
+
+function usage() {
+  return [
+    'Usage: forge gate <enable|disable|approve|reject|status|check> [<issue-id>] <gate-id> [--reason <text>] [--json]',
+    '       forge gate doc <detect|check|init|okf|...> [args]   (doc-update gate; = forge doc-gate, run `forge doc-gate --help`)',
+  ].join('\n');
+}
+
+// The known-toggle set is gates PLUS unlocked toggleable rails (e.g.
+// rail.kernel_tracking): both are governed through the same `forge gate
+// enable|disable` surface and the resolver's rail-aware workflow.gates loop.
+// The gate.* / rail.* id namespaces are disjoint, so one flat map is unambiguous.
+function knownGates() {
+  const graph = getDefaultRuntimeGraph();
+  return new Map([...graph.gates, ...graph.rails].map(primitive => [primitive.id, primitive]));
+}
+
+// Kernel deps + env are threaded through the command opts (4th handler arg) so tests
+// and the orchestrator can inject a shared, already-migrated kernel.
+function kernelDeps(opts = {}) {
+  return { kernelBroker: opts.kernelBroker, kernelDriver: opts.kernelDriver };
+}
+
+function validateKnownGate(gateId) {
+  const gates = knownGates();
+  const gate = gates.get(gateId);
+  if (!gate) {
+    return {
+      ok: false,
+      error: `Unknown gate '${gateId}'. Known gates: ${[...gates.keys()].join(', ')}`,
+    };
+  }
+  return { ok: true, gate };
+}
+
+function handleToggle(action, gateId, projectRoot) {
+  if (!gateId) {
+    return { success: false, error: `Missing gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+  if (action === 'disable' && known.gate.locked === true) {
+    return { success: false, error: `Cannot disable locked gate '${gateId}'.` };
+  }
+
+  const enabled = action === 'enable';
+  const { configPath } = setConfigOverride(
+    projectRoot,
+    ['workflow', 'gates', gateId, 'enabled'],
+    enabled,
+  );
+  const where = path.relative(projectRoot, configPath) || configPath;
+  return {
+    success: true,
+    output: `${action}d gate '${gateId}' (workflow.gates.${gateId}.enabled=${enabled}) in ${where}`,
+  };
+}
+
+async function handleDecision(action, issueId, gateId, flags, projectRoot, opts) {
+  if (!issueId || !gateId) {
+    return { success: false, error: `Missing issue id or gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+
+  const decision = action === 'approve' ? 'approved' : 'rejected';
+  const reason = typeof flags.reason === 'string' ? flags.reason : undefined;
+  const result = await recordGateEvent(projectRoot, {
+    issueId,
+    gateId,
+    decision,
+    reason,
+    env: opts.env,
+    deps: kernelDeps(opts),
+  });
+
+  if (result.issueMissing) {
+    return { success: false, error: `Issue '${issueId}' not found.` };
+  }
+
+  const verb = action === 'approve' ? 'approved' : 'rejected';
+  const suffix = result.duplicate ? ' (already recorded)' : '';
+  const reasonNote = reason ? ` — ${reason}` : '';
+  return {
+    success: true,
+    duplicate: result.duplicate === true,
+    actor: result.actor,
+    output: `${verb} gate '${gateId}' for ${issueId} (actor ${result.actor})${reasonNote}${suffix}`,
+  };
+}
+
+async function handleStatus(issueId, flags, projectRoot, opts) {
+  if (!issueId) {
+    return { success: false, error: `Missing issue id.\n${usage()}` };
+  }
+  const events = await listGateEvents(projectRoot, issueId, { deps: kernelDeps(opts) });
+
+  if (flags.json) {
+    return { success: true, output: JSON.stringify({ issue: issueId, events }, null, 2) };
+  }
+
+  if (events.length === 0) {
+    return { success: true, output: `No gate events for ${issueId}.` };
+  }
+  const lines = events.map(event => {
+    const label = event.event_type === 'gate.approved' ? 'APPROVED' : 'REJECTED';
+    const reason = event.reason ? ` — ${event.reason}` : '';
+    return `${label} ${event.gate} by ${event.actor} at ${event.created_at}${reason}`;
+  });
+  return { success: true, output: `Gate events for ${issueId}:\n${lines.join('\n')}` };
+}
+
+async function handleCheck(issueId, gateId, projectRoot, opts) {
+  if (!issueId || !gateId) {
+    return { success: false, error: `Missing issue id or gate id.\n${usage()}` };
+  }
+  const known = validateKnownGate(gateId);
+  if (!known.ok) return { success: false, error: known.error };
+
+  // Disabled gate/rail → satisfied without any approval event (read via the shipped
+  // resolver). Rails share the workflow.gates toggle surface, so check both collections.
+  const resolved = getResolvedRuntimeGraph({ projectRoot });
+  const resolvedGate = [...resolved.gates, ...resolved.rails].find(gate => gate.id === gateId);
+  if (resolvedGate && resolvedGate.enabled === false) {
+    return { success: true, output: `gate ${gateId} is disabled — satisfied for ${issueId}` };
+  }
+
+  const approved = await isGateApproved(projectRoot, issueId, gateId, { deps: kernelDeps(opts) });
+  if (approved) {
+    return { success: true, output: `gate ${gateId} approved for ${issueId}` };
+  }
+  return { success: false, error: `gate ${gateId} not approved for ${issueId}` };
+}
+
+async function handler(args, flags = {}, projectRoot = process.cwd(), opts = {}) {
+  const [action, ...rest] = args;
+
+  // `gate doc [<doc-gate sub> ...]` → the standalone doc-gate handler, with the
+  // consumed `doc` token dropped so its own arg shape (detect/check/init/okf …)
+  // and flags (`--base`/`--head`/`--json`/`--skip` …) reach it byte-identically.
+  if (action === 'doc') {
+    return docGate.handler(rest, flags, projectRoot, opts);
+  }
+
+  if (TOGGLE_ACTIONS.has(action)) {
+    return handleToggle(action, rest[0], projectRoot);
+  }
+  if (EVENT_ACTIONS.has(action)) {
+    if (action === 'status') {
+      return handleStatus(rest[0], flags, projectRoot, opts);
+    }
+    if (action === 'check') {
+      return handleCheck(rest[0], rest[1], projectRoot, opts);
+    }
+    return handleDecision(action, rest[0], rest[1], flags, projectRoot, opts);
+  }
+
+  return {
+    success: false,
+    error: `Expected 'enable', 'disable', 'approve', 'reject', 'status', 'check', or 'doc'.\n${usage()}`,
+  };
+}
+
+module.exports = {
+  name: 'gate',
+  description: 'Toggle a workflow gate, or record/query human-gate approval events',
+  usage: usage(),
+  handler,
+};