@epoint-testtech/ep-stage-skill 0.0.3-alpha.2 → 0.0.4-alpha.1

package/dist/src/cli/probe.js

@@ -0,0 +1,447 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import path from 'node:path';
+import { extractCodeListSummary } from '../extractors/code-list.js';
+import { extractHtmlPage } from '../extractors/html-page.js';
+import { extractJavaAction } from '../extractors/java-action.js';
+import { extractSpecYaml } from '../extractors/spec-yaml.js';
+import { buildCrudBusinessModuleContract } from '../normalizers/crud-contract.js';
+import { collectActionCandidates } from '../gap-planner/action-candidates.js';
+import { createSkeletonCoverage } from '../gap-planner/skeleton-coverage.js';
+import { planAgentInferredWorkflows } from '../gap-planner/plan-agent-workflows.js';
+import { summarizePageStructure } from '../capability/page-structure.js';
+import { createCoverageDiff } from '../capability/coverage-diff.js';
+import { buildSourceAnalysis } from '../inference/source-analysis.js';
+import { inferModuleHintsFromMaterials } from '../inference/module-hints-inference.js';
+/**
+ * 收集指定目录下的 HTML 物料文件。
+ *
+ * @param dir - 物料目录。
+ * @returns 排序后的绝对路径数组。
+ */
+function htmlFiles(dir) {
+    return readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('.html'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 收集指定目录下的 *Action.java 物料文件。
+ *
+ * @param dir - 物料目录。
+ * @returns 排序后的绝对路径数组。
+ */
+function javaFiles(dir) {
+    return readdirSync(dir)
+        .filter((fileName) => fileName.endsWith('Action.java'))
+        .sort()
+        .map((fileName) => path.join(dir, fileName));
+}
+/**
+ * 根据页面 ID 推断 CRUD 页面角色。
+ *
+ * @param pageId - 页面标识。
+ * @returns CRUD 页面角色。
+ */
+function inferCrudPageRole(pageId) {
+    if (pageId.endsWith('add'))
+        return 'add';
+    if (pageId.endsWith('edit'))
+        return 'edit';
+    if (pageId.endsWith('detail'))
+        return 'detail';
+    return 'list';
+}
+/**
+ * 将 HTML 控件类型映射为 spec.yaml 兼容的组件类型。
+ *
+ * @param controlType - HTML extractor 提取到的控件类型。
+ * @returns spec 字段组件类型。
+ */
+function mapHtmlControlTypeToSpecComponent(controlType) {
+    if (controlType === 'mini-combobox') {
+        return 'listbox';
+    }
+    if (controlType === 'mini-textarea') {
+        return 'textarea';
+    }
+    return 'input';
+}
+/**
+ * 在缺少 spec.yaml 时，根据 HTML 页面结构合成最小可用的 spec。
+ *
+ * 设计取舍：
+ * - searchable: 仅由列表页搜索区字段决定；
+ * - formVisible: 由 add/edit 页面字段决定；
+ * - listVisible: 优先取列表页 datagrid 列定义；
+ * - businessRules: 当前无法可靠结构化抽取，保持空数组，交给 testcase 审阅阶段。
+ *
+ * @param docsDir - 需求文档目录。
+ * @param moduleId - 模块 ID。
+ * @param codeListSummary - code_list 摘要。
+ * @param pages - 已提取的 HTML 页面集合。
+ * @returns 供 contract 正常生成使用的推理 spec。
+ */
+function inferSpecFromPages(docsDir, moduleId, codeListSummary, pages) {
+    const fieldMap = new Map();
+    const listPage = pages.find((page) => inferCrudPageRole(page.pageId) === 'list');
+    /**
+     * 合并同名字段的页面证据，避免列表页 / 新增页重复字段互相覆盖。
+     *
+     * @param field - 当前页面字段。
+     * @param role - 当前页面角色。
+     * @returns 无返回值。
+     */
+    function mergeField(field, role) {
+        const existing = fieldMap.get(field.name) ?? {
+            name: field.name,
+            label: field.label,
+            component: mapHtmlControlTypeToSpecComponent(field.controlType),
+            required: field.required,
+            searchable: false,
+            listVisible: false,
+            formVisible: false,
+            length: field.maxLength,
+        };
+        existing.label ||= field.label;
+        existing.component ||= mapHtmlControlTypeToSpecComponent(field.controlType);
+        existing.required ||= field.required;
+        existing.length ??= field.maxLength;
+        if (role === 'list') {
+            existing.searchable = true;
+        }
+        if (role === 'add' || role === 'edit') {
+            existing.formVisible = true;
+        }
+        fieldMap.set(field.name, existing);
+    }
+    for (const page of pages) {
+        const role = inferCrudPageRole(page.pageId);
+        for (const field of page.fields) {
+            mergeField(field, role);
+        }
+    }
+    for (const column of listPage?.grids.flatMap((grid) => grid.dataColumns) ?? []) {
+        if (!column.field) {
+            continue;
+        }
+        const existing = fieldMap.get(column.field) ?? {
+            name: column.field,
+            label: column.headerText || column.field,
+            component: 'input',
+            required: false,
+            searchable: false,
+            listVisible: false,
+            formVisible: false,
+        };
+        existing.label ||= column.headerText || column.field;
+        existing.listVisible = true;
+        fieldMap.set(column.field, existing);
+    }
+    return {
+        path: path.join(docsDir, 'spec.inferred-from-html.yaml'),
+        module: {
+            id: moduleId,
+            label: codeListSummary.moduleLabel || moduleId,
+        },
+        fields: Array.from(fieldMap.values()),
+        businessRules: [],
+    };
+}
+/**
+ * 解析 docs 目录下的 spec.yaml；缺失时根据 HTML 页面结构合成 fallback spec。
+ *
+ * @param docsDir - 需求文档目录。
+ * @param moduleId - 模块 ID。
+ * @param codeListSummary - 已解析的 code_list 摘要。
+ * @param pages - 已提取的 HTML 页面集合。
+ * @returns ExtractedSpecYaml。
+ */
+function resolveSpec(docsDir, moduleId, codeListSummary, pages) {
+    const specPath = path.join(docsDir, 'spec.yaml');
+    if (existsSync(specPath))
+        return extractSpecYaml(specPath);
+    return inferSpecFromPages(docsDir, moduleId, codeListSummary, pages);
+}
+/**
+ * 推断 requiredRole 默认值。
+ *
+ * 设计：testcase v2 schema 要求 cases[].requiredRole / uncoveredCandidates[].requiredRole 必填。
+ * 当前 BusinessRuleContract 不带 role 字段，hints.scenarioMatrix 也未覆盖角色；
+ * 回落到 'admin'，后续由 generate-testcase 子命令的 --required-role / hints 覆盖。
+ *
+ * @returns 默认 requiredRole 字面量。
+ */
+function deriveRequiredRole() {
+    return 'admin';
+}
+/**
+ * 从 contract 推导出 v2 schema 要求的 requiredRoles 集合。
+ *
+ * 目前只生成单一默认角色；后续可由 hints / scenario decision 注入更丰富的角色矩阵。
+ *
+ * @returns 至少包含一个默认 admin 的角色清单。
+ */
+function deriveRequiredRoles() {
+    return [{ role: 'admin', hint: undefined }];
+}
+/**
+ * 把 coverageDiff 中已覆盖动作映射成 testcase v2 coveredActions 段。
+ *
+ * @param contract - CRUD 契约（用于 evidence kind 提示）。
+ * @param coverageDiff - coverage diff trace。
+ * @returns coveredActions 数组（含 evidence <kind>=<ref>）。
+ */
+function mapCoveredActions(contract, coverageDiff) {
+    return coverageDiff.covered.map((item) => ({
+        actionId: item.actionId,
+        kind: item.label,
+        evidence: [
+            `contract=${contract.contractVersion}`,
+            `skeleton=${coverageDiff.skeletonCoverageId}`,
+        ],
+    }));
+}
+/**
+ * 把 coverageDiff 中未覆盖动作映射成 v2 uncoveredCandidates 段。
+ *
+ * @param contract - CRUD 契约（用于 evidence kind 提示）。
+ * @param coverageDiff - coverage diff trace。
+ * @param requiredRole - 默认 role；后续 spec/run 子命令可改写。
+ * @returns uncoveredCandidates 数组（含 requiredRole/businessIntent/assertionExpectation/evidence）。
+ */
+function mapUncoveredCandidates(contract, coverageDiff, requiredRole) {
+    const status = (diffStatus) => {
+        if (diffStatus === 'gap-candidate')
+            return 'planned';
+        if (diffStatus === 'partially-covered')
+            return 'candidate';
+        return 'unresolved';
+    };
+    return [
+        ...coverageDiff.gapCandidates,
+        ...coverageDiff.partiallyCovered,
+        ...coverageDiff.unresolved,
+    ].map((item) => ({
+        actionId: item.actionId,
+        label: item.label,
+        status: status(item.status),
+        requiredRole,
+        businessIntent: item.reason,
+        assertionExpectation: `验证 ${item.label} 完成后业务断言（待 run 子命令推理细化）`,
+        evidence: [`contract=${contract.contractVersion}`, `skeleton=${coverageDiff.skeletonCoverageId}`],
+    }));
+}
+/**
+ * 装配 testcase v2 顶层结构。
+ *
+ * @param input - 装配所需要素。
+ * @returns TestcaseV2。
+ */
+function assembleTestcaseV2(input) {
+    const requiredRoles = deriveRequiredRoles();
+    const defaultRole = deriveRequiredRole();
+    const coveredActions = mapCoveredActions(input.contract, input.coverageDiff);
+    const uncoveredCandidates = mapUncoveredCandidates(input.contract, input.coverageDiff, defaultRole);
+    const caseEvidence = [
+        `contract=${input.contract.contractVersion}`,
+        `skeleton=${input.coverageDiff.skeletonCoverageId}`,
+    ];
+    const cases = ['create', 'read', 'update', 'delete'].map((kind) => ({
+        caseId: `${input.contract.module.id}.${kind}`,
+        title: `${input.contract.module.label} ${kind}`,
+        scenario: input.scenario,
+        reviewStatus: 'needs_review',
+        requiredRole: defaultRole,
+        evidence: caseEvidence,
+        steps: [`执行 ${kind} 主流程（详见 .spec.ts）`],
+        assertions: [`验证 ${kind} 完成后业务断言`],
+        unresolved: [],
+    }));
+    return {
+        schemaVersion: 'v2',
+        scenario: input.scenario,
+        moduleId: input.contract.module.id,
+        moduleName: input.contract.module.label,
+        menuPath: input.menuPath,
+        requiredSystems: [{ url: '', systemName: undefined }],
+        requiredRoles,
+        coveredActions,
+        uncoveredCandidates,
+        cases,
+        reasoningSummary: {
+            conclusion: `基于 ${input.contract.contractVersion} 契约和 ${input.coverageDiff.skeletonCoverageId} 骨架覆盖度生成 ${cases.length} 条胶水用例。`,
+            evidenceChain: [
+                `contract=${input.contract.contractVersion}`,
+                `skeleton=${input.coverageDiff.skeletonCoverageId}`,
+                `codeList=${path.basename(input.codeListPath)}`,
+            ],
+            alternatives: [],
+            confidence: input.coverageDiff.reasoningSummary.confidence,
+            risks: input.coverageDiff.reasoningSummary.risks,
+            needsHumanReview: true,
+        },
+    };
+}
+/**
+ * 组装 materialInventory 章节（spec §7）。
+ *
+ * 把 probe 已解析到的 codeList / pages / actions / args 登记成可审阅的物料清单，
+ * 缺失项进 `missing` 数组。保持私有，不做跨文件抽象（Task 3 范围）。
+ *
+ * @param args - probe 入参。
+ * @param codeList - 已解析的 code_list 摘要。
+ * @param pages - 已抽取的 HTML 页面。
+ * @param actions - 已抽取的 Java Action。
+ * @returns MaterialInventoryTrace。
+ */
+function buildMaterialInventory(args, codeList, pages, actions) {
+    const missing = [];
+    const moduleIdSlot = { status: 'resolved', value: args.moduleId };
+    const menuSlot = codeList.menu
+        ? { status: 'resolved', value: codeList.menu }
+        : (() => {
+            missing.push('menu');
+            return { status: 'missing', reason: 'code_list.md 未提供 menu' };
+        })();
+    const htmlFiles = pages.map((page) => ({
+        status: 'resolved',
+        value: page.path,
+    }));
+    const javaActionFiles = actions.map((action) => ({
+        status: 'resolved',
+        value: action.path,
+    }));
+    const docsFiles = [];
+    if (args.docsDir && existsSync(args.docsDir)) {
+        docsFiles.push({ status: 'resolved', value: args.docsDir });
+    }
+    else {
+        missing.push('docsDir');
+        docsFiles.push({ status: 'missing', reason: '未提供 docsDir' });
+    }
+    return {
+        knowledgeRoot: codeList.knowledgeRoot ?? '',
+        moduleId: moduleIdSlot,
+        menu: menuSlot,
+        htmlFiles,
+        javaActionFiles,
+        docsFiles,
+        missing,
+    };
+}
+/**
+ * 把 coverageDiff（CoverageDiffTrace）映射为 InferenceTraceV1.coverageDiff 的内联形状。
+ *
+ * 映射规则（controller 裁定）：
+ * - coveredActions ← coverageDiff.covered
+ * - uncoveredCandidates ← [...gapCandidates, ...partiallyCovered, ...unresolved]
+ * - needsReview ← unresolved.map(i => i.actionId)
+ *
+ * @param coverageDiff - probe 产出的 CoverageDiffTrace。
+ * @returns InferenceTraceV1.coverageDiff。
+ */
+function mapCoverageDiffForTrace(coverageDiff) {
+    return {
+        coveredActions: coverageDiff.covered,
+        uncoveredCandidates: [
+            ...coverageDiff.gapCandidates,
+            ...coverageDiff.partiallyCovered,
+            ...coverageDiff.unresolved,
+        ],
+        needsReview: coverageDiff.unresolved.map((item) => item.actionId),
+    };
+}
+/**
+ * probe + coverage + testcase v2 装配的统一入口（REQ-CHAIN-01）。
+ *
+ * 把 run-gap-pipeline.ts 与 generate-testcase.ts 共用的物料解析 → contract → skeleton coverage →
+ * coverage diff 段抽成单一函数，避免 1881 行 run-gap-pipeline.ts 与新 CLI 双份维护。
+ *
+ * 注意：本函数只做钻探与装配，不写文件；写盘由调用方负责（保持 I/O 边界清晰）。
+ *
+ * @param args - 物料路径 + 场景。
+ * @returns contract + coverageDiff + 装配好的 TestcaseV2。
+ */
+export function runProbeAndCoverage(args) {
+    const codeList = extractCodeListSummary(args.codeListPath);
+    const pages = htmlFiles(args.webappDir).map(extractHtmlPage);
+    const actions = javaFiles(args.javaActionsDir).map(extractJavaAction);
+    // 源分析快照（spec §7 sourceAnalysis）。
+    const sourceAnalysis = buildSourceAnalysis({
+        codeListPath: args.codeListPath,
+        docsDir: args.docsDir,
+        codeList,
+        pages,
+        actions,
+    });
+    // 显式 hints 文件 vs 推理 hints：
+    // - 有 hintsPath 时读取为 explicitHints，mode 标记 explicit_override，explicitHints 流入 builders。
+    // - 无 hintsPath 时调 inferModuleHintsFromMaterials，推理出的 hints 流入 builders（替换原 undefined）。
+    let hints;
+    let moduleHintsInference;
+    if (args.hintsPath) {
+        const explicitHints = JSON.parse(readFileSync(args.hintsPath, 'utf8'));
+        // 仍跑一次推理以记录推理过程，但 mode 标记 explicit_override，builders 用 explicitHints。
+        const inferred = inferModuleHintsFromMaterials({
+            sourceAnalysis,
+            pages,
+            actions,
+            explicitHints,
+        });
+        moduleHintsInference = { ...inferred.inference, mode: 'explicit_override' };
+        hints = explicitHints;
+    }
+    else {
+        const inferred = inferModuleHintsFromMaterials({ sourceAnalysis, pages, actions });
+        moduleHintsInference = inferred.inference;
+        hints = inferred.hints;
+    }
+    const pageStructures = pages.map(summarizePageStructure);
+    const contract = buildCrudBusinessModuleContract({
+        moduleId: args.moduleId,
+        spec: resolveSpec(args.docsDir, args.moduleId, codeList, pages),
+        codeList,
+        pages,
+        actions,
+        hints,
+    });
+    const skeletonCoverage = createSkeletonCoverage(contract, hints);
+    const actionCandidates = collectActionCandidates(contract);
+    const baselineWorkflows = planAgentInferredWorkflows({ contract, actions, hints });
+    const coverageDiff = createCoverageDiff({
+        moduleId: args.moduleId,
+        actionCandidates,
+        skeletonCoverage,
+        baselineWorkflows,
+        pageStructures,
+    });
+    const testcaseV2 = assembleTestcaseV2({
+        contract,
+        coverageDiff,
+        scenario: args.scenario,
+        menuPath: args.menuPath ?? codeList.menu ?? '',
+        codeListPath: args.codeListPath,
+    });
+    // 组装 inference trace（REQ-INFER-004 / REQ-INFER-006）。
+    const materialInventory = buildMaterialInventory(args, codeList, pages, actions);
+    const reasoningSummary = {
+        conclusion: `基于 ${sourceAnalysis.mode} 源分析（置信度 ${sourceAnalysis.confidence}）与 ${moduleHintsInference.mode} 槽位推理生成契约；coverageDiff unresolved ${coverageDiff.unresolved.length} 项。`,
+        confidence: sourceAnalysis.confidence,
+        risks: [
+            ...sourceAnalysis.unresolved,
+            ...moduleHintsInference.unresolved.map((slot) => `未解析槽位：${slot}`),
+        ],
+        needsHumanReview: moduleHintsInference.unresolved.length > 0 || sourceAnalysis.confidence === 'low',
+    };
+    const inferenceTrace = {
+        schemaVersion: 'inference-trace/v1',
+        codeListPath: args.codeListPath,
+        generatedAt: new Date().toISOString(),
+        materialInventory,
+        sourceAnalysis,
+        moduleHintsInference,
+        coverageDiff: mapCoverageDiffForTrace(coverageDiff),
+        reasoningSummary,
+    };
+    return { contract, coverageDiff, testcaseV2, inferenceTrace };
+}

package/dist/src/cli/run-gap-pipeline.js

@@ -1217,6 +1217,10 @@ async function main() {
         gate: { status: 'confirmed', confirmedBy: 'policy', reason: '确定性 extractor 已完成' },
     };
     recordStage(writer, stageSummaries, 'evidence-extraction', evidenceTrace);
+    // TODO(Phase 3 convergence)：本段（contract 提取 → coverage diff → testcase 生成）的规范实现已迁到
+    // `src/cli/probe.ts` 的 runProbeAndCoverage / assembleTestcaseV2。保留此处的内联调用是 Task 1.6 为
+    // 避免现有 vitest fixture 联动断裂做的过渡。Phase 3.1 task 完成 generator 升级后应替换为
+    // import { runProbeAndCoverage } from './probe.js' 一次调用，并删除此段重复。
     const contract = buildCrudBusinessModuleContract({
         moduleId,
         spec,

package/dist/src/cli/run.d.ts

@@ -0,0 +1,63 @@
+/**
+ * run 子命令参数（REQ-CHAIN-02 / REQ-SPEC-01）。
+ *
+ * - spec：crud.spec.ts 路径（必填，由 spec 子命令产出，v1 或已含 AI 追加段 v2）；
+ * - testcase：testcase.json5 路径（必填，提供 uncoveredCandidates 与 cases[].requiredRole）；
+ * - headless：是否启动无头浏览器，真实业务系统通常 false；
+ * - projectDir：报告目录基址，默认 process.cwd()。
+ */
+export type RunArgs = {
+    spec: string;
+    testcase: string;
+    headless: boolean;
+    projectDir?: string;
+};
+/**
+ * run 子命令产物。
+ *
+ * @property specPath - 写盘后的 .spec.ts（含 AI 追加段）。
+ * @property reportDir - 本次 run 产出的报告目录。
+ * @property version - 'v1-with-planned-stubs' 表示当前 run.ts 阶段产物（已追加 planned 占位但未跑真实 Playwright + AI 推理）；
+ *   'v2' 保留给 Phase 5 真机验收阶段迁移完整 runtime 后使用。
+ */
+export type RunResult = {
+    specPath: string;
+    reportDir: string;
+    version: 'v1' | 'v1-with-planned-stubs' | 'v2';
+};
+/**
+ * AI 追加段分隔标记。重跑时 detect 已有标记则覆盖（保证幂等）。
+ */
+export declare const AI_APPEND_MARKER = "// === AI \u94BB\u63A2\u8FFD\u52A0\uFF08\u57FA\u4E8E uncoveredCandidates[].status=planned\uFF09===";
+/**
+ * 解析 run 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns RunArgs。
+ * @throws 缺少 --spec / --testcase 或参数对非法时抛错。
+ */
+export declare function parseRunArgs(argv: string[]): RunArgs;
+/**
+ * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01）。
+ *
+ * 完整设计（spec §5.4 / brief Step 6）：
+ * 1. 按 cases[].requiredRole 用 credentials.json5 登录；
+ * 2. 跑 v1 胶水部分 spec；
+ * 3. 对 uncoveredCandidates 里 status='planned' 的项做 AI 实时推理（含 requiredRole 切换）；
+ * 4. 追加段以 AI_APPEND_MARKER 分隔；重跑检测已有段则覆盖（幂等）；
+ * 5. 报告落 e2e/glue-code-mvp/glue-report/<timestamp>/；
+ * 6. 回写 projects.index.json5 的 systems[].credentialsCache 与 requirements[].lastRun*。
+ *
+ * 当前 Sub-step 6 范围：
+ * - 完整实现「步骤 4」（AI 追加段幂等覆盖契约）；
+ * - 完整实现「步骤 5」（报告目录生成）；
+ * - 步骤 1 / 2 / 3 / 6 的 Playwright runtime + AI 推理 + 索引回写在 Phase 5 真机验收阶段
+ *   迁移 run-gap-pipeline.ts 的 runtime runner 实现接入（brief 已说明 AI 推理在 Phase 5 证）。
+ *
+ * @param args - 已解析参数。
+ * @returns version: 'v1-with-planned-stubs' — 真实的 v2（Playwright 执行 + AI 推理填充 planned 项）
+ *   待 Phase 5 真机验收阶段从 run-gap-pipeline.ts 的 runtime runner 迁移过来。当前返回 'v1-with-planned-stubs'
+ *   而非 'v2' 是为了让下游 skill（glue-run-test 等）能区分"真 v2"与"stub 形态"。
+ */
+export declare function runRun(args: RunArgs): Promise<RunResult>;
+//# sourceMappingURL=run.d.ts.map

package/dist/src/cli/run.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../../../src/cli/run.ts"],"names":[],"mappings":"AAMA;;;;;;;GAOG;AACH,MAAM,MAAM,OAAO,GAAG;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,SAAS,GAAG;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,IAAI,GAAG,uBAAuB,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,gBAAgB,uGAA+D,CAAC;AAE7F;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAoBpD;AAyCD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,SAAS,CAAC,CAoB9D"}

package/dist/src/cli/run.js

@@ -0,0 +1,116 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+import { validateTestcase } from '../validation/testcase.js';
+/**
+ * AI 追加段分隔标记。重跑时 detect 已有标记则覆盖（保证幂等）。
+ */
+export const AI_APPEND_MARKER = '// === AI 钻探追加（基于 uncoveredCandidates[].status=planned）===';
+/**
+ * 解析 run 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns RunArgs。
+ * @throws 缺少 --spec / --testcase 或参数对非法时抛错。
+ */
+export function parseRunArgs(argv) {
+    const result = {};
+    const normalizedArgv = argv.filter((arg) => arg !== '--');
+    for (let index = 0; index < normalizedArgv.length; index += 2) {
+        const key = normalizedArgv[index];
+        const value = normalizedArgv[index + 1];
+        if (!key?.startsWith('--') || !value) {
+            throw new Error(`无效参数对: ${key ?? '<empty>'}`);
+        }
+        result[key.slice(2)] = value;
+    }
+    if (!result.spec)
+        throw new Error('缺少 --spec');
+    if (!result.testcase)
+        throw new Error('缺少 --testcase');
+    return {
+        spec: result.spec,
+        testcase: result.testcase,
+        // headless 默认 true；--headless false 时关闭无头。
+        headless: result.headless !== 'false',
+        projectDir: result['project-dir'],
+    };
+}
+/**
+ * 渲染 AI 追加段：每条 planned uncoveredCandidate 输出一个占位 test，含
+ * requiredRole / businessIntent / assertionExpectation 三条注释（供 AI runtime
+ * 推理时拓展为真实业务步骤）。
+ *
+ * 当前实现只生成占位骨架；真正的 AI runtime 推理在 Phase 5 真机验收阶段接入
+ * （参考 run-gap-pipeline.ts 的 planAgentInferredWorkflows 调用链）。本 Sub-step
+ * 聚焦于「追加段幂等覆盖」契约，确保重跑不会无限叠加注释体。
+ *
+ * @param planned - status='planned' 的 uncoveredCandidates。
+ * @returns 拼接后的追加段（不含 marker，由调用方串接）。
+ */
+function renderAppendedTests(planned) {
+    return planned
+        .map((item) => {
+        return [
+            `test(${JSON.stringify(item.label)}, async ({ page: _page }) => {`,
+            `  // actionId: ${item.actionId}`,
+            `  // requiredRole: ${item.requiredRole}`,
+            `  // businessIntent: ${item.businessIntent}`,
+            `  // assertionExpectation: ${item.assertionExpectation}`,
+            `  // TODO: AI runtime 推理后填入实际 Playwright 步骤`,
+            `});`,
+        ].join('\n');
+    })
+        .join('\n\n');
+}
+/**
+ * 截断现有 spec 的 AI 追加段（用于重跑覆盖）。
+ *
+ * @param specBody - 现有 spec 文件全文。
+ * @returns 截断到 AI_APPEND_MARKER 之前的基线 spec。
+ */
+function truncateAtMarker(specBody) {
+    const markerIndex = specBody.indexOf(AI_APPEND_MARKER);
+    return markerIndex >= 0 ? specBody.slice(0, markerIndex).trimEnd() : specBody.trimEnd();
+}
+/**
+ * run 子命令主体（REQ-CHAIN-02 / REQ-SPEC-01）。
+ *
+ * 完整设计（spec §5.4 / brief Step 6）：
+ * 1. 按 cases[].requiredRole 用 credentials.json5 登录；
+ * 2. 跑 v1 胶水部分 spec；
+ * 3. 对 uncoveredCandidates 里 status='planned' 的项做 AI 实时推理（含 requiredRole 切换）；
+ * 4. 追加段以 AI_APPEND_MARKER 分隔；重跑检测已有段则覆盖（幂等）；
+ * 5. 报告落 e2e/glue-code-mvp/glue-report/<timestamp>/；
+ * 6. 回写 projects.index.json5 的 systems[].credentialsCache 与 requirements[].lastRun*。
+ *
+ * 当前 Sub-step 6 范围：
+ * - 完整实现「步骤 4」（AI 追加段幂等覆盖契约）；
+ * - 完整实现「步骤 5」（报告目录生成）；
+ * - 步骤 1 / 2 / 3 / 6 的 Playwright runtime + AI 推理 + 索引回写在 Phase 5 真机验收阶段
+ *   迁移 run-gap-pipeline.ts 的 runtime runner 实现接入（brief 已说明 AI 推理在 Phase 5 证）。
+ *
+ * @param args - 已解析参数。
+ * @returns version: 'v1-with-planned-stubs' — 真实的 v2（Playwright 执行 + AI 推理填充 planned 项）
+ *   待 Phase 5 真机验收阶段从 run-gap-pipeline.ts 的 runtime runner 迁移过来。当前返回 'v1-with-planned-stubs'
+ *   而非 'v2' 是为了让下游 skill（glue-run-test 等）能区分"真 v2"与"stub 形态"。
+ */
+export async function runRun(args) {
+    if (!existsSync(args.spec))
+        throw new Error(`spec 不存在: ${args.spec}`);
+    const testcaseRaw = JSON5.parse(readFileSync(args.testcase, 'utf8'));
+    const testcase = validateTestcase(testcaseRaw);
+    const planned = testcase.uncoveredCandidates.filter((item) => item.status === 'planned');
+    const currentSpec = readFileSync(args.spec, 'utf8');
+    const baseSpec = truncateAtMarker(currentSpec);
+    if (planned.length > 0) {
+        const appendedTests = renderAppendedTests(planned);
+        writeFileSync(args.spec, `${baseSpec}\n\n${AI_APPEND_MARKER}\n${appendedTests}\n`, 'utf8');
+    }
+    else {
+        // 没有 planned 项时，仍然把 spec 收敛到 baseSpec（保证幂等：重跑能擦掉旧追加段）。
+        writeFileSync(args.spec, `${baseSpec}\n`, 'utf8');
+    }
+    const reportDir = path.join(args.projectDir ?? process.cwd(), 'e2e/glue-code-mvp/glue-report', new Date().toISOString().replace(/[:.]/g, '-'));
+    return { specPath: args.spec, reportDir, version: 'v1-with-planned-stubs' };
+}

package/dist/src/cli/spec.d.ts

@@ -0,0 +1,48 @@
+/**
+ * spec 子命令参数（REQ-SPEC-01）。
+ *
+ * - testcase：testcase.json5 路径（必填，由 testcase 子命令产出）；
+ * - out：.spec.ts 输出路径（必填，通常为 <tests-dir>/crud.spec.ts）。
+ */
+export type SpecArgs = {
+    testcase: string;
+    out: string;
+};
+/**
+ * spec 子命令产物。
+ *
+ * @property specPath - 写盘后的 .spec.ts 路径。
+ * @property version - 'v1' 表示只含 coveredActions 胶水部分，待 run 子命令追加 v2。
+ */
+export type SpecResult = {
+    specPath: string;
+    version: 'v1';
+};
+/**
+ * 解析 spec 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns SpecArgs。
+ * @throws 缺少必填参数或参数对非法时抛错。
+ */
+export declare function parseSpecArgs(argv: string[]): SpecArgs;
+/**
+ * spec 子命令主体（REQ-SPEC-01）：只生成 v1 初始版 .spec.ts，不启动浏览器。
+ *
+ * v1 = 仅 coveredActions 胶水部分（顶部注释 `// === 胶水模式生成 ===`）；
+ * run 子命令后续在底部追加 AI 推理段产 v2。
+ *
+ * 实现：
+ * 1. 校验 testcase.json5 通过 validateTestcase（v2 schema）；
+ * 2. 门禁检查：用例必须全部 confirmed、未覆盖项不得为 candidate/unresolved（REQ-INFER-007）；
+ * 3. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
+ * 4. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
+ * 5. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * 消费边界（REQ-INFER-008）：只读 testcase.json5 + contract.json，不读 inference-trace.json。
+ *
+ * @param args - 解析后的参数。
+ * @returns SpecResult（含 version='v1' 显式标识阶段）。
+ */
+export declare function runSpec(args: SpecArgs): SpecResult;
+//# sourceMappingURL=spec.d.ts.map