@actiondock/cli 2.0.12 → 2.2.1

package/dist/commands/serve.js

@@ -0,0 +1,135 @@
+import { resolve } from "node:path";
+import { findProjectRoot, formatHostForUrl, loadProjectConfig, startActionDockServer } from "@actiondock/core";
+import { ArgumentError, ExecutionError } from "../errors.js";
+import { writeStderr, writeStdout } from "../renderer.js";
+import { getEffectiveOptions, parseByteSize } from "../utils/index.js";
+/**
+ * 注册 serve HTTP 服务启动命令。
+ *
+ * @param program Commander 实例
+ * @param context 命令行上下文
+ */
+export function registerServeCommand(program, context) {
+    program
+        .command("serve")
+        .description("Start the ActionDock lightweight HTTP Runner server for remote execution")
+        .option("-p, --port <port>", "Port to listen on (default: 5177)", "5177")
+        .option("-H, --host <host>", "Host address to bind to (default: 127.0.0.1)", "127.0.0.1")
+        .option("-t, --token <token>", "Authentication token for securing the endpoint (or set ACTIONDOCK_TOKEN)")
+        .option("--allow-insecure-no-auth", "Allow non-loopback host binding without authentication token (INSECURE)")
+        .option("--cors-origin <origin>", "Allowed CORS origin (can be specified multiple times)", (val, prev = []) => [...prev, val], [])
+        .option("--max-body <size>", "Maximum allowed JSON request body size (e.g. 1mb, 500kb)", "1mb")
+        .option("--expose-debug-info", "Expose project root path in health and info responses")
+        .option("--no-mcp", "Disable unified MCP protocol endpoint at /mcp")
+        .option("--allow-query-token", "Allow passing authentication token via URL query parameter (?token=xxx)")
+        .option("--management", "Enable config and state management API endpoints (disabled by default for security)")
+        .option("-d, --dir <path>", "Project root directory (default: current working directory)")
+        .action(async (rawOptions, cmd) => {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const port = parseInt(options.port, 10) || 5177;
+        const host = options.host || "127.0.0.1";
+        const token = options.token || (typeof process !== "undefined" ? process.env?.ACTIONDOCK_TOKEN : undefined);
+        const allowInsecureNoAuth = Boolean(options.allowInsecureNoAuth);
+        const allowQueryToken = Boolean(options.allowQueryToken);
+        const enableManagement = Boolean(options.management);
+        const corsOrigins = options.corsOrigin && options.corsOrigin.length > 0 ? options.corsOrigin : undefined;
+        const exposeDebugInfo = Boolean(options.exposeDebugInfo);
+        let maxBodyBytes;
+        if (options.maxBody) {
+            try {
+                maxBodyBytes = parseByteSize(options.maxBody);
+            }
+            catch (err) {
+                throw new ArgumentError(`Invalid max-body format: ${err.message}`);
+            }
+        }
+        const projectRoot = options.dir
+            ? resolve(options.dir)
+            : findProjectRoot(process.cwd());
+        let projectName = "Global Registry Mode";
+        if (projectRoot) {
+            try {
+                const config = loadProjectConfig(projectRoot);
+                projectName = `${config.name} (${config.id})`;
+            }
+            catch {
+                // 降级处理
+            }
+        }
+        let mcpHandler;
+        const enableMcp = options.mcp !== false;
+        if (enableMcp) {
+            // MCP 处理器创建失败时直接终止启动，避免横幅宣称不存在的端点
+            try {
+                const [{ createActionDockMcpServer }, { createMcpHandler }] = await Promise.all([
+                    import("@actiondock/mcp"),
+                    import("@modelcontextprotocol/server"),
+                ]);
+                const handler = createMcpHandler(() => {
+                    return createActionDockMcpServer({
+                        projectRoot: projectRoot || undefined,
+                    });
+                }, {
+                    onerror: (err) => {
+                        writeStderr(`[MCP HTTP Error] ${err?.message || String(err)}`, context);
+                    },
+                });
+                mcpHandler = async (req) => {
+                    return handler.fetch(req);
+                };
+            }
+            catch (err) {
+                throw new ExecutionError(`Failed to initialize MCP endpoint: ${err?.message || String(err)}`, err);
+            }
+        }
+        try {
+            const server = await startActionDockServer({
+                port,
+                host,
+                token,
+                allowInsecureNoAuth,
+                allowQueryToken,
+                corsOrigins,
+                maxBodyBytes,
+                exposeDebugInfo,
+                enableMcp,
+                enableManagement,
+                mcpHandler,
+                projectRoot: projectRoot || undefined,
+            });
+            const displayHost = formatHostForUrl(host);
+            const actualEndpointHost = formatHostForUrl(host === "0.0.0.0" ? "127.0.0.1" : host);
+            writeStdout(`\n======================================================`, context);
+            writeStdout(`  ActionDock 2.0 HTTP Runner Server`, context);
+            writeStdout(`======================================================`, context);
+            writeStdout(`  * Listening on:    http://${displayHost}:${server.port}`, context);
+            writeStdout(`  * Project:         ${projectName}`, context);
+            if (projectRoot && exposeDebugInfo) {
+                writeStdout(`  * Root Path:       ${projectRoot}`, context);
+            }
+            const authDesc = token
+                ? (allowQueryToken ? "Bearer Token / Query Token Enabled" : "Bearer Token Enabled (Query Token Disabled)")
+                : "Disabled (Public/Local)";
+            writeStdout(`  * Authentication:  ${authDesc}`, context);
+            writeStdout(`  * Management APIs: ${enableManagement ? "Enabled" : "Disabled (Default)"}`, context);
+            writeStdout(`  * CORS Origins:    ${corsOrigins ? corsOrigins.join(", ") : "Disabled (Default)"}`, context);
+            writeStdout(`  * Max Body Size:   ${options.maxBody || "1mb"}`, context);
+            writeStdout(`  * Health Endpoint: http://${actualEndpointHost}:${server.port}/api/v1/health`, context);
+            if (enableMcp) {
+                writeStdout(`  * MCP Endpoint:    http://${actualEndpointHost}:${server.port}/mcp`, context);
+            }
+            writeStdout(`======================================================\n`, context);
+            writeStdout(`Server is ready to accept remote requests.`, context);
+            writeStdout(`Press Ctrl+C to terminate.\n`, context);
+            const stopSignalHandler = () => {
+                writeStdout("\nStopping ActionDock server...", context);
+                server.stop();
+            };
+            process.once("SIGINT", stopSignalHandler);
+            process.once("SIGTERM", stopSignalHandler);
+        }
+        catch (err) {
+            throw new ExecutionError(`Failed to start ActionDock server: ${err.message}`, err);
+        }
+    });
+}

package/dist/commands/state-list.d.ts

@@ -0,0 +1,24 @@
+import type { ActionDockTarget } from "@actiondock/core";
+import type { CliContext } from "../types.js";
+/**
+ * 状态键列表渲染参数视图。
+ */
+export interface StateListRenderArgs {
+    target: ActionDockTarget;
+    actionId: string;
+    prefix: string;
+    options: any;
+    effectiveIntent?: string;
+    shouldFallback: boolean;
+    context?: CliContext;
+}
+/**
+ * 渲染单个项目作用域的状态键列表（含 --detail JSON 明细分支）。
+ */
+export declare function renderProjectScopedStateList(args: StateListRenderArgs & {
+    targetRoot: string;
+}): Promise<void>;
+/**
+ * 渲染全部链接包聚合的状态键列表（跳过磁盘失效与清单损坏的链接项）。
+ */
+export declare function renderLinkedPackagesStateList(args: StateListRenderArgs): Promise<void>;

package/dist/commands/state-list.js

@@ -0,0 +1,82 @@
+import { filterWithFallbackInfo, listLinkedPackages, loadProjectConfig, } from "@actiondock/core";
+import { existsSync } from "node:fs";
+import { renderResult, renderStateList } from "../renderer.js";
+/**
+ * 渲染单个项目作用域的状态键列表（含 --detail JSON 明细分支）。
+ */
+export async function renderProjectScopedStateList(args) {
+    const { target, targetRoot, actionId, prefix, options, effectiveIntent, shouldFallback, context } = args;
+    const projConfig = loadProjectConfig(targetRoot);
+    const allKeys = await target.listStateKeys(projConfig.id, actionId, {
+        namespace: options.namespace !== undefined ? options.namespace : null,
+        prefix,
+    });
+    if (options.detail && options.json) {
+        const entries = [];
+        for (const k of allKeys) {
+            const entry = await target.getState(projConfig.id, actionId, k, {
+                namespace: options.namespace,
+                detail: true,
+            });
+            if (entry) {
+                entries.push(entry);
+            }
+        }
+        const filterRes = filterWithFallbackInfo(entries, effectiveIntent, [(e) => e.fullKey, (e) => e.key, (e) => e.namespace], shouldFallback);
+        renderResult(filterRes.items, {
+            json: true,
+            envelope: options.envelope,
+            context,
+        });
+        return;
+    }
+    const filterRes = filterWithFallbackInfo(allKeys, effectiveIntent, [(k) => k], shouldFallback);
+    renderResult(filterRes.items, {
+        json: options.json,
+        envelope: options.envelope,
+        humanFormatter: () => renderStateList(filterRes.items, `${projConfig.name} (${projConfig.id})`, filterRes.isFallback, effectiveIntent),
+        context,
+    });
+}
+/**
+ * 渲染全部链接包聚合的状态键列表（跳过磁盘失效与清单损坏的链接项）。
+ */
+export async function renderLinkedPackagesStateList(args) {
+    const { target, actionId, prefix, options, effectiveIntent, shouldFallback, context } = args;
+    // 扫描所有链接的包状态
+    const linked = listLinkedPackages();
+    if (linked.length === 0) {
+        renderResult([], {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => "No ActionDock project in current directory, and no packages linked.",
+            context,
+        });
+        return;
+    }
+    const aggregatedKeys = [];
+    for (const pkg of linked) {
+        if (!existsSync(pkg.path))
+            continue;
+        try {
+            const config = loadProjectConfig(pkg.path);
+            const keys = await target.listStateKeys(config.id, actionId, {
+                namespace: options.namespace !== undefined ? options.namespace : null,
+                prefix,
+            });
+            for (const k of keys) {
+                aggregatedKeys.push(`${config.id}/${k}`);
+            }
+        }
+        catch {
+            // 单个链接包清单损坏或状态读取失败时跳过，继续聚合其余包
+        }
+    }
+    const filterRes = filterWithFallbackInfo(aggregatedKeys, effectiveIntent, [(k) => k], shouldFallback);
+    renderResult(filterRes.items, {
+        json: options.json,
+        envelope: options.envelope,
+        humanFormatter: () => renderStateList(filterRes.items, "Linked Packages State Store", filterRes.isFallback, effectiveIntent),
+        context,
+    });
+}

package/dist/commands/state.d.ts

@@ -1,2 +1,9 @@
-import type { Command } from "commander";
-export declare function registerStateCommands(program: Command): void;
+import { Command } from "commander";
+import type { CliContext } from "../types.js";
+/**
+ * 注册 state 状态管理命令（get、set、delete、clear、keys、list）。
+ *
+ * @param program Commander 实例
+ * @param context 命令行上下文
+ */
+export declare function registerStateCommands(program: Command, context?: CliContext): void;

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.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;