@specific.dev/spectest 0.88.2 → 0.89.0

package/dist/inspect.d.ts

@@ -163,7 +163,7 @@ export type Provenanced = {
  * recovered at runtime by {@link adoptNullishTag}; `Provenanced` admits it because
  * it includes `null | undefined`.
  */
-export type Wrapped<T> = T extends null | undefined ? T : T extends readonly (infer U)[] ? WrappedArray<U> : T extends (...args: never[]) => unknown ? T : T extends object ? WrappedObject<T> : Carrier<T>;
+export type Wrapped<T> = T extends null | undefined ? T : T extends readonly (infer U)[] ? WrappedArray<U> : T extends ArrayBuffer | SharedArrayBuffer ? WrappedBuffer<T> : T extends ArrayBufferView ? WrappedBinaryView<T> : T extends File ? WrappedFile : T extends Blob ? WrappedBlob : T extends FormData ? WrappedFormData : T extends ReadableStream<infer C> ? WrappedStream<C> : T extends (...args: never[]) => unknown ? T : T extends object ? WrappedObject<T> : Carrier<T>;
 /** A wrapped object: every own property is itself {@link Wrapped}, plus an
  *  `.unwrap()` that recovers the fully-raw value (all nested leaves raw). */
 export type WrappedObject<T> = {
@@ -214,6 +214,69 @@ export interface WrappedArray<U> {
     /** Iteration yields *raw* elements (the runtime forwards the raw iterator). */
     [Symbol.iterator](): IterableIterator<U>;
 }
+/** Native objects need their own views: getters and methods must receive the
+ * real native receiver, and method results must be wrapped after they resolve.
+ * Iteration, callbacks, and control-flow flags on stream readers remain raw.
+ */
+type NativeResult<T> = T extends Promise<infer R> ? Promise<Wrapped<R>> : Wrapped<T>;
+type NativeView<T, K extends keyof T> = Omit<T, K> & {
+    readonly [P in K]: T[P] extends (...args: infer A) => infer R ? (...args: A) => NativeResult<R> : Wrapped<T[P]>;
+} & {
+    unwrap(): T;
+    transform<R>(label: string, fn: (raw: T) => R): Wrapped<R>;
+};
+export type WrappedBuffer<T extends ArrayBuffer | SharedArrayBuffer = ArrayBuffer> = NativeView<T, Extract<keyof T, "byteLength" | "maxByteLength" | "resizable" | "growable" | "detached" | "slice" | "transfer" | "transferToFixedLength">>;
+declare const BINARY_METHOD_NAMES: readonly ["at", "slice", "subarray", "includes", "indexOf", "lastIndexOf", "find", "findLast", "findIndex", "findLastIndex", "some", "every", "filter", "map", "join", "fill", "copyWithin", "reverse", "sort", "toReversed", "toSorted", "with", "toHex", "toBase64", "getInt8", "getUint8", "getInt16", "getUint16", "getInt32", "getUint32", "getFloat16", "getFloat32", "getFloat64", "getBigInt64", "getBigUint64"];
+/** Numeric indexes carry provenance. Like WrappedArray, length and iteration
+ * stay raw; callbacks receive native values. Unwrap for native API inputs. */
+export type WrappedBinaryView<T extends ArrayBufferView> = NativeView<T, Extract<keyof T, number | "buffer" | "byteLength" | "byteOffset" | typeof BINARY_METHOD_NAMES[number]>>;
+export type WrappedBytes = WrappedBinaryView<Uint8Array>;
+export type WrappedBlob = NativeView<Blob, "size" | "type" | "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFile = NativeView<File, "name" | "lastModified" | "webkitRelativePath" | "size" | "type" | "slice" | "text" | "bytes" | "arrayBuffer" | "stream">;
+export type WrappedFormData = NativeView<FormData, "get" | "getAll" | "has">;
+export type WrappedReadResult<T> = {
+    done: false;
+    value: Wrapped<T>;
+} | {
+    done: true;
+    value: Wrapped<T> | undefined;
+};
+export interface WrappedReader<T> extends Omit<ReadableStreamDefaultReader<T>, "read"> {
+    read(): Promise<WrappedReadResult<T>>;
+    unwrap(): ReadableStreamDefaultReader<T>;
+}
+export interface WrappedBYOBReader extends Omit<ReadableStreamBYOBReader, "read"> {
+    read<T extends ArrayBufferView>(view: T, options?: {
+        min?: number;
+    }): Promise<WrappedReadResult<T>>;
+    unwrap(): ReadableStreamBYOBReader;
+}
+export interface WrappedStream<T> extends Omit<ReadableStream<T>, "getReader" | "tee" | "pipeThrough"> {
+    getReader(): WrappedReader<T>;
+    getReader(options: {
+        mode: "byob";
+    }): WrappedBYOBReader;
+    getReader(options: ReadableStreamGetReaderOptions): WrappedReader<T> | WrappedBYOBReader;
+    tee(): [WrappedStream<T>, WrappedStream<T>];
+    pipeThrough<R>(transform: ReadableWritablePair<R, any>, options?: StreamPipeOptions): WrappedStream<R>;
+    unwrap(): ReadableStream<T>;
+    transform<R>(label: string, fn: (raw: ReadableStream<T>) => R): Wrapped<R>;
+}
+/** Response headers whose lookups retain the originating HTTP call's provenance.
+ * Missing headers remain `null`; `expect(headers.get(name)).toBe(null)` still
+ * links to the call. Iterators and other native methods return raw values.
+ */
+export interface WrappedHeaders extends Omit<Headers, "get" | "has" | "getSetCookie" | "getAll" | "toJSON" | "count"> {
+    get(name: string): Carrier<string> | null;
+    /** Unwrap before using the result as a condition. */
+    has(name: string): Carrier<boolean>;
+    getSetCookie(): WrappedArray<string>;
+    getAll(name: "set-cookie" | "Set-Cookie"): WrappedArray<string>;
+    toJSON(): Wrapped<Record<string, string | string[]>>;
+    readonly count: Carrier<number>;
+    unwrap(): Headers;
+    transform<R = unknown>(label: string, fn: (raw: Headers) => R): Wrapped<R>;
+}
 /**
  * The view `ctx.fetch` resolves to in every context (a spectest op wraps
  * unconditionally): a {@link Response} whose status-line accessors are
@@ -222,8 +285,9 @@ export interface WrappedArray<U> {
  * used to silently always be false. Compare `res.status.unwrap() === 200`
  * or `res.unwrap().status === 200`, or assert with `expect(res.status)`.
  *
- * `json<T>()` / `text()` return {@link Wrapped} body values; `.unwrap()`
- * (or {@link unwrap the whole response}) recovers the plain `Response`.
+ * All body readers return provenance-carrying values, including binary bodies,
+ * blobs and form data. `.unwrap()` recovers the native response or body value.
+ * Stream reader `done` and stream `locked` remain raw control-flow booleans.
  */
 export interface WrappedResponse {
     readonly status: Carrier<number>;
@@ -232,13 +296,15 @@ export interface WrappedResponse {
     readonly url: Carrier<string>;
     readonly redirected: Carrier<boolean>;
     readonly type: Carrier<string>;
-    readonly headers: Headers;
-    readonly bodyUsed: boolean;
+    readonly headers: WrappedHeaders;
+    readonly bodyUsed: Carrier<boolean>;
+    readonly body: WrappedStream<Uint8Array> | null;
     json<T = unknown>(): Promise<Wrapped<T>>;
     text(): Promise<Carrier<string>>;
-    arrayBuffer(): Promise<ArrayBuffer>;
-    blob(): Promise<Blob>;
-    formData(): Promise<FormData>;
+    arrayBuffer(): Promise<WrappedBuffer>;
+    bytes(): Promise<WrappedBytes>;
+    blob(): Promise<WrappedBlob>;
+    formData(): Promise<WrappedFormData>;
     clone(): WrappedResponse;
     /** Recover the underlying raw {@link Response} (a real `number` status,
      *  an unwrapped body, etc.). */
@@ -246,12 +312,19 @@ export interface WrappedResponse {
 }
 /** The signature of `ctx.fetch`: a `fetch` that resolves to a
  *  {@link WrappedResponse} so reads carry provenance into assertions. */
-export type SpectestFetch = (input: RequestInfo | URL, init?: RequestInit) => Promise<WrappedResponse>;
+export type SpectestFetch = (input: RequestInfo | URL, init?: SpectestRequestInit) => Promise<WrappedResponse>;
+export interface SpectestRequestInit extends RequestInit {
+    /** Skip the recorder's body capture for open-ended streams. SSE skips it
+     * automatically. The response and assertions remain recorded. */
+    captureBody?: boolean;
+}
 /**
  * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
  * `statusText` / `url` / `redirected` / `type` return carriers tagged
- * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
- * resolved value wrapped under `path: ["body"]`. Everything else passes
- * through bound to the real Response.
+ * to `sourceSeq`. Every body-reading method returns its resolved value
+ * wrapped under `path: ["body"]`. Header lookups carry paths
+ * under `headers`, and clones retain the same provenance. Everything else
+ * passes through bound to the real Response.
  */
 export declare function wrapResponse(res: Response, sourceSeq: number | undefined): WrappedResponse;
+export {};

package/dist/inspect.js

@@ -210,6 +210,20 @@ export function wrap(raw, sourceSeq, path = []) {
         return raw;
     const t = typeof raw;
     if (t === "object") {
+        const native = readRaw(raw);
+        if (native instanceof ArrayBuffer || (typeof SharedArrayBuffer !== "undefined" && native instanceof SharedArrayBuffer)) {
+            return wrapNative(native, sourceSeq, path, new Set(["byteLength", "maxByteLength", "resizable", "growable", "detached"]), new Set(["slice", "transfer", "transferToFixedLength"]));
+        }
+        if (ArrayBuffer.isView(native)) {
+            return wrapNative(native, sourceSeq, path, new Set(["buffer", "byteLength", "byteOffset"]), BINARY_METHODS, true);
+        }
+        if (native instanceof Blob) {
+            return wrapNative(native, sourceSeq, path, new Set(["size", "type", "name", "lastModified", "webkitRelativePath"]), new Set(["slice", "text", "bytes", "arrayBuffer", "stream"]));
+        }
+        if (native instanceof FormData)
+            return wrapFormData(native, sourceSeq, path);
+        if (native instanceof ReadableStream)
+            return wrapStream(native, sourceSeq, path);
         return wrapObject(raw, sourceSeq, path);
     }
     if (t === "function")
@@ -437,15 +451,140 @@ export function field(value, ...path) {
         return cur;
     return retag(cur, tag.sourceSeq, [...tag.path, ...path.map(String)]);
 }
+const BINARY_METHOD_NAMES = [
+    "at", "slice", "subarray", "includes", "indexOf", "lastIndexOf", "find", "findLast",
+    "findIndex", "findLastIndex", "some", "every", "filter", "map", "join",
+    "fill", "copyWithin", "reverse", "sort", "toReversed", "toSorted", "with", "toHex", "toBase64",
+    "getInt8", "getUint8", "getInt16", "getUint16", "getInt32", "getUint32",
+    "getFloat16", "getFloat32", "getFloat64", "getBigInt64", "getBigUint64",
+];
+const BINARY_METHODS = new Set(BINARY_METHOD_NAMES);
+function wrapNative(raw, sourceSeq, path, properties, methods, indexes = false) {
+    const tag = { sourceSeq, path };
+    return new Proxy(raw, {
+        get(target, prop) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            if (prop === "unwrap")
+                return () => target;
+            if (prop === "transform")
+                return makeTransform(target, sourceSeq, path);
+            const value = Reflect.get(target, prop, target);
+            if (typeof prop === "string") {
+                if (properties.has(prop) || (indexes && /^(0|[1-9]\d*)$/.test(prop))) {
+                    return wrapChild(value, sourceSeq, [...path, prop]);
+                }
+                if (methods.has(prop) && typeof value === "function") {
+                    return (...args) => {
+                        const result = value.apply(target, args);
+                        const resultPath = [...path, `<${prop}>`];
+                        return result instanceof Promise
+                            ? result.then((v) => wrapChild(v, sourceSeq, resultPath))
+                            : wrapChild(result, sourceSeq, resultPath);
+                    };
+                }
+            }
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        has(target, prop) {
+            return prop === OP_TAG || prop === UNWRAP || Reflect.has(target, prop);
+        },
+    });
+}
+function wrapFormData(raw, sourceSeq, path) {
+    const base = wrapNative(raw, sourceSeq, path, new Set(), new Set());
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop === "get" || prop === "getAll" || prop === "has") {
+                return (name) => wrapChild(raw[prop](name), sourceSeq, prop === "get" ? [...path, name] : [...path, name, `<${prop}>`]);
+            }
+            return Reflect.get(target, prop);
+        },
+    });
+}
+function wrapStream(raw, sourceSeq, path) {
+    const base = wrapNative(raw, sourceSeq, path, new Set(), new Set(["pipeThrough"]));
+    return new Proxy(base, {
+        get(target, prop) {
+            if (prop === "tee")
+                return () => raw.tee().map((s, i) => wrapStream(s, sourceSeq, [...path, `<tee>`, String(i)]));
+            if (prop === "getReader")
+                return (options) => {
+                    const reader = raw.getReader(options);
+                    let index = 0;
+                    return new Proxy(reader, {
+                        get(r, key) {
+                            if (key === "unwrap" || key === UNWRAP)
+                                return key === "unwrap" ? () => r : r;
+                            if (key === OP_TAG)
+                                return { sourceSeq, path };
+                            if (key === "read")
+                                return async (...args) => {
+                                    const read = r.read;
+                                    const result = await read.apply(r, args);
+                                    const valuePath = [...path, "<read>", String(index++)];
+                                    // done stays a real boolean so normal reader loops terminate.
+                                    return { done: result.done, get value() { return wrapChild(result.value, sourceSeq, valuePath); } };
+                                };
+                            const value = Reflect.get(r, key, r);
+                            return typeof value === "function" ? value.bind(r) : value;
+                        },
+                        has(r, key) { return key === UNWRAP || key === OP_TAG || Reflect.has(r, key); },
+                    });
+                };
+            return Reflect.get(target, prop);
+        },
+    });
+}
+function wrapHeaders(headers, sourceSeq) {
+    const path = ["headers"];
+    const tag = { sourceSeq, path };
+    return new Proxy(headers, {
+        get(target, prop) {
+            if (prop === OP_TAG)
+                return tag;
+            if (prop === UNWRAP)
+                return target;
+            if (prop === "unwrap")
+                return () => target;
+            if (prop === "transform")
+                return makeTransform(target, sourceSeq, path);
+            if (prop === "get" || prop === "has") {
+                return (name) => wrapChild(target[prop](name), sourceSeq, prop === "get" ? [...path, name.toLowerCase()] : [...path, name.toLowerCase(), "<has>"]);
+            }
+            if (prop === "count")
+                return wrap(target.count, sourceSeq, [...path, "count"]);
+            if (prop === "getAll")
+                return (name) => wrap(target.getAll(name), sourceSeq, [...path, name.toLowerCase()]);
+            if (prop === "toJSON")
+                return () => wrap(target.toJSON(), sourceSeq, path);
+            if (prop === "getSetCookie") {
+                return () => wrap(target.getSetCookie(), sourceSeq, [...path, "set-cookie"]);
+            }
+            const value = Reflect.get(target, prop, target);
+            return typeof value === "function" ? value.bind(target) : value;
+        },
+        has(target, prop) {
+            if (prop === OP_TAG || prop === UNWRAP)
+                return true;
+            return Reflect.has(target, prop);
+        },
+    });
+}
 /**
  * Bespoke wrapper for `fetch` responses. Reads on `status` / `ok` /
  * `statusText` / `url` / `redirected` / `type` return carriers tagged
- * to `sourceSeq`. The body-reading methods (`json`, `text`) return the
- * resolved value wrapped under `path: ["body"]`. Everything else passes
- * through bound to the real Response.
+ * to `sourceSeq`. Every body-reading method returns its resolved value
+ * wrapped under `path: ["body"]`. Header lookups carry paths
+ * under `headers`, and clones retain the same provenance. Everything else
+ * passes through bound to the real Response.
  */
 export function wrapResponse(res, sourceSeq) {
     const tag = { sourceSeq, path: [] };
+    let headers;
+    let body;
     const carrierProps = new Set([
         "status",
         "ok",
@@ -453,8 +592,9 @@ export function wrapResponse(res, sourceSeq) {
         "url",
         "redirected",
         "type",
+        "bodyUsed",
     ]);
-    const bodyMethods = new Set(["json", "text"]);
+    const bodyMethods = new Set(["json", "text", "bytes", "arrayBuffer", "blob", "formData"]);
     const handler = {
         get(target, prop) {
             if (prop === OP_TAG)
@@ -466,6 +606,15 @@ export function wrapResponse(res, sourceSeq) {
                 return () => readRaw(target);
             if (prop === "then")
                 return undefined;
+            if (prop === "headers")
+                return headers ??= wrapHeaders(target.headers, sourceSeq);
+            if (prop === "body") {
+                if (target.body === null)
+                    return wrapChild(null, sourceSeq, ["body"]);
+                return body ??= wrapStream(target.body, sourceSeq, ["body"]);
+            }
+            if (prop === "clone")
+                return () => wrapResponse(target.clone(), sourceSeq);
             if (typeof prop === "string" && carrierProps.has(prop)) {
                 const value = target[prop];
                 return wrap(value, sourceSeq, [prop]);
@@ -476,7 +625,7 @@ export function wrapResponse(res, sourceSeq) {
                     return fn;
                 return async (...args) => {
                     const value = await fn.apply(target, args);
-                    return wrap(value, sourceSeq, ["body"]);
+                    return wrapChild(value, sourceSeq, ["body"]);
                 };
             }
             const value = target[prop];

package/package.json

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

package/src/components/electron-chrome.ts

@@ -1,7 +1,55 @@
+// Trust for the environment CA, applied per session. Chromium on Linux
+// reads its own root store (NSS), never the container's mounted bundle, so
+// the renderer rejects every certificate the environment mints while Node
+// in the main process accepts them through NODE_EXTRA_CA_CERTS. This verify
+// procedure accepts exactly the chains that CA issued for the requested
+// host, and defers to Chromium's own verdict for everything else. An app
+// that installs its own procedure later replaces it, as in production.
+// Kept free of Electron so the unit test can run it under Bun.
+export const ELECTRON_CA_TRUST = String.raw`
+const { X509Certificate } = require('node:crypto');
+function loadEnvironmentCa(path) {
+  try { return path ? new X509Certificate(require('node:fs').readFileSync(path)) : null; }
+  catch { return null; }
+}
+// request: { hostname, errorCode, certificate: { data, issuerCert? } }.
+// Returns true only for a chain that ends at the CA and names the host.
+function issuedByEnvironmentCa(ca, request) {
+  try {
+    const leaf = new X509Certificate(request.certificate.data);
+    const host = request.hostname;
+    const named = leaf.checkHost(host) !== undefined || leaf.checkIP(host) !== undefined;
+    if (!named) return false;
+    const chain = [leaf];
+    for (let c = request.certificate; c.issuerCert && c.issuerCert !== c && chain.length < 8; c = c.issuerCert) {
+      chain.push(new X509Certificate(c.issuerCert.data));
+    }
+    for (let i = 0; i < chain.length; i++) {
+      const cert = chain[i];
+      if (cert.fingerprint256 === ca.fingerprint256) return i > 0;
+      const issuer = chain[i + 1] ?? ca;
+      if (!cert.checkIssued(issuer) || !cert.verify(issuer.publicKey)) return false;
+    }
+    return true;
+  } catch { return false; }
+}
+`;
+
 // Runs before the application's main entry, like Playwright's Electron loader.
 // Observe constructor options; do not replace the app entry, preload, IPC, or OS.
 export const ELECTRON_CHROME_HOOK = String.raw`
 const electron = require('electron');
+${ELECTRON_CA_TRUST}
+const environmentCa = loadEnvironmentCa(process.env.NODE_EXTRA_CA_CERTS);
+if (environmentCa) {
+  // Every session, including the default one and app-created partitions.
+  electron.app.on('session-created', session => {
+    session.setCertificateVerifyProc((request, callback) => {
+      if (request.errorCode === 0) return callback(0);
+      callback(issuedByEnvironmentCa(environmentCa, request) ? 0 : -3);
+    });
+  });
+}
 const NativeBrowserWindow = electron.BrowserWindow;
 const WrappedBrowserWindow = new Proxy(NativeBrowserWindow, {
   construct(Target, args, NewTarget) {

package/src/components/electron.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, test } from 'bun:test';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { electron } from './electron.js';
@@ -36,3 +36,86 @@ describe('Electron component contract', () => {
     expect(isDesktopApp(null)).toBe(false);
   });
 });
+
+describe('Electron component in a monorepo', () => {
+  function monorepo(run: (root: string) => void) {
+    const root = mkdtempSync(join(tmpdir(), 'spectest-electron-mono-'));
+    try {
+      mkdirSync(join(root, 'apps', 'desktop'), { recursive: true });
+      writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'], devDependencies: { electron: '44.0.0' } }));
+      writeFileSync(join(root, 'package-lock.json'), '{}');
+      writeFileSync(join(root, 'apps', 'desktop', 'package.json'), JSON.stringify({ name: '@acme/desktop' }));
+      run(root);
+    } finally { rmSync(root, { recursive: true, force: true }); }
+  }
+  test('builds from the context root and runs the app from its workspace', () => monorepo(root => {
+    const service = electron({ appDir: join(root, 'apps/desktop'), context: root });
+    expect(service.image).toMatchObject({ context: root });
+    const content = (service.image as { content: string }).content;
+    expect(content).toContain('COPY . .\nRUN npm ci\n');
+    expect(content).toContain("RUN cd apps/desktop && node \"$(node -p \"require.resolve('electron/install.js')\")\"\n");
+    expect(content).toContain('RUN cd apps/desktop && npm run build\n');
+    expect(service.env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app/apps/desktop');
+  }));
+  test('accepts electron declared at the context root only', () => monorepo(root => {
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).not.toThrow();
+    writeFileSync(join(root, 'package.json'), JSON.stringify({ workspaces: ['apps/*'] }));
+    expect(() => electron({ appDir: join(root, 'apps/desktop'), context: root })).toThrow('declare electron');
+  }));
+  test('rejects an app directory outside the context', () => monorepo(root => {
+    expect(() => electron({ appDir: root, context: join(root, 'apps/desktop') })).toThrow('must be inside context');
+  }));
+  test('the default context keeps the single-app image shape', () => fixture(appDir => {
+    const content = (electron({ appDir }).image as { content: string }).content;
+    expect(content).toContain('RUN node "$(node -p "require.resolve(\'electron/install.js\')")"\nRUN npm run build\n');
+    expect(electron({ appDir }).env?.SPECTEST_ELECTRON_APP_DIR).toBe('/app');
+  }));
+});
+
+describe('Electron environment-CA trust', () => {
+  const { ELECTRON_CA_TRUST } = require('./electron-chrome.js');
+  const { execFileSync } = require('node:child_process');
+  const { readFileSync: read } = require('node:fs');
+  function pki(run: (dir: string) => void) {
+    const dir = mkdtempSync(join(tmpdir(), 'spectest-electron-ca-'));
+    const sh = (cmd: string) => execFileSync('sh', ['-c', cmd], { cwd: dir, stdio: 'pipe' });
+    try {
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout ca.key -out ca.pem -days 2 -subj /CN=env-ca 2>/dev/null');
+      sh('openssl req -x509 -newkey rsa:2048 -nodes -keyout other.key -out other.pem -days 2 -subj /CN=other-ca 2>/dev/null');
+      sh('printf "subjectAltName=DNS:api.example.test\\nbasicConstraints=CA:FALSE\\n" > ext.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout leaf.key -out leaf.csr -subj /CN=api.example.test 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out leaf.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA other.pem -CAkey other.key -CAcreateserial -out stranger.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      sh('printf "basicConstraints=CA:TRUE\\nkeyUsage=keyCertSign\\n" > ica.cnf');
+      sh('openssl req -newkey rsa:2048 -nodes -keyout ica.key -out ica.csr -subj /CN=env-intermediate 2>/dev/null');
+      sh('openssl x509 -req -in ica.csr -CA ca.pem -CAkey ca.key -CAcreateserial -out ica.pem -days 2 -extfile ica.cnf 2>/dev/null');
+      sh('openssl x509 -req -in leaf.csr -CA ica.pem -CAkey ica.key -CAcreateserial -out leaf2.pem -days 2 -extfile ext.cnf 2>/dev/null');
+      run(dir);
+    } finally { rmSync(dir, { recursive: true, force: true }); }
+  }
+  // The hook's source, evaluated the way Electron evaluates it: plain CommonJS.
+  const trust = new Function('require', `${ELECTRON_CA_TRUST}; return { loadEnvironmentCa, issuedByEnvironmentCa };`)(require);
+  const request = (leafPath: string, hostname: string, issuers: string[] = []) => {
+    let cert: any = undefined;
+    for (const p of [...issuers].reverse()) cert = { data: read(p, 'utf8'), issuerCert: cert };
+    return { hostname, errorCode: -202, certificate: { data: read(leafPath, 'utf8'), issuerCert: cert } };
+  };
+  test('accepts a leaf the environment CA issued for the requested host', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(ca).not.toBeNull();
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'api.example.test'))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem')]))).toBe(true);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test', [join(dir, 'ica.pem'), join(dir, 'ca.pem')]))).toBe(true);
+  }));
+  test('rejects other issuers, other hosts, a bare intermediate, and the CA itself', () => pki(dir => {
+    const ca = trust.loadEnvironmentCa(join(dir, 'ca.pem'));
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'stranger.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf.pem'), 'evil.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'leaf2.pem'), 'api.example.test'))).toBe(false);
+    expect(trust.issuedByEnvironmentCa(ca, request(join(dir, 'ca.pem'), 'api.example.test'))).toBe(false);
+  }));
+  test('no CA file means no trust hook', () => {
+    expect(trust.loadEnvironmentCa(undefined)).toBeNull();
+    expect(trust.loadEnvironmentCa('/nonexistent/ca.pem')).toBeNull();
+  });
+});

package/src/components/electron.ts

@@ -1,12 +1,22 @@
 import { existsSync, readFileSync } from "node:fs";
+import { posix } from "node:path";
 import type { ServiceDefinition } from "../index.js";
 import { resolveProjectPath } from "../project-files.js";
 import { desktopApp, type DesktopApp } from "../desktop.js";
 import { ELECTRON_CHROME_HOOK } from "./electron-chrome.js";
 
 export interface ElectronOptions {
-  /** Project-relative app directory; must contain package.json and Electron. */
+  /** Project-relative app directory; must contain package.json. Electron must
+   * be declared here or in the context's package.json. */
   appDir?: string;
+  /**
+   * Image build context, relative to the project root. Default `appDir`.
+   * Set it to the repository root when the app is one workspace of a
+   * monorepo and resolves packages from above its own directory. The
+   * context is copied to `/app`; `installCommand` runs at the context root,
+   * `buildCommand` and Electron run in the app directory below it.
+   */
+  context?: string;
   /** Debian Node image tag, default 24-bookworm-slim. */
   nodeVersion?: string;
   /** Build the main/preload/renderer output; default npm run build. */
@@ -26,13 +36,14 @@ export const ELECTRON_LAUNCHER = String.raw`
 import http from 'node:http';
 import { spawn } from 'node:child_process';
 import { createRequire } from 'node:module';
-const require = createRequire('/app/package.json');
+const appDir = process.env.SPECTEST_ELECTRON_APP_DIR || '/app';
+const require = createRequire(appDir + '/package.json');
 const child = spawn(require('electron'), [
   ...(process.getuid?.() === 0 ? ['--no-sandbox'] : []),
   '--disable-dev-shm-usage', '--remote-debugging-port=9222',
   '-r', '/spectest-electron-chrome.cjs',
   process.env.SPECTEST_ELECTRON_ENTRY || '.',
-], { cwd: '/app', stdio: 'inherit', env: process.env });
+], { cwd: appDir, stdio: 'inherit', env: process.env });
 const upstream = req => ({
   host: '127.0.0.1', port: 9222, path: req.url, method: req.method,
   headers: { ...req.headers, host: '127.0.0.1:9222' },
@@ -68,18 +79,42 @@ child.on('exit', code => process.exit(code ?? 1));
 for (const signal of ['SIGTERM', 'SIGINT']) process.on(signal, () => child.kill(signal));
 `;
 
+/** Read a package.json and tell whether it declares electron. */
+function declaresElectron(manifest: string): boolean {
+  if (!existsSync(manifest)) return false;
+  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
+  return Boolean(pkg.dependencies?.electron || pkg.devDependencies?.electron);
+}
+
+/** The app directory as a path inside the build context: "." or "a/b". */
+function appPathInContext(appDir: string, context: string): string {
+  const rel = posix.relative(posix.normalize(context), posix.normalize(appDir));
+  if (rel === "") return ".";
+  if (rel.startsWith("..") || posix.isAbsolute(rel)) {
+    throw new Error(`electron(): appDir ${JSON.stringify(appDir)} must be inside context ${JSON.stringify(context)}`);
+  }
+  return rel;
+}
+
 /** Real Linux Electron under Xvfb, with a generated image and graphical replay.
  * Like expo(), returns an app handle for the matching context method.
  * Requires Linux-compatible application dependencies and binaries. */
 export function electron(options: ElectronOptions = {}) {
   const appDir = options.appDir ?? ".";
+  const context = options.context ?? appDir;
+  const appPath = appPathInContext(appDir, context);
   const manifest = resolveProjectPath(`${appDir}/package.json`);
   if (!existsSync(manifest)) throw new Error(`electron(): no package.json in ${appDir}`);
-  const pkg = JSON.parse(readFileSync(manifest, "utf8"));
-  if (!pkg.dependencies?.electron && !pkg.devDependencies?.electron) {
-    throw new Error("electron(): declare electron in the app's dependencies or devDependencies");
+  // A monorepo declares electron in the workspace or at the root; both work
+  // because the app resolves `electron` upward from its own directory.
+  if (!declaresElectron(manifest) && !declaresElectron(resolveProjectPath(`${context}/package.json`))) {
+    throw new Error(
+      "electron(): declare electron in the app's dependencies or devDependencies" +
+        (context === appDir ? "" : ` (in ${appDir} or in the context ${context})`),
+    );
   }
-  const locked = existsSync(resolveProjectPath(`${appDir}/package-lock.json`));
+  // The install runs at the context root, so that is where the lockfile counts.
+  const locked = existsSync(resolveProjectPath(`${context}/package-lock.json`));
   const node = options.nodeVersion ?? "24-bookworm-slim";
   if (!/^[\w.-]+$/.test(node)) throw new Error("electron(): invalid Node image tag");
   const install = options.installCommand ?? (locked ? "npm ci" : "npm install");
@@ -87,18 +122,22 @@ export function electron(options: ElectronOptions = {}) {
   if ([install, build].some(command => /[\r\n]/.test(command))) {
     throw new Error("electron(): build/install commands must be single-line shell commands");
   }
+  // Electron can be hoisted to the context root, so find its install script
+  // through Node's resolution from the app directory instead of a fixed path.
+  const inApp = appPath === "." ? "" : `cd ${appPath} && `;
+  const fetchElectron = `${inApp}node "$(node -p "require.resolve('electron/install.js')")"`;
   return {
     image: {
       type: "dockerfile",
-      context: appDir,
+      context,
       exclude: ["node_modules", "**/node_modules", "out", "test-results", ".data"],
       content: `FROM node:${node}
 RUN apt-get update && apt-get install -y --no-install-recommends xvfb xauth libgtk-3-0 libnss3 libgbm1 libasound2 fonts-liberation ca-certificates && rm -rf /var/lib/apt/lists/*
 WORKDIR /app
 COPY . .
 RUN ${install}
-RUN node node_modules/electron/install.js
-RUN ${build}
+RUN ${fetchElectron}
+RUN ${inApp}${build}
 `,
     },
     files: [
@@ -106,7 +145,11 @@ RUN ${build}
       { path: "/spectest-electron-chrome.cjs", content: ELECTRON_CHROME_HOOK },
     ],
     command: "xvfb-run -a node /spectest-electron.mjs",
-    env: { ...options.env, SPECTEST_ELECTRON_ENTRY: options.entry ?? "." },
+    env: {
+      ...options.env,
+      SPECTEST_ELECTRON_ENTRY: options.entry ?? ".",
+      SPECTEST_ELECTRON_APP_DIR: appPath === "." ? "/app" : `/app/${appPath}`,
+    },
     dependsOn: options.dependsOn,
     ports: [9223],
     readyCheck: { type: "http", port: 9223, path: "/json/version", timeoutSecs: 60 },