echopai 2.0.0

package/dist/tools/mcp.js

@@ -0,0 +1,141 @@
+/**
+ * `echopai mcp serve` — stdio MCP server.
+ *
+ * 启动流程:
+ *  1. 解析凭据 (ECHOPAI_KEY / ECHOPAI_PROFILE / --profile)
+ *  2. getWhoami(channel="mcp") 拿 token scopes
+ *  3. 用 OPERATIONS.scopesAny 把 ALL_VERB_SPECS 过滤到 token 可调子集
+ *  4. registerTool 每个可用 verb (Zod inputSchema 直接给 SDK)
+ *  5. connect stdio transport, 进 message loop
+ *
+ * Tool handler:
+ *  - 收到 tools/call → 调 spec.handler(args, ctx) (channel="mcp" 注入 header)
+ *  - 成功 → 返 MCP content block (JSON envelope 序列化为 text)
+ *  - 失败 → CallApiError 映射为 MCP isError=true tool response
+ *
+ * 错误日志走 stderr (MCP stdio 协议: stdout 仅 JSON-RPC, stderr 可任意文本)。
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Command, Option } from "commander";
+import { OPERATIONS } from "../_generated/operations.js";
+import { resolveCredentials, AuthMissingError } from "../runtime/auth.js";
+import { CallApiError } from "../runtime/errors.js";
+import { getWhoami } from "../runtime/whoami_cache.js";
+import { ALL_VERB_SPECS } from "../verbs/index.js";
+import { CLI_VERSION } from "../version.js";
+/** Verb is available iff at least one backing op is callable with token scopes. */
+export function verbAvailable(spec, tokenScopes) {
+    if (spec.backingOps.length === 0)
+        return true;
+    for (const opKey of spec.backingOps) {
+        const op = OPERATIONS[opKey];
+        if (!op)
+            continue;
+        if (op.scopesAny.length === 0)
+            return true;
+        if (op.scopesAny.some((s) => tokenScopes.has(s)))
+            return true;
+    }
+    return false;
+}
+export function filterAvailableVerbs(specs, tokenScopes) {
+    return specs.filter((s) => verbAvailable(s, tokenScopes));
+}
+export function envelopeToToolResponse(envelope) {
+    return {
+        content: [{ type: "text", text: JSON.stringify(envelope) }],
+    };
+}
+export function errorToToolResponse(e) {
+    if (e instanceof CallApiError) {
+        const env = {
+            error: {
+                code: e.code,
+                message: e.message,
+                retryable: e.retryable,
+                ...(e.recovery_hint ? { recovery_hint: e.recovery_hint } : {}),
+                ...(e.requestId ? { request_id: e.requestId } : {}),
+            },
+        };
+        return { content: [{ type: "text", text: JSON.stringify(env) }], isError: true };
+    }
+    const env = {
+        error: {
+            code: "internal_error",
+            message: e instanceof Error ? e.message : String(e),
+            retryable: false,
+        },
+    };
+    return { content: [{ type: "text", text: JSON.stringify(env) }], isError: true };
+}
+export function buildMcpCommand() {
+    const mcp = new Command("mcp").description("Model Context Protocol bridge (expose curated verbs to MCP hosts)");
+    mcp
+        .command("serve")
+        .description("Run an MCP stdio server on this process. For Claude Desktop / Cursor / Claude Code.")
+        .addOption(new Option("--profile <name>", "Use a specific profile"))
+        .action(async (opts) => {
+        let creds;
+        try {
+            creds = resolveCredentials(opts.profile ? { profile: opts.profile } : {});
+        }
+        catch (e) {
+            if (e instanceof AuthMissingError) {
+                process.stderr.write(`[mcp] credential resolution failed: ${e.message}\n` +
+                    `[mcp] hint: ${e.recovery_hint ?? "Run `echopai login` or set ECHOPAI_KEY."}\n`);
+                process.exit(1);
+            }
+            throw e;
+        }
+        let whoami;
+        try {
+            whoami = await getWhoami({
+                baseUrl: creds.baseUrl,
+                bearer: creds.key,
+                cliVersion: CLI_VERSION,
+                channel: "mcp",
+            });
+        }
+        catch (e) {
+            process.stderr.write(`[mcp] whoami failed: ${e instanceof Error ? e.message : String(e)}\n`);
+            process.exit(1);
+        }
+        const tokenScopes = new Set(whoami.scopes);
+        const availableVerbs = filterAvailableVerbs(ALL_VERB_SPECS, tokenScopes);
+        process.stderr.write(`[mcp] kind=${whoami.kind} scopes=[${whoami.scopes.join(",")}]\n` +
+            `[mcp] exposing ${availableVerbs.length}/${ALL_VERB_SPECS.length} curated verbs as MCP tools\n`);
+        const server = new McpServer({
+            name: "echopai",
+            version: CLI_VERSION,
+            title: "EchoPai",
+        }, {
+            capabilities: { tools: {} },
+        });
+        const handlerCtx = {
+            baseUrl: creds.baseUrl,
+            bearer: creds.key,
+            cliVersion: CLI_VERSION,
+            channel: "mcp",
+        };
+        for (const spec of availableVerbs) {
+            server.registerTool(spec.name, {
+                description: spec.description,
+                inputSchema: spec.inputSchema,
+            }, async (args) => {
+                try {
+                    const envelope = await spec.handler(args, handlerCtx);
+                    return envelopeToToolResponse(envelope);
+                }
+                catch (e) {
+                    return errorToToolResponse(e);
+                }
+            });
+        }
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        process.stderr.write("[mcp] connected on stdio; waiting for messages\n");
+        // The server runs until stdin closes; SDK handles shutdown.
+    });
+    return mcp;
+}

package/dist/tools/raw.js

@@ -0,0 +1,96 @@
+/**
+ * `echopai raw call <method> <path> [--data '{...}'] [--query k=v ...]`
+ *
+ * Raw HTTP passthrough — 给未 codegen 的端点 / debug / 应急用。
+ * 跳过 Ajv pre-flight 校验、跳过 envelope 解析；行为 = curl + Bearer 注入 + base URL。
+ *
+ * 自动注入 X-Client / X-Client-Channel / X-Request-Id (与 spec-driven 调用同源)，
+ * 这样 server 端 audit 能识别这是 CLI 流量。
+ *
+ * `echopai api call ...` 保留为 deprecated alias 一个 release (tools/api.ts)；
+ * 下一个 major 移除。
+ */
+import { Command } from "commander";
+import { fetch as undiciFetch } from "undici";
+import { resolveCredentials, AuthMissingError } from "../runtime/auth.js";
+import { buildHttpHeaders } from "../runtime/http.js";
+import { CLI_VERSION } from "../version.js";
+export function buildRawCallCommand() {
+    const call = new Command("call")
+        .description("Raw HTTP passthrough (arbitrary <method> <path>; debug / non-codegen endpoints)")
+        .argument("<method>", "HTTP method (GET|POST|PUT|PATCH|DELETE|HEAD)")
+        .argument("<path>", "URL path (relative; base URL injected from credential)")
+        .option("-d, --data <json>", "POST/PUT/PATCH body (JSON string)")
+        .option("-q, --query <kv...>", "Query string entries: k=v")
+        .option("--header <kv...>", "Extra headers: K=V");
+    call.action(async (method, urlPath, opts) => {
+        const m = method.toUpperCase();
+        if (!["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"].includes(m)) {
+            return die("invalid_args", `Unknown HTTP method: ${method}`, 1);
+        }
+        let creds;
+        try {
+            creds = resolveCredentials({});
+        }
+        catch (e) {
+            if (e instanceof AuthMissingError) {
+                return die("auth_missing", e.message, 1, e.recovery_hint);
+            }
+            throw e;
+        }
+        let url = creds.baseUrl + (urlPath.startsWith("/") ? urlPath : "/" + urlPath);
+        if (opts.query?.length) {
+            const qs = opts.query
+                .map((kv) => {
+                const idx = kv.indexOf("=");
+                if (idx === -1)
+                    return null;
+                return `${encodeURIComponent(kv.slice(0, idx))}=${encodeURIComponent(kv.slice(idx + 1))}`;
+            })
+                .filter((s) => s !== null)
+                .join("&");
+            if (qs)
+                url += (url.includes("?") ? "&" : "?") + qs;
+        }
+        // Use centralized header builder (Phase 1.1) — automatically injects
+        // X-Client / X-Client-Channel / X-Request-Id. Raw passthrough should
+        // still be tagged as CLI traffic in server audit.
+        const { headers } = buildHttpHeaders({
+            bearer: creds.key,
+            cliVersion: CLI_VERSION,
+        });
+        if (opts.header) {
+            for (const kv of opts.header) {
+                const idx = kv.indexOf("=");
+                if (idx === -1)
+                    continue;
+                headers.set(kv.slice(0, idx), kv.slice(idx + 1));
+            }
+        }
+        const init = { method: m, headers };
+        if (opts.data) {
+            if (!headers.has("content-type")) {
+                headers.set("content-type", "application/json");
+            }
+            init.body = opts.data;
+        }
+        const res = await undiciFetch(url, init);
+        const body = await res.text();
+        process.stdout.write(body + (body.endsWith("\n") ? "" : "\n"));
+        process.exit(res.status >= 400 && res.status < 500
+            ? 1
+            : res.status >= 500
+                ? 2
+                : 0);
+    });
+    return call;
+}
+function die(code, message, exitCode, recovery_hint) {
+    const env = {
+        error: { code, message, retryable: false },
+    };
+    if (recovery_hint)
+        env.error.recovery_hint = recovery_hint;
+    process.stderr.write(JSON.stringify(env) + "\n");
+    process.exit(exitCode);
+}

package/dist/tools/schema.js

@@ -0,0 +1,58 @@
+/**
+ * `echopai schema [list | get <key> | export]`
+ *
+ * AI agent ingestion 路径：`echopai schema export | ai-tool` 一次拿全部命令的
+ * input JSON Schema + path + method + 示例。
+ */
+import { Command } from "commander";
+import { OPERATIONS, listOperations } from "../_generated/operations.js";
+import { HELP } from "../_generated/help.js";
+export function buildSchemaCommand() {
+    const cmd = new Command("schema").description("Inspect / export the CLI command surface");
+    cmd
+        .command("list")
+        .description("Print one line per command: cliKey, method, path, summary")
+        .action(() => {
+        for (const op of listOperations()) {
+            process.stdout.write(JSON.stringify({
+                cliKey: op.cliKey,
+                method: op.method,
+                path: op.path,
+                summary: op.summary,
+            }) + "\n");
+        }
+        process.exit(0);
+    });
+    cmd
+        .command("get <cliKey>")
+        .description("Print full operation def + help (input schema + example)")
+        .action((cliKey) => {
+        const op = OPERATIONS[cliKey];
+        if (!op) {
+            process.stderr.write(JSON.stringify({
+                error: {
+                    code: "schema_not_found",
+                    message: `No command with cliKey '${cliKey}'.`,
+                    recovery_hint: "Run `echopai schema list` for available keys.",
+                },
+            }) + "\n");
+            process.exit(1);
+        }
+        const help = HELP[cliKey] ?? null;
+        const out = { ...op, ...(help ? { example: help.example } : {}) };
+        process.stdout.write(JSON.stringify(out, null, 2) + "\n");
+        process.exit(0);
+    });
+    cmd
+        .command("export")
+        .description("NDJSON dump of full surface (one operation per line) — for AI agents")
+        .action(() => {
+        for (const op of listOperations()) {
+            const help = HELP[op.cliKey];
+            const merged = { ...op, ...(help ? { example: help.example } : {}) };
+            process.stdout.write(JSON.stringify(merged) + "\n");
+        }
+        process.exit(0);
+    });
+    return cmd;
+}

package/dist/tools/trace.js

@@ -0,0 +1,54 @@
+/**
+ * `echopai trace [tail | get <request_id>]`
+ *
+ * 本地调用追溯 ring buffer (~/.echopai/trace.ndjson)。每次 CLI 调用结束都会
+ * 写一条 NDJSON。用途：
+ *   - 看最近 N 次调用 (tail)
+ *   - 用 request_id 反查具体一次 (get)
+ *
+ * `ECHOPAI_NO_TRACE=1` 关闭写入；`ECHOPAI_TRACE_FILE=/path` 改路径（测试用）。
+ */
+import { Command, Option } from "commander";
+import { getTraceByRequestId, resolveTraceFile, tailTraces, } from "../runtime/trace.js";
+export function buildTraceCommand() {
+    const cmd = new Command("trace").description("Inspect local CLI invocation trace (~/.echopai/trace.ndjson)");
+    cmd
+        .command("tail")
+        .description("Print last N trace records (NDJSON)")
+        .addOption(new Option("--lines <n>", "Number of records").default("20"))
+        .action((opts) => {
+        const n = Math.max(1, Math.floor(Number(opts.lines) || 20));
+        const records = tailTraces(n);
+        for (const r of records) {
+            process.stdout.write(JSON.stringify(r) + "\n");
+        }
+        process.exit(0);
+    });
+    cmd
+        .command("get <request_id>")
+        .description("Find a single trace record by request_id")
+        .action((requestId) => {
+        const r = getTraceByRequestId(requestId);
+        if (!r) {
+            process.stderr.write(JSON.stringify({
+                error: {
+                    code: "not_found",
+                    message: `No trace record with request_id '${requestId}'.`,
+                    retryable: false,
+                    recovery_hint: "Trace ring buffer holds ~50MB. Older records rotate to `trace.ndjson.1` and beyond that are lost.",
+                },
+            }) + "\n");
+            process.exit(1);
+        }
+        process.stdout.write(JSON.stringify(r, null, 2) + "\n");
+        process.exit(0);
+    });
+    cmd
+        .command("path")
+        .description("Print the resolved trace file path")
+        .action(() => {
+        process.stdout.write(resolveTraceFile() + "\n");
+        process.exit(0);
+    });
+    return cmd;
+}

package/dist/tools/whoami.js

@@ -0,0 +1,132 @@
+/**
+ * `echopai whoami`
+ *
+ * 调 /v1/auth/whoami 拿 token 自省 + 派生 operation 可用性：
+ *   available:    token 至少有一个 op.scopesAny 中的 scope (或 scopesAny 为空)
+ *   unavailable:  op.scopesAny 非空且全部 miss → missing_scopes_any 全部列出
+ *
+ * 输出标准 envelope；缓存 5min in-process (whoami_cache.ts)。
+ *
+ * 该命令是 Phase 4 MCP `tools/list` 推导逻辑的同源——MCP server 启动时调用
+ * 同一个 getWhoami() 拿能力图。
+ */
+import { Command, Option } from "commander";
+import { listOperations } from "../_generated/operations.js";
+import { resolveCredentials, AuthMissingError } from "../runtime/auth.js";
+import { CallApiError } from "../runtime/errors.js";
+import { isTtyHuman, renderError } from "../runtime/tty.js";
+import { clearWhoamiCache, getWhoami } from "../runtime/whoami_cache.js";
+import { CLI_VERSION } from "../version.js";
+export function deriveOperationAvailability(scopes, ops = listOperations()) {
+    const available = [];
+    const unavailable = [];
+    for (const op of ops) {
+        const required = op.scopesAny;
+        const summary = { cliKey: op.cliKey, method: op.method, path: op.path };
+        if (!required || required.length === 0) {
+            available.push(summary);
+            continue;
+        }
+        const hit = required.some((s) => scopes.has(s));
+        if (hit) {
+            available.push(summary);
+        }
+        else {
+            unavailable.push({ ...summary, missing_scopes_any: required.slice() });
+        }
+    }
+    return { available, unavailable };
+}
+export function buildWhoamiOutput(whoami, channel, ops = listOperations()) {
+    const scopeSet = new Set(whoami.scopes);
+    const { available, unavailable } = deriveOperationAvailability(scopeSet, ops);
+    const out = {
+        kind: whoami.kind,
+        scopes: whoami.scopes,
+        channel,
+        operations: { available, unavailable },
+    };
+    if (whoami.app_id)
+        out.app_id = whoami.app_id;
+    if (whoami.org_id)
+        out.org_id = whoami.org_id;
+    if (whoami.app_slug)
+        out.app_slug = whoami.app_slug;
+    if (whoami.audience)
+        out.audience = whoami.audience;
+    if (whoami.api_version)
+        out.api_version = whoami.api_version;
+    if (whoami.allowed_clients)
+        out.allowed_clients = whoami.allowed_clients;
+    if (whoami.feature_flags && Object.keys(whoami.feature_flags).length > 0) {
+        out.feature_flags = whoami.feature_flags;
+    }
+    if (whoami.rate_limit?.qps != null)
+        out.rate_limit_qps = whoami.rate_limit.qps;
+    if (whoami.rate_limit?.monthly_quota != null) {
+        out.monthly_quota = whoami.rate_limit.monthly_quota;
+    }
+    return out;
+}
+export function buildWhoamiCommand() {
+    const cmd = new Command("whoami").description("Show current token capabilities (kind / scopes / available operations)");
+    cmd.addOption(new Option("--no-cache", "Bypass 5-minute whoami cache"));
+    cmd.addOption(new Option("--key <key>", "Override credential (env / config)"));
+    cmd.addOption(new Option("--profile <name>", "Use a specific profile"));
+    cmd.action(async (opts) => {
+        let creds;
+        try {
+            creds = resolveCredentials({
+                ...(opts.key ? { key: opts.key } : {}),
+                ...(opts.profile ? { profile: opts.profile } : {}),
+            });
+        }
+        catch (e) {
+            if (e instanceof AuthMissingError) {
+                emitError("auth_missing", e.message, e.recovery_hint, 1);
+            }
+            throw e;
+        }
+        if (opts.cache === false)
+            clearWhoamiCache();
+        let whoami;
+        try {
+            whoami = await getWhoami({ baseUrl: creds.baseUrl, bearer: creds.key, cliVersion: CLI_VERSION }, { force: opts.cache === false });
+        }
+        catch (e) {
+            if (e instanceof CallApiError) {
+                emitError(e.code, e.message, e.recovery_hint, e.httpStatus && e.httpStatus < 500 ? 1 : 2, e.requestId);
+            }
+            throw e;
+        }
+        const data = buildWhoamiOutput(whoami, "cli");
+        const envelope = {
+            data,
+            meta: {
+                cli_version: CLI_VERSION,
+                ...(whoami.api_version ? { api_version: whoami.api_version } : {}),
+            },
+        };
+        process.stdout.write(JSON.stringify(envelope) + "\n");
+        process.exit(0);
+    });
+    return cmd;
+}
+function emitError(code, message, recoveryHint, exitCode, requestId) {
+    const env = {
+        error: {
+            code,
+            message,
+            retryable: false,
+            ...(recoveryHint ? { recovery_hint: recoveryHint } : {}),
+            ...(requestId ? { request_id: requestId } : {}),
+        },
+    };
+    if (isTtyHuman) {
+        process.stderr.write(renderError(env) + "\n");
+    }
+    else {
+        process.stderr.write(JSON.stringify(env) + "\n");
+    }
+    process.exit(exitCode);
+}

package/dist/verbs/_spec.js

@@ -0,0 +1,15 @@
+/**
+ * VerbSpec —— curated verb 的源声明，CLI 与 MCP 两条入口共享。
+ *
+ * - CLI (commander): build*Command() 内部把 spec.handler 接到 commander.action
+ *   外加 executeVerb (process.exit / stderr / 错误 envelope) 包装。
+ * - MCP: tools/mcp.ts 启动时枚举所有 spec，把 inputSchema 直接喂 SDK
+ *   registerTool，handler 包成 MCP tool callback。
+ *
+ * 单源声明保证两个入口的 verb 名称 / 参数语义 / 输出形态完全同步。
+ *
+ * inputSchema 用 Zod raw shape (Record<string, ZodType>) —— MCP SDK 原生
+ * 接受；CLI 端不重复用它做校验 (commander Option + 我们 verb 内部的
+ * clamp/parse 已足够)。
+ */
+export {};

package/dist/verbs/bars_batch.js

@@ -0,0 +1,66 @@
+/**
+ * `echopai bars-batch` + MCP tool `bars_batch`.
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+const CODE_RE = /^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/;
+export const barsBatchSpec = {
+    name: "bars_batch",
+    description: "Batch K-line for multiple A-share securities in one round-trip. Daily: ≤100 codes × ≤1yr; minute: ≤20 codes × ≤7d. Returns partial-success envelope {items, errors}.",
+    inputSchema: {
+        codes: z
+            .array(z.string().regex(CODE_RE))
+            .min(1)
+            .max(100)
+            .describe("Canonical codes (daily ≤100; minute ≤20)"),
+        from: z.string().regex(DATE_RE).describe("Inclusive start date YYYY-MM-DD"),
+        to: z.string().regex(DATE_RE).describe("Inclusive end date YYYY-MM-DD"),
+        minute: z
+            .boolean()
+            .optional()
+            .describe("Minute-level bars instead of daily (tighter caps apply)"),
+    },
+    handler: async (args, ctx) => {
+        const isMinute = Boolean(args.minute);
+        const cap = isMinute ? 20 : 100;
+        const codes = args.codes;
+        if (codes.length > cap) {
+            throw new Error(`codes count ${codes.length} exceeds cap ${cap} for ${isMinute ? "minute" : "daily"} bars_batch`);
+        }
+        const cliKey = isMinute ? "bars.minute-batch" : "bars.daily-batch";
+        const op = OPERATIONS[cliKey];
+        if (!op)
+            throw new Error(`${cliKey} op missing from codegen`);
+        return callOp(op, { codes, from: args.from, to: args.to }, ctx);
+    },
+    backingOps: ["bars.daily-batch", "bars.minute-batch"],
+};
+export function buildBarsBatchCommand() {
+    // CLI alias keeps the hyphenated form. MCP tool name uses underscore (MCP
+    // convention; underscores parse cleaner across hosts).
+    const cmd = new Command("bars-batch").description(barsBatchSpec.description);
+    cmd.addOption(new Option("--codes <csv>", "Canonical codes, comma-separated")
+        .makeOptionMandatory(true));
+    cmd.addOption(new Option("--from <date>", "Inclusive start YYYY-MM-DD").makeOptionMandatory(true));
+    cmd.addOption(new Option("--to <date>", "Inclusive end YYYY-MM-DD").makeOptionMandatory(true));
+    cmd.addOption(new Option("--minute", "Minute-level bars instead of daily"));
+    cmd.action(async (opts) => {
+        const codes = opts.codes.split(",").map((s) => s.trim()).filter(Boolean);
+        const isMinute = Boolean(opts.minute);
+        const cap = isMinute ? 20 : 100;
+        if (codes.length === 0 || codes.length > cap) {
+            emitVerbError("invalid_args", `codes count ${codes.length} out of range; expected 1-${cap} for ${isMinute ? "minute" : "daily"} bars-batch`, isMinute
+                ? "Daily mode (default) allows up to 100 codes; drop --minute or chunk the request."
+                : "Chunk the request into batches of ≤100 codes.", 1);
+        }
+        const args = { codes, from: opts.from, to: opts.to };
+        if (opts.minute)
+            args.minute = true;
+        await executeVerb(async (ctx) => barsBatchSpec.handler(args, ctx));
+    });
+    return cmd;
+}

package/dist/verbs/chart.js

@@ -0,0 +1,110 @@
+/**
+ * `echopai chart` + MCP tool `chart`.
+ */
+import { Command, Option } from "commander";
+import { z } from "zod";
+import { OPERATIONS } from "../_generated/operations.js";
+import { executeVerb, emitVerbError } from "../runtime/verb_cmd.js";
+import { callOp } from "../runtime/verb_runner.js";
+const DATE_RE = /^\d{4}-\d{2}-\d{2}$/;
+export const chartSpec = {
+    name: "chart",
+    description: "Single-security K-line (daily by default; set minute=true for intraday with a single date). For multi-code use `bars_batch` instead.",
+    inputSchema: {
+        code: z
+            .string()
+            .regex(/^(SSE|SZSE|BSE|SH|SZ|BJ):[0-9]{6}$/)
+            .describe("Single canonical code (e.g. SSE:600519)"),
+        days: z
+            .number()
+            .int()
+            .min(1)
+            .max(365)
+            .default(30)
+            .describe("Daily lookback (ignored when from/to or minute mode are set)"),
+        from: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("YYYY-MM-DD inclusive start (daily mode; overrides days)"),
+        to: z
+            .string()
+            .regex(DATE_RE)
+            .optional()
+            .describe("YYYY-MM-DD inclusive end (daily mode; overrides days)"),
+        minute: z.boolean().optional().describe("Switch to minute-level bars (requires date)"),
+        date: z.string().regex(DATE_RE).optional().describe("Single trade date YYYY-MM-DD (minute mode)"),
+    },
+    handler: async (args, ctx) => {
+        if (args.minute) {
+            if (!args.date) {
+                throw new Error("minute=true requires date (YYYY-MM-DD)");
+            }
+            const op = OPERATIONS["bars.minute"];
+            if (!op)
+                throw new Error("bars.minute op missing");
+            // bars.minute expects a single `date` (YYYY-MM-DD), not from/to —
+            // see stockpulse-rs MinuteBarsQuery + OpenAPI 2026-05-12 correction.
+            return callOp(op, { code: args.code, date: args.date }, ctx);
+        }
+        const op = OPERATIONS["bars.daily"];
+        if (!op)
+            throw new Error("bars.daily op missing");
+        const callArgs = { code: args.code };
+        if (args.from && args.to) {
+            callArgs.from = args.from;
+            callArgs.to = args.to;
+        }
+        else {
+            // bars.daily requires from/to (additionalProperties:false; no `days`).
+            // Derive a from/to window from --days client-side. Includes today;
+            // server skips non-trading days automatically.
+            const days = Math.max(1, Number(args.days ?? 30));
+            const to = new Date();
+            const from = new Date(to.getTime() - (days - 1) * 24 * 3600 * 1000);
+            const fmt = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+            callArgs.from = fmt(from);
+            callArgs.to = fmt(to);
+        }
+        return callOp(op, callArgs, ctx);
+    },
+    backingOps: ["bars.daily", "bars.minute"],
+};
+function clamp(raw, min, max, fallback) {
+    const n = Math.floor(Number(raw));
+    if (!Number.isFinite(n))
+        return fallback;
+    if (n < min)
+        return min;
+    if (n > max)
+        return max;
+    return n;
+}
+export function buildChartCommand() {
+    const cmd = new Command(chartSpec.name).description(chartSpec.description);
+    cmd.addOption(new Option("--code <canonical_code>", "Single canonical code").makeOptionMandatory(true));
+    cmd.addOption(new Option("--days <n>", "Daily lookback (1-365, default 30)").default("30"));
+    cmd.addOption(new Option("--from <date>", "Inclusive start date YYYY-MM-DD (overrides --days)"));
+    cmd.addOption(new Option("--to <date>", "Inclusive end date YYYY-MM-DD (overrides --days)"));
+    cmd.addOption(new Option("--minute", "Switch to minute-level bars (requires --date)"));
+    cmd.addOption(new Option("--date <date>", "Single trade date YYYY-MM-DD (minute mode)"));
+    cmd.action(async (opts) => {
+        if (opts.minute && !opts.date) {
+            emitVerbError("invalid_args", "--minute requires --date YYYY-MM-DD (single trade date)", "Example: echopai chart --minute --code SSE:600519 --date 2026-05-09", 1);
+        }
+        const args = {
+            code: opts.code,
+            days: clamp(opts.days, 1, 365, 30),
+        };
+        if (opts.from)
+            args.from = opts.from;
+        if (opts.to)
+            args.to = opts.to;
+        if (opts.minute)
+            args.minute = true;
+        if (opts.date)
+            args.date = opts.date;
+        await executeVerb(async (ctx) => chartSpec.handler(args, ctx));
+    });
+    return cmd;
+}