echopai 2.0.0

package/README.md

@@ -0,0 +1,386 @@
+# echopai
+
+> **v2.0.0**: npm package renamed from `@echopai/cli` → `echopai` to match
+> the binary name. The scoped package has been unpublished — update your
+> installer to `npm install -g echopai`.
+
+Command-line interface for the EchoPai Open Platform. Programmatic access
+to stock-market data, news, analyst views, sentiment indicators, signals,
+and backtests over `https://api.echopai.com`.
+
+## Features
+
+- **11 curated agent verbs** at the top level (`lookup`, `digest`, `quote`,
+  `views`, `research`, `news`, `sentiment`, `hot`, `chart`, `bars-batch`,
+  `scan`) with task-level defaults, agent-ready outputs, and product-priority
+  encoding (`views` is the PRIMARY research source; `news` is supplementary).
+- **`digest`**: one HTTP call returns views + research-entity performance +
+  quote + sentiment + news for a single security; server-side composite
+  with `meta.partial_failures[]` tolerance; falls back to client-side
+  fan-out if `/v1/digest/{code}` is rolling.
+- **Built-in MCP stdio server** (`echopai mcp serve`) exposing curated verbs
+  to Claude Desktop / Cursor / Claude Code; `tools/list` filtered to the
+  subset your token can actually call.
+- **37 OpenAPI operations as raw mirror** under `echopai raw <noun> <verb>`,
+  auto-generated from `docs/api-contract/openapi.yaml`.
+- **Capability introspection** — `echopai whoami` (token kind / scopes /
+  available verbs / rate limits) + `echopai doctor` (3-state diagnostics).
+- **Write safety** — non-TTY writes refuse without `--yes`
+  (`confirmation_required`); `--dry-run` sends `X-Dry-Run: 1` for ops the
+  server advertises support for; auto `Idempotency-Key` UUIDv4 on every
+  `x-idempotency-required: true` endpoint.
+- **Local trace** — `~/.echopai/trace.ndjson` (50 MB ring buffer);
+  `echopai trace tail` / `trace get <request_id>` for post-hoc inspection.
+- **JSON-first I/O** — JSON envelope on stdout, JSON error on stderr,
+  three-state exit codes (0 / 1 / 2); six output formats
+  (`json` / `ndjson` / `table` / `csv` / `tsv` / `yaml`).
+- **JMESPath filter** — global `--jq <expr>`, `--fields`, `--max-bytes`
+  for shaping responses without piping to `jq`.
+- **Pagination** — `--all` for cursor/offset endpoints, bounded by
+  `--max-pages` / `--max-items`.
+- **Multi-profile config** TOML at `~/.config/echopai/config.toml` (mode 0600).
+- **Shell completion** for bash / zsh / fish.
+
+## Requirements
+
+Node.js 20 or later.
+
+## Installation
+
+```bash
+npm install -g echopai
+echopai --version
+```
+
+Or invoke without installation:
+
+```bash
+npx -y echopai market status
+```
+
+## Authentication
+
+Credentials take the form `eps_live_<lookup>_<secret>` and are issued via the
+EchoPai admin console.
+
+Resolution order (highest precedence first):
+
+1. `ECHOPAI_KEY` environment variable
+2. `--profile <name>` flag (on subcommands that accept it)
+3. Default profile in `~/.config/echopai/config.toml`
+
+Persist a credential locally:
+
+```bash
+echopai login --key eps_live_<lookup>_<secret>
+echopai status
+```
+
+Manage multiple profiles:
+
+```bash
+echopai config profile add prod \
+    --key eps_live_<lookup>_<secret> \
+    --base-url https://api.echopai.com
+echopai config profile switch prod
+echopai config profile list
+```
+
+## AI agent integration (MCP)
+
+The CLI doubles as a Model Context Protocol (MCP) stdio server, exposing
+curated agent verbs as MCP tools to Claude Desktop, Cursor, Claude Code, or
+any MCP-compatible host. The server filters its `tools/list` to the subset
+your token can actually call (intersection of curated-verb scopes with token
+scopes).
+
+Run as an MCP server:
+
+```bash
+ECHOPAI_KEY=eps_live_... echopai mcp serve
+```
+
+Claude Desktop / Cursor / Claude Code config (`~/.config/claude/...` or
+equivalent):
+
+```json
+{
+  "mcpServers": {
+    "echopai": {
+      "command": "echopai",
+      "args": ["mcp", "serve"],
+      "env": {
+        "ECHOPAI_KEY": "eps_live_<lookup>_<secret>"
+      }
+    }
+  }
+}
+```
+
+Available MCP tools (subset shown to LLM depends on token scopes):
+
+| Tool | Purpose | Backing API |
+|---|---|---|
+| `lookup` | Resolve Chinese name / code / pinyin → canonical_code | `semantic.find` |
+| `digest` | One-shot research digest: 5 buckets in one call | `digest.get` + fan-out fallback |
+| `quote` | Real-time quote for 1-200 codes | `quote` |
+| `views` | **PRIMARY** research source (analyst views w/ entity attribution) | `views.recent` |
+| `research` | Research-entity performance (hit rate / coverage) | `research.entity-performance-list` |
+| `news` | **SUPPLEMENTARY** news / market briefs | `news.search` / `news.feed` |
+| `sentiment` | Aggregate market sentiment | `sentiment.overview` |
+| `hot` | Today's hot-stock leaderboard | `stocks.hot` |
+| `chart` | Single-security K-line (daily / minute) | `bars.daily` / `bars.minute` |
+| `bars_batch` | Batch K-line (≤100 codes × 1yr daily; ≤20 × 7d minute) | `bars.daily-batch` / `bars.minute-batch` |
+| `scan` | Full-market quote snapshot (~5800 securities) | `quote.scan` |
+
+The agent should prefer `views` over `news` when forming an investment
+opinion (views carries research-entity attribution; news is breadth-only).
+
+The MCP transport sends `X-Client-Channel: mcp` upstream so server-side
+audit / per-channel rate limiting can distinguish MCP traffic from CLI.
+
+## Common usage
+
+```bash
+# Market session state
+echopai market status
+
+# Real-time quotes (CSV codes)
+echopai quote --codes "SSE:600519,SZSE:000001"
+
+# News search with table output
+echopai news search --query "AI" --since-hours 24 --output table
+
+# Daily bars for a security over a date range
+echopai chart --code SSE:600519 --from 2026-01-01 --to 2026-05-01
+
+# Iterate all pages of analyst views (NDJSON one item per line)
+echopai raw views feed --since-days 7 --all | jq '.title'
+
+# One-shot research digest (server-side composite, 5 buckets, partial-failure tolerant)
+echopai digest --code SSE:600519
+```
+
+## Output formats
+
+```bash
+echopai news search --query AI --output json     # default; pretty in TTY
+echopai news search --query AI --output ndjson   # one JSON object per line
+echopai news search --query AI --output table    # ASCII table
+echopai news search --query AI --output csv      # RFC-4180
+echopai news search --query AI --output tsv
+echopai news search --query AI --output yaml
+```
+
+## Pagination
+
+Endpoints that declare `x-cli-pagination: cursor|offset` accept `--all`:
+
+```bash
+echopai news feed --all --since-hours 168 | jq '.title'
+echopai news feed --all --max-pages 10 --max-items 500
+```
+
+## WebSocket streaming
+
+The CLI does **not** expose `/v1/ws/{news,views}` directly. Those upstream
+handlers gate on user-JWT JSON-auth, which is incompatible with the CLI's
+partner static-key bearer-subprotocol model. Partner SDKs that need WS
+should target the endpoints directly (the OpenAPI ops are still public);
+the CLI sticks to HTTP for now.
+
+## Write safety and dry-run
+
+Curated verbs are all read-only. The raw mirror surfaces a handful of
+writes (e.g. `agent.session-start`); these are gated:
+
+```bash
+# In a non-TTY (script / CI / agent), writes refuse without --yes:
+$ echo "" | echopai raw agent session-start --agent-id my-agent
+{"error":{"code":"confirmation_required","message":"Operation agent.session-start is a write (side-effect=write) and stdout is not a TTY. Pass --yes to confirm."}}
+
+# --dry-run sends X-Dry-Run:1 on ops the server advertises support for.
+# Useful for previewing what a write would do without persisting.
+echopai --yes --dry-run raw agent session-start --agent-id my-agent --budget-usd 1.0
+
+# --dry-run on a write op that doesn't advertise support → refused
+$ echopai --yes --dry-run raw agent session-end <session_id>
+{"error":{"code":"dry_run_unsupported","message":"..."}}
+```
+
+## Channel enforcement
+
+Every outbound HTTP request carries `X-Client-Channel: cli` (or `mcp`
+when running under `echopai mcp serve`). Tokens may carry an
+`allowed_clients` JWT claim restricting which channels the token may use,
+plus `client_overrides` for per-channel `rate_limit_qps` tightening,
+`extra_scopes_deny`, or `read_only` on non-GET methods. Configure these
+on the credential when issuing through admin console.
+
+## Idempotency
+
+For endpoints that declare `x-idempotency-required: true` (for example,
+`agent session-start`), the CLI generates a UUIDv4 `Idempotency-Key` and
+echoes it to stderr so it can be reused on retry:
+
+```text
+$ echopai agent session-start
+[idempotency-key] agent.session-start: 7d8f2c00-3b9a-4f1d-8e2c-9c0a1b2d3e4f
+[idempotency-key] retry: pass --idempotency-key 7d8f2c00-... to dedupe.
+{"data":{"session_id":"sess_..."}}
+```
+
+Provide an explicit key with `--idempotency-key <uuid>` to dedupe at the
+server.
+
+## Exit codes
+
+| Code | Meaning |
+|------|---------|
+| 0    | Success |
+| 1    | User error (4xx, invalid arguments, authentication or scope failure) |
+| 2    | Service error (5xx, network failure, internal error) |
+
+Error envelope (single line on stderr):
+
+```json
+{"error":{"code":"scope_insufficient","message":"...","recovery_hint":"...","request_id":"req_...","http_status":403}}
+```
+
+In a TTY the same envelope is rendered as a coloured, multi-line message
+with the `recovery_hint` highlighted. Non-TTY environments (CI, pipelines)
+always receive single-line JSON.
+
+## Global flags
+
+| Flag | Description |
+|------|-------------|
+| `--debug` | Print HTTP wire trace to stderr; the bearer token is redacted |
+| `--raw` | Skip envelope unwrapping; emit the raw response body |
+| `--jq <expr>` | JMESPath transform applied to `data` (renamed from `--query` in v2.0 to avoid clashing with subcommand `--query` body params, e.g. `news.search`) |
+| `--fields <a,b,c>` | Keep only listed top-level fields per item |
+| `--max-bytes <n>` | Truncate serialised envelope; sets `meta.truncated=true` |
+| `--yes` | Confirm a write op in non-TTY mode (required for `sideEffect=write` ops) |
+| `--dry-run` | Send `X-Dry-Run: 1` on writes where the server advertises support |
+| `--output <format>` | Override per-command default output format |
+
+Profile and credential overrides are exposed on the relevant subcommands
+(`echopai status --profile <name>`, `echopai login --key ...`); they are
+intentionally not declared as global options to avoid conflicting with
+subcommand parameters of the same name.
+
+## Schema introspection
+
+```bash
+echopai schema list           # one line per command (cliKey, method, path, summary)
+echopai schema get news.search
+echopai schema export         # full surface as NDJSON, including JSON Schemas
+```
+
+## Raw HTTP passthrough
+
+For arbitrary requests (debugging, unmirrored endpoints):
+
+```bash
+echopai raw call GET /v1/some/path -q since_hours=24
+echopai raw call POST /v1/some/path -d '{"key":"value"}'
+```
+
+`echopai api call` is a deprecated alias of `raw call`; it will be removed
+in the next major.
+
+## Shell completion
+
+```bash
+echopai completion bash > ~/.local/share/bash-completion/completions/echopai
+echopai completion zsh  > "${fpath[1]}/_echopai"
+echopai completion fish > ~/.config/fish/completions/echopai.fish
+```
+
+## Architecture
+
+```
+docs/api-contract/openapi.yaml                  (single source of truth)
+                 │
+                 ▼  scripts/codegen/generate_cli_v2.py
+src/_generated/  (operations + command tree + help text)
+                 │
+                 ▼
+src/runtime/     (invoker, auth, http, envelope, errors, filters,
+                  trace, paginator, verb_runner, verb_cmd, whoami_cache)
+                 │
+                 ▼
+src/tools/       (login, status, config, raw, schema, completion,
+                  whoami, doctor, trace, mcp)
+src/verbs/       (lookup, digest, quote, views, research, news,
+                  sentiment, hot, chart, bars_batch, scan + _spec)
+                 │
+                 ▼
+src/bin.ts
+```
+
+New raw mirror endpoints are added by setting `x-cli-key` (and optionally
+`x-cli-pagination`, `x-cli-output-default`) on the OpenAPI operation; the
+command tree is regenerated automatically. Curated verbs (`src/verbs/`)
+are hand-written task-level wrappers that can fan-out over multiple raw
+ops; each declares a `VerbSpec` shared by CLI and MCP entries.
+
+## Development
+
+```bash
+cd cli
+npm install
+npm run codegen   # regenerate src/_generated/ from the OpenAPI spec
+npm test          # vitest: codegen, runtime, paginator, idempotency, tools
+npx tsx src/bin.ts --help
+
+# Run against the staging environment
+ECHOPAI_BASE_URL=https://staging.echopai.com \
+ECHOPAI_KEY=eps_live_<lookup>_<secret> \
+  npx tsx src/bin.ts news search --query AI --output table
+
+# HTTP wire trace (bearer redacted)
+npx tsx src/bin.ts market status --debug
+```
+
+## Releasing
+
+Two paths are supported. Both are documented in `docs/PLAN_CLI_V2_REWRITE.md`.
+
+### Tag-triggered release (recommended)
+
+After a version bump is merged to `main`, push a tag named `cli-v<version>`:
+
+```bash
+git tag cli-v2.0.0
+git push origin cli-v2.0.0
+```
+
+`.github/workflows/release-cli.yml` builds, tests, runs `npm publish
+--access public --provenance`, and verifies the new version on the registry.
+The workflow requires a repository secret named `NPM_ACCESS_TOKEN` (an npm
+granular access token with the *Bypass 2FA* flag enabled).
+
+### Local script
+
+For ad-hoc releases without GitHub Actions:
+
+```bash
+bash scripts/publish-cli.sh             # publish the current cli/package.json version
+bash scripts/publish-cli.sh --dry-run   # inspect the tarball without publishing
+```
+
+The script reads `NPM_ACCESS_TOKEN` from `server/.env`, writes it to a
+temporary `.npmrc` (mode 0600), invokes `npm publish`, then deletes the
+file via a shell `trap` (the token never appears on the command line).
+
+## Links
+
+- Platform overview: `https://echopai.com`
+- Partner documentation: `docs/partner-api/`
+- Source: `https://github.com/evanzhangx/EchoPulse/tree/main/cli`
+- Issues: `https://github.com/evanzhangx/EchoPulse/issues`
+
+## License
+
+MIT

package/dist/_generated/commands.js

@@ -0,0 +1,274 @@
+/**
+ * AUTO-GENERATED — DO NOT EDIT BY HAND.
+ *
+ * Source: docs/api-contract/openapi.yaml
+ * Generator: scripts/codegen/generate_cli_v2.py
+ */
+import { Option } from "commander";
+import { OPERATIONS } from "./operations.js";
+/**
+ * commander v12 把 --since-hours 自动 camelCase 成 sinceHours，但 OpenAPI 这
+ * 边期待 snake_case (since_hours)。一次性 camelCase → snake_case 反转。
+ */
+function camelToSnake(s) {
+    return s.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase());
+}
+function attachOperation(cmd, op, dispatch) {
+    cmd.description(op.summary || op.description);
+    // positional args
+    for (const pname of op.positional) {
+        const required = (op.inputSchema.required || []).includes(pname);
+        cmd.argument(required ? `<${pname}>` : `[${pname}]`, String(op.inputSchema.properties[pname]?.description ?? ""));
+    }
+    // remaining params → --flag (dashes for ergonomics; reverse camelCase later)
+    for (const [pname, pschema] of Object.entries(op.inputSchema.properties)) {
+        if (op.positional.includes(pname))
+            continue;
+        const required = (op.inputSchema.required || []).includes(pname);
+        const flagName = `--${pname.replace(/_/g, "-")} <value>`;
+        const desc = String(pschema?.description ?? "");
+        const opt = new Option(flagName, desc);
+        if (required)
+            opt.makeOptionMandatory(true);
+        cmd.addOption(opt);
+    }
+    cmd.addOption(new Option("--output <format>", "Output format: json|ndjson|table|csv|tsv|yaml").choices(["json", "ndjson", "table", "csv", "tsv", "yaml"]).default(op.outputDefault));
+    if (op.pagination !== 'none') {
+        cmd.addOption(new Option("--all", "Fetch all pages and stream NDJSON"));
+        cmd.addOption(new Option("--max-pages <n>", "Stop after N pages (default 1000)"));
+        cmd.addOption(new Option("--max-items <n>", "Stop after N items (default 100000)"));
+    }
+    if (op.idempotencyRequired) {
+        cmd.addOption(new Option("--idempotency-key <uuid>", "Override auto-generated Idempotency-Key (debug / replay)"));
+    }
+    // WS stream options removed (--reconnect / --max-frames). CLI no longer
+    // exposes /v1/ws/{news,views} as commands; codegen now drops x-cli-key
+    // for those ops so `op.stream` is always false here.
+    cmd.action(async (...rawArgs) => {
+        const opts = cmd.opts();
+        // reverse commander's camelCase: sinceHours → since_hours
+        const args = {};
+        for (const [k, v] of Object.entries(opts)) {
+            args[camelToSnake(k)] = v;
+        }
+        op.positional.forEach((pname, i) => {
+            if (rawArgs[i] !== undefined)
+                args[pname] = rawArgs[i];
+        });
+        await dispatch(op, args);
+    });
+}
+export function buildCommandTree(program, dispatch) {
+    {
+        const noun = program.command("agent");
+        noun.description("agent commands");
+        {
+            const cmd = noun.command("session-end");
+            attachOperation(cmd, OPERATIONS["agent.session-end"], dispatch);
+        }
+        {
+            const cmd = noun.command("session-start");
+            attachOperation(cmd, OPERATIONS["agent.session-start"], dispatch);
+        }
+        {
+            const cmd = noun.command("session-usage");
+            attachOperation(cmd, OPERATIONS["agent.session-usage"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("auth");
+        noun.description("auth commands");
+        {
+            const cmd = noun.command("whoami");
+            attachOperation(cmd, OPERATIONS["auth.whoami"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("backtest");
+        noun.description("backtest commands");
+        {
+            const cmd = noun.command("excess-distribution");
+            attachOperation(cmd, OPERATIONS["backtest.excess-distribution"], dispatch);
+        }
+        {
+            const cmd = noun.command("rolling-win-rate");
+            attachOperation(cmd, OPERATIONS["backtest.rolling-win-rate"], dispatch);
+        }
+        {
+            const cmd = noun.command("summary");
+            attachOperation(cmd, OPERATIONS["backtest.summary"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("bars");
+        noun.description("bars commands");
+        {
+            const cmd = noun.command("daily");
+            attachOperation(cmd, OPERATIONS["bars.daily"], dispatch);
+        }
+        {
+            const cmd = noun.command("daily-batch");
+            attachOperation(cmd, OPERATIONS["bars.daily-batch"], dispatch);
+        }
+        {
+            const cmd = noun.command("minute");
+            attachOperation(cmd, OPERATIONS["bars.minute"], dispatch);
+        }
+        {
+            const cmd = noun.command("minute-batch");
+            attachOperation(cmd, OPERATIONS["bars.minute-batch"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("digest");
+        noun.description("digest commands");
+        {
+            const cmd = noun.command("get");
+            attachOperation(cmd, OPERATIONS["digest.get"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("market");
+        noun.description("market commands");
+        {
+            const cmd = noun.command("status");
+            attachOperation(cmd, OPERATIONS["market.status"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("news");
+        noun.description("news commands");
+        {
+            const cmd = noun.command("feed");
+            attachOperation(cmd, OPERATIONS["news.feed"], dispatch);
+        }
+        {
+            const cmd = noun.command("get");
+            attachOperation(cmd, OPERATIONS["news.get"], dispatch);
+        }
+        {
+            const cmd = noun.command("list");
+            attachOperation(cmd, OPERATIONS["news.list"], dispatch);
+        }
+        {
+            const cmd = noun.command("search");
+            attachOperation(cmd, OPERATIONS["news.search"], dispatch);
+        }
+        {
+            const cmd = noun.command("sources");
+            attachOperation(cmd, OPERATIONS["news.sources"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("payment");
+        noun.description("payment commands");
+        {
+            const cmd = noun.command("plans");
+            attachOperation(cmd, OPERATIONS["payment.plans"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("quote");
+        noun.description("quote commands");
+        {
+            const cmd = noun.command("quote");
+            attachOperation(cmd, OPERATIONS["quote"], dispatch);
+        }
+        {
+            const cmd = noun.command("scan");
+            attachOperation(cmd, OPERATIONS["quote.scan"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("research");
+        noun.description("research commands");
+        {
+            const cmd = noun.command("entity-performance");
+            attachOperation(cmd, OPERATIONS["research.entity-performance"], dispatch);
+        }
+        {
+            const cmd = noun.command("entity-performance-list");
+            attachOperation(cmd, OPERATIONS["research.entity-performance-list"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("semantic");
+        noun.description("semantic commands");
+        {
+            const cmd = noun.command("find");
+            attachOperation(cmd, OPERATIONS["semantic.find"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("sentiment");
+        noun.description("sentiment commands");
+        {
+            const cmd = noun.command("breadth");
+            attachOperation(cmd, OPERATIONS["sentiment.breadth"], dispatch);
+        }
+        {
+            const cmd = noun.command("overview");
+            attachOperation(cmd, OPERATIONS["sentiment.overview"], dispatch);
+        }
+        {
+            const cmd = noun.command("pct-distribution");
+            attachOperation(cmd, OPERATIONS["sentiment.pct-distribution"], dispatch);
+        }
+        {
+            const cmd = noun.command("turnover");
+            attachOperation(cmd, OPERATIONS["sentiment.turnover"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("signals");
+        noun.description("signals commands");
+        {
+            const cmd = noun.command("outcome");
+            attachOperation(cmd, OPERATIONS["signals.outcome"], dispatch);
+        }
+        {
+            const cmd = noun.command("outcomes");
+            attachOperation(cmd, OPERATIONS["signals.outcomes"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("squawk");
+        noun.description("squawk commands");
+        {
+            const cmd = noun.command("audio");
+            attachOperation(cmd, OPERATIONS["squawk.audio"], dispatch);
+        }
+        {
+            const cmd = noun.command("waveform");
+            attachOperation(cmd, OPERATIONS["squawk.waveform"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("stocks");
+        noun.description("stocks commands");
+        {
+            const cmd = noun.command("hot");
+            attachOperation(cmd, OPERATIONS["stocks.hot"], dispatch);
+        }
+        {
+            const cmd = noun.command("social-hot");
+            attachOperation(cmd, OPERATIONS["stocks.social-hot"], dispatch);
+        }
+    }
+    {
+        const noun = program.command("views");
+        noun.description("views commands");
+        {
+            const cmd = noun.command("feed");
+            attachOperation(cmd, OPERATIONS["views.feed"], dispatch);
+        }
+        {
+            const cmd = noun.command("get");
+            attachOperation(cmd, OPERATIONS["views.get"], dispatch);
+        }
+        {
+            const cmd = noun.command("recent");
+            attachOperation(cmd, OPERATIONS["views.recent"], dispatch);
+        }
+    }
+}