terramend 0.2.0

package/src/commands/mcp.ts

@@ -0,0 +1,122 @@
+import { existsSync, statSync } from "node:fs";
+import { isAbsolute, resolve } from "node:path";
+import arg from "arg";
+import { startLocalMcpServer } from "#app/mcp/localServer";
+import { setLogSink } from "#app/utils/log";
+
+const SEVERITIES = ["critical", "high", "medium", "low", "info"] as const;
+type SeverityFlag = (typeof SEVERITIES)[number];
+
+const SCAN_SCOPES = ["full", "diff"] as const;
+type ScanScopeFlag = (typeof SCAN_SCOPES)[number];
+
+function isSeverity(value: string): value is SeverityFlag {
+  return (SEVERITIES as readonly string[]).includes(value);
+}
+
+function isScanScope(value: string): value is ScanScopeFlag {
+  return (SCAN_SCOPES as readonly string[]).includes(value);
+}
+
+interface McpCliParams {
+  args: string[];
+  prog: string;
+  showHelp?: boolean;
+}
+
+function printMcpUsage(params: { stream: typeof console.log; prog: string }): void {
+  params.stream(`usage: ${params.prog} mcp [options]\n`);
+  params.stream("start the local MCP server (stdio) exposing terramend's read-only");
+  params.stream("terraform tools — scan, validate, verify, plan, version currency,");
+  params.stream("modules, provider schema, roots — to MCP clients like Claude Code,");
+  params.stream("Cursor, or Windsurf. example registration:");
+  params.stream("  claude mcp add terramend -- npx -y terramend mcp");
+  params.stream("");
+  params.stream("options:");
+  params.stream("  --cwd <dir>                   workspace to operate on (default: current dir)");
+  params.stream(`  --severity-threshold <sev>    minimum severity (${SEVERITIES.join("|")})`);
+  params.stream("  --scan-scope <scope>          full (default) or diff (vs base branch)");
+  params.stream("  --module-catalogue <list>     approved modules to prefer (comma/newline-sep)");
+  params.stream("  -h, --help                    show help");
+}
+
+function parseMcpArgs(args: string[]) {
+  return arg(
+    {
+      "--help": Boolean,
+      "--cwd": String,
+      "--severity-threshold": String,
+      "--scan-scope": String,
+      "--module-catalogue": String,
+      "-h": "--help",
+    },
+    { argv: args },
+  );
+}
+
+export async function runMcpCli(params: McpCliParams): Promise<void> {
+  if (params.showHelp) {
+    printMcpUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  let parsed: ReturnType<typeof parseMcpArgs>;
+  try {
+    parsed = parseMcpArgs(params.args);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`${message}\n`);
+    printMcpUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  if (parsed["--help"]) {
+    printMcpUsage({ stream: console.log, prog: params.prog });
+    return;
+  }
+
+  if (parsed._.length > 0) {
+    console.error(`unexpected positional arguments for mcp: ${parsed._.join(" ")}\n`);
+    printMcpUsage({ stream: console.error, prog: params.prog });
+    process.exit(1);
+  }
+
+  const rawCwd = parsed["--cwd"];
+  let cwd = process.cwd();
+  if (rawCwd) {
+    cwd = isAbsolute(rawCwd) ? rawCwd : resolve(process.cwd(), rawCwd);
+  }
+  if (!existsSync(cwd) || !statSync(cwd).isDirectory()) {
+    console.error(`--cwd is not a directory: ${cwd}`);
+    process.exit(1);
+  }
+
+  const severityRaw = parsed["--severity-threshold"];
+  if (severityRaw !== undefined && !isSeverity(severityRaw)) {
+    console.error(
+      `invalid --severity-threshold: ${severityRaw} (expected ${SEVERITIES.join("|")})`,
+    );
+    process.exit(1);
+  }
+  const scopeRaw = parsed["--scan-scope"];
+  if (scopeRaw !== undefined && !isScanScope(scopeRaw)) {
+    console.error(`invalid --scan-scope: ${scopeRaw} (expected ${SCAN_SCOPES.join("|")})`);
+    process.exit(1);
+  }
+
+  // stdout is the JSON-RPC channel from here on — every diagnostic goes to stderr.
+  setLogSink("stderr");
+
+  const server = await startLocalMcpServer({
+    cwd,
+    severityThreshold: severityRaw,
+    scanScope: scopeRaw,
+    moduleCatalogue: parsed["--module-catalogue"],
+  });
+
+  const shutdown = (): void => {
+    void server.stop().finally(() => process.exit(0));
+  };
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}

package/src/config.ts

@@ -0,0 +1 @@
+// action-level constants shared across the action runtime

package/src/entry.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+
+import { runTerramendCli } from "#app/runCli";
+
+runTerramendCli({
+  cliArgs: ["gha"],
+});

package/src/entryPost.stdlibOnly.test.ts

@@ -0,0 +1,109 @@
+import { readFileSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { describe, expect, it } from "vitest";
+
+// The GHA `post:` hook runs `node action/entryPost.ts` directly against the
+// rsynced action checkout, which deliberately excludes `node_modules`. Any
+// non-relative / non-`node:` import in entryPost.ts (or in its transitive
+// imports) crashes the post-step with `ERR_MODULE_NOT_FOUND` AFTER the agent
+// already exited 0, flipping the workflow to `failure`. see #834.
+//
+// This test parses the static-import graph rooted at entryPost.ts and refuses
+// any specifier that isn't one of:
+//   - node:* (stdlib)
+//   - ./* or ../* (relative)
+//   - #app/* or #package.json (local subpath imports — resolve to ./src/* and
+//     ./package.json via the package.json `imports` map, which ships in the
+//     action checkout; no `node_modules` needed)
+//
+// Any other specifier (`@actions/core`, `terramend`, `zod`, etc.) means the
+// post-hook will need a `node_modules` tree the rsync drops.
+
+const ENTRY_FILE = resolve(import.meta.dirname, "entryPost.ts");
+// `#app/*` maps to `./src/*` (see package.json imports); entryPost.ts lives in src/.
+const SRC_ROOT = import.meta.dirname;
+
+const IMPORT_RE = /^\s*(?:import|export)(?:\s+(?:type\s+)?[\s\S]*?)?\s+from\s+["']([^"']+)["']/gm;
+const SIDE_EFFECT_RE = /^\s*import\s+["']([^"']+)["']/gm;
+// `import.meta.glob` and friends are not used in entryPost.ts; the simple
+// regex above is sufficient here. expand if a transitive dep starts using
+// dynamic imports for stdlib-only logic.
+
+function extractImports(filePath: string): string[] {
+  const source = readFileSync(filePath, "utf8");
+  const specs: string[] = [];
+  for (const re of [IMPORT_RE, SIDE_EFFECT_RE]) {
+    re.lastIndex = 0;
+    for (const m of source.matchAll(re)) specs.push(m[1]!);
+  }
+  return specs;
+}
+
+function isAllowed(spec: string): boolean {
+  return (
+    spec.startsWith("node:") ||
+    spec.startsWith("./") ||
+    spec.startsWith("../") ||
+    spec.startsWith("#app/") ||
+    spec === "#package.json"
+  );
+}
+
+type WalkResult = {
+  visited: Set<string>;
+  violations: { file: string; spec: string }[];
+};
+
+function walk(start: string): WalkResult {
+  const visited = new Set<string>();
+  const violations: WalkResult["violations"] = [];
+  const queue: string[] = [start];
+
+  while (queue.length > 0) {
+    const file = queue.shift()!;
+    if (visited.has(file)) continue;
+    visited.add(file);
+
+    for (const spec of extractImports(file)) {
+      if (!isAllowed(spec)) {
+        violations.push({ file, spec });
+        continue;
+      }
+      if (spec.startsWith("node:") || spec === "#package.json") continue;
+      const resolved = spec.startsWith("#app/")
+        ? resolve(SRC_ROOT, spec.slice("#app/".length))
+        : resolve(dirname(file), spec);
+      const candidate = resolved.endsWith(".ts") ? resolved : `${resolved}.ts`;
+      try {
+        readFileSync(candidate, "utf8");
+        queue.push(candidate);
+      } catch {
+        // non-.ts (e.g. JSON `with { type: "json" }`) — already classified
+        // as relative-allowed above. nothing further to walk.
+      }
+    }
+  }
+  return { visited, violations };
+}
+
+describe("entryPost.ts stdlib-only invariant (#834)", () => {
+  it("only imports node: builtins and relative siblings (no node_modules deps)", () => {
+    const result = walk(ENTRY_FILE);
+    expect(result.violations, JSON.stringify(result.violations, null, 2)).toEqual([]);
+  });
+
+  it("walks the full transitive graph (entryPost + 3 utils)", () => {
+    const result = walk(ENTRY_FILE);
+    expect(result.visited.size).toBeGreaterThanOrEqual(4);
+  });
+
+  it("matches the modules entryPost actually imports today", () => {
+    const direct = extractImports(ENTRY_FILE).sort();
+    expect(direct).toEqual([
+      "#app/utils/codexRefreshDetect",
+      "#app/utils/ghaCore",
+      "#app/utils/postApiFetch",
+      "node:fs",
+    ]);
+  });
+});

package/src/entryPost.ts

@@ -0,0 +1,99 @@
+#!/usr/bin/env node
+//
+// GitHub Actions `post:` entry point. Runs after the main step regardless of
+// exit status (cancellation, timeout, unhandled error) — that's the contract
+// we need for credential persistence: if OpenCode refreshed the Codex
+// auth.json during the run, the refreshed token must land back in Terramend
+// even when the main step died unexpectedly.
+//
+// THIS IS WHY `CODEX_AUTH_JSON` HAS TO LIVE IN TERRAMEND'S OWN SECRET STORE,
+// NOT IN GITHUB ACTIONS SECRETS. The refresh chain rotates on every use; this
+// hook PUTs the rotated chain back to Terramend Postgres so the next run starts
+// from a fresh token. GH Actions secrets are read-only at runtime — there is
+// no API to write them back from inside a job — so a token stashed there
+// silently goes stale on the first refresh and the next run fails. See
+// wiki/codex-auth.md.
+//
+// Today's only job: detect a Codex auth refresh by diffing the on-disk
+// auth.json against the original refresh token (saved to GH Actions state
+// by src/agents/opencode.ts), convert OpenCode's auth shape
+// back to Codex CLI shape, and PUT it to /api/runtime/secret.
+//
+// Silent no-op when the main step didn't materialize Codex auth (no state
+// saved). Best-effort: failures are logged but never throw — the workflow
+// is already done, and a missed refresh write-back means the user re-runs
+// `terramend auth codex` next time the chain breaks.
+//
+// Imports here MUST stay stdlib-only — GHA runs this file directly from the
+// checked-out action repo, which has no node_modules for sha-pinned consumers.
+
+import { existsSync, readFileSync } from "node:fs";
+import { detectCodexRefresh } from "#app/utils/codexRefreshDetect";
+import * as core from "#app/utils/ghaCore";
+import { postApiFetch } from "#app/utils/postApiFetch";
+
+async function main(): Promise<void> {
+  const raw = core.getState("codex_writeback");
+  if (!raw) {
+    core.info("codex post-hook: no writeback state — skipping");
+    return;
+  }
+
+  let state: { apiToken: string; authPath: string; originalRefresh: string };
+  try {
+    state = JSON.parse(raw) as typeof state;
+  } catch (err) {
+    core.warning(`codex post-hook: malformed writeback state — ${err}`);
+    return;
+  }
+  if (!state.apiToken || !state.authPath || !state.originalRefresh) {
+    core.warning("codex post-hook: incomplete writeback state — skipping");
+    return;
+  }
+
+  if (!existsSync(state.authPath)) {
+    core.info(`codex post-hook: ${state.authPath} not found — nothing to write back`);
+    return;
+  }
+
+  let authFileContent: string;
+  try {
+    authFileContent = readFileSync(state.authPath, "utf8");
+  } catch (err) {
+    core.warning(`codex post-hook: cannot read ${state.authPath} — ${err}`);
+    return;
+  }
+
+  const refreshedCodexJson = detectCodexRefresh({
+    authFileContent,
+    originalRefresh: state.originalRefresh,
+  });
+  if (!refreshedCodexJson) {
+    core.info("codex post-hook: refresh chain unchanged — no writeback needed");
+    return;
+  }
+
+  try {
+    const response = await postApiFetch({
+      path: "/api/runtime/secret",
+      method: "PUT",
+      headers: {
+        authorization: `Bearer ${state.apiToken}`,
+        "content-type": "application/json",
+      },
+      body: JSON.stringify({ name: "CODEX_AUTH_JSON", value: refreshedCodexJson }),
+    });
+    if (!response.ok) {
+      const body = await response.text().catch(() => "");
+      core.warning(`codex post-hook: writeback returned ${response.status}: ${body}`);
+      return;
+    }
+    core.info("codex post-hook: refreshed CODEX_AUTH_JSON persisted to Terramend");
+  } catch (err) {
+    core.warning(`codex post-hook: writeback failed — ${err}`);
+  }
+}
+
+main().catch((err) => {
+  core.warning(`codex post-hook: unexpected error — ${err}`);
+});

package/src/external.test.ts

@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+import { formatMcpToolRef, terramendMcpName } from "#app/external";
+
+describe("formatMcpToolRef", () => {
+  it("formats claude tool refs with the mcp__ prefix", () => {
+    expect(formatMcpToolRef("claude", "select_mode")).toBe("mcp__terramend__select_mode");
+  });
+
+  it("formats opencode tool refs with the server-name prefix", () => {
+    expect(formatMcpToolRef("opencode", "select_mode")).toBe("terramend_select_mode");
+  });
+
+  it("uses the shared mcp server name constant", () => {
+    expect(formatMcpToolRef("claude", "push_branch")).toBe(`mcp__${terramendMcpName}__push_branch`);
+  });
+});

package/src/external.ts

@@ -0,0 +1,302 @@
+/**
+ * ⚠️ LIMITED IMPORTS - this file is imported by Next.js and must avoid pulling in backend code.
+ * All shared constants, types, and data used by both the Next.js app and the action runtime live here.
+ * Other files in action/ re-export from this file for backward compatibility.
+ */
+
+import type { PullRequest } from "@octokit/webhooks-types";
+
+// mcp name constant
+export const terramendMcpName = "terramend";
+
+/** @see {@link file://./agents/shared.ts} Agent interface that uses this type */
+export type AgentId = "claude" | "opencode";
+
+/**
+ * format a tool name the way each agent's MCP client presents it to the model.
+ * claude code: mcp__terramend__select_mode
+ * opencode:    terramend_select_mode
+ */
+export function formatMcpToolRef(agentId: AgentId, toolName: string): string {
+  switch (agentId) {
+    case "claude":
+      return `mcp__${terramendMcpName}__${toolName}`;
+    case "opencode":
+      return `${terramendMcpName}_${toolName}`;
+    default:
+      return agentId satisfies never;
+  }
+}
+
+// model alias registry lives in models.ts — re-exported here for shared access
+export type { ModelAlias, ModelProvider, ProviderConfig } from "#app/models";
+export {
+  DEFAULT_PROXY_MODEL,
+  getAutoSelectHintModel,
+  getModelEnvVars,
+  getModelManagedCredentials,
+  getModelProvider,
+  getProviderDisplayName,
+  modelAliases,
+  parseModel,
+  providers,
+  resolveCliModel,
+  resolveDisplayAlias,
+  resolveModelSlug,
+  resolveOpenRouterModel,
+} from "#app/models";
+
+// tool permission types shared with server dispatch
+export type ToolPermission = "disabled" | "enabled";
+export type ShellPermission = "disabled" | "restricted" | "enabled";
+export type PushPermission = "disabled" | "restricted" | "enabled";
+
+// workflow yml permissions for GITHUB_TOKEN
+export type WorkflowPermissionValue = "read" | "write" | "none";
+export type WorkflowIdTokenPermissionValue = "write" | "none";
+
+export interface WorkflowPermissions {
+  actions?: WorkflowPermissionValue;
+  attestations?: WorkflowPermissionValue;
+  checks?: WorkflowPermissionValue;
+  contents?: WorkflowPermissionValue;
+  deployments?: WorkflowPermissionValue;
+  discussions?: WorkflowPermissionValue;
+  "id-token"?: WorkflowIdTokenPermissionValue;
+  issues?: WorkflowPermissionValue;
+  models?: WorkflowPermissionValue;
+  packages?: WorkflowPermissionValue;
+  pages?: WorkflowPermissionValue;
+  "pull-requests"?: WorkflowPermissionValue;
+  "repository-projects"?: WorkflowPermissionValue;
+  "security-events"?: WorkflowPermissionValue;
+  statuses?: WorkflowPermissionValue;
+}
+
+// permission level for the author who triggered the event
+// matches GitHub's permission levels: admin > write > maintain > triage > read > none
+export type AuthorPermission = "admin" | "maintain" | "write" | "triage" | "read" | "none";
+
+// base interface for common payload event fields
+interface BasePayloadEvent {
+  issue_number?: number;
+  is_pr?: boolean;
+  branch?: string;
+  /** title of the issue/PR (or contextual title for comments) */
+  title?: string;
+  /** primary content for this trigger (issue body, PR body, comment body, review body, etc.) */
+  body?: string | null;
+  comment_id?: number;
+  review_id?: number;
+  review_state?: string;
+  /** GraphQL review-thread context (shape owned by the backend producer; not read in-action) */
+  thread?: unknown;
+  pull_request?: PullRequest;
+  check_suite?: {
+    id: number;
+    head_sha: string;
+    head_branch: string | null;
+    status: string | null;
+    conclusion: string | null;
+    url: string;
+  };
+  comment_ids?: number[] | "all";
+  /** permission level of the user who triggered this event */
+  authorPermission?: AuthorPermission;
+  /** when true, runs silently without progress comments (e.g., auto-labeling) */
+  silent?: boolean;
+  [key: string]: unknown;
+}
+
+interface PullRequestOpenedEvent extends BasePayloadEvent {
+  trigger: "pull_request_opened";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  body: string | null;
+  branch: string;
+}
+
+interface PullRequestReadyForReviewEvent extends BasePayloadEvent {
+  trigger: "pull_request_ready_for_review";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  body: string | null;
+  branch: string;
+}
+
+interface PullRequestReviewRequestedEvent extends BasePayloadEvent {
+  trigger: "pull_request_review_requested";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  body: string | null;
+  branch: string;
+}
+
+interface PullRequestReviewSubmittedEvent extends BasePayloadEvent {
+  trigger: "pull_request_review_submitted";
+  issue_number: number;
+  is_pr: true;
+  review_id: number;
+  /** review body is the primary content */
+  body: string | null;
+  review_state: string;
+  branch: string;
+}
+
+interface PullRequestReviewCommentCreatedEvent extends BasePayloadEvent {
+  trigger: "pull_request_review_comment_created";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  comment_id: number;
+  /** comment body is the primary content (null if already in prompt) */
+  body: string | null;
+  thread?: unknown;
+  branch: string;
+}
+
+interface IssuesOpenedEvent extends BasePayloadEvent {
+  trigger: "issues_opened";
+  issue_number: number;
+  title: string;
+  body: string | null;
+}
+
+interface IssuesAssignedEvent extends BasePayloadEvent {
+  trigger: "issues_assigned";
+  issue_number: number;
+  title: string;
+  body: string | null;
+}
+
+interface IssuesLabeledEvent extends BasePayloadEvent {
+  trigger: "issues_labeled";
+  issue_number: number;
+  title: string;
+  body: string | null;
+}
+
+interface IssueCommentCreatedEvent extends BasePayloadEvent {
+  trigger: "issue_comment_created";
+  comment_id: number;
+  /** distinguishes this from PR review comments (which use pull_request_review_comment_created) */
+  comment_type: "issue";
+  /** comment body is the primary content (null if already in prompt) */
+  body: string | null;
+  issue_number: number;
+  // PR-specific fields (only present when is_pr is true)
+  is_pr?: true;
+  branch?: string;
+  title?: string;
+}
+
+interface CheckSuiteCompletedEvent extends BasePayloadEvent {
+  trigger: "check_suite_completed";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  body: string | null;
+  pull_request: PullRequest;
+  branch: string;
+  check_suite: {
+    id: number;
+    head_sha: string;
+    head_branch: string | null;
+    status: string | null;
+    conclusion: string | null;
+    url: string;
+  };
+}
+
+interface WorkflowDispatchEvent extends BasePayloadEvent {
+  trigger: "workflow_dispatch";
+}
+
+interface FixReviewEvent extends BasePayloadEvent {
+  trigger: "fix_review";
+  issue_number: number;
+  is_pr: true;
+  review_id: number;
+  /** when true, only address comments the triggerer approved with 👍 (vs all comments) */
+  approved_only?: boolean | undefined;
+}
+
+interface ImplementPlanEvent extends BasePayloadEvent {
+  trigger: "implement_plan";
+  issue_number: number;
+  plan_comment_id: number;
+  /** plan content is the primary content (null if already in prompt) */
+  body: string | null;
+}
+
+interface PullRequestSynchronizeEvent extends BasePayloadEvent {
+  trigger: "pull_request_synchronize";
+  issue_number: number;
+  is_pr: true;
+  title: string;
+  body: string | null;
+  branch: string;
+  /** SHA before the push -- used to compute incremental range-diff between PR versions */
+  before_sha: string;
+}
+
+interface UnknownEvent extends BasePayloadEvent {
+  trigger: "unknown";
+}
+
+// discriminated union for payload event based on trigger
+// note: all events use issue_number for consistency (PRs are issues in GitHub's API)
+export type PayloadEvent =
+  | PullRequestOpenedEvent
+  | PullRequestReadyForReviewEvent
+  | PullRequestSynchronizeEvent
+  | PullRequestReviewRequestedEvent
+  | PullRequestReviewSubmittedEvent
+  | PullRequestReviewCommentCreatedEvent
+  | IssuesOpenedEvent
+  | IssuesAssignedEvent
+  | IssuesLabeledEvent
+  | IssueCommentCreatedEvent
+  | CheckSuiteCompletedEvent
+  | WorkflowDispatchEvent
+  | FixReviewEvent
+  | ImplementPlanEvent
+  | UnknownEvent;
+
+// writeable payload type for building payloads
+export interface WriteablePayload {
+  "~terramend": true;
+  /** semantic version of the payload to ensure compatibility */
+  version: string;
+  /** provider/model slug (e.g. "anthropic/claude-opus") */
+  model?: string | undefined;
+  /** the user's actual request (body if @terramend tagged) */
+  prompt: string;
+  /** github username of the human who triggered this workflow run */
+  triggerer?: string | undefined;
+  /** event-level instructions for this trigger type (flag-expanded server-side) */
+  eventInstructions?: string | undefined;
+  /**
+   * system-injected note about prior superseded runs (e.g. when the
+   * triggering @terramend comment is edited). rendered alongside the user's
+   * prompt rather than via eventInstructions so it survives user-prompt
+   * precedence.
+   */
+  previousRunsNote?: string | undefined;
+  /** event data from webhook payload - discriminated union based on trigger field */
+  event: PayloadEvent;
+  /** timeout for agent run (e.g., "10m", "1h30m") - defaults to "1h" */
+  timeout?: string | undefined;
+  /** working directory for the agent */
+  cwd?: string | undefined;
+  /** pre-created progress comment (ID + type) for updating status */
+  progressComment?: { id: string; type: "issue" | "review" } | undefined;
+  /** when true, seed the PR summary tmpfile + persist edits at run end */
+  generateSummary?: boolean | undefined;
+}
+
+// immutable payload type for agent execution
+export type Payload = Readonly<WriteablePayload>;

package/src/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Library entry point for npm package
+ * This exports the main function for programmatic usage
+ */
+
+export type { Agent, AgentResult, AgentRunContext } from "#app/agents/shared";
+export {
+  type Inputs as ExecutionInputs,
+  type MainResult,
+  main,
+} from "#app/main";