@actiondock/cli 2.5.1 → 2.7.0

package/dist/commands/run.d.ts

@@ -1,9 +1,18 @@
+import { type InvocationControl } from "@actiondock/core";
+import type { ExecutionResult } from "@actiondock/sdk";
 import { Command } from "commander";
 import type { CliContext } from "../types.js";
+/**
+ * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
+ *
+ * 设计契约：
+ * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
+ */
+export declare function renderRawExecutionResult(targetRef: string, result: ExecutionResult, context?: CliContext): void;
 /**
  * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
  */
-export declare function executeAction(id: string, options: any, context?: CliContext): Promise<void>;
+export declare function executeAction(id: string, options: any, context?: CliContext, flatArgs?: string[], control?: InvocationControl): Promise<void>;
 /**
  * 挂载 run 子命令至指定 Commander 节点。
  *

package/dist/commands/run.js

@@ -1,32 +1,119 @@
-import { readFileSync } from "node:fs";
-import { parseDuration, resolveTarget } from "@actiondock/core";
-import { ArgumentError, ExecutionError, SigintError } from "../errors.js";
-import { writeStdout } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
+import { parseDuration, resolveTarget, validateActionInputValue, mapInputValidationFailure, } from "@actiondock/core";
+import { ArgumentError, ExecutionError, SigintError, packageNotFoundError } from "../errors.js";
+import { writeStderr, writeStdout } from "../renderer.js";
+import { applyTargetOptions, getEffectiveOptions, resolveActionInput, resolveLocalPackageRoot, withTarget, } from "../utils/index.js";
 /**
- * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
+ * 以原始纯文本形式渲染 Action 执行终态结果（默认纯文本模式）。
+ *
+ * 设计契约：
+ * 1. stdout: 仅承载业务有效载荷（payload）。保持原生排版、未转义多行与真实换行，供用户阅读或下游管道直接消费。
  */
-export async function executeAction(id, options, context) {
-    if (!id) {
-        throw new ArgumentError("Action ID is required for run");
-    }
-    let input = {};
-    if (options.input) {
-        try {
-            input = JSON.parse(options.input);
+export function renderRawExecutionResult(targetRef, result, context) {
+    if (result.ok) {
+        const data = result.data;
+        let rawText;
+        let metaInfo;
+        if (typeof data === "string") {
+            rawText = data;
         }
-        catch (err) {
-            throw new ArgumentError(`Error parsing --input JSON: ${err.message}`);
+        else if (data !== null && typeof data === "object") {
+            if ("content" in data && data.content !== undefined) {
+                rawText =
+                    typeof data.content === "object" && data.content !== null
+                        ? JSON.stringify(data.content, null, 2)
+                        : String(data.content);
+                const { content, ...rest } = data;
+                if (Object.keys(rest).length > 0) {
+                    metaInfo = rest;
+                }
+            }
+            else if ("text" in data && typeof data.text === "string") {
+                rawText = data.text;
+                const { text, ...rest } = data;
+                if (Object.keys(rest).length > 0) {
+                    metaInfo = rest;
+                }
+            }
+            else if ("message" in data && typeof data.message === "string") {
+                rawText = data.message;
+                const { message, ...rest } = data;
+                if (Object.keys(rest).length > 0) {
+                    metaInfo = rest;
+                }
+            }
+            else {
+                rawText = JSON.stringify(data, null, 2);
+            }
         }
+        else if (data !== undefined) {
+            rawText = String(data);
+        }
+        else {
+            rawText = "";
+        }
+        if (metaInfo) {
+            const parts = [];
+            const title = metaInfo.path ? String(metaInfo.path) : targetRef;
+            parts.push(title);
+            if (metaInfo.startLine !== undefined && metaInfo.endLine !== undefined) {
+                parts.push(`lines ${metaInfo.startLine}-${metaInfo.endLine}`);
+            }
+            else if (metaInfo.line !== undefined) {
+                parts.push(`line ${metaInfo.line}`);
+            }
+            if (metaInfo.hasMore !== undefined) {
+                parts.push(`hasMore: ${metaInfo.hasMore}`);
+            }
+            if (metaInfo.truncated) {
+                parts.push("truncated: true");
+            }
+            const handled = new Set(["path", "startLine", "endLine", "line", "hasMore", "truncated"]);
+            for (const [k, v] of Object.entries(metaInfo)) {
+                if (!handled.has(k) && v !== undefined) {
+                    parts.push(`${k}: ${typeof v === "object" ? JSON.stringify(v) : v}`);
+                }
+            }
+            if (parts.length > 0) {
+                writeStderr(`[${parts.join(" | ")}]`, context);
+            }
+        }
+        writeStdout(rawText, context);
     }
-    else if (options.inputFile) {
-        try {
-            input = JSON.parse(readFileSync(options.inputFile, "utf-8"));
+    else {
+        writeStderr(`Error [${result.error.code}]: ${result.error.message}`, context);
+        if (result.error.details) {
+            writeStderr(typeof result.error.details === "string"
+                ? result.error.details
+                : JSON.stringify(result.error.details, null, 2), context);
         }
-        catch (err) {
-            throw new ArgumentError(`Error reading --input-file: ${err.message}`);
+        if (context) {
+            context.exitCode = 1;
+        }
+        if (!context?.control) {
+            process.exitCode = 1;
         }
     }
+}
+/**
+ * 统一执行 Action 核心逻辑（使用 ActionDockTarget 门面）。
+ */
+export async function executeAction(id, options, context, flatArgs, control) {
+    if (!id) {
+        throw new ArgumentError("Action ID is required for run");
+    }
+    const effectiveControl = control ?? context?.control;
+    const effectiveSignal = effectiveControl?.signal;
+    const effectiveFlatArgs = flatArgs ?? options.flatArgs;
+    const input = await resolveActionInput({
+        input: options.input,
+        inputFile: options.inputFile,
+        flatArgs: effectiveFlatArgs && effectiveFlatArgs.length > 0 ? effectiveFlatArgs : undefined,
+        stdin: context?.stdin,
+    });
+    const check = validateActionInputValue(input);
+    if (!check.valid) {
+        throw mapInputValidationFailure("cli-pre-target", check);
+    }
     let timeoutMs;
     if (options.timeout) {
         try {
@@ -45,13 +132,6 @@ export async function executeAction(id, options, context) {
                 configOverrides[k] = v.join("=");
         }
     }
-    const controller = new AbortController();
-    let receivedSigint = false;
-    const sigintHandler = () => {
-        receivedSigint = true;
-        controller.abort(new Error("Interrupted by SIGINT"));
-    };
-    process.once("SIGINT", sigintHandler);
     try {
         // 异步执行仅支持远端目标，本地模式直接拒绝
         const resolvedTopology = resolveTarget({
@@ -66,7 +146,7 @@ export async function executeAction(id, options, context) {
         // 目标拓扑解析（仅 local 分支需要包寻址）
         const targetPackageRoot = resolveLocalPackageRoot(options.package);
         if (options.package && !targetPackageRoot) {
-            throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+            throw packageNotFoundError(options.package);
         }
         let targetRef = id;
         if (options.package && !id.includes("/") && !id.includes(":")) {
@@ -74,48 +154,68 @@ export async function executeAction(id, options, context) {
         }
         // 通过 Target 统一执行
         await withTarget(options, context, async (target) => {
+            const isMachine = Boolean(options.json);
             if (options.async) {
                 const ticket = await target.startAction(targetRef, input, {
-                    signal: controller.signal,
+                    signal: effectiveSignal,
                     timeoutMs,
                     config: configOverrides,
                     requestId: options.requestId,
                 });
-                const asyncOutput = {
-                    ok: ticket.status !== "failed",
-                    runId: ticket.runId,
-                    status: ticket.status,
-                };
-                writeStdout(JSON.stringify(asyncOutput, null, 2), context);
+                if (isMachine) {
+                    const asyncOutput = {
+                        ok: ticket.status !== "failed",
+                        runId: ticket.runId,
+                        status: ticket.status,
+                    };
+                    writeStdout(JSON.stringify(asyncOutput, null, 2), context);
+                }
+                else {
+                    writeStderr(`[${ticket.status}] runId: ${ticket.runId}`, context);
+                    writeStdout(ticket.runId, context);
+                }
                 if (ticket.status === "failed") {
-                    process.exitCode = 1;
+                    if (context) {
+                        context.exitCode = 1;
+                    }
                     return;
                 }
             }
             else {
                 const result = await target.runAction(targetRef, input, {
-                    signal: controller.signal,
+                    signal: effectiveSignal,
                     timeoutMs,
                     config: configOverrides,
                     requestId: options.requestId,
                 });
-                writeStdout(JSON.stringify(result, null, 2), context);
+                if (effectiveControl?.cancellationSource === "sigint" &&
+                    (effectiveSignal?.aborted || (!result.ok && result.error?.code === "ACTION_CANCELLED"))) {
+                    throw new SigintError();
+                }
+                if (isMachine) {
+                    writeStdout(JSON.stringify(result, null, 2), context);
+                }
+                else {
+                    renderRawExecutionResult(targetRef, result, context);
+                }
                 if (!result.ok) {
-                    process.exitCode = 1;
+                    if (context) {
+                        context.exitCode = 1;
+                    }
                     return;
                 }
             }
-        }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true });
+        }, { localRoot: targetPackageRoot || undefined, scanLinkedPackages: true, ownDataDir: true });
     }
     catch (err) {
-        if (receivedSigint || err?.name === "AbortError" || err?.message?.includes("SIGINT")) {
+        const isSigint = effectiveControl?.cancellationSource === "sigint" ||
+            err?.message?.includes("Interrupted by SIGINT");
+        if (isSigint &&
+            (err?.name === "AbortError" || effectiveSignal?.aborted || err?.message?.includes("SIGINT") || err instanceof SigintError)) {
             throw new SigintError();
         }
         throw err;
     }
-    finally {
-        process.removeListener("SIGINT", sigintHandler);
-    }
 }
 /**
  * 挂载 run 子命令至指定 Commander 节点。
@@ -125,11 +225,11 @@ export async function executeAction(id, options, context) {
  */
 export function attachRunCommand(parent, context) {
     const cmd = parent
-        .command("run <id>")
+        .command("run <id> [params...]")
         .description("Execute an action (from current project, linked packages, or remote profile)")
         .option("-P, --package <id>", "Target package ID or path")
-        .option("-i, --input <json>", "Input as JSON string")
-        .option("-f, --input-file <path>", "Input from JSON file")
+        .option("-i, --input <json>", "Action input as inline JSON")
+        .option("-f, --input-file <path>", "Action input from JSON file, or '-' for stdin")
         .option("-c, --config <key=value...>", "Temporary config override (repeatable)");
     return applyTargetOptions(cmd)
         .option("--timeout <duration>", "Execution timeout (e.g. 30s, 5m, 500ms)")
@@ -137,10 +237,19 @@ export function attachRunCommand(parent, context) {
         .option("--async", "Execute asynchronously in background (requires remote server or profile)")
         .option("--data-dir <path>", "Custom database directory")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
-        .action(async (id, rawOptions, cmd) => {
-        const options = getEffectiveOptions(rawOptions, cmd);
-        await executeAction(id, options, context);
+        .action(async (id, params, rawOptions, cmd) => {
+        let flatArgs;
+        let effectiveRawOptions = rawOptions;
+        let effectiveCmd = cmd;
+        if (Array.isArray(params)) {
+            flatArgs = params.length > 0 ? params : undefined;
+        }
+        else {
+            effectiveCmd = rawOptions;
+            effectiveRawOptions = params;
+        }
+        const options = getEffectiveOptions(effectiveRawOptions, effectiveCmd);
+        await executeAction(id, { ...options, flatArgs }, context, undefined, context?.control);
     });
 }
 /**

package/dist/commands/runs.js

@@ -1,7 +1,7 @@
-import { filterWithFallbackInfo, findProjectRoot, listLinkedPackages, loadProjectConfig, resolvePackageRoot, resolveTarget, } from "@actiondock/core";
-import { ArgumentError, ExecutionError } from "../errors.js";
+import { filterWithFallbackInfo, findProjectRoot, listLinkedPackages, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
+import { ArgumentError, ExecutionError, NO_PROJECT_NO_LINKED_MESSAGE, notInProjectError, packageNotFoundError, } from "../errors.js";
 import { renderResult, renderRunDetail, renderRunsList } from "../renderer.js";
-import { applyTargetOptions, getEffectiveOptions, resolveIntent, withRemoteTarget, withTarget, } from "../utils/index.js";
+import { applyTargetOptions, getEffectiveOptions, resolveIntent, resolveTargetFromOptions, withRemoteTarget, withTarget, } from "../utils/index.js";
 /**
  * 解析本地目标包根目录与工程配置（仅在 local 分支调用）。
  * 显式指定包且寻址失败时抛出参数错误；工程清单损坏时降级为链接包视图。
@@ -10,7 +10,7 @@ function resolveLocalRunScope(packageOption) {
     if (packageOption) {
         const root = resolvePackageRoot(packageOption);
         if (!root) {
-            throw new ArgumentError(`Package '${packageOption}' not found in linked packages or path`);
+            throw packageNotFoundError(packageOption);
         }
         try {
             return { targetPackageRoot: root, projConfig: loadProjectConfig(root) };
@@ -53,7 +53,6 @@ export function registerRunsCommands(program, context) {
         .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(async (patterns = [], rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
@@ -63,10 +62,9 @@ export function registerRunsCommands(program, context) {
         // 通过 Target 门面统一访问
         await withTarget(options, context, async (target, resolved) => {
             const records = await target.listRuns({
-                packageId: scope.projConfig?.id || options.package,
+                packageId: options.package,
                 actionId: options.action,
-                intent: effectiveIntent,
-                limit,
+                limit: 500,
             });
             // 若处于本地无项目环境且无任何软链接包，则直接输出友好提示
             if (resolved.type === "local" && !scope.targetPackageRoot) {
@@ -74,8 +72,7 @@ export function registerRunsCommands(program, context) {
                 if (linked.length === 0) {
                     renderResult([], {
                         json: options.json,
-                        envelope: options.envelope,
-                        humanFormatter: () => "No ActionDock project in current directory, and no packages linked.",
+                        humanFormatter: () => NO_PROJECT_NO_LINKED_MESSAGE,
                         context,
                     });
                     return;
@@ -85,7 +82,6 @@ export function registerRunsCommands(program, context) {
             const capped = filterRes.items.slice(0, limit);
             renderResult(capped, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => {
                     let title = "Execution Runs";
                     if (resolved.type === "remote") {
@@ -110,7 +106,6 @@ export function registerRunsCommands(program, context) {
         .option("-P, --package <id>", "Target package ID or path"))
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         if (!id) {
@@ -133,7 +128,6 @@ export function registerRunsCommands(program, context) {
             }
             renderResult(run, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => renderRunDetail(run),
                 context,
             });
@@ -145,18 +139,12 @@ export function registerRunsCommands(program, context) {
         .description("Cancel a running action execution on a remote server"))
         .option("-r, --reason <reason>", "Reason for cancellation")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (id, rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         if (!id) {
             throw new ArgumentError("Run ID is required for cancel");
         }
-        const resolved = resolveTarget({
-            profile: options.profile,
-            server: options.server,
-            token: options.token,
-            insecure: options.insecure,
-        }, context?.customHome);
+        const resolved = resolveTargetFromOptions(options, context);
         if (resolved.type === "local") {
             throw new ArgumentError("'ad runs cancel' is only supported for remote execution targets. Use --profile <name> or --server <url>.");
         }
@@ -165,7 +153,6 @@ export function registerRunsCommands(program, context) {
             const isErrorOutcome = result.outcome === "not_found" || result.outcome === "not_owner";
             renderResult(result, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => {
                     if (result.outcome === "not_found") {
                         return `Error: Run record '${id}' not found on remote server.`;
@@ -190,7 +177,6 @@ export function registerRunsCommands(program, context) {
         .option("-a, --action <actionId>", "Filter by action ID"))
         .option("--data-dir <path>", "Custom database storage directory")
         .option("--json", "Output as JSON")
-        .option("--envelope", "Wrap JSON output in standard envelope")
         .action(async (rawOptions, cmd) => {
         const options = getEffectiveOptions(rawOptions, cmd);
         let targetPackageRoot;
@@ -199,14 +185,14 @@ export function registerRunsCommands(program, context) {
             if (options.package) {
                 const root = resolvePackageRoot(options.package);
                 if (!root) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
                 targetPackageRoot = root;
             }
             else {
                 targetPackageRoot = findProjectRoot() || undefined;
                 if (!targetPackageRoot) {
-                    throw new ArgumentError("Not in an ActionDock project. Please specify -P, --package <id> or cd into a project directory.");
+                    throw notInProjectError("Please specify -P, --package <id> or cd into a project directory.");
                 }
             }
             try {
@@ -223,7 +209,6 @@ export function registerRunsCommands(program, context) {
             const payload = { ok: true, clearedCount: count };
             renderResult(payload, {
                 json: options.json,
-                envelope: options.envelope,
                 humanFormatter: () => resolved.type === "remote"
                     ? `Cleared ${count} execution run(s) on remote server.`
                     : `Cleared ${count} execution run(s) in package '${packageId}'.`,

package/dist/commands/serve.js

@@ -192,7 +192,15 @@ export function registerServeCommand(program, context) {
             writeStdout(`Press Ctrl+C to terminate.\n`, context);
             const stopSignalHandler = () => {
                 writeStdout("\nStopping ActionDock server...", context);
-                server.stop();
+                Promise.resolve(server.stop())
+                    .catch((err) => {
+                    // 停止失败必须可见：写入 stderr 一行并标记失败退出码
+                    writeStderr(`[ERROR] Failed to stop ActionDock server gracefully: ${err instanceof Error ? err.message : String(err)}`, context);
+                    process.exitCode = 1;
+                })
+                    .finally(() => {
+                    process.exit(typeof process.exitCode === "number" ? process.exitCode : 0);
+                });
             };
             process.once("SIGINT", stopSignalHandler);
             process.once("SIGTERM", stopSignalHandler);

package/dist/commands/state-list.js

@@ -1,5 +1,6 @@
 import { filterWithFallbackInfo, listLinkedPackages, loadProjectConfig, } from "@actiondock/core";
 import { existsSync } from "node:fs";
+import { NO_PROJECT_NO_LINKED_MESSAGE } from "../errors.js";
 import { renderResult, renderStateList } from "../renderer.js";
 /**
  * 渲染单个项目作用域的状态键列表（含 --detail JSON 明细分支）。
@@ -25,7 +26,6 @@ export async function renderProjectScopedStateList(args) {
         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;
@@ -33,7 +33,6 @@ export async function renderProjectScopedStateList(args) {
     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,
     });
@@ -48,8 +47,7 @@ export async function renderLinkedPackagesStateList(args) {
     if (linked.length === 0) {
         renderResult([], {
             json: options.json,
-            envelope: options.envelope,
-            humanFormatter: () => "No ActionDock project in current directory, and no packages linked.",
+            humanFormatter: () => NO_PROJECT_NO_LINKED_MESSAGE,
             context,
         });
         return;
@@ -75,7 +73,6 @@ export async function renderLinkedPackagesStateList(args) {
     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.js

@@ -1,8 +1,27 @@
 import { decodeStateKey, findProjectRoot, loadProjectConfig, resolvePackageRoot, } from "@actiondock/core";
-import { ArgumentError, ExecutionError } from "../errors.js";
-import { renderResult, renderStateList, writeStdout } from "../renderer.js";
+import { ArgumentError, ExecutionError, packageNotFoundError } from "../errors.js";
+import { renderResult, renderStateList, writeStderr, writeStdout } from "../renderer.js";
 import { applyTargetOptions, getEffectiveOptions, getTargetRoot, resolveIntent, withTarget, } from "../utils/index.js";
 import { renderLinkedPackagesStateList, renderProjectScopedStateList, } from "./state-list.js";
+/**
+ * 解析复合状态键为命名空间与裸键视图。
+ *
+ * 多冒号歧义键（如 `review:owner/repo:42`）不再直接崩溃：
+ * 降级为「整串作为裸 key」并在 stderr 提示可用 -n/--namespace 显式指定，
+ * 保持与本地存储层歧义兜底（deleteStateSmart 的纯键回退）一致的容错语义。
+ */
+function decodeStateKeyWithFallback(rawKey, hasExplicitNamespace, context) {
+    try {
+        const decoded = decodeStateKey(rawKey);
+        return { namespace: decoded.namespace || undefined, key: decoded.key };
+    }
+    catch {
+        if (!hasExplicitNamespace) {
+            writeStderr(`[WARN] State key '${rawKey}' contains multiple colon delimiters; treating it as a bare key. Use -n/--namespace to specify the namespace explicitly.`, context);
+        }
+        return { namespace: undefined, key: rawKey };
+    }
+}
 /**
  * 注册 state 状态管理命令（get、set、delete、clear、keys、list）。
  *
@@ -28,7 +47,6 @@ export function registerStateCommands(program, context) {
                 });
                 renderResult(keys, {
                     json: options.json,
-                    envelope: options.envelope,
                     humanFormatter: () => renderStateList(keys, `Remote Server ${resolved.serverUrl}${resolved.profileName ? ` (Profile: ${resolved.profileName})` : ""}`, false, effectiveIntent),
                     context,
                 });
@@ -39,7 +57,7 @@ export function registerStateCommands(program, context) {
             if (options.package) {
                 targetRoot = resolvePackageRoot(options.package);
                 if (!targetRoot) {
-                    throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
+                    throw packageNotFoundError(options.package);
                 }
             }
             else {
@@ -81,7 +99,6 @@ export function registerStateCommands(program, context) {
         .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 别名
     applyTargetOptions(stateCmd
@@ -95,7 +112,6 @@ export function registerStateCommands(program, context) {
         .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>
     applyTargetOptions(stateCmd
@@ -106,7 +122,6 @@ export function registerStateCommands(program, context) {
         .option("-n, --namespace <ns>", "Explicit namespace scope for key"))
         .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) {
@@ -115,8 +130,8 @@ export function registerStateCommands(program, context) {
         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 decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
+                const effectiveNamespace = options.namespace || decoded.namespace;
                 const actualKey = options.namespace ? rawKey : decoded.key;
                 const entry = await target.getState(options.package || "", actionId, actualKey, {
                     namespace: effectiveNamespace,
@@ -128,7 +143,6 @@ export function registerStateCommands(program, context) {
                 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,
                 });
@@ -148,7 +162,6 @@ export function registerStateCommands(program, context) {
             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,
             });
@@ -182,8 +195,8 @@ export function registerStateCommands(program, context) {
         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 decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
+                const effectiveNamespace = options.namespace || decoded.namespace;
                 const actualKey = options.namespace ? rawKey : decoded.key;
                 await target.setState(options.package || "", actionId, actualKey, parsedVal, {
                     namespace: effectiveNamespace,
@@ -198,7 +211,7 @@ export function registerStateCommands(program, context) {
             let actualNamespace = options.namespace;
             let finalKey = effectiveKey;
             if (options.namespace === undefined && effectiveKey.includes(":")) {
-                const decoded = decodeStateKey(effectiveKey);
+                const decoded = decodeStateKeyWithFallback(effectiveKey, false, context);
                 actualNamespace = decoded.namespace;
                 finalKey = decoded.key;
             }
@@ -227,8 +240,8 @@ export function registerStateCommands(program, context) {
         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 decoded = decodeStateKeyWithFallback(rawKey, options.namespace !== undefined, context);
+                const effectiveNamespace = options.namespace || decoded.namespace;
                 const actualKey = options.namespace ? rawKey : decoded.key;
                 const deleted = await target.deleteState(options.package || "", actionId, actualKey, {
                     namespace: effectiveNamespace,

package/dist/commands/test.js

@@ -1,6 +1,7 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { findProjectRoot } from "@actiondock/core";
+import { writeStderr } from "../renderer.js";
 import { spawnAsync } from "../utils/index.js";
 export function registerTestCommand(program) {
     program
@@ -32,11 +33,14 @@ export function registerTestCommand(program) {
                 testArgs.push(pattern);
             }
         }
-        // stdio inherit 保持实时输出；进程异常（如命令不存在）时回退退出码 1
+        // stdio inherit 保持实时输出；进程异常（如命令不存在）时透传错误消息并以退出码 1 失败
         const proc = await spawnAsync(testCmd, testArgs, {
             cwd,
             stdio: "inherit",
-        }).catch(() => ({ status: 1, signal: null, stdout: "", stderr: "" }));
+        }).catch((err) => {
+            writeStderr(`[ERROR] Failed to run test command '${testCmd}': ${err instanceof Error ? err.message : String(err)}`);
+            return { status: 1, signal: null, stdout: "", stderr: "" };
+        });
         if (proc.status !== 0) {
             process.exitCode = proc.status ?? 1;
         }