echopai 2.8.1 → 2.9.0

package/dist/bin.js

@@ -2928,97 +2928,43 @@ async function downloadAndVerify(url, expectedSha) {
   }
 }
 
-// src/runtime/invoker.ts
-import AjvPkg from "ajv";
-import addFormatsPkg from "ajv-formats";
-
-// src/runtime/auth.ts
-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";
-
-class AuthMissingError extends Error {
-  recovery_hint;
-  constructor(message, recovery_hint) {
-    super(message);
-    this.recovery_hint = recovery_hint;
-    this.name = "AuthMissingError";
-  }
-}
-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");
-}
-function configPath() {
-  return path.join(configDir(), "config.toml");
-}
-function readConfigFile() {
-  const p = configPath();
-  if (!fs.existsSync(p))
-    return {};
-  try {
-    const raw = fs.readFileSync(p, "utf-8");
-    return parseToml(raw);
-  } catch {
-    return {};
-  }
-}
-function writeConfigFile(cfg) {
-  const dir = configDir();
-  fs.mkdirSync(dir, { recursive: true, mode: 448 });
-  const data = stringifyToml(cfg);
-  fs.writeFileSync(configPath(), data, { mode: 384 });
-}
-function resolveCredentials(opts = {}) {
-  const DEFAULT_BASE_URL = "https://api.echopai.com";
-  if (opts.key) {
-    return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-  }
-  const envKey = process.env.ECHOPAI_KEY;
-  if (envKey) {
-    return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
-  }
-  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>`.");
-}
-
-// src/runtime/envelope.ts
-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;
+// src/runtime/tty.ts
+var enable = (() => {
+  if (!process.stderr.isTTY)
+    return false;
+  if (process.env.CI)
+    return false;
+  if (process.env.NO_COLOR)
+    return false;
+  if (process.env.TERM === "dumb")
+    return false;
+  return true;
+})();
+var isTtyHuman = enable;
+var ESC = "\x1B[";
+function ansi(code, s) {
+  if (!enable)
+    return s;
+  return `${ESC}${code}m${s}${ESC}0m`;
 }
-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) };
+var red = (s) => ansi("31", s);
+var green = (s) => ansi("32", s);
+var yellow = (s) => ansi("33", s);
+var cyan = (s) => ansi("36", s);
+var dim = (s) => ansi("2", s);
+var bold = (s) => ansi("1", s);
+function renderError(env) {
+  if (!enable)
+    return JSON.stringify(env);
+  const e = env.error;
+  const label = `${red(bold("✗ " + e.code))}${e.retryable ? " " + dim("(retryable)") : ""}`;
+  const lines = [`${label} ${dim("—")} ${e.message}`];
+  if (e.recovery_hint)
+    lines.push(`  ${cyan("hint:")} ${e.recovery_hint}`);
+  if (e.request_id)
+    lines.push(`  ${dim("request_id: " + e.request_id)}`);
+  return lines.join(`
+`);
 }
 
 // src/runtime/errors.ts
@@ -3157,6 +3103,128 @@ function exitCodeForStatus(httpStatus) {
     return 1;
   return 2;
 }
+var SERVICE_ERROR_CODES = new Set([
+  "network_error",
+  "timeout",
+  "stream_error",
+  "upstream_unavailable",
+  "internal_error",
+  "http_error"
+]);
+function classifyExitCode(code) {
+  return SERVICE_ERROR_CODES.has(code) ? 2 : 1;
+}
+function emitErrorEnvelope(args, exitCode) {
+  const retryable = args.retryable ?? isRetryableByCode(args.code);
+  const hint = resolveRecoveryHint(args.code, args.recovery_hint);
+  const env = { error: { code: args.code, message: args.message, retryable } };
+  if (hint)
+    env.error.recovery_hint = hint;
+  if (args.request_id)
+    env.error.request_id = args.request_id;
+  const ec = exitCode ?? classifyExitCode(args.code);
+  if (isTtyHuman) {
+    process.stderr.write(renderError(env) + `
+`);
+  } else {
+    process.stdout.write(JSON.stringify(env) + `
+`);
+  }
+  process.exit(ec);
+}
+
+// src/runtime/invoker.ts
+import AjvPkg from "ajv";
+import addFormatsPkg from "ajv-formats";
+
+// src/runtime/auth.ts
+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";
+
+class AuthMissingError extends Error {
+  recovery_hint;
+  constructor(message, recovery_hint) {
+    super(message);
+    this.recovery_hint = recovery_hint;
+    this.name = "AuthMissingError";
+  }
+}
+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");
+}
+function configPath() {
+  return path.join(configDir(), "config.toml");
+}
+function readConfigFile() {
+  const p = configPath();
+  if (!fs.existsSync(p))
+    return {};
+  try {
+    const raw = fs.readFileSync(p, "utf-8");
+    return parseToml(raw);
+  } catch {
+    return {};
+  }
+}
+function writeConfigFile(cfg) {
+  const dir = configDir();
+  fs.mkdirSync(dir, { recursive: true, mode: 448 });
+  const data = stringifyToml(cfg);
+  fs.writeFileSync(configPath(), data, { mode: 384 });
+}
+function resolveCredentials(opts = {}) {
+  const DEFAULT_BASE_URL = "https://api.echopai.com";
+  if (opts.key) {
+    return { key: opts.key, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+  }
+  const envKey = process.env.ECHOPAI_KEY;
+  if (envKey) {
+    return { key: envKey, baseUrl: process.env.ECHOPAI_BASE_URL || DEFAULT_BASE_URL, profile: null };
+  }
+  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>`.");
+}
+
+// src/runtime/envelope.ts
+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;
+}
+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) };
+}
 
 // src/runtime/filters.ts
 import jmespathPkg from "jmespath";
@@ -3674,52 +3742,13 @@ function exitCodeForPaginateError(e) {
   return 2;
 }
 
-// src/runtime/tty.ts
-var enable = (() => {
-  if (!process.stderr.isTTY)
-    return false;
-  if (process.env.CI)
-    return false;
-  if (process.env.NO_COLOR)
-    return false;
-  if (process.env.TERM === "dumb")
-    return false;
-  return true;
-})();
-var isTtyHuman = enable;
-var ESC = "\x1B[";
-function ansi(code, s) {
-  if (!enable)
-    return s;
-  return `${ESC}${code}m${s}${ESC}0m`;
-}
-var red = (s) => ansi("31", s);
-var green = (s) => ansi("32", s);
-var yellow = (s) => ansi("33", s);
-var cyan = (s) => ansi("36", s);
-var dim = (s) => ansi("2", s);
-var bold = (s) => ansi("1", s);
-function renderError(env) {
-  if (!enable)
-    return JSON.stringify(env);
-  const e = env.error;
-  const label = `${red(bold("✗ " + e.code))}${e.retryable ? " " + dim("(retryable)") : ""}`;
-  const lines = [`${label} ${dim("—")} ${e.message}`];
-  if (e.recovery_hint)
-    lines.push(`  ${cyan("hint:")} ${e.recovery_hint}`);
-  if (e.request_id)
-    lines.push(`  ${dim("request_id: " + e.request_id)}`);
-  return lines.join(`
-`);
-}
-
 // src/runtime/update_check.ts
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync2, mkdirSync as mkdirSync3, renameSync as renameSync2 } from "node:fs";
 import os2 from "node:os";
 import path2 from "node:path";
 
 // src/version.ts
-var CLI_VERSION = "2.8.1";
+var CLI_VERSION = "2.9.0";
 
 // src/runtime/update_check.ts
 var UPDATE_CACHE_PATH = path2.join(os2.homedir(), ".config", "echopai", "update_cache.json");
@@ -4079,23 +4108,13 @@ function trace(op, t) {
   });
 }
 function writeError(code, message, exitCode, extras) {
-  const retryable = extras?.retryable ?? isRetryableByCode(code);
-  const hint = resolveRecoveryHint(code, extras?.recovery_hint);
-  const env = {
-    error: { code, message, retryable }
-  };
-  if (hint)
-    env.error.recovery_hint = hint;
-  if (extras?.request_id)
-    env.error.request_id = extras.request_id;
-  if (isTtyHuman) {
-    process.stderr.write(renderError(env) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...extras?.retryable !== undefined ? { retryable: extras.retryable } : {},
+    ...extras?.recovery_hint ? { recovery_hint: extras.recovery_hint } : {},
+    ...extras?.request_id ? { request_id: extras.request_id } : {}
+  }, exitCode);
 }
 
 // src/tools/api.ts
@@ -4157,12 +4176,7 @@ function buildApiCommand() {
   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) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/mcp.ts
@@ -4275,29 +4289,18 @@ async function executeVerb(handler) {
     process.exit(0);
   } catch (e) {
     if (e instanceof CallApiError) {
-      emitVerbError(e.code, e.message, e.recovery_hint, e.httpStatus && e.httpStatus < 500 ? 1 : 2, e.requestId);
+      emitVerbError(e.code, e.message, e.recovery_hint, e.httpStatus ? e.httpStatus < 500 ? 1 : 2 : classifyExitCode(e.code), e.requestId);
     }
     emitVerbError("internal_error", e instanceof Error ? e.message : String(e), undefined, 2);
   }
 }
 function emitVerbError(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) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...recoveryHint ? { recovery_hint: recoveryHint } : {},
+    ...requestId ? { request_id: requestId } : {}
+  }, exitCode);
 }
 
 // src/runtime/verb_runner.ts
@@ -6808,14 +6811,7 @@ function buildRawCallCommand() {
   return call;
 }
 function die2(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) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/completion.ts
@@ -7006,12 +7002,7 @@ function redactKey(key) {
   return `eps_live_${parts[2]}_***${last.slice(-4)}`;
 }
 function writeError2(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) + `
-`);
-  process.exit(exitCode);
+  emitErrorEnvelope({ code, message, ...recovery_hint ? { recovery_hint } : {} }, exitCode);
 }
 
 // src/tools/login.ts
@@ -7191,23 +7182,12 @@ function buildWhoamiCommand() {
   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) + `
-`);
-  } else {
-    process.stderr.write(JSON.stringify(env) + `
-`);
-  }
-  process.exit(exitCode);
+  emitErrorEnvelope({
+    code,
+    message,
+    ...recoveryHint ? { recovery_hint: recoveryHint } : {},
+    ...requestId ? { request_id: requestId } : {}
+  }, exitCode);
 }
 
 // src/tools/doctor.ts
@@ -8164,10 +8144,10 @@ var program = new Command31;
 program.name("echopai").description(`Command-line access to the EchoPai market-data platform: quotes, news,
 ` + `analyst research, fundamentals, and sentiment.
 
-` + `Machine-readable by design — a JSON envelope on stdout, JSON errors on
-` + `stderr, and three-state exit codes (0 success / 1 user error / 2 service
-` + `error) — built for AI agents and scripts. Authenticate with the
-` + "ECHOPAI_KEY environment variable or `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Filter or transform output with a JMESPath expression.")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
+` + `Machine-readable by design — in non-TTY (agent/script) mode both success
+` + "`{data:...}` and error `{error:{code,retryable,...}}` envelopes go to stdout\n" + `(one stream to parse), with three-state exit codes (0 success / 1 user error
+` + `/ 2 service error). On a TTY, errors render to stderr for humans. Built for AI
+` + "agents and scripts. Authenticate with ECHOPAI_KEY or `echopai login`.").version(CLI_VERSION, "-V, --version").addOption(new Option23("--debug", "Print HTTP wire trace to stderr (Bearer redacted)")).addOption(new Option23("--raw", "Pass through raw response body (skip envelope wrap)")).addOption(new Option23("--jq <jmespath>", "Filter or transform output with a JMESPath expression.")).addOption(new Option23("--fields <a,b,c>", "Keep only listed top-level fields per item")).addOption(new Option23("--max-bytes <n>", "Truncate serialized envelope to N bytes (sets meta.truncated)")).addOption(new Option23("--yes", "Confirm a write op in non-TTY mode (required for sideEffect=write in agents / CI)")).addOption(new Option23("--dry-run", "Send X-Dry-Run:1 on write ops where the server advertises dry-run support")).addHelpText("after", `
 Authentication:  ECHOPAI_KEY=<eps_live_...> echopai <command>
 ` + `Curated verbs:   echopai <verb>                                  # task-level commands (recommended)
 ` + `Raw operations:  echopai raw <noun> <verb>                       # low-level access to every API operation
@@ -8191,21 +8171,30 @@ var dispatch = async (op, args) => {
   }
   await invoke(op, { ...globalsSnake, ...args }, { cliVersion: CLI_VERSION });
 };
+function detectStrayCodeArgs(args) {
+  if (!Array.isArray(args))
+    return [];
+  const codeLike = /^((SSE|SZSE|BSE|SH|SZ|BJ):)?[0-9]{6}$/i;
+  return args.filter((a) => typeof a === "string" && codeLike.test(a));
+}
 function applyAiFirstHooks(cmd) {
   cmd.configureOutput({ writeErr: () => {} });
   cmd.exitOverride((err) => {
     if (err.code === "commander.helpDisplayed" || err.code === "commander.help" || err.code === "commander.version") {
       process.exit(0);
     }
-    process.stderr.write(JSON.stringify({
-      error: {
-        code: "invalid_args",
-        message: err.message,
-        recovery_hint: "Run with `--help` for usage."
-      }
-    }) + `
-`);
-    process.exit(1);
+    let message = err.message;
+    const stray = detectStrayCodeArgs(cmd.args);
+    if (stray.length > 0) {
+      const opt = /code\b/i.test(err.message) ? "--code" : "--codes";
+      message += `. Detected positional argument(s) [${stray.join(", ")}] — these commands ` + `take codes via an option, not positionally; did you mean ` + `\`${opt} ${stray.join(",")}\`?`;
+    }
+    emitErrorEnvelope({
+      code: "invalid_args",
+      message,
+      retryable: false,
+      recovery_hint: "Run with `--help` for usage."
+    }, 1);
   });
   for (const sub of cmd.commands)
     applyAiFirstHooks(sub);
@@ -8277,12 +8266,5 @@ if (shouldShowWelcome(process.argv)) {
   process.exit(0);
 }
 program.parseAsync(process.argv).catch((e) => {
-  process.stderr.write(JSON.stringify({
-    error: {
-      code: "internal_error",
-      message: e instanceof Error ? e.message : String(e)
-    }
-  }) + `
-`);
-  process.exit(2);
+  emitErrorEnvelope({ code: "internal_error", message: e instanceof Error ? e.message : String(e) }, 2);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "echopai",
-  "version": "2.8.1",
+  "version": "2.9.0",
   "description": "Command-line interface for the EchoPai Open Platform: stock-market data, news, analyst views, sentiment, signals, backtests.",
   "license": "MIT",
   "homepage": "https://echopai.com",