@schmock/cli 2.3.0 → 2.4.0

package/dist/bin.js

@@ -1,26 +1,63 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync, watch } from "node:fs";
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { readFileSync, realpathSync, statSync, watch } from "node:fs";
 import { createServer } from "node:http";
+import {
+  basename,
+  dirname,
+  isAbsolute,
+  relative,
+  resolve as resolvePath,
+  sep
+} from "node:path";
 import { parseArgs } from "node:util";
 import {
   collectBody,
   HTTP_METHODS,
+  HttpIngressError,
   isHttpMethod,
+  normalizeResponse,
   parseNodeHeaders,
   parseNodeQuery,
+  ResourceLimitError,
   schmock,
+  writeRejectedSchmockResponse,
   writeSchmockResponse
 } from "@schmock/core";
-import { openapi } from "@schmock/openapi";
+import { MAX_SEED_MANIFEST_BYTES, openapi } from "@schmock/openapi";
 var MAX_REQUEST_BODY_SIZE = 10 * 1024 * 1024;
+var SHUTDOWN_GRACE_MS = 5000;
 var ALLOWED_METHODS = HTTP_METHODS.join(", ");
-var CORS_HEADERS = {
-  "access-control-allow-origin": "*",
-  "access-control-allow-methods": ALLOWED_METHODS,
-  "access-control-allow-headers": "Content-Type, Authorization"
-};
+var ADMIN_PATH_PREFIX = "/schmock-admin/";
+var DEFAULT_ADMIN_HISTORY_LIMIT = 500;
+var REDACTED = "[redacted]";
+var SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "proxy-authorization",
+  "cookie",
+  "set-cookie",
+  "x-api-key",
+  "x-auth-token",
+  "x-schmock-admin-token"
+]);
+var REQUEST_ADMISSION = Symbol.for("@schmock/core.request-admission");
+function isRequestAdmission(value) {
+  return typeof value === "object" && value !== null && "handle" in value && typeof value.handle === "function" && "release" in value && typeof value.release === "function";
+}
+function acquireRequestAdmission(mock) {
+  const admit = Reflect.get(mock, REQUEST_ADMISSION);
+  if (typeof admit !== "function")
+    return;
+  const admission = Reflect.apply(admit, mock, []);
+  if (!isRequestAdmission(admission)) {
+    throw new Error("Schmock returned an invalid request admission");
+  }
+  return admission;
+}
+var DEFAULT_ALLOWED_REQUEST_HEADERS = "Content-Type, Authorization";
+var REQUEST_HEADER_LIST = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+(?:[ \t]*,[ \t]*[!#$%&'*+\-.^_`|~0-9A-Za-z]+)*$/;
 
 class CliHttpError extends Error {
   status;
@@ -34,25 +71,139 @@ class CliHttpError extends Error {
     this.name = "CliHttpError";
   }
 }
-function isSeedSource(value) {
-  return Array.isArray(value) || typeof value === "string" || typeof value === "object" && value !== null && "count" in value;
+function isCountSource(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && "count" in value && typeof value.count === "number";
+}
+function resolveSeedEntryPath(entry, key, baseDir) {
+  let real;
+  try {
+    real = realpathSync(resolvePath(baseDir, entry));
+  } catch {
+    throw new Error(`Seed entry "${key}" points to a missing file: ${entry}`);
+  }
+  const rel = relative(baseDir, real);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw new Error(`Seed entry "${key}" must stay inside the seed manifest directory: ${entry}`);
+  }
+  return real;
 }
 function loadSeedFile(seedPath) {
-  const raw = readFileSync(seedPath, "utf-8");
-  const parsed = JSON.parse(raw);
+  const manifestPath = resolvePath(seedPath);
+  const { size } = statSync(manifestPath);
+  if (size > MAX_SEED_MANIFEST_BYTES) {
+    throw new ResourceLimitError(`seed manifest "${seedPath}"`, MAX_SEED_MANIFEST_BYTES, size);
+  }
+  const baseDir = realpathSync(dirname(manifestPath));
+  const raw = readFileSync(manifestPath, "utf-8");
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Seed file "${seedPath}" contains invalid JSON`);
+  }
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
-    throw new Error(`Seed file must contain a JSON object, got: ${typeof parsed}`);
+    throw new Error(`Seed file must contain a JSON object, got: ${Array.isArray(parsed) ? "array" : typeof parsed}`);
   }
   const result = {};
   for (const [key, value] of Object.entries(parsed)) {
-    if (isSeedSource(value)) {
+    if (Array.isArray(value)) {
+      result[key] = value;
+    } else if (typeof value === "string") {
+      result[key] = resolveSeedEntryPath(value, key, baseDir);
+    } else if (isCountSource(value)) {
       result[key] = value;
+    } else {
+      throw new Error(`Seed entry "${key}" must be an array, a file path, or { "count": <number> }`);
     }
   }
   return result;
 }
+function isAdminPath(admin, path) {
+  return admin && path.startsWith(ADMIN_PATH_PREFIX);
+}
+function singleHeader(value) {
+  return typeof value === "string" ? value : undefined;
+}
+function requestedAllowHeaders(req) {
+  const requested = singleHeader(req.headers["access-control-request-headers"]);
+  const trimmed = requested?.trim();
+  if (trimmed === undefined || trimmed === "") {
+    return DEFAULT_ALLOWED_REQUEST_HEADERS;
+  }
+  return REQUEST_HEADER_LIST.test(trimmed) ? trimmed : DEFAULT_ALLOWED_REQUEST_HEADERS;
+}
+function corsHeadersFor(req) {
+  return {
+    "access-control-allow-origin": "*",
+    "access-control-allow-methods": ALLOWED_METHODS,
+    "access-control-allow-headers": requestedAllowHeaders(req)
+  };
+}
+function isCorsPreflight(req, method) {
+  return method === "OPTIONS" && singleHeader(req.headers.origin) !== undefined && singleHeader(req.headers["access-control-request-method"]) !== undefined;
+}
+function presentedAdminToken(req) {
+  const authorization = singleHeader(req.headers.authorization);
+  const bearer = authorization ? /^bearer\s+(\S+)$/i.exec(authorization.trim()) : null;
+  if (bearer)
+    return bearer[1];
+  return singleHeader(req.headers["x-schmock-admin-token"]);
+}
+function tokensMatch(expected, presented) {
+  const expectedDigest = createHash("sha256").update(expected).digest();
+  const presentedDigest = createHash("sha256").update(presented).digest();
+  return timingSafeEqual(expectedDigest, presentedDigest);
+}
+function adminResponseHeaders(extra = {}) {
+  return {
+    "content-type": "application/json",
+    "cache-control": "no-store",
+    vary: "origin",
+    ...extra
+  };
+}
+function denyAdminRequest(req, res, adminToken) {
+  if (req.headers.origin !== undefined) {
+    res.writeHead(403, adminResponseHeaders());
+    res.end(JSON.stringify({
+      error: "Admin API refuses browser-originated requests",
+      code: "FORBIDDEN"
+    }));
+    return true;
+  }
+  const presented = presentedAdminToken(req);
+  if (adminToken === undefined || adminToken === "" || presented === undefined || !tokensMatch(adminToken, presented)) {
+    res.writeHead(401, adminResponseHeaders({
+      "www-authenticate": 'Bearer realm="schmock-admin"'
+    }));
+    res.end(JSON.stringify({
+      error: "Admin API requires a valid bearer token",
+      code: "UNAUTHORIZED"
+    }));
+    return true;
+  }
+  return false;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null;
+}
+function redactHeaders(headers) {
+  if (!isRecord(headers))
+    return {};
+  const redacted = {};
+  for (const [name, value] of Object.entries(headers)) {
+    redacted[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+  }
+  return redacted;
+}
+function redactHistory(records) {
+  return records.map((record) => ({
+    ...record,
+    headers: redactHeaders(record.headers)
+  }));
+}
 function handleAdminRequest(method, path, mock, res, headers) {
-  const route = path.replace("/schmock-admin/", "");
+  const route = path.replace(ADMIN_PATH_PREFIX, "");
   if (method === "GET" && route === "routes") {
     res.writeHead(200, headers);
     res.end(JSON.stringify(mock.getRoutes()));
@@ -72,7 +223,7 @@ function handleAdminRequest(method, path, mock, res, headers) {
   }
   if (method === "GET" && route === "history") {
     res.writeHead(200, headers);
-    res.end(JSON.stringify(mock.history()));
+    res.end(JSON.stringify(redactHistory(mock.history())));
     return;
   }
   res.writeHead(404, headers);
@@ -96,76 +247,103 @@ function parseRequestMethod(req) {
   }
   return method;
 }
-function assertBodySize(headers) {
-  const contentLength = headers["content-length"];
-  if (contentLength === undefined)
-    return;
-  const declaredSize = Number(contentLength);
-  if (Number.isFinite(declaredSize) && declaredSize > MAX_REQUEST_BODY_SIZE) {
-    throw new CliHttpError(413, "PAYLOAD_TOO_LARGE", "Request body too large");
-  }
-}
 function toCliHttpError(error) {
   if (error instanceof CliHttpError)
     return error;
-  if (error !== null && typeof error === "object" && "status" in error && error.status === 413) {
-    return new CliHttpError(413, "PAYLOAD_TOO_LARGE", error instanceof Error ? error.message : "Request body too large");
+  if (error instanceof HttpIngressError) {
+    return new CliHttpError(error.status, error.code, error.message);
   }
   return new CliHttpError(500, "SERVER_ERROR", error instanceof Error ? error.message : "Internal Server Error");
 }
 async function handleCliRequest(req, res, mock, options) {
+  const abortController = new AbortController;
+  const abortRequest = () => abortController.abort();
+  req.once("aborted", abortRequest);
+  res.once("close", abortRequest);
+  let admission;
+  let requestMethod = req.method?.toUpperCase() === "HEAD" ? "HEAD" : "GET";
+  let adminRequest = false;
   try {
     const url = parseRequestUrl(req);
-    const method = parseRequestMethod(req);
     const path = url.pathname;
-    if (options.cors && method === "OPTIONS") {
-      res.writeHead(204, CORS_HEADERS);
+    adminRequest = isAdminPath(options.admin, path);
+    const method = parseRequestMethod(req);
+    requestMethod = method;
+    if (options.cors && !adminRequest && isCorsPreflight(req, method)) {
+      res.writeHead(204, corsHeadersFor(req));
       res.end();
       return;
     }
-    if (options.admin && path.startsWith("/schmock-admin/")) {
-      const adminHeaders = {
-        "content-type": "application/json",
-        ...options.cors ? CORS_HEADERS : {}
-      };
-      handleAdminRequest(method, path, mock, res, adminHeaders);
+    if (adminRequest) {
+      if (denyAdminRequest(req, res, options.adminToken))
+        return;
+      handleAdminRequest(method, path, mock, res, adminResponseHeaders());
       return;
     }
+    admission = acquireRequestAdmission(mock);
+    const handleRequest = admission?.handle ?? ((admittedMethod, requestPath, requestOptions) => mock.handle(admittedMethod, requestPath, requestOptions));
     const headers = parseNodeHeaders(req);
-    assertBodySize(headers);
     const query = parseNodeQuery(url);
     const body = await collectBody(req, headers, MAX_REQUEST_BODY_SIZE);
-    const schmockResponse = await mock.handle(method, path, {
+    const schmockResponse = await handleRequest(method, path, {
       headers,
       body,
-      query
+      query,
+      signal: abortController.signal
     });
-    const extraHeaders = options.cors ? CORS_HEADERS : undefined;
+    const extraHeaders = options.cors ? corsHeadersFor(req) : undefined;
     writeSchmockResponse(res, schmockResponse, extraHeaders);
   } catch (error) {
     const cliError = toCliHttpError(error);
     try {
-      if (!res.headersSent) {
-        res.writeHead(cliError.status, {
-          "content-type": "application/json",
-          ...options.cors ? CORS_HEADERS : {},
-          ...cliError.headers
-        });
-      }
-      if (!res.writableEnded) {
-        res.end(JSON.stringify({ error: cliError.message, code: cliError.code }));
+      if (cliError.status === 413)
+        res.shouldKeepAlive = false;
+      if (!res.headersSent && !res.writableEnded) {
+        const response = normalizeResponse({
+          status: cliError.status,
+          body: { error: cliError.message, code: cliError.code },
+          headers: {
+            "content-type": "application/json",
+            ...cliError.headers
+          }
+        }, requestMethod);
+        const extraHeaders = {
+          ...options.cors && !adminRequest ? corsHeadersFor(req) : {},
+          ...cliError.status === 413 ? { connection: "close" } : {}
+        };
+        if (cliError.status === 413) {
+          writeRejectedSchmockResponse(req, res, response, extraHeaders);
+        } else {
+          writeSchmockResponse(res, response, extraHeaders);
+        }
+      } else if (!res.writableEnded) {
+        res.end();
       }
     } catch {
       res.destroy();
     }
+  } finally {
+    req.off("aborted", abortRequest);
+    res.off("close", abortRequest);
+    admission?.release();
   }
 }
 async function createCliMock(options) {
-  const mock = schmock({ debug: options.debug, state: {} });
+  const mock = schmock({
+    debug: options.debug,
+    state: {},
+    maxHistorySize: options.admin ? options.adminHistoryLimit ?? DEFAULT_ADMIN_HISTORY_LIMIT : 0
+  });
   const openapiOptions = {
     spec: options.spec,
     fakerSeed: options.fakerSeed,
-    validateRequests: options.errors
+    validateRequests: options.errors,
+    strict: options.strict,
+    refs: {
+      external: options.refsExternal ?? false,
+      allowHttp: options.refsAllowHttp !== undefined,
+      allowedHosts: options.refsAllowHttp
+    }
   };
   if (options.seed) {
     openapiOptions.seed = loadSeedFile(options.seed);
@@ -174,33 +352,119 @@ async function createCliMock(options) {
   mock.pipe(plugin);
   return mock;
 }
-function listenWithMock(options, mock) {
+function boundedDelay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+  });
+}
+function closeHttpServer(httpServer, graceMs) {
+  return new Promise((resolve) => {
+    let graceTimer;
+    const settle = () => {
+      if (graceTimer !== undefined) {
+        clearTimeout(graceTimer);
+        graceTimer = undefined;
+      }
+      resolve();
+    };
+    httpServer.close(() => settle());
+    try {
+      httpServer.closeIdleConnections();
+    } catch {}
+    graceTimer = setTimeout(() => {
+      try {
+        httpServer.closeAllConnections();
+      } catch {}
+    }, graceMs);
+    graceTimer.unref();
+  });
+}
+function startCliServer(options, holder) {
+  if (options.hostname !== undefined && options.hostname.trim() === "") {
+    throw new Error("Invalid hostname. The hostname must be a non-empty host, address or interface.");
+  }
   const hostname = options.hostname ?? "127.0.0.1";
   const port = options.port ?? 3000;
   const cors = options.cors ?? false;
+  const graceMs = options.shutdownGraceMs ?? SHUTDOWN_GRACE_MS;
   const admin = options.admin ?? false;
+  const adminToken = admin ? options.adminToken : undefined;
   const httpServer = createServer((req, res) => {
-    handleCliRequest(req, res, mock, { admin, cors });
+    handleCliRequest(req, res, holder.mock, { admin, cors, adminToken });
   });
+  const cleanups = [];
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      const settled = closeHttpServer(httpServer, graceMs);
+      const drain = (async () => {
+        for (const cleanup of cleanups.splice(0))
+          await cleanup();
+      })();
+      drain.catch(() => {});
+      try {
+        await Promise.race([drain, boundedDelay(graceMs)]);
+      } finally {
+        await settled;
+      }
+    })();
+    return closing;
+  };
   return new Promise((resolve, reject) => {
-    httpServer.on("error", reject);
+    const onListenError = (error) => reject(error);
+    const reportServerError = (error) => {
+      process.stderr.write(`Server error: ${error instanceof Error ? error.message : String(error)}
+`);
+    };
+    httpServer.once("error", onListenError);
     httpServer.listen(port, hostname, () => {
+      httpServer.on("error", reportServerError);
+      httpServer.off("error", onListenError);
       const addr = httpServer.address();
       const actualPort = addr !== null && typeof addr === "object" ? addr.port : port;
       resolve({
         server: httpServer,
         port: actualPort,
         hostname,
-        close() {
-          httpServer.close();
+        adminToken,
+        close,
+        onClose(cleanup) {
+          cleanups.push(cleanup);
         }
       });
     });
   });
 }
+function resolveAdminToken(options) {
+  if (!options.admin)
+    return;
+  return options.adminToken ?? randomUUID();
+}
 async function createCliServer(options) {
-  const mock = await createCliMock(options);
-  return listenWithMock(options, mock);
+  const resolved = {
+    ...options,
+    adminToken: resolveAdminToken(options)
+  };
+  const holder = { mock: await createCliMock(resolved) };
+  const server = await startCliServer(resolved, holder);
+  if (resolved.watch) {
+    let watcher;
+    try {
+      watcher = startWatch(resolved.spec, resolved, holder, server);
+    } catch (error) {
+      await server.close();
+      throw error;
+    }
+    server.onClose(() => watcher.close());
+  }
+  return server;
+}
+function isLoopbackHost(hostname) {
+  const host = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  if (host === "localhost" || host === "::1" || host === "0:0:0:0:0:0:0:1") {
+    return true;
+  }
+  return /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(host);
 }
 function validatePort(value) {
   const port = Number(value);
@@ -209,6 +473,36 @@ function validatePort(value) {
   }
   return port;
 }
+function validateHistoryLimit(value) {
+  const limit = value.trim() === "" ? Number.NaN : Number(value);
+  if (!Number.isInteger(limit) || limit < 0) {
+    throw new Error(`Invalid --admin-history-limit "${value}". It must be a non-negative integer.`);
+  }
+  return limit;
+}
+function validateFakerSeed(value) {
+  const seed = value.trim() === "" ? Number.NaN : Number(value);
+  if (!Number.isInteger(seed)) {
+    throw new Error(`Invalid --seed-random "${value}". It must be a finite integer.`);
+  }
+  return seed;
+}
+function validateHostname(value) {
+  if (value === undefined)
+    return;
+  if (value.trim() === "") {
+    throw new Error("Invalid --hostname. The hostname must be a non-empty host, address or interface.");
+  }
+  return value;
+}
+function validateAdminToken(value) {
+  if (value === undefined)
+    return;
+  if (value === "" || /\s/.test(value)) {
+    throw new Error("Invalid --admin-token. The token must be non-empty and contain no whitespace.");
+  }
+  return value;
+}
 function parseCliArgs(args) {
   const { values, positionals } = parseArgs({
     args,
@@ -222,27 +516,45 @@ function parseCliArgs(args) {
       errors: { type: "boolean", default: false },
       watch: { type: "boolean", default: false },
       admin: { type: "boolean", default: false },
+      "admin-token": { type: "string" },
+      "admin-history-limit": { type: "string" },
+      strict: { type: "boolean", default: false },
+      "refs-external": { type: "boolean", default: false },
+      "refs-allow-http": { type: "string" },
       "seed-random": { type: "string" },
       help: { type: "boolean", short: "h", default: false }
     },
     strict: true,
     allowPositionals: true
   });
+  if (positionals.length > 1) {
+    throw new Error(`Unexpected extra arguments: ${positionals.slice(1).join(", ")}. Pass exactly one spec path.`);
+  }
   const spec = values.spec ?? positionals[0] ?? "";
   return {
     spec,
     port: values.port ? validatePort(values.port) : undefined,
-    hostname: values.hostname,
+    hostname: validateHostname(values.hostname),
     seed: values.seed,
     cors: values.cors,
     debug: values.debug,
     errors: values.errors,
     watch: values.watch,
     admin: values.admin,
-    fakerSeed: values["seed-random"] ? Number(values["seed-random"]) : undefined,
+    adminToken: validateAdminToken(values["admin-token"]),
+    adminHistoryLimit: values["admin-history-limit"] === undefined ? undefined : validateHistoryLimit(values["admin-history-limit"]),
+    strict: values.strict,
+    refsExternal: values["refs-external"],
+    refsAllowHttp: parseAllowedHosts(values["refs-allow-http"]),
+    fakerSeed: values["seed-random"] === undefined ? undefined : validateFakerSeed(values["seed-random"]),
     help: values.help ?? false
   };
 }
+function parseAllowedHosts(value) {
+  if (value === undefined)
+    return;
+  return value.split(",").map((host) => host.trim()).filter((host) => host.length > 0);
+}
 var USAGE = `Usage: schmock <spec> [options]
        schmock --spec <path> [options]
 
@@ -251,30 +563,52 @@ Options:
   --port <number>     Port to listen on (default: 3000)
   --hostname <host>   Hostname to bind to (default: 127.0.0.1)
   --seed <path>       JSON file with seed data
-  --cors              Enable CORS for all responses
+  --cors              Enable CORS for mock responses (never for /schmock-admin/*)
   --debug             Enable debug logging
   --errors            Enable request body validation against spec
   --watch             Watch spec file and hot-reload on changes
   --admin             Enable /schmock-admin/* introspection endpoints
+  --admin-token <token>
+                      Bearer token required by /schmock-admin/*. Generated and
+                      printed to stderr when --admin is set without it.
+  --admin-history-limit <n>
+                      Requests retained for /schmock-admin/history (default: 500).
+                      Without --admin no history is retained at all.
+  --strict            Validate the spec against the OpenAPI schema at startup
+  --refs-external     Resolve $refs to files outside the spec document
+  --refs-allow-http <hosts>
+                      Also resolve http(s) $refs, limited to this comma-separated
+                      host list (empty list = any public host). Requires
+                      --refs-external.
   --seed-random <n>   Seed for deterministic random generation
   -h, --help          Show this help message
 `;
 var WATCH_DEBOUNCE_MS = 500;
-async function reloadServer(current, options) {
-  const port = current.port;
-  const nextOptions = { ...options, port };
-  const replacementMock = await createCliMock(nextOptions);
-  current.server.closeAllConnections();
-  await new Promise((resolve) => {
-    current.server.close(() => resolve());
-  });
-  return listenWithMock(nextOptions, replacementMock);
+async function reloadMock(holder, options) {
+  const previous = holder.mock;
+  holder.mock = await createCliMock(options);
+  try {
+    previous.reset();
+  } catch {}
 }
-function startWatch(specPath, options, getCurrentServer, onReload) {
+function startWatch(specPath, options, holder, address) {
   let debounceTimer;
   let closed = false;
   let reloadQueue = Promise.resolve();
-  const watcher = watch(specPath, () => {
+  const resolvedSpec = resolvePath(specPath);
+  const specDirectory = dirname(resolvedSpec);
+  const specName = basename(resolvedSpec);
+  const isSpecEvent = (filename) => {
+    if (filename == null)
+      return true;
+    const name = basename(filename.toString());
+    return name === specName || name === basename(specDirectory);
+  };
+  const watcher = watch(specDirectory, (_event, filename) => {
+    if (closed)
+      return;
+    if (!isSpecEvent(filename))
+      return;
     if (debounceTimer)
       clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
@@ -285,32 +619,37 @@ function startWatch(specPath, options, getCurrentServer, onReload) {
 Spec changed, reloading...
 `);
         try {
-          const newServer = await reloadServer(getCurrentServer(), options);
-          if (closed) {
-            newServer.close();
+          await reloadMock(holder, options);
+          if (closed)
             return;
-          }
-          onReload(newServer);
-          process.stderr.write(`Schmock server reloaded on http://${newServer.hostname}:${newServer.port}
+          process.stderr.write(`Schmock server reloaded on http://${address.hostname}:${address.port}
 `);
         } catch (err) {
+          if (closed)
+            return;
           process.stderr.write(`Reload failed: ${err instanceof Error ? err.message : String(err)}
 `);
         }
       });
     }, WATCH_DEBOUNCE_MS);
   });
+  watcher.on("error", (error) => {
+    process.stderr.write(`Spec watch error: ${error instanceof Error ? error.message : String(error)}
+`);
+  });
   return {
-    close() {
+    async close() {
       closed = true;
       watcher.close();
       if (debounceTimer)
         clearTimeout(debounceTimer);
+      await reloadQueue;
     }
   };
 }
 async function run(args) {
-  const options = parseCliArgs(args);
+  const parsed = parseCliArgs(args);
+  const options = { ...parsed, adminToken: resolveAdminToken(parsed) };
   if (options.help) {
     process.stderr.write(USAGE);
     return;
@@ -323,7 +662,7 @@ async function run(args) {
     process.exitCode = 1;
     return;
   }
-  let cliServer = await createCliServer(options);
+  const cliServer = await createCliServer(options);
   process.stderr.write(`Schmock server running on http://${cliServer.hostname}:${cliServer.port}
 `);
   process.stderr.write(`Spec: ${options.spec}
@@ -335,24 +674,49 @@ async function run(args) {
   if (options.admin) {
     process.stderr.write(`Admin: enabled (/schmock-admin/*)
 `);
+    process.stderr.write(`Admin token: ${options.adminToken}
+`);
+    if (!isLoopbackHost(cliServer.hostname)) {
+      process.stderr.write(`WARNING: the admin API is enabled and bound to ${cliServer.hostname}, which is reachable from other hosts.
+` + `WARNING: anyone who can reach this port and the admin token can read recorded requests and reset the mock.
+`);
+    }
   }
-  let watchHandle;
   if (options.watch) {
-    watchHandle = startWatch(options.spec, options, () => cliServer, (newServer) => {
-      cliServer = newServer;
-    });
     process.stderr.write(`Watch: enabled
 `);
   }
-  const shutdown = () => {
-    process.stderr.write(`
+  return new Promise((resolveRun, rejectRun) => {
+    let shuttingDown = false;
+    let repeatReported = false;
+    const shutdown = () => {
+      if (shuttingDown) {
+        if (!repeatReported) {
+          repeatReported = true;
+          process.stderr.write(`Shutdown already in progress; waiting for in-flight requests...
+`);
+        }
+        return;
+      }
+      shuttingDown = true;
+      process.stderr.write(`
 Shutting down...
 `);
-    watchHandle?.close();
-    cliServer.close();
-  };
-  process.on("SIGINT", shutdown);
-  process.on("SIGTERM", shutdown);
+      const release = () => {
+        process.off("SIGINT", shutdown);
+        process.off("SIGTERM", shutdown);
+      };
+      cliServer.close().then((value) => {
+        release();
+        resolveRun(value);
+      }, (error) => {
+        release();
+        rejectRun(error);
+      });
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+  });
 }
 
 // src/bin.ts