@agentic-kit/db-tools 0.11.5 → 0.12.0

package/esm/tools/templates.js

@@ -1,5 +1,6 @@
 import { filterInternalPolicies } from '@agentic-kit/harness';
 import { z } from 'zod';
+import { buildBlueprint } from '../blueprint-construction';
 import { resolveProjectContext } from '../context';
 // A stored blueprint field's `type` is an expanded object (`{ name: 'text' }`),
 // not the bare string the agent passes to provision_blueprint. Flatten it to the
@@ -252,21 +253,8 @@ export const applyTemplateTool = {
             const blueprintId = copyResult.copyTemplateToBlueprint?.result;
             if (!blueprintId)
                 throw new Error('Failed to copy template');
-            const constructResult = await modules.mutation
-                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
-                .unwrap();
-            const constructionId = constructResult.constructBlueprint?.result;
-            if (!constructionId)
-                throw new Error('constructBlueprint returned no construction id');
-            const constructions = await modules.blueprintConstruction
-                .findMany({
-                where: { id: { equalTo: constructionId } },
-                first: 1,
-                select: { tableMap: true },
-            })
-                .unwrap();
-            const tableMap = (constructions?.blueprintConstructions?.nodes?.[0]?.tableMap ?? {});
-            const createdCount = Object.keys(tableMap).length;
+            const { tables } = await buildBlueprint(modules, { blueprintId, schemaId }, { signal: ctx.signal });
+            const createdCount = Object.keys(tables).length;
             return done(true, `Applied template "${params.templateName}" — created ${createdCount} table${createdCount === 1 ? '' : 's'}`);
         }
         catch (err) {

package/graphql-http.d.ts

@@ -0,0 +1,35 @@
+import { type GraphQLAdapter, type GraphQLError } from '@constructive-io/graphql-query/runtime';
+export type { GraphQLError };
+export type HttpGraphQLResponse<T> = {
+    /** The response status, or null when no response arrived. */
+    httpStatus: number | null;
+    data: T | null;
+    /**
+     * Body errors, each with `extensions.httpStatus` added. A non-2xx without
+     * body errors becomes one `{ code: 'HTTP_ERROR', httpStatus }` error, and a
+     * fetch that threw becomes one `{ code: 'NETWORK' }` error.
+     */
+    errors: GraphQLError[];
+};
+export type PostGraphQLArgs = {
+    endpoint: string;
+    headers?: Record<string, string>;
+    query: string;
+    variables?: Record<string, unknown>;
+    fetchFn?: typeof fetch;
+};
+export declare function postGraphQL<T>(args: PostGraphQLArgs): Promise<HttpGraphQLResponse<T>>;
+/**
+ * An ORM adapter over `postGraphQL`: the SDK clients take it in place of their
+ * FetchAdapter, and their failures then carry the status and code.
+ */
+export declare function statusAdapter(endpoint: string, headers?: Record<string, string>, fetchFn?: typeof fetch): GraphQLAdapter;
+export type BackendErrorKind = 'suspended' | 'auth' | 'forbidden' | 'server' | 'network' | 'graphql';
+/**
+ * What a failed backend answer says, first match wins: the database is
+ * suspended or gone (`ACCESS_SUSPENDED`), no response, the backend failing
+ * (5xx, 429), a rejected credential (401), a refusal (403), or anything else.
+ */
+export declare function classifyBackendErrors(errors: readonly GraphQLError[]): BackendErrorKind;
+/** The messages of a failed answer, joined for a reason string. */
+export declare function errorsText(errors: readonly GraphQLError[]): string;

package/graphql-http.js

@@ -0,0 +1,140 @@
+"use strict";
+// A GraphQL POST that keeps what the SDK's FetchAdapter throws away. That
+// adapter turns any non-2xx into `HTTP 403: Forbidden` and drops the body, so
+// a tenant API's `ACCESS_SUSPENDED` (a 403 with a JSON body, sent for a
+// deleted or suspended database) reads the same as any other refusal. Here
+// the body's errors keep their `extensions.code`, and every error carries the
+// HTTP status it arrived with.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.postGraphQL = postGraphQL;
+exports.statusAdapter = statusAdapter;
+exports.classifyBackendErrors = classifyBackendErrors;
+exports.errorsText = errorsText;
+const runtime_1 = require("@constructive-io/graphql-query/runtime");
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
+async function postGraphQL(args) {
+    const fetchFn = (args.fetchFn ?? (0, runtime_1.createFetch)()).bind(globalThis);
+    let response;
+    try {
+        response = await fetchFn(args.endpoint, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'application/json',
+                Accept: 'application/json',
+                ...args.headers,
+            },
+            body: JSON.stringify({ query: args.query, variables: args.variables ?? {} }),
+        });
+    }
+    catch (err) {
+        const cause = err?.cause?.code;
+        return {
+            httpStatus: null,
+            data: null,
+            errors: [
+                {
+                    message: typeof cause === 'string' ? `${errorText(err)} (${cause})` : errorText(err),
+                    extensions: { code: 'NETWORK' },
+                },
+            ],
+        };
+    }
+    const httpStatus = response.status;
+    let body = null;
+    try {
+        body = (await response.json());
+    }
+    catch {
+        body = null;
+    }
+    const bodyErrors = Array.isArray(body?.errors) ? body.errors : [];
+    if (bodyErrors.length > 0) {
+        return {
+            httpStatus,
+            data: body?.data ?? null,
+            errors: bodyErrors.map((error) => ({
+                ...error,
+                message: error?.message ?? '',
+                extensions: { ...error?.extensions, httpStatus },
+            })),
+        };
+    }
+    if (!response.ok || !body) {
+        const text = response.statusText ? `: ${response.statusText}` : '';
+        return {
+            httpStatus,
+            data: null,
+            errors: [
+                {
+                    message: response.ok ? `HTTP ${httpStatus}${text} (the body was not JSON)` : `HTTP ${httpStatus}${text}`,
+                    extensions: { code: 'HTTP_ERROR', httpStatus },
+                },
+            ],
+        };
+    }
+    return { httpStatus, data: body.data ?? null, errors: [] };
+}
+/**
+ * An ORM adapter over `postGraphQL`: the SDK clients take it in place of their
+ * FetchAdapter, and their failures then carry the status and code.
+ */
+function statusAdapter(endpoint, headers, fetchFn) {
+    let current = { ...headers };
+    return {
+        async execute(document, variables) {
+            const result = await postGraphQL({ endpoint, headers: current, query: document, variables, fetchFn });
+            return result.errors.length > 0
+                ? { ok: false, data: null, errors: result.errors }
+                : { ok: true, data: result.data, errors: undefined };
+        },
+        setHeaders(next) {
+            current = { ...current, ...next };
+        },
+        getEndpoint: () => endpoint,
+    };
+}
+const codeOf = (error) => {
+    const code = error?.extensions?.code;
+    return typeof code === 'string' ? code : undefined;
+};
+// The status an error arrived with: ours from extensions, or the SDK
+// adapter's `HTTP 503: …` message.
+const statusOf = (error) => {
+    const status = error?.extensions?.httpStatus;
+    if (typeof status === 'number')
+        return status;
+    const match = /^HTTP (\d{3})\b/.exec(error?.message ?? '');
+    return match ? Number(match[1]) : undefined;
+};
+const AUTH_MESSAGE_RE = /jwt|unauthenticated|invalid token/i;
+const FORBIDDEN_MESSAGE_RE = /permission denied/i;
+/**
+ * What a failed backend answer says, first match wins: the database is
+ * suspended or gone (`ACCESS_SUSPENDED`), no response, the backend failing
+ * (5xx, 429), a rejected credential (401), a refusal (403), or anything else.
+ */
+function classifyBackendErrors(errors) {
+    const list = errors ?? [];
+    const some = (test) => list.some((error) => test(error));
+    if (some((e) => codeOf(e) === 'ACCESS_SUSPENDED'))
+        return 'suspended';
+    if (some((e) => codeOf(e) === 'NETWORK'))
+        return 'network';
+    if (some((e) => {
+        const status = statusOf(e);
+        return status !== undefined && (status >= 500 || status === 429);
+    })) {
+        return 'server';
+    }
+    if (some((e) => statusOf(e) === 401 || codeOf(e) === 'UNAUTHENTICATED' || AUTH_MESSAGE_RE.test(e?.message ?? ''))) {
+        return 'auth';
+    }
+    if (some((e) => statusOf(e) === 403 || codeOf(e) === 'FORBIDDEN' || FORBIDDEN_MESSAGE_RE.test(e?.message ?? ''))) {
+        return 'forbidden';
+    }
+    return 'graphql';
+}
+/** The messages of a failed answer, joined for a reason string. */
+function errorsText(errors) {
+    return (errors ?? []).map((error) => error?.message || codeOf(error) || 'unknown error').join('; ');
+}

package/host.d.ts

@@ -74,6 +74,23 @@ export type StepUpRequest = {
     databaseName: string;
     apiEndpoint: string;
 };
+/**
+ * The database a project is bound to, handed to the host before provisioning
+ * writes it to the project's `.env`, so a host that keeps its own record of
+ * the binding never ends up with a `.env` it doesn't know about.
+ */
+export type ProjectBinding = {
+    cwd: string;
+    databaseId: string;
+    databaseName: string;
+    ownerId: string;
+    apiEndpoint: string;
+    modulesEndpoint: string;
+    /** The database this binding replaced (replace mode). */
+    replaces?: string;
+    /** True when the existing binding was kept: nothing was provisioned. */
+    skipped?: boolean;
+};
 export interface ToolsHost {
     /** Signed-in platform account, or null/undefined when signed out. */
     account(): HostAccount | null | undefined;
@@ -91,6 +108,13 @@ export interface ToolsHost {
     previewToken?(): Promise<PreviewToken | null>;
     /** Treat tokens expiring within this window as already expired. Default 30s. */
     dataTokenSkewMs?: number;
+    /**
+     * How long provision_database waits for a provision ticket to complete.
+     * Default 240s, which keeps an agent tool call under a 5-minute tool
+     * timeout; a host that calls the tool outside such a timeout (e.g. a
+     * pipeline) can wait longer for a cold provision on a loaded backend.
+     */
+    provisionPollDeadlineMs?: number;
     /**
      * Optional provision overlay: pick a base preset and/or layer module
      * add/remove on top of it. The base module list always comes from the pinned
@@ -109,7 +133,29 @@ export interface ToolsHost {
      * Required for create_api_key — without it the tool refuses to mint.
      */
     deliverSecret?(delivery: SecretDelivery): Promise<void>;
+    /**
+     * What to tell the agent to do about a database that is gone or belongs to
+     * another account, in place of the default advice to call
+     * provision_database with `reprovision: true`.
+     */
+    reprovisionHint?: string;
+    /**
+     * Whether the agent may replace a binding through provision_database's
+     * `reprovision: true`. Default true. A host that replaces databases only
+     * after the user approves (calling `provisionDatabase` in replace mode
+     * itself) sets false, and the tool then refuses.
+     */
+    toolReprovision?: boolean;
+    /**
+     * Save a binding in the host's own store. Provisioning calls it before
+     * writing `.env`, on a new binding and on a kept one (`skipped`). If it
+     * throws, `.env` is left alone, the provision ticket stays recorded, and
+     * the call fails with `binding-not-saved`.
+     */
+    persistBinding?(binding: ProjectBinding): Promise<void>;
 }
 export declare const DEFAULT_DATA_TOKEN_SKEW_MS = 30000;
+/** The advice for a database that is gone or under another account. */
+export declare function reprovisionAdvice(host: ToolsHost): string;
 export declare function configureHost(host: ToolsHost): void;
 export declare function getHost(): ToolsHost;

package/host.js

@@ -13,9 +13,19 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_DATA_TOKEN_SKEW_MS = void 0;
+exports.reprovisionAdvice = reprovisionAdvice;
 exports.configureHost = configureHost;
 exports.getHost = getHost;
 exports.DEFAULT_DATA_TOKEN_SKEW_MS = 30_000;
+const DEFAULT_REPROVISION_ADVICE = 'Re-provision with provision_database (reprovision: true): the schema is rebuilt from the project, and records do not carry over.';
+/** The advice for a database that is gone or under another account. */
+function reprovisionAdvice(host) {
+    if (host.reprovisionHint)
+        return host.reprovisionHint;
+    if (host.toolReprovision === false)
+        return 'Ask the user to re-provision it from the app.';
+    return DEFAULT_REPROVISION_ADVICE;
+}
 let currentHost = null;
 function configureHost(host) {
     currentHost = host;

package/index.d.ts

@@ -10,12 +10,21 @@ import { type ToolsHost } from './host';
 export declare const constructiveDbTools: readonly AnyHarnessTool[];
 /** Configure the host and get the tools in one call. */
 export declare function createConstructiveDbTools(host: ToolsHost): readonly AnyHarnessTool[];
-export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, type ContextEnvKey, type ContextSource, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, type ModulesClient, type ProjectContext, type ProjectContextFailureCode, resolveDataToken, resolveProjectContext, } from './context';
+export { BlueprintBuildError, buildBlueprint, CONSTRUCTION_DEADLINE_MS, type ConstructionTableMap, readConstructionFailure, waitForConstruction, type WaitForConstructionOptions, } from './blueprint-construction';
+export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, type ContextEnvKey, type ContextSource, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, type ModulesClient, type ProjectContext, type ProjectContextFailureCode, resolveDataToken, resolveProjectContext, type ResolveResult, } from './context';
+export { type DatabaseProbe, probeBoundDatabase, probeDatabase, type UnreachableCause, } from './db-probe';
 export { constructiveGateDeps, type ConstructiveGateResolvers } from './gate';
-export { type ActiveDataToken, configureHost, type DataAuthBroker, DEFAULT_DATA_TOKEN_SKEW_MS, getHost, type HostAccount, type HostBackendConfig, type HostProvisionOverlay, type PreviewToken, type SecretDelivery, type StepUpRequest, type ToolsHost, } from './host';
+export { type BackendErrorKind, classifyBackendErrors, type HttpGraphQLResponse, postGraphQL, statusAdapter, } from './graphql-http';
+export { type ActiveDataToken, configureHost, type DataAuthBroker, DEFAULT_DATA_TOKEN_SKEW_MS, getHost, type HostAccount, type HostBackendConfig, type HostProvisionOverlay, type PreviewToken, type ProjectBinding, type SecretDelivery, type StepUpRequest, type ToolsHost, } from './host';
+export { archiveBindingKeys, ARCHIVED_BINDING_KEYS, type EnvVars, mergeEnv, provisionEnvVars, readEnv, } from './provision-database/env-file';
 export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, type ProvisionManifest, } from './provision-database/manifest';
 export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, type ModulePreset, type ProvisionModule, } from './provision-database/presets';
+export { provisionDatabase, type ProvisionDatabaseDetails, type ProvisionFailureCode, type ProvisionInput, } from './provision-database/provision';
 export { moduleKey, type ProvisionOverlay, resolveProvisionModules, } from './provision-database/resolve';
+export { accessOf, type ColumnDefault, type FkAction, type ModelColumn, type ModelForeignKey, type ModelPolicy, type ModelTable, type ObjectCategory, readSchemaModel, type SchemaModel, SchemaReadError, type TableAccess, } from './schema-model';
 export { toolSchema } from './tool-schema';
+export { type AddRecordsDetails } from './tools/add-records';
+export { type CreateApiKeyDetails } from './tools/create-api-key';
+export { type RunCodegenDetails, type RunCodegenTimings } from './tools/run-codegen';
 export { createTemplatePreviewTables } from './tools/templates';
 export default constructiveDbTools;

package/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.createTemplatePreviewTables = exports.toolSchema = exports.resolveProvisionModules = exports.moduleKey = exports.getModulePreset = exports.DEFAULT_PROVISION_PRESET = exports.allModulePresets = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.loadProvisionManifest = exports.getHost = exports.DEFAULT_DATA_TOKEN_SKEW_MS = exports.configureHost = exports.constructiveGateDeps = exports.resolveProjectContext = exports.resolveDataToken = exports.fromEnvironment = exports.fromEnvFile = exports.deriveSubdomainEndpoint = exports.CONTEXT_ENV_PREFIX = exports.CONTEXT_ENV_KEYS = exports.constructiveDbTools = void 0;
+exports.createTemplatePreviewTables = exports.toolSchema = exports.SchemaReadError = exports.readSchemaModel = exports.accessOf = exports.resolveProvisionModules = exports.moduleKey = exports.provisionDatabase = exports.getModulePreset = exports.DEFAULT_PROVISION_PRESET = exports.allModulePresets = exports.PROVISION_MANIFEST_FILE = exports.parseProvisionManifest = exports.loadProvisionManifest = exports.readEnv = exports.provisionEnvVars = exports.mergeEnv = exports.ARCHIVED_BINDING_KEYS = exports.archiveBindingKeys = exports.getHost = exports.DEFAULT_DATA_TOKEN_SKEW_MS = exports.configureHost = exports.statusAdapter = exports.postGraphQL = exports.classifyBackendErrors = exports.constructiveGateDeps = exports.probeDatabase = exports.probeBoundDatabase = exports.resolveProjectContext = exports.resolveDataToken = exports.fromEnvironment = exports.fromEnvFile = exports.deriveSubdomainEndpoint = exports.CONTEXT_ENV_PREFIX = exports.CONTEXT_ENV_KEYS = exports.waitForConstruction = exports.readConstructionFailure = exports.CONSTRUCTION_DEADLINE_MS = exports.buildBlueprint = exports.BlueprintBuildError = exports.constructiveDbTools = void 0;
 exports.createConstructiveDbTools = createConstructiveDbTools;
 const host_1 = require("./host");
 const add_policies_1 = require("./tools/add-policies");
@@ -46,6 +46,12 @@ function createConstructiveDbTools(host) {
     (0, host_1.configureHost)(host);
     return exports.constructiveDbTools;
 }
+var blueprint_construction_1 = require("./blueprint-construction");
+Object.defineProperty(exports, "BlueprintBuildError", { enumerable: true, get: function () { return blueprint_construction_1.BlueprintBuildError; } });
+Object.defineProperty(exports, "buildBlueprint", { enumerable: true, get: function () { return blueprint_construction_1.buildBlueprint; } });
+Object.defineProperty(exports, "CONSTRUCTION_DEADLINE_MS", { enumerable: true, get: function () { return blueprint_construction_1.CONSTRUCTION_DEADLINE_MS; } });
+Object.defineProperty(exports, "readConstructionFailure", { enumerable: true, get: function () { return blueprint_construction_1.readConstructionFailure; } });
+Object.defineProperty(exports, "waitForConstruction", { enumerable: true, get: function () { return blueprint_construction_1.waitForConstruction; } });
 var context_1 = require("./context");
 Object.defineProperty(exports, "CONTEXT_ENV_KEYS", { enumerable: true, get: function () { return context_1.CONTEXT_ENV_KEYS; } });
 Object.defineProperty(exports, "CONTEXT_ENV_PREFIX", { enumerable: true, get: function () { return context_1.CONTEXT_ENV_PREFIX; } });
@@ -54,12 +60,25 @@ Object.defineProperty(exports, "fromEnvFile", { enumerable: true, get: function
 Object.defineProperty(exports, "fromEnvironment", { enumerable: true, get: function () { return context_1.fromEnvironment; } });
 Object.defineProperty(exports, "resolveDataToken", { enumerable: true, get: function () { return context_1.resolveDataToken; } });
 Object.defineProperty(exports, "resolveProjectContext", { enumerable: true, get: function () { return context_1.resolveProjectContext; } });
+var db_probe_1 = require("./db-probe");
+Object.defineProperty(exports, "probeBoundDatabase", { enumerable: true, get: function () { return db_probe_1.probeBoundDatabase; } });
+Object.defineProperty(exports, "probeDatabase", { enumerable: true, get: function () { return db_probe_1.probeDatabase; } });
 var gate_1 = require("./gate");
 Object.defineProperty(exports, "constructiveGateDeps", { enumerable: true, get: function () { return gate_1.constructiveGateDeps; } });
+var graphql_http_1 = require("./graphql-http");
+Object.defineProperty(exports, "classifyBackendErrors", { enumerable: true, get: function () { return graphql_http_1.classifyBackendErrors; } });
+Object.defineProperty(exports, "postGraphQL", { enumerable: true, get: function () { return graphql_http_1.postGraphQL; } });
+Object.defineProperty(exports, "statusAdapter", { enumerable: true, get: function () { return graphql_http_1.statusAdapter; } });
 var host_2 = require("./host");
 Object.defineProperty(exports, "configureHost", { enumerable: true, get: function () { return host_2.configureHost; } });
 Object.defineProperty(exports, "DEFAULT_DATA_TOKEN_SKEW_MS", { enumerable: true, get: function () { return host_2.DEFAULT_DATA_TOKEN_SKEW_MS; } });
 Object.defineProperty(exports, "getHost", { enumerable: true, get: function () { return host_2.getHost; } });
+var env_file_1 = require("./provision-database/env-file");
+Object.defineProperty(exports, "archiveBindingKeys", { enumerable: true, get: function () { return env_file_1.archiveBindingKeys; } });
+Object.defineProperty(exports, "ARCHIVED_BINDING_KEYS", { enumerable: true, get: function () { return env_file_1.ARCHIVED_BINDING_KEYS; } });
+Object.defineProperty(exports, "mergeEnv", { enumerable: true, get: function () { return env_file_1.mergeEnv; } });
+Object.defineProperty(exports, "provisionEnvVars", { enumerable: true, get: function () { return env_file_1.provisionEnvVars; } });
+Object.defineProperty(exports, "readEnv", { enumerable: true, get: function () { return env_file_1.readEnv; } });
 var manifest_1 = require("./provision-database/manifest");
 Object.defineProperty(exports, "loadProvisionManifest", { enumerable: true, get: function () { return manifest_1.loadProvisionManifest; } });
 Object.defineProperty(exports, "parseProvisionManifest", { enumerable: true, get: function () { return manifest_1.parseProvisionManifest; } });
@@ -68,9 +87,15 @@ var presets_1 = require("./provision-database/presets");
 Object.defineProperty(exports, "allModulePresets", { enumerable: true, get: function () { return presets_1.allModulePresets; } });
 Object.defineProperty(exports, "DEFAULT_PROVISION_PRESET", { enumerable: true, get: function () { return presets_1.DEFAULT_PROVISION_PRESET; } });
 Object.defineProperty(exports, "getModulePreset", { enumerable: true, get: function () { return presets_1.getModulePreset; } });
+var provision_1 = require("./provision-database/provision");
+Object.defineProperty(exports, "provisionDatabase", { enumerable: true, get: function () { return provision_1.provisionDatabase; } });
 var resolve_1 = require("./provision-database/resolve");
 Object.defineProperty(exports, "moduleKey", { enumerable: true, get: function () { return resolve_1.moduleKey; } });
 Object.defineProperty(exports, "resolveProvisionModules", { enumerable: true, get: function () { return resolve_1.resolveProvisionModules; } });
+var schema_model_1 = require("./schema-model");
+Object.defineProperty(exports, "accessOf", { enumerable: true, get: function () { return schema_model_1.accessOf; } });
+Object.defineProperty(exports, "readSchemaModel", { enumerable: true, get: function () { return schema_model_1.readSchemaModel; } });
+Object.defineProperty(exports, "SchemaReadError", { enumerable: true, get: function () { return schema_model_1.SchemaReadError; } });
 var tool_schema_1 = require("./tool-schema");
 Object.defineProperty(exports, "toolSchema", { enumerable: true, get: function () { return tool_schema_1.toolSchema; } });
 var templates_2 = require("./tools/templates");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentic-kit/db-tools",
-  "version": "0.11.5",
+  "version": "0.12.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "harness-neutral Constructive database tools — provisioning, schema, policies, records, templates and codegen as HarnessTools any adapter can bind",
   "main": "index.js",
@@ -31,8 +31,8 @@
   "dependencies": {
     "12factor-env": "^1.34.0",
     "@agentic-kit/harness": "^0.18.0",
-    "@constructive-io/graphql-query": "^4.22.5",
-    "@constructive-io/sdk": "^1.21.5",
+    "@constructive-io/graphql-query": "^4.22.6",
+    "@constructive-io/sdk": "^1.21.6",
     "node-type-registry": "^1.22.0",
     "zod": "^4.4.3"
   },
@@ -45,5 +45,5 @@
     "database",
     "constructive"
   ],
-  "gitHead": "3e55ca27382b58c3cab2b32e86d1690d0cdae8ce"
+  "gitHead": "124df300f0afc15653854b50a25ac738c70261b7"
 }

package/provision-database/env-file.d.ts

@@ -1,10 +1,31 @@
 export type EnvVars = Record<string, string>;
+/** Parse .env text: quoted values, `export` prefixes and comments; last definition wins. */
+export declare function readEnv(content: string): EnvVars;
 /**
- * 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 declare function mergeEnv(content: string, vars: EnvVars): string;
+/**
+ * Drop every definition of `keys`. Comments and other entries pass through,
+ * and content without those keys comes back unchanged.
+ */
+export declare function removeEnvKeys(content: string, keys: readonly string[]): string;
+/**
+ * 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 declare const PENDING_PROVISION_KEYS: {
+    readonly ticketId: "PROVISION_TICKET_ID";
+    readonly databaseName: "PROVISION_TICKET_DATABASE_NAME";
+    readonly apiEndpoint: "PROVISION_TICKET_API_ENDPOINT";
+    readonly userId: "PROVISION_TICKET_USER_ID";
+    readonly attempts: "PROVISION_TICKET_ATTEMPTS";
+};
 /** The credential keys provision_database owns in a project's .env. */
 export declare const PROVISION_ENV_KEYS: readonly ["DATABASE_ID", "DATABASE_NAME", "OWNER_ID", "ACCESS_TOKEN", "PGDATABASE", "API_ENDPOINT", "MODULES_ENDPOINT"];
 /**

package/provision-database/env-file.js

@@ -1,32 +1,100 @@
 "use strict";
-// 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.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ARCHIVED_BINDING_KEYS = exports.PROVISION_ENV_KEYS = void 0;
+exports.ARCHIVED_BINDING_KEYS = exports.PROVISION_ENV_KEYS = exports.PENDING_PROVISION_KEYS = void 0;
+exports.readEnv = readEnv;
 exports.mergeEnv = mergeEnv;
+exports.removeEnvKeys = removeEnvKeys;
 exports.provisionEnvVars = provisionEnvVars;
 exports.archiveBindingKeys = archiveBindingKeys;
+const dotenv_1 = require("12factor-env/dotenv");
+/** Parse .env text: quoted values, `export` prefixes and comments; last definition wins. */
+function readEnv(content) {
+    return (0, dotenv_1.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.
  */
 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.
+ */
+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.
+ */
+exports.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. */
 exports.PROVISION_ENV_KEYS = [
     'DATABASE_ID',
@@ -76,16 +144,9 @@ function provisionEnvVars(args) {
  */
 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/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;