echopai 2.0.0

package/dist/tools/api.js

@@ -0,0 +1,81 @@
+/**
+ * `echopai api call <method> <path>` — DEPRECATED alias of `echopai raw call`.
+ *
+ * 保留一个 release 给老脚本，新代码请用 `echopai raw call`。
+ * 行为同 raw call，但在调用时往 stderr 打 deprecation 提示一行。
+ */
+import { Command } from "commander";
+import { fetch as undiciFetch, Headers } from "undici";
+import { resolveCredentials, AuthMissingError } from "../runtime/auth.js";
+import { CLI_VERSION } from "../version.js";
+export function buildApiCommand() {
+    const api = new Command("api").description("[DEPRECATED] Use `echopai raw call` instead — alias kept for one release");
+    api
+        .command("call <method> <path>")
+        .description("[DEPRECATED] Call <method> <path> — use `echopai raw call` instead")
+        .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")
+        .action(async (method, urlPath, opts) => {
+        process.stderr.write("[deprecated] `echopai api call` will be removed next major. Use `echopai raw call` instead.\n");
+        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;
+        }
+        const headers = new Headers({
+            Authorization: `Bearer ${creds.key}`,
+            "User-Agent": `echopai-cli/${CLI_VERSION}`,
+            Accept: "application/json",
+        });
+        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 api;
+}
+function die(code, message, exitCode, recovery_hint) {
+    const env = { error: { code, message } };
+    if (recovery_hint)
+        env.error.recovery_hint = recovery_hint;
+    process.stderr.write(JSON.stringify(env) + "\n");
+    process.exit(exitCode);
+}

package/dist/tools/completion.js

@@ -0,0 +1,116 @@
+/**
+ * `echopai completion <bash|zsh|fish>` 输出 shell completion 脚本。
+ *
+ * 不依赖 tabtab，自己生成（30 行 bash / 20 行 zsh / 15 行 fish）。
+ * 用 `echopai schema list` 实时拿命令列表。
+ *
+ *   bash:  echopai completion bash > ~/.local/share/bash-completion/completions/echopai
+ *   zsh:   echopai completion zsh  > ~/.zsh/completions/_echopai  (需要 fpath 含此目录)
+ *   fish:  echopai completion fish > ~/.config/fish/completions/echopai.fish
+ */
+import { Command } from "commander";
+import { listOperations } from "../_generated/operations.js";
+export function buildCompletionCommand() {
+    return new Command("completion")
+        .argument("<shell>", "bash | zsh | fish")
+        .description("Print shell completion script for echopai")
+        .action((shell) => {
+        const ops = listOperations();
+        // groups: map noun → set of verbs
+        const tree = new Map();
+        for (const op of ops) {
+            const parts = op.cliName.split(" ");
+            const noun = parts[0];
+            const verb = parts[1] || "";
+            if (!tree.has(noun))
+                tree.set(noun, new Set());
+            if (verb)
+                tree.get(noun).add(verb);
+        }
+        const nouns = [...tree.keys()].sort();
+        // hand-curated tools
+        const tools = ["login", "logout", "status", "config", "api", "schema", "completion"];
+        const allCmds = [...nouns, ...tools].sort();
+        let out = "";
+        if (shell === "bash") {
+            out = bashCompletion(allCmds, tree);
+        }
+        else if (shell === "zsh") {
+            out = zshCompletion(allCmds, tree);
+        }
+        else if (shell === "fish") {
+            out = fishCompletion(allCmds, tree);
+        }
+        else {
+            process.stderr.write(JSON.stringify({ error: { code: "invalid_args", message: `Unsupported shell '${shell}'`, recovery_hint: "Use bash | zsh | fish." } }) + "\n");
+            process.exit(1);
+        }
+        process.stdout.write(out);
+        process.exit(0);
+    });
+}
+function bashCompletion(cmds, tree) {
+    const subcaseLines = [...tree.entries()]
+        .map(([noun, verbs]) => `        ${noun}) COMPREPLY=( $(compgen -W "${[...verbs].sort().join(" ")}" -- "$cur") );;`)
+        .join("\n");
+    return `# echopai bash completion
+_echopai() {
+    local cur prev
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    if [ "$COMP_CWORD" = "1" ]; then
+        COMPREPLY=( $(compgen -W "${cmds.join(" ")}" -- "$cur") )
+        return
+    fi
+    case "\${COMP_WORDS[1]}" in
+${subcaseLines}
+        config) COMPREPLY=( $(compgen -W "show set profile" -- "$cur") );;
+        schema) COMPREPLY=( $(compgen -W "list get export" -- "$cur") );;
+    esac
+}
+complete -F _echopai echopai
+`;
+}
+function zshCompletion(cmds, tree) {
+    const subcases = [...tree.entries()]
+        .map(([noun, verbs]) => `      "${noun}") _values "${noun} verb" ${[...verbs].sort().map((v) => `"${v}"`).join(" ")} ;;`)
+        .join("\n");
+    return `#compdef echopai
+_echopai() {
+  local -a cmds
+  cmds=(${cmds.map((c) => `"${c}"`).join(" ")})
+  if (( CURRENT == 2 )); then
+    _values "echopai command" $cmds
+    return
+  fi
+  case "$words[2]" in
+${subcases}
+    config) _values "config sub" "show" "set" "profile" ;;
+    schema) _values "schema sub" "list" "get" "export" ;;
+  esac
+}
+_echopai "$@"
+`;
+}
+function fishCompletion(cmds, tree) {
+    const lines = [`# echopai fish completion`];
+    lines.push(`complete -c echopai -f`);
+    for (const c of cmds) {
+        lines.push(`complete -c echopai -n '__fish_use_subcommand' -a "${c}"`);
+    }
+    for (const [noun, verbs] of tree.entries()) {
+        for (const verb of [...verbs].sort()) {
+            lines.push(`complete -c echopai -n "__fish_seen_subcommand_from ${noun}" -a "${verb}"`);
+        }
+    }
+    // hand-curated
+    for (const [parent, sub] of [
+        ["config", ["show", "set", "profile"]],
+        ["schema", ["list", "get", "export"]],
+    ]) {
+        for (const v of sub) {
+            lines.push(`complete -c echopai -n "__fish_seen_subcommand_from ${parent}" -a "${v}"`);
+        }
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/tools/config.js

@@ -0,0 +1,123 @@
+/**
+ * `echopai config [...]`
+ *
+ *   echopai config show                         显示完整 config
+ *   echopai config set default_profile <name>   切默认 profile
+ *
+ *   echopai config profile add <name> --key <eps> [--base-url <url>]
+ *   echopai config profile rm  <name>
+ *   echopai config profile list
+ *   echopai config profile switch <name>        ≡ set default_profile
+ *
+ * 配置文件 ~/.config/echopai/config.toml（XDG）。文件 mode 0600。
+ */
+import { Command } from "commander";
+import { configPath, readConfigFile, writeConfigFile, } from "../runtime/auth.js";
+export function buildConfigCommand() {
+    const cmd = new Command("config").description("Manage CLI config (~/.config/echopai/config.toml)");
+    cmd
+        .command("show")
+        .description("Print current config (key 字段会脱敏成 eps_live_***_***)")
+        .action(() => {
+        const cfg = readConfigFile();
+        const masked = JSON.parse(JSON.stringify(cfg));
+        if (masked.profiles) {
+            for (const p of Object.values(masked.profiles)) {
+                if (p && typeof p === "object" && typeof p.key === "string") {
+                    p.key = redactKey(p.key);
+                }
+            }
+        }
+        process.stdout.write(JSON.stringify({ data: masked, meta: { path: configPath() } }, null, 2) + "\n");
+        process.exit(0);
+    });
+    cmd
+        .command("set <key> <value>")
+        .description("Set a top-level config key (currently only 'default_profile' is recognized)")
+        .action((key, value) => {
+        const cfg = readConfigFile();
+        if (key === "default_profile") {
+            cfg.default_profile = value;
+            writeConfigFile(cfg);
+            process.stdout.write(JSON.stringify({ data: { ok: true }, meta: { path: configPath() } }) + "\n");
+            process.exit(0);
+        }
+        writeError("invalid_args", `Unknown top-level config key '${key}'`, "Use one of: default_profile", 1);
+    });
+    const profile = cmd.command("profile").description("Manage credential profiles");
+    profile
+        .command("add <name>")
+        .description("Add or overwrite a profile")
+        .requiredOption("--key <eps_live_X_Y>", "Bearer credential")
+        .option("--base-url <url>", "API base URL", "https://api.echopai.com")
+        .action((name, opts) => {
+        const cfg = readConfigFile();
+        cfg.profiles = cfg.profiles ?? {};
+        cfg.profiles[name] = { key: opts.key, base_url: opts.baseUrl };
+        if (!cfg.default_profile)
+            cfg.default_profile = name;
+        writeConfigFile(cfg);
+        process.stdout.write(JSON.stringify({ data: { ok: true, name, default: cfg.default_profile === name }, meta: { path: configPath() } }) + "\n");
+        process.exit(0);
+    });
+    profile
+        .command("rm <name>")
+        .description("Remove a profile")
+        .action((name) => {
+        const cfg = readConfigFile();
+        if (!cfg.profiles?.[name]) {
+            writeError("profile_not_found", `Profile '${name}' not in config.`, undefined, 1);
+        }
+        delete cfg.profiles[name];
+        if (cfg.default_profile === name)
+            cfg.default_profile = undefined;
+        writeConfigFile(cfg);
+        process.stdout.write(JSON.stringify({ data: { ok: true, removed: name }, meta: { path: configPath() } }) + "\n");
+        process.exit(0);
+    });
+    profile
+        .command("list")
+        .description("List all profiles (keys redacted)")
+        .action(() => {
+        const cfg = readConfigFile();
+        const items = Object.entries(cfg.profiles ?? {}).map(([name, p]) => ({
+            name,
+            is_default: cfg.default_profile === name,
+            base_url: p?.base_url ?? "https://api.echopai.com",
+            key_redacted: p?.key ? redactKey(p.key) : null,
+        }));
+        process.stdout.write(JSON.stringify({ data: items, meta: { path: configPath() } }) + "\n");
+        process.exit(0);
+    });
+    profile
+        .command("switch <name>")
+        .description("Set default_profile")
+        .action((name) => {
+        const cfg = readConfigFile();
+        if (!cfg.profiles?.[name]) {
+            writeError("profile_not_found", `Profile '${name}' not in config.`, "Run `echopai config profile list` to see available.", 1);
+        }
+        cfg.default_profile = name;
+        writeConfigFile(cfg);
+        process.stdout.write(JSON.stringify({ data: { ok: true, default_profile: name } }) + "\n");
+        process.exit(0);
+    });
+    return cmd;
+}
+export function redactKey(key) {
+    // eps_live_<lookup>_<secret> → eps_live_<lookup>_*** (last 4 chars)
+    if (!key.startsWith("eps_live_"))
+        return "eps_***";
+    const parts = key.split("_");
+    if (parts.length < 4)
+        return "eps_live_***";
+    const last = parts.slice(3).join("_");
+    return `eps_live_${parts[2]}_***${last.slice(-4)}`;
+}
+function writeError(code, message, recovery_hint, exitCode) {
+    const env = { error: { code, message } };
+    if (recovery_hint)
+        env.error.recovery_hint = recovery_hint;
+    process.stderr.write(JSON.stringify(env) + "\n");
+    process.exit(exitCode);
+}

package/dist/tools/doctor.js

@@ -0,0 +1,183 @@
+/**
+ * `echopai doctor`
+ *
+ * 跑一组健康检查，每条 ok | warn | fail。所有 ok → exit 0；存在 fail → exit 1。
+ *
+ * 当前覆盖（Phase 2.4 起步集）：
+ *   credential       本地 token / profile 能解析
+ *   whoami           /v1/auth/whoami 可达且 200
+ *   operations       token 至少能调到一条 operation
+ *   api_version      CLI 期望 api_version 与 server 报告兼容
+ *
+ * 未来扩展：clock_skew (Date header) / ws_news (1-frame 探测) / scope_coverage
+ * (verb tier 满足度)。
+ */
+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, cyan, dim, green, red, yellow } from "../runtime/tty.js";
+import { clearWhoamiCache, getWhoami } from "../runtime/whoami_cache.js";
+import { deriveOperationAvailability } from "./whoami.js";
+import { CLI_VERSION } from "../version.js";
+const EXPECTED_API_VERSION = "2026-05"; // bump when CLI hard-depends on server change
+export async function runDoctor(ctx) {
+    const checks = [];
+    const resolveFn = ctx.resolveCredentialsImpl ?? resolveCredentials;
+    const whoamiFn = ctx.getWhoamiImpl ?? getWhoami;
+    // 1. credential resolution
+    let creds = null;
+    try {
+        creds = resolveFn({});
+        checks.push({ name: "credential", status: "ok" });
+    }
+    catch (e) {
+        if (e instanceof AuthMissingError) {
+            checks.push({
+                name: "credential",
+                status: "fail",
+                message: e.message,
+                recovery_hint: e.recovery_hint ?? "Run `echopai login` or set `ECHOPAI_KEY`.",
+            });
+        }
+        else {
+            checks.push({
+                name: "credential",
+                status: "fail",
+                message: e instanceof Error ? e.message : String(e),
+            });
+        }
+    }
+    if (!creds) {
+        // Subsequent checks all require a credential.
+        for (const name of ["whoami", "operations", "api_version"]) {
+            checks.push({
+                name,
+                status: "fail",
+                message: "skipped: credential unavailable",
+            });
+        }
+        return { ok: false, cli_version: ctx.cliVersion, checks };
+    }
+    // 2. whoami reachable
+    let whoami;
+    try {
+        whoami = await whoamiFn({ baseUrl: creds.baseUrl, bearer: creds.key, cliVersion: ctx.cliVersion }, { force: true });
+        checks.push({
+            name: "whoami",
+            status: "ok",
+            info: {
+                kind: whoami.kind,
+                scope_count: whoami.scopes.length,
+                ...(whoami.app_slug ? { app_slug: whoami.app_slug } : {}),
+            },
+        });
+    }
+    catch (e) {
+        const code = e instanceof CallApiError ? e.code : "internal_error";
+        const msg = e instanceof Error ? e.message : String(e);
+        const hint = e instanceof CallApiError ? e.recovery_hint : undefined;
+        checks.push({
+            name: "whoami",
+            status: "fail",
+            message: `${code}: ${msg}`,
+            ...(hint ? { recovery_hint: hint } : {}),
+        });
+        // Without whoami, downstream checks are meaningless.
+        for (const name of ["operations", "api_version"]) {
+            checks.push({
+                name,
+                status: "fail",
+                message: "skipped: whoami failed",
+            });
+        }
+        return { ok: false, cli_version: ctx.cliVersion, checks };
+    }
+    // 3. operations: at least one usable op
+    const { available, unavailable } = deriveOperationAvailability(new Set(whoami.scopes), listOperations());
+    if (available.length === 0) {
+        checks.push({
+            name: "operations",
+            status: "fail",
+            message: `Token scopes ${JSON.stringify(whoami.scopes)} grant access to 0 operations.`,
+            recovery_hint: "Request additional scopes (e.g. news:read / quote:l1) from your app admin.",
+            info: { available: 0, unavailable: unavailable.length },
+        });
+    }
+    else {
+        checks.push({
+            name: "operations",
+            status: "ok",
+            info: { available: available.length, unavailable: unavailable.length },
+        });
+    }
+    // 4. api_version compatibility
+    const serverVersion = whoami.api_version;
+    if (!serverVersion) {
+        checks.push({
+            name: "api_version",
+            status: "warn",
+            message: "Server did not report api_version (older deployment).",
+        });
+    }
+    else if (serverVersion !== EXPECTED_API_VERSION) {
+        checks.push({
+            name: "api_version",
+            status: "warn",
+            message: `CLI expects ${EXPECTED_API_VERSION}, server reports ${serverVersion}.`,
+            recovery_hint: "Usually safe (additive changes). Upgrade CLI if you hit unexpected errors.",
+            info: { cli_expected: EXPECTED_API_VERSION, server: serverVersion },
+        });
+    }
+    else {
+        checks.push({
+            name: "api_version",
+            status: "ok",
+            info: { version: serverVersion },
+        });
+    }
+    const ok = checks.every((c) => c.status !== "fail");
+    return { ok, cli_version: ctx.cliVersion, checks };
+}
+export function renderDoctorReport(report) {
+    if (!isTtyHuman)
+        return JSON.stringify({ data: report }) + "\n";
+    const lines = [];
+    lines.push(`${cyan("echopai doctor")} ${dim("cli " + report.cli_version)}`);
+    lines.push("");
+    for (const c of report.checks) {
+        const icon = c.status === "ok" ? green("✓") : c.status === "warn" ? yellow("!") : red("✗");
+        const head = `  ${icon} ${c.name}`;
+        if (c.message) {
+            lines.push(`${head}  ${dim("—")} ${c.message}`);
+        }
+        else if (c.info) {
+            lines.push(`${head}  ${dim(JSON.stringify(c.info))}`);
+        }
+        else {
+            lines.push(head);
+        }
+        if (c.recovery_hint)
+            lines.push(`     ${cyan("hint:")} ${c.recovery_hint}`);
+    }
+    lines.push("");
+    lines.push(report.ok ? green("All checks passed.") : red("One or more checks failed."));
+    return lines.join("\n") + "\n";
+}
+export function buildDoctorCommand() {
+    const cmd = new Command("doctor").description("Diagnose CLI environment, credential, server reachability, and capability");
+    cmd.addOption(new Option("--no-cache", "Bypass whoami cache for fresh check"));
+    cmd.action(async (opts) => {
+        if (opts.cache === false)
+            clearWhoamiCache();
+        const report = await runDoctor({ cliVersion: CLI_VERSION });
+        if (isTtyHuman) {
+            process.stdout.write(renderDoctorReport(report));
+        }
+        else {
+            process.stdout.write(JSON.stringify({ data: report }) + "\n");
+        }
+        process.exit(report.ok ? 0 : 1);
+    });
+    return cmd;
+}

package/dist/tools/login.js

@@ -0,0 +1,99 @@
+/**
+ * `echopai login --key <eps_live_X_Y> [--profile <name>] [--base-url <url>]`
+ * `echopai logout [--profile <name>]`
+ * `echopai status [--profile <name>]`
+ *
+ * login 把 key 写入 config profile（默认 'default'）。不在 login 时 round-trip
+ * 验证 key —— 第一次实际调用会自然报 auth_invalid。
+ *
+ * status 显示当前 profile / base_url / 脱敏 key prefix。
+ */
+import { Command } from "commander";
+import { configPath, readConfigFile, resolveCredentials, writeConfigFile, AuthMissingError, } from "../runtime/auth.js";
+import { redactKey } from "./config.js";
+export function buildLoginCommand() {
+    return new Command("login")
+        .description("Save Bearer credential to config profile")
+        .requiredOption("--key <eps_live_X_Y>", "Bearer credential issued by EchoPai admin console")
+        .option("--profile <name>", "Profile to save under", "default")
+        .option("--base-url <url>", "API base URL", "https://api.echopai.com")
+        .action((opts) => {
+        const cfg = readConfigFile();
+        cfg.profiles = cfg.profiles ?? {};
+        cfg.profiles[opts.profile] = { key: opts.key, base_url: opts.baseUrl };
+        if (!cfg.default_profile)
+            cfg.default_profile = opts.profile;
+        writeConfigFile(cfg);
+        process.stdout.write(JSON.stringify({
+            data: {
+                ok: true,
+                profile: opts.profile,
+                base_url: opts.baseUrl,
+                key_redacted: redactKey(opts.key),
+                default: cfg.default_profile === opts.profile,
+            },
+            meta: { path: configPath() },
+        }) + "\n");
+        process.exit(0);
+    });
+}
+export function buildLogoutCommand() {
+    return new Command("logout")
+        .description("Remove Bearer credential from config profile")
+        .option("--profile <name>", "Profile to clear (default = default_profile)")
+        .action((opts) => {
+        const cfg = readConfigFile();
+        const target = opts.profile || cfg.default_profile;
+        if (!target || !cfg.profiles?.[target]) {
+            process.stderr.write(JSON.stringify({
+                error: {
+                    code: "profile_not_found",
+                    message: `No profile '${target ?? "(none)"}' configured.`,
+                },
+            }) + "\n");
+            process.exit(1);
+        }
+        delete cfg.profiles[target];
+        if (cfg.default_profile === target)
+            cfg.default_profile = undefined;
+        writeConfigFile(cfg);
+        process.stdout.write(JSON.stringify({ data: { ok: true, removed_profile: target }, meta: { path: configPath() } }) + "\n");
+        process.exit(0);
+    });
+}
+export function buildStatusCommand() {
+    return new Command("status")
+        .description("Show current credential / profile / base URL (key redacted)")
+        .option("--profile <name>", "Profile to inspect")
+        .action((opts) => {
+        try {
+            const resolveOpts = {};
+            if (opts.profile)
+                resolveOpts.profile = opts.profile;
+            const c = resolveCredentials(resolveOpts);
+            process.stdout.write(JSON.stringify({
+                data: {
+                    source: process.env.ECHOPAI_KEY && !opts.profile
+                        ? "env"
+                        : c.profile
+                            ? "config"
+                            : "env",
+                    profile: c.profile,
+                    base_url: c.baseUrl,
+                    key_redacted: redactKey(c.key),
+                },
+                meta: { config_path: configPath() },
+            }) + "\n");
+            process.exit(0);
+        }
+        catch (e) {
+            if (e instanceof AuthMissingError) {
+                process.stderr.write(JSON.stringify({
+                    error: { code: "auth_missing", message: e.message, recovery_hint: e.recovery_hint },
+                }) + "\n");
+                process.exit(1);
+            }
+            throw e;
+        }
+    });
+}