@dever-labs/mockly-driver 0.4.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Dever Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,245 @@
+# mockly-driver
+
+Node.js client for [Mockly](https://github.com/dever-labs/mockly) — start, stop, and control Mockly HTTP mock servers from Node.js test suites.
+
+```ts
+import { MocklyServer } from 'mockly-driver'
+
+const server = await MocklyServer.ensure() // install binary if needed, then start
+
+await server.addMock({
+  id: 'get-users',
+  request: { method: 'GET', path: '/users' },
+  response: { status: 200, body: '[{"id":1}]', headers: { 'Content-Type': 'application/json' } },
+})
+
+const res = await fetch(`${server.httpBase}/users`)
+// → 200 [{"id":1}]
+
+await server.stop()
+```
+
+## Installation
+
+```sh
+npm install --save-dev mockly-driver
+```
+
+The Mockly binary is **not** bundled in the npm package. Download it once before running tests:
+
+```sh
+npx mockly-driver-install
+```
+
+Or let `MocklyServer.ensure()` handle it automatically on first run.
+
+---
+
+## Usage
+
+### `MocklyServer.ensure(opts?)` _(recommended)_
+
+Downloads the binary if missing, then starts the server.
+
+```ts
+const server = await MocklyServer.ensure()
+```
+
+### `MocklyServer.create(opts?)`
+
+Starts the server using an already-installed binary. Throws if the binary is not found.
+
+```ts
+const server = await MocklyServer.create()
+```
+
+### Test framework integration
+
+```ts
+// vitest / jest
+import { MocklyServer } from 'mockly-driver'
+
+let server: MocklyServer
+
+beforeAll(async () => {
+  server = await MocklyServer.ensure()
+}, 30_000)
+
+afterAll(() => server?.stop())
+
+beforeEach(() => server.reset()) // isolate each test
+
+it('returns 200', async () => {
+  await server.addMock({
+    id: 'ping',
+    request: { method: 'GET', path: '/ping' },
+    response: { status: 200, body: 'pong' },
+  })
+  const res = await fetch(`${server.httpBase}/ping`)
+  expect(res.status).toBe(200)
+})
+```
+
+---
+
+## Management API
+
+### `server.addMock(mock)`
+
+Adds an HTTP mock. Mocks are matched in insertion order — first match wins.
+
+```ts
+await server.addMock({
+  id: 'create-user',
+  request: {
+    method: 'POST',
+    path: '/users',
+    headers: { Authorization: 'Bearer mytoken' }, // exact match
+  },
+  response: {
+    status: 201,
+    body: '{"id":42}',
+    headers: { 'Content-Type': 'application/json' },
+    delay: '50ms',
+  },
+})
+```
+
+> **Note:** Header matching is exact. Place mocks with header constraints _before_ less-specific fallbacks.
+
+### `server.deleteMock(id)`
+
+Removes a mock by id.
+
+### `server.reset()`
+
+Removes all dynamically added mocks, deactivates scenarios, and clears fault injection. Mocks defined in startup config are preserved. Call in `beforeEach` to keep tests isolated.
+
+### Scenarios
+
+Scenarios override mock responses when activated — useful for simulating outage modes.
+
+```ts
+const server = await MocklyServer.ensure({
+  scenarios: [
+    {
+      id: 'auth-down',
+      name: 'Auth service unavailable',
+      patches: [{ mock_id: 'token-endpoint', status: 503, body: '{"error":"down"}' }],
+    },
+  ],
+})
+
+await server.addMock({
+  id: 'token-endpoint',
+  request: { method: 'POST', path: '/token' },
+  response: { status: 200, body: '{"access_token":"abc"}' },
+})
+
+// Normal operation
+const r1 = await fetch(`${server.httpBase}/token`, { method: 'POST' })
+// → 200
+
+await server.activateScenario('auth-down')
+
+const r2 = await fetch(`${server.httpBase}/token`, { method: 'POST' })
+// → 503
+
+await server.deactivateScenario('auth-down')
+```
+
+### Fault injection
+
+```ts
+// Delay every response by 200 ms
+await server.setFault({ enabled: true, delay: '200ms' })
+
+// Override all responses with 503
+await server.setFault({ enabled: true, status_override: 503 })
+
+// Randomly fail 30% of requests
+await server.setFault({ enabled: true, status_override: 503, error_rate: 0.3 })
+
+await server.clearFault()
+```
+
+---
+
+## Binary installation
+
+### Default (download from GitHub)
+
+```sh
+npx mockly-driver-install
+```
+
+Or programmatically:
+
+```ts
+import { install } from 'mockly-driver'
+await install()
+```
+
+### Artifactory / internal mirror
+
+Set `MOCKLY_DOWNLOAD_BASE_URL` to your mirror's base URL (the path up to and including the version segment prefix):
+
+```sh
+MOCKLY_DOWNLOAD_BASE_URL=https://artifactory.company.com/artifactory/github-releases/dever-labs/mockly/releases/download \
+  npx mockly-driver-install
+```
+
+Artifactory setup: create a **Generic Remote Repository** pointing to `https://github.com` and enable "Store Artifacts Locally". The download URL then becomes `https://<artifactory>/artifactory/<repo>/dever-labs/mockly/releases/download`.
+
+### HTTP / HTTPS proxy
+
+Set `HTTPS_PROXY` or `HTTP_PROXY` before running the install:
+
+```sh
+HTTPS_PROXY=https://proxy.company.com:3128 npx mockly-driver-install
+```
+
+Proxy authentication is supported via the proxy URL: `https://user:pass@proxy:3128`.
+
+> **Note:** If your proxy username or password contains special characters (e.g. `@`, `:`, `/`), URL-encode them first — e.g. `p@ss` → `p%40ss`. Use `encodeURIComponent()` in Node.js or an online encoder.
+
+> **Tip:** For Artifactory, `MOCKLY_DOWNLOAD_BASE_URL` is simpler and more reliable than `HTTPS_PROXY`.
+
+### Air-gapped environments
+
+Pre-stage the binary and point to it:
+
+```sh
+# On a machine with internet access:
+npx mockly-driver-install
+
+# Copy bin/mockly[.exe] to the air-gapped machine, then:
+MOCKLY_BINARY_PATH=/opt/tools/mockly npx vitest run
+```
+
+Or set `MOCKLY_NO_INSTALL=true` to make the binary absence a hard error with actionable instructions:
+
+```sh
+MOCKLY_NO_INSTALL=true npx vitest run  # fails fast if binary not staged
+```
+
+### Environment variable reference
+
+| Variable | Description |
+|---|---|
+| `MOCKLY_BINARY_PATH` | Absolute path to a pre-existing binary. Skips all download logic. |
+| `MOCKLY_DOWNLOAD_BASE_URL` | Base URL override for binary downloads (Artifactory / mirrors). |
+| `MOCKLY_VERSION` | Binary version to install. Default: `v0.1.0`. |
+| `MOCKLY_NO_INSTALL` | If set, fail with instructions instead of downloading. |
+| `HTTPS_PROXY` / `HTTP_PROXY` | Route downloads through an HTTP proxy (supports CONNECT). |
+
+---
+
+## Requirements
+
+- Node.js ≥ 18
+- Platforms: Linux (x64/arm64), macOS (x64/arm64), Windows (x64)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { MocklyServer } from './server.js';
+export { install, getBinaryPath, DEFAULT_MOCKLY_VERSION } from './install.js';
+export { getFreePort } from './utils.js';
+export type { HttpMock, MockRequest, MockResponse, Scenario, ScenarioPatch, FaultConfig, MocklyServerOptions, } from './types.js';
+export type { InstallOptions } from './install.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AACxC,YAAY,EACV,QAAQ,EACR,WAAW,EACX,YAAY,EACZ,QAAQ,EACR,aAAa,EACb,WAAW,EACX,mBAAmB,GACpB,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export { MocklyServer } from './server.js';
+export { install, getBinaryPath, DEFAULT_MOCKLY_VERSION } from './install.js';
+export { getFreePort } from './utils.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAE,OAAO,EAAE,aAAa,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAC7E,OAAO,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA"}

package/dist/install.d.ts

@@ -0,0 +1,55 @@
+/** Version of the Mockly binary this package was tested against. */
+export declare const DEFAULT_MOCKLY_VERSION = "v0.1.0";
+export interface InstallOptions {
+    /**
+     * Mockly version to install.
+     * @default process.env.MOCKLY_VERSION ?? DEFAULT_MOCKLY_VERSION
+     */
+    version?: string;
+    /**
+     * Base URL for downloading release assets.
+     *
+     * Override this to route downloads through Artifactory or an internal mirror:
+     * ```
+     * MOCKLY_DOWNLOAD_BASE_URL=https://artifactory.company.com/artifactory/github-releases/dever-labs/mockly/releases/download
+     * ```
+     * The full download URL becomes `${baseUrl}/${version}/${assetName}`.
+     *
+     * @default process.env.MOCKLY_DOWNLOAD_BASE_URL ?? GitHub releases URL
+     */
+    baseUrl?: string;
+    /**
+     * Directory to place the downloaded binary.
+     * @default path.join(process.cwd(), 'bin')
+     */
+    binDir?: string;
+    /**
+     * Re-download even if the binary already exists.
+     * @default false
+     */
+    force?: boolean;
+}
+/**
+ * Returns the path to the installed binary, or `null` if not found.
+ *
+ * Resolution order:
+ * 1. `MOCKLY_BINARY_PATH` env var (absolute path to pre-staged binary)
+ * 2. `<binDir>/mockly[.exe]` (downloaded by `install()`)
+ * 3. `<cwd>/node_modules/.bin/mockly[.exe]` (future: native npm wrapper)
+ */
+export declare function getBinaryPath(binDir?: string): string | null;
+/**
+ * Downloads (or locates) the Mockly binary and returns its path.
+ *
+ * Environment variables (all optional):
+ * - `MOCKLY_BINARY_PATH`       — use this exact binary; skips all download logic
+ * - `MOCKLY_NO_INSTALL`        — throw instead of downloading (for air-gapped envs
+ *                                 where the binary is staged externally)
+ * - `MOCKLY_DOWNLOAD_BASE_URL` — base URL override for Artifactory / internal mirrors
+ * - `MOCKLY_VERSION`           — binary version override
+ * - `HTTPS_PROXY` / `HTTP_PROXY` — route the download through an HTTP proxy
+ *
+ * @returns Absolute path to the installed binary.
+ */
+export declare function install(opts?: InstallOptions): Promise<string>;
+//# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAOA,oEAAoE;AACpE,eAAO,MAAM,sBAAsB,WAAW,CAAA;AAK9C,MAAM,WAAW,cAAc;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAEhB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;IAEf;;;OAGG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAoB5D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAsB,OAAO,CAAC,IAAI,GAAE,cAAmB,GAAG,OAAO,CAAC,MAAM,CAAC,CAyDxE"}

package/dist/install.js

@@ -0,0 +1,244 @@
+import http from 'http';
+import https from 'https';
+import tls from 'tls';
+import { createWriteStream, existsSync, mkdirSync, chmodSync } from 'fs';
+import { join, resolve, dirname } from 'path';
+import { createRequire } from 'module';
+/** Version of the Mockly binary this package was tested against. */
+export const DEFAULT_MOCKLY_VERSION = 'v0.1.0';
+/** Default GitHub releases base URL. */
+const GITHUB_BASE = 'https://github.com/dever-labs/mockly/releases/download';
+/**
+ * Returns the path to the installed binary, or `null` if not found.
+ *
+ * Resolution order:
+ * 1. `MOCKLY_BINARY_PATH` env var (absolute path to pre-staged binary)
+ * 2. `<binDir>/mockly[.exe]` (downloaded by `install()`)
+ * 3. `<cwd>/node_modules/.bin/mockly[.exe]` (future: native npm wrapper)
+ */
+export function getBinaryPath(binDir) {
+    const ext = process.platform === 'win32' ? '.exe' : '';
+    if (process.env.MOCKLY_BINARY_PATH) {
+        const p = resolve(process.env.MOCKLY_BINARY_PATH);
+        if (existsSync(p))
+            return p;
+    }
+    // Bundled binary from platform sub-package (installed via optionalDependencies).
+    const bundled = getBundledBinaryPath(ext);
+    if (bundled)
+        return bundled;
+    const dir = binDir ?? join(process.cwd(), 'bin');
+    const fromBinDir = join(dir, `mockly${ext}`);
+    if (existsSync(fromBinDir))
+        return fromBinDir;
+    const fromModules = resolve(process.cwd(), 'node_modules', '.bin', `mockly${ext}`);
+    if (existsSync(fromModules))
+        return fromModules;
+    return null;
+}
+/**
+ * Downloads (or locates) the Mockly binary and returns its path.
+ *
+ * Environment variables (all optional):
+ * - `MOCKLY_BINARY_PATH`       — use this exact binary; skips all download logic
+ * - `MOCKLY_NO_INSTALL`        — throw instead of downloading (for air-gapped envs
+ *                                 where the binary is staged externally)
+ * - `MOCKLY_DOWNLOAD_BASE_URL` — base URL override for Artifactory / internal mirrors
+ * - `MOCKLY_VERSION`           — binary version override
+ * - `HTTPS_PROXY` / `HTTP_PROXY` — route the download through an HTTP proxy
+ *
+ * @returns Absolute path to the installed binary.
+ */
+export async function install(opts = {}) {
+    const ext = process.platform === 'win32' ? '.exe' : '';
+    const binDir = opts.binDir ?? join(process.cwd(), 'bin');
+    const binPath = join(binDir, `mockly${ext}`);
+    // 1. MOCKLY_BINARY_PATH — use a pre-staged binary without downloading
+    if (process.env.MOCKLY_BINARY_PATH) {
+        const staged = resolve(process.env.MOCKLY_BINARY_PATH);
+        if (!existsSync(staged)) {
+            throw new Error(`MOCKLY_BINARY_PATH is set to "${staged}" but the file does not exist.\n` +
+                `Stage the binary for platform "${process.platform}/${process.arch}" before running tests.`);
+        }
+        return staged;
+    }
+    // 2. Bundled binary via optionalDependencies — no download needed.
+    const bundled = getBundledBinaryPath(ext);
+    if (bundled && !opts.force)
+        return bundled;
+    // 3. Already installed — skip unless force
+    if (!opts.force && existsSync(binPath)) {
+        return binPath;
+    }
+    // 4. MOCKLY_NO_INSTALL — fail fast with actionable instructions
+    if (process.env.MOCKLY_NO_INSTALL) {
+        throw new Error(`MOCKLY_NO_INSTALL is set but no Mockly binary was found.\n\n` +
+            `To resolve this, choose one of:\n` +
+            `  a) Stage the binary manually:\n` +
+            `       Place the binary at: ${binPath}\n` +
+            `       Download from: https://github.com/dever-labs/mockly/releases\n\n` +
+            `  b) Set MOCKLY_BINARY_PATH to the absolute path of an existing binary.\n\n` +
+            `  c) Use MOCKLY_DOWNLOAD_BASE_URL to point to an internal mirror:\n` +
+            `       MOCKLY_DOWNLOAD_BASE_URL=https://artifactory.company.com/artifactory/github-releases/dever-labs/mockly/releases/download`);
+    }
+    // 5. Download
+    const version = opts.version ?? process.env.MOCKLY_VERSION ?? DEFAULT_MOCKLY_VERSION;
+    const baseUrl = opts.baseUrl ?? process.env.MOCKLY_DOWNLOAD_BASE_URL ?? GITHUB_BASE;
+    const asset = getAssetName();
+    const url = `${baseUrl}/${version}/${asset}`;
+    mkdirSync(binDir, { recursive: true });
+    console.log(`mockly-node: downloading ${asset} from ${url}`);
+    await downloadFile(url, binPath);
+    if (process.platform !== 'win32') {
+        chmodSync(binPath, 0o755);
+    }
+    console.log(`mockly-node: installed at ${binPath}`);
+    return binPath;
+}
+/** Maps `${process.platform}-${process.arch}` to the platform sub-package name. */
+const PLATFORM_PACKAGES = {
+    'linux-x64': '@dever-labs/mockly-driver-linux-x64',
+    'linux-arm64': '@dever-labs/mockly-driver-linux-arm64',
+    'darwin-x64': '@dever-labs/mockly-driver-darwin-x64',
+    'darwin-arm64': '@dever-labs/mockly-driver-darwin-arm64',
+    'win32-x64': '@dever-labs/mockly-driver-win32-x64',
+};
+/**
+ * Tries to find the mockly binary bundled in the matching platform sub-package.
+ * Returns the path if found, null otherwise.
+ */
+function getBundledBinaryPath(ext) {
+    const platformKey = `${process.platform}-${process.arch}`;
+    const pkgName = PLATFORM_PACKAGES[platformKey];
+    if (!pkgName)
+        return null;
+    try {
+        const req = createRequire(import.meta.url);
+        const pkgJsonPath = req.resolve(`${pkgName}/package.json`);
+        const candidate = join(dirname(pkgJsonPath), 'bin', `mockly${ext}`);
+        if (existsSync(candidate))
+            return candidate;
+    }
+    catch {
+        // optional dep not installed — fall through to download
+    }
+    return null;
+}
+const ARCH_MAP = {
+    x64: 'amd64',
+    arm64: 'arm64',
+};
+function getAssetName() {
+    const os = process.platform === 'win32' ? 'windows'
+        : process.platform === 'darwin' ? 'darwin'
+            : 'linux';
+    const arch = ARCH_MAP[process.arch];
+    if (!arch) {
+        throw new Error(`Unsupported architecture: ${process.arch}.\n` +
+            `Supported: x64 (amd64), arm64.\n` +
+            `For other platforms, build from source: https://github.com/dever-labs/mockly`);
+    }
+    return `mockly-${os}-${arch}${process.platform === 'win32' ? '.exe' : ''}`;
+}
+// ─── Download ─────────────────────────────────────────────────────────────────
+function getProxyUrl() {
+    return (process.env.HTTPS_PROXY ??
+        process.env.https_proxy ??
+        process.env.npm_config_https_proxy ??
+        process.env.HTTP_PROXY ??
+        process.env.http_proxy ??
+        process.env.npm_config_proxy);
+}
+function downloadFile(url, dest) {
+    const proxyUrl = getProxyUrl();
+    return proxyUrl ? downloadViaProxy(url, dest, proxyUrl) : downloadDirect(url, dest);
+}
+function downloadDirect(url, dest) {
+    return new Promise((resolve, reject) => {
+        const get = (u) => {
+            https.get(u, { headers: { 'User-Agent': 'mockly-install' } }, (res) => {
+                if (res.statusCode === 301 || res.statusCode === 302) {
+                    if (!res.headers.location) {
+                        reject(new Error(`HTTP ${res.statusCode} from ${u} — redirect with no Location header`));
+                        return;
+                    }
+                    get(res.headers.location);
+                    return;
+                }
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode} from ${u}`));
+                    return;
+                }
+                const ws = createWriteStream(dest);
+                res.pipe(ws);
+                ws.on('finish', resolve);
+                ws.on('error', reject);
+            }).on('error', reject);
+        };
+        get(url);
+    });
+}
+/**
+ * Downloads via HTTP CONNECT proxy (for environments where HTTPS_PROXY /
+ * HTTP_PROXY is set but MOCKLY_DOWNLOAD_BASE_URL cannot be used).
+ *
+ * For Artifactory, prefer setting MOCKLY_DOWNLOAD_BASE_URL instead — it is
+ * simpler and avoids CONNECT tunnel complexity.
+ */
+function downloadViaProxy(targetUrl, dest, proxyUrl) {
+    return new Promise((resolve, reject) => {
+        const target = new URL(targetUrl);
+        const proxy = new URL(proxyUrl);
+        const connectOpts = {
+            host: proxy.hostname,
+            port: parseInt(proxy.port) || 3128,
+            method: 'CONNECT',
+            path: `${target.hostname}:443`,
+            headers: {},
+        };
+        if (proxy.username) {
+            const password = proxy.password || '';
+            const auth = Buffer.from(`${decodeURIComponent(proxy.username)}:${decodeURIComponent(password)}`).toString('base64');
+            connectOpts.headers['Proxy-Authorization'] = `Basic ${auth}`;
+        }
+        const connectReq = http.request(connectOpts);
+        connectReq.on('connect', (_res, socket) => {
+            // Wrap the plain socket in TLS to complete the HTTPS tunnel
+            const tlsSocket = tls.connect({ socket, servername: target.hostname });
+            const req = https.request({
+                createConnection: () => tlsSocket,
+                hostname: target.hostname,
+                path: target.pathname + target.search,
+                method: 'GET',
+                headers: { 'User-Agent': 'mockly-install' },
+            }, (res) => {
+                if (res.statusCode === 301 || res.statusCode === 302) {
+                    if (!res.headers.location) {
+                        tlsSocket.destroy();
+                        reject(new Error(`HTTP ${res.statusCode} from ${targetUrl} — redirect with no Location header`));
+                        return;
+                    }
+                    tlsSocket.destroy();
+                    downloadViaProxy(res.headers.location, dest, proxyUrl).then(resolve).catch(reject);
+                    return;
+                }
+                if (res.statusCode !== 200) {
+                    reject(new Error(`HTTP ${res.statusCode} from ${targetUrl} (via proxy ${proxyUrl})`));
+                    return;
+                }
+                const ws = createWriteStream(dest);
+                res.pipe(ws);
+                ws.on('finish', resolve);
+                ws.on('error', (err) => {
+                    tlsSocket.destroy();
+                    reject(err);
+                });
+            });
+            req.on('error', reject);
+            req.end();
+        });
+        connectReq.on('error', reject);
+        connectReq.end();
+    });
+}
+//# sourceMappingURL=install.js.map

package/dist/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"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"}

package/dist/server.d.ts

@@ -0,0 +1,90 @@
+import type { HttpMock, FaultConfig, MocklyServerOptions } from './types.js';
+import type { InstallOptions } from './install.js';
+/**
+ * Controls a Mockly server process for use in integration tests.
+ *
+ * @example
+ * ```ts
+ * // Recommended: ensure binary is installed, then start
+ * const server = await MocklyServer.ensure()
+ *
+ * await server.addMock({
+ *   id: 'get-users',
+ *   request: { method: 'GET', path: '/users' },
+ *   response: { status: 200, body: '[{"id":1}]', headers: { 'Content-Type': 'application/json' } },
+ * })
+ *
+ * // Point your HTTP client at server.httpBase
+ * const res = await fetch(`${server.httpBase}/users`)
+ *
+ * await server.stop()
+ * ```
+ */
+export declare class MocklyServer {
+    readonly httpPort: number;
+    readonly apiPort: number;
+    private proc;
+    private constructor();
+    /** Base URL of the HTTP mock server — e.g. `http://127.0.0.1:45123` */
+    get httpBase(): string;
+    /** Base URL of the management API — e.g. `http://127.0.0.1:45124` */
+    get apiBase(): string;
+    /**
+     * Installs the Mockly binary if it is not already present, then starts the
+     * server. This is the recommended entry point for most test setups.
+     *
+     * Respects all `InstallOptions` and their corresponding environment
+     * variables — see {@link install} for details.
+     */
+    static ensure(opts?: MocklyServerOptions & InstallOptions): Promise<MocklyServer>;
+    /**
+     * Starts the server using an already-installed binary.
+     * Throws immediately if the binary cannot be found — call `ensure()` instead
+     * if you want automatic installation.
+     *
+     * Ports are allocated atomically (both held open simultaneously) to avoid
+     * TOCTOU races where another process could claim a port between allocations.
+     * If startup fails due to a port conflict, create() retries up to 3 times
+     * with freshly allocated ports before giving up.
+     */
+    static create(opts?: MocklyServerOptions): Promise<MocklyServer>;
+    /** Kills the Mockly process and waits for it to exit. */
+    stop(): Promise<void>;
+    /**
+     * Registers a new HTTP mock via the management API.
+     * Mocks are matched in insertion order — the first match wins.
+     *
+     * **Header matching** uses exact string comparison.
+     * Place more-specific mocks (with header requirements) before less-specific
+     * fallbacks to ensure correct priority.
+     */
+    addMock(mock: HttpMock): Promise<void>;
+    /** Removes a mock by id. */
+    deleteMock(id: string): Promise<void>;
+    /**
+     * Activates a named scenario, patching the responses of referenced mocks.
+     * The scenario must have been declared in `MocklyServerOptions.scenarios`.
+     */
+    activateScenario(id: string): Promise<void>;
+    /** Deactivates a previously activated scenario. */
+    deactivateScenario(id: string): Promise<void>;
+    /**
+     * Enables global fault injection.
+     * Faults apply to every request regardless of mock matching.
+     */
+    setFault(config: FaultConfig): Promise<void>;
+    /** Disables all active fault injection. */
+    clearFault(): Promise<void>;
+    /**
+     * Resets all state: removes dynamically added mocks, deactivates scenarios,
+     * and clears fault injection. Mocks from the startup config are preserved.
+     *
+     * Call this in `beforeEach` to keep tests isolated.
+     */
+    reset(): Promise<void>;
+    private _start;
+    private _writeConfig;
+    private _waitReady;
+    private _post;
+}
+//# sourceMappingURL=server.d.ts.map

package/dist/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,QAAQ,EAAY,WAAW,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AACtF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAA;AAIlD;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,YAAY;IAIrB,QAAQ,CAAC,QAAQ,EAAE,MAAM;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM;IAJ1B,OAAO,CAAC,IAAI,CAA4B;IAExC,OAAO;IAKP,uEAAuE;IACvE,IAAI,QAAQ,IAAI,MAAM,CAA+C;IAErE,qEAAqE;IACrE,IAAI,OAAO,IAAI,MAAM,CAA8C;IAEnE;;;;;;OAMG;WACU,MAAM,CAAC,IAAI,GAAE,mBAAmB,GAAG,cAAmB,GAAG,OAAO,CAAC,YAAY,CAAC;IAO3F;;;;;;;;;OASG;WACU,MAAM,CAAC,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,YAAY,CAAC;IAwB1E,yDAAyD;IACnD,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IAU3B;;;;;;;OAOG;IACG,OAAO,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAK5C,4BAA4B;IACtB,UAAU,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C;;;OAGG;IACG,gBAAgB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKjD,mDAAmD;IAC7C,kBAAkB,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAKnD;;;OAGG;IACG,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC;IAKlD,2CAA2C;IACrC,UAAU,IAAI,OAAO,CAAC,IAAI,CAAC;IAIjC;;;;;OAKG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;YAMd,MAAM;IA2BpB,OAAO,CAAC,YAAY;YA4BN,UAAU;IAcxB,OAAO,CAAC,KAAK;CAOd"}

package/dist/server.js

@@ -0,0 +1,224 @@
+import { spawn } from 'child_process';
+import { writeFileSync, mkdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import yaml from 'js-yaml';
+import { install, getBinaryPath } from './install.js';
+import { getFreePorts, sleep } from './utils.js';
+/**
+ * Controls a Mockly server process for use in integration tests.
+ *
+ * @example
+ * ```ts
+ * // Recommended: ensure binary is installed, then start
+ * const server = await MocklyServer.ensure()
+ *
+ * await server.addMock({
+ *   id: 'get-users',
+ *   request: { method: 'GET', path: '/users' },
+ *   response: { status: 200, body: '[{"id":1}]', headers: { 'Content-Type': 'application/json' } },
+ * })
+ *
+ * // Point your HTTP client at server.httpBase
+ * const res = await fetch(`${server.httpBase}/users`)
+ *
+ * await server.stop()
+ * ```
+ */
+export class MocklyServer {
+    httpPort;
+    apiPort;
+    proc = null;
+    constructor(httpPort, apiPort) {
+        this.httpPort = httpPort;
+        this.apiPort = apiPort;
+    }
+    /** Base URL of the HTTP mock server — e.g. `http://127.0.0.1:45123` */
+    get httpBase() { return `http://127.0.0.1:${this.httpPort}`; }
+    /** Base URL of the management API — e.g. `http://127.0.0.1:45124` */
+    get apiBase() { return `http://127.0.0.1:${this.apiPort}`; }
+    /**
+     * Installs the Mockly binary if it is not already present, then starts the
+     * server. This is the recommended entry point for most test setups.
+     *
+     * Respects all `InstallOptions` and their corresponding environment
+     * variables — see {@link install} for details.
+     */
+    static async ensure(opts = {}) {
+        if (!getBinaryPath(opts.binDir)) {
+            await install(opts);
+        }
+        return MocklyServer.create(opts);
+    }
+    /**
+     * Starts the server using an already-installed binary.
+     * Throws immediately if the binary cannot be found — call `ensure()` instead
+     * if you want automatic installation.
+     *
+     * Ports are allocated atomically (both held open simultaneously) to avoid
+     * TOCTOU races where another process could claim a port between allocations.
+     * If startup fails due to a port conflict, create() retries up to 3 times
+     * with freshly allocated ports before giving up.
+     */
+    static async create(opts = {}) {
+        const MAX_ATTEMPTS = 3;
+        let lastError;
+        for (let attempt = 0; attempt < MAX_ATTEMPTS; attempt++) {
+            const [httpPort, apiPort] = await getFreePorts(2);
+            const server = new MocklyServer(httpPort, apiPort);
+            try {
+                await server._start(opts.scenarios ?? []);
+                return server;
+            }
+            catch (err) {
+                await server.stop();
+                const msg = err.message;
+                if (isPortConflict(msg) && attempt < MAX_ATTEMPTS - 1) {
+                    lastError = err;
+                    continue;
+                }
+                throw err;
+            }
+        }
+        throw lastError ?? new Error('Failed to start Mockly after multiple port allocation attempts');
+    }
+    /** Kills the Mockly process and waits for it to exit. */
+    async stop() {
+        if (this.proc) {
+            this.proc.kill();
+            await new Promise((r) => this.proc.once('exit', r));
+            this.proc = null;
+        }
+    }
+    // ── Management API ──────────────────────────────────────────────────────────
+    /**
+     * Registers a new HTTP mock via the management API.
+     * Mocks are matched in insertion order — the first match wins.
+     *
+     * **Header matching** uses exact string comparison.
+     * Place more-specific mocks (with header requirements) before less-specific
+     * fallbacks to ensure correct priority.
+     */
+    async addMock(mock) {
+        const res = await this._post('/api/mocks/http', mock);
+        if (!res.ok)
+            throw new Error(`addMock(${mock.id}) failed: HTTP ${res.status}`);
+    }
+    /** Removes a mock by id. */
+    async deleteMock(id) {
+        await fetch(`${this.apiBase}/api/mocks/http/${id}`, { method: 'DELETE' });
+    }
+    /**
+     * Activates a named scenario, patching the responses of referenced mocks.
+     * The scenario must have been declared in `MocklyServerOptions.scenarios`.
+     */
+    async activateScenario(id) {
+        const res = await this._post(`/api/scenarios/${id}/activate`, null);
+        if (!res.ok)
+            throw new Error(`activateScenario(${id}) failed: HTTP ${res.status}`);
+    }
+    /** Deactivates a previously activated scenario. */
+    async deactivateScenario(id) {
+        const res = await fetch(`${this.apiBase}/api/scenarios/${id}/activate`, { method: 'DELETE' });
+        if (!res.ok)
+            throw new Error(`deactivateScenario(${id}) failed: HTTP ${res.status}`);
+    }
+    /**
+     * Enables global fault injection.
+     * Faults apply to every request regardless of mock matching.
+     */
+    async setFault(config) {
+        const res = await this._post('/api/fault', config);
+        if (!res.ok)
+            throw new Error(`setFault failed: HTTP ${res.status}`);
+    }
+    /** Disables all active fault injection. */
+    async clearFault() {
+        await fetch(`${this.apiBase}/api/fault`, { method: 'DELETE' });
+    }
+    /**
+     * Resets all state: removes dynamically added mocks, deactivates scenarios,
+     * and clears fault injection. Mocks from the startup config are preserved.
+     *
+     * Call this in `beforeEach` to keep tests isolated.
+     */
+    async reset() {
+        await this._post('/api/reset', null);
+    }
+    // ── Private ─────────────────────────────────────────────────────────────────
+    async _start(scenarios) {
+        const bin = getBinaryPath();
+        if (!bin) {
+            throw new Error('Mockly binary not found. Use `MocklyServer.ensure()` instead of ' +
+                '`MocklyServer.create()` to install automatically, or call `install()` first.\n' +
+                'For pre-staged binaries set MOCKLY_BINARY_PATH to the absolute path.');
+        }
+        const cfgPath = this._writeConfig(scenarios);
+        let stderrOutput = '';
+        this.proc = spawn(bin, ['start', '--config', cfgPath, `--api-port=${this.apiPort}`], {
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        this.proc.stderr?.on('data', (chunk) => { stderrOutput += chunk.toString(); });
+        this.proc.on('error', (err) => { throw new Error(`mockly spawn error: ${err.message}`); });
+        try {
+            await this._waitReady();
+        }
+        catch (err) {
+            const detail = stderrOutput.trim() ? `\nMockly output:\n${stderrOutput.trim()}` : '';
+            throw new Error(`${err.message}${detail}`);
+        }
+    }
+    _writeConfig(scenarios) {
+        const dir = join(tmpdir(), `mockly-node-${Date.now()}`);
+        mkdirSync(dir, { recursive: true });
+        const cfgPath = join(dir, 'mockly.yaml');
+        const config = {
+            mockly: { api: { port: this.apiPort } },
+            protocols: { http: { enabled: true, port: this.httpPort } },
+        };
+        if (scenarios.length > 0) {
+            config.scenarios = scenarios.map((s) => ({
+                id: s.id,
+                name: s.name,
+                patches: s.patches.map((p) => {
+                    const patch = { mock_id: p.mock_id };
+                    if (p.status !== undefined)
+                        patch.status = p.status;
+                    if (p.body !== undefined)
+                        patch.body = p.body;
+                    if (p.delay !== undefined)
+                        patch.delay = p.delay;
+                    return patch;
+                }),
+            }));
+        }
+        writeFileSync(cfgPath, yaml.dump(config), 'utf-8');
+        return cfgPath;
+    }
+    async _waitReady(maxMs = 10_000) {
+        const deadline = Date.now() + maxMs;
+        while (Date.now() < deadline) {
+            try {
+                const res = await fetch(`${this.apiBase}/api/protocols`, {
+                    signal: AbortSignal.timeout(300),
+                });
+                if (res.ok)
+                    return;
+            }
+            catch { /* not ready yet */ }
+            await sleep(50);
+        }
+        throw new Error(`Mockly did not become ready on port ${this.apiPort} within ${maxMs}ms`);
+    }
+    _post(path, body) {
+        return fetch(`${this.apiBase}${path}`, {
+            method: 'POST',
+            headers: body !== null ? { 'Content-Type': 'application/json' } : {},
+            body: body !== null ? JSON.stringify(body) : undefined,
+        });
+    }
+}
+function isPortConflict(errorMessage) {
+    return /address already in use|EADDRINUSE|bind/i.test(errorMessage);
+}
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,54 @@
+/** Request matching criteria for an HTTP mock. */
+export interface MockRequest {
+    method: string;
+    path: string;
+    /** Exact header value matching — e.g. `{ Authorization: 'Bearer token123' }` */
+    headers?: Record<string, string>;
+}
+/** Response definition for an HTTP mock. */
+export interface MockResponse {
+    status: number;
+    body?: string;
+    headers?: Record<string, string>;
+    /** Artificial delay — e.g. `'100ms'`, `'1s'` */
+    delay?: string;
+}
+/** A full HTTP mock definition. */
+export interface HttpMock {
+    id: string;
+    request: MockRequest;
+    response: MockResponse;
+}
+/** A single patch applied when a scenario is activated. */
+export interface ScenarioPatch {
+    mock_id: string;
+    status?: number;
+    body?: string;
+    delay?: string;
+}
+/** A named scenario that patches one or more mock responses when activated. */
+export interface Scenario {
+    id: string;
+    name: string;
+    patches: ScenarioPatch[];
+}
+/** Global fault injection configuration. */
+export interface FaultConfig {
+    enabled: boolean;
+    /** Artificial delay added to every request — e.g. `'200ms'` */
+    delay?: string;
+    /** Override the HTTP status of every matched response */
+    status_override?: number;
+    /** Probability (0–1) that the override fires; 0 means always */
+    error_rate?: number;
+}
+/** Options accepted by `MocklyServer.create()`. */
+export interface MocklyServerOptions {
+    /**
+     * Scenarios to include in the startup config.
+     * Scenarios can only be activated/deactivated via the management API;
+     * they cannot be created dynamically after the server starts.
+     */
+    scenarios?: Scenario[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,gFAAgF;IAChF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CACjC;AAED,4CAA4C;AAC5C,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAChC,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,mCAAmC;AACnC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,WAAW,CAAA;IACpB,QAAQ,EAAE,YAAY,CAAA;CACvB;AAED,2DAA2D;AAC3D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,+EAA+E;AAC/E,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,aAAa,EAAE,CAAA;CACzB;AAED,4CAA4C;AAC5C,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAA;IAChB,+DAA+D;IAC/D,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,yDAAyD;IACzD,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,gEAAgE;IAChE,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,mDAAmD;AACnD,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;CACvB"}

package/dist/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/utils.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Returns a free TCP port on 127.0.0.1.
+ * Always allocate ports sequentially, never in parallel, to avoid TOCTOU
+ * races where two concurrent calls could receive the same port.
+ */
+export declare function getFreePort(): Promise<number>;
+/**
+ * Returns n free TCP ports allocated atomically: all sockets are held open
+ * simultaneously so the OS cannot reuse them for each other, then released
+ * together.  This avoids the race condition that arises from calling
+ * getFreePort() sequentially.
+ */
+export declare function getFreePorts(n: number): Promise<number[]>;
+export declare function sleep(ms: number): Promise<void>;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAEA;;;;GAIG;AACH,wBAAgB,WAAW,IAAI,OAAO,CAAC,MAAM,CAAC,CAQ7C;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBzD;AAED,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAE/C"}

package/dist/utils.js

@@ -0,0 +1,52 @@
+import net from 'net';
+/**
+ * Returns a free TCP port on 127.0.0.1.
+ * Always allocate ports sequentially, never in parallel, to avoid TOCTOU
+ * races where two concurrent calls could receive the same port.
+ */
+export function getFreePort() {
+    return new Promise((resolve) => {
+        const srv = net.createServer();
+        srv.listen(0, '127.0.0.1', () => {
+            const port = srv.address().port;
+            srv.close(() => resolve(port));
+        });
+    });
+}
+/**
+ * Returns n free TCP ports allocated atomically: all sockets are held open
+ * simultaneously so the OS cannot reuse them for each other, then released
+ * together.  This avoids the race condition that arises from calling
+ * getFreePort() sequentially.
+ */
+export function getFreePorts(n) {
+    return new Promise((resolve, reject) => {
+        const servers = [];
+        const ports = [];
+        let opened = 0;
+        for (let i = 0; i < n; i++) {
+            const srv = net.createServer();
+            servers.push(srv);
+            srv.listen(0, '127.0.0.1', () => {
+                ports.push(srv.address().port);
+                if (++opened === n) {
+                    let closed = 0;
+                    for (const s of servers) {
+                        s.close((err) => {
+                            if (err) {
+                                reject(err);
+                                return;
+                            }
+                            if (++closed === n)
+                                resolve(ports);
+                        });
+                    }
+                }
+            });
+        }
+    });
+}
+export function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=utils.js.map

package/dist/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,GAAG,MAAM,KAAK,CAAA;AAErB;;;;GAIG;AACH,MAAM,UAAU,WAAW;IACzB,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,EAAE,CAAA;QAC9B,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;YAC9B,MAAM,IAAI,GAAI,GAAG,CAAC,OAAO,EAAsB,CAAC,IAAI,CAAA;YACpD,GAAG,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;QAChC,CAAC,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,CAAS;IACpC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,MAAM,OAAO,GAAiB,EAAE,CAAA;QAChC,MAAM,KAAK,GAAa,EAAE,CAAA;QAC1B,IAAI,MAAM,GAAG,CAAC,CAAA;QAEd,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3B,MAAM,GAAG,GAAG,GAAG,CAAC,YAAY,EAAE,CAAA;YAC9B,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;YACjB,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;gBAC9B,KAAK,CAAC,IAAI,CAAE,GAAG,CAAC,OAAO,EAAsB,CAAC,IAAI,CAAC,CAAA;gBACnD,IAAI,EAAE,MAAM,KAAK,CAAC,EAAE,CAAC;oBACnB,IAAI,MAAM,GAAG,CAAC,CAAA;oBACd,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;wBACxB,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;4BACd,IAAI,GAAG,EAAE,CAAC;gCAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gCAAC,OAAM;4BAAC,CAAC;4BAChC,IAAI,EAAE,MAAM,KAAK,CAAC;gCAAE,OAAO,CAAC,KAAK,CAAC,CAAA;wBACpC,CAAC,CAAC,CAAA;oBACJ,CAAC;gBACH,CAAC;YACH,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC,CAAC,CAAA;AACJ,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,EAAU;IAC9B,OAAO,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;AAC9C,CAAC"}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@dever-labs/mockly-driver",
+  "version": "v0.4.6",
+  "description": "Node.js client for Mockly — start/stop servers and manage HTTP mocks in tests",
+  "keywords": [
+    "mock",
+    "testing",
+    "http",
+    "integration-test",
+    "mockly",
+    "test-server",
+    "driver"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dever-labs/mockly.git",
+    "directory": "clients/node"
+  },
+  "bugs": {
+    "url": "https://github.com/dever-labs/mockly/issues"
+  },
+  "homepage": "https://github.com/dever-labs/mockly/tree/main/clients/node#readme",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "bin": {
+    "mockly-install": "./bin/install.mjs"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "typecheck": "tsc --project tsconfig.json --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "js-yaml": "^4.1.0"
+  },
+  "optionalDependencies": {
+    "@dever-labs/mockly-driver-linux-x64": "v0.4.6",
+    "@dever-labs/mockly-driver-linux-arm64": "v0.4.6",
+    "@dever-labs/mockly-driver-darwin-x64": "v0.4.6",
+    "@dever-labs/mockly-driver-darwin-arm64": "v0.4.6",
+    "@dever-labs/mockly-driver-win32-x64": "v0.4.6"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.2"
+  }
+}