@xenonbyte/da-vinci-workflow 0.2.8 → 0.2.9

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## v0.2.9 - 2026-04-05
+
+### Added
+- modular CLI command registration across `lib/cli/command-handlers-*.js`, with dedicated registry regression coverage for core, workflow, design, and pen command families
+- shared CLI test helpers in `scripts/cli-test-helpers.js` to keep `runCli` / JSON parsing behavior consistent across command-facing test suites
+
+### Changed
+- `runCli` now assembles family-scoped handler context instead of wiring a single flat command map payload, reducing coupling between unrelated CLI surfaces
+- release notes in `README.md` and `README.zh-CN.md` now point to the `0.2.9` modular CLI release
+
+### Fixed
+- `da-vinci --help` now keeps long option descriptions readable by wrapping oversized flags instead of collapsing flag and description text together
+- CLI regression suites now reuse shared process-spawn helpers instead of repeating slightly different local implementations
+
 ## v0.2.8 - 2026-04-05
 
 ### Added

package/README.md

@@ -34,15 +34,15 @@ Use `da-vinci maintainer-readiness` as the canonical maintainer diagnosis surfac
 
 Latest published npm package:
 
-- `@xenonbyte/da-vinci-workflow@0.2.8`
+- `@xenonbyte/da-vinci-workflow@0.2.9`
 
-Release highlights for `0.2.8`:
+Release highlights for `0.2.9`:
 
-- optional workflow decision tracing is now available for `workflow-status` and `next-step` through `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1`, with records written to `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
-- the initial trace-family allowlist now covers persisted-state trust, task-group seed fallback, task-group focus override, stale planning-signal fallback, verification freshness downgrade, and worktree-isolation downgrade
-- workflow decision traces remain bounded and diagnostic-only: they do not change routing truth, do not run on non-eligible commands, and do not block normal command execution when trace persistence fails
-- trace records now reject invalid schema combinations with visible diagnostics instead of silently disappearing
-- trace payloads no longer claim missing evidence exists, and persisted fallback traces no longer imply a fingerprint comparison happened when it did not
+- CLI command dispatch is now split into core, workflow, design, and pen handler registries instead of one oversized `runCli` branch chain
+- registry-level regression coverage now directly exercises representative commands from every CLI family, reducing the risk of missed command wiring during future refactors
+- command-facing test suites now share a common `runCli` / JSON parsing harness, which removes duplicated spawn helpers and keeps test behavior consistent
+- `da-vinci --help` now wraps long flags such as `--confirm-test-evidence-executed` onto a readable second line instead of collapsing flag and description text together
+- the release keeps runtime behavior unchanged while lowering maintenance cost for future CLI surface expansion
 
 ## Discipline And Orchestration Upgrade
 

package/README.zh-CN.md

@@ -37,15 +37,15 @@ Da Vinci 是一个把产品需求一路推进到结构化规格、Pencil 设计
 
 最新已发布 npm 包：
 
-- `@xenonbyte/da-vinci-workflow@0.2.8`
+- `@xenonbyte/da-vinci-workflow@0.2.9`
 
-`0.2.8` 版本重点：
+`0.2.9` 版本重点：
 
-- 现在可以通过 `DA_VINCI_TRACE_WORKFLOW_DECISIONS=1` 为 `workflow-status` 与 `next-step` 开启可选的 workflow decision tracing，记录会写入 `.da-vinci/logs/workflow-decisions/YYYY-MM-DD.ndjson`
-- 首批 trace-family allowlist 已覆盖 persisted-state trust、task-group seed fallback、task-group focus override、stale planning-signal fallback、verification freshness downgrade 与 worktree-isolation downgrade
-- workflow decision trace 仍然是 bounded 且 diagnostic-only：不会改变 routing truth，不会在非 eligible command 上发射，也不会因为 trace 持久化失败而阻断正常命令
-- trace record 现在会对非法 schema 组合给出可见诊断，不再静默丢失
-- trace payload 不再为缺失证据伪造 `evidenceRefs`，persisted fallback trace 也不再错误暗示某些未发生的 fingerprint comparison
+- CLI 命令分发现在拆成 core、workflow、design、pen 四组 handler registry，不再把所有命令逻辑都堆在一个超长 `runCli` 分支链里
+- registry 层回归测试现在直接覆盖每个 CLI family 的代表性命令，后续做命令面重构时更容易及时发现 wiring 漏洞
+- 多个命令测试脚本现在共用统一的 `runCli` / JSON 解析 helper，减少重复的 spawn 逻辑并保持测试行为一致
+- `da-vinci --help` 现在会把 `--confirm-test-evidence-executed` 这类超长 flag 正确换行显示，不再把 flag 和说明挤成一行
+- 这次发布不改变既有运行时契约，但显著降低了 CLI 表面的维护成本和后续扩展风险
 
 ## Discipline And Orchestration 升级
 

package/lib/async-offload.js

@@ -2,6 +2,7 @@ const { Worker } = require("worker_threads");
 const path = require("path");
 
 const WORKER_SCRIPT_PATH = path.join(__dirname, "async-offload-worker.js");
+const DEFAULT_WORKER_TIMEOUT_MS = 5 * 60 * 1000;
 
 function normalizeError(error) {
   if (!error || typeof error !== "object") {
@@ -24,22 +25,51 @@ function normalizeError(error) {
   return wrapped;
 }
 
-function runModuleExportInWorker(modulePath, exportName, args = []) {
+function resolveWorkerTimeoutMs(options = {}) {
+  const optionValue = Number(options.timeoutMs);
+  if (Number.isFinite(optionValue) && optionValue > 0) {
+    return optionValue;
+  }
+
+  const envValue = Number(process.env.DA_VINCI_WORKER_TIMEOUT_MS);
+  if (Number.isFinite(envValue) && envValue > 0) {
+    return envValue;
+  }
+
+  return DEFAULT_WORKER_TIMEOUT_MS;
+}
+
+function buildWorkerTimeoutError(modulePath, exportName, timeoutMs) {
+  const error = new Error(
+    `Worker timed out after ${timeoutMs}ms while running ${path.basename(modulePath)}#${exportName}.`
+  );
+  error.code = "ETIMEDOUT";
+  return error;
+}
+
+function runModuleExportInWorker(modulePath, exportName, args = [], options = {}) {
   return new Promise((resolve, reject) => {
+    const resolvedModulePath = path.resolve(modulePath);
+    const timeoutMs = resolveWorkerTimeoutMs(options);
     const worker = new Worker(WORKER_SCRIPT_PATH, {
       workerData: {
-        modulePath: path.resolve(modulePath),
+        modulePath: resolvedModulePath,
         exportName,
         args
       }
     });
 
     let settled = false;
+    let timeoutHandle = null;
     function settle(callback, value) {
       if (settled) {
         return;
       }
       settled = true;
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+        timeoutHandle = null;
+      }
 
       const termination = worker.terminate();
       if (termination && typeof termination.then === "function") {
@@ -54,6 +84,13 @@ function runModuleExportInWorker(modulePath, exportName, args = []) {
       callback(value);
     }
 
+    timeoutHandle = setTimeout(() => {
+      settle(reject, buildWorkerTimeoutError(resolvedModulePath, exportName, timeoutMs));
+    }, timeoutMs);
+    if (typeof timeoutHandle.unref === "function") {
+      timeoutHandle.unref();
+    }
+
     worker.once("message", (message) => {
       if (message && message.ok) {
         settle(resolve, message.result);

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

@@ -0,0 +1,132 @@
+const { registerCommand } = require("./helpers");
+
+/**
+ * @typedef {Object} CliCoreCommandContext
+ * @property {string[]} argv
+ * @property {string} homeDir
+ * @property {string[]} positionalArgs
+ * @property {boolean} continueOnError
+ * @property {(args: string[], name: string) => string | undefined} getOption
+ * @property {string} VERSION
+ * @property {Function} installPlatforms
+ * @property {Function} uninstallPlatforms
+ * @property {Function} getStatus
+ * @property {Function} verifyInstall
+ * @property {Function} validateAssets
+ * @property {Function} runMaintainerReadinessCheck
+ * @property {Function} formatMaintainerReadinessReport
+ * @property {Function} formatStatus
+ * @property {Function} formatVerifyInstallReport
+ * @property {Function} emitCommandOutput
+ * @property {Function} formatTuiHelp
+ * @property {Function} launchTui
+ */
+
+/**
+ * Register platform/bootstrap-adjacent CLI commands plus the TUI entrypoint.
+ *
+ * @param {import("./helpers").CliCommandHandlerMap} handlers
+ * @param {CliCoreCommandContext} context
+ * @returns {void}
+ */
+function registerCoreCommands(handlers, context) {
+  const {
+    argv,
+    homeDir,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    VERSION,
+    installPlatforms,
+    uninstallPlatforms,
+    getStatus,
+    verifyInstall,
+    validateAssets,
+    runMaintainerReadinessCheck,
+    formatMaintainerReadinessReport,
+    formatStatus,
+    formatVerifyInstallReport,
+    emitCommandOutput,
+    formatTuiHelp,
+    launchTui
+  } = context;
+
+  registerCommand(handlers, ["--version", "-v", "version"], async () => {
+    console.log(`Da Vinci v${VERSION}`);
+  });
+
+  registerCommand(handlers, "install", async () => {
+    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}`
+    );
+  });
+
+  registerCommand(handlers, "uninstall", async () => {
+    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}`
+    );
+  });
+
+  registerCommand(handlers, "status", async () => {
+    console.log(formatStatus(getStatus({ homeDir })));
+  });
+
+  registerCommand(handlers, "verify-install", async () => {
+    const platformValue = getOption(argv, "--platform") || "";
+    const result = verifyInstall({
+      homeDir,
+      platforms: platformValue
+    });
+    emitCommandOutput(result, argv, formatVerifyInstallReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "maintainer-readiness", async () => {
+    const platformValue = getOption(argv, "--platform") || "";
+    const repoRoot = getOption(argv, "--project") || process.cwd();
+    const result = runMaintainerReadinessCheck({
+      repoRoot,
+      homeDir,
+      platforms: platformValue
+    });
+    emitCommandOutput(result, argv, formatMaintainerReadinessReport, ["BLOCK"], continueOnError);
+  });
+
+  registerCommand(handlers, "tui", async () => {
+    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"),
+      continueOnError
+    });
+  });
+
+  registerCommand(handlers, "validate-assets", async () => {
+    const result = validateAssets();
+    console.log(`Da Vinci v${result.version} assets are complete (${result.requiredAssets} required files).`);
+  });
+}
+
+module.exports = {
+  registerCoreCommands
+};

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

@@ -0,0 +1,129 @@
+const { registerCommand } = require("./helpers");
+
+/**
+ * @typedef {Object} CliDesignCommandContext
+ * @property {string[]} argv
+ * @property {string} homeDir
+ * @property {string[]} positionalArgs
+ * @property {boolean} continueOnError
+ * @property {(args: string[], name: string) => string | undefined} getOption
+ * @property {(args: string[], name: string, options?: object) => number | undefined} getIntegerOption
+ * @property {Function} syncIconCatalog
+ * @property {Function} formatIconSyncReport
+ * @property {Function} handleIconSearchCommand
+ * @property {Function} readOperations
+ * @property {Function} readLimitedStdin
+ * @property {Function} preflightPencilBatch
+ * @property {Function} formatPencilPreflightReport
+ * @property {Function} emitOrThrowOnStatus
+ * @property {Function} handleSupervisorReviewCommand
+ * @property {Function} saveCurrentDesign
+ * @property {Function} formatSaveCurrentDesignReport
+ * @property {{ BLOCKED: string, UNAVAILABLE: string }} SAVE_STATUS
+ */
+
+/**
+ * Register design-tooling and design-review command handlers.
+ *
+ * @param {import("./helpers").CliCommandHandlerMap} handlers
+ * @param {CliDesignCommandContext} context
+ * @returns {void}
+ */
+function registerDesignCommands(handlers, context) {
+  const {
+    argv,
+    homeDir,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    getIntegerOption,
+    syncIconCatalog,
+    formatIconSyncReport,
+    handleIconSearchCommand,
+    readOperations,
+    readLimitedStdin,
+    preflightPencilBatch,
+    formatPencilPreflightReport,
+    emitOrThrowOnStatus,
+    handleSupervisorReviewCommand,
+    saveCurrentDesign,
+    formatSaveCurrentDesignReport,
+    SAVE_STATUS
+  } = context;
+
+  registerCommand(handlers, "icon-sync", async () => {
+    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));
+  });
+
+  registerCommand(handlers, "icon-search", async () => {
+    await handleIconSearchCommand(argv, homeDir);
+  });
+
+  registerCommand(handlers, "preflight-pencil", async () => {
+    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);
+  });
+
+  registerCommand(handlers, "supervisor-review", async () => {
+    await handleSupervisorReviewCommand(argv);
+  });
+
+  registerCommand(handlers, "save-current-design", async () => {
+    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 output = argv.includes("--json")
+      ? JSON.stringify(result, null, 2)
+      : formatSaveCurrentDesignReport(result);
+
+    if (
+      emitOrThrowOnStatus(
+        result.status,
+        [SAVE_STATUS.BLOCKED, SAVE_STATUS.UNAVAILABLE],
+        output,
+        continueOnError
+      )
+    ) {
+      return;
+    }
+
+    console.log(output);
+  });
+}
+
+module.exports = {
+  registerDesignCommands
+};

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

@@ -0,0 +1,231 @@
+const { registerCommand } = require("./helpers");
+
+/**
+ * @typedef {Object} CliPenCommandContext
+ * @property {string[]} argv
+ * @property {string} homeDir
+ * @property {string[]} positionalArgs
+ * @property {boolean} continueOnError
+ * @property {(args: string[], name: string) => string | undefined} getOption
+ * @property {(args: string[], name: string) => string[]} getCommaSeparatedOptionValues
+ * @property {Function} ensurePenFile
+ * @property {Function} writePenFromPayloadFiles
+ * @property {Function} comparePenSync
+ * @property {Function} comparePenBaselineAlignment
+ * @property {Function} formatPenBaselineAlignmentReport
+ * @property {Function} syncPenSource
+ * @property {Function} snapshotPenFile
+ * @property {Function} handlePencilLockCommand
+ * @property {Function} handlePencilSessionCommand
+ * @property {Function} emitOrThrowOnStatus
+ */
+
+/**
+ * Register `.pen`, Pencil lock, and Pencil session command handlers.
+ *
+ * @param {import("./helpers").CliCommandHandlerMap} handlers
+ * @param {CliPenCommandContext} context
+ * @returns {void}
+ */
+function registerPenCommands(handlers, context) {
+  const {
+    argv,
+    homeDir,
+    positionalArgs,
+    continueOnError,
+    getOption,
+    getCommaSeparatedOptionValues,
+    ensurePenFile,
+    writePenFromPayloadFiles,
+    comparePenSync,
+    comparePenBaselineAlignment,
+    formatPenBaselineAlignmentReport,
+    syncPenSource,
+    snapshotPenFile,
+    handlePencilLockCommand,
+    handlePencilSessionCommand,
+    emitOrThrowOnStatus
+  } = context;
+
+  registerCommand(handlers, "ensure-pen", async () => {
+    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).`);
+    }
+  });
+
+  registerCommand(handlers, "write-pen", async () => {
+    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).`);
+    }
+  });
+
+  registerCommand(handlers, "check-pen-sync", async () => {
+    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."
+      );
+    }
+  });
+
+  registerCommand(handlers, "check-pen-baseline", async () => {
+    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));
+  });
+
+  registerCommand(handlers, "sync-pen-source", async () => {
+    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}`);
+  });
+
+  registerCommand(handlers, "snapshot-pen", async () => {
+    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).`);
+    }
+  });
+
+  registerCommand(handlers, "pencil-lock", async () => {
+    handlePencilLockCommand(argv, homeDir);
+  });
+
+  registerCommand(handlers, "pencil-session", async () => {
+    handlePencilSessionCommand(argv, homeDir);
+  });
+}
+
+module.exports = {
+  registerPenCommands
+};