@fcannizzaro/exocommand 1.0.0 → 1.0.2

package/README.md

@@ -103,6 +103,12 @@ The server exposes two tools:
 | `listCommands()` | Returns all available commands from the config file. |
 | `execute(name)` | Executes a command by name, streaming output back to the client. |
 
+Remember to tell the agent that they can use these tools to run commands on the project. For example:
+
+```
+You can run predefined shell commands using the `listCommands()` and `execute(name)` tools. Use `listCommands()` to see all available commands, and `execute(name)` to run a specific command.
+```
+
 ## License
 
 [MIT](LICENSE)

package/dist/config.test.js

@@ -0,0 +1,205 @@
+import { test, expect, describe, beforeAll, afterAll } from "bun:test";
+import { loadConfig, loadCommands } from "./config";
+import { join } from "node:path";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+let tmpDir;
+beforeAll(async () => {
+    tmpDir = await mkdtemp(join(tmpdir(), "exocommand-test-"));
+});
+afterAll(async () => {
+    await rm(tmpDir, { recursive: true, force: true });
+});
+async function writeConfig(name, content) {
+    const path = join(tmpDir, name);
+    await Bun.write(path, content);
+    return path;
+}
+describe("loadConfig", () => {
+    test("parses valid config with commands", async () => {
+        const path = await writeConfig("valid.yaml", `
+hello:
+  description: "Print hello"
+  command: "echo hello"
+build:
+  description: "Run build"
+  command: "bun run build"
+`);
+        const config = await loadConfig(path);
+        expect(config.port).toBeUndefined();
+        expect(config.commands).toHaveLength(2);
+        expect(config.commands[0]).toEqual({
+            name: "hello",
+            description: "Print hello",
+            command: "echo hello",
+        });
+        expect(config.commands[1]).toEqual({
+            name: "build",
+            description: "Run build",
+            command: "bun run build",
+        });
+    });
+    test("parses valid port", async () => {
+        const path = await writeConfig("port-valid.yaml", `
+port: 8080
+hello:
+  description: "hi"
+  command: "echo hi"
+`);
+        const config = await loadConfig(path);
+        expect(config.port).toBe(8080);
+    });
+    test("accepts port boundary values", async () => {
+        const pathMin = await writeConfig("port-min.yaml", "port: 1\n");
+        const pathMax = await writeConfig("port-max.yaml", "port: 65535\n");
+        expect((await loadConfig(pathMin)).port).toBe(1);
+        expect((await loadConfig(pathMax)).port).toBe(65535);
+    });
+    test("rejects port 0", async () => {
+        const path = await writeConfig("port-zero.yaml", "port: 0\n");
+        expect(loadConfig(path)).rejects.toThrow("Invalid port");
+    });
+    test("rejects port above 65535", async () => {
+        const path = await writeConfig("port-high.yaml", "port: 65536\n");
+        expect(loadConfig(path)).rejects.toThrow("Invalid port");
+    });
+    test("rejects non-numeric port", async () => {
+        const path = await writeConfig("port-abc.yaml", 'port: "abc"\n');
+        expect(loadConfig(path)).rejects.toThrow("Invalid port");
+    });
+    test("rejects float port", async () => {
+        const path = await writeConfig("port-float.yaml", "port: 3.14\n");
+        expect(loadConfig(path)).rejects.toThrow("Invalid port");
+    });
+    test("port key is not treated as a command", async () => {
+        const path = await writeConfig("port-reserved.yaml", `
+port: 3000
+hello:
+  description: "hi"
+  command: "echo hi"
+`);
+        const config = await loadConfig(path);
+        expect(config.commands).toHaveLength(1);
+        expect(config.commands[0].name).toBe("hello");
+    });
+    test("accepts valid command names", async () => {
+        const path = await writeConfig("names-valid.yaml", `
+hello:
+  description: "a"
+  command: "echo a"
+my-cmd:
+  description: "b"
+  command: "echo b"
+test_123:
+  description: "c"
+  command: "echo c"
+`);
+        const config = await loadConfig(path);
+        expect(config.commands).toHaveLength(3);
+        expect(config.commands.map((c) => c.name)).toEqual([
+            "hello",
+            "my-cmd",
+            "test_123",
+        ]);
+    });
+    test("rejects command name with spaces", async () => {
+        const path = await writeConfig("name-space.yaml", `
+"has space":
+  description: "x"
+  command: "echo x"
+`);
+        expect(loadConfig(path)).rejects.toThrow("Invalid command name");
+    });
+    test("rejects command name with dots", async () => {
+        const path = await writeConfig("name-dot.yaml", `
+"has.dot":
+  description: "x"
+  command: "echo x"
+`);
+        expect(loadConfig(path)).rejects.toThrow("Invalid command name");
+    });
+    test("rejects command missing description", async () => {
+        const path = await writeConfig("no-desc.yaml", `
+broken:
+  command: "echo x"
+`);
+        expect(loadConfig(path)).rejects.toThrow('Invalid command "broken"');
+    });
+    test("rejects command missing command field", async () => {
+        const path = await writeConfig("no-cmd.yaml", `
+broken:
+  description: "x"
+`);
+        expect(loadConfig(path)).rejects.toThrow('Invalid command "broken"');
+    });
+    test("rejects command with wrong types", async () => {
+        const path = await writeConfig("wrong-type.yaml", `
+broken:
+  description: 123
+  command: "echo x"
+`);
+        expect(loadConfig(path)).rejects.toThrow('Invalid command "broken"');
+    });
+    test("throws on file not found", async () => {
+        expect(loadConfig("/nonexistent/path/.exocommand")).rejects.toThrow("Config file not found");
+    });
+    test("throws on empty file", async () => {
+        const path = await writeConfig("empty.yaml", "");
+        expect(loadConfig(path)).rejects.toThrow("expected a YAML mapping");
+    });
+    test("throws on non-object YAML (string)", async () => {
+        const path = await writeConfig("string.yaml", '"hello"');
+        expect(loadConfig(path)).rejects.toThrow("expected a YAML mapping");
+    });
+    test("throws on non-object YAML (number)", async () => {
+        const path = await writeConfig("number.yaml", "42");
+        expect(loadConfig(path)).rejects.toThrow("expected a YAML mapping");
+    });
+    test("throws on non-object YAML (array)", async () => {
+        const path = await writeConfig("array.yaml", "- one\n- two\n");
+        expect(loadConfig(path)).rejects.toThrow("Invalid command");
+    });
+    test("preserves multiline block scalar command", async () => {
+        const path = await writeConfig("multiline.yaml", `
+deploy:
+  description: "Deploy"
+  command: |
+    echo "step 1"
+    echo "step 2"
+`);
+        const config = await loadConfig(path);
+        expect(config.commands[0].command).toBe('echo "step 1"\necho "step 2"');
+    });
+    test("trims whitespace from command", async () => {
+        const path = await writeConfig("trim.yaml", `
+hello:
+  description: "hi"
+  command: "  echo hello  "
+`);
+        const config = await loadConfig(path);
+        expect(config.commands[0].command).toBe("echo hello");
+    });
+    test("returns empty commands when only port is set", async () => {
+        const path = await writeConfig("port-only.yaml", "port: 5000\n");
+        const config = await loadConfig(path);
+        expect(config.port).toBe(5000);
+        expect(config.commands).toHaveLength(0);
+    });
+});
+describe("loadCommands", () => {
+    test("returns only the commands array", async () => {
+        const path = await writeConfig("load-cmds.yaml", `
+port: 3000
+hello:
+  description: "hi"
+  command: "echo hi"
+`);
+        const commands = await loadCommands(path);
+        expect(commands).toHaveLength(1);
+        expect(commands[0]).toEqual({
+            name: "hello",
+            description: "hi",
+            command: "echo hi",
+        });
+    });
+});

package/dist/executor.test.js

@@ -0,0 +1,110 @@
+import { test, expect, describe } from "bun:test";
+import { executeCommand } from "./executor";
+function createLogCollector() {
+    const entries = [];
+    const log = async (level, logger, data) => {
+        entries.push({ level, logger, data });
+    };
+    return { log, entries };
+}
+describe("executeCommand", () => {
+    test("runs a simple command and captures output", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand("echo hello", log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        expect(result.killed).toBe(false);
+        expect(entries).toContainEqual({
+            level: "info",
+            logger: "stdout",
+            data: "hello",
+        });
+    });
+    test("returns non-zero exit code", async () => {
+        const { log } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand("exit 42", log, ac.signal);
+        expect(result.exitCode).toBe(42);
+        expect(result.killed).toBe(false);
+    });
+    test("captures stderr with correct level", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand("echo err >&2", log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        expect(entries).toContainEqual({
+            level: "error",
+            logger: "stderr",
+            data: "err",
+        });
+    });
+    test("captures mixed stdout and stderr", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand('echo out && echo err >&2', log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        const stdoutEntries = entries.filter((e) => e.logger === "stdout");
+        const stderrEntries = entries.filter((e) => e.logger === "stderr");
+        expect(stdoutEntries.length).toBeGreaterThanOrEqual(1);
+        expect(stderrEntries.length).toBeGreaterThanOrEqual(1);
+        expect(stdoutEntries.some((e) => e.data === "out")).toBe(true);
+        expect(stderrEntries.some((e) => e.data === "err")).toBe(true);
+    });
+    test("produces no log entries for silent command", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand("true", log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        expect(entries).toHaveLength(0);
+    });
+    test("captures multiline output as separate entries", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand('echo "line1" && echo "line2" && echo "line3"', log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        const stdoutData = entries
+            .filter((e) => e.logger === "stdout")
+            .map((e) => e.data);
+        expect(stdoutData).toEqual(["line1", "line2", "line3"]);
+    });
+    test("returns immediately with pre-aborted signal", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        ac.abort();
+        const result = await executeCommand("echo should-not-run", log, ac.signal);
+        expect(result.exitCode).toBe(-1);
+        expect(result.killed).toBe(true);
+        expect(entries).toHaveLength(0);
+    });
+    test("kills process on abort during execution", async () => {
+        const { log } = createLogCollector();
+        const ac = new AbortController();
+        const promise = executeCommand("while true; do echo tick; sleep 0.1; done", log, ac.signal);
+        // Wait a moment for the process to start, then abort
+        await new Promise((r) => setTimeout(r, 200));
+        ac.abort();
+        const result = await promise;
+        expect(result.killed).toBe(true);
+    }, 10000);
+    test("does not log empty lines", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand('echo "a" && echo "" && echo "b"', log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        const stdoutData = entries
+            .filter((e) => e.logger === "stdout")
+            .map((e) => e.data);
+        expect(stdoutData).toEqual(["a", "b"]);
+    });
+    test("flushes output without trailing newline", async () => {
+        const { log, entries } = createLogCollector();
+        const ac = new AbortController();
+        const result = await executeCommand("printf 'no-newline'", log, ac.signal);
+        expect(result.exitCode).toBe(0);
+        expect(entries).toContainEqual({
+            level: "info",
+            logger: "stdout",
+            data: "no-newline",
+        });
+    });
+});

package/dist/index.js

@@ -8,7 +8,7 @@ import { logger } from "./logger.js";
 const CONFIG_PATH = process.env.EXO_COMMAND_FILE || "./.exocommand";
 // Load config to get port
 const config = await loadConfig(CONFIG_PATH);
-const PORT = parseInt(process.env.EXO_PORT || String(config.port ?? 3000), 10);
+const PORT = parseInt(process.env.EXO_PORT || String(config.port ?? 5555), 10);
 const transports = new Map();
 const servers = new Set();
 async function handleMcp(req) {

package/package.json

@@ -1,9 +1,11 @@
 {
   "name": "@fcannizzaro/exocommand",
   "module": "index.ts",
-  "version": "1.0.0",
+  "description": "An MCP server that exposes user-defined shell commands as tools for AI coding assistants",
+  "version": "1.0.2",
   "type": "module",
   "main": "dist/index.js",
+  "homepage": "https://github.com/fcannizzaro/exocommand",
   "author": {
     "name": "Francesco Saverio Cannizzaro (fcannizzaro)",
     "url": "https://fcannizzaro.com"
@@ -27,10 +29,11 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "tsc"
+    "build": "tsc",
+    "test": "bun test"
   },
   "bin": {
-    "exocommand": "./index.js"
+    "exocommand": "./dist/index.js"
   },
   "devDependencies": {
     "@types/bun": "latest"