terramend 0.2.0

package/src/mcp/terraform.ts

@@ -0,0 +1,23 @@
+/**
+ * Facade for the Terraform MCP toolchain. The implementation lives in the
+ * per-concern modules under `./terraform/`; this file re-exports every symbol so
+ * existing importers (`#app/mcp/terraform`) keep resolving unchanged.
+ *
+ *   types     — Concern + shared types/helpers (ids, paths, roots, severity)
+ *   scanners  — fmt / validate / tflint / trivy / checkov + provider/arg schema
+ *   decisions — grouping, autonomy, confidence, refusal, prevention, co-location
+ *   cost      — infracost breakdown / delta / escalation
+ *   currency  — registry version currency (provider + module upgrade intel)
+ *   findings  — reviewer findings + SARIF ingest/emit
+ *   plan      — plan parsing + destroy/blast/stability/aggregation
+ *   tools     — the MCP Tool factories + their *Params schemas
+ */
+
+export * from "#app/mcp/terraform/cost";
+export * from "#app/mcp/terraform/currency";
+export * from "#app/mcp/terraform/decisions";
+export * from "#app/mcp/terraform/findings";
+export * from "#app/mcp/terraform/plan";
+export * from "#app/mcp/terraform/scanners";
+export * from "#app/mcp/terraform/tools";
+export * from "#app/mcp/terraform/types";

package/src/mcp/terratest.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "vitest";
+import type { ToolContext } from "#app/mcp/server";
+import {
+  ScaffoldTerratestTool,
+  scaffoldTerraformTest,
+  scaffoldTerratest,
+} from "#app/mcp/terratest";
+
+describe("scaffoldTerratest (§28)", () => {
+  it("emits a plan-only Go test + a native test, and no examples/ fixture", () => {
+    const s = scaffoldTerratest({ moduleName: "vpc", modulePath: "modules/vpc" });
+    const paths = s.files.map((f) => f.path);
+    expect(paths).toEqual(["test/vpc_test.go", "modules/vpc/tests/vpc.tftest.hcl"]);
+    expect(paths.some((p) => p.startsWith("examples/"))).toBe(false);
+  });
+
+  it("points the Go test's TerraformDir at the module dir (not an example)", () => {
+    const s = scaffoldTerratest({ moduleName: "vpc", modulePath: "modules/vpc" });
+    const go = s.files.find((f) => f.path === "test/vpc_test.go")!.content;
+    // from test/ → up one level → modules/vpc
+    expect(go).toContain('TerraformDir: "../modules/vpc"');
+    expect(go).not.toContain("examples/");
+  });
+
+  it("PascalCases the Go test function and is plan-only (no apply)", () => {
+    const s = scaffoldTerratest({ moduleName: "my-cool-vpc", modulePath: "modules/x" });
+    const go = s.files.find((f) => f.path.endsWith("_test.go"))!.content;
+    expect(go).toContain("func TestMyCoolVpc(t *testing.T)");
+    expect(go).toContain("InitAndPlan");
+    expect(go).not.toMatch(/InitAndApply|\bApply\b/);
+  });
+
+  it("surfaces the module's variables as TODO placeholders in both tests", () => {
+    const s = scaffoldTerratest({
+      moduleName: "s3",
+      modulePath: "modules/s3",
+      variables: [{ name: "bucket_name", required: true }, { name: "tags" }],
+    });
+    const go = s.files.find((f) => f.path === "test/s3_test.go")!.content;
+    expect(go).toContain('// "bucket_name": nil, // (required)');
+    expect(go).toContain('// "tags": nil, // (optional)');
+    const native = s.files.find((f) => f.path === "modules/s3/tests/s3.tftest.hcl")!.content;
+    expect(native).toContain("# bucket_name = null # (required)");
+    expect(native).toContain("# tags = null # (optional)");
+  });
+
+  it("sanitizes a name with odd characters for the path and function", () => {
+    const s = scaffoldTerratest({ moduleName: "aws/s3 bucket", modulePath: "modules/s3" });
+    const go = s.files.find((f) => f.path.endsWith("_test.go"))!.content;
+    expect(go).toContain("func TestAwsS3Bucket(");
+    expect(s.files.some((f) => f.path === "test/aws-s3-bucket_test.go")).toBe(true);
+  });
+
+  it("bundles a Terraform-native test that plans the module in place", () => {
+    const s = scaffoldTerratest({ moduleName: "vpc", modulePath: "modules/vpc" });
+    const native = s.files.find((f) => f.path === "modules/vpc/tests/vpc.tftest.hcl")!;
+    expect(native.content).toContain("command = plan");
+    expect(native.content).not.toContain("examples/");
+  });
+});
+
+describe("scaffoldTerraformTest (§28 native variant)", () => {
+  it("emits a plan-only .tftest.hcl run block inside the module's tests/ dir", () => {
+    const f = scaffoldTerraformTest({ moduleName: "my-vpc", modulePath: "modules/my-vpc" });
+    expect(f.path).toBe("modules/my-vpc/tests/my-vpc.tftest.hcl");
+    expect(f.content).toContain('run "plan_my_vpc"');
+    expect(f.content).toContain("command = plan");
+    expect(f.content).not.toMatch(/command\s*=\s*apply/);
+  });
+});
+
+describe("ScaffoldTerratestTool", () => {
+  async function runScaffoldTool(terratest: boolean, params: unknown): Promise<string> {
+    const tool = ScaffoldTerratestTool({ payload: { terratest } } as unknown as ToolContext);
+    const exec = tool.execute as (
+      p: unknown,
+      c: unknown,
+    ) => Promise<{ content: [{ type: "text"; text: string }] }>;
+    const result = await exec(params, {});
+    return result.content[0].text;
+  }
+
+  it("degrades green when the terratest input is disabled", async () => {
+    const text = await runScaffoldTool(false, { module_name: "vpc", module_path: "modules/vpc" });
+    expect(text).toContain("enabled: false");
+    expect(text).toContain("opt-in");
+  });
+
+  it("returns the scaffold files when enabled (variables defaulted)", async () => {
+    const text = await runScaffoldTool(true, { module_name: "vpc", module_path: "modules/vpc" });
+    expect(text).toContain("enabled: true");
+    expect(text).toContain("test/vpc_test.go");
+    expect(text).toContain("modules/vpc/tests/vpc.tftest.hcl");
+  });
+
+  it("threads the variables through to the scaffold", async () => {
+    const text = await runScaffoldTool(true, {
+      module_name: "s3",
+      module_path: "modules/s3",
+      variables: [{ name: "bucket_name", required: true }],
+    });
+    expect(text).toContain("bucket_name");
+    expect(text).toContain("(required)");
+  });
+});

package/src/mcp/terratest.ts

@@ -0,0 +1,196 @@
+import { type } from "arktype";
+import type { ToolContext } from "#app/mcp/server";
+import { execute, tool } from "#app/mcp/shared";
+import { log } from "#app/utils/cli";
+
+/**
+ * §28 Terratest scaffolding (opt-in via the `terratest` input). When Terramend
+ * GENERATES a reusable module, it can also scaffold a minimal Go
+ * [Terratest](https://terratest.gruntwork.io/) smoke test + a Terraform-native
+ * `*.tftest.hcl` so the generated infrastructure is testable from the first
+ * commit. Both tests plan the module **directly** — Terramend does not generate
+ * `examples/` fixtures.
+ *
+ * Design choices:
+ *  - **Plan-only, never apply.** The scaffolded tests run `terraform init` +
+ *    `plan` against the module and assert it plans cleanly. Terramend never
+ *    applies (no cloud credentials — the sovereignty stance), so the generated
+ *    tests mirror that: they're a deployability smoke test the USER runs in their
+ *    own pipeline (with creds) for real apply/assert coverage.
+ *  - **Pure generation.** The file contents are computed deterministically here
+ *    and unit-tested; the agent writes the returned files with its own tools.
+ *  - The Go test + native test files fall outside the Terraform-only default
+ *    allow-list, so the `terratest` input also widens the push guardrail (see
+ *    guardrails.ts).
+ */
+
+export interface ScaffoldFile {
+  /** repo-relative path to write. */
+  path: string;
+  content: string;
+}
+
+export interface TerratestScaffold {
+  files: ScaffoldFile[];
+  notes: string[];
+}
+
+/** PascalCase a module name for the Go test function (`my-vpc` → `MyVpc`). */
+function pascalCase(name: string): string {
+  const parts = name.split(/[^A-Za-z0-9]+/).filter(Boolean);
+  const pascal = parts.map((p) => p.charAt(0).toUpperCase() + p.slice(1)).join("");
+  return /^[A-Za-z]/.test(pascal) ? pascal : `M${pascal}`;
+}
+
+/** compute a repo-relative POSIX path from `fromDir` up to `toPath` — both are
+ * repo-relative POSIX paths (e.g. from `test` to `modules/vpc` → `../modules/vpc`). */
+function relativeUp(fromDir: string, toPath: string): string {
+  const up = fromDir
+    .split("/")
+    .filter(Boolean)
+    .map(() => "..");
+  const rel = `${up.join("/")}/${toPath}`.replace(/\/+/g, "/");
+  return rel.startsWith(".") ? rel : `./${rel}`;
+}
+
+/**
+ * Build a Terratest smoke-test + native test for a generated module. Pure:
+ * `moduleName` names the module, `modulePath` is its repo-relative dir, and
+ * `variables` (optional) are surfaced as TODO placeholders so the test author
+ * fills in real values. Both tests plan the module directly (no `examples/`
+ * fixture). Returns the files to write + operator notes.
+ */
+export function scaffoldTerratest(opts: {
+  moduleName: string;
+  modulePath: string;
+  variables?: { name: string; required?: boolean }[];
+}): TerratestScaffold {
+  const name = opts.moduleName.replace(/[^A-Za-z0-9_-]/g, "-");
+  const fn = pascalCase(name);
+  const terraformDir = relativeUp("test", opts.modulePath);
+  const variables = opts.variables ?? [];
+
+  const goVarLines = variables
+    .map((v) => `\t\t\t// "${v.name}": nil, // ${v.required ? "(required)" : "(optional)"}`)
+    .join("\n");
+  const goTest = `package test
+
+import (
+\t"testing"
+
+\t"github.com/gruntwork-io/terratest/modules/terraform"
+\t"github.com/stretchr/testify/require"
+)
+
+// Test${fn} is a PLAN-ONLY smoke test for the ${name} module: it runs
+// terraform init + plan against the module and asserts it plans cleanly. It
+// deliberately does NOT apply, so it creates no real cloud resources. Add
+// apply/assert coverage in a pipeline where credentials exist.
+func Test${fn}(t *testing.T) {
+\tt.Parallel()
+
+\topts := &terraform.Options{
+\t\tTerraformDir: "${terraformDir}",
+\t\tNoColor:      true,
+\t\tVars: map[string]interface{}{
+\t\t\t// TODO: set the module's variables and a provider configuration before running.
+${goVarLines || "\t\t\t// (no variables detected)"}
+\t\t},
+\t}
+
+\tout := terraform.InitAndPlan(t, opts)
+\trequire.NotEmpty(t, out)
+}
+`;
+
+  return {
+    files: [
+      { path: `test/${name}_test.go`, content: goTest },
+      // a Terraform-native test too (no Go needed) — the lighter option.
+      scaffoldTerraformTest({ moduleName: name, modulePath: opts.modulePath, variables }),
+    ],
+    notes: [
+      "Set the module's variables and a provider configuration before running the tests (the scaffold leaves them as TODO placeholders).",
+      `Both tests are plan-only (no apply). Go/Terratest: \`cd test && go test -run Test${fn} -v\`. Native: \`cd ${opts.modulePath} && terraform test\`.`,
+      "The native `*.tftest.hcl` needs no Go; the Go test needs a go.mod with terratest + testify.",
+    ],
+  };
+}
+
+/**
+ * §28 (native variant) — scaffold a Terraform-native test (Terraform 1.6+) that
+ * lives in the module's own `tests/` dir and plans the module in place. Lighter
+ * than Terratest: no Go toolchain, just HCL that Terraform runs with
+ * `terraform test`. Plan-only `run` block (no apply, so no cloud needed to
+ * construct the test). Pure.
+ */
+export function scaffoldTerraformTest(opts: {
+  moduleName: string;
+  modulePath: string;
+  variables?: { name: string; required?: boolean }[];
+}): ScaffoldFile {
+  const name = opts.moduleName.replace(/[^A-Za-z0-9_-]/g, "-");
+  const varLines = (opts.variables ?? [])
+    .map((v) => `    # ${v.name} = null # ${v.required ? "(required)" : "(optional)"}`)
+    .join("\n");
+  const content = `# Terraform-native test for the ${name} module (Terraform 1.6+).
+# Plan-only — asserts the module plans cleanly without applying. Run with:
+#   cd ${opts.modulePath} && terraform test
+run "plan_${name.replace(/-/g, "_")}" {
+  command = plan
+
+  variables {
+    # TODO: set the module's variables and a provider configuration before running.
+${varLines || "    # (no variables detected)"}
+  }
+
+  # add assertions against planned values, e.g.:
+  # assert {
+  #   condition     = output.id != ""
+  #   error_message = "module must expose an id output"
+  # }
+}
+`;
+  return { path: `${opts.modulePath}/tests/${name}.tftest.hcl`, content };
+}
+
+export const ScaffoldTerratestParams = type({
+  module_name: type.string.describe("the generated module's name (e.g. 'vpc')."),
+  module_path: type.string.describe("the module's repo-relative dir (e.g. 'modules/vpc')."),
+  "variables?": type({ name: "string", "required?": "boolean" })
+    .array()
+    .describe(
+      "optional list of the module's variables, surfaced as TODO placeholders in the tests.",
+    ),
+});
+
+export function ScaffoldTerratestTool(ctx: ToolContext) {
+  return tool({
+    name: "scaffold_terratest",
+    description:
+      "Scaffold a minimal Go Terratest smoke test + a Terraform-native `*.tftest.hcl` for a module you " +
+      "GENERATED, so the new infrastructure is testable from the first commit. Both tests plan the module " +
+      "directly (Terramend does not generate `examples/` fixtures). Opt-in: only available when the " +
+      "`terratest` input is enabled (and that input also widens the push guardrail to allow the test " +
+      "files). Returns the file paths + contents to write with your own tools. The tests are PLAN-ONLY " +
+      "(never apply — Terramend holds no cloud credentials); they're for the user to run in their pipeline. " +
+      "Use it only when generating a reusable module, not for a one-off resource fix.",
+    parameters: ScaffoldTerratestParams,
+    execute: execute(async ({ module_name, module_path, variables }) => {
+      if (!ctx.payload.terratest) {
+        return {
+          enabled: false,
+          reason:
+            "terratest scaffolding is opt-in — set the `terratest: true` action input to enable it (it also widens allowed_paths to permit the test files).",
+        };
+      }
+      const scaffold = scaffoldTerratest({
+        moduleName: module_name,
+        modulePath: module_path,
+        variables: variables ?? [],
+      });
+      log.info(`» scaffold_terratest: ${scaffold.files.length} file(s) for module ${module_name}`);
+      return { enabled: true, ...scaffold };
+    }),
+  });
+}

package/src/mcp/toolFiltering.test.ts

@@ -0,0 +1,85 @@
+import { createServer } from "node:net";
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { type } from "arktype";
+import { FastMCP } from "fastmcp";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import { execute, tool } from "#app/mcp/shared";
+
+function getRandomPort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const srv = createServer();
+    srv.listen(0, "127.0.0.1", () => {
+      const addr = srv.address();
+      if (!addr || typeof addr === "string") return reject(new Error("bad address"));
+      const port = addr.port;
+      srv.close(() => resolve(port));
+    });
+  });
+}
+
+async function connectMcpClient(url: string): Promise<Client> {
+  const transport = new StreamableHTTPClientTransport(new URL(url));
+  const client = new Client({ name: "test-client", version: "0.0.1" });
+  // @ts-expect-error — exactOptionalPropertyTypes mismatch: SDK Transport.sessionId?: string vs StreamableHTTPClientTransport getter returning string | undefined
+  await client.connect(transport);
+  return client;
+}
+
+function mockTool(name: string, description: string) {
+  return tool({
+    name,
+    description,
+    parameters: type({ value: "string" }),
+    execute: execute(async () => ({ ok: true })),
+  });
+}
+
+describe("MCP server tool registration - integration", () => {
+  let server: FastMCP;
+  let serverUrl: string;
+  const clients: Client[] = [];
+
+  beforeAll(async () => {
+    const port = await getRandomPort();
+    serverUrl = `http://127.0.0.1:${port}/mcp`;
+
+    server = new FastMCP({ name: "test-server", version: "0.0.1" });
+    server.addTool(mockTool("shell", "run shell commands"));
+    server.addTool(mockTool("git", "run git commands"));
+    server.addTool(mockTool("set_output", "set output"));
+    server.addTool(mockTool("select_mode", "select a mode"));
+    server.addTool(mockTool("push_branch", "push branch"));
+    server.addTool(mockTool("create_pull_request", "create PR"));
+
+    await server.start({
+      transportType: "httpStream",
+      httpStream: { port, host: "127.0.0.1", endpoint: "/mcp" },
+    });
+  });
+
+  afterAll(async () => {
+    for (const client of clients) {
+      try {
+        await client.close();
+      } catch {
+        // best-effort cleanup
+      }
+    }
+    await server.stop();
+  });
+
+  it("server exposes all registered tools", async () => {
+    const client = await connectMcpClient(serverUrl);
+    clients.push(client);
+    const result = await client.listTools();
+    const names = result.tools.map((t) => t.name);
+    expect(names).toContain("select_mode");
+    expect(names).toContain("push_branch");
+    expect(names).toContain("create_pull_request");
+    expect(names).toContain("shell");
+    expect(names).toContain("git");
+    expect(names).toContain("set_output");
+    expect(names.length).toBe(6);
+  });
+});

package/src/mcp/upload.test.ts

@@ -0,0 +1,180 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileTypeFromBuffer } from "file-type";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import type { ToolContext } from "#app/mcp/server";
+import { UploadFileTool } from "#app/mcp/upload";
+import { apiFetch } from "#app/utils/apiFetch";
+
+vi.mock("node:fs", async (importOriginal) => {
+  const actual = await importOriginal<typeof import("node:fs")>();
+  return {
+    ...actual,
+    default: actual,
+    realpathSync: vi.fn((p: unknown) => String(p)),
+    readFileSync: vi.fn(() => Buffer.from("file-bytes")),
+  };
+});
+
+vi.mock("file-type", () => ({
+  fileTypeFromBuffer: vi.fn(async () => ({ mime: "image/png", ext: "png" })),
+}));
+
+vi.mock("#app/utils/apiFetch", () => ({
+  apiFetch: vi.fn(),
+}));
+
+const apiFetchMock = vi.mocked(apiFetch);
+const fileTypeMock = vi.mocked(fileTypeFromBuffer);
+const realpathMock = vi.mocked(fs.realpathSync);
+
+type ToolResultShape = { content: [{ type: "text"; text: string }]; isError?: boolean };
+
+async function runTool(t: { execute?: unknown }, params: unknown): Promise<ToolResultShape> {
+  const exec = t.execute as (p: unknown, c: unknown) => Promise<ToolResultShape>;
+  return exec(params, {});
+}
+
+const REPO_ROOT = path.join(path.sep, "ws", "repo");
+
+function makeCtx(): ToolContext {
+  return { apiToken: "jwt-token" } as unknown as ToolContext;
+}
+
+function signedUrlResponse(body: Record<string, unknown>, ok = true) {
+  return {
+    ok,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+  } as unknown as Response;
+}
+
+const putFetch = vi.fn(async () => ({ ok: true, statusText: "OK" }));
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  realpathMock.mockImplementation((p: unknown) => String(p));
+  fileTypeMock.mockResolvedValue({ mime: "image/png", ext: "png" } as never);
+  vi.stubEnv("GITHUB_WORKSPACE", REPO_ROOT);
+  vi.stubGlobal("fetch", putFetch);
+  putFetch.mockImplementation(async () => ({ ok: true, statusText: "OK" }));
+  apiFetchMock.mockResolvedValue(
+    signedUrlResponse({
+      uploadUrl: "https://bucket/upload?sig=1",
+      publicUrl: "https://cdn/file.png",
+    }),
+  );
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+describe("UploadFileTool", () => {
+  it("uploads a repo file and returns the public URL", async () => {
+    const filePath = path.join(REPO_ROOT, "shot.png");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("https://cdn/file.png");
+    expect(result.content[0].text).toContain("filename: shot.png");
+    expect(result.content[0].text).toContain("contentType: image/png");
+    expect(apiFetchMock).toHaveBeenCalledWith(
+      expect.objectContaining({
+        path: "/api/upload/signed-url",
+        method: "POST",
+        headers: expect.objectContaining({ Authorization: "Bearer jwt-token" }),
+      }),
+    );
+    expect(putFetch).toHaveBeenCalledWith(
+      "https://bucket/upload?sig=1",
+      expect.objectContaining({
+        method: "PUT",
+        headers: expect.objectContaining({
+          "Content-Type": "image/png",
+          "Content-Length": String(Buffer.from("file-bytes").length),
+        }),
+      }),
+    );
+  });
+
+  it("allows files inside the OS temp dir", async () => {
+    const filePath = path.join(os.tmpdir(), "scratch", "artifact.txt");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("success: true");
+  });
+
+  it("refuses to read a file outside the repo and the temp dir", async () => {
+    const filePath = path.join(path.sep, "etc", "secrets", "auth.json");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("refusing to read");
+    expect(apiFetchMock).not.toHaveBeenCalled();
+    expect(vi.mocked(fs.readFileSync)).not.toHaveBeenCalled();
+  });
+
+  it("refuses to read from the .git directory", async () => {
+    const filePath = path.join(REPO_ROOT, ".git", "config");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain(".git directory");
+  });
+
+  it("falls back to process.cwd() when GITHUB_WORKSPACE is unset", async () => {
+    vi.stubEnv("GITHUB_WORKSPACE", "");
+    const filePath = path.join(process.cwd(), "inside.txt");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.isError).toBeUndefined();
+    expect(result.content[0].text).toContain("success: true");
+  });
+
+  it("defaults the content type when file-type cannot detect one", async () => {
+    fileTypeMock.mockResolvedValue(undefined as never);
+    const filePath = path.join(REPO_ROOT, "notes.txt");
+    const result = await runTool(UploadFileTool(makeCtx()), { path: filePath });
+
+    expect(result.content[0].text).toContain("contentType: application/octet-stream");
+  });
+
+  it("sets Content-Disposition only when the API returns one", async () => {
+    apiFetchMock.mockResolvedValue(
+      signedUrlResponse({
+        uploadUrl: "https://bucket/upload",
+        publicUrl: "https://cdn/f",
+        contentDisposition: "attachment",
+      }),
+    );
+    await runTool(UploadFileTool(makeCtx()), { path: path.join(REPO_ROOT, "f.bin") });
+
+    const headers = (putFetch.mock.calls[0] as unknown[])[1] as { headers: Record<string, string> };
+    expect(headers.headers["Content-Disposition"]).toBe("attachment");
+  });
+
+  it("surfaces a signed-url failure as a tool error", async () => {
+    apiFetchMock.mockResolvedValue(signedUrlResponse({ error: "quota exceeded" }, false));
+    const result = await runTool(UploadFileTool(makeCtx()), {
+      path: path.join(REPO_ROOT, "f.bin"),
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("failed to get upload URL");
+    expect(putFetch).not.toHaveBeenCalled();
+  });
+
+  it("surfaces a failed PUT upload as a tool error", async () => {
+    putFetch.mockImplementation(async () => ({ ok: false, statusText: "Forbidden" }));
+    const result = await runTool(UploadFileTool(makeCtx()), {
+      path: path.join(REPO_ROOT, "f.bin"),
+    });
+
+    expect(result.isError).toBe(true);
+    expect(result.content[0].text).toContain("failed to upload file: Forbidden");
+  });
+});