@peterxiaoyang/superspec 0.1.26 → 0.1.28

package/README.md

@@ -81,6 +81,7 @@ superspec install
 ```
 
 这条命令的意思是：把 SuperSpec 当前可用的工作流入口安装到项目里。
+安装前会检查全局 `openspec` CLI；缺失或版本不一致时，会自动执行 `npm install -g @fission-ai/openspec@1.4.1`，确保后续工作流能调用 OpenSpec。
 当前 beta 会安装 `.superspec/` 引擎目录、`.codex/skills/superspec-*` 阶段入口、`.codex/prompts/*.md` 角色 prompt、`.codex/agents/*.toml` 子智能体配置，补齐 `.codex/config.toml` 的多 agent 开关，并在项目根 `AGENTS.md` 中维护 SuperSpec 轻量门禁片段。`superspec init --scope project` 仍作为兼容别名可用。
 
 Windows PowerShell 如果拦截 npm 的 `.ps1` 脚本，请改用：
@@ -246,7 +247,7 @@ superspec status
 superspec update
 ```
 
-这条命令会先检查 npm 上的 latest 版本；如果有新版，会自动执行全局升级并用新版 CLI 重新同步项目入口。同步内容包括补齐 `.superspec/changes` 运行时目录，把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里，并更新 `AGENTS.md` 中 marker 包裹的 SuperSpec 轻量门禁片段。
+这条命令会先检查 npm 上的 latest 版本；如果有新版，会自动执行全局升级并用新版 CLI 重新同步项目入口。随后会把全局 OpenSpec CLI 拉齐到 `@fission-ai/openspec@1.4.1`。同步内容包括补齐 `.superspec/changes` 运行时目录，把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里，并更新 `AGENTS.md` 中 marker 包裹的 SuperSpec 轻量门禁片段。
 
 ## 进阶信息
 

package/dist/cli.js

@@ -13,6 +13,8 @@ import { recordTestRun, recordTestRunContent } from "./task.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
 import { SUPERSPEC_VERSION } from "./version.js";
 const PACKAGE_NAME = "@peterxiaoyang/superspec";
+const OPENSPEC_PACKAGE_NAME = "@fission-ai/openspec";
+const OPENSPEC_REQUIRED_VERSION = "1.4.1";
 // ===== 参数解析 =====
 function parseArgs(argv) {
     const [command, subcommand, ...rest] = argv;
@@ -110,12 +112,37 @@ class SelfUpdateError extends Error {
         this.latest = latest;
     }
 }
+class OpenSpecDependencyError extends Error {
+    phase;
+    before;
+    constructor(phase, message, before = null) {
+        super(message);
+        this.name = "OpenSpecDependencyError";
+        this.phase = phase;
+        this.before = before;
+    }
+}
 function isTestMode() {
     return process.env.SUPERSPEC_TEST_MODE === "1" || process.env.NODE_ENV === "test";
 }
 function testEnv(name) {
     return isTestMode() ? process.env[name] : undefined;
 }
+function runtimePlatform() {
+    return testEnv("SUPERSPEC_TEST_PLATFORM") ?? process.platform;
+}
+function windowsAwareCommand(name) {
+    return runtimePlatform() === "win32" ? `${name}.cmd` : name;
+}
+function npmCommand() {
+    return windowsAwareCommand("npm");
+}
+function superspecCommand() {
+    return windowsAwareCommand("superspec");
+}
+function openspecCommand() {
+    return windowsAwareCommand("openspec");
+}
 function selfUpdateError(phase, err, latest = null) {
     return new SelfUpdateError(phase, commandErrorMessage(err), latest);
 }
@@ -149,6 +176,112 @@ function selfUpdateFailurePayload(err) {
         },
     };
 }
+function openSpecDependencyFailurePayload(err) {
+    return {
+        ok: false,
+        message: err.message,
+        openspec: {
+            package: OPENSPEC_PACKAGE_NAME,
+            required_version: OPENSPEC_REQUIRED_VERSION,
+            before: err.before,
+            after: null,
+            action: "failed",
+            phase: err.phase,
+        },
+    };
+}
+function parseOpenSpecVersion(output) {
+    const match = output.trim().match(/(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)/);
+    return match?.[1] ?? null;
+}
+let openSpecVersionProbeCount = 0;
+function mockedOpenSpecVersion() {
+    const sequence = testEnv("SUPERSPEC_TEST_OPENSPEC_VERSION_SEQUENCE");
+    if (sequence !== undefined) {
+        const parts = sequence.split("|");
+        const raw = parts[Math.min(openSpecVersionProbeCount, parts.length - 1)]?.trim() ?? "";
+        openSpecVersionProbeCount += 1;
+        if (/^(missing|error)$/i.test(raw))
+            throw new Error("openspec CLI 不可用");
+        return raw;
+    }
+    const explicit = testEnv("SUPERSPEC_TEST_OPENSPEC_VERSION");
+    if (explicit !== undefined) {
+        if (/^(missing|error)$/i.test(explicit.trim()))
+            throw new Error("openspec CLI 不可用");
+        return explicit;
+    }
+    return isTestMode() ? OPENSPEC_REQUIRED_VERSION : undefined;
+}
+function pathOpenSpecVersion() {
+    const mocked = mockedOpenSpecVersion();
+    if (mocked !== undefined) {
+        const parsed = parseOpenSpecVersion(mocked);
+        if (!parsed)
+            throw new Error(`无法解析 openspec --version 输出：${mocked}`);
+        return parsed;
+    }
+    const output = execFileSync(openspecCommand(), ["--version"], {
+        encoding: "utf8",
+        env: process.env,
+    });
+    const parsed = parseOpenSpecVersion(output);
+    if (!parsed)
+        throw new Error(`无法解析 openspec --version 输出：${output.trim()}`);
+    return parsed;
+}
+function installRequiredOpenSpecGlobal(before) {
+    const testError = testEnv("SUPERSPEC_TEST_OPENSPEC_INSTALL_ERROR");
+    if (testError)
+        throw new OpenSpecDependencyError("global_install", testError, before);
+    if (testEnv("SUPERSPEC_TEST_SKIP_OPENSPEC_INSTALL") === "1")
+        return;
+    try {
+        execFileSync(npmCommand(), ["install", "-g", `${OPENSPEC_PACKAGE_NAME}@${OPENSPEC_REQUIRED_VERSION}`], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+    }
+    catch (err) {
+        throw new OpenSpecDependencyError("global_install", `安装 OpenSpec ${OPENSPEC_REQUIRED_VERSION} 失败：${commandErrorMessage(err)}`, before);
+    }
+}
+function ensureOpenSpecCli() {
+    let before = null;
+    try {
+        before = pathOpenSpecVersion();
+    }
+    catch {
+        before = null;
+    }
+    if (before === OPENSPEC_REQUIRED_VERSION) {
+        return {
+            package: OPENSPEC_PACKAGE_NAME,
+            required_version: OPENSPEC_REQUIRED_VERSION,
+            before,
+            after: before,
+            action: "already_satisfied",
+        };
+    }
+    installRequiredOpenSpecGlobal(before);
+    let after;
+    try {
+        after = pathOpenSpecVersion();
+    }
+    catch (err) {
+        throw new OpenSpecDependencyError("version_check", `安装后仍无法读取 openspec --version：${commandErrorMessage(err)}`, before);
+    }
+    if (after !== OPENSPEC_REQUIRED_VERSION) {
+        throw new OpenSpecDependencyError("version_mismatch", `全局 openspec 版本仍为 ${after}，期望 ${OPENSPEC_REQUIRED_VERSION}。请检查 npm 全局 bin 是否在 PATH 前置。`, before);
+    }
+    return {
+        package: OPENSPEC_PACKAGE_NAME,
+        required_version: OPENSPEC_REQUIRED_VERSION,
+        before,
+        after,
+        action: before === null ? "installed" : "updated",
+    };
+}
 function npmLatestVersion() {
     const testError = testEnv("SUPERSPEC_TEST_NPM_VIEW_ERROR");
     if (testError)
@@ -157,7 +290,7 @@ function npmLatestVersion() {
     if (testLatest)
         return testLatest;
     try {
-        const output = execFileSync("npm", ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
+        const output = execFileSync(npmCommand(), ["view", PACKAGE_NAME, "version"], { encoding: "utf8" });
         return output.trim().replace(/^"|"$/g, "");
     }
     catch (err) {
@@ -171,7 +304,7 @@ function installLatestGlobal() {
     if (testEnv("SUPERSPEC_TEST_SKIP_GLOBAL_INSTALL") === "1")
         return;
     try {
-        execFileSync("npm", ["install", "-g", `${PACKAGE_NAME}@latest`], {
+        execFileSync(npmCommand(), ["install", "-g", `${PACKAGE_NAME}@latest`], {
             encoding: "utf8",
             stdio: ["ignore", "pipe", "pipe"],
         });
@@ -198,7 +331,7 @@ function pathCliVersion() {
             throw new Error(`无法解析 superspec --version 输出：${testOutput}`);
         return parsed;
     }
-    const output = execFileSync("superspec", ["--version"], {
+    const output = execFileSync(superspecCommand(), ["--version"], {
         encoding: "utf8",
         env: process.env,
     });
@@ -227,7 +360,7 @@ function rerunUpdatedCli(projectRoot, args) {
     if (testOutput)
         return testOutput;
     try {
-        return execFileSync("superspec", args, {
+        return execFileSync(superspecCommand(), args, {
             cwd: projectRoot,
             encoding: "utf8",
             env: process.env,
@@ -401,13 +534,19 @@ jobs 子命令：
                     return rerun.exitCode;
                 }
             }
-            console.log(JSON.stringify(installProject(projectRoot)));
+            const openspec = ensureOpenSpecCli();
+            console.log(JSON.stringify({
+                ...installProject(projectRoot),
+                openspec,
+            }));
             return 0;
         }
         catch (err) {
             console.log(JSON.stringify(err instanceof SelfUpdateError
                 ? selfUpdateFailurePayload(err)
-                : { ok: false, message: commandErrorMessage(err) }));
+                : err instanceof OpenSpecDependencyError
+                    ? openSpecDependencyFailurePayload(err)
+                    : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }
@@ -421,9 +560,11 @@ jobs 子命令：
                     return rerun.exitCode;
                 }
             }
+            const openspec = ensureOpenSpecCli();
             const result = installProject(projectRoot, { allowLegacyState: true });
             console.log(JSON.stringify({
                 ...result,
+                openspec,
                 message: `SuperSpec ${SUPERSPEC_VERSION} 已更新项目工作流`,
             }));
             return 0;
@@ -431,7 +572,9 @@ jobs 子命令：
         catch (err) {
             console.log(JSON.stringify(err instanceof SelfUpdateError
                 ? selfUpdateFailurePayload(err)
-                : { ok: false, message: commandErrorMessage(err) }));
+                : err instanceof OpenSpecDependencyError
+                    ? openSpecDependencyFailurePayload(err)
+                    : { ok: false, message: commandErrorMessage(err) }));
             return 1;
         }
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.26",
+  "version": "0.1.28",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": {