sdd-flow-kit 1.1.0 → 1.2.1

package/README.md

@@ -71,8 +71,43 @@ npx sdd-flow-kit doctor --agent cursor
 > 完整环境（分支切换 + opsx-workflow）请另执行：`npx sdd-flow-kit install -y`  
 > 跳过 postinstall：`SDD_FLOW_KIT_SKIP_POSTINSTALL=1 pnpm add -D sdd-flow-kit`
 
+##### `pnpm add` 后依赖全被删掉（`Packages: +1 -932`）
+
+**原因**：`pnpm` 会按当前 `package.json` **同步** `node_modules`。若 manifest 里只剩 `sdd-flow-kit`（或文件被误保存成几行空壳），就会卸载其它所有包——**不是** `pnpm add` 单独删包，而是 manifest 已不完整。
+
+**恢复**（在业务仓如 `adInsight-web/frontend`）：
+
+1. 用 Git 恢复完整 `package.json`：`git checkout -- package.json`
+2. 重装：`pnpm install`
+3. 再装 kit（建议 **≥ 1.1.2**，且必须在有完整 `package.json` 的目录执行）：
+   - `cd frontend && pnpm add -D sdd-flow-kit@1.1.2`
+   - 或本地联调：`pnpm add -D file:../../sdd-flow-kit`
+
+**v1.1.2+ 防护**：`repairOpsxDeliveryScripts` 仅合并 `scripts`，写入前检查依赖条数与文件体积；`postinstall` 不再改 `package.json`，且必须有 `INIT_CWD` 才运行。
+
+**pnpm v10 构建脚本**：若出现 `Ignored build scripts: sdd-flow-kit`，执行 `pnpm approve-builds` 选中 `sdd-flow-kit`，或安装后手动：`node ./node_modules/sdd-flow-kit/dist/postinstall.js`
+
 #### 使用说明
 
+##### 安装根：cd 到哪，装到哪（v1.2+）
+
+默认 **`installRoot = 你执行命令时的当前目录`**（`process.cwd()`），也可用 `--project-root` / `SDD_FLOW_KIT_INSTALL_ROOT` 指定。
+
+| 你 cd 到 | 会安装到 |
+|----------|----------|
+| `adInsight-web/frontend` | `frontend/package.json`、`.cursor/skills`、`.opsx`、`pnpm run opsx:delivery-pipeline` |
+| `adInsight-web`（仓库根） | 仓库根（需根目录也有 `package.json`，否则会失败） |
+
+```bash
+cd /path/to/adInsight-web/frontend
+npx sdd-flow-kit install --project ADI -y
+npx sdd-flow-kit run --product ADI --version 2.3.2 -y
+```
+
+**PRD / gate 的 `--project-root`**：与安装根相同；若 `openspec/` 在上级目录，工具会**向上查找**已有 `openspec/PRD`（不把安装写到上级）。
+
+旧行为（在仓库根执行时自动落到 `frontend/`）：设置 `SDD_FLOW_KIT_LEGACY_MONOREPO=1`。
+
 ##### 脚本门禁（v1.1+，**不依赖自然语言**）
 
 `run` 会在 `openspec/PRD/<runId>/NEXT.md` 写入**必须按顺序执行的命令**。AI 与人都以 **exit code** 为准：失败则不得进入下一阶段、不得改 `src/`。

package/dist/cli.js

@@ -16,6 +16,8 @@ const runGate_1 = require("./steps/runGate");
 const runPhaseAdvance_1 = require("./steps/runPhaseAdvance");
 const runPropose_1 = require("./steps/runPropose");
 const runDeliver_1 = require("./steps/runDeliver");
+const bootstrap_1 = require("./core/bootstrap");
+const projectRoots_1 = require("./core/projectRoots");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
 function getArgValue(flag) {
     const idx = process_1.default.argv.indexOf(flag);
@@ -34,9 +36,11 @@ function printHelp() {
         "1) 生成流程产物骨架：",
         "   npx sdd-flow-kit start --product ADI --version 2.3.2",
         "",
-        "2) 安装流程到当前项目（推荐，安装即用）：",
-        "   npx sdd-flow-kit install",
-        "   (等价于: npx sdd-flow-kit setup)",
+        "2) 安装到当前目录（全量：SDD + OPSX + Superpowers，推荐）：",
+        "   cd <你的项目目录>   # 如 adInsight-web/frontend",
+        "   pnpm add -D sdd-flow-kit",
+        "   npx sdd-flow-kit install --project ADI -y",
+        "   本地 OPSX: SDD_OPSX_WORKFLOW_PACKAGE=file:../../opsx-workflow npx sdd-flow-kit install -y",
         "",
         "3) 生成骨架并进入可执行模式（推荐）：",
         "   npx sdd-flow-kit run --product ADI --version 2.3.2 --agent claude-code",
@@ -63,7 +67,9 @@ function printHelp() {
         "   npx sdd-flow-kit deliver --project-root . --run-id <runId> --change <name>",
         "",
         "可选参数：",
-        "   --projectRoot <path>   目标项目根目录（默认当前目录）",
+        "   --projectRoot <path>   目标项目根目录（默认当前目录 = 安装根，cd 到哪装到哪）",
+        "   环境变量 SDD_FLOW_KIT_INSTALL_ROOT 可覆盖安装根（绝对路径）",
+        "   环境变量 SDD_FLOW_KIT_LEGACY_MONOREPO=1 恢复「仓库根无 package.json 时落到 frontend/」",
         "   --agent <name>         cursor | claude-code | codex | openclaw | custom（默认 claude-code）",
         "   --branch <name>        开发分支；不存在会自动创建",
         "   --project <name>       OMS | ADI | 欢盟 | AD Tools（默认 OMS，用于生成 docs/*-doc-skill）",
@@ -138,6 +144,26 @@ async function main() {
         process_1.default.exitCode = 1;
         return;
     }
+    const skipBootstrap = process_1.default.env.SDD_FLOW_KIT_SKIP_BOOTSTRAP === "1";
+    const bootstrapCommands = new Set([
+        "doctor",
+        "ensure-opsx",
+        "run",
+        "invoke",
+        "install",
+        "setup",
+        "gate",
+        "phase",
+        "propose",
+        "deliver",
+    ]);
+    if (!skipBootstrap && !dryRun && bootstrapCommands.has(cmd)) {
+        await (0, bootstrap_1.bootstrapProjectIfNeeded)({
+            projectRoot,
+            agent,
+            projectKind: projectKind,
+        });
+    }
     if (cmd === "gate") {
         const expect = getArgValue("--expect");
         if (!expect || !GATE_EXPECTS.includes(expect)) {
@@ -242,20 +268,13 @@ async function main() {
             // eslint-disable-next-line no-console
             console.log(JSON.stringify({ command: "doctor", projectRoot: path_1.default.resolve(projectRoot), result: doctor }, null, 2));
         }
-        if (cmd === "ensure-opsx" && !dryRun) {
-            await (0, setupProject_1.setupProject)({
-                projectRoot,
-                agent,
-                yes: true,
-                light: true,
-                projectKind: projectKind,
-            });
-        }
         if (!doctor.ok)
             process_1.default.exitCode = 1;
         return;
     }
     if (cmd === "setup" || cmd === "install") {
+        // eslint-disable-next-line no-console
+        console.log(`[sdd-flow-kit] 安装根 installRoot=${(0, projectRoots_1.resolveInstallRoot)(projectRoot)} (cwd=${process_1.default.cwd()})`);
         const result = await (0, setupProject_1.setupProject)({
             projectRoot,
             agent,
@@ -292,7 +311,7 @@ async function main() {
             const text = (fromFlag !== null && fromFlag !== void 0 ? fromFlag : raw).trim();
             const parsed = (0, invokeFlow_1.parseInvokeText)(text);
             if (!parsed) {
-                throw new Error("invoke 解析失败，请使用：开发 ADI 2.3.2 需求");
+                throw new Error("invoke 解析失败，示例：开发 ADI 2.3.2 需求 | 进行ADI_2.3.2版本开发");
             }
             const options = (0, invokeFlow_1.toRunOptions)({
                 parsed,
@@ -326,6 +345,8 @@ async function main() {
         console.log(`已生成 SDD 流程产物骨架：openspec/PRD/${scaffoldRunId}/`);
         return;
     }
+    // eslint-disable-next-line no-console
+    console.log(`[sdd-flow-kit] 安装根 installRoot=${(0, projectRoots_1.resolveInstallRoot)(projectRoot)} (cwd=${process_1.default.cwd()})`);
     const result = await (0, runFlow_1.runFlow)({
         product,
         version,
@@ -342,7 +363,7 @@ async function main() {
     // eslint-disable-next-line no-console
     console.log(`流程已初始化：openspec/PRD/${result.runId}/`);
     // eslint-disable-next-line no-console
-    console.log(`请打开 openspec/PRD/${result.runId}/NEXT.md，按脚本顺序执行 gate / phase / propose / deliver。`);
+    console.log(`请打开 openspec/PRD/${result.runId}/NEXT.md，严格按 gate→phase→propose→deliver 执行；确认点前禁止改 src/。`);
     // eslint-disable-next-line no-console
     console.log(`agent=${result.adapterName}, cli=${result.adapterAvailable ? "detected" : "missing"}, autoExecute=${result.executed ? "yes" : "manual"}`);
     // eslint-disable-next-line no-console

package/dist/core/bootstrap.js

@@ -0,0 +1,58 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bootstrapProjectIfNeeded = bootstrapProjectIfNeeded;
+const path_1 = __importDefault(require("path"));
+const inferProject_1 = require("./inferProject");
+const packageJsonPatch_1 = require("./packageJsonPatch");
+const opsxDelivery_1 = require("./opsxDelivery");
+const projectRoots_1 = require("./projectRoots");
+const setupProject_1 = require("../steps/setupProject");
+/**
+ * pnpm v10 常拦截 postinstall；首次跑 CLI 时补全 SDD + OPSX 全栈（不切分支）。
+ */
+async function bootstrapProjectIfNeeded(options) {
+    var _a;
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    if (await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot)) {
+        return false;
+    }
+    if (options.dryRun) {
+        return true;
+    }
+    const kind = (_a = options.projectKind) !== null && _a !== void 0 ? _a : (await (0, inferProject_1.inferProjectKind)(installRoot));
+    // eslint-disable-next-line no-console
+    console.log("[sdd-flow-kit] 检测到 OPSX 未就绪，正在自动 bootstrap（等价 install -y）…");
+    const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+    const pnpmPatched = await (0, packageJsonPatch_1.ensurePnpmAllowSddFlowKitBuild)(path_1.default.join(pkgRoot, "package.json"));
+    if (pnpmPatched) {
+        // eslint-disable-next-line no-console
+        console.log("[sdd-flow-kit] 已写入 pnpm.onlyBuiltDependencies: sdd-flow-kit；下次 pnpm install 将执行 postinstall");
+    }
+    await (0, setupProject_1.setupProject)({
+        projectRoot: installRoot,
+        agent: options.agent,
+        yes: true,
+        light: false,
+        skipGit: true,
+        projectKind: kind !== null && kind !== void 0 ? kind : "ADI",
+    });
+    if (!(await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot))) {
+        await (0, opsxDelivery_1.ensureOpsxWorkflow)({
+            projectRoot: installRoot,
+            agent: options.agent,
+        });
+    }
+    const ready = await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot);
+    if (ready) {
+        // eslint-disable-next-line no-console
+        console.log("[sdd-flow-kit] bootstrap 完成：SDD + OPSX 已就绪");
+    }
+    else {
+        // eslint-disable-next-line no-console
+        console.warn("[sdd-flow-kit] bootstrap 后仍有检查未通过，请执行: npx sdd-flow-kit doctor --agent cursor");
+    }
+    return true;
+}

package/dist/core/opsxDelivery.js

@@ -3,6 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOpsxWorkflowPackage = resolveOpsxWorkflowPackage;
 exports.deliveryPipelineNpmScripts = deliveryPipelineNpmScripts;
 exports.pathExists = pathExists;
 exports.resolveOpsxAgent = resolveOpsxAgent;
@@ -14,7 +15,12 @@ exports.collectDeliverySetupChecks = collectDeliverySetupChecks;
 const child_process_1 = require("child_process");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
-const fs_1 = require("./fs");
+const packageJsonPatch_1 = require("./packageJsonPatch");
+const projectRoots_1 = require("./projectRoots");
+const opsxWorkflowPackage_1 = require("./opsxWorkflowPackage");
+function resolveOpsxWorkflowPackage() {
+    return (0, opsxWorkflowPackage_1.resolveOpsxWorkflowPackageForCwd)(process.cwd());
+}
 const DELIVERY_SCRIPT_REL = ".cursor/skills/opsx-dev-delivery-pipeline/scripts/opsx-delivery-pipeline.sh";
 function deliveryPipelineNpmScripts() {
     const full = `bash ${DELIVERY_SCRIPT_REL}`;
@@ -44,7 +50,7 @@ async function resolveOpsxAgent(projectRoot, preferred) {
         return "claude-code";
     return preferred;
 }
-/** 将 package.json 中过期的 poquan-delivery-pipeline 脚本修正为 opsx-dev-delivery-pipeline */
+/** 将 package.json 中过期的 poquan 脚本修正为 opsx-dev-delivery-pipeline（仅合并 scripts） */
 async function repairOpsxDeliveryScripts(projectRoot) {
     const pkgPath = path_1.default.join(projectRoot, "package.json");
     if (!(await pathExists(pkgPath)))
@@ -54,29 +60,35 @@ async function repairOpsxDeliveryScripts(projectRoot) {
         return false;
     const { full, short } = deliveryPipelineNpmScripts();
     const text = await promises_1.default.readFile(pkgPath, "utf8");
-    const pkg = JSON.parse(text);
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
     if (!pkg.scripts)
         pkg.scripts = {};
-    let changed = false;
     const needsFix = (v) => !v || v.includes("poquan-dev-delivery-pipeline") || v.includes("poquan-delivery-pipeline");
-    if (needsFix(pkg.scripts["opsx:delivery-pipeline"])) {
-        pkg.scripts["opsx:delivery-pipeline"] = full;
-        changed = true;
-    }
+    const updates = {};
+    if (needsFix(pkg.scripts["opsx:delivery-pipeline"]))
+        updates["opsx:delivery-pipeline"] = full;
     if (needsFix(pkg.scripts["opsx:delivery-pipeline:short"])) {
-        pkg.scripts["opsx:delivery-pipeline:short"] = short;
-        changed = true;
+        updates["opsx:delivery-pipeline:short"] = short;
     }
-    if (!changed)
+    if (Object.keys(updates).length === 0)
         return false;
-    await (0, fs_1.writeTextFileEnsuredDir)(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-    return true;
+    const result = await (0, packageJsonPatch_1.patchPackageJsonScripts)(pkgPath, updates, {
+        minDependencyCount: 2,
+        minBytes: 120,
+    });
+    return result.ok && result.changed;
 }
 function hasCommand(cmd) {
     return (0, child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" }).status === 0;
 }
 function buildOpsxWorkflowSetupCommand(projectRoot, agent) {
-    const baseArgs = ["@lixin5257xxx/opsx-workflow", "setup"];
+    const baseArgs = [resolveOpsxWorkflowPackage(), "setup"];
     if (agent === "cursor") {
         return {
             cmd: "npx",
@@ -92,13 +104,16 @@ function buildOpsxWorkflowSetupCommand(projectRoot, agent) {
     return { cmd: "npx", args: [...baseArgs, "--editor", "codex", "-y"] };
 }
 async function isOpsxApplyReady(projectRoot) {
-    const checks = await collectDeliverySetupChecks(projectRoot);
+    const installRoot = await (0, projectRoots_1.resolvePackageRoot)((0, projectRoots_1.resolveInstallRoot)(projectRoot));
+    const checks = await collectDeliverySetupChecks(installRoot);
     return checks.every((c) => c.ok);
 }
 /** 缺 openspec/TDD/Playwright 工作流时安装 @lixin5257xxx/opsx-workflow，并修复 delivery 脚本 */
 async function ensureOpsxWorkflow(options) {
+    var _a;
+    const installRoot = await (0, projectRoots_1.resolvePackageRoot)((0, projectRoots_1.resolveInstallRoot)(options.projectRoot));
     const plannedActions = [];
-    let checks = await collectDeliverySetupChecks(options.projectRoot);
+    let checks = await collectDeliverySetupChecks(installRoot);
     if (checks.every((c) => c.ok)) {
         return {
             ready: true,
@@ -108,8 +123,8 @@ async function ensureOpsxWorkflow(options) {
             plannedActions,
         };
     }
-    const agent = await resolveOpsxAgent(options.projectRoot, options.agent);
-    const { cmd, args } = buildOpsxWorkflowSetupCommand(options.projectRoot, agent);
+    const agent = await resolveOpsxAgent(installRoot, options.agent);
+    const { cmd, args } = buildOpsxWorkflowSetupCommand(installRoot, agent);
     plannedActions.push(`missing opsx apply stack → run: ${cmd} ${args.join(" ")}`);
     if (options.dryRun) {
         return {
@@ -121,18 +136,21 @@ async function ensureOpsxWorkflow(options) {
         };
     }
     const ret = (0, child_process_1.spawnSync)(cmd, args, {
-        cwd: options.projectRoot,
+        cwd: installRoot,
         stdio: "inherit",
         env: process.env,
     });
     if (ret.status !== 0) {
-        throw new Error(`opsx-workflow 安装失败：${cmd} ${args.join(" ")}`);
+        const hint = ((_a = process.env.SDD_OPSX_WORKFLOW_PACKAGE) === null || _a === void 0 ? void 0 : _a.trim()) ?
+            ""
+            : " 本地 OPSX 可设: SDD_OPSX_WORKFLOW_PACKAGE=file:../../opsx-workflow";
+        throw new Error(`opsx-workflow 安装失败：${cmd} ${args.join(" ")}${hint}`);
     }
-    const repairedScripts = await repairOpsxDeliveryScripts(options.projectRoot);
+    const repairedScripts = await repairOpsxDeliveryScripts(installRoot);
     if (repairedScripts) {
         plannedActions.push("repaired package.json opsx:delivery-pipeline scripts");
     }
-    checks = await collectDeliverySetupChecks(options.projectRoot);
+    checks = await collectDeliverySetupChecks(installRoot);
     return {
         ready: checks.every((c) => c.ok),
         workflowInstalled: true,
@@ -141,45 +159,54 @@ async function ensureOpsxWorkflow(options) {
         plannedActions,
     };
 }
-async function collectDeliverySetupChecks(projectRoot) {
+async function collectDeliverySetupChecks(installRoot) {
     var _a, _b, _c, _d, _e, _f;
     const checks = [];
+    const root = (0, projectRoots_1.resolveInstallRoot)(installRoot);
+    const openspecRoot = await (0, projectRoots_1.resolveOpenspecRoot)(root);
+    checks.push({
+        name: "install-root",
+        ok: true,
+        detail: `安装根=${root}`,
+    });
     checks.push({
         name: "openspec-dir",
-        ok: await pathExists(path_1.default.join(projectRoot, "openspec")),
-        detail: "openspec/ 目录",
+        ok: await pathExists(path_1.default.join(openspecRoot, "openspec")),
+        detail: openspecRoot === root ? "openspec/ 目录（安装根）" : `openspec/ 目录（上级 ${openspecRoot}）`,
     });
+    const openspecOk = hasCommand("openspec") ||
+        (0, child_process_1.spawnSync)("npx", ["openspec", "--version"], { stdio: "ignore", cwd: root }).status === 0;
     checks.push({
         name: "openspec-cli",
-        ok: hasCommand("openspec"),
-        detail: "openspec CLI（npx openspec 或全局安装）",
+        ok: openspecOk,
+        detail: openspecOk ? "openspec CLI 可用" : "请安装 openspec CLI 或执行 opsx-workflow setup",
     });
-    const skillPath = path_1.default.join(projectRoot, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md");
+    const skillPath = path_1.default.join(root, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md");
     checks.push({
         name: "opsx-dev-delivery-pipeline-skill",
         ok: await pathExists(skillPath),
         detail: skillPath,
     });
-    const tddPath = path_1.default.join(projectRoot, ".cursor", "skills", "tdd-script", "SKILL.md");
+    const tddPath = path_1.default.join(root, ".cursor", "skills", "tdd-script", "SKILL.md");
     checks.push({
         name: "tdd-script-skill",
         ok: await pathExists(tddPath),
         detail: tddPath,
     });
-    const applyPath = path_1.default.join(projectRoot, ".cursor", "skills", "openspec-apply-change", "SKILL.md");
+    const applyPath = path_1.default.join(root, ".cursor", "skills", "openspec-apply-change", "SKILL.md");
     checks.push({
         name: "openspec-apply-change-skill",
         ok: await pathExists(applyPath),
         detail: applyPath,
     });
-    const pipelineScript = path_1.default.join(projectRoot, DELIVERY_SCRIPT_REL);
+    const pipelineScript = path_1.default.join(root, DELIVERY_SCRIPT_REL);
     checks.push({
         name: "delivery-pipeline-script",
         ok: await pathExists(pipelineScript),
         detail: pipelineScript,
     });
     try {
-        const pkgText = await promises_1.default.readFile(path_1.default.join(projectRoot, "package.json"), "utf8");
+        const pkgText = await promises_1.default.readFile(path_1.default.join(root, "package.json"), "utf8");
         const pkg = JSON.parse(pkgText);
         const cmd = (_b = (_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a["opsx:delivery-pipeline"]) !== null && _b !== void 0 ? _b : "";
         const ok = cmd.includes("opsx-dev-delivery-pipeline") &&
@@ -199,10 +226,10 @@ async function collectDeliverySetupChecks(projectRoot) {
         });
     }
     try {
-        const cfgText = await promises_1.default.readFile(path_1.default.join(projectRoot, ".opsx", "config.json"), "utf8");
+        const cfgText = await promises_1.default.readFile(path_1.default.join(root, ".opsx", "config.json"), "utf8");
         const cfg = JSON.parse(cfgText);
         const skillsDir = (_c = cfg.skillsDir) !== null && _c !== void 0 ? _c : "";
-        const hasCursorDelivery = await pathExists(path_1.default.join(projectRoot, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md"));
+        const hasCursorDelivery = await pathExists(path_1.default.join(root, ".cursor", "skills", "opsx-dev-delivery-pipeline", "SKILL.md"));
         const nameOk = ((_d = cfg.deliveryPipeline) === null || _d === void 0 ? void 0 : _d.skillName) === "opsx-dev-delivery-pipeline";
         const dirOk = (hasCursorDelivery && skillsDir.includes(".cursor")) ||
             (!hasCursorDelivery && (skillsDir.includes(".cursor") || skillsDir.includes(".claude")));
@@ -222,7 +249,7 @@ async function collectDeliverySetupChecks(projectRoot) {
         });
     }
     try {
-        const pkgText = await promises_1.default.readFile(path_1.default.join(projectRoot, "package.json"), "utf8");
+        const pkgText = await promises_1.default.readFile(path_1.default.join(root, "package.json"), "utf8");
         const pkg = JSON.parse(pkgText);
         const deps = { ...pkg.dependencies, ...pkg.devDependencies };
         const hasPw = Boolean(deps["@playwright/test"] || deps.playwright);
@@ -239,7 +266,7 @@ async function collectDeliverySetupChecks(projectRoot) {
             detail: "无法读取 package.json 检查 Playwright",
         });
     }
-    const agentsMd = path_1.default.join(projectRoot, "AGENTS.md");
+    const agentsMd = path_1.default.join(root, "AGENTS.md");
     checks.push({
         name: "agents-md",
         ok: await pathExists(agentsMd),

package/dist/core/opsxWorkflowPackage.js

@@ -0,0 +1,23 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveOpsxWorkflowPackageForCwd = resolveOpsxWorkflowPackageForCwd;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+/** 本地联调 SDD_OPSX_WORKFLOW_PACKAGE=file:../../opsx-workflow；不存在则回退 npm 包 */
+function resolveOpsxWorkflowPackageForCwd(cwd) {
+    var _a;
+    const fromEnv = (_a = process.env.SDD_OPSX_WORKFLOW_PACKAGE) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnv === null || fromEnv === void 0 ? void 0 : fromEnv.startsWith("file:")) {
+        const localPath = path_1.default.resolve(cwd, fromEnv.slice("file:".length));
+        if (fs_1.default.existsSync(localPath)) {
+            return fromEnv;
+        }
+        // eslint-disable-next-line no-console
+        console.warn(`[sdd-flow-kit] SDD_OPSX_WORKFLOW_PACKAGE=${fromEnv} 不存在 (${localPath})，改用 @lixin5257xxx/opsx-workflow`);
+        return "@lixin5257xxx/opsx-workflow";
+    }
+    return fromEnv || "@lixin5257xxx/opsx-workflow";
+}

package/dist/core/packageJsonPatch.js

@@ -0,0 +1,89 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countPackageDependencies = countPackageDependencies;
+exports.patchPackageJsonScripts = patchPackageJsonScripts;
+exports.ensurePnpmAllowSddFlowKitBuild = ensurePnpmAllowSddFlowKitBuild;
+const promises_1 = __importDefault(require("fs/promises"));
+const fs_1 = require("./fs");
+function countPackageDependencies(pkg) {
+    const deps = pkg.dependencies;
+    const devDeps = pkg.devDependencies;
+    return Object.keys(deps !== null && deps !== void 0 ? deps : {}).length + Object.keys(devDeps !== null && devDeps !== void 0 ? devDeps : {}).length;
+}
+async function patchPackageJsonScripts(pkgPath, scriptUpdates, options = {}) {
+    var _a, _b, _c, _d;
+    const minDependencyCount = (_a = options.minDependencyCount) !== null && _a !== void 0 ? _a : 1;
+    const minBytes = (_b = options.minBytes) !== null && _b !== void 0 ? _b : 80;
+    const minSizeRatio = (_c = options.minSizeRatio) !== null && _c !== void 0 ? _c : 0.5;
+    let text;
+    try {
+        text = await promises_1.default.readFile(pkgPath, "utf8");
+    }
+    catch {
+        return { ok: false, reason: "package.json 不存在或不可读" };
+    }
+    if (text.length < minBytes) {
+        return { ok: false, reason: `package.json 过小（${text.length} 字节）` };
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        return { ok: false, reason: "package.json 不是合法 JSON" };
+    }
+    if (countPackageDependencies(pkg) < minDependencyCount) {
+        return { ok: false, reason: "dependencies 过少" };
+    }
+    const beforeKeys = Object.keys(pkg);
+    const scripts = (_d = pkg.scripts) !== null && _d !== void 0 ? _d : {};
+    let changed = false;
+    for (const [key, value] of Object.entries(scriptUpdates)) {
+        if (scripts[key] !== value) {
+            scripts[key] = value;
+            changed = true;
+        }
+    }
+    if (!changed)
+        return { ok: true, changed: false };
+    pkg.scripts = scripts;
+    for (const key of beforeKeys) {
+        if (!Object.keys(pkg).includes(key)) {
+            return { ok: false, reason: `会丢失字段: ${key}` };
+        }
+    }
+    const out = `${JSON.stringify(pkg, null, 2)}\n`;
+    if (out.length < text.length * minSizeRatio) {
+        return { ok: false, reason: "写入后体积异常缩小" };
+    }
+    await (0, fs_1.writeTextFileEnsuredDir)(pkgPath, out);
+    return { ok: true, changed: true };
+}
+async function ensurePnpmAllowSddFlowKitBuild(pkgPath) {
+    var _a, _b;
+    let text;
+    try {
+        text = await promises_1.default.readFile(pkgPath, "utf8");
+    }
+    catch {
+        return false;
+    }
+    let pkg;
+    try {
+        pkg = JSON.parse(text);
+    }
+    catch {
+        return false;
+    }
+    const pnpm = (_a = pkg.pnpm) !== null && _a !== void 0 ? _a : {};
+    const list = (_b = pnpm.onlyBuiltDependencies) !== null && _b !== void 0 ? _b : [];
+    if (list.includes("sdd-flow-kit"))
+        return false;
+    pnpm.onlyBuiltDependencies = [...list, "sdd-flow-kit"];
+    pkg.pnpm = pnpm;
+    await (0, fs_1.writeTextFileEnsuredDir)(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
+    return true;
+}

package/dist/core/projectRoots.js

@@ -0,0 +1,94 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveInstallRoot = resolveInstallRoot;
+exports.isLegacyMonorepoMode = isLegacyMonorepoMode;
+exports.resolveOpenspecRoot = resolveOpenspecRoot;
+exports.resolvePackageRoot = resolvePackageRoot;
+exports.listOpenspecPrdRoots = listOpenspecPrdRoots;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * 安装根：严格等于 CLI 的 projectRoot（默认 process.cwd()）。
+ * 可通过 SDD_FLOW_KIT_INSTALL_ROOT 覆盖（绝对路径）。
+ * 原则：cd 到哪，package.json / .cursor/skills / opsx-workflow 就装到哪。
+ */
+function resolveInstallRoot(projectRoot) {
+    var _a;
+    const fromEnv = (_a = process.env.SDD_FLOW_KIT_INSTALL_ROOT) === null || _a === void 0 ? void 0 : _a.trim();
+    if (fromEnv)
+        return path_1.default.resolve(fromEnv);
+    return path_1.default.resolve(projectRoot);
+}
+/** 是否启用旧版 monorepo 行为（在仓库根执行时自动落到 frontend/） */
+function isLegacyMonorepoMode() {
+    return process.env.SDD_FLOW_KIT_LEGACY_MONOREPO === "1" || process.env.SDD_FLOW_KIT_LEGACY_MONOREPO === "true";
+}
+/**
+ * 从 installRoot 向上查找含 openspec/ 的目录（用于解析 PRD run、openspec CLI）。
+ * 找不到则退回 installRoot（将在其下新建 openspec/PRD）。
+ */
+async function resolveOpenspecRoot(installRoot) {
+    let cur = path_1.default.resolve(installRoot);
+    for (let i = 0; i < 12; i += 1) {
+        if (await pathExists(path_1.default.join(cur, "openspec"))) {
+            return cur;
+        }
+        const parent = path_1.default.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return path_1.default.resolve(installRoot);
+}
+/**
+ * 交付/门禁用的包根：默认与 installRoot 相同。
+ * 仅当 SDD_FLOW_KIT_LEGACY_MONOREPO=1 且 installRoot 无 package.json 但存在 frontend/package.json 时回落到 frontend/。
+ */
+async function resolvePackageRoot(installRoot) {
+    const root = resolveInstallRoot(installRoot);
+    if (!isLegacyMonorepoMode()) {
+        return root;
+    }
+    const pkgAtRoot = path_1.default.join(root, "package.json");
+    if (await pathExists(pkgAtRoot)) {
+        return root;
+    }
+    const fePkg = path_1.default.join(root, "frontend", "package.json");
+    if (await pathExists(fePkg)) {
+        return path_1.default.join(root, "frontend");
+    }
+    return root;
+}
+/**
+ * 收集自 installRoot 向上所有存在的 openspec/PRD 目录（用于 resolveRun）。
+ */
+async function listOpenspecPrdRoots(startDir) {
+    const seen = new Set();
+    const out = [];
+    let cur = path_1.default.resolve(startDir);
+    for (let i = 0; i < 12; i += 1) {
+        const prdRoot = path_1.default.join(cur, "openspec", "PRD");
+        const key = prdRoot.toLowerCase();
+        if (!seen.has(key) && (await pathExists(prdRoot))) {
+            seen.add(key);
+            out.push(prdRoot);
+        }
+        const parent = path_1.default.dirname(cur);
+        if (parent === cur)
+            break;
+        cur = parent;
+    }
+    return out;
+}