fireemu 0.23.0 → 0.25.0

package/README.md

@@ -16,7 +16,7 @@ Fireemu is being developed to close these gaps. For example, it provides:
 
 Fireemu is still in development and does not yet reproduce every feature and behavior of production Firebase. Before relying on Fireemu’s test results in CI or other automated workflows, we recommend differential testing against production Firebase services for the features and critical workflows your application uses. Run the same tests against Fireemu and a dedicated Firebase test project, and check for differences in results and behavior that could affect your application. Use a dedicated test project, not your live production project.
 
-See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.23.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.23.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
+See the [capability manifest](https://github.com/t-k/fireemu/blob/v0.25.0/crates/fireemu/src/capabilities.json) and [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.25.0/docs/compatibility-contract.md) for supported features, known differences, and the status of compatibility verification.
 
 ## Quick start
 
@@ -72,13 +72,13 @@ Fireemu supports Cloud Firestore, Firebase Authentication (Identity Platform), C
 | Cloud Pub/Sub | Schemas, BigQuery and Cloud Storage subscription delivery, and some APIs such as `UpdateTopic` are not supported.  |
 | Firebase App Check | Local testing with debug tokens is supported. Real attestation through Play Integrity, App Attest, DeviceCheck, or reCAPTCHA, and replay protection using limited-use tokens, are not supported.  |
 
-This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.23.0/crates/fireemu/src/capabilities.json).
+This table highlights key limitations; it is not exhaustive. Check individual API support and conditions with the following command or the [capability manifest](https://github.com/t-k/fireemu/blob/v0.25.0/crates/fireemu/src/capabilities.json).
 
 ```sh
 npx fireemu capabilities
 ```
 
-See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.23.0/docs/functions-export-inventory.md) for support by trigger type.
+See the [Functions support inventory](https://github.com/t-k/fireemu/blob/v0.25.0/docs/functions-export-inventory.md) for support by trigger type.
 
 ### Unsupported products
 
@@ -139,7 +139,7 @@ Use `--ui-port 0` to disable the UI. When automatic UI startup cannot bind the d
 
 When a Functions codebase is loaded, the Functions page shows registered functions, triggers, invocation results, and logs. You can run scheduled functions immediately or advance the virtual clock to their next scheduled execution. 
 
-For clock-sensitive and parallel integration tests, [test clocks and independent worlds](https://github.com/t-k/fireemu/blob/v0.23.0/docs/test-worlds.md) describes explicit Node Date/timer/Cloud Tasks policies and the `fireemu/testing` helper. Separate worlds isolate their clocks, Rules, Functions and service state, including when they use the same project ID.
+For clock-sensitive and parallel integration tests, [test clocks and independent worlds](https://github.com/t-k/fireemu/blob/v0.25.0/docs/test-worlds.md) describes explicit Node Date/timer/Cloud Tasks policies and the `fireemu/testing` helper. Separate worlds isolate their clocks, Rules, Functions and service state, including when they use the same project ID. The `fireemu/control` client also works in `fireemu exec` commands and shares URL resolution and authentication with `world.control()`, so callers do not need to concatenate control URLs.
 
 ### Export data
 
@@ -272,7 +272,7 @@ JSON also works: existing `fireemu.json` files and `--config <path>.json` remain
 | Unsigned emulator custom tokens are accepted | `auth.allowUnsignedCustomTokens` | refused |
 | Firestore and Storage Security Rules accept `@firebase/rules-unit-testing`'s unsigned mock ID token (`authenticatedContext()`, the client SDK's `mockUserToken`) | `auth.allowUnsignedIdTokens` | mock-token fallback disabled; normally verified fireemu-issued tokens still accepted |
 | Identity-provider sign-in accepts the fixture assertions and the sign-in widget (`/emulator/auth/handler`), for built-in, `oidc.*` and `saml.*` providers; under `strict` an `oidc.*` or `saml.*` provider must still be configured and enabled (`auth.providers` or the Admin API), as production requires | `auth.idpAssertions` (`"fixture"`) | `"signed"`: OIDC ID tokens must verify with an `auth.idpSigners` key, SAML responses with the provider's certificates, and the fixture and built-in providers are refused |
-| The strict Eventarc listener admits any credential or none, so the Admin SDK publishes with a fake credential (see [Eventarc authentication](https://github.com/t-k/fireemu/blob/v0.23.0/docs/eventarc-authentication.md)) | `eventarc.authentication` (`"permissive"`) | `"production"`: a missing, malformed or JWT-shaped bearer is refused with production's 401 |
+| The strict Eventarc listener admits any credential or none, so the Admin SDK publishes with a fake credential (see [Eventarc authentication](https://github.com/t-k/fireemu/blob/v0.25.0/docs/eventarc-authentication.md)) | `eventarc.authentication` (`"permissive"`) | `"production"`: a missing, malformed or JWT-shaped bearer is refused with production's 401 |
 | A tenant of `auth.tenants` can have any readable id, such as `tenant-a` | `auth.tenantIdFormat` (`"readable"`) | the id must have production's generated form, the display name, a hyphen and five characters of `a-z0-9` (`"generated"`) |
 | Multi-tenancy is on: the Admin API creates tenants and `auth.tenants` loads without an `updateConfig` call | `auth.multiTenant.allowTenants` (`true`) | unset until it is enabled, as in a new production project: tenant routes are refused and `auth.tenants` needs `allowTenants: true` |
 | Multi-factor authentication is on, SMS and TOTP, without a console toggle, an `updateConfig` call or an `auth.mfa` block | `auth.mfa` (`state: "ENABLED"`, `PHONE_SMS` and TOTP) | off until enabled, as in a new production project: enrollment is refused with `OPERATION_NOT_ALLOWED : SMS based MFA not enabled.` or `TOTP based MFA not enabled.` |
@@ -320,7 +320,7 @@ You can also name the configuration file with `--config`.
 npx fireemu up --config ./fireemu.toml
 ```
 
-Keep Fireemu-specific settings in a Fireemu configuration file containing `schemaVersion = 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.23.0/spec/config/fireemu.schema.json) for all available settings.
+Keep Fireemu-specific settings in a Fireemu configuration file containing `schemaVersion = 1`, rather than in `firebase.json`. See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.25.0/spec/config/fireemu.schema.json) for all available settings.
 
 ### Firebase Authentication (Identity Platform) configuration
 
@@ -351,9 +351,9 @@ Unsigned custom tokens minted by the Firebase Admin SDK in emulator mode are acc
 
 The unsigned mock ID token of `@firebase/rules-unit-testing` is accepted by default when Firestore and Storage Security Rules are evaluated, including with the `strict` profile. This is the token `authenticatedContext()` and the client SDKs' `mockUserToken` option send (`createMockUserToken` in `@firebase/util`). Normal verification runs first. Only after it fails can the mock-token fallback accept a token. Under `strict` that fallback accepts only the exact SDK shape: a JWT whose header is exactly `{"alg":"none","type":"JWT"}` and whose signature is empty. `request.auth` is built from the token's claims, as the official emulator builds it, when the token names a subject (`sub`) and its audience (`aud`) is the project the request goes to. Its `exp` is not checked, because the SDK sets `iat: 0` and `exp: 3600` by default. Every other token is verified as before, expiry included. That covers the unsigned ID tokens fireemu itself issues (their header carries `typ`, not `type`), and a token that claims a signature that does not verify is still refused. The `emulator` profile accepts any unsigned token, as the official emulator does, and its Storage also accepts another project's token. Set `auth.allowUnsignedIdTokens` to `false` (in either profile) or set `productionExact` to disable this fallback. Neither setting refuses fireemu-issued unsigned ID tokens that pass normal verification. Changing only an issued token's header to the SDK shape can still pass normal verification of its payload; it is not a refusal test. For a refusal test, use `createMockUserToken` with its default `iat: 0` / `exp: 3600`, or construct that exact header and empty signature with those times, a subject and the routed project as audience, and run with a clock after expiry (including Firestore's 30-second allowance). A session with `auth.idTokenSigning = "session-rsa"` accepts no unsigned token. The setting does not affect callable Functions, Identity Toolkit or App Check.
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.23.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.25.0/spec/config/fireemu.schema.json) for the format and accepted values of each setting.  
 
-Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.23.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
+Declare `auth.authorizedDomains`, for example `["localhost", "app.test"]`, to set the initial project-wide list in either profile. The list replaces the defaults, so include `localhost` if your tests use it. An empty list authorizes no host under `strict`; an absent or `null` setting keeps the existing defaults (`localhost` and the project's `firebaseapp.com` and `web.app` domains). Validation uses the Admin API's rules for the selected profile, including its conversion of numeric and boolean entries to strings and omission of `null` entries; use strings when writing the list. Fireemu intentionally keeps `localhost` in its defaults for development. The [recorded production sandbox baseline](https://github.com/t-k/fireemu/blob/v0.25.0/conformance/auth-action-production.json) does not include it; new production projects may also omit it. This default is a Fireemu-only convenience, and declaring the list replaces it. Tenant-scoped strict action links currently check the tenant's default domains rather than this project declaration; support for the parent project's live list is pending.
 
 An Admin update changes the live list. A session reset restores the declared list, when present, and preserves an Admin-written list when no initial list was declared. Projects created later receive the declaration word for word, independently of the default project's live list; listing a particular project's `firebaseapp.com` or `web.app` domain therefore gives later projects that same domain. Clearing accounts leaves the live list alone. Auth export/import carries accounts without the domain list or its declaration. The `emulator` profile accepts the setting and exposes the list, while continuing to allow action-link continue URLs outside it.
 
@@ -442,7 +442,7 @@ adjacentIntervals = 1
 
 #### Enable multi-tenancy
 
-Multi-tenancy works by default under both profiles: a new project allows tenants, so the Admin API creates them and `auth.tenants` loads without `multiTenant.allowTenants`. `productionExact` (`strict` only) starts a project as production does, with the switch unset until it is enabled through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). A declared `allowTenants: false` always turns it off. See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.23.0/docs/compatibility-contract.md) for the supported Admin API scope. 
+Multi-tenancy works by default under both profiles: a new project allows tenants, so the Admin API creates them and `auth.tenants` loads without `multiTenant.allowTenants`. `productionExact` (`strict` only) starts a project as production does, with the switch unset until it is enabled through the Admin API, or with `auth.multiTenant` in the file (see "Start with tenants" below). A declared `allowTenants: false` always turns it off. See the [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.25.0/docs/compatibility-contract.md) for the supported Admin API scope. 
 
 #### Start with tenants
 
@@ -493,7 +493,7 @@ A manual run (`POST /v1/sessions/{session}/functions/{name}:run`) enqueues one r
 
 On a task-queue function (`onTaskDispatched`), the same `POST /v1/sessions/{session}/functions/{name}:run` releases the Cloud Tasks that wait for their `scheduleTime`: all of them, or the one named by a `{"task": "<task id>"}` body (404 when no waiting task has that id). Under the strict profile a task enqueued with a `scheduleTime` waits for it, so this is how a test runs a task due in an hour without moving the clock; a released task still obeys the queue's rate and concurrency limits. The Functions page of the Emulator UI lists the waiting tasks with their due time and a **Run now** button.
 
-See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.23.0/spec/config/fireemu.schema.json) for available settings and values. 
+See the [configuration schema](https://github.com/t-k/fireemu/blob/v0.25.0/spec/config/fireemu.schema.json) for available settings and values. 
 
 ### Firestore history limits
 
@@ -569,7 +569,7 @@ Fireemu is compatible with the listed Local Emulator Suite products as shipped b
 
 The `strict` and `emulator` profiles differ in some behaviors to serve their respective purposes. Where the official emulator and production Firebase disagree, Fireemu also adopts production behavior in some cases and records the difference.
 
-Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.23.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.23.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
+Check support for the specific APIs and conditions your application uses, rather than relying on product names alone. The [compatibility contract](https://github.com/t-k/fireemu/blob/v0.25.0/spec/compatibility/contract.json) records scope and known differences. The [compatibility documentation](https://github.com/t-k/fireemu/blob/v0.25.0/docs/compatibility-contract.md) explains the verification process and how to interpret its records. 
 
 ### Network exposure of the Storage port
 
@@ -600,7 +600,7 @@ allowNonLoopbackHosts = true
 
 ### Changes between versions
 
-Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.23.0/CHANGELOG.md) for release changes.
+Configuration and behavior may change between releases. See the [CHANGELOG](https://github.com/t-k/fireemu/blob/v0.25.0/CHANGELOG.md) for release changes.
 
 ## Performance
 
@@ -617,7 +617,7 @@ The following results come from one `standard` run at commit `f3b942c`. Ratios a
 
 The 95% confidence interval for the startup-time ratio is `[21.4, 21.8]`. For the peak-memory ratio, calculated as official emulator divided by Fireemu, it is `[10.2, 11.1]`.
 
-See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.23.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.23.0/tools/bench/) for the benchmark implementation. 
+See [benchmark.yml](https://github.com/t-k/fireemu/blob/v0.25.0/.github/workflows/benchmark.yml) for the workflow and [`tools/bench/`](https://github.com/t-k/fireemu/tree/v0.25.0/tools/bench/) for the benchmark implementation. 
 
 ## Reporting issues and contributing
 
@@ -625,8 +625,8 @@ When reporting an issue, include the Fireemu and Firebase SDK versions, the prof
 
 For compatibility issues, also state whether you are comparing against the actual Firebase service or the official emulator, along with the expected and actual results. Remove credentials and personal information before sharing configuration files or logs.
 
-See the [development guide](https://github.com/t-k/fireemu/blob/v0.23.0/docs/development.md) for build and test instructions.
+See the [development guide](https://github.com/t-k/fireemu/blob/v0.25.0/docs/development.md) for build and test instructions.
 
 ## License
 
-Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.23.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.23.0/THIRD_PARTY_LICENSES.txt).
+Fireemu is licensed under the [Apache License 2.0](https://github.com/t-k/fireemu/blob/v0.25.0/LICENSE). Third-party notices are listed in [THIRD_PARTY_LICENSES.txt](https://github.com/t-k/fireemu/blob/v0.25.0/THIRD_PARTY_LICENSES.txt).

package/control.mjs

@@ -0,0 +1,60 @@
+/** Create an authenticated control client from explicit endpoints or fireemu exec's environment. */
+export function createControlClient(options = {}) {
+  const {origin: suppliedOrigin, apiBaseUrl: suppliedBase, env = process.env, requestTimeoutMs = 10_000} = options;
+  if (suppliedOrigin !== undefined && suppliedBase !== undefined) {
+    throw new TypeError('Specify origin or apiBaseUrl, not both');
+  }
+  const explicit = suppliedOrigin !== undefined || suppliedBase !== undefined;
+  const endpoint = suppliedOrigin ?? suppliedBase ?? env.FIREEMU_CONTROL_URL;
+  const token = options.token ?? (explicit ? undefined : env.FIREEMU_CONTROL_TOKEN);
+  if (typeof endpoint !== 'string' || endpoint.length === 0) {
+    throw new TypeError('Specify origin or apiBaseUrl, or set FIREEMU_CONTROL_URL');
+  }
+  let parsed;
+  try { parsed = new URL(endpoint); }
+  catch { throw new TypeError('Control endpoint must be an absolute HTTP(S) URL'); }
+  if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password || parsed.href.includes('?') || parsed.href.includes('#')) {
+    throw new TypeError('Control endpoint must be HTTP(S), without credentials, query or fragment');
+  }
+  const paths = suppliedOrigin !== undefined ? ['/'] : suppliedBase !== undefined ? ['/v1', '/v1/'] : ['/', '/v1', '/v1/'];
+  if (!paths.includes(parsed.pathname)) throw new TypeError('Control origin must have no path; apiBaseUrl must end in /v1/');
+  if (typeof token !== 'string' || !/^[\x21-\x7e]+$/.test(token)) {
+    throw new TypeError('Specify a nonempty ASCII control token without whitespace, or set FIREEMU_CONTROL_TOKEN');
+  }
+  if (!Number.isSafeInteger(requestTimeoutMs) || requestTimeoutMs <= 0 || requestTimeoutMs > 2_147_483_647) {
+    throw new TypeError('requestTimeoutMs must be a positive integer at most 2147483647');
+  }
+  const origin = parsed.origin;
+  const apiBaseUrl = `${origin}/v1/`;
+  return Object.freeze({
+    origin,
+    apiBaseUrl,
+    async request(method, path, body, {signal} = {}) {
+      // Paths are relative to this capability's endpoint; neither URLs nor redirects may change it.
+      if (typeof path !== 'string' || !path || /[\x00-\x20\x7f\\#]/.test(path) || path.startsWith('//') || /^[a-z][a-z0-9+.-]*:/i.test(path)) {
+        throw new TypeError('Control path must be API-relative or root-relative, not a URL');
+      }
+      const url = new URL(path, apiBaseUrl);
+      if (url.origin !== origin) throw new TypeError('Control path must stay on the configured origin');
+      const response = await fetch(url, {
+        method,
+        headers: {authorization:`Bearer ${token}`, ...(body === undefined ? {} : {'content-type':'application/json'})},
+        body: body === undefined ? undefined : JSON.stringify(body),
+        redirect: 'error',
+        signal: signal ?? AbortSignal.timeout(requestTimeoutMs),
+      });
+      const text = await response.text();
+      let value;
+      try { value = text === '' ? undefined : JSON.parse(text); }
+      catch {
+        if (response.ok) throw controlError(response.status, 'invalid JSON response');
+      }
+      if (!response.ok) throw controlError(response.status, value?.error?.message ?? (value === undefined ? response.statusText : JSON.stringify(value)));
+      return value;
+    },
+  });
+}
+
+function controlError(status, message) {
+  return Object.assign(new Error(`control ${status}: ${message}`), {code:'FIREEMU_CONTROL_HTTP', status});
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fireemu",
-  "version": "0.23.0",
+  "version": "0.25.0",
   "description": "A local runtime for testing Firebase SDK and Functions code, checked against production Firebase behavior",
   "keywords": [
     "emulator",
@@ -22,6 +22,7 @@
   "files": [
     "bin/fireemu.mjs",
     "binary.mjs",
+    "control.mjs",
     "testing.mjs",
     "testing-snapshot.mjs",
     "testing-process.mjs",
@@ -31,17 +32,18 @@
   ],
   "type": "module",
   "optionalDependencies": {
-    "@fireemu/darwin-arm64": "0.23.0",
-    "@fireemu/darwin-x64": "0.23.0",
-    "@fireemu/linux-x64": "0.23.0",
-    "@fireemu/linux-arm64": "0.23.0",
-    "@fireemu/win32-x64": "0.23.0"
+    "@fireemu/darwin-arm64": "0.25.0",
+    "@fireemu/darwin-x64": "0.25.0",
+    "@fireemu/linux-x64": "0.25.0",
+    "@fireemu/linux-arm64": "0.25.0",
+    "@fireemu/win32-x64": "0.25.0"
   },
   "engines": {
     "node": ">=20"
   },
   "exports": {
     "./testing": "./testing.mjs",
-    "./package.json": "./package.json"
+    "./package.json": "./package.json",
+    "./control": "./control.mjs"
   }
 }

package/testing-snapshot.mjs

@@ -2,9 +2,40 @@
 import { constants } from 'node:fs';
 import { cp, mkdir, readFile, writeFile, realpath, symlink, lstat, stat, unlink, readdir, readlink } from 'node:fs/promises';
 import { basename, dirname, join, resolve, relative, sep, delimiter, isAbsolute } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { resolveBinary, ensureExecutable } from './binary.mjs';
+
+const runFile = promisify(execFile);
+
+async function readConfiguration(path, options) {
+  const format = path.toLowerCase().endsWith('.toml') ? 'TOML' : 'JSON';
+  try {
+    if (format === 'JSON') return JSON.parse(await readFile(path, 'utf8'));
+    const binary = resolveBinary(options.binaryPath ? resolve(options.binaryPath) : undefined);
+    if (!binary) throw Error('install the fireemu platform package or supply binaryPath');
+    ensureExecutable(binary.path);
+    // Use the CLI parser so TOML types and rejection rules cannot drift between callers.
+    const { stdout } = await runFile(binary.path, ['__test-world-config', path], {
+      encoding: 'utf8', windowsHide: true, timeout: options.startupTimeoutMs ?? 60_000,
+      killSignal: 'SIGKILL', maxBuffer: 16 * 1024 * 1024, signal: options.signal,
+    });
+    return JSON.parse(stdout);
+  } catch (cause) {
+    throw Error(`Cannot read ${format} configuration ${JSON.stringify(path)}: ${cause.stderr?.trim() || cause.message}`, { cause });
+  }
+}
 
 export async function snapshotInputs(options, root) {
   const cwd=resolve(options.cwd??process.cwd());
+  const nodePathExcludes=options.nodePathExcludes===undefined?[]:options.nodePathExcludes;
+  const packageName=value=>{
+    if(typeof value!=='string'||value.includes('\\')||value.includes('\0'))return false;
+    const parts=value.split('/');
+    return (value.startsWith('@')?parts.length===2&&parts[0].length>1:parts.length===1)
+      &&parts.every((part,index)=>part!=='.'&&part!=='..'&&/^[a-zA-Z0-9._~-]+$/.test(index===0&&value.startsWith('@')?part.slice(1):part));
+  };
+  if(!Array.isArray(nodePathExcludes)||!nodePathExcludes.every(packageName))throw TypeError('nodePathExcludes must be an array of unscoped or scoped package names');
   const privateRoot=await realpath(root);
   const baseline=join(root,'baseline');
   await mkdir(baseline,{mode:0o700});
@@ -17,34 +48,49 @@ export async function snapshotInputs(options, root) {
   };
   const graph=new Map();
   const inside=(parent,path)=>{const suffix=relative(parent,path);return suffix===''||(!suffix.startsWith(`..${sep}`)&&suffix!=='..'&&!isAbsolute(suffix));};
-  const captureTree=async(source,destination)=>{
-    const canonical=await realpath(source);
-    graph.set(canonical,destination);
-    const links=[];
-    await cp(canonical,destination,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:false,verbatimSymlinks:true,filter:async(path,target)=>{
-      if(['.git','.worktree'].includes(basename(path)))return false;
-      if((await lstat(path)).isSymbolicLink())links.push([path,target]);
-      return true;
-    }});
-    for(const [sourceLink,targetLink] of links){
-      const target=await realpath(sourceLink);
-      let copied;
-      const owners=[...graph].filter(([original])=>inside(original,target)).sort((a,b)=>b[0].length-a[0].length);
-      if(owners.length){const [original,snapshot]=owners[0];copied=join(snapshot,relative(original,target));}
-      else{
-        if(graph.size>=4096)throw Error('Functions dependency graph exceeds the snapshot budget');
-        // pnpm packages resolve dependencies from their enclosing node_modules,
-        // including siblings that are not explicit links inside the package.
-        let context=dirname(target);
-        while(basename(context)!=='node_modules'&&dirname(context)!==context)context=dirname(context);
-        if(basename(context)!=='node_modules')context=target;
-        const destination=join(baseline,`linked-${sequence++}`,...(basename(context)==='node_modules'?['node_modules']:[]));
-        await captureTree(context,destination);
-        copied=join(destination,relative(context,target));
+  const omitted=new Set();
+  const captureTree=async(source,destination,excludes=[])=>{
+    try{
+      const canonical=await realpath(source);
+      graph.set(canonical,destination);
+      const links=[];
+      await cp(canonical,destination,{recursive:true,mode:constants.COPYFILE_FICLONE,dereference:false,verbatimSymlinks:true,filter:async(path,target)=>{
+        if(excludes.includes(path)){omitted.add(path);return false;}
+        if(['.git','.worktree'].includes(basename(path)))return false;
+        if((await lstat(path)).isSymbolicLink())links.push([path,target]);
+        return true;
+      }});
+      for(const [sourceLink,targetLink] of links){
+        let linkValue;
+        try{
+          linkValue=await readlink(sourceLink);
+          const target=await realpath(sourceLink);
+          const linkedExcludes=excludes.filter(path=>inside(sourceLink,path)).map(path=>join(target,relative(sourceLink,path)));
+          if([...omitted].some(path=>inside(path,target)))throw Error(`Retained link ${JSON.stringify(sourceLink)} requires excluded NODE_PATH package content ${JSON.stringify(target)}; remove that package from nodePathExcludes`);
+          let copied;
+          const owners=[...graph].filter(([original])=>inside(original,target)).sort((a,b)=>b[0].length-a[0].length);
+          if(owners.length&&linkedExcludes.length)throw Error(`Cannot apply nodePathExcludes through linked scope ${JSON.stringify(sourceLink)}: target ${JSON.stringify(target)} was already captured; narrow env.NODE_PATH instead`);
+          if(owners.length){const [original,snapshot]=owners[0];copied=join(snapshot,relative(original,target));}
+          else{
+            if(graph.size>=4096)throw Error('Functions dependency graph exceeds the snapshot budget');
+            // pnpm packages resolve dependencies from their enclosing node_modules,
+            // including siblings that are not explicit links inside the package.
+            let context=dirname(target);
+            while(basename(context)!=='node_modules'&&dirname(context)!==context)context=dirname(context);
+            if(basename(context)!=='node_modules')context=target;
+            const destination=join(baseline,`linked-${sequence++}`,...(basename(context)==='node_modules'?['node_modules']:[]));
+            await captureTree(context,destination,linkedExcludes);
+            copied=join(destination,relative(context,target));
+          }
+          await unlink(targetLink);
+          const kind=(await lstat(target)).isDirectory()?'dir':'file';
+          await symlink(process.platform==='win32'?copied:relative(dirname(targetLink),copied),targetLink,process.platform==='win32'&&kind==='dir'?'junction':kind);
+        }catch(cause){
+          throw Error(`Cannot snapshot dependency link ${JSON.stringify(sourceLink)} -> ${JSON.stringify(linkValue)}: ${cause.message}`,{cause});
+        }
       }
-      await unlink(targetLink);
-      const kind=(await lstat(target)).isDirectory()?'dir':'file';
-      await symlink(process.platform==='win32'?copied:relative(dirname(targetLink),copied),targetLink,process.platform==='win32'&&kind==='dir'?'junction':kind);
+    }catch(cause){
+      throw Error(`Cannot snapshot dependency tree ${JSON.stringify(source)}: ${cause.message}`,{cause});
     }
   };
   const copySource=async(value,base)=>{
@@ -86,7 +132,7 @@ export async function snapshotInputs(options, root) {
   };
   let input=options.config??{schemaVersion:1};
   let configBase=cwd;
-  if(typeof input==='string'){const path=resolve(cwd,input);input=JSON.parse(await readFile(path,'utf8'));configBase=dirname(path);}
+  if(typeof input==='string'){const path=resolve(cwd,input);input=await readConfiguration(path,options);configBase=dirname(path);}
   let config;
   if(input.schemaVersion===undefined){config={schemaVersion:1,firebaseJson:await snapshotFirebase(input,configBase)};}
   else{
@@ -102,11 +148,18 @@ export async function snapshotInputs(options, root) {
   const functionsConfigured=Boolean(graph.size||config.functions?.manifest||config.functions?.runner);
   const nodePaths=[];
   for(const entry of (functionsConfigured?options.env?.NODE_PATH??'':'').split(delimiter).filter(Boolean)){
-    let original;
-    try{original=await realpath(resolve(cwd,entry));}catch(error){if(error.code==='ENOENT')continue;throw error;}
-    let destination=graph.get(original);
-    if(!destination){destination=join(baseline,`node-path-${sequence++}`,'node_modules');await captureTree(original,destination);}
-    nodePaths.push(destination);
+    let original=resolve(cwd,entry);
+    try{
+      try{original=await realpath(original);}catch(error){if(error.code==='ENOENT')continue;throw error;}
+      let destination=graph.get(original);
+      if(!destination){
+        destination=join(baseline,`node-path-${sequence++}`,'node_modules');
+        await captureTree(original,destination,nodePathExcludes.map(name=>join(original,name)));
+      }
+      nodePaths.push(destination);
+    }catch(cause){
+      throw Error(`Cannot snapshot NODE_PATH entry ${JSON.stringify(entry)} (copy root ${JSON.stringify(original)}): ${cause.message}. If this global package is unused, exclude its name with nodePathExcludes; if all global roots are unused, set env.NODE_PATH to an empty string`,{cause});
+    }
   }
   config.daemon={...config.daemon,clockStart:options.clockStart??config.daemon?.clockStart??'2026-01-01T00:00:00Z',seed:options.seed??config.daemon?.seed??1,authProject:options.projectId??config.daemon?.authProject??'demo-test-world'};
   for(const service of ['firestore','http','storage','functions','eventarc','tasks','pubsub','hub','ui','logging'])config.daemon[`${service}Port`]=0;

package/testing.mjs

@@ -8,6 +8,7 @@ import { fileURLToPath } from 'node:url';
 import { setTimeout as delay } from 'node:timers/promises';
 import { resolveBinary, ensureExecutable } from './binary.mjs';
 import { snapshotInputs, prepareGeneration } from './testing-snapshot.mjs';
+import { createControlClient } from './control.mjs';
 
 const endpointVariables = {firestore:'FIRESTORE_EMULATOR_HOST',auth:'FIREBASE_AUTH_EMULATOR_HOST',storage:'FIREBASE_STORAGE_EMULATOR_HOST',functions:'FIREEMU_FUNCTIONS_HOST',eventarc:'CLOUD_EVENTARC_EMULATOR_HOST',tasks:'CLOUD_TASKS_EMULATOR_HOST',pubsub:'PUBSUB_EMULATOR_HOST',hub:'FIREBASE_EMULATOR_HUB',logging:'FIREBASE_LOGGING_EMULATOR_HOST'};
 const emulatorVariables = new Set([...Object.values(endpointVariables),'FIREBASE_CONFIG','NODE_PATH','FIREBASE_FIRESTORE_EMULATOR_ADDRESS','STORAGE_EMULATOR_HOST','FIREEMU_CONTROL_TOKEN','FIREEMU_CONTROL_URL','FIREEMU_APP_CHECK_EMULATOR_HOST','FIREEMU_APP_CHECK_JWKS_URL','FIREEMU_APP_CHECK_DEBUG_TOKEN_URL','FIREBASE_DATABASE_EMULATOR_HOST']);
@@ -43,17 +44,18 @@ async function stop(process,timeout=5000){
     if(!closed)throw Error('test world process tree did not close after forced retirement');
   }
 }
-function endpoints(descriptor){
+function endpoints(descriptor,control){
   const result={};
   const decode=value=>{const url=new URL(value.includes('://')?value:`http://${value}`);return Object.freeze({host:url.hostname,port:Number(url.port),url:`${url.protocol}//${url.host}`});};
-  result.control=decode(descriptor.controlUrl);
+  result.control=Object.freeze({...decode(descriptor.controlUrl),origin:control.origin,apiBaseUrl:control.apiBaseUrl});
   for(const [service,name] of Object.entries(endpointVariables))if(descriptor.environment[name])result[service]=decode(descriptor.environment[name]);
   return Object.freeze(result);
 }
 
 /** Create an independent emulator world; no method changes the parent's environment. */
 export async function createTestWorld(options={}){
-  options={...options,config:typeof options.config==='object'?structuredClone(options.config):options.config,services:options.services?[...options.services]:undefined,env:{...(options.env??process.env)},clock:options.clock?{...options.clock}:undefined};
+  options={...options,nodePathExcludes:Array.isArray(options.nodePathExcludes)?[...options.nodePathExcludes]:options.nodePathExcludes,config:typeof options.config==='object'?structuredClone(options.config):options.config,services:options.services?[...options.services]:undefined,env:{...(options.env??process.env)},clock:options.clock?{...options.clock}:undefined};
+  if(options.ui!==undefined&&typeof options.ui!=='boolean')throw TypeError('ui must be a boolean');
   const binary=resolveBinary(options.binaryPath?resolve(options.binaryPath):undefined);
   if(!binary)throw Error('fireemu could not start a test world: install the platform package or supply binaryPath');
   const timeout=options.startupTimeoutMs??60_000;
@@ -79,10 +81,11 @@ export async function createTestWorld(options={}){
     if(failures.length)throw new AggregateError(failures,'test world retirement failed; cleanup can be retried');
   };
   const requestFor=async(active,method,path,body,signal)=>{
-    const response=await fetch(`${active.descriptor.controlUrl}${path}`,{method,headers:{authorization:`Bearer ${active.descriptor.controlToken}`,...(body===undefined?{}:{'content-type':'application/json'})},body:body===undefined?undefined:JSON.stringify(body),signal:signal??AbortSignal.timeout(options.requestTimeoutMs??10_000)});
-    const value=await response.json();
-    if(!response.ok)throw Error(`test world control ${response.status}: ${value.error?.message??JSON.stringify(value)}`);
-    return value;
+    try{return await active.control.request(method,path,body,{signal});}
+    catch(error){
+      if(error.code==='FIREEMU_CONTROL_HTTP')error.message=`test world ${error.message}`;
+      throw error;
+    }
   };
   const start=async()=>{
     options.signal?.throwIfAborted();
@@ -91,7 +94,8 @@ export async function createTestWorld(options={}){
     const prepared=await prepareGeneration(snapshot,generationDirectory);
     const readyFile=join(generationDirectory,'ready.json');
     const args=['up','--config',prepared.configPath,'--project',snapshot.config.daemon.authProject,'--only',services.join(','),'--ready-file',readyFile,'--owner-stdin','--log-verbosity','quiet'];
-    for(const name of ['firestore','http','storage','functions','eventarc','tasks','pubsub','hub','ui','logging'])args.push(`--${name}-port`,'0');
+    for(const name of ['firestore','http','storage','functions','eventarc','tasks','pubsub','hub','logging'])args.push(`--${name}-port`,'0');
+    args.push('--ui-port',options.ui?'auto':'0');
     if(prepared.seed)args.push('--import',prepared.seed);
     const temporary=join(generationDirectory,'tmp');
     const environment={...emptyEnvironment(options.env??process.env),NODE_PATH:prepared.nodePath,TMPDIR:temporary,TEMP:temporary,TMP:temporary,FIREEMU_TEST_WORLD_ID:id,FIREEMU_TEST_WORLD_GENERATION:String(next)};
@@ -107,9 +111,10 @@ export async function createTestWorld(options={}){
           const descriptor=JSON.parse(await readFile(readyFile,'utf8'));
           if(descriptor.schemaVersion!==1||descriptor.pid!==daemon.child.pid||descriptor.projectId!==snapshot.config.daemon.authProject)throw Error('invalid test-world readiness descriptor');
           active.descriptor=descriptor;
+          active.control=createControlClient({origin:descriptor.controlUrl,token:descriptor.controlToken,requestTimeoutMs:options.requestTimeoutMs});
           await requestFor(active,'GET','/health/ready',undefined,AbortSignal.timeout(Math.min(1000,timeout)));
           if(daemon.result())throw Error('daemon exited during test-world readiness');
-          active.endpoints=endpoints(descriptor);
+          active.endpoints=endpoints(descriptor,active.control);
           active.environment=Object.freeze({...descriptor.environment,NODE_PATH:prepared.nodePath,TMPDIR:temporary,TEMP:temporary,TMP:temporary,FIREEMU_TEST_WORLD_ID:id,FIREEMU_TEST_WORLD_GENERATION:String(next)});
           generation=next;
           return;
@@ -122,6 +127,7 @@ export async function createTestWorld(options={}){
   const control=(method,path,body)=>enqueue(async()=>{check();return requestFor(current,method,path,body);});
   const world={
     get generation(){return generation;},
+    get uiUrl(){check();return current.descriptor.uiUrl??undefined;},
     get endpoints(){check();return current.endpoints;},
     get environment(){check();return current.environment;},
     get directory(){return directory;},