@specific.dev/spectest 0.79.0 → 0.79.1

package/dist/harness/main.js

@@ -35,7 +35,7 @@
 import net from "node:net";
 import { METHODS } from "../daemon";
 import { codeOf } from "./methods";
-import { PROTOCOL_VERSION, decodeFrame, encodeFrame, fail, ok, } from "./protocol";
+import { PROTOCOL_VERSION, decodeFrame, describeThrow, encodeFrame, fail, ok, } from "./protocol";
 /** Capabilities this build announces. Empty is fine — the slot is what
  *  matters, so a later release has something to negotiate against. */
 const CAPABILITIES = [];
@@ -87,11 +87,11 @@ export function serve(socket, registry) {
             //
             // A refusal the method meant to make (an unknown case, a second test
             // while one is running) reports its own kind and just its message. An
-            // unexpected throw is a bug in the method and carries the stack,
-            // which is the only place that information exists.
+            // unexpected throw carries its message AND its stack — in that order,
+            // because a stack alone is sometimes headerless (`describeThrow`).
             const e = err;
             const code = codeOf(err);
-            const detail = code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+            const detail = code === "handler_error" ? describeThrow(err) : e.message;
             send(fail(req.id, detail, code));
         }
     };

package/dist/harness/protocol.d.ts

@@ -86,3 +86,23 @@ export declare function ok(id: string, result?: Record<string, unknown>): Respon
 /** A failed reply to `id`. Always carries the id: a request that failed must
  *  never leave its caller waiting. */
 export declare function fail(id: string, message: string, code?: string): ResponseFrame;
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export declare function describeThrow(err: unknown): string;

package/dist/harness/protocol.js

@@ -94,3 +94,37 @@ export function ok(id, result = {}) {
 export function fail(id, message, code) {
     return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
 }
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export function describeThrow(err) {
+    const e = err;
+    const message = typeof e?.message === "string" ? e.message : "";
+    const stack = typeof e?.stack === "string" ? e.stack : "";
+    if (!message)
+        return stack || String(err);
+    if (stack.includes(message))
+        return stack;
+    const name = typeof e?.name === "string" && e.name.length > 0 ? e.name : "Error";
+    // The headerless form is `<Name>\n    at …`. Drop that bare first line
+    // and write the header ourselves, so the result reads like the stack a
+    // reader expects rather than a message with a stray `Error` in it.
+    const frames = stack.startsWith(`${name}\n`) ? stack.slice(name.length + 1) : stack;
+    return frames.length > 0 ? `${name}: ${message}\n${frames}` : `${name}: ${message}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@specific.dev/spectest",
-  "version": "0.79.0",
+  "version": "0.79.1",
   "description": "Spectest SDK for defining test environments in TypeScript.",
   "type": "module",
   "main": "./dist/index.js",

package/src/harness/main.ts

@@ -40,6 +40,7 @@ import { codeOf } from "./methods";
 import {
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -115,12 +116,11 @@ export function serve(
       //
       // A refusal the method meant to make (an unknown case, a second test
       // while one is running) reports its own kind and just its message. An
-      // unexpected throw is a bug in the method and carries the stack,
-      // which is the only place that information exists.
+      // unexpected throw carries its message AND its stack — in that order,
+      // because a stack alone is sometimes headerless (`describeThrow`).
       const e = err as Error;
       const code = codeOf(err);
-      const detail =
-        code === "handler_error" ? (e?.stack ?? e?.message ?? String(err)) : e.message;
+      const detail = code === "handler_error" ? describeThrow(err) : e.message;
       send(fail(req.id, detail, code));
     }
   };

package/src/harness/protocol.test.ts

@@ -18,6 +18,7 @@ import {
   KNOWN_METHODS,
   PROTOCOL_VERSION,
   decodeFrame,
+  describeThrow,
   encodeFrame,
   fail,
   ok,
@@ -146,3 +147,44 @@ describe("replies", () => {
     expect(fail("7", "boom", "c")!.error!.code).toBe("c");
   });
 });
+
+describe("describeThrow", () => {
+  test("an ordinary stack, which already opens with the message, is untouched", () => {
+    const err = new Error("docker build for web failed:\nCOPY: not found");
+    expect(describeThrow(err)).toBe(err.stack);
+  });
+
+  /**
+   * The shape this function exists for, produced rather than written by
+   * hand: a promise that rejects while nobody awaits it yet and is
+   * observed a turn later comes back with a headerless stack. That is a
+   * bootstrap image build (`daemon.ts` starts every build at once and a
+   * service awaits its own prep when the DAG reaches it), and the build
+   * log lives in the message it drops.
+   */
+  test("a headerless stack gets its message back", async () => {
+    const message = "docker build for client-app failed:\n#12 ERROR: killed";
+    const rejected = (async () => {
+      throw new Error(message);
+    })();
+    rejected.catch(() => undefined);
+    await new Promise((r) => setTimeout(r, 5));
+    let caught: unknown;
+    try {
+      await rejected;
+    } catch (e) {
+      caught = e;
+    }
+    const described = describeThrow(caught);
+    expect(described).toContain(message);
+    expect(described.startsWith(`Error: ${message}`)).toBe(true);
+    // The frames survive, and the bare `Error` line they hung under does not.
+    expect(described).toContain("    at ");
+    expect(described).not.toContain("\nError\n");
+  });
+
+  test("a non-Error keeps whatever it can say for itself", () => {
+    expect(describeThrow("plain string")).toBe("plain string");
+    expect(describeThrow({ message: "no stack here" })).toBe("Error: no stack here");
+  });
+});

package/src/harness/protocol.ts

@@ -161,3 +161,36 @@ export function ok(id: string, result: Record<string, unknown> = {}): ResponseFr
 export function fail(id: string, message: string, code?: string): ResponseFrame {
   return { kind: "response", id, ok: false, error: code ? { message, code } : { message } };
 }
+
+/**
+ * Describe a thrown value for the wire: the **message first**, then the
+ * frames — never the stack on its own.
+ *
+ * `error.stack` normally opens with `Error: <message>`, which is why it
+ * looked like the richer of the two. It is not always: Bun drops that
+ * header when the rejection is observed a turn later than it settled —
+ * a promise that rejected while nobody was awaiting it yet, which is
+ * exactly what a bootstrap image build is (`daemon.ts` starts every
+ * build at once and each service awaits its own prep when the DAG
+ * reaches it). The whole diagnosis of a failed build IS the message
+ * there: `docker build for <svc> failed:` plus the build log. Sending
+ * the stack alone published four frames and nothing else — no docker,
+ * no BuildKit, no compiler error (reported by the Harmony project,
+ * 2026-09-09; the same run's log had the message intact).
+ *
+ * A stack that already carries the message is returned as it stands, so
+ * the ordinary case is unchanged.
+ */
+export function describeThrow(err: unknown): string {
+  const e = err as { message?: unknown; stack?: unknown; name?: unknown } | null | undefined;
+  const message = typeof e?.message === "string" ? e.message : "";
+  const stack = typeof e?.stack === "string" ? e.stack : "";
+  if (!message) return stack || String(err);
+  if (stack.includes(message)) return stack;
+  const name = typeof e?.name === "string" && e.name.length > 0 ? e.name : "Error";
+  // The headerless form is `<Name>\n    at …`. Drop that bare first line
+  // and write the header ourselves, so the result reads like the stack a
+  // reader expects rather than a message with a stray `Error` in it.
+  const frames = stack.startsWith(`${name}\n`) ? stack.slice(name.length + 1) : stack;
+  return frames.length > 0 ? `${name}: ${message}\n${frames}` : `${name}: ${message}`;
+}