@peterxiaoyang/superspec 0.1.9 → 0.1.10

package/dist/src/init_cli.js

@@ -4,12 +4,36 @@ import { install_workflow, uninstall_workflow, update_workflow } from "./install
 import { homedir } from "node:os";
 import { resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
-import { system_failure_zh } from "./i18n.js";
+import { action_detail_zh, action_status_zh, reason_message_zh, system_failure_zh } from "./i18n.js";
 function usage() {
     return "usage: superspec init [-h] [--scope {project,user}] [--path PATH] [--codex-home PATH] [--format {json,agent,user}] [--create] [--update] [--uninstall] [--dry-run] [--force]\n";
 }
 function help() {
-    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  --format {json,agent,user} 输出格式；json 用于诊断，agent/user 用于安全展示\n  --user-facing          等价于 --format user\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.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  --format {json,agent,user} 输出格式（默认：user）；json 用于诊断或自动化，agent 用于工作流消费\n  --user-facing          等价于 --format user\n  --create               兼容参数；init 默认就会创建缺失内容\n  --update               按 manifest 更新 SuperSpec 管理的文件；用户改动文件保留，新的版本写入 *.new\n  --uninstall            按 manifest 卸载 SuperSpec 管理的文件；.superspec 数据与既有/用户改动文件会保留\n  --dry-run              配合 --uninstall 时只预览将删除的文件，不实际修改\n  --force                安装时覆盖已有且内容不同的文件，并保留 *.bak 备份\n`;
+}
+function requestedOutputFormat(argv) {
+    if (argv.includes("--user-facing"))
+        return "user";
+    let selected = null;
+    for (let idx = 0; idx < argv.length; idx += 1) {
+        if (argv[idx] !== "--format")
+            continue;
+        const value = argv[idx + 1];
+        if (value === undefined || value.startsWith("--"))
+            return null;
+        selected = value;
+    }
+    if (selected === null)
+        return null;
+    try {
+        return parseDecisionOutputFormat(selected);
+    }
+    catch {
+        return null;
+    }
+}
+function fallbackOutputFormat(argv) {
+    return requestedOutputFormat(argv) ?? "user";
 }
 function parse_init_argv(argv) {
     const getValues = (flag) => {
@@ -45,7 +69,7 @@ function parse_init_argv(argv) {
         parseDecisionOutputFormat(value);
     const selectedFormat = argv.includes("--user-facing")
         ? "user"
-        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "user");
     const format = parseDecisionOutputFormat(selectedFormat);
     return {
         path: resolve(getValue("--path") ?? process.cwd()),
@@ -60,6 +84,118 @@ function parse_init_argv(argv) {
 function joinHomeCodex() {
     return `${homedir()}/.codex`;
 }
+function scopeLabel(scope) {
+    return scope === "user" ? "用户级" : "项目级";
+}
+function modeLabel(mode, dryRun) {
+    if (mode === "update")
+        return "更新";
+    if (mode === "uninstall")
+        return dryRun ? "卸载预览" : "卸载";
+    return "初始化";
+}
+function actionSummary(actions) {
+    if (!Array.isArray(actions) || actions.length === 0)
+        return "";
+    const counts = new Map();
+    for (const item of actions) {
+        if (!item || typeof item !== "object")
+            continue;
+        const status = String(item.status ?? "");
+        if (!status)
+            continue;
+        counts.set(status, (counts.get(status) ?? 0) + 1);
+    }
+    const changedOrder = ["created", "updated", "removed", "would_remove", "skipped", "failed"];
+    const parts = changedOrder
+        .map((status) => [status, counts.get(status) ?? 0])
+        .filter(([, count]) => count > 0)
+        .map(([status, count]) => `${action_status_zh(status)} ${count} 项`);
+    if (parts.length > 0)
+        return parts.join("，");
+    const okCount = counts.get("ok") ?? 0;
+    return okCount > 0 ? `已检查 ${okCount} 项，无需改动` : "";
+}
+function actionTarget(action) {
+    const match = action.match(/^(?:install|update|uninstall(?: rmdir)?)\s+(.+)$/u);
+    return match?.[1] ?? "";
+}
+function skippedActionNotes(actions) {
+    if (!Array.isArray(actions))
+        return [];
+    const groups = new Map();
+    for (const item of actions) {
+        if (!item || typeof item !== "object")
+            continue;
+        const action = String(item.action ?? "");
+        const status = String(item.status ?? "");
+        if (status !== "skipped")
+            continue;
+        const detail = String(item.detail ?? "");
+        const note = detail ? action_detail_zh(detail) : "有文件被保留未改动；需要完整列表时添加 --format json。";
+        const target = actionTarget(action);
+        const group = groups.get(note) ?? { count: 0, targets: [] };
+        group.count += 1;
+        if (target && group.targets.length < 3)
+            group.targets.push(target);
+        groups.set(note, group);
+    }
+    return [...groups.entries()].map(([note, group]) => {
+        const hiddenCount = group.count - group.targets.length;
+        if (group.targets.length === 0)
+            return `${note}（${group.count} 项）`;
+        const suffix = hiddenCount > 0 ? ` 等 ${group.count} 项` : "";
+        return `${note}（${group.targets.join("，")}${suffix}）`;
+    });
+}
+function knownInitProblemMessageZh(message) {
+    if (/install manifest missing; run superspec init before --update/iu.test(message)) {
+        return "缺少安装清单；请先运行 superspec init，再执行 update。";
+    }
+    if (/install manifest missing; nothing to uninstall/iu.test(message)) {
+        return "缺少安装清单；当前没有可卸载的 SuperSpec 管理文件。";
+    }
+    return null;
+}
+function reasonTextZh(item) {
+    const code = String(item.code ?? "");
+    const message = String(item.message ?? "");
+    const refs = Array.isArray(item.refs) ? item.refs.map((ref) => String(ref)) : [];
+    return knownInitProblemMessageZh(message) ?? reason_message_zh(code, message, refs);
+}
+function renderInitUserDecision(decision, opts = {}) {
+    const lines = [];
+    const op = modeLabel(opts.mode, opts.dryRun);
+    lines.push(`SuperSpec ${op}${decision.allowed ? "完成" : "未完成"}。`);
+    lines.push(`范围：${scopeLabel(opts.scope)}。`);
+    const root = opts.targetRoot ?? String(decision.install_root ?? decision.project_root ?? "");
+    if (root)
+        lines.push(`位置：${root}`);
+    const summary = actionSummary(decision.actions);
+    if (decision.allowed && summary)
+        lines.push(`处理：${summary}。`);
+    const skippedNotes = skippedActionNotes(decision.actions);
+    if (decision.allowed && skippedNotes.length > 0) {
+        lines.push("跳过项：");
+        for (const note of skippedNotes)
+            lines.push(`- ${note}`);
+    }
+    const reasons = Array.isArray(decision.block_reasons) ? decision.block_reasons : [];
+    if (!decision.allowed && reasons.length > 0) {
+        lines.push("原因：");
+        for (const item of reasons)
+            lines.push(`- ${reasonTextZh(item)}`);
+        lines.push("修正后重新运行同一命令；需要完整诊断时添加 --format json。");
+    }
+    return `${lines.join("\n")}\n`;
+}
+function printInitDecision(decision, opts) {
+    if (opts.format === "user") {
+        process.stdout.write(renderInitUserDecision(decision, opts));
+        return;
+    }
+    printDecision(decision, { command: opts.command ?? "init", format: opts.format });
+}
 function commandFailure(proc) {
     const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
     if (output)
@@ -156,12 +292,19 @@ function openspecPreflightBlocked(args, scope, installResult) {
     const decision = block("project", "openspec_preflight", [reason(code, message)], {
         next_actions: [`install or upgrade @fission-ai/openspec >= ${REQUIRED_OPENSPEC_MIN_VERSION}, then rerun \`superspec init --scope ${scope}\``],
     });
-    printDecision({
+    printInitDecision({
         ...decision,
         project_root: args.path,
         install_scope: scope,
         install_root: targetRoot,
-    }, { command: "init", format: args.format });
+    }, {
+        command: "init",
+        format: args.format,
+        mode: args.mode,
+        scope,
+        targetRoot,
+        dryRun: args.dryRun,
+    });
     return 1;
 }
 function run_init(args, scope) {
@@ -188,7 +331,14 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary, { command: "init", format: args.format });
+    printInitDecision(summary, {
+        command: "init",
+        format: args.format,
+        mode: args.mode,
+        scope,
+        targetRoot,
+        dryRun: args.dryRun,
+    });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
@@ -208,7 +358,14 @@ 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]), { command: "init", format: args?.format });
+        printInitDecision(block(change, "guard_error", [errReason]), {
+            command: "init",
+            format: args?.format ?? fallbackOutputFormat(argv),
+            mode: args?.mode,
+            scope: args?.scope ?? "project",
+            targetRoot: args?.path,
+            dryRun: args?.dryRun,
+        });
         return 2;
     }
 }
@@ -229,7 +386,14 @@ export async function main_init_async(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]), { command: "init", format: args?.format });
+        printInitDecision(block(change, "guard_error", [errReason]), {
+            command: "init",
+            format: args?.format ?? fallbackOutputFormat(argv),
+            mode: args?.mode,
+            scope: args?.scope ?? "project",
+            targetRoot: args?.path,
+            dryRun: args?.dryRun,
+        });
         return 2;
     }
 }

package/dist/superspec.js

@@ -30,7 +30,7 @@ function help() {
         "  version     print SuperSpec CLI version",
         "",
         "examples:",
-        "  superspec init --scope project --format agent",
+        "  superspec init --scope project",
         "  superspec init --scope user",
         "  superspec guard check-init --change <change> --format agent",
         "  superspec doctor",
@@ -49,7 +49,7 @@ function updateHelp() {
         "  --user, --global        equivalent to --scope user",
         "  --path PATH             project root for project scope (default: current directory)",
         "  --codex-home PATH       Codex user home for user scope (default: $CODEX_HOME or ~/.codex)",
-        "  --format {json,agent,user} output format; use agent for workflow consumption",
+        "  --format {json,agent,user} output format (default: user); use json for diagnostics/automation",
         "  --local-only            skip npm self-update and use the currently installed package",
         "  -h, --help              show this help",
         "",

package/package.json

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