@peterxiaoyang/superspec 0.1.2 → 0.1.4

package/dist/src/doctor.js

@@ -0,0 +1,230 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { PACKAGE_ROOT } from "./install_engine.js";
+import { openspec_cli_probe } from "./openspec.js";
+import { commandExists, runCommand } from "./util.js";
+function readPackageJson(packageRoot) {
+    try {
+        const parsed = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export function superspec_package_version(packageRoot = PACKAGE_ROOT) {
+    const version = readPackageJson(packageRoot).version;
+    return typeof version === "string" && version ? version : "0.0.0";
+}
+function realpathMaybe(filePath) {
+    try {
+        return realpathSync(filePath);
+    }
+    catch {
+        return resolve(filePath);
+    }
+}
+function pathInfo(filePath) {
+    if (!filePath)
+        return null;
+    const info = { path: filePath, exists: existsSync(filePath) };
+    if (!info.exists)
+        return info;
+    try {
+        const stat = lstatSync(filePath);
+        info.kind = stat.isSymbolicLink() ? "symlink" : stat.isDirectory() ? "directory" : stat.isFile() ? "file" : "other";
+        if (stat.isSymbolicLink())
+            info.link_target = readlinkSync(filePath);
+        info.realpath = realpathMaybe(filePath);
+    }
+    catch (err) {
+        info.error = err.message;
+    }
+    return info;
+}
+function firstNonEmptyLine(text) {
+    return text.split(/\r?\n/u).map((line) => line.trim()).find((line) => line.length > 0) ?? null;
+}
+function commandPath(cmd, opts) {
+    if (!opts.commandExistsFn(cmd, { cwd: opts.cwd }))
+        return null;
+    const proc = opts.platform === "win32"
+        ? opts.run("where.exe", [cmd], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform })
+        : opts.run("sh", ["-c", `command -v ${cmd}`], { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0)
+        return null;
+    return firstNonEmptyLine(proc.stdout);
+}
+function npmValue(args, opts) {
+    if (!opts.commandExistsFn("npm", { cwd: opts.cwd }))
+        return { available: false, value: null, error: "npm not found on PATH" };
+    const proc = opts.run("npm", args, { cwd: opts.cwd, timeout: 15_000, platform: opts.platform });
+    if (proc.error || proc.status !== 0) {
+        return {
+            available: true,
+            value: null,
+            error: (proc.error?.message ?? (proc.stderr || proc.stdout)).trim(),
+        };
+    }
+    return { available: true, value: firstNonEmptyLine(proc.stdout), error: null };
+}
+function containsUnscopedSuperspecNodeModule(value) {
+    if (!value)
+        return false;
+    return /[/\\]node_modules[/\\]superspec[/\\]/u.test(value);
+}
+function add(checks, status, name, detail, refs) {
+    checks.push({ status, name, detail, refs });
+}
+export function build_doctor_report(opts = {}) {
+    const cwd = resolve(opts.cwd ?? process.cwd());
+    const packageRoot = opts.packageRoot ?? PACKAGE_ROOT;
+    const platform = opts.platform ?? process.platform;
+    const run = opts.run ?? runCommand;
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd, platform }));
+    const packageJson = readPackageJson(packageRoot);
+    const version = superspec_package_version(packageRoot);
+    const packageName = typeof packageJson.name === "string" ? packageJson.name : "unknown";
+    const expectedBin = join(packageRoot, "bin", "superspec.js");
+    const resolvedCommand = commandPath("superspec", { cwd, platform, commandExistsFn, run });
+    const command = pathInfo(resolvedCommand);
+    const prefix = npmValue(["prefix", "-g"], { cwd, platform, commandExistsFn, run });
+    const root = npmValue(["root", "-g"], { cwd, platform, commandExistsFn, run });
+    const npmRoot = typeof root.value === "string" ? root.value : null;
+    const scopedPackage = npmRoot ? pathInfo(join(npmRoot, "@peterxiaoyang", "superspec")) : null;
+    const unscopedPackage = npmRoot ? pathInfo(join(npmRoot, "superspec")) : null;
+    const openspecProbe = openspec_cli_probe({ cwd, commandExistsFn, run });
+    const checks = [];
+    const nextActions = [];
+    if (packageName === "@peterxiaoyang/superspec" && version !== "0.0.0") {
+        add(checks, "ok", "package metadata", `${packageName}@${version}`);
+    }
+    else {
+        add(checks, "fail", "package metadata", `could not identify @peterxiaoyang/superspec package metadata under ${packageRoot}`);
+    }
+    if (openspecProbe.ok) {
+        add(checks, "ok", "OpenSpec CLI", openspecProbe.message);
+    }
+    else {
+        add(checks, "fail", "OpenSpec CLI", openspecProbe.message);
+        nextActions.push("npm install -g @fission-ai/openspec@latest");
+    }
+    if (!command) {
+        add(checks, "warn", "superspec command", "`superspec` is not resolvable from PATH in this shell");
+    }
+    else {
+        const commandRealpath = typeof command.realpath === "string" ? command.realpath : undefined;
+        const commandTarget = typeof command.link_target === "string" ? command.link_target : undefined;
+        if (containsUnscopedSuperspecNodeModule(commandRealpath) || containsUnscopedSuperspecNodeModule(commandTarget)) {
+            add(checks, "fail", "superspec command owner", "`superspec` points at the unscoped `superspec` package, which conflicts with @peterxiaoyang/superspec", [String(command.path)]);
+            nextActions.push("npm uninstall -g superspec");
+            nextActions.push("npm install -g @peterxiaoyang/superspec@latest");
+        }
+        else if (existsSync(expectedBin) && commandRealpath && realpathMaybe(expectedBin) !== commandRealpath) {
+            add(checks, "warn", "superspec command owner", "`superspec` on PATH does not point at this package root", [String(command.path), expectedBin]);
+        }
+        else {
+            add(checks, "ok", "superspec command owner", "`superspec` resolves to this package");
+        }
+    }
+    if (root.error) {
+        add(checks, "warn", "npm global root", String(root.error));
+    }
+    else if (npmRoot) {
+        add(checks, "ok", "npm global root", npmRoot);
+    }
+    if (unscopedPackage?.exists) {
+        add(checks, "warn", "unscoped superspec package", "global package `superspec` is installed and can claim the same `superspec` binary", [String(unscopedPackage.path)]);
+        nextActions.push("npm uninstall -g superspec");
+    }
+    if (scopedPackage && !scopedPackage.exists) {
+        add(checks, "warn", "scoped superspec package", "@peterxiaoyang/superspec is not present under npm global root", [String(scopedPackage.path)]);
+    }
+    const dedupedNextActions = [...new Set(nextActions)];
+    return {
+        ok: !checks.some((check) => check.status === "fail"),
+        cwd,
+        superspec: {
+            name: packageName,
+            version,
+            package_root: packageRoot,
+            expected_bin: expectedBin,
+            entry: opts.argv0 ?? process.argv[1] ?? null,
+            command,
+            scoped_global_package: scopedPackage,
+            unscoped_global_package: unscopedPackage,
+        },
+        node: {
+            version: process.versions.node,
+            exec_path: process.execPath,
+            platform,
+        },
+        npm: {
+            prefix,
+            root,
+        },
+        openspec: {
+            ok: openspecProbe.ok,
+            state: openspecProbe.state,
+            version: openspecProbe.version,
+            message: openspecProbe.message,
+        },
+        checks,
+        next_actions: dedupedNextActions,
+    };
+}
+export function render_doctor_report(report) {
+    const lines = [
+        "SuperSpec doctor",
+        "",
+        `SuperSpec: ${report.superspec.name}@${report.superspec.version}`,
+        `Package root: ${report.superspec.package_root}`,
+        `Command path: ${report.superspec.command?.path ?? "not found"}`,
+        `OpenSpec: ${report.openspec.message}`,
+        `Node: ${report.node.version} (${report.node.platform})`,
+        `npm prefix: ${report.npm.prefix.value ?? "unknown"}`,
+        `npm root: ${report.npm.root.value ?? "unknown"}`,
+        "",
+        "Checks:",
+        ...report.checks.map((check) => {
+            const refs = check.refs && check.refs.length > 0 ? ` (${check.refs.join(", ")})` : "";
+            return `  [${check.status}] ${check.name}: ${check.detail}${refs}`;
+        }),
+    ];
+    if (report.next_actions.length > 0) {
+        lines.push("", "Next actions:", ...report.next_actions.map((action) => `  ${action}`));
+    }
+    lines.push("");
+    return lines.join("\n");
+}
+function doctorHelp() {
+    return [
+        "usage: superspec doctor [--json]",
+        "",
+        "diagnoses SuperSpec, OpenSpec, npm global package, and PATH wiring.",
+        "",
+        "options:",
+        "  --json      print machine-readable JSON",
+        "  -h, --help  show this help",
+        "",
+    ].join("\n");
+}
+export function main_doctor(argv = process.argv.slice(2)) {
+    if (argv.includes("-h") || argv.includes("--help")) {
+        process.stdout.write(doctorHelp());
+        return 0;
+    }
+    const unknown = argv.filter((arg) => arg !== "--json");
+    if (unknown.length > 0) {
+        process.stderr.write(`superspec doctor: unknown option ${JSON.stringify(unknown[0])}\n\n${doctorHelp()}`);
+        return 2;
+    }
+    const report = build_doctor_report();
+    if (argv.includes("--json")) {
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    }
+    else {
+        process.stdout.write(render_doctor_report(report));
+    }
+    return report.ok ? 0 : 1;
+}

package/dist/src/evidence.d.ts

@@ -26,3 +26,4 @@ export declare function live_pass(evidences: JsonMap[], filters?: {
     kind?: string | null;
     task_id?: string | null;
 }): JsonMap[];
+export declare function live_user_confirmations(evidences: JsonMap[], gate: string): JsonMap[];

package/dist/src/evidence.js

@@ -272,6 +272,9 @@ function finding_string_list_reasons(ev, finding, field, opts = {}) {
 function human_confirmation_reasons(ev) {
     const problems = [];
     const gate = normalize_gate(String(ev.gate ?? ""));
+    if (String(ev.created_by ?? "") !== "user") {
+        problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation must be created_by user`));
+    }
     if (!HUMAN_CONFIRMATION_GATES.has(gate)) {
         problems.push(reason("human_confirmation_invalid", `${ev._path}: human_confirmation gate=${repr(ev.gate)} is not consumed by any guard gate; expected one of ${renderList([...HUMAN_CONFIRMATION_GATES].sort())}`));
     }
@@ -847,3 +850,7 @@ export function live_pass(evidences, filters = {}) {
     const dead = superseded_ids(evidences);
     return find_pass(evidences, filters).filter((ev) => !dead.has(ev.evidence_id));
 }
+export function live_user_confirmations(evidences, gate) {
+    return live_pass(evidences, { gate, kind: "human_confirmation" })
+        .filter((ev) => String(ev.created_by ?? "") === "user");
+}

package/dist/src/gates.d.ts

@@ -8,6 +8,7 @@ export declare function check_init(change: string, status: JsonMap, repoRoot: st
 export declare function check_superspec_gate(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], gateRaw: string): Decision;
 export declare function check_artifact(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], artifact: string): Decision;
 export declare function check_task_reopen(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
+export declare function check_apply_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;
 export declare function check_task_edit(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_task_complete(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[], taskId: string): Decision;
 export declare function check_review_ready(change: string, status: JsonMap, changeRoot: string, evidences: JsonMap[]): Decision;

package/dist/src/gates.js

@@ -5,7 +5,7 @@ import { all_done, artifact_status_map, get_repo_root, is_done, normalize_gate,
 import { read_agent_toml_name, read_skill_frontmatter_name, sidecar_business_invariants_path, sidecar_discovery_path, sidecar_test_contract_path } from "./paths.js";
 import { business_invariant_ids, business_invariant_validation_reasons, automated_hard_business_invariant_ids, evidence_invariant_refs, evidence_invariant_ref_reasons, evidence_test_contract_invariant_reasons, human_confirmation_business_invariant_ids, invariant_matrix_coverage_reasons, post_implementation_business_invariant_ids, red_green_invariant_ids, test_contract_invariant_ids, } from "./invariants.js";
 import { evidence_test_id_reasons, declared_test_evidence_reasons, parse_spec_scenarios, parse_tasks, parse_test_contract_ids, parse_test_contract_records, red_green_test_ids, splitList, tasks_structure_hash, task_alternative_verification, task_test_evidence, task_test_refs, test_contract_covers_scenario, test_contract_invariant_refs_by_test, write_scope_conflict_reasons, } from "./tasks.js";
-import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
+import { duplicate_evidence_id_reasons, dangling_evidence_ref_reasons, final_verification_evidences, live_task_reopens, live_task_reopen_resolutions, live_pass, live_user_confirmations, pass_task_reopens, supersede_reasons, unresolved_live_task_reopens, validate_evidence_schema, verify_reference_reasons, } from "./evidence.js";
 import { review_disclosure_reasons } from "./disclosure.js";
 import { archive_manifest_path } from "./archive.js";
 function action_list(...items) {
@@ -311,7 +311,7 @@ function archive_ready_actions(change, reasons, review) {
 function default_gate_next_actions(gate) {
     switch (gate) {
         case "explore_complete":
-            return ["write .superspec/artifacts/discovery.md and record native_subagent critic evidence"];
+            return ["write .superspec/artifacts/discovery.md, record native_subagent critic evidence, and record explore_complete human confirmation"];
         case "proposal_reviewed":
             return ["run the proposal critic review (round-tagged, findings[]) and record a main_review_digest disclosing every finding"];
         case "design_complete":
@@ -478,6 +478,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
                 reasons.push(reason("missing_native_subagent_evidence", `explore_complete requires native_subagent ${role} report`));
         }
         reasons.push(...stale_artifact_review_reasons(exploreReviews, changeRoot, ".superspec/artifacts/discovery.md", "stale_explore_review", "explore_complete"));
+        if (live_user_confirmations(evidences, "explore_complete").length === 0) {
+            reasons.push(reason("missing_human_confirmation", "explore_complete requires human confirmation before entering propose"));
+        }
         // DISC Phase 1: material findings raised by explore reviews must be disclosed to the user
         // (main_review_digest + user_review_decision) before the gate can pass.
         reasons.push(...review_disclosure_reasons("explore_complete", changeRoot, evidences));
@@ -510,7 +513,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             if (!designReviews.some((ev) => ev.agent_role === role))
                 reasons.push(reason(`missing_${role}_review`, `design_complete requires native_subagent ${role} report`));
         }
-        if (live_pass(evidences, { kind: "human_confirmation", gate: "design_complete" }).length === 0)
+        if (live_user_confirmations(evidences, "design_complete").length === 0)
             reasons.push(reason("missing_human_confirmation", "design_complete requires human confirmation"));
         reasons.push(...stale_artifact_review_reasons(designReviews, changeRoot, "design.md", "stale_design_review", "design_complete"));
         // DISC Phase 2: design reviews carrying round-tagged findings enter the disclosure loop
@@ -536,7 +539,7 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
         const humanRequired = human_confirmation_business_invariant_ids(changeRoot);
         if (humanRequired.size > 0) {
             const confirmed = new Set();
-            for (const ev of live_pass(evidences, { gate: "invariants_reviewed", kind: "human_confirmation" })) {
+            for (const ev of live_user_confirmations(evidences, "invariants_reviewed")) {
                 for (const id of evidence_invariant_refs(ev))
                     confirmed.add(id);
             }
@@ -654,6 +657,9 @@ export function check_superspec_gate(change, status, changeRoot, evidences, gate
             }
         }
     }
+    else if (gate === "apply_ready") {
+        return check_apply_ready(change, status, changeRoot, evidences);
+    }
     else {
         return block(change, gate, [reason("unknown_gate", `unknown superspec gate: ${gate}`)]);
     }
@@ -1029,6 +1035,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
         reasons.push(reason("propose_not_complete", "task_reopen requires propose_complete"));
         reasons.push(...propose.block_reasons);
     }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
     const tasks = parse_tasks(changeRoot);
     const task = tasks[taskId];
     if (!task)
@@ -1038,8 +1045,13 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
     reasons.push(...request_changes_round_reasons(evidences));
     const reopenCheck = active_task_reopen_reasons(changeRoot, evidences, task, taskId, "pre_revert");
     reasons.push(...reopenCheck.reasons);
-    if (reasons.length > 0)
-        return block(change, gate, reasons, { task_id: taskId, next_actions: [`keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`] });
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            task_id: taskId,
+            next_actions: action_list(reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null, `keep ${taskId} checked, fix task_reopen evidence / supersedes, then rerun check-task-reopen`),
+        });
+    }
     return allow(change, gate, { task_id: taskId });
 }
 // FIX-8 (audit A-5): apply work requires the user's explicit isolation/execution-mode choice,
@@ -1048,7 +1060,7 @@ export function check_task_reopen(change, status, changeRoot, evidences, taskId)
 // apply-phase scope expansion (SPEC §14.7) and demands explicit user re-approval — redesign,
 // split into a new change, or record a scope_expansion confirmation re-pinning the structure.
 function apply_scope_confirmation_reasons(changeRoot, evidences) {
-    const isolation = live_pass(evidences, { gate: "apply_isolation", kind: "human_confirmation" });
+    const isolation = live_user_confirmations(evidences, "apply_isolation");
     const currentHash = tasks_structure_hash(changeRoot);
     if (isolation.length === 0) {
         const hashHint = currentHash ? ` with tasks_structure_hash=${currentHash}` : "";
@@ -1056,11 +1068,28 @@ function apply_scope_confirmation_reasons(changeRoot, evidences) {
     }
     if (currentHash === null)
         return [];
-    const approvals = [...isolation, ...live_pass(evidences, { gate: "scope_expansion", kind: "human_confirmation" })];
+    const approvals = [...isolation, ...live_user_confirmations(evidences, "scope_expansion")];
     if (approvals.some((ev) => String(ev.tasks_structure_hash ?? "") === currentHash))
         return [];
     return [reason("scope_expansion_unconfirmed", `tasks.md structure changed after the last user-approved apply scope; ask the user to redesign/split the change or re-approve by recording gate="scope_expansion" human_confirmation with tasks_structure_hash=${currentHash}`)];
 }
+export function check_apply_ready(change, status, changeRoot, evidences) {
+    const gate = "apply_ready";
+    const reasons = [];
+    const propose = check_superspec_gate(change, status, changeRoot, evidences, "propose_complete");
+    if (!propose.allowed) {
+        reasons.push(reason("propose_not_complete", "apply_ready requires propose_complete"));
+        reasons.push(...propose.block_reasons);
+    }
+    reasons.push(...apply_scope_confirmation_reasons(changeRoot, evidences));
+    if (reasons.length > 0) {
+        const reasonSet = reason_codes(reasons);
+        return block(change, gate, reasons, {
+            next_actions: action_list(!propose.allowed ? "pass propose_complete before apply" : null, reasonSet.has("apply_isolation_unconfirmed") ? "AskUserQuestion for apply isolation/execution mode and record gate=\"apply_isolation\" human_confirmation" : null, reasonSet.has("scope_expansion_unconfirmed") ? "stop: redesign/split the change or record gate=\"scope_expansion\" human_confirmation re-approving tasks.md structure" : null),
+        });
+    }
+    return allow(change, gate, { openspec_summary: artifact_status_map(status) });
+}
 export function check_task_edit(change, status, changeRoot, evidences, taskId) {
     const gate = "task_edit";
     const reasons = [];
@@ -1378,7 +1407,7 @@ export function check_review_complete(change, status, changeRoot, evidences) {
         && (ev.kind === "verification_review" || ev.kind === "final_test")
         && ev.status === "fail");
     if (failedVerifications.length > 0) {
-        const dispositions = new Set(live_pass(evidences, { gate: "verify_failure_handling", kind: "human_confirmation" })
+        const dispositions = new Set(live_user_confirmations(evidences, "verify_failure_handling")
             .flatMap((ev) => (Array.isArray(ev.confirmed_refs) ? ev.confirmed_refs.map((item) => String(item)) : [])));
         const unhandled = failedVerifications
             .map((ev) => String(ev.evidence_id ?? ev._path ?? "unknown"))
@@ -1456,7 +1485,7 @@ export function check_archive_ready(change, status, changeRoot, evidences) {
     if (!ok && !reviewCodes.has("validate_failed")) {
         reasons.push(reason("validate_failed", "openspec validate did not pass"));
     }
-    if (live_pass(evidences, { gate: "archive_ready", kind: "human_confirmation" }).length === 0) {
+    if (live_user_confirmations(evidences, "archive_ready").length === 0) {
         reasons.push(reason("missing_final_confirmation", "archive_ready requires human confirmation evidence"));
     }
     if (reasons.length > 0)

package/dist/src/git.js

@@ -2,7 +2,7 @@ import { existsSync, statSync } from "node:fs";
 import { dirname, isAbsolute, relative } from "node:path";
 import { GuardError, reason, renderList, runCommand, runtime } from "./util.js";
 import { splitList, task_test_evidence } from "./tasks.js";
-import { live_pass } from "./evidence.js";
+import { live_user_confirmations } from "./evidence.js";
 export function file_blob_sha(filePath) {
     if (!existsSync(filePath) || !statSync(filePath).isFile())
         throw new GuardError(`git_blob_inspection_failure: reviewed target missing: ${filePath}`);
@@ -50,7 +50,7 @@ export function dirty_worktree_reasons(repoRoot, changeRoot, evidences) {
     const unknown = dirty.filter((item) => !(changeRel && item.startsWith(`${changeRel}/`)));
     if (unknown.length === 0)
         return [];
-    const confirmations = live_pass(evidences, { gate: "branch_handling", kind: "human_confirmation" });
+    const confirmations = live_user_confirmations(evidences, "branch_handling");
     const confirmedScopes = confirmations.flatMap((ev) => (Array.isArray(ev.confirmed_paths) ? ev.confirmed_paths.map((item) => String(item)).filter(Boolean) : []));
     const unconfirmed = unknown.filter((item) => !confirmedScopes.some((scope) => pathInScope(item, scope)));
     if (unconfirmed.length === 0)

package/dist/src/init_cli.d.ts

@@ -1,10 +1,11 @@
-import { runCommand, type OpenspecCliProbe } from "./core.ts";
+import { runCommand, type DecisionOutputFormat, type OpenspecCliProbe } from "./core.ts";
 import { type InstallScope } from "./install_engine.ts";
 type InitArgs = {
     path: string;
     codexHome: string;
     mode: "install" | "update" | "uninstall";
     scope: InstallScope | null;
+    format: DecisionOutputFormat;
     dryRun: boolean;
     force: boolean;
 };

package/dist/src/init_cli.js

@@ -1,4 +1,4 @@
-import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
+import { block, commandExists, GuardError, printDecision, reason, runCommand, openspec_cli_probe, parseDecisionOutputFormat, REQUIRED_OPENSPEC_MIN_VERSION, } from "./core.js";
 import { forced_openspec_install_plan, 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";
@@ -6,21 +6,25 @@ 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";
+    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  --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} 输出格式；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`;
 }
 function parse_init_argv(argv) {
-    const getValue = (flag) => {
-        const idx = argv.indexOf(flag);
-        if (idx === -1)
-            return undefined;
-        const value = argv[idx + 1];
-        if (value === undefined || value.startsWith("--"))
-            throw new GuardError(`${flag} 缺少取值`);
-        return value;
+    const getValues = (flag) => {
+        const values = [];
+        for (let idx = 0; idx < argv.length; idx += 1) {
+            if (argv[idx] !== flag)
+                continue;
+            const value = argv[idx + 1];
+            if (value === undefined || value.startsWith("--"))
+                throw new GuardError(`${flag} 缺少取值`);
+            values.push(value);
+        }
+        return values;
     };
+    const getValue = (flag) => getValues(flag)[0];
     const update = argv.includes("--update");
     const uninstall = argv.includes("--uninstall");
     if (update && uninstall)
@@ -36,11 +40,19 @@ function parse_init_argv(argv) {
         scope = "user";
     if (argv.includes("--project"))
         scope = "project";
+    const formatValues = getValues("--format");
+    for (const value of formatValues)
+        parseDecisionOutputFormat(value);
+    const selectedFormat = argv.includes("--user-facing")
+        ? "user"
+        : (formatValues.length > 0 ? formatValues[formatValues.length - 1] : "json");
+    const format = parseDecisionOutputFormat(selectedFormat);
     return {
         path: resolve(getValue("--path") ?? process.cwd()),
         codexHome: resolve(getValue("--codex-home") ?? process.env.CODEX_HOME ?? joinHomeCodex()),
         mode: uninstall ? "uninstall" : update ? "update" : "install",
         scope,
+        format,
         dryRun: argv.includes("--dry-run"),
         force: argv.includes("--force"),
     };
@@ -149,7 +161,7 @@ function openspecPreflightBlocked(args, scope, installResult) {
         project_root: args.path,
         install_scope: scope,
         install_root: targetRoot,
-    }, { command: "init" });
+    }, { command: "init", format: args.format });
     return 1;
 }
 function run_init(args, scope) {
@@ -176,16 +188,17 @@ function run_init(args, scope) {
     }
     summary.install_scope = scope;
     summary.install_root = targetRoot;
-    printDecision(summary, { command: "init" });
+    printDecision(summary, { command: "init", format: args.format });
     return summary.allowed ? 0 : 1;
 }
 export function main_init(argv = process.argv.slice(2)) {
+    let args = null;
     try {
         if (argv.includes("-h") || argv.includes("--help")) {
             process.stdout.write(help());
             return 0;
         }
-        const args = parse_init_argv(argv);
+        args = parse_init_argv(argv);
         const scope = args.scope ?? "project";
         const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
         if (openspecInstall === "failed" || openspecInstall === "skipped")
@@ -195,17 +208,18 @@ 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" });
+        printDecision(block(change, "guard_error", [errReason]), { command: "init", format: args?.format });
         return 2;
     }
 }
 export async function main_init_async(argv = process.argv.slice(2)) {
+    let args = null;
     try {
         if (argv.includes("-h") || argv.includes("--help")) {
             process.stdout.write(help());
             return 0;
         }
-        const args = parse_init_argv(argv);
+        args = parse_init_argv(argv);
         const scope = args.scope ?? (canPrompt() ? await promptInstallScope() : "project");
         const openspecInstall = maybe_install_missing_openspec({ cwd: args.path, scope, mode: args.mode });
         if (openspecInstall === "failed" || openspecInstall === "skipped")
@@ -215,7 +229,7 @@ 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" });
+        printDecision(block(change, "guard_error", [errReason]), { command: "init", format: args?.format });
         return 2;
     }
 }

package/dist/src/self_update.d.ts

@@ -0,0 +1,14 @@
+import { runCommand } from "./util.ts";
+type RunFn = typeof runCommand;
+type CommandExistsFn = (cmd: string, meta?: {
+    cwd?: string;
+}) => boolean;
+export declare function update_self_then_rerun(opts: {
+    args: string[];
+    cwd?: string;
+    run?: RunFn;
+    commandExistsFn?: CommandExistsFn;
+    writeStdout?: (text: string) => void;
+    writeStderr?: (text: string) => void;
+}): number;
+export {};

package/dist/src/self_update.js

@@ -0,0 +1,56 @@
+import { commandExists, runCommand } from "./util.js";
+const SUPERSPEC_NPM_PACKAGE = "@peterxiaoyang/superspec";
+function renderCommand(cmd, args) {
+    return [cmd, ...args].join(" ");
+}
+function commandFailure(proc) {
+    const output = (proc.error?.message ?? (proc.stderr || proc.stdout)).trim();
+    if (output)
+        return output;
+    return proc.status === null ? "command failed" : `command exited with status ${proc.status}`;
+}
+function shouldRetrySuperSpecInstallWithForce(proc) {
+    const output = `${proc.error?.message ?? ""}\n${proc.stderr}\n${proc.stdout}`;
+    const binConflict = /\bEEXIST\b|already exists|file exists|Refusing to delete|will not overwrite|would overwrite/iu.test(output);
+    const superspecBin = /\bsuperspec(?:\.(?:cmd|ps1))?\b/iu.test(output);
+    return binConflict && superspecBin;
+}
+export function update_self_then_rerun(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const run = opts.run ?? runCommand;
+    const commandExistsFn = opts.commandExistsFn ?? ((cmd, meta) => commandExists(cmd, { cwd: meta?.cwd }));
+    const writeStdout = opts.writeStdout ?? ((text) => process.stdout.write(text));
+    const writeStderr = opts.writeStderr ?? ((text) => process.stderr.write(text));
+    if (!commandExistsFn("npm", { cwd })) {
+        writeStderr("SuperSpec update requires npm on PATH to install @peterxiaoyang/superspec@latest. Use `superspec update --local-only` to update surfaces from the currently installed package.\n");
+        return 1;
+    }
+    const installArgs = ["install", "-g", `${SUPERSPEC_NPM_PACKAGE}@latest`];
+    writeStderr(`Updating SuperSpec CLI: ${renderCommand("npm", installArgs)}\n`);
+    let install = run("npm", installArgs, { cwd, timeout: 300_000 });
+    if ((install.error || install.status !== 0) && shouldRetrySuperSpecInstallWithForce(install)) {
+        const forcedArgs = ["install", "-g", "--force", `${SUPERSPEC_NPM_PACKAGE}@latest`];
+        writeStderr(`SuperSpec CLI install hit a global bin conflict; retrying with: ${renderCommand("npm", forcedArgs)}\n`);
+        install = run("npm", forcedArgs, { cwd, timeout: 300_000 });
+    }
+    if (install.error || install.status !== 0) {
+        writeStderr(`SuperSpec CLI update failed: ${commandFailure(install)}\n`);
+        return 1;
+    }
+    if (!commandExistsFn("superspec", { cwd })) {
+        writeStderr("SuperSpec CLI update completed, but `superspec` is not resolvable from PATH. Reopen the shell or check npm global bin configuration.\n");
+        return 1;
+    }
+    const rerunArgs = ["update", ...opts.args, "--skip-self-update"];
+    const rerun = run("superspec", rerunArgs, { cwd, timeout: 300_000 });
+    if (rerun.stdout)
+        writeStdout(rerun.stdout);
+    if (rerun.stderr)
+        writeStderr(rerun.stderr);
+    if (rerun.error || rerun.status !== 0) {
+        if (rerun.error && !rerun.stderr)
+            writeStderr(`SuperSpec update rerun failed: ${rerun.error.message}\n`);
+        return rerun.status ?? 1;
+    }
+    return 0;
+}