gangtise-openapi-cli 0.34.1 → 0.35.0

package/dist/src/cli.js

@@ -14,44 +14,19 @@ import { fetchFileParseResult, pollFileParseResult, submitFileParse } from "./co
 import { normalizeRows, zipFieldRow } from "./core/normalize.js";
 import { parseOutputFormat } from "./core/output.js";
 import { printData } from "./core/printer.js";
-// --- Lazy-loaded modules (deferred to action handlers) ---
 async function createClient() {
     const { GangtiseClient } = await import("./core/client.js");
     return new GangtiseClient(loadConfig());
 }
-/**
- * Acquire a client, run `produce` to fetch data, and render it through the
- * shared pipeline. Collapses the `createClient()` + `printData(await client.call(...),
- * parseOutputFormat(options.format), options.output)` boilerplate that every
- * query command repeated.
- */
 async function emit(options, produce, cache) {
-    // Validate --format before fetching: a typo'd format must not burn a full
-    // (possibly credit-metered) data pull only to fail at render time.
     const format = parseOutputFormat(options.format);
     const client = await createClient();
     await printData(await produce(client), format, options.output, cache);
 }
-/** Acquire a client and run an arbitrary action (downloads, polling, custom shaping). */
 async function withClient(fn) {
     await fn(await createClient());
 }
-/**
- * Server-side default row cap shared by the limit-capped, non-paginated quote endpoints
- * (fund-flow, minute-kline, day/index kline — all default to 6000 per the API docs). We
- * send it EXPLICITLY when `--limit` is omitted (rather than letting the server apply its
- * own default) so the request limit and the truncation `cap` below are always the same
- * number — never a guess about the server's default that can drift out of sync.
- */
 const DEFAULT_QUOTE_LIMIT = 6000;
-/**
- * Limit-capped, non-paginated endpoints (fund-flow, kline) report `total` as the
- * RETURNED row count, not the true total, so a full page (rows == the limit we sent) is
- * the only truncation signal. Flag the result partial (printData → exit 3) + warn so a
- * capped export isn't mistaken for the full set. `cap` MUST be the exact limit the caller
- * sent on the request; `--limit` is validated to <= 10000 so `cap` can't exceed the
- * server ceiling and hide a truncation.
- */
 function flagIfLimitTruncated(data, cap, label) {
     if (!data || typeof data !== "object" || Array.isArray(data))
         return;
@@ -63,11 +38,6 @@ function flagIfLimitTruncated(data, cap, label) {
         process.stderr.write(`[gangtise] warning: ${label} returned ${rec.list.length} rows = the ${cap}-row limit; results are likely truncated (this endpoint has no pagination). Narrow --start-date/--end-date or raise --limit (max 10000), fetching in date batches.\n`);
     }
 }
-/**
- * Run a download. If `output` is set we already know the destination, so the
- * client streams the body straight to disk (no in-memory Uint8Array copy);
- * otherwise we buffer and let the caller resolve a friendly title.
- */
 async function runDownload(client, endpointKey, query, options) {
     if (options.output) {
         const result = await client.call(endpointKey, options.body, query, { streamTo: options.output });
@@ -76,15 +46,8 @@ async function runDownload(client, endpointKey, query, options) {
     }
     const result = await client.call(endpointKey, options.body, query);
     const resolved = options.resolveOutputPath ? await options.resolveOutputPath(result) : undefined;
-    // Title-derived names are auto-generated too — dedupe them like the fallback names.
     await saveDownloadResult(result, options.fallbackName, resolved ? await uniquePath(resolved) : undefined);
 }
-/**
- * Register a download subcommand. All download commands share one shape: a
- * required id option, optionally --file-type / --content-type, then --output.
- * `idField` doubles as the commander option key and the query/title-cache
- * field, so it must stay the camelCase twin of `idOption`.
- */
 function addDownloadCommand(parent, spec) {
     const cmd = parent.command(spec.name ?? "download").requiredOption(`${spec.idOption} <id>`);
     if (spec.fileType) {
@@ -187,17 +150,6 @@ addTimeFilters(summary.command("list").addOption(new Option("--search-type <numb
     categoryList: maybeArray(options.category), marketList: maybeArray(options.market), participantRoleList: maybeArray(options.participantRole),
 }), { endpointKey: "insight.summary.list", idField: "summaryId" }));
 addDownloadCommand(summary, { endpointKey: "insight.summary.download", idOption: "--summary-id", idField: "summaryId", fallbackPrefix: "summary", fileType: { description: "File type: 1=original(default) 2=HTML; only affects meeting platform summaries", choices: ["1", "2"] }, titleListEndpoint: "insight.summary.list" });
-// Pamirs is one lead institution's expert-summary library, exposed on its own
-// path rather than as a `summary list` filter. It advertises a NARROWER filter
-// set than `summary` — no --source / --institution / --participant-role — so the
-// options are spelled out here instead of sharing summary's builder: an
-// unsupported flag would be dropped server-side and silently widen the result.
-// Every enum is whitelisted locally. The server drops an unrecognised VALUE the
-// same way it drops an unrecognised FIELD — silently, returning the unfiltered
-// set with exit 0. Worse, a bad `--search-type` takes `--keyword` down with it:
-// `--keyword 茅台 --search-type 99` answers 2963 (the whole library) instead of 2,
-// so the caller reads a full-library dump as a keyword hit. Same class of defect
-// that put whitelists on securities-search / institution-search / official-account.
 const PAMIRS_CATEGORIES = ["companyAnalysis", "industryAnalysis"];
 const PAMIRS_MARKETS = ["aShares", "hkStocks", "usChinaConcept", "usStocks"];
 addTimeFilters(pamirsSummary.command("list").description("List Pamirs expert summaries (requires the expert-summary database)").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--research-area <id>", "Research area ID: accepts BOTH industry code sets -- citicIndustry (1008001xx) and swIndustry (104xx0000) -- but NOT gangtiseIndustry direction codes (122000xxx), which return 0 on this endpoint only", collectList, []).option("--security <code>", "Security code, e.g. 000001.SZ", collectList, []).option("--category <name>", `Category: ${PAMIRS_CATEGORIES.join(" / ")}`, collectList, []).option("--market <name>", `Market: ${PAMIRS_MARKETS.join(" / ")}`, collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.pamirs-summary.list", {
@@ -258,20 +210,7 @@ addScheduleList(siteVisit, "insight.site-visit.list", {
 });
 addScheduleList(strategy, "insight.strategy.list", { institution: true, location: true });
 addScheduleList(forum, "insight.forum.list", { researchArea: true, location: true });
-// Earnings calendar: the only insight list filtered by DATE (--start-date/--end-date
-// on publishDate), not by the --start-time datetime every sibling uses — so it does
-// not go through addTimeFilters. It also takes no --keyword / --rank-type / --search-type.
-/** Row ceiling applied when `--security` is the only thing bounding a
- * performance-calendar fetch. Far above any single company's calendar (a whole
- * A-share history is dozens of rows), far below the 50k the auto-pagination
- * would otherwise pull if the server ever stopped honoring securityList. */
 const SECURITY_ONLY_ROW_CAP = 1000;
-/** Warn + mark partial when a `--security`-only fetch lands on the cap with rows
- * still unfetched: that is the signature of a filter that did not narrow anything,
- * and the rows on screen are then a truncated slice of the whole calendar rather
- * than a company's. `total` decides it — a result that happens to be exactly `cap`
- * rows long IS complete (from + rows covers total) and must stay exit 0, or every
- * automated caller reads a full answer as truncated. */
 function flagIfImplicitCapHit(data, cap, from) {
     if (!data || typeof data !== "object" || Array.isArray(data))
         return;
@@ -296,25 +235,12 @@ performanceCalendar.command("list").description("Earnings calendar (业绩预告
     .option("--category <name>", `Event type: ${PERFORMANCE_CATEGORIES.join("/")}`, collectList, [])
     .option("--format <format>", "Output format", "table").option("--output <path>", "Output path")
     .action((options) => {
-    // Enum typos first: a misspelled --category is the likelier mistake, and its
-    // message is the more useful one when both checks would fire.
     const marketList = parseChoiceList(options.market, "--market", PERFORMANCE_MARKETS);
     const categoryList = parseChoiceList(options.category, "--category", PERFORMANCE_CATEGORIES);
-    // Unfiltered, this endpoint holds >120k rows (probed 2026-07-25: 126683, it
-    // also carries FUTURE scheduled events) and an omitted --size means "fetch
-    // everything" — 50k rows at the 1000-page cap, ~5000 credits at 0.1/row.
-    // Require a bound: a full date range, an explicit --size, or a security filter.
     const explicitlyBounded = Boolean(options.size) || Boolean(options.startDate && options.endDate);
     if (!explicitlyBounded && !options.security.length) {
         throw new ValidationError("insight performance-calendar list without a bound would auto-paginate the whole calendar (>120k rows at 0.1 credits each): pass --start-date and --end-date, or --security, or an explicit --size");
     }
-    // --security is only a real bound while the server honors securityList. It does
-    // today (probed 2026-07-25: an unknown or malformed code returns total 0, it is
-    // not silently ignored like a bad enum) — but a five-figure credit bill must not
-    // rest on that staying true. When --security is the ONLY bound, cap the fetch:
-    // one company's whole calendar is dozens of rows, so the cap is invisible in
-    // normal use and turns a filter regression into a truncated result (partial +
-    // exit 3) instead of a 5000-credit pull.
     const implicitCap = explicitlyBounded ? undefined : SECURITY_ONLY_ROW_CAP;
     const from = parseFrom(options.from);
     return emit(options, async (client) => {
@@ -349,12 +275,6 @@ addTimeFilters(foreignReport.command("list").addOption(new Option("--search-type
     minReportPages: parseOptionalNumberOption(options.minPages, "--min-pages", { integer: true, min: 0 }), maxReportPages: parseOptionalNumberOption(options.maxPages, "--max-pages", { integer: true, min: 0 }),
 }), { endpointKey: "insight.foreign-report.list", idField: "reportId" }));
 addDownloadCommand(foreignReport, { endpointKey: "insight.foreign-report.download", idOption: "--report-id", idField: "reportId", fallbackPrefix: "foreign-report", fileType: { description: "File type: 1=PDF 2=Markdown 3=CN-PDF 4=CN-Markdown", choices: ["1", "2", "3", "4"], default: "1" }, titleListEndpoint: "insight.foreign-report.list" });
-// Contract: A-share announcement startTime/endTime go out as 13-digit epoch millis
-// (parseTimestamp13), while HK/US announcement and every other insight list send the
-// datetime string straight through. All three filter correctly — verified live against
-// a narrow past window (each returns in-window rows). A-share's API also accepts the
-// string form, but the 13-digit conversion is kept as the historical spec contract;
-// don't "unify" it away without re-confirming the A-share announcement spec.
 addTimeFilters(announcement.command("list").addOption(new Option("--search-type <number>", "Search type: 1=title 2=fulltext").choices(["1", "2"]).default("1")).addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code", collectList, []).option("--category <id>", "Category ID", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.announcement.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: parseTimestamp13(options.startTime, "--start-time"), endTime: parseTimestamp13(options.endTime, "--end-time"),
@@ -380,7 +300,7 @@ addTimeFilters(announcementUs.command("list").addOption(new Option("--search-typ
     securityList: maybeArray(options.security), categoryList: maybeArray(options.category),
 }), { endpointKey: "insight.announcement-us.list", idField: "announcementId" }));
 addDownloadCommand(announcementUs, { endpointKey: "insight.announcement-us.download", idOption: "--announcement-id", idField: "announcementId", fallbackPrefix: "announcement-us", fileType: { description: "File type: 1=original PDF 2=Markdown", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.announcement-us.list" });
-addTimeFilters(foreignOpinion.command("list").addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code -- UNRELIABLE on this endpoint: cn/us/jp yield a null payload (no error); only gl returns rows. Filter on the region field client-side", collectList, []).option("--industry <id>", "Industry ID -- NOT effective on this endpoint: any value yields a null payload (not an empty list), with no error. Omit it and filter on industryList[] client-side", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-opinion.list", {
+addTimeFilters(foreignOpinion.command("list").addOption(new Option("--rank-type <number>", "Rank type: 1=composite 2=time desc").choices(["1", "2"]).default("1")).option("--security <code>", "Security code (e.g. UBER.N)", collectList, []).option("--region <code>", "Region code -- only 'gl' returns rows on this endpoint; cn/us/jp come back as a null payload with no error. Filter on the region field client-side", collectList, []).option("--industry <id>", "Industry ID -- NOT effective on this endpoint: any value yields a null payload (not an empty list), with no error. Omit it and filter on industryList[] client-side", collectList, []).option("--broker <id>", "Broker ID", collectList, []).option("--rating <name>", "Rating", collectList, []).option("--rating-change <name>", "Rating change", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>", "Output path")).action((options) => emit(options, (client) => client.call("insight.foreign-opinion.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     startTime: options.startTime, endTime: options.endTime,
     rankType: parseNumberOption(options.rankType, "--rank-type", { integer: true, min: 1 }),
@@ -408,8 +328,6 @@ addTimeFilters(officialAccount.command("list").addOption(new Option("--search-ty
     categoryList: maybeArray(options.category), industryList: maybeArray(options.industry),
 }), { endpointKey: "insight.official-account.list", idField: "articleId" }));
 addDownloadCommand(officialAccount, { endpointKey: "insight.official-account.download", idOption: "--article-id", idField: "articleId", fallbackPrefix: "official-account", fileType: { description: "File type: 1=txt(default) 2=HTML", choices: ["1", "2"], default: "1" }, titleListEndpoint: "insight.official-account.list" });
-// QA request keys are BARE (source/questionCategory/answerImportant), not the *List
-// convention — the body below mirrors the spec exactly. Datetimes pass through as strings.
 qa.command("list").requiredOption("--security-code <code>", "Security code, e.g. 601012.SH").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all (max page 500)").option("--start-time <datetime>", "Start time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)", datetimeArg("--start-time")).option("--end-time <datetime>", "End time (yyyy-MM-dd or yyyy-MM-dd HH:mm:ss)", datetimeArg("--end-time")).option("--source <type>", "Source: conference/interactive/survey (repeat)", collectList, []).option("--question-category <name>", "Question category (repeat): productAndBusiness/capacityAndProjects/ordersAndCustomers/financialData/materialEvents/capitalOperations/shareholdersAndDividends/corporateGovernance/marketAndValuation/macroAndIndustry/risksAndOthers", collectList, []).option("--answer-important <flag>", "Answer involves key info: 1=yes 0=no (repeat; omit for all)", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("insight.qa.list", {
     from: parseFrom(options.from), size: parseSize(options.size),
     securityCode: options.securityCode, startTime: options.startTime, endTime: options.endTime,
@@ -443,66 +361,24 @@ program.addCommand(insight);
 const quote = new Command("quote").description("Quote APIs");
 const KLINE_MARKETS = { aShares: 1, hkStocks: 2, usStocks: 1 };
 const LEGACY_ALL_MARKET = (shardDays) => ({ all: shardDays });
-/** Realtime takes the same keywords but returns one snapshot per security, so there is
- * nothing to shard and it only needs the accepted-keyword list. */
 const REALTIME_MARKETS = ["aShares", "hkStocks", "usStocks"];
-/** fund-flow is A-share only, so `aShares` is its sole whole-market keyword. */
 const FUND_FLOW_MARKETS = ["aShares"];
-/** Every keyword the quote APIs have ever taken, including ones a given command no
- * longer accepts. What an unrecognised keyword does depends on the endpoint, and BOTH
- * outcomes are worth a local error: the unified `day-kline` / `realtime` / `fund-flow`
- * answer `120001` "invalid security code" (which sends the user hunting for a typo in a
- * code that is fine), while the menu-retired per-market endpoints answer `code=000000`
- * with `total: 0` — a silent empty result indistinguishable from "no data".
- *
- * Compared lower-cased, and 🔴 **that folding is load-bearing, not tidiness** — the API's
- * own case handling differs BY ENDPOINT (probed 2026-08-15, all six):
- *
- *   folds case:      day-kline (aShares/…), realtime, day-kline-hk/-us/index (all)
- *   case-SENSITIVE:  fund-flow — only the literal `aShares` works; `ashares` / `ASHARES`
- *                    come back as `120001 非有效A股`
- *
- * So on five endpoints canonicalising merely keeps our shard lookup in step with the
- * server (drop it and a case variant degrades to an unsharded 6000-row request), but on
- * `fund-flow` it is the ONLY reason `--security ashares` works at all. Removing
- * `canonicalizeMarketKeywords` would turn that from a working query into a hard error —
- * see the fund-flow case test, which exists to pin exactly that.
- *
- * ⚠️ `all` collides with a real ticker root (`ALL` is Allstate on the NYSE), so a bare
- * `--security ALL` fetches the whole US market instead of that stock. That resolution
- * happens on the SERVER (`ALL` / `All` / `all` are equivalent to it on all three retired
- * endpoints), so matching case-sensitively here would not prevent it — it would only stop
- * us from sharding a request the server treats as whole-market anyway, turning a complete
- * result into a 6000-row truncation. The fix for that user is the suffixed `ALL.N`.
- *
- * Unknown keywords are deliberately NOT rejected — this is a known-keyword list, so a
- * future server-side addition degrades to "unsharded" rather than being refused outright
- * (fail-open, no enum drift). */
 const MARKET_KEYWORDS = new Set(["all", "ashares", "hkstocks", "usstocks"]);
 const matchesMarketKeyword = (value, keyword) => value.toLowerCase() === keyword.toLowerCase();
 const checkMarketKeywords = (securities, accepted, command) => {
     const used = securities.filter((s) => MARKET_KEYWORDS.has(s.toLowerCase()));
     if (used.length === 0)
         return;
-    // Report an unsupported keyword before the alone-ness rule: when both are wrong, the
-    // keyword itself is the thing the user has to change.
     const unsupported = used.filter((k) => !accepted.some((a) => matchesMarketKeyword(k, a)));
     if (unsupported.length > 0) {
         throw new ValidationError(accepted.length > 0
             ? `${command}: '${unsupported[0]}' is not a whole-market keyword for this command — use ${accepted.join(" / ")}`
             : `${command}: this command takes explicit security codes only — '${unsupported[0]}' and other whole-market keywords are not supported`);
     }
-    // The API rejects a keyword sent alongside security codes or a second keyword, again
-    // as a bare 120001 that points at the codes rather than at the combination. On
-    // `fund-flow` it is worse than a rejection: the keyword is silently dropped and only
-    // the explicit codes come back, exit 0.
     if (securities.length > 1) {
         throw new ValidationError(`${command}: a market keyword must be passed alone, got '${securities.join(", ")}' — the API rejects it mixed with security codes or another keyword`);
     }
 };
-/** Fold a user-typed keyword back to the spelling the sharding lookup expects, so a case
- * variant reaches the same code path as the canonical form. Non-keywords pass through
- * untouched. */
 const canonicalizeMarketKeywords = (securities, accepted) => securities.map((s) => accepted.find((a) => matchesMarketKeyword(s, a)) ?? s);
 const addKlineCommand = (name, endpointKey, securityHelp, markets) => quote.command(name)
     .option("--security <code>", securityHelp, collectList, [])
@@ -513,30 +389,18 @@ const addKlineCommand = (name, endpointKey, securityHelp, markets) => quote.comm
     .option("--format <format>", "Output format", "table")
     .option("--output <path>")
     .action((options) => {
-    // Validate BEFORE withClient: createClient() logs in when no token is cached, so a
-    // check inside the callback would spend a request to then fail locally anyway.
     checkMarketKeywords(options.security, Object.keys(markets), `quote ${name}`);
     options.security = canonicalizeMarketKeywords(options.security, Object.keys(markets));
     return withClient(async (client) => {
         const format = parseOutputFormat(options.format);
         const body = buildQuoteKlineBody(options);
-        // Each market shards at its own granularity, so resolve which keyword was asked
-        // for before picking shardDays — a whole-market HK pull tolerates 2-day windows
-        // where A-share and US pulls need one day each.
         const keyword = Object.keys(markets).find((k) => isFullMarket(body, k));
         if (keyword) {
-            // A whole-market query is date-sharded: callKlineWithSharding lifts the limit to
-            // the API max and owns completeness (partial / failedShards), so leave `limit`
-            // unset and skip the single-request truncation guard.
             const data = await callKlineWithSharding(client, endpointKey, body, { shardDays: markets[keyword], fullMarketValue: keyword });
             await printData(data, format, options.output);
             return;
         }
-        // Explicit securities go out as one request: pin the limit to the known default so
-        // the sent limit and the truncation cap are the same number by construction.
         const limit = body.limit ?? DEFAULT_QUOTE_LIMIT;
-        // (Nothing to shard: sharding only ever applied to whole-market queries, so this
-        // is exactly the passthrough callKlineWithSharding would have done.)
         const data = await client.call(endpointKey, { ...body, limit });
         flagIfLimitTruncated(data, limit, name);
         await printData(data, format, options.output);
@@ -545,10 +409,6 @@ const addKlineCommand = (name, endpointKey, securityHelp, markets) => quote.comm
 addKlineCommand("day-kline", "quote.day-kline", "Security code — A-share .SH/.SZ/.BJ, HK .HK, US .O/.N/.A, exchange index .SH/.SZ/.BJ, concept index .GT, industry index .CI/.SWI; or one market keyword: aShares / hkStocks / usStocks (auto-sharded by date, must be passed alone)", KLINE_MARKETS);
 addKlineCommand("day-kline-hk", "quote.day-kline-hk", "[deprecated: use 'day-kline'] Security code (HK stock: .HK, or 'all' for full market)", LEGACY_ALL_MARKET(2));
 addKlineCommand("day-kline-us", "quote.day-kline-us", "[deprecated: use 'day-kline'] Security code (US stock: e.g. AAPL.O, or 'all' for full market)", LEGACY_ALL_MARKET(1));
-// 15 days, not the historical 30: ~531 index rows per trading day x ~11 trading days in a
-// 15-day window is ~5.8K, while a 30-day window is ~11.7K — every shard silently maxed out
-// at the 10K cap and lost ~11% of the range (it surfaced as exit 3 + truncatedShards, but
-// the split was never sized to avoid it in the first place).
 addKlineCommand("index-day-kline", "quote.index-day-kline", "[deprecated: use 'day-kline'] Index code (.SH/.SZ/.BJ, or 'all' for full market)", LEGACY_ALL_MARKET(15));
 quote.command("minute-kline").option("--security <code>", "Security code — A-share .SH/.SZ (SH/SZ only), exchange index .SH/.SZ, concept index .GT, industry index .CI/.SWI; no whole-market keyword").option("--start-time <datetime>", "Start time (yyyy-MM-dd HH:mm:ss)", datetimeArg("--start-time")).option("--end-time <datetime>", "End time (yyyy-MM-dd HH:mm:ss)", datetimeArg("--end-time")).option("--limit <number>", "Max rows per request (default: 6000, max: 10000)").option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
@@ -558,17 +418,10 @@ quote.command("minute-kline").option("--security <code>", "Security code — A-s
     await printData(data, format, options.output);
 }));
 quote.command("realtime").description("Realtime quote snapshot (A-share / HK / US stocks and indices)").option("--security <code>", "Security code — stock .SH/.SZ/.BJ/.HK/.O/.N/.A, exchange index .SH/.SZ/.BJ, concept index .GT, industry index .CI/.SWI; or one market keyword: aShares / hkStocks / usStocks (must be passed alone; indices have no whole-market keyword)", collectList, []).option("--field <field>", "Field", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => {
-    // Realtime takes the same market keywords as day-kline but never shards (one snapshot
-    // per security), so it only needs the "alone, and a keyword this API knows" check.
     checkMarketKeywords(options.security, REALTIME_MARKETS, "quote realtime");
     return emit(options, (client) => client.call("quote.realtime", { securityList: maybeArray(options.security), fieldList: maybeArray(options.field) }));
 });
 quote.command("fund-flow").description("A-share daily fund flow (SH/SZ/BJ)").option("--security <code>", "Security code (e.g. 600519.SH / 872931.BJ), or 'aShares' for full A-share market — auto-sharded by day (repeat)", collectList, []).option("--start-date <date>", "Start date yyyy-MM-dd (default: endDate minus 1 year)", dateArg("--start-date")).option("--end-date <date>", "End date yyyy-MM-dd (default: latest trading day)", dateArg("--end-date")).option("--limit <number>", "Max rows per request (default: 6000, max: 10000; single-security cap — aShares auto-shards by day)").option("--field <field>", "Field, e.g. mainNetInflow/largeInflow/xlargeOutflow (repeat); omit for all", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => {
-    // fund-flow needs this guard MORE than the kline commands, not less: mixing the keyword
-    // with codes doesn't even fail here. The server silently drops `aShares` and answers
-    // with just the explicit codes — one row, exit 0, no warning — so "whole market plus
-    // this one" quietly becomes "only this one". Validate before withClient so no login
-    // request is spent on a query that fails locally.
     checkMarketKeywords(options.security, FUND_FLOW_MARKETS, "quote fund-flow");
     options.security = canonicalizeMarketKeywords(options.security, FUND_FLOW_MARKETS);
     return withClient(async (client) => {
@@ -581,11 +434,6 @@ quote.command("fund-flow").description("A-share daily fund flow (SH/SZ/BJ)").opt
             fieldList: maybeArray(options.field),
         };
         if (isFullMarket(body, "aShares")) {
-            // Full-market fund-flow: the server errors (430012/430013) instead of truncating when
-            // a single request exceeds the row cap, so date-shard by day (~5.4k A-share rows/day,
-            // under the lifted API cap) and merge — same mechanism as `--security all` kline.
-            // Sharding needs an explicit range; without both dates it would fall back to one
-            // doomed full-market request, so require the range up front with a clear message.
             if (!body.startDate || !body.endDate) {
                 throw new ValidationError("quote fund-flow --security aShares requires both --start-date and --end-date (the full market is fetched via per-day shards)");
             }
@@ -637,8 +485,6 @@ fundamental.command("valuation-analysis").requiredOption("--security-code <code>
 fundamental.command("top-holders").requiredOption("--security-code <code>").addOption(new Option("--holder-type <type>", "Holder type: top10/top10Float").choices(["top10", "top10Float"]).makeOptionMandatory()).option("--start-date <date>", "Start date (yyyy-MM-dd)", dateArg("--start-date")).option("--end-date <date>", "End date (yyyy-MM-dd)", dateArg("--end-date")).option("--fiscal-year <year>", "Fiscal year", collectList, []).option("--period <period>", "Period: q1/interim/q3/annual/latest", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("fundamental.top-holders", { securityCode: options.securityCode, holderType: options.holderType, startDate: options.startDate, endDate: options.endDate, fiscalYear: maybeArray(options.fiscalYear), period: options.period.length ? options.period : undefined })));
 fundamental.command("earning-forecast").requiredOption("--security-code <code>").option("--start-date <date>", "Start date (default: 1 year before end-date)", dateArg("--start-date")).option("--end-date <date>", "End date (default: today)", dateArg("--end-date")).option("--consensus <name>", "Consensus indicator: netIncome/netIncomeYoy/eps/pe/bps/pb/peg/roe/ps", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => {
     const endDate = options.endDate ?? localDateString(new Date());
-    // Anchor the default window to endDate (as the help text promises), not to today —
-    // a historical --end-date without --start-date should mean "the year before it".
     const startDate = options.startDate ?? new Date(new Date(`${endDate}T00:00:00Z`).getTime() - 365 * 24 * 60 * 60 * 1000).toISOString().slice(0, 10);
     return client.call("fundamental.earning-forecast", { securityCode: options.securityCode, startDate, endDate, consensusList: maybeArray(options.consensus) });
 }));
@@ -676,8 +522,6 @@ ai.command("earnings-review").requiredOption("--security-code <code>").requiredO
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
     const outcome = await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, format, options.output);
     if (outcome !== "ok") {
-        // "failed" already printed its terminal "Do not retry" line — only a timeout
-        // gets the retry hint.
         if (outcome === "timeout") {
             process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
         }
@@ -737,12 +581,8 @@ ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint t
 }));
 ai.command("viewpoint-debate-check").requiredOption("--data-id <id>", "dataId from viewpoint-debate").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => withClient((client) => checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseOutputFormat(options.format), options.output)));
 ai.command("stock-summary").description("Stock highlights: refined research summary per security (A-share / HK)").option("--security <code>", "Security code (e.g. 600519.SH / 00700.HK), up to 6000 per call; market keywords are NOT supported by this endpoint", collectList, []).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => {
-    // Guard against an empty --security: omitting it would send securityList:undefined,
-    // which the backend may treat as all-market (3 credits/row × thousands of rows).
     if (!options.security.length)
         throw new ValidationError("--security is required: pass one or more security codes (A-share / HK), up to 6000 per call");
-    // The endpoint dropped whole-market batches on 2026-08-14 and now answers a market
-    // keyword with 120001 "invalid security code" — which reads as a typo in the code.
     checkMarketKeywords(options.security, [], "ai stock-summary");
     return emit(options, (client) => client.call("ai.stock-summary.list", { securityList: maybeArray(options.security) }));
 });
@@ -772,7 +612,6 @@ reference.command("institution-search").requiredOption("--keyword <text>", "Sear
     categoryList: parseChoiceList(options.category, "--category", ["domesticBroker", "foreignInstitution", "leadInstitution", "opinionInstitution", "foreignOpinionInstitution"]),
     top: parseNumberOption(options.top, "--top", { integer: true, min: 1, max: 10 }),
 })));
-// Note: request key is BARE `category` here (spec), unlike institution-search's `categoryList`.
 reference.command("official-account-search").requiredOption("--keyword <text>", "Search keyword (account name / institution / keyword, e.g. 东吴证券)").option("--category <name>", "Category: listedCompany/broker/government/media (repeat); omit for all incl. uncategorized", collectList, []).option("--top <number>", "Max results (default: 10, max: 10)", "10").option("--format <format>", "Output format", "table").option("--output <path>").action((options) => emit(options, (client) => client.call("reference.official-account-search", {
     keyword: options.keyword,
     category: parseChoiceList(options.category, "--category", ["listedCompany", "broker", "government", "media"]),
@@ -815,29 +654,7 @@ alternative.command("edb-data").option("--indicator-id <id>", "Indicator ID (rep
 alternative.command("concept-info").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-info", { conceptId: options.conceptId })));
 alternative.command("concept-securities").requiredOption("--concept-id <id>", "Concept (theme index) ID, e.g. 121000130 机器人; discover via 'gangtise reference concept-search'").option("--format <format>", "Output format", "json").option("--output <path>").action((options) => emit(options, (client) => client.call("alternative.concept-securities", { conceptId: options.conceptId })));
 program.addCommand(alternative);
-/** Mark and report the request codes the server did not answer for at all.
- *
- * What this catches changed on the server. EDE used to drop any axis it had no
- * DATA for — an indicator empty for every security vanished from
- * `indicatorList`, a security empty for every indicator vanished from
- * `securityCodeList`. Re-probed 2026-08-08: a coverage gap is now padded with
- * `null` and keeps its row and column (`mgn_bal` × 00700.HK, `finc_pb_mrq` ×
- * 09992.HK — both null, both present, even as the only cell in the request).
- *
- * A code the server cannot RESOLVE still vanishes: an unknown indicator code, or
- * a security code with the wrong suffix (`AAPL.US`, whose real form is
- * `AAPL.O`). So this is now a typo detector rather than a coverage detector —
- * which is the more useful of the two, since a coverage gap is visible as `null`
- * but a misspelled code is otherwise invisible: exit code 0, a plausible-looking
- * table, and a `--key-by code` mapping whose key simply is not there.
- *
- * Same signal as a failed page or a row cap: `partial` on the payload (printData
- * → exit 3) plus the omitted codes, so an automated caller can react without
- * parsing stderr. */
 function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
-    // A wholly empty response is not a partial one: the diff against the request
-    // would list everything as "omitted", which says nothing about which axis is
-    // at fault. Exit 0, but say why it is ambiguous.
     if (isEmptyMatrix(data)) {
         process.stderr.write("[gangtise] note: the query returned no data at all. Since a real coverage gap now comes back as a null cell rather than an empty table, this usually means NOTHING in the request resolved — every security code or every indicator code was unrecognised — or a parameter name is wrong. Cross-check codes against 'gangtise indicator search --format json' and 'gangtise reference securities-search'.\n");
         return;
@@ -860,11 +677,6 @@ function flagDropped(rows, data, requestedSecurities, requestedIndicators) {
         parts.push(`securities ${securities.join(", ")}`);
     process.stderr.write(`[gangtise] warning: the response omits ${parts.join(" and ")} entirely — no row/column at all, not a null one. A code the server merely has no data for still comes back as null, so this normally means the code itself was not recognised: check it for typos and, for securities, for the wrong market suffix (US tickers are .O/.N, not .US). Result marked partial (exit 3).\n`);
 }
-/** `--indicator` / `--security` are repeatable, so Commander cannot mark them
- * required — but every matrix endpoint needs at least one of each and answers a
- * missing one with 100001, whose hint sends the user to `--help`, which in turn
- * showed them as optional with a `[]` default. Catch it here: no request, no
- * round trip, and a message that names the flag. */
 function requireIndicatorScope(indicators, securities) {
     const missing = [indicators.length === 0 ? "--indicator" : "", securities.length === 0 ? "--security" : ""].filter(Boolean);
     if (missing.length > 0) {
@@ -880,13 +692,11 @@ indicator.command("search").requiredOption("--keyword <text>", "Search keyword,
     });
     await printData(unwrapIndicatorData(raw), format, options.output);
 }));
-indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate. Report-period indicators (is_*, financial statements) REJECT tradeDate and require --indicator-param 'code:reportDate=yyyy-MM-dd' instead — check parameterList in 'indicator search'", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+indicator.command("cross-section").option("--indicator <code>", "Indicator code, e.g. qte_close (REQUIRED, repeat for multiple)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as each indicator's tradeDate. Report-period indicators (is_*, financial statements) REJECT tradeDate and require --indicator-param 'code:reportDate=yyyy-MM-dd' instead — check parameterList in 'indicator search'", dateArg("--date")).option("--currency <code>", "Currency: DFT/CNY/HKD/USD/EUR/GBP/JPY/TWD/MOP/AUD (default DFT)").option("--scale <code>", "Scale: 0=个 3=千 4=万 6=百万 8=亿 9=十亿 (default 0)").option("--indicator-param <spec>", "Per-indicator param 'code:key=value', e.g. qte_close:adjustType=2 for 前复权 (repeat); read exact keys from 'indicator search'. Bare 'code:' (nothing after the colon) declares the indicator takes NO date — required by any indicator whose parameterList has no date key at all, which otherwise rejects the tradeDate --date injects: the pty_* / scr_* static-attribute families (pty_op_scope, scr_exchg_mkt, scr_isin …), plus div_cash_paid_ratio / div_cash_yr (add 'code:fiscalYear=YYYY' too) and pty_shr_reg. It composes with real params, so 'code:' + 'code:scale=8' keeps the scale", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode, unique & order-stable for batch code→value mapping").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.cross-section", buildIndicatorCrossSectionBody(options));
     const data = requireIndicatorMatrix(raw);
-    // Flatten first: a shape error must not be preceded by a dropped-rows warning
-    // that reads like the run merely came back short.
     const rows = flattenCrossSection(data, options.keyBy);
     flagDropped(rows, data, options.security, options.indicator);
     await printData(rows, format, options.output);
@@ -896,56 +706,23 @@ indicator.command("time-series").option("--indicator <code>", "Indicator code, e
     requireIndicatorScope(options.indicator, options.security);
     const raw = await client.call("indicator.time-series", buildIndicatorTimeSeriesBody(options));
     const data = requireIndicatorMatrix(raw);
-    // Pass the universe itself, not a count: flattenTimeSeries needs to know
-    // whether a sector ID is in play (the server expands it, so one entry can mean
-    // many securities) and dedupes internally. The request only breaks the tie when
-    // the response is 1×1 anyway. Flatten before flagging so a shape error surfaces
-    // on its own.
     const rows = flattenTimeSeries(data, options.keyBy, options.security);
     flagDropped(rows, data, options.security, options.indicator);
     await printData(rows, format, options.output);
 }));
-indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (REQUIRED, repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — omitting it leaves date-bearing indicators unfiltered and silently yields an empty screen. Report-period indicators (is_*) reject tradeDate: give them --indicator-param 'F1:reportDate=yyyy-MM-dd'", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
+indicator.command("screener").description("Screen securities by an expression over indicator values (条件选股)").option("--indicator <spec>", "Bind a variable to an indicator, 'F1:code', e.g. F1:qte_mkt_cptl (REQUIRED, repeat)", collectList, []).option("--security <code>", "Security code, e.g. 600519.SH, or a sector ID from 'gangtise reference sector-search' (REQUIRED, repeat; union, deduped)", collectList, []).requiredOption("--expression <expr>", "Filter over the bound variables, e.g. 'F1 >= 800 && (F2 >= 20 && F2 <= 30)'; also supports contains/notcontains on string indicators").requiredOption("--date <date>", "Data date (yyyy-MM-dd); sent as every indicator's tradeDate unless it already has one — omitting it leaves date-bearing indicators unfiltered and silently yields an empty screen. Report-period indicators (is_*) reject tradeDate: give them --indicator-param 'F1:reportDate=yyyy-MM-dd'", dateArg("--date")).option("--indicator-param <spec>", "Per-variable param 'F1:key=value', e.g. F1:scale=8 (repeat); read exact keys from 'indicator search'. The cross-section no-date opt-out ('F1:' with nothing after the colon) is REJECTED here: an indicator sent with no parameters does not take part in the screen and the query comes back as 0 rows with no error, so indicators whose parameterList has no date key (the pty_* / scr_* families, div_cash_yr, pty_shr_reg) cannot be screened on at all — read them with 'indicator cross-section' and filter client-side", collectList, []).addOption(new Option("--key-by <mode>", "Column key: name=display name (default) | code=indicatorCode").choices(["name", "code"]).default("name")).option("--format <format>", "Output format", "table").option("--output <path>").action((options) => withClient(async (client) => {
     const format = parseOutputFormat(options.format);
     requireIndicatorScope(options.indicator, options.security);
-    // Binding one indicator code to several variables (the same price on two
-    // dates) is supported: the server used to answer every such binding from the
-    // EARLIEST date among them and null the rest, which made the whole result
-    // untrustworthy and needed an `unreliable` flag. Re-probed 2026-08-08 — fixed:
-    // each variable now carries its own date's value, stable across repeats.
     const bindings = parseScreenerIndicators(options.indicator, options.indicatorParam, options.expression);
     const raw = await client.call("indicator.screener", buildIndicatorScreenerBody(options));
-    // Same payload shape as cross-section (one row per matched security, one
-    // column per indicator) with a `field` on each indicator entry. No dropped-row
-    // flag here: a security missing from a screener result means it failed the
-    // filter, which is the whole point.
     const data = requireIndicatorMatrix(raw);
-    // Before anything is rendered: the returned bindings must be the ones that
-    // were asked for, and the expression must still be evaluable from the columns
-    // that came back — otherwise the rows cannot be shown to satisfy the
-    // conditions they claim to. See checkScreenerBindings for how a missing column
-    // is weighed against the expression's boolean structure.
-    // Flatten first: it asserts the payload's structural axes, and a response
-    // missing `indicatorList` outright deserves that diagnosis rather than being
-    // reported as a binding problem. Nothing renders in between, so ordering the
-    // structural check ahead of the semantic one is free.
     const rows = flattenCrossSection(data, options.keyBy);
     const filteredOn = screenerExpressionFields(options.expression);
     const unbound = checkScreenerBindings(data, bindings, options.expression);
-    // Same ambiguity as the other matrix commands: an empty screen is a normal
-    // answer AND what a wrong parameter name produces. Keyed on "nothing matched"
-    // rather than the strict canonical-empty shape — a response that returns zero
-    // securities while still echoing `indicatorList` is just as empty to the
-    // caller, and just as ambiguous, but would slip past isEmptyMatrix.
-    // flattenCrossSection above already asserted this is an array of non-empty
-    // strings, so only its length is left to read.
     if (data.securityCodeList.length === 0) {
         process.stderr.write("[gangtise] note: nothing matched the expression. That is a normal answer — but an empty result is ALSO what an unrecognised code or a wrong parameter name produces. Cross-check the indicator codes and parameters against 'gangtise indicator search --format json'.\n");
     }
     if (unbound.length > 0) {
-        // Whatever reached here still leaves the expression evaluable (or was never
-        // read by it), so the rows stand: losing the column costs information, not
-        // correctness, and it degrades rather than failing.
         const rec = rows;
         rec.partial = true;
         rec.omittedIndicators = unbound.map((field) => bindings.find((b) => b.field === field)?.indicatorCode ?? field);
@@ -972,8 +749,6 @@ tool.command("file-parse").description("Parse a PDF into Markdown + images (asyn
     }
     process.stderr.write(`Got taskId: ${taskId}, waiting for the parse to finish...\n`);
     if (await pollFileParseResult(client, taskId, options.output) !== "ok") {
-        // Fetching the result is free and the task keeps running server-side —
-        // re-checking later costs nothing, resubmitting re-bills the whole file.
         process.stderr.write(`Parse result not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise tool file-parse-check --task-id ${taskId}\n`);
         process.exitCode = 1;
     }
@@ -1003,11 +778,7 @@ program.command("raw").description("Raw API calls").addCommand(new Command("call
             throw new ConfigError(`Invalid JSON in --body: ${options.body}`);
         }
     }
-    // Fail loudly on arguments the endpoint kind can't use — they used to be
-    // silently dropped, leaving the user to puzzle over server-side errors.
     if (endpoint.kind === "download") {
-        // POST download endpoints (file-parse result) take their parameters as a JSON
-        // body; GET ones take --query and can't carry a body at all.
         if (body !== undefined && endpoint.method !== "POST") {
             throw new ValidationError(`--body is not supported for GET download endpoints (use --query key=value); ${endpointKey} is kind=download`);
         }
@@ -1028,29 +799,15 @@ async function checkForUpdate(timeoutMs = 2000) {
     try {
         const response = await fetch("https://registry.npmjs.org/gangtise-openapi-cli/latest", { signal: AbortSignal.timeout(timeoutMs) });
         const latest = (await response.json()).version;
-        // Ordered compare, not inequality: during the just-published window the
-        // registry still serves the PREVIOUS version — don't suggest a "downgrade".
         if (latest && isVersionNewer(latest, CLI_VERSION)) {
             process.stderr.write(`Update available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
         }
     }
-    catch { /* best-effort: offline or a slow registry must not break --version */ }
+    catch { }
 }
-/** Last-resort reporting for anything that escapes main()'s try/catch: an error
- * thrown inside an event callback or a rejected promise nobody awaited. Node's
- * default is a multi-line crash dump on stdout/stderr AND a non-zero exit — so a
- * command whose data was already printed correctly would end up looking like a
- * hard failure, with a stack trace where a message belongs. This release is
- * about exit codes meaning what they say; that is the one path that lies.
- *
- * The stack is kept behind --verbose: reaching here at all means a CLI bug
- * rather than an API failure, and one line is not enough to locate one. */
-/** Milliseconds to let already-queued stdout reach the pipe before leaving. */
 const FATAL_FLUSH_MS = 200;
 let leaving = false;
 function reportFatal(error) {
-    // `error.stack` already opens with "Name: message" — printing both duplicates
-    // the first line.
     const stack = error instanceof Error ? error.stack : undefined;
     const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error);
     const text = `${isVerbose() && stack ? stack : message}\n`;
@@ -1060,17 +817,6 @@ function reportFatal(error) {
     }
     leaving = true;
     process.exitCode = 1;
-    // Terminating is not optional: a fatal error with a live handle (a timer, an
-    // open socket) would otherwise keep the process running forever on `exitCode`
-    // alone. But `process.exit()` on the spot truncates whatever is still queued —
-    // to a pipe BOTH streams are written asynchronously — and a handler meant to
-    // stop this release from lying about exit codes must not start dropping output
-    // to do it. So wait for the diagnostic itself AND for anything stdout still
-    // owes, each bounded by the same deadline.
-    //
-    // stderr is not merely "check the length": the write is issued right here, so
-    // its callback is the only thing that knows when it actually reached the pipe.
-    // Exiting on the spot truncated a large diagnostic to one 64 KiB buffer.
     let pending = 1;
     const leave = () => { if (--pending === 0)
         process.exit(1); };
@@ -1083,12 +829,6 @@ function reportFatal(error) {
 }
 process.on("uncaughtException", reportFatal);
 process.on("unhandledRejection", reportFatal);
-/** Teardown races on a closed stdout: the reader went away, which is not this
- * process's failure. `gangtise ... | head` is the everyday case — it truncates
- * the output and still exits 0, so a same-class race has no principled reason to
- * exit 1. Without a handler the final write crashes Node with an unhandled
- * 'error' event; rethrowing from this callback did the same by another route
- * (a crash dump appended AFTER the correct JSON had already been written). */
 const READER_GONE = new Set(["EPIPE", "ERR_STREAM_DESTROYED", "EBADF"]);
 process.stdout.on("error", (error) => {
     if (error?.code && READER_GONE.has(error.code))
@@ -1096,8 +836,6 @@ process.stdout.on("error", (error) => {
     reportFatal(error);
 });
 async function main() {
-    // Positional check, not argv.includes: "--version" appearing later (e.g. as
-    // another option's value) must not short-circuit the whole command.
     const firstArg = process.argv[2];
     if (firstArg === "--version" || firstArg === "-V") {
         process.stdout.write(`${CLI_VERSION}\n`);
@@ -1110,8 +848,6 @@ async function main() {
     catch (error) {
         if (error instanceof ApiError) {
             const hint = error.hint ? ` ${error.hint}` : "";
-            // traceId is what Gangtise support needs to look a failure up; without it a
-            // 999999 report is unactionable on their side.
             const trace = error.traceId ? ` [trace ${error.traceId}]` : "";
             process.stderr.write(`API error${error.code ? ` (${error.code})` : ""}${trace}: ${error.message}${hint}\n`);
             process.exitCode = 1;