fix(shell-dashboard): harden ops-api types and error reporting

- ProbeLastRun.summary is now nullable to match ProbeRun.summary; the
  server can complete a run with no summary (showcase-ops CR-A1.5).
- ensureOk surfaces body-read failures with a 'body read failed: ...'
  marker instead of swallowing them silently (CR-B1.6 / CR-C15).
- New parseJson helper attributes JSON parse failures to the requesting
  URL so call sites can tell which endpoint produced bad bytes.
- triggerProbe gains a TriggerProbeOptions interface with an optional
  AbortSignal; passed straight through to fetch() so callers can cancel
  in-flight POSTs (CR-B1.5).

Author: jpr5

showcase/shell-dashboard/src/lib/ops-api.test.ts

@@ -258,4 +258,43 @@ describe("triggerProbe", () => {
       }),
     ).rejects.toThrow(/500/);
   });
+
+  it("propagates AbortSignal to fetch (CR-B1.5)", async () => {
+    fetchSpy.mockResolvedValue(jsonResponse(triggerOk()));
+    const ctrl = new AbortController();
+    await triggerProbe("smoke", {
+      token: "t",
+      baseUrl: "http://ops.test",
+      signal: ctrl.signal,
+    });
+    const init = fetchSpy.mock.calls[0]![1] as FetchInit;
+    expect(init?.signal).toBe(ctrl.signal);
+  });
+});
+
+describe("ensureOk error handling (CR-B1.6)", () => {
+  it("includes a body-read failure marker when text() throws", async () => {
+    // Build a Response-like object whose `text()` throws and whose `ok` is
+    // false. Response.text() does not normally throw on Response objects
+    // with string bodies, so we hand-roll a stub.
+    const fakeResponse = {
+      ok: false,
+      status: 502,
+      statusText: "Bad Gateway",
+      text: vi.fn(async () => {
+        throw new Error("stream consumed");
+      }),
+    } as unknown as Response;
+    fetchSpy.mockResolvedValue(fakeResponse);
+    let caught: unknown = null;
+    try {
+      await fetchProbes({ baseUrl: "http://ops.test" });
+    } catch (err) {
+      caught = err;
+    }
+    expect(caught).toBeInstanceOf(Error);
+    expect((caught as Error).message).toMatch(/body read failed/);
+    // status should still appear so callers can match on it.
+    expect((caught as Error).message).toMatch(/502/);
+  });
 });

showcase/shell-dashboard/src/lib/ops-api.ts

@@ -50,7 +50,10 @@ export interface ProbeLastRun {
   finishedAt: string;
   durationMs: number;
   state: "completed" | "failed";
-  summary: ProbeRunSummary;
+  // Nullable: a "completed" run produced by a failure path can land here
+  // without a summary (see showcase-ops CR-A1.5). Consumers MUST null-guard
+  // before reading summary.passed / summary.total / summary.failed.
+  summary: ProbeRunSummary | null;
 }
 
 export interface ProbeServiceProgress {
@@ -139,14 +142,31 @@ async function ensureOk(response: Response, url: string): Promise<void> {
   try {
     const text = await response.text();
     if (text && text.length <= 200) detail = ` — ${text}`;
-  } catch {
-    // ignore body-read failures; the status line is enough.
+  } catch (bodyErr) {
+    // Surface the body-read failure rather than swallowing it silently —
+    // callers and tests need a marker to distinguish "server returned an
+    // empty/unreachable body" from "we just chose not to include it".
+    const msg = (bodyErr as Error)?.message ?? "unknown";
+    detail = ` (body read failed: ${msg})`;
   }
   throw new Error(
     `ops-api request failed: ${response.status} ${response.statusText} at ${url}${detail}`,
   );
 }
 
+/**
+ * Parse a JSON response, wrapping any parse failure with the URL so the
+ * caller can attribute the failure to a specific endpoint.
+ */
+async function parseJson<T>(response: Response, url: string): Promise<T> {
+  try {
+    return (await response.json()) as T;
+  } catch (parseErr) {
+    const msg = (parseErr as Error)?.message ?? "unknown";
+    throw new Error(`ops-api JSON parse failed at ${url}: ${msg}`);
+  }
+}
+
 // ─────────────────────────────────────────────────────────────────────────
 // Public API
 // ─────────────────────────────────────────────────────────────────────────
@@ -162,7 +182,7 @@ export async function fetchProbes(opts: {
     headers: { accept: "application/json" },
   });
   await ensureOk(response, url);
-  return (await response.json()) as ProbesResponse;
+  return parseJson<ProbesResponse>(response, url);
 }
 
 export async function fetchProbeDetail(
@@ -176,12 +196,19 @@ export async function fetchProbeDetail(
     headers: { accept: "application/json" },
   });
   await ensureOk(response, url);
-  return (await response.json()) as ProbeDetailResponse;
+  return parseJson<ProbeDetailResponse>(response, url);
+}
+
+export interface TriggerProbeOptions {
+  slugs?: string[];
+  token: string;
+  baseUrl?: string;
+  signal?: AbortSignal;
 }
 
 export async function triggerProbe(
   id: string,
-  opts: { slugs?: string[]; token: string; baseUrl?: string },
+  opts: TriggerProbeOptions,
 ): Promise<TriggerResponse> {
   const url = `${resolveBaseUrl(opts.baseUrl)}/probes/${encodeURIComponent(
     id,
@@ -199,7 +226,8 @@ export async function triggerProbe(
       authorization: `Bearer ${opts.token}`,
     },
     body: JSON.stringify(body),
+    signal: opts.signal,
   });
   await ensureOk(response, url);
-  return (await response.json()) as TriggerResponse;
+  return parseJson<TriggerResponse>(response, url);
 }