@hithink-tech/hithink-finance-cli 0.1.0

package/dist/domains/market/types.js

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

package/dist/domains/special/types.d.ts

@@ -0,0 +1,5 @@
+export interface SpecialDataRecord {
+    thscode?: string;
+    [field: string]: unknown;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/domains/special/types.js

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

package/dist/domains/symbol/types.d.ts

@@ -0,0 +1,6 @@
+export interface SymbolRecord {
+    thscode: string;
+    ticker?: string;
+    name?: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/domains/symbol/types.js

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

package/dist/infrastructure/credentials/api-key-provider.d.ts

@@ -0,0 +1,14 @@
+import type { AuthProvider, AuthSession, AuthStatus, LoginInput } from '../../application/ports/auth-provider.js';
+import type { CredentialStore } from './keyring.js';
+export declare class ApiKeyAuthProvider implements AuthProvider {
+    private readonly store;
+    private readonly env;
+    readonly method = "api-key";
+    constructor(store: CredentialStore, env?: NodeJS.ProcessEnv);
+    resolve(profile: string, explicit?: string): Promise<AuthSession>;
+    login(input: LoginInput): Promise<AuthStatus>;
+    logout(profile: string): Promise<void>;
+    logoutAll(): Promise<void>;
+    status(profile: string): Promise<AuthStatus>;
+}
+//# sourceMappingURL=api-key-provider.d.ts.map

package/dist/infrastructure/credentials/api-key-provider.js

@@ -0,0 +1,102 @@
+import { CliError } from '../../contracts/errors.js';
+const PROFILE_PREFIX = 'profile:';
+const API_KEY_RECOVERY_HINT = 'Get an API key at https://fuyao.aicubes.cn/admin, then run `hithink-finance auth login`. For non-interactive use, pipe it to `hithink-finance auth login --api-key-stdin`, or set HITHINK_FINANCE_API_KEY for the current process.';
+function account(profile) {
+    return `${PROFILE_PREFIX}${profile}`;
+}
+function credentialStoreError() {
+    return new CliError({
+        code: 'AUTH_CREDENTIAL_STORE_UNAVAILABLE',
+        category: 'authentication',
+        message: 'The system credential store is unavailable.',
+        hint: process.platform === 'linux'
+            ? `Start a Secret Service provider, or use HITHINK_FINANCE_API_KEY for this process. ${API_KEY_RECOVERY_HINT}`
+            : `Unlock the system credential store, or use HITHINK_FINANCE_API_KEY for this process. ${API_KEY_RECOVERY_HINT}`,
+        retryable: false,
+        exitCode: 3,
+    });
+}
+export class ApiKeyAuthProvider {
+    store;
+    env;
+    method = 'api-key';
+    constructor(store, env = process.env) {
+        this.store = store;
+        this.env = env;
+    }
+    async resolve(profile, explicit) {
+        if (explicit !== undefined && explicit.length > 0) {
+            return { method: 'api-key', profile, apiKey: explicit, source: 'explicit' };
+        }
+        const environmentKey = this.env.HITHINK_FINANCE_API_KEY;
+        if (environmentKey !== undefined && environmentKey.length > 0) {
+            return { method: 'api-key', profile, apiKey: environmentKey, source: 'environment' };
+        }
+        let stored;
+        try {
+            stored = await this.store.get(account(profile));
+        }
+        catch {
+            throw credentialStoreError();
+        }
+        if (stored != null && stored.length > 0) {
+            return { method: 'api-key', profile, apiKey: stored, source: 'keyring' };
+        }
+        throw new CliError({
+            code: 'AUTH_API_KEY_MISSING',
+            category: 'authentication',
+            message: 'No API key is configured for the selected profile.',
+            hint: API_KEY_RECOVERY_HINT,
+            retryable: false,
+            exitCode: 3,
+        });
+    }
+    async login(input) {
+        if (input.apiKey.length === 0) {
+            throw new CliError({
+                code: 'AUTH_API_KEY_EMPTY',
+                category: 'validation',
+                message: 'The API key cannot be empty.',
+                hint: 'Provide the key through hidden input, --api-key-stdin, or --api-key.',
+                retryable: false,
+                exitCode: 2,
+            });
+        }
+        try {
+            await this.store.set(account(input.profile), input.apiKey);
+        }
+        catch {
+            throw credentialStoreError();
+        }
+        return { method: 'api-key', profile: input.profile, configured: true };
+    }
+    async logout(profile) {
+        try {
+            await this.store.delete(account(profile));
+        }
+        catch {
+            throw credentialStoreError();
+        }
+    }
+    async logoutAll() {
+        try {
+            const accounts = await this.store.listAccounts();
+            await Promise.all(accounts
+                .filter((candidate) => candidate.startsWith(PROFILE_PREFIX))
+                .map((candidate) => this.store.delete(candidate)));
+        }
+        catch {
+            throw credentialStoreError();
+        }
+    }
+    async status(profile) {
+        try {
+            const key = await this.store.get(account(profile));
+            return { method: 'api-key', profile, configured: key != null && key.length > 0 };
+        }
+        catch {
+            throw credentialStoreError();
+        }
+    }
+}
+//# sourceMappingURL=api-key-provider.js.map

package/dist/infrastructure/credentials/keyring.d.ts

@@ -0,0 +1,15 @@
+export interface CredentialStore {
+    get(account: string): Promise<string | undefined>;
+    set(account: string, secret: string): Promise<void>;
+    delete(account: string): Promise<boolean>;
+    listAccounts(): Promise<string[]>;
+}
+export declare class KeyringCredentialStore implements CredentialStore {
+    private readonly service;
+    constructor(service?: string);
+    get(account: string): Promise<string | undefined>;
+    set(account: string, secret: string): Promise<void>;
+    delete(account: string): Promise<boolean>;
+    listAccounts(): Promise<string[]>;
+}
+//# sourceMappingURL=keyring.d.ts.map

package/dist/infrastructure/credentials/keyring.js

@@ -0,0 +1,21 @@
+import { AsyncEntry, findCredentialsAsync } from '@napi-rs/keyring';
+export class KeyringCredentialStore {
+    service;
+    constructor(service = 'hithink-finance') {
+        this.service = service;
+    }
+    async get(account) {
+        return new AsyncEntry(this.service, account).getPassword();
+    }
+    async set(account, secret) {
+        await new AsyncEntry(this.service, account).setPassword(secret);
+    }
+    async delete(account) {
+        return new AsyncEntry(this.service, account).deleteCredential();
+    }
+    async listAccounts() {
+        const credentials = await findCredentialsAsync(this.service);
+        return credentials.map((credential) => credential.account);
+    }
+}
+//# sourceMappingURL=keyring.js.map

package/dist/infrastructure/credentials/redact.d.ts

@@ -0,0 +1,3 @@
+export declare function redactText(value: string, knownSecrets?: readonly string[]): string;
+export declare function redactValue(value: unknown, knownSecrets?: readonly string[]): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/dist/infrastructure/credentials/redact.js

@@ -0,0 +1,26 @@
+const SECRET_KEYS = new Set(['apikey', 'token', 'authorization', 'cookie', 'secret', 'password']);
+const SECRET_ASSIGNMENT = /\b(api[-_ ]?key|apikey|token|authorization|cookie|secret|password)\s*([=:])\s*([^\s,;]+)/giu;
+export function redactText(value, knownSecrets = []) {
+    let redacted = value.replace(SECRET_ASSIGNMENT, (_match, key, separator) => {
+        return `${key}${separator}[REDACTED]`;
+    });
+    for (const secret of knownSecrets) {
+        if (secret.length > 0)
+            redacted = redacted.replaceAll(secret, '[REDACTED]');
+    }
+    return redacted;
+}
+export function redactValue(value, knownSecrets = []) {
+    if (typeof value === 'string')
+        return redactText(value, knownSecrets);
+    if (Array.isArray(value))
+        return value.map((entry) => redactValue(entry, knownSecrets));
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => {
+            const normalized = key.toLowerCase().replaceAll(/[^a-z]/g, '');
+            return [key, SECRET_KEYS.has(normalized) ? '[REDACTED]' : redactValue(entry, knownSecrets)];
+        }));
+    }
+    return value;
+}
+//# sourceMappingURL=redact.js.map

package/dist/infrastructure/duckdb/connection.d.ts

@@ -0,0 +1,8 @@
+import { type DuckDBConnection } from '@duckdb/node-api';
+export interface OpenDatabase {
+    path: string;
+    connection: DuckDBConnection;
+    close(): void;
+}
+export declare function openDatabase(databasePath: string): Promise<OpenDatabase>;
+//# sourceMappingURL=connection.d.ts.map

package/dist/infrastructure/duckdb/connection.js

@@ -0,0 +1,18 @@
+import { DuckDBInstance } from '@duckdb/node-api';
+import path from 'node:path';
+import { mkdir } from 'node:fs/promises';
+export async function openDatabase(databasePath) {
+    const absolutePath = path.resolve(databasePath);
+    await mkdir(path.dirname(absolutePath), { recursive: true });
+    const instance = await DuckDBInstance.create(absolutePath);
+    const connection = await instance.connect();
+    return {
+        path: absolutePath,
+        connection,
+        close() {
+            connection.closeSync();
+            instance.closeSync();
+        },
+    };
+}
+//# sourceMappingURL=connection.js.map

package/dist/infrastructure/duckdb/dump-client.d.ts

@@ -0,0 +1,20 @@
+export type DumpKind = 'daily-k' | 'daily-k-10d' | 'adjustment-factors';
+export interface FetchFuyaoDumpOptions {
+    baseUrl: string;
+    apiKey: string;
+    kind: DumpKind;
+    cacheDir: string;
+    fetch?: typeof globalThis.fetch;
+    sleep?: (milliseconds: number) => Promise<void>;
+}
+export interface FetchedDump {
+    path: string;
+    releaseId: string;
+    sha256: string;
+}
+export declare function downloadDump(url: URL, targetPath: string, expectedSha256?: string, fetchImplementation?: typeof globalThis.fetch): Promise<{
+    path: string;
+    sha256: string;
+}>;
+export declare function fetchFuyaoDump(options: FetchFuyaoDumpOptions): Promise<FetchedDump>;
+//# sourceMappingURL=dump-client.d.ts.map

package/dist/infrastructure/duckdb/dump-client.js

@@ -0,0 +1,66 @@
+import { createHash } from 'node:crypto';
+import { createWriteStream } from 'node:fs';
+import { mkdir, readFile, rename, rm } from 'node:fs/promises';
+import path from 'node:path';
+import { Readable } from 'node:stream';
+import { pipeline } from 'node:stream/promises';
+export async function downloadDump(url, targetPath, expectedSha256, fetchImplementation = globalThis.fetch) {
+    const absoluteTarget = path.resolve(targetPath);
+    const temporary = `${absoluteTarget}.${process.pid}.download`;
+    await mkdir(path.dirname(absoluteTarget), { recursive: true });
+    const response = await fetchImplementation(url);
+    if (!response.ok || response.body === null)
+        throw new Error(`Dump download failed: HTTP ${response.status}`);
+    try {
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(temporary, { flags: 'wx' }));
+        const sha256 = createHash('sha256')
+            .update(await readFile(temporary))
+            .digest('hex');
+        if (expectedSha256 !== undefined && sha256 !== expectedSha256)
+            throw new Error('Dump checksum mismatch');
+        await rename(temporary, absoluteTarget);
+        return { path: absoluteTarget, sha256 };
+    }
+    catch (error) {
+        await rm(temporary, { force: true });
+        throw error;
+    }
+}
+function releaseId(url) {
+    const segments = url.pathname.split('/').filter(Boolean);
+    return segments.slice(-2).join('/');
+}
+async function signDump(options, fetchImplementation) {
+    const url = new URL(`/api/dump/market-dumps/${options.kind}/download-url`, options.baseUrl);
+    const response = await fetchImplementation(url, {
+        headers: { 'X-api-key': options.apiKey, accept: 'application/json' },
+        signal: AbortSignal.timeout(30_000),
+    });
+    if (!response.ok)
+        throw new Error(`Dump signing failed: HTTP ${response.status}`);
+    const envelope = (await response.json());
+    if (envelope.code !== 0 || envelope.data?.presigned_url === undefined)
+        throw new Error(`Dump signing failed: ${envelope.code ?? 'invalid'} ${envelope.message ?? ''}`);
+    return new URL(envelope.data.presigned_url);
+}
+export async function fetchFuyaoDump(options) {
+    const fetchImplementation = options.fetch ?? globalThis.fetch;
+    const sleep = options.sleep ??
+        ((milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)));
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+        try {
+            const signedUrl = await signDump(options, fetchImplementation);
+            const target = path.join(options.cacheDir, `${options.kind}.parquet`);
+            const downloaded = await downloadDump(signedUrl, target, undefined, fetchImplementation);
+            return { ...downloaded, releaseId: releaseId(signedUrl) };
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt === 0)
+                await sleep(250);
+        }
+    }
+    throw lastError;
+}
+//# sourceMappingURL=dump-client.js.map

package/dist/infrastructure/duckdb/factors.d.ts

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

package/dist/infrastructure/duckdb/factors.js

@@ -0,0 +1,83 @@
+export async function rebuildAdjustmentFactors(connection) {
+    await connection.run('BEGIN TRANSACTION');
+    try {
+        await connection.run('DELETE FROM calc_adjust_factor_daily');
+        await connection.run(`
+      INSERT INTO calc_adjust_factor_daily(thscode, date, forward_factor, backward_factor)
+      WITH
+      -- CTE 1: effective_event — 确定除权事件的实际生效日期
+      -- 每个除权事件在 ex_date 当天或之后第一个有交易记录的日期生效
+      effective_event AS (
+        SELECT e.thscode, e.dividend_per_share AS d,
+               e.per_share_bonus AS s,           -- 每股送转股数
+               e.rights_ratio AS r,              -- 配股比例
+               COALESCE(e.rights_price, 0) AS p, -- 配股价格，无配股时默认为0
+               -- 查找除权日当天或之后第一个有K线数据的交易日作为生效日期
+               (SELECT MIN(k.date) FROM raw_kline_daily k
+                WHERE k.thscode=e.thscode AND k.date>=e.ex_date) AS eff_date
+        FROM raw_adjustment_events e
+      ),
+      -- CTE 2: kline_prev — 获取每个交易日的前一日收盘价
+      -- 使用 LAG 窗口函数取同股票的上一个交易日收盘价
+      kline_prev AS (
+        SELECT thscode, date,
+               LAG(close) OVER(PARTITION BY thscode ORDER BY date) AS prev_close
+        FROM raw_kline_daily
+      ),
+      -- CTE 3: event_ratio — 计算除权日对应的复权比率
+      -- 公式: ratio = (prev_close * (1 + s + r)) / (prev_close - d + r * p)
+      -- 其中 s=送转股数, r=配股比例, d=每股分红, p=配股价
+      -- NULLIF 防止除零错误
+      event_ratio AS (
+        SELECT e.thscode, e.eff_date AS date,
+          (k.prev_close * (1 + e.s + e.r)) /
+          NULLIF(k.prev_close - e.d + e.r * e.p, 0) AS ratio
+        FROM effective_event e JOIN kline_prev k
+          ON k.thscode=e.thscode AND k.date=e.eff_date
+        WHERE k.prev_close IS NOT NULL
+      ),
+      -- CTE 4: day_ratio — 合并同一天多个除权事件的比率
+      -- 使用对数求和: EXP(SUM(LN(ratio))) = ratio1 * ratio2 * ...
+      -- 只在 ratio > 0 时参与计算
+      day_ratio AS (
+        SELECT thscode, date,
+               EXP(SUM(LN(ratio))) AS ratio
+        FROM event_ratio WHERE ratio>0 GROUP BY thscode, date
+      ),
+      -- CTE 5: backward — 计算每个交易日的后复权因子
+      -- 使用窗口函数按股票分区、日期排序累积乘积
+      -- ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW 从上市首日累积到当日
+      -- COALESCE(r.ratio, 1) 表示非除权日的比率为1（不变化）
+      backward AS (
+        SELECT k.thscode, k.date,
+          EXP(SUM(LN(COALESCE(r.ratio,1))) OVER(
+            PARTITION BY k.thscode ORDER BY k.date
+            ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW)) AS backward_factor
+        FROM raw_kline_daily k LEFT JOIN day_ratio r USING(thscode, date)
+      ),
+      -- CTE 6: normalized — 计算前复权因子
+      -- 前复权因子 = 当日后复权因子 / 最后一个交易日的后复权因子
+      -- LAST_VALUE 窗口函数获取该股票全部交易日的最后一个后复权因子
+      normalized AS (
+        SELECT *,
+               LAST_VALUE(backward_factor) OVER(
+                 PARTITION BY thscode ORDER BY date
+                 ROWS BETWEEN UNBOUNDED PRECEDING AND UNBOUNDED FOLLOWING) AS last_factor
+        FROM backward
+      )
+      -- 最终输出：thscode, date, forward_factor, backward_factor
+      SELECT thscode, date,
+             backward_factor / NULLIF(last_factor, 0) AS forward_factor,
+             backward_factor
+      FROM normalized
+    `);
+        const reader = await connection.runAndReadAll('SELECT count(*) FROM calc_adjust_factor_daily');
+        await connection.run('COMMIT');
+        return Number(reader.getRowsJson()[0]?.[0] ?? 0);
+    }
+    catch (error) {
+        await connection.run('ROLLBACK').catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=factors.js.map

package/dist/infrastructure/duckdb/importer.d.ts

@@ -0,0 +1,11 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+export interface ParquetBundle {
+    klinePath: string;
+    eventsPath: string;
+    symbolsPath?: string;
+    batchId: string;
+    source: string;
+    mode?: 'FULL' | 'INCREMENTAL';
+}
+export declare function importParquetBundle(connection: DuckDBConnection, bundle: ParquetBundle): Promise<void>;
+//# sourceMappingURL=importer.d.ts.map

package/dist/infrastructure/duckdb/importer.js

@@ -0,0 +1,105 @@
+async function parquetColumns(connection, parquetPath) {
+    const reader = await connection.runAndReadAll('DESCRIBE SELECT * FROM read_parquet($path)', {
+        path: parquetPath,
+    });
+    return new Set(reader.getRowsJson().map((row) => String(row[0])));
+}
+function requireColumns(actual, required, kind) {
+    const missing = required.filter((column) => !actual.has(column));
+    if (missing.length > 0)
+        throw new Error(`${kind} dump is missing columns: ${missing.join(', ')}`);
+}
+export async function importParquetBundle(connection, bundle) {
+    await connection.run('BEGIN TRANSACTION');
+    try {
+        const klineColumns = await parquetColumns(connection, bundle.klinePath);
+        const eventColumns = await parquetColumns(connection, bundle.eventsPath);
+        const publishedKline = klineColumns.has('date_ms');
+        const publishedEvents = eventColumns.has('ex_date_ms');
+        requireColumns(klineColumns, publishedKline
+            ? [
+                'thscode',
+                'date_ms',
+                'open_price',
+                'high_price',
+                'low_price',
+                'close_price',
+                'volume',
+                'turnover',
+            ]
+            : ['thscode', 'date', 'open', 'high', 'low', 'close', 'volume', 'amount'], 'daily-k');
+        requireColumns(eventColumns, publishedEvents
+            ? [
+                'thscode',
+                'ex_date_ms',
+                'dividend_per_share',
+                'per_share_bonus',
+                'allotment_ratio',
+                'allotment_price',
+            ]
+            : [
+                'thscode',
+                'ex_date',
+                'dividend_per_share',
+                'per_share_bonus',
+                'rights_ratio',
+                'rights_price',
+            ], 'adjustment-factors');
+        await connection.run("INSERT INTO _import_batches(batch_id,source,started_at,status) VALUES ($batch,$source,CURRENT_TIMESTAMP,'running')", { batch: bundle.batchId, source: bundle.source });
+        await connection.run('DELETE FROM stg_kline_daily; DELETE FROM stg_adjustment_events; DELETE FROM stg_symbol');
+        await connection.run(publishedKline
+            ? `INSERT INTO stg_kline_daily SELECT thscode, CAST(epoch_ms(date_ms + 28800000) AS DATE), open_price, high_price, low_price, close_price, NULL::DOUBLE, volume, turnover, $batch FROM read_parquet($path)`
+            : `INSERT INTO stg_kline_daily SELECT thscode,date,open,high,low,close,prev_close,volume,amount,$batch FROM read_parquet($path)`, { path: bundle.klinePath, batch: bundle.batchId });
+        await connection.run(publishedEvents
+            ? `INSERT INTO stg_adjustment_events SELECT thscode, CAST(epoch_ms(ex_date_ms + 28800000) AS DATE), dividend_per_share, per_share_bonus, allotment_ratio, allotment_price, $batch FROM read_parquet($path)`
+            : `INSERT INTO stg_adjustment_events SELECT thscode,ex_date,dividend_per_share,per_share_bonus,rights_ratio,rights_price,$batch FROM read_parquet($path)`, { path: bundle.eventsPath, batch: bundle.batchId });
+        if (bundle.symbolsPath !== undefined) {
+            await connection.run('INSERT INTO stg_symbol SELECT * FROM read_parquet($path)', {
+                path: bundle.symbolsPath,
+            });
+        }
+        else {
+            await connection.run(`
+        INSERT INTO stg_symbol
+        SELECT DISTINCT
+          thscode,
+          split_part(thscode, '.', 1),
+          NULL::VARCHAR,
+          split_part(thscode, '.', 2),
+          'a-share',
+          CURRENT_TIMESTAMP
+        FROM stg_kline_daily
+      `);
+        }
+        if ((bundle.mode ?? 'FULL') === 'FULL') {
+            await connection.run('DELETE FROM raw_kline_daily');
+        }
+        else {
+            await connection.run(`
+        DELETE FROM raw_kline_daily
+        WHERE date BETWEEN (SELECT min(date) FROM stg_kline_daily)
+                       AND (SELECT max(date) FROM stg_kline_daily)
+      `);
+        }
+        await connection.run('INSERT OR REPLACE INTO raw_kline_daily SELECT * FROM stg_kline_daily');
+        await connection.run('DELETE FROM raw_adjustment_events');
+        await connection.run('INSERT OR REPLACE INTO raw_adjustment_events SELECT * FROM stg_adjustment_events');
+        await connection.run(`
+      INSERT INTO dim_symbol
+      SELECT * FROM stg_symbol
+      ON CONFLICT (thscode) DO UPDATE SET
+        ticker=COALESCE(excluded.ticker,dim_symbol.ticker),
+        name=COALESCE(excluded.name,dim_symbol.name),
+        exchange=COALESCE(excluded.exchange,dim_symbol.exchange),
+        asset_type=excluded.asset_type,
+        updated_at=excluded.updated_at
+    `);
+        await connection.run("UPDATE _import_batches SET completed_at=CURRENT_TIMESTAMP,status='complete',row_count=(SELECT count(*) FROM stg_kline_daily) WHERE batch_id=$batch", { batch: bundle.batchId });
+        await connection.run('COMMIT');
+    }
+    catch (error) {
+        await connection.run('ROLLBACK').catch(() => undefined);
+        throw error;
+    }
+}
+//# sourceMappingURL=importer.js.map

package/dist/infrastructure/duckdb/migrations.d.ts

@@ -0,0 +1,17 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+export interface Migration {
+    version: number;
+    name: string;
+    type: 'safe' | 'heavy' | 'destructive';
+    checksum: string;
+    sql: string;
+}
+export declare function planMigrations(connection: DuckDBConnection, available?: readonly Migration[]): Promise<Migration[]>;
+export declare function applyMigrations(connection: DuckDBConnection, available?: readonly Migration[], options?: {
+    allowHeavy?: boolean;
+    allowDestructive?: boolean;
+}): Promise<void>;
+export declare function assertSchemaCompatibility(connection: DuckDBConnection, supportedVersion?: number): Promise<{
+    version: number;
+}>;
+//# sourceMappingURL=migrations.d.ts.map

package/dist/infrastructure/duckdb/migrations.js

@@ -0,0 +1,92 @@
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { CliError } from '../../contracts/errors.js';
+import { SUPPORTED_SCHEMA_VERSION } from './schema.js';
+function normalizeLineEndings(value) {
+    return value.replaceAll('\r\n', '\n');
+}
+const manifestSchema = z.object({
+    schemaVersion: z.number().int().positive(),
+    migrations: z.array(z.object({
+        version: z.number().int().positive(),
+        name: z.string().min(1),
+        type: z.enum(['safe', 'heavy', 'destructive']),
+        file: z.string().min(1),
+        checksum: z.string().regex(/^[a-f0-9]{64}$/u),
+    })),
+});
+function migrationRoot() {
+    return path.resolve(import.meta.dirname, '../../../migrations');
+}
+async function bundledMigrations() {
+    const root = migrationRoot();
+    const manifest = manifestSchema.parse(JSON.parse(await readFile(path.join(root, 'manifest.json'), 'utf8')));
+    const migrations = [];
+    for (const entry of manifest.migrations) {
+        const sql = normalizeLineEndings(await readFile(path.join(root, entry.file), 'utf8'));
+        const checksum = createHash('sha256').update(sql).digest('hex');
+        if (checksum !== entry.checksum) {
+            throw new Error(`Migration checksum mismatch for ${entry.file}`);
+        }
+        migrations.push({ ...entry, sql });
+    }
+    return migrations;
+}
+async function schemaVersion(connection) {
+    const tableReader = await connection.runAndReadAll("SELECT count(*) FROM information_schema.tables WHERE table_schema='main' AND table_name='_meta'");
+    if (Number(tableReader.getRowsJson()[0]?.[0] ?? 0) === 0)
+        return 0;
+    const reader = await connection.runAndReadAll("SELECT value FROM _meta WHERE key='schema_version' LIMIT 1");
+    const value = reader.getRowsJson()[0]?.[0];
+    return value === undefined ? 0 : Number(value);
+}
+export async function planMigrations(connection, available) {
+    const current = await schemaVersion(connection);
+    const migrations = available === undefined ? await bundledMigrations() : [...available];
+    return migrations
+        .filter((migration) => migration.version > current)
+        .sort((a, b) => a.version - b.version);
+}
+export async function applyMigrations(connection, available, options = {}) {
+    const pending = await planMigrations(connection, available);
+    for (const migration of pending) {
+        if ((migration.type === 'heavy' && options.allowHeavy !== true) ||
+            (migration.type === 'destructive' && options.allowDestructive !== true)) {
+            throw new CliError({
+                code: 'DATA_MIGRATION_CONFIRMATION_REQUIRED',
+                category: 'local-data',
+                message: `Migration ${migration.version} (${migration.name}) requires explicit confirmation.`,
+                hint: 'Run `hithink-finance data migrate --apply --yes` after reviewing the plan.',
+                retryable: false,
+                exitCode: 5,
+            });
+        }
+        await connection.run('BEGIN TRANSACTION');
+        try {
+            await connection.run(migration.sql);
+            await connection.run("INSERT OR REPLACE INTO _meta(key, value) VALUES ('schema_version', $version), ('schema_checksum', $checksum)", { version: String(migration.version), checksum: migration.checksum });
+            await connection.run('COMMIT');
+        }
+        catch (error) {
+            await connection.run('ROLLBACK').catch(() => undefined);
+            throw error;
+        }
+    }
+}
+export async function assertSchemaCompatibility(connection, supportedVersion = SUPPORTED_SCHEMA_VERSION) {
+    const version = await schemaVersion(connection);
+    if (version > supportedVersion) {
+        throw new CliError({
+            code: 'DATA_SCHEMA_TOO_NEW',
+            category: 'local-data',
+            message: `Database schema ${version} is newer than supported schema ${supportedVersion}.`,
+            hint: 'Upgrade hithink-finance before writing to this database.',
+            retryable: false,
+            exitCode: 5,
+        });
+    }
+    return { version };
+}
+//# sourceMappingURL=migrations.js.map

package/dist/infrastructure/duckdb/quality.d.ts

@@ -0,0 +1,12 @@
+import type { DuckDBConnection } from '@duckdb/node-api';
+export interface QualityIssue {
+    code: string;
+    count: number;
+    message: string;
+}
+export interface QualityResult {
+    ok: boolean;
+    issues: QualityIssue[];
+}
+export declare function validateDatabase(connection: DuckDBConnection): Promise<QualityResult>;
+//# sourceMappingURL=quality.d.ts.map