@agentic-kit/db-tools 0.11.5 → 0.12.0

package/provision-database/pending-ticket.js

@@ -0,0 +1,72 @@
+"use strict";
+// The provision request provision_database stopped waiting on, as recorded in
+// a project's .env. requestDatabase never resumes by name, so the ticket is
+// the only way back to a provision that is still running.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ABANDONED_TICKETS_KEY = exports.MAX_PENDING_ATTEMPTS = void 0;
+exports.recordedTicket = recordedTicket;
+exports.recordPendingTicket = recordPendingTicket;
+exports.clearPendingTicket = clearPendingTicket;
+exports.archivePendingTicket = archivePendingTicket;
+exports.abandonedTickets = abandonedTickets;
+exports.recordAbandoned = recordAbandoned;
+const env_file_1 = require("./env-file");
+/**
+ * Pending results recorded for one ticket before provision_database stops
+ * following it. At the default 240 s deadline that is about 20 minutes.
+ */
+exports.MAX_PENDING_ATTEMPTS = 5;
+const KEYS = Object.values(env_file_1.PENDING_PROVISION_KEYS);
+/**
+ * Tickets the host told provisioning to stop following (`abandonPending`),
+ * comma-separated. A lookup by name skips them, so an abandoned provision is
+ * never resumed.
+ */
+exports.ABANDONED_TICKETS_KEY = 'PROVISION_TICKET_ABANDONED';
+/** The newest abandoned ids kept; older ones are long finished or failed. */
+const MAX_ABANDONED = 10;
+/**
+ * The recorded ticket, with the name, backend and account it was requested
+ * for. Only a ticket from this backend and account is ours to poll, and one
+ * for another name is a different database.
+ */
+function recordedTicket(env) {
+    const ticketId = env[env_file_1.PENDING_PROVISION_KEYS.ticketId];
+    if (!ticketId)
+        return undefined;
+    const attempts = Number.parseInt(env[env_file_1.PENDING_PROVISION_KEYS.attempts] ?? '', 10);
+    return {
+        ticketId,
+        databaseName: env[env_file_1.PENDING_PROVISION_KEYS.databaseName] ?? '',
+        apiEndpoint: env[env_file_1.PENDING_PROVISION_KEYS.apiEndpoint] ?? '',
+        userId: env[env_file_1.PENDING_PROVISION_KEYS.userId] ?? '',
+        attempts: Number.isFinite(attempts) && attempts > 0 ? attempts : 0,
+    };
+}
+function recordPendingTicket(content, ticket) {
+    return (0, env_file_1.mergeEnv)(content, {
+        [env_file_1.PENDING_PROVISION_KEYS.ticketId]: ticket.ticketId,
+        [env_file_1.PENDING_PROVISION_KEYS.databaseName]: ticket.databaseName,
+        [env_file_1.PENDING_PROVISION_KEYS.apiEndpoint]: ticket.apiEndpoint,
+        [env_file_1.PENDING_PROVISION_KEYS.userId]: ticket.userId,
+        [env_file_1.PENDING_PROVISION_KEYS.attempts]: String(ticket.attempts),
+    });
+}
+function clearPendingTicket(content) {
+    return (0, env_file_1.removeEnvKeys)(content, KEYS);
+}
+/** Comment the record out (`# archived <date>: …`), keeping it readable. */
+function archivePendingTicket(content, archivedOn) {
+    return (0, env_file_1.archiveBindingKeys)(content, KEYS, archivedOn);
+}
+function abandonedTickets(env) {
+    return new Set((env[exports.ABANDONED_TICKETS_KEY] ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean));
+}
+/** Add ticket ids to the abandoned list. */
+function recordAbandoned(content, ticketIds) {
+    const ids = [...new Set([...abandonedTickets((0, env_file_1.readEnv)(content)), ...ticketIds])].slice(-MAX_ABANDONED);
+    return (0, env_file_1.mergeEnv)(content, { [exports.ABANDONED_TICKETS_KEY]: ids.join(',') });
+}

package/provision-database/provision.d.ts

@@ -0,0 +1,71 @@
+import { type RunCommand } from '../app-workspace';
+export type ProvisionInput = {
+    databaseName: string;
+    /** `ensure` keeps a live binding; `replace` swaps the binding for a new database. */
+    mode?: 'ensure' | 'replace';
+    /**
+     * Replace mode: the DATABASE_ID the caller expects bound (null: none). Any
+     * other binding fails `binding-changed`. Undefined replaces whatever is bound.
+     */
+    replaces?: string | null;
+    /** Host only: stop following an in-flight provision and request a new one. */
+    abandonPending?: boolean;
+    /**
+     * Host only: bind this database, which the signed-in account owns and is
+     * active, without requesting one (recovery after `name-taken`).
+     */
+    adopt?: string;
+};
+export type ProvisionFailureCode = 'signed-out' | 'backend-unreachable' | 'db-missing' | 'db-suspended' | 'account-mismatch' | 'binding-live' | 'binding-changed' | 'pending-other' | 'ticket-lost' | 'provision-stuck' | 'name-taken' | 'binding-not-saved' | 'env-write-failed' | 'reprovision-not-allowed' | 'failed';
+export type ProvisionDatabaseDetails = {
+    success: boolean;
+    message: string;
+    /** Why it failed; absent on success and on a pending result. */
+    code?: ProvisionFailureCode;
+    databaseId?: string;
+    databaseName?: string;
+    ownerId?: string;
+    /** True when an existing live binding was kept: nothing changed. */
+    skipped?: boolean;
+    /**
+     * True when the call stopped waiting while the provision is still running.
+     * Calling again with the same database_name resumes it.
+     */
+    pending?: boolean;
+    /** The provision ticket, on a pending or stuck result. */
+    ticketId?: string;
+    /** True when this call finished a provision an earlier call had started. */
+    resumed?: boolean;
+    /** True when that provision was found on the backend by name, not in `.env`. */
+    recovered?: boolean;
+    /** The database the new binding replaced (replace mode). */
+    replaced?: string;
+    /** With `name-taken`: a database of this account holds the name. Never bound automatically. */
+    heldBy?: {
+        databaseId: string;
+        yours: boolean;
+        createdAt?: string;
+    };
+};
+type Details = ProvisionDatabaseDetails;
+/** The DATABASE_ID in a project's `.env`, if any. */
+export declare function boundDatabaseId(cwd: string): Promise<string | undefined>;
+/**
+ * Provision the project's database, or keep the one it is bound to. The host
+ * entry point: replace mode refuses a live binding here, and `abandonPending`
+ * and `adopt` are honoured.
+ */
+export declare function provisionDatabase(input: ProvisionInput, ctx: {
+    cwd: string;
+    signal?: AbortSignal;
+}, exec?: RunCommand): Promise<Details>;
+/**
+ * The provision_database tool's entry point: its `reprovision: true` may
+ * replace a live binding (a clean rebuild), unless the host turned tool
+ * reprovisioning off.
+ */
+export declare function provisionFromTool(input: Pick<ProvisionInput, 'databaseName' | 'mode' | 'replaces'>, ctx: {
+    cwd: string;
+    signal?: AbortSignal;
+}, exec?: RunCommand): Promise<Details>;
+export {};