@zenera/faker 1.1.0

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.d.ts

@@ -0,0 +1,7 @@
+import type { GeneratorInput } from './envelope.ts';
+import type { Schema } from './schema.ts';
+import type { Operation } from './spec.ts';
+import type { Issue } from './validate.ts';
+export declare function probesFor(operation: Operation): GeneratorInput[];
+export declare function echoIssues(input: GeneratorInput, value: unknown, schema: Schema | undefined): Issue[];
+//# sourceMappingURL=probe.d.ts.map

package/dist/probe.js

@@ -0,0 +1,278 @@
+// ---------------------------------------------------------------------------
+// Probes
+//
+// A generator is judged before it is trusted, and it is judged on inputs made
+// up here rather than on traffic. That is not only about cost: a probe built
+// from a request body would put whatever a caller sent into the next prompt,
+// and a mock server is exactly the kind of thing people point at with real
+// payloads by accident.
+//
+// Two probes, deliberately. One ordinary, one at the edges of whatever the
+// schema allows — a generator that hard-codes the first probe's id passes once
+// and fails the second, which is the mistake this catches.
+// ---------------------------------------------------------------------------
+export function probesFor(operation) {
+    return [0, 1].map((variant) => ({
+        operationId: operation.operationId,
+        method: operation.method,
+        path: operation.path,
+        pathParams: values(operation.params, 'path', variant),
+        query: values(operation.params, 'query', variant),
+        headers: {},
+        body: operation.requestBody
+            ? sample(operation.requestBody.schema, variant, 0, operation.requestBody.schema)
+            : undefined,
+        seed: variant === 0 ? 1 : 2,
+    }));
+}
+function values(params, where, variant) {
+    const out = {};
+    for (const p of params) {
+        if (p.in !== where) {
+            continue;
+        }
+        // An optional query parameter is present in one probe and absent in the
+        // other, so a generator cannot assume either.
+        if (!p.required && variant === 1) {
+            continue;
+        }
+        out[p.name] = sample(p.schema, variant, 0, p.schema);
+    }
+    return out;
+}
+const NAMES = ['ada', 'grace', 'linus'];
+/**
+ * A value the schema would accept. Not a faker — that job belongs to the
+ * generator; this only has to be *valid*, so that a probe failure is the
+ * generator's fault and never the probe's.
+ */
+function sample(schema, variant, depth, root) {
+    if (depth > 4) {
+        return null;
+    }
+    // Normalisation hoists anything shared or recursive, so a top-level schema
+    // is quite often nothing but a pointer into `$defs`.
+    const target = follow(schema, root);
+    if (target !== schema) {
+        return sample(target, variant, depth + 1, root);
+    }
+    if (Array.isArray(schema.enum) && schema.enum.length > 0) {
+        return schema.enum[variant % schema.enum.length];
+    }
+    if (schema.const !== undefined) {
+        return schema.const;
+    }
+    for (const key of ['allOf', 'anyOf', 'oneOf']) {
+        const list = schema[key];
+        if (Array.isArray(list) && list.length > 0) {
+            return sample(list[0], variant, depth + 1, root);
+        }
+    }
+    switch (typeOf(schema)) {
+        case 'integer':
+            return bounded(schema, variant === 0 ? 12324 : 7, true);
+        case 'number':
+            return bounded(schema, variant === 0 ? 42.5 : 1.5, false);
+        case 'boolean':
+            return variant === 0;
+        case 'null':
+            return null;
+        case 'array': {
+            const items = schema.items;
+            const one = typeof items === 'object' && items !== null
+                ? sample(items, variant, depth + 1, root)
+                : 1;
+            return variant === 0 ? [one] : [one, one];
+        }
+        case 'object': {
+            const properties = (schema.properties ?? {});
+            const required = Array.isArray(schema.required) ? schema.required : [];
+            const out = {};
+            for (const [name, sub] of Object.entries(properties)) {
+                if (variant === 1 && !required.includes(name)) {
+                    continue;
+                }
+                out[name] = sample(sub, variant, depth + 1, root);
+            }
+            return out;
+        }
+        default:
+            return text(schema, variant);
+    }
+}
+/** One hop through a local `#/$defs/...` pointer, or the schema itself. */
+function follow(schema, root) {
+    const ref = schema.$ref;
+    if (typeof ref !== 'string' || !ref.startsWith('#/$defs/')) {
+        return schema;
+    }
+    const defs = root.$defs;
+    if (typeof defs !== 'object' || defs === null) {
+        return schema;
+    }
+    const target = defs[ref.slice('#/$defs/'.length)];
+    return typeof target === 'object' && target !== null ? target : schema;
+}
+function typeOf(schema) {
+    const type = schema.type;
+    if (typeof type === 'string') {
+        return type;
+    }
+    if (Array.isArray(type)) {
+        return type.find((t) => t !== 'null');
+    }
+    return schema.properties !== undefined
+        ? 'object'
+        : schema.items !== undefined
+            ? 'array'
+            : undefined;
+}
+function bounded(schema, wanted, integer) {
+    const min = num(schema.minimum) ?? num(schema.exclusiveMinimum);
+    const max = num(schema.maximum) ?? num(schema.exclusiveMaximum);
+    let value = wanted;
+    if (min !== undefined && value <= min) {
+        value = min + 1;
+    }
+    if (max !== undefined && value >= max) {
+        value = max - 1;
+    }
+    return integer ? Math.round(value) : value;
+}
+const num = (v) => (typeof v === 'number' ? v : undefined);
+function text(schema, variant) {
+    switch (schema.format) {
+        case 'uuid':
+            return variant === 0
+                ? '3f2504e0-4f89-11d3-9a0c-0305e82c3301'
+                : '9c858901-8a57-4791-81fe-4c455b099bc9';
+        case 'date':
+            return variant === 0 ? '2024-01-15' : '1999-12-31';
+        case 'date-time':
+            return variant === 0 ? '2024-01-15T09:30:00Z' : '1999-12-31T23:59:59Z';
+        case 'email':
+            return `${NAMES[variant % NAMES.length]}@example.com`;
+        case 'uri':
+        case 'url':
+            return 'https://example.com/thing';
+        default:
+            break;
+    }
+    // A `pattern` cannot be satisfied by guessing, so it is left to the
+    // parameter check to tell us the probe was wrong rather than the generator.
+    const base = NAMES[variant % NAMES.length];
+    const min = num(schema.minLength) ?? 0;
+    return base.length >= min ? base : base.padEnd(min, 'x');
+}
+// ---------------------------------------------------------------------------
+// The echo rule
+//
+// `get_user_by_id(12324)` answering `{ user_id: 999 }` validates perfectly and
+// is still wrong, so schema conformance is not the whole test. Where the
+// response declares a property with a parameter's name, the parameter's value
+// has to be the one that comes back.
+//
+// **Path parameters only.** A path segment identifies the resource, so a
+// mismatch there is a broken mock. A query parameter is usually a control
+// rather than content — `?source=realtime`, `?page_size=50`, `?cursor=…` — and
+// real APIs collide those names with unrelated response properties all the
+// time. Enforcing on them rejected working generators for a rule they were
+// right to ignore. The prompt still asks for query echo where it is meaningful;
+// it is simply not a reason to throw the file away.
+// ---------------------------------------------------------------------------
+export function echoIssues(input, value, schema) {
+    if (!schema) {
+        return [];
+    }
+    const declared = propertyNames(schema);
+    const out = [];
+    for (const [name, expected] of Object.entries(input.pathParams)) {
+        if (!declared.has(name) || expected === undefined || expected === null) {
+            continue;
+        }
+        if (!carries(value, name, expected)) {
+            out.push({
+                where: `/${name}`,
+                message: `must echo the path parameter ${JSON.stringify(expected)}, the response schema declares this property`,
+            });
+        }
+    }
+    return out;
+}
+/** Every property name the schema mentions, at any depth. */
+function propertyNames(schema) {
+    const out = new Set();
+    const seen = new Set();
+    const stack = [schema];
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (typeof node !== 'object' || node === null) {
+            continue;
+        }
+        if (Array.isArray(node)) {
+            stack.push(...node);
+            continue;
+        }
+        if (seen.has(node)) {
+            continue;
+        }
+        seen.add(node);
+        const record = node;
+        const properties = record.properties;
+        if (typeof properties === 'object' && properties !== null) {
+            for (const [name, sub] of Object.entries(properties)) {
+                out.add(name);
+                stack.push(sub);
+            }
+        }
+        // `$defs` holds schemas under arbitrary names, so its *values* are the
+        // subschemas — pushing the map itself would walk one level and stop,
+        // which is where every hoisted recursive schema lives.
+        for (const key of ['$defs', 'patternProperties']) {
+            const map = record[key];
+            if (typeof map === 'object' && map !== null) {
+                stack.push(...Object.values(map));
+            }
+        }
+        for (const key of ['items', 'allOf', 'anyOf', 'oneOf', 'prefixItems', 'not']) {
+            stack.push(record[key]);
+        }
+    }
+    return out;
+}
+/** Whether `name` anywhere in the value holds something equal to `expected`. */
+function carries(value, name, expected) {
+    const stack = [value];
+    const seen = new Set();
+    while (stack.length > 0) {
+        const node = stack.pop();
+        if (typeof node !== 'object' || node === null) {
+            continue;
+        }
+        if (Array.isArray(node)) {
+            stack.push(...node);
+            continue;
+        }
+        if (seen.has(node)) {
+            continue;
+        }
+        seen.add(node);
+        const record = node;
+        if (name in record && same(record[name], expected)) {
+            return true;
+        }
+        stack.push(...Object.values(record));
+    }
+    return false;
+}
+/** A path segment is text on the wire; `"12324"` and `12324` are the same id. */
+function same(got, expected) {
+    if (got === expected) {
+        return true;
+    }
+    if (got === null || got === undefined || typeof got === 'object') {
+        return false;
+    }
+    return String(got) === String(expected);
+}
+//# sourceMappingURL=probe.js.map

package/dist/prompt.d.ts

@@ -0,0 +1,11 @@
+import type { Operation } from './spec.ts';
+export declare const SYSTEM: string;
+export declare function brief(operation: Operation): string;
+/**
+ * Repeated in the file the model writes, so it is worth spelling out: the
+ * schema it validates against must be the one it was shown, embedded, not
+ * loaded from anywhere.
+ */
+export declare function instruction(operation: Operation): string;
+export declare function retry(diagnostics: readonly string[]): string;
+//# sourceMappingURL=prompt.d.ts.map