gangtise-openapi-cli 0.34.1 → 0.35.0

package/dist/src/core/args.js

@@ -1,7 +1,5 @@
 import { ValidationError } from "./errors.js";
 export function splitCsv(value) {
-    // Also split on full-width "，": voice-input IMEs produce it, and an unsplit
-    // "600519，000858" goes to the API as one bogus code with no local hint.
     return value
         .split(/[,，]/)
         .map((item) => item.trim())
@@ -62,9 +60,6 @@ export function collectKeyValue(value, previous = {}) {
 export function maybeArray(value) {
     return value.length > 0 ? value : undefined;
 }
-/** True when `latest` is strictly newer than `current` (numeric per-segment
- * compare). Plain inequality would nag "update available" during the
- * just-published window while the registry still serves the previous version. */
 export function isVersionNewer(latest, current) {
     const parse = (v) => v.split(".").map(Number);
     const a = parse(latest);
@@ -79,9 +74,6 @@ export function isVersionNewer(latest, current) {
     }
     return false;
 }
-// Whitelist for enum-valued repeatable options. Only used where the server was
-// probed NOT to reject bad values (it silently ignores the filter or returns
-// empty instead) — endpoints that answer 100003 keep server-side validation.
 export function parseChoiceList(values, optionName, allowed) {
     for (const value of values) {
         if (!allowed.includes(value)) {
@@ -91,40 +83,10 @@ export function parseChoiceList(values, optionName, allowed) {
     return maybeArray(values);
 }
 const YYYY_MM_DD = /^\d{4}-\d{2}-\d{2}$/;
-/**
- * Strict `YYYY-MM-DD` guard for Quote/Fundamental date options.
- *
- * Beyond the documented shape the server accepts two extra year-last formats
- * whose day/month order is *opposite* to each other (probed 2026-07-20 on
- * quote/kline/daily and fundamental/balance-sheet; other groups sharing these
- * flags were not probed, so the guard is applied uniformly as the safe default):
- *
- *   "07/01/2026" -> 2026-01-07   slash  reads DD/MM/YYYY
- *   "07-01-2026" -> 2026-07-01   hyphen reads MM-DD-YYYY
- *
- * Same three digits, six months apart, both HTTP 200, and nothing in the
- * response echoes which date the server actually used. Confirmed by the
- * complement: "25/12/2026" parses while "12/25/2026" errors, and the hyphen
- * forms behave exactly the other way round. Since the CLI cannot know which
- * reading was meant, it forwards only the unambiguous form.
- *
- * Other unambiguous shapes (`20260701`, `2026/07/01`) are rejected too, even
- * though the server handles them — one accepted form beats a per-shape allowlist
- * that has to be re-probed per endpoint group. The message says which form is
- * wanted rather than claiming the input itself was ambiguous.
- *
- * Datetime options (`--start-time`) are guarded separately: pass-through ones by
- * `parseDatetimeOption` (a timezone-free field check that returns the string as-is),
- * and the two conversion endpoints (A-share announcement / knowledge-batch) by
- * `parseTimestamp13`.
- */
 export function parseDateOption(value, optionName) {
     if (!YYYY_MM_DD.test(value)) {
-        throw new ValidationError(`Invalid ${optionName}: expected YYYY-MM-DD, got "${value}" — only that form is forwarded; some endpoints silently misread other layouts (e.g. "07/01/2026") as a different day`);
+        throw new ValidationError(`Invalid ${optionName}: expected YYYY-MM-DD, got "${value}" — only that form is forwarded as-is; on some endpoints other layouts (e.g. "07/01/2026") are read as a different day`);
     }
-    // Shape alone lets 2026-02-30 / 2026-13-01 through; round-trip to reject those.
-    // Built from the ISO string, not Date.UTC(y,...), whose two-digit-year mapping
-    // would turn a valid year 0050 into 1950 and report it as a non-existent date.
     const [year, month, day] = value.split("-").map(Number);
     const parsed = new Date(`${value}T00:00:00Z`);
     if (parsed.getUTCFullYear() !== year || parsed.getUTCMonth() !== month - 1 || parsed.getUTCDate() !== day) {
@@ -132,24 +94,10 @@ export function parseDateOption(value, optionName) {
     }
     return value;
 }
-/** Commander argParser factory — `.option("--start-date <date>", desc, dateArg("--start-date"))`. */
 export function dateArg(optionName) {
     return (value) => parseDateOption(value, optionName);
 }
-/** `yyyy-MM-dd` with an optional ` HH:mm[:ss]` / `THH:mm[:ss]` tail. Anything else
- * is rejected rather than handed to `new Date()`: V8's fallback parser accepts the
- * same year-last shapes the server does but reads them the OTHER way round —
- * `07/01/2026` is July 1 to V8 and January 7 to the server, `25/12/2026` is invalid
- * to V8 and valid to the server (both probed 2026-07-20). Since `announcement list`
- * converts locally while its HK/US siblings pass the string through, an open
- * fallback made the same flag mean two dates six months apart across sibling
- * commands, silently and with exit 0. */
 const LOCAL_DATETIME = /^(\d{4})-(\d{2})-(\d{2})(?:[ T](\d{2}):(\d{2})(?::(\d{2}))?)?$/;
-/** Field-level datetime validation, timezone-free — a real calendar day plus a
- * valid clock time, judged by arithmetic alone (no Date construction, so no
- * dependence on the client's timezone or DST). This is what the pass-through guard
- * needs: a string the CLI forwards verbatim must be judged on its fields, not on
- * whether the local zone happens to contain that wall-clock instant. */
 function datetimeFieldsValid(value) {
     const parts = LOCAL_DATETIME.exec(value);
     if (!parts)
@@ -164,12 +112,6 @@ function datetimeFieldsValid(value) {
         return false;
     return Number(hh) <= 23 && Number(mi) <= 59 && Number(ss) <= 59;
 }
-/** A 10-digit seconds or 13-digit millis epoch, normalized to millis. Judged by
- * digit count, NOT magnitude: a `> 1e12` test sends a real 13-digit `1000000000000`
- * (which equals 1e12) down the seconds branch, and lets Number() coerce scientific
- * / hex / whitespace-padded / 11–12–14-digit inputs through as a "timestamp" — all
- * of which then convert wrong or get rejected by the server. Exactly 10 or 13
- * digits, nothing else. */
 function epochMillis(value) {
     if (/^\d{13}$/.test(value))
         return Number(value);
@@ -185,17 +127,10 @@ export function toTimestamp13(value) {
         return ts;
     if (!datetimeFieldsValid(value))
         return undefined;
-    // `new Date("yyyy-MM-dd")` parses as UTC midnight while `new Date("yyyy-MM-dd
-    // HH:mm:ss")` parses as local time — for CST users the two forms would differ by 8
-    // hours. Build from local components so both mean the same wall-clock day.
     const parts = LOCAL_DATETIME.exec(value);
     const [, y, mo, d, hh = "0", mi = "0", ss = "0"] = parts;
     const year = Number(y);
     const dt = new Date(year, Number(mo) - 1, Number(d), Number(hh), Number(mi), Number(ss));
-    // Full round-trip on every field: rejects the two inputs that cannot convert
-    // faithfully — the two-digit-year remap (new Date(50,…) → 1950) and a DST gap (a
-    // wall-clock time the local zone skips: 02:30 on a US spring-forward morning, or
-    // 02:15 in Lord Howe's 30-minute gap, which only a minute-level check catches).
     const faithful = dt.getFullYear() === year && dt.getMonth() === Number(mo) - 1
         && dt.getDate() === Number(d) && dt.getHours() === Number(hh)
         && dt.getMinutes() === Number(mi) && dt.getSeconds() === Number(ss);
@@ -210,49 +145,23 @@ export function parseTimestamp13(value, optionName) {
     }
     return parsed;
 }
-/**
- * Guard for datetime options forwarded to the server AS A STRING (never converted
- * to a timestamp): the pass-through Insight/Vault list endpoints echo the string
- * verbatim, and probing 2026-07-21 showed they misread year-last separators exactly
- * like the date endpoints — `insight research list` read `07/01/2026` as 2026-01-07
- * but `07-01-2026` as 2026-07-01, a half-year apart, both HTTP 200 with nothing in
- * the response flagging it. Accept a finite epoch or a well-formed `YYYY-MM-DD
- * [ HH:mm[:ss]]` and return the ORIGINAL string unchanged.
- *
- * Validated with `datetimeFieldsValid`, NOT `toTimestamp13`: the latter's local Date
- * round-trip would reject a DST-gap string (e.g. `2026-03-08 02:30:00` under
- * America/New_York) that the server accepts — the CLI forwards this string as-is and
- * the server resolves it in its own zone, so the client's timezone must not decide
- * validity. Distinct from `parseTimestamp13`, which DOES convert (A-share
- * announcement / knowledge-batch want epoch millis, where an unrepresentable local
- * instant genuinely cannot convert).
- */
 export function parseDatetimeOption(value, optionName) {
     if (epochMillis(value) === undefined && !datetimeFieldsValid(value)) {
         throw new ValidationError(`Invalid ${optionName}: expected a Unix timestamp or "YYYY-MM-DD" optionally with " HH:mm[:ss]" (space or T separator), got "${value}" — year-last forms are refused because the API reads their day/month order differently per separator`);
     }
     return value;
 }
-/** Commander argParser factory for pass-through datetime options — same role as
- * `dateArg`, but allows an optional time part and keeps the string as-is. */
 export function datetimeArg(optionName) {
     return (value) => parseDatetimeOption(value, optionName);
 }
-/** Machine-local calendar date as `yyyy-MM-dd`, for CLI "default: today" options.
- * `new Date().toISOString().slice(0,10)` renders the UTC day — for CST users a
- * pre-08:00 "today" resolves to yesterday. Anchoring to local components matches
- * toTimestamp13's local-midnight convention. */
 export function localDateString(d) {
     const month = String(d.getMonth() + 1).padStart(2, "0");
     const day = String(d.getDate()).padStart(2, "0");
     return `${d.getFullYear()}-${month}-${day}`;
 }
-// Parse repeatable `"<lhs>:key=value"` specs into per-lhs parameter lists.
-// The left-hand side is an indicator code for cross-section / time-series and a
-// screener variable (F1, F2…) for the screener, so it stays an opaque string
-// here. Multiple specs for the same lhs accumulate, first-seen order.
 function parseParamSpecs(specs, option, syntax) {
     const groups = new Map();
+    const noQueryDate = new Set();
     for (const spec of specs) {
         const colon = spec.indexOf(":");
         const rest = colon === -1 ? "" : spec.slice(colon + 1);
@@ -260,6 +169,14 @@ function parseParamSpecs(specs, option, syntax) {
         const lhs = colon === -1 ? "" : spec.slice(0, colon).trim();
         const paramKey = eq === -1 ? "" : rest.slice(0, eq).trim();
         const paramValue = eq === -1 ? "" : rest.slice(eq + 1).trim();
+        if (rest.trim() === "") {
+            if (!lhs)
+                throw new ValidationError(`Invalid ${option}: expected "${syntax}", got "${spec}"`);
+            noQueryDate.add(lhs);
+            if (!groups.has(lhs))
+                groups.set(lhs, []);
+            continue;
+        }
         if (!lhs || !paramKey) {
             throw new ValidationError(`Invalid ${option}: expected "${syntax}", got "${spec}"`);
         }
@@ -270,27 +187,19 @@ function parseParamSpecs(specs, option, syntax) {
         }
         params.push({ paramKey, paramValue });
     }
-    return groups;
+    return { groups, noQueryDate };
 }
-// Parse repeatable `--indicator-param "code:key=value"` specs into the nested
-// indicatorParamList the EDE cross-section / time-series endpoints expect.
 export function parseIndicatorParams(specs) {
     if (specs.length === 0)
         return undefined;
-    return [...parseParamSpecs(specs, "--indicator-param", "code:key=value")].map(([indicatorCode, parameters]) => ({ indicatorCode, parameters }));
+    const { groups, noQueryDate } = parseParamSpecs(specs, "--indicator-param", "code:key=value");
+    return [...groups].map(([indicatorCode, parameters]) => (noQueryDate.has(indicatorCode)
+        ? { indicatorCode, parameters, noQueryDate: true }
+        : { indicatorCode, parameters }));
 }
-/** Screener variables are `F` + a positive integer; the server rejects anything
- * else, and a typo'd variable would otherwise surface as an opaque expression
- * error rather than pointing at the binding that is wrong. */
 const SCREENER_FIELD = /^F[1-9][0-9]*$/;
-/** Variable references inside a screener expression, e.g. the F1/F2 in
- * `F1 >= 800 && F2 <= 30`. String literals are stripped first, so a
- * `contains 'F2 系列'` operand is not mistaken for a reference. */
 const SCREENER_FIELD_REF = /\bF[1-9][0-9]*\b/g;
 const SCREENER_STRING_LITERAL = /'[^']*'|"[^"]*"/g;
-/** Split an expression into `(`, `)`, `&&`, `||` and the atoms between them.
- * String literals are copied verbatim so a `||` or an `F2` inside one is never
- * mistaken for syntax. */
 function tokenizeScreenerExpression(src) {
     const tokens = [];
     let atom = "";
@@ -325,20 +234,6 @@ function tokenizeScreenerExpression(src) {
     flush();
     return tokens;
 }
-/** Whether the expression still has a path that could have been evaluated, given
- * the variables the response actually returned a column for.
- *
- * The boolean structure decides, not the mere presence of a `||`:
- *   - a term is evaluable when every variable it names has a column;
- *   - `A && B` needs BOTH sides — a missing mandatory conjunct is an unprovable
- *     claim even if the other side is a disjunction;
- *   - `A || B` needs only one — a row can legitimately match through one operand
- *     while the other is not evaluable at all (probed 2026-08-03: `F1 > 0 || F2
- *     > 0` over 09992.HK, where `finc_pe_ttm` has no HK coverage, matches on F2).
- *
- * So `F1 && (F2 || F3)` missing F1, and `F1 || F2` missing both, are both
- * unevaluable and must fail — checking only for a `||` anywhere would let them
- * through. */
 export function screenerExpressionIsEvaluable(expression, present) {
     const tokens = tokenizeScreenerExpression(expression ?? "");
     let pos = 0;
@@ -351,13 +246,10 @@ export function screenerExpressionIsEvaluable(expression, present) {
             return value;
         }
         const atom = tokens[pos++] ?? "";
-        // A term naming no variable (a literal comparison) is always evaluable.
         return (atom.replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? []).every((ref) => present.has(ref));
     };
     const and = () => {
         let value = unit();
-        // Evaluate both sides before combining: short-circuiting would leave the
-        // parser mid-expression.
         while (tokens[pos] === "&&") {
             pos += 1;
             const right = unit();
@@ -376,18 +268,11 @@ export function screenerExpressionIsEvaluable(expression, present) {
     };
     return or();
 }
-/** Variables the expression actually filters on, string literals stripped. These
- * are the bindings whose VALUES the result depends on — a column missing for one
- * of them means the filter cannot be shown to have been applied. */
 export function screenerExpressionFields(expression) {
     return (expression ?? "").replace(SCREENER_STRING_LITERAL, "").match(SCREENER_FIELD_REF) ?? [];
 }
-// Parse the screener's `--indicator "F1:code"` bindings and merge each one's
-// `--indicator-param "F1:key=value"` specs. Params key off the variable, not the
-// code, because the same indicator may legitimately appear under two variables
-// with different parameters (e.g. the same price on two dates).
 export function parseScreenerIndicators(bindings, paramSpecs, expression) {
-    const params = parseParamSpecs(paramSpecs, "--indicator-param", "F1:key=value");
+    const { groups: params, noQueryDate } = parseParamSpecs(paramSpecs, "--indicator-param", "F1:key=value");
     const indicators = new Map();
     for (const spec of bindings) {
         const colon = spec.indexOf(":");
@@ -404,16 +289,14 @@ export function parseScreenerIndicators(bindings, paramSpecs, expression) {
         }
         indicators.set(field, { field, indicatorCode, parameters: params.get(field) ?? [] });
     }
-    // A param for an unbound variable is silently dropped by the server, so the
-    // query would run with a filter the caller believes is applied but is not.
+    if (noQueryDate.size > 0) {
+        throw new ValidationError(`--indicator-param "${[...noQueryDate][0]}:" (the no-date opt-out) is not supported by the screener: an indicator sent with no parameters does not take part in the screen, so it would run without that condition and answer 0 rows with no error. Read the value with 'indicator cross-section --indicator-param "<code>:"' and filter client-side.`);
+    }
     for (const field of params.keys()) {
         if (!indicators.has(field)) {
             throw new ValidationError(`--indicator-param references "${field}", which no --indicator binds`);
         }
     }
-    // The server does reject this (100003), but only after a round trip — and the
-    // symmetric mistake (binding a variable the expression never uses) it accepts
-    // silently while still billing the extra column.
     for (const ref of screenerExpressionFields(expression)) {
         if (!indicators.has(ref)) {
             throw new ValidationError(`--expression references "${ref}", which no --indicator binds`);

package/dist/src/core/asyncContent.js

@@ -1,44 +1,26 @@
 import { ApiError } from "./errors.js";
 import { printData } from "./printer.js";
 import { isTransientError } from "./transport.js";
-// 14 attempts with exponential backoff (5s→30s cap) ≈ 316s total wait budget.
 export const POLL_MAX_ATTEMPTS = 14;
 const POLL_INITIAL_DELAY_MS = 5_000;
 const POLL_MAX_DELAY_MS = 30_000;
 export function nextPollDelayMs(attempt) {
-    // 5s, 8s, 13s, 20s, 30s, 30s, ...
     const grown = POLL_INITIAL_DELAY_MS * 1.6 ** (attempt - 1);
     return Math.min(POLL_MAX_DELAY_MS, Math.round(grown));
 }
-// Probed 2026-07-20 against a real viewpoint-debate job: the async endpoints are
-// still entirely on the legacy codes — 410110 "正在生成中" and 410111 "生成失败",
-// both string-typed, both HTTP 400, neither carrying the new `errorType` field.
-// The 2026-07-17 spec renumbers them to 140001 RESULT_GENERATING (409) and
-// 140002 PROCESSING_FAILED (500); those are listed ahead of the switchover
-// because the failure mode is expensive and silent — a `--wait` that does not
-// recognize the pending code aborts the poll on a job already billed 50 credits.
 const PENDING_CODES = new Set(["410110", "140001"]);
 const FAILED_CODES = new Set(["410111", "140002"]);
-/** Shared by the AI content endpoints and `tool file-parse` — both report
- * "still generating" with the same codes. */
 export function isAsyncPending(error) {
     return error instanceof ApiError && error.code !== undefined && PENDING_CODES.has(error.code);
 }
 function isAsyncFailed(error) {
     return error instanceof ApiError && error.code !== undefined && FAILED_CODES.has(error.code);
 }
-/** Terminal failures are swallowed here rather than rethrown, so this line is the
- * user's only record of them — it has to carry what the global handler in cli.ts
- * would have printed (code, msg, traceId). Without the traceId the failure is
- * unreportable to Gangtise support, and README promises every error line has one. */
 function terminalFailureLine(error) {
     const api = error instanceof ApiError ? error : undefined;
     const code = api?.code ? ` ${api.code}` : "";
     const trace = api?.traceId ? ` [trace ${api.traceId}]` : "";
     const detail = api?.message ? `: ${api.message}` : "";
-    // Name the *submit* endpoint explicitly: re-running a `*-check` is a free
-    // lookup, it is resubmitting the generation job that re-bills 50 credits for a
-    // verdict that will not change (probed 2026-07-20 on sensitive content).
     return `Content generation failed (terminal${code})${trace}${detail}\n`
         + "This dataId is final — re-checking it will not change. Resubmitting the generation task bills again for the same result; change the parameters first.\n";
 }
@@ -57,10 +39,6 @@ export async function pollAsyncContent(client, getContentEndpoint, dataId, forma
                 return "failed";
             }
             if (!isAsyncPending(error)) {
-                // AI generation windows are exactly when the server is busiest: one 5xx
-                // (after the client's own retries) must not void minutes of waiting —
-                // the dataId is still valid. Transient errors consume this attempt and
-                // polling continues; anything else (no credits, bad params) aborts.
                 if (!isTransientError(error))
                     throw error;
                 const msg = error instanceof Error ? error.message : String(error);

package/dist/src/core/auth.js

@@ -15,13 +15,6 @@ export async function readTokenCache(filePath) {
         return null;
     }
 }
-/**
- * Return a display-safe copy of a token cache for `auth status`: any field whose
- * name matches a credential pattern (token / key / secret / password / credential)
- * is replaced with "<redacted>" so the raw bearer token — or any unknown credential
- * field the cache file might carry (apiKey, privateKey, …) — is never printed; all
- * other metadata (expiresAt, userName, productCode, …) is preserved.
- */
 export function redactTokenCache(cache) {
     if (!cache)
         return null;
@@ -34,11 +27,6 @@ export function redactTokenCache(cache) {
 }
 export async function writeTokenCache(filePath, cache) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    // Write to a fresh 0600 temp file then rename over the target. Writing the bearer
-    // token straight to token.json would (a) keep an existing file's lax perms — the
-    // `mode` option only applies on creation, so a follow-up chmod still leaves a brief
-    // world-readable window — and (b) risk a truncated file on crash. A temp file is
-    // 0600 from the first byte and rename is atomic, carrying the 0600 perms over.
     const tmp = `${filePath}.tmp-${randomUUID()}`;
     await fs.writeFile(tmp, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
     try {
@@ -57,8 +45,6 @@ export function isTokenCacheValid(cache, bufferSeconds = 300) {
     return cache.expiresAt - bufferSeconds > now;
 }
 export function normalizeToken(token) {
-    // Case-insensitive prefix check: GANGTISE_TOKEN="bearer xxx" must become
-    // "Bearer xxx", not the silently-invalid "Bearer bearer xxx".
     const prefix = /^bearer\s+/i.exec(token);
     return `Bearer ${prefix ? token.slice(prefix[0].length) : token}`;
 }