@actiondock/cli 2.0.11 → 2.2.0

package/dist/commands/state.js

@@ -0,0 +1,310 @@
+import { decodeStateKey, findProjectRoot, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
+import { ArgumentError, ExecutionError } from "../errors.js";
+import { renderResult, renderStateList, writeStdout } from "../renderer.js";
+import { getEffectiveOptions, getTargetRoot, resolveIntent, withTarget } from "../utils/index.js";
+import { renderLinkedPackagesStateList, renderProjectScopedStateList, } from "./state-list.js";
+/**
+ * 注册 state 状态管理命令（get、set、delete、clear、keys、list）。
+ *
+ * @param program Commander 实例
+ * @param context 命令行上下文
+ */
+export function registerStateCommands(program, context) {
+    const stateCmd = program
+        .command("state")
+        .description("Inspect and manage Shared State store");
+    // state list / keys 共享实现（远端、本地项目、链接包聚合三分支）
+    const handleListKeys = async (prefix = "", rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const effectiveIntent = resolveIntent(options.intent, prefix ? [prefix] : []);
+        const shouldFallback = options.fallback !== false;
+        await withTarget(options, context, async (target, resolved) => {
+            const actionId = options.action || "";
+            // 远端服务模式：直接列举远端包作用域键
+            if (resolved.type === "remote") {
+                const keys = await target.listStateKeys(options.package || "", actionId, {
+                    namespace: options.namespace,
+                    prefix,
+                });
+                renderResult(keys, {
+                    json: options.json,
+                    envelope: options.envelope,
+                    humanFormatter: () => renderStateList(keys, `Remote Server ${resolved.serverUrl}${resolved.profileName ? ` (Profile: ${resolved.profileName})` : ""}`, false, effectiveIntent),
+                    context,
+                });
+                return;
+            }
+            // 本地工程与链接包模式：按目标根目录决策输出范围
+            let targetRoot = null;
+            if (options.package) {
+                targetRoot = resolvePackageRoot(options.package);
+                if (!targetRoot) {
+                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                }
+            }
+            else {
+                targetRoot = findProjectRoot();
+            }
+            if (targetRoot) {
+                await renderProjectScopedStateList({
+                    target,
+                    targetRoot,
+                    actionId,
+                    prefix,
+                    options,
+                    effectiveIntent,
+                    shouldFallback,
+                    context,
+                });
+                return;
+            }
+            await renderLinkedPackagesStateList({
+                target,
+                actionId,
+                prefix,
+                options,
+                effectiveIntent,
+                shouldFallback,
+                context,
+            });
+        });
+    };
+    // state list
+    stateCmd
+        .command("list [prefix]")
+        .description("List state keys in current project or linked packages")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-a, --action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Filter keys under specific namespace (omit to list all namespaces)")
+        .option("-p, --profile <name>", "Query state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
+        .option("--detail", "Include metadata (ttl, expiresAt, size, updatedAt) in JSON output")
+        .option("--no-fallback", "Disable fallback to full list when no items match intent")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(handleListKeys);
+    // state keys 别名
+    stateCmd
+        .command("keys [prefix]")
+        .description("Alias for 'ad state list [prefix]'")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-a, --action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Filter keys under specific namespace")
+        .option("-p, --profile <name>", "Query state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("-i, --intent <pattern>", "Regex or fuzzy intent filter")
+        .option("--detail", "Include metadata in JSON output")
+        .option("--no-fallback", "Disable fallback")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(handleListKeys);
+    // state get <key>
+    stateCmd
+        .command("get <key>")
+        .description("Get state value by key (supports composite 'ns:key' and detail mode)")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-a, --action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Explicit namespace scope for key")
+        .option("-p, --profile <name>", "Query state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .action(async (rawKey, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!rawKey) {
+            throw new ArgumentError("State key is required");
+        }
+        await withTarget(options, context, async (target, resolved) => {
+            const actionId = options.action || "";
+            if (resolved.type === "remote") {
+                const decoded = decodeStateKey(rawKey);
+                const effectiveNamespace = options.namespace || (decoded.namespace || undefined);
+                const actualKey = options.namespace ? rawKey : decoded.key;
+                const entry = await target.getState(options.package || "", actionId, actualKey, {
+                    namespace: effectiveNamespace,
+                    detail: true,
+                });
+                if (entry === undefined || entry.value === undefined) {
+                    throw new ExecutionError(`State key '${rawKey}' not found on remote server`);
+                }
+                const val = entry.value;
+                renderResult({ key: rawKey, value: val, namespace: entry.namespace || effectiveNamespace }, {
+                    json: options.json,
+                    envelope: options.envelope,
+                    humanFormatter: () => (typeof val === "object" ? JSON.stringify(val, null, 2) : String(val)),
+                    context,
+                });
+                return;
+            }
+            // 本地项目模式
+            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
+            const projConfig = loadProjectConfig(root);
+            const entry = await target.getState(projConfig.id, actionId, effectiveKey, {
+                namespace: options.namespace,
+                detail: true,
+            });
+            if (entry === undefined || entry.value === undefined) {
+                throw new ExecutionError(`State key '${rawKey}' not found in package '${projConfig.id}'`);
+            }
+            const val = entry.value;
+            const matchedNamespace = entry.namespace;
+            renderResult({ key: rawKey, value: val, namespace: matchedNamespace }, {
+                json: options.json,
+                envelope: options.envelope,
+                humanFormatter: () => (typeof val === "object" ? JSON.stringify(val, null, 2) : String(val)),
+                context,
+            });
+        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+    });
+    // state set <key> <value>
+    stateCmd
+        .command("set <key> <value>")
+        .description("Set state key-value (supports JSON value, composite 'ns:key', and --ttl)")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-a, --action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Explicit namespace scope for key")
+        .option("--ttl <seconds>", "Time-To-Live expiration in seconds")
+        .option("-p, --profile <name>", "Set state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .action(async (rawKey, rawVal, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!rawKey || rawVal === undefined) {
+            throw new ArgumentError("Both key and value are required for state set");
+        }
+        let parsedVal = rawVal;
+        try {
+            parsedVal = JSON.parse(rawVal);
+        }
+        catch {
+            parsedVal = rawVal;
+        }
+        const ttlSec = options.ttl ? parseInt(options.ttl, 10) : undefined;
+        if (options.ttl && (isNaN(ttlSec) || ttlSec <= 0)) {
+            throw new ArgumentError(`Invalid --ttl value: '${options.ttl}'. Must be a positive integer.`);
+        }
+        await withTarget(options, context, async (target, resolved) => {
+            const actionId = options.action || "";
+            if (resolved.type === "remote") {
+                const decoded = decodeStateKey(rawKey);
+                const effectiveNamespace = options.namespace || (decoded.namespace || undefined);
+                const actualKey = options.namespace ? rawKey : decoded.key;
+                await target.setState(options.package || "", actionId, actualKey, parsedVal, {
+                    namespace: effectiveNamespace,
+                    ttl: ttlSec,
+                });
+                writeStdout(`[OK] State '${rawKey}' updated on remote server`, context);
+                return;
+            }
+            // 本地项目模式
+            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
+            const projConfig = loadProjectConfig(root);
+            let actualNamespace = options.namespace;
+            let finalKey = effectiveKey;
+            if (options.namespace === undefined && effectiveKey.includes(":")) {
+                const decoded = decodeStateKey(effectiveKey);
+                actualNamespace = decoded.namespace;
+                finalKey = decoded.key;
+            }
+            await target.setState(projConfig.id, actionId, finalKey, parsedVal, {
+                namespace: actualNamespace,
+                ttl: ttlSec,
+            });
+            const displayKey = actualNamespace ? `${actualNamespace}:${finalKey}` : finalKey;
+            writeStdout(`[OK] State '${displayKey}' updated in package '${projConfig.id}'`, context);
+        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+    });
+    // state delete <key>
+    stateCmd
+        .command("delete <key>")
+        .alias("rm")
+        .description("Delete state key entry")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("-a, --action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Explicit namespace scope for key")
+        .option("-p, --profile <name>", "Delete state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .action(async (rawKey, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!rawKey) {
+            throw new ArgumentError("State key is required");
+        }
+        await withTarget(options, context, async (target, resolved) => {
+            const actionId = options.action || "";
+            if (resolved.type === "remote") {
+                const decoded = decodeStateKey(rawKey);
+                const effectiveNamespace = options.namespace || (decoded.namespace || undefined);
+                const actualKey = options.namespace ? rawKey : decoded.key;
+                const deleted = await target.deleteState(options.package || "", actionId, actualKey, {
+                    namespace: effectiveNamespace,
+                });
+                if (!deleted) {
+                    throw new ExecutionError(`State key '${rawKey}' not found on remote server`);
+                }
+                writeStdout(`[OK] State '${rawKey}' deleted on remote server`, context);
+                return;
+            }
+            // 本地项目模式
+            const { root, key: effectiveKey } = getTargetRoot(options.package, rawKey);
+            const projConfig = loadProjectConfig(root);
+            const deleted = await target.deleteState(projConfig.id, actionId, effectiveKey, {
+                namespace: options.namespace,
+            });
+            if (!deleted) {
+                throw new ExecutionError(`State key '${rawKey}' not found in package '${projConfig.id}'`);
+            }
+            writeStdout(`[OK] State '${rawKey}' deleted from package '${projConfig.id}'`, context);
+        }, { localRoot: () => getTargetRoot(options.package, rawKey).root });
+    });
+    // state clear
+    stateCmd
+        .command("clear")
+        .alias("clean")
+        .description("Clear state entries (supports namespace cleanup or global wipe via --all)")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("--action <id>", "Action identifier scope")
+        .option("-n, --namespace <ns>", "Target namespace to clear (required unless --all is specified)")
+        .option("-a, --all", "Dangerously clear all state namespaces for the package")
+        .option("-p, --profile <name>", "Clear state on a remote target")
+        .option("-s, --server <url>", "Remote server URL")
+        .option("-t, --token <token>", "Auth token for remote server")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .action(async (rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!options.all && options.namespace === undefined) {
+            throw new ArgumentError("Must specify either -n/--namespace <name> to clear specific namespace, or --all to clear entire package state store.");
+        }
+        await withTarget(options, context, async (target, resolved) => {
+            const actionId = options.action || "";
+            if (resolved.type === "remote") {
+                const count = await target.clearState(options.package || "", actionId, {
+                    namespace: options.namespace,
+                    all: Boolean(options.all),
+                });
+                writeStdout(`[OK] Cleared ${count} state entry(s) on remote server`, context);
+                return;
+            }
+            // 本地项目模式
+            const { root } = getTargetRoot(options.package);
+            const projConfig = loadProjectConfig(root);
+            const count = await target.clearState(projConfig.id, actionId, {
+                namespace: options.namespace,
+                all: Boolean(options.all),
+            });
+            const scopeDesc = options.all
+                ? "all namespaces"
+                : `namespace '${options.namespace}'`;
+            writeStdout(`[OK] Cleared ${count} state entry(s) in ${scopeDesc} for package '${projConfig.id}'`, context);
+        }, { localRoot: () => getTargetRoot(options.package).root });
+    });
+}

package/dist/commands/test.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerTestCommand(program: Command): void;

package/dist/commands/test.js

@@ -0,0 +1,44 @@
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findProjectRoot } from "@actiondock/core";
+import { spawnAsync } from "../utils/index.js";
+export function registerTestCommand(program) {
+    program
+        .command("test [pattern]")
+        .description("Run project tests using configured test runner (node:test or bun test)")
+        .action(async (pattern) => {
+        const root = findProjectRoot();
+        const cwd = root || process.cwd();
+        const pkgJsonPath = join(cwd, "package.json");
+        let testCmd = "npm";
+        let testArgs = ["test"];
+        if (existsSync(pkgJsonPath)) {
+            try {
+                const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf-8"));
+                if (pkg.scripts?.test?.includes("bun test") && typeof globalThis.Bun !== "undefined") {
+                    testCmd = "bun";
+                    testArgs = ["test"];
+                }
+            }
+            catch {
+                // package.json 解析失败时回退 npm test
+            }
+        }
+        if (pattern) {
+            if (testCmd === "npm") {
+                testArgs.push("--", pattern);
+            }
+            else {
+                testArgs.push(pattern);
+            }
+        }
+        // stdio inherit 保持实时输出；进程异常（如命令不存在）时回退退出码 1
+        const proc = await spawnAsync(testCmd, testArgs, {
+            cwd,
+            stdio: "inherit",
+        }).catch(() => ({ status: 1, signal: null, stdout: "", stderr: "" }));
+        if (proc.status !== 0) {
+            process.exitCode = proc.status ?? 1;
+        }
+    });
+}

package/dist/commands/validate.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+import type { CliContext } from "../types.js";
+/**
+ * 注册顶层统一 validate 命令：校验 Action 的 Schema 与方法定义完整性。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export declare function registerValidateCommand(program: Command, context?: CliContext): void;

package/dist/commands/validate.js

@@ -0,0 +1,106 @@
+import { checkGeneratedTypes, findProjectRoot, GENERATED_TYPES_OUTDATED_CODE, loadActions, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
+import { SelectionPlanner } from "@actiondock/builder";
+import { ArgumentError, ExecutionError } from "../errors.js";
+import { renderActionValidation, renderResult } from "../renderer.js";
+import { getEffectiveOptions } from "../utils/index.js";
+/**
+ * 注册顶层统一 validate 命令：校验 Action 的 Schema 与方法定义完整性。
+ *
+ * @param program Commander 根程序对象
+ * @param context 命令行上下文
+ */
+export function registerValidateCommand(program, context) {
+    program
+        .command("validate [id]")
+        .description("Validate action schemas and definitions")
+        .option("-P, --package <id>", "Target package ID or path")
+        .option("--json", "Output as JSON")
+        .option("--envelope", "Wrap JSON output in standard envelope")
+        .option("--data-dir <path>", "Custom database storage directory")
+        .action(async (id, rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        let root = null;
+        if (options.package) {
+            root = resolvePackageRoot(options.package);
+            if (!root) {
+                throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            }
+        }
+        else {
+            root = findProjectRoot();
+        }
+        if (!root) {
+            throw new ArgumentError("Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id> or cd into a project directory.");
+        }
+        const config = loadProjectConfig(root);
+        const actions = await loadActions(root, config.actionsDir);
+        let toValidate = [];
+        if (id) {
+            const act = actions.get(id);
+            if (!act) {
+                throw new ArgumentError(`Action '${id}' not found in project '${config.id}'`);
+            }
+            toValidate = [{ id, act, spec: config.actions?.[id] }];
+        }
+        else {
+            toValidate = Array.from(actions.entries()).map(([actId, act]) => ({
+                id: actId,
+                act,
+                spec: config.actions?.[actId],
+            }));
+        }
+        const results = [];
+        for (const item of toValidate) {
+            const errors = [];
+            if (!item.id)
+                errors.push("Missing id property");
+            if (!item.act?.run || typeof item.act.run !== "function")
+                errors.push("Missing run method");
+            const inSchema = item.spec?.inputSchema ?? item.act.inputSchema;
+            if (inSchema && typeof inSchema !== "object") {
+                errors.push("Invalid inputSchema object");
+            }
+            const outSchema = item.spec?.outputSchema ?? item.act.outputSchema;
+            if (outSchema && typeof outSchema !== "object") {
+                errors.push("Invalid outputSchema object");
+            }
+            results.push({
+                id: item.id,
+                valid: errors.length === 0,
+                errors,
+            });
+        }
+        const allValid = results.every((r) => r.valid);
+        const validationPayload = { valid: allValid, results };
+        renderResult(validationPayload, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => renderActionValidation(results),
+            context,
+        });
+        if (!allValid) {
+            process.exitCode = 1;
+            return;
+        }
+        // 校验 Action 本地相对依赖完整性
+        try {
+            SelectionPlanner.plan({ projectRoot: root, actions: id ? [id] : undefined });
+        }
+        catch (err) {
+            if (err?.code === "UNMET_LOCAL_DEPENDENCY" ||
+                err?.code === "EXTERNAL_LOCAL_DEPENDENCY" ||
+                err?.code === "FILE_NOT_FOUND") {
+                throw new ExecutionError(`Action dependency integrity validation failed:\n${err.message}`, undefined, err.code);
+            }
+            throw err;
+        }
+        // 只读校验已生成的类型文件摘要是否过期
+        const typeCheck = checkGeneratedTypes(root);
+        if (typeCheck.exists && typeCheck.outdated) {
+            throw new ExecutionError(`Generated types in ${typeCheck.filePath} are outdated. Expected manifest digest '${typeCheck.expectedDigest}', but got '${typeCheck.actualDigest || "none"}'. Run 'ad generate types' to update.`, {
+                expectedDigest: typeCheck.expectedDigest,
+                actualDigest: typeCheck.actualDigest,
+            }, GENERATED_TYPES_OUTDATED_CODE);
+        }
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,43 @@
+import { type ExitCodeValue } from "./types.js";
+/**
+ * 命令行标准错误基类。
+ */
+export declare class CliError extends Error {
+    readonly exitCode: ExitCodeValue;
+    readonly code: string;
+    readonly details?: unknown;
+    constructor(message: string, exitCode?: ExitCodeValue, code?: string, details?: unknown);
+}
+/**
+ * 命令行参数与选项校验错误（退出码为 2）。
+ */
+export declare class ArgumentError extends CliError {
+    constructor(message: string, details?: unknown);
+}
+/**
+ * 业务逻辑或框架执行失败错误（退出码为 1）。
+ */
+export declare class ExecutionError extends CliError {
+    constructor(message: string, details?: unknown, code?: string);
+}
+/**
+ * 用户中断信号错误（退出码为 130）。
+ */
+export declare class SigintError extends CliError {
+    constructor(message?: string);
+}
+/**
+ * 标准化错误信息解析结果。
+ */
+export interface FormattedError {
+    code: string;
+    message: string;
+    exitCode: ExitCodeValue;
+    details?: unknown;
+}
+/**
+ * 解析并格式化任意异常为结构化错误对象。
+ *
+ * @param err 待解析的异常对象
+ */
+export declare function formatError(err: unknown): FormattedError;

package/dist/errors.js

@@ -0,0 +1,103 @@
+import { ExitCode } from "./types.js";
+/**
+ * CLI 信封错误码常量（仅 CLI 输出协议使用，属包内部码，就地常量化管理）。
+ */
+const CLI_CODE_SUCCESS = "SUCCESS";
+const CLI_CODE_INVALID_ARGUMENT = "INVALID_ARGUMENT";
+const CLI_CODE_ERROR = "ERROR";
+const CLI_CODE_UNKNOWN_ERROR = "UNKNOWN_ERROR";
+/**
+ * 命令行标准错误基类。
+ */
+export class CliError extends Error {
+    exitCode;
+    code;
+    details;
+    constructor(message, exitCode = ExitCode.FAILURE, code = "CLI_ERROR", details) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+        this.code = code;
+        this.details = details;
+    }
+}
+/**
+ * 命令行参数与选项校验错误（退出码为 2）。
+ */
+export class ArgumentError extends CliError {
+    constructor(message, details) {
+        super(message, ExitCode.INVALID_ARGUMENT, "INVALID_ARGUMENT", details);
+        this.name = "ArgumentError";
+    }
+}
+/**
+ * 业务逻辑或框架执行失败错误（退出码为 1）。
+ */
+export class ExecutionError extends CliError {
+    constructor(message, details, code = "EXECUTION_FAILURE") {
+        super(message, ExitCode.FAILURE, code, details);
+        this.name = "ExecutionError";
+    }
+}
+/**
+ * 用户中断信号错误（退出码为 130）。
+ */
+export class SigintError extends CliError {
+    constructor(message = "Interrupted by SIGINT") {
+        super(message, ExitCode.SIGINT, "SIGINT_INTERRUPTED");
+        this.name = "SigintError";
+    }
+}
+/**
+ * 解析并格式化任意异常为结构化错误对象。
+ *
+ * @param err 待解析的异常对象
+ */
+export function formatError(err) {
+    if (err instanceof CliError) {
+        return {
+            code: err.code,
+            message: err.message,
+            exitCode: err.exitCode,
+            details: err.details,
+        };
+    }
+    // Commander.js 原生错误处理
+    if (typeof err === "object" && err !== null && "code" in err && typeof err.code === "string") {
+        const commanderErr = err;
+        const code = commanderErr.code;
+        // 参数类异常
+        if (code.startsWith("commander.unknownOption") ||
+            code.startsWith("commander.missingArgument") ||
+            code.startsWith("commander.missingMandatoryOptionValue") ||
+            code.startsWith("commander.optionMissingArgument") ||
+            code.startsWith("commander.invalidArgument") ||
+            code.startsWith("commander.excessArguments")) {
+            return {
+                code: CLI_CODE_INVALID_ARGUMENT,
+                message: commanderErr.message,
+                exitCode: ExitCode.INVALID_ARGUMENT,
+            };
+        }
+        // 正常退出（如 --help 或 --version）
+        if (code === "commander.helpDisplayed" || code === "commander.version") {
+            return {
+                code: CLI_CODE_SUCCESS,
+                message: commanderErr.message,
+                exitCode: ExitCode.SUCCESS,
+            };
+        }
+    }
+    if (err instanceof Error) {
+        return {
+            code: CLI_CODE_ERROR,
+            message: err.message,
+            exitCode: ExitCode.FAILURE,
+        };
+    }
+    return {
+        code: CLI_CODE_UNKNOWN_ERROR,
+        message: String(err),
+        exitCode: ExitCode.FAILURE,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,15 @@
+export * from "./types.js";
+export * from "./errors.js";
+export * from "./renderer.js";
+export * from "./prompt.js";
+export * from "./standalone/index.js";
+export * from "./utils/index.js";
+export * from "./services/index.js";
+export * from "./commands/index.js";
+/**
+ * ActionDock CLI 主执行入口函数。
+ *
+ * @param argv 命令行参数数组（默认使用 process.argv）
+ * @returns 进程退出码
+ */
+export declare function main(argv?: string[]): Promise<number>;