terramend 0.2.0

package/src/utils/assets.test.ts

@@ -0,0 +1,153 @@
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { downloadAssetsInMarkdown } from "#app/utils/assets";
+
+const TOKEN = "ghs_assets_test_token";
+
+type FetchResponseSpec = {
+  ok?: boolean;
+  status?: number;
+  contentType?: string | null;
+  body?: string;
+};
+
+function makeResponse(spec: FetchResponseSpec = {}): Response {
+  const body = spec.body ?? "binary-bytes";
+  const headers = new Headers();
+  if (spec.contentType) headers.set("content-type", spec.contentType);
+  return {
+    ok: spec.ok ?? true,
+    status: spec.status ?? 200,
+    headers,
+    arrayBuffer: async () => new TextEncoder().encode(body).buffer,
+  } as unknown as Response;
+}
+
+let dir: string;
+let fetchMock: ReturnType<typeof vi.fn>;
+
+beforeEach(() => {
+  dir = mkdtempSync(path.join(tmpdir(), "terramend-assets-test-"));
+  fetchMock = vi.fn(async () => makeResponse());
+  vi.stubGlobal("fetch", fetchMock);
+});
+
+afterEach(() => {
+  vi.unstubAllGlobals();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+describe("downloadAssetsInMarkdown", () => {
+  it("returns the markdown unchanged and skips fetch when no asset urls are present", async () => {
+    const markdown = "plain text ![alt](https://example.com/image.png) not a github asset";
+    const result = await downloadAssetsInMarkdown(markdown, dir, TOKEN);
+    expect(result).toBe(markdown);
+    expect(fetchMock).not.toHaveBeenCalled();
+  });
+
+  it("downloads a github.com asset with the installation token and rewrites the url", async () => {
+    const url = "https://github.com/user-attachments/assets/abc-123";
+    fetchMock.mockResolvedValueOnce(makeResponse({ contentType: "image/png", body: "png-data" }));
+
+    const result = await downloadAssetsInMarkdown(`before ![shot](${url}) after`, dir, TOKEN);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [calledUrl, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(calledUrl).toBe(url);
+    expect(init.headers).toEqual({ Authorization: `Bearer ${TOKEN}` });
+
+    expect(result).not.toContain(url);
+    const localPathMatch = /!\[shot\]\((.+)\)/.exec(result);
+    expect(localPathMatch).not.toBeNull();
+    const localPath = localPathMatch?.[1] ?? "";
+    expect(localPath.startsWith(path.join(dir, "assets"))).toBe(true);
+    expect(localPath.endsWith(".png")).toBe(true);
+    expect(readFileSync(localPath, "utf-8")).toBe("png-data");
+  });
+
+  it("fetches signed CDN urls WITHOUT an Authorization header", async () => {
+    const url = "https://private-user-images.githubusercontent.com/1/2.png?jwt=sig";
+    await downloadAssetsInMarkdown(`![cdn](${url})`, dir, TOKEN);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    const [, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(init.headers).toEqual({});
+  });
+
+  it("extracts urls from html <img> tags and owner/repo asset paths", async () => {
+    const url = "https://github.com/octo/repo/assets/99/deadbeef.gif";
+    const markdown = `<p><img alt="x" src="${url}"></p>`;
+    const result = await downloadAssetsInMarkdown(markdown, dir, TOKEN);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(result).not.toContain(url);
+  });
+
+  it("downloads each unique url once and rewrites every occurrence", async () => {
+    const url = "https://github.com/user-attachments/assets/dup-1.png";
+    const markdown = `![a](${url})\n![b](${url})\n<img src="${url}">`;
+    const result = await downloadAssetsInMarkdown(markdown, dir, TOKEN);
+
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(result).not.toContain(url);
+  });
+
+  it("leaves the url untouched when the download responds non-ok", async () => {
+    const url = "https://github.com/user-attachments/assets/missing.png";
+    fetchMock.mockResolvedValueOnce(makeResponse({ ok: false, status: 404 }));
+
+    const result = await downloadAssetsInMarkdown(`![x](${url})`, dir, TOKEN);
+    expect(result).toContain(url);
+  });
+
+  it("leaves the url untouched when fetch throws", async () => {
+    const url = "https://github.com/user-attachments/assets/error.png";
+    fetchMock.mockRejectedValueOnce(new Error("network down"));
+
+    const result = await downloadAssetsInMarkdown(`![x](${url})`, dir, TOKEN);
+    expect(result).toContain(url);
+  });
+});
+
+describe("extension resolution", () => {
+  async function localPathFor(url: string, contentType: string | null): Promise<string> {
+    fetchMock.mockResolvedValueOnce(makeResponse({ contentType }));
+    const result = await downloadAssetsInMarkdown(`![x](${url})`, dir, TOKEN);
+    const match = /!\[x\]\((.+)\)/.exec(result);
+    expect(match).not.toBeNull();
+    return match?.[1] ?? "";
+  }
+
+  const base = "https://github.com/user-attachments/assets";
+
+  it("keeps a whitelisted extension from the url path", async () => {
+    expect(await localPathFor(`${base}/clip.webm`, null)).toMatch(/\.webm$/);
+  });
+
+  it("normalizes .jpeg in the url path to .jpg", async () => {
+    expect(await localPathFor(`${base}/photo.jpeg`, null)).toMatch(/\.jpg$/);
+  });
+
+  it.each([
+    ["image/jpeg", ".jpg"],
+    ["image/gif", ".gif"],
+    ["image/webp", ".webp"],
+    ["image/svg+xml", ".svg"],
+    ["video/mp4", ".mp4"],
+    ["video/quicktime", ".mov"],
+    ["video/webm", ".webm"],
+  ])("derives %s from the response content-type as %s", async (contentType, ext) => {
+    const localPath = await localPathFor(`${base}/raw-${ext.slice(1)}`, contentType);
+    expect(localPath.endsWith(ext)).toBe(true);
+  });
+
+  it("defaults to .png when neither path nor content-type resolve", async () => {
+    expect(await localPathFor(`${base}/opaque-blob`, "application/octet-stream")).toMatch(/\.png$/);
+  });
+
+  it("defaults to .png when the response has no content-type header at all", async () => {
+    expect(await localPathFor(`${base}/headerless-blob`, null)).toMatch(/\.png$/);
+  });
+});

package/src/utils/assets.ts

@@ -0,0 +1,107 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { log } from "#app/utils/cli";
+
+// github image hosts that appear in issue/PR/review/comment markdown.
+//  - github.com/user-attachments/assets/... and github.com/<owner>/<repo>/assets/...
+//    are the raw urls present in *unrendered* bodies (the MCP tools return these);
+//    fetching them needs the installation token.
+//  - {private-user-images,user-images,camo}.githubusercontent.com/... are the signed
+//    urls produced by body_html→turndown (see resolveBody); they self-authenticate via
+//    a jwt/signature in the query string and must be fetched WITHOUT an Authorization
+//    header (sending the token to the CDN would leak it).
+const ASSET_HOST = String.raw`(?:github\.com\/(?:user-attachments\/assets|[^/\s]+\/[^/\s]+\/assets)\/|(?:private-user-images|user-images|camo)\.githubusercontent\.com\/)`;
+const MARKDOWN_IMAGE = new RegExp(String.raw`!\[[^\]]*\]\((https:\/\/${ASSET_HOST}[^\s"')]+)`, "g");
+const HTML_IMAGE = new RegExp(String.raw`<img[^>]+src=["'](https:\/\/${ASSET_HOST}[^"'\s]+)`, "g");
+
+const ALLOWED_EXTENSIONS = new Set([
+  ".png",
+  ".jpg",
+  ".gif",
+  ".webp",
+  ".svg",
+  ".mp4",
+  ".mov",
+  ".webm",
+]);
+
+/**
+ * downloads any github-hosted image/video assets referenced in `markdown` to
+ * `<tmpdir>/assets` and rewrites the urls to the local file paths, so the agent can
+ * read screenshots directly instead of relying on remote (often short-lived, signed)
+ * urls. unique urls are downloaded once and every occurrence is rewritten. assets that
+ * fail to download are left untouched.
+ */
+export async function downloadAssetsInMarkdown(
+  markdown: string,
+  tmpdir: string,
+  githubToken: string,
+): Promise<string> {
+  const urls = new Set<string>();
+  for (const match of markdown.matchAll(MARKDOWN_IMAGE)) urls.add(match[1]!);
+  for (const match of markdown.matchAll(HTML_IMAGE)) urls.add(match[1]!);
+
+  if (urls.size === 0) return markdown;
+
+  const assetsDir = path.join(tmpdir, "assets");
+  fs.mkdirSync(assetsDir, { recursive: true });
+
+  log.debug(`[assets] found ${urls.size} asset(s) to download`);
+
+  let result = markdown;
+  for (const url of urls) {
+    const localPath = await downloadAsset(url, assetsDir, githubToken);
+    if (localPath) result = result.replaceAll(url, localPath);
+  }
+  return result;
+}
+
+async function downloadAsset(
+  url: string,
+  assetsDir: string,
+  githubToken: string,
+): Promise<string | null> {
+  // only github.com itself needs the installation token; the githubusercontent CDN
+  // urls carry their own signature. `redirect: "follow"` (undici default) strips the
+  // Authorization header on cross-origin hops, so the token never reaches S3/the CDN.
+  const needsAuth = new URL(url).hostname === "github.com";
+
+  try {
+    const res = await fetch(url, {
+      headers: needsAuth ? { Authorization: `Bearer ${githubToken}` } : {},
+    });
+    if (!res.ok) {
+      log.warning(`[assets] failed to download ${url}: ${res.status}`);
+      return null;
+    }
+
+    const buffer = Buffer.from(await res.arrayBuffer());
+    const ext = resolveExtension(url, res.headers.get("content-type"));
+    const filename = `${crypto.createHash("sha256").update(url).digest("hex").slice(0, 16)}${ext}`;
+    const localPath = path.join(assetsDir, filename);
+    fs.writeFileSync(localPath, buffer);
+    log.debug(`[assets] downloaded ${url} to ${localPath}`);
+    return localPath;
+  } catch (e) {
+    log.warning(`[assets] error downloading ${url}: ${e}`);
+    return null;
+  }
+}
+
+/** picks a safe, whitelisted file extension from the url path or response content-type. */
+function resolveExtension(url: string, contentType: string | null): string {
+  const fromPath = path.extname(new URL(url).pathname).toLowerCase();
+  if (ALLOWED_EXTENSIONS.has(fromPath)) return fromPath;
+  if (fromPath === ".jpeg") return ".jpg";
+
+  const ct = contentType?.toLowerCase() ?? "";
+  if (ct.includes("jpeg") || ct.includes("jpg")) return ".jpg";
+  if (ct.includes("gif")) return ".gif";
+  if (ct.includes("webp")) return ".webp";
+  if (ct.includes("svg")) return ".svg";
+  if (ct.includes("mp4")) return ".mp4";
+  if (ct.includes("quicktime") || ct.includes("mov")) return ".mov";
+  if (ct.includes("webm")) return ".webm";
+  return ".png";
+}

package/src/utils/billingErrors.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+import {
+  BillingError,
+  formatBillingErrorSummary,
+  formatTransientErrorSummary,
+  TransientError,
+} from "#app/utils/billingErrors";
+
+describe("BillingError", () => {
+  it("defaults the classification fields", () => {
+    const error = new BillingError("payment failed");
+    expect(error.name).toBe("BillingError");
+    expect(error.message).toBe("payment failed");
+    expect(error.code).toBeNull();
+    expect(error.declineCode).toBeNull();
+    expect(error.needsReauthentication).toBe(false);
+  });
+
+  it("keeps the provided classification fields", () => {
+    const error = new BillingError("declined", {
+      code: "router_requires_card",
+      declineCode: "insufficient_funds",
+      needsReauthentication: true,
+    });
+    expect(error.code).toBe("router_requires_card");
+    expect(error.declineCode).toBe("insufficient_funds");
+    expect(error.needsReauthentication).toBe(true);
+  });
+});
+
+describe("formatBillingErrorSummary", () => {
+  it("renders the add-a-card CTA for router_requires_card", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { code: "router_requires_card" }),
+      "acme",
+    );
+    expect(msg).toContain("**Add a card to start using Terramend Router.**");
+    expect(msg).toContain("https://terramend.com/console/acme#model-access");
+  });
+
+  it("renders the exhausted-balance CTA for router_balance_exhausted", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { code: "router_balance_exhausted" }),
+      "acme",
+    );
+    expect(msg).toContain("balance is exhausted");
+    expect(msg).toContain("https://terramend.com/console/acme#billing");
+    expect(msg).toContain("https://terramend.com/console/acme#model-access");
+  });
+
+  it("renders the cut-short framing for router_keylimit_exhausted", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { code: "router_keylimit_exhausted" }),
+      "acme",
+    );
+    expect(msg).toContain("cut short");
+    expect(msg).toContain("#billing");
+  });
+
+  it("renders the monthly-cap framing for router_monthly_limit", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { code: "router_monthly_limit" }),
+      "acme",
+    );
+    expect(msg).toContain("monthly spend limit");
+    expect(msg).toContain("#model-access");
+  });
+
+  it("renders the 3DS branch with the specific decline code when present", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { needsReauthentication: true, declineCode: "authentication_needed" }),
+      "acme",
+    );
+    expect(msg).toContain("3D Secure");
+    expect(msg).toContain("`authentication_needed`");
+  });
+
+  it("falls back to authentication_required when 3DS has no decline code", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { needsReauthentication: true }),
+      "acme",
+    );
+    expect(msg).toContain("`authentication_required`");
+  });
+
+  it("renders the card-declined branch with the Stripe sub-code", () => {
+    const msg = formatBillingErrorSummary(
+      new BillingError("x", { declineCode: "lost_card" }),
+      "acme",
+    );
+    expect(msg).toContain("**Your card was declined** (`lost_card`).");
+    expect(msg).toContain("#billing");
+  });
+
+  it("renders the empty-balance default branch", () => {
+    const msg = formatBillingErrorSummary(new BillingError("x"), "acme");
+    expect(msg).toContain("**Your Terramend balance is empty.**");
+    expect(msg).toContain("https://terramend.com/console/acme#billing");
+  });
+
+  it("URL-encodes the owner in the console deep link", () => {
+    const msg = formatBillingErrorSummary(new BillingError("x"), "weird org");
+    expect(msg).toContain("https://terramend.com/console/weird%20org#billing");
+  });
+});
+
+describe("TransientError / formatTransientErrorSummary", () => {
+  it("names the error class", () => {
+    const error = new TransientError("sync in flight");
+    expect(error.name).toBe("TransientError");
+    expect(error.message).toBe("sync in flight");
+  });
+
+  it("frames the failure as temporary and includes the message + console link", () => {
+    const msg = formatTransientErrorSummary(new TransientError("usage sync incomplete"), "acme");
+    expect(msg).toContain("temporarily unavailable");
+    expect(msg).toContain("usage sync incomplete");
+    expect(msg).toContain("status.terramend.com");
+    expect(msg).toContain("https://terramend.com/console/acme#billing");
+  });
+});

package/src/utils/billingErrors.ts

@@ -0,0 +1,189 @@
+/**
+ * Billing-error classification + user-facing copy for `/api/proxy-token`
+ * failures and OpenRouter mid-run exhaustion. Two error classes (Billing vs.
+ * Transient) keep the framing honest: a card decline is *not* the same UX as
+ * a 503 from the proxy service. Both originate in `utils/proxy.ts` (mint
+ * failures) and `utils/runErrorRenderer.ts` (mid-run keylimit reclassify).
+ *
+ * Renderers return markdown bodies that are written into both the GitHub
+ * Actions job summary and the PR progress comment.
+ *
+ * Lives outside `main.ts` so adding a new error `code` branch is a one-file
+ * edit that does not retrigger the full LLM CI matrix (`action/main.ts` is
+ * in `action/test/coverage.ts::ALWAYS_RUN_ALL`).
+ */
+
+/**
+ * Billing-layer error surfaced from `/api/proxy-token` as a 402. User-actionable
+ * — distinct from TransientError (503 / transient sync issue) so the job
+ * summary + PR comment can use affirmative "you need to do X" copy rather than
+ * the ambiguous "billing error" label that makes transient outages look like
+ * the user's fault.
+ *
+ * `code` is a server-side discriminator: `router_requires_card` (no card + no
+ * wallet balance on Router), or null for unclassified. `declineCode` is
+ * Stripe's more specific sub-reason on `card_declined` (e.g.
+ * `insufficient_funds`, `lost_card`). `needsReauthentication` is the 3DS case
+ * broken out for convenience.
+ */
+export class BillingError extends Error {
+  code: string | null;
+  declineCode: string | null;
+  needsReauthentication: boolean;
+
+  constructor(
+    message: string,
+    opts: {
+      code?: string | null;
+      declineCode?: string | null;
+      needsReauthentication?: boolean;
+    } = {},
+  ) {
+    super(message);
+    this.name = "BillingError";
+    this.code = opts.code ?? null;
+    this.declineCode = opts.declineCode ?? null;
+    this.needsReauthentication = opts.needsReauthentication ?? false;
+  }
+}
+
+/**
+ * Transient service failures from `/api/proxy-token` (503: partial OpenRouter
+ * usage sync, DB flake, in-flight payment intent). Not the user's fault — the
+ * summary uses "temporarily unavailable" framing, and the non-zero exit lets
+ * GH Actions apply whatever retry policy the workflow has configured.
+ */
+export class TransientError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "TransientError";
+  }
+}
+
+/**
+ * Deep link into the right console section for the failing account. Anchors
+ * are defined in `app/console/[owner]/page.tsx` (`#billing`, `#model-access`).
+ * `owner` is the GitHub login of the repo's account — i.e. the org or user
+ * that pays for this repo's runs, which is the right scope for billing.
+ */
+function billingConsoleUrl(owner: string, anchor: "billing" | "model-access"): string {
+  return `https://terramend.com/console/${encodeURIComponent(owner)}#${anchor}`;
+}
+
+/**
+ * Render a BillingError as user-facing markdown (shared between GH job summary
+ * and the PR progress comment). Goals:
+ *
+ *   - quiet, not alarmist — bold first line instead of an `### ❌` H3, since
+ *     the comment already has Terramend branding in the footer
+ *   - actionable — every branch ends in a single CTA deep-linked to the
+ *     correct section of the owner's console
+ *   - honest — say what actually went wrong (card declined vs. balance
+ *     empty vs. 3DS required), don't lump them under "billing error"
+ *
+ * Branches:
+ *   - `router_requires_card`: user is on Router mode with no card AND no
+ *     wallet balance (signup credit exhausted or not granted). Frame as
+ *     "add a card to continue", link to `#model-access` where the Add
+ *     Card flow lives.
+ *   - `router_balance_exhausted`: user has a card on file but auto-reload is
+ *     disabled and they've spent past their $5 overdraft buffer. Frame as
+ *     "balance ran out" and surface both remediation paths (top up, or flip
+ *     on auto-reload).
+ *   - `router_keylimit_exhausted`: OpenRouter rejected mid-run because the
+ *     per-run key budget was exhausted while the agent was working. The
+ *     wallet is now negative; same remediation as `router_balance_exhausted`
+ *     but framed for the after-the-fact case ("this run was cut short").
+ *   - `needsReauthentication`: issuer requires 3DS on every off-session
+ *     charge. Re-adding the card won't help — the only escape is a manual
+ *     top-up where 3DS runs interactively in Stripe Checkout.
+ *   - `declineCode` set: Stripe declined a real charge. Show the sub-code
+ *     so support can act on it; tell the user we'll retry on next dispatch.
+ *   - default: balance hit zero with no in-flight charge (auto-reload off
+ *     or amount below threshold). Direct them to top up or enable auto-reload.
+ */
+export function formatBillingErrorSummary(error: BillingError, owner: string): string {
+  if (error.code === "router_requires_card") {
+    return [
+      "**Add a card to start using Terramend Router.**",
+      "",
+      "Router proxies OpenRouter at raw cost — no platform markup. Add a card and we'll auto-reload your wallet so runs keep flowing.",
+      "",
+      `[Add a card →](${billingConsoleUrl(owner, "model-access")})`,
+    ].join("\n");
+  }
+
+  if (error.code === "router_balance_exhausted") {
+    return [
+      "**Your Terramend Router balance is exhausted.**",
+      "",
+      "You have a card on file but auto-reload is disabled, so runs paused once your balance went past the overdraft buffer.",
+      "",
+      `[Top up balance →](${billingConsoleUrl(owner, "billing")}) · [Enable auto-reload →](${billingConsoleUrl(owner, "model-access")})`,
+    ].join("\n");
+  }
+
+  if (error.code === "router_keylimit_exhausted") {
+    return [
+      "**This run was cut short — your Terramend Router balance ran out mid-run.**",
+      "",
+      "OpenRouter stopped the agent because the per-run budget was exhausted. Your wallet is now negative; top up or enable auto-reload to keep runs flowing.",
+      "",
+      `[Top up balance →](${billingConsoleUrl(owner, "billing")}) · [Enable auto-reload →](${billingConsoleUrl(owner, "model-access")})`,
+    ].join("\n");
+  }
+
+  if (error.code === "router_monthly_limit") {
+    return [
+      "**Terramend Router hit its monthly spend limit.**",
+      "",
+      "Auto-reloads are paused for the rest of this UTC month. Ask your admin to raise the cap, or wait for it to reset at 00:00 UTC on the 1st.",
+      "",
+      `[Adjust limit →](${billingConsoleUrl(owner, "model-access")})`,
+    ].join("\n");
+  }
+
+  if (error.needsReauthentication) {
+    const code = error.declineCode ?? "authentication_required";
+    return [
+      `**Your card issuer requires 3D Secure on every charge** (\`${code}\`).`,
+      "",
+      "Terramend can't complete a 3DS challenge from inside a workflow. Top up your Router balance once in Stripe Checkout — subsequent runs draw from the prepaid balance without re-triggering 3DS.",
+      "",
+      `[Top up balance →](${billingConsoleUrl(owner, "billing")})`,
+    ].join("\n");
+  }
+
+  if (error.declineCode) {
+    return [
+      `**Your card was declined** (\`${error.declineCode}\`).`,
+      "",
+      "Update your payment method and Terramend will retry on the next run.",
+      "",
+      `[Update payment method →](${billingConsoleUrl(owner, "billing")})`,
+    ].join("\n");
+  }
+
+  return [
+    "**Your Terramend balance is empty.**",
+    "",
+    "Top up your balance or enable auto-reload to keep runs flowing.",
+    "",
+    `[Manage billing →](${billingConsoleUrl(owner, "billing")})`,
+  ].join("\n");
+}
+
+/**
+ * Render a TransientError as user-facing markdown. Distinct framing from
+ * BillingError so the user doesn't read an alarm and assume their card
+ * failed — this branch is "our fault, retry shortly", not theirs.
+ */
+export function formatTransientErrorSummary(error: TransientError, owner: string): string {
+  return [
+    "**Terramend billing is temporarily unavailable.**",
+    "",
+    error.message,
+    "",
+    `Usually transient — the next dispatch should succeed. If it persists, check [status.terramend.com](https://status.terramend.com) or [your console](${billingConsoleUrl(owner, "billing")}).`,
+  ].join("\n");
+}