@zenera/gym 0.0.0-stage → 1.1.38

package/dist/setup.js

@@ -0,0 +1,123 @@
+import { credentialError, ensureHome, ensurePodmanReady, envNames, home, invalidError, KeyStore, paths, PROVIDERS, readJson, writeJson, } from '@zenera/cli/lib';
+import { createModel } from '@zenera/neo';
+import { mkdirSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { Box } from "./box.js";
+import { Cache } from "./cache.js";
+import { ensureImage } from "./image.js";
+import { Router } from "./router.js";
+import { loadSpecs, SpecError } from "./spec.js";
+import { Checks } from "./validate.js";
+// ---------------------------------------------------------------------------
+// Assembly
+//
+// The order here is the whole point and it is the same order `zen run` uses:
+// credentials before anything that needs one, the container engine before the
+// image, the image before the box, and the documents last — so the failure a
+// user sees is the first thing that was actually wrong rather than whatever
+// happened to be checked first.
+// ---------------------------------------------------------------------------
+/**
+ * The model each provider gets when none is named — the same picks `zen meta`
+ * 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.
+ */
+const DEFAULT_MODEL = {
+    openai: 'openai:gpt-5.6-sol',
+    anthropic: 'anthropic:claude-opus-5',
+    google: 'google:gemini-3.8-flash',
+    vertex: 'vertex:gemini-3.8-flash',
+    openrouter: 'openrouter:anthropic/claude-opus-5',
+};
+// ---------------------------------------------------------------------------
+// Which model, and why that one
+//
+// The same chain `zen meta` uses: a flag beats the environment, the environment
+// beats what was stored, and with none of them set it is whatever the keys on
+// hand can buy. Which model writes generators is a choice about a tool on this
+// machine and not about a document, so it is stored beside the keyring rather
+// than anywhere near a specification.
+// ---------------------------------------------------------------------------
+/** The variable a shell or a CI job names it with — a zen ref. */
+export const MODEL_ENV = 'ZENERA_GYM_MODEL';
+export const SOURCE_LABELS = {
+    flag: '--model',
+    env: MODEL_ENV,
+    store: 'zen gym model',
+    default: 'recommended',
+};
+const EMPTY = { version: 1 };
+const settingsPath = () => join(home(), 'gym.json');
+export const readSettings = () => readJson(settingsPath(), EMPTY);
+export function writeSettings(file) {
+    ensureHome();
+    writeJson(settingsPath(), file);
+}
+/** What `open` would run, and where it came from, so a command can say so too. */
+export async function chooseModel(flag, keys) {
+    const chain = [
+        ['flag', flag],
+        ['env', process.env[MODEL_ENV]],
+        ['store', (await readSettings()).model],
+        ['default', defaultRef(keys)],
+    ];
+    for (const [from, ref] of chain) {
+        const named = ref?.trim();
+        if (named) {
+            return { ref: named, from };
+        }
+    }
+    return undefined;
+}
+export async function open(opts) {
+    if (opts.specs.length === 0) {
+        throw invalidError('no specification given', 'name one or more openapi/swagger files');
+    }
+    // Real environment variables win, exactly as they do for `zen`.
+    ensureHome();
+    const keys = await KeyStore.open();
+    keys.materialize();
+    const choice = await chooseModel(opts.model, keys);
+    if (!choice) {
+        throw credentialError('no credentials for any provider', 'add one with: zen key add openai');
+    }
+    const model = createModel(choice.ref);
+    const root = resolve(opts.cwd, opts.cache ?? paths.gym());
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    // Podman is asked about before the image is built, so a machine without a
+    // container engine says so instead of failing halfway through a build.
+    await ensurePodmanReady({ image: opts.image, yes: true });
+    const image = opts.image ?? (await ensureImage({ root, onBuild: opts.onImageBuild }));
+    const operations = await loadSpecs(opts.specs.map((s) => resolve(opts.cwd, s)));
+    if (operations.length === 0) {
+        throw invalidError('the specification declares no operations');
+    }
+    const router = new Router(operations);
+    const checks = new Checks();
+    const box = new Box({ root, image, timeout: opts.timeout });
+    await box.fresh();
+    const cache = new Cache({
+        box,
+        checks,
+        model,
+        attempts: opts.attempts,
+        concurrency: opts.concurrency,
+        rebuild: opts.rebuild,
+        ephemeral: opts.ephemeral,
+        ...opts.events,
+    });
+    return { router, checks, cache, box, model, choice, image, root, close: () => box.dispose() };
+}
+/**
+ * Presence, not liveness. `zen init` probes because it is writing a project
+ * that has to work later; this is about to make a call anyway, and the call
+ * itself is a better test than a round trip that costs the same.
+ */
+function defaultRef(keys) {
+    const provider = PROVIDERS.find((p) => envNames(p).some((name) => process.env[name])) ??
+        PROVIDERS.find((p) => keys.active(p) !== undefined);
+    return provider ? DEFAULT_MODEL[provider] : undefined;
+}
+export { SpecError };
+//# sourceMappingURL=setup.js.map

package/dist/spec.d.ts

@@ -0,0 +1,53 @@
+import { CliError } from '@zenera/cli/lib';
+import { type Paging } from './paging.ts';
+import { type Schema } from './schema.ts';
+/**
+ * Version of generator prompt rules and environment contracts.
+ * Bumping this invalidates cached Python generators and triggers regeneration.
+ */
+export declare const GENERATOR_RULES_VERSION = 2;
+export declare const METHODS: readonly ["get", "put", "post", "delete", "patch", "head", "options"];
+export type Method = (typeof METHODS)[number];
+export type ParamIn = 'path' | 'query' | 'header' | 'cookie';
+export interface ParamSpec {
+    name: string;
+    in: ParamIn;
+    required: boolean;
+    schema: Schema;
+    description?: string;
+}
+export interface Operation {
+    /** cache identity — a pure function of the operation's shape, see `keyOf` */
+    key: string;
+    /** the document it came from, for error messages */
+    source: string;
+    method: Method;
+    /** the template, `/users/{user_id}` */
+    path: string;
+    operationId: string;
+    summary?: string;
+    description?: string;
+    params: ParamSpec[];
+    /** query values the path key pinned down, see `splitQuery` */
+    fixed?: Record<string, string>;
+    requestBody?: {
+        required: boolean;
+        schema: Schema;
+    };
+    /** the response a call is answered with; `schema` absent means no body */
+    success: {
+        status: number;
+        schema?: Schema;
+    };
+    /** how the operation turns pages, when it turns pages at all */
+    paging?: Paging;
+}
+/** A `CliError` so an unreadable document exits 3 wherever it is raised. */
+export declare class SpecError extends CliError {
+    constructor(message: string, hint?: string);
+}
+export declare function loadSpecs(files: readonly string[]): Promise<Operation[]>;
+export declare function loadSpec(file: string): Promise<Operation[]>;
+/** The path as it has to be called — what a person needs to see. */
+export declare const called: (op: Operation) => string;
+//# sourceMappingURL=spec.d.ts.map

package/dist/spec.js

@@ -0,0 +1,303 @@
+import SwaggerParser from '@apidevtools/swagger-parser';
+import { CliError, EXIT } from '@zenera/cli/lib';
+import { createHash } from 'node:crypto';
+import { pagingOf } from "./paging.js";
+import { normalize } from "./schema.js";
+/**
+ * Version of generator prompt rules and environment contracts.
+ * Bumping this invalidates cached Python generators and triggers regeneration.
+ */
+export const GENERATOR_RULES_VERSION = 2;
+// ---------------------------------------------------------------------------
+// Documents, flattened
+//
+// Everything below this file works on `Operation`, which is one method on one
+// path with its schemas already dereferenced and already 2020-12. Which
+// document it came from, and which of the three dialects that document was
+// written in, stops mattering here.
+//
+// `dereference` is used rather than `bundle` on purpose: the generator is asked
+// to produce a body for one operation, and it should see that operation's
+// shapes rather than a pointer into a components section it was never shown.
+// ---------------------------------------------------------------------------
+export const METHODS = ['get', 'put', 'post', 'delete', 'patch', 'head', 'options'];
+const isObject = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** A `CliError` so an unreadable document exits 3 wherever it is raised. */
+export class SpecError extends CliError {
+    constructor(message, hint) {
+        super(message, EXIT.invalid, hint);
+        this.name = 'SpecError';
+    }
+}
+// ---------------------------------------------------------------------------
+// Loading
+// ---------------------------------------------------------------------------
+export async function loadSpecs(files) {
+    const out = [];
+    for (const file of files) {
+        out.push(...(await loadSpec(file)));
+    }
+    return out;
+}
+export async function loadSpec(file) {
+    let doc;
+    try {
+        doc = (await SwaggerParser.dereference(file));
+    }
+    catch (err) {
+        throw new SpecError(`${file}: ${err instanceof Error ? err.message.split('\n')[0] : String(err)}`, 'the document must be a readable OpenAPI 3.x or Swagger 2.0 file');
+    }
+    const dialect = dialectOf(doc);
+    const prefix = dialect === 'swagger-2.0' ? (doc.basePath ?? '') : '';
+    const out = [];
+    for (const [template, item] of Object.entries(doc.paths ?? {})) {
+        if (!isObject(item)) {
+            continue;
+        }
+        // Path-level parameters apply to every method on it, and an operation
+        // may override one by repeating its name and location.
+        const shared = params(item.parameters, dialect);
+        for (const method of METHODS) {
+            const op = item[method];
+            if (!isObject(op)) {
+                continue;
+            }
+            const { path, fixed } = splitQuery(join(prefix, template));
+            const merged = override(override(shared, params(op.parameters, dialect)), pinned(fixed));
+            out.push(build({
+                source: file,
+                dialect,
+                method,
+                path,
+                fixed,
+                op,
+                params: merged,
+                body: requestBody(op, dialect),
+            }));
+        }
+    }
+    return out;
+}
+function dialectOf(doc) {
+    if (doc.swagger?.startsWith('2.')) {
+        return 'swagger-2.0';
+    }
+    if (doc.openapi?.startsWith('3.1')) {
+        return 'openapi-3.1';
+    }
+    if (doc.openapi?.startsWith('3.')) {
+        return 'openapi-3.0';
+    }
+    throw new SpecError('neither `swagger: 2.0` nor `openapi: 3.x` is declared');
+}
+function join(prefix, template) {
+    const base = prefix.replace(/\/+$/, '');
+    return `${base}${template.startsWith('/') ? '' : '/'}${template}` || '/';
+}
+/** The path as it has to be called — what a person needs to see. */
+export const called = (op) => op.fixed ? `${op.path}?${new URLSearchParams(op.fixed).toString()}` : op.path;
+/**
+ * A path template has no query string, but some vendors write one
+ * anyway — `/x/{id}?action=retry` — because they need two `post`s under one
+ * path and the object model gives them one. Taken verbatim the key matches
+ * nothing, since a request path never contains a `?`. So it is read for what
+ * it means: the path is the part before the `?`, and each pair after it is a
+ * query value this operation insists on.
+ */
+function splitQuery(template) {
+    const cut = template.indexOf('?');
+    if (cut < 0) {
+        return { path: template };
+    }
+    const fixed = {};
+    for (const [name, value] of new URLSearchParams(template.slice(cut + 1))) {
+        fixed[name] = value;
+    }
+    const path = template.slice(0, cut) || '/';
+    return Object.keys(fixed).length > 0 ? { path, fixed } : { path };
+}
+/** A one-value enum, so the check, the page and the generator all see the rule. */
+function pinned(fixed) {
+    return Object.entries(fixed ?? {}).map(([name, value]) => ({
+        name,
+        in: 'query',
+        required: true,
+        schema: { type: 'string', enum: [value] },
+    }));
+}
+function build(b) {
+    const success = successOf(b.op, b.dialect);
+    const operationId = typeof b.op.operationId === 'string' && b.op.operationId
+        ? b.op.operationId
+        : synthesizeId(b.method, b.path, b.fixed);
+    const operation = {
+        key: '',
+        source: b.source,
+        method: b.method,
+        path: b.path,
+        operationId,
+        summary: typeof b.op.summary === 'string' ? b.op.summary : undefined,
+        description: typeof b.op.description === 'string' ? b.op.description : undefined,
+        params: b.params,
+        fixed: b.fixed,
+        requestBody: b.body,
+        success,
+        paging: pagingOf(b.params, success.schema, b.body?.schema),
+    };
+    return { ...operation, key: keyOf(operation) };
+}
+/**
+ * Cache identity. Everything that changes what a generator must produce is in
+ * here and nothing else is — not the file it came from, not its summary, not
+ * the order of its keys. Editing a spec therefore yields a new key and the old
+ * artefact is simply never looked up again, so there is no invalidation step
+ * to get wrong.
+ */
+function keyOf(op) {
+    const shape = {
+        version: GENERATOR_RULES_VERSION,
+        method: op.method,
+        path: op.path,
+        operationId: op.operationId,
+        params: [...op.params]
+            .sort((a, b) => `${a.in}:${a.name}`.localeCompare(`${b.in}:${b.name}`))
+            .map((p) => [p.in, p.name, p.required, canonical(p.schema)]),
+        body: op.requestBody ? [op.requestBody.required, canonical(op.requestBody.schema)] : null,
+        success: [op.success.status, op.success.schema ? canonical(op.success.schema) : null],
+        // Derived from the two above, so it adds nothing to the identity — it is
+        // here to *change* it, once, for the operations whose generator now has
+        // a pagination rule to obey. Absent rather than null when there is no
+        // paging, so that everything else hashes to exactly what it did before
+        // and no one else is asked to rebuild.
+        ...(op.paging ? { paging: canonical(op.paging) } : {}),
+    };
+    return createHash('sha256').update(JSON.stringify(shape)).digest('hex').slice(0, 16);
+}
+/** Key order is a formatting accident; it must not change a cache key. */
+function canonical(value) {
+    if (Array.isArray(value)) {
+        return value.map(canonical);
+    }
+    if (isObject(value)) {
+        return Object.keys(value)
+            .sort()
+            .map((k) => [k, canonical(value[k])]);
+    }
+    return value;
+}
+function synthesizeId(method, path, fixed) {
+    const words = [...path.split('/'), ...Object.values(fixed ?? {})]
+        .filter(Boolean)
+        .map((s) => s.replace(/[{}]/g, '').replace(/[^A-Za-z0-9]+/g, '_'));
+    return [method, ...words].join('_');
+}
+// ---------------------------------------------------------------------------
+// Parameters
+// ---------------------------------------------------------------------------
+function params(raw, dialect) {
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (!isObject(entry) || typeof entry.name !== 'string') {
+            continue;
+        }
+        const where = entry.in;
+        if (where !== 'path' && where !== 'query' && where !== 'header' && where !== 'cookie') {
+            continue; // `body` and `formData` are handled as a request body
+        }
+        out.push({
+            name: entry.name,
+            in: where,
+            required: where === 'path' ? true : entry.required === true,
+            schema: normalize(paramSchema(entry, dialect), dialect),
+            description: typeof entry.description === 'string' ? entry.description : undefined,
+        });
+    }
+    return out;
+}
+/**
+ * Swagger 2.0 puts a non-body parameter's type keywords directly on the
+ * parameter object; OpenAPI 3 moved them under `schema`. Both end up as a
+ * schema, so the difference is confined to this function.
+ */
+function paramSchema(entry, dialect) {
+    if (dialect !== 'swagger-2.0') {
+        return isObject(entry.schema) ? entry.schema : {};
+    }
+    const { name: _name, in: _in, required: _required, description: _description, collectionFormat: _collectionFormat, allowEmptyValue: _allowEmptyValue, ...rest } = entry;
+    return rest;
+}
+/** Operation-level parameters win over path-level ones with the same identity. */
+function override(base, own) {
+    const merged = new Map(base.map((p) => [`${p.in}:${p.name}`, p]));
+    for (const p of own) {
+        merged.set(`${p.in}:${p.name}`, p);
+    }
+    return [...merged.values()];
+}
+function requestBody(op, dialect) {
+    if (dialect === 'swagger-2.0') {
+        const list = Array.isArray(op.parameters) ? op.parameters : [];
+        const body = list.find((p) => isObject(p) && p.in === 'body');
+        if (!body || !isObject(body.schema)) {
+            return undefined;
+        }
+        return { required: body.required === true, schema: normalize(body.schema, dialect) };
+    }
+    const rb = op.requestBody;
+    if (!isObject(rb)) {
+        return undefined;
+    }
+    const schema = jsonContent(rb.content);
+    return schema
+        ? { required: rb.required === true, schema: normalize(schema, dialect) }
+        : undefined;
+}
+// ---------------------------------------------------------------------------
+// Responses
+// ---------------------------------------------------------------------------
+/**
+ * The response a call gets answered with: the lowest 2xx that carries a JSON
+ * body, or the lowest 2xx at all when none of them do. An operation whose
+ * success response has no JSON schema is answered `204` and never gets a
+ * generator — there is nothing for one to produce.
+ */
+function successOf(op, dialect) {
+    const responses = isObject(op.responses) ? op.responses : {};
+    const codes = Object.keys(responses)
+        .map(Number)
+        .filter((n) => Number.isInteger(n) && n >= 200 && n < 300)
+        .sort((a, b) => a - b);
+    for (const status of codes) {
+        const schema = responseSchema(responses[String(status)], dialect);
+        if (schema) {
+            return { status, schema: normalize(schema, dialect) };
+        }
+    }
+    return { status: codes[0] ?? 204 };
+}
+function responseSchema(response, dialect) {
+    if (!isObject(response)) {
+        return undefined;
+    }
+    if (dialect === 'swagger-2.0') {
+        return isObject(response.schema) ? response.schema : undefined;
+    }
+    return jsonContent(response.content);
+}
+/** The first JSON media type a content map offers, `+json` suffixes included. */
+function jsonContent(content) {
+    if (!isObject(content)) {
+        return undefined;
+    }
+    for (const [type, entry] of Object.entries(content)) {
+        const base = type.split(';')[0].trim();
+        if ((base === 'application/json' || base.endsWith('+json')) && isObject(entry)) {
+            return isObject(entry.schema) ? entry.schema : undefined;
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=spec.js.map

package/dist/validate.d.ts

@@ -0,0 +1,21 @@
+import { type ErrorObject, type ValidateFunction } from 'ajv/dist/2020.js';
+import type { Operation } from './spec.ts';
+export interface Issue {
+    where: string;
+    message: string;
+}
+export declare class Checks {
+    #private;
+    constructor();
+    for(operation: Operation): Compiled;
+}
+export interface Compiled {
+    path: ValidateFunction;
+    query: ValidateFunction;
+    body?: ValidateFunction;
+    bodyRequired: boolean;
+    response?: ValidateFunction;
+}
+export declare function issues(prefix: string, errors: ErrorObject[] | null | undefined): Issue[];
+export declare function describeIssues(list: readonly Issue[]): string;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.js

@@ -0,0 +1,83 @@
+// Both packages are CommonJS. `ajv/dist/2020` has a real named export, so it is
+// imported by name; `ajv-formats` sets `module.exports` to the plugin function
+// but also declares named exports, which NodeNext models as a namespace with a
+// synthetic default. The value is callable at runtime; only the type is wrong.
+import addFormatsDefault from 'ajv-formats';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+const addFormats = addFormatsDefault;
+export class Checks {
+    // `logger: false` silences "unknown format … ignored". Real documents are
+    // full of vendor formats (`ip`, `mac-address`) and there is nothing to do
+    // about them; left on, one spec buries the request log in warnings.
+    #strict = new Ajv2020({
+        allErrors: true,
+        strict: false,
+        validateFormats: true,
+        logger: false,
+    });
+    #loose = new Ajv2020({
+        allErrors: true,
+        strict: false,
+        coerceTypes: true,
+        useDefaults: false,
+        validateFormats: true,
+        logger: false,
+    });
+    #cache = new Map();
+    constructor() {
+        addFormats(this.#strict);
+        addFormats(this.#loose);
+    }
+    for(operation) {
+        const hit = this.#cache.get(operation.key);
+        if (hit) {
+            return hit;
+        }
+        const compiled = {
+            path: this.#loose.compile(envelope(operation.params, 'path')),
+            query: this.#loose.compile(envelope(operation.params, 'query')),
+            body: operation.requestBody
+                ? this.#strict.compile(operation.requestBody.schema)
+                : undefined,
+            bodyRequired: operation.requestBody?.required === true,
+            response: operation.success.schema
+                ? this.#strict.compile(operation.success.schema)
+                : undefined,
+        };
+        this.#cache.set(operation.key, compiled);
+        return compiled;
+    }
+}
+/**
+ * Parameters are validated as one object rather than one at a time, so a
+ * request with three wrong values is answered once with all three.
+ */
+function envelope(params, where) {
+    const mine = params.filter((p) => p.in === where);
+    return {
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: Object.fromEntries(mine.map((p) => [p.name, stripped(p.schema)])),
+        required: mine.filter((p) => p.required).map((p) => p.name),
+        // A query string may carry anything; only what the spec names is checked.
+        additionalProperties: true,
+    };
+}
+/** A subschema must not carry its own `$schema`; only the envelope may. */
+function stripped(schema) {
+    const { $schema: _ignored, ...rest } = schema;
+    return rest;
+}
+// ---------------------------------------------------------------------------
+// Reporting
+// ---------------------------------------------------------------------------
+export function issues(prefix, errors) {
+    return (errors ?? []).map((e) => ({
+        where: `${prefix}${e.instancePath}`,
+        message: e.message ?? 'is invalid',
+    }));
+}
+export function describeIssues(list) {
+    return list.map((i) => `${i.where || '(root)'} ${i.message}`).join('; ');
+}
+//# sourceMappingURL=validate.js.map

package/package.json

@@ -1,6 +1,54 @@
 {
-  "name": "@zenera/gym",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@zenera/gym",
+    "version": "1.1.38",
+    "description": "Simulated API environments for agent training and evaluation, powered by OpenAPI and model-written generators.",
+    "keywords": [
+        "openapi",
+        "swagger",
+        "mock-server",
+        "llm",
+        "testing",
+        "agents",
+        "simulation",
+        "evaluation"
+    ],
+    "license": "MIT",
+    "publishConfig": {
+        "access": "public"
+    },
+    "author": "Andrey Ryabov",
+    "homepage": "https://github.com/zenera-ai/ZeneraNeo#readme",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/zenera-ai/ZeneraNeo.git",
+        "directory": "packages/gym"
+    },
+    "bugs": "https://github.com/zenera-ai/ZeneraNeo/issues",
+    "private": false,
+    "type": "module",
+    "exports": {
+        "./command": {
+            "types": "./dist/command.d.ts",
+            "default": "./dist/command.js"
+        }
+    },
+    "files": [
+        "dist",
+        "!dist/**/*.map"
+    ],
+    "engines": {
+        "node": ">=24"
+    },
+    "scripts": {
+        "build": "tsc -b",
+        "clean": "tsc -b --clean && rm -rf dist",
+        "prepack": "tsc -b"
+    },
+    "dependencies": {
+        "@apidevtools/swagger-parser": "^12.0.0",
+        "ajv": "^8.17.1",
+        "ajv-formats": "^3.0.1",
+        "@zenera/cli": "^1.1.38",
+        "@zenera/neo": "^1.1.38"
+    }
+}