terramend 0.2.0

package/src/utils/terraformMcp.ts

@@ -0,0 +1,83 @@
+/**
+ * HashiCorp terraform-mcp-server integration (P2.2).
+ *
+ * When the `terraform_mcp` input is on, the agent harness registers a SECOND
+ * MCP server next to terramend's: HashiCorp's terraform-mcp-server, run as a
+ * Docker container over stdio. It gives the fixing agent live Terraform
+ * Registry knowledge — current module versions, provider argument shapes —
+ * which directly powers module-source-aware fixes and generation.
+ *
+ * Security posture:
+ *   - the image is VERSION-PINNED (`TERRAFORM_MCP_IMAGE`); bump deliberately.
+ *     (P4's SHA-pinning sweep will move this to a digest pin.)
+ *   - only the read-only `registry` toolset is enabled — no TFE operations,
+ *     and no TFE_TOKEN is ever passed.
+ *   - degrades green: docker absent → a log note, never a failed run.
+ */
+
+import { spawnSync } from "node:child_process";
+import type { ResolvedPayload } from "#app/utils/payload";
+
+/** pinned release of hashicorp/terraform-mcp-server. Bump deliberately. */
+export const TERRAFORM_MCP_IMAGE = "hashicorp/terraform-mcp-server:0.5.2";
+
+/** the registry name the server is registered under in agent MCP configs —
+ * matches HashiCorp's own client-config examples, so agent guidance written
+ * against "the terraform MCP server" finds it under the expected key. */
+export const TERRAFORM_MCP_SERVER_NAME = "terraform";
+
+/** stdio invocation, registry toolset ONLY (module/provider knowledge — the
+ * agent must never get TFE workspace operations from this surface). */
+const TERRAFORM_MCP_DOCKER_ARGS = [
+  "run",
+  "-i",
+  "--rm",
+  TERRAFORM_MCP_IMAGE,
+  "--toolsets=registry",
+] as const;
+
+export type TerraformMcpResolution =
+  | { kind: "disabled" }
+  | { kind: "docker_missing"; note: string }
+  | { kind: "available"; command: "docker"; args: string[] };
+
+let cachedDockerAvailable: boolean | undefined;
+
+/** test hook — the docker probe is cached per process. */
+export function _clearDockerProbeCache(): void {
+  cachedDockerAvailable = undefined;
+}
+
+function dockerAvailable(): boolean {
+  if (cachedDockerAvailable === undefined) {
+    const probe = spawnSync("docker", ["--version"], {
+      stdio: "pipe",
+      encoding: "utf-8",
+      timeout: 10_000,
+    });
+    cachedDockerAvailable = !probe.error && probe.status === 0;
+  }
+  return cachedDockerAvailable;
+}
+
+/**
+ * Decide whether the run gets the terraform-mcp-server, as a discriminated
+ * union so each harness handles all three outcomes explicitly: register the
+ * server (`available`), log the degrade-green note (`docker_missing`), or do
+ * nothing (`disabled`).
+ */
+export function resolveTerraformMcp(
+  payload: Pick<ResolvedPayload, "terraformMcp">,
+): TerraformMcpResolution {
+  if (!payload.terraformMcp) return { kind: "disabled" };
+  if (!dockerAvailable()) {
+    return {
+      kind: "docker_missing",
+      note:
+        "terraform_mcp requested but docker is not available on this runner — " +
+        "continuing without Terraform Registry MCP (module/provider knowledge falls " +
+        "back to the registry HTTP lookups in terraform_version_currency)",
+    };
+  }
+  return { kind: "available", command: "docker", args: [...TERRAFORM_MCP_DOCKER_ARGS] };
+}

package/src/utils/time.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import { isValidTimeString, parseTimeString, resolveTimeoutMs } from "#app/utils/time";
+
+describe("parseTimeString", () => {
+  it.each([
+    ["10m", 600000], // 10 minutes
+    ["1h", 3600000], // 1 hour
+    ["30s", 30000], // 30 seconds
+    ["1h30m", 5400000], // 1 hour 30 minutes
+    ["10m12s", 612000], // 10 minutes 12 seconds
+    ["1h30m45s", 5445000], // 1 hour 30 minutes 45 seconds
+    ["2h", 7200000], // 2 hours
+    ["90m", 5400000], // 90 minutes
+    ["0m", 0], // 0 minutes (edge case)
+    ["0s", 0], // 0 seconds (edge case)
+  ])("parses '%s' to %d ms", (input, expected) => {
+    expect(parseTimeString(input)).toBe(expected);
+  });
+
+  it.each([
+    [""], // empty string
+    ["abc"], // no numbers
+    ["10"], // no unit
+    ["10x"], // invalid unit
+    ["h10m"], // hours without number
+    ["m10"], // units before number
+    ["10 m"], // space between number and unit
+    ["-10m"], // negative number
+    ["10.5m"], // decimal
+    ["10m 30s"], // space between components
+  ])("returns null for invalid input '%s'", (input) => {
+    expect(parseTimeString(input)).toBeNull();
+  });
+});
+
+describe("isValidTimeString", () => {
+  it.each([
+    "10m",
+    "1h",
+    "30s",
+    "1h30m",
+    "10m12s",
+    "1h30m45s",
+  ])("returns true for valid '%s'", (input) => {
+    expect(isValidTimeString(input)).toBe(true);
+  });
+
+  it.each(["", "abc", "10", "10x", "-10m", "10.5m"])("returns false for invalid '%s'", (input) => {
+    expect(isValidTimeString(input)).toBe(false);
+  });
+});
+
+describe("resolveTimeoutMs", () => {
+  it.each([
+    ["1h", 3_600_000],
+    ["10m", 600_000],
+    ["1h30m", 5_400_000],
+  ])("returns ms for valid '%s'", (input, expected) => {
+    expect(resolveTimeoutMs(input)).toBe(expected);
+  });
+
+  it("returns null for undefined input (no timeout configured)", () => {
+    expect(resolveTimeoutMs(undefined)).toBeNull();
+  });
+
+  it.each([
+    ["0m"],
+    ["0s"],
+    ["0h"],
+    ["0h0m0s"],
+  ])("returns null for zero-value '%s' so the caller doesn't insta-timeout", (input) => {
+    // 0ms setTimeout fires in the same tick — without this guard, a user
+    // typo like "0m" rejected the run as "timed out after 0m" the instant
+    // it started. see also the matching payload.timeout handling in main.ts.
+    expect(resolveTimeoutMs(input)).toBeNull();
+  });
+
+  it.each([
+    ["abc"],
+    ["10"],
+    ["10x"],
+    ["-10m"],
+    ["10.5m"],
+    [""],
+  ])("returns null for unparseable input '%s'", (input) => {
+    expect(resolveTimeoutMs(input)).toBeNull();
+  });
+
+  it("returns null for values past node's setTimeout ceiling (~24.8 days)", () => {
+    // 2^31 - 1 ms = 2147483647 ms = 596h31m23s647ms. node silently clamps any
+    // delay above that down to 1ms — a user asking for "999h" would have the
+    // run terminate with "timed out after 999h" within a single tick. reject
+    // here so the caller's warn + fallback kicks in instead.
+    expect(resolveTimeoutMs("999h")).toBeNull();
+    // 600h = 2_160_000_000 ms, safely past the cap.
+    expect(resolveTimeoutMs("600h")).toBeNull();
+  });
+
+  it("accepts the largest value that setTimeout can still honor", () => {
+    // 596h31m23s = 2_147_483_000 ms — just under 2^31-1. this must remain
+    // usable so the "reject over-max" rule doesn't accidentally reject the
+    // boundary itself.
+    expect(resolveTimeoutMs("596h31m23s")).toBe(2_147_483_000);
+  });
+});

package/src/utils/time.ts

@@ -0,0 +1,59 @@
+/**
+ * time string parsing utilities for timeout configuration.
+ * supports formats like "10m", "1h30m", "10m12s", "30s".
+ */
+
+// special value indicating timeout is explicitly disabled via --notimeout flag
+export const TIMEOUT_DISABLED = "none";
+
+// time string regex: supports formats like "10m", "1h30m", "10m12s", "30s"
+// at least one component (hours, minutes, or seconds) is required
+const TIME_STRING_REGEX = /^(?:(\d+)h)?(?:(\d+)m)?(?:(\d+)s)?$/;
+
+/**
+ * parse a time string like "10m", "1h30m", "10m12s" into milliseconds.
+ * returns null if the string is not a valid time format.
+ */
+export function parseTimeString(input: string): number | null {
+  const match = input.match(TIME_STRING_REGEX);
+  if (!match || (!match[1] && !match[2] && !match[3])) return null;
+
+  const hours = parseInt(match[1] || "0", 10);
+  const minutes = parseInt(match[2] || "0", 10);
+  const seconds = parseInt(match[3] || "0", 10);
+
+  return (hours * 3600 + minutes * 60 + seconds) * 1000;
+}
+
+/**
+ * check if a string is a valid time format.
+ */
+export function isValidTimeString(input: string): boolean {
+  return parseTimeString(input) !== null;
+}
+
+/**
+ * resolve a user-supplied timeout string into a setTimeout-safe number of
+ * milliseconds, returning null when the input is unusable.
+ *
+ * "unusable" covers three cases that all cause setTimeout to misbehave if
+ * passed through naively:
+ *   - unparseable ("abc", "10x") — parseTimeString returns null.
+ *   - zero ("0m", "0s") — setTimeout fires immediately, so the run would
+ *     look like an insta-fail with the confusing message "timed out after 0m".
+ *   - overflow (e.g. "999h") — node clamps any delay above 2^31-1 ms
+ *     (~24.8 days) to 1 ms, so a user who asked for "596h" or more would
+ *     get a timeout in a single tick instead of the multi-day window they
+ *     requested. user almost certainly meant --notimeout.
+ *
+ * the caller should warn and fall back to its own default when this returns
+ * null; the reason is always "the input can't be honored" regardless of
+ * which branch triggered it.
+ */
+const TIMEOUT_MAX_MS = 2_147_483_647;
+export function resolveTimeoutMs(input: string | undefined): number | null {
+  if (!input) return null;
+  const parsed = parseTimeString(input);
+  if (parsed === null || parsed <= 0 || parsed > TIMEOUT_MAX_MS) return null;
+  return parsed;
+}

package/src/utils/timer.test.ts

@@ -0,0 +1,91 @@
+import { performance } from "node:perf_hooks";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { ThinkingTimer, Timer } from "#app/utils/timer";
+
+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 debugMock = vi.mocked(log.debug);
+const infoMock = vi.mocked(log.info);
+
+let nowSpy: ReturnType<typeof vi.spyOn>;
+let now = 0;
+
+function setNow(value: number): void {
+  now = value;
+}
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  now = 0;
+  nowSpy = vi.spyOn(performance, "now").mockImplementation(() => now);
+});
+
+afterEach(() => {
+  nowSpy.mockRestore();
+});
+
+describe("Timer", () => {
+  it("measures the first checkpoint from construction", () => {
+    setNow(100);
+    const timer = new Timer();
+    setNow(350);
+    timer.checkpoint("startup");
+    expect(debugMock).toHaveBeenCalledWith("» startup: 250ms");
+  });
+
+  it("measures subsequent checkpoints from the previous one", () => {
+    setNow(0);
+    const timer = new Timer();
+    setNow(50);
+    timer.checkpoint("first");
+    setNow(80);
+    timer.checkpoint("second");
+    expect(debugMock).toHaveBeenLastCalledWith("» second: 30ms");
+  });
+});
+
+describe("ThinkingTimer", () => {
+  it("does nothing on a tool call without a prior tool result", () => {
+    const timer = new ThinkingTimer();
+    setNow(10_000);
+    timer.markToolCall();
+    expect(infoMock).not.toHaveBeenCalled();
+  });
+
+  it("stays silent below the thinking threshold", () => {
+    const timer = new ThinkingTimer();
+    setNow(0);
+    timer.markToolResult();
+    setNow(2999);
+    timer.markToolCall();
+    expect(infoMock).not.toHaveBeenCalled();
+  });
+
+  it("logs the thinking duration once the threshold is crossed", () => {
+    const timer = new ThinkingTimer();
+    setNow(0);
+    timer.markToolResult();
+    setNow(4500);
+    timer.markToolCall();
+    expect(infoMock).toHaveBeenCalledWith("» thought for 4.5 seconds");
+  });
+
+  it("prefixes output with the caller-provided line formatter", () => {
+    const timer = new ThinkingTimer((line) => `[subagent] ${line}`);
+    setNow(0);
+    timer.markToolResult();
+    setNow(10_000);
+    timer.markToolCall();
+    expect(infoMock).toHaveBeenCalledWith("[subagent] » thought for 10 seconds");
+  });
+});

package/src/utils/timer.ts

@@ -0,0 +1,72 @@
+import { performance } from "node:perf_hooks";
+import { log } from "#app/utils/cli";
+
+export class Timer {
+  private initialTimestamp: number;
+  private lastCheckpointTimestamp: number | null = null;
+
+  constructor() {
+    this.initialTimestamp = performance.now();
+  }
+
+  checkpoint(name: string): void {
+    const now = performance.now();
+    const duration = this.lastCheckpointTimestamp
+      ? now - this.lastCheckpointTimestamp
+      : now - this.initialTimestamp;
+
+    log.debug(`» ${name}: ${duration}ms`);
+    this.lastCheckpointTimestamp = now;
+  }
+}
+
+const THINKING_THRESHOLD = 3000; // ms
+
+/**
+ * Measures wall-clock gap between the last tool_result and the next tool_call,
+ * surfacing it as a "thought for Xs" log when over `THINKING_THRESHOLD`.
+ *
+ * Use one instance per logical session (orchestrator, each subagent) — sharing
+ * a single timer across sessions conflates cross-session interleaving as
+ * thinking time. The optional `formatLine` lets the caller prefix output with
+ * a session label so attribution is visible in the merged log stream.
+ */
+export class ThinkingTimer {
+  private readonly durationFormatter = new Intl.NumberFormat("en-US", {
+    style: "unit",
+    unit: "second",
+    unitDisplay: "long",
+    minimumFractionDigits: 0,
+    maximumFractionDigits: 1,
+  });
+
+  private lastToolResultTimestamp: number | null = null;
+  private readonly formatLine: (line: string) => string;
+
+  // node's native TS strip-only mode does not support parameter properties,
+  // so the formatter is declared as a field and assigned in the body.
+  constructor(formatLine: (line: string) => string = (l) => l) {
+    this.formatLine = formatLine;
+  }
+
+  markToolResult(): void {
+    this.lastToolResultTimestamp = performance.now();
+    log.debug(
+      this.formatLine(`» thinking timer: markToolResult at ${this.lastToolResultTimestamp}`),
+    );
+  }
+
+  markToolCall(): void {
+    const now = performance.now();
+    log.debug(
+      this.formatLine(
+        `» thinking timer: markToolCall at ${now}, lastToolResult=${this.lastToolResultTimestamp}`,
+      ),
+    );
+    if (this.lastToolResultTimestamp === null) return;
+    const elapsed = now - this.lastToolResultTimestamp;
+    if (elapsed < THINKING_THRESHOLD) return;
+    const seconds = elapsed / 1000;
+    log.info(this.formatLine(`» thought for ${this.durationFormatter.format(seconds)}`));
+  }
+}

package/src/utils/todoTracking.test.ts

@@ -0,0 +1,223 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { createTodoTracker } from "#app/utils/todoTracking";
+
+vi.mock("#app/utils/log", () => ({
+  log: {
+    info: vi.fn(),
+    debug: vi.fn(),
+    warning: vi.fn(),
+    error: vi.fn(),
+    success: vi.fn(),
+  },
+}));
+
+const DEBOUNCE_MS = 2000;
+
+function todos(...items: { content: string; status?: string; id?: string }[]): unknown {
+  return { todos: items };
+}
+
+describe("createTodoTracker", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  it("publishes rendered markdown after the debounce window", async () => {
+    const onUpdate = vi.fn(async (_body: string) => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(
+      todos(
+        { content: "done item", status: "completed" },
+        { content: "dropped item", status: "cancelled" },
+        { content: "active item", status: "in_progress" },
+        { content: "queued item", status: "pending" },
+      ),
+    );
+
+    expect(onUpdate).not.toHaveBeenCalled();
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS);
+    await tracker.settled();
+
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    const body = onUpdate.mock.calls[0]?.[0];
+    expect(body).toContain("- [x] done item");
+    expect(body).toContain("- ~~dropped item~~");
+    expect(body).toContain("active item");
+    expect(body).toContain("- [ ] queued item");
+    expect(tracker.hasPublished).toBe(true);
+  });
+
+  it("ignores inputs that are not valid todowrite payloads", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(undefined);
+    tracker.update("nope");
+    tracker.update({ noTodos: true });
+    tracker.update({ todos: "not-an-array" });
+
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS * 2);
+    await tracker.settled();
+    expect(onUpdate).not.toHaveBeenCalled();
+    expect(tracker.hasPublished).toBe(false);
+  });
+
+  it("skips malformed entries and defaults id/status", async () => {
+    const onUpdate = vi.fn(async (_body: string) => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update({
+      todos: [
+        null,
+        "string entry",
+        { noContent: true },
+        { content: "no status entry" },
+        { content: "bad status entry", status: "exploded" },
+        { content: "with id", id: "custom", status: "completed" },
+      ],
+    });
+
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS);
+    await tracker.settled();
+
+    const body = onUpdate.mock.calls[0]?.[0];
+    expect(body).toBe("- [ ] no status entry\n- [ ] bad status entry\n- [x] with id");
+  });
+
+  it("replaces state by default and merges when merge=true", () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update({ todos: [{ content: "first", id: "a" }] });
+    tracker.update({ todos: [{ content: "second", id: "b" }] });
+    expect(tracker.renderCollapsible()).toContain("second");
+    expect(tracker.renderCollapsible()).not.toContain("first");
+
+    tracker.update({
+      todos: [{ content: "merged", id: "a", status: "completed" }],
+      merge: true,
+    });
+    const rendered = tracker.renderCollapsible();
+    expect(rendered).toContain("merged");
+    expect(rendered).toContain("second");
+  });
+
+  it("does not publish when the debounce fires with an empty state", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update({ todos: [] });
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS);
+    await tracker.settled();
+    expect(onUpdate).not.toHaveBeenCalled();
+  });
+
+  it("flush publishes immediately and clears the pending debounce", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(todos({ content: "task" }));
+    await tracker.flush();
+
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS * 2);
+    await tracker.settled();
+    // the pending debounce was cleared — no second publish
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+  });
+
+  it("flush is a no-op when state is empty", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+    await tracker.flush();
+    expect(onUpdate).not.toHaveBeenCalled();
+  });
+
+  it("swallows onUpdate failures on flush and stays unpublished", async () => {
+    const onUpdate = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(todos({ content: "task" }));
+    await tracker.flush();
+
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    expect(tracker.hasPublished).toBe(false);
+  });
+
+  it("swallows onUpdate failures from the debounced path", async () => {
+    const onUpdate = vi.fn(async () => {
+      throw new Error("boom");
+    });
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(todos({ content: "task" }));
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS);
+    await tracker.settled();
+
+    expect(onUpdate).toHaveBeenCalledTimes(1);
+    expect(tracker.hasPublished).toBe(false);
+  });
+
+  it("cancel disables the tracker and clears the pending debounce", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(todos({ content: "task" }));
+    expect(tracker.enabled).toBe(true);
+    tracker.cancel();
+    expect(tracker.enabled).toBe(false);
+
+    await vi.advanceTimersByTimeAsync(DEBOUNCE_MS * 2);
+    await tracker.settled();
+    expect(onUpdate).not.toHaveBeenCalled();
+
+    // updates and flushes after cancel are no-ops
+    tracker.update(todos({ content: "late" }));
+    await tracker.flush();
+    expect(onUpdate).not.toHaveBeenCalled();
+
+    // cancel again exercises the no-pending-timer path
+    tracker.cancel();
+  });
+
+  it("completeInProgress flips in_progress items to completed in state", async () => {
+    const onUpdate = vi.fn(async () => undefined);
+    const tracker = createTodoTracker(onUpdate);
+
+    tracker.update(
+      todos({ content: "active", status: "in_progress" }, { content: "queued", status: "pending" }),
+    );
+    tracker.completeInProgress();
+
+    const rendered = tracker.renderCollapsible();
+    expect(rendered).toContain("- [x] active");
+    expect(rendered).toContain("- [ ] queued");
+  });
+
+  it("renderCollapsible returns empty string with no state", () => {
+    const tracker = createTodoTracker(vi.fn(async () => undefined));
+    expect(tracker.renderCollapsible()).toBe("");
+  });
+
+  it("renderCollapsible can complete in-progress items without mutating state", () => {
+    const tracker = createTodoTracker(vi.fn(async () => undefined));
+    tracker.update(
+      todos({ content: "active", status: "in_progress" }, { content: "done", status: "completed" }),
+    );
+
+    const completed = tracker.renderCollapsible({ completeInProgress: true });
+    expect(completed).toContain("Task list (2/2 completed)");
+    expect(completed).toContain("- [x] active");
+
+    // state itself stays in_progress
+    const plain = tracker.renderCollapsible();
+    expect(plain).toContain("Task list (1/2 completed)");
+  });
+});