@icyouo/evt-cli 0.1.0

package/README.md

@@ -0,0 +1,214 @@
+# evt-cli
+
+English | [简体中文](./README.zh-CN.md)
+
+evt-cli is a general-purpose HTTP CLI for running YAML-defined APIs and workflows. It uses YAML for endpoint and flow definitions, and JSON profiles for base URLs, headers, tokens, fixtures, and cache configuration. After installation, use the `evt` command.
+
+## Principles
+
+- 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.
+- 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
+
+Install:
+
+```bash
+npm install -g @icyouo/evt-cli
+```
+
+Run the bundled example data:
+
+```bash
+evt profile list
+evt api list
+evt validate
+evt api call todo.list --profile local --dry-run
+```
+
+During local development, run the entry file directly:
+
+```bash
+node bin/evt.js profile list
+node bin/evt.js api list
+node bin/evt.js validate
+node bin/evt.js api call todo.list --profile local --dry-run
+```
+
+Use your own project data directory:
+
+```bash
+evt validate --config-root /path/to/project/cli
+evt api list --config-root /path/to/project/cli
+evt flow run login --config-root /path/to/project/cli --profile dev
+```
+
+Or set an environment variable:
+
+```bash
+export EVT_CLI_ROOT=/path/to/project/cli
+evt validate
+```
+
+## Data Layout
+
+Recommended project data layout:
+
+```text
+cli/
+  data/
+    apis/
+      *.yaml
+      *.example.yaml
+    flows/
+      *.yaml
+      *.example.yaml
+    profiles/
+      *.json
+      *.example.json
+    scanner.json
+    scanner.example.json
+```
+
+evt-cli ships with `data/**/*.example.*` for validation and reference. Real projects can maintain `data/apis/*.yaml`, `data/flows/*.yaml`, `data/profiles/*.json`, and `data/scanner.json`.
+
+For compatibility with existing projects, evt also reads `apis/`, `flows/`, `profiles/`, and `scanner.config.json` directly under `--config-root` when those paths exist.
+
+## Local Check And Package
+
+```bash
+npm run ci:local
+```
+
+This runs:
+
+- `npm test`
+- `npm run check`
+- `node bin/evt.js validate`
+- `npm run coverage:api`
+- `node scripts/build-package.js`
+
+Local package artifacts:
+
+- `dist/evt-cli/`
+- `dist/evt-cli-<version>-<platform>-<arch>.tar.gz`
+
+The local package directory contains only:
+
+- `evt`
+- `data/`
+- `README.md`
+- `README.zh-CN.md`
+
+It does not include `src/`, `scripts/`, `test/`, or `package.json`.
+
+## API Definitions
+
+Inspect an endpoint:
+
+```bash
+evt api show auth.login
+```
+
+Example API YAML:
+
+```yaml
+namespace: todo
+
+endpoints:
+  list:
+    method: "GET"
+    path: "/api/todos"
+    auth: true
+    schema:
+      query:
+        page:
+          type: "integer"
+          default: 1
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "TodoList"
+```
+
+Each endpoint should include:
+
+- `method`
+- `path`
+- `auth`
+- `bodyType`
+- `service`
+- `schema`
+- `response`
+- `dangerous: true` when the endpoint is destructive or sensitive
+
+## Scan And Coverage
+
+Scan source code for candidate endpoints:
+
+```bash
+evt api scan --scan-config ./scanner.config.json
+```
+
+Check endpoint coverage:
+
+```bash
+npm run coverage:api -- --config-root /path/to/project/cli
+```
+
+Generate missing YAML skeletons:
+
+```bash
+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:
+
+```json
+{
+  "root": ".",
+  "targets": [
+    {
+      "language": "kotlin",
+      "paths": ["shared/src/commonMain/kotlin"],
+      "include": ["**/*Service.kt"]
+    },
+    {
+      "language": "skill",
+      "name": "ast-scanner",
+      "command": "node",
+      "args": ["tools/scan-endpoints.js"]
+    }
+  ]
+}
+```
+
+An external scanner can output a JSON array or `{ "endpoints": [] }`. Each endpoint should include at least:
+
+```json
+{
+  "id": "auth.login",
+  "namespace": "auth",
+  "functionName": "login",
+  "method": "POST",
+  "path": "/api/login"
+}
+```
+
+This JSON is used only for scanning, coverage, and sync. Runtime execution still reads YAML.
+
+## Common Commands
+
+```bash
+evt profile list
+evt api list
+evt api call todo.list --dry-run
+evt flow run login --profile local
+evt cache show
+evt cache clear
+evt api test-all --profile local
+```

package/README.zh-CN.md

@@ -0,0 +1,214 @@
+# evt-cli
+
+简体中文 | [English](./README.md)
+
+evt-cli 是一个通用 HTTP CLI，用 YAML 定义接口、用 YAML 定义 flow、用 profile 管理 base URL/header/token/cache。它适合把客户端接口整理成可执行、可测试、可打包的命令行工具。安装后使用 `evt` 命令。
+
+## 核心原则
+
+- 运行时端点只来自 `apis/*.yaml`。
+- flow 只来自 `flows/*.yaml`。
+- 环境、base URL、headers、测试 fixtures 只来自 `profiles/*.json`。
+- 扫描器只用于覆盖率对比和生成缺失 YAML 骨架，不是运行时数据源。
+- 默认数据目录是当前 CLI 包内目录；也可以通过 `--config-root` 或 `EVT_CLI_ROOT` 指向项目自己的数据目录。
+
+## 快速开始
+
+安装：
+
+```bash
+npm install -g @icyouo/evt-cli
+```
+
+安装后直接运行自带 example 数据：
+
+```bash
+evt profile list
+evt api list
+evt validate
+evt api call todo.list --profile local --dry-run
+```
+
+仓库内开发时也可以直接运行：
+
+```bash
+node bin/evt.js profile list
+node bin/evt.js api list
+node bin/evt.js validate
+node bin/evt.js api call todo.list --profile local --dry-run
+```
+
+使用项目自己的数据目录：
+
+```bash
+evt validate --config-root /path/to/project/cli
+evt api list --config-root /path/to/project/cli
+evt flow run login --config-root /path/to/project/cli --profile dev
+```
+
+也可以设置环境变量：
+
+```bash
+export EVT_CLI_ROOT=/path/to/project/cli
+evt validate
+```
+
+## 数据目录
+
+项目数据目录结构：
+
+```text
+cli/
+  data/
+    apis/
+      *.yaml
+      *.example.yaml
+    flows/
+      *.yaml
+      *.example.yaml
+    profiles/
+      *.json
+      *.example.json
+    scanner.json
+    scanner.example.json
+```
+
+evt-cli 自带 `data/**/*.example.*`，用于开箱验证和复制参考。真实项目可以维护 `data/apis/*.yaml`、`data/flows/*.yaml`、`data/profiles/*.json` 和 `data/scanner.json`。
+
+为了兼容已有项目，`--config-root` 下直接存在 `apis/`、`flows/`、`profiles/`、`scanner.config.json` 时也会被读取。
+
+## 本地校验和打包
+
+```bash
+npm run ci:local
+```
+
+执行内容：
+
+- `npm test`
+- `npm run check`
+- `node bin/evt.js validate`
+- `npm run coverage:api`
+- `node scripts/build-package.js`
+
+产物：
+
+- `dist/evt-cli/`
+- `dist/evt-cli-<version>-<platform>-<arch>.tar.gz`
+
+打包目录只包含：
+
+- `evt`
+- `data/`
+- `README.md`
+- `README.zh-CN.md`
+
+不会包含 `src/`、`scripts/`、`test/`、`package.json`。
+
+## 接口定义
+
+查看接口：
+
+```bash
+evt api show auth.login
+```
+
+接口 YAML 示例：
+
+```yaml
+namespace: todo
+
+endpoints:
+  list:
+    method: "GET"
+    path: "/api/todos"
+    auth: true
+    schema:
+      query:
+        page:
+          type: "integer"
+          default: 1
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "TodoList"
+```
+
+每个 endpoint 应包含：
+
+- `method`
+- `path`
+- `auth`
+- `bodyType`
+- `service`
+- `schema`
+- `response`
+- 必要时标记 `dangerous: true`
+
+## 扫描和覆盖率
+
+扫描源码候选 endpoint：
+
+```bash
+evt api scan --scan-config ./scanner.config.json
+```
+
+覆盖率检查：
+
+```bash
+npm run coverage:api -- --config-root /path/to/project/cli
+```
+
+同步缺失 YAML 骨架：
+
+```bash
+npm run sync:api -- --config-root /path/to/project/cli
+```
+
+扫描器支持 `kotlin`、`swift`、`js`、`dart`，也支持外部 skill/AST 扫描命令：
+
+```json
+{
+  "root": ".",
+  "targets": [
+    {
+      "language": "kotlin",
+      "paths": ["shared/src/commonMain/kotlin"],
+      "include": ["**/*Service.kt"]
+    },
+    {
+      "language": "skill",
+      "name": "ast-scanner",
+      "command": "node",
+      "args": ["tools/scan-endpoints.js"]
+    }
+  ]
+}
+```
+
+外部 scanner 输出 JSON 数组，或 `{ "endpoints": [] }`。每个 endpoint 至少包含：
+
+```json
+{
+  "id": "auth.login",
+  "namespace": "auth",
+  "functionName": "login",
+  "method": "POST",
+  "path": "/api/login"
+}
+```
+
+这个 JSON 只参与扫描/覆盖率/sync，最终运行仍然读取 YAML。
+
+## 常用命令
+
+```bash
+evt profile list
+evt api list
+evt api call todo.list --dry-run
+evt flow run login --profile local
+evt cache show
+evt cache clear
+evt api test-all --profile local
+```

package/bin/evt.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+const { run } = require("../src");
+
+run(process.argv.slice(2)).catch((error) => {
+  console.error(error && error.message ? error.message : String(error));
+  process.exitCode = 1;
+});

package/data/apis/auth.example.yaml

@@ -0,0 +1,44 @@
+namespace: auth
+
+endpoints:
+  login:
+    method: "POST"
+    path: "/api/login"
+    auth: false
+    bodyType: "json"
+    schema:
+      body:
+        email:
+          type: "string"
+          required: true
+          example: "user@example.com"
+        password:
+          type: "string"
+          required: true
+          example: "Password123."
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "LoginData"
+        fields:
+          token: "string"
+          user:
+            type: "object"
+            model: "User"
+            fields:
+              id: "string"
+              email: "string"
+
+  logout:
+    method: "POST"
+    path: "/api/logout"
+    auth: true
+    dangerous: true
+    bodyType: "json"
+    schema: {}
+    response:
+      envelope: "Resp"
+      data:
+        type: "unit"
+        model: "Unit"

package/data/apis/todo.example.yaml

@@ -0,0 +1,52 @@
+namespace: todo
+
+endpoints:
+  list:
+    method: "GET"
+    path: "/api/todos"
+    auth: true
+    schema:
+      query:
+        page:
+          type: "integer"
+          default: 1
+        pageSize:
+          type: "integer"
+          default: 20
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "TodoList"
+        fields:
+          total: "integer"
+          items:
+            type: "array"
+            items:
+              type: "object"
+              model: "Todo"
+
+  create:
+    method: "POST"
+    path: "/api/todos"
+    auth: true
+    dangerous: true
+    bodyType: "json"
+    schema:
+      body:
+        title:
+          type: "string"
+          required: true
+          example: "Example todo"
+        done:
+          type: "boolean"
+          default: false
+    response:
+      envelope: "Resp"
+      data:
+        type: "object"
+        model: "Todo"
+        fields:
+          id: "string"
+          title: "string"
+          done: "boolean"

package/data/flows/login.example.yaml

@@ -0,0 +1,26 @@
+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}}"
+
+save:
+  cache:
+    token: "{{steps.login.response.data.token}}"
+    user: "{{steps.login.response.data.user}}"
+  required:
+    - cache.token

package/data/flows/smoke.example.yaml

@@ -0,0 +1,9 @@
+name: smoke
+description: Example smoke flow.
+
+steps:
+  - id: todos
+    call: todo.list
+    query:
+      page: 1
+      pageSize: 20

package/data/profiles/local.example.json

@@ -0,0 +1,29 @@
+{
+  "name": "local",
+  "env": "example",
+  "platform": "CLI",
+  "baseUrls": {
+    "default": "https://api.example.com"
+  },
+  "auth": {
+    "header": "Authorization",
+    "scheme": "bearer"
+  },
+  "headers": {
+    "Accept": "application/json",
+    "Content-Type": "application/json",
+    "X-Client": "evt-cli"
+  },
+  "inputs": {
+    "email": "user@example.com",
+    "password": "Password123."
+  },
+  "fixtures": {
+    "defaults": {
+      "page": 1,
+      "pageSize": 20,
+      "title": "Example todo",
+      "done": false
+    }
+  }
+}

package/data/scanner.example.json

@@ -0,0 +1,40 @@
+{
+  "root": ".",
+  "targets": [
+    {
+      "language": "kotlin",
+      "paths": [
+        "shared/src/commonMain/kotlin"
+      ],
+      "include": [
+        "**/*Service.kt"
+      ]
+    },
+    {
+      "language": "swift",
+      "paths": [
+        "ios/App/Services"
+      ]
+    },
+    {
+      "language": "js",
+      "paths": [
+        "src/services"
+      ]
+    },
+    {
+      "language": "dart",
+      "paths": [
+        "lib/services"
+      ]
+    },
+    {
+      "language": "skill",
+      "name": "ast-scanner",
+      "command": "node",
+      "args": [
+        "tools/scan-endpoints.js"
+      ]
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@icyouo/evt-cli",
+  "version": "0.1.0",
+  "description": "Run YAML-defined HTTP APIs and interactive workflows from your terminal.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Icyoung/everything-cli.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Icyoung/everything-cli/issues"
+  },
+  "homepage": "https://github.com/Icyoung/everything-cli#readme",
+  "bin": {
+    "evt": "./bin/evt.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "data/",
+    "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",
+    "package:local": "node scripts/build-package.js",
+    "sync:api": "node scripts/sync-api-coverage.js",
+    "coverage:api": "node scripts/check-api-coverage.js"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}