@schmock/cli 2.4.1 → 2.5.0

package/dist/request.d.ts

@@ -0,0 +1,38 @@
+import type * as Schmock from "@schmock/core";
+import type { NodeRequestLike, NodeResponseLike } from "@schmock/core";
+/**
+ * The parts of Node's request and response the bridge uses. Structural, as
+ * core declares them, so a request typed by any `@types/node` copy fits.
+ */
+type NodeRequest = NodeRequestLike;
+type NodeResponse = NodeResponseLike;
+export interface CliRequestContext {
+    /** The mock this request is served by, resolved when it arrives. */
+    readonly mock: Schmock.CallableMockInstance;
+    /** Whether `/schmock-admin/*` is the admin API rather than mock routes. */
+    readonly admin: boolean;
+    readonly cors: boolean;
+    readonly adminToken: string | undefined;
+}
+/**
+ * Serve one CLI request through core's Node bridge, which parses it (400 for a
+ * bad Host or target, 405 with `allow` for a verb Schmock does not route),
+ * collects the body (400 when it is malformed, 413 over core's 10 MB default,
+ * the limit `mock.listen()` uses) and writes every answer. Only what the CLI
+ * adds is decided here: the CORS preflight, the admin API, and which answers
+ * carry CORS headers.
+ *
+ * The preflight and the admin API never use the body, so they are answered
+ * before it is read: an oversized, malformed or stalled upload cannot turn an
+ * admin 401 into a 413 or 400, hold the socket before the refusal, or fail an
+ * authorized admin action on a body it ignores. The admin answer therefore
+ * also reads the mock as it is on arrival, not after an upload a watch reload
+ * may have overtaken.
+ *
+ * The admission is taken on arrival, before the body uploads: a watch reload
+ * resets the previous mock as soon as it swaps in the new one, and an
+ * admission snapshots routes, plugins and state, so a request already under
+ * way keeps being served by the mock it arrived at.
+ */
+export declare function handleCliRequest(req: NodeRequest, res: NodeResponse, context: CliRequestContext): Promise<void>;
+export {};

package/dist/seed-manifest.d.ts

@@ -0,0 +1,15 @@
+import type * as Schmock from "@schmock/core";
+/**
+ * Read a `--seed` manifest.
+ *
+ * Every entry shape is checked explicitly and anything unrecognised throws:
+ * silently dropping a malformed entry used to start a server whose collections
+ * were quietly empty. File entries resolve relative to the manifest rather than
+ * the process CWD, and may not escape the manifest directory.
+ *
+ * @throws ResourceLimitError when the manifest exceeds `MAX_SEED_MANIFEST_BYTES`
+ * @throws SchmockError `OPENAPI_INVALID_OPTION` for a manifest that is not a
+ *   JSON object or holds an entry that is not an array, a file path inside the
+ *   manifest directory, or `{ "count": <number> }`
+ */
+export declare function loadSeedFile(seedPath: string): Schmock.SeedConfig;

package/dist/server.d.ts

@@ -0,0 +1,14 @@
+import type { CliOptions, CliServer } from "./types.js";
+/** Default ceiling on how long a graceful close waits for in-flight requests. */
+export declare const SHUTDOWN_GRACE_MS = 5000;
+export declare function serverUrl(address: {
+    hostname: string;
+    port: number;
+}): string;
+/**
+ * Start a mock server for an OpenAPI spec, as the `schmock` command does.
+ *
+ * @throws SchmockError `INVALID_CONFIG` for a blank hostname or an unusable
+ *   admin token, before anything is bound
+ */
+export declare function createCliServer(options: CliOptions): Promise<CliServer>;

package/dist/types.d.ts

@@ -0,0 +1,28 @@
+import type { Server } from "node:http";
+/**
+ * Options for `createCliServer`, one per `schmock` flag. An alias of the
+ * ambient `Schmock.CliOptions` rather than a copy, so the documented flags
+ * and the accepted options cannot drift apart.
+ */
+export type CliOptions = Schmock.CliOptions;
+/**
+ * A running CLI server. Kept separate from the ambient `Schmock.CliServer`,
+ * whose `server` is a browser-safe subset: this one exposes the exact Node.js
+ * `Server`.
+ */
+export interface CliServer {
+    server: Server;
+    port: number;
+    hostname: string;
+    /**
+     * The bearer token this server requires on `/schmock-admin/*`. Present only
+     * when admin is enabled; supply it as `Authorization: Bearer <token>`.
+     */
+    adminToken?: string;
+    /**
+     * Stop watching, stop accepting, and settle once the socket is released —
+     * within {@link CliOptions.shutdownGraceMs}. Memoized: every call observes
+     * the same shutdown, so closing twice is safe and resolves twice.
+     */
+    close(): Promise<void>;
+}

package/dist/watch.d.ts

@@ -0,0 +1,46 @@
+import type * as Schmock from "@schmock/core";
+import type { CliOptions } from "./types.js";
+/**
+ * The one mutable cell a reload writes to. The socket, the admin token and the
+ * request handler all outlive it, so swapping the mock is the entire reload.
+ */
+export interface MockHolder {
+    mock: Schmock.CallableMockInstance;
+}
+export interface WatchHandle {
+    /** Resolves once the watcher is shut and any in-flight reload has settled. */
+    close(): Promise<void>;
+}
+interface ReloadInput {
+    readonly holder: MockHolder;
+    /** Build a replacement mock from the files as they are now. */
+    readonly rebuild: () => Promise<Schmock.CallableMockInstance>;
+}
+export interface WatchInput extends ReloadInput {
+    /** The spec, `--seed` and `--refs-external` decide what is watched. */
+    readonly options: CliOptions;
+    /** Where the server listens, for the reload banner. */
+    readonly url: string;
+}
+/**
+ * Watch the spec (and everything else a reload reads) and hot-swap the mock
+ * behind the live server on changes.
+ *
+ * The watch is on each file's DIRECTORY, not the file itself. `fs.watch` on a
+ * file follows its inode, so the first atomic editor save — write a sibling
+ * temp file, rename it over the target, which is what vim, JetBrains and VS
+ * Code all do — leaves the watcher bound to the replaced inode and silently
+ * deaf to every later edit. A directory watch sees the rename, keeps seeing
+ * later in-place writes, and re-arms for free when a file is deleted and
+ * recreated. It is non-recursive, so a large tree under a watched directory
+ * costs nothing. One watcher serves each directory, and the set is re-derived
+ * after every reload so a seed manifest that names new files is followed.
+ *
+ * Paths are resolved with `resolve`, deliberately NOT `realpathSync`: a
+ * symlinked spec must keep watching the directory the user actually named.
+ * (Consequence: an editor saving the symlink's TARGET, in another directory,
+ * fires no event. Watching the target instead would break the far commoner
+ * case of a linked spec edited in place.)
+ */
+export declare function startWatch(input: WatchInput): WatchHandle;
+export {};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@schmock/cli",
   "description": "CLI for running Schmock mock servers from OpenAPI specs",
-  "version": "2.4.1",
+  "version": "2.5.0",
   "type": "module",
   "repository": {
     "type": "git",
@@ -40,8 +40,8 @@
     "test": "vitest run",
     "test:watch": "vitest --watch",
     "test:bdd": "vitest run --config vitest.config.bdd.ts",
-    "lint": "biome check src/*.ts",
-    "lint:fix": "biome check --write --unsafe src/*.ts",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write --unsafe src/",
     "check:publish": "publint && attw --pack --ignore-rules cjs-resolves-to-esm"
   },
   "license": "MIT",
@@ -49,8 +49,8 @@
     "node": "^20.19.0 || ^22.13.0 || ^23.5.0 || >=24.0.0"
   },
   "dependencies": {
-    "@schmock/core": "^2.4.1",
-    "@schmock/openapi": "^2.4.1"
+    "@schmock/core": "^2.5.0",
+    "@schmock/openapi": "^2.5.0"
   },
   "devDependencies": {
     "@amiceli/vitest-cucumber": "^7.0.0",

package/dist/bin.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"bin.d.ts","sourceRoot":"","sources":["../src/bin.ts"],"names":[],"mappings":""}

package/dist/cli.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAkB,MAAM,WAAW,CAAC;AAWxD,OAAO,KAAK,KAAK,OAAO,MAAM,eAAe,CAAC;AAgB9C,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,qEAAqE;IACrE,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AA6ID;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAwCjE;AA4jBD,wBAAsB,eAAe,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAsB7E;AAED,qGAAqG;AACrG,wBAAgB,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CASxD;AAqED,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,UAAU,GAAG;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,CA2D3E;AAwKD,wBAAsB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAyFvD"}

package/dist/index.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,YAAY,EAAE,GAAG,EAAE,MAAM,UAAU,CAAC"}