@agentic-kit/db-tools 0.11.5 → 0.12.0

package/esm/provision-database/request-database.js

@@ -21,6 +21,33 @@ export const POLL_DEADLINE_MS = 240_000;
  * a creation that is about to succeed.
  */
 export const MAX_CONSECUTIVE_POLL_FAILURES = 3;
+/**
+ * The provision is still running server-side, but this call stopped waiting:
+ * the deadline passed, or the backend couldn't be reached. A caller should keep
+ * `ticketId` and pass it back as `resumeTicketId`, because requesting the same
+ * name again starts a second provision rather than resuming this one.
+ */
+export class ProvisionPendingError extends Error {
+    ticketId;
+    constructor(message, ticketId, options) {
+        super(message, options);
+        this.ticketId = ticketId;
+        this.name = 'ProvisionPendingError';
+    }
+}
+/**
+ * The recorded ticket can't be read back: it is gone, or this account can't
+ * see it. Nothing says the provision stopped, so a caller must not request
+ * the same database again on this alone.
+ */
+export class ProvisionTicketLostError extends Error {
+    ticketId;
+    constructor(message, ticketId) {
+        super(message);
+        this.ticketId = ticketId;
+        this.name = 'ProvisionTicketLostError';
+    }
+}
 const TICKET_SELECT = {
     id: true,
     status: true,
@@ -29,7 +56,9 @@ const TICKET_SELECT = {
     errorMessage: true,
     bootstrapError: true,
 };
-function createSdkExecutor(args) {
+/** How many of an account's tickets for one name a lookup reads. */
+const LIST_OWN_LIMIT = 5;
+export function createProvisionExecutor(args) {
     const headers = { Authorization: `Bearer ${args.bearer}` };
     const apiClient = api.createClient({ adapter: new api.FetchAdapter(args.apiEndpoint, headers) });
     const modulesClient = modules.createClient({
@@ -59,8 +88,44 @@ function createSdkExecutor(args) {
                 .unwrap();
             return result.databaseProvisionModule ?? null;
         },
+        async listOwn({ databaseName, ownerId }) {
+            const result = await modulesClient.databaseProvisionModule
+                .findMany({
+                select: { ...TICKET_SELECT, databaseName: true, createdAt: true },
+                where: { databaseName: { equalTo: databaseName }, ownerId: { equalTo: ownerId } },
+                orderBy: ['CREATED_AT_DESC'],
+                first: LIST_OWN_LIMIT,
+            })
+                .unwrap();
+            return (result.databaseProvisionModules?.nodes ?? []).filter((ticket) => Boolean(ticket));
+        },
     };
 }
+/** A ticket whose provision or owner bootstrap is still running. */
+export function isTicketInFlight(ticket) {
+    if (ticket.status === 'pending' || ticket.status === 'in_progress')
+        return true;
+    return ticket.status === 'completed' && (ticket.bootstrapStatus === 'pending' || ticket.bootstrapStatus === 'in_progress');
+}
+const NETWORK_ERROR_RE = /fetch failed|network|socket hang up|ECONNRESET|ECONNREFUSED|ETIMEDOUT|EAI_AGAIN|ENOTFOUND|aborted|timed? ?out/i;
+/**
+ * Whether an error reading or requesting a ticket says only that the backend
+ * couldn't be reached or failed: a network error thrown before any response,
+ * or an HTTP 5xx/429 the adapter reports as the only error. A GraphQL error
+ * (validation, permission, an expired or rejected token) is an answer, so the
+ * ticket can't be followed any further.
+ */
+export function isTransientProvisionError(err) {
+    const errors = err?.errors;
+    if (Array.isArray(errors)) {
+        return errors.length > 0 && errors.every((e) => /^HTTP (5\d\d|429)\b/.test(e?.message ?? ''));
+    }
+    if (!(err instanceof Error))
+        return false;
+    const code = err.cause?.code;
+    return NETWORK_ERROR_RE.test(`${err.message} ${typeof code === 'string' ? code : ''}`);
+}
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -69,26 +134,54 @@ function sleep(ms) {
  * `status` AND `bootstrapStatus` both 'completed'. The ticket the mutation
  * returns is checked before the first sleep, so a warm claim with bootstrap
  * already done never waits. `status: 'failed'` surfaces `errorMessage`;
- * `bootstrapStatus: 'failed'` surfaces `bootstrapError`.
+ * `bootstrapStatus: 'failed'` surfaces `bootstrapError`. Stopping short of
+ * either outcome throws `ProvisionPendingError`.
+ *
+ * With `resumeTicketId` the ticket of an earlier call is polled instead of
+ * requesting again, and `resumed` is true. A ticket that reads back empty
+ * throws `ProvisionTicketLostError`, never a new request: the provision may
+ * still be running where this account can't see it.
  */
 export async function requestDatabaseProvision(args) {
     const executor = args.executor ??
-        createSdkExecutor({
+        createProvisionExecutor({
             apiEndpoint: args.apiEndpoint,
             modulesEndpoint: args.modulesEndpoint,
             bearer: args.bearer,
         });
     const intervalMs = args.pollIntervalMs ?? POLL_INTERVAL_MS;
     const deadlineMs = args.pollDeadlineMs ?? POLL_DEADLINE_MS;
-    let ticket = await executor.request({
-        databaseName: args.databaseName,
-        subdomain: args.databaseName,
-        domain: args.domain,
-        request: args.request,
-    });
-    const ticketId = ticket.id;
+    // A backend that can't be reached leaves the old ticket pending rather than
+    // falling back to a new request, which would start a duplicate provision.
+    // Any other error is final for that ticket.
+    let resumedTicket = null;
+    if (args.resumeTicketId) {
+        try {
+            resumedTicket = await executor.poll(args.resumeTicketId);
+        }
+        catch (err) {
+            if (isTransientProvisionError(err)) {
+                throw new ProvisionPendingError(errorText(err), args.resumeTicketId, { cause: err });
+            }
+            throw new Error(`provision ticket ${args.resumeTicketId} could not be read: ${errorText(err)}`, {
+                cause: err,
+            });
+        }
+        if (!resumedTicket) {
+            throw new ProvisionTicketLostError(`provision ticket ${args.resumeTicketId} could not be found on this backend.`, args.resumeTicketId);
+        }
+    }
+    let ticket = resumedTicket ??
+        (await executor.request({
+            databaseName: args.databaseName,
+            subdomain: args.databaseName,
+            domain: args.domain,
+            request: args.request,
+        }));
+    const ticketId = resumedTicket ? (ticket.id ?? args.resumeTicketId) : ticket.id;
     if (!ticketId)
         throw new Error('requestDatabase returned a provision ticket without an id.');
+    const resumed = resumedTicket ? { resumed: true } : {};
     const deadline = Date.now() + deadlineMs;
     let failures = 0;
     for (;;) {
@@ -101,26 +194,34 @@ export async function requestDatabaseProvision(args) {
         if (ticket.status === 'completed' && ticket.bootstrapStatus === 'completed') {
             if (!ticket.databaseId)
                 throw new Error('provisioning completed but returned no databaseId.');
-            return { databaseId: ticket.databaseId };
+            return { databaseId: ticket.databaseId, ticketId, ...resumed };
         }
         if (Date.now() >= deadline) {
-            throw new Error(`provisioning timed out after ${Math.round(deadlineMs / 1000)}s (status: ${ticket.status ?? 'unknown'}, bootstrapStatus: ${ticket.bootstrapStatus ?? 'unknown'})`);
+            throw new ProvisionPendingError(`provisioning timed out after ${Math.round(deadlineMs / 1000)}s (status: ${ticket.status ?? 'unknown'}, bootstrapStatus: ${ticket.bootstrapStatus ?? 'unknown'})`, ticketId);
         }
         await sleep(intervalMs);
-        // A poll that throws (network blip, 502) or comes back empty is retried a
-        // few times rather than failing a provision that is still running.
+        // A poll that can't reach the backend (network blip, 502) or comes back
+        // empty is retried a few times rather than failing a provision that is
+        // still running. Past that, an unreachable backend leaves the ticket
+        // pending; an empty answer, or any error that is an answer, is final.
         let polled;
         try {
             polled = await executor.poll(ticketId);
         }
         catch (err) {
-            if (++failures > MAX_CONSECUTIVE_POLL_FAILURES)
-                throw err;
+            if (!isTransientProvisionError(err)) {
+                throw new Error(`provision ticket ${ticketId} could not be read: ${errorText(err)}`, {
+                    cause: err,
+                });
+            }
+            if (++failures > MAX_CONSECUTIVE_POLL_FAILURES) {
+                throw new ProvisionPendingError(errorText(err), ticketId, { cause: err });
+            }
             continue;
         }
         if (!polled) {
             if (++failures > MAX_CONSECUTIVE_POLL_FAILURES) {
-                throw new Error(`provision ticket ${ticketId} could not be read back.`);
+                throw new ProvisionTicketLostError(`provision ticket ${ticketId} could not be read back.`, ticketId);
             }
             continue;
         }

package/esm/schema-model/normalize.d.ts

@@ -0,0 +1,21 @@
+import type { ColumnDefault, FkAction } from '../schema-model';
+/** A field's type as one name (`integer`, `timestamptz`, `email`, …) plus `[]` per array dimension. */
+export declare function normalizeType(rawType: unknown): string;
+/**
+ * A field's stored default as one of the shapes a planner can compare: a
+ * literal, the current time or date, a generated id, or an expression it
+ * should leave alone. `DEFAULT NULL` is no default.
+ */
+export declare function columnDefault(raw: unknown): ColumnDefault | null;
+export type CheckRead = {
+    values?: string[];
+    other: boolean;
+};
+/**
+ * What one check expression allows. An IN-list gives `values`; anything else
+ * it can't read (ranges, patterns, other columns) sets `other`. In an AND,
+ * one IN-list still gives its values, beside `other` for the rest.
+ */
+export declare function readCheck(raw: unknown): CheckRead;
+/** A stored action code (`c n r a d`) as a name; Postgres' default is no action. */
+export declare function fkAction(code: unknown): FkAction;

package/esm/schema-model/normalize.js

@@ -0,0 +1,244 @@
+// Pure readers for the metaschema's stored shapes: field types, structured
+// defaults, check expressions (Postgres AST JSON) and foreign key actions.
+import { fieldTypeToTypeName, toFieldDefault } from '@agentic-kit/harness';
+const TYPE_ALIASES = {
+    int: 'integer',
+    int4: 'integer',
+    serial: 'integer',
+    serial4: 'integer',
+    int8: 'bigint',
+    bigserial: 'bigint',
+    serial8: 'bigint',
+    int2: 'smallint',
+    smallserial: 'smallint',
+    bool: 'boolean',
+    decimal: 'numeric',
+    float4: 'real',
+    float: 'double precision',
+    float8: 'double precision',
+    'timestamp with time zone': 'timestamptz',
+    'timestamp without time zone': 'timestamp',
+    'time with time zone': 'timetz',
+    'time without time zone': 'time',
+    'character varying': 'varchar',
+    character: 'char',
+    bpchar: 'char',
+};
+/** A field's type as one name (`integer`, `timestamptz`, `email`, …) plus `[]` per array dimension. */
+export function normalizeType(rawType) {
+    const name = fieldTypeToTypeName(rawType).trim().toLowerCase();
+    const dims = /(\[\])*$/.exec(name)?.[0] ?? '';
+    const base = name.slice(0, name.length - dims.length).trim();
+    return (TYPE_ALIASES[base] ?? base) + dims;
+}
+const NOW_KEYWORDS = new Set(['CURRENT_TIMESTAMP', 'LOCALTIMESTAMP']);
+const NOW_FUNCTIONS = new Set([
+    'now',
+    'current_timestamp',
+    'statement_timestamp',
+    'transaction_timestamp',
+    'clock_timestamp',
+]);
+/**
+ * A field's stored default as one of the shapes a planner can compare: a
+ * literal, the current time or date, a generated id, or an expression it
+ * should leave alone. `DEFAULT NULL` is no default.
+ */
+export function columnDefault(raw) {
+    if (raw === null || raw === undefined)
+        return null;
+    if (typeof raw === 'number' || typeof raw === 'boolean')
+        return { kind: 'value', value: raw };
+    if (typeof raw === 'string') {
+        const parsed = toFieldDefault(raw);
+        return parsed ? fromStructured(parsed) : null;
+    }
+    if (typeof raw === 'object' && !Array.isArray(raw))
+        return fromStructured(raw);
+    return { kind: 'expression', text: JSON.stringify(raw) };
+}
+function fromStructured(def) {
+    if (typeof def.sql_keyword === 'string') {
+        const keyword = def.sql_keyword.toUpperCase();
+        if (NOW_KEYWORDS.has(keyword))
+            return { kind: 'now' };
+        if (keyword === 'CURRENT_DATE')
+            return { kind: 'today' };
+        return { kind: 'expression', text: keyword };
+    }
+    if (typeof def.function === 'string') {
+        const fn = def.function.toLowerCase();
+        const bare = !(Array.isArray(def.args) && def.args.length > 0) && def.cast == null;
+        if (bare && NOW_FUNCTIONS.has(fn))
+            return { kind: 'now' };
+        if (bare && fn === 'current_date')
+            return { kind: 'today' };
+        if (bare && fn.includes('uuid'))
+            return { kind: 'generated', fn: def.function };
+        return { kind: 'expression', text: renderDefault(def) };
+    }
+    if ('value' in def && def.operator === undefined) {
+        const value = def.value;
+        if (value === null || value === undefined)
+            return null;
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+            return { kind: 'value', value };
+        }
+        return { kind: 'expression', text: JSON.stringify(value) };
+    }
+    return { kind: 'expression', text: renderDefault(def) };
+}
+const sqlLiteral = (value) => typeof value === 'string' ? `'${value.replace(/'/g, "''")}'` : JSON.stringify(value);
+// SQL-ish text for a default no other shape fits; it is shown, never run.
+function renderDefault(def) {
+    if (def === null || def === undefined)
+        return 'NULL';
+    if (typeof def !== 'object')
+        return sqlLiteral(def);
+    const d = def;
+    let text;
+    if (typeof d.sql_keyword === 'string')
+        text = d.sql_keyword;
+    else if (typeof d.function === 'string') {
+        text = `${d.function}(${Array.isArray(d.args) ? d.args.map(renderDefault).join(', ') : ''})`;
+    }
+    else if (typeof d.operator === 'string')
+        text = `${renderDefault(d.left)} ${d.operator} ${renderDefault(d.right)}`;
+    else if ('value' in d)
+        text = d.value === null ? 'NULL' : sqlLiteral(d.value);
+    else
+        return JSON.stringify(def);
+    const cast = fieldTypeToTypeName(d.cast);
+    return cast ? `${text}::${cast}` : text;
+}
+const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** A node's list: a plain array, or a `{ List: { items } }` wrapper. */
+function listItems(value) {
+    if (Array.isArray(value))
+        return value;
+    if (isObject(value)) {
+        const list = isObject(value.List) ? value.List : value;
+        if (Array.isArray(list.items))
+            return list.items;
+    }
+    return undefined;
+}
+// `{ expression: <ast> }` is how the metaschema stores a raw AST on
+// field.chk and check_constraint.expr.
+function unwrapExpression(value) {
+    return isObject(value) && 'expression' in value ? value.expression : value;
+}
+function unwrapCast(value) {
+    let node = value;
+    while (isObject(node) && isObject(node.TypeCast))
+        node = node.TypeCast.arg;
+    return node;
+}
+const stringOf = (value) => {
+    if (typeof value === 'string')
+        return value;
+    if (isObject(value)) {
+        if (typeof value.sval === 'string')
+            return value.sval;
+        if (typeof value.str === 'string')
+            return value.str;
+        if (isObject(value.String))
+            return stringOf(value.String);
+    }
+    return undefined;
+};
+/** The operator of an `A_Expr`: the last name in its `name` list. */
+function operatorOf(name) {
+    const items = listItems(name);
+    return items && items.length > 0 ? stringOf(items[items.length - 1]) : undefined;
+}
+/** An `A_Const` as text: `sval` plain or wrapped, `ival`, `fval`, `boolval`. */
+function constValue(value) {
+    const node = unwrapCast(value);
+    if (!isObject(node) || !isObject(node.A_Const))
+        return undefined;
+    const c = node.A_Const;
+    if (c.isnull === true)
+        return undefined;
+    if ('sval' in c)
+        return stringOf(c.sval);
+    if ('ival' in c) {
+        // The parser's JSON leaves out zero: `{ ival: {} }` is 0.
+        const ival = isObject(c.ival) ? (c.ival.ival ?? 0) : c.ival;
+        return typeof ival === 'number' ? String(ival) : undefined;
+    }
+    if ('fval' in c) {
+        const fval = isObject(c.fval) ? c.fval.fval : c.fval;
+        return typeof fval === 'string' || typeof fval === 'number' ? String(fval) : undefined;
+    }
+    if ('boolval' in c) {
+        const boolval = isObject(c.boolval) ? (c.boolval.boolval ?? false) : c.boolval;
+        return typeof boolval === 'boolean' ? String(boolval) : undefined;
+    }
+    if (isObject(c.val)) {
+        const val = c.val;
+        if (isObject(val.String))
+            return stringOf(val.String);
+        if (isObject(val.Integer))
+            return String(val.Integer.ival ?? 0);
+    }
+    return undefined;
+}
+/** The values of `col IN (…)` or `col = ANY (ARRAY[…])`; undefined for anything else. */
+function inListValues(value) {
+    if (!isObject(value) || !isObject(value.A_Expr))
+        return undefined;
+    const expr = value.A_Expr;
+    if (operatorOf(expr.name) !== '=')
+        return undefined;
+    let items;
+    if (expr.kind === 'AEXPR_IN') {
+        items = listItems(expr.rexpr);
+    }
+    else if (expr.kind === 'AEXPR_OP_ANY') {
+        const array = unwrapCast(expr.rexpr);
+        items = isObject(array) && isObject(array.A_ArrayExpr) ? listItems(array.A_ArrayExpr.elements) : undefined;
+    }
+    if (!items || items.length === 0)
+        return undefined;
+    const values = items.map(constValue);
+    return values.every((v) => v !== undefined) ? values : undefined;
+}
+/**
+ * What one check expression allows. An IN-list gives `values`; anything else
+ * it can't read (ranges, patterns, other columns) sets `other`. In an AND,
+ * one IN-list still gives its values, beside `other` for the rest.
+ */
+export function readCheck(raw) {
+    const node = unwrapExpression(raw);
+    if (node === null || node === undefined)
+        return { other: false };
+    if (isObject(node) && isObject(node.BoolExpr) && /AND/i.test(String(node.BoolExpr.boolop ?? ''))) {
+        const parts = (listItems(node.BoolExpr.args) ?? []).map(readCheck);
+        const lists = parts.filter((part) => part.values);
+        return {
+            values: lists.length === 1 ? lists[0].values : undefined,
+            other: lists.length > 1 || parts.some((part) => part.other),
+        };
+    }
+    const values = inListValues(node);
+    return values ? { values, other: false } : { other: true };
+}
+// ---- foreign keys -----------------------------------------------------
+const FK_ACTIONS = {
+    c: 'cascade',
+    n: 'set_null',
+    r: 'restrict',
+    a: 'no_action',
+    d: 'set_default',
+    cascade: 'cascade',
+    set_null: 'set_null',
+    restrict: 'restrict',
+    no_action: 'no_action',
+    set_default: 'set_default',
+};
+/** A stored action code (`c n r a d`) as a name; Postgres' default is no action. */
+export function fkAction(code) {
+    const key = String(code ?? '').trim().toLowerCase().replace(/\s+/g, '_');
+    return FK_ACTIONS[key] ?? 'no_action';
+}

package/esm/schema-model.d.ts

@@ -0,0 +1,110 @@
+import type { ProjectContext } from './context';
+import { type GraphQLError } from './graphql-http';
+export type ObjectCategory = 'APP' | 'AUTH' | 'CAPABILITIES' | 'CORE' | 'MEMBERSHIPS' | 'MODULE';
+export type ColumnDefault = {
+    kind: 'value';
+    value: string | number | boolean | null;
+} | {
+    kind: 'now';
+} | {
+    kind: 'today';
+}
+/** A generated id: `uuidv7()`, `gen_random_uuid()`, … */
+ | {
+    kind: 'generated';
+    fn: string;
+}
+/** Anything else; a planner should leave the column's default alone. */
+ | {
+    kind: 'expression';
+    text: string;
+};
+export type ModelColumn = {
+    id: string;
+    name: string;
+    /** A status column made by DataStatusField is 'MODULE'. */
+    category: ObjectCategory;
+    order: number;
+    /** Normalised (`integer`, `timestamptz`, `email`, …) plus `[]` per array dimension. */
+    type: string;
+    rawType: Record<string, unknown> | null;
+    isRequired: boolean;
+    default: ColumnDefault | null;
+    /** The values an IN-list check allows. `_meta` stays the enum source; these spot disagreement. */
+    allowedValues?: string[];
+    /** True when some other check (range, pattern, …) applies too. */
+    hasOtherCheck?: boolean;
+    isPrimaryKey: boolean;
+    /** True when a single-column unique constraint covers it. */
+    isUnique: boolean;
+    /** An identity or generated column. */
+    generated: boolean;
+    label?: string;
+    description?: string;
+    smartTags?: Record<string, unknown>;
+};
+export type FkAction = 'cascade' | 'set_null' | 'restrict' | 'no_action' | 'set_default';
+export type ModelForeignKey = {
+    id: string;
+    name?: string;
+    columnIds: string[];
+    columns: string[];
+    targetTableId: string;
+    targetTable: string;
+    targetCategory: ObjectCategory | null;
+    targetColumns: string[];
+    onDelete: FkAction;
+    onUpdate: FkAction;
+};
+export type ModelPolicy = {
+    id: string;
+    type: string;
+    privilege: string;
+    role: string;
+    permissive: boolean;
+    disabled: boolean;
+    data: Record<string, unknown> | null;
+    withCheck?: Record<string, unknown> | null;
+};
+export type TableAccess = 'shared' | 'private' | 'custom';
+export type ModelTable = {
+    id: string;
+    name: string;
+    category: ObjectCategory;
+    label?: string;
+    columns: ModelColumn[];
+    foreignKeys: ModelForeignKey[];
+    uniqueConstraints: {
+        id: string;
+        columns: string[];
+    }[];
+    access: TableAccess;
+    /** The table's policies, internal ones left out. */
+    policies: ModelPolicy[];
+};
+export type SchemaModel = {
+    databaseId: string;
+    /** The schema hash, read before anything else; null on a backend without it. */
+    hash: string | null;
+    /** APP tables, sorted by name. */
+    tables: ModelTable[];
+};
+/** A read failed, so there is no model: a partial one would look like columns dropped outside. */
+export declare class SchemaReadError extends Error {
+    readonly step: string;
+    readonly errors?: readonly GraphQLError[];
+    constructor(message: string, step: string, errors?: readonly GraphQLError[]);
+}
+/**
+ * The access mode a table's policies amount to. `private` is the app-member
+ * owner policy on `owner_id` and `shared` the plain app-membership policy,
+ * each for the authenticated role over select, insert, update and delete.
+ * Anything else, no policies included, is `custom`. Disabled and internal
+ * policies don't count.
+ */
+export declare function accessOf(policies: readonly ModelPolicy[]): TableAccess;
+/**
+ * Read the APP tables of the context's database. All or nothing: any failed
+ * query throws `SchemaReadError`.
+ */
+export declare function readSchemaModel(context: ProjectContext): Promise<SchemaModel>;