@zenera/faker 1.1.21 → 1.1.23

package/README.md

@@ -92,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.
@@ -114,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
 

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

@@ -33,6 +33,8 @@ 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' },
@@ -62,6 +64,8 @@ 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.')],
@@ -99,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,
@@ -106,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}`)} ` +
@@ -115,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}`);

package/dist/generate.d.ts

@@ -1,5 +1,7 @@
 import type { Model } from '@zenera/neo';
 import type { Box } from './box.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 {
@@ -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,6 +1,6 @@
 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 {
@@ -71,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.
@@ -143,7 +190,7 @@ async function walk(operation, paging, response, box) {
         }
         if (token === sent) {
             return [
-                `- ${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.`,
+                `- ${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)) {
@@ -156,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

package/dist/logger.js

@@ -0,0 +1,273 @@
+import { bold, cyan, dim, green, red, yellow } from '@zenera/cli/lib';
+import { mkdirSync } from 'node:fs';
+import { writeFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+// ---------------------------------------------------------------------------
+// Formatting Helpers
+// ---------------------------------------------------------------------------
+export function formatTimestamp(d) {
+    const pad = (n, w = 2) => String(n).padStart(w, '0');
+    const yyyy = d.getFullYear();
+    const mm = pad(d.getMonth() + 1);
+    const dd = pad(d.getDate());
+    const hh = pad(d.getHours());
+    const min = pad(d.getMinutes());
+    const ss = pad(d.getSeconds());
+    const ms = pad(d.getMilliseconds(), 3);
+    return `${yyyy}-${mm}-${dd} ${hh}:${min}:${ss}.${ms}`;
+}
+export function statusText(status) {
+    switch (status) {
+        case 200:
+            return 'OK';
+        case 201:
+            return 'Created';
+        case 202:
+            return 'Accepted';
+        case 204:
+            return 'No Content';
+        case 400:
+            return 'Bad Request';
+        case 401:
+            return 'Unauthorized';
+        case 403:
+            return 'Forbidden';
+        case 404:
+            return 'Not Found';
+        case 405:
+            return 'Method Not Allowed';
+        case 413:
+            return 'Payload Too Large';
+        case 500:
+            return 'Internal Server Error';
+        case 501:
+            return 'Not Implemented';
+        case 502:
+            return 'Bad Gateway';
+        case 504:
+            return 'Gateway Timeout';
+        default:
+            return status < 400 ? 'Success' : status < 500 ? 'Client Error' : 'Server Error';
+    }
+}
+export function colorForStatus(status) {
+    if (status < 300)
+        return green;
+    if (status < 400)
+        return cyan;
+    if (status < 500)
+        return yellow;
+    return red;
+}
+export function colorForErrorKind(kind) {
+    if (kind.startsWith('CLIENT_ERROR'))
+        return yellow;
+    if (kind === 'SUCCESS')
+        return green;
+    return (s) => red(bold(s));
+}
+// ---------------------------------------------------------------------------
+// Markdown Request / Response Dump File
+// ---------------------------------------------------------------------------
+/**
+ * Saves a markdown file with all input information and output data for a request.
+ * Returns the absolute path of the generated markdown file.
+ */
+export async function saveRequestDump(dir, data) {
+    mkdirSync(dir, { recursive: true });
+    const safePath = data.pathname.replace(/[^a-zA-Z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'root';
+    const isoPrefix = data.timestamp.toISOString().replace(/[:.]/g, '-');
+    const filename = `${isoPrefix}-${data.method.toUpperCase()}-${safePath}-${data.id}.md`;
+    const fullPath = join(dir, filename);
+    const lines = [
+        `# Request: ${data.method.toUpperCase()} ${data.pathname}${data.search}`,
+        '',
+        `- **Request ID**: \`${data.id}\``,
+        `- **Timestamp**: ${data.timestamp.toISOString()}`,
+        `- **Status**: ${data.status} ${statusText(data.status)}`,
+        `- **Duration**: ${data.durationMs}ms`,
+        `- **Operation ID**: ${data.operationId ? `\`${data.operationId}\`` : '_None_'}`,
+        `- **Route Pattern**: ${data.routePath ? `\`${data.routePath}\`` : '_None_'}`,
+        `- **Cache**: ${data.cacheStatus ?? 'n/a'}`,
+    ];
+    if (data.errorKind) {
+        lines.push(`- **Error Kind**: \`${data.errorKind}\``);
+    }
+    if (data.regenerated) {
+        lines.push(`- **Regenerated**: Yes (attempts: ${data.regenAttempts ?? 1})`);
+    }
+    if (data.regenLimitHit) {
+        lines.push(`- **Regeneration Limit**: Hit (limit: ${data.regenLimit})`);
+    }
+    if (data.note) {
+        lines.push(`- **Note**: ${data.note}`);
+    }
+    lines.push('', '---', '', '## Request Info', '');
+    lines.push('### URL & Method', '```http', `${data.method.toUpperCase()} ${data.url}`, '```', '');
+    lines.push('### Path Parameters');
+    if (data.pathParams && Object.keys(data.pathParams).length > 0) {
+        lines.push('```json', JSON.stringify(data.pathParams, null, 2), '```');
+    }
+    else {
+        lines.push('_None_');
+    }
+    lines.push('');
+    lines.push('### Query Parameters');
+    if (data.query && Object.keys(data.query).length > 0) {
+        lines.push('```json', JSON.stringify(data.query, null, 2), '```');
+    }
+    else {
+        lines.push('_None_');
+    }
+    lines.push('');
+    lines.push('### Request Headers');
+    if (data.requestHeaders && Object.keys(data.requestHeaders).length > 0) {
+        lines.push('```json', JSON.stringify(data.requestHeaders, null, 2), '```');
+    }
+    else {
+        lines.push('_None_');
+    }
+    lines.push('');
+    lines.push('### Request Body');
+    if (data.requestBody !== undefined) {
+        lines.push('```json', typeof data.requestBody === 'string'
+            ? data.requestBody
+            : JSON.stringify(data.requestBody, null, 2), '```');
+    }
+    else {
+        lines.push('_Empty_');
+    }
+    lines.push('');
+    lines.push('---', '', '## Response Data', '');
+    lines.push('### Status', '```http', `HTTP/1.1 ${data.status} ${statusText(data.status)}`, '```', '');
+    lines.push('### Response Headers');
+    if (data.responseHeaders && Object.keys(data.responseHeaders).length > 0) {
+        lines.push('```json', JSON.stringify(data.responseHeaders, null, 2), '```');
+    }
+    else {
+        lines.push('_None_');
+    }
+    lines.push('');
+    lines.push('### Response Body');
+    if (data.responseBody !== undefined) {
+        lines.push('```json', typeof data.responseBody === 'string'
+            ? data.responseBody
+            : JSON.stringify(data.responseBody, null, 2), '```');
+    }
+    else {
+        lines.push('_Empty_');
+    }
+    lines.push('');
+    if (data.errorMessage || data.stderr || (data.issues && data.issues.length > 0)) {
+        lines.push('---', '', '## Error & Diagnostics', '');
+        if (data.errorKind) {
+            lines.push(`### Classification`, `\`${data.errorKind}\``, '');
+        }
+        if (data.errorMessage) {
+            lines.push(`### Error Message`, `\`${data.errorMessage}\``, '');
+        }
+        if (data.issues && data.issues.length > 0) {
+            lines.push('### Validation Issues', '```json', JSON.stringify(data.issues, null, 2), '```', '');
+        }
+        if (data.stderr) {
+            lines.push('### Stderr / Traceback', '```', data.stderr, '```', '');
+        }
+    }
+    await writeFile(fullPath, lines.join('\n'), 'utf8');
+    return resolve(fullPath);
+}
+// ---------------------------------------------------------------------------
+// Log Line Formatter
+// ---------------------------------------------------------------------------
+export function formatLogLine(data, dumpPath) {
+    const ts = dim(`[${formatTimestamp(data.timestamp)}]`);
+    const method = cyan(bold(data.method.toUpperCase()));
+    const target = `${data.pathname}${data.search}`;
+    const statusCol = colorForStatus(data.status);
+    const status = statusCol(String(data.status));
+    const duration = dim(`${data.durationMs}ms`);
+    let tag = '';
+    if (data.errorKind) {
+        const tagCol = colorForErrorKind(data.errorKind);
+        tag = ` ${tagCol(`[${data.errorKind}]`)}`;
+    }
+    else if (data.status < 400) {
+        tag = ` ${green('[SUCCESS]')}`;
+    }
+    const note = data.note ? ` ${dim(`· ${data.note}`)}` : '';
+    const errDetail = data.errorMessage ? ` ${dim(`(${data.errorMessage})`)}` : '';
+    const firstLine = `${ts} ${method} ${target} ${status} ${duration}${tag}${note}${errDetail}`;
+    const lines = [firstLine];
+    if (data.stderr && data.stderr.trim()) {
+        const lastStderr = data.stderr.trim().split('\n').slice(-4).join('\n    ');
+        lines.push(`  ${dim('stderr:')} ${red(lastStderr)}`);
+    }
+    if (dumpPath) {
+        const fileUrl = `file://${resolve(dumpPath)}`;
+        lines.push(`  ${dim('↳ dump:')} ${cyan(fileUrl)}`);
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Special Log Messages
+// ---------------------------------------------------------------------------
+export function formatRegenLimitHit(urlPath, limit, operationId) {
+    const ts = dim(`[${formatTimestamp(new Date())}]`);
+    const op = operationId ? ` (${operationId})` : '';
+    return `${ts} ${red(bold('[REGENERATION_LIMIT_HIT]'))} Maximum regeneration limit (${limit}) reached for URL "${urlPath}"${op}. Halting further regeneration attempts.`;
+}
+export function formatRegenerating(urlPath, attempt, limit, operationId, reason) {
+    const ts = dim(`[${formatTimestamp(new Date())}]`);
+    const op = operationId ? ` (${operationId})` : '';
+    const r = reason ? ` [${reason}]` : '';
+    return `${ts} ${yellow(bold('[REGENERATING]'))} Error in generator for "${urlPath}"${op}${r}. Attempting regeneration (${attempt}/${limit})...`;
+}
+export function formatRegenerated(urlPath, attempt, durationMs, operationId) {
+    const ts = dim(`[${formatTimestamp(new Date())}]`);
+    const op = operationId ? ` (${operationId})` : '';
+    return `${ts} ${green(bold('[REGENERATED]'))} Successfully regenerated generator for "${urlPath}"${op} in attempt ${attempt} (${durationMs}ms).`;
+}
+export class RequestHistory {
+    #successful = new Map();
+    #maxExamples;
+    constructor(maxExamples = 5) {
+        this.#maxExamples = maxExamples;
+    }
+    recordSuccess(operationKey, input, output) {
+        let list = this.#successful.get(operationKey);
+        if (!list) {
+            list = [];
+            this.#successful.set(operationKey, list);
+        }
+        list.push({ input, output });
+        if (list.length > this.#maxExamples) {
+            list.shift();
+        }
+    }
+    getSuccessful(operationKey, count = 2) {
+        const list = this.#successful.get(operationKey);
+        if (!list || list.length === 0) {
+            return [];
+        }
+        return list.slice(-count);
+    }
+}
+export class RegenerationLimiter {
+    #counts = new Map();
+    limit;
+    constructor(limit = 3) {
+        this.limit = limit;
+    }
+    countFor(url) {
+        return this.#counts.get(url) ?? 0;
+    }
+    isLimitHit(url) {
+        return (this.#counts.get(url) ?? 0) >= this.limit;
+    }
+    increment(url) {
+        const next = (this.#counts.get(url) ?? 0) + 1;
+        this.#counts.set(url, next);
+        return next;
+    }
+}
+//# sourceMappingURL=logger.js.map