@zenera/faker 1.1.20 → 1.1.21

package/README.md

@@ -57,6 +57,12 @@ zen faker cache clear                # throw it away
 
 `zen mock` is the same command under a shorter noun.
 
+A path key with a query string on it — `/x/{id}?action=retry`, which VMware NSX
+and others write when they need two `post`s under one path — is read for what
+it means rather than taken verbatim: the path is the part before the `?`, and
+each pair after it becomes a required query value that tells those operations
+apart. Call one without it and the 404 says which queries the path answers to.
+
 ## How a body is produced
 
 The first time an operation is called, the faker asks a model to write a
@@ -117,15 +123,27 @@ because a body handed it X.
 zen faker serve <spec...>    Serve them. Generators are written on demand.
 zen faker build <spec...>    Write every generator now and exit.
 zen faker cache ls | clear   What has been generated, or throw it away.
+zen faker model [ref]        Show or set the model it uses.
 ```
 
+The model is looked for in this order: `--model`, `ZENERA_FAKER_MODEL`, what
+`zen faker model <provider>:<id>` stored, then the best one your keys can buy.
+The stored one lives beside the keyring in `~/.zenera/neo/faker.json`, so it is
+remembered between runs and across projects; `zen faker model --clear` forgets
+it.
+
 Useful options: `--port`, `--host` (reachable only from this machine by
 default), `--model`, `--seed` (same request, same answer), `--rebuild`,
 `--attempts`, `--concurrency`, `--timeout`, `--cache <dir>` (the container's
 workspace), `--quiet`. `zen help faker` prints the full table.
 
-`GET /__faker/routes` lists what is being served; `GET /__faker/health` is a
-health check.
+`GET /` is a contents page: every operation the mock is serving, grouped by the
+document it came from, with its parameters and the shape of its answer. Each
+one has a **Run** button, which opens a form — a box per parameter, required
+ones marked, a body prefilled with something the mock will accept — and shows
+the status, the time and the answer. `GET /__faker/routes` is the same thing as
+JSON; `GET /__faker/health` is a health check. A document that declares `/`
+itself keeps it.
 
 ## Credentials
 

package/dist/command.js

@@ -1,12 +1,13 @@
-import { bold, cacheItems, clearCache, CliError, cyan, dim, EXIT, green, json, note, ownedContainers, parse, paths, red, removeContainers, table, usageError, write, writeAll, yellow, } from '@zenera/cli/lib';
+import { bold, cacheItems, clearCache, CliError, cyan, dim, EXIT, green, json, KeyStore, note, ownedContainers, parse, paths, red, removeContainers, table, usageError, write, writeAll, yellow, } from '@zenera/cli/lib';
+import { createModel } from '@zenera/neo';
 import { rmSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
 import { GENERATORS } from "./box.js";
 import { FAKER_KIND } from "./cache.js";
 import { reason } from "./generate.js";
 import { listen } from "./server.js";
-import { open } from "./setup.js";
-import {} from "./spec.js";
+import { chooseModel, MODEL_ENV, open, readSettings, SOURCE_LABELS, writeSettings, } from "./setup.js";
+import { called } from "./spec.js";
 // ---------------------------------------------------------------------------
 // zen faker — a mock API from a specification
 //
@@ -18,7 +19,7 @@ import {} from "./spec.js";
 // resolve until a signal arrives, and the process lives as long as the answer
 // takes, which is what every other command already means.
 // ---------------------------------------------------------------------------
-const USAGE = 'zen faker <serve|build|cache> [spec...]';
+const USAGE = 'zen faker <serve|build|cache|model> [spec...]';
 // `--json` is the frame's, lifted out of the arguments before they arrive; it
 // reaches us as `ctx.json` and must not be declared again or `strict` rejects it.
 const OPTIONS = {
@@ -34,6 +35,7 @@ const OPTIONS = {
     'max-body': { type: 'string' },
     rebuild: { type: 'boolean' },
     'no-cache': { type: 'boolean' },
+    clear: { type: 'boolean' },
     quiet: { type: 'boolean' },
 };
 export const command = {
@@ -45,13 +47,14 @@ export const command = {
             ['  serve <spec...>', dim('Serve the documents. Generators are written on demand.')],
             ['  build <spec...>', dim('Write every generator now and exit.')],
             ['  cache ls|clear', dim('What has been generated, or throw it away.')],
+            ['  model [ref]', dim('Show or set the model it uses. Remembered between runs.')],
         ]),
         '',
         'Options',
         ...table([
             ['  --port <n>', dim('Default 8787.')],
             ['  --host <h>', dim('Default 127.0.0.1. Anything else is reachable off-machine.')],
-            ['  --model <ref>', dim('Which model writes the generators.')],
+            ['  --model <ref>', dim('Which model writes the generators, for this run only.')],
             ['  --image <ref>', dim('Skip the baked image and use this one.')],
             ['  --cache <dir>', dim("The container's workspace. Default ~/.zenera/neo/faker.")],
             ['  --seed <n>', dim('Answer the same request the same way every time.')],
@@ -61,9 +64,12 @@ export const command = {
             ['  --max-body <n>', dim('Largest request body accepted, in bytes.')],
             ['  --rebuild', dim('Ignore what is cached and write it again.')],
             ['  --no-cache', dim('Do not record what is written.')],
+            ['  --clear', dim('With `model`: forget the stored one.')],
             ['  --quiet', dim('No narration.')],
         ]),
         '',
+        dim(`The model is looked for in this order: ${cyan('--model')}, ${cyan(MODEL_ENV)}, ` +
+            `${cyan('zen faker model')}, then the best one your keys can buy.`),
         dim(`Credentials come from the ${cyan('zen')} keyring — try ${cyan('zen key ls')}.`),
     ],
     async run(ctx) {
@@ -75,6 +81,8 @@ export const command = {
                 return await warm(rest, ctx);
             case 'cache':
                 return await cache(rest, ctx);
+            case 'model':
+                return await model(rest, ctx);
             default:
                 throw usageError(name ? `unknown command "${name}"` : 'no command given', USAGE);
         }
@@ -144,7 +152,7 @@ async function warm(args, ctx) {
     const results = [];
     try {
         for (const operation of setup.router.operations) {
-            const id = `${operation.method.toUpperCase()} ${operation.path}`;
+            const id = `${operation.method.toUpperCase()} ${called(operation)}`;
             if (!operation.success.schema) {
                 results.push({ operation: id, status: 'skipped', detail: 'no response body' });
                 continue;
@@ -238,6 +246,58 @@ function listGenerators() {
         .map((row) => ({ key: row.key, ...row.value?.meta }))
         .sort((a, b) => a.key.localeCompare(b.key));
 }
+// ---------------------------------------------------------------------------
+// model
+//
+// A stored model is remembered the way `zen meta model` remembers one: in the
+// home directory, beside the keyring, because it is a choice about this tool on
+// this machine. Shown rather than merely set, since the question when a run
+// surprises you is not "which model" but "why that one".
+// ---------------------------------------------------------------------------
+const MODEL_USAGE = 'zen faker model [ref|--clear]';
+async function model(args, ctx) {
+    const { values, positionals } = parse(args, OPTIONS, MODEL_USAGE);
+    const ref = positionals[0];
+    if (ref && values.clear) {
+        throw usageError('--clear takes no model', MODEL_USAGE);
+    }
+    // Before anything builds a model: vertex reads its project out of the
+    // environment, and the keyring is what puts it there.
+    const keys = await KeyStore.open();
+    keys.materialize();
+    if (ref || values.clear) {
+        const file = await readSettings();
+        if (ref) {
+            // Only that the ref parses: asking the provider costs a call, and
+            // the next run makes one anyway.
+            createModel(ref);
+            writeSettings({ ...file, model: ref });
+        }
+        else {
+            delete file.model;
+            writeSettings(file);
+        }
+        if (ctx.json) {
+            json({ model: ref });
+            return;
+        }
+        note(ref ? `${green('set')} ${ref}` : `${green('cleared')} ${dim('the stored model')}`);
+    }
+    const chosen = await chooseModel(values.model, keys);
+    if (ctx.json) {
+        json({ model: chosen?.ref, from: chosen?.from, stored: (await readSettings()).model });
+        return;
+    }
+    if (!chosen) {
+        note('no model, and no key to recommend one from');
+        note(dim('add a key: zen key add openai'));
+        return;
+    }
+    note(`${cyan(chosen.ref)} ${dim(`from ${SOURCE_LABELS[chosen.from]}`)}`);
+    if (chosen.from === 'default') {
+        note(dim(`set one: zen faker model <provider>:<id>`));
+    }
+}
 function summarize(operations) {
     const by = new Map();
     for (const op of operations) {
@@ -288,7 +348,7 @@ function printSpecs(operations, cwd) {
 // ---------------------------------------------------------------------------
 async function start(values, specs, ctx, what) {
     const loud = !values.quiet && !ctx.json;
-    return open({
+    const setup = await open({
         specs,
         cwd: ctx.cwd,
         cache: values.cache,
@@ -304,7 +364,7 @@ async function start(values, specs, ctx, what) {
             : undefined,
         events: {
             onStart: loud
-                ? ({ operation }) => note(`${dim('writing a generator for')} ${operation.method.toUpperCase()} ${operation.path}`)
+                ? ({ operation }) => note(`${dim('writing a generator for')} ${operation.method.toUpperCase()} ${called(operation)}`)
                 : undefined,
             onAttempt: loud
                 ? ({ operation, attempt, diagnostics }) => note(`  ${yellow(`attempt ${attempt} failed`)} ${dim(`${operation.operationId}: ${(diagnostics ?? []).join(' ').slice(0, 160)}`)}`)
@@ -319,6 +379,10 @@ async function start(values, specs, ctx, what) {
                 : undefined,
         },
     });
+    if (loud) {
+        note(dim(`model ${setup.choice.ref} from ${SOURCE_LABELS[setup.choice.from]}`));
+    }
+    return setup;
 }
 function number(raw, what) {
     if (raw === undefined) {

package/dist/generate.d.ts

@@ -1,6 +1,6 @@
 import type { Model } from '@zenera/neo';
 import type { Box } from './box.ts';
-import type { Operation } from './spec.ts';
+import { type Operation } from './spec.ts';
 import { type Checks } from './validate.ts';
 export interface BuildOptions {
     model: Model;

package/dist/generate.js

@@ -1,12 +1,13 @@
 import { tokenOf } from "./paging.js";
 import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
 import { instruction, retry, SYSTEM } from "./prompt.js";
+import { called } from "./spec.js";
 import { describeIssues, issues } from "./validate.js";
 export class BuildFailed extends Error {
     operation;
     diagnostics;
     constructor(operation, diagnostics) {
-        super(`could not write a generator for ${operation.method.toUpperCase()} ${operation.path}`);
+        super(`could not write a generator for ${operation.method.toUpperCase()} ${called(operation)}`);
         this.name = 'BuildFailed';
         this.operation = operation;
         this.diagnostics = diagnostics;
@@ -90,9 +91,9 @@ async function judge(operation, probes, response, box) {
     const out = [];
     for (const probe of probes) {
         const outcome = await box.run(operation.key, probe);
-        const called = `input ${JSON.stringify({ pathParams: probe.pathParams, query: probe.query })}`;
+        const what = `input ${JSON.stringify({ pathParams: probe.pathParams, query: probe.query })}`;
         if (!outcome.ok) {
-            out.push(`- ${called}: the file ${outcome.fault}.`);
+            out.push(`- ${what}: the file ${outcome.fault}.`);
             if (outcome.stderr) {
                 out.push(`  stderr: ${tail(outcome.stderr)}`);
             }
@@ -100,11 +101,11 @@ async function judge(operation, probes, response, box) {
             break;
         }
         if (response && !response(outcome.value)) {
-            out.push(`- ${called}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`);
+            out.push(`- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`);
         }
         const echo = echoIssues(probe, outcome.value, operation.success.schema);
         if (echo.length > 0) {
-            out.push(`- ${called}: ${describeIssues(echo)}.`);
+            out.push(`- ${what}: ${describeIssues(echo)}.`);
         }
     }
     // Only worth the container round trips once the file answers at all, and
@@ -127,13 +128,13 @@ async function walk(operation, paging, response, box) {
     let sent;
     for (let page = 1; page <= MAX_PAGES; page++) {
         const outcome = await box.run(operation.key, input);
-        const called = `page ${page} of ${operation.method.toUpperCase()} ${operation.path}`;
+        const what = `page ${page} of ${operation.method.toUpperCase()} ${called(operation)}`;
         if (!outcome.ok) {
-            return [`- ${called}: the file ${outcome.fault}.`];
+            return [`- ${what}: the file ${outcome.fault}.`];
         }
         if (response && !response(outcome.value)) {
             return [
-                `- ${called}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
+                `- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
             ];
         }
         const token = tokenOf(outcome.value, paging);
@@ -142,12 +143,12 @@ async function walk(operation, paging, response, box) {
         }
         if (token === sent) {
             return [
-                `- ${called}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the very token the request carried in \`${paging.param}\`. A client following it never advances. Build the token from \`${paging.param}\` so it counts up, and stop after three pages.`,
+                `- ${what}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the very token the request carried in \`${paging.param}\`. A client following it never advances. Build the token from \`${paging.param}\` so it counts up, and stop after three pages.`,
             ];
         }
         if (seen.has(token)) {
             return [
-                `- ${called}: the page tokens cycle — ${JSON.stringify(token)} was handed out earlier in this walk. Every page must offer a token no page has offered before, and the last one must offer none.`,
+                `- ${what}: the page tokens cycle — ${JSON.stringify(token)} was handed out earlier in this walk. Every page must offer a token no page has offered before, and the last one must offer none.`,
             ];
         }
         seen.add(token);

package/dist/page.d.ts

@@ -0,0 +1,3 @@
+import { type Operation } from './spec.ts';
+export declare function indexPage(operations: readonly Operation[]): string;
+//# sourceMappingURL=page.d.ts.map

package/dist/page.js

@@ -0,0 +1,499 @@
+import { bannerArt } from '@zenera/cli/lib';
+import { basename } from 'node:path';
+import { called } from "./spec.js";
+// ---------------------------------------------------------------------------
+// The index page
+//
+// What a person does first with a mock is point a browser at it, and a 404 on
+// `/` tells them nothing about what the thing is serving. So the root is a
+// contents page: every operation, grouped by the document it came from, in the
+// order the document declared it, and a button that calls it.
+//
+// It is one self-contained string — nothing is fetched over a network the mock
+// may well be standing in for: the stylesheet, the run dialog's script and the
+// operation descriptions it works from are all inline. The banner is the CLI's
+// own art, so the page and the terminal agree about what this program is
+// called.
+// ---------------------------------------------------------------------------
+const BRAND = { head: 'Zenera', accent: 'Faker', subtitle: 'Mock API Server' };
+export function indexPage(operations) {
+    const documents = group(operations);
+    const title = `${BRAND.head} ${BRAND.accent}`;
+    const at = new Map(operations.map((operation, i) => [operation, i]));
+    // `<` is escaped so no description can close this script element early.
+    const descriptors = JSON.stringify(operations.map(callable)).replace(/</g, '\\u003c');
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${esc(title)}</title>
+<style>${CSS}</style>
+</head>
+<body>
+<header>
+${banner()}
+<p class="caption">${esc(BRAND.subtitle)}</p>
+<p class="meta">${operations.length} operation${operations.length === 1 ? '' : 's'} &middot; ${documents.length} document${documents.length === 1 ? '' : 's'} &middot; <a href="/__faker/routes">routes</a> &middot; <a href="/__faker/health">health</a></p>
+</header>
+<main>
+${documents.map((d) => document(d, at)).join('\n') || '<p class="empty">No operations are being served.</p>'}
+</main>
+${DIALOG}
+<script type="application/json" id="faker-ops">${descriptors}</script>
+<script>${SCRIPT}</script>
+</body>
+</html>
+`;
+}
+/** By source document, each keeping the order its document declared. */
+function group(operations) {
+    const out = new Map();
+    for (const operation of operations) {
+        const list = out.get(operation.source) ?? [];
+        list.push(operation);
+        out.set(operation.source, list);
+    }
+    return [...out];
+}
+function document([source, operations], at) {
+    return `<section>
+<h2>${esc(basename(source))} <span class="source">${esc(source)}</span></h2>
+${operations.map((operation) => entry(operation, at.get(operation) ?? 0)).join('\n')}
+</section>`;
+}
+function entry(operation, index) {
+    const parts = [
+        `<div class="op">`,
+        `<div class="sig"><span class="verb ${operation.method}">${operation.method.toUpperCase()}</span><code class="path">${esc(called(operation))}</code><span class="id">${esc(operation.operationId)}</span><button type="button" class="try" data-op="${index}">Run</button></div>`,
+    ];
+    if (operation.summary) {
+        parts.push(`<p class="summary">${esc(operation.summary)}</p>`);
+    }
+    if (operation.description && operation.description !== operation.summary) {
+        parts.push(`<p class="about">${esc(operation.description)}</p>`);
+    }
+    parts.push(`<p class="answer">${esc(answer(operation))}</p>`);
+    if (operation.params.length > 0 || operation.requestBody) {
+        parts.push(`<div class="rows"><table class="params">${rows(operation).join('')}</table></div>`);
+    }
+    parts.push('</div>');
+    return parts.join('\n');
+}
+/** The one line that says what a call gets back. */
+function answer(operation) {
+    const body = operation.success.schema ? typeOf(operation.success.schema) : 'no body';
+    const paged = operation.paging
+        ? ` · pages by ${operation.paging.param}${operation.paging.next ? ` → ${operation.paging.next}` : ''}`
+        : '';
+    return `→ ${operation.success.status} ${body}${paged}`;
+}
+function rows(operation) {
+    const out = operation.params.map((p) => `<tr><td class="name">${esc(p.name)}</td><td class="in">${esc(p.in)}</td><td class="type">${esc(typeOf(p.schema))}</td><td class="need">${p.required ? 'required' : ''}</td><td class="note">${esc(p.description ?? '')}</td></tr>`);
+    if (operation.requestBody) {
+        out.push(`<tr><td class="name">body</td><td class="in">body</td><td class="type">${esc(typeOf(operation.requestBody.schema))}</td><td class="need">${operation.requestBody.required ? 'required' : ''}</td><td class="note"></td></tr>`);
+    }
+    return out;
+}
+/** A schema in as many words as fit in a column: the shape, not the contract. */
+function typeOf(schema, root = schema, depth = 0) {
+    const node = deref(schema, root);
+    const type = Array.isArray(node.type) ? node.type.join(' | ') : node.type;
+    if (type === 'array' && depth < 3) {
+        const items = node.items;
+        return `${isObject(items) ? typeOf(items, root, depth + 1) : 'any'}[]`;
+    }
+    if (Array.isArray(node.enum)) {
+        return brief(node.enum.map((v) => String(v)), ' | ');
+    }
+    if (isObject(node.properties)) {
+        return `object { ${brief(Object.keys(node.properties), ', ')} }`;
+    }
+    if (typeof type === 'string') {
+        return `${type}${typeof node.format === 'string' ? ` <${node.format}>` : ''}`;
+    }
+    for (const key of ['oneOf', 'anyOf', 'allOf']) {
+        if (Array.isArray(node[key])) {
+            return key;
+        }
+    }
+    return 'any';
+}
+/**
+ * Anything shared or recursive was hoisted into `$defs` under a made-up name,
+ * so the pointer says nothing and the shape it points at says everything.
+ */
+function deref(schema, root, hops = 0) {
+    const ref = schema.$ref;
+    if (typeof ref !== 'string' || !ref.startsWith(DEFS) || hops >= 4) {
+        return schema;
+    }
+    const defs = root.$defs;
+    if (!isObject(defs)) {
+        return schema;
+    }
+    const target = defs[ref.slice(DEFS.length)];
+    return isObject(target) ? deref(target, root, hops + 1) : schema;
+}
+const DEFS = '#/$defs/';
+function callable(operation) {
+    // Cookies are not the browser's to set from a script, so they are shown in
+    // the table and left out of the form.
+    const fields = operation.params
+        .filter((p) => p.in !== 'cookie')
+        .map((p) => {
+        const node = deref(p.schema, p.schema);
+        return {
+            name: p.name,
+            in: p.in,
+            required: p.required,
+            type: typeOf(p.schema),
+            choices: choicesOf(node),
+            description: p.description,
+        };
+    });
+    const body = operation.requestBody;
+    return {
+        method: operation.method,
+        path: operation.path,
+        shown: called(operation),
+        fields,
+        body: body
+            ? {
+                required: body.required,
+                sample: JSON.stringify(sample(body.schema, body.schema), null, 2),
+            }
+            : undefined,
+    };
+}
+function choicesOf(node) {
+    if (Array.isArray(node.enum)) {
+        return node.enum.map((v) => String(v));
+    }
+    return node.type === 'boolean' ? ['true', 'false'] : undefined;
+}
+/** Something shaped like the body, so the textarea is edited rather than written. */
+function sample(schema, root, depth = 0) {
+    const node = deref(schema, root);
+    if (node.default !== undefined) {
+        return node.default;
+    }
+    if (Array.isArray(node.enum)) {
+        return node.enum[0];
+    }
+    const type = Array.isArray(node.type) ? node.type[0] : node.type;
+    if (type === 'array') {
+        return depth < 2 && isObject(node.items) ? [sample(node.items, root, depth + 1)] : [];
+    }
+    if (isObject(node.properties) && depth < 3) {
+        // Only what the document insists on. An optional branch filled in with
+        // blanks is a request the mock would reject before it answered.
+        const need = Array.isArray(node.required) ? node.required.map(String) : null;
+        const out = {};
+        for (const [name, sub] of Object.entries(node.properties)) {
+            if (isObject(sub) && (need === null || need.includes(name))) {
+                out[name] = sample(sub, root, depth + 1);
+            }
+        }
+        return out;
+    }
+    if (Array.isArray(node.allOf) && depth < 3) {
+        // The branches of an `allOf` all apply at once, so they are merged.
+        return node.allOf
+            .filter(isObject)
+            .reduce((all, branch) => Object.assign(all, sample(branch, root, depth + 1)), {});
+    }
+    for (const key of ['oneOf', 'anyOf']) {
+        const branches = node[key];
+        if (Array.isArray(branches) && isObject(branches[0]) && depth < 3) {
+            return sample(branches[0], root, depth + 1);
+        }
+    }
+    if (type === 'integer' || type === 'number') {
+        return 0;
+    }
+    if (type === 'boolean') {
+        return false;
+    }
+    if (type === 'string') {
+        // A blank fails `format`, and the mock checks the request before it
+        // answers it, so a formatted string starts out as something legal.
+        return LIKE[String(node.format)] ?? '';
+    }
+    return type === 'object' ? {} : null;
+}
+const LIKE = {
+    email: 'someone@example.com',
+    hostname: 'example.com',
+    uri: 'https://example.com',
+    'uri-reference': '/example',
+    uuid: '00000000-0000-4000-8000-000000000000',
+    date: '2024-01-01',
+    'date-time': '2024-01-01T00:00:00Z',
+    time: '00:00:00',
+    duration: 'P1D',
+    ipv4: '127.0.0.1',
+    ipv6: '::1',
+};
+/** A list cut short: a contents page is not the document. */
+const brief = (values, sep) => values.slice(0, MOST).join(sep) + (values.length > MOST ? `${sep}…` : '');
+const MOST = 6;
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The CLI's block face, split at the word so the accent keeps its colour. */
+function banner() {
+    const { head, accent } = bannerArt(BRAND);
+    const rows = head.map((row, i) => `<span class="head">${paint(row)}</span>   <span class="accent">${paint(accent[i] ?? '')}</span>`);
+    return `<pre class="banner" role="img" aria-label="${esc(`${BRAND.head} ${BRAND.accent}`)}">${rows.join('\n')}</pre>`;
+}
+/**
+ * Stroke and bevel, the terminal's two tones. Without the darker bevel the
+ * letter reads as a doubled outline rather than as a raised face.
+ */
+const paint = (row) => row.replace(/[█▀▄]+|[^█▀▄ ]+/g, (run) => /[█▀▄]/.test(run) ? `<b>${run}</b>` : `<i>${run}</i>`);
+const esc = (s) => s.replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' })[c]);
+const DIALOG = `<dialog id="run">
+<div class="run-head"><h3 id="run-title"></h3><button type="button" id="run-close" aria-label="Close">&times;</button></div>
+<form id="run-form">
+<div id="run-fields"></div>
+<div class="actions"><button type="submit" class="go">Run</button><button type="button" id="run-cancel" class="cancel">Cancel</button></div>
+</form>
+<pre id="run-out" hidden></pre>
+</dialog>`;
+// Values from the document reach the dialog as text nodes rather than markup:
+// the page escapes what it prints, and this has to do the same by construction.
+const SCRIPT = `
+const specs = JSON.parse(document.getElementById('faker-ops').textContent);
+const dialog = document.getElementById('run');
+const title = document.getElementById('run-title');
+const slots = document.getElementById('run-fields');
+const form = document.getElementById('run-form');
+const out = document.getElementById('run-out');
+let current = null;
+
+function box(field) {
+    if (field.choices) {
+        const select = document.createElement('select');
+        if (!field.required) {
+            select.append(new Option('', ''));
+        }
+        for (const choice of field.choices) {
+            select.append(new Option(choice, choice));
+        }
+        return select;
+    }
+    const input = document.createElement('input');
+    input.type = 'text';
+    input.placeholder = field.type;
+    return input;
+}
+
+function head(name, hint, required) {
+    const span = document.createElement('span');
+    span.className = 'label';
+    span.textContent = name;
+    const where = document.createElement('em');
+    where.textContent = hint;
+    span.append(' ', where);
+    if (required) {
+        const need = document.createElement('b');
+        need.textContent = 'required';
+        span.append(' ', need);
+    }
+    return span;
+}
+
+function row(field) {
+    const label = document.createElement('label');
+    label.className = 'field';
+    const input = box(field);
+    input.name = field.in + ':' + field.name;
+    input.required = field.required;
+    label.append(head(field.name, field.in + ' \u00b7 ' + field.type, field.required), input);
+    if (field.description) {
+        const note = document.createElement('small');
+        note.textContent = field.description;
+        label.append(note);
+    }
+    return label;
+}
+
+function bodyRow(body) {
+    const label = document.createElement('label');
+    label.className = 'field';
+    const area = document.createElement('textarea');
+    area.name = '@body';
+    area.value = body.sample;
+    area.required = body.required;
+    label.append(head('body', 'application/json', body.required), area);
+    return label;
+}
+
+function show(index) {
+    current = specs[index];
+    title.textContent = current.method.toUpperCase() + ' ' + current.shown;
+    slots.replaceChildren();
+    for (const field of current.fields) {
+        slots.append(row(field));
+    }
+    if (current.body) {
+        slots.append(bodyRow(current.body));
+    }
+    if (!current.fields.length && !current.body) {
+        const hint = document.createElement('p');
+        hint.className = 'hint';
+        hint.textContent = 'This call takes no arguments.';
+        slots.append(hint);
+    }
+    out.hidden = true;
+    out.textContent = '';
+    dialog.showModal();
+}
+
+form.addEventListener('submit', async (event) => {
+    event.preventDefault();
+    const spec = current;
+    const data = new FormData(form);
+    const path = spec.path.replace(/\\{(.*?)\\}/g, (whole, name) =>
+        encodeURIComponent(String(data.get('path:' + name) || '')),
+    );
+    const url = new URL(path, location.origin);
+    const headers = {};
+    for (const field of spec.fields) {
+        const value = data.get(field.in + ':' + field.name);
+        if (value === null || value === '') {
+            continue;
+        }
+        if (field.in === 'query') {
+            url.searchParams.set(field.name, value);
+        }
+        if (field.in === 'header') {
+            headers[field.name] = value;
+        }
+    }
+    let body;
+    const typed = spec.body ? String(data.get('@body') || '').trim() : '';
+    if (typed && spec.method !== 'get' && spec.method !== 'head') {
+        body = typed;
+        headers['content-type'] = 'application/json';
+    }
+
+    out.hidden = false;
+    out.dataset.ok = 'true';
+    out.textContent = 'running\u2026';
+    const started = performance.now();
+    try {
+        const res = await fetch(url, { method: spec.method.toUpperCase(), headers, body });
+        const answer = await res.text();
+        let shown = answer;
+        try {
+            shown = JSON.stringify(JSON.parse(answer), null, 2);
+        } catch {}
+        out.dataset.ok = String(res.ok);
+        out.textContent =
+            res.status + ' ' + res.statusText + ' \u00b7 ' +
+            Math.round(performance.now() - started) + 'ms \u00b7 ' +
+            spec.method.toUpperCase() + ' ' + url.pathname + url.search + '\\n\\n' + shown;
+    } catch (err) {
+        out.dataset.ok = 'false';
+        out.textContent = String(err);
+    }
+});
+
+for (const button of document.querySelectorAll('button.try')) {
+    button.addEventListener('click', () => show(Number(button.dataset.op)));
+}
+document.getElementById('run-close').addEventListener('click', () => dialog.close());
+document.getElementById('run-cancel').addEventListener('click', () => dialog.close());
+`;
+// The two schemes are the terminal's two, and the accent is the same mint the
+// `zen faker` banner is painted in on both.
+const CSS = `
+:root {
+  color-scheme: dark light;
+  --bg: #12131a; --fg: #e6e7ee; --dim: #8b8fa3; --line: #262838;
+  --card: #191b25; --accent: #87ffaf; --shade: #5fd787;
+}
+@media (prefers-color-scheme: light) {
+  :root { --bg: #fbfbfd; --fg: #1d1f2a; --dim: #6a6e80; --line: #e2e3ec;
+          --card: #ffffff; --accent: #14915a; --shade: #0f7548; }
+}
+* { box-sizing: border-box; }
+body { margin: 0; padding: 2rem 0 4rem; background: var(--bg); color: var(--fg);
+  font: 15px/1.55 ui-sans-serif, -apple-system, "Segoe UI", Roboto, sans-serif; }
+header, main { width: 90%; margin: 0 auto; }
+.banner { font: 11px/1 ui-monospace, SFMono-Regular, Menlo, monospace;
+  margin: 0; overflow-x: auto; }
+.banner b, .banner i { font: inherit; }
+.banner .head b { color: var(--fg); }
+.banner .head i { color: var(--dim); }
+.banner .accent b { color: var(--accent); }
+.banner .accent i { color: var(--shade); }
+.caption { margin: .75rem 0 0; color: var(--dim); letter-spacing: .35em;
+  text-transform: uppercase; font-size: 11px; }
+.meta { margin: .35rem 0 2.5rem; color: var(--dim); font-size: 13px; }
+.meta a { color: var(--shade); text-decoration: none; }
+.meta a:hover { text-decoration: underline; }
+h2 { font-size: 14px; font-weight: 600; margin: 2.5rem 0 .75rem;
+  padding-bottom: .4rem; border-bottom: 1px solid var(--line); }
+h2 .source { font-weight: 400; color: var(--dim); font-size: 12px; margin-left: .5rem;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.op { background: var(--card); border: 1px solid var(--line); border-radius: 8px;
+  padding: .8rem 1rem; margin: .5rem 0; }
+.sig { display: flex; align-items: center; gap: .6rem; flex-wrap: wrap; }
+.verb { font: 600 11px/1 ui-monospace, SFMono-Regular, Menlo, monospace; letter-spacing: .08em;
+  padding: .3rem .45rem; border-radius: 4px; color: #0c0d12; background: var(--dim); }
+.verb.get { background: #87ffaf; } .verb.post { background: #7fbcff; }
+.verb.put { background: #ffd479; } .verb.patch { background: #d3a6ff; }
+.verb.delete { background: #ff8f8f; }
+.path { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px;
+  overflow-wrap: anywhere; }
+.id { color: var(--dim); font-size: 12px; margin-left: auto;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.summary { margin: .5rem 0 0; }
+.about { margin: .3rem 0 0; color: var(--dim); font-size: 13px; white-space: pre-wrap;
+  overflow-wrap: anywhere; }
+.answer { margin: .5rem 0 0; color: var(--shade); font-size: 12px; overflow-wrap: anywhere;
+  font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.rows { overflow-x: auto; }
+.params { margin: .6rem 0 0; border-collapse: collapse; width: 100%; font-size: 12px; }
+.params td { padding: .2rem .5rem .2rem 0; vertical-align: top; overflow-wrap: break-word;
+  border-top: 1px solid var(--line); }
+.params .name { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; }
+.params .in, .params .need { color: var(--dim); white-space: nowrap; }
+.params .type { color: var(--dim); max-width: 18rem; overflow-wrap: anywhere; }
+.params .note { color: var(--dim); width: 50%; }
+.empty { color: var(--dim); }
+.try { background: transparent; color: var(--shade); border: 1px solid var(--line);
+  border-radius: 6px; padding: .2rem .6rem; font: 600 11px/1.6 inherit; cursor: pointer; }
+.try:hover { border-color: var(--accent); color: var(--accent); }
+dialog { width: min(48rem, 92%); padding: 0; color: var(--fg); background: var(--card);
+  border: 1px solid var(--line); border-radius: 10px; }
+dialog::backdrop { background: rgba(0, 0, 0, .55); }
+.run-head { display: flex; align-items: center; gap: .6rem;
+  padding: .8rem 1rem; border-bottom: 1px solid var(--line); }
+.run-head h3 { margin: 0; overflow-wrap: anywhere;
+  font: 600 13px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; }
+#run-close { margin-left: auto; background: none; border: 0; color: var(--dim);
+  font-size: 18px; line-height: 1; cursor: pointer; }
+#run-form { padding: 1rem; max-height: 55vh; overflow-y: auto; }
+.field { display: block; margin: 0 0 .9rem; }
+.field .label { font: 600 12px/1.4 ui-monospace, SFMono-Regular, Menlo, monospace; }
+.field .label em { font-style: normal; font-weight: 400; color: var(--dim); font-size: 11px; }
+.field .label b { color: var(--shade); font-size: 11px; }
+.field small { display: block; margin-top: .2rem; color: var(--dim); font-size: 11px; }
+.field input, .field select, .field textarea { display: block; width: 100%; margin-top: .3rem;
+  padding: .4rem .5rem; color: var(--fg); background: var(--bg); border: 1px solid var(--line);
+  border-radius: 6px; font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; }
+.field textarea { min-height: 9rem; resize: vertical; }
+.hint { color: var(--dim); font-size: 13px; margin: 0 0 .9rem; }
+.actions { display: flex; gap: .5rem; }
+.go { background: var(--accent); color: #0c0d12; border: 0; border-radius: 6px;
+  padding: .45rem 1.1rem; font: 600 13px/1.4 inherit; cursor: pointer; }
+.cancel { background: transparent; color: var(--dim); border: 1px solid var(--line);
+  border-radius: 6px; padding: .45rem .9rem; font: 13px/1.4 inherit; cursor: pointer; }
+#run-out { margin: 0; padding: .8rem 1rem; max-height: 40vh; overflow: auto;
+  border-top: 1px solid var(--line); background: var(--bg); white-space: pre-wrap;
+  overflow-wrap: anywhere; font: 12px/1.5 ui-monospace, SFMono-Regular, Menlo, monospace; }
+#run-out[data-ok="false"] { color: #ff8f8f; }
+`;
+//# sourceMappingURL=page.js.map

package/dist/prompt.d.ts

@@ -1,4 +1,4 @@
-import type { Operation } from './spec.ts';
+import { type Operation } from './spec.ts';
 export declare const SYSTEM: string;
 export declare function brief(operation: Operation): string;
 /**

package/dist/prompt.js

@@ -1,4 +1,5 @@
 import { AVAILABLE } from "./image.js";
+import { called } from "./spec.js";
 // ---------------------------------------------------------------------------
 // What the model is told
 //
@@ -53,7 +54,7 @@ export const SYSTEM = [
 ].join('\n');
 export function brief(operation) {
     const lines = [
-        `OPERATION  ${operation.method.toUpperCase()} ${operation.path}`,
+        `OPERATION  ${operation.method.toUpperCase()} ${called(operation)}`,
         `operationId: ${operation.operationId}`,
     ];
     if (operation.summary) {

package/dist/router.d.ts

@@ -7,8 +7,14 @@ export declare class Router {
     #private;
     readonly operations: readonly Operation[];
     constructor(operations: readonly Operation[]);
-    match(method: string, pathname: string): Match | undefined;
+    match(method: string, pathname: string, search?: URLSearchParams): Match | undefined;
     /** Whether the path exists under some other method — a 405, not a 404. */
-    allowed(pathname: string): Method[];
+    allowed(pathname: string, search?: URLSearchParams): Method[];
+    /**
+     * The query strings this method would have answered on this path. Empty
+     * unless the document pinned one, which is the only way a request can miss
+     * a route whose path it matched exactly.
+     */
+    expects(method: string, pathname: string): string[];
 }
 //# sourceMappingURL=router.d.ts.map

package/dist/router.js

@@ -6,7 +6,8 @@ export class Router {
         this.operations = operations;
         const seen = new Map();
         for (const operation of operations) {
-            const id = `${operation.method} ${operation.path}`;
+            const fixed = Object.entries(operation.fixed ?? {}).sort(([a], [b]) => a.localeCompare(b));
+            const id = `${operation.method} ${operation.path}${query(fixed)}`;
             const clash = seen.get(id);
             if (clash) {
                 throw new SpecError(`${id} is declared twice`, `${clash.source} and ${operation.source} both define it`);
@@ -17,17 +18,21 @@ export class Router {
             list.push({
                 operation,
                 segments,
+                fixed,
                 specificity: segments.filter((s) => s.name === undefined).length,
             });
             this.#routes.set(operation.method, list);
         }
         for (const list of this.#routes.values()) {
-            list.sort((a, b) => b.specificity - a.specificity);
+            list.sort((a, b) => b.fixed.length - a.fixed.length || b.specificity - a.specificity);
         }
     }
-    match(method, pathname) {
+    match(method, pathname, search) {
         const parts = split(pathname);
         for (const route of this.#routes.get(method.toLowerCase()) ?? []) {
+            if (!pins(route, search)) {
+                continue;
+            }
             const pathParams = apply(route.segments, parts);
             if (pathParams) {
                 return { operation: route.operation, pathParams };
@@ -36,17 +41,30 @@ export class Router {
         return undefined;
     }
     /** Whether the path exists under some other method — a 405, not a 404. */
-    allowed(pathname) {
+    allowed(pathname, search) {
         const parts = split(pathname);
         const out = [];
         for (const [method, list] of this.#routes) {
-            if (list.some((r) => apply(r.segments, parts) !== undefined)) {
+            if (list.some((r) => pins(r, search) && apply(r.segments, parts) !== undefined)) {
                 out.push(method);
             }
         }
         return out;
     }
+    /**
+     * The query strings this method would have answered on this path. Empty
+     * unless the document pinned one, which is the only way a request can miss
+     * a route whose path it matched exactly.
+     */
+    expects(method, pathname) {
+        const parts = split(pathname);
+        return (this.#routes.get(method.toLowerCase()) ?? [])
+            .filter((r) => r.fixed.length > 0 && apply(r.segments, parts) !== undefined)
+            .map((r) => query(r.fixed));
+    }
 }
+const query = (fixed) => fixed.length === 0 ? '' : `?${new URLSearchParams(fixed).toString()}`;
+const pins = (route, search) => route.fixed.every(([name, value]) => search?.get(name) === value);
 function compile(template) {
     return split(template).map((raw) => {
         const m = /^\{(.+)\}$/.exec(raw);

package/dist/server.js

@@ -2,6 +2,7 @@ import { createHash, randomInt } from 'node:crypto';
 import { createServer } from 'node:http';
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
+import { indexPage } from "./page.js";
 import { cutLoop, pagingSeen } from "./paging.js";
 import { describeIssues, issues } from "./validate.js";
 // ---------------------------------------------------------------------------
@@ -63,16 +64,36 @@ async function handle(req, res, opts) {
         say(200, 'introspection');
         return;
     }
-    const match = opts.router.match(method, url.pathname);
+    const match = opts.router.match(method, url.pathname, url.searchParams);
     if (!match) {
-        const allowed = opts.router.allowed(url.pathname);
+        // The document owns `/` only when it declares it. Otherwise the root is
+        // the contents page, which is what a browser pointed here came for.
+        if (url.pathname === '/' && (method === 'get' || method === 'head')) {
+            html(res, indexPage(opts.router.operations));
+            say(200, 'index');
+            return;
+        }
+        // The path matched and the query did not, which no one guesses unaided
+        // — and it is not a 405 either, since the method is defined here.
+        const expects = opts.router.expects(method, url.pathname);
+        if (expects.length > 0) {
+            send(res, 404, {
+                error: `${req.method} ${url.pathname} is only defined with a query`,
+                expects,
+            });
+            say(404, `expects ${expects.join(' ')}`);
+            return;
+        }
+        const allowed = opts.router.allowed(url.pathname, url.searchParams);
         if (allowed.length > 0) {
             res.setHeader('allow', allowed.map((m) => m.toUpperCase()).join(', '));
             send(res, 405, { error: `${req.method} is not defined for ${url.pathname}` });
             say(405, 'no such method');
             return;
         }
-        send(res, 404, { error: `no operation matches ${req.method} ${url.pathname}` });
+        send(res, 404, {
+            error: `no operation matches ${req.method} ${url.pathname}`,
+        });
         say(404, 'no route');
         return;
     }
@@ -271,4 +292,11 @@ function send(res, status, value) {
     res.setHeader('content-length', Buffer.byteLength(text));
     res.end(text);
 }
+/** Node drops the body itself when the request was a HEAD. */
+function html(res, text) {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/html; charset=utf-8');
+    res.setHeader('content-length', Buffer.byteLength(text));
+    res.end(text);
+}
 //# sourceMappingURL=server.js.map

package/dist/setup.d.ts

@@ -1,9 +1,26 @@
+import { KeyStore } from '@zenera/cli/lib';
 import { type Model } from '@zenera/neo';
 import { Box } from './box.ts';
 import { Cache, type CacheOptions } from './cache.ts';
 import { Router } from './router.ts';
 import { SpecError } from './spec.ts';
 import { Checks } from './validate.ts';
+/** The variable a shell or a CI job names it with — a zen ref. */
+export declare const MODEL_ENV = "ZENERA_FAKER_MODEL";
+export type ModelSource = 'flag' | 'env' | 'store' | 'default';
+export declare const SOURCE_LABELS: Record<ModelSource, string>;
+export interface ModelChoice {
+    ref: string;
+    from: ModelSource;
+}
+export interface FakerFile {
+    version: 1;
+    model?: string;
+}
+export declare const readSettings: () => Promise<FakerFile>;
+export declare function writeSettings(file: FakerFile): void;
+/** What `open` would run, and where it came from, so a command can say so too. */
+export declare function chooseModel(flag: string | undefined, keys: KeyStore): Promise<ModelChoice | undefined>;
 export interface SetupOptions {
     specs: readonly string[];
     cwd: string;
@@ -26,6 +43,7 @@ export interface Setup {
     cache: Cache;
     box: Box;
     model: Model;
+    choice: ModelChoice;
     image: string;
     root: string;
     close(): Promise<void>;

package/dist/setup.js

@@ -1,7 +1,7 @@
-import { credentialError, ensureHome, ensurePodmanReady, envNames, invalidError, KeyStore, paths, PROVIDERS, } from '@zenera/cli/lib';
+import { credentialError, ensureHome, ensurePodmanReady, envNames, home, invalidError, KeyStore, paths, PROVIDERS, readJson, writeJson, } from '@zenera/cli/lib';
 import { createModel } from '@zenera/neo';
 import { mkdirSync } from 'node:fs';
-import { resolve } from 'node:path';
+import { join, resolve } from 'node:path';
 import { Box } from "./box.js";
 import { Cache } from "./cache.js";
 import { ensureImage } from "./image.js";
@@ -18,17 +18,58 @@ import { Checks } from "./validate.js";
 // happened to be checked first.
 // ---------------------------------------------------------------------------
 /**
- * The model each provider gets when none is named. Every ref names its
+ * The model each provider gets when none is named — the same picks `zen meta`
+ * recommends (`RECOMMENDED` in `packages/cli/src/meta.ts`). Every ref names its
  * provider: the shorthand reads the first segment as a *provider name*, so a
- * bare `gemini-3.5-flash` would be asked of OpenAI.
+ * bare `gemini-3.8-flash` would be asked of OpenAI.
  */
 const DEFAULT_MODEL = {
-    openai: 'openai:gpt-5.4-mini',
-    anthropic: 'anthropic:claude-sonnet-4-5',
-    google: 'google:gemini-3.5-flash',
-    vertex: 'vertex:gemini-3.5-flash',
-    openrouter: 'openrouter:inclusionai/ling-3.0-flash-fin:free',
+    openai: 'openai:gpt-5.6-sol',
+    anthropic: 'anthropic:claude-opus-5',
+    google: 'google:gemini-3.8-flash',
+    vertex: 'vertex:gemini-3.8-flash',
+    openrouter: 'openrouter:anthropic/claude-opus-5',
 };
+// ---------------------------------------------------------------------------
+// Which model, and why that one
+//
+// The same chain `zen meta` uses: a flag beats the environment, the environment
+// beats what was stored, and with none of them set it is whatever the keys on
+// hand can buy. Which model writes generators is a choice about a tool on this
+// machine and not about a document, so it is stored beside the keyring rather
+// than anywhere near a specification.
+// ---------------------------------------------------------------------------
+/** The variable a shell or a CI job names it with — a zen ref. */
+export const MODEL_ENV = 'ZENERA_FAKER_MODEL';
+export const SOURCE_LABELS = {
+    flag: '--model',
+    env: MODEL_ENV,
+    store: 'zen faker model',
+    default: 'recommended',
+};
+const EMPTY = { version: 1 };
+const settingsPath = () => join(home(), 'faker.json');
+export const readSettings = () => readJson(settingsPath(), EMPTY);
+export function writeSettings(file) {
+    ensureHome();
+    writeJson(settingsPath(), file);
+}
+/** What `open` would run, and where it came from, so a command can say so too. */
+export async function chooseModel(flag, keys) {
+    const chain = [
+        ['flag', flag],
+        ['env', process.env[MODEL_ENV]],
+        ['store', (await readSettings()).model],
+        ['default', defaultRef(keys)],
+    ];
+    for (const [from, ref] of chain) {
+        const named = ref?.trim();
+        if (named) {
+            return { ref: named, from };
+        }
+    }
+    return undefined;
+}
 export async function open(opts) {
     if (opts.specs.length === 0) {
         throw invalidError('no specification given', 'name one or more openapi/swagger files');
@@ -37,7 +78,11 @@ export async function open(opts) {
     ensureHome();
     const keys = await KeyStore.open();
     keys.materialize();
-    const model = createModel(opts.model ?? defaultRef(keys));
+    const choice = await chooseModel(opts.model, keys);
+    if (!choice) {
+        throw credentialError('no credentials for any provider', 'add one with: zen key add openai');
+    }
+    const model = createModel(choice.ref);
     const root = resolve(opts.cwd, opts.cache ?? paths.faker());
     mkdirSync(root, { recursive: true, mode: 0o700 });
     // Podman is asked about before the image is built, so a machine without a
@@ -62,7 +107,7 @@ export async function open(opts) {
         ephemeral: opts.ephemeral,
         ...opts.events,
     });
-    return { router, checks, cache, box, model, image, root, close: () => box.dispose() };
+    return { router, checks, cache, box, model, choice, image, root, close: () => box.dispose() };
 }
 /**
  * Presence, not liveness. `zen init` probes because it is writing a project
@@ -72,10 +117,7 @@ export async function open(opts) {
 function defaultRef(keys) {
     const provider = PROVIDERS.find((p) => envNames(p).some((name) => process.env[name])) ??
         PROVIDERS.find((p) => keys.active(p) !== undefined);
-    if (!provider) {
-        throw credentialError('no credentials for any provider', 'add one with: zen key add openai');
-    }
-    return DEFAULT_MODEL[provider];
+    return provider ? DEFAULT_MODEL[provider] : undefined;
 }
 export { SpecError };
 //# sourceMappingURL=setup.js.map

package/dist/spec.d.ts

@@ -23,6 +23,8 @@ export interface Operation {
     summary?: string;
     description?: string;
     params: ParamSpec[];
+    /** query values the path key pinned down, see `splitQuery` */
+    fixed?: Record<string, string>;
     requestBody?: {
         required: boolean;
         schema: Schema;
@@ -41,4 +43,6 @@ export declare class SpecError extends CliError {
 }
 export declare function loadSpecs(files: readonly string[]): Promise<Operation[]>;
 export declare function loadSpec(file: string): Promise<Operation[]>;
+/** The path as it has to be called — what a person needs to see. */
+export declare const called: (op: Operation) => string;
 //# sourceMappingURL=spec.d.ts.map

package/dist/spec.js

@@ -57,13 +57,14 @@ export async function loadSpec(file) {
             if (!isObject(op)) {
                 continue;
             }
-            const path = join(prefix, template);
-            const merged = override(shared, params(op.parameters, dialect));
+            const { path, fixed } = splitQuery(join(prefix, template));
+            const merged = override(override(shared, params(op.parameters, dialect)), pinned(fixed));
             out.push(build({
                 source: file,
                 dialect,
                 method,
                 path,
+                fixed,
                 op,
                 params: merged,
                 body: requestBody(op, dialect),
@@ -88,11 +89,42 @@ function join(prefix, template) {
     const base = prefix.replace(/\/+$/, '');
     return `${base}${template.startsWith('/') ? '' : '/'}${template}` || '/';
 }
+/** The path as it has to be called — what a person needs to see. */
+export const called = (op) => op.fixed ? `${op.path}?${new URLSearchParams(op.fixed).toString()}` : op.path;
+/**
+ * A path template has no query string, but VMware, Oracle and others write one
+ * anyway — `/x/{id}?action=retry` — because they need two `post`s under one
+ * path and the object model gives them one. Taken verbatim the key matches
+ * nothing, since a request path never contains a `?`. So it is read for what
+ * it means: the path is the part before the `?`, and each pair after it is a
+ * query value this operation insists on.
+ */
+function splitQuery(template) {
+    const cut = template.indexOf('?');
+    if (cut < 0) {
+        return { path: template };
+    }
+    const fixed = {};
+    for (const [name, value] of new URLSearchParams(template.slice(cut + 1))) {
+        fixed[name] = value;
+    }
+    const path = template.slice(0, cut) || '/';
+    return Object.keys(fixed).length > 0 ? { path, fixed } : { path };
+}
+/** A one-value enum, so the check, the page and the generator all see the rule. */
+function pinned(fixed) {
+    return Object.entries(fixed ?? {}).map(([name, value]) => ({
+        name,
+        in: 'query',
+        required: true,
+        schema: { type: 'string', enum: [value] },
+    }));
+}
 function build(b) {
     const success = successOf(b.op, b.dialect);
     const operationId = typeof b.op.operationId === 'string' && b.op.operationId
         ? b.op.operationId
-        : synthesizeId(b.method, b.path);
+        : synthesizeId(b.method, b.path, b.fixed);
     const operation = {
         key: '',
         source: b.source,
@@ -102,6 +134,7 @@ function build(b) {
         summary: typeof b.op.summary === 'string' ? b.op.summary : undefined,
         description: typeof b.op.description === 'string' ? b.op.description : undefined,
         params: b.params,
+        fixed: b.fixed,
         requestBody: b.body,
         success,
         paging: pagingOf(b.params, success.schema),
@@ -146,9 +179,8 @@ function canonical(value) {
     }
     return value;
 }
-function synthesizeId(method, path) {
-    const words = path
-        .split('/')
+function synthesizeId(method, path, fixed) {
+    const words = [...path.split('/'), ...Object.values(fixed ?? {})]
         .filter(Boolean)
         .map((s) => s.replace(/[{}]/g, '').replace(/[^A-Za-z0-9]+/g, '_'));
     return [method, ...words].join('_');

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@zenera/faker",
-    "version": "1.1.20",
+    "version": "1.1.21",
     "description": "Mock HTTP server for swagger/OpenAPI documents, with response bodies generated by a model.",
     "keywords": [
         "openapi",
@@ -45,7 +45,7 @@
         "@apidevtools/swagger-parser": "^12.0.0",
         "ajv": "^8.17.1",
         "ajv-formats": "^3.0.1",
-        "@zenera/cli": "^1.1.20",
-        "@zenera/neo": "^1.1.20"
+        "@zenera/cli": "^1.1.21",
+        "@zenera/neo": "^1.1.21"
     }
 }