@scenarist/msw-adapter 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Paul Hammond (citypaul)
+
+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

@@ -1,45 +1,320 @@
 # @scenarist/msw-adapter
 
-## ⚠️ IMPORTANT NOTICE ⚠️
+**⚠️ INTERNAL PACKAGE - DO NOT INSTALL DIRECTLY**
 
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
+This package is an internal implementation detail of Scenarist and is **NOT published to npm**. It exists as a workspace dependency used by framework adapters.
 
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
+## Why is this package private?
 
-## Purpose
+**You should install a framework adapter instead:**
+- ✅ `@scenarist/express-adapter` - For Express applications
+- ✅ `@scenarist/nextjs-adapter` - For Next.js applications
+- ✅ `@scenarist/core` - For building custom adapters
 
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@scenarist/msw-adapter`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
+**This package is private because:**
 
-## What is OIDC Trusted Publishing?
+1. **Not user-facing** - Users never import from `@scenarist/msw-adapter` directly
+2. **Implementation detail** - Provides MSW integration layer used internally by framework adapters
+3. **Prevents confusion** - Publishing would mislead users into thinking they should install it
+4. **Version coupling** - Framework adapters control which msw-adapter version they use
+5. **Simpler maintenance** - Internal packages don't need semver/breaking change coordination
+6. **Cleaner API surface** - Framework adapters ARE the public API, msw-adapter is hidden complexity
 
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
+**Dependency structure:**
+```
+Your App
+  ├─ @scenarist/express-adapter (public, install this!)
+  │   └─ @scenarist/msw-adapter (private, workspace:*)
+  │       └─ @scenarist/core (public)
+  │
+  └─ @scenarist/nextjs-adapter (public, install this!)
+      └─ @scenarist/msw-adapter (private, workspace:*)
+          └─ @scenarist/core (public)
+```
 
-## Setup Instructions
+---
+
+## What is Scenarist?
 
-To properly configure OIDC trusted publishing for this package:
+**Scenarist** enables concurrent E2E tests to run with different backend states by switching mock scenarios at runtime via test IDs. This package provides the MSW integration layer that makes it all work.
 
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
+**The big picture:**
 
-## DO NOT USE THIS PACKAGE
+```
+Your App → Scenarist Adapter (Express/Next.js) → MSW Adapter → MSW → Intercepted HTTP
+```
 
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
+**What this package does:**
 
-## More Information
+Converts Scenarist's serializable `ScenaristMock` data into MSW `HttpHandler` instances at runtime, enabling Scenarist to work with any Node.js framework.
 
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
+**Status:** ✅ Stable - Used internally by all Scenarist framework adapters
 
 ---
 
-**Maintained for OIDC setup purposes only**
+## For Framework Adapter Developers
+
+If you're building a custom framework adapter for Scenarist, this package provides the MSW integration you need. Otherwise, you should use one of the existing public adapters listed above.
+
+## What does this package provide?
+
+The MSW adapter is the bridge between Scenarist's serializable mock definitions and MSW's HTTP interception. It provides:
+
+1. **URL Matching** - Converts URL patterns (with wildcards and path params) into MSW-compatible matchers
+2. **Mock Matching** - Finds the right mock definition for incoming requests (with request content matching)
+3. **Response Building** - Transforms `ScenaristMock` into MSW `HttpResponse`
+4. **Dynamic Handler** - Creates a single MSW handler that routes based on active scenarios
+
+## Core Capabilities
+
+This adapter implements all 25 Scenarist capabilities:
+
+### Request Matching (6 capabilities)
+- **Body matching** (partial match) - Match on request body fields
+- **Header matching** (exact, case-insensitive) - Match on header values
+- **Query matching** (exact) - Match on query parameters
+- **Combined matching** - Combine body + headers + query
+- **Specificity-based selection** - Most specific mock wins
+- **Fallback mocks** - Mocks without criteria act as catch-all
+
+### Response Sequences (4 capabilities)
+- **Single responses** - Return same response every time
+- **Response sequences** - Ordered responses for polling scenarios
+- **Repeat modes** - `last`, `cycle`, `none` behaviors
+- **Sequence exhaustion** - Skip exhausted sequences to fallback
+
+### Stateful Mocks (6 capabilities)
+- **State capture** - Extract values from requests
+- **State injection** - Inject state into responses via templates
+- **Array append** - Syntax: `stateKey[]` for arrays
+- **Nested paths** - Dot notation: `user.profile.name`
+- **State isolation** - Per test ID isolation
+- **State reset** - Fresh state on scenario switch
+
+### URL Patterns (4 capabilities)
+- **Exact matches** - `https://api.example.com/users`
+- **Wildcards** - `*/api/*`, `https://*/users`
+- **Path parameters** - `/users/:id`, `/posts/:postId/comments/:commentId`
+- **Native RegExp** - `/\/api\/v\d+\//`, `/\/users\/\d+$/` (weak comparison per MSW behavior)
+
+### MSW Integration (6 capabilities)
+- **Dynamic handler generation** - Single handler routes at runtime
+- **Response building** - Status codes, JSON bodies, headers, delays
+- **Automatic default fallback** - Collects default + active scenario mocks together
+- **Strict mode** - Fail on unmocked requests
+- **Test ID isolation** - Separate state per test ID
+- **Framework-agnostic** - Works with any Node.js framework
+
+## Features
+
+- ✅ **URL pattern matching** - Exact matches, glob patterns (`*/api/*`), path parameters (`/users/:id`)
+- ✅ **Request content matching** - Body, headers, query with specificity-based selection
+- ✅ **Dynamic MSW handler generation** - Single handler routes to correct scenario at runtime
+- ✅ **Response building** - Status codes, JSON bodies, headers, delays, state injection
+- ✅ **Sequences and state** - Polling scenarios and stateful mocks fully supported
+- ✅ **Automatic default fallback** - Collects default + active scenario mocks, uses specificity to select best match
+- ✅ **Framework-agnostic** - Works with Express, Next.js, and any Node.js framework via HTTP-level interception
+
+## Internal Package
+
+⚠️ **This is an internal package used by framework adapters.**
+
+You typically don't install or use this directly. Instead, use a framework-specific adapter:
+
+- **[@scenarist/express-adapter](../../packages/express-adapter)** - For Express applications
+- **[@scenarist/nextjs-adapter](../../packages/nextjs-adapter)** - For Next.js applications (App Router + Pages Router)
+
+## How It Works
+
+### 1. URL Matching
+
+Converts string patterns into MSW-compatible URL matchers:
+
+```typescript
+import { matchesUrl } from '@scenarist/msw-adapter';
+
+matchesUrl('https://api.github.com/users/octocat', 'GET', 'https://api.github.com/users/:username');
+// Returns: { matches: true, params: { username: 'octocat' } }
+
+matchesUrl('https://api.stripe.com/v1/charges', 'POST', '*/v1/charges');
+// Returns: { matches: true, params: {} }
+```
+
+**Supported patterns (three types with different hostname matching):**
+
+**1. Pathname-only patterns** (origin-agnostic - match ANY hostname)
+- Path params: `/users/:id`, `/posts/:postId/comments/:commentId`
+- Exact: `/api/users`
+- Wildcards: `/api/*`, `*/users/*`
+
+**2. Full URL patterns** (hostname-specific - match ONLY specified hostname)
+- Exact: `https://api.example.com/users`
+- Path params: `https://api.example.com/users/:id`
+- Wildcards: `https://*/users`, `https://api.example.com/*`
+
+**3. Native RegExp** (origin-agnostic - MSW weak comparison)
+- `/\/api\/v\d+\//` (matches /api/v1/, /api/v2/, etc.)
+- `/\/users\/\d+$/` (matches /users/123 at any origin)
+
+**IMPORTANT:** If you specify a hostname in a full URL pattern, it WILL be matched. Choose pathname patterns for environment-agnostic mocks, full URL patterns when hostname matters.
+
+### 2. Mock Matching
+
+Finds the right mock for a request:
+
+```typescript
+import { findMatchingMock } from '@scenarist/msw-adapter';
+
+const mocks: ScenaristMock[] = [
+  { method: 'GET', url: '/users/:id', response: { status: 200, body: {...} } },
+  { method: 'POST', url: '/users', response: { status: 201, body: {...} } },
+];
+
+const mock = findMatchingMock(mocks, 'GET', 'https://api.example.com/users/123');
+// Returns the first mock (matches /users/:id)
+```
+
+### 3. Response Building
+
+Converts `ScenaristMock` to MSW `HttpResponse`:
+
+```typescript
+import { buildResponse } from '@scenarist/msw-adapter';
+
+const mockDef: ScenaristMock = {
+  method: 'GET',
+  url: '/api/user',
+  response: {
+    status: 200,
+    body: { id: '123', name: 'John' },
+    headers: { 'X-Custom': 'value' },
+    delay: 100,
+  },
+};
+
+const response = await buildResponse(mockDef);
+// Returns MSW HttpResponse with status, body, headers, and delay
+```
+
+### 4. Dynamic Handler
+
+The core integration - a single MSW handler that routes dynamically:
+
+```typescript
+import { createDynamicHandler } from '@scenarist/msw-adapter';
+import { setupServer } from 'msw/node';
+
+const handler = createDynamicHandler({
+  getTestId: () => testIdStorage.getStore() ?? 'default-test',
+  getActiveScenario: (testId) => manager.getActiveScenario(testId),
+  getScenarioDefinition: (scenarioId) => manager.getScenarioById(scenarioId),
+  strictMode: false,
+});
+
+const server = setupServer(handler);
+server.listen();
+```
+
+**How it works:**
+1. Gets test ID from AsyncLocalStorage (or other context)
+2. Looks up active scenario for that test ID
+3. **Collects mocks from BOTH default AND active scenario** for matching URL + method
+4. Uses specificity-based selection to choose best match
+5. Active scenario mocks (with match criteria) override default mocks (no criteria)
+6. Returns mocked response or passthrough (if no match found)
+
+**Key insight:** Default scenario mocks are ALWAYS collected first, then active scenario mocks are added. The specificity algorithm (from `ResponseSelector`) chooses the most specific match. This means specialized scenarios only need to define what changes - everything else automatically falls back to default.
+
+## Architecture
+
+This package is designed to be framework-agnostic. Framework adapters (Express, Next.js, etc.) handle:
+
+- Test ID extraction (from headers, context, etc.)
+- Scenario management (switching, retrieving)
+- Middleware integration
+
+The MSW adapter handles:
+
+- URL matching and pattern conversion
+- Mock finding and selection
+- Response building
+- MSW handler creation
+
+## API Reference
+
+### URL Matching
+
+```typescript
+export const matchesUrl = (
+  requestUrl: string,
+  method: string,
+  pattern: string
+): { matches: boolean; params: Record<string, string> };
+```
+
+### Mock Matching
+
+```typescript
+export const findMatchingMock = (
+  mocks: ReadonlyArray<ScenaristMock>,
+  method: string,
+  url: string
+): ScenaristMock | undefined;
+```
+
+### Response Building
+
+```typescript
+export const buildResponse = (
+  mockDef: ScenaristMock
+): Promise<HttpResponse>;
+```
+
+### Dynamic Handler
+
+```typescript
+export type DynamicHandlerOptions = {
+  readonly getTestId: () => string;
+  readonly getActiveScenario: (testId: string) => ActiveScenario | undefined;
+  readonly getScenarioDefinition: (scenarioId: string) => ScenaristScenario | undefined;
+  readonly strictMode: boolean;
+};
+
+export const createDynamicHandler = (
+  options: DynamicHandlerOptions
+): HttpHandler;
+```
+
+## TypeScript
+
+Full TypeScript support with strict mode enabled.
+
+**Exported types:**
+```typescript
+import type {
+  DynamicHandlerOptions,
+} from '@scenarist/msw-adapter';
+```
+
+## Testing
+
+This package has comprehensive test coverage:
+
+- ✅ URL matching (exact, glob, path params)
+- ✅ Mock matching (method, URL, precedence)
+- ✅ Response building (status, body, headers, delays)
+- ✅ Dynamic handler (scenarios, fallback, strict mode)
+- ✅ **31 tests passing**
+
+## Contributing
+
+See [CONTRIBUTING.md](../../CONTRIBUTING.md) for development guidelines.
+
+## License
+
+MIT
+
+## Related Packages
+
+- **[@scenarist/core](../core)** - Core scenario management
+- **[@scenarist/express-adapter](../express-adapter)** - Express integration (uses this package)

package/dist/conversion/response-builder.d.ts

@@ -0,0 +1,3 @@
+import type { ScenaristResponse } from '@scenarist/core';
+export declare const buildResponse: (response: ScenaristResponse) => Promise<Response>;
+//# sourceMappingURL=response-builder.d.ts.map

package/dist/conversion/response-builder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-builder.d.ts","sourceRoot":"","sources":["../../src/conversion/response-builder.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,eAAO,MAAM,aAAa,GACxB,UAAU,iBAAiB,KAC1B,OAAO,CAAC,QAAQ,CAclB,CAAC"}

package/dist/conversion/response-builder.js

@@ -0,0 +1,15 @@
+import { HttpResponse, delay } from 'msw';
+export const buildResponse = async (response) => {
+    if (response.delay) {
+        await delay(response.delay);
+    }
+    // Type assertion required: MSW's HttpResponse.json() expects JsonBodyType,
+    // but ScenaristResponse.body is typed as 'unknown' to maintain
+    // framework-agnostic serialization in core package. The body is guaranteed
+    // to be JSON-serializable by ScenaristResponse design contract. We do not
+    // perform runtime validation for performance reasons (garbage in, garbage out).
+    return HttpResponse.json(response.body, {
+        status: response.status,
+        headers: response.headers,
+    });
+};

package/dist/handlers/dynamic-handler.d.ts

@@ -0,0 +1,11 @@
+import type { HttpHandler } from 'msw';
+import type { ActiveScenario, ScenaristScenario, ResponseSelector } from '@scenarist/core';
+export type DynamicHandlerOptions = {
+    readonly getTestId: (request: Request) => string;
+    readonly getActiveScenario: (testId: string) => ActiveScenario | undefined;
+    readonly getScenarioDefinition: (scenarioId: string) => ScenaristScenario | undefined;
+    readonly strictMode: boolean;
+    readonly responseSelector: ResponseSelector;
+};
+export declare const createDynamicHandler: (options: DynamicHandlerOptions) => HttpHandler;
+//# sourceMappingURL=dynamic-handler.d.ts.map

package/dist/handlers/dynamic-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dynamic-handler.d.ts","sourceRoot":"","sources":["../../src/handlers/dynamic-handler.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,KAAK,CAAC;AACvC,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAIjB,gBAAgB,EACjB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,qBAAqB,GAAG;IAClC,QAAQ,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,MAAM,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,cAAc,GAAG,SAAS,CAAC;IAC3E,QAAQ,CAAC,qBAAqB,EAAE,CAC9B,UAAU,EAAE,MAAM,KACf,iBAAiB,GAAG,SAAS,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,gBAAgB,EAAE,gBAAgB,CAAC;CAC7C,CAAC;AAgGF,eAAO,MAAM,oBAAoB,GAC/B,SAAS,qBAAqB,KAC7B,WA8BF,CAAC"}

package/dist/handlers/dynamic-handler.js

@@ -0,0 +1,103 @@
+import { http, passthrough } from 'msw';
+import { buildResponse } from '../conversion/response-builder.js';
+import { matchesUrl } from '../matching/url-matcher.js';
+/**
+ * Extract HttpRequestContext from MSW Request object.
+ * Converts MSW request to the format expected by ResponseSelector.
+ */
+const extractHttpRequestContext = async (request) => {
+    // Parse request body if present
+    let body = undefined;
+    if (request.method !== 'GET' && request.method !== 'HEAD') {
+        try {
+            const clonedRequest = request.clone();
+            body = await clonedRequest.json();
+        }
+        catch {
+            // Body is not JSON or doesn't exist
+            body = undefined;
+        }
+    }
+    // Extract headers as Record<string, string>
+    // Headers are passed through as-is; normalization is core's responsibility.
+    // The Fetch API Headers object already normalizes keys to lowercase,
+    // but even if it didn't, core would handle normalization.
+    const headers = {};
+    request.headers.forEach((value, key) => {
+        headers[key] = value;
+    });
+    // Extract query parameters from URL
+    const url = new URL(request.url);
+    const query = {};
+    url.searchParams.forEach((value, key) => {
+        query[key] = value;
+    });
+    return {
+        method: request.method,
+        url: request.url,
+        body,
+        headers,
+        query,
+    };
+};
+/**
+ * Get mocks from active scenario, with default scenario mocks as fallback.
+ * Returns URL-matching mocks with their extracted params for ResponseSelector to evaluate.
+ *
+ * Default mocks are ALWAYS included (if they match URL+method).
+ * Active scenario mocks are added after defaults, allowing them to override
+ * based on specificity (mocks with match criteria have higher specificity).
+ *
+ * Each mock is paired with params extracted from its URL pattern.
+ * After ResponseSelector chooses a mock, we use THAT mock's params.
+ */
+const getMocksFromScenarios = (activeScenario, getScenarioDefinition, method, url) => {
+    const mocksWithParams = [];
+    // Step 1: ALWAYS include default scenario mocks first
+    // These act as fallback when active scenario mocks don't match
+    const defaultScenario = getScenarioDefinition('default');
+    if (defaultScenario) {
+        defaultScenario.mocks.forEach((mock) => {
+            const methodMatches = mock.method.toUpperCase() === method.toUpperCase();
+            const urlMatch = matchesUrl(mock.url, url);
+            if (methodMatches && urlMatch.matches) {
+                mocksWithParams.push({ mock, params: urlMatch.params });
+            }
+        });
+    }
+    // Step 2: Add active scenario mocks (if any)
+    // These override defaults based on specificity (via ResponseSelector)
+    if (activeScenario) {
+        const scenarioDefinition = getScenarioDefinition(activeScenario.scenarioId);
+        if (scenarioDefinition) {
+            scenarioDefinition.mocks.forEach((mock) => {
+                const methodMatches = mock.method.toUpperCase() === method.toUpperCase();
+                const urlMatch = matchesUrl(mock.url, url);
+                if (methodMatches && urlMatch.matches) {
+                    mocksWithParams.push({ mock, params: urlMatch.params });
+                }
+            });
+        }
+    }
+    return mocksWithParams;
+};
+export const createDynamicHandler = (options) => {
+    return http.all('*', async ({ request }) => {
+        const testId = options.getTestId(request);
+        const activeScenario = options.getActiveScenario(testId);
+        const scenarioId = activeScenario?.scenarioId ?? 'default';
+        // Extract request context for matching
+        const context = await extractHttpRequestContext(request);
+        // Get candidate mocks from active or default scenario
+        const mocks = getMocksFromScenarios(activeScenario, options.getScenarioDefinition, request.method, request.url);
+        // Use injected ResponseSelector to find matching mock
+        const result = options.responseSelector.selectResponse(testId, scenarioId, context, mocks);
+        if (result.success) {
+            return buildResponse(result.data);
+        }
+        if (options.strictMode) {
+            return new Response(null, { status: 501 });
+        }
+        return passthrough();
+    });
+};

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { matchesUrl } from './matching/url-matcher.js';
+export type { UrlMatchResult } from './matching/url-matcher.js';
+export { findMatchingMock } from './matching/mock-matcher.js';
+export { buildResponse } from './conversion/response-builder.js';
+export { createDynamicHandler } from './handlers/dynamic-handler.js';
+export type { DynamicHandlerOptions } from './handlers/dynamic-handler.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":"AAKA,OAAO,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvD,YAAY,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAEhE,OAAO,EAAE,gBAAgB,EAAE,MAAM,4BAA4B,CAAC;AAE9D,OAAO,EAAE,aAAa,EAAE,MAAM,kCAAkC,CAAC;AAEjE,OAAO,EAAE,oBAAoB,EAAE,MAAM,+BAA+B,CAAC;AACrE,YAAY,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC"}

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public API
+// These exports are primarily intended for use by Scenarist adapters
+// (e.g., express-adapter, fastify-adapter). End users should use the
+// higher-level adapter packages rather than these low-level utilities directly.
+export { matchesUrl } from './matching/url-matcher.js';
+export { findMatchingMock } from './matching/mock-matcher.js';
+export { buildResponse } from './conversion/response-builder.js';
+export { createDynamicHandler } from './handlers/dynamic-handler.js';

package/dist/matching/mock-matcher.d.ts

@@ -0,0 +1,3 @@
+import type { ScenaristMock } from '@scenarist/core';
+export declare const findMatchingMock: (mocks: ReadonlyArray<ScenaristMock>, method: string, url: string) => ScenaristMock | undefined;
+//# sourceMappingURL=mock-matcher.d.ts.map

package/dist/matching/mock-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mock-matcher.d.ts","sourceRoot":"","sources":["../../src/matching/mock-matcher.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAGrD,eAAO,MAAM,gBAAgB,GAC3B,OAAO,aAAa,CAAC,aAAa,CAAC,EACnC,QAAQ,MAAM,EACd,KAAK,MAAM,KACV,aAAa,GAAG,SAMlB,CAAC"}

package/dist/matching/mock-matcher.js

@@ -0,0 +1,8 @@
+import { matchesUrl } from './url-matcher.js';
+export const findMatchingMock = (mocks, method, url) => {
+    return mocks.find((mock) => {
+        const methodMatches = mock.method.toUpperCase() === method.toUpperCase();
+        const urlMatch = matchesUrl(mock.url, url);
+        return methodMatches && urlMatch.matches;
+    });
+};

package/dist/matching/url-matcher.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Result of URL matching with path parameter extraction.
+ *
+ * Matches MSW's documented param types:
+ * - string for simple params (:id)
+ * - string[] for repeating params (:path+)
+ */
+export type UrlMatchResult = {
+    readonly matches: boolean;
+    readonly params?: Readonly<Record<string, string | ReadonlyArray<string>>>;
+};
+/**
+ * Match URL patterns using MSW-compatible matching logic.
+ *
+ * Delegates to path-to-regexp v6 (same as MSW 2.x) for all string patterns.
+ * This ensures automatic MSW parity for path parameter extraction.
+ *
+ * Matching strategies:
+ * 1. RegExp patterns: MSW weak comparison (substring matching, origin-agnostic)
+ * 2. Pathname-only patterns: Origin-agnostic (match any hostname)
+ * 3. Full URL patterns: Hostname-specific (must match exactly)
+ *
+ * Pattern type examples:
+ * - Pathname: '/users/:id' matches 'http://localhost/users/123' AND 'https://api.com/users/123'
+ * - Full URL: 'http://api.com/users/:id' matches 'http://api.com/users/123' ONLY
+ *
+ * Path parameter examples (all handled by path-to-regexp):
+ * - Exact: '/users/123' matches '/users/123'
+ * - Simple params: '/users/:id' matches '/users/123' → {id: '123'}
+ * - Multiple params: '/users/:userId/posts/:postId' → {userId: 'alice', postId: '42'}
+ * - Optional params: '/files/:name?' matches '/files' or '/files/doc.txt'
+ * - Repeating params: '/files/:path+' matches '/files/a/b/c' → {path: ['a','b','c']}
+ * - Custom regex: '/orders/:id(\\d+)' matches '/orders/123' but not '/orders/abc'
+ *
+ * @see ADR-0016 for MSW weak comparison semantics
+ */
+export declare const matchesUrl: (pattern: string | RegExp, requestUrl: string) => UrlMatchResult;
+//# sourceMappingURL=url-matcher.d.ts.map

package/dist/matching/url-matcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"url-matcher.d.ts","sourceRoot":"","sources":["../../src/matching/url-matcher.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,MAAM,cAAc,GAAG;IAC3B,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;CAC5E,CAAC;AA8DF;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,UAAU,GACrB,SAAS,MAAM,GAAG,MAAM,EACxB,YAAY,MAAM,KACjB,cAuEF,CAAC"}

package/dist/matching/url-matcher.js

@@ -0,0 +1,142 @@
+import { match } from 'path-to-regexp';
+/**
+ * Extract pathname from URL string, or return as-is if not a valid URL.
+ *
+ * CRITICAL: Handles path-to-regexp syntax (`:param`, `?`, `+`, `(regex)`)
+ * The URL constructor treats `?` as query string delimiter, which breaks optional params.
+ *
+ * Examples:
+ * - 'http://localhost:3001/api/files/:filename?' → '/api/files/:filename?' (preserves ?)
+ * - 'http://localhost:3001/api/files/:path+' → '/api/files/:path+' (preserves +)
+ * - '/api/users/:id' → '/api/users/:id' (already pathname)
+ */
+const extractPathnameOrReturnAsIs = (url) => {
+    // Match protocol://host pattern to manually extract pathname
+    // This preserves path-to-regexp syntax that URL constructor would corrupt
+    const urlPattern = /^https?:\/\/[^/]+(\/.*)?$/;
+    const match = urlPattern.exec(url);
+    if (match) {
+        // Return everything after the host (group 1), or '/' if no path
+        return match[1] || '/';
+    }
+    // Not a full URL, return as-is (already a pathname)
+    return url;
+};
+/**
+ * Extract params from path-to-regexp match result, filtering unnamed groups.
+ *
+ * MSW behavior (via path-to-regexp v6):
+ * - Named params (:id, :name) are included
+ * - Array params (:path+, :path*) are included as arrays
+ * - Unnamed groups like (user|u) create numeric keys ('0', '1', etc.) which are FILTERED OUT
+ *
+ * Returns Record<string, string | string[]> matching MSW's documented types.
+ */
+const extractParams = (params) => {
+    return Object.fromEntries(Object.entries(params).filter(([key, value]) => {
+        // Filter out unnamed groups (numeric keys like '0', '1', '2', etc.)
+        if (/^\d+$/.test(key)) {
+            return false;
+        }
+        // Keep strings and arrays (MSW documented: string | string[])
+        return typeof value === 'string' || Array.isArray(value);
+    }));
+};
+/**
+ * Extract hostname from URL, or return undefined if not a full URL.
+ */
+const extractHostname = (url) => {
+    const urlPattern = /^https?:\/\/([^/]+)/;
+    const match = urlPattern.exec(url);
+    return match ? match[1] : undefined;
+};
+/**
+ * Match URL patterns using MSW-compatible matching logic.
+ *
+ * Delegates to path-to-regexp v6 (same as MSW 2.x) for all string patterns.
+ * This ensures automatic MSW parity for path parameter extraction.
+ *
+ * Matching strategies:
+ * 1. RegExp patterns: MSW weak comparison (substring matching, origin-agnostic)
+ * 2. Pathname-only patterns: Origin-agnostic (match any hostname)
+ * 3. Full URL patterns: Hostname-specific (must match exactly)
+ *
+ * Pattern type examples:
+ * - Pathname: '/users/:id' matches 'http://localhost/users/123' AND 'https://api.com/users/123'
+ * - Full URL: 'http://api.com/users/:id' matches 'http://api.com/users/123' ONLY
+ *
+ * Path parameter examples (all handled by path-to-regexp):
+ * - Exact: '/users/123' matches '/users/123'
+ * - Simple params: '/users/:id' matches '/users/123' → {id: '123'}
+ * - Multiple params: '/users/:userId/posts/:postId' → {userId: 'alice', postId: '42'}
+ * - Optional params: '/files/:name?' matches '/files' or '/files/doc.txt'
+ * - Repeating params: '/files/:path+' matches '/files/a/b/c' → {path: ['a','b','c']}
+ * - Custom regex: '/orders/:id(\\d+)' matches '/orders/123' but not '/orders/abc'
+ *
+ * @see ADR-0016 for MSW weak comparison semantics
+ */
+export const matchesUrl = (pattern, requestUrl) => {
+    /**
+     * RegExp patterns: MSW Weak Comparison (ADR-0016)
+     *
+     * RegExp.test() performs substring matching (origin-agnostic).
+     * This matches MSW's documented behavior for regular expressions.
+     *
+     * Example: /\/posts\// matches:
+     * - 'http://localhost:8080/posts/' ✅
+     * - 'https://backend.dev/user/posts/' ✅
+     * - 'https://api.example.com/posts/123' ✅
+     */
+    if (pattern instanceof RegExp) {
+        return { matches: pattern.test(requestUrl) };
+    }
+    /**
+     * String patterns: Hostname-aware matching
+     *
+     * If pattern is a full URL (has hostname), hostname must match.
+     * If pattern is pathname-only, any hostname matches (origin-agnostic).
+     *
+     * This gives users choice:
+     * - Use pathname patterns for environment-agnostic mocks
+     * - Use full URL patterns when hostname matters
+     */
+    const patternHostname = extractHostname(pattern);
+    const requestHostname = extractHostname(requestUrl);
+    // If pattern has hostname, it must match request hostname
+    if (patternHostname !== undefined && requestHostname !== undefined) {
+        if (patternHostname !== requestHostname) {
+            return { matches: false };
+        }
+    }
+    /**
+     * Pathname matching using path-to-regexp v6 (same as MSW 2.x)
+     *
+     * path-to-regexp handles:
+     * - Exact string matches
+     * - Path parameters (:id, :name, etc.)
+     * - Optional parameters (:id?)
+     * - Repeating parameters (:path+, :path*)
+     * - Custom regex parameters (:id(\\d+))
+     * - Unnamed groups filtering
+     *
+     * By using the same library as MSW, we automatically get MSW-compatible behavior.
+     *
+     * CRITICAL: Strip query parameters from request URL before matching.
+     * path-to-regexp matches against pathname only, not query string.
+     * Example: '/users/123?role=admin' should match pattern '/users/:id'
+     */
+    const patternPath = extractPathnameOrReturnAsIs(pattern);
+    let requestPath = extractPathnameOrReturnAsIs(requestUrl);
+    // Strip query parameters from request path
+    const queryIndex = requestPath.indexOf('?');
+    if (queryIndex !== -1) {
+        requestPath = requestPath.substring(0, queryIndex);
+    }
+    const matcher = match(patternPath, { decode: decodeURIComponent });
+    const result = matcher(requestPath);
+    if (result) {
+        const params = extractParams(result.params);
+        return { matches: true, params };
+    }
+    return { matches: false };
+};

package/package.json

@@ -1,10 +1,69 @@
 {
   "name": "@scenarist/msw-adapter",
-  "version": "0.0.1",
-  "description": "OIDC trusted publishing setup package for @scenarist/msw-adapter",
+  "version": "0.1.0",
+  "description": "Internal: MSW integration layer for Scenarist framework adapters",
+  "author": "Paul Hammond (citypaul) <paul@packsoftware.co.uk>",
+  "license": "MIT",
+  "homepage": "https://github.com/citypaul/scenarist#readme",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/citypaul/scenarist.git",
+    "directory": "internal/msw-adapter"
+  },
+  "bugs": {
+    "url": "https://github.com/citypaul/scenarist/issues"
+  },
   "keywords": [
-    "oidc",
-    "trusted-publishing",
-    "setup"
-  ]
-}
+    "msw",
+    "mock-service-worker",
+    "testing",
+    "scenarist",
+    "internal"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "path-to-regexp": "^6.3.0",
+    "@scenarist/core": "0.1.0"
+  },
+  "peerDependencies": {
+    "msw": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.10.1",
+    "@vitest/coverage-v8": "^4.0.8",
+    "eslint": "^9.39.1",
+    "msw": "^2.12.1",
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.8",
+    "@scenarist/eslint-config": "^0.0.0",
+    "@scenarist/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --project tsconfig.typecheck.json --noEmit",
+    "lint": "eslint .",
+    "clean": "rm -rf dist"
+  }
+}