@evatick/cli 0.3.2 → 0.4.1

package/README.md

@@ -1,7 +1,13 @@
-# EVA CLI
+# EVA Tick CLI
 
-EVA CLI is a stable, machine-readable market-data command-line client for LLMs,
-AI agents, and automation. It connects to the versioned EVA HTTP API.
+Deterministic, machine-readable financial data for AI agents, LLMs, and
+automation.
+
+EVA Tick gives agents canonical instrument IDs, stable JSON, structured errors,
+and predictable commands instead of provider-specific identifiers and
+functions.
+
+![Codex queries financial data through EVA Tick](https://raw.githubusercontent.com/xiaochaohit/evatick-cli/main/docs/assets/eva-tick-codex-demo.gif)
 
 ## Install
 
@@ -10,19 +16,81 @@ npm install --global @evatick/cli
 eva version
 ```
 
-It can also be run without a global installation:
+Run it without installing:
 
 ```shell
 npx @evatick/cli health
 ```
 
-The npm package installs a native executable for the current platform. Python is
-not required. Supported targets are macOS arm64/x64, Linux x64 (glibc), and
-Windows x64.
+The npm package is implemented in Node.js, has no runtime dependencies, and
+does not require Python or platform-specific native executables.
+
+## First query
+
+```shell
+eva health
+eva instrument search --query 平安银行 --type equity --limit 3
+eva instrument resolve --query 000001 --type equity
+eva stock bars --symbol cn:equity:XSHE:000001 \
+  --interval 1d \
+  --start 2026-08-18 \
+  --end 2026-08-21 \
+  --adjustment forward \
+  --limit 3
+```
+
+## Common commands
+
+- `eva instrument search` finds canonical financial instruments by name, code,
+  or alias.
+- `eva stock bars` queries normalized OHLCV bars.
+- `eva index constituents` queries index constituent memberships.
+
+Run `eva COMMAND --help` or `eva GROUP COMMAND --help` for supported options.
+
+## Hosted or self-hosted
+
+The CLI connects to the hosted EVA Tick service at `https://api.evatick.com` by
+default. Point it at a self-hosted [EVA Tick Server](https://github.com/xiaochaohit/evatick-server)
+temporarily with an environment variable:
+
+```shell
+EVA_SERVER_URL=http://127.0.0.1:8765 eva health
+```
+
+Or save the service URL:
+
+```shell
+eva config set --base-url http://127.0.0.1:8765
+eva config show
+```
+
+When a service requires authentication, use `EVA_API_KEY` or
+`eva config set --api-key 'eva_...'`. The CLI sends a key only when configured,
+and `eva config show` masks stored keys.
+
+## Current availability
+
+EVA Tick is designed as a provider-independent financial data layer. The
+current public service starts with mainland China A-shares and indices published
+by the Shanghai Stock Exchange, Shenzhen Stock Exchange, and China Securities
+Index. Availability varies by deployed service and enabled providers.
+
+## Output and safety
+
+- Successful results are compact JSON on stdout.
+- Failures are structured JSON on stderr with stable error codes.
+- JSON, JSONL, and CSV file exports are supported by the npm CLI.
+- Existing files are never overwritten unless `--overwrite` is explicit.
+- Parquet export is available in the Python distribution with
+  `pip install 'evatick[parquet]'`.
+
+## Documentation
 
-JSON, JSONL, and CSV exports are supported. Parquet export remains available in
-the Python distribution (`pip install 'evatick[parquet]'`) and is intentionally
-not bundled into the native npm executables.
+- [Complete CLI documentation and examples](https://github.com/xiaochaohit/evatick-cli#readme)
+- [EVA Tick Skill for Codex](https://www.npmjs.com/package/@evatick/skill)
+- [Self-hosted server and OpenAPI contract](https://github.com/xiaochaohit/evatick-server)
+- [License and data-source notices](https://github.com/xiaochaohit/evatick-cli#license)
 
-See the [EVA CLI repository](https://github.com/xiaochaohit/evatick-cli) for
-commands, configuration, source code, and license information.
+Market data is provided for research and reference only and does not constitute
+investment advice.

package/bin/eva.js

@@ -2,42 +2,21 @@
 
 "use strict";
 
-const { spawnSync } = require("node:child_process");
+const { main } = require("../lib/cli.js");
 
-const targets = {
-  "darwin-arm64": ["@evatick/cli-darwin-arm64", "eva"],
-  "darwin-x64": ["@evatick/cli-darwin-x64", "eva"],
-  "linux-x64": ["@evatick/cli-linux-x64", "eva"],
-  "win32-x64": ["@evatick/cli-win32-x64", "eva.exe"],
-};
-
-const target = `${process.platform}-${process.arch}`;
-const selected = targets[target];
-if (!selected) {
-  console.error(
-    `EVA CLI does not support ${target}. Supported targets: ${Object.keys(targets).join(", ")}.`,
-  );
-  process.exit(1);
-}
-
-let executable;
-try {
-  executable = require.resolve(`${selected[0]}/bin/${selected[1]}`);
-} catch (error) {
-  console.error(
-    `The EVA CLI executable for ${target} is missing. Reinstall @evatick/cli without omitting optional dependencies.`,
-  );
-  process.exit(1);
-}
-
-const result = spawnSync(executable, process.argv.slice(2), {
-  stdio: "inherit",
+main(process.argv.slice(2)).catch((error) => {
+  const problem = error && error.evaProblem
+    ? error.evaProblem
+    : {
+        code: "INTERNAL_ERROR",
+        message: "EVA CLI failed unexpectedly",
+        retryable: false,
+        exitCode: 1,
+      };
+  process.stderr.write(`${JSON.stringify({
+    code: problem.code,
+    message: problem.message,
+    retryable: problem.retryable,
+  })}\n`);
+  process.exitCode = problem.exitCode;
 });
-if (result.error) {
-  console.error(`Unable to start EVA CLI: ${result.error.message}`);
-  process.exit(1);
-}
-if (result.signal) {
-  process.kill(process.pid, result.signal);
-}
-process.exit(result.status === null ? 1 : result.status);

package/lib/cli.js

@@ -0,0 +1,414 @@
+"use strict";
+
+const path = require("node:path");
+const {
+  defaultConfigurationPath,
+  expandHome,
+  loadConfiguration,
+  saveConfiguration,
+} = require("./config.js");
+const { EvaError, usage } = require("./errors.js");
+const { EvaHttpClient } = require("./http-client.js");
+const { dumps, emit } = require("./output.js");
+
+const DEFAULT_SERVER_URL = "https://api.evatick.com";
+const VERSION = require("../package.json").version;
+const INTERVALS = ["1m", "5m", "15m", "30m", "60m", "1d", "1w", "1mo"];
+
+const ROOT_HELP = `NAME
+    eva
+
+PURPOSE
+    通过 EVA 查询股票和指数数据。
+
+USAGE
+    eva [--config PATH] [--server-url URL] [--api-key KEY] COMMAND [OPTIONS]
+
+OPTIONS
+    --config PATH
+    --server-url URL
+    --api-key KEY
+
+COMMANDS
+    config
+    health
+    index
+    instrument
+    stock
+    version
+`;
+
+const HELP = {
+  config: "Usage: eva config [OPTIONS] COMMAND [ARGS]...\n\n  Manage the unified CLI configuration file.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  set\n  show\n",
+  "config set": "Usage: eva config set [OPTIONS]\n\nOptions:\n  --base-url TEXT\n  --help\n",
+  "config show": "Usage: eva config show [OPTIONS]\n\nOptions:\n  --help\n",
+  health: "Usage: eva health [OPTIONS]\n\nOptions:\n  --timeout FLOAT  [default: 10]\n  --retries INTEGER  [default: 0]\n  --help\n",
+  version: "Usage: eva version [OPTIONS]\n\nOptions:\n  --help\n",
+  instrument: "Usage: eva instrument [OPTIONS] COMMAND [ARGS]...\n\n  Discover and resolve canonical instruments.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  list\n  resolve\n  search\n  show\n",
+  "instrument list": "Usage: eva instrument list [OPTIONS]\n\nOptions:\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --cursor TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument search": "Usage: eva instrument search [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument resolve": "Usage: eva instrument resolve [OPTIONS]\n\nOptions:\n  --query TEXT  [required]\n  --type [equity|index]\n  --venue TEXT\n  --publisher TEXT\n  --capability [quote|bars|constituents]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "instrument show": "Usage: eva instrument show [OPTIONS]\n\nOptions:\n  --id TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  stock: "Usage: eva stock [OPTIONS] COMMAND [ARGS]...\n\n  Query mainland A-share data.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  quotes\n",
+  index: "Usage: eva index [OPTIONS] COMMAND [ARGS]...\n\n  Query SSE, SZSE, and CSI index data.\n\nOptions:\n  --help  Show this message and exit.\n\nCommands:\n  bars\n  constituents\n  quotes\n",
+  "stock quotes": "Usage: eva stock quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "index quotes": "Usage: eva index quotes [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "stock bars": "Usage: eva stock bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "index bars": "Usage: eva index bars [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --interval [1m|5m|15m|30m|60m|1d|1w|1mo]  [default: 1d]\n  --start TEXT\n  --end TEXT\n  --adjustment [none|forward|backward]  [default: none]\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+  "index constituents": "Usage: eva index constituents [OPTIONS]\n\nOptions:\n  --symbol TEXT  [required]\n  --as-of TEXT\n  --limit INTEGER\n  --output PATH\n  --format [json|jsonl|csv|parquet]\n  --overwrite\n  --timeout FLOAT  [default: 120]\n  --retries INTEGER  [default: 2]\n  --help\n",
+};
+
+const rootDefinitions = {
+  config: { type: "string" },
+  "server-url": { type: "string" },
+  "api-key": { type: "string" },
+};
+const requestDefinitions = {
+  timeout: { type: "number", min: 0.1, default: 120 },
+  retries: { type: "integer", min: 0, default: 2 },
+};
+const dataDefinitions = {
+  limit: { type: "integer", min: 1 },
+  output: { type: "string" },
+  format: { type: "choice", choices: ["json", "jsonl", "csv", "parquet"] },
+  overwrite: { type: "boolean", default: false },
+  ...requestDefinitions,
+};
+const discoveryDefinitions = {
+  type: { type: "choice", choices: ["equity", "index"] },
+  venue: { type: "string" },
+  publisher: { type: "string" },
+  capability: { type: "choice", choices: ["quote", "bars", "constituents"] },
+};
+
+function parseValue(name, raw, definition) {
+  if (definition.type === "string") return raw;
+  if (definition.type === "choice") {
+    if (!definition.choices.includes(raw)) {
+      throw usage(`Invalid value for '--${name}': '${raw}' is not one of ${definition.choices.join(", ")}.`);
+    }
+    return raw;
+  }
+  const value = Number(raw);
+  const valid = definition.type === "integer" ? Number.isInteger(value) : Number.isFinite(value);
+  if (!valid || value < definition.min) {
+    throw usage(`Invalid value for '--${name}': ${raw}`);
+  }
+  return value;
+}
+
+function parseOptions(arguments_, definitions, required = []) {
+  const values = {};
+  for (const [name, definition] of Object.entries(definitions)) {
+    if (definition.default !== undefined) values[toProperty(name)] = definition.default;
+  }
+  for (let index = 0; index < arguments_.length; index += 1) {
+    const argument = arguments_[index];
+    if (!argument.startsWith("--")) throw usage(`Got unexpected extra argument (${argument})`);
+    const separator = argument.indexOf("=");
+    const name = argument.slice(2, separator === -1 ? undefined : separator);
+    const definition = definitions[name];
+    if (!definition) throw usage(`No such option: --${name}`);
+    const property = toProperty(name);
+    if (definition.type === "boolean") {
+      if (separator !== -1) throw usage(`Option '--${name}' does not take a value.`);
+      values[property] = true;
+      continue;
+    }
+    let raw;
+    if (separator !== -1) raw = argument.slice(separator + 1);
+    else {
+      index += 1;
+      raw = arguments_[index];
+      if (raw === undefined || raw.startsWith("--")) throw usage(`Option '--${name}' requires an argument.`);
+    }
+    values[property] = parseValue(name, raw, definition);
+  }
+  for (const name of required) {
+    if (values[toProperty(name)] === undefined) throw usage(`Missing option '--${name}'.`);
+  }
+  return values;
+}
+
+function toProperty(name) {
+  return name.replace(/-([a-z])/g, (_, letter) => letter.toUpperCase());
+}
+
+function parseRoot(arguments_) {
+  const optionArguments = [];
+  let index = 0;
+  while (index < arguments_.length && arguments_[index].startsWith("--")) {
+    const argument = arguments_[index];
+    if (argument === "--help") return { help: true };
+    optionArguments.push(argument);
+    const name = argument.slice(2).split("=", 1)[0];
+    if (!rootDefinitions[name]) throw usage(`No such option: --${name}`);
+    if (!argument.includes("=")) {
+      index += 1;
+      if (arguments_[index] === undefined) throw usage(`Option '--${name}' requires an argument.`);
+      optionArguments.push(arguments_[index]);
+    }
+    index += 1;
+  }
+  return {
+    options: parseOptions(optionArguments, rootDefinitions),
+    remaining: arguments_.slice(index),
+  };
+}
+
+function queryString(values) {
+  const query = new URLSearchParams();
+  for (const [name, value] of Object.entries(values)) {
+    if (value !== undefined && value !== null) query.set(name, String(value));
+  }
+  return query.toString();
+}
+
+function leaf(pathParts, arguments_) {
+  const key = pathParts.join(" ");
+  if (arguments_.includes("--help")) {
+    process.stdout.write(HELP[key]);
+    return null;
+  }
+  return key;
+}
+
+function contextFrom(rootOptions, environment) {
+  const configurationPath = path.resolve(expandHome(
+    rootOptions.config || defaultConfigurationPath(environment),
+  ));
+  const configuration = loadConfiguration(configurationPath);
+  return {
+    configurationPath,
+    configuration,
+    baseUrl: rootOptions.serverUrl || environment.EVA_SERVER_URL || configuration.baseUrl || DEFAULT_SERVER_URL,
+    apiKey: rootOptions.apiKey || environment.EVA_API_KEY || configuration.apiKey,
+  };
+}
+
+function client(context, options) {
+  return new EvaHttpClient(
+    context.baseUrl,
+    options.timeout,
+    options.retries,
+    context.apiKey,
+    VERSION,
+  );
+}
+
+async function dispatch(context, command, subcommand, arguments_) {
+  const key = leaf(subcommand ? [command, subcommand] : [command], arguments_);
+  if (key === null) return;
+
+  if (key === "version") {
+    parseOptions(arguments_, {});
+    process.stdout.write(`${dumps({
+      eva_cli: VERSION,
+      eva_server_api: "v1",
+      node: process.versions.node,
+    })}\n`);
+    return;
+  }
+  if (key === "config show") {
+    parseOptions(arguments_, {});
+    process.stdout.write(`${dumps({
+      path: context.configurationPath,
+      base_url: context.configuration.baseUrl || null,
+      api_key: context.configuration.apiKey ? "********" : null,
+    })}\n`);
+    return;
+  }
+  if (key === "config set") {
+    const options = parseOptions(arguments_, {
+      "base-url": { type: "string" },
+      "api-key": { type: "string" },
+    });
+    if (options.baseUrl === undefined && options.apiKey === undefined) {
+      throw usage("at least one of --base-url or --api-key is required");
+    }
+    const updated = {
+      baseUrl: options.baseUrl === undefined ? context.configuration.baseUrl : options.baseUrl,
+      apiKey: options.apiKey === undefined ? context.configuration.apiKey : options.apiKey,
+    };
+    if (updated.baseUrl && !(updated.baseUrl.startsWith("http://") || updated.baseUrl.startsWith("https://"))) {
+      throw usage("--base-url must start with http:// or https://");
+    }
+    saveConfiguration(context.configurationPath, updated);
+    process.stdout.write(`${dumps({ path: context.configurationPath, updated: true })}\n`);
+    return;
+  }
+  if (key === "health") {
+    const options = parseOptions(arguments_, {
+      timeout: { type: "number", min: 0.1, default: 10 },
+      retries: { type: "integer", min: 0, default: 0 },
+    });
+    const response = await client(context, options).request("GET", "/v1/health");
+    process.stdout.write(`${dumps(response.data ?? {})}\n`);
+    return;
+  }
+  if (key === "instrument list") {
+    const options = parseOptions(arguments_, {
+      ...discoveryDefinitions,
+      cursor: { type: "string" },
+      ...dataDefinitions,
+    });
+    const limit = options.limit || 100;
+    const response = await client(context, options).request(
+      "GET",
+      `/v1/instruments?${queryString({
+        instrument_type: options.type,
+        venue: options.venue,
+        publisher: options.publisher,
+        capability: options.capability,
+        cursor: options.cursor,
+        limit: Math.min(limit, 1000),
+      })}`,
+    );
+    emit(
+      { items: response.data ?? [], next_cursor: (response.page || {}).next_cursor ?? null },
+      { ...options, limit: undefined },
+    );
+    return;
+  }
+  if (key === "instrument search") {
+    const options = parseOptions(arguments_, {
+      query: { type: "string" }, ...discoveryDefinitions, ...dataDefinitions,
+    }, ["query"]);
+    const limit = Math.min(options.limit || 20, 200);
+    const response = await client(context, options).request(
+      "GET",
+      `/v1/instrument-search?${queryString({
+        q: options.query,
+        instrument_type: options.type,
+        venue: options.venue,
+        publisher: options.publisher,
+        capability: options.capability,
+        limit,
+      })}`,
+    );
+    emit(response.data ?? [], { ...options, limit });
+    return;
+  }
+  if (key === "instrument resolve") {
+    const options = parseOptions(arguments_, {
+      query: { type: "string" }, ...discoveryDefinitions, ...requestDefinitions,
+    }, ["query"]);
+    const resolutionContext = {};
+    if (options.type !== undefined) resolutionContext.instrument_type = options.type;
+    if (options.venue !== undefined) resolutionContext.venue = options.venue;
+    if (options.publisher !== undefined) resolutionContext.publisher = options.publisher;
+    if (options.capability !== undefined) resolutionContext.capability = options.capability;
+    const response = await client(context, options).request("POST", "/v1/instrument-resolve", {
+      query: options.query,
+      context: resolutionContext,
+    });
+    process.stdout.write(`${dumps(response.data ?? {})}\n`);
+    return;
+  }
+  if (key === "instrument show") {
+    const options = parseOptions(arguments_, {
+      id: { type: "string" }, ...requestDefinitions,
+    }, ["id"]);
+    const response = await client(context, options).request(
+      "GET",
+      `/v1/instruments/${encodeURIComponent(options.id)}`,
+    );
+    process.stdout.write(`${dumps(response.data ?? {})}\n`);
+    return;
+  }
+  if (key === "stock quotes" || key === "index quotes") {
+    const options = parseOptions(arguments_, {
+      symbol: { type: "string" }, ...requestDefinitions,
+    }, ["symbol"]);
+    const instrumentType = command === "stock" ? "equity" : "index";
+    const http = client(context, options);
+    const instrumentId = await http.resolve(options.symbol, instrumentType, "quote");
+    const response = await http.request(
+      "GET",
+      `/v1/instruments/${encodeURIComponent(instrumentId)}/quote`,
+    );
+    process.stdout.write(`${dumps(response.data ?? {})}\n`);
+    return;
+  }
+  if (key === "stock bars" || key === "index bars") {
+    const options = parseOptions(arguments_, {
+      symbol: { type: "string" },
+      interval: { type: "choice", choices: INTERVALS, default: "1d" },
+      start: { type: "string" },
+      end: { type: "string" },
+      adjustment: { type: "choice", choices: ["none", "forward", "backward"], default: "none" },
+      ...dataDefinitions,
+    }, ["symbol"]);
+    const instrumentType = command === "stock" ? "equity" : "index";
+    const http = client(context, options);
+    const instrumentId = await http.resolve(options.symbol, instrumentType, "bars");
+    const response = await http.request(
+      "GET",
+      `/v1/instruments/${encodeURIComponent(instrumentId)}/bars?${queryString({
+        interval: options.interval,
+        start: options.start,
+        end: options.end,
+        adjustment: options.adjustment,
+      })}`,
+    );
+    emit(response.data ?? [], options);
+    return;
+  }
+  if (key === "index constituents") {
+    const options = parseOptions(arguments_, {
+      symbol: { type: "string" }, "as-of": { type: "string" }, ...dataDefinitions,
+    }, ["symbol"]);
+    const http = client(context, options);
+    const instrumentId = await http.resolve(options.symbol, "index", "constituents");
+    const suffix = options.asOf ? `?${queryString({ as_of: options.asOf })}` : "";
+    const response = await http.request(
+      "GET",
+      `/v1/indices/${encodeURIComponent(instrumentId)}/constituents${suffix}`,
+    );
+    emit(response.data ?? [], options);
+    return;
+  }
+  throw usage(`No such command '${subcommand || command}'.`);
+}
+
+function commandParts(remaining) {
+  const command = remaining[0];
+  if (!command) return {};
+  if (!["config", "health", "version", "instrument", "stock", "index"].includes(command)) {
+    throw usage(`No such command '${command}'.`);
+  }
+  if (["health", "version"].includes(command)) {
+    return { command, arguments_: remaining.slice(1) };
+  }
+  const subcommand = remaining[1];
+  if (!subcommand) return { command, groupMissing: true };
+  if (subcommand === "--help") return { command, groupHelp: true };
+  if (subcommand.startsWith("--")) throw usage(`No such option: ${subcommand}`);
+  const valid = {
+    config: ["set", "show"],
+    instrument: ["list", "search", "resolve", "show"],
+    stock: ["quotes", "bars"],
+    index: ["quotes", "bars", "constituents"],
+  }[command];
+  if (!valid.includes(subcommand)) throw usage(`No such command '${subcommand}'.`);
+  return { command, subcommand, arguments_: remaining.slice(2) };
+}
+
+async function main(arguments_, environment = process.env) {
+  const root = parseRoot(arguments_);
+  if (root.help) {
+    process.stdout.write(ROOT_HELP);
+    return;
+  }
+  if (!root.remaining.length) throw usage(ROOT_HELP.trimEnd());
+  const parts = commandParts(root.remaining);
+  if (parts.groupHelp) {
+    process.stdout.write(HELP[parts.command]);
+    return;
+  }
+  if (parts.groupMissing) throw usage(HELP[parts.command].trimEnd());
+  const context = contextFrom(root.options, environment);
+  await dispatch(context, parts.command, parts.subcommand, parts.arguments_);
+}
+
+module.exports = { DEFAULT_SERVER_URL, main, parseOptions };

package/lib/config.js

@@ -0,0 +1,101 @@
+"use strict";
+
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { EvaError } = require("./errors.js");
+
+function defaultConfigurationPath(environment = process.env) {
+  if (environment.EVA_CONFIG) return path.resolve(expandHome(environment.EVA_CONFIG));
+  const root = process.platform === "win32"
+    ? environment.APPDATA || path.join(os.homedir(), "AppData", "Roaming")
+    : environment.XDG_CONFIG_HOME || path.join(os.homedir(), ".config");
+  return path.join(root, "eva", "config.json");
+}
+
+function expandHome(value) {
+  if (value === "~") return os.homedir();
+  if (value.startsWith(`~${path.sep}`) || value.startsWith("~/")) {
+    return path.join(os.homedir(), value.slice(2));
+  }
+  return value;
+}
+
+function configurationError(message) {
+  return new EvaError("INVALID_CONFIGURATION", message);
+}
+
+function loadConfiguration(configurationPath) {
+  let stats;
+  try {
+    stats = fs.statSync(configurationPath);
+  } catch (error) {
+    if (error.code === "ENOENT") return {};
+    throw configurationError(`cannot read configuration file: ${configurationPath}`);
+  }
+  if (!stats.isFile()) {
+    throw configurationError(`cannot read configuration file: ${configurationPath}`);
+  }
+  if (process.platform !== "win32" && (stats.mode & 0o077) !== 0) {
+    throw configurationError(
+      `configuration file must be owner-only (use chmod 600): ${configurationPath}`,
+    );
+  }
+  let value;
+  try {
+    value = JSON.parse(fs.readFileSync(configurationPath, "utf8"));
+  } catch {
+    throw configurationError(`cannot read configuration file: ${configurationPath}`);
+  }
+  if (!value || Array.isArray(value) || typeof value !== "object" || value.schema !== "eva.cli-config.v1") {
+    throw configurationError("configuration schema must be eva.cli-config.v1");
+  }
+  const allowed = new Set(["schema", "base_url", "api_key"]);
+  const unknown = Object.keys(value).filter((key) => !allowed.has(key)).sort();
+  if (unknown.length) {
+    throw configurationError(`configuration contains unknown field: ${unknown[0]}`);
+  }
+  if (value.base_url !== undefined && (
+    typeof value.base_url !== "string" ||
+    !(value.base_url.startsWith("http://") || value.base_url.startsWith("https://"))
+  )) {
+    throw configurationError("configuration.base_url must be an HTTP(S) URL");
+  }
+  if (value.api_key !== undefined && (
+    typeof value.api_key !== "string" || !value.api_key.trim()
+  )) {
+    throw configurationError("configuration.api_key must be a non-empty string");
+  }
+  return { baseUrl: value.base_url, apiKey: value.api_key };
+}
+
+function saveConfiguration(configurationPath, configuration) {
+  fs.mkdirSync(path.dirname(configurationPath), { recursive: true });
+  const value = { schema: "eva.cli-config.v1" };
+  if (configuration.baseUrl) value.base_url = configuration.baseUrl;
+  if (configuration.apiKey) value.api_key = configuration.apiKey;
+  const temporary = path.join(
+    path.dirname(configurationPath),
+    `.${path.basename(configurationPath)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  try {
+    fs.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    fs.chmodSync(temporary, 0o600);
+    fs.renameSync(temporary, configurationPath);
+  } finally {
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+
+module.exports = {
+  defaultConfigurationPath,
+  expandHome,
+  loadConfiguration,
+  saveConfiguration,
+};

package/lib/errors.js

@@ -0,0 +1,15 @@
+"use strict";
+
+class EvaError extends Error {
+  constructor(code, message, retryable = false, exitCode = 1) {
+    super(message);
+    this.name = "EvaError";
+    this.evaProblem = { code, message, retryable, exitCode };
+  }
+}
+
+function usage(message) {
+  return new EvaError("INVALID_ARGUMENT", message, false, 2);
+}
+
+module.exports = { EvaError, usage };

package/lib/http-client.js

@@ -0,0 +1,109 @@
+"use strict";
+
+const { EvaError } = require("./errors.js");
+
+function sleep(milliseconds) {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+
+class EvaHttpClient {
+  constructor(baseUrl, timeout, retries, apiKey, version) {
+    if (!(baseUrl.startsWith("http://") || baseUrl.startsWith("https://"))) {
+      throw new EvaError(
+        "INVALID_SERVER_URL",
+        "server URL must start with http:// or https://",
+      );
+    }
+    this.baseUrl = baseUrl.replace(/\/+$/, "");
+    this.timeout = timeout;
+    this.retries = retries;
+    this.apiKey = apiKey;
+    this.version = version;
+  }
+
+  async request(method, requestPath, payload) {
+    const started = performance.now();
+    for (let attempt = 0; attempt <= this.retries; attempt += 1) {
+      const remaining = this.timeout * 1000 - (performance.now() - started);
+      if (remaining <= 0) {
+        throw new EvaError(
+          "TIMEOUT",
+          `server call exceeded the ${this.timeout} second total timeout`,
+          true,
+        );
+      }
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), remaining);
+      try {
+        const body = payload === undefined ? undefined : JSON.stringify(payload);
+        const response = await fetch(`${this.baseUrl}${requestPath}`, {
+          method,
+          body,
+          signal: controller.signal,
+          headers: {
+            Accept: "application/json",
+            "User-Agent": `eva/${this.version}`,
+            ...(this.apiKey ? { Authorization: `Bearer ${this.apiKey}` } : {}),
+            ...(body ? { "Content-Type": "application/json" } : {}),
+          },
+        });
+        const text = await response.text();
+        let parsed;
+        try { parsed = JSON.parse(text); } catch {
+          if (response.ok) {
+            throw new EvaError(
+              "INVALID_SERVER_RESPONSE",
+              "server returned invalid JSON",
+            );
+          }
+          parsed = {};
+        }
+        if (!response.ok) {
+          const retryable = Boolean(parsed.retryable) || [429, 502, 503, 504].includes(response.status);
+          if (retryable && attempt < this.retries) {
+            await sleep(Math.min(250 * (2 ** attempt), remaining));
+            continue;
+          }
+          throw new EvaError(
+            String(parsed.code || "HTTP_ERROR"),
+            String(parsed.detail || `server returned HTTP ${response.status}`),
+            retryable,
+          );
+        }
+        if (!parsed || Array.isArray(parsed) || typeof parsed !== "object") {
+          throw new EvaError(
+            "INVALID_SERVER_RESPONSE",
+            "server returned a non-object JSON response",
+          );
+        }
+        return parsed;
+      } catch (error) {
+        if (error && error.evaProblem) throw error;
+        if (attempt < this.retries) {
+          await sleep(Math.min(250 * (2 ** attempt), remaining));
+          continue;
+        }
+        throw new EvaError("SERVER_UNAVAILABLE", "EVA service is unavailable", true);
+      } finally {
+        clearTimeout(timer);
+      }
+    }
+    throw new Error("HTTP retry loop exhausted");
+  }
+
+  async resolve(query, instrumentType, capability) {
+    const response = await this.request("POST", "/v1/instrument-resolve", {
+      query,
+      context: { instrument_type: instrumentType, capability },
+    });
+    const data = response.data || {};
+    const instrumentId = data.instrument && data.instrument.instrument_id;
+    if (data.status === "resolved" && typeof instrumentId === "string") return instrumentId;
+    throw new EvaError(
+      data.status === "ambiguous" ? "AMBIGUOUS_INSTRUMENT" : "INSTRUMENT_NOT_FOUND",
+      "instrument input did not resolve to one supported instrument",
+    );
+  }
+}
+
+module.exports = { EvaHttpClient };

package/lib/output.js

@@ -0,0 +1,160 @@
+"use strict";
+
+const fs = require("node:fs");
+const path = require("node:path");
+const { EvaError, usage } = require("./errors.js");
+
+function serializationError(code, message) {
+  return new EvaError(code, message);
+}
+
+function applyLimit(value, limit) {
+  if (limit === undefined) return value;
+  if (!Array.isArray(value)) {
+    throw serializationError("LIMIT_NOT_APPLICABLE", "--limit requires a record sequence result");
+  }
+  return value.slice(0, limit);
+}
+
+function dumps(value, { limit, recordBudget = 200 } = {}) {
+  const normalized = applyLimit(value, limit);
+  if (recordBudget !== null && Array.isArray(normalized) && normalized.length > recordBudget) {
+    throw serializationError(
+      "RESULT_TOO_LARGE",
+      `result has ${normalized.length} records; use --limit or --output`,
+    );
+  }
+  return JSON.stringify(normalized);
+}
+
+function validateTarget(target, overwrite) {
+  let parent;
+  try { parent = fs.statSync(path.dirname(target)); } catch { parent = null; }
+  if (!parent || !parent.isDirectory()) {
+    throw serializationError("OUTPUT_PARENT_MISSING", "output parent directory does not exist");
+  }
+  let stats;
+  try { stats = fs.lstatSync(target); } catch (error) {
+    if (error.code === "ENOENT") return;
+    throw error;
+  }
+  if (!stats.isFile()) {
+    throw serializationError("OUTPUT_PATH_INVALID", "output path must be a regular file");
+  }
+  if (!overwrite) throw serializationError("OUTPUT_EXISTS", "output path already exists");
+}
+
+function atomicWrite(target, content, overwrite) {
+  validateTarget(target, overwrite);
+  const temporary = path.join(
+    path.dirname(target),
+    `.${path.basename(target)}.${process.pid}.${Date.now()}.tmp`,
+  );
+  let descriptor;
+  try {
+    descriptor = fs.openSync(temporary, "wx", 0o600);
+    fs.writeFileSync(descriptor, content, "utf8");
+    fs.fsyncSync(descriptor);
+    fs.closeSync(descriptor);
+    descriptor = undefined;
+    if (overwrite) fs.renameSync(temporary, target);
+    else {
+      try { fs.linkSync(temporary, target); } catch (error) {
+        if (error.code === "EEXIST") {
+          throw serializationError("OUTPUT_EXISTS", "output path already exists");
+        }
+        throw error;
+      }
+      fs.unlinkSync(temporary);
+    }
+  } finally {
+    if (descriptor !== undefined) fs.closeSync(descriptor);
+    try { fs.unlinkSync(temporary); } catch (error) {
+      if (error.code !== "ENOENT") throw error;
+    }
+  }
+}
+
+function csvCell(value) {
+  let text;
+  if (value === null || value === undefined) text = "";
+  else if (typeof value === "boolean") text = value ? "True" : "False";
+  else text = String(value);
+  if (/[",\r\n]/.test(text)) return `"${text.replaceAll('"', '""')}"`;
+  return text;
+}
+
+function recordsForFormat(value, format) {
+  if (!Array.isArray(value) || !value.every((record) => record && !Array.isArray(record) && typeof record === "object")) {
+    throw serializationError(
+      "INCOMPATIBLE_OUTPUT_FORMAT",
+      `${format} requires a sequence of record objects`,
+    );
+  }
+  return value;
+}
+
+function csvContent(value) {
+  const records = recordsForFormat(value, "csv");
+  if (!records.length) return "";
+  const fields = Object.keys(records[0]);
+  const expected = new Set(fields);
+  for (const record of records) {
+    const keys = Object.keys(record);
+    if (
+      keys.length !== fields.length ||
+      keys.some((key) => !expected.has(key)) ||
+      Object.values(record).some((item) => item !== null && typeof item === "object")
+    ) {
+      throw serializationError(
+        "INCOMPATIBLE_OUTPUT_FORMAT",
+        "csv requires consistent flat record fields",
+      );
+    }
+  }
+  const lines = [fields.map(csvCell).join(",")];
+  for (const record of records) lines.push(fields.map((field) => csvCell(record[field])).join(","));
+  return `${lines.join("\n")}\n`;
+}
+
+function exportResult(value, { output, format, overwrite, limit }) {
+  const target = path.resolve(output);
+  const extension = path.extname(target).slice(1).toLowerCase();
+  const known = new Set(["csv", "json", "jsonl", "parquet"]);
+  if (format && known.has(extension) && extension !== format) {
+    throw serializationError(
+      "OUTPUT_FORMAT_MISMATCH",
+      "explicit output format conflicts with the file extension",
+    );
+  }
+  const selected = format || extension;
+  if (!known.has(selected)) {
+    throw serializationError("UNSUPPORTED_OUTPUT_FORMAT", "output format is not supported");
+  }
+  const normalized = applyLimit(value, limit);
+  let content;
+  if (selected === "parquet") {
+    recordsForFormat(normalized, "parquet");
+    throw serializationError(
+      "PARQUET_UNAVAILABLE",
+      "Parquet output requires the evatick[parquet] extra",
+    );
+  } else if (selected === "csv") content = csvContent(normalized);
+  else if (selected === "jsonl") {
+    content = recordsForFormat(normalized, "jsonl").map((record) => JSON.stringify(record)).join("\n");
+    if (content) content += "\n";
+  } else content = `${JSON.stringify(normalized)}\n`;
+  atomicWrite(target, content, overwrite);
+  return { path: target, records: Array.isArray(normalized) ? normalized.length : 1 };
+}
+
+function emit(value, options = {}) {
+  if (!options.output) {
+    if (options.format) throw usage("--format requires --output");
+    process.stdout.write(`${dumps(value, { limit: options.limit })}\n`);
+    return;
+  }
+  process.stdout.write(`${dumps(exportResult(value, options))}\n`);
+}
+
+module.exports = { dumps, emit, exportResult };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@evatick/cli",
-  "version": "0.3.2",
-  "description": "EVA market data command-line client for LLMs, agents, and automation",
+  "version": "0.4.1",
+  "description": "EVA Tick CLI for deterministic, machine-readable financial data queries by AI agents, LLMs, and automation",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,16 +17,25 @@
   },
   "files": [
     "bin",
+    "lib",
     "README.md",
     "LICENSE"
   ],
   "engines": {
     "node": ">=18"
   },
-  "optionalDependencies": {
-    "@evatick/cli-darwin-arm64": "0.3.2",
-    "@evatick/cli-darwin-x64": "0.3.2",
-    "@evatick/cli-linux-x64": "0.3.2",
-    "@evatick/cli-win32-x64": "0.3.2"
-  }
+  "keywords": [
+    "eva-tick",
+    "financial-data",
+    "market-data",
+    "ai-agent",
+    "llm",
+    "codex",
+    "automation",
+    "quantitative-finance",
+    "openapi",
+    "akshare",
+    "a-share",
+    "china-stock-market"
+  ]
 }