@icyouo/evt-cli 0.1.0 → 0.1.2

package/README.md

@@ -9,7 +9,8 @@ evt-cli is a general-purpose HTTP CLI for running YAML-defined APIs and workflow
 - Runtime endpoints come only from `apis/*.yaml`.
 - Flows come only from `flows/*.yaml`.
 - Environments, base URLs, headers, and test fixtures come only from `profiles/*.json`.
-- The scanner is only for coverage comparison and generating missing YAML skeletons. It is not a runtime data source.
+- Endpoint definitions are persisted as YAML. Scanner JSON is only an internal machine-readable handoff.
+- Bundled skills are preferred for project data bootstrap. The built-in regex scanner remains as an endpoint-only fallback for users without an agent or skill workflow.
 - The default data directory is bundled with the CLI package. You can also point to your own project data directory with `--config-root` or `EVT_CLI_ROOT`.
 
 ## Quick Start
@@ -77,12 +78,33 @@ evt-cli ships with `data/**/*.example.*` for validation and reference. Real proj
 
 For compatibility with existing projects, evt also reads `apis/`, `flows/`, `profiles/`, and `scanner.config.json` directly under `--config-root` when those paths exist.
 
+## Bootstrap Project Data With Skills
+
+evt-cli ships generic example data and bundled skills. A skill-aware agent can
+turn an empty project data directory into runnable project data:
+
+1. Use `evt-profile-generator` to create `data/profiles/<env>.json` from source
+   config, docs, endpoint schemas, and user-provided test credentials.
+2. Use `evt-api-scanner` to discover API source paths, write
+   `data/scanner.json`, and generate `data/apis/*.yaml`.
+3. Use `evt-flow-generator` to create `data/flows/login.yaml`, smoke flows, and
+   feature flows from the generated endpoints and product workflow.
+4. Run `evt validate --config-root ./cli`.
+5. Run flows with `--dry-run` first, then against a safe test environment.
+
+Profile and flow generation are AI-first tasks because base URLs, headers,
+login state, test accounts, token response paths, and feature sequences are
+project-specific. evt-cli keeps code fallback only for endpoint scanning.
+
 ## Local Check And Package
 
 ```bash
 npm run ci:local
 ```
 
+The npm package includes source code, scripts, tests, data examples, and skills
+so users can run local checks and build the standalone local binary package.
+
 This runs:
 
 - `npm test`
@@ -100,6 +122,7 @@ The local package directory contains only:
 
 - `evt`
 - `data/`
+- `skills/`
 - `README.md`
 - `README.zh-CN.md`
 
@@ -146,7 +169,47 @@ Each endpoint should include:
 - `response`
 - `dangerous: true` when the endpoint is destructive or sensitive
 
-## Scan And Coverage
+## Skills, Scan, Sync, And Coverage
+
+evt-cli includes these bundled skills:
+
+- `skills/evt-profile-generator/SKILL.md`
+- `skills/evt-api-scanner/SKILL.md`
+- `skills/evt-flow-generator/SKILL.md`
+
+Agents can use these skills to create profile JSON, discover source
+directories, write scanner config, generate YAML endpoint definitions, create
+flow YAML, and audit coverage.
+
+Endpoint definitions are written to YAML under `data/apis/*.yaml`. The scanner
+may use JSON internally, but JSON is not the endpoint definition format.
+
+Discover API source paths and write `data/scanner.json`:
+
+```bash
+evt api discover --config-root ./cli
+```
+
+Generate or update YAML endpoint definitions:
+
+```bash
+evt api sync --config-root ./cli
+```
+
+Audit YAML quality after sync:
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
+Check YAML coverage:
+
+```bash
+evt api coverage --config-root ./cli
+```
+
+The built-in regex scanner is still available as a fallback. It is less complete
+than the skill-guided workflow, but it works without an agent.
 
 Scan source code for candidate endpoints:
 
@@ -166,7 +229,8 @@ Generate missing YAML skeletons:
 npm run sync:api -- --config-root /path/to/project/cli
 ```
 
-The scanner supports `kotlin`, `swift`, `js`, and `dart`. It also supports external skill or AST scanner commands:
+The scanner supports `kotlin`, `swift`, `js`, and `dart`. It also supports the
+bundled skill scanner and external command scanners:
 
 ```json
 {
@@ -179,15 +243,16 @@ The scanner supports `kotlin`, `swift`, `js`, and `dart`. It also supports exter
     },
     {
       "language": "skill",
-      "name": "ast-scanner",
-      "command": "node",
-      "args": ["tools/scan-endpoints.js"]
+      "name": "evt-api-scanner",
+      "skill": "evt-api-scanner"
     }
   ]
 }
 ```
 
-An external scanner can output a JSON array or `{ "endpoints": [] }`. Each endpoint should include at least:
+An external scanner can output a JSON array or `{ "endpoints": [] }` as an
+internal scan result. `evt api sync` converts that scan result into YAML. Each
+intermediate endpoint should include at least:
 
 ```json
 {
@@ -206,6 +271,10 @@ This JSON is used only for scanning, coverage, and sync. Runtime execution still
 ```bash
 evt profile list
 evt api list
+evt api discover --config-root ./cli
+evt api sync --config-root ./cli
+evt api audit --config-root ./cli --strict
+evt api coverage --config-root ./cli
 evt api call todo.list --dry-run
 evt flow run login --profile local
 evt cache show

package/README.zh-CN.md

@@ -9,7 +9,8 @@ evt-cli 是一个通用 HTTP CLI，用 YAML 定义接口、用 YAML 定义 flow
 - 运行时端点只来自 `apis/*.yaml`。
 - flow 只来自 `flows/*.yaml`。
 - 环境、base URL、headers、测试 fixtures 只来自 `profiles/*.json`。
-- 扫描器只用于覆盖率对比和生成缺失 YAML 骨架，不是运行时数据源。
+- endpoint 定义持久化格式始终是 YAML。scanner JSON 只作为内部机器中间结果。
+- 内置 skills 优先用于项目 data 初始化。现有正则 scanner 只保留给没有 agent 或 skill workflow 的用户做 endpoint 扫描兜底。
 - 默认数据目录是当前 CLI 包内目录；也可以通过 `--config-root` 或 `EVT_CLI_ROOT` 指向项目自己的数据目录。
 
 ## 快速开始
@@ -77,12 +78,26 @@ evt-cli 自带 `data/**/*.example.*`，用于开箱验证和复制参考。真
 
 为了兼容已有项目，`--config-root` 下直接存在 `apis/`、`flows/`、`profiles/`、`scanner.config.json` 时也会被读取。
 
+## 用 Skills 初始化项目 Data
+
+evt-cli 自带通用 example data 和内置 skills。支持 skill 的 agent 可以把一个空的项目 data 目录生成成可运行的项目 data：
+
+1. 使用 `evt-profile-generator` 根据源码配置、文档、endpoint schema 和用户提供的测试账号生成 `data/profiles/<env>.json`。
+2. 使用 `evt-api-scanner` 发现 API 源码路径，写入 `data/scanner.json`，并生成 `data/apis/*.yaml`。
+3. 使用 `evt-flow-generator` 根据生成的 endpoint 和产品流程生成 `data/flows/login.yaml`、smoke flow 和 feature flow。
+4. 执行 `evt validate --config-root ./cli`。
+5. 先用 `--dry-run` 跑 flow，再在安全测试环境里跑真实请求。
+
+profile 和 flow 生成是 AI-first 任务，因为 base URL、headers、登录态、测试账号、token 返回路径和 feature 调用顺序都依赖具体项目语义。evt-cli 只保留 endpoint 扫描的代码兜底。
+
 ## 本地校验和打包
 
 ```bash
 npm run ci:local
 ```
 
+npm 包会包含源码、脚本、测试、示例数据和 skills，用户可以自行运行本地校验并构建独立本地二进制包。
+
 执行内容：
 
 - `npm test`
@@ -100,6 +115,7 @@ npm run ci:local
 
 - `evt`
 - `data/`
+- `skills/`
 - `README.md`
 - `README.zh-CN.md`
 
@@ -146,7 +162,46 @@ endpoints:
 - `response`
 - 必要时标记 `dangerous: true`
 
-## 扫描和覆盖率
+## Skills、扫描、同步和覆盖率
+
+evt-cli 内置这些 skills：
+
+- `skills/evt-profile-generator/SKILL.md`
+- `skills/evt-api-scanner/SKILL.md`
+- `skills/evt-flow-generator/SKILL.md`
+
+agent 可以使用这些 skills 生成 profile JSON、发现源码目录、写入 scanner 配置、
+生成 YAML endpoint 定义、生成 flow YAML，并做覆盖率审计。
+
+endpoint 定义会写到 `data/apis/*.yaml`。scanner 可以在内部使用 JSON，但 JSON
+不是 endpoint 的最终定义格式。
+
+发现 API 源码路径并写入 `data/scanner.json`：
+
+```bash
+evt api discover --config-root ./cli
+```
+
+生成或更新 YAML endpoint 定义：
+
+```bash
+evt api sync --config-root ./cli
+```
+
+检查 YAML 质量门禁：
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
+检查 YAML 覆盖率：
+
+```bash
+evt api coverage --config-root ./cli
+```
+
+内置正则 scanner 仍然保留为兜底方案。它不如 skill workflow 完整，但不依赖
+agent，也能让没有 agent 的用户勉强使用。
 
 扫描源码候选 endpoint：
 
@@ -166,7 +221,7 @@ npm run coverage:api -- --config-root /path/to/project/cli
 npm run sync:api -- --config-root /path/to/project/cli
 ```
 
-扫描器支持 `kotlin`、`swift`、`js`、`dart`，也支持外部 skill/AST 扫描命令：
+扫描器支持 `kotlin`、`swift`、`js`、`dart`，也支持内置 skill scanner 和外部命令 scanner：
 
 ```json
 {
@@ -179,15 +234,15 @@ npm run sync:api -- --config-root /path/to/project/cli
     },
     {
       "language": "skill",
-      "name": "ast-scanner",
-      "command": "node",
-      "args": ["tools/scan-endpoints.js"]
+      "name": "evt-api-scanner",
+      "skill": "evt-api-scanner"
     }
   ]
 }
 ```
 
-外部 scanner 输出 JSON 数组，或 `{ "endpoints": [] }`。每个 endpoint 至少包含：
+外部 scanner 可以输出 JSON 数组，或 `{ "endpoints": [] }` 作为内部扫描结果。
+`evt api sync` 会把这个扫描结果转换成 YAML。每个中间 endpoint 至少包含：
 
 ```json
 {
@@ -206,6 +261,10 @@ npm run sync:api -- --config-root /path/to/project/cli
 ```bash
 evt profile list
 evt api list
+evt api discover --config-root ./cli
+evt api sync --config-root ./cli
+evt api audit --config-root ./cli --strict
+evt api coverage --config-root ./cli
 evt api call todo.list --dry-run
 evt flow run login --profile local
 evt cache show

package/data/scanner.example.json

@@ -30,11 +30,8 @@
     },
     {
       "language": "skill",
-      "name": "ast-scanner",
-      "command": "node",
-      "args": [
-        "tools/scan-endpoints.js"
-      ]
+      "name": "evt-api-scanner",
+      "skill": "evt-api-scanner"
     }
   ]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icyouo/evt-cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Run YAML-defined HTTP APIs and interactive workflows from your terminal.",
   "license": "MIT",
   "repository": {
@@ -17,17 +17,21 @@
   "files": [
     "bin/",
     "src/",
+    "scripts/",
+    "test/",
     "data/",
+    "skills/",
     "README.md",
     "README.zh-CN.md"
   ],
   "scripts": {
     "ci:local": "node scripts/local-ci.js",
     "test": "node --test",
-    "check": "node --check bin/evt.js && node --check src/index.js && node --check src/api/liveTester.js && node --check scripts/sync-api-coverage.js && node --check scripts/check-api-coverage.js && node --check scripts/local-ci.js && node --check scripts/build-package.js",
+    "check": "node --check bin/evt.js && node --check src/index.js && node --check src/api/liveTester.js && node --check scripts/sync-api-coverage.js && node --check scripts/check-api-coverage.js && node --check scripts/check-api-audit.js && node --check scripts/local-ci.js && node --check scripts/build-package.js && node --check skills/evt-api-scanner/scripts/discover.js && node --check skills/evt-api-scanner/scripts/scan.js",
     "package:local": "node scripts/build-package.js",
     "sync:api": "node scripts/sync-api-coverage.js",
-    "coverage:api": "node scripts/check-api-coverage.js"
+    "coverage:api": "node scripts/check-api-coverage.js",
+    "audit:api": "node scripts/check-api-audit.js"
   },
   "engines": {
     "node": ">=20"

package/scripts/build-package.js

@@ -0,0 +1,173 @@
+#!/usr/bin/env node
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+
+const cliRoot = path.resolve(__dirname, "..");
+const packageJson = require(path.join(cliRoot, "package.json"));
+const distDir = path.join(cliRoot, "dist");
+const packageName = "evt-cli";
+const packageDir = path.join(distDir, packageName);
+const entryId = "bin/evt.js";
+
+function toPosix(file) {
+  return file.split(path.sep).join("/");
+}
+
+function normalizeModuleId(file) {
+  return path.posix.normalize(toPosix(path.relative(cliRoot, file)));
+}
+
+function resolveLocalModule(fromId, request) {
+  const base = path.posix.dirname(fromId);
+  const target = path.posix.normalize(path.posix.join(base, request));
+  const candidates = [
+    target,
+    `${target}.js`,
+    path.posix.join(target, "index.js")
+  ];
+  for (const candidate of candidates) {
+    const absolute = path.join(cliRoot, ...candidate.split("/"));
+    if (fs.existsSync(absolute) && fs.statSync(absolute).isFile()) {
+      return normalizeModuleId(absolute);
+    }
+  }
+  throw new Error(`Unable to resolve ${request} from ${fromId}`);
+}
+
+function findLocalRequires(source) {
+  const requires = [];
+  const pattern = /require\(\s*["']([^"']+)["']\s*\)/g;
+  let match;
+  while ((match = pattern.exec(source)) !== null) {
+    if (match[1].startsWith(".")) {
+      requires.push(match[1]);
+    }
+  }
+  return requires;
+}
+
+function collectModules(entry) {
+  const modules = new Map();
+  const queue = [entry];
+
+  while (queue.length > 0) {
+    const id = queue.shift();
+    if (modules.has(id)) continue;
+
+    const absolute = path.join(cliRoot, ...id.split("/"));
+    let source = fs.readFileSync(absolute, "utf8");
+    if (source.startsWith("#!")) {
+      source = source.replace(/^#!.*\n/, "");
+    }
+    modules.set(id, source);
+
+    for (const request of findLocalRequires(source)) {
+      const resolved = resolveLocalModule(id, request);
+      if (!modules.has(resolved)) {
+        queue.push(resolved);
+      }
+    }
+  }
+
+  return modules;
+}
+
+function renderExecutable(modules) {
+  const moduleEntries = Array.from(modules.entries())
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([id, source]) => `modules[${JSON.stringify(id)}] = function(require, module, exports, __filename, __dirname) {\n${source}\n};`)
+    .join("\n\n");
+
+  return `#!/usr/bin/env node
+const __nodeRequire = require;
+const path = __nodeRequire("node:path");
+const runtimeRoot = path.dirname(process.argv[1] ? path.resolve(process.argv[1]) : __filename);
+const modules = Object.create(null);
+const moduleCache = Object.create(null);
+
+${moduleEntries}
+
+function resolveModule(fromId, request) {
+  if (!request.startsWith(".")) return request;
+  const base = path.posix.dirname(fromId);
+  const target = path.posix.normalize(path.posix.join(base, request));
+  const candidates = [target, target + ".js", path.posix.join(target, "index.js")];
+  for (const candidate of candidates) {
+    if (Object.prototype.hasOwnProperty.call(modules, candidate)) return candidate;
+  }
+  throw new Error("Unable to resolve " + request + " from " + fromId);
+}
+
+function loadModule(id) {
+  if (!Object.prototype.hasOwnProperty.call(modules, id)) {
+    return __nodeRequire(id);
+  }
+  if (moduleCache[id]) return moduleCache[id].exports;
+  const filename = path.join(runtimeRoot, ...id.split("/"));
+  const dirname = path.dirname(filename);
+  const module = { exports: {} };
+  moduleCache[id] = module;
+  const localRequire = (request) => loadModule(resolveModule(id, request));
+  modules[id](localRequire, module, module.exports, filename, dirname);
+  return module.exports;
+}
+
+loadModule(${JSON.stringify(entryId)});
+`;
+}
+
+function copyDir(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir, { withFileTypes: true })) {
+    if (entry.name === ".DS_Store") continue;
+    const source = path.join(sourceDir, entry.name);
+    const target = path.join(targetDir, entry.name);
+    if (entry.isDirectory()) {
+      copyDir(source, target);
+    } else if (entry.isFile()) {
+      fs.copyFileSync(source, target);
+    }
+  }
+}
+
+function run(command, args) {
+  const result = spawnSync(command, args, {
+    cwd: distDir,
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+function cleanDist() {
+  fs.rmSync(distDir, { recursive: true, force: true });
+  fs.mkdirSync(packageDir, { recursive: true });
+}
+
+function main() {
+  cleanDist();
+
+  const executablePath = path.join(packageDir, "evt");
+  fs.writeFileSync(executablePath, renderExecutable(collectModules(entryId)));
+  fs.chmodSync(executablePath, 0o755);
+
+  copyDir(path.join(cliRoot, "data"), path.join(packageDir, "data"));
+  copyDir(path.join(cliRoot, "skills"), path.join(packageDir, "skills"));
+  fs.copyFileSync(path.join(cliRoot, "README.md"), path.join(packageDir, "README.md"));
+  fs.copyFileSync(path.join(cliRoot, "README.zh-CN.md"), path.join(packageDir, "README.zh-CN.md"));
+
+  const artifactName = `${packageName}-${packageJson.version}-${process.platform}-${process.arch}.tar.gz`;
+  run("tar", ["-czf", artifactName, packageName]);
+
+  console.log("\nLocal package artifacts:");
+  console.log(`- dist/${packageName}/`);
+  console.log(`- dist/${artifactName}`);
+  console.log("\nPackage contents are limited to evt, data examples, skills, README.md, and README.zh-CN.md.");
+  console.log("No npm publish or remote upload was performed.");
+}
+
+main();