@xenonbyte/da-vinci-workflow 0.2.8 → 0.2.9

package/lib/cli/command-handlers-workflow.js

@@ -0,0 +1,221 @@
+const { registerCommand } = require("./helpers");
+
+/**
+ * @typedef {Object} CliWorkflowCommandContext
+ * @property {string[]} argv
+ * @property {string[]} positionalArgs
+ * @property {boolean} continueOnError
+ * @property {(args: string[], name: string) => string | undefined} getOption
+ * @property {(args: string[], name: string) => string[]} getCommaSeparatedOptionValues
+ * @property {Function} deriveWorkflowStatus
+ * @property {Function} formatWorkflowStatusReport
+ * @property {Function} formatNextStepReport
+ * @property {Function} generatePlanningSidecars
+ * @property {Function} formatGenerateSidecarsReport
+ * @property {Function} writeTaskExecutionEnvelope
+ * @property {Function} formatTaskExecutionReport
+ * @property {Function} writeTaskReviewEnvelope
+ * @property {Function} formatTaskReviewReport
+ * @property {Function} runWorktreePreflight
+ * @property {Function} formatWorktreePreflightReport
+ * @property {Function} diffSpec
+ * @property {Function} formatDiffSpecReport
+ * @property {Function} scaffoldFromBindings
+ * @property {Function} formatScaffoldReport
+ * @property {Function} auditProject
+ * @property {Function} formatAuditReport
+ * @property {Function} bootstrapProjectArtifacts
+ * @property {Function} formatBootstrapProjectReport
+ * @property {Function} persistExecutionSignal
+ * @property {Function} emitCommandOutput
+ * @property {Function} emitOrThrowOnStatus
+ */
+
+/**
+ * Register workflow, planning, review, and audit-oriented CLI commands.
+ *
+ * @param {import("./helpers").CliCommandHandlerMap} handlers
+ * @param {CliWorkflowCommandContext} context
+ * @returns {void}
+ */
+function registerWorkflowCommands(handlers, context) {
+  const {
+    argv,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    getCommaSeparatedOptionValues,
+    deriveWorkflowStatus,
+    formatWorkflowStatusReport,
+    formatNextStepReport,
+    generatePlanningSidecars,
+    formatGenerateSidecarsReport,
+    writeTaskExecutionEnvelope,
+    formatTaskExecutionReport,
+    writeTaskReviewEnvelope,
+    formatTaskReviewReport,
+    runWorktreePreflight,
+    formatWorktreePreflightReport,
+    diffSpec,
+    formatDiffSpecReport,
+    scaffoldFromBindings,
+    formatScaffoldReport,
+    auditProject,
+    formatAuditReport,
+    bootstrapProjectArtifacts,
+    formatBootstrapProjectReport,
+    persistExecutionSignal,
+    emitCommandOutput,
+    emitOrThrowOnStatus
+  } = context;
+
+  registerCommand(handlers, "workflow-status", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "workflow-status",
+      env: process.env
+    });
+
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    console.log(formatWorkflowStatusReport(result));
+  });
+
+  registerCommand(handlers, "next-step", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = deriveWorkflowStatus(projectPath, {
+      changeId,
+      traceSurface: "next-step",
+      env: process.env
+    });
+
+    if (argv.includes("--json")) {
+      console.log(
+        JSON.stringify(
+          {
+            stage: result.stage,
+            checkpointState: result.checkpointState,
+            nextStep: result.nextStep || null,
+            blockingGate: result.blockingGate || null,
+            discipline: result.discipline || null,
+            executionProfile: result.executionProfile || null,
+            worktreePreflight: result.worktreePreflight || null,
+            verificationFreshness: result.verificationFreshness || null,
+            traceDiagnostics: result.traceDiagnostics || null
+          },
+          null,
+          2
+        )
+      );
+      return;
+    }
+
+    console.log(formatNextStepReport(result));
+  });
+
+  registerCommand(handlers, "generate-sidecars", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = generatePlanningSidecars(projectPath, { changeId, write: true });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "generate-sidecars", result, false);
+    emitCommandOutput(result, argv, formatGenerateSidecarsReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "task-execution", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = writeTaskExecutionEnvelope(projectPath, {
+      changeId,
+      taskGroupId: getOption(argv, "--task-group"),
+      status: getOption(argv, "--status"),
+      summary: getOption(argv, "--summary"),
+      changedFiles: getCommaSeparatedOptionValues(argv, "--changed-files"),
+      testEvidence: getCommaSeparatedOptionValues(argv, "--test-evidence"),
+      pendingTestEvidence: getCommaSeparatedOptionValues(argv, "--pending-test-evidence"),
+      confirmTestEvidenceExecuted: argv.includes("--confirm-test-evidence-executed"),
+      concerns: getCommaSeparatedOptionValues(argv, "--concerns"),
+      blockers: getCommaSeparatedOptionValues(argv, "--blockers"),
+      outOfScopeWrites: getCommaSeparatedOptionValues(argv, "--out-of-scope-writes"),
+      partial: argv.includes("--partial")
+    });
+    emitCommandOutput(result, argv, formatTaskExecutionReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "task-review", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = writeTaskReviewEnvelope(projectPath, {
+      changeId,
+      taskGroupId: getOption(argv, "--task-group"),
+      stage: getOption(argv, "--stage"),
+      status: getOption(argv, "--status"),
+      summary: getOption(argv, "--summary"),
+      issues: getCommaSeparatedOptionValues(argv, "--issues"),
+      reviewer: getOption(argv, "--reviewer"),
+      writeVerification: argv.includes("--write-verification")
+    });
+    emitCommandOutput(result, argv, formatTaskReviewReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "worktree-preflight", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const result = runWorktreePreflight(projectPath);
+    persistExecutionSignal(projectPath, changeId || "global", "worktree-preflight", result, false);
+    if (argv.includes("--json")) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatWorktreePreflightReport(result));
+  });
+
+  registerCommand(handlers, "diff-spec", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const fromDir = getOption(argv, "--from");
+    const result = diffSpec(projectPath, { changeId, fromDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "diff-spec", result, false);
+    emitCommandOutput(result, argv, formatDiffSpecReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "scaffold", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const outputDir = getOption(argv, "--output");
+    const result = scaffoldFromBindings(projectPath, { changeId, outputDir });
+    persistExecutionSignal(projectPath, result.changeId || changeId, "scaffold", result, false);
+    emitCommandOutput(result, argv, formatScaffoldReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "audit", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const mode = getOption(argv, "--mode");
+    const changeId = getOption(argv, "--change");
+    const result = auditProject(projectPath, { mode, changeId });
+    const report = formatAuditReport(result);
+
+    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
+      return;
+    }
+
+    console.log(report);
+  });
+
+  registerCommand(handlers, "bootstrap-project", async () => {
+    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
+    const changeId = getOption(argv, "--change");
+    const force = argv.includes("--force");
+    const result = bootstrapProjectArtifacts(projectPath, { changeId, force });
+    console.log(formatBootstrapProjectReport(result));
+  });
+}
+
+module.exports = {
+  registerWorkflowCommands
+};

package/lib/cli/command-handlers.js

@@ -0,0 +1,49 @@
+const { registerCoreCommands } = require("./command-handlers-core");
+const { registerWorkflowCommands } = require("./command-handlers-workflow");
+const { registerDesignCommands } = require("./command-handlers-design");
+const { registerPenCommands } = require("./command-handlers-pen");
+
+function resolveFamilyContext(shared, optionHelpers, family) {
+  return {
+    ...shared,
+    ...optionHelpers,
+    ...(family || {})
+  };
+}
+
+/**
+ * Build the complete CLI command registry from command-family registration modules.
+ *
+ * @param {object} context
+ * @returns {Map<string, Function>}
+ */
+function buildCommandHandlers(context) {
+  const shared = context && context.shared ? context.shared : context;
+  const optionHelpers = context && context.optionHelpers ? context.optionHelpers : context;
+  const handlers = new Map();
+  registerCoreCommands(
+    handlers,
+    resolveFamilyContext(shared, optionHelpers, context && context.core ? context.core : context)
+  );
+  registerWorkflowCommands(
+    handlers,
+    resolveFamilyContext(
+      shared,
+      optionHelpers,
+      context && context.workflow ? context.workflow : context
+    )
+  );
+  registerDesignCommands(
+    handlers,
+    resolveFamilyContext(shared, optionHelpers, context && context.design ? context.design : context)
+  );
+  registerPenCommands(
+    handlers,
+    resolveFamilyContext(shared, optionHelpers, context && context.pen ? context.pen : context)
+  );
+  return handlers;
+}
+
+module.exports = {
+  buildCommandHandlers
+};

package/lib/cli/helpers.js

@@ -1,6 +1,19 @@
 const { writeExecutionSignal } = require("../execution-signals");
 const { STATUS } = require("../workflow-contract");
 
+/**
+ * @typedef {Map<string, Function>} CliCommandHandlerMap
+ */
+
+/**
+ * Throw on blocked/failing statuses unless `--continue-on-error` is active.
+ *
+ * @param {string} status
+ * @param {string[]} blockedStatuses
+ * @param {string} output
+ * @param {boolean} continueOnError
+ * @returns {boolean}
+ */
 function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
   if (!Array.isArray(blockedStatuses) || !blockedStatuses.includes(status)) {
     return false;
@@ -12,6 +25,53 @@ function emitOrThrowOnStatus(status, blockedStatuses, output, continueOnError) {
   throw new Error(output);
 }
 
+/**
+ * Emit either JSON or formatted text for a command result, respecting `--continue-on-error`.
+ *
+ * @param {{ status: string }} result
+ * @param {string[]} argv
+ * @param {(result: object) => string} formatter
+ * @param {string[]} blockedStatuses
+ * @param {boolean} continueOnError
+ * @returns {void}
+ */
+function emitCommandOutput(result, argv, formatter, blockedStatuses, continueOnError) {
+  const output = argv.includes("--json")
+    ? JSON.stringify(result, null, 2)
+    : formatter(result);
+  if (
+    Array.isArray(blockedStatuses) &&
+    emitOrThrowOnStatus(result.status, blockedStatuses, output, continueOnError)
+  ) {
+    return;
+  }
+  console.log(output);
+}
+
+/**
+ * Register one or more command names against the same handler.
+ *
+ * @param {CliCommandHandlerMap} handlers
+ * @param {string|string[]} names
+ * @param {Function} handler
+ * @returns {void}
+ */
+function registerCommand(handlers, names, handler) {
+  for (const name of Array.isArray(names) ? names : [names]) {
+    handlers.set(name, handler);
+  }
+}
+
+/**
+ * Persist an advisory execution signal for workflow/routing consumers.
+ *
+ * @param {string} projectPath
+ * @param {string} changeId
+ * @param {string} surface
+ * @param {{ status?: string, failures?: string[], warnings?: string[], notes?: string[], gates?: object, summary?: object }} result
+ * @param {boolean} [strict=false]
+ * @returns {void}
+ */
 function persistExecutionSignal(projectPath, changeId, surface, result, strict = false) {
   const normalizeStatus = (status) => {
     const normalized = String(status || "").trim().toUpperCase();
@@ -100,5 +160,7 @@ function persistExecutionSignal(projectPath, changeId, surface, result, strict =
 
 module.exports = {
   emitOrThrowOnStatus,
+  emitCommandOutput,
+  registerCommand,
   persistExecutionSignal
 };