@actiondock/cli 2.0.0

package/src/commands/mcp.ts

@@ -0,0 +1,199 @@
+import { resolve } from "node:path";
+import { findProjectRoot, loadProjectConfig } from "@actiondock/core";
+import { startMcpHttpServer, startMcpStdio } from "@actiondock/mcp";
+import { Command } from "commander";
+import { parseByteSize } from "../utils/bytes";
+import { parseDuration } from "../utils/duration";
+
+function parseListOption(val: string, prev: string[] = []): string[] {
+  const parts = val.split(",").map((s) => s.trim()).filter(Boolean);
+  return [...prev, ...parts];
+}
+
+export function registerMcpCommands(program: Command): void {
+  const mcpCommand = program
+    .command("mcp")
+    .description("Model Context Protocol (MCP) server for ActionDock Actions (STDIO default)")
+    .option(
+      "-d, --dir <path>",
+      "Project root directory or directories (can be specified multiple times or comma-separated)",
+      parseListOption,
+      []
+    )
+    .option(
+      "--package <package-id>",
+      "Specific linked package ID(s) to serve (can be specified multiple times or comma-separated)",
+      parseListOption,
+      []
+    )
+    .option("--all", "Serve all linked packages from global registry")
+    .option("--timeout <duration>", "Execution timeout (e.g. 30s, 5m, 500ms)")
+    .action(async (options) => {
+      // Default: stdio mode
+      let timeoutMs: number | undefined;
+      if (options.timeout) {
+        try {
+          timeoutMs = parseDuration(options.timeout);
+        } catch (err: any) {
+          process.stderr.write(`Error: ${err.message}\n`);
+          process.exit(1);
+        }
+      }
+
+      const projectRoots =
+        options.dir && options.dir.length > 0
+          ? options.dir.map((d: string) => resolve(d))
+          : undefined;
+      const packageIds =
+        options.package && options.package.length > 0 ? options.package : undefined;
+      const all = Boolean(options.all);
+
+      try {
+        await startMcpStdio({
+          projectRoots,
+          packageIds,
+          all,
+          timeoutMs,
+        });
+      } catch (err: any) {
+        process.stderr.write(`Failed to start MCP STDIO server: ${err.message}\n`);
+        process.exit(1);
+      }
+    });
+
+  mcpCommand
+    .command("serve")
+    .description("Start the ActionDock MCP server over HTTP transport")
+    .option("-p, --port <port>", "Port to listen on (default: 5178)", "5178")
+    .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("--token-env <env>", "Environment variable name containing the authentication 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: string, prev: string[] = []) => [...prev, val],
+      []
+    )
+    .option("--max-body <size>", "Maximum allowed JSON request body size (e.g. 1mb, 500kb)", "1mb")
+    .option(
+      "-d, --dir <path>",
+      "Project root directory or directories (can be specified multiple times or comma-separated)",
+      parseListOption,
+      []
+    )
+    .option(
+      "--package <package-id>",
+      "Specific linked package ID(s) to serve (can be specified multiple times or comma-separated)",
+      parseListOption,
+      []
+    )
+    .option("--all", "Serve all linked packages from global registry")
+    .option("--timeout <duration>", "Execution timeout (e.g. 30s, 5m, 500ms)")
+    .action(async (options) => {
+      const port = parseInt(options.port, 10) || 5178;
+      const host = options.host || "127.0.0.1";
+      const token =
+        options.token ||
+        (options.tokenEnv ? process.env[options.tokenEnv] : undefined) ||
+        process.env.ACTIONDOCK_TOKEN;
+      const allowInsecureNoAuth = Boolean(options.allowInsecureNoAuth);
+      const corsOrigins =
+        options.corsOrigin && options.corsOrigin.length > 0 ? options.corsOrigin : undefined;
+
+      let maxBodyBytes: number | undefined;
+      if (options.maxBody) {
+        try {
+          maxBodyBytes = parseByteSize(options.maxBody);
+        } catch (err: any) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+      }
+
+      let timeoutMs: number | undefined;
+      if (options.timeout) {
+        try {
+          timeoutMs = parseDuration(options.timeout);
+        } catch (err: any) {
+          console.error(`Error: ${err.message}`);
+          process.exit(1);
+        }
+      }
+
+      const projectRoots =
+        options.dir && options.dir.length > 0
+          ? options.dir.map((d: string) => resolve(d))
+          : undefined;
+      const packageIds =
+        options.package && options.package.length > 0 ? options.package : undefined;
+      const all = Boolean(options.all);
+
+      let targetDescription = "ActionDock MCP Server";
+      if (all) {
+        targetDescription = "All Linked Packages (Global Registry Mode)";
+      } else if (packageIds && packageIds.length > 1) {
+        targetDescription = `Packages: ${packageIds.join(", ")}`;
+      } else if (projectRoots && projectRoots.length > 1) {
+        targetDescription = `Directories: ${projectRoots.join(", ")}`;
+      } else if (projectRoots && projectRoots.length === 1) {
+        try {
+          const config = loadProjectConfig(projectRoots[0]);
+          targetDescription = `${config.name} (${config.id})`;
+        } catch {
+          targetDescription = projectRoots[0];
+        }
+      } else if (packageIds && packageIds.length === 1) {
+        targetDescription = `Package: ${packageIds[0]}`;
+      } else {
+        const currentRoot = findProjectRoot(process.cwd());
+        if (currentRoot) {
+          try {
+            const config = loadProjectConfig(currentRoot);
+            targetDescription = `${config.name} (${config.id})`;
+          } catch {
+            targetDescription = currentRoot;
+          }
+        }
+      }
+
+      try {
+        const server = startMcpHttpServer({
+          port,
+          host,
+          token,
+          allowInsecureNoAuth,
+          corsOrigins,
+          maxBodyBytes,
+          projectRoots,
+          packageIds,
+          all,
+          timeoutMs,
+        });
+
+        console.log(`\n======================================================`);
+        console.log(`  ActionDock 2.0 MCP HTTP Server`);
+        console.log(`======================================================`);
+        console.log(`  * Listening on:    http://${host}:${server.port}`);
+        console.log(`  * MCP Endpoint:    http://${host === "0.0.0.0" ? "127.0.0.1" : host}:${server.port}/mcp`);
+        console.log(`  * Target:          ${targetDescription}`);
+        console.log(`  * Authentication:  ${token ? "Bearer Token Enabled" : "Disabled (Local)"}`);
+        console.log(`  * CORS Origins:    ${corsOrigins ? corsOrigins.join(", ") : "Disabled (Default)"}`);
+        console.log(`======================================================\n`);
+        console.log(`Press Ctrl+C to terminate.\n`);
+
+        process.on("SIGINT", () => {
+          console.log("\nStopping MCP HTTP server...");
+          server.stop();
+          process.exit(0);
+        });
+        process.on("SIGTERM", () => {
+          server.stop();
+          process.exit(0);
+        });
+      } catch (err: any) {
+        console.error(`Failed to start ActionDock MCP HTTP server: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}

package/src/commands/playbook.ts

@@ -0,0 +1,359 @@
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import {
+  filterWithFallbackInfo,
+  findProjectRoot,
+  listLinkedPackages,
+  loadActions,
+  loadPlaybooks,
+  loadProjectConfig,
+  resolvePlaybookProject,
+} from "@actiondock/core";
+import type { PlaybookDefinition } from "@actiondock/core";
+import { Command } from "commander";
+import { resolveIntent } from "../utils/filter";
+
+export function registerPlaybookCommands(program: Command): void {
+  const pbCmd = program
+    .command("playbook")
+    .description("Manage task Playbooks (Task SOPs for AI Agents)");
+
+  // playbook list
+  pbCmd
+    .command("list [patterns...]")
+    .description("List playbooks in current project or linked packages")
+    .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("--json", "Output as JSON")
+    .action((patterns, options) => {
+      try {
+        const effectiveIntent = resolveIntent(options.intent, patterns);
+        const shouldFallback = options.fallback !== false;
+
+        const root = findProjectRoot();
+        if (root) {
+          const config = loadProjectConfig(root);
+          const playbooks = loadPlaybooks(root, config.playbooksDir);
+          const rawList = Array.from(playbooks.values()).map((p) => ({
+            id: p.id,
+            description: p.description || "",
+            actions: p.actions || [],
+            file: p.filePath,
+            packageId: config.id,
+          }));
+
+          const filterRes = filterWithFallbackInfo(
+            rawList,
+            effectiveIntent,
+            [(p) => p.id, (p) => p.description, (p) => p.actions, (p) => p.file],
+            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 'ac link' inside an Action package to register it.");
+            return;
+          }
+
+          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],
+                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.id, (p) => p.description, (p) => p.actions, (p) => p.file],
+                  false
+                ).items;
+
+                if (matchedPlaybooks.length > 0) {
+                  filteredPackages.push({
+                    ...pkg,
+                    playbooks: matchedPlaybooks,
+                  });
+                }
+              }
+            }
+
+            if (filteredPackages.length === 0 && shouldFallback) {
+              filteredPackages = aggregated;
+            }
+          }
+
+          if (options.json) {
+            console.log(JSON.stringify(filteredPackages, null, 2));
+          } else {
+            console.log("Playbooks in Linked Packages:\n");
+            for (const pkg of filteredPackages) {
+              console.log(`* Package: ${pkg.packageId} (${pkg.path})`);
+              if (pkg.playbooks.length === 0) {
+                console.log("    (No playbooks)");
+              } else {
+                for (const p of pkg.playbooks) {
+                  console.log(`    - ${p.id.padEnd(26)} ${p.description}`);
+                }
+              }
+            }
+          }
+        }
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // playbook create / new
+  pbCmd
+    .command("create <id>")
+    .alias("new")
+    .description("Scaffold a new Playbook markdown file")
+    .option("-d, --desc <description>", "Playbook description")
+    .option("-a, --actions <actions...>", "Referenced action IDs")
+    .option("-f, --file <filePath>", "Target file path relative to playbooks dir")
+    .action((id, options) => {
+      const root = findProjectRoot();
+      if (!root) {
+        console.error("Error: Not in an ActionDock project (actiondock.json not found)");
+        process.exit(1);
+      }
+      try {
+        const config = loadProjectConfig(root);
+        const pbDir = resolve(root, config.playbooksDir || "playbooks");
+        if (!existsSync(pbDir)) {
+          mkdirSync(pbDir, { recursive: true });
+        }
+
+        const cleanName = id.replace(/[^a-zA-Z0-9-_]/g, "-");
+        const targetRelFile = options.file || `${cleanName}.md`;
+        const targetFullFile = resolve(pbDir, targetRelFile);
+
+        if (existsSync(targetFullFile)) {
+          console.error(`Error: File '${targetFullFile}' already exists`);
+          process.exit(1);
+        }
+
+        mkdirSync(dirname(targetFullFile), { recursive: true });
+
+        const desc = options.desc || `SOP guide for ${id}`;
+        const actionsList = Array.isArray(options.actions) ? options.actions : [];
+        const actionsYaml =
+          actionsList.length > 0
+            ? `actions:\n${actionsList.map((a: string) => `  - ${a}`).join("\n")}\n`
+            : "actions: []\n";
+
+        const template = `---
+id: ${id}
+description: ${desc}
+${actionsYaml}---
+
+# ${id.replace(/[-_]/g, " ").replace(/\b\w/g, (c: string) => c.toUpperCase())} SOP
+
+This playbook provides task execution guidance for AI Agents.
+
+## Instructions
+
+1. Inspect available actions with \`<binary> list --json\`.
+2. Follow the required steps to complete the task.
+`;
+
+        writeFileSync(targetFullFile, template, "utf-8");
+        console.log(`[OK] Created Playbook '${id}' at ${targetFullFile}`);
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // playbook show
+  pbCmd
+    .command("show <id>")
+    .description("Show playbook content and metadata (from current project or linked packages)")
+    .option("--json", "Output as JSON")
+    .action((id, options) => {
+      try {
+        const resolved = resolvePlaybookProject(id);
+        const pb = resolved.playbook;
+
+        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(", ")}`);
+          }
+          console.log(`File:        ${pb.filePath}\n`);
+          console.log("--- Content ---");
+          console.log(pb.content);
+        }
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+
+  // playbook validate
+  pbCmd
+    .command("validate [id]")
+    .description("Validate playbook format and action references (in current project or linked packages)")
+    .option("--json", "Output as JSON")
+    .action(async (id, options) => {
+      try {
+        const root = findProjectRoot();
+        const targets: Array<{ root: string; packageId: string; playbooks: PlaybookDefinition[] }> = [];
+
+        if (root) {
+          const config = loadProjectConfig(root);
+          const playbooks = loadPlaybooks(root, config.playbooksDir);
+          if (id) {
+            const pb = playbooks.get(id);
+            if (!pb) {
+              console.error(`Error: Playbook '${id}' not found in current project`);
+              process.exit(1);
+            }
+            targets.push({ root, packageId: config.id, playbooks: [pb] });
+          } else {
+            targets.push({ root, packageId: config.id, playbooks: Array.from(playbooks.values()) });
+          }
+        } else if (id) {
+          const resolved = resolvePlaybookProject(id);
+          targets.push({
+            root: resolved.projectRoot,
+            packageId: resolved.packageId,
+            playbooks: [resolved.playbook],
+          });
+        } else {
+          // 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);
+          }
+          for (const pkg of linkedList) {
+            if (!existsSync(pkg.path)) continue;
+            try {
+              const config = loadProjectConfig(pkg.path);
+              const playbooks = loadPlaybooks(pkg.path, config.playbooksDir);
+              targets.push({
+                root: pkg.path,
+                packageId: pkg.id,
+                playbooks: Array.from(playbooks.values()),
+              });
+            } catch {}
+          }
+        }
+
+        const results: Array<{ id: string; packageId: string; valid: boolean; warnings: string[]; errors: string[] }> = [];
+
+        for (const target of targets) {
+          const config = loadProjectConfig(target.root);
+          const actions = await loadActions(target.root, config.actionsDir);
+
+          for (const pb of target.playbooks) {
+            if (!pb) continue;
+            const errors: string[] = [];
+            const warnings: string[] = [];
+
+            if (!pb.id) errors.push("Missing playbook id");
+            if (!pb.content) warnings.push("Playbook content is empty");
+
+            if (pb.actions) {
+              for (const actId of pb.actions) {
+                if (!actions.has(actId)) {
+                  warnings.push(`Referenced action '${actId}' not found in package '${target.packageId}'`);
+                }
+              }
+            }
+
+            results.push({
+              id: pb.id,
+              packageId: target.packageId,
+              valid: errors.length === 0,
+              warnings,
+              errors,
+            });
+          }
+        }
+
+        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("; ")}`);
+            }
+          }
+        }
+        if (!allValid) process.exit(1);
+      } catch (err: any) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+      }
+    });
+}
+