terramend 0.2.0

package/src/cli.test.ts

@@ -0,0 +1,129 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { runCli as runGhaCli } from "#app/commands/gha";
+
+vi.mock("#app/commands/gha", () => ({ runCli: vi.fn(async () => {}) }));
+
+const ORIGINAL_ARGV = process.argv;
+
+type ConsoleSpy = { mock: { calls: unknown[][] } };
+
+let logSpy: ConsoleSpy;
+let errorSpy: ConsoleSpy;
+let exitSpy: { mock: { calls: unknown[][] } };
+
+/**
+ * cli.ts runs its command dispatch at module top level, so each scenario
+ * re-imports it with a fresh module registry and stubbed process.argv.
+ * `process.exit` is mocked to throw, which the module's own top-level catch
+ * converts into a second exit(1) — flows that exit therefore reject the
+ * dynamic import with "process.exit:1".
+ */
+async function importCli(argv: string[]): Promise<{ rejection: unknown }> {
+  process.argv = ["node", "/usr/local/bin/terramend", ...argv];
+  vi.resetModules();
+  try {
+    await import("#app/cli");
+    return { rejection: undefined };
+  } catch (error) {
+    return { rejection: error };
+  }
+}
+
+function loggedLines(spy: ConsoleSpy): string {
+  return spy.mock.calls.map((call) => call.join(" ")).join("\n");
+}
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  exitSpy = vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+    throw new Error(`process.exit:${code}`);
+  }) as never);
+});
+
+afterEach(() => {
+  process.argv = ORIGINAL_ARGV;
+  vi.unstubAllEnvs();
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+describe("cli entry", () => {
+  it("prints the version and exits 0 on --version", async () => {
+    vi.stubEnv("CLI_VERSION", "1.2.3");
+
+    const { rejection } = await importCli(["--version"]);
+
+    expect(logSpy).toHaveBeenCalledWith("1.2.3");
+    expect(exitSpy.mock.calls[0]).toEqual([0]);
+    expect(rejection).toBeInstanceOf(Error);
+  });
+
+  it("prints usage and exits 0 when no command is given", async () => {
+    await importCli([]);
+
+    expect(loggedLines(logSpy)).toContain("usage: terramend <command>");
+    expect(loggedLines(logSpy)).toContain("gha");
+    expect(exitSpy.mock.calls[0]).toEqual([0]);
+  });
+
+  it("prints the banner and usage on --help without a command", async () => {
+    await importCli(["--help"]);
+
+    expect(loggedLines(logSpy)).toContain("terramend");
+    expect(loggedLines(logSpy)).toContain("usage: terramend <command>");
+    expect(exitSpy.mock.calls[0]).toEqual([0]);
+  });
+
+  it("prints usage and exits 0 on --help with an unknown command", async () => {
+    await importCli(["--help", "wat"]);
+
+    expect(loggedLines(logSpy)).toContain("usage: terramend <command>");
+    expect(exitSpy.mock.calls[0]).toEqual([0]);
+    expect(runGhaCli).not.toHaveBeenCalled();
+  });
+
+  it("dispatches the gha command with its arguments", async () => {
+    const { rejection } = await importCli(["gha", "token", "--post"]);
+
+    expect(rejection).toBeUndefined();
+    expect(runGhaCli).toHaveBeenCalledWith({
+      args: ["token", "--post"],
+      prog: "terramend",
+      showHelp: false,
+    });
+    expect(exitSpy).not.toHaveBeenCalled();
+  });
+
+  it("forwards showHelp to the gha command on --help gha", async () => {
+    const { rejection } = await importCli(["--help", "gha"]);
+
+    expect(rejection).toBeUndefined();
+    expect(runGhaCli).toHaveBeenCalledWith({ args: [], prog: "terramend", showHelp: true });
+  });
+
+  it("errors with usage on an unknown command", async () => {
+    await importCli(["frobnicate"]);
+
+    expect(loggedLines(errorSpy)).toContain("unknown command:");
+    expect(loggedLines(errorSpy)).toContain("usage: terramend <command>");
+    expect(exitSpy.mock.calls[0]).toEqual([1]);
+  });
+
+  it("errors with usage on an unknown global option", async () => {
+    await importCli(["--bogus"]);
+
+    expect(loggedLines(errorSpy)).toContain("unknown or unexpected option: --bogus");
+    expect(exitSpy.mock.calls[0]).toEqual([1]);
+  });
+
+  it("reports command failures via the top-level catch and exits 1", async () => {
+    vi.mocked(runGhaCli).mockRejectedValueOnce(new Error("gha blew up"));
+
+    const { rejection } = await importCli(["gha"]);
+
+    expect(loggedLines(errorSpy)).toContain("gha blew up");
+    expect(exitSpy.mock.calls[0]).toEqual([1]);
+    expect(rejection).toBeInstanceOf(Error);
+  });
+});

package/src/cli.ts

@@ -0,0 +1,105 @@
+import { basename } from "node:path";
+import arg from "arg";
+import pc from "picocolors";
+import { runCli as runGhaCli } from "#app/commands/gha";
+import { runMcpCli } from "#app/commands/mcp";
+
+const VERSION = process.env.CLI_VERSION ?? "0.0.0";
+const bin = basename(process.argv[1] || "");
+const PROG = bin === "pf" || bin === "terramend" ? bin : "terramend";
+const rawArgs = process.argv.slice(2);
+
+function printMainUsage(stream: typeof console.log): void {
+  stream(`usage: ${PROG} <command>\n`);
+  stream("commands:");
+  stream("  gha         run the github action runtime flow (used by action.yml)");
+  stream("  mcp         start the local MCP server (stdio) with read-only terraform tools");
+  stream("");
+  stream("global options:");
+  stream("  -h, --help      show help");
+  stream("  -v, --version   show version");
+}
+
+function parseGlobalArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--version": Boolean,
+      "-h": "--help",
+      "-v": "--version",
+    },
+    {
+      argv: args,
+      stopAtPositional: true,
+    },
+  );
+}
+
+function exitWithUsageError(message: string): never {
+  console.error(`${message}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+async function run(): Promise<void> {
+  let globalParsed: ReturnType<typeof parseGlobalArgs>;
+  try {
+    globalParsed = parseGlobalArgs(rawArgs);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    exitWithUsageError(message);
+  }
+
+  if (globalParsed["--version"]) {
+    console.log(VERSION);
+    process.exit(0);
+  }
+
+  const command = globalParsed._[0];
+  const commandArgs = globalParsed._.slice(1);
+
+  if (!command) {
+    if (globalParsed["--help"]) {
+      console.log(`${pc.bold("terramend")} v${VERSION}\n`);
+      printMainUsage(console.log);
+      process.exit(0);
+    }
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  if (command === "gha") {
+    await runGhaCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (command === "mcp") {
+    await runMcpCli({
+      args: commandArgs,
+      prog: PROG,
+      showHelp: globalParsed["--help"] === true,
+    });
+    return;
+  }
+
+  if (globalParsed["--help"]) {
+    printMainUsage(console.log);
+    process.exit(0);
+  }
+
+  console.error(`unknown command: ${pc.bold(command)}\n`);
+  printMainUsage(console.error);
+  process.exit(1);
+}
+
+try {
+  await run();
+} catch (error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(pc.red(message));
+  process.exit(1);
+}

package/src/commands/gha.test.ts

@@ -0,0 +1,192 @@
+import { dirname } from "node:path";
+import * as core from "@actions/core";
+import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { main } from "#app/main";
+import { acquireInstallationToken, revokeInstallationToken } from "#app/utils/token";
+
+vi.mock("@actions/core", () => ({
+  getInput: vi.fn(() => ""),
+  getState: vi.fn(() => ""),
+  setFailed: vi.fn(),
+  setSecret: vi.fn(),
+  saveState: vi.fn(),
+  setOutput: vi.fn(),
+  info: vi.fn(),
+  debug: vi.fn(),
+}));
+vi.mock("#app/main", () => ({ main: vi.fn(async () => ({ success: true })) }));
+vi.mock("#app/utils/token", () => ({
+  acquireInstallationToken: vi.fn(async () => "inst-token"),
+  revokeInstallationToken: vi.fn(async () => {}),
+}));
+
+// gha.ts prepends the action runtime's node bin dir to PATH at import time —
+// import dynamically so the original PATH can be captured and restored.
+const SAVED_PATH = process.env.PATH;
+let gha: typeof import("#app/commands/gha");
+
+beforeAll(async () => {
+  gha = await import("#app/commands/gha");
+});
+
+afterAll(() => {
+  process.env.PATH = SAVED_PATH;
+});
+
+type ConsoleSpy = { mock: { calls: unknown[][] } };
+
+let logSpy: ConsoleSpy;
+let errorSpy: ConsoleSpy;
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, "log").mockImplementation(() => {});
+  errorSpy = vi.spyOn(console, "error").mockImplementation(() => {});
+  vi.spyOn(process, "exit").mockImplementation(((code?: number) => {
+    throw new Error(`process.exit:${code}`);
+  }) as never);
+});
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.clearAllMocks();
+});
+
+function loggedLines(spy: ConsoleSpy): string {
+  return spy.mock.calls.map((call) => call.join(" ")).join("\n");
+}
+
+describe("gha module import", () => {
+  it("prepends the action runtime's node bin dir to PATH", () => {
+    expect(process.env.PATH).toContain(dirname(process.execPath));
+  });
+});
+
+describe("runCli – help and arg handling", () => {
+  it("prints gha usage when showHelp is set", async () => {
+    await gha.runCli({ args: [], prog: "terramend", showHelp: true });
+
+    expect(loggedLines(logSpy)).toContain("usage: terramend gha [subcommand]");
+    expect(main).not.toHaveBeenCalled();
+  });
+
+  it("prints gha usage on --help", async () => {
+    await gha.runCli({ args: ["--help"], prog: "terramend" });
+
+    expect(loggedLines(logSpy)).toContain("usage: terramend gha [subcommand]");
+  });
+
+  it("errors with usage and exits 1 on an unknown option", async () => {
+    await expect(gha.runCli({ args: ["--bogus"], prog: "terramend" })).rejects.toThrow(
+      "process.exit:1",
+    );
+    expect(loggedLines(errorSpy)).toContain("usage: terramend gha [subcommand]");
+  });
+
+  it("errors and exits 1 on an unknown subcommand", async () => {
+    await expect(gha.runCli({ args: ["frobnicate"], prog: "terramend" })).rejects.toThrow(
+      "process.exit:1",
+    );
+    expect(loggedLines(errorSpy)).toContain("unknown gha subcommand: frobnicate");
+  });
+
+  it("runs the main action flow when no subcommand is given", async () => {
+    await gha.runCli({ args: [], prog: "terramend" });
+
+    expect(main).toHaveBeenCalledOnce();
+    expect(core.setFailed).not.toHaveBeenCalled();
+  });
+});
+
+describe("runCli – gha token", () => {
+  it("prints token usage on gha token --help", async () => {
+    await gha.runCli({ args: ["token", "--help"], prog: "terramend" });
+
+    expect(loggedLines(logSpy)).toContain("usage: terramend gha token [--post]");
+    expect(acquireInstallationToken).not.toHaveBeenCalled();
+  });
+
+  it("rejects unexpected positional arguments", async () => {
+    await expect(gha.runCli({ args: ["token", "extra"], prog: "terramend" })).rejects.toThrow(
+      "process.exit:1",
+    );
+    expect(loggedLines(errorSpy)).toContain("unexpected positional arguments for gha token: extra");
+  });
+
+  it("errors with token usage on an unknown token option", async () => {
+    await expect(gha.runCli({ args: ["token", "--bogus"], prog: "terramend" })).rejects.toThrow(
+      "process.exit:1",
+    );
+    expect(loggedLines(errorSpy)).toContain("usage: terramend gha token [--post]");
+  });
+
+  it("acquires a token scoped to the current repo by default", async () => {
+    await gha.runCli({ args: ["token"], prog: "terramend" });
+
+    expect(acquireInstallationToken).toHaveBeenCalledWith({ repos: [] });
+    expect(core.setSecret).toHaveBeenCalledWith("inst-token");
+    expect(core.saveState).toHaveBeenCalledWith("token", "inst-token");
+    expect(core.setOutput).toHaveBeenCalledWith("token", "inst-token");
+    expect(core.info).toHaveBeenCalledWith("» installation token acquired (current repo only)");
+  });
+
+  it("acquires a token for additional repos from the repos input", async () => {
+    vi.mocked(core.getInput).mockReturnValueOnce("octo/a, octo/b ,");
+
+    await gha.runCli({ args: ["token"], prog: "terramend" });
+
+    expect(acquireInstallationToken).toHaveBeenCalledWith({ repos: ["octo/a", "octo/b"] });
+    expect(core.info).toHaveBeenCalledWith(
+      "» installation token acquired (current repo + octo/a, octo/b)",
+    );
+  });
+
+  it("revokes the saved token in the post step", async () => {
+    vi.mocked(core.getState).mockReturnValueOnce("saved-token");
+
+    await gha.runCli({ args: ["token", "--post"], prog: "terramend" });
+
+    expect(revokeInstallationToken).toHaveBeenCalledWith("saved-token");
+    expect(core.info).toHaveBeenCalledWith("» installation token revoked");
+  });
+
+  it("skips revocation when no token was saved", async () => {
+    await gha.runCli({ args: ["token", "--post"], prog: "terramend" });
+
+    expect(revokeInstallationToken).not.toHaveBeenCalled();
+    expect(core.debug).toHaveBeenCalledWith("no token found in state, skipping revocation");
+  });
+});
+
+describe("run – failure reporting", () => {
+  it("setFailed when main reports an unsuccessful run", async () => {
+    vi.mocked(main).mockResolvedValueOnce({ success: false, error: "agent gave up" });
+
+    await gha.run([]);
+
+    expect(core.setFailed).toHaveBeenCalledWith("action failed: agent gave up");
+  });
+
+  it("setFailed with a fallback message when main fails without an error", async () => {
+    vi.mocked(main).mockResolvedValueOnce({ success: false });
+
+    await gha.run([]);
+
+    expect(core.setFailed).toHaveBeenCalledWith("action failed: agent execution failed");
+  });
+
+  it("setFailed when main throws", async () => {
+    vi.mocked(main).mockRejectedValueOnce(new Error("boom"));
+
+    await gha.run([]);
+
+    expect(core.setFailed).toHaveBeenCalledWith("action failed: boom");
+  });
+
+  it("setFailed when token acquisition throws", async () => {
+    vi.mocked(acquireInstallationToken).mockRejectedValueOnce(new Error("no app key"));
+
+    await gha.run(["token"]);
+
+    expect(core.setFailed).toHaveBeenCalledWith("no app key");
+  });
+});

package/src/commands/gha.ts

@@ -0,0 +1,188 @@
+import { dirname } from "node:path";
+import * as core from "@actions/core";
+import arg from "arg";
+import { main } from "#app/main";
+import { acquireInstallationToken, revokeInstallationToken } from "#app/utils/token";
+
+// GitHub Actions runs the action entry point with the node24 binary specified
+// in action.yml, but doesn't add that binary's directory to PATH. Without this,
+// spawned processes (pnpm, npm, etc.) resolve to the runner's default node (v20).
+process.env.PATH = `${dirname(process.execPath)}:${process.env.PATH}`;
+
+const STATE_TOKEN = "token";
+
+interface GhaCliParams {
+  args: string[];
+  prog: string;
+  showHelp?: boolean;
+}
+
+async function runMain(): Promise<void> {
+  try {
+    const result = await main();
+    if (!result.success) {
+      throw new Error(result.error || "agent execution failed");
+    }
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : "unknown error occurred";
+    core.setFailed(`action failed: ${errorMessage}`);
+  }
+}
+
+async function tokenMain(): Promise<void> {
+  const reposInput = core.getInput("repos");
+  const additionalRepos = reposInput
+    ? reposInput
+        .split(",")
+        .map((r) => r.trim())
+        .filter(Boolean)
+    : [];
+
+  const token = await acquireInstallationToken({ repos: additionalRepos });
+
+  core.setSecret(token);
+  core.saveState(STATE_TOKEN, token);
+  core.setOutput("token", token);
+
+  const scope = additionalRepos.length
+    ? `current repo + ${additionalRepos.join(", ")}`
+    : "current repo only";
+  core.info(`» installation token acquired (${scope})`);
+}
+
+async function tokenPost(): Promise<void> {
+  const token = core.getState(STATE_TOKEN);
+  if (!token) {
+    core.debug("no token found in state, skipping revocation");
+    return;
+  }
+  await revokeInstallationToken(token);
+  core.info("» installation token revoked");
+}
+
+function printGhaUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} gha [subcommand]\n`);
+  params.stream("run the github action runtime flow.");
+  params.stream("");
+  params.stream("subcommands:");
+  params.stream("  token        acquire a github app installation token");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+}
+
+function printGhaTokenUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} gha token [--post]\n`);
+  params.stream("acquire a github app installation token, or revoke it in the post step.");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  -h, --help   show help");
+  params.stream("  --post       revoke the previously-acquired token (post-step usage only)");
+}
+
+function parseGhaArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+      stopAtPositional: true,
+    },
+  );
+}
+
+function parseGhaTokenArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--post": Boolean,
+      "-h": "--help",
+    },
+    {
+      argv: args,
+    },
+  );
+}
+
+export async function runCli(params: GhaCliParams): Promise<void> {
+  if (params.showHelp) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  let parsed: ReturnType<typeof parseGhaArgs>;
+  try {
+    parsed = parseGhaArgs(params.args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--help"]) {
+    printGhaUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  const positional = parsed._;
+  const subcommand = positional[0];
+
+  if (!subcommand) {
+    await run(["gha"]);
+    return;
+  }
+
+  if (subcommand !== "token") {
+    console.error(`unknown gha subcommand: ${subcommand}\n`);
+    printGhaUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  // gha token [--post]
+  let tokenParsed: ReturnType<typeof parseGhaTokenArgs>;
+  try {
+    tokenParsed = parseGhaTokenArgs(positional.slice(1));
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printGhaTokenUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (tokenParsed["--help"]) {
+    printGhaTokenUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  if (tokenParsed._.length > 0) {
+    console.error(`unexpected positional arguments for gha token: ${tokenParsed._.join(" ")}\n`);
+    printGhaTokenUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  const normalizedArgs = ["gha", "token"];
+  if (tokenParsed["--post"]) {
+    normalizedArgs.push("--post");
+  }
+  await run(normalizedArgs);
+}
+
+export async function run(args: string[]) {
+  try {
+    if (args.includes("token")) {
+      if (args.includes("--post")) {
+        await tokenPost();
+      } else {
+        await tokenMain();
+      }
+    } else {
+      await runMain();
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    core.setFailed(message);
+  }
+}