sdd-flow-kit 1.3.21 → 1.3.23

package/dist/cli.js

@@ -27,15 +27,42 @@ 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 inferProject_1 = require("./core/inferProject");
 const ALLOWED_AGENTS = ["cursor", "claude-code", "codex", "openclaw", "custom"];
-function getArgValue(flag) {
+/** 读取 flag 后的参数；allowMultiWord 时合并至下一个以 - 开头的 token（支持未加引号的 AD Tools）。 */
+function getArgValue(flag, options) {
     const idx = process_1.default.argv.indexOf(flag);
     if (idx === -1)
         return null;
-    const v = process_1.default.argv[idx + 1];
-    if (!v)
+    const first = process_1.default.argv[idx + 1];
+    if (!first || first.startsWith("-"))
         return null;
-    return v;
+    if (!(options === null || options === void 0 ? void 0 : options.allowMultiWord))
+        return first;
+    const parts = [first];
+    for (let i = idx + 2; i < process_1.default.argv.length; i += 1) {
+        const token = process_1.default.argv[i];
+        if (token.startsWith("-"))
+            break;
+        parts.push(token);
+    }
+    return parts.join(" ");
+}
+/** 统计 flag 在 argv 中占用的 token 数（含多词值），供 getFreeTextArgs 跳过。 */
+function countFlagArgTokens(flag) {
+    const idx = process_1.default.argv.indexOf(flag);
+    if (idx === -1)
+        return 0;
+    if (flag === "--project") {
+        const raw = getArgValue("--project", { allowMultiWord: true });
+        if (!raw)
+            return 1;
+        return 1 + raw.split(" ").length;
+    }
+    const next = process_1.default.argv[idx + 1];
+    if (!next || next.startsWith("-"))
+        return 1;
+    return 2;
 }
 function getFreeTextArgs(startIndex) {
     const flagsWithValue = new Set([
@@ -64,7 +91,8 @@ function getFreeTextArgs(startIndex) {
             continue;
         }
         if (flagsWithValue.has(token)) {
-            i += 1;
+            const consumed = countFlagArgTokens(token);
+            i += Math.max(consumed - 1, 0);
             continue;
         }
         if (token.startsWith("--"))
@@ -96,6 +124,7 @@ function printHelp() {
         "",
         "5) 环境健检：",
         "   npx sdd-flow-kit doctor --agent cursor",
+        "   npx sdd-flow-kit doctor --fix -y   # 自动补齐 OPSX / Playwright E2E",
         "",
         "6) Apply 前确保 OPSX+TDD+Playwright（/opsx-apply 前必须）：",
         "   npx sdd-flow-kit ensure-opsx --agent cursor -y",
@@ -142,7 +171,7 @@ function printHelp() {
         "   环境变量 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 | BreakX（默认 OMS，用于生成 docs/*-doc-skill）",
+        "   --project <name>       OMS | ADI | 欢盟 | AD Tools | BreakX（默认 OMS；支持 \"AD Tools\" / AD Tools / adtools）",
         "   -y                     非交互模式（使用默认值）",
         "   --dry-run              预演模式：仅检测并输出计划，不执行写入/安装/切分支",
         "   --plan-json            输出机器可读 JSON 计划结果",
@@ -152,7 +181,7 @@ function printHelp() {
     ].join("\n"));
 }
 async function main() {
-    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l, _m;
+    var _a, _b, _c, _d, _e, _f, _g, _h, _j, _k, _l;
     const cmd = process_1.default.argv[2];
     if (!cmd || cmd === "--help" || cmd === "-h") {
         printHelp();
@@ -216,7 +245,9 @@ async function main() {
         ? ((_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");
+    const rawProjectArg = getArgValue("--project", { allowMultiWord: true });
+    const resolvedProject = rawProjectArg ? (0, inferProject_1.resolveProjectKindInput)(rawProjectArg) : null;
+    const projectKind = (_j = resolvedProject !== null && resolvedProject !== void 0 ? resolvedProject : ((guardIntent === null || guardIntent === void 0 ? void 0 : guardIntent.product) ? (0, inferProject_1.resolveProjectKindInput)(guardIntent.product) : null)) !== null && _j !== void 0 ? _j : "OMS";
     if (!ALLOWED_AGENTS.includes(agentValue)) {
         // eslint-disable-next-line no-console
         console.error(`不支持的 --agent: ${agentValue}`);
@@ -225,10 +256,9 @@ async function main() {
         return;
     }
     const agent = agentValue;
-    const allowedProjects = ["OMS", "ADI", "欢盟", "AD Tools", "BreakX"];
-    if (!allowedProjects.includes(projectKind)) {
+    if (rawProjectArg && !resolvedProject) {
         // eslint-disable-next-line no-console
-        console.error(`不支持的 --project: ${projectKind}（可选：${allowedProjects.join(" / ")}）`);
+        console.error(`不支持的 --project: ${rawProjectArg}（可选：${inferProject_1.ALLOWED_PROJECTS.join(" / ")}；别名示例：adtools）`);
         process_1.default.exitCode = 1;
         return;
     }
@@ -467,7 +497,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const from = ((_l = getArgValue("--from")) !== null && _l !== void 0 ? _l : "docs-done");
+        const from = ((_k = getArgValue("--from")) !== null && _k !== void 0 ? _k : "docs-done");
         if (!CHAIN_FROM.includes(from)) {
             // eslint-disable-next-line no-console
             console.error(`chain 需要 --from ${CHAIN_FROM.join("|")}`);
@@ -496,7 +526,7 @@ async function main() {
             process_1.default.exitCode = 1;
             return;
         }
-        const modeArg = (_m = getArgValue("--execution-mode")) !== null && _m !== void 0 ? _m : getArgValue("--executionMode");
+        const modeArg = (_l = getArgValue("--execution-mode")) !== null && _l !== void 0 ? _l : getArgValue("--executionMode");
         const textArg = getArgValue("--text");
         const strictCommands = process_1.default.argv.includes("--strict-commands");
         const result = await (0, runSessionMode_1.runSessionMode)({

package/dist/core/bootstrap.js

@@ -8,6 +8,7 @@ const path_1 = __importDefault(require("path"));
 const inferProject_1 = require("./inferProject");
 const packageJsonPatch_1 = require("./packageJsonPatch");
 const opsxDelivery_1 = require("./opsxDelivery");
+const playwrightEnsure_1 = require("./playwrightEnsure");
 const projectRoots_1 = require("./projectRoots");
 const setupProject_1 = require("../steps/setupProject");
 /**
@@ -16,41 +17,66 @@ const setupProject_1 = require("../steps/setupProject");
 async function bootstrapProjectIfNeeded(options) {
     var _a;
     const installRoot = (0, projectRoots_1.resolveInstallRoot)(options.projectRoot);
+    const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(installRoot);
     const opsxReady = await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot);
     const sddReady = await (0, projectRoots_1.isSddKitSkillInstalled)(installRoot);
-    if (opsxReady && sddReady) {
+    const pwReady = await (0, playwrightEnsure_1.isPlaywrightEnvironmentReady)(pkgRoot);
+    if (opsxReady && sddReady && pwReady.ready) {
         return false;
     }
     if (options.dryRun) {
         return true;
     }
-    const kind = (_a = options.projectKind) !== null && _a !== void 0 ? _a : (await (0, inferProject_1.inferProjectKind)(installRoot));
-    const missing = [];
-    if (!sddReady)
-        missing.push("SDD skill");
-    if (!opsxReady)
-        missing.push("OPSX");
-    // eslint-disable-next-line no-console
-    console.log(`[sdd-flow-kit] 检测到 ${missing.join(" / ")} 未就绪，正在自动 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) {
+    if (opsxReady && sddReady && !pwReady.ready) {
         // eslint-disable-next-line no-console
-        console.log("[sdd-flow-kit] 已写入 pnpm.onlyBuiltDependencies: sdd-flow-kit；下次 pnpm install 将执行 postinstall");
+        console.log(`[sdd-flow-kit] 检测到 Playwright E2E 未就绪（${pwReady.missing.join("、")}），正在自动补齐…`);
+        const pw = await (0, playwrightEnsure_1.ensurePlaywrightEnvironment)(pkgRoot, false);
+        if (pw.actions.length > 0) {
+            for (const action of pw.actions) {
+                // eslint-disable-next-line no-console
+                console.log(`[sdd-flow-kit]   - ${action}`);
+            }
+        }
     }
-    await (0, setupProject_1.setupProject)({
-        projectRoot: installRoot,
-        agent: options.agent,
-        yes: true,
-        light: opsxReady,
-        skipGit: true,
-        projectKind: kind !== null && kind !== void 0 ? kind : "OMS",
-    });
-    if (!(await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot))) {
-        await (0, opsxDelivery_1.ensureOpsxWorkflow)({
+    else {
+        const kind = (_a = options.projectKind) !== null && _a !== void 0 ? _a : (await (0, inferProject_1.inferProjectKind)(installRoot));
+        const missing = [];
+        if (!sddReady)
+            missing.push("SDD skill");
+        if (!opsxReady)
+            missing.push("OPSX");
+        if (!pwReady.ready)
+            missing.push("Playwright E2E");
+        // eslint-disable-next-line no-console
+        console.log(`[sdd-flow-kit] 检测到 ${missing.join(" / ")} 未就绪，正在自动 bootstrap（等价 install -y）…`);
+        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: opsxReady,
+            skipGit: true,
+            projectKind: kind !== null && kind !== void 0 ? kind : "OMS",
         });
+        if (!(await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot))) {
+            await (0, opsxDelivery_1.ensureOpsxWorkflow)({
+                projectRoot: installRoot,
+                agent: options.agent,
+            });
+        }
+        const pw = await (0, playwrightEnsure_1.ensurePlaywrightEnvironment)(pkgRoot, false);
+        if (pw.actions.length > 0) {
+            // eslint-disable-next-line no-console
+            console.log(`[sdd-flow-kit] Playwright: ${pw.detail}`);
+            for (const action of pw.actions) {
+                // eslint-disable-next-line no-console
+                console.log(`[sdd-flow-kit]   - ${action}`);
+            }
+        }
     }
     const ready = await (0, opsxDelivery_1.isOpsxApplyReady)(installRoot);
     const skillReady = await (0, projectRoots_1.isSddKitSkillInstalled)(installRoot);

package/dist/core/e2eScaffold.js

@@ -0,0 +1,64 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.countE2eSpecFiles = countE2eSpecFiles;
+exports.ensureE2eScaffold = ensureE2eScaffold;
+const promises_1 = __importDefault(require("fs/promises"));
+const path_1 = __importDefault(require("path"));
+const fs_1 = require("./fs");
+const templates_1 = require("./templates");
+const E2E_SPEC_RE = /\.spec\.(ts|js|mjs)$/i;
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** 统计 e2e/ 下可执行的 Playwright 用例文件数 */
+async function countE2eSpecFiles(pkgRoot) {
+    const e2eDir = path_1.default.join(pkgRoot, "e2e");
+    if (!(await pathExists(e2eDir)))
+        return 0;
+    let count = 0;
+    async function walk(dir) {
+        const entries = await promises_1.default.readdir(dir, { withFileTypes: true });
+        for (const ent of entries) {
+            const full = path_1.default.join(dir, ent.name);
+            if (ent.isDirectory()) {
+                await walk(full);
+            }
+            else if (E2E_SPEC_RE.test(ent.name)) {
+                count += 1;
+            }
+        }
+    }
+    await walk(e2eDir);
+    return count;
+}
+/** 若项目尚无 e2e 下任何 .spec.ts，写入最小 smoke 用例，避免 Playwright 环境检测永远失败。 */
+async function ensureE2eScaffold(pkgRoot, dryRun = false) {
+    const existing = await countE2eSpecFiles(pkgRoot);
+    if (existing > 0) {
+        return { ok: true, detail: `已有 ${existing} 个 e2e spec`, scaffolded: false };
+    }
+    const target = path_1.default.join(pkgRoot, "e2e", "smoke", "app-loads.spec.ts");
+    if (dryRun) {
+        return {
+            ok: false,
+            detail: `dry-run: 将写入 ${path_1.default.relative(pkgRoot, target)}`,
+            scaffolded: false,
+        };
+    }
+    const content = await (0, templates_1.loadTemplateText)("e2e-scaffold/smoke-app-loads.spec.ts.template");
+    await (0, fs_1.writeTextFileEnsuredDir)(target, content);
+    return {
+        ok: true,
+        detail: `已写入 smoke 用例: ${path_1.default.relative(pkgRoot, target)}`,
+        scaffolded: true,
+    };
+}

package/dist/core/inferProject.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.PRODUCT_PREFIX_BY_KIND = exports.DOC_SKILL_BY_KIND = exports.ALLOWED_PROJECTS = void 0;
 exports.productToKind = productToKind;
+exports.resolveProjectKindInput = resolveProjectKindInput;
 exports.resolveDocSkillDir = resolveDocSkillDir;
 exports.inferProjectKind = inferProjectKind;
 const promises_1 = __importDefault(require("fs/promises"));
@@ -38,6 +39,31 @@ function productToKind(product) {
         return "BreakX";
     return "OMS";
 }
+/**
+ * 将 CLI `--project` 入参解析为规范项目类型。
+ * 支持精确名、别名（adtools / ad-tools）及带空格写法；无法识别时返回 null（避免 productToKind 默认回落 OMS）。
+ */
+function resolveProjectKindInput(raw) {
+    const value = raw.trim();
+    if (!value)
+        return null;
+    if (exports.ALLOWED_PROJECTS.includes(value)) {
+        return value;
+    }
+    const upper = value.toUpperCase();
+    const compact = upper.replace(/[\s_-]+/g, "");
+    if (upper === "ADI" || upper.includes("ADINSIGHT"))
+        return "ADI";
+    if (upper === "OMS" || upper.includes("OPERATION"))
+        return "OMS";
+    if (value === "欢盟" || upper === "HUAN" || upper === "HUANMENG" || compact === "HM")
+        return "欢盟";
+    if (upper.includes("AD TOOLS") || compact === "ADTOOLS")
+        return "AD Tools";
+    if (compact === "BREAKX" || upper.includes("POQUAN") || value.includes("破圈"))
+        return "BreakX";
+    return null;
+}
 /** 从 projectRoot 向上查找 docs/*-doc-skill（适配 frontend 子目录 + 根目录 docs） */
 async function resolveDocSkillDir(projectRoot, kind) {
     const dirName = exports.DOC_SKILL_BY_KIND[kind];

package/dist/core/opsxDelivery.js

@@ -17,6 +17,7 @@ const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
 const packageJsonPatch_1 = require("./packageJsonPatch");
 const projectRoots_1 = require("./projectRoots");
+const playwrightEnsure_1 = require("./playwrightEnsure");
 const opsxWorkflowPackage_1 = require("./opsxWorkflowPackage");
 function resolveOpsxWorkflowPackage() {
     return (0, opsxWorkflowPackage_1.resolveOpsxWorkflowPackageForCwd)(process.cwd());
@@ -249,19 +250,18 @@ async function collectDeliverySetupChecks(installRoot) {
         });
     }
     try {
-        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);
+        const pwReady = await (0, playwrightEnsure_1.isPlaywrightEnvironmentReady)(root);
         checks.push({
-            name: "playwright-dependency",
-            ok: hasPw,
-            detail: hasPw ? "@playwright/test 或 playwright 已声明" : "package.json 缺少 Playwright 依赖",
+            name: "playwright-e2e-environment",
+            ok: pwReady.ready,
+            detail: pwReady.ready
+                ? "Playwright 依赖、node_modules 与 e2e spec 已就绪"
+                : `缺失: ${pwReady.missing.join("、")}（install/bootstrap 会自动补齐，或 npx sdd-flow-kit doctor --fix）`,
         });
     }
     catch {
         checks.push({
-            name: "playwright-dependency",
+            name: "playwright-e2e-environment",
             ok: false,
             detail: "无法读取 package.json 检查 Playwright",
         });

package/dist/core/playwrightEnsure.js

@@ -4,12 +4,25 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.hasPlaywrightDependency = hasPlaywrightDependency;
+exports.isPlaywrightDependencyInstalled = isPlaywrightDependencyInstalled;
+exports.isPlaywrightEnvironmentReady = isPlaywrightEnvironmentReady;
 exports.ensurePlaywright = ensurePlaywright;
+exports.ensurePlaywrightEnvironment = ensurePlaywrightEnvironment;
 exports.runMandatoryE2e = runMandatoryE2e;
 const child_process_1 = require("child_process");
 const promises_1 = __importDefault(require("fs/promises"));
 const path_1 = __importDefault(require("path"));
+const e2eScaffold_1 = require("./e2eScaffold");
 const packageJsonPatch_1 = require("./packageJsonPatch");
+async function pathExists(filePath) {
+    try {
+        await promises_1.default.access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 async function detectPackageManager(pkgRoot) {
     try {
         await promises_1.default.access(path_1.default.join(pkgRoot, "pnpm-lock.yaml"));
@@ -43,62 +56,222 @@ async function hasPlaywrightDependency(pkgRoot) {
     const deps = { ...pkg.dependencies, ...pkg.devDependencies };
     return Boolean(deps["@playwright/test"] || deps.playwright);
 }
+/** 校验 node_modules 中是否已实际安装 @playwright/test（避免仅 package.json 声明但 pnpm store 不一致） */
+async function isPlaywrightDependencyInstalled(pkgRoot) {
+    return pathExists(path_1.default.join(pkgRoot, "node_modules", "@playwright", "test", "package.json"));
+}
 function runCmd(cmd, args, cwd) {
-    var _a;
+    var _a, _b, _c;
     const ret = (0, child_process_1.spawnSync)(cmd, args, {
         cwd,
-        stdio: "inherit",
+        stdio: "pipe",
+        encoding: "utf8",
         shell: process.platform === "win32",
         env: process.env,
     });
+    const output = `${(_a = ret.stdout) !== null && _a !== void 0 ? _a : ""}${(_b = ret.stderr) !== null && _b !== void 0 ? _b : ""}`;
     if (ret.status !== 0) {
-        return { ok: false, detail: `${cmd} ${args.join(" ")} 退出码 ${(_a = ret.status) !== null && _a !== void 0 ? _a : 1}` };
+        return { ok: false, detail: `${cmd} ${args.join(" ")} 退出码 ${(_c = ret.status) !== null && _c !== void 0 ? _c : 1}`, output };
     }
-    return { ok: true, detail: "ok" };
+    return { ok: true, detail: "ok", output };
+}
+function isPnpmStoreMismatch(output) {
+    return /ERR_PNPM_UNEXPECTED_STORE|Unexpected store location/i.test(output);
 }
 /**
- * 强制确保 Playwright 可用：缺依赖则安装，缺浏览器则 install chromium，缺 test:e2e 则写入脚本。
+ * pnpm 项目 node_modules 与 lock/store 不一致时先执行 install，修复后再 add Playwright。
  */
-async function ensurePlaywright(pkgRoot, dryRun = false) {
+async function repairPnpmNodeModules(pkgRoot, dryRun) {
+    const pm = await detectPackageManager(pkgRoot);
+    if (pm !== "pnpm") {
+        return { ok: true, detail: "非 pnpm 项目，跳过 store 修复" };
+    }
+    if (!(await pathExists(path_1.default.join(pkgRoot, "pnpm-lock.yaml")))) {
+        return { ok: true, detail: "无 pnpm-lock.yaml，跳过 store 修复" };
+    }
+    const needsRepair = !(await pathExists(path_1.default.join(pkgRoot, "node_modules"))) ||
+        ((await hasPlaywrightDependency(pkgRoot)) && !(await isPlaywrightDependencyInstalled(pkgRoot)));
+    if (!needsRepair) {
+        return { ok: true, detail: "pnpm node_modules 已就绪" };
+    }
+    if (dryRun) {
+        return { ok: false, detail: "dry-run: 将执行 pnpm install 修复 node_modules/store" };
+    }
+    const install = runCmd("pnpm", ["install"], pkgRoot);
+    if (!install.ok) {
+        return { ok: false, detail: `pnpm install 失败: ${install.detail}` };
+    }
+    return { ok: true, detail: "已执行 pnpm install 修复 node_modules" };
+}
+async function installPlaywrightDependency(pkgRoot, pm, dryRun) {
+    if (dryRun) {
+        return { ok: false, detail: `dry-run: 将安装 @playwright/test（${pm}）`, installed: false };
+    }
+    const addArgs = pm === "pnpm"
+        ? ["add", "-D", "@playwright/test"]
+        : pm === "yarn"
+            ? ["add", "-D", "@playwright/test"]
+            : ["install", "-D", "@playwright/test"];
+    let add = runCmd(pm, addArgs, pkgRoot);
+    if (!add.ok && pm === "pnpm" && isPnpmStoreMismatch(add.output)) {
+        const reinstall = runCmd("pnpm", ["install"], pkgRoot);
+        if (!reinstall.ok) {
+            return { ok: false, detail: `pnpm store 修复失败: ${reinstall.detail}`, installed: false };
+        }
+        add = runCmd(pm, addArgs, pkgRoot);
+    }
+    if (!add.ok) {
+        return { ok: false, detail: `安装 @playwright/test 失败: ${add.detail}`, installed: false };
+    }
+    return { ok: true, detail: "已安装 @playwright/test", installed: true };
+}
+async function installPlaywrightBrowsers(pkgRoot, dryRun) {
     var _a;
+    if (dryRun) {
+        return { ok: true, detail: "dry-run: 将安装 chromium 浏览器" };
+    }
+    const pkg = await readPkg(pkgRoot);
+    const script = (_a = pkg === null || pkg === void 0 ? void 0 : pkg.scripts) === null || _a === void 0 ? void 0 : _a["playwright:install"];
+    if (script) {
+        const pm = await detectPackageManager(pkgRoot);
+        const runScript = pm === "yarn" ? ["run", "playwright:install"] : ["run", "playwright:install"];
+        const viaScript = runCmd(pm, runScript, pkgRoot);
+        if (viaScript.ok) {
+            return { ok: true, detail: "已执行 playwright:install" };
+        }
+    }
+    const browsers = runCmd("pnpm", ["exec", "playwright", "install", "chromium"], pkgRoot);
+    if (browsers.ok) {
+        return { ok: true, detail: "已执行 pnpm exec playwright install chromium" };
+    }
+    const fallback = runCmd("npx", ["playwright", "install", "chromium"], pkgRoot);
+    if (!fallback.ok) {
+        return { ok: false, detail: `playwright install chromium 失败: ${fallback.detail}` };
+    }
+    return { ok: true, detail: "已执行 npx playwright install chromium" };
+}
+async function ensurePlaywrightScripts(pkgRoot, dryRun) {
+    var _a, _b, _c;
+    const pkg = await readPkg(pkgRoot);
+    if (!pkg)
+        return;
+    const updates = {};
+    if (!((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a["test:e2e"])) {
+        updates["test:e2e"] = "playwright test";
+    }
+    if (!((_b = pkg.scripts) === null || _b === void 0 ? void 0 : _b["playwright:install"])) {
+        const pm = await detectPackageManager(pkgRoot);
+        updates["playwright:install"] =
+            pm === "pnpm" ? "pnpm exec playwright install chromium" : "npx playwright install chromium";
+    }
+    if (!((_c = pkg.scripts) === null || _c === void 0 ? void 0 : _c.e2e)) {
+        const pm = await detectPackageManager(pkgRoot);
+        updates.e2e = pm === "pnpm" ? "pnpm exec playwright test e2e --workers=1" : "npx playwright test e2e --workers=1";
+    }
+    if (Object.keys(updates).length === 0 || dryRun)
+        return;
+    await (0, packageJsonPatch_1.patchPackageJsonScripts)(path_1.default.join(pkgRoot, "package.json"), updates, {
+        minDependencyCount: 1,
+        minBytes: 40,
+        minSizeRatio: 0.3,
+    });
+}
+/** Playwright 依赖、浏览器与 e2e spec 是否满足交付前最低要求 */
+async function isPlaywrightEnvironmentReady(pkgRoot) {
+    const missing = [];
+    if (!(await hasPlaywrightDependency(pkgRoot))) {
+        missing.push("@playwright/test 依赖未声明");
+    }
+    else if (!(await isPlaywrightDependencyInstalled(pkgRoot))) {
+        missing.push("@playwright/test 未安装到 node_modules");
+    }
+    if (!(await pathExists(path_1.default.join(pkgRoot, "playwright.config.ts"))) &&
+        !(await pathExists(path_1.default.join(pkgRoot, "playwright.config.js")))) {
+        missing.push("playwright.config.ts/js");
+    }
+    const specCount = await (0, e2eScaffold_1.countE2eSpecFiles)(pkgRoot);
+    if (specCount === 0) {
+        missing.push("e2e/**/*.spec.ts");
+    }
+    return { ready: missing.length === 0, missing };
+}
+/**
+ * 强制确保 Playwright 可用：pnpm install 修复 store、安装依赖、浏览器与 e2e smoke 脚手架。
+ */
+async function ensurePlaywright(pkgRoot, dryRun = false) {
     const pkg = await readPkg(pkgRoot);
     if (!pkg) {
         return { ok: false, detail: "无法读取 package.json", installed: false };
     }
+    const repair = await repairPnpmNodeModules(pkgRoot, dryRun);
+    if (!repair.ok) {
+        return { ok: false, detail: repair.detail, installed: false };
+    }
     const pm = await detectPackageManager(pkgRoot);
     let installed = false;
-    if (!(await hasPlaywrightDependency(pkgRoot))) {
-        if (dryRun) {
-            return {
-                ok: false,
-                detail: `dry-run: 将安装 @playwright/test（${pm}）`,
-                installed: false,
-            };
-        }
-        const addArgs = pm === "pnpm"
-            ? ["add", "-D", "@playwright/test"]
-            : pm === "yarn"
-                ? ["add", "-D", "@playwright/test"]
-                : ["install", "-D", "@playwright/test"];
-        const add = runCmd(pm, addArgs, pkgRoot);
+    if (!(await hasPlaywrightDependency(pkgRoot)) || !(await isPlaywrightDependencyInstalled(pkgRoot))) {
+        const add = await installPlaywrightDependency(pkgRoot, pm, dryRun);
         if (!add.ok) {
-            return { ok: false, detail: `安装 @playwright/test 失败: ${add.detail}`, installed: false };
-        }
-        installed = true;
-    }
-    if (!((_a = pkg.scripts) === null || _a === void 0 ? void 0 : _a["test:e2e"])) {
-        if (!dryRun) {
-            await (0, packageJsonPatch_1.patchPackageJsonScripts)(path_1.default.join(pkgRoot, "package.json"), { "test:e2e": "playwright test" }, { minDependencyCount: 1, minBytes: 40, minSizeRatio: 0.3 });
+            return { ok: false, detail: add.detail, installed: false };
         }
+        installed = installed || add.installed;
     }
-    if (dryRun) {
-        return { ok: true, detail: "dry-run: Playwright 已就绪", installed };
+    await ensurePlaywrightScripts(pkgRoot, dryRun);
+    const scaffold = await (0, e2eScaffold_1.ensureE2eScaffold)(pkgRoot, dryRun);
+    if (!scaffold.ok && dryRun) {
+        return { ok: false, detail: scaffold.detail, installed };
     }
-    const browsers = runCmd("npx", ["playwright", "install", "chromium"], pkgRoot);
+    const browsers = await installPlaywrightBrowsers(pkgRoot, dryRun);
     if (!browsers.ok) {
-        return { ok: false, detail: `playwright install chromium 失败: ${browsers.detail}`, installed };
+        return { ok: false, detail: browsers.detail, installed };
+    }
+    const ready = await isPlaywrightEnvironmentReady(pkgRoot);
+    if (!ready.ready && !dryRun) {
+        return {
+            ok: false,
+            detail: `Playwright 仍缺: ${ready.missing.join("、")}`,
+            installed,
+        };
+    }
+    return {
+        ok: true,
+        detail: installed ? "已安装 @playwright/test、chromium 与 e2e smoke" : "Playwright 已就绪",
+        installed,
+    };
+}
+/**
+ * install / bootstrap / doctor 统一入口：检测未就绪则自动执行 pnpm install → add @playwright/test → playwright:install → e2e scaffold。
+ */
+async function ensurePlaywrightEnvironment(pkgRoot, dryRun = false) {
+    const before = await isPlaywrightEnvironmentReady(pkgRoot);
+    if (before.ready) {
+        return { ok: true, detail: "Playwright E2E 环境已就绪", actions: [] };
+    }
+    const actions = [`检测到缺失: ${before.missing.join("、")}`];
+    const result = await ensurePlaywright(pkgRoot, dryRun);
+    if (result.installed) {
+        actions.push("安装 @playwright/test");
+    }
+    if (result.ok) {
+        actions.push(result.detail);
+    }
+    else {
+        actions.push(result.detail);
+        return { ok: false, detail: result.detail, actions };
     }
-    return { ok: true, detail: installed ? "已安装 @playwright/test 与 chromium" : "Playwright 已就绪", installed };
+    const after = await isPlaywrightEnvironmentReady(pkgRoot);
+    if (!after.ready && !dryRun) {
+        return {
+            ok: false,
+            detail: `Playwright 仍缺: ${after.missing.join("、")}`,
+            actions,
+        };
+    }
+    return {
+        ok: true,
+        detail: dryRun ? "dry-run: Playwright 环境将补齐" : "Playwright E2E 环境已自动补齐",
+        actions,
+    };
 }
 /** 强制执行 E2E（先 ensurePlaywright，再跑 test:e2e 或 playwright test） */
 async function runMandatoryE2e(pkgRoot, dryRun = false) {

package/dist/steps/doctor.js

@@ -11,6 +11,8 @@ const process_1 = __importDefault(require("process"));
 const nodeCompat_1 = require("../core/nodeCompat");
 const bootstrap_1 = require("../core/bootstrap");
 const opsxDelivery_1 = require("../core/opsxDelivery");
+const playwrightEnsure_1 = require("../core/playwrightEnsure");
+const projectRoots_1 = require("../core/projectRoots");
 function hasCommand(cmd) {
     const out = (0, child_process_1.spawnSync)("which", [cmd], { stdio: "ignore" });
     return out.status === 0;
@@ -35,6 +37,9 @@ function agentBin(agent) {
         return "openclaw";
     return null;
 }
+async function refreshDeliveryChecks(projectRoot) {
+    return (0, opsxDelivery_1.collectDeliverySetupChecks)(projectRoot);
+}
 async function runDoctor(options) {
     const checks = [];
     checks.push({
@@ -80,7 +85,7 @@ async function runDoctor(options) {
             detail: `${expectedDir} 目录存在性`,
         });
     }
-    for (const c of await (0, opsxDelivery_1.collectDeliverySetupChecks)(options.projectRoot)) {
+    for (const c of await refreshDeliveryChecks(options.projectRoot)) {
         checks.push(c);
     }
     let ok = checks.every((c) => c.ok);
@@ -91,13 +96,38 @@ async function runDoctor(options) {
             "delivery-pipeline-script",
             "package-json-delivery-script",
         ].includes(c.name));
+    const playwrightFailed = checks.some((c) => !c.ok && c.name === "playwright-e2e-environment");
+    // Playwright 优先自动补齐，避免仅为 E2E 缺失触发完整 OPSX bootstrap
+    if (!ok && playwrightFailed && !options.dryRun) {
+        const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(options.projectRoot);
+        const pw = await (0, playwrightEnsure_1.ensurePlaywrightEnvironment)(pkgRoot, false);
+        if (pw.actions.length > 0) {
+            checks.push({
+                name: "ensure-playwright-environment",
+                ok: pw.ok,
+                detail: `${pw.detail} | ${pw.actions.join(" | ")}`,
+            });
+        }
+        const delivery = await refreshDeliveryChecks(options.projectRoot);
+        checks.length = 0;
+        checks.push({
+            name: "node-version",
+            ok: (0, nodeCompat_1.isNodeVersionSupported)(),
+            detail: `Node ${process_1.default.version}（要求 ${(0, nodeCompat_1.nodeVersionRequirementLabel)()}，推荐 18/20 LTS）`,
+        }, {
+            name: "openspec-dir",
+            ok: await hasPath(path_1.default.join(options.projectRoot, "openspec")),
+            detail: "openspec 目录存在性",
+        }, ...delivery);
+        ok = checks.every((c) => c.ok);
+    }
     if (!ok && opsxStackFailed && !options.fix && !options.dryRun) {
         await (0, bootstrap_1.bootstrapProjectIfNeeded)({
             projectRoot: options.projectRoot,
             agent: options.agent,
         });
         checks.length = 0;
-        for (const c of await (0, opsxDelivery_1.collectDeliverySetupChecks)(options.projectRoot)) {
+        for (const c of await refreshDeliveryChecks(options.projectRoot)) {
             checks.push(c);
         }
         ok = checks.every((c) => c.ok);
@@ -120,6 +150,20 @@ async function runDoctor(options) {
             });
         }
         ok = checks.every((c) => c.ok);
+        if (!ok && !options.dryRun) {
+            const pkgRoot = await (0, projectRoots_1.resolvePackageRoot)(options.projectRoot);
+            const pw = await (0, playwrightEnsure_1.ensurePlaywrightEnvironment)(pkgRoot, false);
+            checks.push({
+                name: "ensure-playwright-environment",
+                ok: pw.ok,
+                detail: pw.actions.length > 0 ? `${pw.detail} | ${pw.actions.join(" | ")}` : pw.detail,
+            });
+            checks.length = 0;
+            for (const c of await refreshDeliveryChecks(options.projectRoot)) {
+                checks.push(c);
+            }
+            ok = checks.every((c) => c.ok);
+        }
     }
     return { ok, checks };
 }

package/dist/steps/setupProject.js

@@ -13,6 +13,7 @@ const readlinePrompt_1 = require("../core/readlinePrompt");
 const utils_1 = require("../core/utils");
 const opsxDelivery_1 = require("../core/opsxDelivery");
 const packageJsonPatch_1 = require("../core/packageJsonPatch");
+const playwrightEnsure_1 = require("../core/playwrightEnsure");
 const projectRoots_1 = require("../core/projectRoots");
 const templates_1 = require("../core/templates");
 const EDITOR_CHOICES = ["claude-code", "cursor", "codex", "openclaw"];
@@ -393,6 +394,16 @@ async function setupProject(options) {
         if (repaired) {
             plannedActions.push("repaired package.json opsx:delivery-pipeline scripts (poquan → opsx)");
         }
+        if (!options.light) {
+            const pw = await (0, playwrightEnsure_1.ensurePlaywrightEnvironment)(pkgRoot, false);
+            plannedActions.push(...pw.actions);
+            if (pw.ok) {
+                plannedActions.push(`Playwright E2E: ${pw.detail}`);
+            }
+            else {
+                plannedActions.push(`Playwright E2E 未完全就绪: ${pw.detail}；可执行 npx sdd-flow-kit doctor --fix -y`);
+            }
+        }
     }
     const summary = [
         "# SETUP-SUMMARY",

package/package.json

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

package/src/templates/e2e-scaffold/smoke-app-loads.spec.ts.template

@@ -0,0 +1,10 @@
+import { test, expect } from "@playwright/test";
+
+/**
+ * OPSX / sdd-flow-kit 自动写入的 smoke 用例：验证 dev 服可拉起且首页可访问。
+ * change 级验收请在本目录或子目录新增 *.spec.ts，并在 e2e-scope.config.json 绑定。
+ */
+test("应用首页可加载 @smoke", async ({ page }) => {
+  await page.goto("/");
+  await expect(page).toHaveURL(/\//);
+});