sdd-flow-kit 1.2.3 → 1.3.0

package/dist/steps/runValidate.js

@@ -0,0 +1,204 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MAX_VALIDATE_RETRIES = void 0;
+exports.runValidate = runValidate;
+const path_1 = __importDefault(require("path"));
+const child_process_1 = require("child_process");
+const resolveRun_1 = require("./resolveRun");
+const runGate_1 = require("./runGate");
+const opsxDelivery_1 = require("../core/opsxDelivery");
+const projectRoots_1 = require("../core/projectRoots");
+const sessionState_1 = require("../core/sessionState");
+const fs_1 = require("../core/fs");
+const openspecGate_1 = require("../core/openspecGate");
+/** 验收回退最大次数，超过需用户确认 */
+exports.MAX_VALIDATE_RETRIES = 3;
+/**
+ * 验收命令：跑 lint+type+unit（delivery-pipeline:short）+ e2e/Playwright，写入 .validate-pass.json 或 .validate-fail.json。
+ * 验收不通过时回退到 apply_in_progress，超过 MAX_VALIDATE_RETRIES 次则需用户确认。
+ */
+async function runValidate(options) {
+    var _a, _b, _c;
+    const loaded = await (0, resolveRun_1.loadRunSession)(options.projectRoot, options.runId);
+    if (!(loaded === null || loaded === void 0 ? void 0 : loaded.resolved)) {
+        return { ok: false, detail: "未找到 PRD run", needUserConfirm: false };
+    }
+    // 前置门禁：impl-allowed
+    const implGate = await (0, runGate_1.runGate)({
+        projectRoot: options.projectRoot,
+        runId: loaded.resolved.runId,
+        expect: "impl-allowed",
+        change: options.change,
+    });
+    if (!implGate.ok) {
+        (0, runGate_1.printGateResult)(implGate);
+        return { ok: false, detail: "impl-allowed gate 未通过，不能验收", needUserConfirm: false };
+    }
+    const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
+    const agent = options.agent || "cursor";
+    if (options.dryRun) {
+        return { ok: true, detail: `dry-run: would validate in ${pkgRoot} (installRoot=${installRoot})`, needUserConfirm: false };
+    }
+    // 确保 opsx 环境就绪
+    const ensured = await (0, opsxDelivery_1.ensureOpsxWorkflow)({ projectRoot: pkgRoot, agent, dryRun: false });
+    if (!ensured.ready) {
+        return { ok: false, detail: "ensure-opsx 未就绪", needUserConfirm: false };
+    }
+    // ---- 检查1: tasks.md 全完成 ----
+    const tasks = await (0, openspecGate_1.checkTasksAllDone)(installRoot, options.change);
+    // ---- 检查2: delivery-pipeline:short（lint + type check + unit test） ----
+    const shortRet = (0, child_process_1.spawnSync)("pnpm", ["run", "opsx:delivery-pipeline:short", "--", options.change], {
+        cwd: pkgRoot,
+        stdio: "inherit",
+        shell: process.platform === "win32",
+    });
+    const shortExitCode = (_a = shortRet.status) !== null && _a !== void 0 ? _a : 1;
+    // ---- 检查3: e2e / Playwright ----
+    let e2eExitCode = 0;
+    let e2eDetail = "e2e 未执行";
+    const hasPlaywrightScript = await hasScript(pkgRoot, "test:e2e");
+    if (hasPlaywrightScript) {
+        const e2eRet = (0, child_process_1.spawnSync)("pnpm", ["run", "test:e2e"], {
+            cwd: pkgRoot,
+            stdio: "inherit",
+            shell: process.platform === "win32",
+            env: { ...process.env, CI: "1" },
+        });
+        e2eExitCode = (_b = e2eRet.status) !== null && _b !== void 0 ? _b : 1;
+        e2eDetail = e2eExitCode === 0 ? "e2e/Playwright 全通过" : `e2e/Playwright 退出码 ${e2eExitCode}`;
+    }
+    else {
+        // 尝试直接用 npx playwright test
+        const hasPlaywrightCli = (0, child_process_1.spawnSync)("npx", ["playwright", "--version"], {
+            cwd: pkgRoot,
+            stdio: "ignore",
+        }).status === 0;
+        if (hasPlaywrightCli) {
+            const e2eRet = (0, child_process_1.spawnSync)("npx", ["playwright", "test"], {
+                cwd: pkgRoot,
+                stdio: "inherit",
+                shell: process.platform === "win32",
+                env: { ...process.env, CI: "1" },
+            });
+            e2eExitCode = (_c = e2eRet.status) !== null && _c !== void 0 ? _c : 1;
+            e2eDetail = e2eExitCode === 0 ? "Playwright test 全通过" : `Playwright test 退出码 ${e2eExitCode}`;
+        }
+        else {
+            e2eDetail = "未检测到 Playwright，跳过 e2e（建议配置 test:e2e 脚本）";
+        }
+    }
+    // ---- 综合判定 ----
+    const allPassed = tasks.ok && shortExitCode === 0 && e2eExitCode === 0;
+    const verdict = allPassed ? "pass" : "fail";
+    const payload = {
+        change: options.change,
+        verdict,
+        tasksOk: tasks.ok,
+        tasksDetail: tasks.detail,
+        pipelineShortExitCode: shortExitCode,
+        e2eExitCode,
+        e2eDetail,
+        at: new Date().toISOString(),
+    };
+    const markerFile = verdict === "pass" ? ".validate-pass.json" : ".validate-fail.json";
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(loaded.resolved.outputRoot, markerFile), `${JSON.stringify(payload, null, 2)}\n`);
+    // ---- 更新 session ----
+    let needUserConfirm = false;
+    if (loaded.session) {
+        if (verdict === "pass") {
+            const next = {
+                ...loaded.session,
+                status: "validate_done",
+            };
+            await (0, sessionState_1.writeSession)(loaded.resolved.outputRoot, next);
+        }
+        else {
+            // 验收失败：回退计数 +1
+            const newRetryCount = (loaded.session.validateRetryCount || 0) + 1;
+            needUserConfirm = newRetryCount > exports.MAX_VALIDATE_RETRIES;
+            const next = {
+                ...loaded.session,
+                status: "apply_in_progress",
+                validateRetryCount: newRetryCount,
+            };
+            await (0, sessionState_1.writeSession)(loaded.resolved.outputRoot, next);
+            // 清理上次验收标记（重新实现后需要重新验收）
+            await cleanupValidateMarkers(loaded.resolved.outputRoot);
+        }
+    }
+    if (verdict === "fail") {
+        const retryInfo = loaded.session
+            ? `（第 ${loaded.session.validateRetryCount + 1} 次验收失败${needUserConfirm ? "，已达上限，需用户确认后继续" : ""}）`
+            : "";
+        return {
+            ok: false,
+            detail: `验收失败: tasks=${tasks.detail}, pipeline=${shortExitCode}, e2e=${e2eDetail} ${retryInfo}`,
+            needUserConfirm,
+        };
+    }
+    return { ok: true, detail: "验收通过（lint+type+unit+e2e），可进入交付", needUserConfirm: false };
+}
+/** 检查 package.json 是否有指定 script */
+async function hasScript(pkgRoot, scriptName) {
+    var _a;
+    try {
+        const { readFile: readFileFs } = await Promise.resolve().then(() => __importStar(require("fs/promises")));
+        const pkgText = await readFileFs(path_1.default.join(pkgRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(pkgText);
+        return Boolean((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a[scriptName]);
+    }
+    catch {
+        return false;
+    }
+}
+/** 清理验收标记文件，重新实现后需要重新验收 */
+async function cleanupValidateMarkers(outputRoot) {
+    const { unlink } = await Promise.resolve().then(() => __importStar(require("fs/promises")));
+    for (const f of [".validate-pass.json", ".validate-fail.json"]) {
+        const p = path_1.default.join(outputRoot, f);
+        const content = await (0, fs_1.readFileIfExists)(p);
+        if (content !== null) {
+            try {
+                await unlink(p);
+            }
+            catch { /* ignore */ }
+        }
+    }
+}

package/dist/steps/setupProject.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.setupProject = setupProject;
 const child_process_1 = require("child_process");
+const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const process_1 = __importDefault(require("process"));
 const fs_1 = require("../core/fs");
@@ -15,7 +16,7 @@ const packageJsonPatch_1 = require("../core/packageJsonPatch");
 const projectRoots_1 = require("../core/projectRoots");
 const templates_1 = require("../core/templates");
 const EDITOR_CHOICES = ["claude-code", "cursor", "codex", "openclaw"];
-const PROJECT_CHOICES = ["OMS", "ADI", "欢盟", "AD Tools"];
+const PROJECT_CHOICES = ["OMS", "ADI", "欢盟", "AD Tools", "BreakX"];
 function runGit(args, cwd) {
     var _a, _b;
     const out = (0, child_process_1.spawnSync)("git", args, { cwd, encoding: "utf8" });
@@ -87,6 +88,7 @@ async function askProjectKind(defaultKind) {
         "2) ADI",
         "3) 欢盟",
         "4) AD Tools",
+        "5) BreakX",
         "输入编号（回车默认 1）：",
     ].join("\n");
     const answer = (await (0, readlinePrompt_1.promptLine)(rl, `${prompt}\n`)).trim();
@@ -131,6 +133,7 @@ async function installAgentSkill(projectRoot, projectKind) {
     if (targets.length === 0)
         return;
     const template = await (0, templates_1.loadTemplateText)("artifacts/06-agent-skill.template.md");
+    const layered = await (0, templates_1.loadTemplateText)("skills/layered-testing-strategy.md");
     for (const target of targets) {
         const agentName = target.includes("/.cursor/")
             ? "cursor"
@@ -145,6 +148,8 @@ async function installAgentSkill(projectRoot, projectKind) {
             DEFAULT_PRODUCT: projectKind === "AD Tools" ? "AD Tools" : projectKind,
         });
         await (0, fs_1.writeTextFileEnsuredDir)(target, content);
+        const layeredPath = path_1.default.join(path_1.default.dirname(target), "LAYERED-TESTING.md");
+        await (0, fs_1.writeTextFileEnsuredDir)(layeredPath, layered);
     }
 }
 async function installSddCursorRule(projectRoot) {
@@ -167,6 +172,8 @@ function docSkillDirName(kind) {
             return { dir: "huan-doc-skill", prefix: "HUAN" };
         case "AD Tools":
             return { dir: "ad-tools-doc-skill", prefix: "ADTOOLS" };
+        case "BreakX":
+            return { dir: "breakx-doc-skill", prefix: "BreakX" };
         case "OMS":
         default:
             return { dir: "oms-doc-skill", prefix: "OMS" };
@@ -183,12 +190,67 @@ async function installDocsSkill(projectRoot, kind) {
         PRODUCT_PREFIX: prefix,
         PRODUCT_PREFIX_LOWER: prefix.toLowerCase(),
         SKILL_DIR: dir,
+        CONFLUENCE_SPACE_NOTE: kind === "BreakX"
+            ? "- BreakX PRD 位于 Confluence **xhs** 空间，页面标题通常以 `Vx.y.z` 开头（如 `V1.0.2 审稿子任务...`）\n- 脚本默认 `CONFLUENCE_SPACE=xhs`，优先匹配该空间下的页面"
+            : "",
     });
     const py = (0, utils_1.replaceAllStr)(pyTemplate, "{{DOC_PRODUCT_PREFIX}}", prefix);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(docsDir, "SKILL.md"), md);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(docsDir, "confluence-doc.py"), py);
     return { dirPath: docsDir };
 }
+function parseDevPortFromScript(script) {
+    var _a, _b;
+    // Common patterns:
+    // - vite --port 3000
+    // - next dev -p 3000
+    // - next dev --port 3000
+    // - nuxt dev -p 3000
+    const m = (_b = (_a = script.match(/(?:--port|-p)\s+(\d{2,5})\b/)) !== null && _a !== void 0 ? _a : script.match(/\bPORT=(\d{2,5})\b/)) !== null && _b !== void 0 ? _b : null;
+    if (!m)
+        return null;
+    const port = Number(m[1]);
+    if (!Number.isFinite(port) || port < 1 || port > 65535)
+        return null;
+    return port;
+}
+async function resolveDefaultDevServerUrl(projectRoot) {
+    var _a, _b, _c, _d, _e, _f, _g, _h;
+    const envUrl = ((_a = process_1.default.env.SDD_DEV_SERVER_URL) === null || _a === void 0 ? void 0 : _a.trim()) ||
+        ((_b = process_1.default.env.OPSX_DEV_SERVER_URL) === null || _b === void 0 ? void 0 : _b.trim()) ||
+        ((_c = process_1.default.env.DEV_SERVER_URL) === null || _c === void 0 ? void 0 : _c.trim()) ||
+        "";
+    if (envUrl)
+        return envUrl;
+    const envPortRaw = ((_d = process_1.default.env.SDD_DEV_SERVER_PORT) === null || _d === void 0 ? void 0 : _d.trim()) ||
+        ((_e = process_1.default.env.OPSX_DEV_SERVER_PORT) === null || _e === void 0 ? void 0 : _e.trim()) ||
+        ((_f = process_1.default.env.DEV_SERVER_PORT) === null || _f === void 0 ? void 0 : _f.trim()) ||
+        "";
+    if (envPortRaw) {
+        const port = Number(envPortRaw);
+        if (Number.isFinite(port) && port >= 1 && port <= 65535) {
+            return `http://localhost:${port}`;
+        }
+    }
+    try {
+        const pkgText = await promises_1.default.readFile(path_1.default.join(projectRoot, "package.json"), "utf8");
+        const pkg = JSON.parse(pkgText);
+        const devScript = (_h = (_g = pkg.scripts) === null || _g === void 0 ? void 0 : _g.dev) !== null && _h !== void 0 ? _h : "";
+        const parsedPort = devScript ? parseDevPortFromScript(devScript) : null;
+        if (parsedPort)
+            return `http://localhost:${parsedPort}`;
+        const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+        // Heuristics: Next.js defaults to 3000; Vite defaults to 5173.
+        if (deps.next)
+            return "http://localhost:3000";
+        if (deps.vite)
+            return "http://localhost:5173";
+    }
+    catch {
+        // ignore and fallback
+    }
+    return "http://localhost:5173";
+}
 function getOpsxPathsByAgent(agent) {
     switch (agent) {
         case "cursor":
@@ -207,6 +269,7 @@ async function installOpsxConfig(projectRoot, agent) {
     const target = path_1.default.join(projectRoot, ".opsx", "config.json");
     const resolvedAgent = await (0, opsxDelivery_1.resolveOpsxAgent)(projectRoot, agent);
     const paths = getOpsxPathsByAgent(resolvedAgent);
+    const devServerUrl = await resolveDefaultDevServerUrl(projectRoot);
     const config = {
         version: 1,
         editor: paths.editor,
@@ -217,7 +280,7 @@ async function installOpsxConfig(projectRoot, agent) {
             packageManager: "pnpm",
             unitScript: "unit",
             playwrightCommand: "exec playwright test",
-            devServerUrl: "http://localhost:5173",
+            devServerUrl,
             playwrightPicDir: "playwright-pic",
         },
     };

package/dist/steps/startFlow.js

@@ -69,17 +69,19 @@ async function startFlowScaffold(options) {
     const file01Template = await (0, templates_1.loadTemplateText)("artifacts/01-需求分析报告.template.md");
     const file02Template = await (0, templates_1.loadTemplateText)("artifacts/02-改动点清单.template.md");
     const file03Template = await (0, templates_1.loadTemplateText)("artifacts/03-待确认问题清单.template.md");
+    const file05Template = await (0, templates_1.loadTemplateText)("artifacts/05-验收清单.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "01-需求分析报告.md"), file01Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "02-改动点清单.md"), file02Template);
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "03-待确认问题清单.md"), file03Template);
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "05-验收清单.md"), file05Template);
     // 4) Step4 技术文档入口（草稿）
     const techDocTemplate = await (0, templates_1.loadTemplateText)("artifacts/04-技术文档.template.md");
     await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "04-技术文档草稿.md"), techDocTemplate);
     // 5) Step5 openspec 提案入口（草稿）
-    const openspecEntryTemplate = await (0, templates_1.loadTemplateText)("artifacts/05-openspec-提案草稿.template.md");
-    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "05-openspec-提案草稿.md"), openspecEntryTemplate);
-    const opsxAutoChainTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-opsx-auto-chain.template.md");
-    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-opsx-自动串联指引.md"), opsxAutoChainTemplate);
+    const openspecEntryTemplate = await (0, templates_1.loadTemplateText)("artifacts/06-openspec-提案草稿.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "06-openspec-提案草稿.md"), openspecEntryTemplate);
+    const opsxAutoChainTemplate = await (0, templates_1.loadTemplateText)("artifacts/07-opsx-auto-chain.template.md");
+    await (0, fs_1.writeTextFileEnsuredDir)(path_1.default.join(outputRoot, "07-opsx-自动串联指引.md"), opsxAutoChainTemplate);
     const session = (0, sessionState_1.defaultSession)({
         product: options.product,
         version: options.version,
@@ -104,21 +106,22 @@ async function startFlowScaffold(options) {
         "",
         "## Step 3：人工核验（暂停点）",
         "用户补充待确认点并确认闭环后，才进入 Step 4。",
-        "门禁：未闭环时禁止生成 01/02/04，禁止 /opsx-propose。",
+        "门禁：未闭环时禁止生成 01/02/04/05，禁止 /opsx-propose。",
         "**重要**：用户粘贴确认点时，AI 仅更新 `openspec/PRD` 文档，**禁止**修改 `src/` 等业务代码。",
         "",
-        "## Step 4：生成 01 / 02 / 闭环03 / 04",
-        "用户确认后产出：",
+        "## Step 4：生成 05 → 04 → 01 / 02 / 闭环03",
+        "用户确认后产出（顺序重要）：",
         "- `03-待确认问题清单.md`（已闭合）",
-        "- `01-需求分析报告.md`",
+        "- `05-验收清单.md`（从 `source/PRD.md` 逐条抽取 AC，标注「定义状态：已定义」）",
+        "- `04-技术文档草稿.md`（引用 AC-ID）",
+        "- `01-需求分析报告.md`（业务概述，非验收 SSOT）",
         "- `02-改动点清单.md`",
-        "- `04-技术文档草稿.md`",
         "",
-        "## Step 5–6：脚本门禁（禁止仅靠自然语言跳步）",
+        "## Step 5–7：脚本门禁（禁止仅靠自然语言跳步）",
         "每一步必须先执行 `NEXT.md` 中的 `npx sdd-flow-kit gate` / `phase advance` / `propose` / `deliver`。",
         "命令失败 (exit≠0) 时 **不得** 改 `src/` 或宣称完成。",
         "",
-        "详见：`NEXT.md`、`06-opsx-自动串联指引.md`、`.cursor/skills/sdd-flow-kit/SKILL.md`。",
+        "详见：`NEXT.md`、`07-opsx-自动串联指引.md`、`.cursor/skills/sdd-flow-kit/SKILL.md`。",
     ].join("\n"));
     return {
         runId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-flow-kit",
-  "version": "1.2.3",
+  "version": "1.3.0",
   "private": false,
   "description": "Cross-agent SDD automated development workflow kit (ADI/ADI-like).",
   "license": "MIT",

package/src/templates/artifacts/01-/351/234/200/346/261/202/345/210/206/346/236/220/346/212/245/345/221/212.template.md

@@ -1,5 +1,8 @@
 # 01-需求分析报告
 
+> **定位**：业务概述、范围、风险与确认点摘要。  
+> **不是**完整验收标准 — implement/deliver 的唯一验收 SSOT 为 `05-验收清单.md`。
+
 ## 业务概述
 - （在此处总结 PRD 核心目标）
 
@@ -16,7 +19,9 @@
 - 兼容性问题：
 - 副作用分析：
 
+## 已闭合确认点摘要
+- （引用 `03-待确认问题清单.md` 中的结论；Intentional 偏差须同步到 05）
+
 ---
 
 > 矛盾点池状态：待填写（提问模式/交付模式）
-