@peterxiaoyang/superspec 0.1.0 → 0.1.1

package/dist/src/init_cli.d.ts

@@ -1,2 +1,25 @@
+import { runCommand } from "./core.ts";
+import { type InstallScope } from "./install_engine.ts";
+type InitArgs = {
+    path: string;
+    codexHome: string;
+    mode: "install" | "update" | "uninstall";
+    scope: InstallScope | null;
+    dryRun: boolean;
+    force: boolean;
+};
+export declare function maybe_install_missing_openspec(opts: {
+    cwd: string;
+    scope: InstallScope;
+    mode: InitArgs["mode"];
+    interactive?: boolean;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+    confirm?: (question: string) => Promise<boolean>;
+    run?: typeof runCommand;
+    writeStderr?: (text: string) => void;
+}): Promise<"not-needed" | "installed" | "skipped" | "failed">;
 export declare function main_init(argv?: string[]): number;
 export declare function main_init_async(argv?: string[]): Promise<number>;
+export {};

package/dist/src/init_cli.js

@@ -1,14 +1,15 @@
-import { block, GuardError, printDecision, reason } from "./core.js";
-import { project_init } from "./project_init.js";
+import { block, commandExists, GuardError, printDecision, reason, runCommand } from "./core.js";
+import { project_init, recommended_openspec_install_plan } from "./project_init.js";
 import { install_workflow, uninstall_workflow, update_workflow } from "./install_engine.js";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { system_failure_zh } from "./i18n.js";
 function usage() {
     return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    return `${usage()}\noptional arguments:\n  -h, --help             show this help message and exit\n  --scope {project,user} install into this project's .codex directory or into the Codex user home (default: project)\n  --project              shortcut for --scope project\n  --user                 shortcut for --scope user\n  --global               compatibility alias for --user\n  --path PATH            project root for --scope project (default: current directory)\n  --codex-home PATH      Codex user home for --scope user (default: $CODEX_HOME or ~/.codex)\n  --create               accepted for compatibility; init creates missing surfaces by default\n  --update               manifest-driven update of managed SuperSpec surfaces (user-modified files kept, new version written to *.new)\n  --uninstall            manifest-driven removal of managed SuperSpec surfaces (.superspec data and preexisting/user-modified files are kept)\n  --dry-run              with --uninstall: print what would be removed without touching files\n  --force                with install: overwrite pre-existing different files (backs up *.bak)\n`;
+    return `${usage()}\n可选参数：\n  -h, --help             显示帮助并退出\n  --scope {project,user} 安装到当前项目的 .codex 目录，或安装到用户级 Codex 目录（默认：project）\n  --project              等价于 --scope project\n  --user                 等价于 --scope user\n  --global               兼容别名，等价于 --user\n  --path PATH            --scope project 时使用的项目根目录（默认：当前目录）\n  --codex-home PATH      --scope user 时使用的 Codex 用户目录（默认：$CODEX_HOME 或 ~/.codex）\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新受管 SuperSpec 内容；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载受管 SuperSpec 内容；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
 }
 function parse_init_argv(argv) {
     const getValue = (flag) => {
@@ -17,19 +18,19 @@ function parse_init_argv(argv) {
             return undefined;
         const value = argv[idx + 1];
         if (value === undefined || value.startsWith("--"))
-            throw new GuardError(`${flag} requires a value`);
+            throw new GuardError(`${flag} 缺少取值`);
         return value;
     };
     const update = argv.includes("--update");
     const uninstall = argv.includes("--uninstall");
     if (update && uninstall)
-        throw new GuardError("--update and --uninstall are mutually exclusive");
+        throw new GuardError("--update 与 --uninstall 不能同时使用");
     const scopeFlag = getValue("--scope");
     if (scopeFlag !== undefined && !["project", "user", "global"].includes(scopeFlag))
-        throw new GuardError("--scope must be project or user");
+        throw new GuardError("--scope 只能是 project 或 user");
     const userShortcut = argv.includes("--user") || argv.includes("--global");
     if (userShortcut && argv.includes("--project"))
-        throw new GuardError("--user/--global and --project are mutually exclusive");
+        throw new GuardError("--user/--global 与 --project 不能同时使用");
     let scope = scopeFlag === "global" ? "user" : scopeFlag ?? null;
     if (userShortcut)
         scope = "user";
@@ -47,6 +48,14 @@ function parse_init_argv(argv) {
 function joinHomeCodex() {
     return `${homedir()}/.codex`;
 }
+function commandFailure(proc) {
+    const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    if (output)
+        return system_failure_zh(output, `安装命令执行失败（退出状态码 ${proc.status ?? "未知"}）。`);
+    if (proc.status !== null)
+        return `安装命令执行失败（退出状态码 ${proc.status}）。`;
+    return "安装命令执行失败，请查看终端日志后重试。";
+}
 function engineDecision(gate, projectRoot, result, nextActions) {
     if (result.problems.length > 0) {
         const decision = block("project", gate, result.problems.map((item) => reason(`${gate}_failed`, item)));
@@ -68,12 +77,12 @@ async function promptInstallScope() {
     const rl = createInterface({ input: process.stdin, output: process.stderr });
     try {
         for (;;) {
-            const answer = (await rl.question("Install SuperSpec Codex surfaces to project or user? [project] ")).trim().toLowerCase();
-            if (answer === "" || answer === "project" || answer === "p" || answer === "1")
+            const answer = (await rl.question("请选择安装范围：project 还是 user？[project] ")).trim().toLowerCase();
+            if (answer === "" || answer === "project" || answer === "p" || answer === "1" || answer === "项目")
                 return "project";
-            if (answer === "user" || answer === "u" || answer === "2" || answer === "global" || answer === "g")
+            if (answer === "user" || answer === "u" || answer === "2" || answer === "global" || answer === "g" || answer === "用户")
                 return "user";
-            process.stderr.write("Please answer project or user.\n");
+            process.stderr.write("请输入 project 或 user。\n");
         }
     }
     finally {
@@ -83,6 +92,56 @@ async function promptInstallScope() {
 function canPrompt() {
     return Boolean(process.stdin.isTTY && process.stderr.isTTY);
 }
+async function promptYesNo(question, defaultYes = true) {
+    const rl = createInterface({ input: process.stdin, output: process.stderr });
+    const suffix = defaultYes ? "[Y/n]" : "[y/N]";
+    try {
+        for (;;) {
+            const answer = (await rl.question(`${question} ${suffix} `)).trim().toLowerCase();
+            if (answer === "")
+                return defaultYes;
+            if (["y", "yes", "是", "好", "确认"].includes(answer))
+                return true;
+            if (["n", "no", "否", "不", "取消"].includes(answer))
+                return false;
+            process.stderr.write("请输入 y / n，或输入 是 / 否。\n");
+        }
+    }
+    finally {
+        rl.close();
+    }
+}
+export async function maybe_install_missing_openspec(opts) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    if (opts.scope !== "project" || opts.mode !== "install")
+        return "not-needed";
+    if (commandExistsFn("openspec", { cwd: opts.cwd }))
+        return "not-needed";
+    if (!(opts.interactive ?? canPrompt()))
+        return "skipped";
+    const plan = recommended_openspec_install_plan({ cwd: opts.cwd, commandExistsFn });
+    if (plan === null)
+        return "skipped";
+    const confirm = opts.confirm ?? ((question) => promptYesNo(question));
+    const accepted = await confirm(`未检测到 openspec CLI。是否现在尝试自动安装？\n将执行：${plan.rendered}`);
+    if (!accepted)
+        return "skipped";
+    const writeStderr = opts.writeStderr ?? ((text) => {
+        process.stderr.write(text);
+    });
+    writeStderr(`正在安装 OpenSpec CLI：${plan.rendered}\n`);
+    const proc = (opts.run ?? runCommand)(plan.cmd, plan.args, { cwd: opts.cwd, timeout: 300_000 });
+    if (proc.error || proc.status !== 0) {
+        writeStderr(`自动安装 OpenSpec CLI 失败：${commandFailure(proc)}\n`);
+        return "failed";
+    }
+    if (!commandExistsFn("openspec", { cwd: opts.cwd })) {
+        writeStderr("安装命令已完成，但当前 PATH 里仍未检测到 `openspec`。请重新打开终端或确认全局 bin 已在 PATH 中，然后重新运行 superspec init。\n");
+        return "failed";
+    }
+    writeStderr("OpenSpec CLI 安装完成，继续执行 superspec init。\n");
+    return "installed";
+}
 function run_init(args, scope) {
     const targetRoot = scope === "user" ? args.codexHome : args.path;
     const gatePrefix = scope === "user" ? "user" : "project";
@@ -107,7 +166,7 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary);
+    printDecision(summary, { command: "init" });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
@@ -122,7 +181,7 @@ export function main_init(argv = process.argv.slice(2)) {
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]));
+        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
         return 2;
     }
 }
@@ -134,12 +193,13 @@ export async function main_init_async(argv = process.argv.slice(2)) {
         }
         const args = parse_init_argv(argv);
         const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
+        await maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
         return run_init(args, scope);
     }
     catch (err) {
         const change = "project";
         const errReason = err instanceof GuardError ? reason("guard_error", err.message) : reason("guard_internal_error", `${err.name}: ${err.message}`);
-        printDecision(block(change, "guard_error", [errReason]));
+        printDecision(block(change, "guard_error", [errReason]), { command: "init" });
         return 2;
     }
 }

package/dist/src/project_init.d.ts

@@ -1,4 +1,24 @@
 import { type JsonMap } from "./core.ts";
+export declare const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
+export declare const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
+export type OpenspecInstallPlan = {
+    manager: "npm" | "pnpm" | "yarn" | "bun";
+    cmd: string;
+    args: string[];
+    rendered: string;
+};
+export declare function recommended_openspec_install_plan(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): OpenspecInstallPlan | null;
+export declare function missing_openspec_cli_message(opts?: {
+    cwd?: string;
+    commandExistsFn?: (cmd: string, meta?: {
+        cwd?: string;
+    }) => boolean;
+}): string;
 export declare function project_init(repoRootRaw?: string, opts?: {
     force?: boolean;
 }): JsonMap;

package/dist/src/project_init.js

@@ -2,15 +2,44 @@ import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "no
 import { join, resolve } from "node:path";
 import { REQUIRED_SUPERSPEC_AGENT_ROLES, REQUIRED_OPENSPEC_CODEX_SKILLS, block, reason, read_agent_toml_name, read_skill_frontmatter_name, commandExists, runCommand, } from "./core.js";
 import { install_workflow } from "./install_engine.js";
+import { system_failure_zh } from "./i18n.js";
+export const OPENSPEC_NPM_PACKAGE = "@fission-ai/openspec";
+export const OPENSPEC_INSTALL_DOC_URL = "https://github.com/Fission-AI/OpenSpec#readme";
 const ROLE_DESCRIPTIONS = {
-    architect: "System design, boundaries, interfaces, and long-horizon tradeoffs",
-    critic: "Critical review of plans, evidence, assumptions, and scope drift",
-    "test-engineer": "Test strategy, coverage, and RED/GREEN evidence review",
-    "code-reviewer": "Code/spec/security review lane for the code-review workflow",
-    verifier: "Final completion evidence and verification review",
+    architect: "系统设计、边界、接口与长期取舍",
+    critic: "对计划、证据、假设与范围漂移做对抗审查",
+    "test-engineer": "测试策略、覆盖率与 RED/GREEN 证据审查",
+    "code-reviewer": "代码 / 规格 / 安全审查",
+    verifier: "最终完成证据与验证审查",
 };
 function commandFailure(proc) {
-    return (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    return system_failure_zh((proc.error?.message ?? (proc.stderr || proc.stdout)).trim(), proc.status !== null && proc.status !== undefined ? `命令执行失败（退出状态码 ${proc.status}）。` : "命令执行失败，请查看终端日志后重试。");
+}
+function renderCommand(cmd, args) {
+    return [cmd, ...args].join(" ");
+}
+export function recommended_openspec_install_plan(opts = {}) {
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const versionedPackage = `${OPENSPEC_NPM_PACKAGE}@latest`;
+    const candidates = [
+        { manager: "npm", cmd: "npm", args: ["install", "-g", versionedPackage] },
+        { manager: "pnpm", cmd: "pnpm", args: ["add", "-g", versionedPackage] },
+        { manager: "yarn", cmd: "yarn", args: ["global", "add", versionedPackage] },
+        { manager: "bun", cmd: "bun", args: ["add", "-g", versionedPackage] },
+    ];
+    for (const candidate of candidates) {
+        if (!commandExistsFn(candidate.cmd, { cwd: opts.cwd }))
+            continue;
+        return { ...candidate, rendered: renderCommand(candidate.cmd, candidate.args) };
+    }
+    return null;
+}
+export function missing_openspec_cli_message(opts = {}) {
+    const plan = recommended_openspec_install_plan(opts);
+    if (plan) {
+        return `PATH 中缺少 openspec CLI。可先运行 \`${plan.rendered}\` 安装，然后重新运行 superspec init --scope project。`;
+    }
+    return `PATH 中缺少 openspec CLI。请先安装 OpenSpec CLI（${OPENSPEC_INSTALL_DOC_URL}），然后重新运行 superspec init --scope project。`;
 }
 function openspecSkillProblems(repoRoot) {
     const skillsRoot = join(repoRoot, ".codex", "skills");
@@ -34,9 +63,9 @@ function writeSuperSpecAgent(repoRoot, name) {
         `description = "${ROLE_DESCRIPTIONS[name] ?? `superspec ${name} role`}"`,
         'model_reasoning_effort = "high"',
         'developer_instructions = """',
-        `You are the repo-local superspec ${name} native subagent.`,
-        "Follow the assigned superspec gate evidence task, cite concrete files, and report blockers upward.",
-        "Do not substitute main-thread self-review for required role evidence.",
+        `你是仓库本地的 superspec ${name} native subagent。`,
+        "遵循分配给你的 superspec gate 证据任务，引用具体文件，并把阻塞点上报主线程。",
+        "不要用主线程自审替代必须的角色证据。",
         '"""',
         "",
     ].join("\n"), "utf8");
@@ -51,16 +80,16 @@ function writeSuperSpecPrompt(repoRoot, name) {
         'argument-hint: "superspec gate evidence task"',
         "---",
         "",
-        `You are the repo-local superspec ${name} role.`,
+        `你是仓库本地的 superspec ${name} 角色。`,
         "",
-        "Review the provided superspec gate context with concrete file-backed evidence. Produce a concise pass/block report, cite source anchors and target refs, and do not replace required native-subagent evidence with main-thread self-review.",
+        "请基于具体文件证据审查提供的 superspec gate 上下文，输出简洁的通过 / 阻塞报告，引用 source anchors 与 target refs，并且不要用主线程自审替代必须的 native-subagent 证据。",
         "",
     ].join("\n"), "utf8");
     return filePath;
 }
 function ensureOpenSpecCodex(repoRoot, actions) {
     if (!commandExists("openspec", { cwd: repoRoot }))
-        return ["openspec CLI is not available in PATH"];
+        return [missing_openspec_cli_message({ cwd: repoRoot })];
     let problems = openspecSkillProblems(repoRoot);
     if (problems.length === 0) {
         actions.push({ action: "openspec_codex_skills", status: "ok" });
@@ -71,10 +100,10 @@ function ensureOpenSpecCodex(repoRoot, actions) {
         action: "openspec init --tools codex .",
         status: init.status === 0 ? "updated" : "failed",
         refs: problems,
-        detail: init.status === 0 ? undefined : (init.stderr || init.stdout).trim(),
+        detail: init.status === 0 ? undefined : commandFailure(init),
     });
     if (init.error || init.status !== 0)
-        return [`openspec init failed: ${commandFailure(init)}`];
+        return [`openspec init 执行失败：${commandFailure(init)}`];
     problems = openspecSkillProblems(repoRoot);
     if (problems.length === 0)
         return [];
@@ -83,12 +112,12 @@ function ensureOpenSpecCodex(repoRoot, actions) {
         action: "openspec update --force .",
         status: update.status === 0 ? "updated" : "failed",
         refs: problems,
-        detail: update.status === 0 ? undefined : (update.stderr || update.stdout).trim(),
+        detail: update.status === 0 ? undefined : commandFailure(update),
     });
     if (update.error || update.status !== 0)
-        return [`openspec update failed: ${commandFailure(update)}`];
+        return [`openspec update 执行失败：${commandFailure(update)}`];
     problems = openspecSkillProblems(repoRoot);
-    return problems.length === 0 ? [] : [`OpenSpec Codex skills remain missing/invalid: ${problems.join(", ")}`];
+    return problems.length === 0 ? [] : [`OpenSpec 配套技能文件仍然缺失或无效：${problems.join(", ")}`];
 }
 function ensureSuperSpecRoles(repoRoot, actions) {
     const problems = [];
@@ -99,14 +128,14 @@ function ensureSuperSpecRoles(repoRoot, actions) {
             created.push(writeSuperSpecAgent(repoRoot, name));
         }
         else if (read_agent_toml_name(agentPath) !== name) {
-            problems.push(`invalid agent ${agentPath}`);
+            problems.push(`agent 文件无效：${agentPath}`);
         }
         const promptPath = join(repoRoot, ".codex", "prompts", `${name}.md`);
         if (!existsSync(promptPath) || !statSync(promptPath).isFile()) {
             created.push(writeSuperSpecPrompt(repoRoot, name));
         }
         else if (!readFileSync(promptPath, "utf8").trim()) {
-            problems.push(`empty prompt ${promptPath}`);
+            problems.push(`prompt 文件为空：${promptPath}`);
         }
     }
     actions.push({

package/dist/src/util.d.ts

@@ -1,3 +1,4 @@
+import { type WorkflowTermHint } from "./i18n.ts";
 export declare const SCHEMA_VERSION = 1;
 export declare const GUARD_VERSION = "superspec-guard@1";
 export declare const CONFIG_FILENAME = "config.yaml";
@@ -12,6 +13,9 @@ export type Reason = {
     code: string;
     message: string;
     refs: string[];
+    label_zh?: string;
+    hint_zh?: string;
+    message_zh?: string;
 };
 export type Decision = {
     allowed: boolean;
@@ -24,6 +28,16 @@ export type Decision = {
     block_reasons: Reason[];
     next_allowed_actions: string[];
     trust_warnings: string[];
+    actions?: JsonMap[];
+    decision_zh?: string;
+    gate_label_zh?: string;
+    gate_hint_zh?: string;
+    command?: string;
+    command_label_zh?: string;
+    command_hint_zh?: string;
+    next_allowed_actions_zh?: string[];
+    trust_warnings_zh?: string[];
+    workflow_terms_zh?: WorkflowTermHint[];
 };
 export type TaskInfo = {
     task_id: string;
@@ -82,7 +96,12 @@ export declare function block(change: string, gate: string, reasons: Reason[], o
     gate_summary?: Record<string, any>;
     next_actions?: string[];
 }): Decision;
-export declare function printDecision(decision: JsonMap): void;
+export declare function decorateDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): JsonMap;
+export declare function printDecision(decision: JsonMap, opts?: {
+    command?: string;
+}): void;
 export declare function runCommand(cmd: string, args: string[], opts?: {
     cwd?: string;
     timeout?: number;

package/dist/src/util.js

@@ -2,6 +2,7 @@ import { createHash } from "node:crypto";
 import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, statSync } from "node:fs";
 import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { spawnSync } from "node:child_process";
+import { action_detail_zh, action_label_zh, action_status_zh, command_zh, decision_zh, gate_zh, reason_message_zh, reason_zh, translate_action_zh, trust_warning_zh, workflow_terms_zh_for } from "./i18n.js";
 export const SCHEMA_VERSION = 1;
 export const GUARD_VERSION = "superspec-guard@1";
 export const CONFIG_FILENAME = "config.yaml";
@@ -234,7 +235,8 @@ export class GuardError extends Error {
 }
 export const runtime = {};
 export function reason(code, message, refs = null) {
-    return { code, message, refs: refs ?? [] };
+    const zh = reason_zh(code);
+    return { code, message, refs: refs ?? [], label_zh: zh.label_zh, hint_zh: zh.hint_zh };
 }
 export function pinned_ref_key(item) {
     return `${String(item.path)}\u0000${String(item.blob_sha)}`;
@@ -273,8 +275,85 @@ export function block(change, gate, reasons, opts = {}) {
         trust_warnings: trustWarnings(),
     };
 }
-export function printDecision(decision) {
-    process.stdout.write(`${JSON.stringify(decision, null, 2)}\n`);
+export function decorateDecision(decision, opts = {}) {
+    const gateInfo = gate_zh(String(decision.gate ?? ""));
+    const command = opts.command ?? (typeof decision.command === "string" ? String(decision.command) : "");
+    const commandInfo = command ? command_zh(command) : null;
+    const reasons = Array.isArray(decision.block_reasons)
+        ? decision.block_reasons.map((item) => {
+            const base = item && typeof item === "object" ? { ...item } : { code: String(item), message: "", refs: [] };
+            const zh = reason_zh(String(base.code ?? ""));
+            return { ...base, label_zh: zh.label_zh, hint_zh: zh.hint_zh };
+        })
+        : [];
+    const nextActions = Array.isArray(decision.next_allowed_actions) ? decision.next_allowed_actions.map((item) => String(item)) : [];
+    return {
+        ...decision,
+        command: command || decision.command,
+        decision_zh: decision_zh(String(decision.decision ?? "")),
+        gate_label_zh: gateInfo.label_zh,
+        gate_hint_zh: gateInfo.hint_zh,
+        command_label_zh: commandInfo?.label_zh,
+        command_hint_zh: commandInfo?.hint_zh,
+        block_reasons: reasons,
+        next_allowed_actions_zh: nextActions.map((item) => translate_action_zh(item)),
+        trust_warnings_zh: Array.isArray(decision.trust_warnings) ? decision.trust_warnings.map((item) => trust_warning_zh(String(item))) : [],
+        workflow_terms_zh: workflow_terms_zh_for(command || undefined, String(decision.gate ?? ""), reasons.map((item) => String(item.code ?? ""))),
+    };
+}
+function sanitizeReasonForOutput(item) {
+    const refs = Array.isArray(item.refs) ? item.refs.map((ref) => String(ref)) : [];
+    return {
+        ...item,
+        refs,
+        message: String(item.message ?? ""),
+        message_zh: reason_message_zh(String(item.code ?? ""), String(item.message ?? ""), refs),
+    };
+}
+function sanitizeDecisionForOutput(decision) {
+    const reasons = Array.isArray(decision.block_reasons) ? decision.block_reasons.map((item) => sanitizeReasonForOutput(item)) : [];
+    const nextActions = Array.isArray(decision.next_allowed_actions)
+        ? decision.next_allowed_actions.map((item) => String(item))
+        : [];
+    const nextActionsZh = Array.isArray(decision.next_allowed_actions_zh)
+        ? decision.next_allowed_actions_zh.map((item) => String(item))
+        : [];
+    const trustWarnings = Array.isArray(decision.trust_warnings)
+        ? decision.trust_warnings.map((item) => String(item))
+        : [];
+    const trustWarningsZh = Array.isArray(decision.trust_warnings_zh)
+        ? decision.trust_warnings_zh.map((item) => String(item))
+        : [];
+    const actions = Array.isArray(decision.actions)
+        ? decision.actions.map((item) => {
+            const base = item && typeof item === "object" ? { ...item } : { action: String(item) };
+            const action = String(base.action ?? "");
+            const status = typeof base.status === "string" ? String(base.status) : "";
+            const detail = typeof base.detail === "string" ? String(base.detail) : "";
+            return {
+                ...base,
+                action,
+                status: status || base.status,
+                detail: detail || base.detail,
+                action_zh: action_label_zh(action),
+                status_zh: status ? action_status_zh(status) : undefined,
+                detail_zh: detail ? action_detail_zh(detail) : undefined,
+            };
+        })
+        : decision.actions;
+    return {
+        ...decision,
+        block_reasons: reasons,
+        next_allowed_actions: nextActions,
+        next_allowed_actions_zh: nextActionsZh,
+        trust_warnings: trustWarnings,
+        trust_warnings_zh: trustWarningsZh,
+        actions,
+    };
+}
+export function printDecision(decision, opts = {}) {
+    const decorated = decorateDecision(decision, opts);
+    process.stdout.write(`${JSON.stringify(sanitizeDecisionForOutput(decorated), null, 2)}\n`);
 }
 export function runCommand(cmd, args, opts = {}) {
     const platform = opts.platform ?? process.platform;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "SuperSpec workflow package: guard runtime, generic workflow templates, and Codex adapter payload.",
   "repository": {
     "type": "git",