@xenonbyte/da-vinci-workflow 0.2.7 → 0.2.9

package/lib/cli.js

@@ -79,7 +79,12 @@ const {
 } = require("./verify");
 const { diffSpec, formatDiffSpecReport } = require("./diff-spec");
 const { scaffoldFromBindings, formatScaffoldReport } = require("./scaffold");
-const { emitOrThrowOnStatus, persistExecutionSignal } = require("./cli/helpers");
+const {
+  emitOrThrowOnStatus,
+  emitCommandOutput,
+  persistExecutionSignal
+} = require("./cli/helpers");
+const { buildCommandHandlers } = require("./cli/command-handlers");
 const { handleVerifyFamilyCommand } = require("./cli/verify-family");
 const { handleLintFamilyCommand } = require("./cli/lint-family");
 const {
@@ -280,6 +285,18 @@ const HELP_OPTION_SPECS = [
   { flag: "--force", description: "overwrite bootstrap placeholders or force commands that explicitly support it" }
 ];
 
+const HELP_COMMANDS = new Set(["help", "--help", "-h"]);
+const HELP_OPTION_FLAG_WIDTH = 30;
+
+function formatHelpOptionLine(optionSpec) {
+  const flag = String(optionSpec.flag || "").trim();
+  const description = String(optionSpec.description || "").trim();
+  if (flag.length >= HELP_OPTION_FLAG_WIDTH) {
+    return [`  ${flag}`, `${" ".repeat(HELP_OPTION_FLAG_WIDTH + 2)}${description}`].join("\n");
+  }
+  return `  ${flag.padEnd(HELP_OPTION_FLAG_WIDTH, " ")}${description}`;
+}
+
 function readLimitedStdin(maxBytes = DEFAULT_MAX_PREFLIGHT_STDIN_BYTES, options = {}) {
   const limit =
     Number.isFinite(Number(maxBytes)) && Number(maxBytes) > 0
@@ -546,10 +563,7 @@ function appendStatusIssues(lines, label, missing = [], mismatched = [], unreada
 }
 
 function printHelp() {
-  const optionLines = HELP_OPTION_SPECS.map((optionSpec) => {
-    const paddedFlag = optionSpec.flag.padEnd(30, " ");
-    return `  ${paddedFlag}${optionSpec.description}`;
-  });
+  const optionLines = HELP_OPTION_SPECS.map(formatHelpOptionLine);
 
   console.log(
     [
@@ -1000,140 +1014,92 @@ async function runCli(argv) {
   const positionalArgs = getPositionalArgs(argv.slice(1), OPTION_FLAGS_WITH_VALUES);
   const continueOnError = shouldContinueOnError(argv);
 
-  if (!command || command === "help" || command === "--help" || command === "-h") {
+  if (!command || HELP_COMMANDS.has(command)) {
     printHelp();
     return;
   }
 
-  if (command === "--version" || command === "-v" || command === "version") {
-    console.log(`Da Vinci v${VERSION}`);
-    return;
-  }
-
-  if (command === "install") {
-    const platformValue = getOption(argv, "--platform") || "all";
-    const result = installPlatforms(platformValue, { homeDir });
-    console.log(
-      `Installed Da Vinci v${result.version} for ${result.platforms.join(", ")} at ${result.homeDir}`
-    );
-    return;
-  }
-
-  if (command === "uninstall") {
-    const platformValue = getOption(argv, "--platform") || "all";
-    const result = uninstallPlatforms(platformValue, { homeDir });
-    console.log(
-      `Uninstalled Da Vinci v${result.version} for ${result.platforms.join(", ")} from ${result.homeDir}`
-    );
-    return;
-  }
-
-  if (command === "status") {
-    console.log(formatStatus(getStatus({ homeDir })));
-    return;
-  }
-
-  if (command === "verify-install") {
-    const platformValue = getOption(argv, "--platform") || "";
-    const result = verifyInstall({
-      homeDir,
-      platforms: platformValue
-    });
-    const output = argv.includes("--json")
-      ? JSON.stringify(result, null, 2)
-      : formatVerifyInstallReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "maintainer-readiness") {
-    const platformValue = getOption(argv, "--platform") || "";
-    const repoRoot = getOption(argv, "--project") || process.cwd();
-    const result = runMaintainerReadinessCheck({
-      repoRoot,
+  const handlers = buildCommandHandlers({
+    shared: {
+      argv,
       homeDir,
-      platforms: platformValue
-    });
-    const output = argv.includes("--json")
-      ? JSON.stringify(result, null, 2)
-      : formatMaintainerReadinessReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "tui") {
-    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
-    const changeId = getOption(argv, "--change");
-    const lang = getOption(argv, "--lang");
-    const tuiWidth = getOption(argv, "--tui-width");
-    const altScreen = argv.includes("--alt-screen")
-      ? true
-      : argv.includes("--no-alt-screen")
-        ? false
-        : undefined;
-    if (argv.includes("--help") || argv.includes("-h")) {
-      console.log(formatTuiHelp(lang));
-      return;
-    }
-    await launchTui({
-      projectPath,
-      changeId,
-      lang,
-      tuiWidth,
-      altScreen,
-      strict: argv.includes("--strict"),
-      jsonOutput: argv.includes("--json"),
+      positionalArgs,
       continueOnError
-    });
-    return;
-  }
-
-  if (command === "workflow-status") {
-    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
-    const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
-
-    if (argv.includes("--json")) {
-      console.log(JSON.stringify(result, null, 2));
-      return;
-    }
-
-    console.log(formatWorkflowStatusReport(result));
-    return;
-  }
-
-  if (command === "next-step") {
-    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
-    const changeId = getOption(argv, "--change");
-    const result = deriveWorkflowStatus(projectPath, { changeId });
-
-    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
-          },
-          null,
-          2
-        )
-      );
-      return;
+    },
+    optionHelpers: {
+      getOption,
+      getIntegerOption,
+      getCommaSeparatedOptionValues
+    },
+    core: {
+      VERSION,
+      installPlatforms,
+      uninstallPlatforms,
+      getStatus,
+      verifyInstall,
+      validateAssets,
+      runMaintainerReadinessCheck,
+      formatMaintainerReadinessReport,
+      formatStatus,
+      formatVerifyInstallReport,
+      emitCommandOutput,
+      formatTuiHelp,
+      launchTui
+    },
+    workflow: {
+      deriveWorkflowStatus,
+      formatWorkflowStatusReport,
+      formatNextStepReport,
+      generatePlanningSidecars,
+      formatGenerateSidecarsReport,
+      writeTaskExecutionEnvelope,
+      formatTaskExecutionReport,
+      writeTaskReviewEnvelope,
+      formatTaskReviewReport,
+      runWorktreePreflight,
+      formatWorktreePreflightReport,
+      diffSpec,
+      formatDiffSpecReport,
+      scaffoldFromBindings,
+      formatScaffoldReport,
+      auditProject,
+      formatAuditReport,
+      bootstrapProjectArtifacts,
+      formatBootstrapProjectReport,
+      persistExecutionSignal,
+      emitCommandOutput,
+      emitOrThrowOnStatus
+    },
+    design: {
+      syncIconCatalog,
+      formatIconSyncReport,
+      handleIconSearchCommand,
+      readOperations,
+      readLimitedStdin,
+      preflightPencilBatch,
+      formatPencilPreflightReport,
+      emitOrThrowOnStatus,
+      handleSupervisorReviewCommand,
+      saveCurrentDesign,
+      formatSaveCurrentDesignReport,
+      SAVE_STATUS
+    },
+    pen: {
+      ensurePenFile,
+      writePenFromPayloadFiles,
+      comparePenSync,
+      comparePenBaselineAlignment,
+      formatPenBaselineAlignmentReport,
+      syncPenSource,
+      snapshotPenFile,
+      handlePencilLockCommand,
+      handlePencilSessionCommand,
+      emitOrThrowOnStatus
     }
-
-    console.log(formatNextStepReport(result));
+  });
+  const commandHandler = handlers.get(command);
+  if (commandHandler) {
+    await commandHandler();
     return;
   }
 
@@ -1158,22 +1124,6 @@ async function runCli(argv) {
     return;
   }
 
-  if (command === "generate-sidecars") {
-    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);
-    const useJson = argv.includes("--json");
-    const output = useJson ? JSON.stringify(result, null, 2) : formatGenerateSidecarsReport(result);
-
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-
-    console.log(output);
-    return;
-  }
-
   if (
     handleVerifyFamilyCommand(command, {
       argv,
@@ -1194,391 +1144,6 @@ async function runCli(argv) {
     return;
   }
 
-  if (command === "task-execution") {
-    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")
-    });
-    const useJson = argv.includes("--json");
-    const output = useJson ? JSON.stringify(result, null, 2) : formatTaskExecutionReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "task-review") {
-    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")
-    });
-    const useJson = argv.includes("--json");
-    const output = useJson ? JSON.stringify(result, null, 2) : formatTaskReviewReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "worktree-preflight") {
-    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));
-    return;
-  }
-
-  if (command === "diff-spec") {
-    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);
-    const useJson = argv.includes("--json");
-    const output = useJson ? JSON.stringify(result, null, 2) : formatDiffSpecReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "scaffold") {
-    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);
-    const useJson = argv.includes("--json");
-    const output = useJson ? JSON.stringify(result, null, 2) : formatScaffoldReport(result);
-    if (emitOrThrowOnStatus(result.status, ["BLOCK"], output, continueOnError)) {
-      return;
-    }
-    console.log(output);
-    return;
-  }
-
-  if (command === "validate-assets") {
-    const result = validateAssets();
-    console.log(`Da Vinci v${result.version} assets are complete (${result.requiredAssets} required files).`);
-    return;
-  }
-
-  if (command === "audit") {
-    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);
-    return;
-  }
-
-  if (command === "bootstrap-project") {
-    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));
-    return;
-  }
-
-  if (command === "icon-sync") {
-    const outputPath = getOption(argv, "--output") || getOption(argv, "--catalog");
-    const timeoutMs = getIntegerOption(argv, "--timeout-ms", { min: 1 });
-    const strict = argv.includes("--strict");
-
-    const result = await syncIconCatalog({
-      outputPath,
-      timeoutMs,
-      strict,
-      homeDir
-    });
-
-    console.log(formatIconSyncReport(result));
-    return;
-  }
-
-  if (command === "icon-search") {
-    await handleIconSearchCommand(argv, homeDir);
-    return;
-  }
-
-  if (command === "preflight-pencil") {
-    const opsFile = getOption(argv, "--ops-file");
-    let operations = "";
-
-    if (opsFile) {
-      operations = readOperations(opsFile);
-    } else if (!process.stdin.isTTY) {
-      operations = readLimitedStdin();
-    } else {
-      throw new Error("`preflight-pencil` requires `--ops-file <path>` or piped stdin input.");
-    }
-
-    const result = preflightPencilBatch(operations);
-    const report = formatPencilPreflightReport(result);
-
-    if (emitOrThrowOnStatus(result.status, ["FAIL"], report, continueOnError)) {
-      return;
-    }
-
-    console.log(report);
-    return;
-  }
-
-  if (command === "supervisor-review") {
-    await handleSupervisorReviewCommand(argv);
-    return;
-  }
-
-  if (command === "ensure-pen") {
-    const outputPath = getOption(argv, "--output");
-    const version = getOption(argv, "--version");
-    const verifyWithPencil = argv.includes("--verify-open");
-
-    if (!outputPath) {
-      throw new Error("`ensure-pen` requires `--output <path>`.");
-    }
-
-    const result = ensurePenFile({
-      outputPath,
-      version,
-      verifyWithPencil
-    });
-
-    console.log(`${result.created ? "Created" : "Verified existing"} .pen source at ${result.outputPath}`);
-    console.log(`State file: ${result.statePath}`);
-    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
-    if (result.verification) {
-      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
-    }
-    return;
-  }
-
-  if (command === "write-pen") {
-    const outputPath = getOption(argv, "--output");
-    const nodesFile = getOption(argv, "--nodes-file");
-    const variablesFile = getOption(argv, "--variables-file");
-    const version = getOption(argv, "--version");
-    const verifyWithPencil = argv.includes("--verify-open");
-
-    if (!outputPath || !nodesFile) {
-      throw new Error("`write-pen` requires `--output <path>` and `--nodes-file <path>`.");
-    }
-
-    const result = writePenFromPayloadFiles({
-      outputPath,
-      nodesFile,
-      variablesFile,
-      version,
-      verifyWithPencil
-    });
-
-    console.log(`Wrote .pen file to ${result.outputPath}`);
-    console.log(`State file: ${result.statePath}`);
-    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
-    console.log(`Top-level nodes: ${result.document.children.length}`);
-    if (result.verification) {
-      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
-    }
-    return;
-  }
-
-  if (command === "check-pen-sync") {
-    const penPath = getOption(argv, "--pen");
-    const nodesFile = getOption(argv, "--nodes-file");
-    const variablesFile = getOption(argv, "--variables-file");
-    const version = getOption(argv, "--version");
-
-    if (!penPath || !nodesFile) {
-      throw new Error("`check-pen-sync` requires `--pen <path>` and `--nodes-file <path>`.");
-    }
-
-    const result = comparePenSync({
-      penPath,
-      nodesFile,
-      variablesFile,
-      version
-    });
-
-    if (!result.inSync) {
-      throw new Error(
-        [
-          "Registered `.pen` is out of sync with the provided live payload.",
-          `Pen: ${result.penPath}`,
-          `State file: ${result.statePath}`,
-          `Persisted hash: ${result.persistedHash}`,
-          `Live hash: ${result.liveHash}`
-        ].join("\n")
-      );
-    }
-
-    console.log(`Registered .pen is in sync: ${result.penPath}`);
-    console.log(`State file: ${result.statePath}`);
-    console.log(`Snapshot hash: ${result.liveHash}`);
-    if (!result.usedStateFile) {
-      console.log(
-        result.stateHash
-          ? "State file hash was stale; sync comparison fell back to hashing the disk .pen file directly."
-          : "State file was missing; sync comparison fell back to hashing the disk .pen file directly."
-      );
-    }
-    return;
-  }
-
-  if (command === "check-pen-baseline") {
-    const penPath = getOption(argv, "--pen");
-    const baselinePaths = getCommaSeparatedOptionValues(argv, "--baseline");
-    const preferredSource = getOption(argv, "--prefer-source");
-
-    if (!penPath || baselinePaths.length === 0) {
-      throw new Error(
-        "`check-pen-baseline` requires `--pen <path>` and at least one `--baseline <path>`."
-      );
-    }
-
-    const result = comparePenBaselineAlignment({
-      penPath,
-      baselinePaths,
-      preferredSource
-    });
-
-    if (
-      emitOrThrowOnStatus(
-        result.status,
-        ["BLOCK"],
-        [
-          "Baseline alignment check failed.",
-          formatPenBaselineAlignmentReport(result)
-        ].join("\n"),
-        continueOnError
-      )
-    ) {
-      return;
-    }
-
-    console.log(formatPenBaselineAlignmentReport(result));
-    return;
-  }
-
-  if (command === "sync-pen-source") {
-    const sourcePath = getOption(argv, "--from");
-    const targetPath = getOption(argv, "--to");
-
-    if (!sourcePath || !targetPath) {
-      throw new Error("`sync-pen-source` requires `--from <path>` and `--to <path>`.");
-    }
-
-    const result = syncPenSource({
-      sourcePath,
-      targetPath
-    });
-
-    console.log(`Synced .pen source from ${result.sourcePath} to ${result.targetPath}`);
-    console.log(`State file: ${result.statePath}`);
-    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
-    return;
-  }
-
-  if (command === "snapshot-pen") {
-    const inputPath = getOption(argv, "--input");
-    const outputPath = getOption(argv, "--output");
-    const version = getOption(argv, "--version");
-    const verifyWithPencil = argv.includes("--verify-open");
-
-    if (!inputPath || !outputPath) {
-      throw new Error("`snapshot-pen` requires `--input <path>` and `--output <path>`.");
-    }
-
-    const result = snapshotPenFile({
-      inputPath,
-      outputPath,
-      version,
-      verifyWithPencil
-    });
-
-    console.log(`Snapshotted ${result.inputPath} to ${result.outputPath}`);
-    console.log(`State file: ${result.statePath}`);
-    console.log(`Snapshot hash: ${result.state.snapshotHash}`);
-    console.log(`Top-level nodes: ${result.document.children.length}`);
-    if (result.verification) {
-      console.log(`Verified reopen with Pencil (${result.verification.topLevelCount} top-level nodes).`);
-    }
-    return;
-  }
-
-  if (command === "save-current-design") {
-    const projectPath = getOption(argv, "--project") || positionalArgs[0] || process.cwd();
-    const pencilBin = getOption(argv, "--pencil-bin");
-    const result = await saveCurrentDesign({
-      projectPath,
-      homeDir,
-      pencilBin,
-      allowLocalBridge: true
-    });
-    const useJson = argv.includes("--json");
-    const output = useJson
-      ? JSON.stringify(result, null, 2)
-      : formatSaveCurrentDesignReport(result);
-
-    if (
-      emitOrThrowOnStatus(
-        result.status,
-        [SAVE_STATUS.BLOCKED, SAVE_STATUS.UNAVAILABLE],
-        output,
-        continueOnError
-      )
-    ) {
-      return;
-    }
-
-    console.log(output);
-    return;
-  }
-
-  if (command === "pencil-lock") {
-    handlePencilLockCommand(argv, homeDir);
-    return;
-  }
-
-  if (command === "pencil-session") {
-    handlePencilSessionCommand(argv, homeDir);
-    return;
-  }
-
   throw new Error(`Unknown command: ${command}`);
 }