@agentic-kit/db-tools 0.11.4 → 0.12.0

package/esm/provision-database/env-file.js

@@ -1,26 +1,92 @@
-// Pure .env merge — used by provision_database to persist provisioning
-// credentials without clobbering existing keys: replace a key in place if
-// present, else append.
+// Pure .env edits — used by provision_database to persist provisioning
+// credentials without clobbering existing keys.
 // Kept side-effect-free so it is unit-testable (the tool does the fs write).
+//
+// Reads go through the same parser context.ts uses (quotes, `export`,
+// comments, the last definition wins), and edits find a key the way that
+// parser does, so a key written as `export KEY="value"` or spread over several
+// lines by a quoted value is still the key being replaced or removed.
+import { parseDotenv } from '12factor-env/dotenv';
+/** Parse .env text: quoted values, `export` prefixes and comments; last definition wins. */
+export function readEnv(content) {
+    return parseDotenv(content);
+}
+const ENTRY_RE = /^(\s*)(export\s+)?([\w.-]+)\s*=\s*(.*)$/;
+const QUOTES = new Set(['"', "'", '`']);
+// Group lines into entries: a key with the lines its value spans (a quoted
+// value left open continues to the line that closes it), or a non-entry line
+// (comment, blank, anything else) with a null key.
+function envEntries(content) {
+    const lines = content.split('\n');
+    const entries = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const match = line.trimStart().startsWith('#') ? null : ENTRY_RE.exec(line);
+        if (!match) {
+            entries.push({ key: null, exported: false, lines: [line] });
+            continue;
+        }
+        const value = match[4];
+        const span = [line];
+        if (QUOTES.has(value[0]) && !value.slice(1).includes(value[0])) {
+            while (i + 1 < lines.length) {
+                span.push(lines[++i]);
+                if (lines[i].includes(value[0]))
+                    break;
+            }
+        }
+        entries.push({ key: match[3], exported: !!match[2], lines: span });
+    }
+    return entries;
+}
 /**
- * Upsert `vars` into the existing `.env` `content`. Existing keys are replaced
- * in place (preserving surrounding lines/comments); new keys are appended.
+ * Upsert `vars` into the existing `.env` `content`. An existing key is
+ * replaced in place (keeping an `export` prefix), and any later definition of
+ * it is dropped so the new value is the one that wins; new keys are appended.
  * Returns the new file body, trailing-newline-terminated.
  */
 export function mergeEnv(content, vars) {
-    let out = content;
-    for (const [key, val] of Object.entries(vars)) {
-        // Escape the key for the regex, and use a replacement function so `$`
-        // sequences in the value are never treated as replacement specials.
-        const escapedKey = key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-        const regex = new RegExp(`^${escapedKey}=.*`, 'm');
-        if (regex.test(out))
-            out = out.replace(regex, () => `${key}=${val}`);
-        else
-            out += `\n${key}=${val}`;
+    const remaining = new Map(Object.entries(vars));
+    const written = new Set();
+    const out = [];
+    for (const entry of envEntries(content)) {
+        if (entry.key !== null && remaining.has(entry.key)) {
+            out.push(`${entry.exported ? 'export ' : ''}${entry.key}=${remaining.get(entry.key)}`);
+            remaining.delete(entry.key);
+            written.add(entry.key);
+        }
+        else if (entry.key === null || !written.has(entry.key)) {
+            out.push(...entry.lines);
+        }
     }
-    return out.trim() + '\n';
+    let text = out.join('\n');
+    for (const [key, value] of remaining)
+        text += `\n${key}=${value}`;
+    return text.trim() + '\n';
 }
+/**
+ * Drop every definition of `keys`. Comments and other entries pass through,
+ * and content without those keys comes back unchanged.
+ */
+export function removeEnvKeys(content, keys) {
+    const keySet = new Set(keys);
+    const entries = envEntries(content);
+    const kept = entries.filter((entry) => entry.key === null || !keySet.has(entry.key));
+    return kept.length === entries.length ? content : kept.flatMap((entry) => entry.lines).join('\n');
+}
+/**
+ * The provision request provision_database is still waiting on, recorded when
+ * it stops waiting so the next call resumes that ticket. It's resumed only
+ * for the same database name, backend and account. Absent whenever no request
+ * is pending.
+ */
+export const PENDING_PROVISION_KEYS = {
+    ticketId: 'PROVISION_TICKET_ID',
+    databaseName: 'PROVISION_TICKET_DATABASE_NAME',
+    apiEndpoint: 'PROVISION_TICKET_API_ENDPOINT',
+    userId: 'PROVISION_TICKET_USER_ID',
+    attempts: 'PROVISION_TICKET_ATTEMPTS',
+};
 /** The credential keys provision_database owns in a project's .env. */
 export const PROVISION_ENV_KEYS = [
     'DATABASE_ID',
@@ -70,16 +136,9 @@ export function provisionEnvVars(args) {
  */
 export function archiveBindingKeys(content, keys, archivedOn) {
     const keySet = new Set(keys);
-    return content
-        .split('\n')
-        .map((line) => {
-        if (line.trimStart().startsWith('#'))
-            return line;
-        const eq = line.indexOf('=');
-        if (eq === -1)
-            return line;
-        const key = line.slice(0, eq).trim();
-        return keySet.has(key) ? `# archived ${archivedOn}: ${line.trim()}` : line;
-    })
+    return envEntries(content)
+        .flatMap((entry) => entry.key !== null && keySet.has(entry.key)
+        ? entry.lines.map((line) => `# archived ${archivedOn}: ${line.trim()}`)
+        : entry.lines)
         .join('\n');
 }

package/esm/provision-database/pending-ticket.d.ts

@@ -0,0 +1,33 @@
+import { type EnvVars } from './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.
+ */
+export declare const MAX_PENDING_ATTEMPTS = 5;
+export type PendingTicket = {
+    ticketId: string;
+    databaseName: string;
+    apiEndpoint: string;
+    userId: string;
+    /** Pending results recorded for this ticket so far. */
+    attempts: number;
+};
+/**
+ * Tickets the host told provisioning to stop following (`abandonPending`),
+ * comma-separated. A lookup by name skips them, so an abandoned provision is
+ * never resumed.
+ */
+export declare const ABANDONED_TICKETS_KEY = "PROVISION_TICKET_ABANDONED";
+/**
+ * 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.
+ */
+export declare function recordedTicket(env: EnvVars): PendingTicket | undefined;
+export declare function recordPendingTicket(content: string, ticket: PendingTicket): string;
+export declare function clearPendingTicket(content: string): string;
+/** Comment the record out (`# archived <date>: …`), keeping it readable. */
+export declare function archivePendingTicket(content: string, archivedOn: string): string;
+export declare function abandonedTickets(env: EnvVars): Set<string>;
+/** Add ticket ids to the abandoned list. */
+export declare function recordAbandoned(content: string, ticketIds: readonly string[]): string;

package/esm/provision-database/pending-ticket.js

@@ -0,0 +1,63 @@
+// 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.
+import { archiveBindingKeys, mergeEnv, PENDING_PROVISION_KEYS, readEnv, removeEnvKeys, } from './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.
+ */
+export const MAX_PENDING_ATTEMPTS = 5;
+const KEYS = Object.values(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.
+ */
+export const 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.
+ */
+export function recordedTicket(env) {
+    const ticketId = env[PENDING_PROVISION_KEYS.ticketId];
+    if (!ticketId)
+        return undefined;
+    const attempts = Number.parseInt(env[PENDING_PROVISION_KEYS.attempts] ?? '', 10);
+    return {
+        ticketId,
+        databaseName: env[PENDING_PROVISION_KEYS.databaseName] ?? '',
+        apiEndpoint: env[PENDING_PROVISION_KEYS.apiEndpoint] ?? '',
+        userId: env[PENDING_PROVISION_KEYS.userId] ?? '',
+        attempts: Number.isFinite(attempts) && attempts > 0 ? attempts : 0,
+    };
+}
+export function recordPendingTicket(content, ticket) {
+    return mergeEnv(content, {
+        [PENDING_PROVISION_KEYS.ticketId]: ticket.ticketId,
+        [PENDING_PROVISION_KEYS.databaseName]: ticket.databaseName,
+        [PENDING_PROVISION_KEYS.apiEndpoint]: ticket.apiEndpoint,
+        [PENDING_PROVISION_KEYS.userId]: ticket.userId,
+        [PENDING_PROVISION_KEYS.attempts]: String(ticket.attempts),
+    });
+}
+export function clearPendingTicket(content) {
+    return removeEnvKeys(content, KEYS);
+}
+/** Comment the record out (`# archived <date>: …`), keeping it readable. */
+export function archivePendingTicket(content, archivedOn) {
+    return archiveBindingKeys(content, KEYS, archivedOn);
+}
+export function abandonedTickets(env) {
+    return new Set((env[ABANDONED_TICKETS_KEY] ?? '')
+        .split(',')
+        .map((id) => id.trim())
+        .filter(Boolean));
+}
+/** Add ticket ids to the abandoned list. */
+export function recordAbandoned(content, ticketIds) {
+    const ids = [...new Set([...abandonedTickets(readEnv(content)), ...ticketIds])].slice(-MAX_ABANDONED);
+    return mergeEnv(content, { [ABANDONED_TICKETS_KEY]: ids.join(',') });
+}

package/esm/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 {};