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

package/dist/src/cli/probe.js

@@ -0,0 +1,221 @@
+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';
+/**
+ * 收集指定目录下的 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));
+}
+/**
+ * 解析 docs 目录下的 spec.yaml；缺失时返回最小空骨架。
+ *
+ * @param docsDir - 需求文档目录。
+ * @param moduleId - 模块 ID。
+ * @param codeListSummary - 已解析的 code_list 摘要。
+ * @returns ExtractedSpecYaml。
+ */
+function resolveSpec(docsDir, moduleId, codeListSummary) {
+    const specPath = path.join(docsDir, 'spec.yaml');
+    if (existsSync(specPath))
+        return extractSpecYaml(specPath);
+    return {
+        path: specPath,
+        module: { id: moduleId, label: codeListSummary.moduleLabel },
+        fields: [],
+        businessRules: [],
+    };
+}
+/**
+ * 推断 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,
+        },
+    };
+}
+/**
+ * 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 hints = args.hintsPath
+        ? JSON.parse(readFileSync(args.hintsPath, 'utf8'))
+        : undefined;
+    const codeList = extractCodeListSummary(args.codeListPath);
+    const pages = htmlFiles(args.webappDir).map(extractHtmlPage);
+    const actions = javaFiles(args.javaActionsDir).map(extractJavaAction);
+    const pageStructures = pages.map(summarizePageStructure);
+    const contract = buildCrudBusinessModuleContract({
+        moduleId: args.moduleId,
+        spec: resolveSpec(args.docsDir, args.moduleId, codeList),
+        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,
+    });
+    return { contract, coverageDiff, testcaseV2 };
+}

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,45 @@
+/**
+ * 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. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
+ * 3. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
+ * 4. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * @param args - 解析后的参数。
+ * @returns SpecResult（含 version='v1' 显式标识阶段）。
+ */
+export declare function runSpec(args: SpecArgs): SpecResult;
+//# sourceMappingURL=spec.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"spec.d.ts","sourceRoot":"","sources":["../../../src/cli/spec.ts"],"names":[],"mappings":"AAOA;;;;;GAKG;AACH,MAAM,MAAM,QAAQ,GAAG;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,IAAI,CAAC;CACf,CAAC;AAIF;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,QAAQ,CActD;AAeD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,UAAU,CAkBlD"}

package/dist/src/cli/spec.js

@@ -0,0 +1,74 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import JSON5 from 'json5';
+import { generateStageSkeletonCrudSpec } from '../generators/stage-skeleton-script.js';
+import { validateTestcase } from '../validation/testcase.js';
+const SKELETON_MARKER_LINE = '// === 胶水模式生成（基于 contract + coveredActions）===';
+/**
+ * 解析 spec 子命令参数。
+ *
+ * @param argv - 已剥离子命令名的命令行参数。
+ * @returns SpecArgs。
+ * @throws 缺少必填参数或参数对非法时抛错。
+ */
+export function parseSpecArgs(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.testcase)
+        throw new Error('缺少 --testcase');
+    if (!result.out)
+        throw new Error('缺少 --out');
+    return { testcase: result.testcase, out: result.out };
+}
+/**
+ * 定位 testcase 旁挂的 contract.json：
+ * <tests-dir>/.ep-stage/contract.json（由 testcase 子命令的 probe 内部写入，
+ * 当前 Sub-step 4 未保存该文件；本函数兜底返回 null，调用方需先用 dev/extract-contract 显式生成）。
+ *
+ * @param testcasePath - testcase.json5 绝对路径。
+ * @returns contract.json 绝对路径或 null。
+ */
+function locateContract(testcasePath) {
+    const candidate = path.join(path.dirname(testcasePath), '.ep-stage', 'contract.json');
+    return existsSync(candidate) ? candidate : null;
+}
+/**
+ * spec 子命令主体（REQ-SPEC-01）：只生成 v1 初始版 .spec.ts，不启动浏览器。
+ *
+ * v1 = 仅 coveredActions 胶水部分（顶部注释 `// === 胶水模式生成 ===`）；
+ * run 子命令后续在底部追加 AI 推理段产 v2。
+ *
+ * 实现：
+ * 1. 校验 testcase.json5 通过 validateTestcase（v2 schema）；
+ * 2. 加载 contract.json（位于 <tests-dir>/.ep-stage/contract.json；不存在时报错引导用户先跑 testcase 子命令）；
+ * 3. 调 generateStageSkeletonCrudSpec 生成基线骨架脚本；
+ * 4. 头部插入 SKELETON_MARKER_LINE 标记，写盘。
+ *
+ * @param args - 解析后的参数。
+ * @returns SpecResult（含 version='v1' 显式标识阶段）。
+ */
+export function runSpec(args) {
+    const testcaseRaw = JSON5.parse(readFileSync(args.testcase, 'utf8'));
+    const testcase = validateTestcase(testcaseRaw);
+    const contractPath = locateContract(args.testcase);
+    if (!contractPath) {
+        throw new Error(`未找到 ${path.dirname(args.testcase)}/.ep-stage/contract.json。请先运行 \`ep-stage-skill testcase --code-list <p> --tests-dir <p>\` 生成 contract.json。`);
+    }
+    const contract = JSON.parse(readFileSync(contractPath, 'utf8'));
+    const script = generateStageSkeletonCrudSpec({
+        contract,
+        menuNavigation: testcase.menuPath,
+    });
+    const body = `${SKELETON_MARKER_LINE}\n${script}`;
+    mkdirSync(path.dirname(args.out), { recursive: true });
+    writeFileSync(args.out, body, 'utf8');
+    return { specPath: args.out, version: 'v1' };
+}

package/dist/src/context/stage-context.d.ts

@@ -10,19 +10,58 @@ export type StageContext = {
     codeListPaths: string[];
     stageContextPath?: string;
 };
+/**
+ * projects.index.json5 顶层 systems[] 条目（REQ-DATA-01 修订 / spec §4.1）。
+ *
+ * 系统级凭据缓存按 (url, role) 维度组织，跨多个 project 共用。
+ * knownRoles 与 credentialsCache 必填，可为空数组 / 空对象（spec 要求字段存在）。
+ */
+export type SystemEntry = {
+    url: string;
+    knownRoles: string[];
+    credentialsCache: Record<string, {
+        username: string;
+        password: string;
+        lastUsed: string;
+    }>;
+};
+/**
+ * projects.index.json5 中 projects[].requirements[] 条目（REQ-DATA-01 修订 / spec §4.1）。
+ */
+export type RequirementEntry = {
+    name: string;
+    requirementDir: string;
+    testsDir: string;
+    lastRunAt?: string;
+    lastRunStatus?: 'passed' | 'failed' | 'partial' | 'never';
+};
+/**
+ * projects.index.json5 中 projects[] 条目（REQ-DATA-01 修订 / spec §4.1）。
+ *
+ * stageCreateVersion 承接砍掉的 stage-context.md 元信息；requirements[] 承载需求级状态。
+ * 旧字段 envPath/knowledgeRoot/codeListPaths/stageContextPath 已被 schema 拒绝，类型层不再声明。
+ * 兼容性：旧数据若残留这些字段，由 normalizeProjectIndexEntry 内的 graceful-read 路径解析，
+ * 不污染类型契约。
+ */
 export type ProjectIndexEntry = {
     projectName: string;
     projectDir: string;
     mode: StageContextMode;
-    envPath?: string;
-    knowledgeRoot?: string;
-    codeListPaths?: string[];
-    stageContextPath?: string;
+    createdAt?: string;
+    stageCreateVersion: string;
+    requirements: RequirementEntry[];
 };
-export type ProjectIndex = {
-    version?: 1;
+/**
+ * projects.index.json5 顶层结构（REQ-DATA-01 修订 / spec §4.1）。
+ *
+ * 顶层 systems[] 承接多项目共享的系统级凭据缓存。
+ */
+export type ProjectsIndex = {
     projects: ProjectIndexEntry[];
+    systems: SystemEntry[];
 };
+/** @deprecated 旧名，使用 ProjectsIndex；保留仅为外部 import 兼容。 */
+export type ProjectIndex = ProjectsIndex;
 export type ResolveStageContextInput = {
     stageContextPath?: string;
     projectDir?: string;
@@ -34,27 +73,52 @@ export type ResolveStageContextResult = {
     context: StageContext;
     trace: ObservableStagePayload;
 };
+export type LookupProjectByRequirementInput = {
+    requirementPath: string;
+    homeDir?: string;
+};
 /**
  * 读取项目级 stage-context.md，并将相对路径归一到项目目录。
  *
+ * @deprecated stage-context.md 已砍（REQ-ENV-01 修订）；新链路应从 projects.index.json5 反查
+ *             ({@link lookupProjectByRequirement})。本函数保留仅为零回归兼容，
+ *             不要在新代码里调用。
  * @param stageContextPath - stage-context.md 文件路径。
  * @returns 归一化后的项目上下文。
  * @throws 当 frontmatter 缺少必要字段或格式不合法时抛出错误。
  */
 export declare function readStageContext(stageContextPath: string): StageContext;
 /**
- * 写入用户级 ep-stage 项目索引。
+ * 写入用户级 ep-stage 项目索引（REQ-DATA-01 修订 / spec §4.1）。
  *
- * @param input - HOME 目录和项目列表。
+ * 新 schema：顶层 `{ projects: [...], systems: [...] }`，无 `version` 字段；
+ * projects[] 条目不再写入 envPath/knowledgeRoot/codeListPaths/stageContextPath 等 legacy 字段。
+ *
+ * @param input - HOME 目录、项目列表，以及可选的 systems[]（不传按空数组写入）。
  * @returns 写入后的索引文件路径。
  */
 export declare function writeProjectIndex(input: {
     homeDir?: string;
     projects: ProjectIndexEntry[];
+    systems?: SystemEntry[];
 }): string;
+/**
+ * 从 `~/.ep-stage/projects.index.json5` 反查匹配的 ProjectIndexEntry（REQ-DATA-01 修订 / spec §5.2 §5.3）。
+ *
+ * 匹配优先级：①精确 requirementDir / testsDir 命中；②精确 projectDir 命中。
+ * 用于 glue-generate-testcase / glue-run-test skill 的「反查项目脚手架」步骤——
+ * 给定一个需求目录或项目目录，回到对应的 ProjectIndexEntry（不再依赖砍掉的 stage-context.md）。
+ *
+ * @param input - 需求路径或项目目录 + 可选 homeDir。
+ * @returns 匹配的 ProjectIndexEntry，未匹配返回 null。
+ */
+export declare function lookupProjectByRequirement(input: LookupProjectByRequirementInput): ProjectIndexEntry | null;
 /**
  * 按固定优先级解析 ep-stage 项目上下文，并返回可审阅 trace。
  *
+ * @deprecated 旧链路依赖 stage-context.md 与 codeListPaths 匹配，stage-context.md 已砍
+ *             （REQ-ENV-01 修订）。保留实现仅为零回归兼容；新代码请使用
+ *             {@link lookupProjectByRequirement}。
  * @param input - 显式路径、当前目录、code_list 路径和可选 HOME。
  * @returns 解析出的项目上下文与 context-resolution trace。
  * @throws 当无法定位任何上下文来源时抛出错误。

package/dist/src/context/stage-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stage-context.d.ts","sourceRoot":"","sources":["../../../src/context/stage-context.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE/E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG;IACzB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAWF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAqBvE;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;CAC/B,GAAG,MAAM,CAST;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CA6D9F"}
+{"version":3,"file":"stage-context.d.ts","sourceRoot":"","sources":["../../../src/context/stage-context.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAE/E,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,MAAM,CAAC;AAElD,MAAM,MAAM,YAAY,GAAG;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,WAAW,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,MAAM,WAAW,GAAG;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;CAC5F,CAAC;AAEF;;GAEG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,aAAa,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;CAC3D,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,iBAAiB,GAAG;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,YAAY,EAAE,gBAAgB,EAAE,CAAC;CAClC,CAAC;AAEF;;;;GAIG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,EAAE,WAAW,EAAE,CAAC;CACxB,CAAC;AAEF,wDAAwD;AACxD,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,MAAM,MAAM,wBAAwB,GAAG;IACrC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,OAAO,EAAE,YAAY,CAAC;IACtB,KAAK,EAAE,sBAAsB,CAAC;CAC/B,CAAC;AAEF,MAAM,MAAM,+BAA+B,GAAG;IAC5C,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB,CAAC;AAuBF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,gBAAgB,EAAE,MAAM,GAAG,YAAY,CAqBvE;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE;IACvC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,OAAO,CAAC,EAAE,WAAW,EAAE,CAAC;CACzB,GAAG,MAAM,CAST;AAED;;;;;;;;;GASG;AACH,wBAAgB,0BAA0B,CACxC,KAAK,EAAE,+BAA+B,GACrC,iBAAiB,GAAG,IAAI,CAmB1B;AAED;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,wBAAwB,GAAG,yBAAyB,CA8D9F"}