@hithink-tech/hithink-finance-cli 0.1.0

package/dist/commands/system/update.js

@@ -0,0 +1,72 @@
+import { localizeText } from '../../cli/i18n.js';
+import { successEnvelope } from '../../contracts/envelope.js';
+import { CliError } from '../../contracts/errors.js';
+import { installGlobalPackage, runExecutable } from '../../infrastructure/updater/install.js';
+import { renderResult } from '../../output/renderer.js';
+import { readUpdateCache, scheduleUpdateCheck } from '../../infrastructure/updater/check.js';
+import { updateCacheDecision } from '../../infrastructure/updater/cache.js';
+import path from 'node:path';
+export function registerUpdateCommand(program, context, metadata, dependencies) {
+    const command = program
+        .command('update')
+        .description(localizeText(context.language, 'Check or repair the installed CLI version'))
+        .option('--check', localizeText(context.language, 'Check for a newer version without installing'))
+        .option('--repair', localizeText(context.language, 'Repair the current or target installation'))
+        .option('--target-version <version>', localizeText(context.language, 'Install a specific SemVer version'));
+    command.action(async () => {
+        const options = command.opts();
+        if (options.check === true) {
+            const cacheFile = path.join(dependencies.platformPaths.stateDir, 'update-cache.json');
+            const cached = await readUpdateCache(cacheFile);
+            const decision = updateCacheDecision(cached, Date.now(), !dependencies.resolvedConfig.updateCheck);
+            if (decision === 'refresh')
+                scheduleUpdateCheck(dependencies.packageRoot, metadata.name, cacheFile);
+            await renderResult(successEnvelope('update.check', {
+                currentVersion: metadata.version,
+                latestVersion: cached?.latestVersion,
+                cacheStatus: decision,
+                refreshScheduled: decision === 'refresh',
+                networkUsed: false,
+            }, { requestId: context.requestId }), context);
+            return;
+        }
+        const version = options.targetVersion ?? metadata.version;
+        if (!/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(version)) {
+            throw new CliError({
+                code: 'CLI_BAD_ARGUMENT',
+                category: 'validation',
+                message: 'Update version must be a valid SemVer value.',
+                hint: 'Use a version such as 1.2.3 or 1.2.3-next.1.',
+                retryable: false,
+                exitCode: 2,
+            });
+        }
+        const npm = process.env.HITHINK_FINANCE_NPM_EXECUTABLE ??
+            (process.platform === 'win32' ? 'npm.cmd' : 'npm');
+        const code = await installGlobalPackage(npm, metadata.name, version);
+        if (code !== 0)
+            throw new CliError({
+                code: 'UPDATE_INSTALL_FAILED',
+                category: 'internal',
+                message: 'npm global installation failed.',
+                hint: 'Run update --repair after checking npm permissions.',
+                retryable: true,
+                exitCode: 1,
+            });
+        const cli = process.env.HITHINK_FINANCE_CLI_EXECUTABLE ??
+            (process.platform === 'win32' ? 'hithink-finance.cmd' : 'hithink-finance');
+        const skillsCode = await runExecutable(cli, ['skills', 'sync', '--repair', '--yes']);
+        const doctorCode = await runExecutable(cli, ['doctor', '--format', 'json']);
+        if (skillsCode !== 0 || doctorCode !== 0)
+            throw new CliError({
+                code: 'UPDATE_REPAIR_PARTIAL',
+                category: 'internal',
+                message: 'The package updated, but Skill synchronization or doctor failed.',
+                hint: 'Run `hithink-finance update --repair`.',
+                retryable: true,
+                exitCode: 6,
+            });
+        await renderResult(successEnvelope('update', { version, repaired: options.repair === true }, { requestId: context.requestId }), context);
+    });
+}
+//# sourceMappingURL=update.js.map

package/dist/contracts/envelope.d.ts

@@ -0,0 +1,37 @@
+import { CliError, type ErrorCategory } from './errors.js';
+export interface ResultMeta {
+    source?: 'local' | 'remote';
+    count?: number;
+    asOf?: string;
+    adjust?: string;
+    truncated: boolean;
+    requestId: string;
+    schemaVersion: '1';
+}
+export interface ResultEnvelope<T> {
+    ok: true;
+    command: string;
+    data: T;
+    meta: ResultMeta;
+}
+export interface ErrorBody {
+    code: string;
+    category: ErrorCategory;
+    message: string;
+    hint: string;
+    retryable: boolean;
+    requestId?: string;
+}
+export interface ErrorEnvelope {
+    ok: false;
+    command: string;
+    error: ErrorBody;
+    meta: {
+        cliVersion: string;
+        schemaVersion: '1';
+    };
+}
+export type Envelope<T = unknown> = ResultEnvelope<T> | ErrorEnvelope;
+export declare function successEnvelope<T>(command: string, data: T, meta: Partial<ResultMeta> & Pick<ResultMeta, 'requestId'>): ResultEnvelope<T>;
+export declare function errorEnvelope(command: string, error: CliError, cliVersion: string): ErrorEnvelope;
+//# sourceMappingURL=envelope.d.ts.map

package/dist/contracts/envelope.js

@@ -0,0 +1,36 @@
+import { CliError } from './errors.js';
+import { redactText } from '../infrastructure/credentials/redact.js';
+export function successEnvelope(command, data, meta) {
+    return {
+        ok: true,
+        command,
+        data,
+        meta: {
+            ...meta,
+            truncated: meta.truncated ?? false,
+            schemaVersion: '1',
+        },
+    };
+}
+export function errorEnvelope(command, error, cliVersion) {
+    const body = {
+        code: error.code,
+        category: error.category,
+        message: redactText(error.message),
+        hint: redactText(error.hint),
+        retryable: error.retryable,
+    };
+    if (error.requestId !== undefined) {
+        body.requestId = error.requestId;
+    }
+    return {
+        ok: false,
+        command,
+        error: body,
+        meta: {
+            cliVersion,
+            schemaVersion: '1',
+        },
+    };
+}
+//# sourceMappingURL=envelope.js.map

package/dist/contracts/errors.d.ts

@@ -0,0 +1,23 @@
+export type ErrorCategory = 'validation' | 'authentication' | 'upstream' | 'local-data' | 'internal';
+export type ExitCode = 0 | 1 | 2 | 3 | 4 | 5 | 6;
+export { redactText } from '../infrastructure/credentials/redact.js';
+export interface CliErrorOptions {
+    code: string;
+    category: ErrorCategory;
+    message: string;
+    hint: string;
+    retryable: boolean;
+    exitCode: Exclude<ExitCode, 0>;
+    requestId?: string;
+}
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly category: ErrorCategory;
+    readonly hint: string;
+    readonly retryable: boolean;
+    readonly exitCode: Exclude<ExitCode, 0>;
+    readonly requestId: string | undefined;
+    constructor(options: CliErrorOptions);
+}
+export declare function internalError(error: unknown): CliError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/contracts/errors.js

@@ -0,0 +1,33 @@
+export { redactText } from '../infrastructure/credentials/redact.js';
+export class CliError extends Error {
+    code;
+    category;
+    hint;
+    retryable;
+    exitCode;
+    requestId;
+    constructor(options) {
+        super(options.message);
+        this.name = 'CliError';
+        this.code = options.code;
+        this.category = options.category;
+        this.hint = options.hint;
+        this.retryable = options.retryable;
+        this.exitCode = options.exitCode;
+        this.requestId = options.requestId;
+    }
+}
+export function internalError(error) {
+    if (error instanceof CliError) {
+        return error;
+    }
+    return new CliError({
+        code: 'CLI_INTERNAL_ERROR',
+        category: 'internal',
+        message: error instanceof Error ? error.message : 'Unexpected internal error.',
+        hint: 'Run the command again with --debug and report the request ID if the error persists.',
+        retryable: false,
+        exitCode: 1,
+    });
+}
+//# sourceMappingURL=errors.js.map

package/dist/contracts/local-capabilities.d.ts

@@ -0,0 +1,13 @@
+export interface LocalCapabilityDescriptor {
+    id: string;
+    command: readonly [string, string];
+    description: string;
+    options?: readonly LocalCapabilityOption[];
+}
+export interface LocalCapabilityOption {
+    flags: string;
+    required?: boolean;
+    description?: string;
+}
+export declare const localCapabilities: readonly LocalCapabilityDescriptor[];
+//# sourceMappingURL=local-capabilities.d.ts.map

package/dist/contracts/local-capabilities.js

@@ -0,0 +1,37 @@
+export const localCapabilities = [
+    descriptor('data.init', 'data', 'init'),
+    descriptor('data.sync', 'data', 'sync'),
+    descriptor('data.status', 'data', 'status'),
+    descriptor('data.validate', 'data', 'validate'),
+    descriptor('data.repair', 'data', 'repair'),
+    descriptor('data.migrate', 'data', 'migrate'),
+    descriptor('data.clean', 'data', 'clean'),
+    descriptor('data.remove', 'data', 'remove'),
+    descriptor('db.describe', 'db', 'describe'),
+    descriptor('db.query', 'db', 'query', [{ flags: '--sql <sql>', required: true }]),
+    descriptor('db.export', 'db', 'export', [
+        { flags: '--sql <sql>', required: true },
+        { flags: '--output <path>', required: true },
+        { flags: '--file-format <format>', required: false },
+    ]),
+    descriptor('market.panel', 'market', 'panel', [
+        { flags: '--start <date>', required: true },
+        { flags: '--end <date>', required: true },
+        { flags: '--output <path>', required: true },
+        { flags: '--file-format <format>', required: false },
+    ]),
+    descriptor('market.adjustment-factors', 'market', 'adjustment-factors', [
+        { flags: '--thscode <code>', required: true },
+        { flags: '--start <date>', required: false },
+        { flags: '--end <date>', required: false },
+    ]),
+];
+function descriptor(id, group, leaf, options) {
+    return {
+        id,
+        command: [group, leaf],
+        description: `Local capability ${id}`,
+        ...(options === undefined ? {} : { options }),
+    };
+}
+//# sourceMappingURL=local-capabilities.js.map

package/dist/contracts/registry.d.ts

@@ -0,0 +1,9 @@
+import type { Command } from 'commander';
+export interface CommandDescriptor {
+    id: string;
+    path: readonly string[];
+    describe: (language: 'zh-CN' | 'en') => string;
+    register: (program: Command) => void;
+}
+export declare function commandPath(descriptor: Pick<CommandDescriptor, 'path'>): string;
+//# sourceMappingURL=registry.d.ts.map

package/dist/contracts/registry.js

@@ -0,0 +1,4 @@
+export function commandPath(descriptor) {
+    return descriptor.path.join('.');
+}
+//# sourceMappingURL=registry.js.map

package/dist/contracts/remote-capabilities.d.ts

@@ -0,0 +1,24 @@
+import { type ZodType } from 'zod';
+export interface RemoteOptionDescriptor {
+    flags: string;
+    description: string;
+    type: 'string' | 'integer' | 'boolean';
+    required?: boolean;
+    choices?: readonly string[];
+    defaultValue?: string | number | boolean;
+    queryName?: string;
+}
+export interface RemoteCapabilityDescriptor {
+    id: string;
+    command: readonly [string, string];
+    description: string;
+    endpoint: string;
+    method: 'GET';
+    inputSchema: ZodType<Record<string, unknown>>;
+    outputSchema: ZodType<unknown>;
+    options: readonly RemoteOptionDescriptor[];
+    paging: 'none' | 'offset' | 'page';
+    window: 'none' | 'ten-years' | 'one-year' | 'today-only';
+}
+export declare const remoteCapabilities: readonly RemoteCapabilityDescriptor[];
+//# sourceMappingURL=remote-capabilities.d.ts.map