cursedbelt-core 1.0.0

package/src/testTmpRoot.spec.ts

@@ -0,0 +1,102 @@
+import { describe, expect, it } from 'bun:test';
+import { isAbsolute, resolve, sep } from 'node:path';
+import { resolveTestTmpRoot } from '../scripts/testTmpRoot';
+
+/**
+ * 🔴 THE CHECKER CANNOT SEE THIS ONE, WHICH IS WHY IT IS A TEST.
+ *
+ * `scripts/testTmpRoot.ts` is a bun test PRELOAD: it runs before the first spec in
+ * this repo, on every `bun test`, and it decides where every `mkdtemp` in the suite
+ * lands. Until 2026-09-13 it pointed `$TMPDIR` at the PREVIOUS generation's state
+ * root — 77 MB and 259 process directories had accumulated there — and
+ * `tools/check-paths.ts` reported nothing, because the path was interpolated from
+ * `$HOME` on one line and assembled from a variable on the next. Neither line
+ * carried a shape the trigger looks for.
+ *
+ * So the gate is here instead, and it asserts the RESOLVED root rather than the
+ * source text: a previous generation's directory cannot come back through a
+ * variable, a rename, or a constant without one of these failing.
+ *
+ * This spec lives in `src/` rather than beside the file it proves because
+ * `bun run test` is `bun test src` — a spec under `scripts/` would never run, and
+ * a gate that does not run is the exact failure mode above.
+ */
+
+/** Every directory name this generation must never write into. */
+const PREVIOUS_GENERATIONS = ['app-managed', 'code-retiring', 'code-active', 'Master-Docs'];
+
+const REPO_ROOT = resolve(import.meta.dir, '..');
+
+describe('the test scratch root', () => {
+  it('lives under $FORGE_STATE when the generation supplies one', () => {
+    const root = resolveTestTmpRoot({ FORGE_STATE: '/state/cursedforge' });
+    expect(root.startsWith(`/state/cursedforge${sep}`)).toBe(true);
+  });
+
+  it('falls back to this repo, never to anything derived from $HOME', () => {
+    const root = resolveTestTmpRoot({ HOME: '/home/somebody' });
+    expect(root.startsWith(`${REPO_ROOT}${sep}`)).toBe(true);
+    expect(root).not.toContain('/home/somebody');
+    // Gitignored here, so a fallback run leaves nothing for git to report.
+    expect(root).toContain('.agent.noindex');
+  });
+
+  it('treats a blank $FORGE_STATE as no $FORGE_STATE', () => {
+    expect(resolveTestTmpRoot({ FORGE_STATE: '   ', HOME: '/home/somebody' }).startsWith(`${REPO_ROOT}${sep}`)).toBe(
+      true,
+    );
+  });
+
+  /*
+   * 🔴 `.noindex` is not decoration and is not cosmetic: it is the only marker that
+   * keeps Spotlight out of files written LATER into a tree, and a test root is
+   * written to constantly (measured 43× on this machine). Both branches carry it.
+   */
+  it('keeps a .noindex segment on every branch', () => {
+    for (const env of [{ FORGE_STATE: '/state/cursedforge' }, { HOME: '/home/somebody' }]) {
+      expect(resolveTestTmpRoot(env).split(sep).some((segment) => segment.endsWith('.noindex'))).toBe(true);
+    }
+  });
+
+  it('resolves an absolute path, whatever the caller cwd is', () => {
+    for (const env of [{ FORGE_STATE: '/state/cursedforge' }, {}]) {
+      expect(isAbsolute(resolveTestTmpRoot(env))).toBe(true);
+    }
+  });
+
+  /*
+   * The assertion the whole file exists for. Note the envs that TRY to steer it
+   * back: the previous generation's own variable, and a home that already contains
+   * its folder. Neither may reach the answer.
+   */
+  it('never resolves a previous generation, whatever the environment says', () => {
+    const envs: Array<Record<string, string | undefined>> = [
+      {},
+      { HOME: '/home/somebody' },
+      { FORGE_STATE: '/state/cursedforge', HOME: '/home/somebody' },
+      { APP_MANAGED_HOME: '/nowhere/inherited', HOME: '/home/somebody' },
+      { HOME: `/home/somebody/${PREVIOUS_GENERATIONS[0]}` },
+    ];
+    for (const env of envs) {
+      const root = resolveTestTmpRoot(env);
+      for (const name of PREVIOUS_GENERATIONS) {
+        expect(root, `resolved "${root}" for env ${JSON.stringify(env)}`).not.toContain(name);
+      }
+    }
+  });
+
+  /*
+   * And the live one: whatever this very process ended up with. The preload has
+   * already run by the time any spec does, so `$TMPDIR` here is the real answer on
+   * the real machine — the measurement the source-text assertions above cannot make.
+   */
+  it('has already pointed THIS process somewhere legitimate', () => {
+    const live = process.env.TMPDIR ?? '';
+    if (process.env.TMPDIR_TEST_PASSTHROUGH) return; // a suite asked for the system root
+    for (const name of PREVIOUS_GENERATIONS) {
+      expect(live, `$TMPDIR is "${live}"`).not.toContain(name);
+    }
+    const expected = resolveTestTmpRoot();
+    expect(live.startsWith(`${expected}${sep}`)).toBe(true);
+  });
+});

package/src/testing/bytes.ts

@@ -0,0 +1,38 @@
+/**
+ * `Uint8Array` → a body the DOM types accept, in ONE place.
+ *
+ * ## The problem this exists to stop being solved five different ways
+ *
+ * TypeScript 5.7 made `Uint8Array` generic in its buffer: `Uint8Array<ArrayBufferLike>`.
+ * `BodyInit` accepts `ArrayBufferView<ArrayBuffer>` — an ArrayBuffer view, NOT a
+ * possibly-shared one — so `new Response(bytes)` and `fetch(url, { body: bytes })`
+ * stopped compiling for every plain `new Uint8Array([…])` in the repo. Nothing
+ * about the runtime changed; the types got more precise about `SharedArrayBuffer`.
+ *
+ * Two fixes suggest themselves and one of them is a bug:
+ *
+ *   * `bytes.buffer as ArrayBuffer` — **wrong in general.** `.buffer` is the
+ *     WHOLE underlying buffer, so for any view that does not span it (`subarray`,
+ *     a slice of a decoder's output, a chunk read off a stream) this silently
+ *     sends more bytes than the caller holds. It happens to be right for a
+ *     literal `new Uint8Array([1,2,3,4])` and that is exactly what makes it a
+ *     trap: it works everywhere it is first tried.
+ *   * `bytes as Uint8Array<ArrayBuffer>` — correct, and what this does. It
+ *     asserts the one thing the caller actually knows (this buffer is not
+ *     shared), changes no lengths, and keeps the view's own offset.
+ *
+ * Test-only by intent: production code that needs to send bytes should hold a
+ * correctly-typed buffer rather than assert one.
+ */
+
+/** A `Uint8Array` as a `BodyInit`, preserving byte offset and length. */
+export const asBody = (bytes: Uint8Array): Uint8Array<ArrayBuffer> => bytes as Uint8Array<ArrayBuffer>;
+
+/** `new Response(bytes)` with the assertion applied — the common case. */
+export const bytesResponse = (bytes: Uint8Array, init?: ResponseInit): Response =>
+  new Response(asBody(bytes), init);
+
+/** A readable stream of `bytes` — what the media catalogue's ingest paths take. */
+export const bytesStream = (bytes: Uint8Array | string): ReadableStream<Uint8Array> =>
+  new Response(typeof bytes === 'string' ? asBody(new TextEncoder().encode(bytes)) : asBody(bytes))
+    .body as ReadableStream<Uint8Array>;

package/src/testing/domInspect.spec.ts

@@ -0,0 +1,79 @@
+/**
+ * The standing gate on the cheap-DOM-inspect preload.
+ *
+ * This is a PERFORMANCE assertion, which is normally a bad idea — a wall-clock
+ * threshold on a shared CI runner is how you get a flaky suite. It earns its
+ * place because the failure it guards is three orders of magnitude wide, not a
+ * few percent: without the inspector a single failing `expect` on an attached
+ * 50-child element measured 1,576 ms, with it 0.1 ms. The threshold below sits
+ * at 150 ms — 10× the headroom a loaded runner could plausibly need, and still
+ * 10× under the broken behavior. Nothing between those two numbers is a state
+ * this code can actually be in.
+ *
+ * If this goes red, the preload stopped running or happy-dom moved the class:
+ * check `installCheapDomInspect()` is still called AFTER `GlobalRegistrator
+ * .register()` in both `happydom.ts` preloads.
+ */
+import { describe, expect, test } from 'bun:test';
+
+/** Comfortably above a slow runner, comfortably below the 1,576 ms failure. */
+const BUDGET_MS = 150;
+
+const attachedTree = (children: number): Element => {
+  const el = document.createElement('div');
+  el.className = 'subject';
+  el.innerHTML = '<span>x</span>'.repeat(children);
+  document.body.appendChild(el);
+  return el;
+};
+
+describe('the cheap DOM inspector is installed by the test preload', () => {
+  test('a failing expect on a deep ATTACHED element is fast', () => {
+    const el = attachedTree(50);
+    const started = performance.now();
+    // Deliberately fails: this is the exact shape `waitFor(() => expect(el)
+    // .toBeNull())` runs on every poll.
+    expect(() => expect(el).toBeNull()).toThrow();
+    const elapsed = performance.now() - started;
+    expect(elapsed).toBeLessThan(BUDGET_MS);
+  });
+
+  test('the message shows the MARKUP, not the node object graph', () => {
+    const el = attachedTree(1);
+    let message = '';
+    try {
+      expect(el).toBeNull();
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('<div class="subject">');
+    // The old serializer walked upward through parentNode into the document —
+    // that walk is both the cost and the reason the message was unreadable.
+    expect(message).not.toContain('Symbol(parentNode)');
+    expect(message).not.toContain('HTMLHtmlElement');
+  });
+
+  test('very large markup is elided rather than dumped whole', () => {
+    const el = attachedTree(400);
+    let message = '';
+    try {
+      expect(el).toBeNull();
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('more chars');
+    expect(message.length).toBeLessThan(2000);
+  });
+
+  test('a text node still describes itself', () => {
+    const text = document.createTextNode('hello');
+    let message = '';
+    try {
+      expect(text).toBeNull();
+    } catch (error) {
+      message = (error as Error).message;
+    }
+    expect(message).toContain('#text');
+    expect(message).toContain('hello');
+  });
+});

package/src/testing/domInspect.ts

@@ -0,0 +1,127 @@
+/**
+ * Make a happy-dom node CHEAP to serialize, for every `bun test` process in this
+ * repo. Imported by `packages/cursedbelt/happydom.ts` and
+ * `packages/cursedshell/happydom.ts` — the two test preloads — so it is the ONE
+ * place this behavior is defined.
+ *
+ * ## The bug this exists to not have
+ *
+ * `expect(received)` builds its failure message EAGERLY, before anything decides
+ * whether that message will ever be read. When `received` is a happy-dom node,
+ * Bun's inspector walks the node's own object graph — and a happy-dom node holds
+ * `[Symbol(parentNode)]`, so the walk goes UPWARD through the parent chain into
+ * `HTMLBodyElement` → `HTMLHtmlElement` → `HTMLDocument` → the window, and back
+ * down through every sibling subtree it meets on the way.
+ *
+ * Measured on this repo's own studio spec (2026-07-26):
+ *
+ * | received value                        | cost of ONE failing `expect` |
+ * |---------------------------------------|------------------------------|
+ * | `true`                                | 0.1 ms                       |
+ * | a plain object                        | 0.0 ms                       |
+ * | a detached empty `<div>`              | 9.8 ms                       |
+ * | an ATTACHED empty `<div>`             | 29.8 ms                      |
+ * | an attached `<div>` with 50 children  | **1,576 ms**                 |
+ *
+ * That cost is paid on assertions that FAIL, which sounds rare until you notice
+ * that `waitFor(() => expect(el).toBeNull())` fails on purpose on every poll
+ * until the condition comes true. The studio spec's `settled()` helper spent
+ * ~790 ms per mount building error strings that `waitFor` then threw away — 12
+ * mounts, ~9.5 s of a 10.5 s file, and on the CI runner the same two assertions
+ * blew through Bun's 5,000 ms per-test timeout and turned `main` red.
+ *
+ * ## The fix
+ *
+ * Install `nodejs.util.inspect.custom` on happy-dom's `Node.prototype` (the
+ * common ancestor of every element, text node, fragment and document), returning
+ * TRUNCATED `outerHTML`. Bun's inspector honors that hook and stops walking.
+ * Same measurement, after: **1,576 ms → 0.1 ms.**
+ *
+ * The message gets BETTER as well as faster. What it replaces is not an HTML
+ * dump; it is a `[Symbol(listeners)] / [Symbol(parentNode)]` object graph that
+ * scrolls for thousands of lines and never shows the markup. `outerHTML` is what
+ * someone reading a failure actually wants.
+ *
+ * ## What this deliberately does NOT do
+ *
+ * It does not touch `prettyDOM`, `screen.debug()` or any Testing Library output
+ * — those have their own serializer and are called only when someone asks for
+ * them, so they were never the cost. Only the implicit `expect`/`console.log`
+ * path changes.
+ */
+
+/** Longest markup we will put in a failure message before eliding the middle. */
+const MAX_MARKUP = 800;
+
+/** Node.nodeType constants, spelled out so this file needs no DOM lib types. */
+const ELEMENT_NODE = 1;
+const TEXT_NODE = 3;
+const COMMENT_NODE = 8;
+const DOCUMENT_NODE = 9;
+const DOCUMENT_FRAGMENT_NODE = 11;
+
+const INSPECT = Symbol.for('nodejs.util.inspect.custom');
+
+interface MinimalNode {
+  nodeType: number;
+  nodeName?: string;
+  outerHTML?: string;
+  innerHTML?: string;
+  data?: string;
+  childNodes?: { length: number };
+}
+
+/** Keep the head and the tail: the opening tag says what it is, the closing tag
+ *  says where it ended, and the middle of a 40 KB body is never the useful part. */
+function elide(markup: string): string {
+  if (markup.length <= MAX_MARKUP) return markup;
+  const head = markup.slice(0, MAX_MARKUP - 120);
+  const tail = markup.slice(-100);
+  return `${head}\n  … ${markup.length - MAX_MARKUP + 20} more chars …\n${tail}`;
+}
+
+function describe(node: MinimalNode): string {
+  switch (node.nodeType) {
+    case ELEMENT_NODE:
+      return elide(node.outerHTML ?? `<${(node.nodeName ?? 'element').toLowerCase()} />`);
+    case TEXT_NODE:
+      return `#text ${JSON.stringify(node.data ?? '')}`;
+    case COMMENT_NODE:
+      return `<!--${node.data ?? ''}-->`;
+    case DOCUMENT_NODE:
+      return '#document';
+    case DOCUMENT_FRAGMENT_NODE:
+      return elide(`#document-fragment ${node.innerHTML ?? `(${node.childNodes?.length ?? 0} children)`}`);
+    default:
+      return `${node.nodeName ?? 'Node'}(nodeType ${node.nodeType})`;
+  }
+}
+
+/**
+ * Install the cheap inspector. Idempotent, and a no-op when happy-dom has not
+ * registered its globals (a pure-logic preload has no `Node`).
+ *
+ * Call AFTER `GlobalRegistrator.register()` — before it, `globalThis.Node` is
+ * whatever Bun ships and patching it would miss the class the specs actually get.
+ */
+export function installCheapDomInspect(): void {
+  const NodeCtor = (globalThis as { Node?: { prototype?: object } }).Node;
+  const proto = NodeCtor?.prototype;
+  if (!proto) return;
+  if (Object.hasOwn(proto, INSPECT)) return; // already installed
+
+  Object.defineProperty(proto, INSPECT, {
+    value(this: MinimalNode) {
+      // An inspector that throws turns a readable assertion failure into an
+      // unreadable one, so every branch here is best-effort.
+      try {
+        return describe(this);
+      } catch {
+        return '[unserializable DOM node]';
+      }
+    },
+    configurable: true,
+    enumerable: false,
+    writable: true,
+  });
+}

package/src/testing/fakeFetch.ts

@@ -0,0 +1,26 @@
+/**
+ * A `fetch` stand-in that actually satisfies `typeof fetch`.
+ *
+ * `typeof fetch` is not just a call signature: the DOM lib declares `preconnect`
+ * on it, so a bare `async (input) => new Response(…)` is NOT assignable and
+ * `as typeof fetch` is refused outright ("neither type sufficiently overlaps").
+ * The reflexive workaround is `as unknown as typeof fetch`, and that is the
+ * pattern worth stopping: a double assertion silences THIS mismatch and every
+ * future one, including a genuine argument-shape error in the fake.
+ *
+ * This attaches the missing member instead. The result is a real value of the
+ * type, so the fake's own `(input, init)` signature stays checked — which is the
+ * whole reason to type a fake at all.
+ */
+
+/** The part of `fetch` a test actually implements. */
+export type FetchImpl = (input: RequestInfo | URL, init?: RequestInit) => Promise<Response>;
+
+/**
+ * Wrap a fake so it is a complete `typeof fetch`.
+ *
+ * `preconnect` is a no-op: it is a resource HINT with no observable result, so a
+ * test that triggered one and got nothing has lost nothing.
+ */
+export const fakeFetch = (impl: FetchImpl): typeof fetch =>
+  Object.assign(impl, { preconnect: () => undefined }) as typeof fetch;

package/src/testing/index.ts

@@ -0,0 +1,11 @@
+// cursedbelt-core/testing — test-only helpers shared across every `bun test` process
+// in the fleet. Its own subpath so nothing test-related is reachable from the
+// runtime entrypoints.
+//
+// Exposed on 2026-08-02 so consumers (e.g. cursed-satellites' happydom preload)
+// can `import { installCheapDomInspect } from "cursedbelt-core/testing"` instead of
+// keeping a ~60-line hand-port of domInspect.ts — the file already lived here,
+// it just had no export.
+export { installCheapDomInspect } from "./domInspect";
+export { asBody, bytesResponse, bytesStream } from "./bytes";
+export { type FetchImpl, fakeFetch } from "./fakeFetch";