@icyouo/evt-cli 0.1.0 → 0.1.1

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.
+- The bundled skill scanner is preferred for discovery and YAML generation. The built-in regex scanner remains as a 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
@@ -83,6 +84,9 @@ For compatibility with existing projects, evt also reads `apis/`, `flows/`, `pro
 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 +104,7 @@ The local package directory contains only:
 
 - `evt`
 - `data/`
+- `skills/`
 - `README.md`
 - `README.zh-CN.md`
 
@@ -146,7 +151,35 @@ Each endpoint should include:
 - `response`
 - `dangerous: true` when the endpoint is destructive or sensitive
 
-## Scan And Coverage
+## Skill Scan, Sync, And Coverage
+
+evt-cli includes `skills/evt-api-scanner/SKILL.md`. Agents can use this skill to
+discover source directories, write scanner config, generate YAML endpoint
+definitions, 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
+```
+
+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 +199,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 +213,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 +241,9 @@ 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 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 只作为内部机器中间结果。
+- 内置 skill scanner 优先用于发现、生成 YAML 和覆盖率审计。现有正则 scanner 保留给没有 agent 或 skill workflow 的用户兜底。
 - 默认数据目录是当前 CLI 包内目录；也可以通过 `--config-root` 或 `EVT_CLI_ROOT` 指向项目自己的数据目录。
 
 ## 快速开始
@@ -83,6 +84,8 @@ evt-cli 自带 `data/**/*.example.*`，用于开箱验证和复制参考。真
 npm run ci:local
 ```
 
+npm 包会包含源码、脚本、测试、示例数据和 skills，用户可以自行运行本地校验并构建独立本地二进制包。
+
 执行内容：
 
 - `npm test`
@@ -100,6 +103,7 @@ npm run ci:local
 
 - `evt`
 - `data/`
+- `skills/`
 - `README.md`
 - `README.zh-CN.md`
 
@@ -146,7 +150,34 @@ endpoints:
 - `response`
 - 必要时标记 `dangerous: true`
 
-## 扫描和覆盖率
+## Skill 扫描、同步和覆盖率
+
+evt-cli 内置 `skills/evt-api-scanner/SKILL.md`。agent 可以使用这个 skill
+发现源码目录、写入 scanner 配置、生成 YAML endpoint 定义，并做覆盖率审计。
+
+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 coverage --config-root ./cli
+```
+
+内置正则 scanner 仍然保留为兜底方案。它不如 skill workflow 完整，但不依赖
+agent，也能让没有 agent 的用户勉强使用。
 
 扫描源码候选 endpoint：
 
@@ -166,7 +197,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 +210,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 +237,9 @@ 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 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.1",
   "description": "Run YAML-defined HTTP APIs and interactive workflows from your terminal.",
   "license": "MIT",
   "repository": {
@@ -17,14 +17,17 @@
   "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/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"

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();

package/scripts/check-api-coverage.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+const { loadApiRegistry } = require("../src/config/loaders");
+const { compareScanToRegistry, parseCliScanOptions, scanServices } = require("../src/config/serviceScanner");
+const { setConfigRoot } = require("../src/util/paths");
+
+function runApiCoverage(argv = process.argv.slice(2), options = {}) {
+  const scanOptions = parseCliScanOptions(argv);
+  setConfigRoot(scanOptions.configRoot);
+  const registry = loadApiRegistry();
+  const scanned = scanServices(scanOptions);
+  const comparison = compareScanToRegistry(scanned, registry);
+  const missingSchema = Object.values(registry)
+    .filter((endpoint) => !endpoint.schema)
+    .map((endpoint) => endpoint.id);
+  const missingResponse = Object.values(registry)
+    .filter((endpoint) => !endpoint.response || Object.keys(endpoint.response).length === 0)
+    .map((endpoint) => endpoint.id);
+
+  const failed = comparison.missing.length > 0 || missingSchema.length > 0 || missingResponse.length > 0;
+  const payload = {
+    scanned: scanned.length,
+    covered: comparison.covered.length,
+    missing: comparison.missing.map((endpoint) => endpoint.id),
+    endpoints: Object.keys(registry).length,
+    missingSchema,
+    missingResponse
+  };
+
+  console.log(JSON.stringify(payload, null, 2));
+  if (failed && options.exitOnFailure) process.exit(1);
+  return { failed, payload };
+}
+
+if (require.main === module) {
+  runApiCoverage(process.argv.slice(2), { exitOnFailure: true });
+}
+
+module.exports = {
+  runApiCoverage
+};

package/scripts/local-ci.js

@@ -0,0 +1,38 @@
+#!/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 distDir = path.join(cliRoot, "dist");
+
+function run(command, args, options = {}) {
+  const label = [command, ...args].join(" ");
+  console.log(`\n> ${label}`);
+  const result = spawnSync(command, args, {
+    cwd: cliRoot,
+    stdio: "inherit",
+    shell: false,
+    ...options
+  });
+  if (result.status !== 0) {
+    process.exit(result.status || 1);
+  }
+}
+
+function cleanDist() {
+  fs.rmSync(distDir, { recursive: true, force: true });
+  fs.mkdirSync(distDir, { recursive: true });
+}
+
+function main() {
+  run("npm", ["test"]);
+  run("npm", ["run", "check"]);
+  run("node", ["bin/evt.js", "validate"]);
+  run("npm", ["run", "coverage:api"]);
+  cleanDist();
+  run("node", ["scripts/build-package.js"]);
+}
+
+main();