@zenera/faker 1.1.20 → 1.1.22

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
@@ -86,20 +92,21 @@ nothing it shouldn't, and hands back `abc` again - so the client asks for the
 same page forever.
 
 The faker reads the document for this. Where an operation has a paging
-parameter (`cursor`, `page`, `offset`, `page_token`, …) and a response property
-that carries the next one (`next`, `next_cursor`, `has_more`, …), three things
-happen, all in the operation's own names:
+parameter (`cursor`, `page`, `offset`, `page_token`, …) in query or request body
+and a response property that carries the next one (`next`, `next_cursor`, `has_more`, …),
+three things happen, all in the operation's own names:
 
-- the model is told to fabricate **three pages** in total, to build the token
+- the model is told to fabricate **between 1 and 10 pages** in total, to build the token
   out of the paging parameter rather than the seed, and to end the list - null,
-  absent, or `has_more: false` where the schema leaves no other room;
+  absent, or `has_more: false` (and empty items) where the schema leaves no other room;
 - the generator is then **walked**: the faker calls it with no cursor, follows
   the token it gets back, and rejects the file if the token repeats, cycles, or
   never runs out. The diagnostics say which, and the model gets another go;
-- at request time a token identical to the one just sent is **cut** - nulled or
-  dropped, whichever the schema allows - and the request line says so. Nothing
-  is invented in its place; a generator written before this rule existed is
-  still cached, and a cache is not rebuilt because a rule changed.
+- at request time, pagination is tracked and bounded: a token identical to the one
+  just sent is **cut** (nulled or dropped), cycles are stopped, and streams are capped
+  to random 1-10 pages, returning empty results if a client loops past the end. The
+  request line narrates each cut. Nothing is invented in its place; a generator written
+  before this rule existed is still cached, and a cache is not rebuilt because a rule changed.
 
 Only paginated operations are affected. Their cache keys changed once, so they
 are written again on first use; everything else keeps the key it had.
@@ -108,8 +115,8 @@ are written again on first use; everything else keeps the key it had.
 Plenty of documents describe the envelope and never write down the parameter
 that reads it back. The first two steps cannot help there - nothing static can
 see a parameter that is not declared - but the cut still applies: it takes the
-paging parameter from the request itself, since a client only sends `?cursor=X`
-because a body handed it X.
+paging parameter from query parameters or request body, since a client only sends
+`cursor=X` because a body handed it X.
 
 ## Commands
 
@@ -117,15 +124,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/cache.d.ts

@@ -1,7 +1,9 @@
 import type { Model } from '@zenera/neo';
 import type { Box } from './box.ts';
+import type { GeneratorInput } from './envelope.ts';
 import { BuildFailed } from './generate.ts';
-import type { Operation } from './spec.ts';
+import type { ExampleRequest } from './prompt.ts';
+import { type Operation } from './spec.ts';
 import type { Checks } from './validate.ts';
 export declare const FAKER_KIND = "faker-generator";
 /** What is kept about a generator besides the code, for `zen faker cache ls`. */
@@ -12,6 +14,7 @@ export interface GeneratorMeta {
     source?: string;
     model?: string;
     attempts?: number;
+    rulesVersion?: number;
     createdAt?: string;
 }
 export interface Generator {
@@ -53,6 +56,13 @@ export interface CacheOptions {
         error: Error;
     }) => void;
 }
+export interface CacheRegenerateContext {
+    currentSource: string;
+    failingInput: GeneratorInput;
+    fault: string;
+    stderr?: string;
+    examples?: readonly ExampleRequest[];
+}
 export declare class Cache {
     #private;
     constructor(opts: CacheOptions);
@@ -65,6 +75,9 @@ export declare class Cache {
      * build and for everyone who waited on it, and true from then on.
      */
     ensure(operation: Operation): Promise<Generator>;
+    get model(): Model;
+    getSource(key: string): Promise<string | undefined>;
+    regenerate(operation: Operation, ctx: CacheRegenerateContext): Promise<Generator>;
 }
 export { BuildFailed };
 //# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -1,5 +1,6 @@
 import { Cache as Store } from '@zenera/cli/lib';
-import { build, BuildFailed } from "./generate.js";
+import { build, BuildFailed, regenerate } from "./generate.js";
+import { GENERATOR_RULES_VERSION } from "./spec.js";
 // ---------------------------------------------------------------------------
 // The cache
 //
@@ -64,6 +65,60 @@ export class Cache {
         this.#live.set(operation.key, started);
         return started;
     }
+    get model() {
+        return this.#opts.model;
+    }
+    async getSource(key) {
+        const found = this.#store.get(key);
+        return found?.source?.trim() ? found.source : undefined;
+    }
+    async regenerate(operation, ctx) {
+        const { box, model, checks, ephemeral } = this.#opts;
+        await this.#enter();
+        this.#opts.onStart?.({ operation });
+        try {
+            const built = await regenerate(operation, {
+                model,
+                box,
+                checks,
+                attempts: this.#opts.attempts,
+                currentSource: ctx.currentSource,
+                failingInput: ctx.failingInput,
+                fault: ctx.fault,
+                stderr: ctx.stderr,
+                examples: ctx.examples,
+                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+            });
+            if (!ephemeral) {
+                this.#store.put(operation.key, {
+                    source: built.source,
+                    meta: {
+                        operationId: operation.operationId,
+                        method: operation.method,
+                        path: operation.path,
+                        source: operation.source,
+                        model: model.id,
+                        attempts: built.attempts,
+                        rulesVersion: GENERATOR_RULES_VERSION,
+                        createdAt: new Date().toISOString(),
+                    },
+                });
+            }
+            this.#opts.onReady?.({ operation, cached: false, attempts: built.attempts });
+            const gen = { key: operation.key, source: built.source, cached: false };
+            this.#settled.add(operation.key);
+            this.#live.set(operation.key, Promise.resolve(gen));
+            return gen;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.#opts.onFail?.({ operation, error });
+            throw error;
+        }
+        finally {
+            this.#leave();
+        }
+    }
     async #make(operation) {
         const { box, model, checks, rebuild, ephemeral } = this.#opts;
         // Read before queueing: a cache hit costs nothing and must not wait
@@ -93,6 +148,7 @@ export class Cache {
                         source: operation.source,
                         model: model.id,
                         attempts: built.attempts,
+                        rulesVersion: GENERATOR_RULES_VERSION,
                         createdAt: new Date().toISOString(),
                     },
                 });

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 = {
@@ -32,8 +33,11 @@ const OPTIONS = {
     seed: { type: 'string' },
     timeout: { type: 'string' },
     'max-body': { type: 'string' },
+    'regen-limit': { type: 'string' },
+    'requests-dir': { type: 'string' },
     rebuild: { type: 'boolean' },
     'no-cache': { type: 'boolean' },
+    clear: { type: 'boolean' },
     quiet: { type: 'boolean' },
 };
 export const command = {
@@ -45,13 +49,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.')],
@@ -59,11 +64,16 @@ export const command = {
             ['  --concurrency <n>', dim('Generators written at once. Default 4.')],
             ['  --timeout <s>', dim('Seconds one generator may take. Default 30.')],
             ['  --max-body <n>', dim('Largest request body accepted, in bytes.')],
+            ['  --regen-limit <n>', dim('Maximum regenerations per URL on error. Default 3.')],
+            ['  --requests-dir <dir>', dim('Where to save request/response .md files.')],
             ['  --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 +85,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);
         }
@@ -91,6 +103,9 @@ async function serve(args, ctx) {
         printSpecs(setup.router.operations, ctx.cwd);
     }
     const host = values.host ?? '127.0.0.1';
+    const requestsDir = values['requests-dir']
+        ? resolve(ctx.cwd, values['requests-dir'])
+        : undefined;
     const listener = await listen({
         router: setup.router,
         cache: setup.cache,
@@ -98,7 +113,9 @@ async function serve(args, ctx) {
         box: setup.box,
         seed: number(values.seed, 'seed'),
         maxBody: number(values['max-body'], 'max-body'),
-        onRequest: values.quiet ? undefined : (line) => note(dim(line)),
+        requestsDir,
+        regenLimit: number(values['regen-limit'], 'regen-limit'),
+        onRequest: values.quiet ? undefined : (line) => note(line),
     }, host, number(values.port, 'port') ?? 8787);
     if (!values.quiet) {
         note(`${green('listening')} ${cyan(`http://${host}:${listener.port}`)} ` +
@@ -107,6 +124,7 @@ async function serve(args, ctx) {
             note(yellow(`bound to ${host} — this mock is reachable from the network`));
         }
         note(dim(`generators: ${setup.root}/${GENERATORS}`));
+        note(dim(`request logs: ${requestsDir ?? `${setup.root}/requests`}`));
     }
     // The address is the answer; the rest was narration.
     write(`http://${host}:${listener.port}`);
@@ -144,7 +162,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 +256,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 +358,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 +374,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 +389,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,8 @@
 import type { Model } from '@zenera/neo';
 import type { Box } from './box.ts';
-import type { Operation } from './spec.ts';
+import type { GeneratorInput } from './envelope.ts';
+import { type ExampleRequest } from './prompt.ts';
+import { type Operation } from './spec.ts';
 import { type Checks } from './validate.ts';
 export interface BuildOptions {
     model: Model;
@@ -15,6 +17,13 @@ export interface Built {
     source: string;
     attempts: number;
 }
+export interface RegenerateOptions extends BuildOptions {
+    currentSource: string;
+    failingInput: GeneratorInput;
+    fault: string;
+    stderr?: string;
+    examples?: readonly ExampleRequest[];
+}
 export declare class BuildFailed extends Error {
     readonly operation: Operation;
     readonly diagnostics: readonly string[];
@@ -30,6 +39,7 @@ export declare class BuildFailed extends Error {
  */
 export declare function reason(err: unknown): string;
 export declare function build(operation: Operation, opts: BuildOptions): Promise<Built>;
+export declare function regenerate(operation: Operation, opts: RegenerateOptions): Promise<Built>;
 /**
  * Models fence code even when told not to, and a stray ```python line is a
  * syntax error rather than a bad answer — not worth a round trip.

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 { instruction, regenerationInstruction, 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;
@@ -70,6 +71,53 @@ export async function build(operation, opts) {
     }
     throw new BuildFailed(operation, last);
 }
+export async function regenerate(operation, opts) {
+    const limit = Math.max(1, opts.attempts ?? 3);
+    const exampleInputs = opts.examples?.map((e) => e.input) ?? [];
+    const probes = [opts.failingInput, ...exampleInputs, ...probesFor(operation)];
+    const response = opts.checks.for(operation).response;
+    const messages = [
+        {
+            role: 'user',
+            content: [
+                {
+                    type: 'text',
+                    text: regenerationInstruction({
+                        operation,
+                        currentSource: opts.currentSource,
+                        failingInput: opts.failingInput,
+                        fault: opts.fault,
+                        stderr: opts.stderr,
+                        examples: opts.examples,
+                    }),
+                },
+            ],
+        },
+    ];
+    let last = [];
+    for (let attempt = 1; attempt <= limit; attempt++) {
+        const answer = await ask(opts, {
+            system: SYSTEM,
+            messages,
+            tools: [],
+            signal: opts.signal,
+        });
+        const source = unfence(answer.text);
+        if (!source.trim()) {
+            last = ['the answer was empty'];
+        }
+        else {
+            await opts.box.write(operation.key, source);
+            last = await judge(operation, probes, response, opts.box);
+            if (last.length === 0) {
+                return { source, attempts: attempt };
+            }
+        }
+        opts.onAttempt?.(attempt, last);
+        messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
+    }
+    throw new BuildFailed(operation, last);
+}
 /**
  * Streamed when the adapter can, and every delta is dropped: nothing here
  * renders progress. It is the *socket* that needs them.
@@ -90,9 +138,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 +148,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 +175,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 +190,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 pagination ends.`,
             ];
         }
         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);
@@ -155,7 +203,7 @@ async function walk(operation, paging, response, box) {
         input = nextPage(input, paging, token);
     }
     return [
-        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Fabricate three pages in total and set it to null on the last.`,
+        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Fabricate between 1 and 10 pages in total and set it to null on the last.`,
     ];
 }
 /**

package/dist/logger.d.ts

@@ -0,0 +1,62 @@
+import type { GeneratorInput } from './envelope.ts';
+export type ErrorKind = 'CLIENT_ERROR: NOT_FOUND' | 'CLIENT_ERROR: METHOD_NOT_ALLOWED' | 'CLIENT_ERROR: BAD_REQUEST' | 'CLIENT_ERROR: VALIDATION_FAILED' | 'CLIENT_ERROR: PAYLOAD_TOO_LARGE' | 'GENERATOR_FAULT' | 'GENERATOR_TIMEOUT' | 'GENERATOR_SCHEMA_MISMATCH' | 'GENERATOR_BUILD_FAILED' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
+export interface RequestDumpData {
+    id: string;
+    timestamp: Date;
+    durationMs: number;
+    method: string;
+    url: string;
+    pathname: string;
+    search: string;
+    operationId?: string;
+    routePath?: string;
+    pathParams?: Record<string, string>;
+    query?: Record<string, string>;
+    requestHeaders: Record<string, string>;
+    requestBody?: unknown;
+    status: number;
+    responseHeaders?: Record<string, string | number>;
+    responseBody?: unknown;
+    errorKind?: ErrorKind;
+    errorMessage?: string;
+    stderr?: string;
+    cacheStatus?: 'hit' | 'miss' | 'regenerated';
+    regenerated?: boolean;
+    regenAttempts?: number;
+    regenLimitHit?: boolean;
+    regenLimit?: number;
+    issues?: readonly unknown[];
+    note?: string;
+}
+export declare function formatTimestamp(d: Date): string;
+export declare function statusText(status: number): string;
+export declare function colorForStatus(status: number): (s: string) => string;
+export declare function colorForErrorKind(kind: ErrorKind): (s: string) => string;
+/**
+ * Saves a markdown file with all input information and output data for a request.
+ * Returns the absolute path of the generated markdown file.
+ */
+export declare function saveRequestDump(dir: string, data: RequestDumpData): Promise<string>;
+export declare function formatLogLine(data: RequestDumpData, dumpPath: string): string;
+export declare function formatRegenLimitHit(urlPath: string, limit: number, operationId?: string): string;
+export declare function formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string): string;
+export declare function formatRegenerated(urlPath: string, attempt: number, durationMs: number, operationId?: string): string;
+export interface ExampleRequest {
+    input: GeneratorInput;
+    output?: unknown;
+}
+export declare class RequestHistory {
+    #private;
+    constructor(maxExamples?: number);
+    recordSuccess(operationKey: string, input: GeneratorInput, output: unknown): void;
+    getSuccessful(operationKey: string, count?: number): ExampleRequest[];
+}
+export declare class RegenerationLimiter {
+    #private;
+    readonly limit: number;
+    constructor(limit?: number);
+    countFor(url: string): number;
+    isLimitHit(url: string): boolean;
+    increment(url: string): number;
+}
+//# sourceMappingURL=logger.d.ts.map