@fcannizzaro/exocommand 1.0.10 → 1.1.0

package/README.md

@@ -13,43 +13,78 @@
 
 ## Overview
 
-Exocommand lets you define a curated set of shell commands in a simple YAML file and makes them available to any [MCP](https://modelcontextprotocol.io)-compatible AI client. Instead of giving an AI agent unrestricted terminal access, you control exactly which commands it can discover and execute.
+Exocommand is a centralized [MCP](https://modelcontextprotocol.io) server that manages multiple projects, each with its own set of shell commands defined in a `.exocommand` YAML file. Instead of giving an AI agent unrestricted terminal access, you register projects with the server and control exactly which commands each agent can discover and execute.
 
 ## Features
 
-- **YAML configuration** -- Define commands in a `.exocommand` file with a name, description, and shell command.
-- **Live reload** -- The server watches the config file for changes and notifies connected clients automatically.
+- **Multi-project registry** -- Register multiple projects, each with a unique access key. The server manages them all from a single process.
+- **TUI dashboard** -- When running in a terminal, the server displays a real-time dashboard with project tabs, execution cards, status indicators, and animated spinners.
+- **YAML configuration** -- Define commands per project in a `.exocommand` file with a name, description, and shell command.
+- **Live reload** -- The server watches each project's config file for changes and notifies connected clients automatically.
 - **Streaming output** -- By default, stdout and stderr are streamed line-by-line to the client via SSE in real time. If the server crashes mid-execution, the client retains all lines already received.
 - **Task mode** -- Opt-in execution mode backed by the MCP experimental tasks API for crash-resilient, independently-pollable command execution.
 - **Cancellation** -- Long-running commands can be cancelled by the client; the spawned process is killed immediately.
-- **Multi-session** -- Uses the Streamable HTTP transport, supporting multiple concurrent MCP sessions.
-- **Configurable port** -- Set via the config file, the `EXO_PORT` environment variable, or defaults to `5555`.
+- **Multi-session** -- Uses the Streamable HTTP transport, supporting multiple concurrent MCP sessions across projects.
 
-## Usage
+<p align="center">
+  <img src="media/tui.webp" alt="TUI Dashboard" />
+</p>
+
+## Quick Start
+
+1. **Create a config file** in your project directory (skip if you already have one):
+
+```bash
+bunx @fcannizzaro/exocommand init
+```
 
-Run the server in your project directory:
+2. **Register the project** by pointing to a directory containing a `.exocommand` file (or to the file directly):
+
+```bash
+bunx @fcannizzaro/exocommand add .
+```
+
+This validates the config and prints an access key:
+
+```
+  ✓ Project registered
+
+    Key     a1b2c3d4e5f6
+    Header  exocommand-project: a1b2c3d4e5f6
+    Config  /path/to/project/.exocommand
+```
+
+3. **Start the server:**
 
 ```bash
 bunx @fcannizzaro/exocommand
 ```
 
-> use `@fcannizzaro/exocommand@latest` to always run the latest version from npm
+> Use `@fcannizzaro/exocommand@latest` to always run the latest version from npm.
 
 The server starts on `http://127.0.0.1:5555/mcp` by default.
 
-> If no `.exocommand` file exists, the CLI will create a sample configuration file and exit. Edit the generated file with your own commands, then run the CLI again to start the server.
+4. **Connect an MCP client** with the `exocommand-project` header set to the access key (see [Connecting an AI Client](#connecting-an-ai-client)).
 
-## Configuration
+## CLI Commands
 
-Create a `.exocommand` file in the project root (or set a custom path with the `EXO_COMMAND_FILE` env var):
+| Command | Description |
+| --- | --- |
+| `exocommand` | Start the MCP server. |
+| `exocommand init` | Create a sample `.exocommand` config file in the current directory. Errors if the file already exists. |
+| `exocommand add <path>` | Register a project. Accepts a directory (auto-resolves `.exocommand` inside it) or a direct file path. Validates the config and prints the access key. |
+| `exocommand ls` | List all registered projects with their access keys and config paths. Missing configs are flagged. |
+| `exocommand rm <key-or-path>` | Remove a project by its access key or filesystem path. |
 
-```yaml
-# Optional: override the default port
-port: 4444
+- The registry is stored at `~/.exocommand/exocommand.db.json`.
+- Access keys are 12-character hex strings.
+- Re-adding an already registered path returns the existing key (no duplicates).
+
+## Configuration
 
-# Optional: enable task-based execution mode (default: false)
-# taskMode: true
+Create a `.exocommand` file in the project root:
 
+```yaml
 build:
   description: "Run the production build"
   command: "cargo build --release"
@@ -64,21 +99,20 @@ list-external:
   cwd: ../
 ```
 
-Each top-level key (except reserved keys like `port` and `taskMode`) is a command name. Names may contain letters, numbers, hyphens, and underscores.
+Each top-level key is a command name. Names may contain letters, numbers, hyphens, and underscores.
 
 | Field | Required | Description |
 | --- | --- | --- |
 | `description` | Yes | What the command does. |
 | `command` | Yes | The shell command to run. |
-| `cwd` | No | Working directory for the command. Relative paths are resolved from the server's working directory. |
+| `cwd` | No | Working directory for the command. Relative paths are resolved from the config file's directory. |
 
 ### Environment Variables
 
 | Variable | Description | Default |
 | --- | --- | --- |
-| `EXO_COMMAND_FILE` | Path to the `.exocommand` config file | `./.exocommand` |
-| `EXO_PORT` | Server port (overrides config file) | `5555` |
-| `EXO_TASK_MODE` | Enable task mode (`true` or `1`, overrides config file) | `false` |
+| `EXO_PORT` | Server port | `5555` |
+| `EXO_TASK_MODE` | Enable task mode (`true` or `1`) | `false` |
 
 ### Execution Modes
 
@@ -86,24 +120,13 @@ The `execute` tool supports two execution modes:
 
 **Streaming (default)** -- Each output line is sent as an SSE event on the response stream as it happens. The client receives lines in real time. If the server crashes mid-execution, all lines sent up to that point are already with the client. Cancellation works through the standard MCP request signal (client disconnect or `notifications/cancelled`).
 
-**Task mode** -- Enabled via `taskMode: true` in the config file or `EXO_TASK_MODE=true`. Uses the MCP experimental tasks API. The server creates a background task, and clients can poll its status independently. Task-aware clients get full crash resilience (disconnect, reconnect, and resume polling). Supports structured cancellation via `tasks/cancel`.
-
-## Safety
-
-Remember to mount the `.exocommand` as read-only volume on Docker, to prevent the agent from modifying it.
-
-If you have already use a script to start containerized agents, you can modify it to automatically mount the `.exocommand` file when present in the launch directory:
-
-```bash
-docker run \
-  # ...
-  $([ -f "$PWD/.exocommand" ] && echo "-v $PWD/.exocommand:$PWD/.exocommand:ro") \
-  # ...
-```
+**Task mode** -- Enabled via `EXO_TASK_MODE=true`. Uses the MCP experimental tasks API. The server creates a background task, and clients can poll its status independently. Task-aware clients get full crash resilience (disconnect, reconnect, and resume polling). Supports structured cancellation via `tasks/cancel`.
 
 ## Connecting an AI Client
 
-Point any MCP-compatible client at the server's `/mcp` endpoint. For example, with [OpenCode](https://opencode.ai):
+Point any MCP-compatible client at the server's `/mcp` endpoint. Clients must include the `exocommand-project` header with the project's access key on the initialize request.
+
+For example, with [OpenCode](https://opencode.ai):
 
 ```json
 {
@@ -111,7 +134,10 @@ Point any MCP-compatible client at the server's `/mcp` endpoint. For example, wi
     "exocommand": {
       "enabled": true,
       "type": "remote",
-      "url": "http://host.docker.internal:5555/mcp"
+      "url": "http://host.docker.internal:5555/mcp",
+      "headers": {
+        "exocommand-project": "<access-key>"
+      }
     }
   }
 }
@@ -121,7 +147,7 @@ The server exposes two tools:
 
 | Tool | Description |
 | --- | --- |
-| `listCommands()` | Returns all available commands from the config file. |
+| `listCommands()` | Returns all available commands from the project's config file. |
 | `execute(name, timeout?)` | Executes a command by name, streaming output back to the client. An optional `timeout` (in seconds) kills the process after the given duration and returns the buffered output. |
 
 Remember to tell the agent that they can use these tools to run commands on the project. For example:
@@ -130,6 +156,19 @@ Remember to tell the agent that they can use these tools to run commands on the
 You can run predefined shell commands using the `listCommands()` and `execute(name, timeout?)` tools. Use `listCommands()` to see all available commands, and `execute(name, timeout?)` to run a specific command, with an optional timeout in seconds.
 ```
 
+## Safety
+
+When running agents in Docker, mount `.exocommand` files as read-only volumes to prevent the agent from modifying them.
+
+If you use a script to start containerized agents, you can automatically mount the `.exocommand` file when present in the launch directory:
+
+```bash
+docker run \
+  # ...
+  $([ -f "$PWD/.exocommand" ] && echo "-v $PWD/.exocommand:$PWD/.exocommand:ro") \
+  # ...
+```
+
 ## License
 
 [MIT](LICENSE)

package/dist/cli.js

@@ -0,0 +1,29 @@
+export function parseArgs(argv) {
+    const args = argv.slice(2);
+    if (args.length === 0) {
+        return { kind: "serve" };
+    }
+    const subcommand = args[0];
+    switch (subcommand) {
+        case "add": {
+            const target = args[1];
+            if (!target) {
+                throw new Error("Usage: exocommand add <path-to-.exocommand-or-directory>");
+            }
+            return { kind: "add", path: target };
+        }
+        case "ls":
+            return { kind: "ls" };
+        case "init":
+            return { kind: "init" };
+        case "rm": {
+            const target = args[1];
+            if (!target) {
+                throw new Error("Usage: exocommand rm <access-key-or-path>");
+            }
+            return { kind: "rm", target };
+        }
+        default:
+            throw new Error(`Unknown subcommand "${subcommand}". Available: add, init, ls, rm`);
+    }
+}

package/dist/cli.test.js

@@ -0,0 +1,45 @@
+import { test, expect, describe } from "bun:test";
+import { parseArgs } from "./cli";
+describe("parseArgs", () => {
+    test("no args returns serve action", () => {
+        const result = parseArgs(["node", "exocommand"]);
+        expect(result).toEqual({ kind: "serve" });
+    });
+    test("add with path returns add action", () => {
+        const result = parseArgs(["node", "exocommand", "add", "."]);
+        expect(result).toEqual({ kind: "add", path: "." });
+    });
+    test("add with absolute path returns add action", () => {
+        const result = parseArgs(["node", "exocommand", "add", "/home/user/project/.exocommand"]);
+        expect(result).toEqual({ kind: "add", path: "/home/user/project/.exocommand" });
+    });
+    test("add without path throws", () => {
+        expect(() => parseArgs(["node", "exocommand", "add"])).toThrow("Usage: exocommand add <path-to-.exocommand-or-directory>");
+    });
+    test("ls returns ls action", () => {
+        const result = parseArgs(["node", "exocommand", "ls"]);
+        expect(result).toEqual({ kind: "ls" });
+    });
+    test("rm with key returns rm action", () => {
+        const result = parseArgs(["node", "exocommand", "rm", "a1b2c3d4e5f6"]);
+        expect(result).toEqual({ kind: "rm", target: "a1b2c3d4e5f6" });
+    });
+    test("rm with path returns rm action", () => {
+        const result = parseArgs(["node", "exocommand", "rm", "."]);
+        expect(result).toEqual({ kind: "rm", target: "." });
+    });
+    test("rm with absolute path returns rm action", () => {
+        const result = parseArgs(["node", "exocommand", "rm", "/home/user/project"]);
+        expect(result).toEqual({ kind: "rm", target: "/home/user/project" });
+    });
+    test("rm without target throws", () => {
+        expect(() => parseArgs(["node", "exocommand", "rm"])).toThrow("Usage: exocommand rm <access-key-or-path>");
+    });
+    test("init returns init action", () => {
+        const result = parseArgs(["node", "exocommand", "init"]);
+        expect(result).toEqual({ kind: "init" });
+    });
+    test("unknown subcommand throws", () => {
+        expect(() => parseArgs(["node", "exocommand", "unknown"])).toThrow('Unknown subcommand "unknown". Available: add, init, ls, rm');
+    });
+});

package/dist/config.js

@@ -1,4 +1,5 @@
 import { readFile, writeFile, access } from "node:fs/promises";
+import { dirname, isAbsolute, resolve } from "node:path";
 import { parse as parseYaml } from "yaml";
 const NAME_PATTERN = /^[a-zA-Z0-9_-]+$/;
 const RESERVED_KEYS = new Set(["port", "taskMode"]);
@@ -51,11 +52,17 @@ export async function loadConfig(filePath) {
             throw new Error(`Invalid command "${name}": "cwd" must be a string`);
         }
         const { description, command, cwd } = value;
+        // Resolve relative cwd against the config file's directory
+        const resolvedCwd = cwd
+            ? isAbsolute(cwd)
+                ? cwd
+                : resolve(dirname(filePath), cwd)
+            : undefined;
         config.commands.push({
             name,
             description,
             command: command.trim(),
-            ...(cwd ? { cwd } : {}),
+            ...(resolvedCwd ? { cwd: resolvedCwd } : {}),
         });
     }
     return config;

package/dist/config.test.js

@@ -1,6 +1,6 @@
 import { test, expect, describe, beforeAll, afterAll } from "bun:test";
 import { loadConfig, loadCommands } from "./config";
-import { join } from "node:path";
+import { join, dirname, resolve } from "node:path";
 import { mkdtemp, rm } from "node:fs/promises";
 import { tmpdir } from "node:os";
 let tmpDir;
@@ -236,6 +236,36 @@ hello:
 `);
         expect(loadCommands(path)).rejects.toThrow('"cwd" must be a string');
     });
+    test("resolves relative cwd against config file directory", async () => {
+        const path = await writeConfig("cwd-relative.yaml", `
+hello:
+  description: "hi"
+  command: "echo hi"
+  cwd: "../other"
+`);
+        const commands = await loadCommands(path);
+        expect(commands[0].cwd).toBe(resolve(dirname(path), "../other"));
+    });
+    test("preserves absolute cwd as-is", async () => {
+        const path = await writeConfig("cwd-absolute.yaml", `
+hello:
+  description: "hi"
+  command: "echo hi"
+  cwd: "/usr/local/bin"
+`);
+        const commands = await loadCommands(path);
+        expect(commands[0].cwd).toBe("/usr/local/bin");
+    });
+    test("resolves dot cwd to config file directory", async () => {
+        const path = await writeConfig("cwd-dot.yaml", `
+hello:
+  description: "hi"
+  command: "echo hi"
+  cwd: "."
+`);
+        const commands = await loadCommands(path);
+        expect(commands[0].cwd).toBe(dirname(path));
+    });
 });
 describe("loadConfig taskMode", () => {
     test("parses taskMode: true", async () => {