@mistriwork/engine 0.0.0-stage → 1.0.0-rc.10

package/dist/server/migrate/snapshot.js

@@ -0,0 +1,239 @@
+/**
+ * The schema as a flat list of what is in it — each table, column,
+ * constraint, index, view, trigger and enum, keyed by name, with its
+ * definition as the engine prints it — so two readings compare as maps.
+ *
+ * That is what drift is: the live schema against the one migrations left.
+ * The one they left is recorded in the database after every run (a row per
+ * history table in `__mistri_schema_snapshot`), because a migration's
+ * effect cannot be known from its text and a file beside the migrations
+ * would be one environment's truth checked into every environment's
+ * repository. `baseline` writes the first reading beside the migrations as
+ * well, read-only, as the record of what the database was when tablewalk
+ * started owning its changes.
+ *
+ * Scoped to the schemas the run is given (the App's sources, the
+ * connection's "schemas", --schema), never tablewalk's own reserved tables
+ * or sign-in schema, which tablewalk upgrades whatever a baseline says, and
+ * never the history table itself.
+ */
+import { isRuntimeTable } from '../../shared/runtimeTables.js';
+import { RESERVED_SCHEMAS } from '../../adapters/reservedSql.js';
+import { qualified } from './history.js';
+const SNAPSHOT_TABLE = '__mistri_schema_snapshot';
+/* A plain name stays plain; one with a dot, a space, a capital or a quote is
+   quoted, so a key never reads as a different path. */
+const q = (name) => (/^[a-z_][a-z0-9_$]*$/.test(name) ? name : `"${name.replace(/"/g, '""')}"`);
+const squash = (sql) => (sql ?? '').replace(/\s+/g, ' ').trim();
+export async function readSchema(db, scope, history) {
+    const skip = (table) => isRuntimeTable(table) || table === history;
+    if (db.dialect === 'sqlite')
+        return readSqlite(db, skip);
+    const schemas = [...new Set(scope.length ? scope : [db.home])].filter((schema) => !RESERVED_SCHEMAS.includes(schema.toLowerCase()));
+    return readPostgres(db, schemas, skip);
+}
+async function readSqlite(db, skip) {
+    const out = {};
+    const master = await db.all("SELECT type, name, tbl_name, sql FROM sqlite_master WHERE name NOT LIKE 'sqlite_%' ORDER BY name");
+    for (const object of master) {
+        if (skip(object.tbl_name))
+            continue;
+        if (object.type === 'view')
+            out[`view ${q(object.name)}`] = squash(object.sql);
+        if (object.type === 'trigger')
+            out[`trigger ${q(object.tbl_name)}.${q(object.name)}`] = squash(object.sql);
+        if (object.type === 'index' && object.sql)
+            out[`index ${q(object.tbl_name)}.${q(object.name)}`] = squash(object.sql);
+        if (object.type !== 'table')
+            continue;
+        const table = q(object.name);
+        out[`table ${table}`] = /\bWITHOUT\s+ROWID\s*$/i.test(squash(object.sql)) ? 'table without rowid' : 'table';
+        for (const column of await db.all('SELECT name, type, "notnull", dflt_value, pk, hidden FROM pragma_table_xinfo(?)', [object.name])) {
+            out[`column ${table}.${q(column.name)}`] = [
+                column.type || 'any',
+                column.notnull ? 'not null' : '',
+                column.dflt_value !== null ? `default ${column.dflt_value}` : '',
+                column.pk ? 'primary key' : '',
+                column.hidden >= 2 ? 'generated' : '',
+            ]
+                .filter(Boolean)
+                .join(' ');
+        }
+        const keys = new Map();
+        for (const fk of await db.all('SELECT id, "table", "from", "to", on_update, on_delete FROM pragma_foreign_key_list(?) ORDER BY id, seq', [object.name])) {
+            const key = keys.get(fk.id) ?? {
+                parent: fk.table,
+                from: [],
+                to: [],
+                rule: `on update ${fk.on_update.toLowerCase()} on delete ${fk.on_delete.toLowerCase()}`,
+            };
+            key.from.push(fk.from);
+            if (fk.to)
+                key.to.push(fk.to);
+            keys.set(fk.id, key);
+        }
+        for (const key of keys.values()) {
+            out[`foreign key ${table}(${key.from.map(q).join(', ')})`] =
+                `references ${q(key.parent)}${key.to.length ? `(${key.to.map(q).join(', ')})` : ''} ${key.rule}`;
+        }
+        for (const index of await db.all('SELECT name, origin FROM pragma_index_list(?)', [object.name])) {
+            if (index.origin !== 'u')
+                continue;
+            const columns = await db.all('SELECT name FROM pragma_index_info(?) ORDER BY seqno', [index.name]);
+            out[`unique ${table}(${columns.map((column) => q(column.name ?? '<expression>')).join(', ')})`] = 'unique';
+        }
+    }
+    return out;
+}
+async function readPostgres(db, schemas, skip) {
+    const out = {};
+    /* The definitions as pg_get_*def prints them, with every name qualified:
+       read with an empty search path, so a reading never depends on the path
+       the session happened to have. */
+    const [{ path }] = await db.all("SELECT current_setting('search_path') AS path");
+    await db.run("SELECT set_config('search_path', 'pg_catalog', false)");
+    try {
+        const where = 'n.nspname = ANY(?::text[])';
+        const name = (schema, relation) => `${q(schema)}.${q(relation)}`;
+        for (const row of await db.all(`SELECT n.nspname AS s, c.relname AS t, c.relkind AS k FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE ${where} AND c.relkind IN ('r', 'p', 'f')`, [schemas])) {
+            if (!skip(row.t))
+                out[`table ${name(row.s, row.t)}`] = row.k === 'p' ? 'partitioned table' : row.k === 'f' ? 'foreign table' : 'table';
+        }
+        for (const row of await db.all(`SELECT n.nspname AS s, c.relname AS t, a.attname AS c, format_type(a.atttypid, a.atttypmod) AS ty, a.attnotnull AS nn,
+              pg_get_expr(d.adbin, d.adrelid) AS df, a.attidentity AS id, a.attgenerated AS gen
+       FROM pg_attribute a JOIN pg_class c ON c.oid = a.attrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+       LEFT JOIN pg_attrdef d ON d.adrelid = a.attrelid AND d.adnum = a.attnum
+       WHERE ${where} AND c.relkind IN ('r', 'p', 'f') AND a.attnum > 0 AND NOT a.attisdropped`, [schemas])) {
+            if (skip(row.t))
+                continue;
+            out[`column ${name(row.s, row.t)}.${q(row.c)}`] = [
+                row.ty,
+                row.nn ? 'not null' : '',
+                row.gen === 's' ? `generated always as ${row.df}` : row.df !== null ? `default ${row.df}` : '',
+                row.id === 'a' ? 'generated always as identity' : row.id === 'd' ? 'generated by default as identity' : '',
+            ]
+                .filter(Boolean)
+                .join(' ');
+        }
+        for (const row of await db.all(`SELECT n.nspname AS s, c.relname AS t, co.conname AS name, pg_get_constraintdef(co.oid, true) AS def
+       FROM pg_constraint co JOIN pg_class c ON c.oid = co.conrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE ${where} AND co.contype IN ('p', 'u', 'f', 'c', 'x')`, [schemas])) {
+            if (!skip(row.t))
+                out[`constraint ${name(row.s, row.t)}.${q(row.name)}`] = row.def;
+        }
+        // An index a constraint owns is said by the constraint.
+        for (const row of await db.all(`SELECT n.nspname AS s, t.relname AS t, i.relname AS name, pg_get_indexdef(i.oid) AS def
+       FROM pg_index x JOIN pg_class i ON i.oid = x.indexrelid JOIN pg_class t ON t.oid = x.indrelid JOIN pg_namespace n ON n.oid = i.relnamespace
+       WHERE ${where} AND NOT EXISTS (SELECT 1 FROM pg_constraint co WHERE co.conindid = x.indexrelid AND co.contype IN ('p', 'u', 'x'))`, [schemas])) {
+            if (!skip(row.t))
+                out[`index ${name(row.s, row.t)}.${q(row.name)}`] = row.def;
+        }
+        for (const row of await db.all(`SELECT n.nspname AS s, c.relname AS v, c.relkind AS k, pg_get_viewdef(c.oid, true) AS def
+       FROM pg_class c JOIN pg_namespace n ON n.oid = c.relnamespace WHERE ${where} AND c.relkind IN ('v', 'm')`, [schemas])) {
+            if (!skip(row.v))
+                out[`${row.k === 'm' ? 'materialized view' : 'view'} ${name(row.s, row.v)}`] = squash(row.def);
+        }
+        for (const row of await db.all(`SELECT n.nspname AS s, c.relname AS t, tg.tgname AS name, pg_get_triggerdef(tg.oid, true) AS def
+       FROM pg_trigger tg JOIN pg_class c ON c.oid = tg.tgrelid JOIN pg_namespace n ON n.oid = c.relnamespace
+       WHERE ${where} AND NOT tg.tgisinternal`, [schemas])) {
+            if (!skip(row.t))
+                out[`trigger ${name(row.s, row.t)}.${q(row.name)}`] = row.def;
+        }
+        for (const row of await db.all(`SELECT n.nspname AS s, t.typname AS t, string_agg(quote_literal(e.enumlabel), ', ' ORDER BY e.enumsortorder) AS labels
+       FROM pg_type t JOIN pg_enum e ON e.enumtypid = t.oid JOIN pg_namespace n ON n.oid = t.typnamespace
+       WHERE ${where} GROUP BY n.nspname, t.typname`, [schemas])) {
+            out[`enum ${name(row.s, row.t)}`] = `(${row.labels})`;
+        }
+    }
+    finally {
+        await db.run("SELECT set_config('search_path', ?, false)", [path]);
+    }
+    return out;
+}
+/** What differs between the schema migrations left and the one there now. A new or dropped table is one line, not one per column. */
+export function drift(expected, live) {
+    const changes = [];
+    for (const key of [...new Set([...Object.keys(expected), ...Object.keys(live)])].sort()) {
+        if (expected[key] !== live[key])
+            changes.push({
+                key,
+                ...(expected[key] !== undefined ? { was: expected[key] } : {}),
+                ...(live[key] !== undefined ? { now: live[key] } : {}),
+            });
+    }
+    const whole = new Set(changes
+        .filter((change) => change.key.startsWith('table ') && (change.was === undefined || change.now === undefined))
+        .map((change) => change.key.slice(6)));
+    return changes.filter((change) => {
+        const owner = /^(?:column|constraint|index|trigger) (.+)\.[^.]+$/.exec(change.key)?.[1] ??
+            /^(?:foreign key|unique) ([^(]+)\(/.exec(change.key)?.[1];
+        return !(owner !== undefined && whole.has(owner) && !change.key.startsWith('table '));
+    });
+}
+export function sayChange(change) {
+    if (change.was === undefined)
+        return `+ ${change.key}  ${change.now}  (added outside migrations)`;
+    if (change.now === undefined)
+        return `- ${change.key}  (dropped outside migrations)`;
+    return `~ ${change.key}  ${change.was} → ${change.now}  (changed outside migrations)`;
+}
+/**
+ * The schema to record after a run: what the database is now, except where
+ * it had drifted before the run and the run left that alone — that stays
+ * drift, so a run never quietly blesses a column someone added by hand. A
+ * migration that changed the drifted object (putting it back, or altering
+ * it) settles it, and so does one that names it: adopting a hand-made column
+ * is `ADD COLUMN IF NOT EXISTS note`, which changes nothing here and makes
+ * the column everywhere else. `applied` is the text of the files the run
+ * applied.
+ */
+export function carryForward(expected, before, after, applied = []) {
+    const next = { ...after };
+    const texts = applied.map((text) => text.toLowerCase());
+    for (const key of new Set([...Object.keys(expected), ...Object.keys(before)])) {
+        if (expected[key] === before[key] || after[key] !== before[key])
+            continue;
+        if (named(key, texts))
+            continue;
+        if (expected[key] === undefined)
+            delete next[key];
+        else
+            next[key] = expected[key];
+    }
+    return next;
+}
+/* Whether a migration's text names the object a key is about: its own name,
+   and for a column or a key its table's too. Words, not SQL: a name inside a
+   comment counts, which errs toward settling what a person wrote about. */
+function named(key, texts) {
+    const kind = /^(foreign key|unique|materialized view|[a-z]+) /.exec(key)?.[1] ?? '';
+    const idents = [...key.slice(kind.length + 1).matchAll(/"((?:[^"]|"")*)"|([^."(),\s]+)/g)].map((match) => (match[1] ?? match[2]).replace(/""/g, '"').toLowerCase());
+    const wanted = kind === 'column' ? idents.slice(-2) : kind === 'foreign key' || kind === 'unique' ? idents : idents.slice(-1);
+    const word = (name) => new RegExp(`(^|[^a-z0-9_$])${name.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}($|[^a-z0-9_$])`);
+    return texts.some((text) => wanted.every((name) => word(name).test(text)));
+}
+export async function readSnapshot(db, history) {
+    const exists = db.dialect === 'sqlite'
+        ? await db.all("SELECT 1 FROM sqlite_master WHERE type = 'table' AND name = ?", [SNAPSHOT_TABLE])
+        : db.dialect === 'postgres'
+            ? await db.all('SELECT 1 FROM pg_catalog.pg_tables WHERE schemaname = ? AND tablename = ?', [db.home, SNAPSHOT_TABLE])
+            : [];
+    if (!exists.length)
+        return undefined;
+    const [row] = await db.all(`SELECT installed_rank, taken_on, objects FROM ${qualified(db, SNAPSHOT_TABLE)} WHERE history_table = ?`, [history]);
+    return row ? { rank: Number(row.installed_rank), takenOn: row.taken_on, objects: JSON.parse(row.objects) } : undefined;
+}
+export async function writeSnapshot(db, history, rank, objects) {
+    const table = qualified(db, SNAPSHOT_TABLE);
+    await db.run(`CREATE TABLE IF NOT EXISTS ${table} (history_table TEXT NOT NULL PRIMARY KEY, installed_rank INT NOT NULL, taken_on VARCHAR(32) NOT NULL, objects TEXT NOT NULL)`);
+    // One statement, so two runs finishing together cannot both find the row gone and both insert it.
+    const upsert = 'ON CONFLICT (history_table) DO UPDATE SET installed_rank = excluded.installed_rank, taken_on = excluded.taken_on, objects = excluded.objects';
+    await db.run(`INSERT INTO ${table} (history_table, installed_rank, taken_on, objects) VALUES (?, ?, ?, ?) ${upsert}`, [
+        history,
+        rank,
+        new Date().toISOString().replace('T', ' ').slice(0, 19),
+        JSON.stringify(sorted(objects)),
+    ]);
+}
+export const sorted = (objects) => Object.fromEntries(Object.entries(objects).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));

package/dist/server/migrate/target.d.ts

@@ -0,0 +1,33 @@
+import type { ConnectionConfig, Registry } from '../connections.js';
+import type { StartupConfig } from '../cli/config.js';
+import type { MigrateTarget } from './runner.js';
+interface TargetFlags {
+    readonly connection?: string;
+    /** The id of the connection the command line named (`<db>`, --db, DATABASE_URL): it wins over a config's. */
+    readonly argument?: string;
+    readonly migrations?: string;
+    readonly table?: string;
+    /** --schema, as parsed: wins over what the App and the connection say. */
+    readonly schemas: readonly string[];
+}
+/**
+ * What an App says about the database a run is about, without the engine reading the App: the connection it binds
+ * (its own, or its home source's) and the schemas its sources keep, home source first. The App framework derives it
+ * from a loaded App (cli/appTargets.ts); a run with no App has none.
+ */
+export interface TargetBinding {
+    readonly connection?: string;
+    readonly schemas?: ReadonlyArray<Readonly<{
+        connection: string;
+        schema: string;
+    }>>;
+}
+interface ResolvedTarget extends MigrateTarget {
+    readonly connection: ConnectionConfig;
+}
+/** The connection the run is about: named, the App's home source's, or the only one. `tablewalk seed` reads it the same way. */
+export declare function targetConnection(registry: Registry, flags: Pick<TargetFlags, 'connection' | 'argument'>, binding?: TargetBinding, purpose?: string): ConnectionConfig;
+/** The directory alone, for `migrate new`, which writes a file and opens no database. */
+export declare function targetDir(registry: Registry, config: StartupConfig, flags: TargetFlags, appDir?: string, binding?: TargetBinding): string;
+export declare function resolveTarget(registry: Registry, config: StartupConfig, flags: TargetFlags, appDir?: string, binding?: TargetBinding): Promise<ResolvedTarget>;
+export {};

package/dist/server/migrate/target.js

@@ -0,0 +1,82 @@
+/**
+ * Which database a migration run is about, and which of its schemas, which
+ * directory and which history table: read the way a start reads a
+ * connection, so `tablewalk migrate` and `mistri check --pending` agree
+ * with the server about what "the App's database" is.
+ *
+ * The directory defaults to `migrations/` inside the App's directory. It is
+ * the one place the App's other derived facts already live (its generated
+ * `mistri-schema.d.ts`, its `authority.lock`), it travels with the App in
+ * version control, and a change to it is reviewed beside the App code that
+ * needs it. A connection that says otherwise (`"migrations": { "dir": … }`
+ * in tablewalk.json, relative to that file) wins, which is how several Apps
+ * over one database share its migrations, and `--migrations` wins over both.
+ */
+import { dirname, resolve } from 'node:path';
+import { resolveConnection } from '../auth/credentials.js';
+import { DEFAULT_HISTORY_TABLE } from './history.js';
+import { configFileName } from '../product.js';
+/** The connection the run is about: named, the App's home source's, or the only one. `tablewalk seed` reads it the same way. */
+export function targetConnection(registry, flags, binding, purpose = 'migrate') {
+    const find = (name) => registry.configs().find((config) => config.id === name || config.name === name);
+    const bound = flags.connection ?? binding?.connection;
+    if (bound !== undefined) {
+        const found = find(bound);
+        if (!found)
+            throw new Error(`there is no connection "${bound}". Known: ${registry
+                .configs()
+                .map((config) => config.name)
+                .join(', ') || 'none'}.`);
+        return found;
+    }
+    if (flags.argument)
+        return registry.configOf(flags.argument);
+    const configs = registry.configs();
+    if (configs.length === 1)
+        return configs[0];
+    if (configs.length > 1)
+        throw new Error(`several connections are configured (${configs.map((config) => config.name).join(', ')}): name one with --connection.`);
+    throw new Error(`no database to ${purpose}. Name it — a SQLite file, --db <url>, or --config <file> — or keep a ${configFileName()} beside where you run it.`);
+}
+function directoryOf(connection, config, flags, appDir) {
+    const base = config.configPath ? dirname(config.configPath) : process.cwd();
+    return flags.migrations !== undefined
+        ? resolve(flags.migrations)
+        : connection?.migrations
+            ? resolve(base, connection.migrations.dir)
+            : appDir !== undefined
+                ? resolve(appDir, 'migrations')
+                : resolve('migrations');
+}
+/** The directory alone, for `migrate new`, which writes a file and opens no database. */
+export function targetDir(registry, config, flags, appDir, binding) {
+    let connection;
+    try {
+        connection = targetConnection(registry, flags, binding);
+    }
+    catch {
+        connection = undefined;
+    }
+    return directoryOf(connection, config, flags, appDir);
+}
+export async function resolveTarget(registry, config, flags, appDir, binding) {
+    const connection = targetConnection(registry, flags, binding);
+    if (connection.http)
+        throw new Error(`"${connection.name}" is an HTTP API, which has no schema of its own to migrate.`);
+    const { url } = await resolveConnection(connection.name, connection.url, { secrets: true });
+    /* The App's schemas on this connection, home source first: an App that
+       keeps a source per schema owns those and nothing else of a shared
+       database. */
+    const appSchemas = (binding?.schemas ?? [])
+        .filter((source) => {
+        const bound = registry.configs().find((config) => config.id === source.connection || config.name === source.connection);
+        return bound?.id === connection.id;
+    })
+        .map((source) => source.schema);
+    const schemas = [...new Set(flags.schemas.length ? flags.schemas : appSchemas.length ? appSchemas : (connection.schemas ?? []))];
+    const dir = directoryOf(connection, config, flags, appDir);
+    const table = flags.table ?? connection.migrations?.table ?? DEFAULT_HISTORY_TABLE;
+    if (!/^[A-Za-z_][A-Za-z0-9_$]{0,62}$/.test(table))
+        throw new Error(`"${table}" is not a table name the history can have: letters, digits and _, at most 63.`);
+    return { url, schemas, dir, table, connection };
+}

package/dist/server/openapiDraft.d.ts

@@ -0,0 +1,25 @@
+import type { HttpConnectionConfig } from './httpConnection.js';
+interface Writer {
+    write(text: string): unknown;
+}
+/** `--from-openapi`: drafts and prints; answers the exit code, 0 with at least one resource, 1 otherwise. */
+export declare function draftFromOpenapi(source: string, out?: Writer, err?: Writer): Promise<number>;
+interface OpenapiBootOptions {
+    /** The API's base URL, when the spec's `servers` does not give a usable one. */
+    apiUrl?: string;
+    /** The environment variable holding a bearer token; only its name is kept. */
+    tokenEnv?: string;
+}
+/**
+ * `--openapi`: a connection straight from a spec. The description is drafted
+ * in memory (and said on stderr, as `--from-openapi` says it), the base URL is
+ * `--api-url` or the spec's server, and the token is a `${VAR}` reference,
+ * expanded when the connection opens, as a config's is. Throws with a reason
+ * a person can act on.
+ */
+export declare function openapiConnection(source: string, options: OpenapiBootOptions, err?: Writer): Promise<{
+    name: string;
+    url: string;
+    http: HttpConnectionConfig;
+}>;
+export {};

package/dist/server/openapiDraft.js

@@ -0,0 +1,171 @@
+/**
+ * An API's OpenAPI spec, turned into what tablewalk reads.
+ *
+ * `--from-openapi` drafts the description and prints it: the description goes
+ * to stdout and nothing else does, so redirecting it is the whole workflow
+ * (`--from-openapi crm.json > crm.http.json`). `--openapi` drafts the same
+ * description in memory and serves the API as a connection straight away, with
+ * no config file and no description on disk. Either way, what was guessed and
+ * what was skipped goes to stderr, where a person reads it before trusting the
+ * result — a draft to confirm, as `--scaffold-app` is.
+ */
+import { createHash } from 'node:crypto';
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { isIP } from 'node:net';
+import { DEFAULT_POLICY, HttpSourceError, send } from '../adapters/http/egress.js';
+import { OpenApiError, readOpenApi } from '../adapters/http/openapi.js';
+import { draftDescription } from '../adapters/http/httpDescription.js';
+import { product } from './product.js';
+/* Specs run to megabytes (a large public API's is several), well past what one
+   API answer may be, so a spec fetch gets a cap of its own. */
+const SPEC_MAX_BYTES = 25 * 1024 * 1024;
+const isLoopback = (host) => {
+    const bare = host.replace(/^\[|\]$/g, '');
+    return bare === 'localhost' || (isIP(bare) === 4 && bare.startsWith('127.')) || bare === '::1';
+};
+/**
+ * Read a spec from a file or an http(s) URL. A URL is fetched through egress,
+ * under the rules every API request follows, with no credential: a spec that
+ * needs one is downloaded first and named as a file. Throws with a reason.
+ */
+async function loadSpec(source) {
+    if (!source)
+        throw new Error('needs a spec: a JSON file or an https URL (OpenAPI 3.0 or 3.1).');
+    if (/^https?:\/\//i.test(source)) {
+        let url;
+        try {
+            url = new URL(source);
+        }
+        catch {
+            throw new Error(`${source} is not a URL.`);
+        }
+        const policy = { ...DEFAULT_POLICY, maxBytes: SPEC_MAX_BYTES, insecure: url.protocol === 'http:' && isLoopback(url.hostname) };
+        let reply;
+        try {
+            reply = await send(url, { accept: 'application/json' }, policy);
+        }
+        catch (error) {
+            if (error instanceof HttpSourceError)
+                throw new Error(`${url.host}: ${error.message}`);
+            throw error;
+        }
+        if (reply.status < 200 || reply.status > 299)
+            throw new Error(`${source} answered ${reply.status}.`);
+        // The hash of the document as parsed: the bytes on the wire are egress's to keep.
+        const sha256 = createHash('sha256').update(JSON.stringify(reply.json)).digest('hex');
+        return { document: reply.json, name: source, sha256, url };
+    }
+    let bytes;
+    try {
+        bytes = await readFile(source);
+    }
+    catch {
+        throw new Error(`no spec file at ${source}`);
+    }
+    let document;
+    try {
+        document = JSON.parse(bytes.toString('utf8'));
+    }
+    catch (error) {
+        // YAML is the usual reason; tablewalk takes no YAML dependency for it.
+        throw new Error(`${source} is not JSON (${error.message}). Specs are read as JSON; convert a YAML one first.`);
+    }
+    // The hash of the exact bytes read, so a description can say which spec it came from.
+    return { document, name: basename(source), sha256: createHash('sha256').update(bytes).digest('hex') };
+}
+/* Read the spec's resources and say, on stderr, what was guessed and what was
+   skipped. Throws when nothing could be drafted, since a description with no
+   resources is not one a connection can read. */
+function draft(spec, source, err) {
+    let catalog;
+    try {
+        catalog = readOpenApi(spec.document);
+    }
+    catch (error) {
+        if (!(error instanceof OpenApiError))
+            throw error;
+        throw new Error(`${source}: ${error.message}`);
+    }
+    for (const resource of catalog.resources) {
+        for (const guess of resource.guesses)
+            err.write(`guessed  ${resource.name}: ${guess}\n`);
+    }
+    for (const skip of catalog.skipped)
+        err.write(`skipped  ${skip.operation}: ${skip.reason}\n`);
+    if (!catalog.resources.length)
+        throw new Error(`No resource could be drafted from ${source}: every operation was skipped, for the reasons above.`);
+    return { catalog, description: draftDescription(catalog, { file: spec.name, sha256: spec.sha256 }) };
+}
+const drafted = (catalog) => {
+    const count = catalog.resources.length;
+    return `${count} resource${count === 1 ? '' : 's'} drafted from ${catalog.title}${catalog.version ? ` ${catalog.version}` : ''}`;
+};
+/** `--from-openapi`: drafts and prints; answers the exit code, 0 with at least one resource, 1 otherwise. */
+export async function draftFromOpenapi(source, out = process.stdout, err = process.stderr) {
+    try {
+        const { catalog, description } = draft(await loadSpec(source), source, err);
+        out.write(`${JSON.stringify(description, null, 2)}\n`);
+        err.write(`${drafted(catalog)}. Confirm the guesses above before using it.\n`);
+        return 0;
+    }
+    catch (error) {
+        err.write(`${product()}: --from-openapi ${error.message}\n`);
+        return 1;
+    }
+}
+/* The base every description path resolves under: `--api-url`, else the
+   spec's first server, resolved against the spec's own URL when it came from
+   one. A server with `{variables}` is a template, not an address. */
+function baseOf(spec, options) {
+    const servers = spec.document.servers;
+    const written = options.apiUrl ?? (Array.isArray(servers) && typeof servers[0]?.url === 'string' ? servers[0].url : undefined);
+    if (!written)
+        throw new Error('The spec names no server. Pass --api-url <base URL> to say where the API is.');
+    if (!options.apiUrl && /\{[^}]*\}/.test(written)) {
+        throw new Error(`The spec's server "${written}" has variables. Pass --api-url with the address filled in.`);
+    }
+    let url;
+    try {
+        url = spec.url && !options.apiUrl ? new URL(written, spec.url) : new URL(written);
+    }
+    catch {
+        throw new Error(`The spec's server "${written}" is not an address on its own. Pass --api-url <base URL> to say where the API is.`);
+    }
+    if (url.protocol !== 'https:' && url.protocol !== 'http:')
+        throw new Error(`${url.protocol}// is not an API address; use https.`);
+    if (url.username || url.password)
+        throw new Error('A credential belongs in --api-token-env, not in the URL.');
+    if (url.protocol === 'http:' && !isLoopback(url.hostname)) {
+        throw new Error(`${url.host} would be reached over plain http. From the command line that is allowed only to this machine; use https, or a config with "insecure": true.`);
+    }
+    url.search = '';
+    url.hash = '';
+    return url;
+}
+/**
+ * `--openapi`: a connection straight from a spec. The description is drafted
+ * in memory (and said on stderr, as `--from-openapi` says it), the base URL is
+ * `--api-url` or the spec's server, and the token is a `${VAR}` reference,
+ * expanded when the connection opens, as a config's is. Throws with a reason
+ * a person can act on.
+ */
+export async function openapiConnection(source, options, err = process.stderr) {
+    const spec = await loadSpec(source);
+    const { catalog, description } = draft(spec, source, err);
+    const base = baseOf(spec, options);
+    let auth;
+    if (options.tokenEnv !== undefined) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(options.tokenEnv))
+            throw new Error(`--api-token-env takes a variable's name, not "${options.tokenEnv}".`);
+        if (process.env[options.tokenEnv] === undefined)
+            throw new Error(`${options.tokenEnv} is not set. Export it, or leave out --api-token-env.`);
+        auth = { bearer: `\${${options.tokenEnv}}` };
+    }
+    err.write(`${drafted(catalog)}, served from ${base.origin}${base.pathname}.\n`);
+    return {
+        name: catalog.title || basename(spec.name),
+        url: base.toString(),
+        http: { description, ...(auth ? { auth } : {}), ...(base.protocol === 'http:' ? { insecure: true } : {}) },
+    };
+}

package/dist/server/operations/diagnostics.d.ts

@@ -0,0 +1,101 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Writable } from 'node:stream';
+import type { ConnectionPoolStats } from '../connections.js';
+import { type RequestMetricsSnapshot } from './requestMetrics.js';
+/** One open database pool's meters (poolMetrics.ts), by its connection's
+ * position in the configuration: never a name, URL or database. */
+export interface CapacityPool {
+    readonly position: number;
+    readonly dialect: string;
+    readonly role: string;
+    /** Which of the connection's replicas, from 1, for a replica's readers. */
+    readonly replica?: number;
+    readonly pooler: string;
+    readonly size: number;
+    readonly open: number | null;
+    readonly inUse: number;
+    readonly waiting: number;
+    readonly saturated: boolean;
+    readonly checkouts: number;
+    readonly queued: number;
+    readonly timedOut: number;
+    readonly failed: number;
+    readonly waitBuckets: readonly number[];
+    readonly holdBuckets: readonly number[];
+}
+/** What separates "add pods" from "raise the pool" from "the database is
+ * slow": the event loop's cumulative busy and idle time, and every open pool. */
+export interface CapacitySnapshot {
+    readonly eventLoop: Readonly<{
+        activeMs: number;
+        idleMs: number;
+    }>;
+    readonly durationBoundsMs: readonly number[];
+    readonly pools: readonly CapacityPool[];
+}
+/** The registry's pools and this process's event loop, now. Cumulative
+ * since start: compare two snapshots for an interval, as with the HTTP metrics. */
+export declare function collectCapacity(source: {
+    poolStats(): readonly ConnectionPoolStats[];
+}): CapacitySnapshot;
+export interface RequestDiagnostic {
+    event: 'http.request';
+    timestamp: string;
+    requestId: string;
+    method: string;
+    route: string;
+    status: number | null;
+    durationMs: number;
+    outcome: 'completed' | 'aborted';
+    droppedTotal: number;
+}
+export interface RequestMetricsDiagnostic extends RequestMetricsSnapshot {
+    readonly event: 'http.metrics';
+    readonly version: 1;
+    /** The pools and event loop at the moment the summary was taken, once a host attaches them. */
+    readonly capacity?: CapacitySnapshot;
+    readonly health: Readonly<{
+        droppedTotal: number;
+        failed: boolean;
+        queuedRecords: number;
+        writingRecord: boolean;
+        writingSummary: boolean;
+        summaryPending: boolean;
+        summaryDroppedTotal: number;
+    }>;
+}
+/** Local, best-effort HTTP diagnostics, separate from the business journal.
+ * The caller owns the stream. No request waits for it, and only one bounded
+ * record is handed to it at a time. A failed stream disables further output. */
+export declare class RequestDiagnostics {
+    private readonly output;
+    private readonly queue;
+    private scheduled;
+    private writing;
+    private failed;
+    private dropped;
+    private readonly metrics;
+    private summaryPending;
+    private summaryRevision;
+    private summaryDropped;
+    private flushPromise;
+    private flushDone;
+    private capacity;
+    constructor(output: Writable);
+    get droppedTotal(): number;
+    /** Carry the host's capacity (its pools and event loop) in every summary
+     * from now on. Read when the summary is taken, never per request. */
+    watchCapacity(read: () => CapacitySnapshot): void;
+    snapshot(): RequestMetricsDiagnostic;
+    private get revision();
+    observe(req: IncomingMessage, res: ServerResponse): void;
+    /** A bounded shutdown opportunity, not a delivery guarantee. Does not end
+     * stderr (or a caller's stream), and never participates in a business write. */
+    flush(timeoutMs?: number): Promise<boolean>;
+    private enqueue;
+    private schedule;
+    private readonly fail;
+    private notifyIdle;
+}
+/** Only the exact explicit opt-in enables diagnostics. MCP never calls this. */
+export declare function diagnosticsFromEnvironment(value: string | undefined, output?: Writable): RequestDiagnostics | undefined;