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

package/dist/server/httpConnection.js

@@ -0,0 +1,170 @@
+/**
+ * An `http` connection in the config file: checked when the file is read,
+ * opened when the connection is first used.
+ *
+ *   { "name": "Desk", "kind": "http", "url": "https://desk.example/v1/",
+ *     "description": "desk.http.json", "auth": { "bearer": "${DESK_TOKEN}" },
+ *     "cache": { "ttl": 60 } }
+ *
+ * The description is the file `tablewalk --from-openapi` drafts, found
+ * relative to the config file so the two travel together — or the description
+ * itself, inline, which is what `--openapi` drafts in memory and what saving
+ * such a connection writes. The credential is written as a `${VAR}` reference
+ * and expanded only here, at open, into a header the adapter hands to egress;
+ * it is never stored expanded, never sent to the browser, and never attached
+ * to a URL a browser supplied. `cache` opts the connection's reads into the
+ * deployment's cache (the process's own, or the Valkey a `"kind": "cache"`
+ * connection names) for `ttl` seconds.
+ */
+import { readFile } from 'node:fs/promises';
+import { dirname, resolve } from 'node:path';
+import { DEFAULT_POLICY } from '../adapters/http/egress.js';
+import { HttpAdapter } from '../adapters/http/httpAdapter.js';
+import { readDescription } from '../adapters/http/httpDescription.js';
+import { expandEnvReferences } from './auth/credentials.js';
+import { product } from './product.js';
+const HTTP_ONLY = ['description', 'auth', 'insecure', 'allowLinkLocal', 'cache'];
+/* RFC 9110's token, minus the headers the request itself owns. */
+const HEADER_NAME = /^[A-Za-z0-9!#$%&'*+.^_`|~-]+$/;
+const OWNED_HEADERS = new Set(['host', 'content-length', 'content-type', 'accept', 'connection', 'transfer-encoding', 'cookie']);
+/* A day: an answer older than that is not a cached answer, it is a copy. */
+const MAX_CACHE_TTL_SECONDS = 86_400;
+/**
+ * An entry's HTTP fields, checked: the resolved block for an `http`
+ * connection, undefined for a database. Throws naming the field, because a
+ * config someone wrote is refused rather than half-read. Service kinds
+ * (`cache`, `webhook`, …) are read by serviceConnections.ts before this is asked.
+ */
+export function httpConnectionOf(entry, path) {
+    const where = `${path}: connection "${String(entry.name)}"`;
+    if (entry.kind === undefined) {
+        const stray = HTTP_ONLY.find((key) => entry[key] !== undefined);
+        if (stray)
+            throw new Error(`${where} has "${stray}", which only an HTTP connection takes. Add "kind": "http", or remove it.`);
+        return undefined;
+    }
+    /* Said by name rather than as an unknown kind: a config written for 0.9.5 or earlier had one, and the reader should learn where it went. */
+    if (entry.kind === 'search') {
+        throw new Error(`${where} has "kind": "search". Search providers are not part of ${product()}: they are packs (Typesense is @mistriwork/search-typesense, SQLite FTS5 is @mistriwork/search-sqlite, Postgres tsvector is @mistriwork/search-postgres), which ship after 1.0. Remove the entry, and a text filter runs on the database.`);
+    }
+    if (entry.kind !== 'http') {
+        throw new Error(`${where} has "kind": ${JSON.stringify(entry.kind)}. The kinds are "http", "cache" and "webhook"; a database needs none.`);
+    }
+    // Writes to an API arrive with their own slice; until then a flag saying otherwise would be a promise nothing keeps.
+    if (entry.writable === true)
+        throw new Error(`${where} is an HTTP connection, which is read-only; remove "writable".`);
+    if (entry.schemas !== undefined)
+        throw new Error(`${where} is an HTTP connection; "schemas" belongs to Postgres.`);
+    const written = entry.description;
+    let description;
+    if (typeof written === 'string' && written)
+        description = written;
+    else if (written && typeof written === 'object' && !Array.isArray(written))
+        description = readDescription(written, `${where}: "description"`);
+    else
+        throw new Error(`${where} needs a "description": the file ${product()} --from-openapi drafts from the API's spec, or the description itself.`);
+    for (const flag of ['insecure', 'allowLinkLocal']) {
+        if (entry[flag] !== undefined && typeof entry[flag] !== 'boolean') {
+            throw new Error(`${where} has "${flag}": ${JSON.stringify(entry[flag])}. It must be true or false, without quotes.`);
+        }
+    }
+    // A base URL that is still a reference is checked when it opens, once the environment has said what it is.
+    if (!String(entry.url).includes('${'))
+        baseUrl(String(entry.url), entry.insecure === true, where);
+    return {
+        description,
+        ...(typeof description === 'string' ? { descriptionPath: resolve(dirname(path), description) } : {}),
+        ...(entry.auth !== undefined ? { auth: authOf(entry.auth, where) } : {}),
+        ...(entry.insecure === true ? { insecure: true } : {}),
+        ...(entry.allowLinkLocal === true ? { allowLinkLocal: true } : {}),
+        ...(entry.cache !== undefined ? { cache: cacheOf(entry.cache, where) } : {}),
+    };
+}
+function cacheOf(value, where) {
+    const cache = value;
+    const keys = cache && typeof cache === 'object' && !Array.isArray(cache) ? Object.keys(cache).join(',') : '';
+    if (keys === 'ttl' && Number.isSafeInteger(cache.ttl) && cache.ttl >= 1 && cache.ttl <= MAX_CACHE_TTL_SECONDS) {
+        return { ttl: cache.ttl };
+    }
+    throw new Error(`${where} has a "cache" ${product()} cannot read. Write { "ttl": 60 }: whole seconds, from 1 to ${MAX_CACHE_TTL_SECONDS}.`);
+}
+function authOf(value, where) {
+    const auth = value;
+    const keys = auth && typeof auth === 'object' && !Array.isArray(auth) ? Object.keys(auth).sort().join(',') : '';
+    if (keys === 'bearer' && typeof auth.bearer === 'string' && auth.bearer)
+        return { bearer: auth.bearer };
+    if (keys === 'header,value' && typeof auth.header === 'string' && typeof auth.value === 'string' && auth.value) {
+        if (!HEADER_NAME.test(auth.header) || OWNED_HEADERS.has(auth.header.toLowerCase())) {
+            throw new Error(`${where} has "auth.header": ${JSON.stringify(auth.header)}, which is not a header a credential can travel in.`);
+        }
+        return { header: auth.header, value: auth.value };
+    }
+    throw new Error(`${where} has an "auth" ${product()} cannot read. Write { "bearer": "\${TOKEN}" } or { "header": "x-api-key", "value": "\${KEY}" }.`);
+}
+/* The base every description path resolves under: https unless the operator
+   said otherwise, no credential in it, and ending in "/" so a relative path
+   extends it rather than replacing its last segment. */
+function baseUrl(text, insecure, where) {
+    let url;
+    try {
+        url = new URL(text);
+    }
+    catch {
+        throw new Error(`${where} has a "url" that is not a URL.`);
+    }
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && insecure)) {
+        throw new Error(`${where} has a ${url.protocol}// "url". Use https, or set "insecure": true for an API on a trusted network.`);
+    }
+    if (url.username || url.password)
+        throw new Error(`${where} has a credential in its "url"; it belongs in "auth".`);
+    if (url.search || url.hash)
+        throw new Error(`${where} has a query or fragment in its "url"; the base is a path only.`);
+    if (!url.pathname.endsWith('/'))
+        url.pathname += '/';
+    return url;
+}
+/* A description file, read and checked. */
+async function describedIn(file) {
+    let text;
+    try {
+        text = await readFile(file, 'utf8');
+    }
+    catch {
+        throw new Error(`the description file ${file} could not be read.`);
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new Error(`${file} is not valid JSON.`);
+    }
+    return readDescription(raw, file);
+}
+/**
+ * Open an HTTP connection: read its description, resolve its credential and
+ * hand both to the adapter. `secrets: false` — a URL a browser supplied —
+ * opens without the credential rather than sending it to that URL, and
+ * without the cache: an answer fetched for one URL is not kept under a name
+ * another URL could be given.
+ */
+export async function openHttp(name, url, http, options) {
+    const where = `"${name}"`;
+    const base = baseUrl(options.secrets ? expandEnvReferences(url, options.environment) : url, http.insecure === true, where);
+    const description = typeof http.description === 'string' ? await describedIn(http.descriptionPath ?? http.description) : http.description;
+    let auth;
+    let secret = 'none';
+    let warning;
+    if (http.auth && options.secrets) {
+        const written = 'bearer' in http.auth ? http.auth.bearer : http.auth.value;
+        const value = expandEnvReferences(written, options.environment);
+        auth =
+            'bearer' in http.auth ? { header: 'authorization', value: `Bearer ${value}` } : { header: http.auth.header.toLowerCase(), value };
+        secret = value !== written ? 'environment' : 'inline';
+        if (secret === 'inline')
+            warning = 'This connection has its credential written into the config file. Prefer ${ENV_VAR}.';
+    }
+    const policy = { ...DEFAULT_POLICY, insecure: http.insecure === true, allowLinkLocal: http.allowLinkLocal === true };
+    const cache = http.cache && options.cache && options.secrets ? { store: options.cache, ttlMs: http.cache.ttl * 1000 } : undefined;
+    return { adapter: new HttpAdapter({ base, description, label: name, auth, policy, ...(cache ? { cache } : {}) }), secret, warning };
+}

package/dist/server/impact.d.ts

@@ -0,0 +1,55 @@
+/**
+ * What deleting a row would take with it — shared by the HTTP endpoint and
+ * the MCP server, which cannot import index.ts without also running it.
+ *
+ * One filtered count per incoming constraint, batched, with the constraint's
+ * `ON DELETE` rule beside each count: the same three rows are three
+ * deletions, three holes, or a refusal depending on it, and a count without
+ * the rule invites the reader to guess which.
+ *
+ * Only the first level. A `cascade` whose children themselves cascade would
+ * need the whole reachable graph, and walking it means a query per table per
+ * level on a schema that may be cyclic — expensive, and slow exactly when the
+ * answer matters most. Saying "three invoice rows, which cascade" is honest
+ * and useful; claiming a total that quietly stopped one level down would not
+ * be.
+ */
+import type { Adapter } from '../adapters/adapter.js';
+import { type DatabaseSchema } from '../shared/schema.js';
+/**
+ * Run `work` over `items`, at most `width` at a time, keeping input order.
+ *
+ * `Promise.all` over a map is the usual shape and is unbounded: it starts
+ * everything and hopes the pool underneath copes. For a handful of cheap
+ * queries that is right; for a dozen table scans it is a way to make one page
+ * load monopolise a connection.
+ */
+export declare function inBatches<T, R>(items: readonly T[], width: number, work: (item: T) => Promise<R>): Promise<R[]>;
+export declare function deleteImpact(adapter: Adapter, schema: DatabaseSchema, tableId: string, key: Record<string, string | number>, errorMessage?: (error: unknown) => string): Promise<NonNullable<{
+    table: string;
+    columns: string[];
+    constraint: string;
+    onDelete: import("../shared/schema.js").DeleteRule | undefined;
+    filter: {
+        groups: {
+            column: string;
+            op: '=';
+            value: string | number;
+        }[][];
+    };
+    count: number;
+} | {
+    table: string;
+    columns: string[];
+    constraint: string;
+    onDelete: import("../shared/schema.js").DeleteRule | undefined;
+    filter: {
+        groups: {
+            column: string;
+            op: '=';
+            value: string | number;
+        }[][];
+    };
+    count: number;
+    error: string;
+} | null>[]>;

package/dist/server/impact.js

@@ -0,0 +1,47 @@
+import { referencesTo } from '../shared/schema.js';
+/**
+ * Run `work` over `items`, at most `width` at a time, keeping input order.
+ *
+ * `Promise.all` over a map is the usual shape and is unbounded: it starts
+ * everything and hopes the pool underneath copes. For a handful of cheap
+ * queries that is right; for a dozen table scans it is a way to make one page
+ * load monopolise a connection.
+ */
+export async function inBatches(items, width, work) {
+    const out = [];
+    for (let i = 0; i < items.length; i += width) {
+        out.push(...(await Promise.all(items.slice(i, i + width).map(work))));
+    }
+    return out;
+}
+export async function deleteImpact(adapter, schema, tableId, key, errorMessage = (error) => error.message) {
+    // A declared reference is not the database's: deleting its target touches no row that names it.
+    const incoming = referencesTo(schema, tableId).filter((fk) => !fk.declared);
+    const found = await inBatches(incoming, 4, async (fk) => {
+        const conditions = fk.to.columns.map((toCol, i) => ({
+            column: fk.from.columns[i] ?? fk.from.columns[0],
+            op: '=',
+            value: key[toCol],
+        }));
+        if (conditions.some((c) => c.value === undefined || c.value === null))
+            return null;
+        const base = {
+            table: fk.from.table,
+            columns: fk.from.columns,
+            constraint: fk.name,
+            onDelete: fk.onDelete,
+            filter: { groups: [conditions] },
+        };
+        try {
+            return { ...base, count: await adapter.count(fk.from.table, base.filter) };
+        }
+        catch (err) {
+            // One unreadable table must not stop the report; a count nobody could
+            // take is more honest as an error than as a zero.
+            return { ...base, count: -1, error: errorMessage(err) };
+        }
+    });
+    /* Constraints with nothing behind them are dropped: "0 rows point at this"
+       is noise in a list whose only job is to say what would be affected. */
+    return found.filter((r) => r !== null).filter((r) => r.count !== 0);
+}

package/dist/server/journal.d.ts

@@ -0,0 +1,134 @@
+/**
+ * What was written, and how to put it back.
+ *
+ * Transactions protect a call from failing *halfway*. They do nothing at all
+ * about a call that succeeded and should not have — which is the failure mode
+ * that actually happens when an agent has write access: nothing errored,
+ * nothing rolled back, and the row is simply wrong now. Every destructive
+ * label in the tool surface warns about that and none of them helped after
+ * the fact.
+ *
+ * So every write that lands is recorded with what it would take to undo it,
+ * and `revert` undoes the last one. The browser has had an undo for its own
+ * edits since write mode shipped; this is the same idea one door out, covering
+ * the writes an agent makes as well, and covering inserts and deletes, which
+ * that one never did.
+ *
+ * Three things it deliberately does not do.
+ *
+ * It is **not persisted**. The browser's undo stack makes this argument and it
+ * is the right one: a stack that outlives the process invites undoing
+ * something from an hour ago, by which time the row has very likely moved on
+ * and the "undo" is an overwrite wearing a friendly name. In-session is the
+ * honest scope.
+ *
+ * It **checks before it writes**. Putting the old value back over a newer one
+ * is not an undo, it is a silent overwrite — so the row is re-read first and
+ * the revert refused if it no longer holds what this journal put there. An
+ * undo that can quietly destroy someone else's edit is worse than no undo.
+ *
+ * And it **does not pretend about SQL**. A `runSql` write is recorded so the
+ * history is complete, and marked unrevertible with the reason: arbitrary SQL
+ * has no general inverse, and guessing one is how a safety net becomes the
+ * thing that cut you.
+ */
+import { type Adapter, type WriteTransaction } from '../adapters/adapter.js';
+type WriteKind = 'update' | 'insert' | 'delete' | 'insert_graph' | 'delete_graph' | 'sql';
+/** One row's worth of change, and everything needed to reverse it. */
+export interface WriteStep {
+    table: string;
+    /** The row's primary key. Absent only where the write never had one. */
+    key?: Record<string, unknown>;
+    /** What the row held before. The inverse of an update or a delete. */
+    before?: Record<string, unknown>;
+    /** What it holds after, which is what a revert checks is still true. */
+    after?: Record<string, unknown>;
+    /** Complete stored image for bounded single-row inverses. Requires a fenced
+     * transaction and lossless comparison; restore also requires non-replacing
+     * insertion. Unmarked graph/scoped entries retain their existing contracts. */
+    wholeRow?: boolean;
+    /** Bounded update inverse: fence and compare only the touched fields, then
+     * verify their restored stored values before committing. */
+    exactFields?: boolean;
+}
+export interface JournalEntry {
+    id: number;
+    connection: string;
+    kind: WriteKind;
+    at: string;
+    /** One line, in the words someone would use about it afterwards. */
+    summary: string;
+    /** Who made it, when a proxy header said (see --auth-proxy-header). */
+    by?: string;
+    /** Verified account and authored app identity, never request-supplied labels. */
+    principal?: string;
+    app?: string;
+    revertible: boolean;
+    /** Present when it is not, saying why rather than leaving it to be guessed. */
+    reason?: string;
+    /** In-memory attempt state, not a durable operation receipt. */
+    undoState?: 'pending' | 'unknown';
+    /** A confirmed write without a safe inverse must not expose an older Undo. */
+    blocksUndo?: boolean;
+    steps: WriteStep[];
+}
+/** Record a write that landed. Returns the entry, mostly for tests. */
+export declare function recordWrite(connection: string, entry: Omit<JournalEntry, 'id' | 'at' | 'connection'>): JournalEntry;
+/** The most recent first, which is the order anyone asks about them in. */
+export declare function history(connection: string, limit?: number): JournalEntry[];
+/** The newest write that could still be undone, if there is one. */
+export declare function lastRevertible(connection: string): JournalEntry | undefined;
+/** Entries are newest first. Never silently step past an unresolved Undo. */
+export declare function latestRevertible(entries: readonly JournalEntry[]): JournalEntry | undefined;
+export declare function forget(connection: string, id: number): void;
+/** Testing seam: a fresh process is the normal state, and tests want it too. */
+export declare function clearJournal(connection?: string): void;
+/** Fail closed without publishing another entry (or consulting a clock). The
+ * caller supplies already verified ownership; no record values are introduced. */
+export declare function quarantineHistory(connection: string, owner?: {
+    principal?: string;
+    app?: string;
+}): void;
+type RevertResult = {
+    entry: JournalEntry;
+    /** What was put back, in the order it was put back. */
+    steps?: Array<{
+        table: string;
+        key?: Record<string, unknown>;
+        action: string;
+    }>;
+} & ({
+    reverted: true;
+    outcome: 'applied';
+    errors?: never;
+} | {
+    reverted: false;
+    outcome: 'not_applied' | 'unknown';
+    errors?: string[];
+});
+/**
+ * Undo one recorded write.
+ *
+ * Every step is checked against the database before anything is written, and
+ * the whole revert is refused if any of them has moved on. Half an undo is
+ * worse than none: it leaves the row in a state neither the write nor the
+ * revert intended, and nothing recorded that it happened.
+ */
+export declare function revert(adapter: Adapter, connection: string, entry: JournalEntry, errorMessage?: (error: unknown) => string): Promise<RevertResult>;
+/** Call on the fenced writer BOTH when capturing an image and when undoing it.
+ * SQL equality detects lossy driver conversions (e.g. submillisecond dates);
+ * strict scalar comparison also rejects NULL/empty and collation-equivalent
+ * text changes. Capture-time validation is essential: a later rounded value
+ * could match an image whose original precision was already lost.
+ * Permission wrappers must expose complete raw fields before marking wholeRow.
+ * This proves one scalar row, not trigger/cascade side effects or DDL history. */
+export declare function journalImageMatches(tx: Pick<WriteTransaction, 'query'>, table: string, image: Record<string, unknown> | undefined): Promise<boolean>;
+/** The touched-field counterpart to journalImageMatches. Call under lockRecord
+ * before and after a shared update to establish lossless history, and around
+ * its inverse to detect races and restore coercion. Untouched fields need no
+ * projection or inverse permission. A successful capture is not a guarantee
+ * that generic type coercion will restore it; inverse readback must still pass. */
+export declare function journalFieldsMatch(tx: Pick<WriteTransaction, 'query'>, table: string, key: Record<string, unknown> | undefined, values: Record<string, unknown> | undefined): Promise<boolean>;
+/** A sentence for the history, in the words someone would use about it. */
+export declare function summarise(kind: WriteKind, steps: WriteStep[], detail?: string): string;
+export {};