@crvouga/mockingbird-service-google-ads 1.2.0 → 1.4.0

package/CHANGELOG.md

@@ -1,6 +1,18 @@
 # Changelog — @crvouga/mockingbird-service-google-ads
 
-## 1.2.0 (2026-10-11)
+## 1.4.0 (2026-10-15)
+
+### Features
+
+- unify the emulator control plane ([2068547](https://github.com/crvouga/mockingbird/commit/2068547bedde4e2e2331c1657c1a78120e84428b))
+
+## 1.3.0 (2026-10-10)
+
+### Features
+
+- resolve reported emulator coverage gaps ([6edc643](https://github.com/crvouga/mockingbird/commit/6edc6438444853a51aca27849c4c8c0449109ea0))
+
+## 1.2.0 (2026-10-08)
 
 ### Features
 

package/DISCOVERY.md

@@ -35,6 +35,7 @@ repository; live parity is an additional oracle check, not a substitute for the
 
 - `GET /__admin/health`
 - `GET /__admin`
+- `GET /__admin/controls`
 - `GET /__admin/state`
 - `GET /__admin/requests`
 - `GET /__admin/metrics`
@@ -45,6 +46,28 @@ For HTTP services, use `x-mockingbird-namespace` (or the documented credential/p
 parallel tests do not share state. Admin state, journal, metrics and fault-preset endpoints are
 designed for assertions and diagnosis by consuming test suites.
 
+## Admin controls
+
+Every HTTP emulator takes the same controls, and each means the same thing at boot
+(`createRuntime({ adminControls })`, `serve --admin-controls`), over `/__admin`, and in a request header:
+
+| Control | Admin API | Request header | Interface |
+| --- | --- | --- | --- |
+| Isolate state by key | `GET /__admin/namespaces` | `x-mockingbird-namespace: <key>` | [Namespaces](https://mockingbird.chrisvouga.dev/docs/admin-controls/namespaces) |
+| Reset to boot | `POST /__admin/reset` | `x-mockingbird-reset: true` | [Reset](https://mockingbird.chrisvouga.dev/docs/admin-controls/reset) |
+| Snapshot and restore | `POST /__admin/snapshots`, `POST /__admin/snapshots/<id>/restore` | `x-mockingbird-snapshot: <name>`, `x-mockingbird-restore: <name>` | [Snapshot and restore](https://mockingbird.chrisvouga.dev/docs/admin-controls/snapshot-and-restore) |
+| Move the clock | `POST /__admin/clock` | `x-mockingbird-time: <instant>`, `x-mockingbird-advance: <duration>` | [Clock](https://mockingbird.chrisvouga.dev/docs/admin-controls/clock) |
+| Read or branch from old state | `GET /__admin/timeline` | `x-mockingbird-at: <checkpoint>`, `x-mockingbird-branch: <name>` | [Checkpoints and branches](https://mockingbird.chrisvouga.dev/docs/admin-controls/checkpoints-and-branches) |
+| Inject a fault | `POST /__admin/faults` | `x-mockingbird-fault: <fault>` | [Faults](https://mockingbird.chrisvouga.dev/docs/admin-controls/faults) |
+| Latency and timeouts | `PUT /__admin/latency` | `x-mockingbird-delay: <duration>`, `x-mockingbird-timeout: <duration>` | [Latency and timeouts](https://mockingbird.chrisvouga.dev/docs/admin-controls/latency-and-timeouts) |
+| Replay from a seed | `PUT /__admin/controls` | `x-mockingbird-seed: <seed>` | [Seed and determinism](https://mockingbird.chrisvouga.dev/docs/admin-controls/seed-and-determinism) |
+| See what happened | `GET /__admin/requests`, `GET /__admin/state` | | [Journal, metrics and state](https://mockingbird.chrisvouga.dev/docs/admin-controls/journal-and-state) |
+
+`GET /__admin` lists every route and header with a one-line summary, and `GET /__admin/controls`
+is the namespace's current control document. The same seed and the same requests give the same
+bytes. Setting controls as an emulator starts is [Boot](https://mockingbird.chrisvouga.dev/docs/admin-controls/boot); every route and header is in
+the [Reference](https://mockingbird.chrisvouga.dev/docs/admin-controls/reference). The full guide: <https://mockingbird.chrisvouga.dev/docs/admin-controls>.
+
 ## Report a mismatch or missing capability
 
 Follow the [agent reporting contract](https://github.com/crvouga/mockingbird/blob/main/docs/REPORTING_ISSUES.md). Include package version,

package/README.md

@@ -15,27 +15,24 @@ bun add @crvouga/mockingbird-service-google-ads
 ## Usage
 
 ```ts
-import {
-  createRuntime,
-  DEFAULT_CUSTOMER,
-  DEFAULT_TOKEN,
-} from "@crvouga/mockingbird-service-google-ads"
-
-const emulator = createRuntime()
-const response = await emulator.fetch(
-  new Request(`http://emulator.local/v25/customers/${DEFAULT_CUSTOMER}/googleAds:search`, {
-    method: "POST",
-    headers: {
-      authorization: `Bearer ${DEFAULT_TOKEN}`,
-      "content-type": "application/json",
-    },
-    body: JSON.stringify({
-      query: "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign",
-    }),
-  }),
-)
-
-console.log(await response.json())
+import { OAuth2Client } from "google-auth-library"
+import { DEFAULT_CUSTOMER, DEFAULT_TOKEN } from "@crvouga/mockingbird-service-google-ads"
+import { createServer } from "@crvouga/mockingbird-service-google-ads/server"
+
+const emulator = await createServer()
+
+// Google publishes no Node client for the Ads API, so the application calls REST through
+// google-auth-library. Only the base URL and the fixture token change.
+const client = new OAuth2Client()
+client.setCredentials({ access_token: DEFAULT_TOKEN })
+const response = await client.request({
+  url: `${emulator.url}/v25/customers/${DEFAULT_CUSTOMER}/googleAds:search`,
+  method: "POST",
+  data: { query: "SELECT campaign.id, campaign.name, metrics.clicks FROM campaign" },
+})
+console.log(response.data)
+
+await emulator.close()
 ```
 
 The Ads and Analytics Data routes use OAuth Bearer credentials. Measurement Protocol routes use
@@ -51,7 +48,7 @@ faults, and resets are isolated by namespace.
 
 | Operation | Route | Behavior |
 | --- | --- | --- |
-| SearchGoogleAds | `POST /v25/customers/{customerId}/googleAds:search` | GAQL selection, filtering, ordering, aggregation, summary rows, stable 10,000-row pages and validate-only requests |
+| SearchGoogleAds | `POST /v25/customers/{customerId}/googleAds:search` | GAQL selection, filtering, ordering, aggregation, summary rows, fixed 10,000-row pages, two-hour page tokens bound to the query, and validate-only requests |
 | SearchStreamGoogleAds | `POST /v25/customers/{customerId}/googleAds:searchStream` | Deterministic JSON batches and optional summary rows |
 | MutateCampaignBudgets | `POST /v25/customers/{customerId}/campaignBudgets:mutate` | Create, update, remove, update masks, validate-only and atomic or partial failure |
 | UploadClickConversions | `POST /v25/customers/{customerId}:uploadClickConversions` | Click identifiers, conversion actions, duplicate detection, job IDs and partial failure |
@@ -63,6 +60,50 @@ faults, and resets are isolated by namespace.
 The exact request and response schemas are in [`openapi.yaml`](openapi.yaml), and the generated
 support matrix is in [`SUPPORT.md`](SUPPORT.md).
 
+Campaign budgets are read back with GAQL (`FROM campaign_budget`); uploaded conversions and
+collected events are read through the inspection routes below, and events also through the
+Analytics Data reports. REST rows use protobuf JSON names (`costMicros`, `conversionsValue`,
+`conversionActionCategory`) and int64 values are strings; GAQL field names stay snake_case.
+
+Google Ads failures are a `google.rpc.Status` whose `details` hold a `GoogleAdsFailure` with the
+per-operation `errorCode`, `message`, `location` and a `requestId` equal to the `request-id`
+response header. Unparsable JSON and every Analytics Data failure are a bare status with no Ads
+detail and no `request-id` header.
+
+## Where Google differs from a common assumption
+
+These follow Google's documentation and the pinned `googleapis` v25 protos rather than what a
+client written against an older contract may expect.
+
+- **Search page size is fixed.** `Search` returns pages of up to 10,000 rows and a request that
+  sets `pageSize` is rejected with `requestError: PAGE_SIZE_NOT_SUPPORTED`. Continue by re-sending
+  the identical query with `pageToken`; a changed query is `INVALID_PAGE_TOKEN` and a token unused
+  for two hours is `EXPIRED_PAGE_TOKEN`
+  ([paging guide](https://developers.google.com/google-ads/api/docs/reporting/paging),
+  [`SearchGoogleAdsRequest`](https://github.com/googleapis/googleapis/blob/03a91044136a014466d4293eb1fe91f2b02075d2/google/ads/googleads/v25/services/google_ads_service.proto)).
+  To page a small fixture, lower the emulator's page with the `searchPageSize` setting; the
+  request still cannot choose it.
+- **`/mp/collect` never reports validation errors over HTTP.** It answers an empty `204` for a
+  bad secret, an unparsable body or a rejected event alike. Inspect a rejection with
+  `POST /debug/mp/collect`, which returns `validationMessages` and stores nothing, or with
+  `GET /__admin/request-metadata`, which records `accepted`, `rejected`, `duplicate` and `reasons`
+  per request
+  ([validation guide](https://developers.google.com/analytics/devguides/collection/protocol/ga4/validating-events)).
+- **Timestamps older than 72 hours are overridden, not rejected,** unless the request sets
+  `validation_behavior: "ENFORCE_RECOMMENDATIONS"`
+  ([sending guide](https://developers.google.com/analytics/devguides/collection/protocol/ga4/sending-events?client_type=gtag)).
+  Google documents no bound for future timestamps, so the one-minute `futureToleranceMs` default
+  is a test policy of this emulator, not a vendor rule; set it to `null` to disable it.
+- **A validate-only budget mutation returns errors only.** A valid preflight answers `{}` with no
+  `results` and writes nothing
+  ([`MutateCampaignBudgetsRequest`](https://github.com/googleapis/googleapis/blob/03a91044136a014466d4293eb1fe91f2b02075d2/google/ads/googleads/v25/services/campaign_budget_service.proto)).
+- **Mutations take no idempotency key.** The duplicate guards are Google's own: a shared budget
+  name (`campaignBudgetError: DUPLICATE_NAME`), a conversion `orderId`
+  (`ORDER_ID_ALREADY_IN_USE`), a click and conversion time (`CLICK_CONVERSION_ALREADY_EXISTS`),
+  and a web `purchase` event's `transaction_id` per user.
+- **`developer-token` is accepted and ignored.** The pinned protos mark the developer-token
+  errors as sunset; `login-customer-id` is still checked against the customer's manager.
+
 ## Controls and failures
 
 Service-specific controls are protected by the shared `x-mockingbird-admin-key` guard and live
@@ -70,21 +111,41 @@ beside the shared health, state, clock, journal, fault, reset, and Timeline endp
 
 | Control | Purpose |
 | --- | --- |
-| `GET /__admin/events` | Inspect stored Analytics events |
-| `GET /__admin/conversions` | Inspect uploaded conversions |
+| `GET /__admin/events` | Inspect stored Analytics events, oldest first |
+| `GET /__admin/conversions` | Inspect uploaded conversions, oldest first |
 | `GET /__admin/budgets` | Inspect campaign budgets |
-| `GET /__admin/budget-mutations` | Inspect the mutation audit trail |
+| `GET /__admin/budget-mutations` | Inspect the mutation audit trail: request ID, `before` and `after` per write |
 | `GET /__admin/request-metadata` | Inspect redacted request metadata |
-| `POST /__admin/daily-metrics` | Seed synthetic daily Ads metrics |
+| `POST /__admin/daily-metrics` | Seed synthetic daily Ads metrics (`availableAt` delays one row) |
 | `POST /__admin/page-tokens/expire` | Expire all current GAQL page tokens |
-| `GET /__admin/settings` | Read reporting lag, page-token TTL and future-timestamp policy |
+| `GET /__admin/settings` | Read `reportingLagMs`, `pageTokenTtlMs`, `futureToleranceMs` and `searchPageSize` |
 | `PUT /__admin/settings` | Update those deterministic test settings |
 
-Fault presets include `quota_exhausted`, `server_error`, `network_reset`, `slow_response`,
-`ambiguous_budget_write`, `partial_budget_failure`, and `partial_conversion_failure`. The
-ambiguous-write preset commits the mutation before returning 503 so retry logic can be tested
-against an uncertain outcome. Sensitive event and conversion payloads are sealed in state;
-journals and inspection metadata contain only the fields needed for assertions.
+| To | Use |
+| --- | --- |
+| Advance the reporting date | `POST /__admin/clock {"advance": "1d"}` or `{"set": "<ISO-8601>"}`; GAQL `DURING` ranges and Analytics `today`/`yesterday`/`NdaysAgo` follow it |
+| Delay reporting | `PUT /__admin/settings {"reportingLagMs": n}` hides new events until the clock passes it |
+| Page a small fixture | `PUT /__admin/settings {"searchPageSize": n}` (1 to 10,000) |
+| Add latency | the `slow_response` preset, or `POST /__admin/faults {"latencyMs": n, "count": 1}` |
+| Fail one request | the `server_error` or `network_reset` preset |
+| Throttle | the `quota_exhausted` or `rate_limited` preset; `"count": n` throttles n requests |
+| See what arrived | `GET /__admin/requests` (the journal) and `GET /__admin/request-metadata` |
+
+Fault presets are `quota_exhausted`, `rate_limited`, `server_error`, `network_reset`,
+`slow_response`, `ambiguous_budget_write`, `partial_budget_failure`, and
+`partial_conversion_failure`. Each fires once unless `count` says otherwise, and is scoped to the
+calling namespace. The two throttling presets answer `429 RESOURCE_EXHAUSTED` with
+`quotaError: RESOURCE_EXHAUSTED` or `RESOURCE_TEMPORARILY_EXHAUSTED` and the backoff in
+`details.quotaErrorDetails.retryDelay`, before anything is written.
+
+`ambiguous_budget_write` commits the next executed budget mutation and then returns `503`, so
+retry logic can be tested against an uncertain outcome. A validate-only preflight executes
+nothing and does not spend it: the fault waits for the real call that follows. Reconcile before
+replaying: the `503` carries a `request-id` header, and `GET /__admin/budget-mutations` lists the
+write under that request ID with the budget's `before` and `after`.
+
+Sensitive event and conversion payloads are sealed in state; journals and inspection metadata
+contain only the fields needed for assertions.
 
 ## API
 
@@ -100,11 +161,19 @@ and the public fixture/runtime option types. The Node `./server` entry exports `
 Acceptance tests cover GAQL precision and paging, budget preflight and partial writes, conversion
 deduplication, GA4 event validation and reporting, OAuth scope/expiry behavior, encrypted state,
 namespaces, resets, fault recovery, and the unmodified `google-auth-library` 11.1.0 HTTP signing
-path. Property tests exercise every parity-enabled operation and prove that a divergent transport
-is detected deterministically.
-
-The emulator intentionally implements a bounded subset. It does not model the complete Google Ads
-resource graph, every GAQL function, every Analytics dimension or metric, real Google identity,
-production quota allocation, billing, dashboards, attribution processing, or undocumented
-backend behavior. Normal operation is local and does not contact Google; only the explicit parity
-command uses credentials supplied through `.env.local` or GitHub Actions secrets.
+path. Runtime tests drive every control above over `/__admin`. Property tests exercise every
+parity-enabled operation and prove that a divergent transport is detected deterministically.
+
+`test/consumer.ts` is a port of the raw-fetch traffic described in the original service request.
+It is not the requesting application's client, whose source is not in this repository, so no test
+here runs that client unmodified.
+
+## Deliberately not modelled
+
+The emulator implements a bounded subset. It does not model the complete Google Ads resource
+graph, every GAQL function, GAQL field-compatibility rules between segments and metrics, every
+Analytics dimension or metric, real Google identity, production quota allocation, billing,
+dashboards, attribution processing, or undocumented backend behavior. Uploaded conversions do not
+feed `metrics.conversions`; seed those with daily metrics. Normal operation is local and does not
+contact Google; only the explicit parity command uses credentials supplied through `.env.local`
+or GitHub Actions secrets.

package/dist/{chunk-KCDQPGFS.js → chunk-ITE3L2DF.js}

@@ -1,9 +1,12 @@
 import {
   createClock,
   createRuntime,
+  normalizeBootControls,
   parseDuration,
-  resolveAdminPrefix
-} from "./chunk-DDJPMCRI.js";
+  parseFaultHeader,
+  resolveAdminPrefix,
+  restoreClock
+} from "./chunk-SNVGFGLM.js";
 
 // ../../adapters/node/dist/cli.js
 import { readFile as readFile2 } from "node:fs/promises";
@@ -50,6 +53,8 @@ var serve = async (api, options = {}) => {
         req.socket.destroy();
         return;
       }
+      if (aborted.signal.aborted)
+        return;
       res.writeHead(500, { "content-type": "application/json" });
       res.end(JSON.stringify({
         error: {
@@ -81,6 +86,7 @@ var serve = async (api, options = {}) => {
       }
       res.end();
     } catch {
+      await new Promise((resolve2) => setImmediate(resolve2));
       res.destroy();
     } finally {
       reader.releaseLock();
@@ -164,11 +170,11 @@ var httpChild = async (target, entry, options) => {
     adminKey: entry.adminKey,
     seed: entry.seed,
     onLog: options.onLog,
+    ...entry.adminControls !== void 0 ? { adminControls: entry.adminControls } : {},
     ...entry.fixtures !== void 0 ? { fixtures: entry.fixtures } : {},
     ...entry.baseUrl !== void 0 ? { baseUrl: entry.baseUrl } : {}
   });
   const adminPrefix = resolveAdminPrefix(entry.adminPrefix);
-  runtime.isolateNamespaces();
   const locked = /* @__PURE__ */ new Set();
   const active = /* @__PURE__ */ new Map();
   const api = {
@@ -430,19 +436,12 @@ async function startFleet(config, options) {
           return json(400, { error: "freeze must be boolean" });
         const response2 = await transaction(namespace, selected, async (_name, child) => {
           const childClock = child.clock(namespace);
-          childClock.freeze();
-          childClock.set(target);
-          if (!frozen)
-            childClock.unfreeze();
+          restoreClock(childClock, { now: target, frozen });
           await child.settle?.(namespace);
           return childClock.state();
         });
-        if (response2.ok) {
-          current.freeze();
-          current.set(target);
-          if (!frozen)
-            current.unfreeze();
-        }
+        if (response2.ok)
+          restoreClock(current, { now: target, frozen });
         return response2;
       }
       if (!route)
@@ -461,13 +460,8 @@ async function startFleet(config, options) {
           return json(404, { error: "no snapshot in this namespace" });
         const restored = new Map([...point.values].map(([name]) => [name, children.get(name)]));
         const response2 = await transaction(namespace, restored, async (name, child) => child.restore(namespace, point.values.get(name)));
-        if (response2.ok) {
-          const current = clock(namespace);
-          current.freeze();
-          current.set(point.clock.now);
-          if (!point.clock.frozen)
-            current.unfreeze();
-        }
+        if (response2.ok)
+          restoreClock(clock(namespace), point.clock);
         return response2;
       }
       const snapshotId = randomUUID();
@@ -493,6 +487,8 @@ async function startFleet(config, options) {
     for (const [name, entry] of Object.entries(config.services)) {
       if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name))
         throw new Error("invalid service name");
+      if (config.adminControls !== void 0 || entry.adminControls !== void 0)
+        normalizeBootControls({ ...config.adminControls, ...entry.adminControls }, `services.${name}.adminControls`);
       try {
         const target = await options.load(name);
         if (entry.protocol && entry.protocol !== ("protocol" in target ? target.protocol : "http"))
@@ -501,7 +497,9 @@ async function startFleet(config, options) {
         const child = "start" in target ? await target.start(entry) : await httpChild(target, {
           ...entry,
           adminPrefix: resolveAdminPrefix(entry.adminPrefix ?? adminPrefix),
-          ...adminKey !== void 0 ? { adminKey } : {}
+          ...adminKey !== void 0 ? { adminKey } : {},
+          // Fleet-wide controls, with the service's own keys replacing them.
+          ...config.adminControls !== void 0 || entry.adminControls !== void 0 ? { adminControls: { ...config.adminControls, ...entry.adminControls } } : {}
         }, options);
         children.set(name, child);
         if (!await child.ready())
@@ -634,7 +632,51 @@ var COMMON_SERVE_OPTIONS = {
     value: "<key>",
     description: "Require x-mockingbird-admin-key on /__admin/* (env MOCKINGBIRD_ADMIN_KEY)"
   },
-  seed: { type: "string", value: "<seed>", description: "Seed for every random choice" },
+  seed: {
+    type: "string",
+    value: "<seed>",
+    description: "Seed for every random choice (env MOCKINGBIRD_SEED)"
+  },
+  "admin-controls": {
+    type: "string",
+    value: "<json|file>",
+    description: "Admin controls to boot with, as JSON or a JSON file: clock, latency, faults, snapshot, namespaces (env MOCKINGBIRD_ADMIN_CONTROLS)"
+  },
+  clock: {
+    type: "string",
+    value: "<instant>",
+    description: "Start the clock at this instant (epoch ms or ISO-8601)"
+  },
+  freeze: { type: "boolean", description: "Freeze the clock: it moves only when told to" },
+  "auto-advance": {
+    type: "string",
+    value: "<duration>",
+    description: "Step the clock this much before every request (e.g. 1s)"
+  },
+  latency: {
+    type: "string",
+    value: "<duration>",
+    description: "Baseline response time for every request (e.g. 250ms)"
+  },
+  jitter: {
+    type: "string",
+    value: "<duration>",
+    description: "Seeded extra latency between 0 and this"
+  },
+  "virtual-time": {
+    type: "boolean",
+    description: "Spend latency, delays and timeouts on the mock clock instead of really waiting"
+  },
+  fault: {
+    type: "string",
+    value: "<fault>",
+    description: 'A fault to boot with, as in x-mockingbird-fault: 503, rate_limited, "status=503; delay=2s"'
+  },
+  snapshot: {
+    type: "string",
+    value: "<file>",
+    description: "Start from a snapshot document (GET /__admin/snapshots/:id)"
+  },
   log: {
     type: "string",
     value: "<pretty|json|off>",
@@ -681,6 +723,68 @@ var formatLog = (format) => {
   };
 };
 var asString = (value) => typeof value === "string" ? value : void 0;
+var readJsonFile = async (path, label) => {
+  try {
+    return JSON.parse(await readFile2(path, "utf8"));
+  } catch (error) {
+    throw new Error(`${label}: cannot read ${path}: ${error instanceof Error ? error.message : error}`);
+  }
+};
+var isObject2 = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var resolveServeControls = async (values, env = process.env, base) => {
+  const source = asString(values["admin-controls"]) ?? env.MOCKINGBIRD_ADMIN_CONTROLS;
+  let document = isObject2(base) ? { ...base } : {};
+  if (source !== void 0 && source.trim() !== "") {
+    let parsed;
+    if (source.trim().startsWith("{")) {
+      try {
+        parsed = JSON.parse(source);
+      } catch {
+        throw new Error("--admin-controls: not valid JSON");
+      }
+    } else
+      parsed = await readJsonFile(source, "--admin-controls");
+    if (!isObject2(parsed))
+      throw new Error("--admin-controls: expected a JSON object");
+    document = { ...document, ...parsed };
+  }
+  const clock = isObject2(document.clock) ? { ...document.clock } : {};
+  const now = asString(values.clock);
+  if (now !== void 0)
+    clock.now = now;
+  if (values.freeze === true)
+    clock.frozen = true;
+  const autoAdvance = asString(values["auto-advance"]);
+  if (autoAdvance !== void 0)
+    clock.autoAdvance = autoAdvance;
+  if (Object.keys(clock).length > 0)
+    document.clock = clock;
+  const delay = asString(values.latency);
+  const jitter = asString(values.jitter);
+  if (delay !== void 0 || jitter !== void 0) {
+    const latency = isObject2(document.latency) ? { ...document.latency } : document.latency !== void 0 ? { delay: document.latency } : {};
+    if (delay !== void 0)
+      latency.delay = delay;
+    if (jitter !== void 0)
+      latency.jitter = jitter;
+    document.latency = latency;
+  }
+  if (values["virtual-time"] === true)
+    document.virtualTime = true;
+  const fault = asString(values.fault);
+  if (fault !== void 0)
+    document.faults = [
+      ...Array.isArray(document.faults) ? document.faults : [],
+      parseFaultHeader(fault, "--fault")
+    ];
+  const snapshot = asString(values.snapshot);
+  if (snapshot !== void 0)
+    document.snapshot = await readJsonFile(snapshot, "--snapshot");
+  if (Object.keys(document).length === 0)
+    return void 0;
+  normalizeBootControls(document, "adminControls");
+  return document;
+};
 var loadTarget = async (name, own) => {
   if (name === own.name)
     return own;
@@ -707,7 +811,8 @@ var start = async (target, values, config) => {
     adminPrefix,
     adminKey: config.adminKey,
     seed: config.seed,
-    onLog: formatLog(config.log)
+    onLog: formatLog(config.log),
+    ...config.adminControls !== void 0 ? { adminControls: config.adminControls } : {}
   });
   const listening = await listen(runtime, { port: config.port, host: config.host });
   target.listening?.(listening);
@@ -747,6 +852,9 @@ var serveCommand = (target) => ({
         const adminKey2 = config.adminKey ?? asString(values["admin-key"]) ?? process.env.MOCKINGBIRD_ADMIN_KEY;
         if (adminKey2 !== void 0)
           config.adminKey = adminKey2;
+        const adminControls = await resolveServeControls(values, process.env, config.adminControls);
+        if (adminControls !== void 0)
+          config.adminControls = adminControls;
         const fleet = await startFleet(config, {
           load: (name) => loadTarget(name, target),
           onLog: formatLog(config.log ?? log),
@@ -772,10 +880,12 @@ var serveCommand = (target) => ({
     }
     const port = asString(values.port);
     const adminKey = asString(values["admin-key"]) ?? process.env.MOCKINGBIRD_ADMIN_KEY;
-    const seed = asString(values.seed);
+    const seed = asString(values.seed) ?? process.env.MOCKINGBIRD_SEED;
     let listening;
     try {
+      const adminControls = await resolveServeControls(values);
       listening = await start(target, values, {
+        ...adminControls !== void 0 ? { adminControls } : {},
         adminPrefix: resolveAdminPrefix(asString(values["admin-prefix"]) ?? process.env.MOCKINGBIRD_ADMIN_PREFIX),
         port: port === void 0 ? target.defaultPort : Number.parseInt(port, 10),
         host: asString(values.host) ?? "127.0.0.1",
@@ -804,6 +914,7 @@ var serveTarget = {
   create: (_values, common) => createRuntime({
     ...common.adminPrefix !== void 0 ? { adminPrefix: common.adminPrefix } : {},
     ...common.adminKey !== void 0 ? { adminKey: common.adminKey } : {},
+    ...common.adminControls !== void 0 ? { adminControls: common.adminControls } : {},
     ...common.seed !== void 0 ? { seed: common.seed } : {},
     ...common.onLog ? { onLog: common.onLog } : {}
   }),
@@ -817,4 +928,4 @@ export {
   createServer2 as createServer,
   serveTarget
 };
-//# sourceMappingURL=chunk-KCDQPGFS.js.map
+//# sourceMappingURL=chunk-ITE3L2DF.js.map