@zenera/faker 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrey Ryabov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,106 @@
+# @zenera/faker
+
+**A mock HTTP server for swagger/OpenAPI documents. Point it at a spec and it
+serves it — the response bodies are written, once, by a model.**
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE)
+[![Node](https://img.shields.io/badge/node-%E2%89%A524-brightgreen.svg)](https://nodejs.org)
+
+> Part of [ZeneraNeo](https://github.com/andreyryabov/ZeneraNeo). It ships no
+> binary of its own: installing it adds a `faker` **subcommand** to
+> [`zen`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md),
+> which is also where the credentials already are.
+
+## Install
+
+Node.js 24+ and [podman](https://podman.io). Install it alongside the CLI:
+
+```sh
+npm i -g @zenera/cli @zenera/faker openai
+zen key add openai          # the keyring `zen` already uses
+```
+
+The first start builds one image; every start after that reuses it. `zen --help`
+lists `faker` whether or not it is installed, and says what to run if not.
+
+## Use
+
+```sh
+zen faker serve api/openapi.yaml --port 8787
+curl -s localhost:8787/users/12324
+# { "user_id": 12324, "email": "brooke.hoffman@example.org", ... }
+```
+
+More than one document at a time is fine, and the same request answers the same
+way every time when you pin a seed:
+
+```sh
+zen faker serve specs/*.yaml --seed 42
+```
+
+Warm it up before a demo or a test run, so no request pays for a model turn:
+
+```sh
+zen faker build api/openapi.yaml     # write every generator now and exit
+zen faker cache ls                   # what has been generated
+zen faker cache clear                # throw it away
+```
+
+`zen mock` is the same command under a shorter noun.
+
+## How a body is produced
+
+The first time an operation is called, the faker asks a model to write a
+**Python generator** for it — one file, taking a JSON input path and a JSON
+output path. That file is then run against synthetic probes and judged twice:
+against the operation's response schema, and against the echo rule, which says
+that where a path or query parameter shares a name with a property in the
+response, the response has to carry the value that was asked for.
+`GET /users/12324` answering with somebody else's id validates perfectly and is
+still wrong.
+
+If it fails, the diagnostics go back to the model and it tries again, up to
+`--attempts`. If it passes, the file is cached under `~/.zenera/neo/faker` and
+every later request is just `podman exec python3 gen.py in.json out.json` — no
+model, no tokens.
+
+Generators run in a container with **no network**, on an image baked once with
+`faker`, `exrex`, `jsonschema` and `python-dateutil`.
+
+## Commands
+
+```
+zen faker serve <spec...>    Serve them. Generators are written on demand.
+zen faker build <spec...>    Write every generator now and exit.
+zen faker cache ls | clear   What has been generated, or throw it away.
+```
+
+Useful options: `--port`, `--host` (loopback by default), `--model`, `--seed`
+(same request, same answer), `--rebuild`, `--attempts`, `--concurrency`,
+`--timeout`, `--cache <dir>`, `--quiet`. `zen help faker` prints the full table.
+
+`GET /__faker/routes` lists what is being served; `GET /__faker/health` is a
+health check.
+
+## Credentials
+
+The keyring is `zen`'s, so there is nothing new to configure:
+
+```sh
+zen key add openai
+zen key ls --check
+```
+
+Environment variables still win over the keyring, exactly as they do for `zen`.
+
+## The rest of the family
+
+| Package                                                                                     | What it is                                           |
+| ------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
+| [`@zenera/cli`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md) | `zen` — agent projects on the command line           |
+| [`@zenera/neo`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/neo/README.md) | the runtime — agents, models, tools, skills, memory  |
+| [`@zenera/rag`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/rag/README.md) | `zen rag` — an API description as a searchable graph |
+
+## License
+
+[MIT](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE).

package/dist/box.d.ts

@@ -0,0 +1,43 @@
+import { type Runner, type Sandbox } from '@zenera/neo';
+export declare const GENERATORS = "generators";
+export interface BoxOptions {
+    /** host directory mounted at /workspace; holds generators/ and io/ */
+    root: string;
+    image: string;
+    /** seconds one generator may take */
+    timeout?: number;
+    engine?: string;
+    exec?: Runner;
+}
+export interface Outcome {
+    ok: boolean;
+    /** parsed `output.json`, when the run produced one */
+    value?: unknown;
+    /** what went wrong, in the words the build loop feeds back to the model */
+    fault?: string;
+    stderr?: string;
+    durationMs: number;
+}
+export declare class Box {
+    #private;
+    readonly root: string;
+    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.
+     */
+    fresh(): Promise<void>;
+    /** Host path of a generator's source file. */
+    sourceOf(key: string): string;
+    write(key: string, source: string): Promise<void>;
+    /**
+     * 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.
+     */
+    run(key: string, input: unknown): Promise<Outcome>;
+    dispose(): Promise<void>;
+}
+//# sourceMappingURL=box.d.ts.map

package/dist/box.js

@@ -0,0 +1,158 @@
+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
+//
+// One container for the whole process, offline, with the faker's own directory
+// bind-mounted at /workspace. That single mount is what makes the file contract
+// work in both directions: the host writes `input.json` and reads
+// `output.json`, the generator sees the same two paths from inside, and neither
+// side has to serialise anything through a pipe.
+//
+// Nothing the model wrote ever reaches an argument on this side. The generator
+// is invoked by a script built here out of paths derived here, and the script
+// itself travels on stdin — the same rule the sandbox tools follow.
+// ---------------------------------------------------------------------------
+export const GENERATORS = 'generators';
+const IO = 'io';
+const ENTRY = 'gen.py';
+export class Box {
+    root;
+    #pool;
+    #timeout;
+    #engine;
+    #exec;
+    constructor(opts) {
+        this.root = opts.root;
+        this.#timeout = opts.timeout ?? 30;
+        this.#engine = opts.engine ?? 'podman';
+        this.#exec = opts.exec ?? runProcess;
+        mkdirSync(join(opts.root, GENERATORS), { recursive: true });
+        mkdirSync(join(opts.root, IO), { recursive: true });
+        this.#pool = new SandboxPool({
+            root: opts.root,
+            key: 'faker',
+            image: opts.image,
+            // The one line that keeps model-written code from calling home.
+            network: 'none',
+            workdir: SANDBOX_MOUNT,
+            timeout: this.#timeout,
+            // Deliberately NOT persisted, unlike `zen`'s sandbox. A container's
+            // name is a hash of its configuration, which includes the host
+            // path but not the directory behind it — so a cache directory that
+            // is deleted and recreated (`zen faker cache clear`, or any rm -rf)
+            // gets a stopped container reattached whose bind mount still points
+            // at the old inode. Everything written here is then invisible
+            // inside, and every generator fails with "can't open file".
+            // `zen` persists to keep `pip install`s; the libraries here are
+            // baked into the image, so there is nothing to keep.
+            persist: false,
+            readOnly: false,
+            // Deliberately empty: the keyring is in this process's environment
+            // and none of it belongs in the container.
+            env: {},
+            engine: opts.engine,
+            exec: opts.exec,
+        });
+    }
+    get sandbox() {
+        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.
+     */
+    async fresh() {
+        await this.#exec(this.#engine, ['rm', '--force', '--volumes', this.sandbox.name], {
+            timeoutMs: 60_000,
+        }).catch(() => undefined);
+    }
+    /** Host path of a generator's source file. */
+    sourceOf(key) {
+        return join(this.root, GENERATORS, key, ENTRY);
+    }
+    async write(key, source) {
+        mkdirSync(join(this.root, GENERATORS, key), { recursive: true });
+        await writeFile(this.sourceOf(key), source, 'utf8');
+    }
+    /**
+     * 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.
+     */
+    async run(key, input) {
+        const id = randomUUID();
+        const dir = join(this.root, IO, id);
+        mkdirSync(dir, { recursive: true });
+        const started = Date.now();
+        try {
+            await writeFile(join(dir, 'input.json'), JSON.stringify(input), 'utf8');
+            const script = [
+                `exec python3 ${inside(GENERATORS, key, ENTRY)}`,
+                inside(IO, id, 'input.json'),
+                inside(IO, id, 'output.json'),
+            ].join(' ');
+            const res = await this.sandbox.exec(script, { timeout: this.#timeout });
+            const stderr = res.stderr.trim();
+            if (res.timed_out) {
+                return {
+                    ok: false,
+                    fault: `took longer than ${this.#timeout}s`,
+                    stderr,
+                    durationMs: Date.now() - started,
+                };
+            }
+            if (res.exit_code !== 0) {
+                return {
+                    ok: false,
+                    fault: `exited ${res.exit_code}`,
+                    stderr: stderr || res.stdout.trim(),
+                    durationMs: Date.now() - started,
+                };
+            }
+            let text;
+            try {
+                text = await readFile(join(dir, 'output.json'), 'utf8');
+            }
+            catch {
+                return {
+                    ok: false,
+                    fault: 'wrote no output file',
+                    stderr,
+                    durationMs: Date.now() - started,
+                };
+            }
+            try {
+                return {
+                    ok: true,
+                    value: JSON.parse(text),
+                    stderr,
+                    durationMs: Date.now() - started,
+                };
+            }
+            catch (err) {
+                return {
+                    ok: false,
+                    fault: `output.json is not JSON: ${err instanceof Error ? err.message : String(err)}`,
+                    stderr,
+                    durationMs: Date.now() - started,
+                };
+            }
+        }
+        finally {
+            rmSync(dir, { recursive: true, force: true });
+        }
+    }
+    async dispose() {
+        await this.#pool.dispose();
+    }
+}
+/** A path inside the container. Every segment is derived here, never given. */
+function inside(...parts) {
+    return [SANDBOX_MOUNT, ...parts].join('/');
+}
+//# sourceMappingURL=box.js.map

package/dist/cache.d.ts

@@ -0,0 +1,57 @@
+import type { Model } from '@zenera/neo';
+import { type Box } from './box.ts';
+import { BuildFailed } from './generate.ts';
+import type { Operation } from './spec.ts';
+import type { Checks } from './validate.ts';
+export interface Generator {
+    key: string;
+    source: string;
+    /** whether it came off disk rather than out of a model */
+    cached: boolean;
+}
+export interface CacheEvent {
+    operation: Operation;
+    attempt?: number;
+    diagnostics?: readonly string[];
+}
+export interface CacheOptions {
+    box: Box;
+    checks: Checks;
+    model: Model;
+    attempts?: number;
+    /**
+     * How many generators may be written at once. A client that walks every
+     * route — which is exactly what people do to a new mock — would otherwise
+     * open one model request per operation simultaneously and be rate limited
+     * on all of them.
+     */
+    concurrency?: number;
+    /** ignore what is on disk and write fresh */
+    rebuild?: boolean;
+    /** run generators but keep nothing */
+    ephemeral?: boolean;
+    onStart?: (e: CacheEvent) => void;
+    onAttempt?: (e: CacheEvent) => void;
+    onReady?: (e: CacheEvent & {
+        cached: boolean;
+        attempts: number;
+    }) => void;
+    onFail?: (e: CacheEvent & {
+        error: Error;
+    }) => void;
+}
+export declare class Cache {
+    #private;
+    constructor(opts: CacheOptions);
+    /**
+     * The generator for an operation, written if it does not exist yet. Callers
+     * that arrive during a build wait for that build rather than starting one.
+     *
+     * `cached` answers "did this call cost a model turn", which is what the
+     * response header is for — so it is false for the caller that triggered the
+     * build and for everyone who waited on it, and true from then on.
+     */
+    ensure(operation: Operation): Promise<Generator>;
+}
+export { BuildFailed };
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.js

@@ -0,0 +1,125 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { writeJson } from '@zenera/cli/lib';
+import { GENERATORS } from "./box.js";
+import { build, BuildFailed } from "./generate.js";
+const DEFAULT_CONCURRENCY = 4;
+export class Cache {
+    #opts;
+    #live = new Map();
+    #settled = new Set();
+    #slots;
+    #waiting = [];
+    #running = 0;
+    constructor(opts) {
+        this.#opts = opts;
+        this.#slots = Math.max(1, opts.concurrency ?? DEFAULT_CONCURRENCY);
+    }
+    /**
+     * The generator for an operation, written if it does not exist yet. Callers
+     * that arrive during a build wait for that build rather than starting one.
+     *
+     * `cached` answers "did this call cost a model turn", which is what the
+     * response header is for — so it is false for the caller that triggered the
+     * build and for everyone who waited on it, and true from then on.
+     */
+    ensure(operation) {
+        const already = this.#settled.has(operation.key);
+        const running = this.#live.get(operation.key);
+        if (running) {
+            return already ? running.then((g) => ({ ...g, cached: true })) : running;
+        }
+        const started = this.#make(operation).then((g) => {
+            this.#settled.add(operation.key);
+            return g;
+        }, (err) => {
+            // A model that tried and could not is remembered: re-asking it
+            // once per request is how a mock server becomes an invoice.
+            // Anything else — a rate limit, a dropped connection — is about
+            // this moment rather than this operation, so it is forgotten
+            // and the next request gets a fresh go.
+            if (!(err instanceof BuildFailed)) {
+                this.#live.delete(operation.key);
+            }
+            throw err;
+        });
+        this.#live.set(operation.key, started);
+        return started;
+    }
+    async #make(operation) {
+        const { box, model, checks, rebuild, ephemeral } = this.#opts;
+        // Read before queueing: a cache hit costs nothing and must not wait
+        // behind somebody else's model call.
+        const source = rebuild ? undefined : await read(box, operation.key);
+        if (source !== undefined) {
+            this.#opts.onReady?.({ operation, cached: true, attempts: 0 });
+            return { key: operation.key, source, cached: true };
+        }
+        await this.#enter();
+        this.#opts.onStart?.({ operation });
+        try {
+            const built = await build(operation, {
+                model,
+                box,
+                checks,
+                attempts: this.#opts.attempts,
+                onAttempt: (attempt, diagnostics) => this.#opts.onAttempt?.({ operation, attempt, diagnostics }),
+            });
+            if (!ephemeral) {
+                writeJson(join(box.root, GENERATORS, operation.key, 'meta.json'), {
+                    version: 1,
+                    operationId: operation.operationId,
+                    method: operation.method,
+                    path: operation.path,
+                    source: operation.source,
+                    model: model.id,
+                    attempts: built.attempts,
+                    rebuilt: Boolean(rebuild),
+                    createdAt: new Date().toISOString(),
+                }, 0o644);
+            }
+            this.#opts.onReady?.({ operation, cached: false, attempts: built.attempts });
+            return { key: operation.key, source: built.source, cached: false };
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            this.#opts.onFail?.({ operation, error });
+            throw error;
+        }
+        finally {
+            this.#leave();
+        }
+    }
+    #enter() {
+        if (this.#running < this.#slots) {
+            this.#running++;
+            return Promise.resolve();
+        }
+        return new Promise((admit) => this.#waiting.push(admit));
+    }
+    /** Hands the slot straight to whoever is next, so the count stays exact. */
+    #leave() {
+        const next = this.#waiting.shift();
+        if (next) {
+            next();
+            return;
+        }
+        this.#running--;
+    }
+}
+async function read(box, key) {
+    const path = box.sourceOf(key);
+    if (!existsSync(path)) {
+        return undefined;
+    }
+    try {
+        const source = await readFile(path, 'utf8');
+        return source.trim() ? source : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export { BuildFailed };
+//# sourceMappingURL=cache.js.map

package/dist/command.d.ts

@@ -0,0 +1,3 @@
+import { type Command } from '@zenera/cli/lib';
+export declare const command: Command;
+//# sourceMappingURL=command.d.ts.map