@zenera/gym 1.1.40 → 1.1.41

package/dist/generate.js

@@ -1,22 +1,44 @@
+import { loose, tool } from '@zenera/neo';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import RandExp from 'randexp';
+import { runAgent } from "./agents.js";
+import { ACCOUNTS, OWNER_TYPE } from "./runtime.js";
 import { tokenOf } from "./paging.js";
 import { echoIssues, nextPage, probesFor, walkStart } from "./probe.js";
-import { instruction, regenerationInstruction, retry, SYSTEM, } from "./prompt.js";
+import { brief, repairBrief, retryNudge, SYSTEM } from "./prompt.js";
+import { properties } from "./schema.js";
 import { called } from "./spec.js";
 import { describeIssues, issues } from "./validate.js";
-/**
- * Tries per generator. Each one carries the previous file and what was wrong
- * with it, so the later attempts are the informed ones — a model that has seen
- * its own traceback usually needs two or three goes at a fiddly schema, and the
- * whole loop costs nothing once the file is cached.
- */
+// ---------------------------------------------------------------------------
+// Writing a handler
+//
+// An agent with tools rather than a prompt with a retry loop. It can look
+// before it writes — the operations around this one, the handlers already
+// written for them, the collections the world already holds, any type it was
+// not shown — and that is what makes `getMessage` read the collection
+// `listMessages` filled instead of inventing its own.
+//
+// It cannot decide it is finished. `test_handler` is the judge: it runs the
+// module against probe requests in a throwaway copy of the world and reports
+// everything wrong with the answers, and the first test that passes ends the
+// run. The judgement is deliberately harsher than the schema — a body can
+// validate and still be about somebody else (the echo rule), or validate and
+// page forever (the walk).
+// ---------------------------------------------------------------------------
+/** Failed tests per build before giving up. */
 export const DEFAULT_ATTEMPTS = 5;
+/** How many times a run that stopped without passing is started again. */
+const RESTARTS = 2;
 export class BuildFailed extends Error {
     operation;
     diagnostics;
     /** the build report on disk, filled in by whoever was writing one */
     dump;
+    /** the agent's HTML run report */
+    report;
     constructor(operation, diagnostics) {
-        super(`could not write a generator for ${operation.method.toUpperCase()} ${called(operation)}`);
+        super(`could not write a handler for ${operation.method.toUpperCase()} ${called(operation)}`);
         this.name = 'BuildFailed';
         this.operation = operation;
         this.diagnostics = diagnostics;
@@ -27,8 +49,7 @@ export class BuildFailed extends Error {
  *
  * `fetch failed` is undici's word for a dozen different problems — a DNS
  * miss, a refused connection, a TLS error, a timeout — and which one it was is
- * only ever in `cause`. Reporting the top-level message alone turns every
- * network fault into the same useless sentence.
+ * only ever in `cause`.
  */
 export function reason(err) {
     if (err instanceof BuildFailed && err.diagnostics.length > 0) {
@@ -53,148 +74,376 @@ export function reason(err) {
     }
     return parts.join(' — ') || String(err);
 }
-export async function build(operation, opts) {
+/** Writes the handler for an operation, or repairs the one it has. */
+export async function build(operation, opts, repair) {
     const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
-    const probes = probesFor(operation);
-    const response = opts.checks.for(operation).response;
-    const messages = [
-        { role: 'user', content: [{ type: 'text', text: instruction(operation) }] },
-    ];
-    let last = [];
-    for (let attempt = 1; attempt <= limit; attempt++) {
-        const answer = await ask(opts, {
-            system: SYSTEM,
-            messages,
-            tools: [],
+    const state = {
+        bindings: {},
+        failures: 0,
+        passed: undefined,
+        last: [],
+        lastSource: '',
+    };
+    let report;
+    const intro = [
+        brief(operation, {
+            catalog: opts.catalog,
+            siblings: await siblings(operation, opts),
+            collections: opts.world.store.collections(),
+            bindings: opts.bindings.all(),
+            passages: await opts.world.knowledge.recall([
+                operation.summary,
+                operation.operationId,
+                `${operation.method.toUpperCase()} ${operation.path}`,
+            ]
+                .filter(Boolean)
+                .join(' — '), 3),
+        }),
+        ...(repair ? ['', repairBrief(repair)] : []),
+    ].join('\n');
+    for (let run = 0; run <= RESTARTS && !state.passed && state.failures < limit; run++) {
+        const input = run === 0
+            ? intro
+            : [
+                intro,
+                '',
+                'YOUR LAST VERSION:',
+                '```ts',
+                state.lastSource,
+                '```',
+                '',
+                retryNudge(state.last.length > 0 ? state.last : ['- it was never tested']),
+            ].join('\n');
+        const done = await runAgent({
+            model: opts.model,
+            name: 'builder',
+            label: operation.operationId,
+            instructions: SYSTEM,
+            tools: tools(operation, opts, state, limit),
+            input,
+            maxToolCalls: limit * 3 + 10,
+            done: () => Boolean(state.passed) || state.failures >= limit,
+            reportDir: opts.reportDir,
             signal: opts.signal,
         });
-        const source = unfence(answer.text);
-        if (!source.trim()) {
-            last = ['the answer was empty'];
-        }
-        else {
-            await opts.box.write(operation.key, source);
-            last = await judge(operation, probes, response, opts.box);
-            if (last.length === 0) {
-                return { source, attempts: attempt };
-            }
-        }
-        await opts.onAttempt?.(attempt, last, source, limit);
-        messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
+        report = done.report ?? report;
     }
-    throw new BuildFailed(operation, last);
+    if (state.passed) {
+        return {
+            source: state.passed,
+            attempts: Math.max(1, state.failures + 1),
+            report,
+            bindings: state.bindings,
+        };
+    }
+    const failed = new BuildFailed(operation, state.last.length > 0 ? state.last : ['the agent stopped without testing a handler']);
+    failed.report = report;
+    throw failed;
 }
-export async function regenerate(operation, opts) {
-    const limit = Math.max(1, opts.attempts ?? DEFAULT_ATTEMPTS);
-    const exampleInputs = opts.examples?.map((e) => e.input) ?? [];
-    const probes = [opts.failingInput, ...exampleInputs, ...probesFor(operation)];
-    const response = opts.checks.for(operation).response;
-    const messages = [
-        {
-            role: 'user',
-            content: [
-                {
-                    type: 'text',
-                    text: regenerationInstruction({
-                        operation,
-                        currentSource: opts.currentSource,
-                        failingInput: opts.failingInput,
-                        fault: opts.fault,
-                        stderr: opts.stderr,
-                        examples: opts.examples,
-                    }),
-                },
-            ],
+function tools(operation, opts, state, limit) {
+    const listOperations = tool({
+        name: 'list_operations',
+        description: 'Operations this server answers, with whether each already has a handler. ' +
+            'Filter by path (e.g. "/users/*/messages*") or by operationId.',
+        parameters: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'A substring, or a glob with * and ?.' },
+                name: { type: 'string', description: 'A substring of the operationId.' },
+            },
+            additionalProperties: false,
         },
-    ];
-    let last = [];
-    for (let attempt = 1; attempt <= limit; attempt++) {
-        const answer = await ask(opts, {
-            system: SYSTEM,
-            messages,
-            tools: [],
-            signal: opts.signal,
-        });
-        const source = unfence(answer.text);
-        if (!source.trim()) {
-            last = ['the answer was empty'];
-        }
-        else {
-            await opts.box.write(operation.key, source);
-            last = await judge(operation, probes, response, opts.box);
-            if (last.length === 0) {
-                return { source, attempts: attempt };
+        execute: async ({ path, name }) => {
+            const byPath = path ? loose(path) : undefined;
+            const byName = name ? loose(name) : undefined;
+            const found = opts.operations.filter((o) => (!byPath || byPath(o.path)) && (!byName || byName(o.operationId)));
+            const rows = await Promise.all(found.slice(0, 80).map(async (o) => {
+                const built = Boolean(await opts.sourceOf(o));
+                return `${built ? '[built]' : '[     ]'} ${o.method.toUpperCase()} ${called(o)}  ${o.operationId}`;
+            }));
+            return { found: found.length, operations: rows };
+        },
+    });
+    const readHandler = tool({
+        name: 'read_handler',
+        description: 'The handler already written for another operation. Read the siblings of this ' +
+            'operation before writing it, and use the same collections and types they use.',
+        parameters: {
+            type: 'object',
+            properties: { operationId: { type: 'string' } },
+            required: ['operationId'],
+            additionalProperties: false,
+        },
+        execute: async ({ operationId }) => {
+            const other = opts.operations.find((o) => o.operationId === operationId);
+            if (!other) {
+                return {
+                    error: `no operation called ${operationId}`,
+                    hint: 'call list_operations',
+                };
+            }
+            const source = await opts.sourceOf(other);
+            return source ? { source } : { error: `${operationId} has no handler yet` };
+        },
+    });
+    const listCollections = tool({
+        name: 'list_collections',
+        description: 'The collections the world holds, with record counts and sample ids.',
+        parameters: { type: 'object', properties: {}, additionalProperties: false },
+        execute: () => ({ collections: opts.world.store.collections() }),
+    });
+    const readCollection = tool({
+        name: 'read_collection',
+        description: 'A few records from a collection, to see the shape stored there.',
+        parameters: {
+            type: 'object',
+            properties: {
+                collection: { type: 'string' },
+                limit: { type: 'integer', description: 'Default 3.' },
+            },
+            required: ['collection'],
+            additionalProperties: false,
+        },
+        execute: ({ collection, limit }) => {
+            const col = opts.world.store.collection(collection);
+            const text = JSON.stringify(col.all().slice(0, Math.min(limit ?? 3, 10)));
+            return {
+                total: col.count(),
+                records: text.length > 12_000 ? `${text.slice(0, 12_000)}…` : JSON.parse(text),
+            };
+        },
+    });
+    const describeTypes = tool({
+        name: 'describe_types',
+        description: 'Schema types by name, as TypeScript, with everything they refer to.',
+        parameters: {
+            type: 'object',
+            properties: { names: { type: 'array', items: { type: 'string' } } },
+            required: ['names'],
+            additionalProperties: false,
+        },
+        execute: ({ names }) => {
+            const { code, omitted } = opts.catalog.declare(names, 30_000);
+            return code
+                ? { typescript: code, ...(omitted.length ? { omitted } : {}) }
+                : { error: `no such type: ${names.join(', ')}` };
+        },
+    });
+    const testHandler = tool({
+        name: 'test_handler',
+        description: 'Saves the handler module and judges it: runs it against probe requests in a ' +
+            'copy of the world, checks every answer against the response schema, the echo ' +
+            'rule and, for paged operations, that the pages advance and end. Returns ok, or ' +
+            'every problem found.',
+        parameters: {
+            type: 'object',
+            properties: {
+                source: { type: 'string', description: 'The whole TypeScript module.' },
+            },
+            required: ['source'],
+            additionalProperties: false,
+        },
+        execute: async ({ source }) => {
+            if (state.passed || state.failures >= limit) {
+                return { error: 'the build is over' };
             }
+            const code = unfence(String(source ?? ''));
+            state.lastSource = code;
+            const { problems, placed } = code.trim()
+                ? await test(operation, code, opts)
+                : { problems: ['- the module is empty'], placed: {} };
+            if (problems.length === 0) {
+                // Bound only on a pass: a failing handler must not fix where a
+                // type lives for everyone after it.
+                for (const [type, binding] of Object.entries(placed)) {
+                    opts.bindings.bind(type, binding);
+                }
+                state.passed = code;
+                state.bindings = placed;
+                return { ok: true };
+            }
+            state.failures++;
+            state.last = problems;
+            await opts.onAttempt?.(state.failures, problems, code, limit);
+            return {
+                ok: false,
+                problems,
+                testsLeft: Math.max(0, limit - state.failures),
+            };
+        },
+    });
+    return [
+        listOperations,
+        readHandler,
+        listCollections,
+        readCollection,
+        describeTypes,
+        ...opts.catalog.tools(),
+        ...opts.world.knowledge.tools,
+        testHandler,
+    ];
+}
+/** Writes the module and judges it in a copy of the world nobody else can see. */
+async function test(operation, source, opts) {
+    await opts.box.write(operation.key, source);
+    const scratch = join(opts.box.root, 'scratch', `${operation.key}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}.sqlite`);
+    opts.world.store.snapshot(scratch);
+    try {
+        const used = [];
+        const problems = await judge(operation, opts, scratch, used);
+        const { problems: misplaced, placed } = placement(used, opts);
+        return { problems: [...problems, ...misplaced], placed };
+    }
+    finally {
+        opts.box.release(scratch);
+        opts.world.release(scratch);
+        for (const suffix of ['', '-wal', '-shm']) {
+            rmSync(`${scratch}${suffix}`, { force: true });
         }
-        await opts.onAttempt?.(attempt, last, source, limit);
-        messages.push({ role: 'assistant', content: source }, { role: 'user', content: [{ type: 'text', text: retry(last) }] });
     }
-    throw new BuildFailed(operation, last);
-}
-/**
- * Streamed when the adapter can, and every delta is dropped: nothing here
- * renders progress. It is the *socket* that needs them.
- *
- * A generator is a few hundred lines, and a model asked for one in a single
- * non-streaming call sends nothing at all while it thinks. Something upstream
- * closes a connection that has been idle for a minute, and the whole attempt
- * dies with `UND_ERR_SOCKET other side closed` at ~61 s — not a timeout anyone
- * here set, and not the SDK's, which is ten minutes. Tokens on the wire keep
- * it open.
- */
-function ask(opts, request) {
-    return opts.model.stream ? opts.model.stream(request, discard) : opts.model.generate(request);
 }
-const discard = () => { };
-/** Every probe, run and checked. Empty means the generator is good. */
-async function judge(operation, probes, response, box) {
+async function judge(operation, opts, db, used) {
+    const response = opts.checks.for(operation).response;
     const out = [];
-    for (const probe of probes) {
-        const outcome = await box.run(operation.key, probe);
-        const what = `input ${JSON.stringify({ pathParams: probe.pathParams, query: probe.query })}`;
+    for (const probe of fitted(operation, probesFor(operation))) {
+        const outcome = await opts.box.run(operation.key, probe, { db, probe: true });
+        used.push(...(outcome.used ?? []));
+        const what = `request ${JSON.stringify({ pathParams: probe.pathParams, query: probe.query, ...(probe.body !== undefined ? { body: probe.body } : {}) }).slice(0, 600)}`;
         if (!outcome.ok) {
-            out.push(`- ${what}: the file ${outcome.fault}.`);
+            out.push(`- ${what}: the handler ${outcome.fault}.`);
             if (outcome.stderr) {
-                out.push(`  stderr: ${tail(outcome.stderr)}`);
+                out.push(`  stack: ${tail(outcome.stderr)}`);
             }
-            // A file that will not run says nothing about the next probe.
             break;
         }
+        if (outcome.status !== undefined) {
+            out.push(`- ${what}: answered HTTP ${outcome.status} ${JSON.stringify(outcome.value).slice(0, 200)}. ` +
+                'An ordinary request must get a body: make missing content with ctx.lookup / ctx.ensure instead of failing.');
+            continue;
+        }
         if (response && !response(outcome.value)) {
-            out.push(`- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`);
+            out.push(`- ${what}: the answer does not match the response schema — ${describeIssues(issues('', response.errors))}. ` +
+                `It answered: ${JSON.stringify(outcome.value).slice(0, 400)}`);
         }
         const echo = echoIssues(probe, outcome.value, operation.success.schema);
         if (echo.length > 0) {
             out.push(`- ${what}: ${describeIssues(echo)}.`);
         }
     }
-    // Only worth the container round trips once the file answers at all, and
-    // only for an operation that hands out a token somebody could follow.
     if (out.length === 0 && operation.paging?.next) {
-        out.push(...(await walk(operation, operation.paging, response, box)));
+        out.push(...(await walk(operation, operation.paging, opts, db, used)));
     }
     return out;
 }
-/** How many pages a mock may offer before it is simply not terminating. */
-const MAX_PAGES = 8;
 /**
- * Follows the operation's own cursor and reports the ways that walk fails to
- * end. A schema cannot express this and neither can any one response: the bug
- * is a relation between two of them.
+ * Probe path values that the response would have to echo, made to fit the
+ * response's own pattern. Asking for message `ada` when ids are sixteen hex
+ * digits is a test no handler can pass.
  */
-async function walk(operation, paging, response, box) {
+function fitted(operation, probes) {
+    const schema = operation.success.schema;
+    if (!schema) {
+        return probes;
+    }
+    const patterned = new Map();
+    for (const p of properties(schema)) {
+        if (typeof p.schema.pattern === 'string' && !patterned.has(p.name)) {
+            patterned.set(p.name, p.schema.pattern);
+        }
+    }
+    return probes.map((probe, i) => {
+        const pathParams = { ...probe.pathParams };
+        for (const name of Object.keys(pathParams)) {
+            const pattern = patterned.get(name);
+            if (pattern) {
+                try {
+                    const gen = new RandExp(pattern);
+                    gen.max = 6;
+                    let n = i + 7;
+                    gen.randInt = (a, b) => a + ((n = (n * 48271) % 2147483647) % (b - a + 1));
+                    pathParams[name] = gen.gen();
+                }
+                catch {
+                    // an unreadable pattern keeps the plain probe value
+                }
+            }
+        }
+        return { ...probe, pathParams };
+    });
+}
+/**
+ * Where the handler put each type it touched, checked against where every
+ * handler before it put them. Untyped access is refused outright: a collection
+ * nobody can name a type for is a collection the next handler cannot find.
+ */
+function placement(used, opts) {
+    const problems = new Set();
+    const byType = new Map();
+    for (const use of used) {
+        if (use.collection === ACCOUNTS || use.type === OWNER_TYPE) {
+            continue;
+        }
+        if (!use.type) {
+            problems.add(`- \`${use.collection}\` is used without a type. Name the type instead — ` +
+                `ctx.lookup('Message', id), ctx.ensure('Message', …), ctx.db.collection('Message') — ` +
+                'so every handler finds the same records in the same place.');
+            continue;
+        }
+        if (!opts.catalog.hasType(use.type)) {
+            problems.add(`- \`${use.type}\` is not a type the documents declare; ` +
+                'describe_types, list_api or grep_api finds the right name.');
+            continue;
+        }
+        const seen = byType.get(use.type) ?? { collections: new Set(), idFields: new Set() };
+        seen.collections.add(use.collection);
+        if (use.idField) {
+            seen.idFields.add(use.idField);
+        }
+        byType.set(use.type, seen);
+    }
+    const placed = {};
+    for (const [type, seen] of byType) {
+        if (seen.collections.size > 1 || seen.idFields.size > 1) {
+            problems.add(`- \`${type}\` is stored two ways in this handler ` +
+                `(${[...seen.collections].join(', ')}; keyed by ${[...seen.idFields].join(', ') || 'id'}). ` +
+                'Use one type name and one id field throughout.');
+            continue;
+        }
+        const binding = {
+            collection: [...seen.collections][0],
+            idField: [...seen.idFields][0] ?? opts.bindings.of(type)?.idField ?? 'id',
+        };
+        const conflict = opts.bindings.conflict(type, binding);
+        if (conflict) {
+            problems.add(`- ${conflict} — fixed by an earlier handler. Use the type name ` +
+                `(ctx.lookup('${type}', …)) and leave the collection and id field to the binding.`);
+            continue;
+        }
+        placed[type] = binding;
+    }
+    return { problems: [...problems], placed };
+}
+/** How many pages a judged handler may offer before it is not terminating. */
+const MAX_PAGES = 8;
+async function walk(operation, paging, opts, db, used) {
     let input = walkStart(operation, paging);
     const seen = new Set();
     let sent;
+    // Enough content to need more than one page, so the token is exercised.
+    if (paging.size) {
+        input = setSize(input, paging, 2);
+    }
     for (let page = 1; page <= MAX_PAGES; page++) {
-        const outcome = await box.run(operation.key, input);
+        const outcome = await opts.box.run(operation.key, input, { db, probe: true });
+        used.push(...(outcome.used ?? []));
         const what = `page ${page} of ${operation.method.toUpperCase()} ${called(operation)}`;
         if (!outcome.ok) {
-            return [`- ${what}: the file ${outcome.fault}.`];
+            return [`- ${what}: the handler ${outcome.fault}.`];
         }
+        const response = opts.checks.for(operation).response;
         if (response && !response(outcome.value)) {
             return [
-                `- ${what}: the output does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
+                `- ${what}: the answer does not match the response schema — ${describeIssues(issues('', response.errors))}.`,
             ];
         }
         const token = tokenOf(outcome.value, paging);
@@ -203,12 +452,12 @@ async function walk(operation, paging, response, box) {
         }
         if (token === sent) {
             return [
-                `- ${what}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the very token the request carried in \`${paging.param}\`. A client following it never advances. Build the token from \`${paging.param}\` so it counts up, and stop after pagination ends.`,
+                `- ${what}: \`${paging.next}\` came back as ${JSON.stringify(token)}, the token the request sent in \`${paging.param}\`. Pass the client's token to ctx.page and answer with its nextToken.`,
             ];
         }
         if (seen.has(token)) {
             return [
-                `- ${what}: the page tokens cycle — ${JSON.stringify(token)} was handed out earlier in this walk. Every page must offer a token no page has offered before, and the last one must offer none.`,
+                `- ${what}: the page tokens cycle — ${JSON.stringify(token)} was handed out before.`,
             ];
         }
         seen.add(token);
@@ -216,12 +465,60 @@ async function walk(operation, paging, response, box) {
         input = nextPage(input, paging, token);
     }
     return [
-        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Fabricate between 1 and 10 pages in total and set it to null on the last.`,
+        `- ${operation.method.toUpperCase()} ${operation.path}: the pages never run out — after ${MAX_PAGES} of them \`${paging.next}\` is still set. Page with ctx.page so the list ends.`,
     ];
 }
+function setSize(input, paging, size) {
+    if (!paging.size) {
+        return input;
+    }
+    if (paging.paramIn === 'body' && typeof input.body === 'object' && input.body !== null) {
+        return { ...input, body: { ...input.body, [paging.size]: size } };
+    }
+    return { ...input, query: { ...input.query, [paging.size]: String(size) } };
+}
+/** Operations sharing this one's resource path, or a response type with it. */
+/**
+ * The operations a handler must agree with, closest first. Same record type and
+ * same resource are the strongest ties; operations that merely carry the type
+ * somewhere (traced through the graph) come next; nearby paths last. In a large
+ * API the list is cut, and the cut must fall on the weakest.
+ */
+async function siblings(operation, opts) {
+    const base = resourceOf(operation.path);
+    const mine = opts.catalog.itemType(operation);
+    const carriers = new Set((mine ? opts.catalog.carriers(mine) : []).map((c) => `${c.method} ${c.path}`));
+    const scored = opts.operations
+        .filter((o) => o !== operation)
+        .map((o) => {
+        const type = opts.catalog.itemType(o);
+        const other = resourceOf(o.path);
+        const score = (mine && type === mine ? 4 : 0) +
+            (other === base ? 3 : 0) +
+            (carriers.has(`${o.method} ${o.path}`) ? 2 : 0) +
+            (near(o.path, base) ? 1 : 0);
+        return { operation: o, type, score };
+    })
+        .filter((x) => x.score > 0)
+        .sort((a, b) => b.score - a.score || a.operation.path.localeCompare(b.operation.path))
+        .slice(0, 25);
+    return Promise.all(scored.map(async ({ operation: o, type }) => ({
+        operation: o,
+        type,
+        built: Boolean(await opts.sourceOf(o)),
+    })));
+}
+/** One or two segments above or below. */
+function near(path, base) {
+    const depth = (p) => p.split('/').filter(Boolean).length;
+    const [short, long] = path.length < base.length ? [path, base] : [base, path];
+    return long.startsWith(`${short}/`) && depth(long) - depth(short) <= 2;
+}
+/** `/users/{userId}/messages/{id}` → `/users/{userId}/messages`. */
+const resourceOf = (path) => path.replace(/\/\{[^/]+\}$/, '') || '/';
 /**
- * Models fence code even when told not to, and a stray ```python line is a
- * syntax error rather than a bad answer — not worth a round trip.
+ * Models fence code even when told not to, and a stray ```ts line is a syntax
+ * error rather than a bad answer — not worth a round trip.
  */
 export function unfence(text) {
     const trimmed = text.trim();
@@ -232,5 +529,5 @@ export function unfence(text) {
     const close = body.lastIndexOf('```');
     return (close === -1 ? body : body.slice(0, close)).trimEnd();
 }
-const tail = (s) => s.trim().split('\n').slice(-6).join('\n  ');
+const tail = (s) => s.trim().split('\n').slice(0, 6).join('\n  ');
 //# sourceMappingURL=generate.js.map

package/dist/inputs.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Every API document the arguments name, absolute, de-duplicated, in the order
+ * named (and sorted within a directory or a pattern, so a start is repeatable).
+ */
+export declare function expandSchemas(args: readonly string[], cwd: string): Promise<string[]>;
+/**
+ * Checks story and docs arguments before anything reads them. They are read by
+ * `@zenera/rag`, which takes a named file at its word — so an API document
+ * passed here by mistake would quietly become a very long story.
+ */
+export declare function checkTexts(args: readonly string[], cwd: string, flag: '--story' | '--docs'): Promise<void>;
+//# sourceMappingURL=inputs.d.ts.map