@actiondock/cli 2.0.9 → 2.0.11-beta.0

package/src/commands/serve.ts

@@ -3,6 +3,7 @@ import { findProjectRoot, loadProjectConfig, startActionDockServer } from "@acti
 import { createActionDockMcpServer } from "@actiondock/mcp";
 import { createMcpHandler } from "@modelcontextprotocol/server";
 import { Command } from "commander";
+import { ExecutionError } from "@actiondock/runtime-cli";
 import { parseByteSize } from "../utils/bytes";
 
 export function registerServeCommand(program: Command): void {
@@ -36,8 +37,7 @@ export function registerServeCommand(program: Command): void {
         try {
           maxBodyBytes = parseByteSize(options.maxBody);
         } catch (err: any) {
-          console.error(`Error: ${err.message}`);
-          process.exit(1);
+          throw new ExecutionError(err.message);
         }
       }
 
@@ -126,8 +126,7 @@ export function registerServeCommand(program: Command): void {
           process.exit(0);
         });
       } catch (err: any) {
-        console.error(`Failed to start ActionDock server: ${err.message}`);
-        process.exit(1);
+        throw new ExecutionError(`Failed to start ActionDock server: ${err.message}`);
       }
     });
 }

package/src/commands/state.ts

@@ -13,6 +13,7 @@ import {
   resolveTarget,
   setRemoteStateKey,
 } from "@actiondock/core";
+import { ArgumentError, ExecutionError, getEffectiveOptions, renderResult } from "@actiondock/runtime-cli";
 import { Command } from "commander";
 import { resolveIntent } from "../utils/filter";
 
@@ -31,13 +32,11 @@ function getTargetRoot(packageOption?: string, keyHint?: string): { root: string
   const root = resolvePackageRoot(targetPackage);
   if (!root) {
     if (targetPackage) {
-      console.error(`Error: Package '${targetPackage}' not found in linked packages or path`);
-    } else {
-      console.error(
-        "Error: Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id> or cd into a project directory."
-      );
+      throw new ArgumentError(`Package '${targetPackage}' not found in linked packages or path`);
     }
-    process.exit(1);
+    throw new ArgumentError(
+      "Not in an ActionDock project (actiondock.json not found).\nPlease specify -P, --package <id> or cd into a project directory."
+    );
   }
   return { root, key: effectiveKey };
 }
@@ -59,11 +58,15 @@ export function registerStateCommands(program: Command): void {
     .option("-i, --intent <pattern>", "Regex or fuzzy intent filter; falls back to full list when no match")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("-d, --detail", "Show detailed state entry objects (including namespace, expiration, update time)")
+    .option("--data-dir <path>", "Custom database storage directory")
     .option("--json", "Output as JSON")
-    .action(async (prefix = "", options) => {
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (prefix = "", rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, prefix ? [prefix] : []);
         const shouldFallback = options.fallback !== false;
+        const isMachine = Boolean(options.json || options.envelope);
 
         const target = resolveTarget({
           profile: options.profile,
@@ -77,8 +80,8 @@ export function registerStateCommands(program: Command): void {
             namespace: options.namespace,
             prefix,
           });
-          if (options.json) {
-            console.log(JSON.stringify(res.keys, null, 2));
+          if (isMachine) {
+            renderResult(res.keys, { json: options.json, envelope: options.envelope });
             return;
           }
           console.log(
@@ -95,15 +98,17 @@ export function registerStateCommands(program: Command): void {
           : findProjectRoot();
 
         if (options.package && !targetRoot) {
-          console.error(`Error: Package '${options.package}' not found in linked packages or path`);
-          process.exit(1);
+          throw new ArgumentError(`Package '${options.package}' not found in linked packages or path`);
         }
 
         if (targetRoot) {
           const projConfig = loadProjectConfig(targetRoot);
-          const storage = createStorage(projConfig.id, { projectRoot: targetRoot });
+          const storage = createStorage(projConfig.id, {
+            projectRoot: targetRoot,
+            dataDir: options.dataDir,
+          });
 
-          if (options.detail && options.json) {
+          if (options.detail && isMachine) {
             const entries = await storage.listStateEntries({
               namespace: options.namespace,
               prefix: prefix || undefined,
@@ -117,7 +122,7 @@ export function registerStateCommands(program: Command): void {
               shouldFallback
             );
 
-            console.log(JSON.stringify(filterRes.items, null, 2));
+            renderResult(filterRes.items, { json: options.json, envelope: options.envelope });
             return;
           }
 
@@ -134,8 +139,8 @@ export function registerStateCommands(program: Command): void {
             shouldFallback
           );
 
-          if (options.json) {
-            console.log(JSON.stringify(filterRes.items, null, 2));
+          if (isMachine) {
+            renderResult(filterRes.items, { json: options.json, envelope: options.envelope });
           } else {
             const nsDesc = options.namespace ? ` [namespace: ${options.namespace}]` : "";
             const filterDesc = prefix ? ` (filter: ${prefix})` : "";
@@ -157,6 +162,10 @@ export function registerStateCommands(program: Command): void {
         // Outside project: list state keys across all linked packages
         const linkedList = listLinkedPackages();
         if (linkedList.length === 0) {
+          if (isMachine) {
+            renderResult([], { json: options.json, envelope: options.envelope });
+            return;
+          }
           console.log("No ActionDock project in current directory, and no packages linked.");
           console.log("Run 'ad link' inside an Action package to register it.");
           return;
@@ -174,9 +183,12 @@ export function registerStateCommands(program: Command): void {
           if (!existsSync(pkg.path)) continue;
           try {
             const projConfig = loadProjectConfig(pkg.path);
-            const storage = createStorage(projConfig.id, { projectRoot: pkg.path });
+            const storage = createStorage(projConfig.id, {
+              projectRoot: pkg.path,
+              dataDir: options.dataDir,
+            });
 
-            if (options.detail && options.json) {
+            if (options.detail && isMachine) {
               const entries = await storage.listStateEntries({
                 namespace: options.namespace,
                 prefix: prefix || undefined,
@@ -243,8 +255,8 @@ export function registerStateCommands(program: Command): void {
           }
         }
 
-        if (options.json) {
-          console.log(JSON.stringify(filteredPackages, null, 2));
+        if (isMachine) {
+          renderResult(filteredPackages, { json: options.json, envelope: options.envelope });
         } else {
           console.log("State Keys in Linked Packages:\n");
           for (const pkg of filteredPackages) {
@@ -259,8 +271,8 @@ export function registerStateCommands(program: Command): void {
           }
         }
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof ExecutionError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -273,9 +285,13 @@ export function registerStateCommands(program: Command): void {
     .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")
-    .action(async (rawKey, options) => {
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (rawKey, rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const isMachine = Boolean(options.json || options.envelope);
         const target = resolveTarget({
           profile: options.profile,
           server: options.server,
@@ -287,8 +303,8 @@ export function registerStateCommands(program: Command): void {
             package: options.package,
             namespace: options.namespace,
           });
-          if (options.json) {
-            console.log(JSON.stringify(res, null, 2));
+          if (isMachine) {
+            renderResult(res, { json: options.json, envelope: options.envelope });
           } else {
             console.log(res.value !== undefined ? JSON.stringify(res.value, null, 2) : "undefined");
           }
@@ -297,7 +313,10 @@ export function registerStateCommands(program: Command): void {
 
         const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
-        const storage = createStorage(projConfig.id, { projectRoot: root });
+        const storage = createStorage(projConfig.id, {
+          projectRoot: root,
+          dataDir: options.dataDir,
+        });
 
         let val: unknown;
         let entryNamespace = options.namespace || "";
@@ -314,29 +333,25 @@ export function registerStateCommands(program: Command): void {
         storage.close();
 
         if (val === undefined) {
-          console.error(`Error: State key '${key}' not found in ${projConfig.id}`);
-          process.exit(1);
+          throw new ExecutionError(`State key '${key}' not found in ${projConfig.id}`);
         }
 
-        if (options.json) {
-          console.log(
-            JSON.stringify(
-              {
-                key,
-                packageId: projConfig.id,
-                namespace: entryNamespace,
-                value: val,
-              },
-              null,
-              2
-            )
+        if (isMachine) {
+          renderResult(
+            {
+              key,
+              packageId: projConfig.id,
+              namespace: entryNamespace,
+              value: val,
+            },
+            { json: options.json, envelope: options.envelope }
           );
         } else {
           console.log(val !== undefined ? JSON.stringify(val, null, 2) : "undefined");
         }
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof ExecutionError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -350,8 +365,13 @@ export function registerStateCommands(program: Command): void {
     .option("-s, --server <url>", "Remote server URL")
     .option("-t, --token <token>", "Auth token for remote server")
     .option("--ttl <seconds>", "Time to live in seconds", (v) => parseInt(v, 10))
-    .action(async (rawKey, rawValue, options) => {
+    .option("--data-dir <path>", "Custom database storage directory")
+    .option("--json", "Output as JSON")
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (rawKey, rawValue, rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const isMachine = Boolean(options.json || options.envelope);
         let parsed: unknown = rawValue;
         try {
           parsed = JSON.parse(rawValue);
@@ -371,13 +391,23 @@ export function registerStateCommands(program: Command): void {
             namespace: options.namespace,
             ttl: options.ttl,
           });
-          console.log(`[OK] State '${rawKey}' updated on remote server ${target.serverUrl}`);
+          if (isMachine) {
+            renderResult(
+              { ok: true, key: rawKey, value: parsed, ttl: options.ttl },
+              { json: options.json, envelope: options.envelope }
+            );
+          } else {
+            console.log(`[OK] State '${rawKey}' updated on remote server ${target.serverUrl}`);
+          }
           return;
         }
 
         const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
-        const storage = createStorage(projConfig.id, { projectRoot: root });
+        const storage = createStorage(projConfig.id, {
+          projectRoot: root,
+          dataDir: options.dataDir,
+        });
 
         let ns = "";
         let actualKey = key;
@@ -395,12 +425,25 @@ export function registerStateCommands(program: Command): void {
         storage.close();
 
         const displayKey = ns ? `${ns}:${actualKey}` : actualKey;
-        console.log(
-          `[OK] State '${displayKey}' set to ${JSON.stringify(parsed)}${options.ttl ? ` (TTL: ${options.ttl}s)` : ""} in ${projConfig.id}`
-        );
+        if (isMachine) {
+          renderResult(
+            {
+              ok: true,
+              key: displayKey,
+              value: parsed,
+              ttl: options.ttl,
+              packageId: projConfig.id,
+            },
+            { json: options.json, envelope: options.envelope }
+          );
+        } else {
+          console.log(
+            `[OK] State '${displayKey}' set to ${JSON.stringify(parsed)}${options.ttl ? ` (TTL: ${options.ttl}s)` : ""} in ${projConfig.id}`
+          );
+        }
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof ExecutionError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -415,8 +458,13 @@ export function registerStateCommands(program: Command): void {
     .option("-s, --server <url>", "Remote server URL")
     .option("-t, --token <token>", "Auth token for remote server")
     .option("--silent", "Do not exit with error if key is not found")
-    .action(async (rawKey, options) => {
+    .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) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const isMachine = Boolean(options.json || options.envelope);
         const target = resolveTarget({
           profile: options.profile,
           server: options.server,
@@ -428,27 +476,40 @@ export function registerStateCommands(program: Command): void {
             package: options.package,
             namespace: options.namespace,
           });
-          console.log(`[OK] State '${rawKey}' deleted from remote server ${target.serverUrl}`);
+          if (isMachine) {
+            renderResult({ ok: true, key: rawKey }, { json: options.json, envelope: options.envelope });
+          } else {
+            console.log(`[OK] State '${rawKey}' deleted from remote server ${target.serverUrl}`);
+          }
           return;
         }
 
         const { root, key } = getTargetRoot(options.package, rawKey);
         const projConfig = loadProjectConfig(root);
-        const storage = createStorage(projConfig.id, { projectRoot: root });
+        const storage = createStorage(projConfig.id, {
+          projectRoot: root,
+          dataDir: options.dataDir,
+        });
         const deleted = await storage.deleteStateSmart(key, options.namespace);
         storage.close();
 
         if (deleted) {
-          console.log(`[OK] State '${key}' deleted from ${projConfig.id}`);
+          if (isMachine) {
+            renderResult({ ok: true, key, deleted: true, packageId: projConfig.id }, { json: options.json, envelope: options.envelope });
+          } else {
+            console.log(`[OK] State '${key}' deleted from ${projConfig.id}`);
+          }
         } else {
           if (!options.silent) {
-            console.error(`Error: State key '${key}' not found in ${projConfig.id}`);
-            process.exit(1);
+            throw new ExecutionError(`State key '${key}' not found in ${projConfig.id}`);
+          }
+          if (isMachine) {
+            renderResult({ ok: true, key, deleted: false, packageId: projConfig.id }, { json: options.json, envelope: options.envelope });
           }
         }
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof ExecutionError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -463,8 +524,13 @@ export function registerStateCommands(program: Command): void {
     .option("-s, --server <url>", "Remote server URL")
     .option("-t, --token <token>", "Auth token for remote server")
     .option("-a, --all", "Clear all state entries across all namespaces in this package")
-    .action(async (prefix = "", options) => {
+    .option("--data-dir <path>", "Custom database storage directory")
+    .option("--json", "Output as JSON")
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (prefix = "", rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        const isMachine = Boolean(options.json || options.envelope);
         const target = resolveTarget({
           profile: options.profile,
           server: options.server,
@@ -478,13 +544,20 @@ export function registerStateCommands(program: Command): void {
             prefix,
             all: Boolean(options.all),
           });
-          console.log(`[OK] Cleared ${res.clearedCount} state entry(s) on remote server ${target.serverUrl}`);
+          if (isMachine) {
+            renderResult(res, { json: options.json, envelope: options.envelope });
+          } else {
+            console.log(`[OK] Cleared ${res.clearedCount} state entry(s) on remote server ${target.serverUrl}`);
+          }
           return;
         }
 
         const { root } = getTargetRoot(options.package);
         const projConfig = loadProjectConfig(root);
-        const storage = createStorage(projConfig.id, { projectRoot: root });
+        const storage = createStorage(projConfig.id, {
+          projectRoot: root,
+          dataDir: options.dataDir,
+        });
         const count = await storage.clearState({
           namespace: options.namespace,
           all: options.all,
@@ -499,10 +572,18 @@ export function registerStateCommands(program: Command): void {
             : prefix
               ? `prefix '${prefix}'`
               : "root namespace";
-        console.log(`[OK] Cleared ${count} state entry(s) (${scopeDesc}) from ${projConfig.id}`);
+
+        if (isMachine) {
+          renderResult(
+            { ok: true, clearedCount: count, scope: scopeDesc, packageId: projConfig.id },
+            { json: options.json, envelope: options.envelope }
+          );
+        } else {
+          console.log(`[OK] Cleared ${count} state entry(s) (${scopeDesc}) from ${projConfig.id}`);
+        }
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof ExecutionError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 }

package/src/commands/test.ts

@@ -42,7 +42,7 @@ export function registerTestCommand(program: Command): void {
       });
 
       if (proc.status !== 0) {
-        process.exit(proc.status ?? 1);
+        process.exitCode = proc.status ?? 1;
       }
     });
 }

package/src/index.ts

@@ -1,4 +1,6 @@
+import { formatError } from "@actiondock/runtime-cli";
 import { setupNodeRuntime } from "@actiondock/runtime-node";
+import { CommanderError } from "commander";
 import { createCliProgram } from "./commands";
 
 export * from "./commands";
@@ -7,16 +9,50 @@ export * from "./commands";
  * ActionDock CLI 主执行入口函数。
  * 
  * @param argv 命令行参数数组（默认使用 process.argv）
+ * @returns 进程退出码
  */
-export async function main(argv: string[] = process.argv): Promise<void> {
+export async function main(argv: string[] = process.argv): Promise<number> {
   setupNodeRuntime();
   const program = createCliProgram();
-  await program.parseAsync(argv);
+
+  const isMachine = argv.includes("--json") || argv.includes("--envelope");
+
+  try {
+    await program.parseAsync(argv);
+    return typeof process.exitCode === "number" ? process.exitCode : 0;
+  } catch (err: unknown) {
+    if (err instanceof CommanderError) {
+      if (err.exitCode === 0) {
+        return 0;
+      }
+    }
+
+    const formatted = formatError(err);
+    if (isMachine) {
+      const errorEnv = {
+        ok: false,
+        error: {
+          code: formatted.code,
+          message: formatted.message,
+          ...(formatted.details !== undefined ? { details: formatted.details } : {}),
+        },
+      };
+      console.log(JSON.stringify(errorEnv, null, 2));
+    } else {
+      const msg = formatted.message.startsWith("Error: ")
+        ? formatted.message
+        : `Error: ${formatted.message}`;
+      console.error(msg);
+    }
+    process.exitCode = formatted.exitCode;
+    return formatted.exitCode;
+  }
 }
 
 if ((import.meta as any).main) {
   main().catch((err) => {
     console.error("Fatal error:", err);
-    process.exit(1);
+    process.exitCode = 1;
   });
 }
+

package/src/utils/bytes.ts

@@ -1,36 +1,2 @@
-/**
- * Parses human-readable byte size string into number of bytes.
- * e.g. "1mb" -> 1048576, "500kb" -> 512000, "1048576" -> 1048576
- */
-export function parseByteSize(str: string): number {
-  const trimmed = str.trim().toLowerCase();
-  const match = trimmed.match(/^(\d+(?:\.\d+)?)\s*([a-z]+)?$/);
-  if (!match) {
-    const num = Number(trimmed);
-    if (!isNaN(num) && num > 0) return num;
-    throw new Error(`Invalid byte size format: '${str}'. Examples: '1mb', '500kb', '1048576'`);
-  }
+export { parseByteSize } from "@actiondock/runtime-cli";
 
-  const value = parseFloat(match[1]);
-  const unit = match[2] || "b";
-
-  switch (unit) {
-    case "b":
-    case "bytes":
-      return Math.floor(value);
-    case "k":
-    case "kb":
-    case "kib":
-      return Math.floor(value * 1024);
-    case "m":
-    case "mb":
-    case "mib":
-      return Math.floor(value * 1024 * 1024);
-    case "g":
-    case "gb":
-    case "gib":
-      return Math.floor(value * 1024 * 1024 * 1024);
-    default:
-      throw new Error(`Unsupported byte size unit '${unit}' in '${str}'`);
-  }
-}

package/src/utils/filter.ts

@@ -1,24 +1,2 @@
-/**
- * Resolves effective intent string from an explicit option (--intent)
- * and optional positional pattern arguments.
- * Multiple terms are combined with '|' (regex OR).
- */
-export function resolveIntent(
-  optionsIntent?: string,
-  positionalPatterns?: string[]
-): string | undefined {
-  const parts: string[] = [];
-  if (optionsIntent && optionsIntent.trim()) {
-    parts.push(optionsIntent.trim());
-  }
-  if (positionalPatterns && positionalPatterns.length > 0) {
-    for (const p of positionalPatterns) {
-      if (typeof p === "string" && p.trim()) {
-        parts.push(p.trim());
-      }
-    }
-  }
-  if (parts.length === 0) return undefined;
-  if (parts.length === 1) return parts[0];
-  return parts.join("|");
-}
+export { resolveIntent } from "@actiondock/runtime-cli";
+