@zenera/gym 0.0.0-stage → 1.1.38

package/dist/logger.js

@@ -0,0 +1,321 @@
+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 503:
+            return 'Service Unavailable';
+        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}`);
+    }
+    if (data.buildDump) {
+        lines.push(`- **Build report**: [${data.buildDump}](file://${data.buildDump})`);
+    }
+    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.hint) {
+            lines.push(`### What to do`, data.hint, '');
+        }
+        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);
+}
+export async function saveBuildDump(dir, data) {
+    mkdirSync(dir, { recursive: true });
+    const safePath = data.path.replace(/[^a-zA-Z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'root';
+    const isoPrefix = data.started.toISOString().replace(/[:.]/g, '-');
+    const what = data.regeneration ? 'regen' : 'build';
+    const fullPath = join(dir, `${isoPrefix}-${what}-${data.method.toUpperCase()}-${safePath}.md`);
+    const outcome = data.gaveUp
+        ? `gave up after ${data.attempts.length} of ${data.limit}`
+        : `attempt ${data.attempts.length} of ${data.limit} rejected`;
+    const lines = [
+        `# ${data.regeneration ? 'Regeneration' : 'Build'}: ` +
+            `${data.method.toUpperCase()} ${data.path}`,
+        '',
+        `- **Operation ID**: ${data.operationId ? `\`${data.operationId}\`` : '_None_'}`,
+        `- **Key**: \`${data.key}\``,
+        `- **Started**: ${data.started.toISOString()}`,
+        `- **Model**: ${data.model ? `\`${data.model}\`` : '_Unknown_'}`,
+        `- **Outcome**: ${outcome}`,
+        '',
+    ];
+    for (const a of data.attempts) {
+        const elapsed = Math.max(0, a.at.getTime() - data.started.getTime());
+        lines.push('---', '', `## Attempt ${a.attempt} of ${data.limit}`, '', `_Rejected ${a.at.toISOString()}, ${elapsed}ms into the build._`, '', '### Why it was rejected', '', ...(a.diagnostics.length > 0
+            ? a.diagnostics.map((d) => (d.trimStart().startsWith('-') ? d : `- ${d}`))
+            : ['_No diagnostics._']), '', '### Generator', '', '```python', a.source, '```', '');
+    }
+    await writeFile(fullPath, lines.join('\n'), 'utf8');
+    return resolve(fullPath);
+}
+export function formatDumpPath(label, path) {
+    return `  ${dim(`↳ ${label}:`)} ${cyan(`file://${resolve(path)}`)}`;
+}
+// ---------------------------------------------------------------------------
+// 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 (data.hint) {
+        lines.push(`  ${dim('↳ fix:')} ${yellow(data.hint)}`);
+    }
+    if (dumpPath) {
+        const fileUrl = `file://${resolve(dumpPath)}`;
+        lines.push(`  ${dim('↳ dump:')} ${cyan(fileUrl)}`);
+    }
+    if (data.buildDump) {
+        lines.push(formatDumpPath('build', data.buildDump));
+    }
+    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, stderr) {
+    const ts = dim(`[${formatTimestamp(new Date())}]`);
+    const op = operationId ? ` (${operationId})` : '';
+    const r = reason ? ` [${reason}]` : '';
+    const head = `${ts} ${yellow(bold('[REGENERATING]'))} Error in generator for "${urlPath}"${op}${r}. Attempting regeneration (${attempt}/${limit})...`;
+    const tail = stderr?.trim().split('\n').slice(-3).join('\n    ');
+    return tail ? `${head}\n  ${dim('stderr:')} ${red(tail)}` : head;
+}
+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

package/dist/main.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=main.d.ts.map

package/dist/main.js

@@ -0,0 +1,363 @@
+#!/usr/bin/env node
+import { rmSync } from 'node:fs';
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { bold, CliError, cyan, dim, EXIT, fail, green, invokedAs, json, note, ownedContainers, parse, paths, printBanner, red, removeContainers, split, table, usageError, write, writeAll, yellow, } from 'zenera-cli/lib';
+import { GENERATORS } from "./box.js";
+import { reason } from "./generate.js";
+import { listen } from "./server.js";
+import { open } from "./setup.js";
+import { SpecError } from "./spec.js";
+// ---------------------------------------------------------------------------
+// zfake — a mock API from a specification
+//
+// A separate binary rather than a `zen` subcommand. `zen` runs agent projects
+// and everything in it is shaped by that; this is a server, it stays up, and
+// the only thing the two genuinely share is where credentials live. Putting it
+// under `zen` would have meant one command that means two different things.
+// ---------------------------------------------------------------------------
+/** What the user typed: `zfake`, `zen-fake`, `zen-faker` or `zenera-fake`. */
+const NAME = invokedAs('zfake');
+const USAGE = `${NAME} <serve|build|cache> [spec...] [options]`;
+const BANNER = {
+    head: 'Zenera',
+    accent: 'Faker',
+    subtitle: 'Mock API Server',
+};
+const OPTIONS = {
+    port: { type: 'string' },
+    host: { type: 'string' },
+    model: { type: 'string' },
+    image: { type: 'string' },
+    cache: { type: 'string' },
+    attempts: { type: 'string' },
+    concurrency: { type: 'string' },
+    seed: { type: 'string' },
+    timeout: { type: 'string' },
+    'max-body': { type: 'string' },
+    rebuild: { type: 'boolean' },
+    'no-cache': { type: 'boolean' },
+    quiet: { type: 'boolean' },
+    json: { type: 'boolean' },
+};
+async function main(argv) {
+    const { name, after } = split(argv);
+    if (!name || name === 'help' || name === '--help' || name === '-h') {
+        usage();
+        return name ? EXIT.ok : EXIT.usage;
+    }
+    try {
+        switch (name) {
+            case 'serve':
+                return await serve(after);
+            case 'build':
+                return await warm(after);
+            case 'cache':
+                return await cache(after);
+            default:
+                throw usageError(`unknown command "${name}"`, USAGE);
+        }
+    }
+    catch (err) {
+        if (err instanceof CliError) {
+            fail(err.message, err.hint);
+            return err.code;
+        }
+        if (err instanceof SpecError) {
+            fail(err.message, err.hint);
+            return EXIT.invalid;
+        }
+        fail(err instanceof Error ? err.message : String(err));
+        return EXIT.failed;
+    }
+}
+// ---------------------------------------------------------------------------
+// serve
+// ---------------------------------------------------------------------------
+async function serve(args) {
+    const { values, positionals } = parse(args, OPTIONS, `${NAME} serve <spec...>`);
+    const loud = !values.quiet && !values.json;
+    if (loud) {
+        printBanner(BANNER);
+    }
+    const setup = await start(values, positionals, 'serve');
+    if (loud) {
+        printSpecs(setup.router.operations);
+    }
+    const host = values.host ?? '127.0.0.1';
+    const listener = await listen({
+        router: setup.router,
+        cache: setup.cache,
+        checks: setup.checks,
+        box: setup.box,
+        seed: number(values.seed, 'seed'),
+        maxBody: number(values['max-body'], 'max-body'),
+        onRequest: values.quiet ? undefined : (line) => note(dim(line)),
+    }, host, number(values.port, 'port') ?? 8787);
+    if (!values.quiet) {
+        note(`${green('listening')} ${cyan(`http://${host}:${listener.port}`)} ` +
+            dim(`${setup.router.operations.length} operations`));
+        if (host !== '127.0.0.1' && host !== 'localhost') {
+            note(yellow(`bound to ${host} — this mock is reachable from the network`));
+        }
+        note(dim(`generators: ${setup.root}/${GENERATORS}`));
+    }
+    // The address is the answer; the rest was narration.
+    write(`http://${host}:${listener.port}`);
+    await until(['SIGINT', 'SIGTERM']);
+    if (!values.quiet) {
+        note(dim('stopping'));
+    }
+    await listener.close();
+    await setup.close();
+    return EXIT.ok;
+}
+/** Resolves when one of the signals arrives, and stops listening for them. */
+function until(signals) {
+    return new Promise((settle) => {
+        const done = () => {
+            for (const s of signals) {
+                process.off(s, done);
+            }
+            settle();
+        };
+        for (const s of signals) {
+            process.once(s, done);
+        }
+    });
+}
+// ---------------------------------------------------------------------------
+// build — every generator, up front
+// ---------------------------------------------------------------------------
+async function warm(args) {
+    const { values, positionals } = parse(args, OPTIONS, `${NAME} build <spec...>`);
+    const loud = !values.quiet && !values.json;
+    if (loud) {
+        printBanner(BANNER);
+    }
+    const setup = await start(values, positionals, 'build');
+    if (loud) {
+        printSpecs(setup.router.operations);
+    }
+    const results = [];
+    try {
+        for (const operation of setup.router.operations) {
+            const id = `${operation.method.toUpperCase()} ${operation.path}`;
+            if (!operation.success.schema) {
+                results.push({ operation: id, status: 'skipped', detail: 'no response body' });
+                continue;
+            }
+            try {
+                const generator = await setup.cache.ensure(operation);
+                results.push({ operation: id, status: generator.cached ? 'cached' : 'built' });
+            }
+            catch (err) {
+                results.push({
+                    operation: id,
+                    status: 'failed',
+                    detail: reason(err),
+                });
+            }
+        }
+    }
+    finally {
+        await setup.close();
+    }
+    if (values.json) {
+        json(results);
+    }
+    else {
+        writeAll(table(results.map((r) => [
+            `  ${mark(r.status)}`,
+            r.operation,
+            dim(r.detail?.slice(0, 100) ?? ''),
+        ])));
+    }
+    return results.some((r) => r.status === 'failed') ? EXIT.failed : EXIT.ok;
+}
+const mark = (status) => status === 'failed' ? red('failed') : status === 'skipped' ? dim('skipped') : green(status);
+// ---------------------------------------------------------------------------
+// cache
+// ---------------------------------------------------------------------------
+async function cache(args) {
+    const { values, positionals } = parse(args, OPTIONS, `${NAME} cache <ls|clear>`);
+    const root = values.cache ?? paths.faker();
+    const sub = positionals[0] ?? 'ls';
+    if (sub === 'ls') {
+        const entries = await listGenerators(root);
+        if (values.json) {
+            json(entries);
+            return EXIT.ok;
+        }
+        if (entries.length === 0) {
+            note('nothing cached yet');
+            return EXIT.ok;
+        }
+        writeAll(table([
+            [bold('KEY'), bold('OPERATION'), bold('MODEL'), bold('TRIES')],
+            ...entries.map((e) => [
+                e.key,
+                `${e.method?.toUpperCase() ?? '?'} ${e.path ?? ''}`,
+                dim(e.model ?? '—'),
+                dim(String(e.attempts ?? '—')),
+            ]),
+        ]));
+        return EXIT.ok;
+    }
+    if (sub === 'clear') {
+        rmSync(join(root, GENERATORS), { recursive: true, force: true });
+        // The container is named after its configuration, so a stale one would
+        // otherwise sit there stopped forever with nothing pointing at it.
+        // `zn-<key>-<digest>` is the shape, and this one's key is `faker`.
+        const mine = (await ownedContainers()).filter((c) => c.name.startsWith('zn-faker-'));
+        if (mine.length > 0) {
+            await removeContainers(mine.map((c) => c.name));
+        }
+        note(`${green('cleared')} ${dim(root)}`);
+        return EXIT.ok;
+    }
+    throw usageError(`unknown cache command "${sub}"`, `${NAME} cache <ls|clear>`);
+}
+async function listGenerators(root) {
+    let keys;
+    try {
+        keys = await readdir(join(root, GENERATORS));
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const key of keys.sort()) {
+        try {
+            const meta = JSON.parse(await readFile(join(root, GENERATORS, key, 'meta.json'), 'utf8'));
+            out.push({ key, ...meta });
+        }
+        catch {
+            out.push({ key });
+        }
+    }
+    return out;
+}
+function summarize(operations) {
+    const by = new Map();
+    for (const op of operations) {
+        let stat = by.get(op.source);
+        if (!stat) {
+            stat = { source: op.source, paths: new Set(), methods: 0, functions: 0 };
+            by.set(op.source, stat);
+        }
+        stat.paths.add(op.path);
+        stat.methods += 1;
+        if (op.success.schema) {
+            stat.functions += 1;
+        }
+    }
+    return [...by.values()];
+}
+const HEADERS = ['PATHS', 'METHODS', 'FUNCTIONS'];
+function printSpecs(operations) {
+    const stats = summarize(operations);
+    const rows = stats.map((s) => ({
+        name: relative(process.cwd(), s.source) || s.source,
+        cells: [s.paths.size, s.methods, s.functions],
+    }));
+    if (rows.length > 1) {
+        rows.push({
+            name: 'total',
+            cells: HEADERS.map((_, i) => rows.reduce((n, r) => n + r.cells[i], 0)),
+        });
+    }
+    // Numbers are padded before they are styled: a colour code has no width,
+    // and `table` cannot know that.
+    const widths = HEADERS.map((h, i) => Math.max(h.length, ...rows.map((r) => String(r.cells[i]).length)));
+    const lines = table([
+        [bold('SPEC'), ...HEADERS.map((h, i) => bold(h.padStart(widths[i])))],
+        ...rows.map((r) => [
+            r.name === 'total' ? dim(r.name) : r.name,
+            ...r.cells.map((c, i) => String(c).padStart(widths[i])),
+        ]),
+    ]);
+    note('');
+    for (const line of lines) {
+        note(`  ${line}`);
+    }
+    note('');
+}
+// ---------------------------------------------------------------------------
+// Shared
+// ---------------------------------------------------------------------------
+async function start(values, specs, what) {
+    const loud = !values.quiet && !values.json;
+    return open({
+        specs,
+        cwd: process.cwd(),
+        cache: values.cache,
+        model: values.model,
+        image: values.image,
+        attempts: number(values.attempts, 'attempts'),
+        concurrency: number(values.concurrency, 'concurrency'),
+        timeout: number(values.timeout, 'timeout'),
+        rebuild: values.rebuild,
+        ephemeral: values['no-cache'],
+        onImageBuild: loud
+            ? (tag) => note(`${dim('building')} ${tag} ${dim('— once, then cached')}`)
+            : undefined,
+        events: {
+            onStart: loud
+                ? ({ operation }) => note(`${dim('writing a generator for')} ${operation.method.toUpperCase()} ${operation.path}`)
+                : undefined,
+            onAttempt: loud
+                ? ({ operation, attempt, diagnostics }) => note(`  ${yellow(`attempt ${attempt} failed`)} ${dim(`${operation.operationId}: ${(diagnostics ?? []).join(' ').slice(0, 160)}`)}`)
+                : undefined,
+            onReady: loud && what === 'serve'
+                ? ({ operation, cached }) => cached
+                    ? undefined
+                    : note(`  ${green('ready')} ${dim(operation.operationId)}`)
+                : undefined,
+            onFail: loud
+                ? ({ operation, error }) => note(`  ${red('gave up')} ${dim(operation.operationId)} ${reason(error)}`)
+                : undefined,
+        },
+    });
+}
+function number(raw, what) {
+    if (raw === undefined) {
+        return undefined;
+    }
+    const value = Number(raw);
+    if (!Number.isFinite(value)) {
+        throw usageError(`--${what} must be a number, got "${raw}"`);
+    }
+    return value;
+}
+function usage() {
+    printBanner(BANNER);
+    write(`${bold(NAME)} ${dim('— a mock API from an openapi/swagger document')}`);
+    write(`\n${bold('Usage')}\n  ${USAGE}`);
+    write(`\n${bold('Commands')}`);
+    writeAll(table([
+        ['  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.')],
+    ]));
+    write(`\n${bold('Options')}`);
+    writeAll(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.')],
+        ['  --image <ref>', dim('Skip the baked image and use this one.')],
+        ['  --cache <dir>', dim('Where generators live. Default ~/.zenera/neo/faker.')],
+        ['  --seed <n>', dim('Answer the same request the same way every time.')],
+        ['  --attempts <n>', dim('Tries per generator before giving up. Default 3.')],
+        ['  --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.')],
+        ['  --rebuild', dim('Ignore what is cached and write it again.')],
+        ['  --no-cache', dim('Do not record what is written.')],
+        ['  --quiet', dim('No narration.')],
+        ['  --json', dim('Machine-readable output.')],
+    ]));
+    write(`\n${dim(`Credentials come from the ${cyan('zen')} keyring — try ${cyan('zen key ls')}.`)}`);
+}
+process.exitCode = await main(process.argv.slice(2));
+//# sourceMappingURL=main.js.map

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