@zenera/faker 1.1.24 → 1.1.26

package/dist/box.d.ts

@@ -1,5 +1,7 @@
 import { type Runner, type Sandbox } from '@zenera/neo';
 export declare const GENERATORS = "generators";
+/** Every faker container's name starts with this; `cache clear` relies on it. */
+export declare const CONTAINER_PREFIX = "zn-faker-";
 export interface BoxOptions {
     /** host directory mounted at /workspace; holds generators/ and io/ */
     root: string;
@@ -8,6 +10,23 @@ export interface BoxOptions {
     timeout?: number;
     engine?: string;
     exec?: Runner;
+    /** the process the container belongs to; defaults to this one */
+    owner?: number;
+}
+/**
+ * The container engine could not run the generator at all. Nothing is known
+ * about the generator from this, so it must never be fed back to a model as a
+ * fault in the code: rewriting a working file cannot bring a container back.
+ */
+export declare class SandboxUnavailable extends Error {
+    readonly hint: string;
+    readonly container: string;
+    readonly stderr?: string;
+    constructor(message: string, opts: {
+        hint: string;
+        container: string;
+        stderr?: string;
+    });
 }
 export interface Outcome {
     ok: boolean;
@@ -24,9 +43,11 @@ export declare class Box {
     constructor(opts: BoxOptions);
     get sandbox(): Sandbox;
     /**
-     * Removes a container of this name left behind by a process that did not
-     * get to clean up. Belt to `persist: false`'s braces: a hard kill never
-     * runs `dispose`, and the leftover is exactly the stale-mount trap above.
+     * Removes this process's container if a previous owner of the pid left one,
+     * and every faker container whose owning process is gone. Belt to
+     * `persist: false`'s braces: a hard kill never runs `dispose`, and the
+     * leftover is exactly the stale-mount trap above. A container whose owner
+     * is alive is another server's, and is never touched.
      */
     fresh(): Promise<void>;
     /** Host path of a generator's source file. */
@@ -36,6 +57,8 @@ export declare class Box {
      * One generator, one input, one output. The io directory is removed
      * afterwards whatever happened — a mock server left alone for a week must
      * not fill a disk with request envelopes.
+     *
+     * Throws `SandboxUnavailable` when the engine, not the generator, failed.
      */
     run(key: string, input: unknown): Promise<Outcome>;
     dispose(): Promise<void>;

package/dist/box.js

@@ -1,8 +1,8 @@
+import { SANDBOX_MOUNT, SandboxError, SandboxPool, pidAlive, runProcess, } from '@zenera/neo';
 import { randomUUID } from 'node:crypto';
 import { mkdirSync, rmSync } from 'node:fs';
 import { readFile, writeFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { SANDBOX_MOUNT, SandboxPool, runProcess } from '@zenera/neo';
 // ---------------------------------------------------------------------------
 // Where generators run
 //
@@ -19,22 +19,51 @@ import { SANDBOX_MOUNT, SandboxPool, runProcess } from '@zenera/neo';
 export const GENERATORS = 'generators';
 const IO = 'io';
 const ENTRY = 'gen.py';
+/** Every faker container's name starts with this; `cache clear` relies on it. */
+export const CONTAINER_PREFIX = 'zn-faker-';
+/** `zn-faker-<pid>-<digest>`; a name without the pid predates per-process containers. */
+const OWNED_BY = /^zn-faker-(\d+)-[0-9a-f]+$/;
+/** Pause before the one retry of an engine failure, long enough for a concurrent rm to finish. */
+const ENGINE_RETRY_MS = 300;
+/**
+ * The container engine could not run the generator at all. Nothing is known
+ * about the generator from this, so it must never be fed back to a model as a
+ * fault in the code: rewriting a working file cannot bring a container back.
+ */
+export class SandboxUnavailable extends Error {
+    hint;
+    container;
+    stderr;
+    constructor(message, opts) {
+        super(message);
+        this.name = 'SandboxUnavailable';
+        this.hint = opts.hint;
+        this.container = opts.container;
+        this.stderr = opts.stderr;
+    }
+}
 export class Box {
     root;
     #pool;
     #timeout;
     #engine;
     #exec;
+    #owner;
     constructor(opts) {
         this.root = opts.root;
         this.#timeout = opts.timeout ?? 30;
         this.#engine = opts.engine ?? 'podman';
         this.#exec = opts.exec ?? runProcess;
+        this.#owner = opts.owner ?? process.pid;
         mkdirSync(join(opts.root, GENERATORS), { recursive: true });
         mkdirSync(join(opts.root, IO), { recursive: true });
         this.#pool = new SandboxPool({
             root: opts.root,
-            key: 'faker',
+            // One container per process. The name is otherwise a pure function
+            // of the configuration, so two servers on the same --cache shared
+            // one container, and each start (`fresh`) or exit (`dispose`)
+            // removed it from under the other: `exited 125, no such container`.
+            key: `faker-${this.#owner}`,
             image: opts.image,
             // The one line that keeps model-written code from calling home.
             network: 'none',
@@ -62,14 +91,21 @@ export class Box {
         return this.#pool.for();
     }
     /**
-     * Removes a container of this name left behind by a process that did not
-     * get to clean up. Belt to `persist: false`'s braces: a hard kill never
-     * runs `dispose`, and the leftover is exactly the stale-mount trap above.
+     * Removes this process's container if a previous owner of the pid left one,
+     * and every faker container whose owning process is gone. Belt to
+     * `persist: false`'s braces: a hard kill never runs `dispose`, and the
+     * leftover is exactly the stale-mount trap above. A container whose owner
+     * is alive is another server's, and is never touched.
      */
     async fresh() {
-        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name], {
-            timeoutMs: 60_000,
-        }).catch(() => undefined);
+        const listed = await this.#exec(this.#engine, ['ps', '--all', '--filter', `name=^${CONTAINER_PREFIX}`, '--format', '{{.Names}}'], { timeoutMs: 60_000 }).catch(() => undefined);
+        const orphans = (listed?.code === 0 ? listed.stdout.split('\n') : [])
+            .map((n) => n.trim())
+            .filter((name) => {
+            const pid = Number(OWNED_BY.exec(name)?.[1]);
+            return Number.isInteger(pid) && pid !== this.#owner && !pidAlive(pid);
+        });
+        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name, ...orphans], { timeoutMs: 60_000 }).catch(() => undefined);
     }
     /** Host path of a generator's source file. */
     sourceOf(key) {
@@ -83,6 +119,8 @@ export class Box {
      * One generator, one input, one output. The io directory is removed
      * afterwards whatever happened — a mock server left alone for a week must
      * not fill a disk with request envelopes.
+     *
+     * Throws `SandboxUnavailable` when the engine, not the generator, failed.
      */
     async run(key, input) {
         const id = randomUUID();
@@ -96,7 +134,17 @@ export class Box {
                 inside(IO, id, 'input.json'),
                 inside(IO, id, 'output.json'),
             ].join(' ');
-            const res = await this.sandbox.exec(script, { timeout: this.#timeout });
+            let res = await this.#exec1(script);
+            if (engineFault(res)) {
+                // `exec` already brought a vanished container back once; a
+                // second fault is usually a concurrent rm still settling.
+                await new Promise((settle) => setTimeout(settle, ENGINE_RETRY_MS));
+                res = await this.#exec1(script);
+            }
+            const fault = engineFault(res);
+            if (fault) {
+                throw this.#unavailable(fault, res.stderr.trim() || res.stdout.trim());
+            }
             const stderr = res.stderr.trim();
             if (res.timed_out) {
                 return {
@@ -150,6 +198,59 @@ export class Box {
     async dispose() {
         await this.#pool.dispose();
     }
+    async #exec1(script) {
+        try {
+            return await this.sandbox.exec(script, { timeout: this.#timeout });
+        }
+        catch (err) {
+            if (err instanceof SandboxError) {
+                throw new SandboxUnavailable(`${this.#engine} could not run the generator: ${err.message}`, {
+                    hint: err.hint ??
+                        `check \`${this.#engine} ps -a --filter name=${CONTAINER_PREFIX}\``,
+                    container: this.sandbox.name,
+                });
+            }
+            throw err;
+        }
+    }
+    #unavailable(fault, stderr) {
+        const name = this.sandbox.name;
+        const first = stderr.split('\n')[0] ?? '';
+        const hint = fault === 'missing-file'
+            ? `the generator is on the host but not inside ${name}, so its bind mount is stale ` +
+                `(the --cache directory was deleted and recreated while the server ran). ` +
+                `Restart \`zen faker serve\`.`
+            : fault === 'no-python'
+                ? `the image has no python3. Rebuild it: \`zen faker serve --rebuild …\`, or pass a working --image.`
+                : `${name} was removed or stopped while this server was using it, twice in a row. ` +
+                    `Usual causes: \`zen sandbox clean\` or \`zen faker cache clear\` run meanwhile, ` +
+                    `a ${this.#engine} machine restart, or an older \`zen faker\` (before per-process ` +
+                    `containers) started on the same --cache. Check \`${this.#engine} ps -a --filter ` +
+                    `name=${CONTAINER_PREFIX}\` and \`${this.#engine} machine list\`; the next request ` +
+                    `recreates the container.`;
+        return new SandboxUnavailable(`${this.#engine} could not run the generator in ${name} — ${first || fault} ` +
+            `(an engine failure, not a fault in the generator; nothing was regenerated)`, { hint, container: name, stderr: stderr || undefined });
+    }
+}
+/**
+ * A failure of the container rather than of the code in it. 125 is podman's
+ * own exit code for "could not exec at all"; the other two are our command
+ * line failing before a line of the generator ran.
+ */
+function engineFault(res) {
+    if (res.timed_out) {
+        return undefined;
+    }
+    if (res.exit_code === 125) {
+        return 'engine';
+    }
+    if (res.exit_code === 2 && /can't open file '\/workspace\/generators\//.test(res.stderr)) {
+        return 'missing-file';
+    }
+    if (res.exit_code === 127 && /python3: (not found|No such file)/.test(res.stderr)) {
+        return 'no-python';
+    }
+    return undefined;
 }
 /** A path inside the container. Every segment is derived here, never given. */
 function inside(...parts) {

package/dist/cache.js

@@ -118,6 +118,8 @@ export class Cache {
         }
         catch (err) {
             const error = err instanceof Error ? err : new Error(String(err));
+            // The box holds the last rejected attempt; the next request must run the old file.
+            await box.write(operation.key, ctx.currentSource).catch(() => undefined);
             const dump = await this.#finished(operation, error);
             this.#opts.onFail?.({ operation, error, dump });
             throw error;

package/dist/command.js

@@ -2,7 +2,7 @@ import { bold, cacheItems, clearCache, CliError, cyan, dim, EXIT, green, json, K
 import { createModel } from '@zenera/neo';
 import { rmSync } from 'node:fs';
 import { join, relative, resolve } from 'node:path';
-import { GENERATORS } from "./box.js";
+import { CONTAINER_PREFIX, GENERATORS } from "./box.js";
 import { FAKER_KIND } from "./cache.js";
 import { reason } from "./generate.js";
 import { formatDumpPath } from "./logger.js";
@@ -238,7 +238,7 @@ async function cache(args, ctx) {
         // 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-'));
+        const mine = (await ownedContainers()).filter((c) => c.name.startsWith(CONTAINER_PREFIX));
         if (mine.length > 0) {
             await removeContainers(mine.map((c) => c.name));
         }

package/dist/generate.js

@@ -47,6 +47,10 @@ export function reason(err) {
         }
         at = e.cause;
     }
+    const hint = err?.hint;
+    if (typeof hint === 'string' && hint) {
+        parts.push(hint);
+    }
     return parts.join(' — ') || String(err);
 }
 export async function build(operation, opts) {

package/dist/logger.d.ts

@@ -1,5 +1,5 @@
 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 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' | 'SANDBOX_UNAVAILABLE' | 'SERVER_INTERNAL_ERROR' | 'REGENERATION_LIMIT_HIT' | 'REGENERATION_FAILED' | 'SUCCESS';
 export interface RequestDumpData {
     id: string;
     timestamp: Date;
@@ -19,6 +19,8 @@ export interface RequestDumpData {
     responseBody?: unknown;
     errorKind?: ErrorKind;
     errorMessage?: string;
+    /** what to do about it, when the fix is not in the generator */
+    hint?: string;
     stderr?: string;
     /** the build report, when the answer was "there is no generator" */
     buildDump?: string;
@@ -64,7 +66,7 @@ export declare function saveBuildDump(dir: string, data: BuildDumpData): Promise
 export declare function formatDumpPath(label: string, path: string): 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 formatRegenerating(urlPath: string, attempt: number, limit: number, operationId?: string, reason?: string, stderr?: string): string;
 export declare function formatRegenerated(urlPath: string, attempt: number, durationMs: number, operationId?: string): string;
 export interface ExampleRequest {
     input: GeneratorInput;

package/dist/logger.js

@@ -44,6 +44,8 @@ export function statusText(status) {
             return 'Not Implemented';
         case 502:
             return 'Bad Gateway';
+        case 503:
+            return 'Service Unavailable';
         case 504:
             return 'Gateway Timeout';
         default:
@@ -169,6 +171,9 @@ export async function saveRequestDump(dir, data) {
         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), '```', '');
         }
@@ -237,6 +242,9 @@ export function formatLogLine(data, dumpPath) {
         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)}`);
@@ -254,11 +262,13 @@ export function formatRegenLimitHit(urlPath, limit, operationId) {
     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) {
+export function formatRegenerating(urlPath, attempt, limit, operationId, reason, stderr) {
     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})...`;
+    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())}]`);

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/probe.js

@@ -1,4 +1,4 @@
-import { propertyNames } from "./schema.js";
+import { properties } from "./schema.js";
 // ---------------------------------------------------------------------------
 // Probes
 //
@@ -235,10 +235,18 @@ export function echoIssues(input, value, schema) {
     if (!schema) {
         return [];
     }
-    const declared = propertyNames(schema);
+    const declared = new Map();
+    for (const p of properties(schema)) {
+        declared.set(p.name, [...(declared.get(p.name) ?? []), p.schema]);
+    }
     const out = [];
     for (const [name, expected] of Object.entries(input.pathParams)) {
-        if (!declared.has(name) || expected === undefined || expected === null) {
+        const subs = declared.get(name);
+        if (!subs || expected === undefined || expected === null) {
+            continue;
+        }
+        // A value the response may not hold cannot be echoed: the schema check wins.
+        if (!subs.some((s) => admits(s, expected))) {
             continue;
         }
         if (!carries(value, name, expected)) {
@@ -250,6 +258,17 @@ export function echoIssues(input, value, schema) {
     }
     return out;
 }
+function admits(schema, value) {
+    if (typeof schema.pattern !== 'string') {
+        return true;
+    }
+    try {
+        return new RegExp(schema.pattern, 'u').test(String(value));
+    }
+    catch {
+        return true;
+    }
+}
 /** Whether `name` anywhere in the value holds something equal to `expected`. */
 function carries(value, name, expected) {
     const stack = [value];

package/dist/prompt.js

@@ -36,7 +36,9 @@ export const SYSTEM = [
     "   in the response schema, that property must carry the request's value,",
     '   converted to the type the schema declares. `GET /users/{user_id}` called',
     '   with `user_id=12324` answers with `user_id` 12324, not a random one. Do',
-    '   this generically, by looking the names up at run time. Do the same for a',
+    '   this generically, by looking the names up at run time. If the value would',
+    "   break that property's schema (it fails a `pattern`, say), the schema wins:",
+    '   generate a valid value instead, and do not exit non-zero. Do the same for a',
     '   query parameter where it plainly describes the content rather than',
     '   controlling the call. A paging control — a cursor, page, offset or',
     '   page-size parameter (whether in query or request body) — is never content',

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 import { type Server } from 'node:http';
-import type { Box } from './box.ts';
+import { type Box } from './box.ts';
 import { type Cache } from './cache.ts';
 import { RegenerationLimiter, RequestHistory } from './logger.ts';
 import { PaginationLimiter } from './paging.ts';

package/dist/server.js

@@ -2,6 +2,7 @@ import { createHash, randomInt, randomUUID } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { createServer } from 'node:http';
 import { join } from 'node:path';
+import { SandboxUnavailable } from "./box.js";
 import { BuildFailed } from "./cache.js";
 import { reason } from "./generate.js";
 import { formatLogLine, formatRegenerated, formatRegenerating, formatRegenLimitHit, RegenerationLimiter, RequestHistory, saveRequestDump, } from "./logger.js";
@@ -39,7 +40,7 @@ export function build(opts) {
     };
     return createServer((req, res) => {
         handle(req, res, enriched).catch((err) => {
-            const message = err instanceof Error ? err.message : String(err);
+            const message = reason(err);
             send(res, 500, { error: message });
             opts.onRequest?.(`${req.method ?? 'GET'} ${req.url ?? '/'} 500 [SERVER_INTERNAL_ERROR] ${message}`);
         });
@@ -93,6 +94,7 @@ async function handle(req, res, opts) {
             responseBody: meta.responseBody,
             errorKind: meta.errorKind,
             errorMessage: meta.errorMessage,
+            hint: meta.hint,
             stderr: meta.stderr,
             buildDump: meta.buildDump,
             cacheStatus: meta.cacheStatus,
@@ -182,6 +184,30 @@ async function handle(req, res, opts) {
     }
     const { operation, pathParams } = match;
     res.setHeader('x-faker-operation', operation.operationId);
+    /** The container could not run anything: say so, and never blame the generator. */
+    const sandboxDown = async (err, extra = {}) => {
+        const bodyObj = {
+            error: err.message,
+            hint: err.hint,
+            container: err.container,
+            stderr: err.stderr,
+        };
+        res.setHeader('retry-after', '1');
+        const end = prepareSend(res, 503, bodyObj);
+        await finish(503, {
+            operationId: operation.operationId,
+            routePath: operation.path,
+            pathParams,
+            ...extra,
+            errorKind: 'SANDBOX_UNAVAILABLE',
+            errorMessage: err.message,
+            hint: err.hint,
+            stderr: err.stderr,
+            responseBody: bodyObj,
+            note: 'container engine failed',
+        });
+        end();
+    };
     let body;
     try {
         body = await readBody(req, opts.maxBody ?? DEFAULT_MAX_BODY);
@@ -240,6 +266,10 @@ async function handle(req, res, opts) {
         generator = await opts.cache.ensure(operation);
     }
     catch (err) {
+        if (err instanceof SandboxUnavailable) {
+            await sandboxDown(err, { requestBody: body });
+            return;
+        }
         const status = err instanceof BuildFailed ? 501 : 500;
         const detail = reason(err);
         const bodyObj = {
@@ -275,7 +305,17 @@ async function handle(req, res, opts) {
         body,
         seed: seedFor(opts.seed, operation, pathParams, url.searchParams),
     };
-    let outcome = await opts.box.run(operation.key, input);
+    let outcome;
+    try {
+        outcome = await opts.box.run(operation.key, input);
+    }
+    catch (err) {
+        if (err instanceof SandboxUnavailable) {
+            await sandboxDown(err, { requestBody: body, cacheStatus });
+            return;
+        }
+        throw err;
+    }
     const responseValidator = opts.checks.for(operation).response;
     let schemaMismatch = false;
     if (outcome.ok && responseValidator && !responseValidator(outcome.value)) {
@@ -323,7 +363,7 @@ async function handle(req, res, opts) {
             return;
         }
         const attempt = opts.limiter.increment(urlKey);
-        opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault));
+        opts.onRequest?.(formatRegenerating(urlKey, attempt, opts.limiter.limit, operation.operationId, outcome.fault, outcome.stderr));
         const regenStarted = Date.now();
         let currentSource = generator.source;
         if (!currentSource?.trim()) {
@@ -361,6 +401,10 @@ async function handle(req, res, opts) {
             }
         }
         catch (regenErr) {
+            if (regenErr instanceof SandboxUnavailable) {
+                await sandboxDown(regenErr, { requestBody: body, cacheStatus });
+                return;
+            }
             const detail = reason(regenErr);
             const bodyObj = {
                 error: `regeneration failed for ${operation.operationId}: ${detail}`,

package/dist/setup.js

@@ -19,7 +19,7 @@ import { Checks } from "./validate.js";
 // ---------------------------------------------------------------------------
 /**
  * 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
+ * recommends (`RECOMMENDED` in `packages/cli/src/meta/model.ts`). Every ref names its
  * provider: the shorthand reads the first segment as a *provider name*, so a
  * bare `gemini-3.8-flash` would be asked of OpenAI.
  */

package/package.json

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