@zenera/rag 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,144 @@
+# @zenera/rag
+
+**An OpenAPI description, indexed as a graph and searched by meaning — for
+agents that have to call an API they have not read.**
+
+[![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 `rag` **subcommand** to
+> [`zen`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/cli/README.md),
+> which is also where the credentials already are.
+
+## Why
+
+A large specification does not fit in a prompt, and the parts of it that answer
+a question are scattered: the field is on a schema, the schema is on a request
+body, the request body belongs to one operation out of three hundred. Vector
+search finds the field. Only a graph gets from there to the call.
+
+So this keeps both — a [graphology](https://graphology.github.io) graph for
+structure and a [LanceDB](https://lancedb.com) table for hybrid vector +
+full-text retrieval — and answers with the connected piece of the API that
+matched, rendered as a tree, a Mermaid diagram, TypeScript declarations or a
+standalone OpenAPI document.
+
+## Install
+
+Node.js 24+. Install it alongside the CLI:
+
+```sh
+npm i -g @zenera/cli @zenera/rag openai
+zen key add openai          # the keyring `zen` already uses
+```
+
+## Use
+
+Index once, then ask:
+
+```sh
+zen rag schema index --embedding openai:text-embedding-3-small ./specs/*.yaml
+zen rag schema search --output-property "user billing history"
+zen rag schema search --input-property "password reset token" --format ts
+zen rag schema search --interactive
+zen rag schema stats                  # what is in the index, and what built it
+zen rag schema show Type:Invoice      # a named node, with no search in between
+```
+
+Non-interactive search is a machine interface: every field is a flag, the whole
+query can arrive as one JSON object, `--json` is a stable shape, no terminal is
+required, and an empty result exits 0.
+
+```sh
+zen rag schema search --query - --format ts <<'JSON'
+{
+  "input_properties": ["password reset token"],
+  "method_type": "read_write",
+  "exclude_ids": ["Type:PublicUserProfile"],
+  "limit": 3
+}
+JSON
+```
+
+## Commands
+
+```
+zen rag schema index <spec...>   Read the documents and write a searchable index.
+zen rag schema search            Ask it something. --interactive for a prompt.
+zen rag schema show <id...>      Print named nodes, with no search in between.
+zen rag schema stats             What is in an index, and what built it.
+```
+
+Search terms are one flag each — `--all`, `--method`, `--type`, `--input-type`,
+`--output-type`, `--property`, `--input-property`, `--output-property` — shaped
+by `--direction`, `--method-type`, `--limit`, `--max-hops`, `--max-nodes` and
+the four `--exclude-*` filters, and rendered by `--format text | mermaid |
+mermaid-flowchart | ts | openapi`. `zen help rag` prints the full table.
+
+## From an agent
+
+```ts
+import { createEmbedder, loadProject } from '@zenera/neo';
+import { SchemaIndex, schemaTools } from '@zenera/rag';
+
+const index = await SchemaIndex.open(
+    './schema-db',
+    createEmbedder('openai:text-embedding-3-small'),
+);
+const project = await loadProject('./my-project', { tools: schemaTools(index) });
+```
+
+Four tools in the group `schema`, selectable as `schema:*`:
+
+| Tool                       | For                                                     |
+| -------------------------- | ------------------------------------------------------- |
+| `search_api`               | the connected piece of the API that matches an intent   |
+| `describe_types`           | named schemas as declarations that compile on their own |
+| `find_types_with_property` | which types have a field of this name — no search       |
+| `list_methods`             | the shape of the API, by path                           |
+
+`find_types_with_property` is the one for the repair loop: when `tsc` says
+`'password' does not exist in type 'PublicUserProfile'`, the model does not
+need the word explained again, it needs the list of types that have one.
+
+## What an index is
+
+```
+schema-db/
+├── manifest.json     written last — its absence means "not indexed"
+├── graph.json        topology and light attributes, read whole
+├── schemas.json      the raw schemas, read on first hydrate
+├── operations.json   likewise, for the OpenAPI subset
+└── lance/            one table: a row per node, one text column, one vector
+```
+
+The manifest records which embedder made the vectors, and a search with a
+different one is refused rather than answered with noise.
+
+## Notes
+
+- Documents are **bundled, not dereferenced**: `#/components/schemas/User` is
+  an edge and `User` is a node id. Swagger 2.0, OpenAPI 3.0 and 3.1 are
+  converted to 2020-12 on the way in, `discriminator` included — it is what
+  turns a `oneOf` into a TypeScript tagged union the compiler can narrow.
+- A **query parameter is a property**, like any field in a body. Nobody should
+  have to know in advance which one `page_size` is.
+- Every type carries a **direction** — `input`, `output` or `both` — worked out
+  by propagating from the operations through composition, so a shared DTO is
+  honestly both rather than whichever side was read last.
+- Filters reaching the store are **closed enums only**. Exclusion lists are
+  applied in JavaScript afterwards, so nothing a model wrote ever reaches a SQL
+  predicate.
+
+## 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/faker`](https://github.com/andreyryabov/ZeneraNeo/blob/main/packages/faker/README.md) | `zen faker` — a mock API from the same kind of document |
+
+## License
+
+[MIT](https://github.com/andreyryabov/ZeneraNeo/blob/main/LICENSE).

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

package/dist/command.js

@@ -0,0 +1,436 @@
+import { relative, resolve } from 'node:path';
+import { bold, CliError, cyan, dim, ensureHome, EXIT, isInteractive, json, KeyStore, note, parse, PROVIDERS, SHAPES, table, usageError, write, } from '@zenera/cli/lib';
+import { createEmbedder } from '@zenera/neo';
+import { isFormat, present } from "./present.js";
+import { isEmpty, parseQuery, QueryError } from "./query.js";
+import { repl } from "./repl.js";
+import { buildIndex } from "./schema/build.js";
+import { assertSameEmbedding, openIndex, readManifest } from "./schema/files.js";
+import { SchemaIndex } from "./schema/search.js";
+import { stitch } from "./schema/subgraph.js";
+// ---------------------------------------------------------------------------
+// zen rag — an api description, as something to search
+//
+// `search` has two modes and neither is the afterthought. Interactively it is
+// a loop with prompts; non-interactively it is a tool, and that is the mode
+// that has to be exactly specified: every field settable from a flag, the whole
+// query settable as one JSON object, a stable `--json` shape, no terminal
+// required, and exit 0 when nothing matched — an empty answer is an answer, and
+// a caller that has to tell "no results" from "the index is missing" by parsing
+// stderr will get it wrong.
+// ---------------------------------------------------------------------------
+const USAGE = 'zen rag schema <index|search|show|stats> [spec...]';
+const INDEX_USAGE = 'zen rag schema index --embedding <ref> [--out <dir>] <spec...>';
+const SEARCH_USAGE = 'zen rag schema search [--dir <dir>] [query...]';
+const DEFAULT_DIR = './schema-db';
+export const command = {
+    summary: 'Search an openapi/swagger document as a graph.',
+    usage: USAGE,
+    details: [
+        'Commands',
+        ...table([
+            ['  index <spec...>', dim('Read the documents and write a searchable index.')],
+            ['  search', dim('Ask it something. --interactive for a prompt.')],
+            ['  show <id...>', dim('Print named nodes, with no search in between.')],
+            ['  stats', dim('What is in an index, and what built it.')],
+        ]),
+        '',
+        'Index',
+        ...table([
+            [
+                '  --embedding <ref>',
+                dim('Which embedder makes the vectors. Omit it to be shown the choices.'),
+            ],
+            ['  -o, --out <dir>', dim(`Where the index goes. Default ${DEFAULT_DIR}.`)],
+            [
+                '  --batch <n>',
+                dim('Texts per embedding request, and how often progress prints. Default 96.'),
+            ],
+        ]),
+        '',
+        'Search terms (repeatable)',
+        ...table([
+            ['  <text>', dim('A bare phrase, the same as --all.')],
+            ['  --all <q>', dim('Against everything, unfiltered.')],
+            ['  --method <q>', dim('Operations.')],
+            ['  --type <q>', dim('Schemas, on the side --direction names.')],
+            ['  --input-type <q>', dim('Schemas a call accepts.')],
+            ['  --output-type <q>', dim('Schemas a call returns.')],
+            ['  --property <q>', dim('Fields and parameters, per --direction.')],
+            ['  --input-property <q>', dim('Fields and parameters a call accepts.')],
+            ['  --output-property <q>', dim('Fields a call returns.')],
+            ['  --query <json|->', dim('A whole query object; - reads stdin.')],
+        ]),
+        '',
+        'Search filters and shape',
+        ...table([
+            ['  -d, --dir <dir>', dim(`Which index. Default ${DEFAULT_DIR}.`)],
+            ['  --embedding <ref>', dim('Must be the one the index was built with.')],
+            ['  --direction <d>', dim('input | output | any. Default any.')],
+            ['  --method-type <t>', dim('read_only | read_write | any. Default any.')],
+            ['  --exclude-id <id>', dim('Drop a node. Repeatable, as are the three below.')],
+            ['  --exclude-method <name>', dim('Drop an operation by name.')],
+            ['  --exclude-type <name>', dim('Drop a schema by name.')],
+            ['  --exclude-property <name>', dim('Drop a field by name.')],
+            ['  --limit <n>', dim('Seeds kept per term. Default 5.')],
+            ['  --max-hops <n>', dim('How far apart two hits may be. Default 3.')],
+            ['  --max-nodes <n>', dim('Nodes per result. Default 200.')],
+            ['  --format <f>', dim('text | mermaid | mermaid-flowchart | ts | openapi.')],
+            ['  --no-docs', dim('Leave the descriptions out.')],
+            ['  --interactive', dim('Prompt, search, refine. Needs a terminal.')],
+            ['  --quiet', dim('No narration.')],
+        ]),
+        '',
+        dim(`Credentials come from the ${cyan('zen')} keyring — try ${cyan('zen key ls')}.`),
+    ],
+    async run(ctx) {
+        const [group, ...rest] = ctx.args;
+        // `schema` is the only subject so far; leaving it out is a courtesy,
+        // not a second spelling to support forever.
+        const [name, ...tail] = group === 'schema' ? rest : ctx.args;
+        switch (name) {
+            case 'index':
+                return await index(tail, ctx);
+            case 'search':
+                return await search(tail, ctx);
+            case 'show':
+                return await show(tail, ctx);
+            case 'stats':
+                return await stats(tail, ctx);
+            default:
+                throw usageError(name ? `unknown command "${name}"` : 'no command given', USAGE);
+        }
+    },
+};
+async function index(args, ctx) {
+    const { values, positionals } = parse(args, {
+        out: { type: 'string', short: 'o' },
+        embedding: { type: 'string' },
+        batch: { type: 'string' },
+        quiet: { type: 'boolean' },
+    }, INDEX_USAGE);
+    if (positionals.length === 0) {
+        throw usageError('no document given', INDEX_USAGE);
+    }
+    const out = resolve(ctx.cwd, values.out ?? DEFAULT_DIR);
+    const loud = !values.quiet && !ctx.json;
+    const chosen = await embedder(values.embedding);
+    const started = Date.now();
+    const { manifest } = await buildIndex({
+        files: positionals.map((file) => resolve(ctx.cwd, file)),
+        out,
+        embedder: chosen,
+        embeddingRef: values.embedding,
+        indexer: 'zenera-rag',
+        batch: values.batch ? count(values.batch, '--batch') : undefined,
+        onRead: loud
+            ? (summary) => {
+                printSources(summary.sources, ctx.cwd);
+                // The first batch can take a while and says nothing while it
+                // does; this is the line that makes that a wait, not a hang.
+                note(dim(`  embedding ${summary.counts.entities} entities with ${chosen.id} …`));
+            }
+            : undefined,
+        onProgress: loud
+            ? (done, total) => note(dim(`  embedded ${done}/${total} · ${Math.round((done / total) * 100)}% · ${elapsed(started)}`))
+            : undefined,
+    });
+    if (ctx.json) {
+        json({ out, manifest });
+        return;
+    }
+    // stdout is the path and nothing else, so `DIR=$(zen rag schema index …)`
+    // works; what it means goes to stderr, where the narration lives.
+    note();
+    write(out);
+    note(`  wrote ${bold(String(manifest.counts.entities))} entities to ${bold(out)}, ` +
+        `embedded with ${manifest.embedding.ref} (${manifest.embedding.dimensions}d)`);
+    const where = out === resolve(ctx.cwd, DEFAULT_DIR) ? '' : ` --dir ${relative(ctx.cwd, out) || out}`;
+    note(dim(`  search it: ${cyan(`zen rag schema search${where} --all "what you are after"`)}`));
+}
+const HEADERS = ['PATHS', 'OPERATIONS', 'SCHEMAS', 'FIELDS'];
+function elapsed(since) {
+    const seconds = Math.round((Date.now() - since) / 1000);
+    return seconds < 60 ? `${seconds}s` : `${Math.floor(seconds / 60)}m${seconds % 60}s`;
+}
+function printSources(sources, cwd) {
+    const rows = sources.map((s) => ({
+        name: relative(cwd, s.path) || s.path,
+        dialect: s.dialect,
+        cells: [s.paths, s.methods, s.types, s.properties],
+    }));
+    if (rows.length > 1) {
+        rows.push({
+            name: 'total',
+            dialect: '',
+            cells: HEADERS.map((_, i) => rows.reduce((n, r) => n + (r.cells[i] ?? 0), 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)));
+    note();
+    notes(table([
+        [bold('SPEC'), bold('DIALECT'), ...HEADERS.map((h, i) => bold(h.padStart(widths[i])))],
+        ...rows.map((r) => [
+            r.name === 'total' ? dim(r.name) : r.name,
+            dim(r.dialect),
+            ...r.cells.map((c, i) => String(c).padStart(widths[i])),
+        ]),
+    ]).map((line) => `  ${line}`));
+    note();
+}
+const MANY = { type: 'string', multiple: true };
+const SEARCH_OPTIONS = {
+    dir: { type: 'string', short: 'd' },
+    embedding: { type: 'string' },
+    all: MANY,
+    method: MANY,
+    type: MANY,
+    'input-type': MANY,
+    'output-type': MANY,
+    property: MANY,
+    'input-property': MANY,
+    'output-property': MANY,
+    query: { type: 'string' },
+    direction: { type: 'string' },
+    'method-type': { type: 'string' },
+    'exclude-id': MANY,
+    'exclude-method': MANY,
+    'exclude-type': MANY,
+    'exclude-property': MANY,
+    limit: { type: 'string' },
+    'max-hops': { type: 'string' },
+    'max-nodes': { type: 'string' },
+    format: { type: 'string' },
+    'no-docs': { type: 'boolean' },
+    'only-hits': { type: 'boolean' },
+    interactive: { type: 'boolean' },
+    quiet: { type: 'boolean' },
+};
+async function search(args, ctx) {
+    const { values, positionals } = parse(args, SEARCH_OPTIONS, SEARCH_USAGE);
+    const dir = resolve(ctx.cwd, values.dir ?? DEFAULT_DIR);
+    const format = formatOf(values.format);
+    const options = { docs: !values['no-docs'], onlyHits: values['only-hits'] };
+    const query = { ...(await fromStdin(values.query)), ...fromFlags(values, positionals) };
+    // Everything that can be wrong about the invocation is settled before a
+    // credential is asked for, so a typo is a usage error and not a login.
+    if (values.interactive && !isInteractive()) {
+        throw usageError('--interactive needs a terminal', SEARCH_USAGE);
+    }
+    if (!values.interactive && isEmpty(query)) {
+        throw usageError('no query given', SEARCH_USAGE);
+    }
+    const manifest = await readManifest(dir);
+    const ref = values.embedding ?? manifest.embedding.ref;
+    assertSameEmbedding(manifest, ref);
+    const index = await SchemaIndex.open(dir, await embedder(ref));
+    try {
+        if (values.interactive) {
+            await repl(index, query, { format, ...options });
+            return;
+        }
+        const result = await index.search(query);
+        if (ctx.json) {
+            json({
+                seeds: result.seeds,
+                empty: result.empty,
+                subgraphs: result.subgraphs,
+                rendered: await present(index, result.subgraphs, format, options),
+            });
+            return;
+        }
+        const text = await present(index, result.subgraphs, format, options);
+        if (text) {
+            write(text);
+        }
+        if (!values.quiet) {
+            note(dim(`  ${result.seeds.length} seed(s) · ${result.subgraphs.length} result(s)${result.empty.length > 0 ? ` · nothing for: ${result.empty.join(', ')}` : ''}`));
+        }
+    }
+    finally {
+        index.close();
+    }
+}
+/** Flags win over `--query`: the more specific spelling is the later thought. */
+function fromFlags(values, positionals = []) {
+    const query = {};
+    const put = (key, value) => {
+        if (value !== undefined && (!Array.isArray(value) || value.length > 0)) {
+            query[key] = value;
+        }
+    };
+    // A bare phrase is the unfiltered search; there is nothing else it could mean.
+    put('all', [...(values.all ?? []), ...positionals]);
+    put('methods', values.method);
+    put('types', values.type);
+    put('input_types', values['input-type']);
+    put('output_types', values['output-type']);
+    put('properties', values.property);
+    put('input_properties', values['input-property']);
+    put('output_properties', values['output-property']);
+    put('exclude_ids', values['exclude-id']);
+    put('exclude_methods', values['exclude-method']);
+    put('exclude_types', values['exclude-type']);
+    put('exclude_properties', values['exclude-property']);
+    put('direction', values.direction);
+    put('method_type', values['method-type']);
+    put('limit', values.limit && count(values.limit, '--limit'));
+    put('max_hops', values['max-hops'] && count(values['max-hops'], '--max-hops'));
+    put('max_nodes', values['max-nodes'] && count(values['max-nodes'], '--max-nodes'));
+    return check(query);
+}
+async function fromStdin(source) {
+    if (source === undefined) {
+        return {};
+    }
+    const text = source === '-' ? await readStdin() : source;
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch (err) {
+        throw usageError(`--query is not JSON: ${err.message}`, SEARCH_USAGE);
+    }
+    return check(parsed);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function check(value) {
+    try {
+        return parseQuery(value);
+    }
+    catch (err) {
+        if (err instanceof QueryError) {
+            throw usageError(err.message, SEARCH_USAGE);
+        }
+        throw err;
+    }
+}
+// ---------------------------------------------------------------------------
+// show, stats
+// ---------------------------------------------------------------------------
+/**
+ * No embedder and no store: naming a node is a graph lookup, and asking for a
+ * credential to print something already on disk would be theatre.
+ */
+async function show(args, ctx) {
+    const usage = 'zen rag schema show <id...>';
+    const { values, positionals } = parse(args, SEARCH_OPTIONS, usage);
+    if (positionals.length === 0) {
+        throw usageError('no node named', usage);
+    }
+    const format = formatOf(values.format);
+    const index = await openIndex(resolve(ctx.cwd, values.dir ?? DEFAULT_DIR));
+    const missing = positionals.filter((id) => !index.graph.hasNode(id));
+    if (missing.length > 0) {
+        throw new CliError(`no such node: ${missing.join(', ')}`, EXIT.failed, 'ids look like `Type:User` or `Property:User.email`');
+    }
+    const subgraphs = stitch(index.graph, positionals.map((id) => ({ id, term: id, field: 'show', score: 1 })), { maxNodes: values['max-nodes'] ? count(values['max-nodes'], '--max-nodes') : undefined });
+    const text = await present(index, subgraphs, format, { docs: !values['no-docs'] });
+    if (ctx.json) {
+        json({ subgraphs, rendered: text });
+    }
+    else if (text) {
+        write(text);
+    }
+}
+async function stats(args, ctx) {
+    const { values } = parse(args, { dir: { type: 'string', short: 'd' } }, 'zen rag schema stats [--dir <dir>]');
+    const dir = resolve(ctx.cwd, values.dir ?? DEFAULT_DIR);
+    const manifest = await readManifest(dir);
+    if (ctx.json) {
+        json(manifest);
+        return;
+    }
+    note(bold(dir));
+    notes(table([
+        ['  built', manifest.createdAt],
+        ['  by', manifest.indexer],
+        ['  embedder', `${manifest.embedding.ref} (${manifest.embedding.dimensions}d)`],
+        [
+            '  indexes',
+            `fts ${yes(manifest.indexes.fts)} · vector ${yes(manifest.indexes.vector)}`,
+        ],
+    ]));
+    printSources(manifest.sources, ctx.cwd);
+    notes(table([['  entities', String(manifest.counts.entities)]]).map(dim));
+}
+function notes(lines) {
+    for (const line of lines) {
+        note(line);
+    }
+}
+const yes = (value) => (value ? 'yes' : 'no');
+// ---------------------------------------------------------------------------
+/** The keyring is materialised here, and only here: `show` and `stats` read no vectors. */
+async function embedder(ref) {
+    ensureHome();
+    const keys = await KeyStore.open();
+    // Asked before materialising, because materialising is what erases the
+    // difference between "the environment had it" and "the keyring supplied it".
+    const fromEnv = new Set(PROVIDERS.filter((p) => process.env[SHAPES[p].env]));
+    keys.materialize();
+    if (!ref) {
+        throw choices(keys, fromEnv);
+    }
+    return createEmbedder(ref);
+}
+/**
+ * Well-known embedding models per provider. A list rather than a lookup: any
+ * ref the registry can parse works, and these are the ones worth typing.
+ * Anthropic is absent because it publishes no embeddings API at all.
+ */
+const EMBEDDINGS = {
+    openai: ['text-embedding-3-small', 'text-embedding-3-large'],
+    google: ['gemini-embedding-001'],
+    vertex: ['gemini-embedding-001', 'text-embedding-005'],
+    openrouter: ['openai/text-embedding-3-small'],
+};
+/** What could be passed, with the ones this machine can actually use first. */
+function choices(keys, fromEnv) {
+    const rows = [];
+    const rest = [];
+    for (const provider of PROVIDERS) {
+        for (const model of EMBEDDINGS[provider] ?? []) {
+            const source = fromEnv.has(provider)
+                ? 'environment'
+                : keys.active(provider)
+                    ? 'keyring'
+                    : '';
+            const row = [`  ${cyan(`${provider}:${model}`)}`, dim(source || SHAPES[provider].env)];
+            (source ? rows : rest).push(row);
+        }
+    }
+    note(bold('Embeddings'));
+    notes(table([...rows, ...rest]));
+    note('');
+    if (rows.length === 0) {
+        note(dim('  no provider on this machine has a credential — try: zen key add openai'));
+        note('');
+    }
+    return usageError('no embedder named', 'pass --embedding <ref>, one of the above');
+}
+function formatOf(value) {
+    if (value === undefined) {
+        return 'text';
+    }
+    if (!isFormat(value)) {
+        throw usageError(`unknown format "${value}"`, 'expected text, mermaid, mermaid-flowchart, ts or openapi');
+    }
+    return value;
+}
+function count(value, flag) {
+    const number = Number(value);
+    if (!Number.isInteger(number) || number < 1) {
+        throw usageError(`${flag} must be a whole number of at least 1`, USAGE);
+    }
+    return number;
+}
+//# sourceMappingURL=command.js.map

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+export * from './present.ts';
+export * from './query.ts';
+export * from './schema/build.ts';
+export * from './schema/entities.ts';
+export * from './schema/files.ts';
+export * from './schema/graph.ts';
+export * from './schema/hydrate.ts';
+export * from './schema/render.ts';
+export * from './schema/schema.ts';
+export * from './schema/search.ts';
+export * from './schema/spec.ts';
+export * from './schema/store.ts';
+export * from './schema/subgraph.ts';
+export * from './schema/tools.ts';
+export * from './schema/typescript.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -0,0 +1,16 @@
+export * from "./present.js";
+export * from "./query.js";
+export * from "./schema/build.js";
+export * from "./schema/entities.js";
+export * from "./schema/files.js";
+export * from "./schema/graph.js";
+export * from "./schema/hydrate.js";
+export * from "./schema/render.js";
+export * from "./schema/schema.js";
+export * from "./schema/search.js";
+export * from "./schema/spec.js";
+export * from "./schema/store.js";
+export * from "./schema/subgraph.js";
+export * from "./schema/tools.js";
+export * from "./schema/typescript.js";
+//# sourceMappingURL=index.js.map

package/dist/present.d.ts

@@ -0,0 +1,17 @@
+import { type HydrateOptions } from './schema/hydrate.ts';
+import { type RenderOptions } from './schema/render.ts';
+import type { Schema } from './schema/schema.ts';
+import type { Operation } from './schema/spec.ts';
+import type { Subgraph } from './schema/subgraph.ts';
+export declare const FORMATS: readonly ["text", "mermaid", "mermaid-flowchart", "ts", "openapi"];
+export type Format = (typeof FORMATS)[number];
+export declare function isFormat(value: string): value is Format;
+export interface OutputOptions extends RenderOptions, HydrateOptions {
+}
+/** Two of the four formats need what is on disk; an open index is enough. */
+export interface SchemaSource {
+    schemas(): Promise<Record<string, Schema>>;
+    operations(): Promise<Operation[]>;
+}
+export declare function present(index: SchemaSource, subgraphs: readonly Subgraph[], format: Format, options?: OutputOptions): Promise<string>;
+//# sourceMappingURL=present.d.ts.map