@peterxiaoyang/superspec 0.1.17-alpha → 0.1.20

package/README.md

@@ -232,13 +232,13 @@ openspec instructions proposal --change <change>
 superspec status
 ```
 
-更新当前 beta CLI：
+同步当前项目的 SuperSpec 工作流入口：
 
 ```bash
 superspec update
 ```
 
-这条命令只检查当前 `.superspec/changes` 运行时是否已经是新引擎布局；真正升级全局 npm 包仍需使用 `npm install -g @peterxiaoyang/superspec@<version>`。
+这条命令会补齐 `.superspec/changes` 运行时目录，并把当前 CLI 内置的 `.codex/skills/superspec-*`、`.codex/prompts/*.md`、`.codex/agents/*.toml` 同步到项目里。真正升级全局 npm 包仍需使用 `npm install -g @peterxiaoyang/superspec@<version>`。
 
 ## 进阶信息
 

package/dist/cli.js

@@ -9,6 +9,7 @@ import { proposeReady, commitTransition, transitionInit, transitionExplore, star
 import { recordJobSubmit, recordUserDecision, jobsList, jobsPacket } from "./record.js";
 import { recordTestRun } from "./task.js";
 import { probeOpenSpec, openspecStatus, changeRoot } from "./openspec.js";
+import { SUPERSPEC_VERSION } from "./version.js";
 // ===== 参数解析 =====
 function parseArgs(argv) {
     const [command, subcommand, ...rest] = argv;
@@ -44,7 +45,7 @@ function parseFlags(args) {
 async function main(argv) {
     // --help / 无参数 → 打印用法
     if (argv.length === 0 || argv.includes("--help") || argv.includes("-h")) {
-        console.log(`SuperSpec 流程引擎 0.1.16-alpha
+        console.log(`SuperSpec 流程引擎 ${SUPERSPEC_VERSION}
 
 用法：superspec <命令> [选项]
 
@@ -55,7 +56,7 @@ async function main(argv) {
   jobs <子命令> --change <C>        工作项管理（见下）
   install                           安装项目工作流入口
   init --scope project              install 的兼容别名
-  update                           更新 SuperSpec
+  update                           同步项目工作流模板
   version                          版本号
 
 transition 子命令：
@@ -75,7 +76,7 @@ jobs 子命令：
     }
     // version
     if (argv[0] === "version" || argv[0] === "--version" || argv[0] === "-v") {
-        console.log("SuperSpec 0.1.16-alpha");
+        console.log(`SuperSpec ${SUPERSPEC_VERSION}`);
         return 0;
     }
     const { command, subcommand, opts } = parseArgs(argv);
@@ -102,20 +103,21 @@ jobs 子命令：
         }
     }
     if (command === "update") {
-        // 检测是否从老版 update 过来
-        const { existsSync } = await import("node:fs");
-        const isLegacyUpdate = !existsSync(join(projectRoot, ".superspec", "changes"));
-        if (isLegacyUpdate) {
+        try {
+            const result = installProject(projectRoot, { allowLegacyState: true });
+            console.log(JSON.stringify({
+                ...result,
+                message: `SuperSpec ${SUPERSPEC_VERSION} 已更新项目工作流`,
+            }));
+            return 0;
+        }
+        catch (err) {
             console.log(JSON.stringify({
                 ok: false,
-                message: "SuperSpec 0.1.16-alpha 是全新引擎，不能从 0.x 直接 update。\n" +
-                    "请用 npm install -g @peterxiaoyang/superspec@0.1.16-alpha 手动安装。\n" +
-                    "现有 change 请先用 0.1.x 完成归档。",
+                message: err.message,
             }));
             return 1;
         }
-        console.log(JSON.stringify({ ok: true, message: "已是最新版本 0.1.16-alpha" }));
-        return 0;
     }
     const change = opts.change;
     if (!change && command !== "status") {

package/dist/install.d.ts

@@ -15,5 +15,6 @@ export interface InstallResult {
 }
 export interface InstallOptions {
     templateRoot?: string;
+    allowLegacyState?: boolean;
 }
 export declare function installProject(projectRoot: string, options?: InstallOptions): InstallResult;

package/dist/install.js

@@ -1,5 +1,6 @@
-import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { SUPERSPEC_VERSION } from "./version.js";
 export const WORKFLOW_SKILLS = [
     "superspec-explore",
     "superspec-propose",
@@ -58,13 +59,23 @@ function assertWorkflowTemplates(templateRoot) {
         throw new Error(`workflow templates missing: ${missing.join(", ")}`);
     }
 }
+function writeBundledFile(src, dest) {
+    mkdirSync(dirname(dest), { recursive: true });
+    const next = readFileSync(src, "utf8");
+    if (existsSync(dest)) {
+        const current = readFileSync(dest, "utf8");
+        if (current === next)
+            return;
+        writeFileSync(`${dest}.bak`, current);
+    }
+    writeFileSync(dest, next);
+}
 function copySkills(templateRoot, projectRoot) {
     const skillsDest = join(projectRoot, ".codex", "skills");
     const installedSkills = [];
     for (const skill of WORKFLOW_SKILLS) {
         const src = join(templateRoot, "skills", skill, "SKILL.md");
-        mkdirSync(join(skillsDest, skill), { recursive: true });
-        copyFileSync(src, join(skillsDest, skill, "SKILL.md"));
+        writeBundledFile(src, join(skillsDest, skill, "SKILL.md"));
         installedSkills.push(skill);
     }
     return installedSkills;
@@ -74,8 +85,7 @@ function copyPrompts(templateRoot, projectRoot) {
     const installedPrompts = [];
     for (const prompt of WORKFLOW_PROMPTS) {
         const src = join(templateRoot, "prompts", prompt);
-        mkdirSync(promptsDest, { recursive: true });
-        copyFileSync(src, join(promptsDest, prompt));
+        writeBundledFile(src, join(promptsDest, prompt));
         installedPrompts.push(prompt);
     }
     return installedPrompts;
@@ -85,12 +95,88 @@ function copyAgents(templateRoot, projectRoot) {
     const installedAgents = [];
     for (const agent of WORKFLOW_AGENTS) {
         const src = join(templateRoot, "agents", agent);
-        mkdirSync(agentsDest, { recursive: true });
-        copyFileSync(src, join(agentsDest, agent));
+        writeBundledFile(src, join(agentsDest, agent));
         installedAgents.push(agent);
     }
     return installedAgents;
 }
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isLegacySuperspecHook(value) {
+    return isRecord(value)
+        && typeof value.command === "string"
+        && /\bsuperspec-hook\b/.test(value.command);
+}
+function removeLegacySuperspecHookCommands(hooks) {
+    if (!isRecord(hooks))
+        return { hooks, removed: 0 };
+    let removed = 0;
+    const nextHooks = { ...hooks };
+    for (const [eventName, eventValue] of Object.entries(hooks)) {
+        if (!Array.isArray(eventValue))
+            continue;
+        const nextEvent = [];
+        for (const entry of eventValue) {
+            if (!isRecord(entry) || !Array.isArray(entry.hooks)) {
+                nextEvent.push(entry);
+                continue;
+            }
+            const keptCommands = entry.hooks.filter(command => {
+                if (!isLegacySuperspecHook(command))
+                    return true;
+                removed += 1;
+                return false;
+            });
+            if (keptCommands.length > 0) {
+                nextEvent.push({ ...entry, hooks: keptCommands });
+            }
+        }
+        if (nextEvent.length > 0)
+            nextHooks[eventName] = nextEvent;
+        else
+            delete nextHooks[eventName];
+    }
+    return { hooks: nextHooks, removed };
+}
+function hasUserHookContent(config) {
+    return Object.entries(config).some(([key, value]) => {
+        if (key === "superspec")
+            return false;
+        if (key === "hooks" && isRecord(value) && Object.keys(value).length === 0)
+            return false;
+        return true;
+    });
+}
+function migrateLegacyManagedHooks(projectRoot) {
+    const hooksPath = join(projectRoot, ".codex", "hooks.json");
+    if (!existsSync(hooksPath))
+        return;
+    const current = readFileSync(hooksPath, "utf8");
+    let parsed;
+    try {
+        parsed = JSON.parse(current);
+    }
+    catch {
+        return;
+    }
+    if (!isRecord(parsed) || !isRecord(parsed.superspec) || parsed.superspec.managed !== true)
+        return;
+    const migrated = removeLegacySuperspecHookCommands(parsed.hooks);
+    if (migrated.removed === 0)
+        return;
+    writeFileSync(`${hooksPath}.bak`, current);
+    const nextConfig = { ...parsed, hooks: migrated.hooks };
+    delete nextConfig.superspec;
+    if (isRecord(nextConfig.hooks) && Object.keys(nextConfig.hooks).length === 0) {
+        delete nextConfig.hooks;
+    }
+    if (!hasUserHookContent(nextConfig)) {
+        rmSync(hooksPath);
+        return;
+    }
+    writeFileSync(hooksPath, `${JSON.stringify(nextConfig, null, 2)}\n`);
+}
 function insertMissingTableEntries(content, table, entries) {
     const tablePattern = new RegExp(`^\\[${table}\\]\\s*$`, "m");
     const tableMatch = tablePattern.exec(content);
@@ -157,10 +243,10 @@ function ensureOpenSpecChineseContext(projectRoot) {
     return OPENSPEC_CONFIG_PATH;
 }
 export function installProject(projectRoot, options = {}) {
-    if (legacyStateFound(projectRoot)) {
+    if (!options.allowLegacyState && legacyStateFound(projectRoot)) {
         throw new Error("检测到老版 SuperSpec (0.x) 的状态文件。\n" +
-            "SuperSpec 0.1.16-alpha 是全新引擎，不兼容 0.x 的状态格式。\n" +
-            "请先用老版（0.1.x）完成或归档现有 change，再安装 0.1.16-alpha。\n" +
+            `SuperSpec ${SUPERSPEC_VERSION} 是全新引擎，不兼容 0.x 的状态格式。\n` +
+            `请先用老版（0.1.x）完成或归档现有 change，再安装 ${SUPERSPEC_VERSION}。\n` +
             "或在全新项目目录中安装。");
     }
     const templateRoot = options.templateRoot ?? defaultTemplateRoot();
@@ -170,9 +256,10 @@ export function installProject(projectRoot, options = {}) {
     const gitignorePath = join(engineDir, ".gitignore");
     if (!existsSync(gitignorePath))
         writeFileSync(gitignorePath, "changes/\n*.log\n*.tmp\n");
+    migrateLegacyManagedHooks(projectRoot);
     return {
         ok: true,
-        message: "SuperSpec 0.1.16-alpha 已安装",
+        message: `SuperSpec ${SUPERSPEC_VERSION} 已安装`,
         installed: {
             engine_dir: ".superspec/",
             skills: copySkills(templateRoot, projectRoot),

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare const SUPERSPEC_VERSION: string;

package/dist/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from "node:module";
+const require = createRequire(import.meta.url);
+function readPackageVersion() {
+    const pkg = require("../package.json");
+    if (!pkg.version)
+        throw new Error("package.json 缺少 version 字段");
+    return pkg.version;
+}
+export const SUPERSPEC_VERSION = readPackageVersion();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@peterxiaoyang/superspec",
-  "version": "0.1.17-alpha",
+  "version": "0.1.20",
   "description": "SuperSpec 流程引擎 — transition engine with lightweight fact-sync",
   "type": "module",
   "engines": { "node": ">=20.19.0" },