terminal-commands 0.1.1 → 0.1.2

package/src/agent-core.ts

@@ -1,173 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,57 +0,0 @@
-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");
-}

package/src/cli-options.ts

@@ -1,459 +0,0 @@
-import { promises as fs } from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-export const COMMANDS = [
-  "login",
-  "connect",
-  "status",
-  "logout",
-  "help",
-] as const;
-
-export type Command = (typeof COMMANDS)[number];
-
-export type OptionKind = "boolean" | "string" | "list";
-
-export interface OptionSpec {
-  readonly name: string;
-  readonly alias?: string;
-  readonly kind: OptionKind;
-  readonly env?: string;
-  readonly placeholder?: string;
-  readonly separator?: string;
-  readonly description: string;
-  readonly commands: readonly Command[];
-}
-
-export const COMMAND_SUMMARIES: Record<Exclude<Command, "help">, string> = {
-  login: "Sign in using a URL and one-time code",
-  connect: "Connect this machine until stopped",
-  status: "Show sign-in state and the settings connect would use",
-  logout: "Remove locally saved credentials",
-};
-
-const AUTH_COMMANDS = ["login", "connect", "status", "logout"] as const;
-
-export const OPTIONS: readonly OptionSpec[] = [
-  {
-    name: "root",
-    alias: "r",
-    kind: "list",
-    env: "MACHINE_TERMINAL_ROOTS",
-    placeholder: "<path>",
-    separator: path.delimiter,
-    commands: ["connect", "status"],
-    description:
-      "Approved filesystem root. Repeat the flag, or pass several paths separated by the platform path delimiter. Defaults to the current directory.",
-  },
-  {
-    name: "name",
-    kind: "string",
-    env: "MACHINE_TERMINAL_DEVICE_NAME",
-    placeholder: "<name>",
-    commands: ["connect", "status"],
-    description:
-      "Device name shown in the client. Defaults to this machine's hostname.",
-  },
-  {
-    name: "device-id",
-    kind: "string",
-    env: "MACHINE_TERMINAL_DEVICE_ID",
-    placeholder: "<id>",
-    commands: ["connect", "status"],
-    description:
-      "Device identifier to report. Defaults to the saved local device ID.",
-  },
-  {
-    name: "port",
-    kind: "string",
-    env: "MACHINE_TERMINAL_PORT",
-    placeholder: "<port>",
-    commands: ["connect", "status"],
-    description: "Port for the local MCP service. Defaults to 3333.",
-  },
-  {
-    name: "host",
-    kind: "string",
-    env: "MACHINE_TERMINAL_HOST",
-    placeholder: "<host>",
-    commands: ["connect", "status"],
-    description:
-      "Bind address for the local MCP service. Defaults to 127.0.0.1.",
-  },
-  {
-    name: "gateway-url",
-    kind: "string",
-    env: "MACHINE_TERMINAL_GATEWAY_URL",
-    placeholder: "<url>",
-    commands: ["connect", "status"],
-    description:
-      "Gateway WebSocket URL. Defaults to wss://mcp.terminalcommands.fr/device/connect.",
-  },
-  {
-    name: "allow-destructive",
-    kind: "boolean",
-    env: "MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE",
-    commands: ["connect"],
-    description:
-      "Ask in this terminal before each command and file write. Without it both are refused.",
-  },
-  {
-    name: "allow-shell",
-    kind: "boolean",
-    env: "MACHINE_TERMINAL_ALLOW_SHELL",
-    commands: ["connect"],
-    description:
-      "Permit shells and privilege tools such as sudo. Leave off unless you need them.",
-  },
-  {
-    name: "auto-approve",
-    kind: "boolean",
-    env: "MACHINE_TERMINAL_AUTO_APPROVE",
-    commands: ["connect"],
-    description:
-      "Approve every command and file write automatically, without a terminal prompt. Implies --allow-destructive. Use with caution.",
-  },
-  {
-    name: "allowed-program",
-    kind: "list",
-    env: "MACHINE_TERMINAL_ALLOWED_PROGRAMS",
-    placeholder: "<name>",
-    separator: ",",
-    commands: ["connect"],
-    description:
-      "Executable allowlist. Repeat the flag or separate names with commas. Defaults to any program that is not blocked.",
-  },
-  {
-    name: "allow-public-bind",
-    kind: "boolean",
-    env: "MACHINE_TERMINAL_ALLOW_PUBLIC_BIND",
-    commands: ["connect"],
-    description: "Permit a non-loopback bind. Only behind authenticated HTTPS.",
-  },
-  {
-    name: "auth-issuer",
-    kind: "string",
-    env: "MACHINE_TERMINAL_AUTH_ISSUER",
-    placeholder: "<url>",
-    commands: AUTH_COMMANDS,
-    description: "OAuth issuer. Change this only for a self-hosted gateway.",
-  },
-  {
-    name: "auth-client-id",
-    kind: "string",
-    env: "MACHINE_TERMINAL_AUTH_CLIENT_ID",
-    placeholder: "<id>",
-    commands: AUTH_COMMANDS,
-    description: "OAuth client ID used by the device authorization flow.",
-  },
-  {
-    name: "auth-audience",
-    kind: "string",
-    env: "MACHINE_TERMINAL_AUTH_AUDIENCE",
-    placeholder: "<url>",
-    commands: AUTH_COMMANDS,
-    description: "OAuth audience the access token is issued for.",
-  },
-  {
-    name: "dry-run",
-    kind: "boolean",
-    commands: ["connect"],
-    description:
-      "Print the resolved settings and exit without starting anything.",
-  },
-  {
-    name: "json",
-    kind: "boolean",
-    commands: ["connect", "status"],
-    description: "Print machine-readable JSON instead of a summary.",
-  },
-];
-
-export interface ParsedCommandLine {
-  readonly command: Command;
-  readonly help: boolean;
-  readonly options: ReadonlyMap<string, string[] | boolean>;
-}
-
-function findByName(name: string): OptionSpec | undefined {
-  return OPTIONS.find((option) => option.name === name);
-}
-
-function findByAlias(alias: string): OptionSpec | undefined {
-  return OPTIONS.find((option) => option.alias === alias);
-}
-
-function asCommand(token: string): Command {
-  const match = COMMANDS.find((name) => name === token);
-  if (!match) {
-    throw new Error(
-      `Unknown command: ${token}. Expected one of: ${COMMANDS.join(", ")}.`,
-    );
-  }
-  return match;
-}
-
-function splitValues(value: string, separator?: string): string[] {
-  const parts = separator ? value.split(separator) : [value];
-  return parts.map((part) => part.trim()).filter(Boolean);
-}
-
-function readBoolean(value: string, name: string): boolean {
-  const normalized = value.trim().toLowerCase();
-  if (new Set(["1", "true", "yes", "on"]).has(normalized)) return true;
-  if (new Set(["0", "false", "no", "off"]).has(normalized)) return false;
-  throw new Error(`--${name} accepts true or false, not "${value}".`);
-}
-
-function missingValue(spec: OptionSpec): Error {
-  return new Error(
-    `Option --${spec.name} needs a value, for example --${spec.name} ${spec.placeholder ?? "<value>"}.`,
-  );
-}
-
-export function parseCommandLine(argv: readonly string[]): ParsedCommandLine {
-  const options = new Map<string, string[] | boolean>();
-  const queue = [...argv];
-  let command: Command | undefined;
-  let help = false;
-
-  const record = (spec: OptionSpec, value: string): void => {
-    if (spec.kind !== "list") {
-      options.set(spec.name, [value]);
-      return;
-    }
-    const current = options.get(spec.name);
-    const existing = Array.isArray(current) ? current : [];
-    options.set(spec.name, [
-      ...existing,
-      ...splitValues(value, spec.separator),
-    ]);
-  };
-
-  while (queue.length > 0) {
-    const token = queue.shift() as string;
-
-    if (token === "--help" || token === "-h") {
-      help = true;
-      continue;
-    }
-
-    if (token.startsWith("--")) {
-      const body = token.slice(2);
-      if (body.length === 0) {
-        throw new Error("A bare `--` is not supported. Pass options directly.");
-      }
-      const equals = body.indexOf("=");
-      const rawName = equals === -1 ? body : body.slice(0, equals);
-      const inline = equals === -1 ? undefined : body.slice(equals + 1);
-      const negated =
-        findByName(rawName) === undefined && rawName.startsWith("no-");
-      const name = negated ? rawName.slice(3) : rawName;
-      const spec = findByName(name);
-      if (!spec) {
-        throw new Error(
-          `Unknown option: --${rawName}. Run \`terminal-commands --help\` to see every option.`,
-        );
-      }
-      if (spec.kind === "boolean") {
-        if (inline === undefined) {
-          options.set(spec.name, !negated);
-          continue;
-        }
-        if (negated)
-          throw new Error(`--no-${spec.name} does not take a value.`);
-        options.set(spec.name, readBoolean(inline, spec.name));
-        continue;
-      }
-      if (negated)
-        throw new Error(`--no-${name} is only available for on/off options.`);
-      const value = inline ?? queue.shift();
-      if (
-        value === undefined ||
-        (inline === undefined && value.startsWith("--"))
-      ) {
-        throw missingValue(spec);
-      }
-      record(spec, value);
-      continue;
-    }
-
-    if (token.startsWith("-") && token.length > 1) {
-      const body = token.slice(1);
-      const alias = body.slice(0, 1);
-      const spec = findByAlias(alias);
-      if (!spec) {
-        throw new Error(
-          `Unknown option: -${alias}. Run \`terminal-commands --help\` to see every option.`,
-        );
-      }
-      const attached = body.slice(1).replace(/^=/, "");
-      if (spec.kind === "boolean") {
-        if (attached.length > 0)
-          throw new Error(`-${alias} does not take a value.`);
-        options.set(spec.name, true);
-        continue;
-      }
-      const value = attached.length > 0 ? attached : queue.shift();
-      if (
-        value === undefined ||
-        (attached.length === 0 && value.startsWith("--"))
-      ) {
-        throw missingValue(spec);
-      }
-      record(spec, value);
-      continue;
-    }
-
-    if (command !== undefined) throw new Error(`Unexpected argument: ${token}`);
-    command = asCommand(token);
-  }
-
-  const resolved = command ?? "help";
-  if (resolved !== "help") {
-    for (const name of options.keys()) {
-      const spec = findByName(name);
-      if (!spec || spec.commands.includes(resolved)) continue;
-      throw new Error(
-        `--${name} is not available for \`${resolved}\`. It applies to: ${spec.commands.join(", ")}.`,
-      );
-    }
-  }
-
-  return { command: resolved, help: help || resolved === "help", options };
-}
-
-/**
- * Turn parsed options into environment overrides. A flag replaces the matching
- * environment variable outright, so --root never appends to MACHINE_TERMINAL_ROOTS.
- */
-export function optionEnvironment(
-  parsed: ParsedCommandLine,
-): Record<string, string> {
-  const environment: Record<string, string> = {};
-  for (const spec of OPTIONS) {
-    if (!spec.env) continue;
-    const value = parsed.options.get(spec.name);
-    if (value === undefined) continue;
-    if (typeof value === "boolean") {
-      environment[spec.env] = value ? "1" : "0";
-      continue;
-    }
-    if (value.length > 0)
-      environment[spec.env] = value.join(spec.separator ?? ",");
-  }
-  return environment;
-}
-
-export function expandHome(value: string, home = os.homedir()): string {
-  if (value === "~") return home;
-  if (value.startsWith(`~${path.sep}`) || value.startsWith("~/")) {
-    return path.join(home, value.slice(2));
-  }
-  return value;
-}
-
-export function splitRootList(raw: string | undefined): string[] {
-  if (!raw) return [];
-  return raw
-    .split(path.delimiter)
-    .map((part) => part.trim())
-    .filter(Boolean);
-}
-
-export function normalizeRoots(
-  values: readonly string[],
-  cwd = process.cwd(),
-): string[] {
-  const resolved = values.map((value) => path.resolve(cwd, expandHome(value)));
-  return [...new Set(resolved)];
-}
-
-export async function assertRootsExist(
-  roots: readonly string[],
-): Promise<void> {
-  const problems: string[] = [];
-  for (const root of roots) {
-    try {
-      const stats = await fs.stat(root);
-      if (!stats.isDirectory()) problems.push(`${root} is not a directory`);
-    } catch {
-      problems.push(`${root} does not exist`);
-    }
-  }
-  if (problems.length > 0) {
-    throw new Error(
-      `Cannot approve these roots:\n  - ${problems.join("\n  - ")}`,
-    );
-  }
-}
-
-function flagLabel(spec: OptionSpec): string {
-  const alias = spec.alias ? `-${spec.alias}, ` : "";
-  const value =
-    spec.kind === "boolean" ? "" : ` ${spec.placeholder ?? "<value>"}`;
-  return `${alias}--${spec.name}${value}`;
-}
-
-function renderOptionLines(specs: readonly OptionSpec[]): string[] {
-  const labels = specs.map((spec) => flagLabel(spec));
-  const width = labels.reduce(
-    (widest, label) => Math.max(widest, label.length),
-    0,
-  );
-  return specs.map((spec, index) => {
-    const label = (labels[index] ?? "").padEnd(width);
-    const environment = spec.env ? ` [${spec.env}]` : "";
-    return `  ${label}  ${spec.description}${environment}`;
-  });
-}
-
-export function renderHelp(command: Command = "help"): string {
-  const lines: string[] = [];
-
-  if (command === "help") {
-    lines.push(
-      "Terminal Commands CLI",
-      "",
-      "Usage:",
-      "  terminal-commands <command> [options]",
-      "  npm run cli -- <command> [options]",
-      "",
-      "Commands:",
-    );
-    for (const [name, summary] of Object.entries(COMMAND_SUMMARIES)) {
-      lines.push(`  ${name.padEnd(9)}${summary}`);
-    }
-    lines.push("", "Options:", ...renderOptionLines(OPTIONS));
-  } else {
-    const relevant = OPTIONS.filter((option) =>
-      option.commands.includes(command),
-    );
-    lines.push(
-      `terminal-commands ${command} - ${COMMAND_SUMMARIES[command]}`,
-      "",
-      "Usage:",
-      `  terminal-commands ${command} [options]`,
-      "",
-    );
-    if (relevant.length > 0)
-      lines.push("Options:", ...renderOptionLines(relevant));
-    else lines.push("This command takes no options.");
-  }
-
-  lines.push(
-    "",
-    "Each option also reads the environment variable in brackets. A flag beats the",
-    "environment, and the environment beats the default. Use --no-<option> to turn an",
-    "on/off option back off when the environment sets it.",
-    "",
-    "Examples:",
-    "  terminal-commands connect --root ~/Documents/GitHub --root ~/work",
-    "  terminal-commands connect --root . --dry-run",
-    "  terminal-commands connect --root ~/code --name laptop --allow-destructive",
-    "  npm run cli -- connect --root ~/Documents/GitHub --allowed-program git,node",
-  );
-
-  return lines.join("\n");
-}