@icyouo/evt-cli 0.1.0 → 0.1.2

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/config/serviceScanner.js

@@ -97,6 +97,7 @@ function normalizeConfig(config, baseDir = repoRoot) {
   return {
     ...config,
     root,
+    apiDir: config.apiDir ? path.resolve(baseDir, config.apiDir) : undefined,
     targets: (config.targets || []).map((target) => ({ ...target }))
   };
 }
@@ -375,37 +376,85 @@ function normalizeSkillEndpoint(rawEndpoint, target, config) {
 }
 
 function scanSkillTarget(config, target) {
-  if (!target.command) {
+  const resolvedTarget = resolveSkillTarget(target);
+  if (!resolvedTarget.command) {
     throw new Error("Skill scanner target must define command");
   }
-  const cwd = target.cwd ? path.resolve(config.root, target.cwd) : config.root;
-  const result = spawnSync(target.command, (target.args || []).map(String), {
+  const cwd = resolvedTarget.cwd ? path.resolve(config.root, resolvedTarget.cwd) : config.root;
+  const result = spawnSync(resolvedTarget.command, (resolvedTarget.args || []).map(String), {
     cwd,
     encoding: "utf8",
     shell: false,
     env: {
       ...process.env,
-      ...(target.env || {})
+      EVT_SCAN_ROOT: config.root,
+      ...(resolvedTarget.env || {})
     },
-    maxBuffer: target.maxBuffer || 10 * 1024 * 1024
+    maxBuffer: resolvedTarget.maxBuffer || 10 * 1024 * 1024
   });
 
   if (result.error) {
-    throw new Error(`Skill scanner ${target.name || target.command} failed: ${result.error.message}`);
+    throw new Error(`Skill scanner ${resolvedTarget.name || resolvedTarget.command} failed: ${result.error.message}`);
   }
   if (result.status !== 0) {
     const stderr = String(result.stderr || "").trim();
-    throw new Error(`Skill scanner ${target.name || target.command} exited with ${result.status}${stderr ? `: ${stderr}` : ""}`);
+    throw new Error(`Skill scanner ${resolvedTarget.name || resolvedTarget.command} exited with ${result.status}${stderr ? `: ${stderr}` : ""}`);
   }
 
-  return parseSkillOutput(result.stdout, target)
-    .map((endpoint) => normalizeSkillEndpoint(endpoint, target, config));
+  return parseSkillOutput(result.stdout, resolvedTarget)
+    .map((endpoint) => normalizeSkillEndpoint(endpoint, resolvedTarget, config));
+}
+
+function resolveSkillTarget(target) {
+  if (!target.skill) return target;
+  if (target.skill !== "evt-api-scanner") return target;
+  return {
+    ...target,
+    name: target.name || "evt-api-scanner",
+    command: process.execPath,
+    args: target.args || [
+      path.join(cliRoot, "skills", "evt-api-scanner", "scripts", "scan.js"),
+      "--root",
+      "."
+    ]
+  };
+}
+
+function splitTargets(targets) {
+  const skillTargets = [];
+  const fallbackTargets = [];
+  for (const target of targets || []) {
+    if (isSkillTarget(target)) {
+      skillTargets.push(target);
+    } else {
+      fallbackTargets.push(target);
+    }
+  }
+  return { skillTargets, fallbackTargets };
+}
+
+function scanTargets(config, targets) {
+  return targets.flatMap((target) => scanTarget(config, target));
 }
 
 function scanServices(options = {}) {
   const config = loadScanConfig(options);
   if (!config.targets || config.targets.length === 0) return [];
-  return config.targets.flatMap((target) => scanTarget(config, target));
+  if (options.preferFallback) {
+    return scanTargets(config, config.targets.filter((target) => !isSkillTarget(target)));
+  }
+
+  const { skillTargets, fallbackTargets } = splitTargets(config.targets);
+  if (skillTargets.length === 0) {
+    return scanTargets(config, fallbackTargets);
+  }
+  try {
+    const skillEndpoints = scanTargets(config, skillTargets);
+    if (skillEndpoints.length > 0 || fallbackTargets.length === 0) return skillEndpoints;
+  } catch (error) {
+    if (fallbackTargets.length === 0 || options.strictSkill) throw error;
+  }
+  return scanTargets(config, fallbackTargets);
 }
 
 function compareScanToRegistry(scanned, registry) {
@@ -422,5 +471,6 @@ module.exports = {
   loadScanConfig,
   defaultScanConfig,
   parseCliScanOptions,
+  resolveSkillTarget,
   repoRoot
 };

package/src/index.js

@@ -1,7 +1,9 @@
+const path = require("node:path");
+const { spawnSync } = require("node:child_process");
 const { parseArgs } = require("./util/args");
 const { parseJsonObject, stableJson } = require("./util/json");
 const { redact } = require("./util/redact");
-const { setConfigRoot } = require("./util/paths");
+const { cliRoot, setConfigRoot } = require("./util/paths");
 const {
   listApiFiles,
   listProfiles,
@@ -16,6 +18,9 @@ const { runFlow } = require("./flow/runner");
 const { toCurl } = require("./http/requestBuilder");
 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") {
@@ -32,7 +37,11 @@ function usage() {
     "  evt profile show <name>",
     "  evt api list",
     "  evt api show <id>",
+    "  evt api discover [--config-root ./cli]",
     "  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",
@@ -42,6 +51,17 @@ function usage() {
   ].join("\n");
 }
 
+function runNodeScript(relativeScript, args) {
+  const result = spawnSync(process.execPath, [path.join(cliRoot, relativeScript), ...args], {
+    cwd: process.cwd(),
+    stdio: "inherit",
+    shell: false
+  });
+  if (result.status !== 0) {
+    throw new Error(`${relativeScript} failed with exit code ${result.status || 1}`);
+  }
+}
+
 function commonRuntime(options) {
   const profile = loadProfile(options.profile || "local");
   const cachePath = resolveCachePath(options.cache);
@@ -73,6 +93,30 @@ async function handleApi(tokens) {
   const sub = tokens[0];
   const options = parseArgs(tokens.slice(1));
   setConfigRoot(options.configRoot);
+
+  if (sub === "discover") {
+    const args = tokens.slice(1);
+    if (!options.configRoot && !args.includes("--config-root")) {
+      args.push("--config-root", "./cli");
+    }
+    runNodeScript("skills/evt-api-scanner/scripts/discover.js", args);
+    return;
+  }
+  if (sub === "sync") {
+    runSyncApiCoverage(tokens.slice(1));
+    return;
+  }
+  if (sub === "coverage") {
+    const result = runApiCoverage(tokens.slice(1));
+    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();
 
   if (sub === "list") {

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);
+});

package/test/duration.test.js

@@ -0,0 +1,11 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { parseDuration } = require("../src/util/duration");
+
+test("parses duration values", () => {
+  assert.equal(parseDuration(1000), 1000);
+  assert.equal(parseDuration("1000"), 1000);
+  assert.equal(parseDuration("500ms"), 500);
+  assert.equal(parseDuration("2s"), 2000);
+  assert.equal(parseDuration("1m"), 60000);
+});

package/test/flow.test.js

@@ -0,0 +1,215 @@
+const test = require("node:test");
+const assert = require("node:assert/strict");
+const { runFlow } = require("../src/flow/runner");
+const { loadApiRegistry, loadProfile } = require("../src/config/loaders");
+
+test("runs login flow in dry-run mode without prompt", async () => {
+  const result = await runFlow({
+    name: "login",
+    inputs: {
+      email: { required: true },
+      password: { required: true },
+      code: { default: "" },
+      googleCode: { default: "" }
+    },
+    steps: [
+      {
+        id: "login",
+        call: "auth.login",
+        body: {
+          email: "{{inputs.email}}",
+          password: "{{inputs.password}}"
+        }
+      }
+    ]
+  }, {
+    registry: loadApiRegistry(),
+    profile: loadProfile("local"),
+    cache: {},
+    cachePath: "/tmp/evt-cli-test-cache.json",
+    set: {
+      email: "user@example.com",
+      password: "secret"
+    },
+    dryRun: true,
+    noInteractive: true
+  });
+
+  assert.equal(result.flow, "login");
+  assert.equal(result.timeline.filter((item) => item.call).length, 1);
+  assert.equal(result.steps.login.request.method, "POST");
+});
+
+test("fails when required cache save value is missing", async () => {
+  const cachePath = "/tmp/evt-cli-required-cache-test.json";
+  const originalFetch = global.fetch;
+  global.fetch = async () => ({
+    ok: true,
+    status: 200,
+    text: async () => JSON.stringify({ code: 0, data: { info: { email: "user@example.com" } } })
+  });
+
+  try {
+    await assert.rejects(
+      runFlow({
+        name: "save-required",
+        steps: [
+          {
+            id: "login",
+            call: "auth.login",
+            body: {
+              email: "user@example.com",
+              password: "secret"
+            }
+          }
+        ],
+        save: {
+          cache: {
+            token: "{{steps.login.response.data.token}}"
+          },
+          required: ["cache.token"]
+        }
+      }, {
+        registry: loadApiRegistry(),
+        profile: loadProfile("local"),
+        cache: {},
+        cachePath,
+        set: {},
+        dryRun: false,
+        noInteractive: true
+      }),
+      /required save value: cache\.token/
+    );
+  } finally {
+    global.fetch = originalFetch;
+  }
+});
+
+test("supports step expect and extract variables", async () => {
+  const originalFetch = global.fetch;
+  global.fetch = async () => ({
+    ok: true,
+    status: 200,
+    text: async () => JSON.stringify({ code: 0, data: { token: "token-value" } })
+  });
+
+  try {
+    const result = await runFlow({
+      name: "expect-extract",
+      steps: [
+        {
+          id: "login",
+          call: "auth.login",
+          body: {
+            email: "user@example.com",
+            password: "secret"
+          },
+          expect: [
+            { path: "response.code", equals: 0 },
+            { path: "response.data.token", exists: true }
+          ],
+          extract: {
+            token: "response.data.token"
+          }
+        }
+      ]
+    }, {
+      registry: loadApiRegistry(),
+      profile: loadProfile("local"),
+      cache: {},
+      cachePath: "/tmp/evt-cli-extract-cache-test.json",
+      set: {},
+      dryRun: false,
+      noInteractive: true
+    });
+
+    assert.deepEqual(result.vars, ["token"]);
+  } finally {
+    global.fetch = originalFetch;
+  }
+});
+
+test("updates flow cache for later authenticated steps", async () => {
+  const originalFetch = global.fetch;
+  const seen = [];
+  global.fetch = async (url, options) => {
+    seen.push({ url, options });
+    if (seen.length === 1) {
+      return {
+        ok: true,
+        status: 200,
+        text: async () => JSON.stringify({ code: 0, data: { token: "token-value" } })
+      };
+    }
+    return {
+      ok: true,
+      status: 200,
+      text: async () => JSON.stringify({ code: 0, data: { email: "user@example.com" } })
+    };
+  };
+
+  try {
+    await runFlow({
+      name: "flow-cache",
+      steps: [
+        {
+          id: "login",
+          call: "auth.login",
+          body: {
+            email: "user@example.com",
+            password: "secret"
+          },
+          extract: {
+            token: "response.data.token"
+          },
+          cache: {
+            token: "{{vars.token}}"
+          }
+        },
+        {
+          id: "user",
+          call: "todo.list"
+        }
+      ]
+    }, {
+      registry: loadApiRegistry(),
+      profile: loadProfile("local"),
+      cache: {},
+      cachePath: "/tmp/evt-cli-flow-cache-test.json",
+      set: {},
+      dryRun: false,
+      noInteractive: true
+    });
+
+    assert.equal(seen[1].options.headers.Authorization, "Bearer token-value");
+  } finally {
+    global.fetch = originalFetch;
+  }
+});
+
+test("skips response expectations during dry-run", async () => {
+  const result = await runFlow({
+    name: "dry-run-expect",
+    steps: [
+      {
+        id: "oauth",
+        call: "auth.login",
+        expect: { path: "response.code", equals: 0 },
+        extract: {
+          token: "response.data.token"
+        }
+      }
+    ]
+  }, {
+    registry: loadApiRegistry(),
+    profile: loadProfile("local"),
+    cache: {},
+    cachePath: "/tmp/evt-cli-dry-run-expect-cache-test.json",
+    set: {},
+    dryRun: true,
+    noInteractive: true
+  });
+
+  assert.equal(result.flow, "dry-run-expect");
+  assert.deepEqual(result.vars, []);
+});