terminal-commands 0.1.1

package/test/agent-core.test.ts

@@ -0,0 +1,37 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { authorizeToolCall } from "../src/agent-core.js";
+
+test("allows read-only tools without an approval callback", async () => {
+  await authorizeToolCall("read_text_file", { path: "notes.txt" }, false);
+});
+
+test("rejects destructive tools when local approval is disabled", async () => {
+  await assert.rejects(
+    authorizeToolCall("write_text_file", { path: "notes.txt" }, false),
+    /disabled unless explicitly enabled/,
+  );
+});
+
+test("requires and honors an explicit approval for destructive tools", async () => {
+  await assert.rejects(
+    authorizeToolCall("run_program", { program: "git" }, true),
+    /not approved/,
+  );
+  await assert.rejects(
+    authorizeToolCall(
+      "run_program",
+      { program: "git" },
+      true,
+      async () => false,
+    ),
+    /not approved/,
+  );
+  await authorizeToolCall(
+    "run_program",
+    { program: "git" },
+    true,
+    async () => true,
+  );
+});

package/test/cli-options.test.ts

@@ -0,0 +1,121 @@
+import assert from "node:assert/strict";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  OPTIONS,
+  normalizeRoots,
+  optionEnvironment,
+  parseCommandLine,
+  renderHelp,
+} from "../src/cli-options.js";
+
+const delimited = (...values: string[]) => values.join(path.delimiter);
+
+test("collects repeated roots into the roots environment variable", () => {
+  const parsed = parseCommandLine([
+    "connect",
+    "--root",
+    "/tmp/a",
+    "--root=/tmp/b",
+  ]);
+  assert.equal(parsed.command, "connect");
+  assert.equal(
+    optionEnvironment(parsed).MACHINE_TERMINAL_ROOTS,
+    delimited("/tmp/a", "/tmp/b"),
+  );
+});
+
+test("splits a delimited root list passed to one flag", () => {
+  const parsed = parseCommandLine([
+    "connect",
+    "-r",
+    delimited("/tmp/a", "/tmp/b"),
+  ]);
+  assert.equal(
+    optionEnvironment(parsed).MACHINE_TERMINAL_ROOTS,
+    delimited("/tmp/a", "/tmp/b"),
+  );
+});
+
+test("collects an executable allowlist as a comma-delimited list", () => {
+  const parsed = parseCommandLine([
+    "connect",
+    "--allowed-program",
+    "git,node",
+    "--allowed-program",
+    "rg",
+  ]);
+  assert.equal(
+    optionEnvironment(parsed).MACHINE_TERMINAL_ALLOWED_PROGRAMS,
+    "git,node,rg",
+  );
+});
+
+test("maps on/off options to 1 and 0", () => {
+  const on = parseCommandLine(["connect", "--allow-destructive"]);
+  const off = parseCommandLine(["connect", "--no-allow-shell"]);
+  assert.equal(on.options.get("allow-destructive"), true);
+  assert.equal(
+    optionEnvironment(on).MACHINE_TERMINAL_AGENT_ALLOW_DESTRUCTIVE,
+    "1",
+  );
+  assert.equal(optionEnvironment(off).MACHINE_TERMINAL_ALLOW_SHELL, "0");
+});
+
+test("keeps the last value of a single-value option", () => {
+  const parsed = parseCommandLine([
+    "connect",
+    "--name",
+    "first",
+    "--name",
+    "second",
+  ]);
+  assert.equal(
+    optionEnvironment(parsed).MACHINE_TERMINAL_DEVICE_NAME,
+    "second",
+  );
+});
+
+test("rejects unknown, misplaced, and incomplete options", () => {
+  assert.throws(
+    () => parseCommandLine(["connect", "--roots"]),
+    /Unknown option/,
+  );
+  assert.throws(
+    () => parseCommandLine(["logout", "--root", "/tmp"]),
+    /not available for `logout`/,
+  );
+  assert.throws(() => parseCommandLine(["connect", "--root"]), /needs a value/);
+  assert.throws(
+    () => parseCommandLine(["connect", "--root", "--name", "x"]),
+    /needs a value/,
+  );
+  assert.throws(() => parseCommandLine(["dance"]), /Unknown command/);
+  assert.throws(
+    () => parseCommandLine(["connect", "extra"]),
+    /Unexpected argument/,
+  );
+});
+
+test("defaults to help and supports per-command help", () => {
+  assert.equal(parseCommandLine([]).help, true);
+  const parsed = parseCommandLine(["connect", "--help"]);
+  assert.equal(parsed.command, "connect");
+  assert.equal(parsed.help, true);
+});
+
+test("normalizes roots to absolute, de-duplicated paths", () => {
+  const base = path.resolve(path.sep, "tmp", "work");
+  const roots = normalizeRoots(["b", "./b", path.join("a", "..", "b")], base);
+  assert.deepEqual(roots, [path.join(base, "b")]);
+});
+
+test("help lists every option with its environment variable", () => {
+  const help = renderHelp();
+  for (const option of OPTIONS) {
+    assert.ok(help.includes(`--${option.name}`), `missing --${option.name}`);
+    if (option.env)
+      assert.ok(help.includes(option.env), `missing ${option.env}`);
+  }
+});

package/test/credential-store.test.ts

@@ -0,0 +1,44 @@
+import assert from "node:assert/strict";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  clearCredentials,
+  credentialsPath,
+  loadCredentials,
+  loadOrCreateDeviceId,
+  saveCredentials,
+} from "../src/credential-store.js";
+
+test("stores credentials privately and keeps a stable generated device id", async () => {
+  const temporary = await fs.mkdtemp(
+    path.join(os.tmpdir(), "terminal-commands-test-"),
+  );
+  const environment = { XDG_CONFIG_HOME: temporary };
+  try {
+    await saveCredentials(
+      {
+        accessToken: "secret",
+        expiresAt: Date.now() + 60_000,
+        issuer: "https://auth.example.test/",
+        audience: "https://mcp.example.test",
+      },
+      environment,
+    );
+    assert.equal((await loadCredentials(environment))?.accessToken, "secret");
+    if (process.platform !== "win32") {
+      assert.equal(
+        (await fs.stat(credentialsPath(environment))).mode & 0o777,
+        0o600,
+      );
+    }
+    const first = await loadOrCreateDeviceId(environment);
+    assert.equal(await loadOrCreateDeviceId(environment), first);
+    await clearCredentials(environment);
+    assert.equal(await loadCredentials(environment), null);
+  } finally {
+    await fs.rm(temporary, { recursive: true, force: true });
+  }
+});

package/test/device-auth.test.ts

@@ -0,0 +1,88 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  pollForDeviceToken,
+  refreshDeviceToken,
+  requestDeviceCode,
+  type DeviceAuthConfig,
+  type FetchLike,
+} from "../src/device-auth.js";
+
+const config: DeviceAuthConfig = {
+  issuer: "https://auth.example.test/",
+  clientId: "public-cli-client",
+  audience: "https://mcp.example.test",
+  scope: "terminal:connect offline_access",
+};
+
+test("starts device authorization with the configured audience and scope", async () => {
+  let submitted = "";
+  const fetchImpl: FetchLike = async (input, init) => {
+    assert.equal(String(input), "https://auth.example.test/oauth/device/code");
+    submitted = String(init?.body);
+    return new Response(
+      JSON.stringify({
+        device_code: "device-code",
+        user_code: "ABCD-EFGH",
+        verification_uri: "https://auth.example.test/activate",
+        expires_in: 600,
+        interval: 1,
+      }),
+      { status: 200 },
+    );
+  };
+  const result = await requestDeviceCode(config, fetchImpl);
+  assert.equal(result.user_code, "ABCD-EFGH");
+  assert.match(submitted, /audience=https%3A%2F%2Fmcp\.example\.test/);
+  assert.match(submitted, /terminal%3Aconnect/);
+});
+
+test("exchanges an approved device code without exposing tokens", async () => {
+  const fetchImpl: FetchLike = async () =>
+    new Response(
+      JSON.stringify({
+        access_token: "access-token",
+        refresh_token: "refresh-token",
+        expires_in: 3600,
+        token_type: "Bearer",
+      }),
+      { status: 200 },
+    );
+  const result = await pollForDeviceToken(
+    config,
+    "device-code",
+    10,
+    1,
+    undefined,
+    fetchImpl,
+  );
+  assert.equal(result.accessToken, "access-token");
+  assert.equal(result.refreshToken, "refresh-token");
+  assert.equal(result.issuer, config.issuer);
+  assert.equal(result.audience, config.audience);
+  assert.ok(result.expiresAt > Date.now());
+});
+
+test("refreshes an expired CLI access token", async () => {
+  let submitted = "";
+  const fetchImpl: FetchLike = async (_input, init) => {
+    submitted = String(init?.body);
+    return new Response(
+      JSON.stringify({ access_token: "new-token", expires_in: 900 }),
+      {
+        status: 200,
+      },
+    );
+  };
+  const result = await refreshDeviceToken(
+    config,
+    "old-refresh-token",
+    fetchImpl,
+  );
+  assert.equal(result.accessToken, "new-token");
+  assert.equal(result.refreshToken, "old-refresh-token");
+  assert.equal(result.issuer, config.issuer);
+  assert.equal(result.audience, config.audience);
+  assert.match(submitted, /grant_type=refresh_token/);
+});

package/test/runner.test.ts

@@ -0,0 +1,29 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { runProgram } from "../src/runner.js";
+
+test("runProgram captures stdout without a shell", async () => {
+  const result = await runProgram({
+    program: process.execPath,
+    args: ["-e", "process.stdout.write('ok')"],
+    cwd: process.cwd(),
+    timeoutMs: 5_000,
+    maxOutputChars: 10_000,
+  });
+  assert.equal(result.exitCode, 0);
+  assert.equal(result.stdout, "ok");
+  assert.equal(result.stderr, "");
+});
+
+test("runProgram reports non-zero exits", async () => {
+  const result = await runProgram({
+    program: process.execPath,
+    args: ["-e", "process.stderr.write('bad'); process.exit(7)"],
+    cwd: process.cwd(),
+    timeoutMs: 5_000,
+    maxOutputChars: 10_000,
+  });
+  assert.equal(result.exitCode, 7);
+  assert.equal(result.stderr, "bad");
+});

package/test/security.test.ts

@@ -0,0 +1,113 @@
+import assert from "node:assert/strict";
+import {
+  mkdtemp,
+  mkdir,
+  readFile,
+  rm,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+
+import {
+  assertProgramAllowed,
+  configuredRoots,
+  isWithinRoot,
+  resolveReadablePath,
+  resolveWritablePath,
+  safeEnvironment,
+} from "../src/security.js";
+
+test("configuredRoots resolves and deduplicates paths", () => {
+  const raw = [".", "."].join(path.delimiter);
+  assert.deepEqual(configuredRoots(raw), [process.cwd()]);
+});
+
+test("configuredRoots defaults to the launch directory", () => {
+  assert.deepEqual(configuredRoots(undefined), [process.cwd()]);
+});
+
+test("isWithinRoot rejects sibling prefix paths", () => {
+  assert.equal(isWithinRoot("/tmp/work", "/tmp/work"), true);
+  assert.equal(isWithinRoot("/tmp/work/file", "/tmp/work"), true);
+  assert.equal(isWithinRoot("/tmp/work-evil/file", "/tmp/work"), false);
+});
+
+test("safeEnvironment excludes secrets", () => {
+  const filtered = safeEnvironment({
+    PATH: "/bin",
+    OPENAI_API_KEY: "secret",
+    NPM_TOKEN: "secret",
+  });
+  assert.deepEqual(filtered, { PATH: "/bin" });
+});
+
+test("shells and privilege tools are blocked by default", () => {
+  const previous = process.env.MACHINE_TERMINAL_ALLOW_SHELL;
+  try {
+    delete process.env.MACHINE_TERMINAL_ALLOW_SHELL;
+    for (const program of ["bash", "sh", "sudo", "su", "zsh"]) {
+      assert.throws(
+        () => assertProgramAllowed(`/bin/${program}`),
+        /blocked by default/,
+      );
+    }
+  } finally {
+    if (previous === undefined) delete process.env.MACHINE_TERMINAL_ALLOW_SHELL;
+    else process.env.MACHINE_TERMINAL_ALLOW_SHELL = previous;
+  }
+});
+
+test("an explicit program allowlist is enforced", () => {
+  const previous = process.env.MACHINE_TERMINAL_ALLOWED_PROGRAMS;
+  process.env.MACHINE_TERMINAL_ALLOWED_PROGRAMS = "git,node";
+  assert.doesNotThrow(() => assertProgramAllowed("git"));
+  assert.throws(() => assertProgramAllowed("python3"), /not in/);
+  if (previous === undefined)
+    delete process.env.MACHINE_TERMINAL_ALLOWED_PROGRAMS;
+  else process.env.MACHINE_TERMINAL_ALLOWED_PROGRAMS = previous;
+});
+
+test("readable paths cannot escape configured roots", async () => {
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "terminal-commands-"));
+  const root = path.join(workspace, "root");
+  await writeFile(path.join(workspace, "outside.txt"), "outside");
+  await mkdir(root);
+  await writeFile(path.join(root, "inside.txt"), "inside");
+
+  try {
+    await assert.rejects(
+      resolveReadablePath("../outside.txt", [root], root),
+      /outside MACHINE_TERMINAL_ROOTS/,
+    );
+    assert.equal(
+      await readFile(
+        await resolveReadablePath("inside.txt", [root], root),
+        "utf8",
+      ),
+      "inside",
+    );
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+});
+
+test("writable paths reject symbolic links", async () => {
+  const workspace = await mkdtemp(path.join(os.tmpdir(), "terminal-commands-"));
+  const root = path.join(workspace, "root");
+  const target = path.join(workspace, "target.txt");
+  await mkdir(root);
+  await writeFile(target, "target");
+  await symlink(target, path.join(root, "link.txt"));
+
+  try {
+    await assert.rejects(
+      resolveWritablePath("link.txt", [root], root),
+      /symbolic links is not allowed/,
+    );
+  } finally {
+    await rm(workspace, { recursive: true, force: true });
+  }
+});

package/test/smoke.mjs

@@ -0,0 +1,34 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+const client = new Client({
+  name: "terminal-commands-smoke-test",
+  version: "0.1.0",
+});
+const transport = new StreamableHTTPClientTransport(
+  new URL("http://127.0.0.1:3333/mcp"),
+);
+
+try {
+  await client.connect(transport);
+  const tools = await client.listTools();
+  const expected = [
+    "get_system_info",
+    "list_directory",
+    "read_text_file",
+    "run_program",
+    "write_text_file",
+  ];
+  const actual = tools.tools.map((tool) => tool.name).sort();
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error(`Unexpected tools: ${actual.join(", ")}`);
+  }
+  const result = await client.callTool({
+    name: "get_system_info",
+    arguments: {},
+  });
+  if (result.isError) throw new Error("get_system_info returned an error");
+  console.log(`MCP smoke test passed; discovered ${actual.length} tools.`);
+} finally {
+  await client.close();
+}

package/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noUncheckedIndexedAccess": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src/**/*.ts", "test/**/*.ts"]
+}