terminal-commands 0.1.1

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "terminal-commands",
+  "version": "0.1.1",
+  "private": false,
+  "type": "module",
+  "description": "A cross-platform, approval-gated terminal companion for ChatGPT, Claude, Codex, and any MCP-compatible AI client.",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "terminal-commands": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "esbuild src/index.ts src/stdio.ts src/agent.ts src/cli.ts --bundle --platform=node --format=esm --target=node20 --outdir=dist --banner:js=\"import { createRequire as __createRequire } from 'module'; const require = __createRequire(import.meta.url);\"",
+    "check": "tsc --noEmit",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "start:agent": "node dist/agent.js",
+    "cli": "node dist/cli.js",
+    "cli:dev": "tsx src/cli.ts",
+    "test": "tsx --test test/**/*.test.ts",
+    "test:smoke": "node test/smoke.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "express": "5.2.1",
+    "ws": "8.21.3",
+    "zod": "4.6.4"
+  },
+  "devDependencies": {
+    "@types/express": "5.0.6",
+    "@types/node": "26.5.1",
+    "@types/ws": "8.18.1",
+    "esbuild": "0.28.2",
+    "tsx": "4.23.13",
+    "typescript": "7.0.2"
+  }
+}

package/src/agent-config.ts

@@ -0,0 +1,40 @@
+import os from "node:os";
+
+import { z } from "zod";
+
+const schema = z.object({
+  MACHINE_TERMINAL_GATEWAY_URL: z.string().url(),
+  MACHINE_TERMINAL_DEVICE_TOKEN: z.string().min(1),
+  MACHINE_TERMINAL_DEVICE_ID: z.string().min(1).max(128),
+  MACHINE_TERMINAL_DEVICE_NAME: z
+    .string()
+    .min(1)
+    .max(128)
+    .default(os.hostname()),
+  MACHINE_TERMINAL_LOCAL_MCP_URL: z
+    .string()
+    .url()
+    .default("http://127.0.0.1:3333/mcp"),
+  MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE: z.enum(["0", "1"]).default("0"),
+});
+
+export type AgentConfig = z.infer<typeof schema>;
+
+export function loadAgentConfig(
+  environment: NodeJS.ProcessEnv = process.env,
+): AgentConfig {
+  const config = schema.parse(environment);
+  const gateway = new URL(config.MACHINE_TERMINAL_GATEWAY_URL);
+  if (!new Set(["wss:", "ws:"]).has(gateway.protocol)) {
+    throw new Error("MACHINE_TERMINAL_GATEWAY_URL must use wss:// or ws://.");
+  }
+  if (
+    gateway.protocol === "ws:" &&
+    !new Set(["127.0.0.1", "localhost", "::1"]).has(gateway.hostname)
+  ) {
+    throw new Error(
+      "Unencrypted ws:// is allowed only for loopback development.",
+    );
+  }
+  return config;
+}

package/src/agent-core.ts

@@ -0,0 +1,173 @@
+import os from "node:os";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import WebSocket, { type RawData } from "ws";
+import { z } from "zod";
+
+import type { AgentConfig } from "./agent-config.js";
+
+const destructiveTools = new Set(["run_program", "write_text_file"]);
+const requestSchema = z.object({
+  type: z.literal("request"),
+  requestId: z.string().uuid(),
+  tool: z.enum([
+    "get_system_info",
+    "list_directory",
+    "read_text_file",
+    "run_program",
+    "write_text_file",
+  ]),
+  arguments: z.record(z.string(), z.unknown()),
+});
+
+export interface RunAgentOptions {
+  config: AgentConfig;
+  getToken?: () => Promise<string>;
+  approve?: (tool: string, args: Record<string, unknown>) => Promise<boolean>;
+  signal?: AbortSignal;
+  log?: (message: string) => void;
+}
+
+export async function authorizeToolCall(
+  tool: string,
+  args: Record<string, unknown>,
+  allowDestructive: boolean,
+  approve?: (tool: string, args: Record<string, unknown>) => Promise<boolean>,
+): Promise<void> {
+  if (!destructiveTools.has(tool)) return;
+  if (!allowDestructive) {
+    throw new Error(
+      "This action requires local approval. Commands and writes are disabled unless explicitly enabled.",
+    );
+  }
+  if (!approve || !(await approve(tool, args))) {
+    throw new Error("The action was not approved on the connected machine.");
+  }
+}
+
+async function connectOnce(options: RunAgentOptions): Promise<void> {
+  const { config, signal } = options;
+  const client = new Client({
+    name: "terminal-commands-cli",
+    version: "0.1.0",
+  });
+  await client.connect(
+    new StreamableHTTPClientTransport(
+      new URL(config.MACHINE_TERMINAL_LOCAL_MCP_URL),
+    ),
+  );
+  const token = options.getToken
+    ? await options.getToken()
+    : config.MACHINE_TERMINAL_DEVICE_TOKEN;
+  const socket = new WebSocket(config.MACHINE_TERMINAL_GATEWAY_URL, {
+    headers: { Authorization: `Bearer ${token}` },
+  });
+  const stop = () => socket.close(1000, "Client stopping.");
+  signal?.addEventListener("abort", stop, { once: true });
+
+  socket.on("open", () => {
+    socket.send(
+      JSON.stringify({
+        type: "hello",
+        deviceId: config.MACHINE_TERMINAL_DEVICE_ID,
+        name: config.MACHINE_TERMINAL_DEVICE_NAME,
+        platform: `${os.platform()}-${os.arch()}`,
+      }),
+    );
+  });
+  socket.on("message", (raw: RawData) => {
+    void handleMessage(options, client, socket, raw);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    socket.once("close", resolve);
+    socket.once("error", reject);
+  }).finally(() => signal?.removeEventListener("abort", stop));
+  await client.close();
+}
+
+async function handleMessage(
+  options: RunAgentOptions,
+  client: Client,
+  socket: WebSocket,
+  raw: RawData,
+): Promise<void> {
+  let requestId: string | undefined;
+  try {
+    const parsed = requestSchema.parse(JSON.parse(raw.toString()) as unknown);
+    requestId = parsed.requestId;
+    await authorizeToolCall(
+      parsed.tool,
+      parsed.arguments,
+      options.config.MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE === "1",
+      options.approve,
+    );
+    const result = await client.callTool({
+      name: parsed.tool,
+      arguments: parsed.arguments,
+    });
+    if (result.isError) {
+      const content = Array.isArray(result.content) ? result.content : [];
+      const message = content
+        .flatMap((item) =>
+          typeof item === "object" &&
+          item !== null &&
+          "type" in item &&
+          item.type === "text" &&
+          "text" in item &&
+          typeof item.text === "string"
+            ? [item.text]
+            : [],
+        )
+        .join("\n");
+      throw new Error(message || "The local tool failed.");
+    }
+    if (socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "response",
+          requestId,
+          result: result.structuredContent ?? { content: result.content },
+        }),
+      );
+    }
+  } catch (error) {
+    if (!requestId || socket.readyState !== WebSocket.OPEN) return;
+    socket.send(
+      JSON.stringify({
+        type: "response",
+        requestId,
+        error: error instanceof Error ? error.message : "Local request failed.",
+      }),
+    );
+  }
+}
+
+export async function runAgent(options: RunAgentOptions): Promise<void> {
+  let reconnectDelayMs = 1_000;
+  while (!options.signal?.aborted) {
+    try {
+      await connectOnce(options);
+      reconnectDelayMs = 1_000;
+    } catch (error) {
+      if (options.signal?.aborted) break;
+      options.log?.(
+        `Connection failed: ${error instanceof Error ? error.message : "unknown error"}`,
+      );
+    }
+    if (options.signal?.aborted) break;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, reconnectDelayMs);
+      options.signal?.addEventListener(
+        "abort",
+        () => {
+          clearTimeout(timer);
+          resolve();
+        },
+        { once: true },
+      );
+    });
+    reconnectDelayMs = Math.min(reconnectDelayMs * 2, 30_000);
+  }
+}

package/src/agent.ts

@@ -0,0 +1,16 @@
+import { runAgent } from "./agent-core.js";
+import { loadAgentConfig } from "./agent-config.js";
+
+const controller = new AbortController();
+const stop = () => controller.abort();
+process.on("SIGINT", stop);
+process.on("SIGTERM", stop);
+
+void runAgent({
+  config: loadAgentConfig(),
+  signal: controller.signal,
+  log: (message) => console.error(`Terminal Commands: ${message}`),
+}).catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 1;
+});

package/src/cli-format.ts

@@ -0,0 +1,57 @@
+const isColorEnabled =
+  Boolean(process.stdout.isTTY) &&
+  process.env.NO_COLOR === undefined &&
+  process.env.TERM !== "dumb";
+
+const CODES = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  dim: "\u001b[2m",
+  red: "\u001b[31m",
+  green: "\u001b[32m",
+  yellow: "\u001b[33m",
+  blue: "\u001b[34m",
+  cyan: "\u001b[36m",
+  gray: "\u001b[90m",
+} as const;
+
+type ColorName = keyof typeof CODES;
+
+function paint(code: ColorName, text: string): string {
+  if (!isColorEnabled) return text;
+  return `${CODES[code]}${text}${CODES.reset}`;
+}
+
+export const bold = (text: string) => paint("bold", text);
+export const dim = (text: string) => paint("dim", text);
+export const ok = (text: string) => paint("green", text);
+export const warn = (text: string) => paint("yellow", text);
+export const danger = (text: string) => paint("red", text);
+export const info = (text: string) => paint("cyan", text);
+export const muted = (text: string) => paint("gray", text);
+
+export function heading(text: string): string {
+  const rule = "─".repeat(Math.max(text.length, 3));
+  return `${bold(info(text))}\n${muted(rule)}`;
+}
+
+export function subheading(text: string): string {
+  return bold(text);
+}
+
+export function bullet(text: string): string {
+  return `  ${muted("•")} ${text}`;
+}
+
+/** Renders "label  value" pairs with labels aligned to the widest label. */
+export function keyValueBlock(
+  rows: ReadonlyArray<readonly [string, string]>,
+): string {
+  const width = rows.reduce(
+    (widest, [label]) => Math.max(widest, label.length),
+    0,
+  );
+  return rows
+    .map(([label, value]) => `  ${dim(label.padEnd(width))}  ${value}`)
+    .join("\n");
+}