forge-workflow 0.0.9 → 0.1.0-beta.2

package/lib/commands/_manifest.js

@@ -0,0 +1,91 @@
+/**
+ * Static Command Manifest — GENERATED FILE, DO NOT EDIT.
+ *
+ * Regenerate with: node scripts/gen-command-manifest.js
+ * Drift is enforced by test/structural/command-manifest-drift.test.js.
+ *
+ * This module `require`s every command by a static relative path so
+ * `bun build --compile` can statically bundle the command graph. The registry
+ * (lib/commands/_registry.js) consumes `commands` as its fast, bundleable path
+ * and falls back to `fs.readdirSync` auto-discovery for dev/extension commands.
+ *
+ * @module commands/_manifest
+ */
+
+'use strict';
+
+/**
+ * @typedef {Object} ManifestEntry
+ * @property {string} file - Command filename (e.g. `status.js`)
+ * @property {import("./_registry").CommandModule} module - The required command module
+ */
+
+/** @type {ManifestEntry[]} */
+const commands = [
+  { file: "adapter.js", module: require("./adapter") },
+  { file: "add.js", module: require("./add") },
+  { file: "audit.js", module: require("./audit") },
+  { file: "blocked.js", module: require("./blocked") },
+  { file: "board.js", module: require("./board") },
+  { file: "claim.js", module: require("./claim") },
+  { file: "claims.js", module: require("./claims") },
+  { file: "clean.js", module: require("./clean") },
+  { file: "close.js", module: require("./close") },
+  { file: "comment.js", module: require("./comment") },
+  { file: "control.js", module: require("./control") },
+  { file: "create.js", module: require("./create") },
+  { file: "dev.js", module: require("./dev") },
+  { file: "doc-gate.js", module: require("./doc-gate") },
+  { file: "doctor.js", module: require("./doctor") },
+  { file: "explain.js", module: require("./explain") },
+  { file: "export.js", module: require("./export") },
+  { file: "gate.js", module: require("./gate") },
+  { file: "hooks.js", module: require("./hooks") },
+  { file: "inbox.js", module: require("./inbox") },
+  { file: "init.js", module: require("./init") },
+  { file: "insights.js", module: require("./insights") },
+  { file: "issue.js", module: require("./issue") },
+  { file: "issues.js", module: require("./issues") },
+  { file: "lint.js", module: require("./lint") },
+  { file: "list.js", module: require("./list") },
+  { file: "merge.js", module: require("./merge") },
+  { file: "migrate.js", module: require("./migrate") },
+  { file: "new.js", module: require("./new") },
+  { file: "options.js", module: require("./options") },
+  { file: "orient.js", module: require("./orient") },
+  { file: "orphans.js", module: require("./orphans") },
+  { file: "patch.js", module: require("./patch") },
+  { file: "plan.js", module: require("./plan") },
+  { file: "preflight.js", module: require("./preflight") },
+  { file: "prime.js", module: require("./prime") },
+  { file: "push.js", module: require("./push") },
+  { file: "ready.js", module: require("./ready") },
+  { file: "recall.js", module: require("./recall") },
+  { file: "recap.js", module: require("./recap") },
+  { file: "recommend.js", module: require("./recommend") },
+  { file: "release.js", module: require("./release") },
+  { file: "remember.js", module: require("./remember") },
+  { file: "role.js", module: require("./role") },
+  { file: "serve.js", module: require("./serve") },
+  { file: "setup.js", module: require("./setup") },
+  { file: "shepherd.js", module: require("./shepherd") },
+  { file: "ship.js", module: require("./ship") },
+  { file: "show.js", module: require("./show") },
+  { file: "stage.js", module: require("./stage") },
+  { file: "stale.js", module: require("./stale") },
+  { file: "status.js", module: require("./status") },
+  { file: "sync.js", module: require("./sync") },
+  { file: "team.js", module: require("./team") },
+  { file: "test.js", module: require("./test") },
+  { file: "update.js", module: require("./update") },
+  { file: "upgrade.js", module: require("./upgrade") },
+  { file: "validate.js", module: require("./validate") },
+  { file: "worktree.js", module: require("./worktree") },
+];
+
+module.exports = {
+  // Absolute path of the canonical commands directory this manifest describes.
+  // The registry applies the manifest only when asked to load this exact dir.
+  dir: __dirname,
+  commands,
+};

package/lib/commands/_registry.js

@@ -13,11 +13,26 @@ const { existsSync, readdirSync } = require('node:fs');
 const path = require('node:path');
 const { normalizeStageId } = require('../workflow/stages');
 
+// Static command manifest (bundleable fast path). This is a static require so
+// `bun build --compile` can bundle the command graph; the file is generated by
+// scripts/gen-command-manifest.js and drift-checked in test/structural. In a dev
+// checkout before generation (or if removed) it may be absent — fall back to
+// readdir auto-discovery below.
+let STATIC_MANIFEST = null;
+try {
+  STATIC_MANIFEST = require('./_manifest');
+} catch (err) {
+  if (err.code !== 'MODULE_NOT_FOUND') {
+    console.warn(`[registry] Failed to load static manifest: ${err.message}`);
+  }
+  STATIC_MANIFEST = null;
+}
+
 /**
  * @typedef {Object} CommandModule
  * @property {string} name - Command name used for routing
  * @property {string} description - Human-readable description
- * @property {function(Array, Object, string): Promise<*>} handler - Async command handler
+ * @property {function(Array, Object, string, Object=): Promise<*>} handler - Async command handler (4th arg: resolved command opts)
  * @property {string} [usage] - Usage string (optional)
  * @property {Object<string, string>} [flags] - Flag descriptions (optional)
  */
@@ -57,46 +72,68 @@ function validateCommand(mod) {
  * @param {string} commandsDir - Absolute path to the commands directory
  * @returns {{ commands: Map<string, CommandModule>, getHelp: () => string }}
  */
-function loadCommands(commandsDir) {
-  /** @type {Map<string, CommandModule>} */
-  const commands = new Map();
+function addCommand(commands, file, mod) {
+  const validation = validateCommand(mod);
+  if (!validation.valid) {
+    console.warn(`[registry] Skipping ${file}: ${validation.reason}`);
+    return;
+  }
 
-  if (!commandsDir || !existsSync(commandsDir)) {
-    return {
-      commands,
-      getHelp: () => buildHelp(commands),
-    };
+  if (commands.has(mod.name)) {
+    console.warn(
+      `[registry] Skipping ${file}: duplicate command name "${mod.name}"`
+    );
+    return;
   }
 
-  const files = readdirSync(commandsDir)
-    .filter(f => f.endsWith('.js') && !f.startsWith('_'))
-    .sort(); // deterministic order — first file wins on duplicates
+  commands.set(mod.name, mod);
+}
 
-  for (const file of files) {
-    const filePath = path.join(commandsDir, file);
+function loadCommands(commandsDir) {
+  /** @type {Map<string, CommandModule>} */
+  const commands = new Map();
 
-    let mod;
-    try {
-      mod = require(filePath);
-    } catch (_err) {
-      console.warn(`[registry] Skipping ${file}: failed to load — ${_err.message}`);
-      continue;
+  // Files already contributed by the static manifest — skip re-requiring them
+  // during the readdir pass so they neither double-load nor warn as duplicates.
+  const seenFiles = new Set();
+
+  // 1) Static manifest fast path (bundleable). Applied only when the caller asks
+  //    for the exact canonical commands dir the manifest describes; extension
+  //    dirs fall through to readdir below. In a compiled binary there is no real
+  //    commands dir on disk, so the manifest is the only path that resolves.
+  if (
+    STATIC_MANIFEST &&
+    Array.isArray(STATIC_MANIFEST.commands) &&
+    commandsDir &&
+    path.resolve(commandsDir) === path.resolve(STATIC_MANIFEST.dir)
+  ) {
+    for (const entry of STATIC_MANIFEST.commands) {
+      seenFiles.add(entry.file);
+      addCommand(commands, entry.file, entry.module);
     }
+  }
 
-    const validation = validateCommand(mod);
-    if (!validation.valid) {
-      console.warn(`[registry] Skipping ${file}: ${validation.reason}`);
-      continue;
-    }
+  // 2) readdir auto-discovery (dev/extension fallback). Picks up command files
+  //    not covered by the manifest — including brand-new files a developer or
+  //    user drops in without regenerating the manifest — preserving extensibility.
+  if (commandsDir && existsSync(commandsDir)) {
+    const files = readdirSync(commandsDir)
+      .filter(f => f.endsWith('.js') && !f.startsWith('_'))
+      .sort(); // deterministic order — first file wins on duplicates
+
+    for (const file of files) {
+      if (seenFiles.has(file)) continue;
+
+      let mod;
+      try {
+        mod = require(path.join(commandsDir, file));
+      } catch (_err) {
+        console.warn(`[registry] Skipping ${file}: failed to load — ${_err.message}`);
+        continue;
+      }
 
-    if (commands.has(mod.name)) {
-      console.warn(
-        `[registry] Skipping ${file}: duplicate command name "${mod.name}"`
-      );
-      continue;
+      addCommand(commands, file, mod);
     }
-
-    commands.set(mod.name, mod);
   }
 
   return {
@@ -143,8 +180,9 @@ async function executeCommand(commands, commandName, args, flags, projectRoot, o
   }
 
   try {
+    let enforcement = null;
     if (typeof options.enforceStage === 'function' && isStageCommand(commandName)) {
-      const enforcement = await options.enforceStage({
+      enforcement = await options.enforceStage({
         commandName,
         args,
         flags,
@@ -161,7 +199,20 @@ async function executeCommand(commands, commandName, args, flags, projectRoot, o
       }
     }
 
-    return await command.handler(args, flags, projectRoot);
+    // Forward a resolved per-command opts object as the handler's 4th arg. Issue/
+    // alias handlers read it (shouldUseKernelBroker(opts)); other handlers ignore
+    // it. Backward-compatible: defaults to {} so existing 3-arg handlers are
+    // unaffected.
+    const result = await command.handler(args, flags, projectRoot, options.commandOpts ?? {});
+
+    // Record stage COMPLETION into the kernel only when the command SUCCEEDED, so
+    // a stage counts as 'done' (which gates ship/review) only when its command
+    // actually passed — not merely when it was entered.
+    if (result?.success !== false && typeof enforcement?.recordCompletion === 'function') {
+      enforcement.recordCompletion();
+    }
+
+    return result;
   } catch (err) {
     return {
       success: false,

package/lib/commands/_resolve-command-opts.js

@@ -0,0 +1,261 @@
+'use strict';
+
+/**
+ * Resolve the per-command opts object that bin/forge.js threads to the registry
+ * handler (the 4th arg). For issue/alias commands this:
+ *
+ *   1. Strips the selector tokens (`--kernel`, `--issue-backend <val>`) from the
+ *      args BEFORE they reach the handler / bd. This is load-bearing: bin
+ *      parseFlags() early-returns for issue passthrough commands, so these tokens
+ *      otherwise flow untouched into the handler and (beads path) into bd, which
+ *      rejects the unknown flag — and the positional `kernel`/`beads` value would
+ *      be mistaken for an issue id.
+ *   2. Resolves the backend (flag > env > config > default) via the backend
+ *      authority module (lib/issue-backend.js). The CLI flag tokens are mapped to
+ *      that module's `deps.issueBackend` signal; env/config/default precedence is
+ *      applied by the resolver itself.
+ *   3. When kernel, assembles the kernel deps (driver + flag) via the CLI broker
+ *      factory so createKernelIssueBackend has a real driver (B1).
+ *
+ * Kernel-native tool commands (KERNEL_TOOL_COMMANDS, e.g. `export`) instead get a
+ * migrated Kernel broker injected as `_broker` (independent of the selector), and
+ * all other non-issue commands get an empty opts object and untouched args.
+ *
+ * @module commands/resolve-command-opts
+ */
+
+const { resolveIssueBackend } = require('../issue-backend');
+const {
+  buildMigratedKernelIssueDeps: defaultBuildKernelIssueDeps,
+} = require('../kernel/cli-broker-factory');
+
+// Commands that route issue operations and therefore honor the selector. Mirrors
+// the alias wrappers in lib/commands/ plus the `issue`/`issues` grouping commands.
+const ISSUE_COMMANDS = new Set([
+  'create',
+  'update',
+  'claim',
+  'release',
+  'comment',
+  'close',
+  'show',
+  'list',
+  'ready',
+  'blocked',
+  'stale',
+  'orphans',
+  'lint',
+  // Epic grouping read — must be kernel-routed (its issue.children rollup has no
+  // verified Beads equivalent), so it belongs in ISSUE_COMMANDS like the rest.
+  'children',
+  // Lease-ownership verification — a kernel-only read (leases live in the Kernel),
+  // so it is kernel-routed like the rest of the issue surface.
+  'owns',
+  // Active-lease listing — a kernel-only read (leases live in the Kernel), so it
+  // is kernel-routed like the rest of the issue surface.
+  'claims',
+  'search',
+  'stats',
+  'dep',
+  'issue',
+  'issues',
+]);
+
+// Kernel-native tool commands that operate directly on the Kernel regardless of the
+// issue-backend selector, so they need a real (migrated) Kernel broker injected as
+// the handler's `_broker`. `export` drains the Kernel projection outbox to
+// git-tracked JSONL (D16); without an injected broker its handler always reports
+// "No Kernel broker available" and writes nothing.
+const KERNEL_TOOL_COMMANDS = new Set([
+  'export',
+]);
+
+const ISSUE_BACKEND_FLAG = '--issue-backend';
+const KERNEL_FLAG = '--kernel';
+const KERNEL = 'kernel';
+
+/**
+ * Remove the issue-backend selector tokens from an args array and report what
+ * they selected. Handles `--kernel`, `--issue-backend <val>` (space form), and
+ * `--issue-backend=<val>` (= form). All other tokens pass through unchanged.
+ *
+ * @param {string[]} rawArgs
+ * @returns {{ args: string[], flags: { kernel?: boolean, issueBackend?: string } }}
+ */
+function stripSelectorTokens(rawArgs = []) {
+  const args = [];
+  const flags = {};
+  for (let i = 0; i < rawArgs.length; i += 1) {
+    const token = rawArgs[i];
+    if (token === KERNEL_FLAG) {
+      flags.kernel = true;
+      continue;
+    }
+    if (token === ISSUE_BACKEND_FLAG) {
+      // Space form: consume the following value token as the backend name. Only a
+      // non-flag token counts — a missing value or a following flag (e.g.
+      // `--issue-backend --reason=x`) must throw rather than silently swallow the
+      // next flag and fall back to the default backend.
+      const next = rawArgs[i + 1];
+      if (typeof next === 'string' && !next.startsWith('--')) {
+        flags.issueBackend = next;
+        i += 1;
+      } else {
+        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel or beads.`);
+      }
+      continue;
+    }
+    if (typeof token === 'string' && token.startsWith(`${ISSUE_BACKEND_FLAG}=`)) {
+      // Equals form: reject an empty value (`--issue-backend=`) for the same reason.
+      const value = token.slice(ISSUE_BACKEND_FLAG.length + 1).trim();
+      if (!value) {
+        throw new Error(`${ISSUE_BACKEND_FLAG} requires a value: kernel or beads.`);
+      }
+      flags.issueBackend = value;
+      continue;
+    }
+    args.push(token);
+  }
+  return { args, flags };
+}
+
+/**
+ * Reduce the stripped selector flags to a single explicit backend value (or null
+ * when no flag selects one), honoring `--kernel` / `--issue-backend` equivalence
+ * and rejecting a mutually-exclusive conflict. Returned values are NOT validated
+ * here — the backend authority module normalizes/warns on unknown values.
+ *
+ * @param {{ kernel?: boolean, issueBackend?: string }} flags
+ * @returns {string|null}
+ * @throws {Error} when --kernel and --issue-backend select different backends.
+ */
+function resolveFlagBackend(flags = {}) {
+  const fromBackend = typeof flags.issueBackend === 'string' && flags.issueBackend.trim()
+    ? flags.issueBackend.trim()
+    : null;
+  const fromKernel = flags.kernel === true ? KERNEL : null;
+
+  if (fromKernel && fromBackend && fromKernel !== fromBackend.toLowerCase()) {
+    throw new Error(
+      `Conflicting issue backend flags: --kernel selects '${KERNEL}' but `
+      + `--issue-backend selects '${fromBackend}'. These are mutually exclusive.`,
+    );
+  }
+
+  return fromKernel || fromBackend || null;
+}
+
+// Run the first-use Beads import safety net for a kernel-routed command. Resolving the
+// migrate module lives INSIDE the try so even a require() failure (missing/corrupt
+// module) can never break command-opts resolution — the whole point of the safety net.
+// Shared by both kernel branches (issue + KERNEL_TOOL_COMMANDS) so the two call sites
+// cannot drift.
+async function runRuntimeAutoMigrate(deps, kernelDeps) {
+  try {
+    const autoMigrate = deps.autoMigrateBeadsAtRuntime
+      || require('./migrate').autoMigrateBeadsAtRuntime;
+    await autoMigrate({
+      projectRoot: deps.projectRoot,
+      databasePath: kernelDeps.kernelDatabasePath,
+      broker: kernelDeps.kernelBroker,
+      driver: kernelDeps.kernelDriver,
+    });
+  } catch {
+    // A migration-hook failure (including a require() failure) must never break the
+    // command it rides on.
+  }
+}
+
+/**
+ * Resolve the command opts and selector-stripped args for a dispatched command.
+ *
+ * @param {string} command - The command name (e.g. 'close').
+ * @param {string[]} rawArgs - The command args (already `args.slice(1)`).
+ * @param {Object} [deps]
+ * @param {Object} [deps.env] - Environment snapshot (default process.env).
+ * @param {string} [deps.projectRoot] - Repo root for env/config resolution + kernel DB.
+ * @param {Function} [deps.buildKernelIssueDeps] - Factory override (tests). May be
+ *   sync or async; its result is awaited.
+ * @returns {Promise<{ commandOpts: Object, args: string[] }>}
+ * @throws {Error} on conflicting flags (surfaced to user).
+ */
+async function resolveCommandOpts(command, rawArgs = [], deps = {}) {
+  const buildKernelIssueDeps = deps.buildKernelIssueDeps || defaultBuildKernelIssueDeps;
+
+  if (KERNEL_TOOL_COMMANDS.has(command)) {
+    // Kernel-native tools (e.g. `export`) always get a migrated Kernel broker the
+    // same way issue commands do (the CLI broker factory builds the driver, builds
+    // the broker, and runs initialize()). The handler consumes it as `_broker`.
+    // If no broker can be built (e.g. no SQLite runtime) we fall through with no
+    // broker so the handler skips gracefully rather than hard-failing — these tools
+    // are explicitly non-fatal when the Kernel is unavailable.
+    try {
+      const kernelDeps = await buildKernelIssueDeps({
+        projectRoot: deps.projectRoot,
+        databasePath: deps.databasePath,
+        gitCommonDir: deps.gitCommonDir,
+      });
+      // Same first-use safety net as the issue branch: an export-first upgrader would
+      // otherwise drain an EMPTY kernel and never trigger the one-time Beads import.
+      await runRuntimeAutoMigrate(deps, kernelDeps);
+      return { commandOpts: { _broker: kernelDeps.kernelBroker }, args: rawArgs };
+    } catch {
+      return { commandOpts: {}, args: rawArgs };
+    }
+  }
+
+  if (!ISSUE_COMMANDS.has(command)) {
+    return { commandOpts: {}, args: rawArgs };
+  }
+
+  const env = deps.env || process.env;
+
+  const { args, flags } = stripSelectorTokens(rawArgs);
+  const flagBackend = resolveFlagBackend(flags);
+  const issueBackend = resolveIssueBackend({
+    deps: flagBackend ? { issueBackend: flagBackend } : {},
+    env,
+    projectRoot: deps.projectRoot,
+  });
+
+  if (issueBackend !== KERNEL) {
+    return {
+      commandOpts: {
+        issueBackend,
+        useKernelBroker: false,
+      },
+      args,
+    };
+  }
+
+  // Kernel backend: assemble the driver (B1) + migrated broker (B2). The factory
+  // builder constructs the driver, builds the broker, and runs initialize().
+  const kernelDeps = await buildKernelIssueDeps({
+    projectRoot: deps.projectRoot,
+    databasePath: deps.databasePath,
+    gitCommonDir: deps.gitCommonDir,
+  });
+
+  // Safety net: the kernel is the default backend, but onboarding auto-migrate runs
+  // only from `forge setup`/`init`. An existing repo whose user merely upgrades forge
+  // would read an EMPTY kernel here and their existing Beads issues would appear to
+  // vanish. Import them ONCE on first kernel use (idempotent, gated by an in-DB marker
+  // that shares the kernel DB lifecycle, stderr only).
+  await runRuntimeAutoMigrate(deps, kernelDeps);
+
+  return {
+    commandOpts: {
+      issueBackend: KERNEL,
+      ...kernelDeps,
+    },
+    args,
+  };
+}
+
+module.exports = {
+  resolveCommandOpts,
+  stripSelectorTokens,
+  resolveFlagBackend,
+  ISSUE_COMMANDS,
+  KERNEL_TOOL_COMMANDS,
+};