@epoint-testtech/stage-create 0.0.3-alpha.1

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+import { fileURLToPath } from 'url';
+import { program } from 'commander';
+import prompts from 'prompts';
+import { copyTemplateDir } from './render-template.js';
+import { writeGlueProjectContext, validateRequiredContextInput } from './stage-context.js';
+const currentFilePath = fileURLToPath(import.meta.url);
+const TEMPLATES_DIR = path.resolve(path.dirname(currentFilePath), '..', 'templates');
+const DEFAULT_STAGE_CORE_DEPENDENCY = '^0.0.3-alpha.1';
+const DEFAULT_EP_STAGE_SKILL_DEPENDENCY = '^0.0.3-alpha.1';
+program
+    .name('stage-create')
+    .description('Epoint Stage 项目脚手架')
+    .argument('[project-name]', '项目名称')
+    .option('--mode <mode>', '模式：default 或 glue')
+    .action(async (projectName, options) => {
+    const answers = await prompts([
+        {
+            type: projectName ? undefined : 'text',
+            name: 'projectName',
+            message: '项目名称',
+            initial: 'stage-project',
+        },
+        {
+            type: options?.mode ? undefined : 'select',
+            name: 'mode',
+            message: '选择模式',
+            choices: [
+                { title: '默认 — 基础 playwright.config.ts 配置', value: 'default' },
+                { title: '胶水模式 — 完整骨架（CrudPage + LoginPage + MenuPage 示例）', value: 'glue' },
+            ],
+            initial: 0,
+        },
+    ]);
+    const rawName = projectName ?? answers.projectName;
+    const mode = options?.mode ?? answers.mode ?? 'default';
+    if (!rawName) {
+        console.error('项目名称不能为空');
+        process.exit(1);
+    }
+    // 支持传入路径：从路径中提取项目名（如 /tmp/my-project → my-project）
+    const name = path.basename(rawName);
+    const templateDir = path.join(TEMPLATES_DIR, mode);
+    const outputDir = path.resolve(rawName);
+    const stageCoreDependency = process.env.STAGE_CORE_DEPENDENCY ?? DEFAULT_STAGE_CORE_DEPENDENCY;
+    const epStageSkillDependency = process.env.EP_STAGE_SKILL_DEPENDENCY ?? DEFAULT_EP_STAGE_SKILL_DEPENDENCY;
+    if (fs.existsSync(outputDir)) {
+        console.error(`目录已存在: ${outputDir}`);
+        process.exit(1);
+    }
+    const glueContextAnswers = mode === 'glue'
+        ? await readGlueContextAnswers()
+        : {};
+    // glue 模式必填项校验必须早于 mkdirSync，避免缺失输入时留下空项目骨架。
+    if (mode === 'glue') {
+        validateRequiredContextInput({
+            loginSystemUrl: glueContextAnswers.loginSystemUrl ?? '',
+            loginUsername: glueContextAnswers.loginUsername ?? '',
+            loginPassword: glueContextAnswers.loginPassword ?? '',
+        });
+    }
+    console.log('生成中...');
+    fs.mkdirSync(outputDir, { recursive: true });
+    copyTemplateDir(templateDir, outputDir, {
+        projectName: name,
+        stageCoreDependency,
+        epStageSkillDependency,
+    });
+    if (mode === 'glue') {
+        writeGlueProjectContext({
+            projectName: name,
+            projectDir: outputDir,
+            loginSystemUrl: glueContextAnswers.loginSystemUrl ?? '',
+            loginUsername: glueContextAnswers.loginUsername ?? '',
+            loginPassword: glueContextAnswers.loginPassword ?? '',
+            knowledgeRoot: glueContextAnswers.knowledgeRoot,
+        });
+    }
+    console.log(`\n完成！执行以下命令开始：`);
+    console.log(`  cd ${outputDir}`);
+    console.log(`  pnpm install`);
+    if (mode === 'default') {
+        console.log(`  cp .env.example .env`);
+    }
+    console.log(`  pnpm test`);
+});
+program.parse();
+/**
+ * 读取 glue 模式项目上下文输入。
+ *
+ * @returns 登录配置和可选知识库路径。
+ */
+async function readGlueContextAnswers() {
+    if (!process.stdin.isTTY) {
+        const [loginSystemUrl, loginUsername, loginPassword, knowledgeRoot] = fs
+            .readFileSync(0, 'utf8')
+            .split(/\r?\n/);
+        return {
+            loginSystemUrl,
+            loginUsername,
+            loginPassword,
+            knowledgeRoot,
+        };
+    }
+    return prompts([
+        {
+            type: 'text',
+            name: 'loginSystemUrl',
+            message: '登录页面地址',
+        },
+        {
+            type: 'text',
+            name: 'loginUsername',
+            message: '登录用户名',
+        },
+        {
+            type: 'password',
+            name: 'loginPassword',
+            message: '登录密码',
+        },
+        {
+            type: 'text',
+            name: 'knowledgeRoot',
+            message: '知识库路径（可选）',
+        },
+    ]);
+}

package/dist/render-template.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 用变量字典渲染模板字符串。
+ * 模板占位符格式：{{variableName}}
+ */
+export declare function renderTemplate(content: string, vars: Record<string, string>): string;
+/**
+ * 递归复制模板目录，渲染所有 .tpl 文件后去掉 .tpl 后缀。
+ * 非模板文件直接复制。
+ */
+export declare function copyTemplateDir(templateDir: string, outputDir: string, vars: Record<string, string>): void;

package/dist/render-template.js

@@ -0,0 +1,34 @@
+import * as fs from 'fs';
+import * as path from 'path';
+/**
+ * 用变量字典渲染模板字符串。
+ * 模板占位符格式：{{variableName}}
+ */
+export function renderTemplate(content, vars) {
+    return content.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] ?? '');
+}
+/**
+ * 递归复制模板目录，渲染所有 .tpl 文件后去掉 .tpl 后缀。
+ * 非模板文件直接复制。
+ */
+export function copyTemplateDir(templateDir, outputDir, vars) {
+    const entries = fs.readdirSync(templateDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const srcPath = path.join(templateDir, entry.name);
+        const destName = entry.name.endsWith('.tpl')
+            ? entry.name.replace(/\.tpl$/, '')
+            : entry.name;
+        const destPath = path.join(outputDir, destName);
+        if (entry.isDirectory()) {
+            fs.mkdirSync(destPath, { recursive: true });
+            copyTemplateDir(srcPath, destPath, vars);
+        }
+        else if (entry.name.endsWith('.tpl')) {
+            const content = fs.readFileSync(srcPath, 'utf-8');
+            fs.writeFileSync(destPath, renderTemplate(content, vars));
+        }
+        else {
+            fs.copyFileSync(srcPath, destPath);
+        }
+    }
+}

package/dist/stage-context.d.ts

@@ -0,0 +1,27 @@
+export type WriteGlueProjectContextInput = {
+    projectName: string;
+    projectDir: string;
+    loginSystemUrl: string;
+    loginUsername: string;
+    loginPassword: string;
+    knowledgeRoot?: string;
+    homeDir?: string;
+};
+/**
+ * 写入 glue 项目的运行上下文文件和用户级项目索引。
+ *
+ * @param input - 项目目录、登录配置和可选知识库路径。
+ * @returns 写入的 .env、stage-context.md 和项目索引路径。
+ */
+export declare function writeGlueProjectContext(input: WriteGlueProjectContextInput): {
+    envPath: string;
+    stageContextPath: string;
+    projectIndexPath: string;
+};
+/**
+ * 校验 glue 模式运行所需的必填输入。
+ *
+ * @param input - glue 项目上下文输入。
+ * @throws 当登录地址、用户名或密码为空时抛出错误。
+ */
+export declare function validateRequiredContextInput(input: Pick<WriteGlueProjectContextInput, 'loginSystemUrl' | 'loginUsername' | 'loginPassword'>): void;

package/dist/stage-context.js

@@ -0,0 +1,175 @@
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import JSON5 from 'json5';
+/**
+ * 写入 glue 项目的运行上下文文件和用户级项目索引。
+ *
+ * @param input - 项目目录、登录配置和可选知识库路径。
+ * @returns 写入的 .env、stage-context.md 和项目索引路径。
+ */
+export function writeGlueProjectContext(input) {
+    const projectDir = path.resolve(input.projectDir);
+    const envPath = path.join(projectDir, '.env');
+    const stageContextPath = path.join(projectDir, 'stage-context.md');
+    const projectIndexPath = path.join(input.homeDir ?? os.homedir(), '.ep-stage', 'projects.index.json5');
+    const knowledgeRoot = normalizeOptionalPath(input.knowledgeRoot);
+    const codeListPaths = getExistingCodeListPaths(knowledgeRoot);
+    validateRequiredContextInput(input);
+    fs.writeFileSync(envPath, renderEnv(input), 'utf8');
+    fs.writeFileSync(stageContextPath, renderStageContext({
+        projectName: input.projectName,
+        knowledgeRoot,
+        codeListPaths,
+    }), 'utf8');
+    const index = readProjectIndex(projectIndexPath);
+    const nextEntry = {
+        projectName: input.projectName,
+        projectDir,
+        mode: 'glue',
+        envPath: '.env',
+        ...(knowledgeRoot ? { knowledgeRoot } : {}),
+        codeListPaths,
+        stageContextPath,
+    };
+    const dedupedProjects = index.projects.filter((project) => path.resolve(project.projectDir) !== projectDir);
+    fs.mkdirSync(path.dirname(projectIndexPath), { recursive: true });
+    fs.writeFileSync(projectIndexPath, `${JSON5.stringify({ version: 1, projects: [...dedupedProjects, nextEntry] }, null, 2)}\n`, 'utf8');
+    return { envPath, stageContextPath, projectIndexPath };
+}
+/**
+ * 渲染 glue 模式运行所需的 .env 文件。
+ *
+ * @param input - 登录地址、账号和密码。
+ * @returns .env 文件内容。
+ */
+function renderEnv(input) {
+    return [
+        '# Stage 环境变量配置',
+        '',
+        'LOGIN_SYSTEM_URL=' + renderEnvValue(input.loginSystemUrl),
+        'LOGIN_USERNAME=' + renderEnvValue(input.loginUsername),
+        'LOGIN_PASSWORD=' + renderEnvValue(input.loginPassword),
+        '',
+    ].join('\n');
+}
+/**
+ * 渲染项目级 stage-context.md。
+ *
+ * @param input - 项目名和可选知识库路径。
+ * @returns stage-context.md 文件内容。
+ */
+function renderStageContext(input) {
+    const frontmatter = [
+        '---',
+        `projectName: ${renderYamlString(input.projectName)}`,
+        `projectDir: ${renderYamlString('.')}`,
+        `mode: ${renderYamlString('glue')}`,
+        `envPath: ${renderYamlString('.env')}`,
+        ...(input.knowledgeRoot ? [`knowledgeRoot: ${renderYamlString(input.knowledgeRoot)}`] : []),
+        ...renderYamlStringArray('codeListPaths', input.codeListPaths),
+        '---',
+    ];
+    return [
+        ...frontmatter,
+        '',
+        `# ${input.projectName}`,
+        '',
+        '此文件由 stage-create glue 模式生成，用于 ep-stage skills/CLI 解析项目上下文。',
+        '',
+    ].join('\n');
+}
+/**
+ * 读取已有用户级项目索引，允许 JSON5 注释和尾逗号。
+ *
+ * @param projectIndexPath - 用户级项目索引路径。
+ * @returns 解析后的项目索引。
+ */
+function readProjectIndex(projectIndexPath) {
+    if (!fs.existsSync(projectIndexPath)) {
+        return { projects: [] };
+    }
+    const parsed = JSON5.parse(fs.readFileSync(projectIndexPath, 'utf8'));
+    return { projects: parsed.projects ?? [] };
+}
+/**
+ * 校验 glue 模式运行所需的必填输入。
+ *
+ * @param input - glue 项目上下文输入。
+ * @throws 当登录地址、用户名或密码为空时抛出错误。
+ */
+export function validateRequiredContextInput(input) {
+    if (!input.loginSystemUrl.trim()) {
+        throw new Error('登录页面地址不能为空');
+    }
+    if (!input.loginUsername.trim()) {
+        throw new Error('登录用户名不能为空');
+    }
+    if (!input.loginPassword.trim()) {
+        throw new Error('登录密码不能为空');
+    }
+}
+/**
+ * 渲染 .env 值，必要时使用双引号并转义特殊字符。
+ *
+ * @param value - 原始环境变量值。
+ * @returns 可写入 .env 的安全值。
+ */
+function renderEnvValue(value) {
+    if (!/[\s#"\\\r\n]/.test(value)) {
+        return value;
+    }
+    return `"${value
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"')
+        .replace(/\n/g, '\\n')
+        .replace(/\r/g, '\\r')}"`;
+}
+/**
+ * 渲染 YAML 字符串标量。
+ *
+ * @param value - 原始字符串。
+ * @returns 可放入 YAML frontmatter 的双引号标量。
+ */
+function renderYamlString(value) {
+    return JSON.stringify(value);
+}
+/**
+ * 渲染 YAML 字符串数组。
+ *
+ * @param key - 字段名。
+ * @param values - 字符串数组。
+ * @returns YAML 行数组。
+ */
+function renderYamlStringArray(key, values) {
+    if (values.length === 0) {
+        return [`${key}: []`];
+    }
+    return [
+        `${key}:`,
+        ...values.map((value) => `  - ${renderYamlString(value)}`),
+    ];
+}
+/**
+ * 只在 knowledgeRoot/_docs/code_list.md 实际存在时登记 code list。
+ *
+ * @param knowledgeRoot - 可选知识库根目录。
+ * @returns 已存在的 code_list.md 路径列表。
+ */
+function getExistingCodeListPaths(knowledgeRoot) {
+    if (!knowledgeRoot) {
+        return [];
+    }
+    const codeListPath = path.join(knowledgeRoot, '_docs', 'code_list.md');
+    return fs.existsSync(codeListPath) ? [codeListPath] : [];
+}
+/**
+ * 归一化可选路径，空字符串视为未提供。
+ *
+ * @param value - 用户输入的可选路径。
+ * @returns 绝对路径或 undefined。
+ */
+function normalizeOptionalPath(value) {
+    const trimmed = value?.trim();
+    return trimmed ? path.resolve(trimmed) : undefined;
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@epoint-testtech/stage-create",
+  "version": "0.0.3-alpha.1",
+  "description": "Epoint Stage — Playwright 脚手架 CLI",
+  "type": "module",
+  "bin": {
+    "stage-create": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "commander": "^12.0.0",
+    "json5": "^2.2.3",
+    "prompts": "^2.4.2"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/prompts": "^2.4.9",
+    "tsx": "^4.20.0",
+    "typescript": "^6.0.3"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "pnpm run build && node --test test/**/*.test.mjs",
+    "dev": "tsx src/index.ts"
+  }
+}

package/templates/default/.env.example

@@ -0,0 +1,18 @@
+# Stage 环境变量配置
+# 复制此文件为 .env 并填写实际值
+
+# 登录页面地址
+LOGIN_SYSTEM_URL=
+
+# 登录用户名
+LOGIN_USERNAME=
+
+# 登录密码
+LOGIN_PASSWORD=
+
+# 回放稳定性配置，可按项目情况调整
+STAGE_ACTION_TIMEOUT_MS=30000
+STAGE_NAVIGATION_TIMEOUT_MS=60000
+STAGE_EXPECT_TIMEOUT_MS=30000
+STAGE_TEST_TIMEOUT_MS=1800000
+STAGE_SLOW_MO_MS=500

package/templates/default/package.json.tpl

@@ -0,0 +1,20 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "report": "playwright show-report"
+  },
+  "dependencies": {
+    "@epoint-testtech/stage-core": "{{stageCoreDependency}}",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "typescript": "^6.0.3"
+  }
+}

package/templates/default/playwright.config.ts

@@ -0,0 +1,44 @@
+import { defineConfig, devices } from '@playwright/test';
+import dotenv from 'dotenv';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+const configDir = path.dirname(fileURLToPath(import.meta.url));
+
+dotenv.config({ path: path.resolve(configDir, '.env') });
+
+export default defineConfig({
+  testDir: './src/tests',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  // 双报告并存：原生 HTML（查用例/trace/截图）+ stage-core 流程执行报告（流程视角，解释跳过/续测）。
+  // 编排器「报告」入口：流程报告 → /report，原生报告 → /pw-report。
+  reporter: [
+    ['html', { open: 'never' }],
+    ['@epoint-testtech/stage-core/reporter', { outputDir: 'stage-report', stateDir: '.stage-state' }],
+  ],
+  timeout: 30 * 60 * 1000,
+
+  use: {
+    baseURL: process.env.LOGIN_SYSTEM_URL,
+    ignoreHTTPSErrors: true,
+    actionTimeout: 10_000,
+    trace: 'on-first-retry',
+    headless: !!(process.env.CI || process.env.HEADLESS === 'true'),
+    launchOptions: { slowMo: 500 },
+    viewport: { width: 1800, height: 900 },
+    locale: 'zh-CN',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+    permissions: ['clipboard-read'],
+  },
+
+  projects: [
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'], viewport: { width: 1800, height: 900 } },
+    },
+  ],
+});

package/templates/default/setup-mac.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env sh
+set -eu
+
+cd "$(dirname "$0")"
+
+echo "==> 检查 pnpm"
+if ! command -v pnpm >/dev/null 2>&1; then
+  if command -v corepack >/dev/null 2>&1; then
+    corepack enable
+    corepack prepare pnpm@10.33.0 --activate
+  else
+    echo "未检测到 pnpm/corepack。请先安装 Node.js 18+，再重新运行本脚本。"
+    exit 1
+  fi
+fi
+
+echo "==> 安装项目依赖"
+pnpm install
+
+if [ ! -f .env ] && [ -f .env.example ]; then
+  echo "==> 创建 .env"
+  cp .env.example .env
+fi
+
+echo "==> 安装 Playwright 浏览器"
+npx playwright install
+
+echo ""
+echo "环境初始化完成。请按需编辑 .env，然后运行：pnpm test"

package/templates/default/setup-windows.cmd

@@ -0,0 +1,13 @@
+@echo off
+setlocal
+cd /d "%~dp0"
+powershell -NoProfile -ExecutionPolicy Bypass -File "%~dp0setup-windows.ps1"
+if errorlevel 1 (
+  echo.
+  echo Setup FAILED. See the error above.
+  pause
+  exit /b 1
+)
+echo.
+echo Setup completed. Edit .env if needed, then run: pnpm test
+pause

package/templates/default/setup-windows.ps1

@@ -0,0 +1,26 @@
+$ErrorActionPreference = "Stop"
+# 让 Write-Host 的中文在控制台正常显示（PowerShell 5.1 默认 GBK 输出）
+try { [Console]::OutputEncoding = [System.Text.Encoding]::UTF8 } catch {}
+Set-Location $PSScriptRoot
+
+Write-Host "==> 检查 pnpm"
+if (-not (Get-Command pnpm -ErrorAction SilentlyContinue)) {
+  if (Get-Command corepack -ErrorAction SilentlyContinue) {
+    corepack enable
+    corepack prepare pnpm@10.33.0 --activate
+  } else {
+    Write-Host "未检测到 pnpm/corepack。请先安装 Node.js 18+，再重新运行本脚本。"
+    exit 1
+  }
+}
+
+Write-Host "==> 安装项目依赖"
+pnpm install
+
+if ((-not (Test-Path ".env")) -and (Test-Path ".env.example")) {
+  Write-Host "==> 创建 .env"
+  Copy-Item ".env.example" ".env"
+}
+
+Write-Host "==> 安装 Playwright 浏览器"
+npx playwright install

package/templates/default/src/global.setup.ts

@@ -0,0 +1,5 @@
+import { generateTimeStamp } from '@epoint-testtech/stage-core/utils';
+
+export default async function globalSetup() {
+  process.env.STAGE_EXECUTION_TIMESTAMP ??= generateTimeStamp();
+}

package/templates/default/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts"]
+}

package/templates/glue/.env.example

@@ -0,0 +1,18 @@
+# Stage 环境变量配置
+# 复制此文件为 .env 并填写实际值
+
+# 登录页面地址
+LOGIN_SYSTEM_URL=
+
+# 登录用户名
+LOGIN_USERNAME=
+
+# 登录密码
+LOGIN_PASSWORD=
+
+# 回放稳定性配置，可按项目情况调整
+STAGE_ACTION_TIMEOUT_MS=30000
+STAGE_NAVIGATION_TIMEOUT_MS=60000
+STAGE_EXPECT_TIMEOUT_MS=30000
+STAGE_TEST_TIMEOUT_MS=1800000
+STAGE_SLOW_MO_MS=500

package/templates/glue/package.json.tpl

@@ -0,0 +1,21 @@
+{
+  "name": "{{projectName}}",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "test": "playwright test",
+    "test:headed": "playwright test --headed",
+    "test:debug": "playwright test --debug",
+    "report": "playwright show-report"
+  },
+  "dependencies": {
+    "@epoint-testtech/stage-core": "{{stageCoreDependency}}",
+    "@epoint-testtech/ep-stage-skill": "{{epStageSkillDependency}}",
+    "dotenv": "^17.2.3"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.60.0",
+    "typescript": "^6.0.3"
+  }
+}