create-interview-cockpit 0.5.0 → 0.6.0

package/template/server/src/infra-runner.ts

@@ -0,0 +1,1104 @@
+import fs from "fs/promises";
+import path from "path";
+import { randomUUID } from "crypto";
+import { spawn } from "child_process";
+import * as storage from "./storage.js";
+
+type InfraExecutionMode = "plan-only" | "localstack";
+export type InfraRunAction = "validate" | "plan" | "command";
+type InfraRunStatus = "completed" | "failed";
+type OutputKind = "stdout" | "stderr" | "info";
+
+interface InfraLabWorkspace {
+  version: 1;
+  label: string;
+  provider: "aws";
+  executionMode: InfraExecutionMode;
+  activeFile: string;
+  files: Record<string, string>;
+}
+
+export interface InfraRunArtifact {
+  key: string;
+  label: string;
+  kind: "text" | "json";
+  fileName: string;
+}
+
+export interface InfraDiagnostic {
+  severity: string;
+  summary: string;
+  detail?: string;
+  address?: string;
+  filename?: string;
+  line?: number;
+}
+
+export interface InfraPlanSummary {
+  add: number;
+  change: number;
+  destroy: number;
+  replace: number;
+  resourceCount: number;
+  outputCount: number;
+}
+
+export interface InfraRunListItem {
+  id: string;
+  fileId?: string;
+  questionId?: string;
+  label: string;
+  action: InfraRunAction;
+  command?: string;
+  status: InfraRunStatus;
+  startedAt: string;
+  completedAt: string;
+  durationMs: number;
+  provider: "aws";
+  executionMode: InfraExecutionMode;
+  diagnostics: InfraDiagnostic[];
+  planSummary?: InfraPlanSummary;
+  error?: string;
+  artifacts: InfraRunArtifact[];
+}
+
+export interface InfraRunDetails extends InfraRunListItem {
+  logs: string;
+  validationJson?: unknown;
+  planJson?: unknown;
+  workspaceSnapshot?: InfraLabWorkspace;
+}
+
+export type InfraStreamMessage =
+  | { type: "output"; kind: OutputKind; text: string }
+  | { type: "complete"; run: InfraRunDetails }
+  | { type: "error"; error: string };
+
+interface RunCommandResult {
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  combined: string;
+}
+
+interface ParsedCommand {
+  args: string[];
+  subcommand: string;
+  action: InfraRunAction;
+  displayCommand: string;
+  planOutputFile?: string;
+}
+
+const MAX_FILE_COUNT = 24;
+const MAX_TOTAL_SOURCE_BYTES = 500_000;
+const MAX_LOG_CHARS = 200_000;
+const SOURCE_MANIFEST = ".infra-source-files.json";
+const ALLOWED_SUBCOMMANDS = new Set([
+  "fmt",
+  "init",
+  "validate",
+  "plan",
+  "show",
+  "apply",
+  "destroy",
+  "output",
+  "state",
+  "version",
+  "providers",
+]);
+
+function getInfraRunsDir(): string {
+  return path.resolve(storage.getContextFilesDir(), "..", "infra-runs");
+}
+
+function getInfraSessionsDir(): string {
+  return path.resolve(storage.getContextFilesDir(), "..", "infra-sessions");
+}
+
+function stripAnsi(text: string): string {
+  return text.replace(/\x1b\[[0-9;]*[A-Za-z]/g, "");
+}
+
+function appendLog(buffer: string, chunk: string): string {
+  if (!chunk || buffer.length >= MAX_LOG_CHARS) return buffer;
+  const remaining = MAX_LOG_CHARS - buffer.length;
+  if (chunk.length <= remaining) return buffer + chunk;
+  return `${buffer}${chunk.slice(0, remaining)}\n[log truncated]\n`;
+}
+
+function sanitizeKey(value: string): string {
+  return value.replace(/[^a-zA-Z0-9_-]/g, "-").slice(0, 120) || "session";
+}
+
+function assertSafeRelativePath(filePath: string, label: string): void {
+  if (!filePath || path.isAbsolute(filePath) || filePath.includes("..")) {
+    throw new Error(`${label} must stay within the infra workspace`);
+  }
+}
+
+function parseWorkspace(input: unknown): InfraLabWorkspace {
+  if (!input || typeof input !== "object") {
+    throw new Error("workspace payload is required");
+  }
+
+  const candidate = input as Partial<InfraLabWorkspace> & {
+    files?: Record<string, unknown>;
+  };
+
+  if (!candidate.files || typeof candidate.files !== "object") {
+    throw new Error("workspace.files must be provided");
+  }
+
+  const files = Object.fromEntries(
+    Object.entries(candidate.files)
+      .filter(
+        (entry): entry is [string, string] =>
+          typeof entry[0] === "string" && typeof entry[1] === "string",
+      )
+      .map(([name, content]) => [name.trim(), content]),
+  );
+
+  const fileNames = Object.keys(files).filter(Boolean);
+  if (fileNames.length === 0) {
+    throw new Error("workspace must contain at least one file");
+  }
+  if (fileNames.length > MAX_FILE_COUNT) {
+    throw new Error(`workspace exceeds the ${MAX_FILE_COUNT} file limit`);
+  }
+
+  let totalBytes = 0;
+  for (const name of fileNames) {
+    assertSafeRelativePath(name, "Workspace file path");
+    totalBytes += Buffer.byteLength(files[name], "utf8");
+  }
+
+  if (totalBytes > MAX_TOTAL_SOURCE_BYTES) {
+    throw new Error("workspace source exceeds the allowed size limit");
+  }
+
+  return {
+    version: 1,
+    label:
+      typeof candidate.label === "string" && candidate.label.trim()
+        ? candidate.label.trim()
+        : "Infrastructure Lab",
+    provider: "aws",
+    executionMode:
+      candidate.executionMode === "plan-only" ? "plan-only" : "localstack",
+    activeFile:
+      typeof candidate.activeFile === "string" && files[candidate.activeFile]
+        ? candidate.activeFile
+        : fileNames[0],
+    files,
+  };
+}
+
+function getDefaultEnv(mode: InfraExecutionMode): NodeJS.ProcessEnv {
+  const base: NodeJS.ProcessEnv = {
+    ...process.env,
+    TF_IN_AUTOMATION: "1",
+  };
+
+  if (mode === "localstack") {
+    return {
+      ...base,
+      AWS_ACCESS_KEY_ID: process.env.AWS_ACCESS_KEY_ID || "test",
+      AWS_SECRET_ACCESS_KEY: process.env.AWS_SECRET_ACCESS_KEY || "test",
+      AWS_DEFAULT_REGION: process.env.AWS_DEFAULT_REGION || "us-east-1",
+      AWS_REGION: process.env.AWS_REGION || "us-east-1",
+    };
+  }
+
+  return base;
+}
+
+function splitCommand(command: string): string[] {
+  const tokens: string[] = [];
+  let current = "";
+  let quote: '"' | "'" | null = null;
+  let escape = false;
+
+  for (const char of command.trim()) {
+    if (escape) {
+      current += char;
+      escape = false;
+      continue;
+    }
+
+    if (char === "\\") {
+      escape = true;
+      continue;
+    }
+
+    if (quote) {
+      if (char === quote) {
+        quote = null;
+      } else {
+        current += char;
+      }
+      continue;
+    }
+
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      if (current) {
+        tokens.push(current);
+        current = "";
+      }
+      continue;
+    }
+
+    current += char;
+  }
+
+  if (escape) current += "\\";
+  if (quote) throw new Error("Command has an unclosed quote");
+  if (current) tokens.push(current);
+  return tokens;
+}
+
+function extractPlanOutputFile(args: string[]): string | undefined {
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (token.startsWith("-out=")) {
+      const value = token.slice(5).trim();
+      if (value) return value;
+    }
+    if (token === "-out" && args[index + 1]) {
+      return args[index + 1];
+    }
+  }
+  return undefined;
+}
+
+function parseCommand(command: string): ParsedCommand {
+  const tokens = splitCommand(command);
+  if (tokens.length === 0) {
+    throw new Error("Type a Terraform command to run");
+  }
+
+  const args = tokens[0] === "terraform" ? tokens.slice(1) : [...tokens];
+  if (args.length === 0) {
+    throw new Error("Type a Terraform subcommand after 'terraform'");
+  }
+
+  const subcommand = args[0];
+  if (!ALLOWED_SUBCOMMANDS.has(subcommand)) {
+    throw new Error(
+      "Only Terraform commands are allowed here: fmt, init, validate, plan, show, apply, destroy, output, state, version, providers",
+    );
+  }
+
+  if (args.some((arg) => arg === "-chdir" || arg.startsWith("-chdir="))) {
+    throw new Error("-chdir is disabled in the infra lab console");
+  }
+
+  if (
+    (subcommand === "apply" || subcommand === "destroy") &&
+    !args.includes("-auto-approve")
+  ) {
+    throw new Error(
+      `${subcommand} requires -auto-approve in the infra lab console`,
+    );
+  }
+
+  const planOutputFile =
+    subcommand === "plan" ? extractPlanOutputFile(args.slice(1)) : undefined;
+  if (planOutputFile) {
+    assertSafeRelativePath(planOutputFile, "Plan output file");
+  }
+
+  return {
+    args,
+    subcommand,
+    action:
+      subcommand === "validate"
+        ? "validate"
+        : subcommand === "plan"
+          ? "plan"
+          : "command",
+    displayCommand: `$ terraform ${args.join(" ")}\n`,
+    planOutputFile,
+  };
+}
+
+async function runTerraformCommand(
+  cwd: string,
+  args: string[],
+  executionMode: InfraExecutionMode,
+  onChunk?: (chunk: { kind: OutputKind; text: string }) => void,
+): Promise<RunCommandResult> {
+  return await new Promise<RunCommandResult>((resolve) => {
+    const stdout: string[] = [];
+    const stderr: string[] = [];
+    const commandLine = `$ terraform ${args.join(" ")}\n`;
+    let settled = false;
+
+    onChunk?.({ kind: "info", text: commandLine });
+
+    const child = spawn("terraform", args, {
+      cwd,
+      env: {
+        ...getDefaultEnv(executionMode),
+        TF_DATA_DIR: path.join(cwd, ".tfdata"),
+      },
+    });
+
+    const finish = (result: RunCommandResult) => {
+      if (settled) return;
+      settled = true;
+      resolve(result);
+    };
+
+    child.stdout.on("data", (chunk: Buffer) => {
+      const text = stripAnsi(chunk.toString());
+      stdout.push(text);
+      onChunk?.({ kind: "stdout", text });
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      const text = stripAnsi(chunk.toString());
+      stderr.push(text);
+      onChunk?.({ kind: "stderr", text });
+    });
+    child.on("error", (error) => {
+      const message = `terraform launch failed: ${error.message}\n`;
+      onChunk?.({ kind: "stderr", text: message });
+      finish({
+        exitCode: 1,
+        stdout: "",
+        stderr: message,
+        combined: `${commandLine}${message}`,
+      });
+    });
+    child.on("close", (code) => {
+      const out = stdout.join("");
+      const err = stderr.join("");
+      finish({
+        exitCode: typeof code === "number" ? code : 1,
+        stdout: out,
+        stderr: err,
+        combined: `${commandLine}${out}${err}`,
+      });
+    });
+  });
+}
+
+function toDiagnostics(value: unknown): InfraDiagnostic[] {
+  if (!value || typeof value !== "object") return [];
+  const diagnostics = (value as { diagnostics?: unknown }).diagnostics;
+  if (!Array.isArray(diagnostics)) return [];
+
+  return diagnostics
+    .filter(
+      (entry): entry is Record<string, unknown> =>
+        !!entry && typeof entry === "object",
+    )
+    .map((entry) => {
+      const range =
+        entry.range && typeof entry.range === "object"
+          ? (entry.range as { filename?: unknown; start?: { line?: unknown } })
+          : undefined;
+      return {
+        severity: typeof entry.severity === "string" ? entry.severity : "error",
+        summary:
+          typeof entry.summary === "string"
+            ? entry.summary
+            : "Terraform reported a validation issue.",
+        detail: typeof entry.detail === "string" ? entry.detail : undefined,
+        address: typeof entry.address === "string" ? entry.address : undefined,
+        filename:
+          range && typeof range.filename === "string"
+            ? range.filename
+            : undefined,
+        line:
+          range && range.start && typeof range.start.line === "number"
+            ? range.start.line
+            : undefined,
+      } satisfies InfraDiagnostic;
+    });
+}
+
+function toPlanSummary(value: unknown): InfraPlanSummary | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const resourceChanges = (value as { resource_changes?: unknown })
+    .resource_changes;
+  if (!Array.isArray(resourceChanges)) return undefined;
+
+  const outputs =
+    (value as { planned_values?: { outputs?: Record<string, unknown> } })
+      .planned_values?.outputs || {};
+
+  const summary: InfraPlanSummary = {
+    add: 0,
+    change: 0,
+    destroy: 0,
+    replace: 0,
+    resourceCount: resourceChanges.length,
+    outputCount: Object.keys(outputs).length,
+  };
+
+  for (const change of resourceChanges) {
+    const actions =
+      change &&
+      typeof change === "object" &&
+      (change as { change?: { actions?: unknown } }).change?.actions;
+
+    if (!Array.isArray(actions)) continue;
+    const steps = actions.filter(
+      (step): step is string => typeof step === "string",
+    );
+
+    if (
+      steps.length === 2 &&
+      steps.includes("create") &&
+      steps.includes("delete")
+    ) {
+      summary.replace += 1;
+      continue;
+    }
+    if (steps.includes("create")) summary.add += 1;
+    if (steps.includes("update")) summary.change += 1;
+    if (steps.includes("delete")) summary.destroy += 1;
+  }
+
+  return summary;
+}
+
+async function writeWorkspaceFiles(
+  workspaceDir: string,
+  workspace: InfraLabWorkspace,
+): Promise<void> {
+  await fs.mkdir(workspaceDir, { recursive: true });
+  await Promise.all(
+    Object.entries(workspace.files).map(async ([name, content]) => {
+      const target = path.join(workspaceDir, name);
+      await fs.mkdir(path.dirname(target), { recursive: true });
+      await fs.writeFile(target, content, "utf8");
+    }),
+  );
+}
+
+// Injected when executionMode === "localstack" — skips real AWS credential
+// validation so Terraform doesn't call STS with the test keys.
+// const LOCALSTACK_OVERRIDE = `# Auto-injected by infra-runner — do not edit
+// provider "aws" {
+//   skip_credentials_validation = true
+//   skip_requesting_account_id  = true
+//   skip_metadata_api_check     = true
+// }
+// `;
+
+async function injectLocalStackOverride(workspaceDir: string): Promise<void> {
+  // await fs.writeFile(
+  //   path.join(workspaceDir, "_localstack_override.tf"),
+  //   LOCALSTACK_OVERRIDE,
+  //   "utf8",
+  // );
+}
+
+async function writeArtifact(
+  artifactsDir: string,
+  key: string,
+  fileName: string,
+  kind: "text" | "json",
+  value: string | unknown,
+): Promise<InfraRunArtifact> {
+  await fs.mkdir(artifactsDir, { recursive: true });
+  const target = path.join(artifactsDir, fileName);
+  const content =
+    kind === "json" ? JSON.stringify(value, null, 2) : String(value);
+  await fs.writeFile(target, content, "utf8");
+  return {
+    key,
+    label: key,
+    kind,
+    fileName,
+  };
+}
+
+async function readJsonFile(filePath: string): Promise<unknown | undefined> {
+  try {
+    const raw = await fs.readFile(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return undefined;
+  }
+}
+
+async function readTextFile(filePath: string): Promise<string> {
+  try {
+    return await fs.readFile(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+async function saveMetadata(
+  runDir: string,
+  metadata: InfraRunListItem,
+): Promise<void> {
+  await fs.mkdir(runDir, { recursive: true });
+  await fs.writeFile(
+    path.join(runDir, "metadata.json"),
+    JSON.stringify(metadata, null, 2),
+    "utf8",
+  );
+}
+
+async function syncWorkspaceToSession(
+  sessionKey: string,
+  workspace: InfraLabWorkspace,
+): Promise<string> {
+  const sessionDir = path.join(getInfraSessionsDir(), sanitizeKey(sessionKey));
+  const workspaceDir = path.join(sessionDir, "workspace");
+  const manifestPath = path.join(sessionDir, SOURCE_MANIFEST);
+  await fs.mkdir(sessionDir, { recursive: true });
+
+  const previous = await readJsonFile(manifestPath);
+  const previousFiles = Array.isArray(previous)
+    ? previous.filter((item): item is string => typeof item === "string")
+    : [];
+  const nextFiles = Object.keys(workspace.files);
+
+  await Promise.all(
+    previousFiles
+      .filter((fileName) => !nextFiles.includes(fileName))
+      .map(async (fileName) => {
+        try {
+          await fs.unlink(path.join(workspaceDir, fileName));
+        } catch {
+          // ignore if already gone
+        }
+      }),
+  );
+
+  await writeWorkspaceFiles(workspaceDir, workspace);
+  if (workspace.executionMode === "localstack") {
+    await injectLocalStackOverride(workspaceDir);
+  }
+  await fs.writeFile(manifestPath, JSON.stringify(nextFiles, null, 2), "utf8");
+  return workspaceDir;
+}
+
+async function readWorkspaceSnapshot(
+  workspaceDir: string,
+  workspace: InfraLabWorkspace,
+): Promise<InfraLabWorkspace> {
+  const manifest = await readJsonFile(
+    path.join(path.dirname(workspaceDir), SOURCE_MANIFEST),
+  );
+  const fileNames = Array.isArray(manifest)
+    ? manifest.filter((item): item is string => typeof item === "string")
+    : Object.keys(workspace.files);
+
+  // Also pick up any Terraform-generated files that appeared after the command
+  const GENERATED_FILES = [".terraform.lock.hcl"];
+  const extraFiles: string[] = [];
+  for (const gen of GENERATED_FILES) {
+    if (!fileNames.includes(gen)) {
+      try {
+        await fs.access(path.join(workspaceDir, gen));
+        extraFiles.push(gen);
+      } catch {
+        // not generated yet — skip
+      }
+    }
+  }
+
+  const files = Object.fromEntries(
+    await Promise.all(
+      [...fileNames, ...extraFiles].map(async (fileName) => {
+        try {
+          const content = await fs.readFile(
+            path.join(workspaceDir, fileName),
+            "utf8",
+          );
+          return [fileName, content] as const;
+        } catch {
+          return [fileName, ""] as const;
+        }
+      }),
+    ),
+  );
+
+  const activeFile = files[workspace.activeFile]
+    ? workspace.activeFile
+    : Object.keys(files)[0] || workspace.activeFile;
+
+  return {
+    ...workspace,
+    activeFile,
+    files,
+  };
+}
+
+async function collectValidationArtifacts(
+  workspaceDir: string,
+  executionMode: InfraExecutionMode,
+  artifactsDir: string,
+): Promise<{
+  diagnostics: InfraDiagnostic[];
+  validationJson?: unknown;
+  artifacts: InfraRunArtifact[];
+}> {
+  const artifacts: InfraRunArtifact[] = [];
+  try {
+    const validate = await runTerraformCommand(
+      workspaceDir,
+      ["validate", "-json"],
+      executionMode,
+    );
+    const validationJson = validate.stdout
+      ? JSON.parse(validate.stdout)
+      : undefined;
+    const diagnostics = toDiagnostics(validationJson);
+    artifacts.push(
+      await writeArtifact(
+        artifactsDir,
+        "validation-json",
+        "validation.json",
+        "json",
+        validationJson ?? { diagnostics: [] },
+      ),
+    );
+    return { diagnostics, validationJson, artifacts };
+  } catch {
+    return { diagnostics: [], artifacts };
+  }
+}
+
+async function collectPlanArtifacts(
+  workspaceDir: string,
+  executionMode: InfraExecutionMode,
+  artifactsDir: string,
+  planFile?: string,
+): Promise<{
+  planSummary?: InfraPlanSummary;
+  planJson?: unknown;
+  artifacts: InfraRunArtifact[];
+}> {
+  const artifacts: InfraRunArtifact[] = [];
+  if (!planFile) return { artifacts };
+
+  try {
+    assertSafeRelativePath(planFile, "Plan output file");
+    await fs.access(path.join(workspaceDir, planFile));
+  } catch {
+    return { artifacts };
+  }
+
+  try {
+    const show = await runTerraformCommand(
+      workspaceDir,
+      ["show", "-json", planFile],
+      executionMode,
+    );
+    if (show.exitCode !== 0 || !show.stdout.trim()) {
+      return { artifacts };
+    }
+
+    const planJson = JSON.parse(show.stdout);
+    const planSummary = toPlanSummary(planJson);
+    artifacts.push(
+      await writeArtifact(
+        artifactsDir,
+        "plan-json",
+        "plan.json",
+        "json",
+        planJson,
+      ),
+    );
+    return { planSummary, planJson, artifacts };
+  } catch {
+    return { artifacts };
+  }
+}
+
+function describeRunError(result: RunCommandResult, fallback: string): string {
+  return result.stderr.trim() || result.stdout.trim() || fallback;
+}
+
+export async function runInfraAction(input: {
+  questionId?: string;
+  fileId?: string;
+  label?: string;
+  action: Extract<InfraRunAction, "validate" | "plan">;
+  workspace: unknown;
+}): Promise<InfraRunDetails> {
+  if (input.action !== "validate" && input.action !== "plan") {
+    throw new Error("action must be 'validate' or 'plan'");
+  }
+
+  const workspace = parseWorkspace(input.workspace);
+  const runId = randomUUID();
+  const startedAt = new Date().toISOString();
+  const runDir = path.join(getInfraRunsDir(), runId);
+  const workspaceDir = path.join(runDir, "workspace");
+  const artifactsDir = path.join(runDir, "artifacts");
+  let logs = "";
+  const artifacts: InfraRunArtifact[] = [];
+  let diagnostics: InfraDiagnostic[] = [];
+  let planSummary: InfraPlanSummary | undefined;
+  let validationJson: unknown;
+  let planJson: unknown;
+  let workspaceSnapshot: InfraLabWorkspace | undefined;
+  let status: InfraRunStatus = "completed";
+  let error: string | undefined;
+
+  await fs.mkdir(runDir, { recursive: true });
+  await writeWorkspaceFiles(workspaceDir, workspace);
+  if (workspace.executionMode === "localstack") {
+    await injectLocalStackOverride(workspaceDir);
+  }
+  artifacts.push(
+    await writeArtifact(
+      artifactsDir,
+      "workspace",
+      "workspace.json",
+      "json",
+      workspace,
+    ),
+  );
+
+  const runStep = async (args: string[]) => {
+    const result = await runTerraformCommand(
+      workspaceDir,
+      args,
+      workspace.executionMode,
+    );
+    logs = appendLog(logs, result.combined);
+    return result;
+  };
+
+  try {
+    const fmt = await runStep(["fmt", "-recursive"]);
+    if (fmt.exitCode !== 0) {
+      status = "failed";
+      error = describeRunError(fmt, "terraform fmt failed");
+      throw new Error(error);
+    }
+
+    const init = await runStep([
+      "init",
+      "-backend=false",
+      "-input=false",
+      "-no-color",
+    ]);
+    if (init.exitCode !== 0) {
+      status = "failed";
+      error = describeRunError(init, "terraform init failed");
+      throw new Error(error);
+    }
+
+    const validation = await collectValidationArtifacts(
+      workspaceDir,
+      workspace.executionMode,
+      artifactsDir,
+    );
+    diagnostics = validation.diagnostics;
+    validationJson = validation.validationJson;
+    artifacts.push(...validation.artifacts);
+    if (
+      input.action === "validate" &&
+      diagnostics.some((item) => item.severity === "error")
+    ) {
+      status = "failed";
+      error = diagnostics[0]?.summary || "terraform validate failed";
+      throw new Error(error);
+    }
+
+    if (input.action === "plan") {
+      const plan = await runStep([
+        "plan",
+        "-out=tfplan",
+        "-input=false",
+        "-lock=false",
+        "-no-color",
+      ]);
+      artifacts.push(
+        await writeArtifact(
+          artifactsDir,
+          "plan-text",
+          "plan.txt",
+          "text",
+          plan.stdout || plan.stderr,
+        ),
+      );
+      if (plan.exitCode !== 0) {
+        status = "failed";
+        error = describeRunError(plan, "terraform plan failed");
+        throw new Error(error);
+      }
+
+      const planArtifacts = await collectPlanArtifacts(
+        workspaceDir,
+        workspace.executionMode,
+        artifactsDir,
+        "tfplan",
+      );
+      planSummary = planArtifacts.planSummary;
+      planJson = planArtifacts.planJson;
+      artifacts.push(...planArtifacts.artifacts);
+    }
+  } catch (runError: any) {
+    if (!error) {
+      error = String(runError?.message ?? runError ?? "Infra run failed");
+    }
+  }
+
+  workspaceSnapshot = await readWorkspaceSnapshot(workspaceDir, workspace);
+  artifacts.push(
+    await writeArtifact(
+      artifactsDir,
+      "workspace-after",
+      "workspace-after.json",
+      "json",
+      workspaceSnapshot,
+    ),
+  );
+  artifacts.push(
+    await writeArtifact(artifactsDir, "log", "run.log", "text", logs),
+  );
+
+  const completedAt = new Date().toISOString();
+  const metadata: InfraRunListItem = {
+    id: runId,
+    ...(input.fileId ? { fileId: input.fileId } : {}),
+    ...(input.questionId ? { questionId: input.questionId } : {}),
+    label: input.label?.trim() || workspace.label,
+    action: input.action,
+    command:
+      input.action === "plan"
+        ? "terraform plan -out=tfplan -input=false -lock=false -no-color"
+        : "terraform validate -json",
+    status,
+    startedAt,
+    completedAt,
+    durationMs: new Date(completedAt).getTime() - new Date(startedAt).getTime(),
+    provider: "aws",
+    executionMode: workspace.executionMode,
+    diagnostics,
+    ...(planSummary ? { planSummary } : {}),
+    ...(error ? { error } : {}),
+    artifacts,
+  };
+
+  await saveMetadata(runDir, metadata);
+
+  return {
+    ...metadata,
+    logs,
+    ...(validationJson !== undefined ? { validationJson } : {}),
+    ...(planJson !== undefined ? { planJson } : {}),
+    ...(workspaceSnapshot ? { workspaceSnapshot } : {}),
+  };
+}
+
+export async function streamInfraCommand(input: {
+  questionId?: string;
+  fileId?: string;
+  label?: string;
+  command: string;
+  workspace: unknown;
+  onMessage?: (message: InfraStreamMessage) => void;
+}): Promise<InfraRunDetails> {
+  const workspace = parseWorkspace(input.workspace);
+  const parsed = parseCommand(input.command);
+  const sessionKey =
+    input.fileId ?? input.questionId ?? `draft-${randomUUID()}`;
+  const runId = randomUUID();
+  const startedAt = new Date().toISOString();
+  const runDir = path.join(getInfraRunsDir(), runId);
+  const artifactsDir = path.join(runDir, "artifacts");
+  const workspaceDir = await syncWorkspaceToSession(sessionKey, workspace);
+
+  let logs = "";
+  const artifacts: InfraRunArtifact[] = [];
+  let diagnostics: InfraDiagnostic[] = [];
+  let planSummary: InfraPlanSummary | undefined;
+  let validationJson: unknown;
+  let planJson: unknown;
+  let workspaceSnapshot: InfraLabWorkspace | undefined;
+  let status: InfraRunStatus = "completed";
+  let error: string | undefined;
+
+  await fs.mkdir(runDir, { recursive: true });
+  artifacts.push(
+    await writeArtifact(
+      artifactsDir,
+      "workspace",
+      "workspace.json",
+      "json",
+      workspace,
+    ),
+  );
+
+  const emit = (message: InfraStreamMessage) => {
+    input.onMessage?.(message);
+  };
+
+  const commandResult = await runTerraformCommand(
+    workspaceDir,
+    parsed.args,
+    workspace.executionMode,
+    (chunk) => {
+      logs = appendLog(logs, chunk.text);
+      emit({ type: "output", kind: chunk.kind, text: chunk.text });
+    },
+  );
+
+  if (commandResult.exitCode !== 0) {
+    status = "failed";
+    error = describeRunError(
+      commandResult,
+      `terraform ${parsed.subcommand} failed`,
+    );
+  }
+
+  if (parsed.subcommand === "validate") {
+    const validation = await collectValidationArtifacts(
+      workspaceDir,
+      workspace.executionMode,
+      artifactsDir,
+    );
+    diagnostics = validation.diagnostics;
+    validationJson = validation.validationJson;
+    artifacts.push(...validation.artifacts);
+  }
+
+  if (parsed.subcommand === "plan") {
+    artifacts.push(
+      await writeArtifact(
+        artifactsDir,
+        "plan-text",
+        "plan.txt",
+        "text",
+        commandResult.stdout || commandResult.stderr,
+      ),
+    );
+    const planArtifacts = await collectPlanArtifacts(
+      workspaceDir,
+      workspace.executionMode,
+      artifactsDir,
+      parsed.planOutputFile,
+    );
+    planSummary = planArtifacts.planSummary;
+    planJson = planArtifacts.planJson;
+    artifacts.push(...planArtifacts.artifacts);
+  }
+
+  workspaceSnapshot = await readWorkspaceSnapshot(workspaceDir, workspace);
+  artifacts.push(
+    await writeArtifact(
+      artifactsDir,
+      "workspace-after",
+      "workspace-after.json",
+      "json",
+      workspaceSnapshot,
+    ),
+  );
+  artifacts.push(
+    await writeArtifact(artifactsDir, "log", "run.log", "text", logs),
+  );
+
+  const completedAt = new Date().toISOString();
+  const metadata: InfraRunListItem = {
+    id: runId,
+    ...(input.fileId ? { fileId: input.fileId } : {}),
+    ...(input.questionId ? { questionId: input.questionId } : {}),
+    label: input.label?.trim() || workspace.label,
+    action: parsed.action,
+    command: `terraform ${parsed.args.join(" ")}`,
+    status,
+    startedAt,
+    completedAt,
+    durationMs: new Date(completedAt).getTime() - new Date(startedAt).getTime(),
+    provider: "aws",
+    executionMode: workspace.executionMode,
+    diagnostics,
+    ...(planSummary ? { planSummary } : {}),
+    ...(error ? { error } : {}),
+    artifacts,
+  };
+
+  await saveMetadata(runDir, metadata);
+
+  const run: InfraRunDetails = {
+    ...metadata,
+    logs,
+    ...(validationJson !== undefined ? { validationJson } : {}),
+    ...(planJson !== undefined ? { planJson } : {}),
+    ...(workspaceSnapshot ? { workspaceSnapshot } : {}),
+  };
+
+  emit({ type: "complete", run });
+  return run;
+}
+
+export async function listInfraRuns(filter?: {
+  fileId?: string;
+  questionId?: string;
+}): Promise<InfraRunListItem[]> {
+  const runsDir = getInfraRunsDir();
+  try {
+    const entries = await fs.readdir(runsDir, { withFileTypes: true });
+    const items = await Promise.all(
+      entries
+        .filter((entry) => entry.isDirectory())
+        .map(async (entry) => {
+          try {
+            const raw = await fs.readFile(
+              path.join(runsDir, entry.name, "metadata.json"),
+              "utf8",
+            );
+            return JSON.parse(raw) as InfraRunListItem;
+          } catch {
+            return null;
+          }
+        }),
+    );
+
+    return items
+      .filter((item): item is InfraRunListItem => !!item)
+      .filter((item) => (filter?.fileId ? item.fileId === filter.fileId : true))
+      .filter((item) =>
+        filter?.questionId ? item.questionId === filter.questionId : true,
+      )
+      .sort((left, right) => right.startedAt.localeCompare(left.startedAt));
+  } catch {
+    return [];
+  }
+}
+
+export async function getInfraRun(runId: string): Promise<InfraRunDetails> {
+  const runDir = path.join(getInfraRunsDir(), runId);
+  const metadataRaw = await fs.readFile(
+    path.join(runDir, "metadata.json"),
+    "utf8",
+  );
+  const metadata = JSON.parse(metadataRaw) as InfraRunListItem;
+  const logs = await readTextFile(path.join(runDir, "artifacts", "run.log"));
+  const validationJson = await readJsonFile(
+    path.join(runDir, "artifacts", "validation.json"),
+  );
+  const planJson = await readJsonFile(
+    path.join(runDir, "artifacts", "plan.json"),
+  );
+  const workspaceSnapshot = await readJsonFile(
+    path.join(runDir, "artifacts", "workspace-after.json"),
+  );
+
+  return {
+    ...metadata,
+    logs,
+    ...(validationJson !== undefined ? { validationJson } : {}),
+    ...(planJson !== undefined ? { planJson } : {}),
+    ...(workspaceSnapshot
+      ? { workspaceSnapshot: workspaceSnapshot as InfraLabWorkspace }
+      : {}),
+  };
+}