@xenonbyte/da-vinci-workflow 0.2.1 → 0.2.2

package/tui/catalog.js

@@ -0,0 +1,1190 @@
+const path = require("path");
+
+const STAGES = [
+  {
+    id: "setup",
+    title: {
+      en: "Setup & Tooling",
+      zh: "初始化与工具"
+    },
+    summary: {
+      en: "Install, validate, bootstrap, and inspect the local Da Vinci environment.",
+      zh: "安装、校验、初始化并检查本地 Da Vinci 环境。"
+    }
+  },
+  {
+    id: "routing",
+    title: {
+      en: "Routing & Resume",
+      zh: "选路与续跑"
+    },
+    summary: {
+      en: "Detect the current workflow phase before deciding the next prompt or CLI action.",
+      zh: "在决定下一步提示词或命令前，先判断当前工作流阶段。"
+    }
+  },
+  {
+    id: "planning",
+    title: {
+      en: "Planning & Drift",
+      zh: "规划与漂移检查"
+    },
+    summary: {
+      en: "Lint planning artifacts, generate sidecars, and inspect requirement drift before implementation.",
+      zh: "在实现前校验规划工件、生成 sidecar，并检查需求漂移。"
+    }
+  },
+  {
+    id: "visual",
+    title: {
+      en: "Visual & Review",
+      zh: "视觉与审查"
+    },
+    summary: {
+      en: "Prepare icon catalogs and run design-supervisor review when visual gates matter.",
+      zh: "在视觉门禁重要时准备图标目录并执行 design-supervisor 审查。"
+    }
+  },
+  {
+    id: "pen",
+    title: {
+      en: "Pen Files & Sync",
+      zh: "Pen 文件与同步"
+    },
+    summary: {
+      en: "Seed, write, diff, and sync project-local `.pen` sources.",
+      zh: "初始化、写入、比对并同步项目内 `.pen` 设计源。"
+    }
+  },
+  {
+    id: "pencil",
+    title: {
+      en: "Pencil Session",
+      zh: "Pencil 会话"
+    },
+    summary: {
+      en: "Control lock ownership and live Pencil session lifecycle safely.",
+      zh: "安全管理锁、会话和 live Pencil 生命周期。"
+    }
+  },
+  {
+    id: "verification",
+    title: {
+      en: "Verification & Completion",
+      zh: "验证与完成"
+    },
+    summary: {
+      en: "Verify bindings, implementation coverage, structural alignment, and completion readiness.",
+      zh: "验证 bindings、实现覆盖、结构一致性以及完成就绪度。"
+    }
+  }
+];
+
+function normalizeLanguage(value) {
+  return value === "zh" ? "zh" : "en";
+}
+
+function resolveLocalizedText(record, lang) {
+  if (record == null) {
+    return "";
+  }
+  if (typeof record === "string") {
+    return record;
+  }
+  const normalized = normalizeLanguage(lang);
+  return record[normalized] || record.en || "";
+}
+
+function defaultValue(value, placeholder) {
+  return value ? String(value).trim() : placeholder;
+}
+
+function maybePush(args, flag, value) {
+  const normalized = String(value || "").trim();
+  if (!normalized) {
+    return;
+  }
+  args.push(flag, normalized);
+}
+
+function maybeProject(args, context, options = {}) {
+  const requested = String(context.projectPath || "").trim();
+  if (!requested) {
+    return;
+  }
+  const currentDir = path.resolve(process.cwd());
+  const resolved = path.resolve(requested);
+  if (!options.force && resolved === currentDir) {
+    return;
+  }
+  args.push("--project", requested);
+}
+
+function maybeChange(args, context) {
+  maybePush(args, "--change", context.changeId);
+}
+
+function maybeStrict(args, context, enabled) {
+  if (enabled && context.strict) {
+    args.push("--strict");
+  }
+}
+
+function maybeJson(args, context, enabled) {
+  if (enabled && context.jsonOutput) {
+    args.push("--json");
+  }
+}
+
+function maybeContinueOnError(args, context, enabled) {
+  if (enabled && context.continueOnError) {
+    args.push("--continue-on-error");
+  }
+}
+
+function createCommand(definition) {
+  return {
+    supportsProject: true,
+    supportsChange: false,
+    supportsStrict: false,
+    supportsJson: false,
+    supportsContinueOnError: false,
+    ...definition
+  };
+}
+
+function createParameter(flag, value, description, options = {}) {
+  return {
+    flag,
+    value,
+    description,
+    required: options.required === true
+  };
+}
+
+const COMMON_PARAMETER_HINTS = {
+  project: createParameter("--project", "<path>", {
+    en: "Project root used as the execution cwd when you are not already inside the target repository.",
+    zh: "当你当前不在目标仓库目录里时，用它指定执行时的项目根目录。"
+  }),
+  change: createParameter("--change", "<id>", {
+    en: "Active change slice. Leave it blank only when the CLI can safely infer a single active change.",
+    zh: "当前活跃的 change 切片。只有 CLI 能安全推断唯一 active change 时才建议留空。"
+  }),
+  strict: createParameter("--strict", "", {
+    en: "Upgrade advisory findings into blocking failures where the command supports strict mode.",
+    zh: "在命令支持 strict 时，把 advisory 发现升级为阻断失败。"
+  }),
+  json: createParameter("--json", "", {
+    en: "Emit machine-readable JSON output instead of the default text report.",
+    zh: "输出机器可读的 JSON，而不是默认的文本报告。"
+  }),
+  continueOnError: createParameter("--continue-on-error", "", {
+    en: "Keep running supported checks after the first finding instead of stopping immediately.",
+    zh: "遇到第一个问题后仍继续执行支持的检查，而不是立即停止。"
+  })
+};
+
+const COMMANDS = [
+  createCommand({
+    id: "install",
+    stageId: "setup",
+    title: { en: "install", zh: "install" },
+    summary: {
+      en: "Install prompt and command assets into local Codex, Claude, and Gemini homes.",
+      zh: "把提示词和命令资产安装到本地 Codex、Claude、Gemini 目录。"
+    },
+    details: {
+      en: "Use this when the workflow skill is not installed yet or needs reinstalling for local testing.",
+      zh: "当 workflow skill 还未安装，或需要本地重装测试时使用。"
+    },
+    buildArgs() {
+      return ["install", "--platform", "codex,claude,gemini"];
+    }
+  }),
+  createCommand({
+    id: "uninstall",
+    stageId: "setup",
+    title: { en: "uninstall", zh: "uninstall" },
+    summary: {
+      en: "Remove previously installed Da Vinci prompt and command assets from local homes.",
+      zh: "从本地目录移除已安装的 Da Vinci 提示词和命令资产。"
+    },
+    details: {
+      en: "Use this when validating install drift or resetting the local prompt surfaces.",
+      zh: "当你要验证安装漂移或重置本地提示词面时使用。"
+    },
+    buildArgs() {
+      return ["uninstall", "--platform", "codex,claude,gemini"];
+    }
+  }),
+  createCommand({
+    id: "status",
+    stageId: "setup",
+    title: { en: "status", zh: "status" },
+    summary: {
+      en: "Inspect whether local prompt and command assets are installed and still match the repo.",
+      zh: "检查本地提示词和命令资产是否已安装且仍与仓库一致。"
+    },
+    details: {
+      en: "Useful before debugging a platform-specific prompt issue.",
+      zh: "在排查平台特定提示词问题前很有用。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["status"];
+    }
+  }),
+  createCommand({
+    id: "validate-assets",
+    stageId: "setup",
+    title: { en: "validate-assets", zh: "validate-assets" },
+    summary: {
+      en: "Check that the packaged Da Vinci assets are complete.",
+      zh: "检查打包后的 Da Vinci 资产是否完整。"
+    },
+    details: {
+      en: "Use this before publishing or when pack/install output looks incomplete.",
+      zh: "在发布前或怀疑打包/安装资产不完整时使用。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["validate-assets"];
+    }
+  }),
+  createCommand({
+    id: "bootstrap-project",
+    stageId: "setup",
+    title: { en: "bootstrap-project", zh: "bootstrap-project" },
+    summary: {
+      en: "Create the minimum `.da-vinci/` project spine and optionally seed one change slice.",
+      zh: "创建最小 `.da-vinci/` 项目骨架，并可顺带初始化一个 change 切片。"
+    },
+    details: {
+      en: "Start here when the repository has no usable workflow artifacts yet.",
+      zh: "当仓库里还没有可用工作流工件时，从这里开始。"
+    },
+    supportsChange: true,
+    buildArgs(context) {
+      const args = ["bootstrap-project"];
+      maybeProject(args, context, { force: true });
+      maybeChange(args, context);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "workflow-status",
+    stageId: "routing",
+    title: { en: "workflow-status", zh: "workflow-status" },
+    summary: {
+      en: "Inspect the current stage, blockers, and handoff gates from artifact truth.",
+      zh: "根据工件真相检查当前阶段、阻塞项和交接门禁。"
+    },
+    details: {
+      en: "Run this first whenever you resume a paused project or are unsure which stage is active.",
+      zh: "每次恢复暂停项目，或不确定当前阶段时，先运行它。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    buildArgs(context) {
+      const args = ["workflow-status"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeJson(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "next-step",
+    stageId: "routing",
+    title: { en: "next-step", zh: "next-step" },
+    summary: {
+      en: "Derive the first recommended continuation action from the current workflow state.",
+      zh: "根据当前工作流状态给出第一优先的续跑动作。"
+    },
+    details: {
+      en: "Use it after `workflow-status` to decide whether to keep planning, bind pages, generate tasks, or implement.",
+      zh: "通常在 `workflow-status` 之后运行，用来判断接下来是补规划、做绑定、生成任务还是实现。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    buildArgs(context) {
+      const args = ["next-step"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeJson(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "lint-spec",
+    stageId: "planning",
+    title: { en: "lint-spec", zh: "lint-spec" },
+    summary: {
+      en: "Lint runtime `spec.md` files before implementation planning or code generation.",
+      zh: "在实现规划或代码落地前校验运行时 `spec.md`。"
+    },
+    details: {
+      en: "Use it when spec headings, acceptance quality, or state semantics may still be unstable.",
+      zh: "当 spec 标题结构、验收标准质量或状态语义还不够稳定时使用。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["lint-spec"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "scope-check",
+    stageId: "planning",
+    title: { en: "scope-check", zh: "scope-check" },
+    summary: {
+      en: "Check page/state propagation across proposal, page-map, runtime specs, Pencil design, and tasks.",
+      zh: "检查 proposal、page-map、运行时 spec、Pencil 设计和任务之间的页面/状态传播。"
+    },
+    details: {
+      en: "Use this before implementation when planning artifacts disagree or the active pages are ambiguous.",
+      zh: "当规划工件有分歧，或活跃页面不明确时，在实现前运行。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["scope-check"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "lint-tasks",
+    stageId: "planning",
+    title: { en: "lint-tasks", zh: "lint-tasks" },
+    summary: {
+      en: "Validate task groups, ordering, and verification coverage inside `tasks.md`.",
+      zh: "校验 `tasks.md` 里的任务分组、顺序和验证覆盖。"
+    },
+    details: {
+      en: "Use it after task generation and before build handoff.",
+      zh: "在任务生成后、实现交接前使用。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["lint-tasks"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "lint-bindings",
+    stageId: "planning",
+    title: { en: "lint-bindings", zh: "lint-bindings" },
+    summary: {
+      en: "Validate implementation-to-Pencil mappings before scaffold or verify steps.",
+      zh: "在 scaffold 或 verify 前校验实现到 Pencil 的映射。"
+    },
+    details: {
+      en: "Run this after editing `pencil-bindings.md` or when implementation landing paths changed.",
+      zh: "修改了 `pencil-bindings.md`，或实现落点路径改变后运行。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["lint-bindings"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "generate-sidecars",
+    stageId: "planning",
+    title: { en: "generate-sidecars", zh: "generate-sidecars" },
+    summary: {
+      en: "Write deterministic planning sidecars for spec, tasks, page-map, and bindings.",
+      zh: "为 spec、tasks、page-map 和 bindings 写入确定性的 planning sidecar。"
+    },
+    details: {
+      en: "Use it after planning edits when you need explicit diffable state for continuation.",
+      zh: "当规划工件改动后需要显式、可比对的续跑状态时使用。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["generate-sidecars"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "diff-spec",
+    stageId: "planning",
+    title: { en: "diff-spec", zh: "diff-spec" },
+    summary: {
+      en: "Compare current planning artifacts with saved sidecars to inspect drift safely.",
+      zh: "把当前规划工件与已保存的 sidecar 做比对，安全检查漂移。"
+    },
+    details: {
+      en: "Useful after spec, task, or bindings edits when a paused workflow needs fresh route decisions.",
+      zh: "当 spec、tasks 或 bindings 发生变化，而暂停中的工作流需要重新判断下一步时很有用。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["diff-spec"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "scaffold",
+    stageId: "planning",
+    title: { en: "scaffold", zh: "scaffold" },
+    summary: {
+      en: "Generate a constrained TODO skeleton from `pencil-bindings.md` mappings.",
+      zh: "根据 `pencil-bindings.md` 映射生成受约束的 TODO 骨架。"
+    },
+    details: {
+      en: "This is an MVP skeleton only, not autonomous production code generation.",
+      zh: "它只是 MVP 级骨架，不是自动生成生产代码。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["scaffold"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "icon-sync",
+    stageId: "visual",
+    title: { en: "icon-sync", zh: "icon-sync" },
+    summary: {
+      en: "Fetch official icon catalogs for supported libraries into the local cache.",
+      zh: "把支持库的官方图标目录拉到本地缓存。"
+    },
+    details: {
+      en: "Run this when the design depends on newer icon names than the local cache already knows.",
+      zh: "当设计依赖本地图标缓存还不认识的新图标名时运行。"
+    },
+    supportsProject: false,
+    supportsStrict: true,
+    buildArgs(context) {
+      const args = ["icon-sync"];
+      maybeStrict(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "icon-search",
+    stageId: "visual",
+    title: { en: "icon-search", zh: "icon-search" },
+    summary: {
+      en: "Search synced icon catalogs for buildable icon names before Pencil work.",
+      zh: "在 Pencil 工作前搜索已同步图标目录中的可落地图标名。"
+    },
+    details: {
+      en: "The preview keeps a query placeholder so you can fill it before running.",
+      zh: "预览里会保留查询占位符，运行前填入关键词即可。"
+    },
+    supportsProject: false,
+    supportsJson: true,
+    buildArgs(context) {
+      const args = ["icon-search", "--query", "<query>"];
+      maybeJson(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "supervisor-review",
+    stageId: "visual",
+    title: { en: "supervisor-review", zh: "supervisor-review" },
+    summary: {
+      en: "Run or record Design-Supervisor review for the active change slice.",
+      zh: "为当前 change 切片执行或记录 Design-Supervisor 审查。"
+    },
+    details: {
+      en: "Use it after anchor screenshots are ready and reviewer-backed style signoff matters.",
+      zh: "当 anchor 截图已准备好，且需要 reviewer 风格签收时使用。"
+    },
+    supportsChange: true,
+    supportsJson: true,
+    buildArgs(context) {
+      const args = ["supervisor-review"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      if (!String(context.changeId || "").trim()) {
+        args.push("--change", "<change-id>");
+      }
+      maybeJson(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "preflight-pencil",
+    stageId: "pen",
+    title: { en: "preflight-pencil", zh: "preflight-pencil" },
+    summary: {
+      en: "Statically check a Pencil `batch_design` payload before sending it to MCP.",
+      zh: "在发送给 MCP 前静态校验 Pencil `batch_design` 载荷。"
+    },
+    details: {
+      en: "Use it when a non-trivial Pencil operation list may fail due to syntax or schema drift.",
+      zh: "当较复杂的 Pencil 操作列表可能因为语法或 schema 漂移失败时使用。"
+    },
+    buildArgs() {
+      return ["preflight-pencil", "--ops-file", "<ops-file>"];
+    }
+  }),
+  createCommand({
+    id: "ensure-pen",
+    stageId: "pen",
+    title: { en: "ensure-pen", zh: "ensure-pen" },
+    summary: {
+      en: "Seed or verify a project-local `.pen` file before live editing begins.",
+      zh: "在 live 编辑开始前初始化或校验项目内 `.pen` 文件。"
+    },
+    details: {
+      en: "Use it to make sure the workflow-owned `.pen` exists before Pencil work starts.",
+      zh: "用它确保工作流管理的 `.pen` 在开始 Pencil 工作前已经存在。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["ensure-pen", "--output", "<pen-output-path>"];
+    }
+  }),
+  createCommand({
+    id: "write-pen",
+    stageId: "pen",
+    title: { en: "write-pen", zh: "write-pen" },
+    summary: {
+      en: "Write a `.pen` file from node and variable payloads captured from MCP.",
+      zh: "根据 MCP 抓取到的节点和变量载荷写入 `.pen` 文件。"
+    },
+    details: {
+      en: "Useful when persisting a live Pencil snapshot back into the project-owned source.",
+      zh: "当你要把 live Pencil 快照持久化回项目自有设计源时很有用。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["write-pen", "--output", "<pen-output-path>", "--nodes-file", "<nodes-json>"];
+    }
+  }),
+  createCommand({
+    id: "check-pen-sync",
+    stageId: "pen",
+    title: { en: "check-pen-sync", zh: "check-pen-sync" },
+    summary: {
+      en: "Compare the current live payload with a persisted project-local `.pen` file.",
+      zh: "比较当前 live 载荷与已持久化的项目内 `.pen` 文件。"
+    },
+    details: {
+      en: "Run this before closing a session when you need explicit sync evidence.",
+      zh: "当你在结束会话前需要显式同步证据时运行。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["check-pen-sync", "--pen", "<pen-path>", "--nodes-file", "<nodes-json>"];
+    }
+  }),
+  createCommand({
+    id: "check-pen-baseline",
+    stageId: "pen",
+    title: { en: "check-pen-baseline", zh: "check-pen-baseline" },
+    summary: {
+      en: "Compare the project-local `.pen` file with one or more external baseline sources.",
+      zh: "把项目内 `.pen` 与一个或多个外部 baseline 源做比对。"
+    },
+    details: {
+      en: "Use it before a new write phase when backups or mirrored sources may have drifted.",
+      zh: "当备份或镜像源可能漂移时，在新的写阶段前运行。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["check-pen-baseline", "--pen", "<pen-path>", "--baseline", "<baseline-path>"];
+    }
+  }),
+  createCommand({
+    id: "sync-pen-source",
+    stageId: "pen",
+    title: { en: "sync-pen-source", zh: "sync-pen-source" },
+    summary: {
+      en: "Copy the selected latest `.pen` source back into the project baseline path.",
+      zh: "把选定的最新 `.pen` 源同步回项目 baseline 路径。"
+    },
+    details: {
+      en: "Use it after manually choosing the winner between divergent `.pen` sources.",
+      zh: "当你在多个分歧 `.pen` 源之间手动选定胜出版本后使用。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["sync-pen-source", "--from", "<source-pen>", "--to", "<target-pen>"];
+    }
+  }),
+  createCommand({
+    id: "snapshot-pen",
+    stageId: "pen",
+    title: { en: "snapshot-pen", zh: "snapshot-pen" },
+    summary: {
+      en: "Copy a `.pen` file to a new location while recording snapshot metadata.",
+      zh: "把 `.pen` 文件复制到新位置，并记录快照元数据。"
+    },
+    details: {
+      en: "This is a disk-to-disk utility rather than a live-edit persistence step.",
+      zh: "它是磁盘到磁盘的工具，不是 live 编辑持久化步骤。"
+    },
+    supportsProject: false,
+    buildArgs() {
+      return ["snapshot-pen", "--input", "<source-pen>", "--output", "<snapshot-pen>"];
+    }
+  }),
+  createCommand({
+    id: "pencil-lock-acquire",
+    stageId: "pencil",
+    title: { en: "pencil-lock acquire", zh: "pencil-lock acquire" },
+    summary: {
+      en: "Acquire the global Pencil lock for the active project before write operations.",
+      zh: "在执行写操作前为当前项目获取全局 Pencil 锁。"
+    },
+    details: {
+      en: "Use it when orchestrating Pencil writes manually or outside `pencil-session begin`.",
+      zh: "当你手动编排 Pencil 写操作，或不通过 `pencil-session begin` 时使用。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-lock", "acquire"];
+      maybeProject(args, context, { force: true });
+      return args;
+    }
+  }),
+  createCommand({
+    id: "pencil-lock-release",
+    stageId: "pencil",
+    title: { en: "pencil-lock release", zh: "pencil-lock release" },
+    summary: {
+      en: "Release the global Pencil lock for the active project.",
+      zh: "释放当前项目持有的全局 Pencil 锁。"
+    },
+    details: {
+      en: "Use it after emergency recovery or when you managed lock ownership manually.",
+      zh: "在应急恢复后，或你手动管理锁时使用。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-lock", "release"];
+      maybeProject(args, context, { force: true });
+      return args;
+    }
+  }),
+  createCommand({
+    id: "pencil-lock-status",
+    stageId: "pencil",
+    title: { en: "pencil-lock status", zh: "pencil-lock status" },
+    summary: {
+      en: "Inspect current global Pencil lock ownership.",
+      zh: "检查当前全局 Pencil 锁的持有状态。"
+    },
+    details: {
+      en: "Run it when another workflow appears to be holding Pencil write access.",
+      zh: "当你怀疑别的工作流占用了 Pencil 写权限时运行。"
+    },
+    buildArgs() {
+      return ["pencil-lock", "status"];
+    }
+  }),
+  createCommand({
+    id: "pencil-session-begin",
+    stageId: "pencil",
+    title: { en: "pencil-session begin", zh: "pencil-session begin" },
+    summary: {
+      en: "Begin a workflow-owned Pencil session on the registered project-local `.pen` source.",
+      zh: "在已登记的项目内 `.pen` 源上开始工作流管理的 Pencil 会话。"
+    },
+    details: {
+      en: "Use it before the first live write in a design phase.",
+      zh: "在设计阶段首次 live 写入前使用。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-session", "begin"];
+      maybeProject(args, context, { force: true });
+      args.push("--pen", "<pen-path>");
+      return args;
+    }
+  }),
+  createCommand({
+    id: "pencil-session-persist",
+    stageId: "pencil",
+    title: { en: "pencil-session persist", zh: "pencil-session persist" },
+    summary: {
+      en: "Persist the current live Pencil payload back into the workflow-owned `.pen` source.",
+      zh: "把当前 live Pencil 载荷持久化回工作流管理的 `.pen` 源。"
+    },
+    details: {
+      en: "Use it after material design edits during an open session.",
+      zh: "在打开的会话中完成实质性设计修改后使用。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-session", "persist"];
+      maybeProject(args, context, { force: true });
+      args.push("--pen", "<pen-path>", "--nodes-file", "<nodes-json>");
+      return args;
+    }
+  }),
+  createCommand({
+    id: "pencil-session-end",
+    stageId: "pencil",
+    title: { en: "pencil-session end", zh: "pencil-session end" },
+    summary: {
+      en: "End the active Pencil session after final sync verification.",
+      zh: "在完成最终同步校验后结束当前 Pencil 会话。"
+    },
+    details: {
+      en: "Use it only after the final live snapshot has been persisted or explicitly force-close if recovery is needed.",
+      zh: "应在最终 live 快照已持久化后使用；只有需要恢复时才显式强制关闭。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-session", "end"];
+      maybeProject(args, context, { force: true });
+      args.push("--pen", "<pen-path>", "--nodes-file", "<nodes-json>");
+      return args;
+    }
+  }),
+  createCommand({
+    id: "pencil-session-status",
+    stageId: "pencil",
+    title: { en: "pencil-session status", zh: "pencil-session status" },
+    summary: {
+      en: "Inspect the active project Pencil session and sync metadata.",
+      zh: "检查当前项目的 Pencil 会话与同步元数据。"
+    },
+    details: {
+      en: "Run it before resuming design work when you are unsure whether the previous session ended cleanly.",
+      zh: "当你不确定上一次会话是否正常结束时，在恢复设计工作前运行。"
+    },
+    buildArgs(context) {
+      const args = ["pencil-session", "status"];
+      maybeProject(args, context, { force: true });
+      return args;
+    }
+  }),
+  createCommand({
+    id: "verify-bindings",
+    stageId: "verification",
+    title: { en: "verify-bindings", zh: "verify-bindings" },
+    summary: {
+      en: "Verify that implementation routes are still traceable to Pencil bindings.",
+      zh: "验证实现路由仍然能追溯到 Pencil bindings。"
+    },
+    details: {
+      en: "Run it before terminal claims or after bindings / routing edits.",
+      zh: "在终态声明前，或 bindings / 路由改动后运行。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["verify-bindings"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "verify-implementation",
+    stageId: "verification",
+    title: { en: "verify-implementation", zh: "verify-implementation" },
+    summary: {
+      en: "Check whether real implementation files cover the active requirement and task surfaces.",
+      zh: "检查真实实现文件是否覆盖当前需求与任务面。"
+    },
+    details: {
+      en: "Use it after code changes to validate that test files or fixtures are not being mistaken for the implementation.",
+      zh: "在代码修改后运行，确认不会把测试文件或 fixture 误当成真实实现。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["verify-implementation"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "verify-structure",
+    stageId: "verification",
+    title: { en: "verify-structure", zh: "verify-structure" },
+    summary: {
+      en: "Check structural alignment between bindings and implementation markup.",
+      zh: "检查 bindings 与实现结构之间的一致性。"
+    },
+    details: {
+      en: "Useful after markup-heavy changes or when you need heuristic fallback visibility.",
+      zh: "在大量结构变动后，或你需要看 heuristic fallback 情况时很有用。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["verify-structure"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "verify-coverage",
+    stageId: "verification",
+    title: { en: "verify-coverage", zh: "verify-coverage" },
+    summary: {
+      en: "Aggregate requirement, design, bindings, implementation, and test evidence into one signal.",
+      zh: "把需求、设计、bindings、实现和测试证据聚合成一个总信号。"
+    },
+    details: {
+      en: "Use it before completion audit or terminal status claims.",
+      zh: "在 completion audit 或终态声明前使用。"
+    },
+    supportsChange: true,
+    supportsStrict: true,
+    supportsJson: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["verify-coverage"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeStrict(args, context, true);
+      maybeJson(args, context, true);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  }),
+  createCommand({
+    id: "audit",
+    stageId: "verification",
+    title: { en: "audit", zh: "audit" },
+    summary: {
+      en: "Run integrity or completion audit once the workflow is ready for that gate.",
+      zh: "在工作流准备好后执行 integrity 或 completion audit。"
+    },
+    details: {
+      en: "The preview defaults to integrity mode; edit it to `completion` before terminal completion claims.",
+      zh: "预览默认是 integrity 模式；在终态完成声明前，把它改成 `completion`。"
+    },
+    supportsChange: true,
+    supportsContinueOnError: true,
+    buildArgs(context) {
+      const args = ["audit", "--mode", "integrity"];
+      maybeProject(args, context);
+      maybeChange(args, context);
+      maybeContinueOnError(args, context, true);
+      return args;
+    }
+  })
+];
+
+const COMMAND_PARAMETER_HINTS = {
+  install: [
+    createParameter("--platform", "codex,claude,gemini", {
+      en: "Fixed in the TUI to install assets for all supported local prompt surfaces.",
+      zh: "TUI 里固定为所有支持的平台一起安装资产。"
+    })
+  ],
+  uninstall: [
+    createParameter("--platform", "codex,claude,gemini", {
+      en: "Fixed in the TUI to remove assets from every supported local prompt surface.",
+      zh: "TUI 里固定为从所有支持的平台一起移除资产。"
+    })
+  ],
+  "icon-search": [
+    createParameter("--query", "<query>", {
+      en: "Keyword or phrase to search inside the synced icon catalogs.",
+      zh: "用于在已同步图标目录里搜索的关键词或短语。"
+    }, { required: true })
+  ],
+  "preflight-pencil": [
+    createParameter("--ops-file", "<ops-file>", {
+      en: "Path to the Pencil operations file that should be statically checked before MCP submission.",
+      zh: "在提交给 MCP 前要做静态校验的 Pencil 操作文件路径。"
+    }, { required: true })
+  ],
+  "ensure-pen": [
+    createParameter("--output", "<pen-output-path>", {
+      en: "Destination path for the workflow-owned `.pen` source that should exist locally.",
+      zh: "工作流管理的 `.pen` 设计源在本地应写入或校验的目标路径。"
+    }, { required: true })
+  ],
+  "write-pen": [
+    createParameter("--output", "<pen-output-path>", {
+      en: "Destination `.pen` file path to write from the captured MCP payload.",
+      zh: "把 MCP 抓取载荷写成 `.pen` 文件时的输出路径。"
+    }, { required: true }),
+    createParameter("--nodes-file", "<nodes-json>", {
+      en: "Path to the captured nodes JSON payload exported from Pencil MCP.",
+      zh: "从 Pencil MCP 导出的节点 JSON 载荷路径。"
+    }, { required: true })
+  ],
+  "check-pen-sync": [
+    createParameter("--pen", "<pen-path>", {
+      en: "Project-local `.pen` file to compare against the current live payload.",
+      zh: "要与当前 live 载荷做比对的项目内 `.pen` 文件。"
+    }, { required: true }),
+    createParameter("--nodes-file", "<nodes-json>", {
+      en: "Path to the live nodes JSON payload captured from the current session.",
+      zh: "当前会话抓取到的 live nodes JSON 载荷路径。"
+    }, { required: true })
+  ],
+  "check-pen-baseline": [
+    createParameter("--pen", "<pen-path>", {
+      en: "Project-local `.pen` file that acts as the workflow-owned source of truth.",
+      zh: "作为工作流自有真相源的项目内 `.pen` 文件。"
+    }, { required: true }),
+    createParameter("--baseline", "<baseline-path>", {
+      en: "External baseline `.pen` path that should be compared with the project-local source.",
+      zh: "要与项目内设计源做比较的外部 baseline `.pen` 路径。"
+    }, { required: true })
+  ],
+  "sync-pen-source": [
+    createParameter("--from", "<source-pen>", {
+      en: "Source `.pen` file that won the manual comparison and should be copied forward.",
+      zh: "手动比对后选中的胜出 `.pen` 源路径。"
+    }, { required: true }),
+    createParameter("--to", "<target-pen>", {
+      en: "Destination `.pen` path that should receive the chosen source file.",
+      zh: "接收最终胜出设计源的目标 `.pen` 路径。"
+    }, { required: true })
+  ],
+  "snapshot-pen": [
+    createParameter("--input", "<source-pen>", {
+      en: "Source `.pen` file to snapshot.",
+      zh: "要制作快照的源 `.pen` 文件。"
+    }, { required: true }),
+    createParameter("--output", "<snapshot-pen>", {
+      en: "Destination path for the recorded `.pen` snapshot.",
+      zh: "记录 `.pen` 快照的输出路径。"
+    }, { required: true })
+  ],
+  "pencil-session-begin": [
+    createParameter("--pen", "<pen-path>", {
+      en: "Registered project-local `.pen` source that the live Pencil session should open against.",
+      zh: "live Pencil 会话要基于其开启的已登记项目内 `.pen` 设计源。"
+    }, { required: true })
+  ],
+  "pencil-session-persist": [
+    createParameter("--pen", "<pen-path>", {
+      en: "Registered project-local `.pen` source that should receive the persisted live changes.",
+      zh: "接收 live 设计改动持久化结果的已登记项目内 `.pen` 设计源。"
+    }, { required: true }),
+    createParameter("--nodes-file", "<nodes-json>", {
+      en: "Captured live nodes JSON payload that should be written back into the `.pen` source.",
+      zh: "需要写回 `.pen` 设计源的 live nodes JSON 载荷。"
+    }, { required: true })
+  ],
+  "pencil-session-end": [
+    createParameter("--pen", "<pen-path>", {
+      en: "Registered project-local `.pen` source associated with the session being closed.",
+      zh: "当前要关闭会话所关联的已登记项目内 `.pen` 设计源。"
+    }, { required: true }),
+    createParameter("--nodes-file", "<nodes-json>", {
+      en: "Final live nodes JSON payload used for the closing sync verification.",
+      zh: "结束前做同步校验所使用的最终 live nodes JSON 载荷。"
+    }, { required: true })
+  ],
+  audit: [
+    createParameter("--mode", "integrity|completion", {
+      en: "Audit mode. The preview defaults to `integrity`; switch to `completion` before final completion claims.",
+      zh: "审查模式。预览默认使用 `integrity`；在做最终完成声明前改成 `completion`。"
+    })
+  ]
+};
+
+function getCommandParameterItems(command) {
+  if (!command) {
+    return [];
+  }
+  const items = [];
+  if (command.supportsProject) {
+    items.push(COMMON_PARAMETER_HINTS.project);
+  }
+  if (command.supportsChange) {
+    items.push(COMMON_PARAMETER_HINTS.change);
+  }
+  if (command.supportsStrict) {
+    items.push(COMMON_PARAMETER_HINTS.strict);
+  }
+  if (command.supportsJson) {
+    items.push(COMMON_PARAMETER_HINTS.json);
+  }
+  if (command.supportsContinueOnError) {
+    items.push(COMMON_PARAMETER_HINTS.continueOnError);
+  }
+  for (const item of COMMAND_PARAMETER_HINTS[command.id] || []) {
+    items.push(item);
+  }
+
+  const deduped = [];
+  const seen = new Set();
+  for (const item of items) {
+    const key = `${item.flag} ${item.value || ""}`.trim();
+    if (seen.has(key)) {
+      continue;
+    }
+    seen.add(key);
+    deduped.push({ ...item });
+  }
+  return deduped;
+}
+
+function getStageById(stageId) {
+  return STAGES.find((stage) => stage.id === stageId) || null;
+}
+
+function getCommandById(commandId) {
+  return COMMANDS.find((command) => command.id === commandId) || null;
+}
+
+function buildCommandArgs(command, context = {}) {
+  if (!command || typeof command.buildArgs !== "function") {
+    throw new Error("Command definition is missing a buildArgs function.");
+  }
+  return command.buildArgs(context);
+}
+
+function shellQuote(value) {
+  const text = String(value || "");
+  if (/^[A-Za-z0-9_./:@=+-]+$/.test(text)) {
+    return text;
+  }
+  return `'${text.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function buildDisplayCommand(command, context = {}) {
+  const args = buildCommandArgs(command, context);
+  return ["da-vinci", ...args].map(shellQuote).join(" ");
+}
+
+function hasPlaceholders(args) {
+  return (args || []).some((token) => /^<.+>$/.test(String(token || "").trim()));
+}
+
+function getDefaultLanguage(localeValue) {
+  const locale = String(localeValue || process.env.LANG || "").toLowerCase();
+  if (locale.startsWith("zh")) {
+    return "zh";
+  }
+  return "en";
+}
+
+function tokenizeCommandLine(input) {
+  const source = String(input || "").trim();
+  const tokens = [];
+  let current = "";
+  let quote = "";
+  let escaping = false;
+
+  for (let index = 0; index < source.length; index += 1) {
+    const char = source[index];
+    if (escaping) {
+      current += char;
+      escaping = false;
+      continue;
+    }
+    if (char === "\\") {
+      escaping = true;
+      continue;
+    }
+    if (quote) {
+      if (char === quote) {
+        quote = "";
+      } else {
+        current += char;
+      }
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+    current += char;
+  }
+
+  if (escaping) {
+    current += "\\";
+  }
+  if (quote) {
+    throw new Error("Unclosed quote in command preview.");
+  }
+  if (current) {
+    tokens.push(current);
+  }
+  return tokens;
+}
+
+module.exports = {
+  STAGES,
+  COMMANDS,
+  buildCommandArgs,
+  buildDisplayCommand,
+  getCommandParameterItems,
+  getCommandById,
+  getDefaultLanguage,
+  getStageById,
+  hasPlaceholders,
+  normalizeLanguage,
+  resolveLocalizedText,
+  tokenizeCommandLine
+};