terramend 0.2.0

package/src/utils/setup.ts

@@ -0,0 +1,352 @@
+import { execFileSync, execSync } from "node:child_process";
+import { mkdtempSync, readdirSync, realpathSync, unlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { ShellPermission } from "#app/external";
+import type { ToolState } from "#app/toolState";
+import { log } from "#app/utils/cli";
+import type { OctokitWithPlugins } from "#app/utils/github";
+import { isInsideDocker } from "#app/utils/globals";
+import { $ } from "#app/utils/shell";
+
+export interface SetupOptions {
+  tempDir: string;
+}
+
+/**
+ * Create a shared temp directory for the action
+ */
+export function createTempDirectory(): string {
+  const sharedTempDir = mkdtempSync(join(tmpdir(), "terramend-"));
+  process.env.TERRAMEND_TEMP_DIR = sharedTempDir;
+  log.info(`» created temp dir at ${sharedTempDir}`);
+  return sharedTempDir;
+}
+
+/**
+ * snapshot-and-delete the GHA runner's known credential leak surfaces inside
+ * `$RUNNER_TEMP` before the agent spawns. without this, a shell-capable agent
+ * can grep:
+ *   - `_runner_file_commands/set_output_*` for `core.setOutput('token', ghs_…)`
+ *     calls made by earlier composite-action steps (e.g.
+ *     terramend/terramend/get-installation-token);
+ *   - `<uuid>.sh` rendered step scripts whose `run: |` body embeds
+ *     `${{ steps.token.outputs.token }}` literally (GHA expands BEFORE writing);
+ *   - `git-credentials-*.config` written by `actions/checkout@v6` for the
+ *     workflow GITHUB_TOKEN.
+ *
+ * the running bash process already has its own `.sh` open via fd, so the
+ * unlink is safe — `unlink` removes the dirent, the kernel keeps reading.
+ *
+ * preserves every `_runner_file_commands/` file path the runner pre-allocated
+ * for OUR step — `$GITHUB_OUTPUT`, `$GITHUB_ENV`, `$GITHUB_PATH`,
+ * `$GITHUB_STATE`, `$GITHUB_STEP_SUMMARY`. those are read by the runner
+ * AFTER we exit (or by our own `post:` hook), and wiping them would break
+ * terramend's `result` output, `post:` state handoff, and job summary.
+ *
+ * silent no-op when `$RUNNER_TEMP` is unset (local dev, `pnpm dev:run`).
+ * per-file errors are tolerated — the runner may delete files between
+ * our readdir and our unlink.
+ */
+export function wipeRunnerLeakSurface(): void {
+  const runnerTemp = process.env.RUNNER_TEMP;
+  if (!runnerTemp) return;
+
+  const preserve = new Set<string>();
+  for (const envVar of [
+    "GITHUB_OUTPUT",
+    "GITHUB_ENV",
+    "GITHUB_PATH",
+    "GITHUB_STATE",
+    "GITHUB_STEP_SUMMARY",
+  ]) {
+    const path = process.env[envVar];
+    if (!path) continue;
+    try {
+      preserve.add(realpathSync(path));
+    } catch {
+      // path may not exist yet — preserve the literal in case it gets created later
+      preserve.add(path);
+    }
+  }
+
+  const wiped: string[] = [];
+
+  const tryUnlink = (path: string): void => {
+    let resolved = path;
+    try {
+      resolved = realpathSync(path);
+    } catch {
+      // file may already be gone — fall through to unlink for the race-tolerant path
+    }
+    if (preserve.has(resolved) || preserve.has(path)) return;
+    try {
+      unlinkSync(path);
+      wiped.push(path);
+    } catch {
+      // race-tolerant: file may have been deleted between readdir and unlink
+    }
+  };
+
+  const listDir = (dir: string): string[] => {
+    try {
+      return readdirSync(dir);
+    } catch {
+      return [];
+    }
+  };
+
+  const fileCommandsDir = join(runnerTemp, "_runner_file_commands");
+  for (const entry of listDir(fileCommandsDir)) {
+    tryUnlink(join(fileCommandsDir, entry));
+  }
+
+  for (const entry of listDir(runnerTemp)) {
+    if (entry.endsWith(".sh") || /^git-credentials-.*\.config$/.test(entry)) {
+      tryUnlink(join(runnerTemp, entry));
+    }
+  }
+
+  if (wiped.length > 0) {
+    log.info(`» wiped ${wiped.length} leak-surface file(s) from $RUNNER_TEMP`);
+    log.debug(`» wiped paths: ${wiped.join(", ")}`);
+  }
+}
+
+/**
+ * Setup the test repository for running actions
+ */
+export function setupTestRepo(options: SetupOptions): void {
+  const tempDir = options.tempDir;
+  const repo = process.env.GITHUB_REPOSITORY;
+  if (!repo) throw new Error("GITHUB_REPOSITORY is required");
+  log.info(`» cloning ${repo} into ${tempDir}...`);
+
+  // use https with token in ci or when running inside docker
+  if (process.env.CI || isInsideDocker) {
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN;
+    if (!token) {
+      throw new Error("GITHUB_TOKEN or GH_TOKEN is required for https clone in ci or docker");
+    }
+    $("git", ["clone", `https://x-access-token:${token}@github.com/${repo}.git`, tempDir]);
+  } else {
+    $("git", ["clone", `git@github.com:${repo}.git`, tempDir]);
+  }
+}
+
+/**
+ * build an env suitable for targeting a specific git repo via `cwd`.
+ *
+ * inherited GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE override cwd resolution,
+ * which matters when this code runs as a child of `git push` (pre-push hook)
+ * or inside another git subcommand. if we don't strip them, a call that
+ * names `repoDir` in cwd silently operates on the outer repo instead.
+ */
+function envScopedToRepo(): NodeJS.ProcessEnv {
+  const scoped = { ...process.env };
+  for (const key of Object.keys(scoped)) {
+    if (key.startsWith("GIT_")) delete scoped[key];
+  }
+  return scoped;
+}
+
+/**
+ * remove any `[includeIf ...]` entries from the local git config so that
+ * actions/checkout-persisted credentials don't ride alongside ASKPASS-provided
+ * auth for subsequent git operations.
+ *
+ * SECURITY: git config subsection values can contain arbitrary characters
+ * including `$(...)` command substitutions, and `${IFS}` spacing tricks defeat
+ * naive split-on-space filtering. we read keys via the `-z` (null-terminated)
+ * output format and feed them to a spawn-array `git config --unset-all` so
+ * the shell never interpolates key contents — closing the RCE path that a
+ * string-interpolated `execSync(...)` would expose.
+ */
+export function removeIncludeIfEntries(repoDir: string): void {
+  const env = envScopedToRepo();
+  let configOutput: string;
+  try {
+    configOutput = execSync("git config --local --get-regexp -z ^includeif\\.", {
+      cwd: repoDir,
+      encoding: "utf-8",
+      stdio: "pipe",
+      env,
+    });
+  } catch {
+    log.debug("» no includeIf credential entries to remove");
+    return;
+  }
+  const seen = new Set<string>();
+  for (const entry of configOutput.split("\0")) {
+    if (!entry) continue;
+    // -z format: each entry is "<key>\n<value>". the key is up to the first newline.
+    const nl = entry.indexOf("\n");
+    const key = nl === -1 ? entry : entry.slice(0, nl);
+    if (!key || seen.has(key)) continue;
+    seen.add(key);
+    try {
+      // execFileSync (not execSync) so the key — which can contain arbitrary
+      // characters including shell metacharacters and $() command substitutions
+      // — is passed as an argv element and never interpolated by a shell.
+      // this is the load-bearing side of a9aa3b2b's injection fix.
+      execFileSync("git", ["config", "--local", "--unset-all", key], {
+        cwd: repoDir,
+        stdio: "pipe",
+        env,
+      });
+    } catch (error) {
+      log.debug(
+        `» failed to unset ${key}: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+  }
+  if (seen.size > 0)
+    log.info(
+      `» removed ${seen.size} includeIf credential ${seen.size === 1 ? "entry" : "entries"}`,
+    );
+}
+
+export interface GitContext {
+  gitToken: string;
+  owner: string;
+  name: string;
+  octokit: OctokitWithPlugins;
+  toolState: ToolState;
+  // shell permission level — controls hook and security behavior:
+  //   enabled: full shell, hooks run, no restrictions
+  //   restricted: MCP shell in stripped env, hooks run, token protection on auth ops
+  //   disabled: no shell, hooks disabled globally, all code execution paths blocked
+  shell: ShellPermission;
+  postCheckoutScript: string | null;
+}
+
+export type SetupGitParams = GitContext;
+
+/**
+ * setup git configuration and authentication for the repository.
+ * - configures git identity (user.email, user.name)
+ * - sets up authentication via gitToken (minimal contents:write)
+ *
+ * gitToken is a minimal-permission token (contents + workflows) used for git operations.
+ * it is assumed to be potentially exfiltratable, so it has limited scope.
+ */
+export async function setupGit(params: SetupGitParams): Promise<void> {
+  const repoDir = process.cwd();
+
+  // 1. configure git identity
+  log.info("» setting up git configuration...");
+  try {
+    // check current config - only set defaults if not configured or using generic bot
+    let currentEmail = "";
+    try {
+      currentEmail = execSync("git config user.email", {
+        cwd: repoDir,
+        stdio: "pipe",
+        encoding: "utf-8",
+      }).trim();
+    } catch {
+      // not configured
+    }
+
+    const shouldSetDefaults =
+      !currentEmail || currentEmail === "github-actions[bot]@users.noreply.github.com";
+
+    if (shouldSetDefaults) {
+      // plain noreply email with no numeric account id — the upstream id
+      // resolved commits to the wrong bot account on GitHub.
+      execSync('git config --local user.email "terramend[bot]@users.noreply.github.com"', {
+        cwd: repoDir,
+        stdio: "pipe",
+      });
+      execSync('git config --local user.name "terramend[bot]"', {
+        cwd: repoDir,
+        stdio: "pipe",
+      });
+      log.debug("» git user configured (using defaults)");
+    } else {
+      log.debug(`» git user already configured (${currentEmail}), skipping`);
+    }
+
+    // SECURITY: disable git hooks when shell is disabled to prevent code execution.
+    // in restricted mode, hooks run in the stripped sandbox — that's fine.
+    // in enabled mode, the agent has full shell anyway.
+    // in disabled mode, hooks are the primary code-execution escape vector.
+    if (params.shell === "disabled") {
+      execSync("git config --local core.hooksPath /dev/null", {
+        cwd: repoDir,
+        stdio: "pipe",
+      });
+      log.debug("» git hooks disabled (shell=disabled)");
+    }
+  } catch (error) {
+    // If git config fails, log warning but don't fail the action
+    // This can happen if we're not in a git repo or git isn't available
+    log.info(`Failed to set git config: ${error instanceof Error ? error.message : String(error)}`);
+  }
+
+  // 2. setup authentication
+  // remove existing git auth headers that actions/checkout might have set
+  try {
+    execSync("git config --local --unset-all http.https://github.com/.extraheader", {
+      cwd: repoDir,
+      stdio: "pipe",
+    });
+    log.info("» removed existing authentication headers");
+  } catch {
+    log.debug("» no existing authentication headers to remove");
+  }
+
+  // remove includeIf entries that actions/checkout@v6 uses for credential persistence.
+  // v6 stores credentials in an external file loaded via includeIf.gitdir, which our
+  // --unset-all above doesn't catch. without this, stale credentials from actions/checkout
+  // would be sent alongside ASKPASS-provided credentials.
+  removeIncludeIfEntries(repoDir);
+
+  // SECURITY: set origin URL without token - auth is injected via GIT_ASKPASS
+  // in $git() calls. this prevents token leakage to git hooks and subprocesses.
+  const originUrl = `https://github.com/${params.owner}/${params.name}.git`;
+  $("git", ["remote", "set-url", "origin", originUrl], { cwd: repoDir });
+
+  // initialize pushUrl to base repo - may be updated by checkout_pr for fork PRs
+  params.toolState.pushUrl = originUrl;
+
+  // disable credential helpers to prevent prompts and ensure clean auth state
+  $("git", ["config", "--local", "credential.helper", ""], { cwd: repoDir });
+
+  // pin the run-entry HEAD for the checkout_pr initial-branch invariant; see
+  // captureInitialHead for the named-branch vs detached split and why it
+  // matters (zed-industries/cloud 2026-05-18 cross-PR clobber shape).
+  params.toolState.initialHead = captureInitialHead(repoDir);
+
+  log.info("» git authentication configured");
+}
+
+/**
+ * snapshot the current HEAD as either a branch name (when on a named branch)
+ * or a literal SHA (when detached). used by setupGit to pin the run-entry
+ * position and by checkout_pr to compare the live HEAD against it.
+ *
+ * splitting the two cases is load-bearing: `git rev-parse --abbrev-ref HEAD`
+ * returns the sentinel string `"HEAD"` on detached entry — which is the
+ * default `actions/checkout` state for `pull_request` events. storing that
+ * raw string would make any future detached state (including a subagent's
+ * `git checkout --detach <sha>`) compare equal.
+ */
+export function captureInitialHead(
+  repoDir: string,
+): { kind: "branch"; name: string } | { kind: "detached"; sha: string } {
+  try {
+    const name = $("git", ["symbolic-ref", "--short", "HEAD"], {
+      cwd: repoDir,
+      log: false,
+    }).trim();
+    if (name) return { kind: "branch", name };
+  } catch {
+    // detached HEAD — fall through
+  }
+  const sha = $("git", ["rev-parse", "HEAD"], {
+    cwd: repoDir,
+    log: false,
+  }).trim();
+  return { kind: "detached", sha };
+}

package/src/utils/shell.ts

@@ -0,0 +1,103 @@
+import { spawnSync } from "node:child_process";
+import { type EnvMode, resolveEnv } from "#app/utils/secrets";
+
+interface ShellOptions {
+  cwd?: string;
+  encoding?:
+    | "utf-8"
+    | "utf8"
+    | "ascii"
+    | "base64"
+    | "base64url"
+    | "hex"
+    | "latin1"
+    | "ucs-2"
+    | "ucs2"
+    | "utf16le";
+  log?: boolean;
+  /**
+   * env mode: "restricted" (default) filters secrets, "inherit" passes full env,
+   * or provide a custom env object (merged with restricted base)
+   */
+  env?: EnvMode;
+  onError?: (result: { status: number; stdout: string; stderr: string }) => void;
+}
+
+/**
+ * Execute a shell command safely using spawnSync with argument arrays.
+ * Prevents shell injection by avoiding string interpolation in shell commands.
+ *
+ * SECURITY: by default, env vars are filtered to remove secrets (tokens, keys, passwords).
+ * this prevents malicious code (git hooks, npm scripts, etc.) from exfiltrating credentials.
+ * use env: "inherit" only when absolutely necessary.
+ *
+ * @param cmd - The command to execute
+ * @param args - Array of arguments to pass to the command
+ * @param options - Optional configuration (cwd, encoding, onError)
+ * @returns The trimmed stdout output
+ * @throws Error if command fails and no onError handler is provided
+ */
+export function $(cmd: string, args: string[], options?: ShellOptions): string {
+  const encoding = options?.encoding ?? "utf-8";
+  const env = resolveEnv(options?.env);
+
+  // CRITICAL: use "ignore" for stdin instead of "inherit" to avoid breaking MCP transport
+  // when running inside an MCP server, stdin is used for JSON-RPC protocol
+  const result = spawnSync(cmd, args, {
+    stdio: ["ignore", "pipe", "pipe"],
+    encoding,
+    cwd: options?.cwd,
+    env,
+  });
+
+  const stdout = result.stdout ?? "";
+  const stderr = result.stderr ?? "";
+
+  // Write output to process streams so it behaves like stdio: "inherit"
+  // CRITICAL: when running inside an MCP server, stdout is used for JSON-RPC protocol
+  // so we must write to stderr instead to avoid corrupting the protocol
+  // Only log if log option is not explicitly set to false
+  if (options?.log !== false) {
+    // if stdout is a TTY, it's safe to write to it; otherwise it's likely a pipe used for JSON-RPC
+    const canWriteToStdout = process.stdout.isTTY === true;
+    if (stdout) {
+      if (canWriteToStdout) {
+        process.stdout.write(stdout);
+      } else {
+        // stdout is a pipe (MCP context) - write to stderr instead
+        process.stderr.write(stdout);
+      }
+    }
+    if (stderr) {
+      process.stderr.write(stderr);
+    }
+  }
+
+  // Handle errors
+  if (result.status !== 0) {
+    const errorResult = {
+      status: result.status ?? -1,
+      stdout,
+      stderr,
+    };
+
+    if (options?.onError) {
+      options.onError(errorResult);
+      return stdout.trim();
+    }
+
+    // many git subcommands write context-bearing diagnostics to stdout, not
+    // stderr (merge conflicts, cherry-pick rejections, diff --exit-code,
+    // ls-files --error-unmatch). Falling back to "Unknown error" robbed the
+    // agent of any signal and forced an extra MCP round-trip. see #766.
+    const detail = [stderr, stdout]
+      .map((s) => s.trim())
+      .filter(Boolean)
+      .join("\n");
+    throw new Error(
+      `Command failed with exit code ${errorResult.status}: ${detail || "Unknown error"}`,
+    );
+  }
+
+  return stdout.trim();
+}

package/src/utils/skills.test.ts

@@ -0,0 +1,46 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, beforeEach, describe, expect, it, vi } from "vitest";
+import { installBundledSkills } from "#app/utils/skills";
+
+vi.mock("#app/utils/cli", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+import { log } from "#app/utils/cli";
+
+const successMock = vi.mocked(log.success);
+
+const TEMP = mkdtempSync(join(tmpdir(), "terramend-skills-"));
+
+afterAll(() => {
+  rmSync(TEMP, { recursive: true, force: true });
+});
+
+beforeEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("installBundledSkills", () => {
+  it("writes every bundled skill into all agent auto-scan dirs under HOME", () => {
+    const home = join(TEMP, "home");
+    installBundledSkills({ home });
+
+    const targets = [".opencode/skills", ".claude/skills", ".agents/skills"].map((dir) =>
+      join(home, dir, "terraform-best-practices", "SKILL.md"),
+    );
+    const contents = targets.map((path) => readFileSync(path, "utf8"));
+    for (const content of contents) {
+      expect(content.length).toBeGreaterThan(0);
+      expect(content).toBe(contents[0]);
+    }
+    expect(successMock).toHaveBeenCalledWith(expect.stringContaining("terraform-best-practices"));
+  });
+});

package/src/utils/skills.ts

@@ -0,0 +1,67 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { log } from "#app/utils/cli";
+
+/**
+ * skills bundled with the action runtime. the SKILL.md files live in
+ * `action/skills/<name>/SKILL.md` and are read at runtime — no esbuild loader,
+ * no codegen. this matters because the preview / oss path runs `cli.ts` from
+ * source (see `runCli.ts#runLocalCli`) where esbuild loaders don't apply.
+ */
+const BUNDLED_SKILL_NAMES = ["terraform-best-practices"] as const;
+
+/**
+ * resolve the on-disk path of a bundled SKILL.md by checking the two locations
+ * the file may live in:
+ *   - source mode (`runLocalCli`): `<actionRoot>/skills/<name>/SKILL.md`,
+ *     reached as `../skills/...` from `utils/skills.ts`.
+ *   - bundled mode (npx published package): `<distDir>/skills/<name>/SKILL.md`,
+ *     reached as `./skills/...` from `dist/cli.mjs`.
+ *
+ * the bundled-mode copy is produced by an esbuild post-build step in
+ * `esbuild.config.js`.
+ */
+function resolveSkillPath(name: string): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const candidates = [
+    join(here, "..", "skills", name, "SKILL.md"),
+    join(here, "skills", name, "SKILL.md"),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(`bundled skill not found: ${name} (looked in ${candidates.join(", ")})`);
+}
+
+/**
+ * each agent has its own auto-scan dir under HOME. we write to all of them so
+ * the same `installBundledSkills` call works regardless of which agent is
+ * running, without coupling skills.ts to agent identity.
+ *
+ * verified empirically (PR #565):
+ *   - OpenCode registers skills from `$HOME/.agents/skills/` and `.opencode/skills/`.
+ *   - Claude Code only registers skills from `$HOME/.claude/skills/` —
+ *     it does NOT scan `.agents/skills/`, so writing only there leaves the
+ *     skill on disk but invisible to Claude's `Skill` tool.
+ */
+const SKILL_TARGET_DIRS = [".opencode/skills", ".claude/skills", ".agents/skills"] as const;
+
+/**
+ * write all bundled skills into the fake HOME so OpenCode / Claude Code discover
+ * them via their auto-scan directories.
+ *
+ * called once per agent run from each agent's `run()`. cheap (small file
+ * writes), no network, idempotent.
+ */
+export function installBundledSkills(params: { home: string }): void {
+  for (const name of BUNDLED_SKILL_NAMES) {
+    const content = readFileSync(resolveSkillPath(name), "utf8");
+    for (const targetDir of SKILL_TARGET_DIRS) {
+      const skillDir = join(params.home, targetDir, name);
+      mkdirSync(skillDir, { recursive: true });
+      writeFileSync(join(skillDir, "SKILL.md"), content);
+    }
+  }
+  log.success(`installed bundled skills: ${BUNDLED_SKILL_NAMES.join(", ")}`);
+}