@hithink-tech/hithink-finance-cli 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 0.1.0 - Unreleased
+
+- Initial TypeScript CLI with hithink finance REST capabilities, DuckDB data engine, Agent Skills, and lifecycle commands.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HiThink-Tech
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# hithink-finance CLI
+
+`hithink-finance` 是同花顺金融数据服务的 Node.js 命令行客户端，面向人类终端、AI Agent、CI 和自动化脚本。它统一提供远端数据、本地 DuckDB、认证、结构化输出、能力发现、诊断和生命周期管理，运行时不依赖 monorepo 的 Python 子项目。
+
+CLI 文档只维护命令和运行语义；上游 REST 参数与响应字段统一见 [`docs/api/`](../docs/api/README.md)。
+
+## 环境与安装
+
+需要 Node.js `>=22.12.0`。
+
+### 从当前仓库运行
+
+```bash
+cd hithink-finance-cli
+npm ci --ignore-scripts
+npm run build
+node dist/cli/main.js --help
+node dist/cli/main.js capabilities --format json
+```
+
+### npm 发布后安装
+
+```bash
+npm install -g @hithink-tech/hithink-finance-cli
+hithink-finance version --format json
+hithink-finance doctor --format json
+```
+
+如果 `npm install` 返回 `E404`，说明包尚未发布或当前 registry 无法访问。报告实际状态，不要在终端指引中把源码安装伪装成正式发布安装。
+
+## API Key 与认证
+
+远端命令使用统一 API Key，获取地址：<https://fuyao.aicubes.cn/admin>。
+
+交互式终端：
+
+```bash
+hithink-finance auth login
+hithink-finance auth status --format json
+```
+
+Agent/CI 使用 stdin 或进程环境变量：
+
+```bash
+printf '%s' "$HITHINK_FINANCE_API_KEY" | \
+  hithink-finance auth login --api-key-stdin --format json
+```
+
+不要把 Key 写入配置文件、命令参数记录、日志、Markdown、对话或 Git。`config show` 只展示非敏感配置。
+
+## 能力发现
+
+CLI 的当前命令事实由运行时输出提供：
+
+```bash
+hithink-finance capabilities --format json
+hithink-finance schema market.snapshot --format json
+hithink-finance market snapshot --help
+```
+
+Agent 不应只凭 README 猜参数。先读取 `capabilities`，再对目标 capability 读取 `schema`。
+
+## 命令导航
+
+| 命令组                          | 用途                                                 |
+| ------------------------------- | ---------------------------------------------------- |
+| `version`, `doctor`             | 版本和环境诊断                                       |
+| `auth`, `config`                | API Key 与非敏感配置                                 |
+| `symbol`                        | 标的检索与代码表                                     |
+| `market`                        | 个股行情、交易日历、本地面板和复权因子               |
+| `financials`                    | 财务报表与财务指标                                   |
+| `index`                         | 指数/板块目录、成分和行情                            |
+| `special`                       | 涨停、连板、异动、热榜和龙虎榜                       |
+| `data`                          | 本地数据库初始化、同步、状态、校验、迁移、修复和清理 |
+| `db`                            | DuckDB 描述、只读 SQL 和导出                         |
+| `capabilities`, `schema`        | 机器可读命令契约                                     |
+| `skills`, `update`, `uninstall` | Agent Skills 与 CLI 生命周期                         |
+
+常见调用：
+
+```bash
+hithink-finance symbol search --q 600519 --limit 5 --format json
+hithink-finance market snapshot --thscodes 600519.SH --format json
+hithink-finance financials income --thscode 600519.SH --limit 4 --format json
+hithink-finance index constituents --thscode 000300.SH --format json
+hithink-finance special limit-up-pool --size 50 --format json
+hithink-finance data status --format json
+hithink-finance db query --sql "SELECT * FROM v_daily_qfq LIMIT 10" --format json
+```
+
+## 输出与错误语义
+
+- 机器读取显式使用 `--format json`；人类交互可选择 `table`。
+- 成功以进程退出码 0 和 JSON 信封 `ok=true` 为准。
+- 失败以非 0 退出码和 `ok=false` 为准，读取 `error.code`、`error.category`、`error.hint` 与请求标识。
+- 远端上游使用 `{code, message, request_id, data}`，但 CLI 会规范化为自己的信封；不要混用两套成功判断。
+- `--debug` 只向 stderr 输出诊断，不污染机器可读 stdout。
+
+## 大结果与数据源
+
+`--source auto|local|remote` 控制支持该选项的行情路由。只有具体命令声明的 `--output <path>` 才能直接落盘，它不是全局选项。
+
+```bash
+hithink-finance market panel \
+  --start 2026-01-01 --end 2026-01-31 \
+  --output panel.parquet --file-format parquet --format json
+
+hithink-finance db export \
+  --sql "SELECT * FROM v_daily_qfq" \
+  --output daily.parquet --file-format parquet --format json
+```
+
+全市场、分页全集、多标的或长时间窗口必须落盘。终端和 Agent 对话只报告路径、行数、窗口和摘要。
+
+## 本地 DuckDB
+
+```bash
+hithink-finance data init --format json
+hithink-finance data sync --format json
+hithink-finance data status --format json
+hithink-finance data validate --format json
+hithink-finance db describe --format json
+```
+
+初始化和同步需要远端 API Key；已有本地库的只读查询通常不需要。迁移、修复、清理和卸载等有副作用操作先查看计划或帮助，并在命令要求时获得用户明确确认。
+
+## 配置优先级
+
+CLI 按以下顺序解析非敏感配置：
+
+1. CLI 参数
+2. 环境变量
+3. 项目 `hithink-finance.config.json`
+4. 用户配置
+5. 默认值
+
+使用 `hithink-finance config show --format json` 查看最终生效的非敏感配置。多套环境使用 `--profile <name>`。
+
+## Agent Skill
+
+跨 REST API、MCP、CLI 和 Python SDK 的统一入口是仓库根 [`skills/hithink-finance`](../skills/hithink-finance/SKILL.md)：
+
+```bash
+npx skills add HiThink-Tech/Financial-API --skill hithink-finance -g --yes
+```
+
+CLI 包还可以通过 `hithink-finance skills status|sync|remove` 管理命令专用的领域 Skills。它们补充 CLI 参数路由，不替代统一 `hithink-finance` Skill，也不是上游 API 文档的事实源。
+
+## 开发与验证
+
+```bash
+npm ci --ignore-scripts
+npm run generate:contracts
+npm run verify
+node scripts/release-smoke.mjs
+```
+
+- 改动命令、选项、输出或错误语义后，先运行 `npm run generate:contracts` 更新 CLI 自带能力与 Skill 契约。
+- `npm run verify` 依次检查格式、lint、类型、测试和构建。
+- 发布流程与许可守门见 [`docs/maintainers/npm-publishing.md`](docs/maintainers/npm-publishing.md)。
+- 版本变化见 [`CHANGELOG.md`](CHANGELOG.md)，安全问题按 [`SECURITY.md`](SECURITY.md) 私下报告。

package/SECURITY.md

@@ -0,0 +1,3 @@
+# Security
+
+Report vulnerabilities privately through GitHub Security Advisories for `HiThink-Tech/Financial-API`. Do not include API keys, credentials, private datasets, or production logs containing secrets.

package/dist/application/config.d.ts

@@ -0,0 +1,44 @@
+import { z } from 'zod';
+import { type PlatformPaths } from '../infrastructure/filesystem/platform-paths.js';
+declare const configFileSchema: z.ZodObject<{
+    dbPath: z.ZodOptional<z.ZodString>;
+    profile: z.ZodOptional<z.ZodString>;
+    format: z.ZodOptional<z.ZodEnum<{
+        auto: "auto";
+        json: "json";
+        ndjson: "ndjson";
+        csv: "csv";
+        table: "table";
+    }>>;
+    language: z.ZodOptional<z.ZodEnum<{
+        "zh-CN": "zh-CN";
+        en: "en";
+    }>>;
+    updateCheck: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+export type ConfigFile = z.infer<typeof configFileSchema>;
+export interface ConfigOverrides {
+    dbPath?: string;
+    profile?: string;
+    format?: ConfigFile['format'];
+    language?: ConfigFile['language'];
+    configPath?: string;
+}
+export interface ResolvedConfig {
+    dbPath: string;
+    profile: string;
+    format: NonNullable<ConfigFile['format']>;
+    language?: ConfigFile['language'];
+    updateCheck: boolean;
+    configPath?: string;
+}
+export interface LoadConfigInput {
+    cli?: ConfigOverrides;
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    paths?: PlatformPaths;
+}
+export declare function parseConfigFile(value: unknown, source: string): ConfigFile;
+export declare function loadConfig(input?: LoadConfigInput): Promise<ResolvedConfig>;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/application/config.js

@@ -0,0 +1,111 @@
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { CliError } from '../contracts/errors.js';
+import { createPlatformPaths, } from '../infrastructure/filesystem/platform-paths.js';
+const configFileSchema = z
+    .object({
+    dbPath: z.string().min(1).optional(),
+    profile: z.string().min(1).optional(),
+    format: z.enum(['auto', 'json', 'ndjson', 'csv', 'table']).optional(),
+    language: z.enum(['zh-CN', 'en']).optional(),
+    updateCheck: z.boolean().optional(),
+})
+    .strict();
+const SECRET_KEYS = new Set(['apikey', 'token', 'authorization', 'cookie', 'secret']);
+function containsSecret(value) {
+    if (Array.isArray(value))
+        return value.some(containsSecret);
+    if (value === null || typeof value !== 'object')
+        return false;
+    return Object.entries(value).some(([key, entry]) => {
+        const normalized = key.toLowerCase().replaceAll(/[^a-z]/g, '');
+        return SECRET_KEYS.has(normalized) || containsSecret(entry);
+    });
+}
+function configError(code, message, hint) {
+    return new CliError({
+        code,
+        category: 'validation',
+        message: `${code}: ${message}`,
+        hint,
+        retryable: false,
+        exitCode: 2,
+    });
+}
+export function parseConfigFile(value, source) {
+    if (containsSecret(value)) {
+        throw configError('CONFIG_SECRET_FORBIDDEN', `Secrets are not allowed in ${source}.`, 'Use HITHINK_FINANCE_API_KEY, --api-key-stdin, or the system credential store.');
+    }
+    const parsed = configFileSchema.safeParse(value);
+    if (!parsed.success) {
+        throw configError('CONFIG_INVALID', `Configuration in ${source} does not match the supported schema.`, parsed.error.issues.map((issue) => issue.message).join('; '));
+    }
+    return parsed.data;
+}
+async function readConfig(configPath) {
+    let content;
+    try {
+        content = await readFile(configPath, 'utf8');
+    }
+    catch (error) {
+        if (typeof error === 'object' && error !== null && 'code' in error && error.code === 'ENOENT') {
+            return undefined;
+        }
+        throw error;
+    }
+    try {
+        return parseConfigFile(JSON.parse(content), configPath);
+    }
+    catch (error) {
+        if (error instanceof CliError)
+            throw error;
+        throw configError('CONFIG_INVALID', `Configuration in ${configPath} is not valid JSON.`, 'Fix the JSON syntax or remove the file.');
+    }
+}
+function resolveFrom(baseDirectory, value) {
+    return path.isAbsolute(value) ? path.normalize(value) : path.resolve(baseDirectory, value);
+}
+export async function loadConfig(input = {}) {
+    const cwd = input.cwd ?? process.cwd();
+    const env = input.env ?? process.env;
+    const paths = input.paths ?? createPlatformPaths({ env });
+    const cli = input.cli ?? {};
+    const explicitConfigPath = cli.configPath ?? env.HITHINK_FINANCE_CONFIG;
+    const projectConfigPath = resolveFrom(cwd, explicitConfigPath ?? 'hithink-finance.config.json');
+    const [userConfig, projectConfig] = await Promise.all([
+        readConfig(paths.userConfigFile),
+        readConfig(projectConfigPath),
+    ]);
+    let dbPath = paths.defaultDbPath;
+    if (userConfig?.dbPath !== undefined) {
+        dbPath = resolveFrom(path.dirname(paths.userConfigFile), userConfig.dbPath);
+    }
+    if (projectConfig?.dbPath !== undefined) {
+        dbPath = resolveFrom(path.dirname(projectConfigPath), projectConfig.dbPath);
+    }
+    if (env.HITHINK_FINANCE_DB_PATH !== undefined) {
+        dbPath = resolveFrom(cwd, env.HITHINK_FINANCE_DB_PATH);
+    }
+    if (cli.dbPath !== undefined) {
+        dbPath = resolveFrom(cwd, cli.dbPath);
+    }
+    const language = cli.language ?? projectConfig?.language ?? userConfig?.language;
+    const result = {
+        dbPath,
+        profile: cli.profile ??
+            env.HITHINK_FINANCE_PROFILE ??
+            projectConfig?.profile ??
+            userConfig?.profile ??
+            'default',
+        format: cli.format ?? projectConfig?.format ?? userConfig?.format ?? 'auto',
+        updateCheck: env.HITHINK_FINANCE_NO_UPDATE_CHECK === undefined &&
+            (projectConfig?.updateCheck ?? userConfig?.updateCheck ?? true),
+    };
+    if (language !== undefined)
+        result.language = language;
+    if (explicitConfigPath !== undefined)
+        result.configPath = projectConfigPath;
+    return result;
+}
+//# sourceMappingURL=config.js.map

package/dist/application/ports/auth-provider.d.ts

@@ -0,0 +1,23 @@
+export interface AuthSession {
+    method: 'api-key';
+    profile: string;
+    apiKey: string;
+    source: 'explicit' | 'environment' | 'keyring';
+}
+export interface LoginInput {
+    profile: string;
+    apiKey: string;
+}
+export interface AuthStatus {
+    method: 'api-key';
+    profile: string;
+    configured: boolean;
+}
+export interface AuthProvider {
+    readonly method: string;
+    resolve(profile: string, explicit?: string): Promise<AuthSession>;
+    login(input: LoginInput): Promise<AuthStatus>;
+    logout(profile: string): Promise<void>;
+    status(profile: string): Promise<AuthStatus>;
+}
+//# sourceMappingURL=auth-provider.d.ts.map

package/dist/application/ports/auth-provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=auth-provider.js.map

package/dist/application/source-policy.d.ts

@@ -0,0 +1,13 @@
+export type DataSource = 'auto' | 'local' | 'remote';
+export type RequestKind = 'snapshot' | 'financials' | 'index' | 'special' | 'calendar' | 'panel' | 'factors' | 'db' | 'maintenance' | 'history';
+export interface SourceRequest {
+    kind: RequestKind;
+    requested: DataSource;
+    symbolCount?: number;
+}
+export interface LocalState {
+    exists: boolean;
+    coversWindow: boolean;
+}
+export declare function chooseSource(request: SourceRequest, local: LocalState): Exclude<DataSource, 'auto'>;
+//# sourceMappingURL=source-policy.d.ts.map

package/dist/application/source-policy.js

@@ -0,0 +1,31 @@
+import { CliError } from '../contracts/errors.js';
+function sourceError(code, message) {
+    throw new CliError({
+        code,
+        category: 'local-data',
+        message: `${code}: ${message}`,
+        hint: 'Initialize/sync local data or choose a supported --source.',
+        retryable: false,
+        exitCode: 5,
+    });
+}
+export function chooseSource(request, local) {
+    const remoteOnly = ['snapshot', 'financials', 'index', 'special', 'calendar'].includes(request.kind);
+    const localOnly = ['panel', 'factors', 'db', 'maintenance'].includes(request.kind);
+    if (request.requested === 'local' && remoteOnly)
+        return sourceError('SOURCE_NOT_SUPPORTED', `${request.kind} is remote-only.`);
+    if (request.requested === 'remote' && localOnly)
+        return sourceError('SOURCE_NOT_SUPPORTED', `${request.kind} is local-only.`);
+    if (request.requested !== 'auto')
+        return request.requested;
+    if (remoteOnly)
+        return 'remote';
+    if (localOnly)
+        return 'local';
+    if (local.exists && local.coversWindow)
+        return 'local';
+    if ((request.symbolCount ?? 1) === 1)
+        return 'remote';
+    return sourceError('DATA_INITIALIZATION_REQUIRED', 'Bulk history requires covered local data.');
+}
+//# sourceMappingURL=source-policy.js.map

package/dist/application/use-cases/data-clean.d.ts

@@ -0,0 +1,2 @@
+export declare function cleanManagedCache(cachePath: string, managedRoot: string): Promise<void>;
+//# sourceMappingURL=data-clean.d.ts.map

package/dist/application/use-cases/data-clean.js

@@ -0,0 +1,18 @@
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from '../../contracts/errors.js';
+export async function cleanManagedCache(cachePath, managedRoot) {
+    const target = path.resolve(cachePath);
+    const root = path.resolve(managedRoot);
+    if (target !== root && !target.startsWith(`${root}${path.sep}`))
+        throw new CliError({
+            code: 'PATH_OUTSIDE_MANAGED_ROOT',
+            category: 'validation',
+            message: 'The cleanup target is outside the managed cache root.',
+            hint: 'Only pass paths inside the CLI-managed cache directory.',
+            retryable: false,
+            exitCode: 2,
+        });
+    await rm(target, { recursive: true, force: true });
+}
+//# sourceMappingURL=data-clean.js.map

package/dist/application/use-cases/data-init.d.ts

@@ -0,0 +1,4 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+import { type ParquetBundle } from '../../infrastructure/duckdb/importer.js';
+export declare function initializeData(connection: DuckDBConnection, bundle: ParquetBundle): Promise<number>;
+//# sourceMappingURL=data-init.d.ts.map

package/dist/application/use-cases/data-init.js

@@ -0,0 +1,9 @@
+import { importParquetBundle } from '../../infrastructure/duckdb/importer.js';
+import { applyMigrations } from '../../infrastructure/duckdb/migrations.js';
+import { rebuildAdjustmentFactors } from '../../infrastructure/duckdb/factors.js';
+export async function initializeData(connection, bundle) {
+    await applyMigrations(connection);
+    await importParquetBundle(connection, bundle);
+    return rebuildAdjustmentFactors(connection);
+}
+//# sourceMappingURL=data-init.js.map

package/dist/application/use-cases/data-remove.d.ts

@@ -0,0 +1,2 @@
+export declare function removeDatabase(databasePath: string, allowedExactPath: string, confirmed: boolean): Promise<void>;
+//# sourceMappingURL=data-remove.d.ts.map

package/dist/application/use-cases/data-remove.js

@@ -0,0 +1,27 @@
+import { rm } from 'node:fs/promises';
+import path from 'node:path';
+import { CliError } from '../../contracts/errors.js';
+export async function removeDatabase(databasePath, allowedExactPath, confirmed) {
+    const target = path.resolve(databasePath);
+    const allowed = path.resolve(allowedExactPath);
+    if (target !== allowed)
+        throw new CliError({
+            code: 'PATH_NOT_CONFIRMED',
+            category: 'validation',
+            message: 'The database path does not match the confirmed removal target.',
+            hint: 'Run `data remove --plan` and confirm the exact path before deleting.',
+            retryable: false,
+            exitCode: 2,
+        });
+    if (!confirmed)
+        throw new CliError({
+            code: 'CONFIRMATION_REQUIRED',
+            category: 'validation',
+            message: 'Database removal requires explicit confirmation.',
+            hint: 'Re-run with --yes after reviewing the removal plan.',
+            retryable: false,
+            exitCode: 2,
+        });
+    await rm(target, { force: true });
+}
+//# sourceMappingURL=data-remove.js.map

package/dist/application/use-cases/data-repair.d.ts

@@ -0,0 +1,5 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+export declare function repairData(connection: DuckDBConnection): Promise<{
+    factorRows: number;
+}>;
+//# sourceMappingURL=data-repair.d.ts.map

package/dist/application/use-cases/data-repair.js

@@ -0,0 +1,5 @@
+import { rebuildAdjustmentFactors } from '../../infrastructure/duckdb/factors.js';
+export async function repairData(connection) {
+    return { factorRows: await rebuildAdjustmentFactors(connection) };
+}
+//# sourceMappingURL=data-repair.js.map

package/dist/application/use-cases/data-sync.d.ts

@@ -0,0 +1,25 @@
+export type SyncDecision = 'SKIP' | 'INCREMENTAL' | 'FULL';
+export interface LocalSyncState {
+    maxDate: string | null;
+    releaseId: string | null;
+}
+export interface RemoteReleaseState {
+    latestDate: string;
+    releaseId: string;
+    lagTradingDays: number;
+}
+export declare function chooseSyncDecision(local: LocalSyncState, remote: RemoteReleaseState, maxIncrementalLag?: number): SyncDecision;
+import type { DuckDBConnection } from '@duckdb/node-api';
+export interface FuyaoSyncOptions {
+    baseUrl: string;
+    apiKey: string;
+    cacheDir: string;
+    now?: Date;
+}
+export declare function syncDataFromFuyao(connection: DuckDBConnection, options: FuyaoSyncOptions): Promise<{
+    decision: SyncDecision;
+    releaseId: string;
+    factorRows: number;
+    quality: unknown;
+}>;
+//# sourceMappingURL=data-sync.d.ts.map

package/dist/application/use-cases/data-sync.js

@@ -0,0 +1,55 @@
+export function chooseSyncDecision(local, remote, maxIncrementalLag = 5) {
+    if (local.maxDate === null)
+        return 'FULL';
+    if (local.maxDate >= remote.latestDate && local.releaseId === remote.releaseId)
+        return 'SKIP';
+    return remote.lagTradingDays <= maxIncrementalLag ? 'INCREMENTAL' : 'FULL';
+}
+import { fetchFuyaoDump } from '../../infrastructure/duckdb/dump-client.js';
+import { importParquetBundle } from '../../infrastructure/duckdb/importer.js';
+import { applyMigrations } from '../../infrastructure/duckdb/migrations.js';
+import { rebuildAdjustmentFactors } from '../../infrastructure/duckdb/factors.js';
+import { validateDatabase } from '../../infrastructure/duckdb/quality.js';
+async function scalar(connection, sql) {
+    const reader = await connection.runAndReadAll(sql);
+    const value = reader.getRowsJson()[0]?.[0];
+    return value === null || value === undefined ? null : String(value);
+}
+export async function syncDataFromFuyao(connection, options) {
+    await applyMigrations(connection);
+    const maxDate = await scalar(connection, 'SELECT max(date)::VARCHAR FROM raw_kline_daily');
+    const previousRelease = await scalar(connection, "SELECT value FROM _meta WHERE key='last_kline_release_id'");
+    const now = options.now ?? new Date();
+    const lagDays = maxDate === null
+        ? Number.POSITIVE_INFINITY
+        : Math.floor((now.getTime() - Date.parse(`${maxDate}T00:00:00Z`)) / 86_400_000);
+    const kind = maxDate === null || lagDays > 14 ? 'daily-k' : 'daily-k-10d';
+    const kline = await fetchFuyaoDump({ ...options, kind });
+    if (previousRelease === kline.releaseId) {
+        return {
+            decision: 'SKIP',
+            releaseId: kline.releaseId,
+            factorRows: 0,
+            quality: await validateDatabase(connection),
+        };
+    }
+    const events = await fetchFuyaoDump({ ...options, kind: 'adjustment-factors' });
+    const decision = kind === 'daily-k' ? 'FULL' : 'INCREMENTAL';
+    const batchId = `${decision.toLowerCase()}-${Date.now()}`;
+    await importParquetBundle(connection, {
+        klinePath: kline.path,
+        eventsPath: events.path,
+        batchId,
+        source: `fuyao:${kline.releaseId}`,
+        mode: decision,
+    });
+    const factorRows = await rebuildAdjustmentFactors(connection);
+    await connection.run("INSERT OR REPLACE INTO _meta VALUES ('last_kline_release_id',$kline),('last_adjustment_release_id',$events),('last_sync_mode',$mode)", { kline: kline.releaseId, events: events.releaseId, mode: decision });
+    return {
+        decision,
+        releaseId: kline.releaseId,
+        factorRows,
+        quality: await validateDatabase(connection),
+    };
+}
+//# sourceMappingURL=data-sync.js.map

package/dist/application/use-cases/local-query.d.ts

@@ -0,0 +1,4 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+export declare function queryReadOnly(connection: DuckDBConnection, sql: string): Promise<Record<string, unknown>[]>;
+export declare function exportQuery(connection: DuckDBConnection, sql: string, outputPath: string, format: 'ndjson' | 'csv' | 'parquet'): Promise<number>;
+//# sourceMappingURL=local-query.d.ts.map