@schmock/cli 2.4.1 → 2.5.0

package/dist/index.js

@@ -1,124 +1,12 @@
-// src/cli.ts
+// src/admin.ts
 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 { MAX_SEED_MANIFEST_BYTES, openapi } from "@schmock/openapi";
-var MAX_REQUEST_BODY_SIZE = 10 * 1024 * 1024;
-var SHUTDOWN_GRACE_MS = 5000;
+import { SchmockError, SENSITIVE_HEADER_NAMES } from "@schmock/core";
+
+// src/cors.ts
+import { HTTP_METHODS } from "@schmock/core";
 var ALLOWED_METHODS = HTTP_METHODS.join(", ");
-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;
-  code;
-  headers;
-  constructor(status, code, message, headers = {}) {
-    super(message);
-    this.status = status;
-    this.code = code;
-    this.headers = headers;
-    this.name = "CliHttpError";
-  }
-}
-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 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: ${Array.isArray(parsed) ? "array" : typeof parsed}`);
-  }
-  const result = {};
-  for (const [key, value] of Object.entries(parsed)) {
-    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;
 }
@@ -140,6 +28,22 @@ function corsHeadersFor(req) {
 function isCorsPreflight(req, method) {
   return method === "OPTIONS" && singleHeader(req.headers.origin) !== undefined && singleHeader(req.headers["access-control-request-method"]) !== undefined;
 }
+
+// src/admin.ts
+var ADMIN_PATH_PREFIX = "/schmock-admin/";
+var DEFAULT_ADMIN_HISTORY_LIMIT = 500;
+var REDACTED = "[redacted]";
+var CREDENTIAL_NAME = /(?:^|[-_])(?:api[-_]?key|key|token|secret|password)$/;
+function isSensitiveHeader(name) {
+  const lower = name.toLowerCase();
+  return SENSITIVE_HEADER_NAMES.has(lower) || CREDENTIAL_NAME.test(lower);
+}
+function isSensitiveQueryKey(name) {
+  return CREDENTIAL_NAME.test(name.toLowerCase());
+}
+function isAdminPath(admin, path) {
+  return admin && path.startsWith(ADMIN_PATH_PREFIX);
+}
 function presentedAdminToken(req) {
   const authorization = singleHeader(req.headers.authorization);
   const bearer = authorization ? /^bearer\s+(\S+)$/i.exec(authorization.trim()) : null;
@@ -152,336 +56,128 @@ function tokensMatch(expected, presented) {
   const presentedDigest = createHash("sha256").update(presented).digest();
   return timingSafeEqual(expectedDigest, presentedDigest);
 }
-function adminResponseHeaders(extra = {}) {
+function adminResponse(status, body, extraHeaders = {}) {
   return {
-    "content-type": "application/json",
-    "cache-control": "no-store",
-    vary: "origin",
-    ...extra
+    status,
+    body,
+    headers: {
+      "content-type": "application/json",
+      "cache-control": "no-store",
+      vary: "origin",
+      ...extraHeaders
+    }
   };
 }
-function denyAdminRequest(req, res, adminToken) {
+function refuseAdminRequest(req, adminToken) {
   if (req.headers.origin !== undefined) {
-    res.writeHead(403, adminResponseHeaders());
-    res.end(JSON.stringify({
+    return adminResponse(403, 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({
+    return adminResponse(401, JSON.stringify({
       error: "Admin API requires a valid bearer token",
       code: "UNAUTHORIZED"
-    }));
-    return true;
+    }), { "www-authenticate": 'Bearer realm="schmock-admin"' });
   }
-  return false;
+  return;
 }
-function isRecord(value) {
+function isObjectLike(value) {
   return typeof value === "object" && value !== null;
 }
-function redactHeaders(headers) {
-  if (!isRecord(headers))
+function redactEntries(entries, isSensitive) {
+  if (!isObjectLike(entries))
     return {};
   const redacted = {};
-  for (const [name, value] of Object.entries(headers)) {
-    redacted[name] = SENSITIVE_HEADERS.has(name.toLowerCase()) ? REDACTED : value;
+  for (const [name, value] of Object.entries(entries)) {
+    redacted[name] = isSensitive(name) ? REDACTED : value;
   }
   return redacted;
 }
 function redactHistory(records) {
   return records.map((record) => ({
     ...record,
-    headers: redactHeaders(record.headers)
+    query: redactEntries(record.query, isSensitiveQueryKey),
+    headers: redactEntries(record.headers, isSensitiveHeader)
   }));
 }
-function handleAdminRequest(method, path, mock, res, headers) {
+function dispatchAdminRequest({
+  method,
+  path,
+  mock
+}) {
   const route = path.replace(ADMIN_PATH_PREFIX, "");
   if (method === "GET" && route === "routes") {
-    res.writeHead(200, headers);
-    res.end(JSON.stringify(mock.getRoutes()));
-    return;
+    return adminResponse(200, JSON.stringify(mock.getRoutes()));
   }
   if (method === "GET" && route === "state") {
-    res.writeHead(200, headers);
-    res.end(JSON.stringify(mock.getState()));
-    return;
+    return adminResponse(200, JSON.stringify(mock.getState()));
   }
   if (method === "POST" && route === "reset") {
     mock.resetHistory();
     mock.resetState();
-    res.writeHead(204, headers);
-    res.end();
-    return;
+    return adminResponse(204);
   }
   if (method === "GET" && route === "history") {
-    res.writeHead(200, headers);
-    res.end(JSON.stringify(redactHistory(mock.history())));
-    return;
+    return adminResponse(200, JSON.stringify(redactHistory(mock.history())));
   }
-  res.writeHead(404, headers);
-  res.end(JSON.stringify({ error: "Unknown admin endpoint", code: "NOT_FOUND" }));
+  return adminResponse(404, JSON.stringify({ error: "Unknown admin endpoint", code: "NOT_FOUND" }));
 }
-function parseRequestUrl(req) {
-  const host = req.headers.host;
-  if (!host) {
-    throw new CliHttpError(400, "BAD_REQUEST", "Missing Host header");
-  }
-  try {
-    return new URL(req.url ?? "/", `http://${host}`);
-  } catch {
-    throw new CliHttpError(400, "BAD_REQUEST", "Malformed request target");
-  }
-}
-function parseRequestMethod(req) {
-  const method = (req.method ?? "GET").toUpperCase();
-  if (!isHttpMethod(method)) {
-    throw new CliHttpError(405, "METHOD_NOT_ALLOWED", `Unsupported HTTP method: ${method}`, { allow: ALLOWED_METHODS });
-  }
-  return method;
-}
-function toCliHttpError(error) {
-  if (error instanceof CliHttpError)
-    return error;
-  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");
+function answerAdminRequest(request) {
+  return refuseAdminRequest(request.req, request.adminToken) ?? dispatchAdminRequest(request);
 }
-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 path = url.pathname;
-    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 (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);
-    const query = parseNodeQuery(url);
-    const body = await collectBody(req, headers, MAX_REQUEST_BODY_SIZE);
-    const schmockResponse = await handleRequest(method, path, {
-      headers,
-      body,
-      query,
-      signal: abortController.signal
-    });
-    const extraHeaders = options.cors ? corsHeadersFor(req) : undefined;
-    writeSchmockResponse(res, schmockResponse, extraHeaders);
-  } catch (error) {
-    const cliError = toCliHttpError(error);
-    try {
-      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: {},
-    maxHistorySize: options.admin ? options.adminHistoryLimit ?? DEFAULT_ADMIN_HISTORY_LIMIT : 0
-  });
-  const openapiOptions = {
-    spec: options.spec,
-    fakerSeed: options.fakerSeed,
-    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);
-  }
-  const plugin = await openapi(openapiOptions);
-  mock.pipe(plugin);
-  return 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, 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) => {
-    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,
-        adminToken,
-        close,
-        onClose(cleanup) {
-          cleanups.push(cleanup);
-        }
-      });
-    });
-  });
+function isUsableAdminToken(value) {
+  return value !== "" && !/\s/.test(value);
 }
 function resolveAdminToken(options) {
   if (!options.admin)
     return;
-  return options.adminToken ?? randomUUID();
-}
-async function createCliServer(options) {
-  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());
+  if (options.adminToken === undefined)
+    return randomUUID();
+  if (!isUsableAdminToken(options.adminToken)) {
+    throw new SchmockError("Invalid admin token. The token must be non-empty and contain no whitespace.", "INVALID_CONFIG", { option: "adminToken" });
   }
-  return server;
+  return options.adminToken;
 }
+
+// src/args.ts
+import { parseArgs } from "node:util";
+import { SchmockError as SchmockError2 } from "@schmock/core";
 function isLoopbackHost(hostname) {
-  const host = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "");
+  const host = hostname.trim().toLowerCase().replace(/^\[|\]$/g, "").replace(/^::ffff:(?=\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$)/, "");
   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 invalidFlag(message, context) {
+  return new SchmockError2(message, "INVALID_CONFIG", context);
+}
+function parseDecimal(value, { signed = false } = {}) {
+  const trimmed = value.trim();
+  const pattern = signed ? /^-?\d+$/ : /^\d+$/;
+  return pattern.test(trimmed) ? Number(trimmed) : Number.NaN;
+}
 function validatePort(value) {
-  const port = Number(value);
+  const port = parseDecimal(value);
   if (!Number.isInteger(port) || port < 0 || port > 65535) {
-    throw new Error(`Invalid port "${value}". Port must be an integer between 0 and 65535.`);
+    throw invalidFlag(`Invalid port "${value}". Port must be an integer between 0 and 65535.`, { flag: "--port", value });
   }
   return port;
 }
 function validateHistoryLimit(value) {
-  const limit = value.trim() === "" ? Number.NaN : Number(value);
+  const limit = parseDecimal(value);
   if (!Number.isInteger(limit) || limit < 0) {
-    throw new Error(`Invalid --admin-history-limit "${value}". It must be a non-negative integer.`);
+    throw invalidFlag(`Invalid --admin-history-limit "${value}". It must be a non-negative integer.`, { flag: "--admin-history-limit", value });
   }
   return limit;
 }
 function validateFakerSeed(value) {
-  const seed = value.trim() === "" ? Number.NaN : Number(value);
+  const seed = parseDecimal(value, { signed: true });
   if (!Number.isInteger(seed)) {
-    throw new Error(`Invalid --seed-random "${value}". It must be a finite integer.`);
+    throw invalidFlag(`Invalid --seed-random "${value}". It must be a finite integer.`, { flag: "--seed-random", value });
   }
   return seed;
 }
@@ -489,18 +185,23 @@ 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.");
+    throw invalidFlag("Invalid --hostname. The hostname must be a non-empty host, address or interface.", { flag: "--hostname", value });
   }
   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.");
+  if (!isUsableAdminToken(value)) {
+    throw invalidFlag("Invalid --admin-token. The token must be non-empty and contain no whitespace.", { flag: "--admin-token" });
   }
   return value;
 }
+function parseAllowedHosts(value) {
+  if (value === undefined)
+    return;
+  return value.split(",").map((host) => host.trim()).filter((host) => host.length > 0);
+}
 function parseCliArgs(args) {
   const { values, positionals } = parseArgs({
     args,
@@ -526,12 +227,17 @@ function parseCliArgs(args) {
     allowPositionals: true
   });
   if (positionals.length > 1) {
-    throw new Error(`Unexpected extra arguments: ${positionals.slice(1).join(", ")}. Pass exactly one spec path.`);
+    throw invalidFlag(`Unexpected extra arguments: ${positionals.slice(1).join(", ")}. Pass exactly one spec path.`, { flag: "<spec>" });
   }
   const spec = values.spec ?? positionals[0] ?? "";
+  if (values["admin-token"] !== undefined && !values.admin) {
+    throw invalidFlag("--admin-token requires --admin.", {
+      flag: "--admin-token"
+    });
+  }
   return {
     spec,
-    port: values.port ? validatePort(values.port) : undefined,
+    port: values.port === undefined ? undefined : validatePort(values.port),
     hostname: validateHostname(values.hostname),
     seed: values.seed,
     cors: values.cors,
@@ -548,11 +254,6 @@ function parseCliArgs(args) {
     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]
 
@@ -581,32 +282,216 @@ Options:
   --seed-random <n>   Seed for deterministic random generation
   -h, --help          Show this help message
 `;
+
+// src/server.ts
+import { createServer } from "node:http";
+import { SchmockError as SchmockError4, schmock } from "@schmock/core";
+import { openapi } from "@schmock/openapi";
+
+// src/request.ts
+import { serveNodeRequest } from "@schmock/core";
+import { acquireRequestAdmission } from "@schmock/core/adapter";
+function admitRequest(mock) {
+  const noRelease = () => {};
+  let admission;
+  try {
+    admission = acquireRequestAdmission(mock);
+  } catch (error) {
+    return { handle: () => Promise.reject(error), release: noRelease };
+  }
+  return admission ?? {
+    handle: (method, path, options) => mock.handle(method, path, options),
+    release: noRelease
+  };
+}
+function handleCliRequest(req, res, context) {
+  const { mock, admin, cors, adminToken } = context;
+  const admission = admitRequest(mock);
+  const answerBeforeBody = (method, path) => {
+    const adminRequest = isAdminPath(admin, path);
+    if (cors && !adminRequest && isCorsPreflight(req, method)) {
+      return { status: 204, body: undefined, headers: {} };
+    }
+    if (adminRequest) {
+      return answerAdminRequest({ req, method, path, mock, adminToken });
+    }
+    return;
+  };
+  return serveNodeRequest(req, res, {
+    handle: (method, path, options) => admission.handle(method, path, options),
+    answerBeforeBody,
+    extraHeaders: ({ path }) => cors && !(path !== undefined && isAdminPath(admin, path)) ? corsHeadersFor(req) : undefined
+  }).finally(() => admission.release());
+}
+
+// src/seed-manifest.ts
+import { readFileSync, realpathSync, statSync } from "node:fs";
+import {
+  dirname,
+  isAbsolute,
+  relative,
+  resolve as resolvePath,
+  sep
+} from "node:path";
+import { ResourceLimitError, SchmockError as SchmockError3 } from "@schmock/core";
+import { MAX_SEED_MANIFEST_BYTES } from "@schmock/openapi";
+function invalidSeed(message, context = {}) {
+  return new SchmockError3(message, "OPENAPI_INVALID_OPTION", {
+    option: "seed",
+    ...context
+  });
+}
+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 invalidSeed(`Seed entry "${key}" points to a missing file: ${entry}`, {
+      resource: key
+    });
+  }
+  const rel = relative(baseDir, real);
+  if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
+    throw invalidSeed(`Seed entry "${key}" must stay inside the seed manifest directory: ${entry}`, { resource: key });
+  }
+  return real;
+}
+function loadSeedFile(seedPath) {
+  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 invalidSeed(`Seed file "${seedPath}" contains invalid JSON`);
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+    throw invalidSeed(`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 (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 invalidSeed(`Seed entry "${key}" must be an array, a file path, or { "count": <number> }`, { resource: key });
+    }
+  }
+  return result;
+}
+
+// src/watch.ts
+import { realpathSync as realpathSync2, watch } from "node:fs";
+import { basename, dirname as dirname2, relative as relative2, resolve as resolvePath2 } from "node:path";
 var WATCH_DEBOUNCE_MS = 500;
-async function reloadMock(holder, options) {
+async function reloadMock({ holder, rebuild }) {
   const previous = holder.mock;
-  holder.mock = await createCliMock(options);
+  holder.mock = await rebuild();
   try {
     previous.reset();
   } catch {}
 }
-function startWatch(specPath, options, holder, address) {
+var SCHEMA_EXTENSION = /\.(?:json|ya?ml)$/i;
+function isSchemaSibling(name) {
+  return SCHEMA_EXTENSION.test(name) && !name.startsWith(".");
+}
+function seedEntryFiles(seedPath) {
+  try {
+    return Object.values(loadSeedFile(seedPath)).filter((source) => typeof source === "string");
+  } catch {
+    return [];
+  }
+}
+function realDirectory(directory) {
+  try {
+    return realpathSync2(directory);
+  } catch {
+    return directory;
+  }
+}
+function collectWatchTargets(options) {
+  const targets = new Map;
+  const matcherFor = (directory) => {
+    let matcher = targets.get(directory);
+    if (!matcher) {
+      matcher = { names: new Set, schemaSiblings: false };
+      targets.set(directory, matcher);
+    }
+    return matcher;
+  };
+  const addFile = (path) => {
+    matcherFor(dirname2(path)).names.add(basename(path));
+  };
+  const resolvedSpec = resolvePath2(options.spec);
+  addFile(resolvedSpec);
+  if (options.refsExternal) {
+    matcherFor(dirname2(resolvedSpec)).schemaSiblings = true;
+  }
+  if (options.seed !== undefined) {
+    const manifest = resolvePath2(options.seed);
+    const manifestDirectory = dirname2(manifest);
+    addFile(manifest);
+    const realManifestDirectory = realDirectory(manifestDirectory);
+    for (const entry of seedEntryFiles(options.seed)) {
+      addFile(resolvePath2(manifestDirectory, relative2(realManifestDirectory, entry)));
+    }
+  }
+  return targets;
+}
+function matchesWatchTarget(matcher, directory, filename) {
+  if (filename == null)
+    return true;
+  const name = basename(filename.toString());
+  return matcher.names.has(name) || name === basename(directory) || matcher.schemaSiblings && isSchemaSibling(name);
+}
+function startWatch(input) {
+  const { options, url } = input;
   let debounceTimer;
   let closed = false;
   let reloadQueue = Promise.resolve();
-  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);
+  let targets = collectWatchTargets(options);
+  const watchers = new Map;
+  const reportWatchError = (error) => {
+    process.stderr.write(`Spec watch error: ${error instanceof Error ? error.message : String(error)}
+`);
+  };
+  const closeWatchers = () => {
+    for (const watcher of watchers.values())
+      watcher.close();
+    watchers.clear();
   };
-  const watcher = watch(specDirectory, (_event, filename) => {
+  const rearm = () => {
     if (closed)
       return;
-    if (!isSpecEvent(filename))
-      return;
+    targets = collectWatchTargets(options);
+    for (const [directory, watcher] of watchers) {
+      if (targets.has(directory))
+        continue;
+      watcher.close();
+      watchers.delete(directory);
+    }
+    for (const directory of targets.keys()) {
+      if (watchers.has(directory))
+        continue;
+      try {
+        watchers.set(directory, watchDirectory(directory));
+      } catch (error) {
+        reportWatchError(error);
+      }
+    }
+  };
+  const scheduleReload = () => {
     if (debounceTimer)
       clearTimeout(debounceTimer);
     debounceTimer = setTimeout(() => {
@@ -617,10 +502,10 @@ function startWatch(specPath, options, holder, address) {
 Spec changed, reloading...
 `);
         try {
-          await reloadMock(holder, options);
+          await reloadMock(input);
           if (closed)
             return;
-          process.stderr.write(`Schmock server reloaded on http://${address.hostname}:${address.port}
+          process.stderr.write(`Schmock server reloaded on ${url} (state and request history reset)
 `);
         } catch (err) {
           if (closed)
@@ -628,23 +513,200 @@ Spec changed, reloading...
           process.stderr.write(`Reload failed: ${err instanceof Error ? err.message : String(err)}
 `);
         }
+        rearm();
       });
     }, WATCH_DEBOUNCE_MS);
-  });
-  watcher.on("error", (error) => {
-    process.stderr.write(`Spec watch error: ${error instanceof Error ? error.message : String(error)}
-`);
-  });
+  };
+  function watchDirectory(directory) {
+    const watcher = watch(directory, (_event, filename) => {
+      if (closed)
+        return;
+      const matcher = targets.get(directory);
+      if (matcher === undefined)
+        return;
+      if (!matchesWatchTarget(matcher, directory, filename))
+        return;
+      scheduleReload();
+    });
+    watcher.on("error", reportWatchError);
+    return watcher;
+  }
+  try {
+    for (const directory of targets.keys()) {
+      watchers.set(directory, watchDirectory(directory));
+    }
+  } catch (error) {
+    closeWatchers();
+    throw error;
+  }
   return {
     async close() {
       closed = true;
-      watcher.close();
+      closeWatchers();
       if (debounceTimer)
         clearTimeout(debounceTimer);
       await reloadQueue;
     }
   };
 }
+
+// src/server.ts
+var SHUTDOWN_GRACE_MS = 5000;
+async function createCliMock(options) {
+  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,
+    strict: options.strict,
+    refs: {
+      external: options.refsExternal ?? false,
+      allowHttp: options.refsAllowHttp !== undefined,
+      allowedHosts: options.refsAllowHttp
+    }
+  };
+  if (options.seed) {
+    openapiOptions.seed = loadSeedFile(options.seed);
+  }
+  const plugin = await openapi(openapiOptions);
+  mock.pipe(plugin);
+  return mock;
+}
+function boundedDelay(ms) {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms).unref();
+  });
+}
+function closeHttpServer({
+  httpServer,
+  graceMs,
+  sockets
+}) {
+  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 {}
+      for (const socket of sockets)
+        socket.destroy();
+    }, graceMs);
+    graceTimer.unref();
+  });
+}
+function startCliServer(options, holder) {
+  if (options.hostname !== undefined && options.hostname.trim() === "") {
+    throw new SchmockError4("Invalid hostname. The hostname must be a non-empty host, address or interface.", "INVALID_CONFIG", { option: "hostname", value: options.hostname });
+  }
+  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: holder.mock,
+      admin,
+      cors,
+      adminToken
+    });
+  });
+  const sockets = new Set;
+  httpServer.on("connection", (socket) => {
+    sockets.add(socket);
+    socket.once("close", () => sockets.delete(socket));
+  });
+  const cleanups = [];
+  let closing;
+  const close = () => {
+    closing ??= (async () => {
+      const settled = closeHttpServer({ httpServer, graceMs, sockets });
+      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) => {
+    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,
+        adminToken,
+        close,
+        onClose(cleanup) {
+          cleanups.push(cleanup);
+        }
+      });
+    });
+  });
+}
+function formatUrlHost(hostname) {
+  return hostname.includes(":") && !hostname.startsWith("[") ? `[${hostname}]` : hostname;
+}
+function serverUrl(address) {
+  return `http://${formatUrlHost(address.hostname)}:${address.port}`;
+}
+async function createCliServer(options) {
+  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({
+        options: resolved,
+        holder,
+        rebuild: () => createCliMock(resolved),
+        url: serverUrl(server)
+      });
+    } catch (error) {
+      await server.close();
+      throw error;
+    }
+    server.onClose(() => watcher.close());
+  }
+  return server;
+}
+
+// src/cli.ts
 async function run(args) {
   const parsed = parseCliArgs(args);
   const options = { ...parsed, adminToken: resolveAdminToken(parsed) };
@@ -661,7 +723,7 @@ async function run(args) {
     return;
   }
   const cliServer = await createCliServer(options);
-  process.stderr.write(`Schmock server running on http://${cliServer.hostname}:${cliServer.port}
+  process.stderr.write(`Schmock server running on ${serverUrl(cliServer)}
 `);
   process.stderr.write(`Spec: ${options.spec}
 `);
@@ -679,24 +741,36 @@ async function run(args) {
 ` + `WARNING: anyone who can reach this port and the admin token can read recorded requests and reset the mock.
 `);
     }
+  } else if (options.adminHistoryLimit !== undefined) {
+    process.stderr.write(`WARNING: --admin-history-limit has no effect without --admin; no history is retained.
+`);
   }
   if (options.watch) {
     process.stderr.write(`Watch: enabled
 `);
   }
+  const graceMs = options.shutdownGraceMs ?? SHUTDOWN_GRACE_MS;
   return new Promise((resolveRun, rejectRun) => {
     let shuttingDown = false;
     let repeatReported = false;
+    let forceExitAfter = Number.POSITIVE_INFINITY;
     const shutdown = () => {
       if (shuttingDown) {
+        if (Date.now() >= forceExitAfter) {
+          process.stderr.write(`Shutdown did not finish within the grace window; forcing exit.
+`);
+          process.exit(1);
+          return;
+        }
         if (!repeatReported) {
           repeatReported = true;
-          process.stderr.write(`Shutdown already in progress; waiting for in-flight requests...
+          process.stderr.write(`Shutdown already in progress; waiting for in-flight requests (signal again after ${graceMs} ms to force an exit)...
 `);
         }
         return;
       }
       shuttingDown = true;
+      forceExitAfter = Date.now() + graceMs;
       process.stderr.write(`
 Shutting down...
 `);