echopai 2.0.0

package/dist/bin.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * EchoPai CLI v1 entry.
+ *
+ * Layered:
+ *   bin.ts                — entry, build commander tree (≤50 lines logic)
+ *   _generated/commands.ts — spec-derived command tree (DO NOT EDIT)
+ *   runtime/*             — invoker / auth / paginator / format / errors
+ *   tools/*               — hand-curated UX (login / status / config / api / schema / completion)
+ *
+ * Persona detection:
+ *   - TTY + !CI → human mode (table default, color, spinner)
+ *   - else → AI/script mode (NDJSON / JSON, no color, no spinner)
+ *
+ * See docs/PLAN_CLI_V2_REWRITE.md for design details.
+ */
+import { Command, Option } from "commander";
+import { buildCommandTree } from "./_generated/commands.js";
+import { invoke } from "./runtime/invoker.js";
+import { buildApiCommand } from "./tools/api.js";
+import { buildMcpCommand } from "./tools/mcp.js";
+import { buildRawCallCommand } from "./tools/raw.js";
+import { buildBarsBatchCommand, buildChartCommand, buildDigestCommand, buildHotCommand, buildLookupCommand, buildNewsCommand, buildQuoteCommand, buildResearchCommand, buildScanCommand, buildSentimentCommand, buildViewsCommand, } from "./verbs/index.js";
+import { buildCompletionCommand } from "./tools/completion.js";
+import { buildConfigCommand } from "./tools/config.js";
+import { buildLoginCommand, buildLogoutCommand, buildStatusCommand } from "./tools/login.js";
+import { buildDoctorCommand } from "./tools/doctor.js";
+import { buildSchemaCommand } from "./tools/schema.js";
+import { buildTraceCommand } from "./tools/trace.js";
+import { buildWhoamiCommand } from "./tools/whoami.js";
+import { CLI_VERSION } from "./version.js";
+const program = new Command();
+program
+    .name("echopai")
+    .description("EchoPai CLI v1 — partner-grade access to stock-market data, news, sentiment,\n" +
+    "views, signals, backtest.\n\n" +
+    "AI-First: JSON envelope on stdout, JSON errors on stderr, three-state exit\n" +
+    "codes (0 success / 1 user error / 2 service error). Set ECHOPAI_KEY env\n" +
+    "var or run `echopai login`.")
+    .version(CLI_VERSION, "-V, --version")
+    // 注意（v1.0.1 hotfix）：不再声明全局 --key / --profile —— 它们跟 `echopai login
+    // --key` / `echopai status --profile` 等子命令的同名 option 冲突（commander 会
+    // 把值吞给最近的解析器导致子命令看不到 → required / value missing）。
+    // 凭据覆盖改用 ECHOPAI_KEY / ECHOPAI_PROFILE env var；spec-driven 子命令的
+    // dispatch 自动从 env 读取 cred（runtime/auth.ts）。
+    .addOption(new Option("--debug", "Print HTTP wire trace to stderr (Bearer redacted)"))
+    .addOption(new Option("--raw", "Pass through raw response body (skip envelope wrap)"))
+    .addOption(new Option("--jq <jmespath>", "Transform data with JMESPath expression (renamed from --query to avoid clash with news.search etc.)"))
+    .addOption(new Option("--fields <a,b,c>", "Keep only listed top-level fields per item"))
+    .addOption(new Option("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)"))
+    .addOption(new Option("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)"))
+    .addOption(new Option("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support"))
+    .addHelpText("after", "\nAuthentication: ECHOPAI_KEY=<eps_live_<lookup>_<secret>> echopai <cmd>\n" +
+    "Raw mirror:     echopai raw <noun> <verb>   # all OpenAPI ops, e.g. raw news search\n" +
+    "Curated verbs:  echopai <verb>              # task-level entry (Phase 3.6+)\n" +
+    "Capability:     echopai whoami | echopai doctor\n" +
+    "Schema dump:    echopai schema export       # AI agents pipe this for command surface\n" +
+    "Profile:        echopai config profile add prod --base-url https://api.echopai.com\n");
+const dispatch = async (op, args) => {
+    // commander stores global flags on the *root* command's opts in camelCase
+    // (e.g. --max-bytes → maxBytes). Subcommand-level opts go through
+    // camelToSnake inside attachOperation; mirror that here so runtime sees
+    // consistent snake_case (max_bytes / max_pages / max_items …).
+    const globals = program.opts();
+    const globalsSnake = {};
+    for (const [k, v] of Object.entries(globals)) {
+        globalsSnake[k.replace(/[A-Z]/g, (m) => "_" + m.toLowerCase())] = v;
+    }
+    await invoke(op, { ...globalsSnake, ...args }, { cliVersion: CLI_VERSION });
+};
+/**
+ * Replace commander's plain-text "error: ..." stderr output with a JSON
+ * envelope so AI parsers see only valid JSON on stderr.
+ */
+function applyAiFirstHooks(cmd) {
+    cmd.configureOutput({ writeErr: () => { } });
+    cmd.exitOverride((err) => {
+        // Help / version display exits 0 quietly.
+        if (err.code === "commander.helpDisplayed" ||
+            err.code === "commander.help" ||
+            err.code === "commander.version") {
+            process.exit(0);
+        }
+        // commander.unknownCommand / .missingArgument / .missingMandatoryOptionValue
+        // / .invalidArgument / .conflictingOption etc.
+        process.stderr.write(JSON.stringify({
+            error: {
+                code: "invalid_args",
+                message: err.message,
+                recovery_hint: "Run with `--help` for usage.",
+            },
+        }) + "\n");
+        process.exit(1);
+    });
+    for (const sub of cmd.commands)
+        applyAiFirstHooks(sub);
+}
+// Spec-driven raw mirror (Phase 3.5): all OpenAPI operations under `raw`
+// namespace. The top level is reserved for curated agent verbs.
+//
+// Phase 3.7+ — `raw` is now the only place to find spec-driven operations.
+// Top-level previously held spec mirrors but starting this PR the curated
+// verbs (`views` / `news` / `quote` / `sentiment` / `research` / `hot` /
+// `lookup` / `digest` etc.) take precedence at the top level. Use `echopai raw <noun>
+// <verb>` for the raw mirror (e.g. `raw views feed`, `raw quote`, etc.).
+const rawCmd = new Command("raw").description("Raw 1:1 mirror of OpenAPI operations (escape hatch for power users / scripts)");
+buildCommandTree(rawCmd, dispatch);
+rawCmd.addCommand(buildRawCallCommand());
+program.addCommand(rawCmd);
+// Top-level spec commands kept ONLY for nouns that don't conflict with a
+// curated verb. Curated-verb nouns (views/news/quote/sentiment/research/hot
+// /lookup/digest) are NOT generated at top level — they go below in their canonical
+// curated form. Use `echopai raw <noun>` for the spec mirror.
+const CURATED_NOUNS = new Set([
+    "views",
+    "news",
+    "quote",
+    "sentiment",
+    "research",
+    "hot",
+    "lookup",
+    "digest",
+]);
+const topLevelSpecDispatch = async (op, args) => {
+    await dispatch(op, args);
+};
+const topLevelStub = new Command();
+buildCommandTree(topLevelStub, topLevelSpecDispatch);
+for (const sub of topLevelStub.commands) {
+    if (CURATED_NOUNS.has(sub.name()))
+        continue;
+    program.addCommand(sub);
+}
+// Curated agent verbs (Phase 3.6+): task-level entries that wrap one or
+// more raw operations + map output for AI agents. Listed before tools so
+// `--help` shows them first.
+// Product priority (see feedback_views_over_news.md): views > research > news
+program.addCommand(buildLookupCommand());
+program.addCommand(buildDigestCommand()); // one-shot fan-out (Phase 5.1)
+program.addCommand(buildQuoteCommand());
+program.addCommand(buildViewsCommand()); // PRIMARY research source
+program.addCommand(buildResearchCommand()); // views quality signal layer
+program.addCommand(buildNewsCommand()); // supplementary breadth
+program.addCommand(buildSentimentCommand());
+program.addCommand(buildHotCommand());
+program.addCommand(buildChartCommand()); // single-code K-line
+program.addCommand(buildBarsBatchCommand()); // multi-code batch K-line (PR 3.2/3.3 server)
+program.addCommand(buildScanCommand()); // full-market scan (PR 3.4 server)
+// hand-curated tools
+program.addCommand(buildLoginCommand());
+program.addCommand(buildLogoutCommand());
+program.addCommand(buildStatusCommand());
+program.addCommand(buildConfigCommand());
+program.addCommand(buildApiCommand()); // deprecated alias of `raw call`; remove next major
+program.addCommand(buildSchemaCommand());
+program.addCommand(buildTraceCommand());
+program.addCommand(buildWhoamiCommand());
+program.addCommand(buildDoctorCommand());
+program.addCommand(buildMcpCommand());
+program.addCommand(buildCompletionCommand());
+applyAiFirstHooks(program);
+program.parseAsync(process.argv).catch((e) => {
+    process.stderr.write(JSON.stringify({
+        error: {
+            code: "internal_error",
+            message: e instanceof Error ? e.message : String(e),
+        },
+    }) + "\n");
+    process.exit(2);
+});

package/dist/runtime/auth.js

@@ -0,0 +1,95 @@
+/**
+ * Credential / profile resolution.
+ *
+ * Precedence（高 → 低）：
+ *   1. --key <eps_live_X_Y>   命令行
+ *   2. ECHOPAI_KEY env
+ *   3. ~/.config/echopai/config.toml 默认 profile
+ *   4. ~/.config/echopai/config.toml 指定 profile（--profile <name> 或 ECHOPAI_PROFILE）
+ *   5. 报错 auth_missing
+ *
+ * 配置文件格式（TOML）：
+ *
+ *   default_profile = "prod"
+ *
+ *   [profiles.prod]
+ *   key = "eps_live_xxx_yyy"
+ *   base_url = "https://api.echopai.com"
+ *
+ *   [profiles.staging]
+ *   key = "eps_live_aaa_bbb"
+ *   base_url = "https://staging.echopai.com"
+ *
+ * XDG paths：
+ *   Linux/macOS: $XDG_CONFIG_HOME/echopai/config.toml or ~/.config/echopai/config.toml
+ *   Windows:     %APPDATA%/echopai/config.toml
+ */
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+export class AuthMissingError extends Error {
+    recovery_hint;
+    constructor(message, recovery_hint) {
+        super(message);
+        this.recovery_hint = recovery_hint;
+        this.name = "AuthMissingError";
+    }
+}
+export function configDir() {
+    if (process.platform === "win32") {
+        const appdata = process.env.APPDATA || path.join(os.homedir(), "AppData", "Roaming");
+        return path.join(appdata, "echopai");
+    }
+    const xdg = process.env.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+    return path.join(xdg, "echopai");
+}
+export function configPath() {
+    return path.join(configDir(), "config.toml");
+}
+export function readConfigFile() {
+    const p = configPath();
+    if (!fs.existsSync(p))
+        return {};
+    try {
+        const raw = fs.readFileSync(p, "utf-8");
+        return parseToml(raw);
+    }
+    catch {
+        return {};
+    }
+}
+export function writeConfigFile(cfg) {
+    const dir = configDir();
+    fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+    const data = stringifyToml(cfg);
+    fs.writeFileSync(configPath(), data, { mode: 0o600 });
+}
+export function resolveCredentials(opts = {}) {
+    const DEFAULT_BASE_URL = "https://api.echopai.com";
+    // 1. --key arg
+    if (opts.key) {
+        return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+    }
+    // 2. env var
+    const envKey = process.env.ECHOPAI_KEY;
+    if (envKey) {
+        return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+    }
+    // 3+4. config file
+    const cfg = readConfigFile();
+    const profileName = opts.profile || process.env.ECHOPAI_PROFILE || cfg.default_profile;
+    if (profileName && cfg.profiles && cfg.profiles[profileName]) {
+        const p = cfg.profiles[profileName];
+        if (p.key) {
+            return {
+                key: p.key,
+                baseUrl: p.base_url || process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL,
+                profile: profileName,
+            };
+        }
+    }
+    throw new AuthMissingError(profileName
+        ? `No key configured for profile '${profileName}'.`
+        : "No credential found.", "Set ECHOPAI_KEY env var, or run `echopai login --key eps_live_<lookup>_<secret>`.");
+}

package/dist/runtime/envelope.js

@@ -0,0 +1,52 @@
+/**
+ * Standard CLI success envelope.
+ *
+ * 服务端响应有时含 `{data, meta}`（pagination cursors / has_more / total 等），
+ * 有时只返 data。本模块统一对外输出：
+ *
+ *   { data, meta: { ...serverMeta, request_id, endpoint, method, cli_version,
+ *                   api_version?, duration_ms, truncated } }
+ *
+ * CLI 字段永远覆盖 server 同名字段——CLI 是观察者，知道真相（例如 server 没 echo
+ * X-Request-Id 时，CLI 端的 uuid 才是 canonical）。
+ *
+ * truncated 默认 false；PR 1.4 引入 --max-bytes / --fields 等截断逻辑后，
+ * 触发时由 invoker / paginator 写为 true 并附 truncation_reason。
+ *
+ * 与 http.ts 关系：http.ts 出站（request headers），envelope.ts 入站（response meta）。
+ */
+/**
+ * Merge server-provided meta with CLI-known truth. CLI fields win on collision.
+ */
+export function mergeMeta(serverMeta, cli) {
+    const merged = {
+        ...(serverMeta ?? {}),
+        request_id: cli.requestId,
+        endpoint: cli.endpoint,
+        method: cli.method,
+        cli_version: cli.cliVersion,
+        duration_ms: cli.durationMs,
+        truncated: false,
+    };
+    if (cli.apiVersion)
+        merged.api_version = cli.apiVersion;
+    return merged;
+}
+/**
+ * Build a complete response envelope from a raw response body.
+ *
+ * - 若 body 是 `{data, meta}` 形态：data 透传，meta 合并 CLI 字段。
+ * - 否则：整 body 当 data，meta 全部由 CLI 提供。
+ * - body 为 null/字符串/数组时也走"整 body 当 data"分支。
+ */
+export function buildResponseEnvelope(body, cli) {
+    if (typeof body === "object" &&
+        body !== null &&
+        !Array.isArray(body) &&
+        "data" in body &&
+        "meta" in body) {
+        const e = body;
+        return { data: e.data, meta: mergeMeta(e.meta, cli) };
+    }
+    return { data: body, meta: mergeMeta(undefined, cli) };
+}

package/dist/runtime/errors.js

@@ -0,0 +1,186 @@
+/**
+ * 错误层：解析 API envelope，分级 exit code，输出 stderr JSON。
+ *
+ * Canonical envelope (server + CLI uniform):
+ *   { "error": {
+ *       "code": "<machine_code>",
+ *       "message": "<human>",
+ *       "retryable": <bool>,
+ *       "recovery_hint": "<actionable>",
+ *       "request_id": "<uuid>"
+ *   } }
+ *
+ * `code` must be a member of KNOWN_ERROR_CODES (see docs/api-contract/error-codes.md).
+ * Server may emit codes outside this set; CLI accepts them but logs a warning under
+ * --debug. `recovery_hint` falls back to DEFAULT_RECOVERY_HINTS when server omits it.
+ *
+ * Exit code 三态：
+ *   0 success
+ *   1 user error      (4xx — auth_missing / scope_insufficient / kind_not_allowed /
+ *                      invalid_args / validation_failed / not_found / confirmation_required ...)
+ *   2 service error   (5xx, 429 retryable, network failure, internal_error, stream_error)
+ */
+export const KNOWN_ERROR_CODES = [
+    // auth / identity
+    "auth_missing",
+    "auth_invalid",
+    "auth_expired",
+    // permission / scope
+    "scope_insufficient",
+    "kind_not_allowed",
+    "channel_not_allowed",
+    // input / validation
+    "invalid_args",
+    "validation_failed",
+    "not_found",
+    "idempotency_conflict",
+    // write / confirmation
+    "confirmation_required",
+    "dry_run_unsupported",
+    "unsafe_command",
+    // rate / quota
+    "rate_limited",
+    "quota_exhausted",
+    "agent_budget_exhausted",
+    // transport / infrastructure
+    "network_error",
+    "timeout",
+    "stream_error",
+    "upstream_unavailable",
+    // server / internal
+    "internal_error",
+    "http_error",
+];
+const KNOWN_CODE_SET = new Set(KNOWN_ERROR_CODES);
+export function isKnownErrorCode(code) {
+    return KNOWN_CODE_SET.has(code);
+}
+/**
+ * Codes that are safe to retry with the same input. Server may also set
+ * `retryable` per-response; if it does, server wins. This map is the
+ * fallback when server omits `retryable`.
+ */
+const RETRYABLE_CODES = new Set([
+    "rate_limited",
+    "network_error",
+    "timeout",
+    "stream_error",
+    "upstream_unavailable",
+    "internal_error",
+]);
+export function isRetryableByCode(code) {
+    return RETRYABLE_CODES.has(code);
+}
+/**
+ * Default recovery hints when server omits `recovery_hint`. Keep in sync with
+ * docs/api-contract/error-codes.md.
+ */
+export const DEFAULT_RECOVERY_HINTS = {
+    auth_missing: "Run `echopai login`, or set `ECHOPAI_KEY=<token>`.",
+    auth_invalid: "Token rejected. Re-issue via `echopai login` or check token revocation.",
+    auth_expired: "Token expired. Re-issue via `echopai login`.",
+    scope_insufficient: "Run `echopai whoami` to see available scopes; request the missing scope from your app admin.",
+    kind_not_allowed: "Endpoint not available for this token kind. See `echopai whoami` for your kind.",
+    channel_not_allowed: "This CLI/MCP channel is not authorized for the current token. Check `allowed_clients` on your app config.",
+    invalid_args: "Check parameter types/format. Run with `--help` for the schema.",
+    validation_failed: "Server rejected the request body. Check the `message` for the offending field.",
+    not_found: "Resource does not exist or is not visible to this token.",
+    idempotency_conflict: "Same Idempotency-Key seen with a different body. Use a new key or replay the original request exactly.",
+    confirmation_required: "Non-TTY write requires `--yes`. Re-run with `--yes` after verifying the operation.",
+    dry_run_unsupported: "This endpoint does not support `--dry-run`. Run without `--dry-run` (and `--yes` if it's a write).",
+    unsafe_command: "This command is gated. See `docs/PLAN_CLI_V2_AGENT_SURFACE.md` §6 for safety model.",
+    rate_limited: "Slow down. Honor `Retry-After` header if present; back off and retry.",
+    quota_exhausted: "Monthly quota for this endpoint class exceeded. Upgrade plan or wait until reset.",
+    agent_budget_exhausted: "Agent budget exhausted. Start a new session via `agent session-start` or request a budget bump.",
+    network_error: "Verify network reachability and `base_url`. Use `--debug` for full trace.",
+    timeout: "Server took too long. Retry; if persistent, check `echopai doctor`.",
+    stream_error: "WebSocket closed abnormally. Use `--debug` to see the close code/reason; `--reconnect` to auto-retry.",
+    upstream_unavailable: "Upstream service is temporarily unavailable. Retry with backoff.",
+    internal_error: "Server-side error. Retry; include the `request_id` when reporting.",
+    http_error: "Server did not return a typed error envelope. See `message` and `request_id`.",
+};
+/**
+ * Resolve effective recovery hint:
+ *   1. Explicit hint (server-provided or CLI-passed)
+ *   2. DEFAULT_RECOVERY_HINTS[code] fallback
+ *   3. undefined if code unknown and no hint
+ */
+export function resolveRecoveryHint(code, explicit) {
+    if (explicit && explicit.length > 0)
+        return explicit;
+    if (isKnownErrorCode(code))
+        return DEFAULT_RECOVERY_HINTS[code];
+    return undefined;
+}
+export class CallApiError extends Error {
+    code;
+    retryable;
+    recovery_hint;
+    httpStatus;
+    requestId;
+    raw;
+    constructor(args) {
+        super(args.message);
+        this.name = "CallApiError";
+        this.code = args.code;
+        this.retryable = args.retryable ?? isRetryableByCode(args.code);
+        this.recovery_hint = resolveRecoveryHint(args.code, args.recovery_hint);
+        this.httpStatus = args.httpStatus;
+        this.requestId = args.requestId;
+        this.raw = args.raw;
+    }
+}
+/**
+ * Parse possibly-envelope JSON body. Returns CallApiError if it looks like a
+ * standard EchoPai error, else null.
+ */
+export function tryParseErrorEnvelope(body, httpStatus, requestId) {
+    if (typeof body !== "object" || body === null)
+        return null;
+    const obj = body;
+    const direct = errorFromObject(obj.error, body, httpStatus, requestId);
+    if (direct)
+        return direct;
+    // FastAPI sometimes wraps the service envelope as {detail: {error: {...}}}.
+    if (typeof obj.detail === "object" && obj.detail !== null) {
+        const detail = obj.detail;
+        const nested = errorFromObject(detail.error, body, httpStatus, requestId);
+        if (nested)
+            return nested;
+    }
+    // FastAPI fallback {detail: "..."}
+    if (typeof obj.detail === "string") {
+        return new CallApiError({
+            code: httpStatus === 401 ? "auth_missing" : "http_error",
+            message: obj.detail,
+            httpStatus,
+            requestId,
+            raw: body,
+        });
+    }
+    return null;
+}
+function errorFromObject(value, raw, httpStatus, requestId) {
+    if (typeof value !== "object" || value === null)
+        return null;
+    const env = value;
+    if (typeof env.code !== "string" || typeof env.message !== "string") {
+        return null;
+    }
+    return new CallApiError({
+        code: env.code,
+        message: env.message,
+        ...(typeof env.retryable === "boolean" ? { retryable: env.retryable } : {}),
+        ...(typeof env.recovery_hint === "string"
+            ? { recovery_hint: env.recovery_hint }
+            : {}),
+        httpStatus,
+        requestId,
+        raw,
+    });
+}
+export function exitCodeForStatus(httpStatus) {
+    if (httpStatus >= 400 && httpStatus < 500)
+        return 1;
+    return 2;
+}

package/dist/runtime/filters.js

@@ -0,0 +1,153 @@
+/**
+ * Output filter pipeline applied between response envelope and render.
+ *
+ * Pipeline order (each step optional, --flag triggers):
+ *   1. --query <jmespath>     data = jmespath.search(data, expr)
+ *   2. --fields a,b,c          keep only these keys per item/object
+ *   3. --max-bytes N           binary-search items truncation; meta.truncated=true
+ *
+ * 设计原则：
+ * - JMESPath 错误算 user error（exit 1），调用方负责捕获并 writeError("invalid_args")。
+ * - --fields 对 array / {items:[]} / 普通 object 都做 best-effort projection。
+ * - --max-bytes 是 serialized envelope 的字节数；items 数组形态可智能裁剪，
+ *   其他形态退化为整 data 替换为 omitted 占位符。
+ * - 截断时 meta.truncated 翻为 true，加 truncation_reason / truncated_items_dropped。
+ */
+import jmespathPkg from "jmespath";
+const jmes = jmespathPkg;
+const jmesSearch = jmes.search ?? (jmes.default ? jmes.default.search : (() => null));
+export class FilterError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "FilterError";
+    }
+}
+export function applyFilters(envelope, opts) {
+    let data = envelope.data;
+    let meta = { ...envelope.meta };
+    if (opts.query && opts.query.length > 0) {
+        try {
+            data = jmesSearch(data, opts.query);
+        }
+        catch (e) {
+            throw new FilterError(`Invalid --query expression: ${e instanceof Error ? e.message : String(e)}`);
+        }
+    }
+    if (opts.fields && opts.fields.length > 0) {
+        data = pickFields(data, opts.fields);
+    }
+    if (opts.maxBytes !== undefined && opts.maxBytes > 0) {
+        return enforceMaxBytes({ data, meta }, opts.maxBytes);
+    }
+    return { data, meta };
+}
+/**
+ * Recursively project: array → map; {items:[...]} → recurse into items;
+ * plain object → pick listed keys; primitive → unchanged.
+ */
+export function pickFields(value, fields) {
+    if (Array.isArray(value)) {
+        return value.map((item) => pickFields(item, fields));
+    }
+    if (value !== null && typeof value === "object") {
+        const obj = value;
+        if (Array.isArray(obj.items)) {
+            return {
+                ...obj,
+                items: obj.items.map((it) => pickFields(it, fields)),
+            };
+        }
+        const out = {};
+        for (const f of fields) {
+            if (f in obj)
+                out[f] = obj[f];
+        }
+        return out;
+    }
+    return value;
+}
+function enforceMaxBytes(env, maxBytes) {
+    const initialSize = JSON.stringify(env).length;
+    if (initialSize <= maxBytes)
+        return env;
+    const data = env.data;
+    // Truncatable shape 1: object with {items: [...]} (envelope-style)
+    if (data !== null && typeof data === "object" && !Array.isArray(data)) {
+        const obj = data;
+        if (Array.isArray(obj.items)) {
+            const items = obj.items;
+            const total = items.length;
+            const buildEnv = (n) => ({
+                data: { ...obj, items: items.slice(0, n) },
+                meta: {
+                    ...env.meta,
+                    truncated: true,
+                    truncation_reason: "max_bytes",
+                    truncated_items_dropped: total - n,
+                },
+            });
+            const fit = binarySearchFit(buildEnv, total, maxBytes);
+            return buildEnv(fit);
+        }
+    }
+    // Truncatable shape 2: top-level array
+    if (Array.isArray(data)) {
+        const total = data.length;
+        const buildEnv = (n) => ({
+            data: data.slice(0, n),
+            meta: {
+                ...env.meta,
+                truncated: true,
+                truncation_reason: "max_bytes",
+                truncated_items_dropped: total - n,
+            },
+        });
+        const fit = binarySearchFit(buildEnv, total, maxBytes);
+        return buildEnv(fit);
+    }
+    // Non-truncatable: replace data with placeholder
+    return {
+        data: {
+            omitted: true,
+            reason: "response exceeded --max-bytes; data is not paginatable",
+        },
+        meta: {
+            ...env.meta,
+            truncated: true,
+            truncation_reason: "max_bytes",
+        },
+    };
+}
+function binarySearchFit(shape, total, maxBytes) {
+    // Find largest n in [0, total] where JSON.stringify(shape(n)).length <= maxBytes
+    let lo = 0;
+    let hi = total;
+    while (lo < hi) {
+        const mid = Math.floor((lo + hi + 1) / 2);
+        const size = JSON.stringify(shape(mid)).length;
+        if (size <= maxBytes)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return lo;
+}
+export function parseFieldsFlag(raw) {
+    if (typeof raw !== "string" || raw.length === 0)
+        return undefined;
+    const fields = raw
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    return fields.length > 0 ? fields : undefined;
+}
+export function parseMaxBytesFlag(raw) {
+    if (typeof raw === "number" && raw > 0)
+        return raw;
+    if (typeof raw === "string" && raw.length > 0) {
+        const n = Number(raw);
+        if (Number.isFinite(n) && n > 0)
+            return n;
+    }
+    return undefined;
+}