@hithink-tech/hithink-finance-cli 0.1.0

package/dist/infrastructure/skills/manifest.d.ts

@@ -0,0 +1,11 @@
+export interface ManagedSkillManifest {
+    protocolVersion: '1';
+    cliVersion: string;
+    files: Record<string, string>;
+}
+export declare function buildSkillManifest(root: string, cliVersion: string): Promise<ManagedSkillManifest>;
+export declare function reconcileManagedSkills(source: string, target: string, next: ManagedSkillManifest, previous?: ManagedSkillManifest): Promise<{
+    backups: string[];
+}>;
+export declare function removeManagedSkills(target: string, manifest: ManagedSkillManifest): Promise<void>;
+//# sourceMappingURL=manifest.d.ts.map

package/dist/infrastructure/skills/manifest.js

@@ -0,0 +1,62 @@
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readdir, readFile, rm, stat } from 'node:fs/promises';
+import path from 'node:path';
+async function files(root, current = root) {
+    const output = [];
+    for (const entry of await readdir(current, { withFileTypes: true })) {
+        const absolute = path.join(current, entry.name);
+        if (entry.isDirectory())
+            output.push(...(await files(root, absolute)));
+        else if (entry.isFile())
+            output.push(path.relative(root, absolute).replaceAll(path.sep, '/'));
+    }
+    return output.sort();
+}
+async function hash(file) {
+    return createHash('sha256')
+        .update(await readFile(file))
+        .digest('hex');
+}
+export async function buildSkillManifest(root, cliVersion) {
+    const entries = {};
+    for (const relative of await files(root))
+        entries[relative] = await hash(path.join(root, ...relative.split('/')));
+    return { protocolVersion: '1', cliVersion, files: entries };
+}
+async function exists(file) {
+    try {
+        return (await stat(file)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+export async function reconcileManagedSkills(source, target, next, previous) {
+    const backups = [];
+    for (const [relative, nextHash] of Object.entries(next.files)) {
+        const sourceFile = path.join(source, ...relative.split('/'));
+        const targetFile = path.join(target, ...relative.split('/'));
+        await mkdir(path.dirname(targetFile), { recursive: true });
+        if (await exists(targetFile)) {
+            const currentHash = await hash(targetFile);
+            const oldHash = previous?.files[relative];
+            if (oldHash !== undefined && currentHash !== oldHash && currentHash !== nextHash) {
+                const backup = `${targetFile}.backup-${Date.now()}`;
+                await copyFile(targetFile, backup);
+                backups.push(backup);
+            }
+        }
+        await copyFile(sourceFile, targetFile);
+    }
+    if (previous !== undefined) {
+        for (const relative of Object.keys(previous.files))
+            if (!(relative in next.files))
+                await rm(path.join(target, ...relative.split('/')), { force: true });
+    }
+    return { backups };
+}
+export async function removeManagedSkills(target, manifest) {
+    for (const relative of Object.keys(manifest.files))
+        await rm(path.join(target, ...relative.split('/')), { force: true });
+}
+//# sourceMappingURL=manifest.js.map

package/dist/infrastructure/updater/cache.d.ts

@@ -0,0 +1,15 @@
+export interface UpdateCacheState {
+    checkedAt: number;
+    status: 'success' | 'failure';
+    refreshStartedAt?: number;
+    promptedAt?: number;
+    promptedCurrentVersion?: string;
+    promptedLatestVersion?: string;
+    latestVersion?: string;
+}
+export type UpdateCacheDecision = 'disabled' | 'fresh' | 'cooldown' | 'refreshing' | 'refresh';
+export type UpdatePromptDecision = 'none' | 'prompt';
+export declare function updateCacheDecision(state: UpdateCacheState | undefined, now: number, disabled?: boolean): UpdateCacheDecision;
+export declare function compareSemver(leftVersion: string, rightVersion: string): number;
+export declare function updatePromptDecision(state: UpdateCacheState | undefined, currentVersion: string, now: number, disabled?: boolean): UpdatePromptDecision;
+//# sourceMappingURL=cache.d.ts.map

package/dist/infrastructure/updater/cache.js

@@ -0,0 +1,76 @@
+const PROMPT_TTL_MS = 24 * 3_600_000;
+export function updateCacheDecision(state, now, disabled = false) {
+    if (disabled)
+        return 'disabled';
+    if (state?.refreshStartedAt !== undefined && now - state.refreshStartedAt < 5 * 60_000)
+        return 'refreshing';
+    if (state === undefined)
+        return 'refresh';
+    const age = now - state.checkedAt;
+    if (state.status === 'success' && age < 24 * 3_600_000)
+        return 'fresh';
+    if (state.status === 'failure' && age < 6 * 3_600_000)
+        return 'cooldown';
+    return 'refresh';
+}
+function parseSemver(value) {
+    const match = /^(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?$/u.exec(value);
+    if (match === null)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4]?.split('.') ?? [],
+    };
+}
+function comparePrerelease(left, right) {
+    if (left.length === 0 && right.length === 0)
+        return 0;
+    if (left.length === 0)
+        return 1;
+    if (right.length === 0)
+        return -1;
+    const length = Math.max(left.length, right.length);
+    for (let index = 0; index < length; index += 1) {
+        const leftPart = left[index];
+        const rightPart = right[index];
+        if (leftPart === undefined)
+            return -1;
+        if (rightPart === undefined)
+            return 1;
+        if (leftPart === rightPart)
+            continue;
+        const leftNumeric = /^\d+$/u.test(leftPart);
+        const rightNumeric = /^\d+$/u.test(rightPart);
+        if (leftNumeric && rightNumeric)
+            return Number(leftPart) - Number(rightPart);
+        if (leftNumeric)
+            return -1;
+        if (rightNumeric)
+            return 1;
+        return leftPart.localeCompare(rightPart);
+    }
+    return 0;
+}
+export function compareSemver(leftVersion, rightVersion) {
+    const left = parseSemver(leftVersion);
+    const right = parseSemver(rightVersion);
+    if (left === undefined || right === undefined)
+        return 0;
+    const core = left.major - right.major || left.minor - right.minor || left.patch - right.patch;
+    return core === 0 ? comparePrerelease(left.prerelease, right.prerelease) : core;
+}
+export function updatePromptDecision(state, currentVersion, now, disabled = false) {
+    if (disabled || state?.status !== 'success' || state.latestVersion === undefined)
+        return 'none';
+    if (compareSemver(state.latestVersion, currentVersion) <= 0)
+        return 'none';
+    if (state.promptedAt !== undefined &&
+        state.promptedCurrentVersion === currentVersion &&
+        state.promptedLatestVersion === state.latestVersion &&
+        now - state.promptedAt < PROMPT_TTL_MS)
+        return 'none';
+    return 'prompt';
+}
+//# sourceMappingURL=cache.js.map

package/dist/infrastructure/updater/check.d.ts

@@ -0,0 +1,13 @@
+import type { UpdateCacheState } from './cache.js';
+export declare function readUpdateCache(file: string): Promise<UpdateCacheState | undefined>;
+export declare function scheduleUpdateCheck(packageRoot: string, packageName: string, cacheFile: string): void;
+export interface UpdateNoticeOptions {
+    packageRoot: string;
+    packageName: string;
+    currentVersion: string;
+    cacheFile: string;
+    stderr: NodeJS.WriteStream;
+    disabled?: boolean;
+}
+export declare function maybeEmitCachedUpdateNotice(options: UpdateNoticeOptions): Promise<void>;
+//# sourceMappingURL=check.d.ts.map

package/dist/infrastructure/updater/check.js

@@ -0,0 +1,51 @@
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { updateCacheDecision, updatePromptDecision } from './cache.js';
+export async function readUpdateCache(file) {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch {
+        return undefined;
+    }
+}
+async function writeUpdateCache(file, state) {
+    await mkdir(path.dirname(file), { recursive: true });
+    const temporary = `${file}.${process.pid}.tmp`;
+    await writeFile(temporary, `${JSON.stringify(state)}\n`, { mode: 0o600 });
+    await rename(temporary, file);
+}
+export function scheduleUpdateCheck(packageRoot, packageName, cacheFile) {
+    const child = spawn(process.execPath, [path.join(packageRoot, 'scripts', 'update-check.mjs'), packageName, cacheFile], { detached: true, stdio: 'ignore', windowsHide: true, env: process.env });
+    child.unref();
+}
+export async function maybeEmitCachedUpdateNotice(options) {
+    try {
+        const cached = await readUpdateCache(options.cacheFile);
+        const now = Date.now();
+        const disabled = options.disabled === true;
+        const decision = updateCacheDecision(cached, now, disabled);
+        if (decision === 'refresh') {
+            scheduleUpdateCheck(options.packageRoot, options.packageName, options.cacheFile);
+        }
+        if (cached === undefined ||
+            cached.latestVersion === undefined ||
+            updatePromptDecision(cached, options.currentVersion, now, disabled) !== 'prompt')
+            return;
+        const latestVersion = cached.latestVersion;
+        options.stderr.write(`[update] A newer hithink-finance CLI version is available: ${latestVersion} ` +
+            `(current ${options.currentVersion}).\n` +
+            'Run `hithink-finance update --check --format json` to inspect it; ' +
+            'run `hithink-finance update --repair` to update after confirmation.\n');
+        await writeUpdateCache(options.cacheFile, {
+            ...cached,
+            promptedAt: now,
+            promptedCurrentVersion: options.currentVersion,
+            promptedLatestVersion: latestVersion,
+        });
+    }
+    catch {
+    }
+}
+//# sourceMappingURL=check.js.map

package/dist/infrastructure/updater/install.d.ts

@@ -0,0 +1,4 @@
+export declare function installGlobalPackage(npmExecutable: string, packageName: string, version: string): Promise<number>;
+export declare function runExecutable(executable: string, executableArgs: string[]): Promise<number>;
+export declare function uninstallGlobalPackage(npmExecutable: string, packageName: string): Promise<number>;
+//# sourceMappingURL=install.d.ts.map

package/dist/infrastructure/updater/install.js

@@ -0,0 +1,39 @@
+import { spawn } from 'node:child_process';
+export async function installGlobalPackage(npmExecutable, packageName, version) {
+    return new Promise((resolve, reject) => {
+        const npmArgs = ['install', '-g', `${packageName}@${version}`];
+        const isWindowsScript = process.platform === 'win32' && /\.(cmd|bat)$/iu.test(npmExecutable);
+        const command = isWindowsScript ? (process.env.ComSpec ?? 'cmd.exe') : npmExecutable;
+        const args = isWindowsScript
+            ?
+                ['/d', '/s', '/c', npmExecutable, ...npmArgs]
+            : npmArgs;
+        const child = spawn(command, args, {
+            stdio: 'inherit',
+            windowsHide: true,
+            env: process.env,
+        });
+        child.once('error', reject);
+        child.once('exit', (code) => resolve(code ?? 1));
+    });
+}
+export async function runExecutable(executable, executableArgs) {
+    return new Promise((resolve, reject) => {
+        const isWindowsScript = process.platform === 'win32' && /\.(cmd|bat)$/iu.test(executable);
+        const command = isWindowsScript ? (process.env.ComSpec ?? 'cmd.exe') : executable;
+        const args = isWindowsScript
+            ? ['/d', '/s', '/c', executable, ...executableArgs]
+            : executableArgs;
+        const child = spawn(command, args, {
+            stdio: 'inherit',
+            windowsHide: true,
+            env: process.env,
+        });
+        child.once('error', reject);
+        child.once('exit', (code) => resolve(code ?? 1));
+    });
+}
+export async function uninstallGlobalPackage(npmExecutable, packageName) {
+    return runExecutable(npmExecutable, ['uninstall', '-g', packageName]);
+}
+//# sourceMappingURL=install.js.map

package/dist/output/json.d.ts

@@ -0,0 +1,3 @@
+export declare function externalize(value: unknown): unknown;
+export declare function renderJson(value: unknown): string;
+//# sourceMappingURL=json.d.ts.map

package/dist/output/json.js

@@ -0,0 +1,16 @@
+function snakeCase(key) {
+    return key.replace(/[A-Z]/g, (letter) => `_${letter.toLowerCase()}`);
+}
+export function externalize(value) {
+    if (Array.isArray(value)) {
+        return value.map(externalize);
+    }
+    if (value !== null && typeof value === 'object') {
+        return Object.fromEntries(Object.entries(value).map(([key, entry]) => [snakeCase(key), externalize(entry)]));
+    }
+    return value;
+}
+export function renderJson(value) {
+    return `${JSON.stringify(externalize(value))}\n`;
+}
+//# sourceMappingURL=json.js.map

package/dist/output/renderer.d.ts

@@ -0,0 +1,4 @@
+import type { CliContext } from '../cli/context.js';
+import type { Envelope } from '../contracts/envelope.js';
+export declare function renderResult(result: Envelope, context: CliContext): Promise<void>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/output/renderer.js

@@ -0,0 +1,47 @@
+import { externalize, renderJson } from './json.js';
+import { renderTable } from './table.js';
+function resolvedFormat(context) {
+    if (context.format !== 'auto') {
+        return context.format;
+    }
+    return context.stdout.isTTY === true ? 'table' : 'json';
+}
+function csvEscape(value) {
+    if (value === null || value === undefined)
+        return '';
+    const text = typeof value === 'object' ? JSON.stringify(externalize(value)) : String(externalize(value));
+    return /[",\n\r]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+function renderCsv(value) {
+    const external = externalize(value);
+    const rows = Array.isArray(external) ? external : [external];
+    if (rows.length === 0)
+        return '\n';
+    if (rows.every((row) => row !== null && typeof row === 'object' && !Array.isArray(row))) {
+        const headers = [
+            ...new Set(rows.flatMap((row) => Object.keys(row))),
+        ];
+        return `${headers.join(',')}\n${rows
+            .map((row) => headers.map((header) => csvEscape(row[header])).join(','))
+            .join('\n')}\n`;
+    }
+    return `value\n${rows.map(csvEscape).join('\n')}\n`;
+}
+export async function renderResult(result, context) {
+    const stream = result.ok ? context.stdout : context.stderr;
+    const format = resolvedFormat(context);
+    if (format === 'json' || format === 'ndjson') {
+        stream.write(renderJson(result));
+        return;
+    }
+    if (format === 'csv' && result.ok) {
+        stream.write(renderCsv(result.data));
+        return;
+    }
+    if (!result.ok) {
+        stream.write(`hithink-finance v${result.meta.cliVersion} — Error (${result.error.code}): ${result.error.message}\n${result.error.hint}\n`);
+        return;
+    }
+    stream.write(renderTable(result.data));
+}
+//# sourceMappingURL=renderer.js.map

package/dist/output/table.d.ts

@@ -0,0 +1,2 @@
+export declare function renderTable(value: unknown): string;
+//# sourceMappingURL=table.d.ts.map

package/dist/output/table.js

@@ -0,0 +1,31 @@
+export function renderTable(value) {
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return `${String(value)}\n`;
+    }
+    if (value !== null && typeof value === 'object' && !Array.isArray(value)) {
+        return rowsToTable(['key', 'value'], Object.entries(value).map(([key, entry]) => [key, cell(entry)]));
+    }
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return '(empty)\n';
+        if (value.every((entry) => entry !== null && typeof entry === 'object' && !Array.isArray(entry))) {
+            const records = value;
+            const headers = [...new Set(records.flatMap((record) => Object.keys(record)))];
+            return rowsToTable(headers, records.map((record) => headers.map((header) => cell(record[header]))));
+        }
+        return rowsToTable(['value'], value.map((entry) => [cell(entry)]));
+    }
+    return `${cell(value)}\n`;
+}
+function cell(value) {
+    if (value === null || value === undefined)
+        return '';
+    return typeof value === 'object' ? JSON.stringify(value) : String(value);
+}
+function rowsToTable(headers, rows) {
+    const widths = headers.map((header, index) => Math.max(header.length, ...rows.map((row) => row[index]?.length ?? 0)));
+    const renderRow = (row) => `| ${row.map((entry, index) => entry.padEnd(widths[index] ?? 0)).join(' | ')} |`;
+    const separator = `| ${widths.map((width) => '-'.repeat(width)).join(' | ')} |`;
+    return `${[renderRow(headers), separator, ...rows.map(renderRow)].join('\n')}\n`;
+}
+//# sourceMappingURL=table.js.map

package/migrations/001-initial.sql

@@ -0,0 +1,95 @@
+CREATE TABLE IF NOT EXISTS _meta (
+  key VARCHAR PRIMARY KEY,
+  value VARCHAR NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS _import_batches (
+  batch_id VARCHAR PRIMARY KEY,
+  source VARCHAR NOT NULL,
+  started_at TIMESTAMP NOT NULL,
+  completed_at TIMESTAMP,
+  status VARCHAR NOT NULL,
+  row_count BIGINT,
+  content_hash VARCHAR,
+  error_code VARCHAR
+);
+
+CREATE TABLE IF NOT EXISTS raw_kline_daily (
+  thscode VARCHAR NOT NULL,
+  date DATE NOT NULL,
+  open DOUBLE NOT NULL,
+  high DOUBLE NOT NULL,
+  low DOUBLE NOT NULL,
+  close DOUBLE NOT NULL,
+  prev_close DOUBLE,
+  volume DOUBLE NOT NULL,
+  amount DOUBLE NOT NULL,
+  batch_id VARCHAR,
+  PRIMARY KEY (thscode, date)
+);
+
+CREATE TABLE IF NOT EXISTS raw_adjustment_events (
+  thscode VARCHAR NOT NULL,
+  ex_date DATE NOT NULL,
+  dividend_per_share DOUBLE NOT NULL DEFAULT 0,
+  per_share_bonus DOUBLE NOT NULL DEFAULT 0,
+  rights_ratio DOUBLE NOT NULL DEFAULT 0,
+  rights_price DOUBLE,
+  batch_id VARCHAR,
+  PRIMARY KEY (thscode, ex_date)
+);
+
+CREATE TABLE IF NOT EXISTS dim_symbol (
+  thscode VARCHAR PRIMARY KEY,
+  ticker VARCHAR,
+  name VARCHAR,
+  exchange VARCHAR,
+  asset_type VARCHAR NOT NULL DEFAULT 'a-share',
+  updated_at TIMESTAMP
+);
+
+CREATE TABLE IF NOT EXISTS calc_adjust_factor_daily (
+  thscode VARCHAR NOT NULL,
+  date DATE NOT NULL,
+  forward_factor DOUBLE NOT NULL,
+  backward_factor DOUBLE NOT NULL,
+  PRIMARY KEY (thscode, date)
+);
+
+CREATE TABLE IF NOT EXISTS stg_kline_daily AS SELECT * FROM raw_kline_daily WHERE FALSE;
+CREATE TABLE IF NOT EXISTS stg_adjustment_events AS SELECT * FROM raw_adjustment_events WHERE FALSE;
+CREATE TABLE IF NOT EXISTS stg_symbol AS SELECT * FROM dim_symbol WHERE FALSE;
+
+CREATE OR REPLACE VIEW v_symbol AS
+SELECT thscode, ticker, name, exchange, asset_type, updated_at
+FROM dim_symbol;
+
+CREATE OR REPLACE VIEW v_daily AS
+SELECT thscode, date, open, high, low, close, prev_close, volume, amount
+FROM raw_kline_daily;
+
+CREATE OR REPLACE VIEW v_daily_qfq AS
+SELECT
+  d.thscode,
+  d.date,
+  d.open * COALESCE(f.forward_factor, 1) AS open,
+  d.high * COALESCE(f.forward_factor, 1) AS high,
+  d.low * COALESCE(f.forward_factor, 1) AS low,
+  d.close * COALESCE(f.forward_factor, 1) AS close,
+  d.volume,
+  d.amount
+FROM raw_kline_daily d
+LEFT JOIN calc_adjust_factor_daily f USING (thscode, date);
+
+CREATE OR REPLACE VIEW v_daily_hfq AS
+SELECT
+  d.thscode,
+  d.date,
+  d.open * COALESCE(f.backward_factor, 1) AS open,
+  d.high * COALESCE(f.backward_factor, 1) AS high,
+  d.low * COALESCE(f.backward_factor, 1) AS low,
+  d.close * COALESCE(f.backward_factor, 1) AS close,
+  d.volume,
+  d.amount
+FROM raw_kline_daily d
+LEFT JOIN calc_adjust_factor_daily f USING (thscode, date);

package/migrations/manifest.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "migrations": [
+    {
+      "version": 1,
+      "name": "initial",
+      "type": "safe",
+      "file": "001-initial.sql",
+      "checksum": "de348d8053706344413a06d58b3420baa227058a627b727402f98a33458fbab3"
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@hithink-tech/hithink-finance-cli",
+  "version": "0.1.0",
+  "description": "hithink finance CLI for humans, automation, and AI agents",
+  "type": "module",
+  "bin": {
+    "hithink-finance": "./dist/cli/main.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "schemas",
+    "migrations",
+    "skills",
+    "scripts/postinstall.mjs",
+    "scripts/update-check.mjs",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "generate:contracts": "npm run build && node scripts/generate-contracts.mjs && prettier --write \"schemas/*.json\" \"skills/**/*.md\"",
+    "postinstall": "node scripts/postinstall.mjs",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --check .",
+    "verify": "npm run format && npm run lint && npm run typecheck && npm run test && npm run build",
+    "prepublishOnly": "node scripts/check-license.mjs && npm run verify"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HiThink-Tech/Financial-API.git",
+    "directory": "hithink-finance-cli"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "homepage": "https://github.com/HiThink-Tech/Financial-API/tree/main/hithink-finance-cli",
+  "bugs": {
+    "url": "https://github.com/HiThink-Tech/Financial-API/issues"
+  },
+  "dependencies": {
+    "@duckdb/node-api": "1.5.4-r.1",
+    "@napi-rs/keyring": "1.3.0",
+    "commander": "15.0.0",
+    "skills": "1.5.15",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@eslint/js": "10.0.1",
+    "@types/node": "22.15.1",
+    "eslint": "10.6.0",
+    "execa": "9.6.1",
+    "prettier": "3.9.4",
+    "typescript": "6.0.3",
+    "typescript-eslint": "8.63.0",
+    "vitest": "4.1.10"
+  }
+}