gangtise-openapi-cli 0.10.3 → 0.10.5

package/README.md

@@ -1,19 +1,13 @@
 # Gangtise OpenAPI CLI
 
-一个可直接调用 Gangtise OpenAPI 的命令行工具。
+一个可直接调用 Gangtise OpenAPI 获取金融数据的命令行工具，同时提供Agent Skill。
 
-## 安装
+## 首次安装
 
 ```bash
 npm install -g gangtise-openapi-cli
 ```
 
-更新到最新版：
-
-```bash
-npm update -g gangtise-openapi-cli
-```
-
 验证安装：
 
 ```bash
@@ -28,8 +22,22 @@ cd gangtise-openapi-cli
 npm install
 npm run dev -- --help
 ```
+## 版本更新
+
+查看当前版本（自动与线上版本比对）：
+
+```bash
+gangtise --version
+```
+
+手动更新到最新版：
+
+```bash
+npm update -g gangtise-openapi-cli
+```
 
-## 配置
+
+## 环境配置
 
 优先读取以下环境变量：
 
@@ -40,8 +48,53 @@ export GANGTISE_BASE_URL="https://open.gangtise.com"
 export GANGTISE_TOKEN="Bearer xxx"
 ```
 
-如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地。
+如果没有 `GANGTISE_TOKEN`，CLI 会自动调用 token 接口并缓存到本地（`~/.config/gangtise/token.json`，权限 0600）。
+
+
+## AI Agent Skill
+
+本项目包含 Skill 定义（`gangtise-openapi/SKILL.md`），可让 AI agent 自动调用 `gangtise` CLI 完成投研数据查询。支持以下 AI 编程助手：
+
+- [Claude Code](https://claude.ai/claude-code) — `~/.claude/skills/`
+- [OpenClaw](https://github.com/openclaw/openclaw) — `~/.openclaw/skills/`
+- [Hermes](https://github.com/nicepkg/hermes) — `~/.hermes/skills/`
+
+Skill 目录结构：
+
+```
+gangtise-openapi/
+├── SKILL.md                    # 主 skill 文件（命令参考、参数枚举、使用规则）
+└── references/
+    ├── fields.md               # 字段中英文对照速查表
+    └── lookup-ids.md           # 常用 ID 速查表（行业/券商/机构/公告分类等）
+```
+
+安装：
+
+```bash
+# Claude Code
+cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
+
+# OpenClaw
+cp -r gangtise-openapi ~/.openclaw/skills/gangtise-openapi
+
+# Hermes
+cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
+```
+
+> **版本更新**：每次 CLI 发版时，`gangtise-openapi/SKILL.md` 的 `version` 字段会自动同步。更新 CLI 后，请将项目中的 `gangtise-openapi/` 目录重新复制到对应的 skills 目录覆盖更新：
+>
+> ```bash
+> # 示例：更新 Claude Code 的 skill
+> cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
+> ```
+>
+> 可通过查看 SKILL.md 头部的 `version` 字段确认当前版本。
 
+安装后，可以用自然语言触发，例如：
+- "帮我查今天所有的研报"
+- "用 gangtise 命令查一下贵州茅台的日K线"
+- "导出最近一周的首席观点到 jsonl"
 
 ## 数据接口覆盖
 
@@ -83,43 +136,6 @@ export GANGTISE_TOKEN="Bearer xxx"
 | | `my-conference-list` / `my-conference-download` | 我的会议列表与下载 |
 | **Raw** | `call` | 原始接口调用（可访问任意 endpoint） |
 
-## AI Agent Skill
-
-本项目包含 SKill 定义（`gangtise-openapi/SKILL.md`），可让 AI agent 自动调用 `gangtise` CLI 完成投研数据查询。支持以下 AI 编程助手：
-
-- [Claude Code](https://claude.ai/claude-code) — `~/.claude/skills/`
-- [OpenClaw](https://github.com/openclaw/openclaw) — `~/.openclaw/skills/`
-- [Hermes](https://github.com/nicepkg/hermes) — `~/.hermes/skills/`
-
-Skill 目录结构：
-
-```
-gangtise-openapi/
-├── SKILL.md                    # 主 skill 文件（命令参考、参数枚举、使用规则）
-└── references/
-    ├── fields.md               # 字段中英文对照速查表
-    └── lookup-ids.md           # 常用 ID 速查表（行业/券商/机构/公告分类等）
-```
-
-安装：
-
-```bash
-# Claude Code
-cp -r gangtise-openapi ~/.claude/skills/gangtise-openapi
-
-# OpenClaw
-cp -r gangtise-openapi ~/.openclaw/skills/gangtise-openapi
-
-# Hermes
-cp -r gangtise-openapi ~/.hermes/skills/gangtise-openapi
-```
-
-安装后，可以用自然语言触发，例如：
-- "帮我查今天所有的研报"
-- "用 gangtise 命令查一下贵州茅台的日K线"
-- "导出最近一周的首席观点到 jsonl"
-
-
 ## 命令概览
 
 - `gangtise auth ...`
@@ -176,6 +192,8 @@ gangtise ai knowledge-batch --query 比亚迪 --query 最近热门概念
 - **有时间范围时**（传了 `--start-time/--end-time` 或 `--start-date/--end-date`）：**省略 `--size`**，CLI 自动翻页查全
 - **无时间范围时**（未传时间参数）：默认 `--size 200`，防止一次查询数据量过大
 - 如果显式传了 `--size`，则按指定值翻页，直到达到 `size` 或数据取完
+- 安全上限：自动翻页最多 1000 页，防止异常循环
+- 分页结果中 `total` 字段会被保留（json 格式输出 `{total, list}`），同时 stderr 输出 `Total: N, showing: M`
 
 ## 智能文件命名
 
@@ -279,7 +297,7 @@ gangtise ai peer-comparison --security-code 600519.SH
 gangtise ai earnings-review --security-code 600519.SH --period 2025q3
 gangtise ai theme-tracking --theme-id 121000131 --date 2026-03-01 --type morning
 gangtise ai hot-topic --start-date 2026-03-22 --end-date 2026-03-27 --category morningBriefing --category noonBriefing --with-related-securities --with-close-reading
-# 不传 --category 默认查全部类型（早报+午报+盘中快报+晚报），--with-related-securities 和 --with-close-reading 默认开启
+# 不传 --category 默认查全部类型（早报+午报+盘中快报+晚报），--with-related-securities 和 --with-close-reading 默认开启，可用 --no-with-related-securities / --no-with-close-reading 关闭
 gangtise ai hot-topic --start-date 2026-04-15 --end-date 2026-04-17
 gangtise ai research-outline --security-code 600519.SH
 # 管理层讨论-财报
@@ -328,11 +346,13 @@ gangtise raw call insight.opinion.list --body '{"from":0,"size":120}'
 支持：
 
 - `table`
-- `json`
-- `jsonl`
+- `json`（分页结果保留 `{total, list}` 结构）
+- `jsonl`（每行一条记录）
 - `csv`
 - `markdown`
 
+所有格式均支持 `--output <path>` 输出到文件（自动创建父目录）。
+
 ## 常见错误
 
 | 错误码 | 说明 |
@@ -349,3 +369,5 @@ gangtise raw call insight.opinion.list --body '{"from":0,"size":120}'
 | `999999` | Gangtise 系统错误，请稍后重试 |
 | `433007` | 不支持该数据源（`knowledge-resource-download` 需正确的 `resourceType + sourceId` 组合） |
 | `430007` | 行情查询超出限制（日K线/分钟K线不传 `--security` 返回全市场，数据量过大；请指定证券代码或缩短日期范围） |
+| `410110` | 异步任务生成中（非终态，需继续轮询） |
+| `410111` | 异步任务生成失败（终态，不可重试） |

package/dist/src/cli.js

@@ -37,7 +37,8 @@ function getTitleCachePath() {
     }
     return _titleCachePath;
 }
-const TITLE_CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24h
+const TITLE_LOOKUP_SIZE = 200;
+const TITLE_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
 async function readTitleCache() {
     try {
         const fs = await import("node:fs/promises");
@@ -63,11 +64,15 @@ function lookupTitleCache(data, endpoint, id) {
 }
 async function printData(data, format, output, cache) {
     const normalized = await normalizeRows(data);
-    // Populate title cache from list results
-    if (cache && Array.isArray(normalized)) {
+    const items = Array.isArray(normalized)
+        ? normalized
+        : (normalized && typeof normalized === "object" && Array.isArray(normalized.list))
+            ? normalized.list
+            : null;
+    if (cache && items) {
         const titleField = cache.titleField ?? "title";
         const titles = {};
-        for (const row of normalized) {
+        for (const row of items) {
             if (row && typeof row === "object") {
                 const r = row;
                 const id = r[cache.idField];
@@ -79,6 +84,13 @@ async function printData(data, format, output, cache) {
         if (Object.keys(titles).length > 0)
             writeTitleCache(cache.endpointKey, titles).catch(() => { });
     }
+    if (normalized && typeof normalized === "object" && !Array.isArray(normalized)) {
+        const meta = normalized;
+        if (typeof meta.total === "number") {
+            const listLen = Array.isArray(meta.list) ? meta.list.length : 0;
+            process.stderr.write(`Total: ${meta.total}, showing: ${listLen}\n`);
+        }
+    }
     const content = await renderOutput(normalized, format);
     if (output) {
         await saveOutputIfNeeded(content, output);
@@ -141,7 +153,7 @@ async function resolveTitle(client, result, listEndpoint, idField, idValue, titl
     catch { /* ignore */ }
     // 2. Fallback: query list API (scan recent 200 items)
     try {
-        const resp = await client.call(listEndpoint, { from: 0, size: 200 });
+        const resp = await client.call(listEndpoint, { from: 0, size: TITLE_LOOKUP_SIZE });
         const items = Array.isArray(resp) ? resp : (resp.list ?? []);
         const match = items.find(f => String(f[idField]) === String(idValue));
         const rawTitle = match?.[titleField];
@@ -179,6 +191,46 @@ async function saveDownloadResult(result, fallbackName, output) {
     }
     throw new DownloadError("Unexpected download response");
 }
+const POLL_MAX_ATTEMPTS = 12;
+const POLL_DELAY_MS = 15_000;
+async function pollAsyncContent(client, getContentEndpoint, dataId, format, output) {
+    for (let attempt = 1; attempt <= POLL_MAX_ATTEMPTS; attempt++) {
+        try {
+            const result = await client.call(getContentEndpoint, { dataId });
+            if (result?.content) {
+                await printData(result, format, output);
+                return true;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中")))) {
+                throw error;
+            }
+        }
+        if (attempt < POLL_MAX_ATTEMPTS) {
+            process.stderr.write(`Attempt ${attempt}/${POLL_MAX_ATTEMPTS}: content not ready, retrying in 15s...\n`);
+            await new Promise(resolve => setTimeout(resolve, POLL_DELAY_MS));
+        }
+    }
+    return false;
+}
+function checkAsyncContent(client, getContentEndpoint, dataId, format, output) {
+    return (async () => {
+        try {
+            const result = await client.call(getContentEndpoint, { dataId });
+            if (result?.content) {
+                await printData(result, format, output);
+                return;
+            }
+        }
+        catch (error) {
+            if (!(error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中")))) {
+                throw error;
+            }
+        }
+        process.stdout.write(`${JSON.stringify({ dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
+    })();
+}
 function addTimeFilters(command) {
     return command
         .option("--from <number>", "Starting offset", "0")
@@ -424,7 +476,6 @@ ai.command("peer-comparison").requiredOption("--security-code <code>").option("-
 });
 ai.command("earnings-review").requiredOption("--security-code <code>").requiredOption("--period <period>", "Report period (e.g. 2025q3, 2025interim, 2025annual)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    // Step 1: get dataId
     const idResult = await client.call("ai.earnings-review.get-id", { securityCode: options.securityCode, period: options.period });
     const dataId = idResult?.dataId;
     if (!dataId) {
@@ -432,56 +483,20 @@ ai.command("earnings-review").requiredOption("--security-code <code>").requiredO
         process.exitCode = 1;
         return;
     }
-    // Non-blocking: return dataId immediately
     if (!options.wait) {
         process.stderr.write(`Earnings review task submitted. dataId: ${dataId}\n`);
         process.stdout.write(`${JSON.stringify({ dataId, status: "pending", hint: `Run 'gangtise ai earnings-review-check --data-id ${dataId}' in ~2 minutes to get results` })}\n`);
         return;
     }
-    // Blocking (--wait): poll for content
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    let attempts = 0;
-    const maxAttempts = 12;
-    const delayMs = 15_000;
-    while (attempts < maxAttempts) {
-        attempts++;
-        try {
-            const contentResult = await client.call("ai.earnings-review.get-content", { dataId });
-            if (contentResult?.content) {
-                await printData(contentResult, parseFormat(options.format), options.output);
-                return;
-            }
-        }
-        catch (error) {
-            if (!(error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中")))) {
-                throw error;
-            }
-        }
-        if (attempts < maxAttempts) {
-            process.stderr.write(`Attempt ${attempts}/${maxAttempts}: content not ready, retrying in 15s...\n`);
-            await new Promise(resolve => setTimeout(resolve, delayMs));
-        }
+    if (!await pollAsyncContent(client, "ai.earnings-review.get-content", dataId, parseFormat(options.format), options.output)) {
+        process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
+        process.exitCode = 1;
     }
-    process.stderr.write(`Content not available after ${maxAttempts} attempts. Try again later with: gangtise ai earnings-review-check --data-id ${dataId}\n`);
-    process.exitCode = 1;
 });
 ai.command("earnings-review-check").requiredOption("--data-id <id>", "dataId from earnings-review").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    try {
-        const contentResult = await client.call("ai.earnings-review.get-content", { dataId: options.dataId });
-        if (contentResult?.content) {
-            await printData(contentResult, parseFormat(options.format), options.output);
-            return;
-        }
-        process.stdout.write(`${JSON.stringify({ dataId: options.dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
-    }
-    catch (error) {
-        if (error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中"))) {
-            process.stdout.write(`${JSON.stringify({ dataId: options.dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
-            return;
-        }
-        throw error;
-    }
+    await checkAsyncContent(client, "ai.earnings-review.get-content", options.dataId, parseFormat(options.format), options.output);
 });
 ai.command("theme-tracking").requiredOption("--theme-id <id>", "Theme ID (use lookup theme-id list)").requiredOption("--date <date>", "Date (yyyy-MM-dd)").option("--type <name>", "Report type: morning/night", collectList, []).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
@@ -492,7 +507,7 @@ ai.command("research-outline").requiredOption("--security-code <code>").option("
     const client = await createClient();
     await printData(await client.call("ai.research-outline", { securityCode: options.securityCode }), parseFormat(options.format), options.output);
 });
-ai.command("hot-topic").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--category <name>", "Report type: morningBriefing/noonBriefing/afternoonFlash/eveningBriefing", collectList, []).option("--with-related-securities", "Include related securities info", true).option("--with-close-reading", "Include close reading content", true).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
+ai.command("hot-topic").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-date <date>", "Start date (yyyy-MM-dd)").option("--end-date <date>", "End date (yyyy-MM-dd)").option("--category <name>", "Report type: morningBriefing/noonBriefing/afternoonFlash/eveningBriefing", collectList, []).option("--with-related-securities", "Include related securities info").option("--no-with-related-securities", "Exclude related securities info").option("--with-close-reading", "Include close reading content").option("--no-with-close-reading", "Exclude close reading content").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
     const ALL_CATEGORIES = ["morningBriefing", "noonBriefing", "afternoonFlash", "eveningBriefing"];
     await printData(await client.call("ai.hot-topic", {
@@ -501,8 +516,8 @@ ai.command("hot-topic").option("--from <number>", "Starting offset", "0").option
         startDate: options.startDate,
         endDate: options.endDate,
         categoryList: options.category.length > 0 ? options.category : ALL_CATEGORIES,
-        withRelatedSecurities: options.withRelatedSecurities || undefined,
-        withCloseReading: options.withCloseReading || undefined,
+        withRelatedSecurities: options.withRelatedSecurities === false ? undefined : true,
+        withCloseReading: options.withCloseReading === false ? undefined : true,
     }), parseFormat(options.format), options.output);
 });
 ai.command("management-discuss-announcement").requiredOption("--report-date <date>", "Report date (yyyy-MM-dd, e.g. 2025-06-30)").requiredOption("--security-code <code>", "Security code (e.g. 000001.SZ)").addOption(new Option("--dimension <name>", "Discussion dimension").choices(["businessOperation", "financialPerformance", "developmentAndRisk"]).makeOptionMandatory()).option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
@@ -523,7 +538,6 @@ ai.command("management-discuss-earnings-call").requiredOption("--report-date <da
 });
 ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint text (max 1000 chars)").option("--wait", "Wait for content generation (blocking, up to 3 min)").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    // Step 1: get dataId
     const idResult = await client.call("ai.viewpoint-debate.get-id", { viewpoint: options.viewpoint });
     const dataId = idResult?.dataId;
     if (!dataId) {
@@ -531,56 +545,20 @@ ai.command("viewpoint-debate").requiredOption("--viewpoint <text>", "Viewpoint t
         process.exitCode = 1;
         return;
     }
-    // Non-blocking: return dataId immediately
     if (!options.wait) {
         process.stderr.write(`Viewpoint debate task submitted. dataId: ${dataId}\n`);
         process.stdout.write(`${JSON.stringify({ dataId, status: "pending", hint: `Run 'gangtise ai viewpoint-debate-check --data-id ${dataId}' in ~2 minutes to get results` })}\n`);
         return;
     }
-    // Blocking (--wait): poll for content
     process.stderr.write(`Got dataId: ${dataId}, waiting for content generation...\n`);
-    let attempts = 0;
-    const maxAttempts = 12;
-    const delayMs = 15_000;
-    while (attempts < maxAttempts) {
-        attempts++;
-        try {
-            const contentResult = await client.call("ai.viewpoint-debate.get-content", { dataId });
-            if (contentResult?.content) {
-                await printData(contentResult, parseFormat(options.format), options.output);
-                return;
-            }
-        }
-        catch (error) {
-            if (!(error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中")))) {
-                throw error;
-            }
-        }
-        if (attempts < maxAttempts) {
-            process.stderr.write(`Attempt ${attempts}/${maxAttempts}: content not ready, retrying in 15s...\n`);
-            await new Promise(resolve => setTimeout(resolve, delayMs));
-        }
+    if (!await pollAsyncContent(client, "ai.viewpoint-debate.get-content", dataId, parseFormat(options.format), options.output)) {
+        process.stderr.write(`Content not available after ${POLL_MAX_ATTEMPTS} attempts. Try again later with: gangtise ai viewpoint-debate-check --data-id ${dataId}\n`);
+        process.exitCode = 1;
     }
-    process.stderr.write(`Content not available after ${maxAttempts} attempts. Try again later with: gangtise ai viewpoint-debate-check --data-id ${dataId}\n`);
-    process.exitCode = 1;
 });
 ai.command("viewpoint-debate-check").requiredOption("--data-id <id>", "dataId from viewpoint-debate").option("--format <format>", "Output format", "json").option("--output <path>").action(async (options) => {
     const client = await createClient();
-    try {
-        const contentResult = await client.call("ai.viewpoint-debate.get-content", { dataId: options.dataId });
-        if (contentResult?.content) {
-            await printData(contentResult, parseFormat(options.format), options.output);
-            return;
-        }
-        process.stdout.write(`${JSON.stringify({ dataId: options.dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
-    }
-    catch (error) {
-        if (error instanceof ApiError && (error.code === "410110" || error.message?.includes("生成中"))) {
-            process.stdout.write(`${JSON.stringify({ dataId: options.dataId, status: "pending", hint: "Content not ready yet, retry in ~2 minutes" })}\n`);
-            return;
-        }
-        throw error;
-    }
+    await checkAsyncContent(client, "ai.viewpoint-debate.get-content", options.dataId, parseFormat(options.format), options.output);
 });
 const vault = new Command("vault").description("Vault APIs");
 vault.command("drive-list").option("--from <number>", "Starting offset", "0").option("--size <number>", "Total rows to return; omit to fetch all").option("--start-time <datetime>").option("--end-time <datetime>").option("--keyword <text>").option("--file-type <number>", "File type", collectNumberList, []).option("--space-type <number>", "Space type", collectNumberList, []).option("--format <format>", "Output format", "table").option("--output <path>").action(async (options) => {
@@ -617,7 +595,15 @@ program.addCommand(vault);
 program.addCommand(ai);
 program.command("raw").description("Raw API calls").addCommand(new Command("call").argument("<endpointKey>").option("--body <json>").option("--query <key=value>", "Query string pair", collectKeyValue, {}).option("--format <format>", "Output format", "json").option("--output <path>").action(async (endpointKey, options) => {
     const client = await createClient();
-    const body = options.body ? JSON.parse(options.body) : undefined;
+    let body;
+    if (options.body) {
+        try {
+            body = JSON.parse(options.body);
+        }
+        catch {
+            throw new ConfigError(`Invalid JSON in --body: ${options.body}`);
+        }
+    }
     const data = await client.call(endpointKey, body, options.query);
     if (data && typeof data === "object" && "data" in data && data.data instanceof Uint8Array) {
         await saveDownloadResult(data, "download.bin", options.output);
@@ -646,3 +632,23 @@ async function main() {
     }
 }
 void main();
+// Background update check on --version
+if (process.argv.includes("--version") || process.argv.includes("-V")) {
+    import("node:https").then((https) => {
+        const req = https.get("https://registry.npmjs.org/gangtise-openapi-cli/latest", (res) => {
+            let body = "";
+            res.on("data", (chunk) => { body += chunk; });
+            res.on("end", () => {
+                try {
+                    const latest = JSON.parse(body).version;
+                    if (latest && latest !== CLI_VERSION) {
+                        process.stderr.write(`\nUpdate available: ${CLI_VERSION} → ${latest}\nRun: npm update -g gangtise-openapi-cli\n`);
+                    }
+                }
+                catch { /* ignore */ }
+            });
+        });
+        req.on("error", () => { });
+        req.setTimeout(3000, () => { req.destroy(); });
+    }).catch(() => { });
+}

package/dist/src/core/auth.js

@@ -4,18 +4,22 @@ import { ConfigError } from "./errors.js";
 export async function readTokenCache(filePath) {
     try {
         const content = await fs.readFile(filePath, "utf8");
-        return JSON.parse(content);
+        const parsed = JSON.parse(content);
+        if (parsed && typeof parsed === "object" && typeof parsed.accessToken === "string" && typeof parsed.expiresAt === "number") {
+            return parsed;
+        }
+        return null;
     }
     catch (error) {
         if (error.code === "ENOENT") {
             return null;
         }
-        throw error;
+        return null;
     }
 }
 export async function writeTokenCache(filePath, cache) {
     await fs.mkdir(path.dirname(filePath), { recursive: true });
-    await fs.writeFile(filePath, JSON.stringify(cache, null, 2), "utf8");
+    await fs.writeFile(filePath, JSON.stringify(cache, null, 2), { encoding: "utf8", mode: 0o600 });
 }
 export function isTokenCacheValid(cache, bufferSeconds = 300) {
     if (!cache?.accessToken || !cache.expiresAt) {

package/dist/src/core/client.js

@@ -1,10 +1,11 @@
 import { request } from "undici";
-import { normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
+import { isTokenCacheValid, normalizeToken, readTokenCache, requireAccessCredentials, writeTokenCache } from "./auth.js";
 import { ApiError, ValidationError } from "./errors.js";
 import { ENDPOINTS, ENDPOINT_REGISTRY } from "./endpoints.js";
 import { getLookupData } from "./lookupData/index.js";
 export class GangtiseClient {
     config;
+    refreshPromise = null;
     constructor(config) {
         this.config = config;
     }
@@ -13,17 +14,22 @@ export class GangtiseClient {
             return normalizeToken(this.config.token);
         }
         const cache = await readTokenCache(this.config.tokenCachePath);
-        if (cache?.accessToken && cache.expiresAt - 300 > Math.floor(Date.now() / 1000)) {
+        if (isTokenCacheValid(cache)) {
             return normalizeToken(cache.accessToken);
         }
+        if (!this.refreshPromise) {
+            this.refreshPromise = this.doTokenRefresh().finally(() => { this.refreshPromise = null; });
+        }
+        return this.refreshPromise;
+    }
+    async doTokenRefresh() {
         const credentials = requireAccessCredentials(this.config.accessKey, this.config.secretKey);
         const envelope = await this.requestJson(ENDPOINTS.authLogin, {
             accessKey: credentials.accessKey,
             secretKey: credentials.secretKey,
         }, false);
         const accessToken = normalizeToken(envelope.accessToken);
-        const issuedAt = envelope.time ?? Math.floor(Date.now() / 1000);
-        const expiresAt = issuedAt + envelope.expiresIn;
+        const expiresAt = Math.floor(Date.now() / 1000) + envelope.expiresIn;
         await writeTokenCache(this.config.tokenCachePath, {
             ...envelope,
             accessToken,
@@ -83,7 +89,8 @@ export class GangtiseClient {
         let firstPage;
         let total;
         let nextFrom = startFrom;
-        while (true) {
+        const MAX_PAGES = 1000;
+        for (let pageCount = 0; pageCount < MAX_PAGES; pageCount++) {
             const remaining = requestedSize === undefined
                 ? maxPageSize
                 : Math.min(maxPageSize, requestedSize - collected.length);
@@ -126,7 +133,7 @@ export class GangtiseClient {
             }
         }
         if (!firstPage) {
-            return initialBody;
+            return { total: 0, list: [] };
         }
         return {
             ...firstPage,
@@ -160,12 +167,15 @@ export class GangtiseClient {
             bodyTimeout: this.config.timeoutMs,
         });
         const text = await response.body.text();
+        if (response.statusCode >= 500) {
+            throw new ApiError(`Server error (HTTP ${response.statusCode})`, undefined, response.statusCode, text.slice(0, 500));
+        }
         let parsed;
         try {
             parsed = JSON.parse(text);
         }
         catch {
-            throw new ApiError('Failed to parse API response', undefined, response.statusCode, text);
+            throw new ApiError('Failed to parse API response', undefined, response.statusCode, text.slice(0, 500));
         }
         return this.unwrapEnvelope(parsed, response.statusCode);
     }

package/dist/src/core/lookupData/index.js

@@ -13,7 +13,10 @@ export async function getLookupData(key) {
     if (cache.has(key))
         return cache.get(key);
     const mod = await loaders[key]();
-    const data = Object.values(mod)[0];
+    const values = Object.values(mod);
+    const data = values.find(v => Array.isArray(v));
+    if (!data)
+        throw new Error(`Lookup module "${key}" has no exported array`);
     cache.set(key, data);
     return data;
 }

package/dist/src/core/normalize.js

@@ -7,7 +7,7 @@ export function normalizeRows(value) {
     }
     const record = value;
     if (Array.isArray(record.fieldList) && Array.isArray(record.list)) {
-        return record.list.map((row) => {
+        const normalizedList = record.list.map((row) => {
             if (!Array.isArray(row))
                 return row;
             return record.fieldList.reduce((acc, field, index) => {
@@ -15,9 +15,14 @@ export function normalizeRows(value) {
                 return acc;
             }, {});
         });
+        const { fieldList, list, ...meta } = record;
+        const hasMeta = Object.keys(meta).length > 0;
+        return hasMeta ? { ...meta, list: normalizedList } : normalizedList;
     }
     if (Array.isArray(record.list)) {
-        return record.list;
+        const { list, ...meta } = record;
+        const hasMeta = Object.keys(meta).length > 0;
+        return hasMeta ? { ...meta, list } : list;
     }
     return value;
 }

package/dist/src/core/output.js

@@ -16,7 +16,15 @@ function toRows(value) {
         return value.map((item, index) => ({ index, value: item }));
     }
     if (value && typeof value === "object") {
-        return [value];
+        const record = value;
+        if (Array.isArray(record.list)) {
+            const list = record.list;
+            if (list.every((item) => item && typeof item === "object" && !Array.isArray(item))) {
+                return list;
+            }
+            return list.map((item, index) => ({ index, value: item }));
+        }
+        return [record];
     }
     return [{ value }];
 }
@@ -51,6 +59,9 @@ function renderCsv(rows) {
     }
     const columns = Array.from(new Set(rows.flatMap((row) => Object.keys(row))));
     const escape = (value) => {
+        if (/^[=+\-@\t\r]/.test(value)) {
+            value = "'" + value;
+        }
         if (/[",\n]/.test(value)) {
             return `"${value.replaceAll("\"", "\"\"")}"`;
         }
@@ -65,8 +76,12 @@ export function renderOutput(value, format) {
     switch (format) {
         case "json":
             return JSON.stringify(value, null, 2);
-        case "jsonl":
-            return rows.map((row) => JSON.stringify(row)).join("\n");
+        case "jsonl": {
+            const items = value && typeof value === "object" && !Array.isArray(value) && Array.isArray(value.list)
+                ? value.list
+                : null;
+            return (items ?? rows).map((item) => JSON.stringify(item)).join("\n");
+        }
         case "csv":
             return renderCsv(rows);
         case "markdown":
@@ -80,6 +95,8 @@ export async function saveOutputIfNeeded(content, outputPath) {
     if (!outputPath) {
         return;
     }
+    const { dirname } = await import("node:path");
+    await (await import("node:fs/promises")).mkdir(dirname(outputPath), { recursive: true });
     if (typeof content === "string") {
         await fs.writeFile(outputPath, content, "utf8");
         return;

package/dist/src/version.js

@@ -1,2 +1,2 @@
 // Auto-generated — DO NOT EDIT
-export const CLI_VERSION = "0.10.3";
+export const CLI_VERSION = "0.10.5";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gangtise-openapi-cli",
-  "version": "0.10.3",
+  "version": "0.10.5",
   "description": "CLI for Gangtise OpenAPI",
   "license": "MIT",
   "repository": {
@@ -23,7 +23,7 @@
     "build": "tsc -p tsconfig.json",
     "dev": "tsx src/cli.ts",
     "test": "vitest run",
-    "prepare": "node -e \"const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));require('fs').writeFileSync('src/version.ts','// Auto-generated — DO NOT EDIT\\nexport const CLI_VERSION = \\\"'+p.version+'\\\"\\n')\" && npm run build"
+    "prepare": "node scripts/prepare.cjs && npm run build"
   },
   "engines": {
     "node": ">=20"