@agentic-kit/db-tools 0.2.0

package/tools/mutations.js

@@ -0,0 +1,233 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.deleteFieldTool = exports.updateFieldTool = exports.createFieldTool = exports.deleteTableTool = void 0;
+const harness_1 = require("@agentic-kit/harness");
+const zod_1 = require("zod");
+const context_1 = require("../context");
+const schema_resolve_1 = require("../schema-resolve");
+function ok(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: true, message },
+    };
+}
+function fail(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message },
+    };
+}
+// ── delete_table ──────────────────────────────────────────────────────────
+const DeleteTableZod = zod_1.z.object({
+    table_name: zod_1.z.string().describe('Name of the table to delete (snake_case)'),
+});
+exports.deleteTableTool = {
+    name: 'delete_table',
+    label: 'Delete table',
+    description: 'Permanently delete a table and its data from the project database.',
+    promptSnippet: 'delete_table: drop an existing table by name. Destructive — gated.',
+    parameters: DeleteTableZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        try {
+            const schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            const table = (0, schema_resolve_1.resolveTable)(schema, params.table_name);
+            await resolved.context.api.table
+                .delete({ where: { id: table.id }, select: { id: true } })
+                .unwrap();
+            return ok(`Deleted table ${params.table_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to delete table');
+        }
+    },
+};
+// ── create_field ──────────────────────────────────────────────────────────
+const CreateFieldZod = zod_1.z.object({
+    table_name: zod_1.z.string().describe('Name of the table to add the field to'),
+    field_name: zod_1.z.string().describe('Field name in snake_case'),
+    type: zod_1.z
+        .string()
+        .describe('PostgreSQL type: text, integer, smallint, numeric, boolean, date, timestamp, timestamptz, time, json, jsonb, inet, email, url, image, upload'),
+    is_required: zod_1.z.boolean().describe('Whether the field is NOT NULL. Defaults to false.').optional(),
+    default_value: zod_1.z
+        .union([zod_1.z.string(), zod_1.z.null()])
+        .describe('SQL default expression, e.g. "now()", "\'draft\'"')
+        .optional(),
+    is_unique: zod_1.z
+        .boolean()
+        .describe('Whether the field has a unique constraint. Defaults to false.')
+        .optional(),
+});
+exports.createFieldTool = {
+    name: 'create_field',
+    label: 'Create field',
+    description: 'Add a new field (column) to an existing table in the project database.',
+    promptSnippet: 'create_field: add a column to an existing table. Gated.',
+    parameters: CreateFieldZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { api, databaseId } = resolved.context;
+        try {
+            const schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            const table = (0, schema_resolve_1.resolveTable)(schema, params.table_name);
+            const result = await api.field
+                .create({
+                data: {
+                    name: params.field_name,
+                    type: (0, harness_1.toFieldType)(params.type),
+                    tableId: table.id,
+                    databaseId,
+                    isRequired: params.is_required ?? false,
+                    defaultValue: (0, harness_1.toFieldDefault)(params.default_value),
+                },
+                select: { id: true, name: true, type: true },
+            })
+                .unwrap();
+            const createdId = result.createField?.field?.id;
+            if (params.is_unique && createdId) {
+                try {
+                    await api.uniqueConstraint
+                        .create({
+                        data: {
+                            tableId: table.id,
+                            databaseId,
+                            fieldIds: [createdId],
+                            name: `${table.name}_${params.field_name}_key`,
+                            type: 'u',
+                        },
+                        select: { id: true },
+                    })
+                        .unwrap();
+                }
+                catch (err) {
+                    console.warn('Failed to create unique constraint:', err);
+                }
+            }
+            return ok(`Added field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to create field');
+        }
+    },
+};
+// ── update_field ──────────────────────────────────────────────────────────
+const UpdateFieldZod = zod_1.z.object({
+    table_name: zod_1.z.string().describe('Name of the table containing the field'),
+    field_name: zod_1.z.string().describe('Current field name'),
+    new_name: zod_1.z.string().describe('New field name in snake_case (if renaming)').optional(),
+    new_type: zod_1.z.string().describe('New PostgreSQL type (if changing type)').optional(),
+    is_required: zod_1.z.boolean().describe('Set NOT NULL constraint').optional(),
+    default_value: zod_1.z
+        .union([zod_1.z.string(), zod_1.z.null()])
+        .describe('New SQL default expression, or null to remove')
+        .optional(),
+    is_unique: zod_1.z.boolean().describe('Set or remove unique constraint').optional(),
+});
+exports.updateFieldTool = {
+    name: 'update_field',
+    label: 'Update field',
+    description: 'Modify an existing field: rename, change type, toggle required/unique, or set default.',
+    promptSnippet: 'update_field: rename/retype/toggle an existing column. Gated.',
+    parameters: UpdateFieldZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { api, databaseId } = resolved.context;
+        try {
+            const schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            const table = (0, schema_resolve_1.resolveTable)(schema, params.table_name);
+            const field = (0, schema_resolve_1.resolveField)(table, params.field_name);
+            const patch = {};
+            if (params.new_name)
+                patch.name = params.new_name;
+            if (params.new_type)
+                patch.type = (0, harness_1.toFieldType)(params.new_type);
+            if (params.is_required !== undefined)
+                patch.isRequired = params.is_required;
+            if (params.default_value !== undefined) {
+                patch.defaultValue =
+                    params.default_value === null ? null : ((0, harness_1.toFieldDefault)(params.default_value) ?? null);
+            }
+            if (Object.keys(patch).length > 0) {
+                await api.field
+                    .update({
+                    where: { id: field.id },
+                    data: patch,
+                    select: { id: true, name: true, type: true },
+                })
+                    .unwrap();
+            }
+            if (params.is_unique !== undefined) {
+                const existingUniqueId = (0, schema_resolve_1.findUniqueConstraintId)(table, field.id);
+                if (params.is_unique && !existingUniqueId) {
+                    try {
+                        await api.uniqueConstraint
+                            .create({
+                            data: {
+                                tableId: table.id,
+                                databaseId,
+                                fieldIds: [field.id],
+                                name: `${table.name}_${params.new_name ?? field.name}_key`,
+                                type: 'u',
+                            },
+                            select: { id: true },
+                        })
+                            .unwrap();
+                    }
+                    catch (err) {
+                        console.warn('Failed to create unique constraint:', err);
+                    }
+                }
+                else if (!params.is_unique && existingUniqueId) {
+                    try {
+                        await api.uniqueConstraint
+                            .delete({ where: { id: existingUniqueId }, select: { id: true } })
+                            .unwrap();
+                    }
+                    catch (err) {
+                        console.warn('Failed to delete unique constraint:', err);
+                    }
+                }
+            }
+            return ok(`Updated field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to update field');
+        }
+    },
+};
+// ── delete_field ──────────────────────────────────────────────────────────
+const DeleteFieldZod = zod_1.z.object({
+    table_name: zod_1.z.string().describe('Name of the table containing the field'),
+    field_name: zod_1.z.string().describe('Name of the field to delete'),
+});
+exports.deleteFieldTool = {
+    name: 'delete_field',
+    label: 'Delete field',
+    description: 'Permanently delete a field (column) from an existing table.',
+    promptSnippet: 'delete_field: drop a column from a table by name. Destructive — gated.',
+    parameters: DeleteFieldZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        try {
+            const schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            const table = (0, schema_resolve_1.resolveTable)(schema, params.table_name);
+            const field = (0, schema_resolve_1.resolveField)(table, params.field_name);
+            await resolved.context.api.field
+                .delete({ where: { id: field.id }, select: { id: true } })
+                .unwrap();
+            return ok(`Deleted field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to delete field');
+        }
+    },
+};

package/tools/provision-blueprint.d.ts

@@ -0,0 +1,21 @@
+import { BlueprintZod, type HarnessTool } from '@agentic-kit/harness';
+type ProvisionedField = {
+    name: string;
+    type: string;
+    isRequired: boolean;
+    defaultValue: string | null;
+};
+type ProvisionedTable = {
+    name: string;
+    fields: ProvisionedField[];
+    policies: string[];
+    relationCount: number;
+};
+export type ProvisionBlueprintDetails = {
+    created: number;
+    total: number;
+    tables: ProvisionedTable[];
+    error: string | null;
+};
+export declare const provisionBlueprintTool: HarnessTool<typeof BlueprintZod, ProvisionBlueprintDetails>;
+export {};

package/tools/provision-blueprint.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provisionBlueprintTool = void 0;
+const harness_1 = require("@agentic-kit/harness");
+const context_1 = require("../context");
+function formatText(name, details) {
+    if (details.error)
+        return `Failed to provision "${name}": ${details.error}`;
+    const lines = [`Created ${details.created} table${details.created === 1 ? '' : 's'} from "${name}":`];
+    for (const table of details.tables) {
+        const parts = [`${table.fields.length} field${table.fields.length === 1 ? '' : 's'}`];
+        if (table.relationCount > 0) {
+            parts.push(`${table.relationCount} relation${table.relationCount === 1 ? '' : 's'}`);
+        }
+        if (table.policies.length > 0) {
+            parts.push(`policies: ${table.policies.map((policy) => policy.replace(/^Authz/, '')).join(', ')}`);
+        }
+        lines.push(`  - ${table.name} (${parts.join(', ')})`);
+    }
+    return lines.join('\n');
+}
+exports.provisionBlueprintTool = {
+    name: 'provision_blueprint',
+    label: 'Provision blueprint',
+    description: 'Create one or more related tables (with fields, RLS policies, and relations) in the project database from a blueprint definition. Always put related tables in a SINGLE call so relations are created together.',
+    promptSnippet: 'provision_blueprint: create new tables from scratch in a single call (fields + policies + relations). Call describe_schema first.',
+    parameters: harness_1.BlueprintZod,
+    async execute(params, ctx) {
+        const empty = { created: 0, total: 0, tables: [], error: null };
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context) {
+            return { content: [{ type: 'text', text: resolved.reason }], details: empty };
+        }
+        const { modules, databaseId, schemaId, ownerId } = resolved.context;
+        if (!ownerId) {
+            return {
+                content: [{ type: 'text', text: 'Not authenticated (missing OWNER_ID in .env).' }],
+                details: empty,
+            };
+        }
+        const definition = (0, harness_1.expandBlueprintDefaults)(params.definition);
+        const uniqueName = `${params.name}_${Date.now()}`;
+        try {
+            const createResult = await modules.blueprint
+                .create({
+                data: {
+                    ownerId,
+                    databaseId,
+                    name: uniqueName,
+                    displayName: params.name,
+                    description: params.description,
+                    definition,
+                },
+                select: { id: true, name: true },
+            })
+                .unwrap();
+            const blueprintId = createResult.createBlueprint?.blueprint?.id;
+            if (!blueprintId)
+                throw new Error('Failed to create blueprint');
+            const constructResult = await modules.mutation
+                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
+                .unwrap();
+            const result = constructResult.constructBlueprint?.result;
+            if (!result) {
+                const constructions = await modules.blueprintConstruction
+                    .findMany({
+                    where: { blueprintId: { equalTo: blueprintId } },
+                    orderBy: ['ID_DESC'],
+                    first: 1,
+                    select: { status: true, errorDetails: true },
+                })
+                    .unwrap();
+                const error = constructions?.blueprintConstructions?.nodes?.[0]?.errorDetails ?? 'Unknown error';
+                const details = {
+                    created: 0,
+                    total: params.definition.tables.length,
+                    tables: [],
+                    error: typeof error === 'string' ? error : JSON.stringify(error),
+                };
+                return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+            }
+            const relations = params.definition.relations ?? [];
+            const details = {
+                created: params.definition.tables.length,
+                total: params.definition.tables.length,
+                tables: params.definition.tables.map((t) => ({
+                    name: t.table_name,
+                    fields: (t.fields ?? []).map((f) => ({
+                        name: f.name,
+                        type: f.type,
+                        isRequired: f.is_required ?? false,
+                        defaultValue: f.default ?? null,
+                    })),
+                    policies: (0, harness_1.filterInternalPolicies)(t.policies.map((p) => p.$type)),
+                    relationCount: relations.filter((r) => r.source_table === t.table_name).length,
+                })),
+                error: null,
+            };
+            return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to provision blueprint';
+            const details = {
+                created: 0,
+                total: params.definition.tables.length,
+                tables: [],
+                error: message,
+            };
+            return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+        }
+    },
+};

package/tools/provision-database.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+declare const ProvisionDatabaseZod: z.ZodObject<{
+    database_name: z.ZodString;
+    reprovision: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ProvisionDatabaseDetails = {
+    success: boolean;
+    message: string;
+    databaseId?: string;
+    databaseName?: string;
+    ownerId?: string;
+    fixupNote?: string;
+    /** True when an existing live binding was kept — nothing changed. */
+    skipped?: boolean;
+};
+export declare const provisionDatabaseTool: HarnessTool<typeof ProvisionDatabaseZod, ProvisionDatabaseDetails>;
+export {};

package/tools/provision-database.js

@@ -0,0 +1,266 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.provisionDatabaseTool = void 0;
+const promises_1 = require("node:fs/promises");
+const promises_2 = require("node:fs/promises");
+const node_path_1 = __importDefault(require("node:path"));
+const zod_1 = require("zod");
+const app_workspace_1 = require("../app-workspace");
+const db_probe_1 = require("../db-probe");
+const host_1 = require("../host");
+const credential_1 = require("../provision-database/credential");
+const env_file_1 = require("../provision-database/env-file");
+const manifest_1 = require("../provision-database/manifest");
+const pg_fixups_1 = require("../provision-database/pg-fixups");
+const preset_match_1 = require("../provision-database/preset-match");
+const request_database_1 = require("../provision-database/request-database");
+const resolve_1 = require("../provision-database/resolve");
+const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
+const DEFAULT_MODULES_ENDPOINT = 'http://modules.localhost:3000/graphql';
+// The per-DB endpoints are subdomain.<domain>; the provisioning domain is the api
+// endpoint's host minus its first label (api.localhost -> localhost,
+// api.launchql.dev -> launchql.dev), so dev and devnet both provision correctly.
+function provisionDomain(apiEndpoint) {
+    try {
+        const { hostname } = new URL(apiEndpoint);
+        // A bare IP host has no domain hierarchy to strip: dropping its first label
+        // ('192.168.1.10' -> '168.1.10') would yield a garbage domain. Use it verbatim.
+        if (hostname.includes(':') || /^\d{1,3}(\.\d{1,3}){3}$/.test(hostname))
+            return hostname;
+        const parts = hostname.split('.');
+        return parts.length > 1 ? parts.slice(1).join('.') : parts.join('.');
+    }
+    catch {
+        return 'localhost';
+    }
+}
+const ProvisionDatabaseZod = zod_1.z.object({
+    database_name: zod_1.z
+        .string()
+        .describe('Name for the app database (lowercase, alphanumeric + underscores). Doubles as the deterministic provisioning subdomain (api-<name>/auth-<name>/app-<name>.localhost), so keep it short and URL-safe.'),
+    reprovision: zod_1.z
+        .boolean()
+        .describe('Mint a fresh database even though the project already carries a binding — use when the bound database no longer exists on this backend (refreshed backend, deleted database), when it belongs to a different account than the one signed in, or when the user asks for a clean rebuild. The old .env keys are archived as comments and the old database is never deleted server-side. The schema must be rebuilt afterwards (provision_blueprint + run_codegen); records do not carry over.')
+        .optional(),
+});
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+// Minimal .env reader for the idempotency check (full parsing lives in context.ts).
+function parseEnvKeys(source) {
+    const env = {};
+    for (const rawLine of source.split('\n')) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith('#'))
+            continue;
+        const eq = line.indexOf('=');
+        if (eq === -1)
+            continue;
+        env[line.slice(0, eq).trim()] = line.slice(eq + 1).trim();
+    }
+    return env;
+}
+exports.provisionDatabaseTool = {
+    name: 'provision_database',
+    label: 'Provision database',
+    description: 'Bootstrap a new Constructive database for the project under your account: provision the standard module set, enable membership defaults, and write credentials (DATABASE_ID, ACCESS_TOKEN, etc.) to the project .env. Run this ONCE before any schema/record tools. If the project is already bound to a live database under the signed-in account it skips; if the bound database no longer exists on this backend (refreshed/deleted) or belongs to a different account, pass reprovision: true to mint a fresh one (old keys archived in .env, old database kept; rebuild the schema afterwards).',
+    promptSnippet: 'provision_database: one-time bootstrap of the project database (owner + modules + .env). Run before describe_schema/provision_blueprint. Skips when the existing binding is live under the signed-in account; reprovision: true replaces a dead or foreign-account binding (archives old keys, never deletes the old db). Gated.',
+    parameters: ProvisionDatabaseZod,
+    async execute(params, ctx) {
+        const databaseName = params.database_name.trim();
+        if (!databaseName)
+            return fail('database_name is required.');
+        const envPath = node_path_1.default.join(ctx.cwd, '.env');
+        let existing = '';
+        try {
+            existing = await (0, promises_2.readFile)(envPath, 'utf8');
+        }
+        catch {
+            /* no existing .env — fine */
+        }
+        // Unify endpoints onto the app's backend-config store (environment-aware:
+        // *.localhost:3000 in dev, *.launchql.dev packaged). A process.env override
+        // still wins for ad-hoc dev; the hardcoded default is a last resort if the
+        // store isn't ready.
+        const host = (0, host_1.getHost)();
+        const backend = host.backendConfig();
+        const apiEndpoint = process.env.API_ENDPOINT || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
+        const modulesEndpoint = process.env.MODULES_ENDPOINT || backend?.modulesEndpoint || DEFAULT_MODULES_ENDPOINT;
+        // Every new project provisions UNDER the account (requestDatabase owns the
+        // database to the JWT user), so it is account-owned and enumerable. The
+        // account bearer is the single credential: it authenticates the provision
+        // mutation, the idempotency
+        // probe below, and is the ACCESS_TOKEN written to .env for project-local
+        // scripts. It expires with the login session — a relogin plus any provision
+        // run (including the skip path) refreshes the .env copy. A signed-in session
+        // with no usable bearer errors out here rather than silently minting a
+        // throwaway owner. Gate BEFORE prewarm so an error return doesn't leak a
+        // detached background scaffold/install.
+        const credential = (0, credential_1.selectProvisionCredential)(host.account(), host.signInHint);
+        if (credential.mode === 'error') {
+            return fail(`Cannot provision a database: ${credential.reason}`);
+        }
+        const ownerId = credential.ownerId;
+        // Idempotency keyed on binding liveness AND ownership: a binding is done only
+        // when its database still answers and belongs to the signed-in account
+        // (schemas are account-scoped). A dead binding (backend refreshed, database
+        // deleted, key revoked) or a live one under another account points at the
+        // reprovision path; an unreachable backend is a retry, never a reprovision.
+        const existingEnv = parseEnvKeys(existing);
+        const hasBinding = Boolean(existingEnv.DATABASE_ID && existingEnv.ACCESS_TOKEN);
+        if (hasBinding && !params.reprovision) {
+            // The probe carries the account bearer, so it only ever targets the
+            // app-configured backend — never a .env-pinned endpoint, which an
+            // untrusted cloned project controls.
+            const probe = await (0, db_probe_1.probeDatabase)({
+                endpoint: apiEndpoint,
+                bearer: credential.bearer,
+                databaseId: existingEnv.DATABASE_ID,
+                signInHint: host.signInHint,
+            });
+            if (probe.outcome === 'unreachable') {
+                return fail(`Cannot verify the existing database binding: backend unreachable (${probe.detail}). Check the Constructive backend is running, then retry — do not reprovision on an unreachable backend.`);
+            }
+            if (probe.outcome === 'missing') {
+                return fail(`Project carries a binding (DATABASE_ID=${existingEnv.DATABASE_ID}) but that database no longer exists on this backend. Re-run with reprovision: true to mint a fresh database (old keys archived in .env, old database untouched), then rebuild the schema (provision_blueprint + run_codegen); records do not carry over.`);
+            }
+            const sessionUserId = host.account()?.userId;
+            if (probe.ownerId && sessionUserId && probe.ownerId !== sessionUserId) {
+                return fail(`Project carries a binding (DATABASE_ID=${existingEnv.DATABASE_ID}) but that database was provisioned under a different account than the one signed in. Re-run with reprovision: true to mint a fresh database under this account (old keys archived in .env, old database untouched), then rebuild the schema (provision_blueprint + run_codegen); records do not carry over.`);
+            }
+            // Heal .env on the skip path: a stale token (relogin) or missing/stale
+            // endpoint pins (project provisioned before pins existed, or backend
+            // config changed) refresh to the current session + backend.
+            const refresh = {};
+            if (existingEnv.ACCESS_TOKEN !== credential.bearer)
+                refresh.ACCESS_TOKEN = credential.bearer;
+            if (existingEnv.API_ENDPOINT !== apiEndpoint)
+                refresh.API_ENDPOINT = apiEndpoint;
+            if (existingEnv.MODULES_ENDPOINT !== modulesEndpoint) {
+                refresh.MODULES_ENDPOINT = modulesEndpoint;
+            }
+            let tokenNote = '';
+            if (Object.keys(refresh).length > 0) {
+                const keys = Object.keys(refresh).join(', ');
+                try {
+                    await (0, promises_1.writeFile)(envPath, (0, env_file_1.mergeEnv)(existing, refresh));
+                    tokenNote = ` Refreshed in .env from the signed-in session: ${keys}.`;
+                }
+                catch (err) {
+                    tokenNote = ` Could not refresh ${keys} in .env: ${err instanceof Error ? err.message : String(err)}.`;
+                }
+            }
+            const message = `Project already provisioned (DATABASE_ID=${existingEnv.DATABASE_ID}) and the database is live under this account. Skipping — pass reprovision: true only for an explicit clean rebuild.${tokenNote}`;
+            return {
+                content: [{ type: 'text', text: message }],
+                details: {
+                    success: true,
+                    message,
+                    databaseId: existingEnv.DATABASE_ID,
+                    databaseName: existingEnv.DATABASE_NAME,
+                    ownerId: existingEnv.OWNER_ID,
+                    skipped: true,
+                },
+            };
+        }
+        if (hasBinding && params.reprovision) {
+            existing = (0, env_file_1.archiveBindingKeys)(existing, env_file_1.ARCHIVED_BINDING_KEYS, new Date().toISOString().slice(0, 10));
+        }
+        // The packages/app scaffold + pnpm install are database-INDEPENDENT, so kick
+        // them off now to run concurrently with the provisioning request below
+        // (near-instant on a warm-pool hit, up to minutes on the cold path).
+        // This keeps clone + install off run_codegen's critical path. Best-effort:
+        // run_codegen re-runs the same idempotent steps, so a prewarm failure is
+        // harmless. Never let it reject (we await it before returning).
+        const prewarm = (0, app_workspace_1.prewarmAppWorkspace)(ctx.cwd).catch((err) => ({
+            ok: false,
+            out: err instanceof Error ? err.message : String(err),
+        }));
+        // Resolve the module set: pinned base preset from node-type-registry, then
+        // ordered overlays (host default < project-local provision.json). No list is
+        // hand-copied here; overlays are pure data. A bad preset/manifest fails the
+        // run rather than provisioning a wrong module set.
+        let modules;
+        try {
+            const layers = [];
+            const hostOverlay = await host.provisionOverlay?.();
+            if (hostOverlay)
+                layers.push(hostOverlay);
+            const projectOverlay = await (0, manifest_1.loadProvisionManifest)(ctx.cwd);
+            if (projectOverlay)
+                layers.push(projectOverlay);
+            modules = (0, resolve_1.resolveProvisionModules)(layers);
+        }
+        catch (err) {
+            return fail(`Cannot resolve provision modules: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const physicalDb = process.env.CONSTRUCTIVE_DB || 'constructive';
+        // Provision on the API endpoint: requestDatabase claims a warm-pool
+        // database when the resolved module set matches a cataloged preset
+        // (near-instant) and cold-provisions asynchronously otherwise; the ticket
+        // is polled on the modules endpoint until the database AND its deferred
+        // owner bootstrap complete. No retry wrapper: a pending ticket is the
+        // normal first response, and transient poll failures are absorbed inside
+        // the poll loop. The domain still derives from the api endpoint's host
+        // (per-DB endpoints live under it), and an explicit subdomain
+        // (= databaseName) keeps them deterministic (SUBDOMAIN-001).
+        let databaseId;
+        try {
+            ({ databaseId } = await (0, request_database_1.requestDatabaseProvision)({
+                apiEndpoint,
+                modulesEndpoint,
+                bearer: credential.bearer,
+                databaseName,
+                domain: provisionDomain(apiEndpoint),
+                request: (0, preset_match_1.selectProvisionRequest)(modules),
+            }));
+        }
+        catch (err) {
+            const detail = err instanceof Error ? err.message : String(err);
+            const nameTakenHint = /already exists|already taken|already in use|duplicate/i.test(detail)
+                ? ' The database name is already taken on the backend — re-run with a different database_name.'
+                : '';
+            return fail(`Database provisioning failed: ${detail}.${nameTakenHint}`);
+        }
+        // Enable membership defaults + naming settings at the SQL level. Best-effort:
+        // provisioning already succeeded, so a fixup failure is a warning, not an error.
+        const fixup = await (0, pg_fixups_1.applySqlFixups)({ databaseName, physicalDb });
+        // Persist the binding to the project .env (upsert, preserving other keys).
+        const merged = (0, env_file_1.mergeEnv)(existing, (0, env_file_1.provisionEnvVars)({
+            databaseId,
+            databaseName,
+            ownerId,
+            accessToken: credential.bearer,
+            apiEndpoint,
+            modulesEndpoint,
+        }));
+        try {
+            await (0, promises_1.writeFile)(envPath, merged);
+        }
+        catch (err) {
+            return fail(`Database provisioned (ID: ${databaseId}) but writing .env failed: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Settle the concurrent prewarm so the scaffold + install are in place before
+        // run_codegen runs. A failure here is non-fatal — run_codegen redoes the work.
+        const prewarmResult = await prewarm;
+        const prewarmNote = prewarmResult.ok ? ' packages/app prewarmed.' : '';
+        const reprovisionNote = hasBinding && params.reprovision
+            ? ' Previous binding archived in .env (old database kept); rebuild the schema with provision_blueprint + run_codegen.'
+            : '';
+        const message = `Provisioned database "${databaseName}" (ID: ${databaseId}). Credentials written to .env. ${fixup.note}${prewarmNote}${reprovisionNote}`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: true,
+                message,
+                databaseId,
+                databaseName,
+                ownerId,
+                fixupNote: fixup.note,
+            },
+        };
+    },
+};

package/tools/run-codegen.d.ts

@@ -0,0 +1,12 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+import { prewarmAppWorkspace } from '../app-workspace';
+declare const RunCodegenZod: z.ZodObject<{}, z.core.$strip>;
+export type RunCodegenDetails = {
+    success: boolean;
+    message: string;
+    barrelsRewritten?: number;
+    generatedSubmodules?: string[];
+};
+export declare const runCodegenTool: HarnessTool<typeof RunCodegenZod, RunCodegenDetails>;
+export { prewarmAppWorkspace };