sdd-flow-kit 1.3.14 → 1.3.18

package/dist/cli.js

@@ -20,10 +20,13 @@ const runDeliver_1 = require("./steps/runDeliver");
 const runPrdReview_1 = require("./steps/runPrdReview");
 const runPrdDiff_1 = require("./steps/runPrdDiff");
 const runPrdRemediate_1 = require("./steps/runPrdRemediate");
+const runSyncSourcePrd_1 = require("./steps/runSyncSourcePrd");
 const runChain_1 = require("./steps/runChain");
 const runSessionMode_1 = require("./steps/runSessionMode");
+const runGuard_1 = require("./steps/runGuard");
 const bootstrap_1 = require("./core/bootstrap");
 const projectRoots_1 = require("./core/projectRoots");
+const versionIntent_1 = require("./core/versionIntent");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
 function getArgValue(flag) {
     const idx = process_1.default.argv.indexOf(flag);
@@ -34,6 +37,42 @@ function getArgValue(flag) {
         return null;
     return v;
 }
+function getFreeTextArgs(startIndex) {
+    const flagsWithValue = new Set([
+        "--agent",
+        "--project",
+        "--product",
+        "--version",
+        "--project-root",
+        "--projectRoot",
+        "--run-id",
+        "--runId",
+        "--change",
+        "--branch",
+        "--from",
+        "--to",
+        "--expect",
+        "--execution-mode",
+        "--executionMode",
+        "--text",
+    ]);
+    const parts = [];
+    const tokens = process_1.default.argv.slice(startIndex);
+    for (let i = 0; i < tokens.length; i += 1) {
+        const token = tokens[i];
+        if (token === "-y" || token === "--dry-run" || token === "--plan-json" || token === "--strict-commands") {
+            continue;
+        }
+        if (flagsWithValue.has(token)) {
+            i += 1;
+            continue;
+        }
+        if (token.startsWith("--"))
+            continue;
+        parts.push(token);
+    }
+    return parts.join(" ").trim();
+}
 function printHelp() {
     // eslint-disable-next-line no-console
     console.log([
@@ -51,7 +90,8 @@ function printHelp() {
         "3) 生成骨架并进入可执行模式（推荐）：",
         "   npx sdd-flow-kit run --product ADI --version 2.3.2 --agent claude-code",
         "",
-        "4) 一句话触发（可选能力）：",
+        "4) 一句话触发（版本开发强制入口）：",
+        "   npx sdd-flow-kit guard \"开发 ADI_V2.3.4版本\" -y --agent cursor",
         "   npx sdd-flow-kit invoke \"开发 XXX 1.2.3 需求\"",
         "",
         "5) 环境健检：",
@@ -68,6 +108,7 @@ function printHelp() {
         "   npx sdd-flow-kit gate --project-root . --run-id <runId> --expect prd-coverage --change <name>",
         "",
         "10) PRD 一致性复查（最细粒度，交付前强制）：",
+        "   npx sdd-flow-kit sync-source-prd --project-root . --run-id <runId>",
         "   npx sdd-flow-kit prd-review --project-root . --run-id <runId>",
         "   # 在 AI 工具执行 openspec/PRD/<runId>/08-PRD一致性复查提示词.md",
         "   npx sdd-flow-kit prd-diff --project-root . --run-id <runId>",
@@ -111,7 +152,7 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
@@ -144,6 +185,7 @@ async function main() {
         cmd !== "install" &&
         cmd !== "doctor" &&
         cmd !== "ensure-opsx" &&
+        cmd !== "guard" &&
         cmd !== "invoke" &&
         cmd !== "gate" &&
         cmd !== "phase" &&
@@ -152,6 +194,7 @@ async function main() {
         cmd !== "prd-review" &&
         cmd !== "prd-diff" &&
         cmd !== "prd-remediate" &&
+        cmd !== "sync-source-prd" &&
         cmd !== "deliver" &&
         cmd !== "chain" &&
         cmd !== "session") {
@@ -169,7 +212,11 @@ async function main() {
     const dryRun = process_1.default.argv.includes("--dry-run");
     const planJson = process_1.default.argv.includes("--plan-json");
     const agentValue = (_g = getArgValue("--agent")) !== null && _g !== void 0 ? _g : "claude-code";
-    const projectKind = ((_h = getArgValue("--project")) !== null && _h !== void 0 ? _h : "OMS");
+    const rawGuardText = cmd === "guard"
+        ? ((_h = getArgValue("--text")) !== null && _h !== void 0 ? _h : getFreeTextArgs(3)).trim()
+        : "";
+    const guardIntent = rawGuardText ? (0, versionIntent_1.parseVersionIntent)(rawGuardText) : null;
+    const projectKind = ((_k = (_j = getArgValue("--project")) !== null && _j !== void 0 ? _j : guardIntent === null || guardIntent === void 0 ? void 0 : guardIntent.product) !== null && _k !== void 0 ? _k : "OMS");
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -189,6 +236,7 @@ async function main() {
     const bootstrapCommands = new Set([
         "doctor",
         "ensure-opsx",
+        "guard",
         "run",
         "invoke",
         "install",
@@ -200,6 +248,7 @@ async function main() {
         "prd-review",
         "prd-diff",
         "prd-remediate",
+        "sync-source-prd",
         "deliver",
         "chain",
         "session",
@@ -211,6 +260,36 @@ async function main() {
             projectKind: projectKind,
         });
     }
+    if (cmd === "guard") {
+        const text = rawGuardText;
+        if (!text) {
+            // eslint-disable-next-line no-console
+            console.error("guard 需要自然语言文本，例如：npx sdd-flow-kit guard \"开发 ADI_V2.3.4版本\" -y --agent cursor");
+            process_1.default.exitCode = 1;
+            return;
+        }
+        const result = await (0, runGuard_1.runGuard)({
+            text,
+            projectRoot,
+            branch,
+            yes,
+            dryRun,
+            agent,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `ℹ️ ${result.detail}`);
+        if (result.ok && result.nextPath) {
+            // eslint-disable-next-line no-console
+            console.log(`下一步：读取 ${result.nextPath} 与同目录 .session-state.json`);
+        }
+        if (planJson) {
+            // eslint-disable-next-line no-console
+            console.log(JSON.stringify({ command: "guard", projectRoot, dryRun, result }, null, 2));
+        }
+        if (!result.ok)
+            process_1.default.exitCode = 2;
+        return;
+    }
     if (cmd === "gate") {
         const expect = getArgValue("--expect");
         if (!expect || !GATE_EXPECTS.includes(expect)) {
@@ -277,6 +356,18 @@ async function main() {
             process_1.default.exitCode = 1;
         return;
     }
+    if (cmd === "sync-source-prd") {
+        const result = await (0, runSyncSourcePrd_1.runSyncSourcePrd)({
+            projectRoot,
+            runId,
+            dryRun,
+        });
+        // eslint-disable-next-line no-console
+        console.log(result.ok ? `✅ ${result.detail}` : `❌ ${result.detail}`);
+        if (!result.ok)
+            process_1.default.exitCode = 1;
+        return;
+    }
     if (cmd === "validate") {
         if (!changeName) {
             // eslint-disable-next-line no-console
@@ -376,7 +467,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const from = ((_j = getArgValue("--from")) !== null && _j !== void 0 ? _j : "docs-done");
+        const from = ((_l = getArgValue("--from")) !== null && _l !== void 0 ? _l : "docs-done");
         if (!CHAIN_FROM.includes(from)) {
             // eslint-disable-next-line no-console
             console.error(`chain 需要 --from ${CHAIN_FROM.join("|")}`);
@@ -405,7 +496,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const modeArg = (_k = getArgValue("--execution-mode")) !== null && _k !== void 0 ? _k : getArgValue("--executionMode");
+        const modeArg = (_m = getArgValue("--execution-mode")) !== null && _m !== void 0 ? _m : getArgValue("--executionMode");
         const textArg = getArgValue("--text");
         const strictCommands = process_1.default.argv.includes("--strict-commands");
         const result = await (0, runSessionMode_1.runSessionMode)({
@@ -474,11 +565,7 @@ async function main() {
     }
     if (!product || !version) {
         if (cmd === "invoke") {
-            const raw = process_1.default.argv
-                .slice(3)
-                .filter((token) => !token.startsWith("--") && token !== "-y")
-                .join(" ")
-                .trim();
+            const raw = getFreeTextArgs(3);
             const fromFlag = getArgValue("--text");
             const text = (fromFlag !== null && fromFlag !== void 0 ? fromFlag : raw).trim();
             const parsed = (0, invokeFlow_1.parseInvokeText)(text);

package/dist/core/apiFieldContract.js

@@ -0,0 +1,90 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkApiFieldContract = checkApiFieldContract;
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const API_MODULE_DIR_RE = /(^|\/)(src|frontend\/src)\/config\/api\/modules\//;
+const NORMALIZE_MARKERS = /snakeToCamel|camelToSnake|normalizeFinanceApiResult|normalize\w*Api|caseTransform|toCamelCase|toSnakeCase/i;
+const API_CLIENT_CALL_RE = /\b(?:apiClient|request|post|get)\s*[.(]/i;
+/**
+ * 扫描 change 关联的 API 模块：对接后端时须在模块层做字段 normalize（防 SNAKE_CASE 漏映射）。
+ */
+async function checkApiFieldContract(pkgRoot, changeName) {
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_API_FIELD_CONTRACT === "1" ||
+        process.env.OPSX_SKIP_API_FIELD_CONTRACT === "1";
+    if (skip) {
+        checks.push({
+            name: "api-field-contract",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_API_FIELD_CONTRACT=1",
+        });
+        return checks;
+    }
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    const artifactParts = ["tasks.md", "proposal.md", "design.md"];
+    let blob = "";
+    for (const f of artifactParts) {
+        const c = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, f));
+        if (c)
+            blob += c;
+    }
+    const moduleRefs = new Set();
+    const modRe = /config\/api\/modules\/([\w/-]+)/g;
+    let m;
+    while ((m = modRe.exec(blob)) !== null) {
+        moduleRefs.add(m[1].replace(/\/index$/, ""));
+    }
+    if (moduleRefs.size === 0) {
+        checks.push({
+            name: "api-field-contract",
+            ok: true,
+            detail: "change 未引用 config/api/modules，跳过 API 字段契约检查",
+        });
+        return checks;
+    }
+    const failures = [];
+    const passed = [];
+    for (const mod of moduleRefs) {
+        const candidates = [
+            path_1.default.join(pkgRoot, "src/config/api/modules", mod, "index.ts"),
+            path_1.default.join(pkgRoot, "frontend/src/config/api/modules", mod, "index.ts"),
+            path_1.default.join(pkgRoot, "src/config/api/modules", `${mod}.ts`),
+            path_1.default.join(pkgRoot, "frontend/src/config/api/modules", `${mod}.ts`),
+        ];
+        let found = false;
+        for (const fp of candidates) {
+            const content = await (0, fs_1.readFileIfExists)(fp);
+            if (content === null)
+                continue;
+            found = true;
+            const rel = path_1.default.relative(pkgRoot, fp).replace(/\\/g, "/");
+            if (!API_MODULE_DIR_RE.test(`/${rel}`))
+                continue;
+            if (!API_CLIENT_CALL_RE.test(content)) {
+                passed.push(`${rel}（无 HTTP 调用，跳过）`);
+                continue;
+            }
+            if (!NORMALIZE_MARKERS.test(content)) {
+                failures.push(`${rel} 含 API 调用但未发现 snake/camel normalize（须防后端 SNAKE_CASE 漏映射）`);
+            }
+            else {
+                passed.push(rel);
+            }
+        }
+        if (!found) {
+            failures.push(`config/api/modules/${mod} 在 change 中引用但文件不存在`);
+        }
+    }
+    checks.push({
+        name: "api-field-contract",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `API 字段契约通过: ${passed.join(", ") || "(无模块文件)"}`
+            : failures.join(" | "),
+    });
+    return checks;
+}

package/dist/core/demoImplementationCoverage.js

@@ -0,0 +1,242 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseDemoReferenceSection = parseDemoReferenceSection;
+exports.checkDemoReferenceArtifacts = checkDemoReferenceArtifacts;
+exports.checkDemoImplementationCoverage = checkDemoImplementationCoverage;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const testAssertionAnalysis_1 = require("./testAssertionAnalysis");
+const DEMO_SECTION_RE = /^##\s*(演示代码参照|Demo Reference)\s*$/im;
+const DEMO_EXEMPT_RE = /^DEMO_REFERENCE_EXEMPT:\s*(.+)$/m;
+const MAPPING_HEADER_RE = /演示模块|Demo Module/i;
+const UI_SCENARIO_KEYWORDS = /上传|点击|页面|按钮|弹窗|列表|表格|展示|抽屉|详情|编辑|导出|筛选|输入框|对话框|导航|toast|保存|删除|添加/i;
+/**
+ * 从 Markdown 解析「演示代码参照」章节与模块映射表。
+ */
+function parseDemoReferenceSection(content) {
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k;
+    const exemptMatch = content.match(DEMO_EXEMPT_RE);
+    const exempt = ((_a = exemptMatch === null || exemptMatch === void 0 ? void 0 : exemptMatch[1]) === null || _a === void 0 ? void 0 : _a.trim()) || null;
+    const sectionMatch = content.match(DEMO_SECTION_RE);
+    if (!sectionMatch || sectionMatch.index === undefined) {
+        return { hasSection: false, exempt, demoRoot: null, demoStack: null, mappings: [] };
+    }
+    const sectionBody = content.slice(sectionMatch.index);
+    const demoRoot = ((_c = (_b = sectionBody.match(/演示代码根路径[：:]\s*`?([^`\n]+)`?/i)) === null || _b === void 0 ? void 0 : _b[1]) === null || _c === void 0 ? void 0 : _c.trim()) ||
+        ((_e = (_d = sectionBody.match(/Demo Root[：:]\s*`?([^`\n]+)`?/i)) === null || _d === void 0 ? void 0 : _d[1]) === null || _e === void 0 ? void 0 : _e.trim()) ||
+        null;
+    const demoStack = ((_g = (_f = sectionBody.match(/技术栈[：:]\s*`?(vue|react|其他)[^`\n]*`?/i)) === null || _f === void 0 ? void 0 : _f[1]) === null || _g === void 0 ? void 0 : _g.trim()) ||
+        ((_j = (_h = sectionBody.match(/Stack[：:]\s*`?(vue|react|other)[^`\n]*`?/i)) === null || _h === void 0 ? void 0 : _h[1]) === null || _j === void 0 ? void 0 : _j.trim()) ||
+        null;
+    const mappings = [];
+    const lines = sectionBody.split("\n");
+    let inTable = false;
+    for (let i = 0; i < lines.length; i += 1) {
+        const line = lines[i].trim();
+        if (line.startsWith("|") && MAPPING_HEADER_RE.test(line)) {
+            inTable = true;
+            continue;
+        }
+        if (!inTable || !line.startsWith("|"))
+            continue;
+        if (/^\|\s*[-:]+/.test(line))
+            continue;
+        const cells = line
+            .split("|")
+            .map((c) => c.trim())
+            .filter((_, idx, arr) => idx > 0 && idx < arr.length - 1);
+        if (cells.length < 4)
+            continue;
+        if (/演示模块|Demo Module/i.test(cells[0]))
+            continue;
+        const signals = ((_k = cells[3]) !== null && _k !== void 0 ? _k : "")
+            .split(/[、,，|；;]/)
+            .map((s) => s.trim())
+            .filter((s) => s.length >= 2);
+        mappings.push({
+            moduleName: cells[0],
+            demoRef: cells[1],
+            productionPath: cells[2].replace(/\\/g, "/"),
+            interactionSignals: signals,
+            rowLine: i + 1,
+        });
+    }
+    return { hasSection: true, exempt, demoRoot, demoStack, mappings };
+}
+async function readChangeDesignAndTasks(pkgRoot, changeName) {
+    const changeDir = path_1.default.join(pkgRoot, "openspec/changes", changeName);
+    const design = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, "design.md"));
+    const tasks = await (0, fs_1.readFileIfExists)(path_1.default.join(changeDir, "tasks.md"));
+    return { design, tasks };
+}
+async function changeHasUiScenarios(pkgRoot, changeName) {
+    const specsDir = path_1.default.join(pkgRoot, "openspec/changes", changeName, "specs");
+    let entries;
+    try {
+        entries = await promises_1.default.readdir(specsDir, { withFileTypes: true });
+    }
+    catch {
+        return false;
+    }
+    for (const cap of entries) {
+        if (!cap.isDirectory())
+            continue;
+        const specPath = path_1.default.join(specsDir, cap.name, "spec.md");
+        const content = await (0, fs_1.readFileIfExists)(specPath);
+        if (!content)
+            continue;
+        const blocks = content.split(/^####\s+Scenario:/m);
+        for (let i = 1; i < blocks.length; i += 1) {
+            if (UI_SCENARIO_KEYWORDS.test(blocks[i]))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Propose / AC 阶段：design 须声明演示参照与模块映射表；tasks 须含演示迁移段。
+ */
+async function checkDemoReferenceArtifacts(pkgRoot, changeName) {
+    const checks = [];
+    const skip = process.env.POQUAN_SKIP_DEMO_REFERENCE === "1" ||
+        process.env.OPSX_SKIP_DEMO_REFERENCE === "1";
+    if (skip) {
+        checks.push({
+            name: "demo-reference-artifacts",
+            ok: true,
+            detail: "SKIP: OPSX_SKIP_DEMO_REFERENCE=1",
+        });
+        return checks;
+    }
+    const requiresUi = await changeHasUiScenarios(pkgRoot, changeName);
+    const { design, tasks } = await readChangeDesignAndTasks(pkgRoot, changeName);
+    if (!design) {
+        checks.push({
+            name: "demo-reference-design",
+            ok: !requiresUi,
+            detail: requiresUi
+                ? "UI change 缺少 design.md，无法声明演示代码参照"
+                : "无 UI Scenario，跳过演示参照",
+        });
+        return checks;
+    }
+    const parsed = parseDemoReferenceSection(design);
+    if (parsed.exempt) {
+        checks.push({
+            name: "demo-reference-design",
+            ok: true,
+            detail: `DEMO_REFERENCE_EXEMPT: ${parsed.exempt}`,
+        });
+        return checks;
+    }
+    if (!requiresUi) {
+        checks.push({
+            name: "demo-reference-design",
+            ok: true,
+            detail: "无 UI Scenario，不要求演示映射表",
+        });
+        return checks;
+    }
+    if (!parsed.hasSection) {
+        checks.push({
+            name: "demo-reference-design",
+            ok: false,
+            detail: "design.md 缺少 ## 演示代码参照（须映射演示模块→生产组件→关键交互）",
+        });
+        return checks;
+    }
+    if (!parsed.demoRoot) {
+        checks.push({
+            name: "demo-reference-root",
+            ok: false,
+            detail: "演示代码参照 未填写「演示代码根路径」（Vue/React 演示仓库或目录）",
+        });
+    }
+    else {
+        checks.push({
+            name: "demo-reference-root",
+            ok: true,
+            detail: `演示根路径: ${parsed.demoRoot}`,
+        });
+    }
+    if (parsed.mappings.length === 0) {
+        checks.push({
+            name: "demo-module-mapping",
+            ok: false,
+            detail: "演示模块映射表为空（至少须覆盖详情/弹窗等每个 UI 子模块一行）",
+        });
+    }
+    else {
+        checks.push({
+            name: "demo-module-mapping",
+            ok: true,
+            detail: `已登记 ${parsed.mappings.length} 个演示模块映射`,
+        });
+    }
+    const tasksText = tasks !== null && tasks !== void 0 ? tasks : "";
+    const hasMigrationSection = /##\s*演示模块迁移|演示模块迁移/.test(tasksText);
+    const missingInTasks = [];
+    for (const m of parsed.mappings) {
+        const prodBase = path_1.default.basename(m.productionPath);
+        if (!tasksText.includes(m.moduleName) && !tasksText.includes(prodBase)) {
+            missingInTasks.push(m.moduleName);
+        }
+    }
+    checks.push({
+        name: "demo-tasks-migration",
+        ok: hasMigrationSection && missingInTasks.length === 0,
+        detail: hasMigrationSection && missingInTasks.length === 0
+            ? "tasks.md 含演示模块迁移且覆盖全部映射行"
+            : `tasks 缺少演示迁移: section=${hasMigrationSection}, 未覆盖模块=${missingInTasks.join(", ") || "无"}`,
+    });
+    return checks;
+}
+/**
+ * Validate / Deliver：生产代码须实现映射表中的组件与关键交互信号。
+ */
+async function checkDemoImplementationCoverage(pkgRoot, changeName) {
+    const checks = [];
+    const artifactChecks = await checkDemoReferenceArtifacts(pkgRoot, changeName);
+    const exempt = artifactChecks.some((c) => c.ok && c.detail.startsWith("DEMO_REFERENCE_EXEMPT"));
+    if (exempt || artifactChecks.some((c) => c.name === "demo-reference-design" && c.ok && c.detail.includes("跳过"))) {
+        checks.push(...artifactChecks.filter((c) => c.ok));
+        return checks;
+    }
+    const failedArtifact = artifactChecks.filter((c) => !c.ok);
+    if (failedArtifact.length > 0) {
+        checks.push(...failedArtifact);
+        return checks;
+    }
+    const { design } = await readChangeDesignAndTasks(pkgRoot, changeName);
+    const parsed = parseDemoReferenceSection(design !== null && design !== void 0 ? design : "");
+    const failures = [];
+    for (const m of parsed.mappings) {
+        const prodRel = m.productionPath.replace(/^\.\//, "");
+        const abs = path_1.default.join(pkgRoot, prodRel);
+        const content = await (0, fs_1.readFileIfExists)(abs);
+        if (content === null) {
+            failures.push(`${m.moduleName}: 生产文件不存在 ${prodRel}`);
+            continue;
+        }
+        const code = (0, testAssertionAnalysis_1.stripComments)(content);
+        const missingSignals = m.interactionSignals.filter((s) => !code.includes(s));
+        if (m.interactionSignals.length > 0 && missingSignals.length === m.interactionSignals.length) {
+            failures.push(`${m.moduleName}: ${prodRel} 未实现任何关键交互（${m.interactionSignals.join("、")}）`);
+        }
+        else if (missingSignals.length > 0) {
+            failures.push(`${m.moduleName}: ${prodRel} 缺少交互信号: ${missingSignals.join("、")}`);
+        }
+    }
+    checks.push({
+        name: "demo-implementation-coverage",
+        ok: failures.length === 0,
+        detail: failures.length === 0
+            ? `演示模块已全部落地（${parsed.mappings.length} 项）`
+            : failures.join(" | "),
+    });
+    return checks;
+}