@actiondock/cli 2.0.9 → 2.0.11-beta.0

package/src/commands/mcp.ts

@@ -2,6 +2,7 @@ import { resolve } from "node:path";
 import { findProjectRoot, loadProjectConfig } from "@actiondock/core";
 import { startMcpHttpServer, startMcpStdio } from "@actiondock/mcp";
 import { Command } from "commander";
+import { ExecutionError } from "@actiondock/runtime-cli";
 import { parseByteSize } from "../utils/bytes";
 import { parseDuration } from "../utils/duration";
 
@@ -35,8 +36,7 @@ export function registerMcpCommands(program: Command): void {
         try {
           timeoutMs = parseDuration(options.timeout);
         } catch (err: any) {
-          process.stderr.write(`Error: ${err.message}\n`);
-          process.exit(1);
+          throw new ExecutionError(err.message);
         }
       }
 
@@ -56,8 +56,7 @@ export function registerMcpCommands(program: Command): void {
           timeoutMs,
         });
       } catch (err: any) {
-        process.stderr.write(`Failed to start MCP STDIO server: ${err.message}\n`);
-        process.exit(1);
+        throw new ExecutionError(`Failed to start MCP STDIO server: ${err.message}`);
       }
     });
 
@@ -106,8 +105,7 @@ export function registerMcpCommands(program: Command): void {
         try {
           maxBodyBytes = parseByteSize(options.maxBody);
         } catch (err: any) {
-          console.error(`Error: ${err.message}`);
-          process.exit(1);
+          throw new ExecutionError(err.message);
         }
       }
 
@@ -116,8 +114,7 @@ export function registerMcpCommands(program: Command): void {
         try {
           timeoutMs = parseDuration(options.timeout);
         } catch (err: any) {
-          console.error(`Error: ${err.message}`);
-          process.exit(1);
+          throw new ExecutionError(err.message);
         }
       }
 
@@ -192,8 +189,7 @@ export function registerMcpCommands(program: Command): void {
           process.exit(0);
         });
       } catch (err: any) {
-        console.error(`Failed to start ActionDock MCP HTTP server: ${err.message}`);
-        process.exit(1);
+        throw new ExecutionError(`Failed to start ActionDock MCP HTTP server: ${err.message}`);
       }
     });
 }

package/src/commands/playbook.ts

@@ -11,11 +11,19 @@ import {
   loadPlaybooks,
   loadProjectConfig,
   resolveActionProject,
+  resolvePackageRoot,
   resolvePlaybookProject,
   resolveTarget,
 } from "@actiondock/core";
 import type { PlaybookDefinition } from "@actiondock/core";
 import { Command } from "commander";
+import {
+  ArgumentError,
+  CliError,
+  ExecutionError,
+  getEffectiveOptions,
+  renderResult,
+} from "@actiondock/runtime-cli";
 import { resolveIntent } from "../utils/filter";
 
 export function registerPlaybookCommands(program: Command): void {
@@ -32,12 +40,17 @@ export function registerPlaybookCommands(program: Command): void {
     .option("-p, --profile <name>", "Query against a specific profile")
     .option("-s, --server <url>", "Remote server URL")
     .option("-t, --token <token>", "Auth token for remote server")
+    .option("--fallback", "Enable fallback to full list when no items match intent")
     .option("--no-fallback", "Disable fallback to full list when no items match intent")
     .option("--json", "Output as JSON")
-    .action(async (patterns, options) => {
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (patterns, rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
         const effectiveIntent = resolveIntent(options.intent, patterns);
-        const shouldFallback = options.fallback !== false;
+        const isMachine = Boolean(options.json || options.envelope);
+        const fallbackExplicit = options.fallback === true || (Array.isArray(process.argv) && process.argv.includes("--fallback"));
+        const shouldFallback = isMachine ? fallbackExplicit : options.fallback !== false;
 
         const target = resolveTarget({
           profile: options.profile,
@@ -46,31 +59,65 @@ export function registerPlaybookCommands(program: Command): void {
         });
 
         if (target.type === "remote") {
-          const remotePbs = await fetchRemotePlaybooks(target.serverUrl!, target.token, {
+          let remotePbs = await fetchRemotePlaybooks(target.serverUrl!, target.token, {
             intent: effectiveIntent,
             package: options.package,
           });
-          if (options.json) {
-            console.log(JSON.stringify(remotePbs, null, 2));
-            return;
+
+          let isFallback = false;
+          if (remotePbs.length === 0 && effectiveIntent && shouldFallback) {
+            remotePbs = await fetchRemotePlaybooks(target.serverUrl!, target.token, {
+              package: options.package,
+            });
+            isFallback = true;
           }
-          console.log(
-            `Playbooks on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}:\n`
-          );
-          if (remotePbs.length === 0) {
-            console.log("  (No playbooks found)");
-          } else {
-            for (const p of remotePbs) {
-              console.log(`  ${p.id.padEnd(24)} ${p.description} (Package: ${p.packageId})`);
-            }
+
+          if (isFallback && isMachine) {
+            renderResult(
+              { items: remotePbs, isFallback: true, matchedCount: 0 },
+              { json: options.json, envelope: options.envelope }
+            );
+            return;
           }
+
+          renderResult(remotePbs, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+              const lines = [
+                `Playbooks on remote server ${target.serverUrl}${target.profileName ? ` (Profile: ${target.profileName})` : ""}:\n`,
+              ];
+              if (isFallback && effectiveIntent) {
+                lines.push(`(No remote playbooks matched intent '${effectiveIntent}', showing all playbooks)\n`);
+              }
+              if (remotePbs.length === 0) {
+                lines.push("  (No playbooks found)");
+              } else {
+                for (const p of remotePbs) {
+                  lines.push(`  ${p.id.padEnd(24)} ${p.description} (Package: ${p.packageId})`);
+                }
+              }
+              return lines.join("\n");
+            },
+          });
           return;
         }
 
-        const root = findProjectRoot();
-        if (root) {
-          const config = loadProjectConfig(root);
-          const playbooks = loadPlaybooks(root, config.playbooksDir);
+        let targetRoot: string | null = 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) {
+          const config = loadProjectConfig(targetRoot);
+          const playbooks = loadPlaybooks(targetRoot, config.playbooksDir);
           const rawList = Array.from(playbooks.values()).map((p) => ({
             id: p.id,
             description: p.description || "",
@@ -86,116 +133,144 @@ export function registerPlaybookCommands(program: Command): void {
             shouldFallback
           );
 
-          if (options.json) {
-            console.log(JSON.stringify(filterRes.items, null, 2));
-          } else {
-            console.log(`Playbooks in ${config.id} (${root}):\n`);
-            if (filterRes.isFallback && effectiveIntent) {
-              console.log(`(No playbooks matched intent '${effectiveIntent}', showing all playbooks)\n`);
-            }
-            for (const p of filterRes.items) {
-              console.log(`  ${p.id.padEnd(24)} ${p.description}`);
-            }
-          }
-        } else {
-          // List playbooks across all linked packages
-          const linkedList = listLinkedPackages();
-          if (linkedList.length === 0) {
-            console.log("No ActionDock project in current directory, and no packages linked.");
-            console.log("Run 'ad link' inside an Action package to register it.");
+          if (filterRes.isFallback && isMachine) {
+            renderResult(
+              { items: filterRes.items, isFallback: true, matchedCount: 0 },
+              { json: options.json, envelope: options.envelope }
+            );
             return;
           }
 
-          const aggregated: Array<{
-            packageId: string;
-            packageName: string;
-            path: string;
-            playbooks: Array<{
-              id: string;
-              description: string;
-              actions: string[];
-              file: string;
-            }>;
-          }> = [];
+          renderResult(filterRes.items, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+              const lines = [`Playbooks in ${config.id} (${targetRoot}):\n`];
+              if (filterRes.isFallback && effectiveIntent) {
+                lines.push(`(No playbooks matched intent '${effectiveIntent}', showing all playbooks)\n`);
+              }
+              for (const p of filterRes.items) {
+                lines.push(`  ${p.id.padEnd(24)} ${p.description}`);
+              }
+              return lines.join("\n");
+            },
+          });
+          return;
+        }
+        // List playbooks across all linked packages
+        const linkedList = listLinkedPackages();
+        if (linkedList.length === 0) {
+          renderResult([], {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () =>
+              "No ActionDock project in current directory, and no packages linked.\nRun 'ad link' inside an Action package to register it.",
+          });
+          return;
+        }
 
-          for (const pkg of linkedList) {
-            if (!existsSync(pkg.path)) continue;
-            try {
-              const config = loadProjectConfig(pkg.path);
-              const playbooks = loadPlaybooks(pkg.path, config.playbooksDir);
-              const pkgPlaybooks = Array.from(playbooks.values()).map((p) => ({
-                id: p.id,
-                description: p.description || "",
-                actions: p.actions || [],
-                file: p.filePath,
-              }));
-
-              aggregated.push({
-                packageId: pkg.id,
-                packageName: pkg.name,
-                path: pkg.path,
-                playbooks: pkgPlaybooks,
-              });
-            } catch {
-              // Ignore broken linked package
-            }
+        const aggregated: Array<{
+          packageId: string;
+          packageName: string;
+          path: string;
+          playbooks: Array<{
+            id: string;
+            description: string;
+            actions: string[];
+            file: string;
+          }>;
+        }> = [];
+
+        for (const pkg of linkedList) {
+          if (!existsSync(pkg.path)) continue;
+          try {
+            const config = loadProjectConfig(pkg.path);
+            const playbooks = loadPlaybooks(pkg.path, config.playbooksDir);
+            const pkgPlaybooks = Array.from(playbooks.values()).map((p) => ({
+              id: p.id,
+              description: p.description || "",
+              actions: p.actions || [],
+              file: p.filePath,
+            }));
+
+            aggregated.push({
+              packageId: pkg.id,
+              packageName: pkg.name,
+              path: pkg.path,
+              playbooks: pkgPlaybooks,
+            });
+          } catch {
+            // Ignore broken linked package
           }
+        }
 
-          let filteredPackages: typeof aggregated = [];
-          if (!effectiveIntent) {
-            filteredPackages = aggregated;
-          } else {
-            for (const pkg of aggregated) {
-              const pkgMatches = filterWithFallbackInfo(
-                [pkg],
+        let filteredPackages: typeof aggregated = [];
+        let isFallback = false;
+        if (!effectiveIntent) {
+          filteredPackages = aggregated;
+        } else {
+          for (const pkg of aggregated) {
+            const pkgMatches = filterWithFallbackInfo(
+              [pkg],
+              effectiveIntent,
+              [(p) => p.packageId, (p) => p.packageName, (p) => p.path],
+              false
+            ).matchedCount > 0;
+
+            if (pkgMatches) {
+              filteredPackages.push(pkg);
+            } else {
+              const matchedPlaybooks = filterWithFallbackInfo(
+                pkg.playbooks,
                 effectiveIntent,
-                [(p) => p.packageId, (p) => p.packageName, (p) => p.path],
+                [(p) => p.id, (p) => p.description, (p) => p.actions, (p) => p.file],
                 false
-              ).matchedCount > 0;
+              ).items;
 
-              if (pkgMatches) {
-                filteredPackages.push(pkg);
-              } else {
-                const matchedPlaybooks = filterWithFallbackInfo(
-                  pkg.playbooks,
-                  effectiveIntent,
-                  [(p) => p.id, (p) => p.description, (p) => p.actions, (p) => p.file],
-                  false
-                ).items;
-
-                if (matchedPlaybooks.length > 0) {
-                  filteredPackages.push({
-                    ...pkg,
-                    playbooks: matchedPlaybooks,
-                  });
-                }
+              if (matchedPlaybooks.length > 0) {
+                filteredPackages.push({
+                  ...pkg,
+                  playbooks: matchedPlaybooks,
+                });
               }
             }
+          }
 
-            if (filteredPackages.length === 0 && shouldFallback) {
-              filteredPackages = aggregated;
-            }
+          if (filteredPackages.length === 0 && shouldFallback) {
+            filteredPackages = aggregated;
+            isFallback = true;
           }
+        }
 
-          if (options.json) {
-            console.log(JSON.stringify(filteredPackages, null, 2));
-          } else {
-            console.log("Playbooks in Linked Packages:\n");
+        if (isFallback && isMachine) {
+          renderResult(
+            { packages: filteredPackages, isFallback: true, matchedCount: 0 },
+            { json: options.json, envelope: options.envelope }
+          );
+          return;
+        }
+
+        renderResult(filteredPackages, {
+          json: options.json,
+          envelope: options.envelope,
+          humanFormatter: () => {
+            const lines = ["Playbooks in Linked Packages:\n"];
             for (const pkg of filteredPackages) {
-              console.log(`* Package: ${pkg.packageId} (${pkg.path})`);
+              lines.push(`* Package: ${pkg.packageId} (${pkg.path})`);
               if (pkg.playbooks.length === 0) {
-                console.log("    (No playbooks)");
+                lines.push("    (No playbooks)");
               } else {
                 for (const p of pkg.playbooks) {
-                  console.log(`    - ${p.id.padEnd(26)} ${p.description}`);
+                  lines.push(`    - ${p.id.padEnd(26)} ${p.description}`);
                 }
               }
             }
-          }
-        }
+            return lines.join("\n");
+          },
+        });
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof CliError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -210,8 +285,7 @@ export function registerPlaybookCommands(program: Command): void {
     .action((id, options) => {
       const root = findProjectRoot();
       if (!root) {
-        console.error("Error: Not in an ActionDock project (actiondock.json not found)");
-        process.exit(1);
+        throw new ExecutionError("Not in an ActionDock project (actiondock.json not found)");
       }
       try {
         const config = loadProjectConfig(root);
@@ -225,8 +299,7 @@ export function registerPlaybookCommands(program: Command): void {
         const targetFullFile = resolve(pbDir, targetRelFile);
 
         if (existsSync(targetFullFile)) {
-          console.error(`Error: File '${targetFullFile}' already exists`);
-          process.exit(1);
+          throw new ExecutionError(`File '${targetFullFile}' already exists`);
         }
 
         mkdirSync(dirname(targetFullFile), { recursive: true });
@@ -256,8 +329,10 @@ This playbook provides task execution guidance for AI Agents.
         writeFileSync(targetFullFile, template, "utf-8");
         console.log(`[OK] Created Playbook '${id}' at ${targetFullFile}`);
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof CliError) {
+          throw err;
+        }
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -265,12 +340,19 @@ This playbook provides task execution guidance for AI Agents.
   pbCmd
     .command("show <id>")
     .description("Show playbook content and metadata (from current project or linked packages)")
+    .option("-P, --package <id>", "Target package ID or path")
     .option("-p, --profile <name>", "Query against a specific profile")
     .option("-s, --server <url>", "Remote server URL")
     .option("-t, --token <token>", "Auth token for remote server")
     .option("--json", "Output as JSON")
-    .action(async (id, options) => {
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (id, rawOptions, cmd) => {
       try {
+        const options = getEffectiveOptions(rawOptions, cmd);
+        if (!id) {
+          throw new ArgumentError("Playbook ID is required for show");
+        }
+
         const target = resolveTarget({
           profile: options.profile,
           server: options.server,
@@ -279,39 +361,64 @@ This playbook provides task execution guidance for AI Agents.
 
         if (target.type === "remote") {
           const pb = await fetchRemotePlaybookShow(target.serverUrl!, id, target.token);
-          if (options.json) {
-            console.log(JSON.stringify(pb, null, 2));
-            return;
-          }
-          console.log(`Playbook:    ${pb.id} (Package: ${pb.packageId})`);
-          if (pb.description) console.log(`Description: ${pb.description}`);
-          if (pb.actions && pb.actions.length > 0) {
-            console.log(`Actions:     ${pb.actions.join(", ")}`);
-          }
-          if (pb.filePath) console.log(`File:        ${pb.filePath}\n`);
-          console.log("--- Content ---");
-          console.log(pb.content);
+          renderResult(pb, {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+              const lines = [`Playbook:    ${pb.id} (Package: ${pb.packageId})`];
+              if (pb.description) lines.push(`Description: ${pb.description}`);
+              if (pb.actions && pb.actions.length > 0) {
+                lines.push(`Actions:     ${pb.actions.join(", ")}`);
+              }
+              if (pb.filePath) lines.push(`File:        ${pb.filePath}\n`);
+              lines.push("--- Content ---", pb.content);
+              return lines.join("\n");
+            },
+          });
           return;
         }
 
-        const resolved = resolvePlaybookProject(id);
-        const pb = resolved.playbook;
+        let showTarget = id;
+        if (options.package && !id.includes("/") && !id.includes(":")) {
+          const pkgRoot = resolvePackageRoot(options.package);
+          if (!pkgRoot) {
+            throw new ArgumentError(
+              `Package '${options.package}' not found in linked packages or path`
+            );
+          }
+          showTarget = `${options.package}/${id}`;
+        }
 
-        if (options.json) {
-          console.log(JSON.stringify({ ...pb, packageId: resolved.packageId }, null, 2));
-        } else {
-          console.log(`Playbook:    ${pb.id} (Package: ${resolved.packageId})`);
-          if (pb.description) console.log(`Description: ${pb.description}`);
-          if (pb.actions && pb.actions.length > 0) {
-            console.log(`Actions:     ${pb.actions.join(", ")}`);
+        let resolved;
+        try {
+          resolved = resolvePlaybookProject(showTarget);
+        } catch (err: any) {
+          if (err.message?.includes("not found") || err.message?.includes("no longer exists")) {
+            throw new ArgumentError(err.message);
           }
-          console.log(`File:        ${pb.filePath}\n`);
-          console.log("--- Content ---");
-          console.log(pb.content);
+          throw new ExecutionError(err.message);
         }
+
+        const pb = resolved.playbook;
+        const payload = { ...pb, packageId: resolved.packageId };
+
+        renderResult(payload, {
+          json: options.json,
+          envelope: options.envelope,
+          humanFormatter: () => {
+            const lines = [`Playbook:    ${pb.id} (Package: ${resolved.packageId})`];
+            if (pb.description) lines.push(`Description: ${pb.description}`);
+            if (pb.actions && pb.actions.length > 0) {
+              lines.push(`Actions:     ${pb.actions.join(", ")}`);
+            }
+            if (pb.filePath) lines.push(`File:        ${pb.filePath}\n`);
+            lines.push("--- Content ---", pb.content);
+            return lines.join("\n");
+          },
+        });
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof CliError) throw err;
+        throw new ExecutionError(err.message);
       }
     });
 
@@ -319,10 +426,24 @@ This playbook provides task execution guidance for AI Agents.
   pbCmd
     .command("validate [id]")
     .description("Validate playbook format and action references (in current project or linked packages)")
+    .option("-P, --package <id>", "Target package ID or path")
     .option("--json", "Output as JSON")
-    .action(async (id, options) => {
+    .option("--envelope", "Wrap JSON output in standard envelope")
+    .action(async (id, rawOptions, cmd) => {
       try {
-        const root = findProjectRoot();
+        const options = getEffectiveOptions(rawOptions, cmd);
+        let root: string | null = 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();
+        }
+
         const targets: Array<{ root: string; packageId: string; playbooks: PlaybookDefinition[] }> = [];
 
         if (root) {
@@ -331,8 +452,7 @@ This playbook provides task execution guidance for AI Agents.
           if (id) {
             const pb = playbooks.get(id);
             if (!pb) {
-              console.error(`Error: Playbook '${id}' not found in current project`);
-              process.exit(1);
+              throw new ArgumentError(`Playbook '${id}' not found in package '${config.id}'`);
             }
             targets.push({ root, packageId: config.id, playbooks: [pb] });
           } else {
@@ -349,8 +469,7 @@ This playbook provides task execution guidance for AI Agents.
           // Outside project: validate all linked packages
           const linkedList = listLinkedPackages();
           if (linkedList.length === 0) {
-            console.error("Error: Not in an ActionDock project, and no packages linked.");
-            process.exit(1);
+            throw new ArgumentError("Not in an ActionDock project, and no packages linked.");
           }
           for (const pkg of linkedList) {
             if (!existsSync(pkg.path)) continue;
@@ -415,23 +534,32 @@ This playbook provides task execution guidance for AI Agents.
         }
 
         const allValid = results.every((r) => r.valid);
-        if (options.json) {
-          console.log(JSON.stringify({ valid: allValid, results }, null, 2));
-        } else {
-          for (const r of results) {
-            const prefix = targets.length > 1 || !root ? `[${r.packageId}] ` : "";
-            if (r.valid) {
-              const warn = r.warnings.length > 0 ? ` (Warnings: ${r.warnings.join("; ")})` : "";
-              console.log(`[OK] ${prefix}${r.id}: Valid${warn}`);
-            } else {
-              console.log(`[FAIL] ${prefix}${r.id}: ${r.errors.join("; ")}`);
-            }
+        renderResult(
+          { valid: allValid, results },
+          {
+            json: options.json,
+            envelope: options.envelope,
+            humanFormatter: () => {
+              const lines: string[] = [];
+              for (const r of results) {
+                const prefix = targets.length > 1 || !root ? `[${r.packageId}] ` : "";
+                if (r.valid) {
+                  const warn = r.warnings.length > 0 ? ` (Warnings: ${r.warnings.join("; ")})` : "";
+                  lines.push(`[OK] ${prefix}${r.id}: Valid${warn}`);
+                } else {
+                  lines.push(`[FAIL] ${prefix}${r.id}: ${r.errors.join("; ")}`);
+                }
+              }
+              return lines.join("\n");
+            },
           }
-        }
-        if (!allValid) process.exit(1);
+        );
+        if (!allValid) process.exitCode = 1;
       } catch (err: any) {
-        console.error(`Error: ${err.message}`);
-        process.exit(1);
+        if (err instanceof ArgumentError || err instanceof CliError) {
+          throw err;
+        }
+        throw new ExecutionError(err.message);
       }
     });
 }