@appthrust/kest 0.6.0 → 0.8.0

package/README.md

@@ -443,6 +443,23 @@ namespace "kest-9hdhj" deleted
 bun add -d @appthrust/kest
 ```
 
+### TypeScript Configuration
+
+If your project doesn't have a `tsconfig.json` yet, install the Bun TypeScript preset and create one:
+
+```sh
+bun add -D @types/bun @tsconfig/bun
+```
+
+```json
+// tsconfig.json
+{
+  "extends": "@tsconfig/bun"
+}
+```
+
+This enables proper type checking, autocompletion, and compatibility with Bun's APIs.
+
 ### Write Your First Test
 
 Create a test file, e.g. `my-operator.test.ts`:
@@ -802,6 +819,114 @@ await ns.apply(import("./fixtures/deployment-v1.ts"));
 - [ ] Is the diff between test steps visible as a spec-level change?
 - [ ] Can you reconstruct the applied manifest from the failure report alone?
 
+### Reuse manifests with mutation for update scenarios
+
+The "keep manifests visible" principle works well when each `apply` is independent. But in **update scenarios** -- where a test applies the same resource twice with a small change -- duplicating the entire manifest obscures the intent. The reader has to mentally diff two large blocks to spot what actually changed:
+
+```ts
+// ❌ Bad — the two manifests are nearly identical.
+//    The reader must scan every line to find the one difference.
+test("scaling up increases available replicas", async (s) => {
+  const ns = await s.newNamespace();
+
+  s.when("I apply a Deployment with 1 replica");
+  await ns.apply({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name: "my-app" },
+    spec: {
+      replicas: 1,
+      selector: { matchLabels: { app: "my-app" } },
+      template: {
+        metadata: { labels: { app: "my-app" } },
+        spec: { containers: [{ name: "app", image: "nginx" }] },
+      },
+    },
+  });
+
+  s.when("I scale to 3 replicas");
+  await ns.apply({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    metadata: { name: "my-app" },
+    spec: {
+      replicas: 3, // <-- the only change, buried in a wall of duplication
+      selector: { matchLabels: { app: "my-app" } },
+      template: {
+        metadata: { labels: { app: "my-app" } },
+        spec: { containers: [{ name: "app", image: "nginx" }] },
+      },
+    },
+  });
+
+  s.then("the Deployment should have 3 available replicas");
+  await ns.assert({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    name: "my-app",
+    test() {
+      expect(this.status?.availableReplicas).toBe(3);
+    },
+  });
+});
+```
+
+Instead, define the manifest once, then use `structuredClone` to create a copy and mutate only the fields the scenario cares about. The mutation lines **are** the test scenario -- they tell the reader exactly what changed:
+
+```ts
+// ✅ Good — the base manifest is visible, and the mutation is the scenario.
+test("scaling up increases available replicas", async (s) => {
+  const ns = await s.newNamespace();
+
+  s.when("I apply a Deployment with 1 replica");
+  const deployment = {
+    apiVersion: "apps/v1" as const,
+    kind: "Deployment" as const,
+    metadata: { name: "my-app" },
+    spec: {
+      replicas: 1,
+      selector: { matchLabels: { app: "my-app" } },
+      template: {
+        metadata: { labels: { app: "my-app" } },
+        spec: { containers: [{ name: "app", image: "nginx" }] },
+      },
+    },
+  };
+  await ns.apply(deployment);
+
+  s.when("I scale to 3 replicas");
+  const scaled = structuredClone(deployment);
+  scaled.spec.replicas = 3;
+  await ns.apply(scaled);
+
+  s.then("the Deployment should have 3 available replicas");
+  await ns.assert({
+    apiVersion: "apps/v1",
+    kind: "Deployment",
+    name: "my-app",
+    test() {
+      expect(this.status?.availableReplicas).toBe(3);
+    },
+  });
+});
+```
+
+`structuredClone` is a standard API (no dependencies) that creates a true deep copy, so mutations never affect the original. The base manifest stays fully visible in the test, and the mutation lines make the intent unmistakable.
+
+**When to use which approach:**
+
+| Scenario | Approach |
+| --- | --- |
+| Each `apply` is a different resource or independent input | Inline each manifest separately (keep manifests visible) |
+| The same resource is applied twice with a small change | `structuredClone` + targeted mutation |
+| The manifest is too large to inline comfortably | Static fixture files (`import("./fixtures/...")`) |
+
+**Mutation-readability checklist:**
+
+- [ ] Is the base manifest defined once and fully visible in the test?
+- [ ] Are only the fields relevant to the scenario mutated?
+- [ ] Can a reader understand the update by reading just the mutation lines?
+
 ### Avoiding naming collisions between tests
 
 When tests run in parallel, hard-coded resource names can collide. In most cases, `newNamespace()` is all you need -- each test gets its own namespace, so names like `"my-config"` or `"my-app"` are already isolated:
@@ -929,6 +1054,50 @@ await s.create({
 - [ ] Is `generateName` reserved for cluster-scoped resources or multi-instance cases?
 - [ ] Can you identify every resource in the failure report without decoding random suffixes?
 
+### Use `toMatchObject` for assertions without type parameters
+
+When you omit the type parameter from assertion actions (`assert`, `assertList`,
+`assertOne`, etc.), `this` is typed as the generic `K8sResource`. Custom fields
+like `spec` become `unknown`, forcing type casts on every access:
+
+```ts
+// ❌ Without a type parameter, every field access needs a cast
+await ns.assert({
+  apiVersion: "example.com/v1",
+  kind: "MyResource",
+  name: "my-instance",
+  test() {
+    expect((this.spec as any).replicas).toBe(3);
+    expect((this.spec as any).image).toBe("my-app:latest");
+  },
+});
+```
+
+Use `toMatchObject` instead — it accepts a plain object and checks that the
+resource contains the expected subset, with no type narrowing required:
+
+```ts
+// ✅ toMatchObject — no casts, no type parameter needed
+await ns.assert({
+  apiVersion: "example.com/v1",
+  kind: "MyResource",
+  name: "my-instance",
+  test() {
+    expect(this).toMatchObject({
+      spec: {
+        replicas: 3,
+        image: "my-app:latest",
+      },
+    });
+  },
+});
+```
+
+**When to use which:**
+
+- **With a type parameter** (e.g. `assert<MyResource>`) — either style works; `this` is fully typed, so it's a matter of preference.
+- **Without a type parameter** — always use `toMatchObject`. `this.spec` is `unknown`, and `toMatchObject` scales naturally as you add more assertions.
+
 ## Type Safety
 
 Define TypeScript interfaces for your Kubernetes resources to get full type checking in manifests and assertions:

package/example/example.test.ts

@@ -60,6 +60,34 @@ test("Example: applies ConfigMap using YAML, file import, and object literal", a
   // 4. Namespace
 });
 
+test("Example: diff demo - ConfigMap data mismatch (expected to fail)", async (s) => {
+  s.given("a new namespace exists");
+  const ns = await s.newNamespace();
+
+  s.when("I apply a ConfigMap with actual data");
+  await ns.apply<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    metadata: { name: "diff-demo" },
+    data: { mode: "actual-value", env: "production" },
+  });
+
+  s.then("asserting with different expected data should produce a diff");
+  await ns.assert<ConfigMap>({
+    apiVersion: "v1",
+    kind: "ConfigMap",
+    name: "diff-demo",
+    test() {
+      expect(this).toMatchObject({
+        data: {
+          mode: "expected-value",
+          env: "staging",
+        },
+      });
+    },
+  });
+});
+
 test("Example: asserts a non-existent ConfigMap (expected to fail)", async (s) => {
   s.given("a new namespace exists");
   const ns = await s.newNamespace();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@appthrust/kest",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Kubernetes E2E testing framework designed for humans and AI alike",
   "type": "module",
   "module": "ts/index.ts",

package/ts/apis/index.ts

@@ -1487,7 +1487,27 @@ export interface K8sResource {
   kind: string;
   metadata: {
     name: string;
-    namespace?: string;
+    namespace?: string | undefined;
+    labels?: Record<string, string> | undefined;
+    annotations?: Record<string, string> | undefined;
+    resourceVersion?: string | undefined;
+    uid?: string | undefined;
+    creationTimestamp?: string | undefined;
+    generation?: number | undefined;
+    finalizers?: ReadonlyArray<string> | undefined;
+    ownerReferences?:
+      | ReadonlyArray<{
+          apiVersion: string;
+          kind: string;
+          name: string;
+          uid: string;
+          controller?: boolean | undefined;
+          blockOwnerDeletion?: boolean | undefined;
+        }>
+      | undefined;
+    deletionTimestamp?: string | undefined;
+    deletionGracePeriodSeconds?: number | undefined;
+    generateName?: string | undefined;
     [key: string]: unknown;
   };
   [key: string]: unknown;

package/ts/recording/index.ts

@@ -53,6 +53,7 @@ type CommandEvent =
 
 type RetryEvent =
   | BaseEvent<"RetryStart", Record<string, never>>
+  | BaseEvent<"RetryAttempt", { readonly attempt: number }>
   | BaseEvent<
       "RetryEnd",
       | {

package/ts/reporter/markdown/index.ts

@@ -9,6 +9,7 @@ export interface MarkdownReporterOptions {
    * If false (default), remove ANSI escape codes.
    */
   enableANSI?: undefined | boolean;
+  workspaceRoot?: undefined | string;
 }
 
 export function newMarkdownReporter(

package/ts/reporter/markdown/parser/index.ts

@@ -7,6 +7,7 @@ import type {
   Report,
   Scenario,
 } from "../model";
+import { stripAnsi } from "../strip-ansi";
 
 const bddKeywordByKind = {
   BDDGiven: "given",
@@ -89,6 +90,9 @@ function handleNonBDDEvent(state: ParseState, event: Event): void {
     case "RetryEnd":
       handleRetryEnd(state, event);
       return;
+    case "RetryAttempt":
+      handleRetryAttempt(state);
+      return;
     case "RetryStart":
       return;
     default:
@@ -158,8 +162,11 @@ function applyRegularActionEnd(
     currentAction.error = {
       message: {
         text: event.data.error.message,
-        language: isDiffLike(event.data.error.message) ? "diff" : "text",
+        language: isDiffLike(stripAnsi(event.data.error.message))
+          ? "diff"
+          : "text",
       },
+      stack: event.data.error.stack,
     };
   }
 
@@ -263,6 +270,16 @@ function handleCleanupActionEnd(
   return true;
 }
 
+function handleRetryAttempt(state: ParseState): void {
+  if (state.inCleanup) {
+    return;
+  }
+  if (!state.currentAction) {
+    return;
+  }
+  state.currentAction.commands = [];
+}
+
 function handleRetryEnd(
   state: ParseState,
   event: Extract<Event, { kind: "RetryEnd" }>
@@ -342,7 +359,7 @@ function bddFromEvent(event: Event): BDDSection | undefined {
   return { keyword, description: event.data.description, actions: [] };
 }
 
-function isDiffLike(message: string): boolean {
+export function isDiffLike(message: string): boolean {
   const lines = message.split(/\r?\n/);
   let sawPlus = false;
   let sawMinus = false;

package/ts/reporter/markdown/renderer/index.ts

@@ -1,6 +1,8 @@
 import { codeToANSIForcedColors } from "../../shiki";
 import type { MarkdownReporterOptions } from "../index";
 import type { Action, Report } from "../model";
+import { stripAnsi } from "../strip-ansi";
+import { renderTrace } from "../trace/render";
 
 const markdownLang = "markdown";
 const markdownTheme = "catppuccin-mocha";
@@ -11,6 +13,11 @@ type StdinReplacement = Readonly<{
   stdinLanguage: string;
 }>;
 
+type TraceReplacement = Readonly<{
+  placeholder: string;
+  rawStack: string;
+}>;
+
 function normalizeStdin(stdin: string): string {
   // Match `ts/reporter/markdown.ts` behavior: keep content stable.
   return stdin.replace(/^\n/, "").replace(/\s+$/, "");
@@ -41,9 +48,40 @@ function applyStdinReplacements(
   return current;
 }
 
+async function resolveTraceReplacements(
+  markdown: string,
+  replacements: ReadonlyArray<TraceReplacement>,
+  options: MarkdownReporterOptions
+): Promise<string> {
+  if (replacements.length === 0) {
+    return markdown;
+  }
+
+  let current = markdown;
+  for (const r of replacements) {
+    const rendered = await renderTrace(r.rawStack, {
+      workspaceRoot: options.workspaceRoot,
+      enableANSI: options.enableANSI,
+    });
+
+    if (rendered) {
+      current = current.replace(r.placeholder, rendered);
+    } else {
+      // Remove the entire trace code block (fences + placeholder + blank line)
+      current = current.replace(
+        `\`\`\`ts title="trace"\n${r.placeholder}\n\`\`\`\n\n`,
+        ""
+      );
+    }
+  }
+  return current;
+}
+
 async function highlightMarkdown(
   markdown: string,
-  stdinReplacements: ReadonlyArray<StdinReplacement>
+  stdinReplacements: ReadonlyArray<StdinReplacement>,
+  traceReplacements: ReadonlyArray<TraceReplacement>,
+  options: MarkdownReporterOptions
 ): Promise<string> {
   const stripped = stripAnsi(markdown);
   try {
@@ -53,45 +91,34 @@ async function highlightMarkdown(
       markdownTheme
     );
 
-    if (stdinReplacements.length === 0) {
-      // Keep output shape stable: always end with a single trailing newline.
-      return highlightedMarkdown.replace(/\n+$/, "\n");
+    let result = highlightedMarkdown;
+
+    if (stdinReplacements.length > 0) {
+      const highlightedStdinList = await Promise.all(
+        stdinReplacements.map(async (r) => {
+          const highlightedStdin = await codeToANSIForcedColors(
+            r.stdin,
+            r.stdinLanguage,
+            markdownTheme
+          );
+          // Avoid inserting an extra blank line before `EOF`.
+          const trimmed = trimFinalNewline(
+            highlightedStdin.replace(/\n+$/, "\n")
+          );
+          return { ...r, stdin: trimmed } satisfies StdinReplacement;
+        })
+      );
+      result = applyStdinReplacements(result, highlightedStdinList);
     }
 
-    const highlightedStdinList = await Promise.all(
-      stdinReplacements.map(async (r) => {
-        const highlightedStdin = await codeToANSIForcedColors(
-          r.stdin,
-          r.stdinLanguage,
-          markdownTheme
-        );
-        // Avoid inserting an extra blank line before `EOF`.
-        const trimmed = trimFinalNewline(
-          highlightedStdin.replace(/\n+$/, "\n")
-        );
-        return { ...r, stdin: trimmed } satisfies StdinReplacement;
-      })
-    );
+    result = await resolveTraceReplacements(result, traceReplacements, options);
 
-    const replaced = applyStdinReplacements(
-      highlightedMarkdown,
-      highlightedStdinList
-    );
-    return replaced.replace(/\n+$/, "\n");
+    return result.replace(/\n+$/, "\n");
   } catch {
     return stripped;
   }
 }
 
-function stripAnsi(input: string): string {
-  // Prefer Bun's built-in ANSI stripper when available.
-  if (typeof Bun !== "undefined" && typeof Bun.stripANSI === "function") {
-    return Bun.stripANSI(input);
-  }
-  // biome-ignore lint/suspicious/noControlCharactersInRegex: intended
-  return input.replace(/\u001b\[[0-9;]*m/g, "");
-}
-
 function trimFinalNewline(input: string): string {
   return input.replace(/\n$/, "");
 }
@@ -114,7 +141,7 @@ function statusEmoji(status: keyof typeof statusEmojiByStatus): string {
 }
 
 // biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
-export function renderReport(
+export async function renderReport(
   report: Report,
   options: MarkdownReporterOptions
 ): Promise<string> {
@@ -122,7 +149,9 @@ export function renderReport(
 
   const renderedScenarios: Array<string> = [];
   const stdinReplacements: Array<StdinReplacement> = [];
+  const traceReplacements: Array<TraceReplacement> = [];
   let stdinSeq = 0;
+  let traceSeq = 0;
 
   for (const scenario of report.scenarios) {
     const isEmpty =
@@ -230,10 +259,22 @@ export function renderReport(
         const lang = action.error.message.language ?? "text";
         lines.push("Error:");
         lines.push("");
-        lines.push(`\`\`\`${lang}`);
+        lines.push(`\`\`\`${lang} title="message"`);
         lines.push(trimFinalNewline(messageText));
         lines.push("```");
         lines.push("");
+
+        if (action.error?.stack) {
+          const placeholder = `__KEST_TRACE_${traceSeq++}__`;
+          traceReplacements.push({
+            placeholder,
+            rawStack: action.error.stack,
+          });
+          lines.push('```ts title="trace"');
+          lines.push(placeholder);
+          lines.push("```");
+          lines.push("");
+        }
       }
     };
 
@@ -289,7 +330,17 @@ export function renderReport(
   const rendered = renderedScenarios.join("\n\n");
   const markdown = rendered.endsWith("\n") ? rendered : `${rendered}\n`;
   if (!enableANSI) {
-    return Promise.resolve(markdown);
+    const resolved = await resolveTraceReplacements(
+      markdown,
+      traceReplacements,
+      options
+    );
+    return resolved;
   }
-  return highlightMarkdown(markdown, stdinReplacements);
+  return highlightMarkdown(
+    markdown,
+    stdinReplacements,
+    traceReplacements,
+    options
+  );
 }

package/ts/reporter/markdown/strip-ansi.ts

@@ -0,0 +1,8 @@
+export function stripAnsi(input: string): string {
+  // Prefer Bun's built-in ANSI stripper when available.
+  if (typeof Bun !== "undefined" && typeof Bun.stripANSI === "function") {
+    return Bun.stripANSI(input);
+  }
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: intended
+  return input.replace(/\u001b\[[0-9;]*m/g, "");
+}

package/ts/reporter/markdown/trace/find-user-frame.ts

@@ -0,0 +1,38 @@
+import type { StackFrame } from "./parse-stack";
+
+export function findUserFrame(
+  frames: Array<StackFrame>,
+  workspaceRoot: string
+): StackFrame | undefined {
+  const root = workspaceRoot.endsWith("/")
+    ? workspaceRoot
+    : `${workspaceRoot}/`;
+
+  for (const frame of frames) {
+    const { filePath } = frame;
+
+    if (filePath.includes("unknown")) {
+      continue;
+    }
+    if (filePath.startsWith("<")) {
+      continue;
+    }
+    if (filePath.includes("/node_modules/")) {
+      continue;
+    }
+    if (filePath.startsWith("native:")) {
+      continue;
+    }
+
+    if (filePath.startsWith(root)) {
+      const relative = filePath.slice(root.length);
+      if (relative.startsWith("ts/")) {
+        continue;
+      }
+    }
+
+    return frame;
+  }
+
+  return undefined;
+}

package/ts/reporter/markdown/trace/parse-stack.ts

@@ -0,0 +1,65 @@
+export interface StackFrame {
+  funcName?: string;
+  filePath: string;
+  line: number;
+  col: number;
+}
+
+// Pattern: at funcName (filePath:line:col)
+const withFuncAndParens =
+  /^\s*at\s+(?:async\s+)?(.+?)\s+\((.+):(\d+):(\d+)\)\s*$/;
+
+// Pattern: at (filePath:line:col)
+const withParensNoFunc = /^\s*at\s+(?:async\s+)?\((.+):(\d+):(\d+)\)\s*$/;
+
+// Pattern: at filePath:line:col
+const bareLocation = /^\s*at\s+(?:async\s+)?(.+):(\d+):(\d+)\s*$/;
+
+export function parseStack(rawStack: string): Array<StackFrame> {
+  if (!rawStack) {
+    return [];
+  }
+
+  const lines = rawStack.split("\n");
+  const frames: Array<StackFrame> = [];
+
+  for (const line of lines) {
+    if (!/^\s*at\s/.test(line)) {
+      continue;
+    }
+
+    let match: RegExpMatchArray | null;
+
+    match = line.match(withParensNoFunc);
+    if (match) {
+      frames.push({
+        filePath: match[1] as string,
+        line: Number(match[2]),
+        col: Number(match[3]),
+      });
+      continue;
+    }
+
+    match = line.match(withFuncAndParens);
+    if (match) {
+      frames.push({
+        funcName: match[1] as string,
+        filePath: match[2] as string,
+        line: Number(match[3]),
+        col: Number(match[4]),
+      });
+      continue;
+    }
+
+    match = line.match(bareLocation);
+    if (match) {
+      frames.push({
+        filePath: match[1] as string,
+        line: Number(match[2]),
+        col: Number(match[3]),
+      });
+    }
+  }
+
+  return frames;
+}

package/ts/reporter/markdown/trace/read-snippet.ts

@@ -0,0 +1,33 @@
+export interface Snippet {
+  lines: Array<{ lineNumber: number; code: string }>;
+  caretCol: number;
+}
+
+export async function readSnippet(
+  filePath: string,
+  line: number,
+  col: number,
+  contextLines = 5
+): Promise<Snippet | undefined> {
+  let content: string;
+  try {
+    content = await Bun.file(filePath).text();
+  } catch {
+    return undefined;
+  }
+
+  const allLines = content.split("\n");
+
+  if (line < 1 || line > allLines.length) {
+    return undefined;
+  }
+
+  const start = Math.max(1, line - contextLines);
+  const extracted: Array<{ lineNumber: number; code: string }> = [];
+
+  for (let i = start; i <= line; i++) {
+    extracted.push({ lineNumber: i, code: allLines[i - 1] as string });
+  }
+
+  return { lines: extracted, caretCol: col };
+}

package/ts/reporter/markdown/trace/render.ts

@@ -0,0 +1,223 @@
+import { codeToANSIForcedColors } from "../../shiki";
+import { findUserFrame } from "./find-user-frame";
+import type { StackFrame } from "./parse-stack";
+import { parseStack } from "./parse-stack";
+import type { Snippet } from "./read-snippet";
+import { readSnippet } from "./read-snippet";
+
+export interface RenderTraceOptions {
+  workspaceRoot?: undefined | string;
+  enableANSI?: undefined | boolean;
+}
+
+// Catppuccin Mocha palette
+const overlay0 = "#6c7086";
+const subtext0 = "#a6adc8";
+const textColor = "#cdd6f4";
+const peach = "#fab387";
+const flamingo = "#f2cdcd";
+const red = "#f38ba8";
+const maroon = "#eba0ac";
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [
+    Number.parseInt(h.slice(0, 2), 16),
+    Number.parseInt(h.slice(2, 4), 16),
+    Number.parseInt(h.slice(4, 6), 16),
+  ];
+}
+
+function fg(hex: string, s: string): string {
+  const [r, g, b] = hexToRgb(hex);
+  return `\x1b[38;2;${r};${g};${b}m${s}\x1b[0m`;
+}
+
+function fgBold(hex: string, s: string): string {
+  const [r, g, b] = hexToRgb(hex);
+  return `\x1b[1;38;2;${r};${g};${b}m${s}\x1b[0m`;
+}
+
+function formatSnippetPlain(
+  snippet: Snippet,
+  gutterWidth: number
+): Array<string> {
+  const parts: Array<string> = [];
+  for (const { lineNumber, code } of snippet.lines) {
+    const num = String(lineNumber).padStart(gutterWidth);
+    parts.push(`${num} | ${code}`);
+  }
+  const caretOffset = gutterWidth + " | ".length + snippet.caretCol - 1;
+  parts.push(`${" ".repeat(caretOffset)}^`);
+  return parts;
+}
+
+async function formatSnippetANSI(
+  snippet: Snippet,
+  gutterWidth: number
+): Promise<Array<string>> {
+  // Build the snippet text with line numbers for Shiki highlighting
+  const snippetText = snippet.lines
+    .map(({ lineNumber, code }) => {
+      const num = String(lineNumber).padStart(gutterWidth);
+      return `${num} | ${code}`;
+    })
+    .join("\n");
+
+  const highlighted = await codeToANSIForcedColors(
+    snippetText,
+    "typescript",
+    "catppuccin-mocha"
+  );
+
+  const lines = highlighted.replace(/\n$/, "").split("\n");
+
+  // Add bold Maroon caret line
+  const caretOffset = gutterWidth + " | ".length + snippet.caretCol - 1;
+  lines.push(fgBold(maroon, `${" ".repeat(caretOffset)}^`));
+
+  return lines;
+}
+
+function formatFramePlain(frame: StackFrame): string {
+  if (frame.funcName) {
+    return `at ${frame.funcName} (${frame.filePath}:${frame.line}:${frame.col})`;
+  }
+  return `at ${frame.filePath}:${frame.line}:${frame.col}`;
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+function formatFrameANSI(
+  frame: StackFrame,
+  workspaceRoot: string | undefined,
+  snippetFrame: StackFrame | undefined
+): string {
+  let root: string | undefined;
+  if (workspaceRoot) {
+    root = workspaceRoot.endsWith("/") ? workspaceRoot : `${workspaceRoot}/`;
+  }
+
+  // Determine if this frame matches the snippet source (both file AND line)
+  let isSnippetSource = false;
+  if (snippetFrame && root) {
+    const frameRel = frame.filePath.startsWith(root)
+      ? frame.filePath.slice(root.length)
+      : frame.filePath;
+    const snippetRel = snippetFrame.filePath.startsWith(root)
+      ? snippetFrame.filePath.slice(root.length)
+      : snippetFrame.filePath;
+    isSnippetSource =
+      frameRel === snippetRel && frame.line === snippetFrame.line;
+  }
+
+  const parts: Array<string> = [];
+
+  // "at"
+  parts.push(fg(overlay0, "at"));
+
+  // function name (if present)
+  if (frame.funcName) {
+    parts.push(" ");
+    parts.push(fg(textColor, frame.funcName));
+    parts.push(" ");
+    parts.push(fg(overlay0, "("));
+  } else {
+    parts.push(" ");
+  }
+
+  // Split workspace root vs relative path
+  let wsRoot = "";
+  let relPath = frame.filePath;
+  if (root && frame.filePath.startsWith(root)) {
+    wsRoot = root;
+    relPath = frame.filePath.slice(root.length);
+  }
+
+  // workspace root part
+  if (wsRoot) {
+    parts.push(fg(subtext0, wsRoot));
+  }
+
+  // file name part
+  if (isSnippetSource) {
+    parts.push(fgBold(red, relPath));
+  } else {
+    parts.push(fg(peach, relPath));
+  }
+
+  // colon
+  parts.push(fg(overlay0, ":"));
+
+  // line number
+  if (isSnippetSource) {
+    parts.push(fgBold(maroon, String(frame.line)));
+  } else {
+    parts.push(fg(flamingo, String(frame.line)));
+  }
+
+  // colon
+  parts.push(fg(overlay0, ":"));
+
+  // column number
+  parts.push(fg(overlay0, String(frame.col)));
+
+  if (frame.funcName) {
+    parts.push(fg(overlay0, ")"));
+  }
+
+  return parts.join("");
+}
+
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: rendering is intentionally linear and explicit
+export async function renderTrace(
+  rawStack: string,
+  options: RenderTraceOptions
+): Promise<string | undefined> {
+  const frames = parseStack(rawStack);
+  if (frames.length === 0) {
+    return undefined;
+  }
+
+  const enableANSI = options.enableANSI ?? false;
+  const parts: Array<string> = [];
+  let snippetFrame: StackFrame | undefined;
+
+  // Try to get snippet if workspaceRoot is provided
+  if (options.workspaceRoot) {
+    const userFrame = findUserFrame(frames, options.workspaceRoot);
+    if (userFrame) {
+      const snippet = await readSnippet(
+        userFrame.filePath,
+        userFrame.line,
+        userFrame.col
+      );
+      if (snippet) {
+        snippetFrame = userFrame;
+        const maxLineNum = Math.max(...snippet.lines.map((l) => l.lineNumber));
+        const gutterWidth = String(maxLineNum).length;
+
+        if (enableANSI) {
+          parts.push(...(await formatSnippetANSI(snippet, gutterWidth)));
+        } else {
+          parts.push(...formatSnippetPlain(snippet, gutterWidth));
+        }
+
+        // Blank line separator between snippet and frames
+        parts.push("");
+      }
+    }
+  }
+
+  // Format stack frames
+  if (enableANSI) {
+    for (const frame of frames) {
+      parts.push(formatFrameANSI(frame, options.workspaceRoot, snippetFrame));
+    }
+  } else {
+    for (const frame of frames) {
+      parts.push(formatFramePlain(frame));
+    }
+  }
+
+  return parts.join("\n");
+}

package/ts/retry.ts

@@ -77,6 +77,7 @@ export async function retryUntil<T>(
     }
 
     retries += 1;
+    recorder?.record("RetryAttempt", { attempt: retries });
 
     try {
       const value = await fn();

package/ts/test.ts

@@ -51,7 +51,7 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
       const recorder = new Recorder();
       const kubectl = createKubectl({ recorder, cwd: workspaceRoot });
       const reverting = createReverting({ recorder });
-      const reporter = newMarkdownReporter({ enableANSI: true });
+      const reporter = newMarkdownReporter({ enableANSI: true, workspaceRoot });
       const scenario = createScenario({
         name: label,
         recorder,
@@ -70,7 +70,7 @@ function makeScenarioTest(runner: BunTestRunner): TestFunction {
       recorder.record("ScenarioEnd", {});
       await report(recorder, scenario, testErr);
       if (testErr) {
-        throw testErr;
+        throw new Error(`Scenario failed: ${label}`);
       }
     };
     const report = async (