@zenera/faker 1.1.20 → 1.1.22

package/dist/server.js

@@ -1,8 +1,12 @@
-import { createHash, randomInt } from 'node:crypto';
+import { createHash, randomInt, randomUUID } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
+import { join } from 'node:path';
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
-import { cutLoop, pagingSeen } from "./paging.js";
+import { formatLogLine, formatRegenerated, formatRegenerating, formatRegenLimitHit, RegenerationLimiter, RequestHistory, saveRequestDump, } from "./logger.js";
+import { indexPage } from "./page.js";
+import { cutLoop, getSentToken, PaginationLimiter, pagingSeen, } from "./paging.js";
 import { describeIssues, issues } from "./validate.js";
 // ---------------------------------------------------------------------------
 // The server
@@ -22,11 +26,22 @@ const REDACTED = /^(authorization|cookie|set-cookie|proxy-authorization)$/i;
 const SECRETISH = /key|token|secret|password|credential/i;
 const DEFAULT_MAX_BODY = 1024 * 1024;
 export function build(opts) {
+    const history = opts.history ?? new RequestHistory();
+    const limiter = opts.limiter ?? new RegenerationLimiter(opts.regenLimit ?? 3);
+    const paginationLimiter = opts.paginationLimiter ?? new PaginationLimiter(opts.maxPages);
+    const requestsDir = opts.requestsDir ?? join(opts.box.root, 'requests');
+    const enriched = {
+        ...opts,
+        history,
+        limiter,
+        paginationLimiter,
+        requestsDir,
+    };
     return createServer((req, res) => {
-        handle(req, res, opts).catch((err) => {
-            // Nothing below is expected to throw; if it does, the client still
-            // gets an answer and the operator still gets the reason.
-            send(res, 500, { error: err instanceof Error ? err.message : String(err) });
+        handle(req, res, enriched).catch((err) => {
+            const message = err instanceof Error ? err.message : String(err);
+            send(res, 500, { error: message });
+            opts.onRequest?.(`${req.method ?? 'GET'} ${req.url ?? '/'} 500 [SERVER_INTERNAL_ERROR] ${message}`);
         });
     });
 }
@@ -53,27 +68,115 @@ export async function listen(opts, host, port) {
 // ---------------------------------------------------------------------------
 async function handle(req, res, opts) {
     const started = Date.now();
+    const timestamp = new Date(started);
+    const id = randomUUID().slice(0, 8);
     const url = new URL(req.url ?? '/', 'http://localhost');
     const method = (req.method ?? 'GET').toLowerCase();
-    // The search string is part of the request: without it a 400 caused by a
-    // query parameter is unexplainable from the log.
-    const say = (status, what) => opts.onRequest?.(`${req.method} ${url.pathname}${url.search} ${status} ${Date.now() - started}ms ${what}`);
+    const finish = async (status, meta) => {
+        const responseHeaders = Object.fromEntries(Object.entries(res.getHeaders()).map(([k, v]) => [k, String(v)]));
+        const dumpData = {
+            id,
+            timestamp,
+            durationMs: Date.now() - started,
+            method,
+            url: req.url ?? '/',
+            pathname: url.pathname,
+            search: url.search,
+            operationId: meta.operationId,
+            routePath: meta.routePath,
+            pathParams: meta.pathParams,
+            query: meta.query ?? Object.fromEntries(url.searchParams),
+            requestHeaders: safeHeaders(req),
+            requestBody: meta.requestBody,
+            status,
+            responseHeaders,
+            responseBody: meta.responseBody,
+            errorKind: meta.errorKind,
+            errorMessage: meta.errorMessage,
+            stderr: meta.stderr,
+            cacheStatus: meta.cacheStatus,
+            regenerated: meta.regenerated,
+            regenAttempts: meta.regenAttempts,
+            regenLimitHit: meta.regenLimitHit,
+            regenLimit: opts.limiter?.limit,
+            issues: meta.issues,
+            note: meta.note,
+        };
+        let dumpPath = '';
+        const shouldDump = Boolean(opts.requestsDir &&
+            url.pathname !== '/' &&
+            !url.pathname.startsWith('/__faker/') &&
+            meta.operationId);
+        if (shouldDump) {
+            try {
+                dumpPath = await saveRequestDump(opts.requestsDir, dumpData);
+            }
+            catch {
+                // Ignore filesystem dump write failures so server remains operational
+            }
+        }
+        if (opts.onRequest) {
+            opts.onRequest(formatLogLine(dumpData, dumpPath));
+        }
+    };
     if (url.pathname.startsWith('/__faker/')) {
         introspect(url.pathname, res, opts);
-        say(200, 'introspection');
+        await finish(200, { note: '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')) {
+            const end = prepareHtml(res, indexPage(opts.router.operations));
+            await finish(200, { note: 'index' });
+            end();
+            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) {
+            const bodyObj = {
+                error: `${req.method} ${url.pathname} is only defined with a query`,
+                expects,
+            };
+            const end = prepareSend(res, 404, bodyObj);
+            await finish(404, {
+                errorKind: 'CLIENT_ERROR: NOT_FOUND',
+                errorMessage: `expects ${expects.join(' ')}`,
+                responseBody: bodyObj,
+                note: `expects ${expects.join(' ')}`,
+            });
+            end();
+            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');
+            const bodyObj = { error: `${req.method} is not defined for ${url.pathname}` };
+            const end = prepareSend(res, 405, bodyObj);
+            await finish(405, {
+                errorKind: 'CLIENT_ERROR: METHOD_NOT_ALLOWED',
+                errorMessage: 'no such method',
+                responseBody: bodyObj,
+                note: 'no such method',
+            });
+            end();
             return;
         }
-        send(res, 404, { error: `no operation matches ${req.method} ${url.pathname}` });
-        say(404, 'no route');
+        const bodyObj = {
+            error: `no operation matches ${req.method} ${url.pathname}`,
+        };
+        const end = prepareSend(res, 404, bodyObj);
+        await finish(404, {
+            errorKind: 'CLIENT_ERROR: NOT_FOUND',
+            errorMessage: 'no route',
+            responseBody: bodyObj,
+            note: 'no route',
+        });
+        end();
         return;
     }
     const { operation, pathParams } = match;
@@ -84,20 +187,51 @@ async function handle(req, res, opts) {
     }
     catch (err) {
         const message = err instanceof Error ? err.message : String(err);
-        send(res, message.includes('too large') ? 413 : 400, { error: message });
-        say(400, 'bad body');
+        const status = message.includes('too large') ? 413 : 400;
+        const errorKind = status === 413 ? 'CLIENT_ERROR: PAYLOAD_TOO_LARGE' : 'CLIENT_ERROR: BAD_REQUEST';
+        const bodyObj = { error: message };
+        const end = prepareSend(res, status, bodyObj);
+        await finish(status, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            errorKind,
+            errorMessage: message,
+            responseBody: bodyObj,
+            note: status === 413 ? 'body too large' : 'bad body',
+        });
+        end();
         return;
     }
     const problems = check(operation, opts.checks, pathParams, url.searchParams, body);
     if (problems.length > 0) {
-        send(res, 400, { error: describeIssues(problems), issues: problems });
-        say(400, describeIssues(problems));
+        const desc = describeIssues(problems);
+        const bodyObj = { error: desc, issues: problems };
+        const end = prepareSend(res, 400, bodyObj);
+        await finish(400, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            errorKind: 'CLIENT_ERROR: VALIDATION_FAILED',
+            errorMessage: desc,
+            issues: problems,
+            responseBody: bodyObj,
+            note: desc,
+        });
+        end();
         return;
     }
     if (!operation.success.schema) {
         res.statusCode = operation.success.status;
+        await finish(operation.success.status, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            note: 'no body declared',
+        });
         res.end();
-        say(operation.success.status, 'no body declared');
         return;
     }
     let generator;
@@ -107,15 +241,27 @@ async function handle(req, res, opts) {
     catch (err) {
         const status = err instanceof BuildFailed ? 501 : 500;
         const detail = reason(err);
-        send(res, status, {
+        const bodyObj = {
             error: `no generator for ${operation.operationId}`,
             detail,
             diagnostics: err instanceof BuildFailed ? err.diagnostics : undefined,
+        };
+        const end = prepareSend(res, status, bodyObj);
+        await finish(status, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            requestBody: body,
+            errorKind: 'GENERATOR_BUILD_FAILED',
+            errorMessage: `no generator: ${detail}`,
+            responseBody: bodyObj,
+            note: `no generator: ${detail}`,
         });
-        say(status, `no generator: ${detail}`);
+        end();
         return;
     }
     res.setHeader('x-faker-cache', generator.cached ? 'hit' : 'miss');
+    let cacheStatus = generator.cached ? 'hit' : 'miss';
     const input = {
         operationId: operation.operationId,
         method: operation.method,
@@ -126,33 +272,179 @@ async function handle(req, res, opts) {
         body,
         seed: seedFor(opts.seed, operation, pathParams, url.searchParams),
     };
-    const outcome = await opts.box.run(operation.key, input);
+    let outcome = await opts.box.run(operation.key, input);
+    const responseValidator = opts.checks.for(operation).response;
+    let schemaMismatch = false;
+    if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
+        schemaMismatch = true;
+        const desc = describeIssues(issues('', responseValidator.errors));
+        outcome = {
+            ok: false,
+            fault: `output does not match response schema — ${desc}`,
+            stderr: outcome.stderr,
+            durationMs: outcome.durationMs,
+            value: outcome.value,
+        };
+    }
     if (!outcome.ok) {
-        send(res, 502, {
-            error: `the generator for ${operation.operationId} ${outcome.fault}`,
-            stderr: outcome.stderr || undefined,
-        });
-        say(502, 'generator faulted');
-        return;
+        const urlKey = url.pathname;
+        const errorKind = outcome.fault?.includes('longer than')
+            ? 'GENERATOR_TIMEOUT'
+            : schemaMismatch
+                ? 'GENERATOR_SCHEMA_MISMATCH'
+                : 'GENERATOR_FAULT';
+        // Check regeneration limit for this URL
+        if (opts.limiter.isLimitHit(urlKey)) {
+            opts.onRequest?.(formatRegenLimitHit(urlKey, opts.limiter.limit, operation.operationId));
+            const bodyObj = {
+                error: `the generator for ${operation.operationId} ${outcome.fault}`,
+                stderr: outcome.stderr || undefined,
+                regenerationLimitHit: true,
+                regenerationLimit: opts.limiter.limit,
+            };
+            const end = prepareSend(res, 502, bodyObj);
+            await finish(502, {
+                operationId: operation.operationId,
+                routePath: operation.path,
+                pathParams,
+                requestBody: body,
+                errorKind,
+                errorMessage: `${outcome.fault} (regeneration limit reached)`,
+                stderr: outcome.stderr,
+                responseBody: bodyObj,
+                cacheStatus,
+                regenLimitHit: true,
+                note: 'generator faulted (limit hit)',
+            });
+            end();
+            return;
+        }
+        const attempt = opts.limiter.increment(urlKey);
+        opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault));
+        const regenStarted = Date.now();
+        let currentSource = generator.source;
+        if (!currentSource?.trim()) {
+            currentSource = (await opts.cache.getSource?.(operation.key)) ?? '';
+        }
+        if (!currentSource?.trim()) {
+            try {
+                currentSource = await readFile(opts.box.sourceOf(operation.key), 'utf8');
+            }
+            catch {
+                currentSource = '# generator';
+            }
+        }
+        const examples = opts.history.getSuccessful(operation.key, 2);
+        try {
+            await opts.cache.regenerate(operation, {
+                currentSource,
+                failingInput: input,
+                fault: outcome.fault ?? 'generator faulted',
+                stderr: outcome.stderr,
+                examples,
+            });
+            cacheStatus = 'regenerated';
+            res.setHeader('x-faker-cache', 'regenerated');
+            opts.onRequest?.(formatRegenerated(urlKey, attempt, Date.now() - regenStarted, operation.operationId));
+            // Re-run the request with the newly regenerated generator
+            outcome = await opts.box.run(operation.key, input);
+            if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
+                outcome = {
+                    ok: false,
+                    fault: 'output does not match response schema after regeneration',
+                    stderr: outcome.stderr,
+                    durationMs: outcome.durationMs,
+                };
+            }
+        }
+        catch (regenErr) {
+            const detail = reason(regenErr);
+            const bodyObj = {
+                error: `regeneration failed for ${operation.operationId}: ${detail}`,
+                stderr: outcome.stderr || undefined,
+                regenerated: false,
+            };
+            const end = prepareSend(res, 502, bodyObj);
+            await finish(502, {
+                operationId: operation.operationId,
+                routePath: operation.path,
+                pathParams,
+                requestBody: body,
+                errorKind: 'REGENERATION_FAILED',
+                errorMessage: `regeneration failed: ${detail}`,
+                stderr: outcome.stderr,
+                responseBody: bodyObj,
+                cacheStatus,
+                regenAttempts: attempt,
+                note: 'regeneration failed',
+            });
+            end();
+            return;
+        }
+        if (!outcome.ok) {
+            const bodyObj = {
+                error: `the regenerated generator for ${operation.operationId} ${outcome.fault}`,
+                stderr: outcome.stderr || undefined,
+                regenerated: true,
+            };
+            const end = prepareSend(res, 502, bodyObj);
+            await finish(502, {
+                operationId: operation.operationId,
+                routePath: operation.path,
+                pathParams,
+                requestBody: body,
+                errorKind,
+                errorMessage: `regenerated generator ${outcome.fault}`,
+                stderr: outcome.stderr,
+                responseBody: bodyObj,
+                cacheStatus,
+                regenerated: true,
+                regenAttempts: attempt,
+                note: 'regenerated generator faulted',
+            });
+            end();
+            return;
+        }
     }
-    const note = generator.cached ? 'hit' : 'miss';
-    const looped = cut(operation, outcome.value, url.searchParams);
-    send(res, operation.success.status, outcome.value);
-    say(operation.success.status, looped ? `${note} · cut a looping page token` : note);
+    const note = cacheStatus;
+    const streamKey = `${operation.key}:${req.socket.remoteAddress || 'local'}`;
+    const cutResult = cut(operation, outcome.value, url.searchParams, body, opts.paginationLimiter, streamKey);
+    opts.history.recordSuccess(operation.key, input, outcome.value);
+    const end = prepareSend(res, operation.success.status, outcome.value);
+    await finish(operation.success.status, {
+        operationId: operation.operationId,
+        routePath: operation.path,
+        pathParams,
+        requestBody: body,
+        responseBody: outcome.value,
+        cacheStatus,
+        regenerated: cacheStatus === 'regenerated',
+        note: cutResult?.cut ? `${note} · ${cutResult.reason}` : note,
+    });
+    end();
 }
 /**
  * The generator on disk was written before the pagination rule existed, and a
  * cache is not rebuilt just because the rule changed. A body offering back the
  * token it was handed is therefore still possible, and it is the one bug here
  * that costs the client rather than the mock: it hangs.
+ *
+ * In addition, pagination is tracked and capped to prevent infinite loops (random
+ * 1-10 max pages by default) and repetitive cycling tokens.
  */
-function cut(operation, value, query) {
-    const paging = operation.paging ?? pagingSeen(operation.params, operation.success.schema, query);
+function cut(operation, value, query, body, limiter, streamKey = 'default') {
+    const paging = operation.paging ?? pagingSeen(operation.params, operation.success.schema, query, body);
     if (!paging) {
-        return false;
+        return undefined;
+    }
+    const sent = getSentToken(query, body, paging);
+    if (limiter) {
+        return limiter.process(operation.key, streamKey, sent, value, paging);
     }
-    const sent = query.get(paging.param);
-    return sent !== null && cutLoop(value, paging, sent);
+    if (sent !== undefined && cutLoop(value, paging, sent)) {
+        return { cut: true, reason: 'cut a looping page token' };
+    }
+    return undefined;
 }
 function check(operation, checks, pathParams, query, body) {
     const compiled = checks.for(operation);
@@ -264,11 +556,24 @@ function introspect(pathname, res, opts) {
     }
     send(res, 404, { error: `no such endpoint: ${pathname}` });
 }
-function send(res, status, value) {
+function prepareSend(res, status, value) {
     const text = `${JSON.stringify(value, null, 2)}\n`;
     res.statusCode = status;
     res.setHeader('content-type', 'application/json; charset=utf-8');
     res.setHeader('content-length', Buffer.byteLength(text));
-    res.end(text);
+    return () => res.end(text);
+}
+function send(res, status, value) {
+    prepareSend(res, status, value)();
+}
+function prepareHtml(res, text) {
+    res.statusCode = 200;
+    res.setHeader('content-type', 'text/html; charset=utf-8');
+    res.setHeader('content-length', Buffer.byteLength(text));
+    return () => res.end(text);
+}
+/** Node drops the body itself when the request was a HEAD. */
+function html(res, text) {
+    prepareHtml(res, 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

@@ -1,6 +1,11 @@
 import { CliError } from '@zenera/cli/lib';
 import { type Paging } from './paging.ts';
 import { type Schema } from './schema.ts';
+/**
+ * Version of generator prompt rules and environment contracts.
+ * Bumping this invalidates cached Python generators and triggers regeneration.
+ */
+export declare const GENERATOR_RULES_VERSION = 2;
 export declare const METHODS: readonly ["get", "put", "post", "delete", "patch", "head", "options"];
 export type Method = (typeof METHODS)[number];
 export type ParamIn = 'path' | 'query' | 'header' | 'cookie';
@@ -23,6 +28,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 +48,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