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

package/dist/test/util/softlink.test.js

@@ -0,0 +1,82 @@
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
+import { mkdtempSync, rmSync, writeFileSync, existsSync, readFileSync, lstatSync, mkdirSync, symlinkSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { createSoftlinkWithFallback, softlinkFs } from '../../src/util/softlink.js';
+/**
+ * REQ-FILE-02：跨平台软链 fallback util
+ * 三档 fallback：symlink（macOS/Linux）→ hardlink → copy + 时间戳警示（Windows 无管理员权限）。
+ *
+ * 注：fallback 路径通过 softlinkFs.* spy 模拟失败；ESM namespace 不可写，
+ * 因此 softlink.ts 显式暴露 softlinkFs 对象供测试替换。
+ */
+describe('createSoftlinkWithFallback', () => {
+    let tmpDir;
+    let target;
+    let linkPath;
+    beforeEach(() => {
+        tmpDir = mkdtempSync(path.join(os.tmpdir(), 'softlink-test-'));
+        target = path.join(tmpDir, 'code_list.md');
+        linkPath = path.join(tmpDir, 'requirement', 'code_list.md');
+        writeFileSync(target, '# upstream code list\n');
+        mkdirSync(path.dirname(linkPath), { recursive: true });
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+        rmSync(tmpDir, { recursive: true, force: true });
+    });
+    it('symlink 成功时返回 strategy=symlink，且链接指向 target', () => {
+        const result = createSoftlinkWithFallback(target, linkPath);
+        expect(result.strategy).toBe('symlink');
+        expect(result.warned).toBeUndefined();
+        expect(existsSync(linkPath)).toBe(true);
+        expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+        // 通过链接读到的内容应该和源文件一致
+        expect(readFileSync(linkPath, 'utf8')).toBe('# upstream code list\n');
+    });
+    it('目标已存在时先 unlink 再创建（覆盖语义）', () => {
+        // 先放一个老文件占位
+        writeFileSync(linkPath, '# stale content\n');
+        const result = createSoftlinkWithFallback(target, linkPath);
+        expect(result.strategy).toBe('symlink');
+        expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+        expect(readFileSync(linkPath, 'utf8')).toBe('# upstream code list\n');
+    });
+    it('目标已存在且为旧 symlink 时也能覆盖', () => {
+        // 先建一个指向别处的 symlink
+        const altTarget = path.join(tmpDir, 'alt.md');
+        writeFileSync(altTarget, '# alt\n');
+        symlinkSync(altTarget, linkPath, 'file');
+        expect(lstatSync(linkPath).isSymbolicLink()).toBe(true);
+        const result = createSoftlinkWithFallback(target, linkPath);
+        expect(result.strategy).toBe('symlink');
+        expect(readFileSync(linkPath, 'utf8')).toBe('# upstream code list\n');
+    });
+    it('symlink 失败时回退到 hardlink', () => {
+        // mock softlinkFs.symlinkSync 抛错，模拟 Windows 无权限
+        vi.spyOn(softlinkFs, 'symlinkSync').mockImplementation(() => {
+            throw new Error('EPERM: operation not permitted');
+        });
+        const result = createSoftlinkWithFallback(target, linkPath);
+        expect(result.strategy).toBe('hardlink');
+        expect(result.warned).toBeUndefined();
+        expect(existsSync(linkPath)).toBe(true);
+        expect(lstatSync(linkPath).isSymbolicLink()).toBe(false);
+        expect(readFileSync(linkPath, 'utf8')).toBe('# upstream code list\n');
+    });
+    it('symlink 与 hardlink 均失败时回退到 copy，并返回 warned=true', () => {
+        vi.spyOn(softlinkFs, 'symlinkSync').mockImplementation(() => {
+            throw new Error('EPERM: symlink not permitted');
+        });
+        vi.spyOn(softlinkFs, 'linkSync').mockImplementation(() => {
+            throw new Error('EXDEV: cross-device link not permitted');
+        });
+        const result = createSoftlinkWithFallback(target, linkPath);
+        expect(result.strategy).toBe('copy');
+        expect(result.warned).toBe(true);
+        expect(existsSync(linkPath)).toBe(true);
+        expect(lstatSync(linkPath).isSymbolicLink()).toBe(false);
+        // copy 的文件内容等于源文件
+        expect(readFileSync(linkPath, 'utf8')).toBe('# upstream code list\n');
+    });
+});

package/dist/test/validation/credentials.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=credentials.test.d.ts.map

package/dist/test/validation/credentials.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"credentials.test.d.ts","sourceRoot":"","sources":["../../../test/validation/credentials.test.ts"],"names":[],"mappings":""}

package/dist/test/validation/credentials.test.js

@@ -0,0 +1,72 @@
+import { describe, it, expect } from 'vitest';
+import { validateCredentials } from '../../src/validation/credentials.js';
+describe('validateCredentials', () => {
+    it('合法数组（≥1 条）通过', () => {
+        const result = validateCredentials([
+            {
+                url: 'http://example.test',
+                username: 'admin',
+                password: 'pwd',
+                role: '系统管理员',
+                systemName: '基础平台',
+            },
+        ]);
+        expect(result).toHaveLength(1);
+        expect(result[0]).toMatchObject({
+            url: 'http://example.test',
+            username: 'admin',
+            password: 'pwd',
+            role: '系统管理员',
+            systemName: '基础平台',
+        });
+    });
+    it('允许无 role / systemName 的条目', () => {
+        const result = validateCredentials([
+            { url: 'http://example.test', username: 'admin', password: 'pwd' },
+        ]);
+        expect(result[0]).toEqual({
+            url: 'http://example.test',
+            username: 'admin',
+            password: 'pwd',
+        });
+        expect(result[0]).not.toHaveProperty('role');
+        expect(result[0]).not.toHaveProperty('systemName');
+    });
+    it('非数组报错', () => {
+        expect(() => validateCredentials({ url: 'x' })).toThrow(/数组/);
+    });
+    it('空数组报错', () => {
+        expect(() => validateCredentials([])).toThrow(/至少|1 条/);
+    });
+    it('条目缺 url 报错', () => {
+        expect(() => validateCredentials([{ username: 'admin', password: 'pwd' }])).toThrow(/url/);
+    });
+    it('条目缺 username 报错', () => {
+        expect(() => validateCredentials([{ url: 'http://example.test', password: 'pwd' }])).toThrow(/username/);
+    });
+    it('条目缺 password 报错', () => {
+        expect(() => validateCredentials([{ url: 'http://example.test', username: 'admin' }])).toThrow(/password/);
+    });
+    it('条目空字符串字段（空白）报错', () => {
+        expect(() => validateCredentials([{ url: '  ', username: 'admin', password: 'pwd' }])).toThrow(/url/);
+    });
+    it('同 (url, role) 重复报错', () => {
+        expect(() => validateCredentials([
+            { url: 'http://example.test', username: 'a', password: 'p1', role: '管理员' },
+            { url: 'http://example.test', username: 'b', password: 'p2', role: '管理员' },
+        ])).toThrow(/重复/);
+    });
+    it('同 url 但 role 不同允许', () => {
+        const result = validateCredentials([
+            { url: 'http://example.test', username: 'a', password: 'p1', role: '管理员' },
+            { url: 'http://example.test', username: 'b', password: 'p2', role: '业务员' },
+        ]);
+        expect(result).toHaveLength(2);
+    });
+    it('同 url 都没 role 视作 (url, "") 也会触发重复', () => {
+        expect(() => validateCredentials([
+            { url: 'http://example.test', username: 'a', password: 'p1' },
+            { url: 'http://example.test', username: 'b', password: 'p2' },
+        ])).toThrow(/重复/);
+    });
+});

package/dist/test/validation/projects-index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=projects-index.test.d.ts.map

package/dist/test/validation/projects-index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"projects-index.test.d.ts","sourceRoot":"","sources":["../../../test/validation/projects-index.test.ts"],"names":[],"mappings":""}

package/dist/test/validation/projects-index.test.js

@@ -0,0 +1,48 @@
+import { describe, it, expect } from 'vitest';
+import { validateProjectsIndex } from '../../src/validation/projects-index.js';
+describe('validateProjectsIndex', () => {
+    it('通过合法结构（含 systems[] 与 stageCreateVersion）', () => {
+        const obj = {
+            projects: [
+                {
+                    projectName: 'demo',
+                    projectDir: '/abs/demo',
+                    mode: 'glue',
+                    createdAt: '2026-06-25T00:00:00Z',
+                    stageCreateVersion: '0.0.4-alpha.0',
+                    requirements: [],
+                },
+            ],
+            systems: [],
+        };
+        const result = validateProjectsIndex(obj);
+        expect(result.projects).toHaveLength(1);
+        expect(result.projects[0].stageCreateVersion).toBe('0.0.4-alpha.0');
+        expect(result.systems).toEqual([]);
+    });
+    it('缺 systems 字段时报结构化错误', () => {
+        expect(() => validateProjectsIndex({ projects: [] })).toThrow(/systems/);
+    });
+    it('项目条目缺 stageCreateVersion 报错（stage-context.md 砍掉后的元信息承接）', () => {
+        expect(() => validateProjectsIndex({
+            projects: [{ projectName: 'x', projectDir: '/x', mode: 'glue', requirements: [] }],
+            systems: [],
+        })).toThrow(/stageCreateVersion/);
+    });
+    it('不允许残留 stageContextPath / envPath / knowledgeRoot 字段', () => {
+        expect(() => validateProjectsIndex({
+            projects: [
+                {
+                    projectName: 'x',
+                    projectDir: '/x',
+                    mode: 'glue',
+                    createdAt: '2026-06-25T00:00:00Z',
+                    stageCreateVersion: '0.0.4-alpha.0',
+                    requirements: [],
+                    stageContextPath: '/x/stage-context.md', // 应被拒绝
+                },
+            ],
+            systems: [],
+        })).toThrow(/stageContextPath|removed/);
+    });
+});

package/dist/test/validation/testcase.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=testcase.test.d.ts.map

package/dist/test/validation/testcase.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testcase.test.d.ts","sourceRoot":"","sources":["../../../test/validation/testcase.test.ts"],"names":[],"mappings":""}

package/dist/test/validation/testcase.test.js

@@ -0,0 +1,129 @@
+import { describe, it, expect } from 'vitest';
+import { validateTestcase } from '../../src/validation/testcase.js';
+/**
+ * 构造一份满足 v2 schema 的最小合法 testcase（REQ-DATA-02）。
+ *
+ * @returns 合法 testcase v2 对象。
+ */
+function makeValidTestcase() {
+    return {
+        schemaVersion: 'v2',
+        scenario: '组织管理 CRUD 主流程',
+        moduleId: 'org-management',
+        moduleName: '组织管理',
+        menuPath: '系统管理 > 组织管理',
+        requiredSystems: [{ url: 'http://example.test', systemName: '基础平台' }],
+        requiredRoles: [{ role: '系统管理员', hint: '可访问组织管理菜单' }],
+        coveredActions: [
+            { actionId: 'create', kind: 'create', evidence: ['html=org-list.html#btn-add'] },
+        ],
+        uncoveredCandidates: [
+            {
+                actionId: 'export',
+                label: '导出',
+                status: 'planned',
+                requiredRole: '系统管理员',
+                businessIntent: '导出当前查询结果',
+                assertionExpectation: '断言下载文件存在',
+                evidence: ['hint=ModuleHints.export'],
+            },
+        ],
+        cases: [
+            {
+                caseId: 'CASE-001',
+                title: '管理员新增组织',
+                scenario: '组织管理 CRUD 主流程',
+                reviewStatus: 'confirmed',
+                requiredRole: '系统管理员',
+                evidence: ['spec=org-management.spec.yaml#create'],
+                steps: ['打开菜单', '点击新增'],
+                assertions: ['列表出现新组织'],
+                unresolved: [],
+            },
+        ],
+        reasoningSummary: {
+            conclusion: '主流程覆盖增删改查',
+            evidenceChain: ['html=org-list.html'],
+            alternatives: [],
+            confidence: 'high',
+            risks: [],
+            needsHumanReview: false,
+        },
+    };
+}
+describe('validateTestcase', () => {
+    it('合法 v2 testcase 通过', () => {
+        const result = validateTestcase(makeValidTestcase());
+        expect(result.schemaVersion).toBe('v2');
+        expect(result.cases).toHaveLength(1);
+    });
+    it('缺 schemaVersion 报版本错误引导重跑（v1 升级路径）', () => {
+        const tc = makeValidTestcase();
+        delete tc.schemaVersion;
+        expect(() => validateTestcase(tc)).toThrow(/schemaVersion|v2|重跑/);
+    });
+    it('schemaVersion 非 v2（视作 v1）也走版本错误引导重跑', () => {
+        const tc = { ...makeValidTestcase(), schemaVersion: 'v1' };
+        expect(() => validateTestcase(tc)).toThrow(/schemaVersion|v2|重跑/);
+    });
+    it('缺 scenario 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.scenario;
+        expect(() => validateTestcase(tc)).toThrow(/scenario/);
+    });
+    it('缺 menuPath 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.menuPath;
+        expect(() => validateTestcase(tc)).toThrow(/menuPath/);
+    });
+    it('缺 requiredSystems[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.requiredSystems;
+        expect(() => validateTestcase(tc)).toThrow(/requiredSystems/);
+    });
+    it('缺 requiredRoles[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.requiredRoles;
+        expect(() => validateTestcase(tc)).toThrow(/requiredRoles/);
+    });
+    it('缺 coveredActions[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.coveredActions;
+        expect(() => validateTestcase(tc)).toThrow(/coveredActions/);
+    });
+    it('缺 uncoveredCandidates[] 报错', () => {
+        const tc = makeValidTestcase();
+        delete tc.uncoveredCandidates;
+        expect(() => validateTestcase(tc)).toThrow(/uncoveredCandidates/);
+    });
+    it('uncoveredCandidates[].requiredRole 缺失报错', () => {
+        const tc = makeValidTestcase();
+        const uncovered = tc.uncoveredCandidates;
+        delete uncovered[0].requiredRole;
+        expect(() => validateTestcase(tc)).toThrow(/uncoveredCandidates.*requiredRole/);
+    });
+    it('coveredActions[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const covered = tc.coveredActions;
+        covered[0].evidence = ['某条非法 evidence 字符串'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('uncoveredCandidates[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const uncovered = tc.uncoveredCandidates;
+        uncovered[0].evidence = ['plainstring'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('cases[].evidence 非 <kind>=<ref> 报错', () => {
+        const tc = makeValidTestcase();
+        const cases = tc.cases;
+        cases[0].evidence = ['noequalsign'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+    it('evidence kind 必须在 html/java/spec/contract/skeleton/hint 范围内', () => {
+        const tc = makeValidTestcase();
+        const covered = tc.coveredActions;
+        covered[0].evidence = ['unknownkind=foo.html'];
+        expect(() => validateTestcase(tc)).toThrow(/evidence/);
+    });
+});

package/docs/README.md

@@ -1,4 +1,4 @@
-# @epoint/ep-stage-skill
+# @epoint-testtech/ep-stage-skill
 
 > 胶水编码链路 Agent Skill — 解析上游物料，按契约生成可执行测试脚本
 
@@ -11,8 +11,8 @@
 AI Agent 可发现的 Skill 入口（Claude Code 扫 `.claude/skills/`、Codex 扫 `.agents/skills/`，均 symlink 到包内源）：
 
 ```text
-.claude/skills/{glue-test, create-project, recording-to-glue}
-.agents/skills/{glue-test, create-project, recording-to-glue}
+.claude/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
+.agents/skills/{glue-create-project, glue-generate-testcase, glue-run-test, recording-to-glue}
   → packages/ep-stage-skill/codex-skill/ep-stage/<skill>/
 ```
 
@@ -31,11 +31,11 @@ AI Agent 可发现的 Skill 入口（Claude Code 扫 `.claude/skills/`、Codex
 
 ```bash
 # 可观测默认入口（推荐）
-pnpm --filter @epoint/ep-stage-skill run:gap-pipeline -- \
+pnpm --filter @epoint-testtech/ep-stage-skill run:gap-pipeline -- \
   --code-list <code_list.md>
 
 # 生成契约
-pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
+pnpm --filter @epoint-testtech/ep-stage-skill generate:crud-contract -- \
   --module-id <模块ID> \
   --docs <上游文档目录> \
   --code-list <code_list.md> \
@@ -45,7 +45,7 @@ pnpm --filter @epoint/ep-stage-skill generate:crud-contract -- \
   --out output/<module>.crud.contract.json
 
 # 生成测试脚本
-pnpm --filter @epoint/ep-stage-skill generate:playwright-tests -- \
+pnpm --filter @epoint-testtech/ep-stage-skill generate:playwright-tests -- \
   --contract output/<module>.crud.contract.json \
   --out <glue项目>/src/tests/<name>.spec.ts \
   --menu "一级菜单>二级菜单" \

package/docs/mvp-usage-guide.md

@@ -1,8 +1,8 @@
-# glue-test CRUD 契约生成器 — MVP 使用手册
+# glue-run-test CRUD 契约生成器 — MVP 使用手册
 
 ## 概述
 
-`glue-test` 是一个 TypeScript agent skill，用于从上游业务模块物料中提取结构化信息，归一化为 `crud-business-module/v1` 契约 JSON。该契约作为 AI Agent 生成 Playwright 测试脚本的地基，确保 Agent 不需要自己编造 selector、按钮文本或业务预期。
+`glue-run-test` 是一个 TypeScript agent skill，用于从上游业务模块物料中提取结构化信息，归一化为 `crud-business-module/v1` 契约 JSON。该契约作为 AI Agent 生成 Playwright 测试脚本的地基，确保 Agent 不需要自己编造 selector、按钮文本或业务预期。
 
 当前 MVP 只面向公司自研 `zwplace` CRUD 场景，负责：
 
@@ -14,7 +14,7 @@
 ## 数据流
 
 ```
-上游物料                          glue-test                        输出
+上游物料                          glue-run-test                        输出
 ┌──────────────┐               ┌──────────────┐               ┌──────────────┐
 │ HTML 页面    │──extractor──→ │              │               │              │
 │ spec.yaml    │──extractor──→ │  normalizer  │──CLI 输出──→  │ 契约 JSON    │

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@epoint-testtech/ep-stage-skill",
-  "version": "0.0.3-alpha.1",
+  "version": "0.0.4-alpha.0",
   "type": "module",
   "main": "dist/src/index.js",
   "types": "dist/src/index.d.ts",
+  "bin": {
+    "ep-stage-skill": "./dist/src/cli/index.js"
+  },
   "files": [
     "dist",
     "codex-skill",
@@ -31,8 +34,10 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "build": "tsc",
-    "generate:crud-contract": "node --import tsx src/cli/generate-crud-contract.ts",
-    "generate:playwright-tests": "node --import tsx src/cli/generate-playwright-tests.ts",
-    "run:gap-pipeline": "node --import tsx src/cli/run-gap-pipeline.ts"
+    "generate:crud-contract": "node --import tsx src/cli/dev/extract-contract.ts",
+    "generate:playwright-tests": "node --import tsx src/cli/index.ts spec",
+    "run:gap-pipeline": "node --import tsx src/cli/run-gap-pipeline.ts",
+    "cli": "node --import tsx src/cli/index.ts",
+    "generate:testcase": "node --import tsx src/cli/index.ts testcase"
   }
 }

package/codex-skill/ep-stage/create-project/SKILL.md

@@ -1,59 +0,0 @@
----
-name: create-project
-description: 使用时机：当用户需要通过现有 stage-create CLI 创建 ep-stage Playwright 项目（尤其是 default 或 glue 模式项目）时使用。
----
-
-# ep-stage: create-project
-
-当用户需要创建 ep-stage 项目，或要求生成 glue 模式（glue-mode）Playwright 脚手架时，使用本 skill。
-
-## 行为契约（Behavior Contract）
-
-本 skill 引导 Agent 调用现有 `@epoint/stage-create` CLI，不重新实现脚手架逻辑。
-
-当前命令示例：
-
-```bash
-stage-create my-glue-project --mode glue
-stage-create my-default-project --mode default
-```
-
-## 必填输入
-
-- 项目名称（project name）：必填，缺失时必须向用户询问。
-- 模式（mode）：`glue` 或 `default`，缺失时必须向用户询问。
-
-不要自行猜测项目名称。不要发明名为 `ep-stage: create-project` 的命令——那是 skill 名称，不是 shell 命令。
-
-## 模式选择指引
-
-- 当项目需要包含胶水骨架（glue skeletons）、页面组件（page components）、报告辅助（report helpers）以及物料驱动的测试生成时，使用 `glue` 模式。
-- 当项目只需要标准 Playwright 基线时，使用 `default` 模式。
-
-## 验证
-
-创建项目后，验证输出目录存在且包含：
-
-```text
-package.json
-playwright.config.ts
-tsconfig.json
-```
-
-对于 `glue` 模式，还需验证：
-
-```text
-src/skeletons/
-src/web/component/
-src/report/
-```
-
-## glue 项目上下文
-
-创建 glue 项目后必须生成（由 stage-create CLI 交互写入）：
-
-- `<project>/stage-context.md`
-- `<project>/.env`
-- `~/.ep-stage/projects.index.json5`
-
-这些文件供后续 `glue-testcase` 和 `glue-test` 内置读取，不依赖用户项目存在 `AGENTS.md`。