terminal-commands 0.1.1

package/src/cli.ts

@@ -0,0 +1,475 @@
+#!/usr/bin/env node
+import { spawn, type ChildProcess } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import os from "node:os";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+
+import { runAgent } from "./agent-core.js";
+import { loadAgentConfig } from "./agent-config.js";
+import {
+  assertRootsExist,
+  normalizeRoots,
+  optionEnvironment,
+  parseCommandLine,
+  renderHelp,
+  splitRootList,
+  type ParsedCommandLine,
+} from "./cli-options.js";
+import {
+  bold,
+  danger,
+  dim,
+  heading,
+  info,
+  keyValueBlock,
+  muted,
+  ok,
+  warn,
+} from "./cli-format.js";
+import {
+  clearCredentials,
+  configDirectory,
+  loadCredentials,
+  loadOrCreateDeviceId,
+  saveCredentials,
+} from "./credential-store.js";
+import {
+  pollForDeviceToken,
+  refreshDeviceToken,
+  requestDeviceCode,
+  type DeviceAuthConfig,
+  type StoredCredentials,
+} from "./device-auth.js";
+
+const DEFAULTS = {
+  issuer: "https://auth.terminalcommands.fr/",
+  clientId: "ggauJpZPhb1e6qsqUVX2bW7k0V5PdR9B",
+  audience: "https://mcp.terminalcommands.fr",
+  gatewayUrl: "wss://mcp.terminalcommands.fr/device/connect",
+  host: "127.0.0.1",
+  port: "3333",
+} as const;
+
+const LOOPBACK = new Set(["127.0.0.1", "::1", "localhost"]);
+const WILDCARD = new Set(["0.0.0.0", "::"]);
+
+interface Settings {
+  readonly deviceName: string;
+  readonly roots: string[];
+  readonly rootsAreDefault: boolean;
+  readonly host: string;
+  readonly port: number;
+  readonly localUrl: string;
+  readonly gatewayUrl: string;
+  readonly allowDestructive: boolean;
+  readonly autoApprove: boolean;
+  readonly allowShell: boolean;
+  readonly allowedPrograms: string[];
+  readonly allowPublicBind: boolean;
+}
+
+function resolveAuth(environment: NodeJS.ProcessEnv): DeviceAuthConfig {
+  return {
+    issuer: environment.MACHINE_TERMINAL_AUTH_ISSUER ?? DEFAULTS.issuer,
+    clientId: environment.MACHINE_TERMINAL_AUTH_CLIENT_ID ?? DEFAULTS.clientId,
+    audience: environment.MACHINE_TERMINAL_AUTH_AUDIENCE ?? DEFAULTS.audience,
+    scope: "openid profile email offline_access terminal:connect",
+  };
+}
+
+function urlHost(host: string): string {
+  if (WILDCARD.has(host)) return "127.0.0.1";
+  return host.includes(":") ? `[${host}]` : host;
+}
+
+function resolveSettings(environment: NodeJS.ProcessEnv): Settings {
+  const port = Number.parseInt(
+    environment.MACHINE_TERMINAL_PORT ?? DEFAULTS.port,
+    10,
+  );
+  if (!Number.isInteger(port) || port < 1 || port > 65_535) {
+    throw new Error("--port must be a TCP port between 1 and 65535.");
+  }
+
+  const requested = splitRootList(environment.MACHINE_TERMINAL_ROOTS);
+  const rootsAreDefault = requested.length === 0;
+  const host = environment.MACHINE_TERMINAL_HOST ?? DEFAULTS.host;
+  const autoApprove = environment.MACHINE_TERMINAL_AUTO_APPROVE === "1";
+
+  return {
+    deviceName: environment.MACHINE_TERMINAL_DEVICE_NAME ?? os.hostname(),
+    roots: normalizeRoots(rootsAreDefault ? [process.cwd()] : requested),
+    rootsAreDefault,
+    host,
+    port,
+    localUrl: `http://${urlHost(host)}:${port}`,
+    gatewayUrl: environment.MACHINE_TERMINAL_GATEWAY_URL ?? DEFAULTS.gatewayUrl,
+    allowDestructive:
+      autoApprove ||
+      environment.MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE === "1",
+    autoApprove,
+    allowShell: environment.MACHINE_TERMINAL_ALLOW_SHELL === "1",
+    allowedPrograms: (environment.MACHINE_TERMINAL_ALLOWED_PROGRAMS ?? "")
+      .split(",")
+      .map((value) => value.trim())
+      .filter(Boolean),
+    allowPublicBind: environment.MACHINE_TERMINAL_ALLOW_PUBLIC_BIND === "1",
+  };
+}
+
+function assertBindable(settings: Settings): void {
+  if (LOOPBACK.has(settings.host) || settings.allowPublicBind) return;
+  throw new Error(
+    `--host ${settings.host} would expose the local service beyond this machine. Keep the default 127.0.0.1, or add --allow-public-bind only behind authenticated HTTPS.`,
+  );
+}
+
+function describeSettings(settings: Settings, deviceId: string): string {
+  const approvedRoots = settings.roots.map((root) => `  ${muted("-")} ${root}`);
+  if (settings.rootsAreDefault) {
+    approvedRoots.push(
+      muted("  (no --root given, so only the current directory is approved)"),
+    );
+  }
+
+  const commandsWrites = settings.autoApprove
+    ? danger("auto-approved without prompting (--auto-approve)") +
+      dim(" — every request runs unattended, only use with a trusted client")
+    : settings.allowDestructive
+      ? warn("ask in this terminal each time")
+      : ok("refused") +
+        dim(
+          " (add --allow-destructive to approve interactively, or --auto-approve to skip prompts)",
+        );
+
+  const shellPrograms = settings.allowShell
+    ? danger("allowed (--allow-shell)") +
+      dim(" — shells and privilege tools such as sudo can run")
+    : ok("blocked") +
+      dim(
+        " (add --allow-shell to permit shells and privilege tools such as sudo)",
+      );
+
+  const programAllowlist =
+    settings.allowedPrograms.length > 0
+      ? ok(`only ${settings.allowedPrograms.join(", ")}`) +
+        dim(" (--allowed-program)")
+      : warn("any program that is not blocked") +
+        dim(
+          " (add --allowed-program <name> to restrict to specific executables)",
+        );
+
+  return [
+    heading("Terminal Commands"),
+    "",
+    bold("Device"),
+    keyValueBlock([
+      ["Name", settings.deviceName],
+      ["ID", deviceId],
+    ]),
+    "",
+    bold("Network"),
+    keyValueBlock([
+      ["Gateway", settings.gatewayUrl],
+      ["Local MCP", `${settings.localUrl}/mcp`],
+    ]),
+    "",
+    bold("Approved roots"),
+    approvedRoots.join("\n"),
+    "",
+    bold("Security"),
+    keyValueBlock([
+      ["Commands, writes", commandsWrites],
+      ["Shell programs", shellPrograms],
+      ["Program allowlist", programAllowlist],
+    ]),
+  ].join("\n");
+}
+
+function approvalSummary(tool: string, args: Record<string, unknown>): string {
+  if (tool === "write_text_file") {
+    const bytes = Buffer.byteLength(String(args.contents ?? ""));
+    return `Write ${bytes} bytes to ${String(args.path ?? "an unknown path")}${args.overwrite ? " (overwrite)" : ""}`;
+  }
+  if (tool === "run_program") {
+    const command = [
+      String(args.program ?? ""),
+      ...(Array.isArray(args.args) ? args.args.map(String) : []),
+    ];
+    return `Run: ${command.join(" ")}`;
+  }
+  return `Run destructive tool: ${tool}`;
+}
+
+function createAutoApprover() {
+  return (tool: string, args: Record<string, unknown>): Promise<boolean> => {
+    console.log(
+      `\n${warn("Approval requested:")} ${approvalSummary(tool, args)} ${dim("(auto-approved)")}`,
+    );
+    return Promise.resolve(true);
+  };
+}
+
+function createTerminalApprover() {
+  let queue = Promise.resolve(false);
+  return (tool: string, args: Record<string, unknown>): Promise<boolean> => {
+    queue = queue
+      .catch(() => false)
+      .then(async () => {
+        if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+        const prompt = createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        });
+        try {
+          console.log(
+            `\n${warn("Approval requested:")} ${approvalSummary(tool, args)}`,
+          );
+          const answer = await prompt.question(
+            `${bold("Approve this action?")} [y/N] `,
+          );
+          return new Set(["y", "yes"]).has(answer.trim().toLowerCase());
+        } finally {
+          prompt.close();
+        }
+      });
+    return queue;
+  };
+}
+
+async function login(environment: NodeJS.ProcessEnv): Promise<void> {
+  const auth = resolveAuth(environment);
+  const code = await requestDeviceCode(auth);
+  console.log(`\n${bold("Open this address in any browser:")}`);
+  console.log(info(code.verification_uri_complete ?? code.verification_uri));
+  console.log(`\n${bold("One-time code:")} ${info(code.user_code)}`);
+  console.log(dim("\nWaiting for approval..."));
+  const credentials = await pollForDeviceToken(
+    auth,
+    code.device_code,
+    code.expires_in,
+    code.interval,
+  );
+  await saveCredentials(credentials);
+  console.log(
+    `${ok("Signed in.")} Run \`terminal-commands connect\` to connect this machine.`,
+  );
+}
+
+async function validCredentials(
+  auth: DeviceAuthConfig,
+): Promise<StoredCredentials> {
+  const current = await loadCredentials();
+  if (!current)
+    throw new Error("Not signed in. Run `terminal-commands login` first.");
+  if (current.issuer !== auth.issuer || current.audience !== auth.audience) {
+    throw new Error(
+      "Saved login belongs to a different Terminal Commands server. Run `terminal-commands login` again.",
+    );
+  }
+  if (current.expiresAt > Date.now() + 60_000) return current;
+  if (!current.refreshToken)
+    throw new Error("Login expired. Run `terminal-commands login` again.");
+  const refreshed = await refreshDeviceToken(auth, current.refreshToken);
+  await saveCredentials(refreshed);
+  return refreshed;
+}
+
+async function waitForHealth(url: string, child: ChildProcess): Promise<void> {
+  const deadline = Date.now() + 10_000;
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null)
+      throw new Error("The local terminal service could not start.");
+    try {
+      const response = await fetch(url);
+      if (response.ok) return;
+    } catch {}
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  throw new Error("Timed out while starting the local terminal service.");
+}
+
+async function connect(
+  environment: NodeJS.ProcessEnv,
+  parsed: ParsedCommandLine,
+): Promise<void> {
+  const settings = resolveSettings(environment);
+  assertBindable(settings);
+  await assertRootsExist(settings.roots);
+
+  const deviceId =
+    environment.MACHINE_TERMINAL_DEVICE_ID ?? (await loadOrCreateDeviceId());
+  const asJson = parsed.options.get("json") === true;
+
+  if (parsed.options.get("dry-run") === true) {
+    console.log(
+      asJson
+        ? JSON.stringify({ ...settings, deviceId, dryRun: true }, null, 2)
+        : describeSettings(settings, deviceId),
+    );
+    return;
+  }
+
+  const auth = resolveAuth(environment);
+  const firstCredentials = await validCredentials(auth);
+
+  console.log(
+    asJson
+      ? JSON.stringify({ ...settings, deviceId }, null, 2)
+      : describeSettings(settings, deviceId),
+  );
+  if (
+    settings.allowDestructive &&
+    !settings.autoApprove &&
+    !(process.stdin.isTTY && process.stdout.isTTY)
+  ) {
+    console.error(
+      warn(
+        "Terminal Commands: approvals need an interactive terminal, so commands and file writes will still be refused here.",
+      ),
+    );
+  }
+
+  const childEnvironment: NodeJS.ProcessEnv = {
+    ...environment,
+    MACHINE_TERMINAL_HOST: settings.host,
+    MACHINE_TERMINAL_PORT: String(settings.port),
+    MACHINE_TERMINAL_ROOTS: settings.roots.join(path.delimiter),
+  };
+
+  const serverEntry = fileURLToPath(new URL("./index.js", import.meta.url));
+  const local = spawn(process.execPath, [serverEntry], {
+    env: childEnvironment,
+    stdio: ["ignore", "inherit", "inherit"],
+  });
+  const controller = new AbortController();
+  const stop = () => controller.abort();
+  process.once("SIGINT", stop);
+  process.once("SIGTERM", stop);
+
+  try {
+    await waitForHealth(`${settings.localUrl}/health`, local);
+    const config = loadAgentConfig({
+      ...childEnvironment,
+      MACHINE_TERMINAL_GATEWAY_URL: settings.gatewayUrl,
+      MACHINE_TERMINAL_DEVICE_TOKEN: firstCredentials.accessToken,
+      MACHINE_TERMINAL_DEVICE_ID: deviceId,
+      MACHINE_TERMINAL_DEVICE_NAME: settings.deviceName,
+      MACHINE_TERMINAL_LOCAL_MCP_URL: `${settings.localUrl}/mcp`,
+      MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE: settings.allowDestructive
+        ? "1"
+        : "0",
+    });
+    console.log(
+      `\n${ok("Connecting")} ${bold(config.MACHINE_TERMINAL_DEVICE_NAME)} securely. ${dim("Press Ctrl+C to stop.")}`,
+    );
+    await runAgent({
+      config,
+      signal: controller.signal,
+      getToken: async () => (await validCredentials(auth)).accessToken,
+      approve: settings.autoApprove
+        ? createAutoApprover()
+        : createTerminalApprover(),
+      log: (message) => console.error(`Terminal Commands: ${message}`),
+    });
+  } finally {
+    local.kill("SIGTERM");
+    process.removeListener("SIGINT", stop);
+    process.removeListener("SIGTERM", stop);
+  }
+}
+
+async function status(
+  environment: NodeJS.ProcessEnv,
+  parsed: ParsedCommandLine,
+): Promise<void> {
+  const auth = resolveAuth(environment);
+  const credentials = await loadCredentials();
+  const deviceId =
+    environment.MACHINE_TERMINAL_DEVICE_ID ?? (await loadOrCreateDeviceId());
+  const settings = resolveSettings(environment);
+
+  const payload = {
+    signedIn: credentials !== null,
+    deviceId,
+    deviceName: settings.deviceName,
+    tokenExpiresAt: credentials
+      ? new Date(credentials.expiresAt).toISOString()
+      : null,
+    issuer: auth.issuer,
+    audience: auth.audience,
+    gatewayUrl: settings.gatewayUrl,
+    localUrl: `${settings.localUrl}/mcp`,
+    roots: settings.roots,
+    rootsAreDefault: settings.rootsAreDefault,
+    configDirectory: configDirectory(),
+  };
+
+  if (parsed.options.get("json") === true) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+
+  const rootLines = payload.roots.map((root) => `  ${muted("-")} ${root}`);
+  if (payload.rootsAreDefault) {
+    rootLines.push(
+      muted(
+        "  (no --root or MACHINE_TERMINAL_ROOTS set, so this is the current directory)",
+      ),
+    );
+  }
+
+  console.log(
+    [
+      heading("Terminal Commands — Status"),
+      "",
+      bold("Account"),
+      keyValueBlock([
+        ["Signed in", payload.signedIn ? ok("yes") : danger("no")],
+        ["Device ID", payload.deviceId],
+        ["Device name", payload.deviceName],
+        ...(payload.tokenExpiresAt
+          ? ([["Token expires", payload.tokenExpiresAt]] as const)
+          : []),
+      ]),
+      "",
+      bold("Network"),
+      keyValueBlock([
+        ["Gateway", payload.gatewayUrl],
+        ["Config folder", payload.configDirectory],
+      ]),
+      "",
+      bold("Approved roots"),
+      rootLines.join("\n"),
+    ].join("\n"),
+  );
+}
+
+async function main(): Promise<void> {
+  const parsed = parseCommandLine(process.argv.slice(2));
+  if (parsed.help) {
+    console.log(renderHelp(parsed.command));
+    return;
+  }
+
+  const environment: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...optionEnvironment(parsed),
+  };
+
+  if (parsed.command === "login") return login(environment);
+  if (parsed.command === "connect") return connect(environment, parsed);
+  if (parsed.command === "status") return status(environment, parsed);
+  if (parsed.command === "logout") {
+    await clearCredentials();
+    console.log(ok("Signed out and removed locally saved credentials."));
+    return;
+  }
+  console.log(renderHelp());
+}
+
+void main().catch((error) => {
+  console.error(danger(error instanceof Error ? error.message : String(error)));
+  process.exitCode = 1;
+});

package/src/credential-store.ts

@@ -0,0 +1,98 @@
+import { promises as fs } from "node:fs";
+import { randomUUID } from "node:crypto";
+import os from "node:os";
+import path from "node:path";
+
+import { z } from "zod";
+
+import type { StoredCredentials } from "./device-auth.js";
+
+const storedSchema = z.object({
+  accessToken: z.string().min(1),
+  refreshToken: z.string().min(1).optional(),
+  expiresAt: z.number().int().positive(),
+  scope: z.string().optional(),
+  tokenType: z.string().optional(),
+  issuer: z.string().url(),
+  audience: z.string().min(1),
+});
+
+export function configDirectory(
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  if (process.platform === "win32") {
+    return path.join(
+      environment.APPDATA ?? path.join(os.homedir(), "AppData", "Roaming"),
+      "Terminal Commands",
+    );
+  }
+  return path.join(
+    environment.XDG_CONFIG_HOME ?? path.join(os.homedir(), ".config"),
+    "terminal-commands",
+  );
+}
+
+export function credentialsPath(
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  return path.join(configDirectory(environment), "credentials.json");
+}
+
+export async function saveCredentials(
+  credentials: StoredCredentials,
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  const directory = configDirectory(environment);
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const target = credentialsPath(environment);
+  const temporary = `${target}.${process.pid}.tmp`;
+  await fs.writeFile(temporary, `${JSON.stringify(credentials)}\n`, {
+    mode: 0o600,
+  });
+  await fs.rename(temporary, target);
+  if (process.platform !== "win32") await fs.chmod(target, 0o600);
+}
+
+export async function loadCredentials(
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<StoredCredentials | null> {
+  try {
+    return storedSchema.parse(
+      JSON.parse(await fs.readFile(credentialsPath(environment), "utf8")),
+    );
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+export async function clearCredentials(
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<void> {
+  try {
+    await fs.unlink(credentialsPath(environment));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export async function loadOrCreateDeviceId(
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<string> {
+  const directory = configDirectory(environment);
+  const target = path.join(directory, "device-id");
+  try {
+    const value = (await fs.readFile(target, "utf8")).trim();
+    if (value) return value;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+  await fs.mkdir(directory, { recursive: true, mode: 0o700 });
+  const value = randomUUID();
+  await fs
+    .writeFile(target, `${value}\n`, { mode: 0o600, flag: "wx" })
+    .catch(async (error) => {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    });
+  return (await fs.readFile(target, "utf8")).trim();
+}