terminal-commands 0.1.1

package/src/cli-options.ts

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