@icyouo/evt-cli 0.1.1 → 0.1.2

package/README.md

@@ -10,7 +10,7 @@ evt-cli is a general-purpose HTTP CLI for running YAML-defined APIs and workflow
 - Flows come only from `flows/*.yaml`.
 - Environments, base URLs, headers, and test fixtures come only from `profiles/*.json`.
 - 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.
+- 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
@@ -78,6 +78,24 @@ 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
@@ -151,11 +169,17 @@ Each endpoint should include:
 - `response`
 - `dangerous: true` when the endpoint is destructive or sensitive
 
-## Skill Scan, Sync, And Coverage
+## Skills, Scan, Sync, And Coverage
+
+evt-cli includes these bundled skills:
 
-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.
+- `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.
@@ -172,6 +196,12 @@ Generate or update YAML endpoint definitions:
 evt api sync --config-root ./cli
 ```
 
+Audit YAML quality after sync:
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
 Check YAML coverage:
 
 ```bash
@@ -243,6 +273,7 @@ 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

package/README.zh-CN.md

@@ -10,7 +10,7 @@ evt-cli 是一个通用 HTTP CLI，用 YAML 定义接口、用 YAML 定义 flow
 - flow 只来自 `flows/*.yaml`。
 - 环境、base URL、headers、测试 fixtures 只来自 `profiles/*.json`。
 - endpoint 定义持久化格式始终是 YAML。scanner JSON 只作为内部机器中间结果。
-- 内置 skill scanner 优先用于发现、生成 YAML 和覆盖率审计。现有正则 scanner 保留给没有 agent 或 skill workflow 的用户兜底。
+- 内置 skills 优先用于项目 data 初始化。现有正则 scanner 只保留给没有 agent 或 skill workflow 的用户做 endpoint 扫描兜底。
 - 默认数据目录是当前 CLI 包内目录；也可以通过 `--config-root` 或 `EVT_CLI_ROOT` 指向项目自己的数据目录。
 
 ## 快速开始
@@ -78,6 +78,18 @@ 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
@@ -150,10 +162,16 @@ endpoints:
 - `response`
 - 必要时标记 `dangerous: true`
 
-## Skill 扫描、同步和覆盖率
+## Skills、扫描、同步和覆盖率
+
+evt-cli 内置这些 skills：
 
-evt-cli 内置 `skills/evt-api-scanner/SKILL.md`。agent 可以使用这个 skill
-发现源码目录、写入 scanner 配置、生成 YAML endpoint 定义，并做覆盖率审计。
+- `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 的最终定义格式。
@@ -170,6 +188,12 @@ evt api discover --config-root ./cli
 evt api sync --config-root ./cli
 ```
 
+检查 YAML 质量门禁：
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
 检查 YAML 覆盖率：
 
 ```bash
@@ -239,6 +263,7 @@ 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@icyouo/evt-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Run YAML-defined HTTP APIs and interactive workflows from your terminal.",
   "license": "MIT",
   "repository": {
@@ -27,10 +27,11 @@
   "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 && node --check skills/evt-api-scanner/scripts/discover.js && node --check skills/evt-api-scanner/scripts/scan.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/check-api-audit.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+const { listProfiles, loadApiRegistry, loadProfile } = require("../src/config/loaders");
+const { compareScanToRegistry, scanServices } = require("../src/config/serviceScanner");
+const { setConfigRoot } = require("../src/util/paths");
+
+function toNumber(value, fallback) {
+  if (value === undefined || value === null || value === "") return fallback;
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`Expected number, got: ${value}`);
+  return parsed;
+}
+
+function camelOption(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function parseAuditOptions(argv = []) {
+  const options = {};
+  const booleanOptions = new Set(["strict", "preferFallback", "strictSkill"]);
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith("--")) continue;
+    const raw = token.slice(2);
+    const equals = raw.indexOf("=");
+    const name = camelOption(equals >= 0 ? raw.slice(0, equals) : raw);
+    const inlineValue = equals >= 0 ? raw.slice(equals + 1) : undefined;
+    if (booleanOptions.has(name)) {
+      options[name] = inlineValue === undefined ? true : inlineValue !== "false";
+    } else if (inlineValue !== undefined) {
+      options[name] = inlineValue;
+    } else {
+      index += 1;
+      if (index >= argv.length) throw new Error(`--${raw} expects a value`);
+      options[name] = argv[index];
+    }
+  }
+  return options;
+}
+
+function hasObjectEntries(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value) && Object.keys(value).length > 0;
+}
+
+function schemaGroupHasFields(group) {
+  return hasObjectEntries(group);
+}
+
+function hasMeaningfulSchema(endpoint) {
+  const schema = endpoint.schema;
+  if (!hasObjectEntries(schema)) return false;
+  return schemaGroupHasFields(schema.path) || schemaGroupHasFields(schema.query) || schemaGroupHasFields(schema.body);
+}
+
+function hasDetailedResponse(endpoint) {
+  const response = endpoint.response;
+  if (!hasObjectEntries(response)) return false;
+  const data = response.data;
+  if (!data || typeof data !== "object" || Array.isArray(data)) return true;
+  if (data.type !== "object") return true;
+  return Boolean(data.model || data.fields || data.items || response.envelope);
+}
+
+function isGenericResponse(endpoint) {
+  return hasObjectEntries(endpoint.response) && !hasDetailedResponse(endpoint);
+}
+
+function hasUnresolvedPath(endpoint) {
+  const value = String(endpoint.path || "");
+  return /\$\{|AppConfig|undefined|null/.test(value);
+}
+
+function hasUsablePath(endpoint) {
+  const value = String(endpoint.path || "");
+  return /^https?:\/\//i.test(value) || value.startsWith("/") || Boolean(endpoint.service);
+}
+
+function looksPrivate(endpoint) {
+  const haystack = `${endpoint.id || ""} ${endpoint.path || ""}`.toLowerCase();
+  return /(user|account|asset|balance|order|position|history|withdraw|deposit|transfer|address|invite|identity|auth|password|bind|google|phone|email)/.test(haystack) &&
+    !/(login|register|oauth|public|config|country|currency|currencies|banner|language|version|market|ticker|kline|depth|symbol|spotitems|contractitems)/.test(haystack);
+}
+
+function looksPublic(endpoint) {
+  const haystack = `${endpoint.id || ""} ${endpoint.path || ""}`.toLowerCase();
+  return /(login|register|oauth|public|config|country|currency|currencies|banner|language|version|market|ticker|kline|depth|symbol|spotitems|contractitems)/.test(haystack);
+}
+
+function looksDangerous(endpoint) {
+  const method = String(endpoint.method || "GET").toUpperCase();
+  if (method === "GET") return false;
+  const haystack = `${endpoint.id || ""} ${endpoint.path || ""}`.toLowerCase();
+  return /(create|change|adjust|cancel|close|open|transfer|withdraw|bind|unbind|modify|patch|add|update|delete|disable|identity|set|unlink|margin|leverage|order|password)/.test(haystack) &&
+    !/(login|check|send|verify|oauth)/.test(haystack);
+}
+
+function endpointList(registry) {
+  return Object.values(registry).sort((left, right) => left.id.localeCompare(right.id));
+}
+
+function ratio(count, total) {
+  return total === 0 ? 0 : count / total;
+}
+
+function collectProfileServices() {
+  const services = new Set();
+  const profiles = [];
+  for (const profileName of listProfiles()) {
+    const profile = loadProfile(profileName);
+    profiles.push(profileName);
+    for (const service of Object.keys(profile.baseUrls || {})) {
+      services.add(service);
+    }
+    if (profile.baseUrl) services.add("default");
+  }
+  return { profiles, services };
+}
+
+function summarize(registry, scanned) {
+  const endpoints = endpointList(registry);
+  const comparison = compareScanToRegistry(scanned, registry);
+  const { profiles, services } = collectProfileServices();
+  const byMethodPath = new Map();
+  for (const endpoint of endpoints) {
+    const key = `${String(endpoint.method || "GET").toUpperCase()}:${endpoint.path}`;
+    if (!byMethodPath.has(key)) byMethodPath.set(key, []);
+    byMethodPath.get(key).push(endpoint.id);
+  }
+
+  const emptySchema = endpoints.filter((endpoint) => !hasMeaningfulSchema(endpoint));
+  const missingResponse = endpoints.filter((endpoint) => !hasObjectEntries(endpoint.response));
+  const genericResponse = endpoints.filter(isGenericResponse);
+  const unresolvedPath = endpoints.filter(hasUnresolvedPath);
+  const unusablePath = endpoints.filter((endpoint) => !hasUsablePath(endpoint));
+  const unmatchedService = endpoints.filter((endpoint) => endpoint.service && profiles.length > 0 && !services.has(endpoint.service));
+  const duplicateMethodPath = Array.from(byMethodPath.entries())
+    .filter(([, ids]) => ids.length > 1)
+    .map(([key, ids]) => ({ key, ids }));
+  const authSuspect = endpoints.filter((endpoint) =>
+    (endpoint.auth === false && looksPrivate(endpoint)) ||
+    (endpoint.auth === true && looksPublic(endpoint))
+  );
+  const dangerousSuspect = endpoints.filter((endpoint) => !endpoint.dangerous && looksDangerous(endpoint));
+
+  return {
+    scanned: scanned.length,
+    endpoints: endpoints.length,
+    covered: comparison.covered.length,
+    missing: comparison.missing.map((endpoint) => endpoint.id),
+    profiles,
+    emptySchema: emptySchema.map((endpoint) => endpoint.id),
+    missingResponse: missingResponse.map((endpoint) => endpoint.id),
+    genericResponse: genericResponse.map((endpoint) => endpoint.id),
+    unresolvedPath: unresolvedPath.map((endpoint) => endpoint.id),
+    unusablePath: unusablePath.map((endpoint) => endpoint.id),
+    unmatchedService: unmatchedService.map((endpoint) => `${endpoint.id}:${endpoint.service}`),
+    duplicateMethodPath,
+    authSuspect: authSuspect.map((endpoint) => endpoint.id),
+    dangerousSuspect: dangerousSuspect.map((endpoint) => endpoint.id),
+    ratios: {
+      emptySchema: ratio(emptySchema.length, endpoints.length),
+      genericResponse: ratio(genericResponse.length, endpoints.length)
+    }
+  };
+}
+
+function evaluateStrict(summary, options) {
+  const maxMissing = toNumber(options.maxMissing, 0);
+  const maxEmptySchemaRatio = toNumber(options.maxEmptySchemaRatio, 0.25);
+  const maxGenericResponseRatio = toNumber(options.maxGenericResponseRatio, 0.05);
+  const maxUnresolvedPath = toNumber(options.maxUnresolvedPath, 0);
+  const maxUnmatchedService = toNumber(options.maxUnmatchedService, 0);
+  const maxUnusablePath = toNumber(options.maxUnusablePath, 0);
+  const maxDuplicateMethodPath = toNumber(options.maxDuplicateMethodPath, 0);
+  const failures = [];
+
+  if (summary.missing.length > maxMissing) failures.push(`missing scan coverage ${summary.missing.length} > ${maxMissing}`);
+  if (summary.ratios.emptySchema > maxEmptySchemaRatio) {
+    failures.push(`empty schema ratio ${summary.ratios.emptySchema.toFixed(3)} > ${maxEmptySchemaRatio}`);
+  }
+  if (summary.ratios.genericResponse > maxGenericResponseRatio) {
+    failures.push(`generic response ratio ${summary.ratios.genericResponse.toFixed(3)} > ${maxGenericResponseRatio}`);
+  }
+  if (summary.unresolvedPath.length > maxUnresolvedPath) failures.push(`unresolved paths ${summary.unresolvedPath.length} > ${maxUnresolvedPath}`);
+  if (summary.unmatchedService.length > maxUnmatchedService) failures.push(`unmatched services ${summary.unmatchedService.length} > ${maxUnmatchedService}`);
+  if (summary.unusablePath.length > maxUnusablePath) failures.push(`unusable paths ${summary.unusablePath.length} > ${maxUnusablePath}`);
+  if (summary.duplicateMethodPath.length > maxDuplicateMethodPath) {
+    failures.push(`duplicate method+path ${summary.duplicateMethodPath.length} > ${maxDuplicateMethodPath}`);
+  }
+  if (summary.missingResponse.length > 0) failures.push(`missing responses ${summary.missingResponse.length} > 0`);
+
+  return failures;
+}
+
+function compact(summary) {
+  return {
+    scanned: summary.scanned,
+    endpoints: summary.endpoints,
+    covered: summary.covered,
+    missing: summary.missing,
+    profiles: summary.profiles,
+    counts: {
+      emptySchema: summary.emptySchema.length,
+      missingResponse: summary.missingResponse.length,
+      genericResponse: summary.genericResponse.length,
+      unresolvedPath: summary.unresolvedPath.length,
+      unusablePath: summary.unusablePath.length,
+      unmatchedService: summary.unmatchedService.length,
+      duplicateMethodPath: summary.duplicateMethodPath.length,
+      authSuspect: summary.authSuspect.length,
+      dangerousSuspect: summary.dangerousSuspect.length
+    },
+    ratios: summary.ratios,
+    samples: {
+      emptySchema: summary.emptySchema.slice(0, 25),
+      genericResponse: summary.genericResponse.slice(0, 25),
+      unresolvedPath: summary.unresolvedPath.slice(0, 25),
+      unmatchedService: summary.unmatchedService.slice(0, 25),
+      authSuspect: summary.authSuspect.slice(0, 25),
+      dangerousSuspect: summary.dangerousSuspect.slice(0, 25)
+    },
+    duplicateMethodPath: summary.duplicateMethodPath.slice(0, 25)
+  };
+}
+
+function runApiAudit(argv = process.argv.slice(2), options = {}) {
+  const auditOptions = parseAuditOptions(argv);
+  const strict = Boolean(auditOptions.strict || options.strict);
+  setConfigRoot(auditOptions.configRoot);
+  const registry = loadApiRegistry();
+  const scanned = scanServices(auditOptions);
+  const summary = summarize(registry, scanned);
+  const failures = strict ? evaluateStrict(summary, auditOptions) : [];
+  const payload = {
+    ok: failures.length === 0,
+    strict: Boolean(strict),
+    ...compact(summary),
+    failures
+  };
+
+  if (!options.silent) {
+    console.log(JSON.stringify(payload, null, 2));
+  }
+  if (failures.length > 0 && options.exitOnFailure) process.exit(1);
+  return { failed: failures.length > 0, payload, summary };
+}
+
+if (require.main === module) {
+  runApiAudit(process.argv.slice(2), { exitOnFailure: true });
+}
+
+module.exports = {
+  runApiAudit,
+  summarize,
+  evaluateStrict,
+  parseAuditOptions,
+  hasMeaningfulSchema,
+  hasDetailedResponse,
+  isGenericResponse
+};

package/skills/evt-api-scanner/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: evt-api-scanner
-description: Use when an agent needs to discover API source locations, generate evt-cli scanner config, scan a codebase for HTTP endpoints, sync YAML API definitions, or check endpoint coverage for evt-cli projects.
+description: Use when an agent needs to discover API source locations, generate evt-cli scanner config, scan a codebase for HTTP endpoints, sync YAML API definitions, check endpoint coverage, or bootstrap endpoint data for evt-cli projects.
 ---
 
 # evt-api-scanner
@@ -14,24 +14,63 @@ scan, sync, or audit YAML API definitions.
    - Prefer the user's explicit `--config-root`.
    - Otherwise use `EVT_CLI_ROOT`.
    - Otherwise use `./cli` from the project root.
-2. Discover source locations and write scanner config:
+2. Read any existing non-example API YAML first. Preserve existing endpoint IDs,
+   service names, auth flags, schema, response, and dangerous markers unless
+   source evidence proves they are wrong.
+3. Discover source locations and write scanner config:
 
 ```bash
 node skills/evt-api-scanner/scripts/discover.js --root . --config-root ./cli
 ```
 
-3. Generate or update endpoint YAML:
+4. Generate or update endpoint YAML:
 
 ```bash
 evt api sync --config-root ./cli
 ```
 
-4. Check YAML coverage:
+5. Enrich the generated YAML from source. Do not stop at scanner skeletons.
+6. Audit YAML quality:
+
+```bash
+evt api audit --config-root ./cli --strict
+```
+
+If strict audit fails because of empty schemas, generic responses, unresolved
+paths, or unmatched services, use the audit samples as the next edit queue and
+continue enrichment.
+
+7. Check YAML coverage:
 
 ```bash
 evt api coverage --config-root ./cli
 ```
 
+8. When bootstrapping an empty project, continue with:
+   - `evt-profile-generator` to create `data/profiles/*.json`.
+   - `evt-flow-generator` to create `data/flows/*.yaml`.
+
+## Source Evidence
+
+Collect these signals before finalizing YAML:
+
+- HTTP service declarations for method, path, body type, and function names.
+- Repository or client call sites for auth requirements, default arguments,
+  endpoint aliases, and feature ownership.
+- Request DTOs, method parameters, annotations, or typed request builders for
+  `schema.path`, `schema.query`, and `schema.body`.
+- Response DTOs, generic wrappers, serializers, or model declarations for
+  `response.envelope`, `response.data.model`, `response.data.type`, and fields.
+- App config, DI modules, HTTP clients, interceptors, or base URL providers for
+  `service` names and absolute URL handling.
+- Existing tests, docs, and product flows for dangerous operations and required
+  ordering.
+
+For Kotlin/KMP projects, inspect service interfaces, repositories, DTO/model
+files, app config, DI modules, and header/interceptor builders. For Swift, JS,
+and Dart projects, inspect equivalent API clients, request models, response
+models, environment config, and auth/header middleware.
+
 ## Endpoint Format
 
 Endpoint definitions are always persisted as YAML under `data/apis/*.yaml` or
@@ -48,10 +87,58 @@ endpoints:
     method: "POST"
     path: "/api/login"
     auth: false
-    schema: {}
-    response: {}
+    schema:
+      body:
+        email:
+          type: "string"
+          required: true
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "LoginData"
+        fields:
+          token: "string"
+          user:
+            type: "object"
+```
+
+## Quality Rules
+
+- Endpoint IDs should be stable. Preserve existing IDs. If no YAML exists, use
+  source function names exactly and do not add, remove, or normalize prefixes
+  such as `get` unless a project convention proves that mapping.
+- Do not leave `schema: {}` when source parameters or request DTOs exist.
+- Do not use generic `response.data.type: object` when a response type or DTO
+  can be resolved.
+- For wrapped responses such as `Resp<T>`, record the envelope and the nested
+  data model.
+- Preserve path parameters, query parameters embedded in path strings, and
+  absolute URLs. Map alternate hosts to `service` when profiles can provide a
+  named base URL.
+- Infer `auth` from the HTTP client, repository call path, interceptor, or
+  feature state. Public market/config endpoints are usually unauthenticated;
+  user/account/order/history endpoints usually require auth. Mark uncertain
+  cases in the final report.
+- Mark mutating or irreversible endpoints with `dangerous: true`; examples are
+  order creation/cancelation, withdrawal, transfer, account deletion, and
+  credential changes.
+- Keep scanner JSON internal. Runtime endpoint data remains YAML.
+
+## Completion Check
+
+Run these before final answer:
+
+```bash
+evt validate --config-root ./cli
+evt api audit --config-root ./cli --strict
+evt api coverage --config-root ./cli
 ```
 
+Report endpoint count, empty-schema count, generic-response count, auth
+uncertain count, and any endpoints whose ID or path could not be resolved
+confidently.
+
 ## Fallback
 
 evt-cli should prefer this skill scanner when configured. If the skill scanner

package/skills/evt-flow-generator/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: evt-flow-generator
+description: Use when an agent needs to create or update evt-cli YAML flows from API YAML definitions, product workflows, authentication requirements, or test scenarios, including interactive inputs, waits, token cache saves, and feature smoke flows.
+---
+
+# evt-flow-generator
+
+Use this skill to produce executable evt-cli flows under `data/flows/*.yaml` or
+legacy `flows/*.yaml`.
+
+## Workflow
+
+1. Locate the evt config root.
+   - Prefer the user's explicit `--config-root`.
+   - Otherwise use `EVT_CLI_ROOT`.
+   - Otherwise use `./cli` from the project root.
+2. Inspect available endpoints:
+
+```bash
+evt api list --config-root ./cli
+evt api show <namespace.endpoint> --config-root ./cli
+```
+
+3. Read existing flow examples and product docs/source to identify:
+   - login or session refresh sequence
+   - token field path in the login response
+   - prerequisite calls for feature flows
+   - required waits between calls
+   - safe smoke-test values from profile fixtures
+4. Read the evt runtime semantics before saving values:
+   - each step result contains `response`, the full parsed response
+   - each step result contains `data`, the unwrapped `response.data` when present
+   - for wrapped APIs, prefer `steps.<id>.response.data.<field>` for cache saves
+5. Write YAML flows such as:
+   - `data/flows/login.yaml`
+   - `data/flows/smoke.yaml`
+   - `data/flows/<feature>.yaml`
+6. Validate:
+
+```bash
+evt validate --config-root ./cli
+```
+
+## Flow Format
+
+```yaml
+name: login
+description: Login and save session token.
+
+inputs:
+  email:
+    prompt: Email
+    type: string
+    required: true
+  password:
+    prompt: Password
+    type: password
+    required: true
+
+steps:
+  - id: login
+    call: auth.login
+    body:
+      email: "{{inputs.email}}"
+      password: "{{inputs.password}}"
+    expect:
+      path: response.data.token
+      exists: true
+
+save:
+  cache:
+    token: "{{steps.login.response.data.token}}"
+  required:
+    - cache.token
+```
+
+Use waits when the backend needs spacing:
+
+```yaml
+steps:
+  - id: createOrder
+    call: trade.createOrder
+    body:
+      symbol: "{{inputs.symbol}}"
+      side: "BUY"
+  - wait: 2s
+  - id: queryOrder
+    call: trade.orderDetail
+    query:
+      orderId: "{{steps.createOrder.response.data.orderId}}"
+```
+
+Use `afterWait` when only one step needs a post-call interval.
+
+## Rules
+
+- Runtime flows are YAML. Do not persist flow definitions as JSON.
+- Keep bundled `*.example.yaml` generic; write project-specific flows to
+  non-example YAML files.
+- Use `inputs` for values a user may need to type dynamically.
+- Use `profile.inputs` by naming flow inputs the same way as profile keys.
+- Use profile-backed values for device/session fields when source does so, for
+  example `{{profile.device.fingerprintId}}` instead of a new placeholder input.
+- Use `wait` or `afterWait` for backend intervals; valid values include `500ms`,
+  `2s`, and `1m`.
+- Preserve waits found in source, tests, docs, or existing flows.
+- Save login state through `save.cache.token` and `save.required`. For wrapped
+  responses, prefer `{{steps.login.response.data.token}}`.
+- Reference previous step outputs with `{{steps.<id>.<path>}}`.
+- Prefer `expect` checks for required response fields when a flow depends on
+  them.
+- Put logout last in flows that include logout.
+- For feature flows, include prerequisite reads, state-changing calls, follow-up
+  reads, waits, cleanup, and final assertions when the scenario needs them.
+- Use endpoint schema and profile fixtures to build request bodies. Do not
+  invent field names that are absent from endpoint YAML or source models.
+- Do not include destructive business actions unless the project or user states
+  that the environment is safe for testing.
+
+## Completion Check
+
+After writing flows, run:
+
+```bash
+evt validate --config-root ./cli
+evt flow run login --config-root ./cli --profile <profile> --dry-run
+```
+
+For login flows, inspect the dry-run output and verify:
+
+- the expected endpoint order is present
+- required waits are present
+- token save path matches the response model
+- headers come from the selected profile
+- no required input is missing
+
+When real credentials and a safe test environment are available, run the login
+flow without `--dry-run`, confirm the token is written to cache, then run the
+authenticated smoke or feature flow. Report any step that was only inferred.

package/skills/evt-profile-generator/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: evt-profile-generator
+description: Use when an agent needs to create or update evt-cli profile JSON files from project source, environment config, API YAML schemas, documentation, or user-provided credentials so evt-cli can run real APIs and flows.
+---
+
+# evt-profile-generator
+
+Use this skill to produce usable evt-cli profiles under `data/profiles/*.json`
+or legacy `profiles/*.json`.
+
+## Workflow
+
+1. Locate the evt config root.
+   - Prefer the user's explicit `--config-root`.
+   - Otherwise use `EVT_CLI_ROOT`.
+   - Otherwise use `./cli` from the project root.
+2. Read existing profile examples:
+
+```bash
+evt profile list --config-root ./cli
+```
+
+3. Inspect project source, docs, and environment files for:
+   - base URLs by environment
+   - static headers, app version, device/platform headers, tenant headers
+   - auth header name and token scheme
+   - login inputs and test fixtures required by endpoint schemas
+4. Inspect the project's HTTP runtime before writing headers:
+   - environment config and app config
+   - DI modules or client factories
+   - header builders and interceptors
+   - auth/session/cache code
+   - platform/device providers
+5. Write real profiles such as `data/profiles/dev.json`,
+   `data/profiles/android.dev.json`, or `data/profiles/ios.dev.json`.
+6. Validate:
+
+```bash
+evt validate --config-root ./cli
+```
+
+## Profile Format
+
+Use valid JSON only. Do not add comments.
+
+```json
+{
+  "name": "dev",
+  "env": "dev",
+  "platform": "ANDROID",
+  "baseUrls": {
+    "default": "https://api.dev.example.com"
+  },
+  "auth": {
+    "header": "Authorization",
+    "scheme": "bearer"
+  },
+  "headers": {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "Platform": "{{profile.platform}}"
+  },
+  "device": {
+    "fingerprintId": "dev-fingerprint"
+  },
+  "inputs": {
+    "email": "user@example.com",
+    "password": "Password123."
+  },
+  "fixtures": {
+    "defaults": {
+      "page": 1,
+      "pageSize": 20
+    }
+  }
+}
+```
+
+## Rules
+
+- Keep bundled `*.example.json` generic; write project-specific data to
+  non-example profile files.
+- Do not invent production secrets. Use user-provided test credentials,
+  documented test values, or safe placeholders.
+- Prefer separate profiles when platforms have different headers, device
+  fields, or base URLs.
+- Use exact enum casing and header names from source. If source uses `ANDROID`,
+  do not write `android`.
+- Include backing fields for every templated header value, such as
+  `{{profile.device.fingerprintId}}`.
+- Only include headers sent by the same runtime client. Do not merge unrelated
+  web, server, or third-party headers just because they appear elsewhere in the
+  repository.
+- Keep static app headers and device headers in the profile; keep dynamic
+  per-request headers in endpoint YAML or flow steps.
+- Put values needed by interactive flows in `inputs`.
+- Put reusable endpoint test values in `fixtures.defaults` or grouped fixture
+  objects named after the endpoint domain.
+- Configure token injection with `auth.header` and `auth.scheme`; token values
+  themselves belong in evt cache after login, not in the profile.
+- If multiple API hosts exist, add named entries in `baseUrls` and set matching
+  endpoint metadata only when the API YAML supports it.
+- Make `baseUrls` names match endpoint `service` values exactly.
+- If auth uses a raw token header, set `"scheme": "raw"`. If it uses an
+  Authorization bearer token, set `"scheme": "bearer"`.
+- Prefer values from source or docs over guesses. If a required runtime value is
+  unknown, leave a realistic placeholder and make the related flow input
+  interactive.
+
+## Completion Check
+
+After writing the profile, run:
+
+```bash
+evt validate --config-root ./cli
+evt profile list --config-root ./cli
+```
+
+If endpoint YAML and flows already exist, also dry-run login with the generated
+profile and compare the produced request headers with the source header builder.
+Report placeholder credentials, uncertain headers, and base URLs that were not
+found in source.

package/src/index.js

@@ -20,6 +20,7 @@ const { compareScanToRegistry, scanServices } = require("./config/serviceScanner
 const { runLiveApiTest } = require("./api/liveTester");
 const { runSyncApiCoverage } = require("../scripts/sync-api-coverage");
 const { runApiCoverage } = require("../scripts/check-api-coverage");
+const { runApiAudit } = require("../scripts/check-api-audit");
 
 function print(value, json = false) {
   if (json || typeof value !== "string") {
@@ -40,6 +41,7 @@ function usage() {
     "  evt api scan [--missing] [--scan-config path/to/scanner.json]",
     "  evt api sync [--config-root ./cli]",
     "  evt api coverage [--config-root ./cli]",
+    "  evt api audit [--config-root ./cli] [--strict]",
     "  evt api call <id> [--profile local] [--set k=v] [--body '{...}'] [--dry-run]",
     "  evt api test-all [--profile local] [--include-dangerous] [--only namespace]",
     "  evt validate",
@@ -109,6 +111,11 @@ async function handleApi(tokens) {
     if (result.failed) throw new Error("API coverage failed");
     return;
   }
+  if (sub === "audit") {
+    const result = runApiAudit(tokens.slice(1));
+    if (result.failed) throw new Error("API audit failed");
+    return;
+  }
 
   const registry = loadApiRegistry();
 

package/src/util/args.js

@@ -38,6 +38,9 @@ function parseArgs(tokens) {
       "includeDangerous",
       "noLogin",
       "missing",
+      "strict",
+      "preferFallback",
+      "strictSkill",
       "help"
     ]);
 

package/test/apiAudit.test.js

@@ -0,0 +1,137 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
+const { runApiAudit } = require("../scripts/check-api-audit");
+
+function writeFile(root, relative, content) {
+  const file = path.join(root, relative);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  fs.writeFileSync(file, content);
+  return file;
+}
+
+function fixtureRoot() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "evt-api-audit-"));
+  writeFile(root, "src/AuthService.kt", `
+    class AuthService(val http: Http) {
+      suspend fun login(): Resp<LoginData> {
+        return http.post("/api/login")
+      }
+    }
+  `);
+  writeFile(root, "data/scanner.json", JSON.stringify({
+    root,
+    targets: [
+      {
+        language: "kotlin",
+        paths: ["src"],
+        namespaceStripSuffixes: ["Service"]
+      }
+    ]
+  }, null, 2));
+  return root;
+}
+
+test("api audit flags scanner skeletons in strict mode", () => {
+  const root = fixtureRoot();
+  writeFile(root, "data/apis/auth.yaml", `
+namespace: auth
+
+endpoints:
+  login:
+    method: "POST"
+    path: "/api/login"
+    auth: false
+    schema: {}
+    response:
+      data:
+        type: "object"
+`);
+
+  const result = runApiAudit(["--config-root", root, "--strict"], { silent: true });
+
+  assert.equal(result.failed, true);
+  assert.equal(result.payload.counts.emptySchema, 1);
+  assert.equal(result.payload.counts.genericResponse, 1);
+  assert.match(result.payload.failures.join("\\n"), /empty schema ratio/);
+  assert.match(result.payload.failures.join("\\n"), /generic response ratio/);
+});
+
+test("api audit passes enriched endpoint definitions", () => {
+  const root = fixtureRoot();
+  writeFile(root, "data/apis/auth.yaml", `
+namespace: auth
+
+endpoints:
+  login:
+    method: "POST"
+    path: "/api/login"
+    auth: false
+    schema:
+      body:
+        email:
+          type: "string"
+          required: true
+        password:
+          type: "string"
+          required: true
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "LoginData"
+        fields:
+          token: "string"
+`);
+
+  const result = runApiAudit(["--config-root", root, "--strict"], { silent: true });
+
+  assert.equal(result.failed, false);
+  assert.equal(result.payload.counts.emptySchema, 0);
+  assert.equal(result.payload.counts.genericResponse, 0);
+  assert.deepEqual(result.payload.failures, []);
+});
+
+test("cli api audit accepts strict as a boolean flag", () => {
+  const root = fixtureRoot();
+  writeFile(root, "data/apis/auth.yaml", `
+namespace: auth
+
+endpoints:
+  login:
+    method: "POST"
+    path: "/api/login"
+    auth: false
+    schema:
+      body:
+        email:
+          type: "string"
+          required: true
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "LoginData"
+        fields:
+          token: "string"
+`);
+
+  const result = spawnSync(process.execPath, [
+    path.join(__dirname, "..", "bin", "evt.js"),
+    "api",
+    "audit",
+    "--config-root",
+    root,
+    "--strict"
+  ], {
+    encoding: "utf8"
+  });
+
+  assert.equal(result.status, 0, result.stderr || result.stdout);
+  const payload = JSON.parse(result.stdout);
+  assert.equal(payload.ok, true);
+  assert.equal(payload.strict, true);
+});