clawmatrix 0.2.11 → 0.3.1

package/src/cli.ts

@@ -46,13 +46,30 @@ async function callGateway(method: string, params?: Record<string, unknown>): Pr
   return JSON.parse(stdout);
 }
 
+// ── Style helpers (TTY-aware: strip ANSI when output goes to LLM/pipe) ──
+
+const isTTY = process.stdout.isTTY === true;
+const ansi = (code: string, reset: string) =>
+  isTTY ? (s: string) => `\x1b[${code}m${s}\x1b[${reset}m` : (s: string) => s;
+
+const bold   = ansi("1", "22");
+const dim    = ansi("2", "22");
+const green  = ansi("32", "39");
+const red    = ansi("31", "39");
+const cyan   = ansi("36", "39");
+const yellow = ansi("33", "39");
+
+/** TTY-aware JSON output: pretty for humans, compact for LLM callers. */
+const jsonOut = (data: unknown) => JSON.stringify(data, null, isTTY ? 2 : 0);
+
 export const registerClusterCli = ({ program }: { program: Command }) => {
   const cmd = program.command("clawmatrix").description("ClawMatrix cluster management");
 
   cmd
     .command("status")
     .description("Show cluster topology and peer status")
-    .action(async () => {
+    .option("--json", "Output raw JSON (structured, machine-readable)")
+    .action(async (opts: { json?: boolean }) => {
       let data: Record<string, unknown>;
       try {
         data = (await callGateway("clawmatrix.status")) as Record<string, unknown>;
@@ -66,13 +83,12 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
         return;
       }
 
-      // Style helpers
-      const bold = (s: string) => `\x1b[1m${s}\x1b[22m`;
-      const dim = (s: string) => `\x1b[2m${s}\x1b[22m`;
-      const green = (s: string) => `\x1b[32m${s}\x1b[39m`;
-      const red = (s: string) => `\x1b[31m${s}\x1b[39m`;
-      const cyan = (s: string) => `\x1b[36m${s}\x1b[39m`;
-      const yellow = (s: string) => `\x1b[33m${s}\x1b[39m`;
+      // --json: raw structured output for programmatic consumption
+      if (opts.json) {
+        console.log(jsonOut(data));
+        return;
+      }
+
       const bar = dim("│");
       const lbl = (text: string) => dim(text.padEnd(13));
 
@@ -168,7 +184,459 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
         console.log("[]");
         return;
       }
-      console.log(JSON.stringify(peers, null, 2));
+      console.log(jsonOut(peers));
+    });
+
+  cmd
+    .command("check <nodeId>")
+    .description("Check if a specific node is reachable (minimal JSON output)")
+    .action(async (nodeId: string) => {
+      try {
+        const peers = (await callGateway("clawmatrix.peers")) as Array<{
+          nodeId: string;
+          connected: boolean;
+          status: string;
+          latencyMs: number;
+          agents?: Array<{ id: string }>;
+          models?: Array<{ id: string }>;
+          toolProxy?: { enabled: boolean };
+        }>;
+        const peer = peers.find((p) => p.nodeId === nodeId);
+        if (!peer) {
+          console.log(jsonOut({ nodeId, reachable: false, status: "unknown", error: "Node not found in peer list" }));
+          process.exitCode = 1;
+          return;
+        }
+        console.log(jsonOut({
+          nodeId: peer.nodeId,
+          reachable: peer.connected,
+          status: peer.status,
+          latencyMs: peer.latencyMs,
+          agents: peer.agents?.length ?? 0,
+          models: peer.models?.length ?? 0,
+          toolProxy: peer.toolProxy?.enabled ?? false,
+        }));
+        if (!peer.connected) process.exitCode = 1;
+      } catch {
+        console.log(jsonOut({ nodeId, reachable: false, status: "error", error: "Could not reach gateway" }));
+        process.exitCode = 1;
+      }
+    });
+
+  // ── Tool proxy commands ────────────────────────────────────────
+  //
+  // Design: model-facing CLI (optimized for LLM consumption)
+  //
+  // 1. Non-TTY auto-compact: When called from Claude Code / Codex (non-TTY),
+  //    output is plain text without ANSI colors, brief by default.
+  // 2. Progressive disclosure: `tools` lists names → `tools --describe <name>`
+  //    gives full usage for a single tool. LLMs should query incrementally.
+  // 3. Structured output: JSON for programmatic use, compact text for LLMs.
+
+  type ToolListEntry = {
+    nodeId: string;
+    status: string;
+    toolProxy: {
+      enabled: boolean;
+      allow: string[];
+      deny: string[];
+      catalog?: Array<{ name: string; description: string; usage?: string; inputSchema?: Record<string, unknown> }>;
+    };
+  };
+
+  async function fetchToolList(node?: string): Promise<ToolListEntry[]> {
+    return (await callGateway("clawmatrix.tools.list", node ? { node } : undefined)) as ToolListEntry[];
+  }
+
+  cmd
+    .command("tools [node]")
+    .description("List available tools on remote nodes (compact by default for LLM callers)")
+    .option("--json", "Output raw JSON")
+    .option("-v, --verbose", "Show full usage/params for every tool (caution: large output)")
+    .option("-f, --filter <keyword>", "Filter tools by keyword (matches name, description, usage)")
+    .option("-d, --describe <tool>", "Show detailed usage for a single tool")
+    .action(async (node: string | undefined, opts: { json?: boolean; verbose?: boolean; filter?: string; describe?: string }) => {
+      try {
+        const data = await fetchToolList(node);
+
+        // --json: raw structured output
+        if (opts.json) {
+          console.log(jsonOut(data));
+          return;
+        }
+
+        if (data.length === 0) {
+          console.log("No nodes with tool proxy enabled.");
+          return;
+        }
+
+        // --describe <tool>: show full detail for one tool then exit
+        if (opts.describe) {
+          const toolName = opts.describe.toLowerCase();
+          for (const entry of data) {
+            const catalog = entry.toolProxy.catalog ?? [];
+            const found = catalog.find((t) => t.name.toLowerCase() === toolName);
+            if (found) {
+              console.log(`node: ${entry.nodeId}`);
+              console.log(`tool: ${found.name}`);
+              console.log(`description: ${found.description}`);
+              if (found.inputSchema) {
+                console.log(`params: ${JSON.stringify(found.inputSchema)}`);
+              }
+              if (found.usage) {
+                console.log(`usage:\n${found.usage}`);
+              }
+              console.log(`\ninvoke: clawmatrix call ${entry.nodeId} ${found.name} '{}'`);
+              return;
+            }
+          }
+          console.error(`Tool "${opts.describe}" not found. Run 'clawmatrix tools' to see available tools.`);
+          process.exitCode = 1;
+          return;
+        }
+
+        const filterLower = opts.filter?.toLowerCase();
+        const matchesFilter = (t: { name: string; description: string; usage?: string }) =>
+          !filterLower ||
+          t.name.toLowerCase().includes(filterLower) ||
+          t.description.toLowerCase().includes(filterLower) ||
+          (t.usage ?? "").toLowerCase().includes(filterLower);
+
+        const bar = dim("│");
+
+        console.log();
+        for (const entry of data) {
+          const tools = entry.toolProxy.allow;
+          const catalog = entry.toolProxy.catalog ?? [];
+          const catalogMap = new Map(catalog.map((t) => [t.name, t]));
+          const denied = entry.toolProxy.deny;
+          const isWildcard = tools.includes("*");
+
+          const toolsToShow = isWildcard
+            ? catalog.filter(matchesFilter)
+            : tools
+                .map((name) => catalogMap.get(name) ?? { name, description: "", usage: "" })
+                .filter(matchesFilter);
+
+          const totalCount = isWildcard ? catalog.length : tools.length;
+          const shownCount = toolsToShow.length;
+          const countLabel = filterLower
+            ? `${shownCount}/${totalCount} matched`
+            : `${totalCount} tools`;
+
+          console.log(`  ${cyan("◆")}  ${bold(entry.nodeId)}  ${green(entry.status)}  ${dim(countLabel)}`);
+          console.log(`  ${bar}`);
+
+          if (toolsToShow.length === 0 && !filterLower) {
+            if (isWildcard) {
+              console.log(`  ${bar}  ${green("*")} ${dim("(all tools allowed)")}`);
+            } else {
+              console.log(`  ${bar}  ${dim("No tools advertised")}`);
+            }
+          } else if (toolsToShow.length === 0) {
+            console.log(`  ${bar}  ${dim(`No tools matching "${opts.filter}"`)}`);
+          } else if (opts.verbose) {
+            // Verbose: full name + description + usage (opt-in, large output)
+            for (const tool of toolsToShow) {
+              console.log(`  ${bar}  ${green("●")} ${bold(tool.name)}`);
+              if (tool.description) {
+                console.log(`  ${bar}    ${dim(tool.description)}`);
+              }
+              if (tool.usage) {
+                for (const line of tool.usage.split("\n")) {
+                  console.log(`  ${bar}    ${line}`);
+                }
+              }
+            }
+          } else {
+            // Default: compact — name + one-line description (LLM-friendly)
+            const maxNameLen = Math.max(...toolsToShow.map((t) => t.name.length));
+            for (const tool of toolsToShow) {
+              const padded = tool.name.padEnd(maxNameLen);
+              const desc = tool.description ? `  ${dim(tool.description)}` : "";
+              console.log(`  ${bar}  ${green("●")} ${padded}${desc}`);
+            }
+
+            // Hint for LLMs: how to get more detail
+            if (!isTTY && toolsToShow.length > 5) {
+              console.log(`  ${bar}`);
+              console.log(`  ${bar}  ${dim("Tip: use --describe <tool> for full usage of a specific tool")}`);
+            }
+          }
+
+          if (denied.length > 0) {
+            console.log(`  ${bar}  ${dim("Denied:")} ${denied.join(", ")}`);
+          }
+          console.log();
+        }
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
+
+  cmd
+    .command("call <node> <tool> [params]")
+    .description("Invoke a tool on a remote node")
+    .option("-t, --timeout <ms>", "Timeout in milliseconds")
+    .action(async (node: string, tool: string, paramsStr: string | undefined, opts: { timeout?: string }) => {
+      try {
+        let toolParams: Record<string, unknown> = {};
+        if (paramsStr) {
+          try {
+            toolParams = JSON.parse(paramsStr);
+          } catch {
+            console.error(`Error: Invalid JSON params: ${paramsStr}`);
+            console.error('Expected JSON object, e.g. \'{"days": 7}\'');
+            process.exitCode = 1;
+            return;
+          }
+        }
+
+        const timeout = opts.timeout ? parseInt(opts.timeout, 10) : undefined;
+        if (timeout !== undefined && isNaN(timeout)) {
+          console.error("Error: --timeout must be a number");
+          process.exitCode = 1;
+          return;
+        }
+
+        const result = await callGateway("clawmatrix.tools.call", {
+          node,
+          tool,
+          params: toolParams,
+          ...(timeout !== undefined && { timeout }),
+        });
+
+        // Compact JSON for LLM callers (non-TTY), pretty for humans
+        console.log(jsonOut(result));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        // Provide actionable hints for common errors
+        if (msg.includes("not reachable")) {
+          console.error(`Error: Node "${node}" is not reachable. Run 'clawmatrix status' to check connectivity.`);
+        } else if (msg.includes("not allowed")) {
+          console.error(`Error: Tool "${tool}" is not allowed on node "${node}". Run 'clawmatrix tools ${node}' to see available tools.`);
+        } else if (msg.includes("timed out")) {
+          console.error(`Error: Tool "${tool}" timed out on node "${node}". Try increasing timeout with -t <ms>.`);
+        } else {
+          console.error(`Error: ${msg}`);
+        }
+        process.exitCode = 1;
+      }
+    });
+
+  cmd
+    .command("batch <node> [items]")
+    .description("Invoke multiple tools on a remote node in sequence (pass JSON array or pipe via stdin)")
+    .option("--no-stop-on-error", "Continue on error")
+    .option("-t, --timeout <ms>", "Timeout in milliseconds")
+    .action(async (node: string, itemsStr: string | undefined, opts: { stopOnError?: boolean; timeout?: string }) => {
+      try {
+        let jsonStr = itemsStr;
+
+        // Read from stdin if no argument provided and stdin is piped
+        if (!jsonStr && !process.stdin.isTTY) {
+          const chunks: Buffer[] = [];
+          for await (const chunk of process.stdin) {
+            chunks.push(Buffer.from(chunk));
+          }
+          jsonStr = Buffer.concat(chunks).toString("utf-8").trim();
+        }
+
+        if (!jsonStr) {
+          console.error('Error: No items provided. Pass JSON array as argument or pipe via stdin.');
+          console.error('Example: clawmatrix batch iphone \'[{"tool":"get_location"},{"tool":"battery"}]\'');
+          process.exitCode = 1;
+          return;
+        }
+
+        const items = JSON.parse(jsonStr) as Array<{ tool: string; params?: Record<string, unknown> }>;
+        const timeout = opts.timeout ? parseInt(opts.timeout, 10) : undefined;
+        if (timeout !== undefined && isNaN(timeout)) {
+          console.error("Error: --timeout must be a number");
+          process.exitCode = 1;
+          return;
+        }
+
+        const results = await callGateway("clawmatrix.tools.batch", {
+          node,
+          items,
+          stopOnError: opts.stopOnError !== false,
+          ...(timeout !== undefined && { timeout }),
+        });
+
+        console.log(jsonOut(results));
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        console.error(`Error: ${msg}`);
+        process.exitCode = 1;
+      }
+    });
+
+  // ── Models command ──────────────────────────────────────────────
+
+  cmd
+    .command("models")
+    .description("List all models available across the cluster")
+    .option("--json", "Output raw JSON")
+    .option("-n, --node <nodeId>", "Filter by node ID")
+    .action(async (opts: { json?: boolean; node?: string }) => {
+      try {
+        const data = (await callGateway("clawmatrix.models.list", opts.node ? { node: opts.node } : undefined)) as Array<{
+          id: string;
+          nodeId: string;
+          provider: string;
+          description?: string;
+          contextWindow?: number;
+          maxTokens?: number;
+          reasoning?: boolean;
+          input?: string[];
+          reachable: boolean;
+        }>;
+
+        if (opts.json) {
+          console.log(jsonOut(data));
+          return;
+        }
+
+        if (data.length === 0) {
+          console.log("No models available in the cluster.");
+          return;
+        }
+
+        const bar = dim("│");
+
+        // Group by nodeId
+        const byNode = new Map<string, typeof data>();
+        for (const m of data) {
+          const arr = byNode.get(m.nodeId) ?? [];
+          arr.push(m);
+          byNode.set(m.nodeId, arr);
+        }
+
+        console.log();
+        for (const [nodeId, models] of byNode) {
+          const reachable = models[0]?.reachable !== false;
+          const statusLabel = reachable ? green("reachable") : red("unreachable");
+          console.log(`  ${cyan("◆")}  ${bold(nodeId)}  ${statusLabel}  ${dim(`${models.length} models`)}`);
+          console.log(`  ${bar}`);
+
+          const maxIdLen = Math.max(...models.map((m) => m.id.length));
+          for (const m of models) {
+            const padded = m.id.padEnd(maxIdLen);
+            const details: string[] = [];
+            if (m.contextWindow) details.push(`${Math.round(m.contextWindow / 1000)}k ctx`);
+            if (m.reasoning) details.push("reasoning");
+            if (m.input && m.input.includes("image")) details.push("vision");
+            const detailStr = details.length > 0 ? `  ${dim(details.join(", "))}` : "";
+            console.log(`  ${bar}  ${green("●")} ${padded}${detailStr}`);
+          }
+          console.log();
+        }
+      } catch {
+        console.log("Could not reach gateway. Is it running?");
+      }
+    });
+
+  // ── Events command ─────────────────────────────────────────────
+
+  cmd
+    .command("events")
+    .description("Query and consume ingested events (messages, calls, location changes)")
+    .option("--json", "Output raw JSON")
+    .option("-t, --type <type>", "Filter by event type (e.g. message_received)")
+    .option("-s, --source <source>", "Filter by source (e.g. shortcuts)")
+    .option("-l, --limit <n>", "Max events to return (default: 20)")
+    .option("-a, --all", "Include already-consumed events")
+    .option("--consume <ids>", "Consume events by ID (comma-separated)")
+    .action(async (opts: { json?: boolean; type?: string; source?: string; limit?: string; all?: boolean; consume?: string }) => {
+      try {
+        if (opts.consume) {
+          const ids = opts.consume.split(",").map((s) => s.trim()).filter(Boolean);
+          const result = await callGateway("clawmatrix.events.consume", { ids });
+          console.log(jsonOut(result));
+          return;
+        }
+
+        const params: Record<string, unknown> = {};
+        if (opts.type) params.type = opts.type;
+        if (opts.source) params.source = opts.source;
+        if (opts.limit) {
+          const limit = parseInt(opts.limit, 10);
+          if (isNaN(limit)) {
+            console.error("Error: --limit must be a number");
+            process.exitCode = 1;
+            return;
+          }
+          params.limit = limit;
+        }
+        if (opts.all) params.unconsumed = false;
+
+        const events = (await callGateway("clawmatrix.events.query", params)) as Array<{
+          id: string;
+          type: string;
+          source: string;
+          ts: number;
+          consumed: boolean;
+          data: Record<string, unknown>;
+        }>;
+
+        if (opts.json) {
+          console.log(jsonOut(events));
+          return;
+        }
+
+        if (events.length === 0) {
+          console.log("No events found.");
+          return;
+        }
+
+        const bar = dim("│");
+        console.log();
+        console.log(`  ${cyan("◆")}  ${bold("Events")}  ${dim(`${events.length} result(s)`)}`);
+        console.log(`  ${bar}`);
+
+        for (const evt of events) {
+          const age = Math.floor((Date.now() - evt.ts) / 1000);
+          const ageStr = age < 60 ? `${age}s ago` : age < 3600 ? `${Math.floor(age / 60)}m ago` : `${Math.floor(age / 3600)}h ago`;
+          const consumed = evt.consumed ? dim(" [consumed]") : "";
+          console.log(`  ${bar}  ${green("●")} ${bold(evt.type)} ${dim(`from ${evt.source}`)} ${dim(ageStr)}${consumed}`);
+          console.log(`  ${bar}    ${dim("id:")} ${evt.id}`);
+          const dataStr = JSON.stringify(evt.data);
+          const truncated = dataStr.length > 120 ? dataStr.slice(0, 120) + "..." : dataStr;
+          console.log(`  ${bar}    ${dim("data:")} ${truncated}`);
+        }
+        console.log();
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("not enabled")) {
+          console.log("Events not available (web.enabled = false in config).");
+        } else {
+          console.log("Could not reach gateway. Is it running?");
+        }
+      }
+    });
+
+  // ── Structured help for LLM discovery ────────────────────────────
+
+  cmd
+    .command("help-json")
+    .description("Output structured command reference (JSON) for programmatic consumption")
+    .action(() => {
+      const commands = [
+        { name: "status", args: "", options: ["--json"], description: "Show cluster topology and peer status" },
+        { name: "peers", args: "", options: [], description: "List known peers (JSON)" },
+        { name: "check", args: "<nodeId>", options: [], description: "Check if a specific node is reachable (minimal JSON)" },
+        { name: "tools", args: "[node]", options: ["--json", "-v/--verbose", "-f/--filter <keyword>", "-d/--describe <tool>"], description: "List available tools on remote nodes" },
+        { name: "call", args: "<node> <tool> [json-params]", options: ["-t/--timeout <ms>"], description: "Invoke a tool on a remote node" },
+        { name: "batch", args: "<node> [items-json]", options: ["--no-stop-on-error", "-t/--timeout <ms>"], description: "Invoke multiple tools in sequence" },
+        { name: "models", args: "", options: ["--json", "-n/--node <nodeId>"], description: "List all models available across the cluster" },
+        { name: "events", args: "", options: ["--json", "-t/--type", "-s/--source", "-l/--limit", "-a/--all", "--consume <ids>"], description: "Query and consume ingested events" },
+        { name: "approve", args: "<approvalId>", options: [], description: "Approve a pending peer join request" },
+        { name: "deny", args: "<approvalId>", options: [], description: "Deny a pending peer join request" },
+        { name: "approval list", args: "", options: [], description: "List approved and pending peers" },
+        { name: "approval revoke", args: "<nodeId>", options: [], description: "Revoke an approved peer" },
+      ];
+      console.log(jsonOut({ prefix: "clawmatrix", commands }));
     });
 
   // ── Peer approval commands ──────────────────────────────────────
@@ -219,7 +687,7 @@ export const registerClusterCli = ({ program }: { program: Command }) => {
     .action(async () => {
       try {
         const data = await callGateway("clawmatrix.approval.list") as Record<string, unknown>;
-        console.log(JSON.stringify(data, null, 2));
+        console.log(jsonOut(data));
       } catch {
         console.log("Could not reach gateway. Is it running?");
       }