@agentic-kit/db-tools 0.2.0

package/esm/tools/provision-blueprint.js

@@ -0,0 +1,109 @@
+import { BlueprintZod, expandBlueprintDefaults, filterInternalPolicies, } from '@agentic-kit/harness';
+import { resolveProjectContext } from '../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');
+}
+export const 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: BlueprintZod,
+    async execute(params, ctx) {
+        const empty = { created: 0, total: 0, tables: [], error: null };
+        const resolved = await 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 = 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: 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/esm/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/esm/tools/provision-database.js

@@ -0,0 +1,260 @@
+import { writeFile } from 'node:fs/promises';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { prewarmAppWorkspace } from '../app-workspace';
+import { probeDatabase } from '../db-probe';
+import { getHost } from '../host';
+import { selectProvisionCredential } from '../provision-database/credential';
+import { archiveBindingKeys, ARCHIVED_BINDING_KEYS, mergeEnv, provisionEnvVars, } from '../provision-database/env-file';
+import { loadProvisionManifest } from '../provision-database/manifest';
+import { applySqlFixups } from '../provision-database/pg-fixups';
+import { selectProvisionRequest } from '../provision-database/preset-match';
+import { requestDatabaseProvision } from '../provision-database/request-database';
+import { resolveProvisionModules } from '../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 = z.object({
+    database_name: 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: 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;
+}
+export const 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 = path.join(ctx.cwd, '.env');
+        let existing = '';
+        try {
+            existing = await 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 = 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 = 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 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 writeFile(envPath, 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 = archiveBindingKeys(existing, 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 = 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 loadProvisionManifest(ctx.cwd);
+            if (projectOverlay)
+                layers.push(projectOverlay);
+            modules = 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 requestDatabaseProvision({
+                apiEndpoint,
+                modulesEndpoint,
+                bearer: credential.bearer,
+                databaseName,
+                domain: provisionDomain(apiEndpoint),
+                request: 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 applySqlFixups({ databaseName, physicalDb });
+        // Persist the binding to the project .env (upsert, preserving other keys).
+        const merged = mergeEnv(existing, provisionEnvVars({
+            databaseId,
+            databaseName,
+            ownerId,
+            accessToken: credential.bearer,
+            apiEndpoint,
+            modulesEndpoint,
+        }));
+        try {
+            await 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/esm/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 };

package/esm/tools/run-codegen.js

@@ -0,0 +1,137 @@
+import { existsSync } from 'node:fs';
+import { readFile, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { z } from 'zod';
+import { ensureAppScaffold, ensureWorkspaceConfig, IGNORED_BUILDS_RE, pinCodegenLatest, prewarmAppWorkspace, run, } from '../app-workspace';
+import { getHost } from '../host';
+import { normalizeSdkBarrels } from '../run-codegen/barrels';
+import { codegenEndpointEnv, derivePlaneEndpoints, envLocalContent } from '../run-codegen/endpoints';
+const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
+const RunCodegenZod = z.object({});
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+const FETCH_RESET_RE = /Failed to fetch schema|Connection reset|ECONNRESET|socket hang up/i;
+// Read the binding provision_database wrote to the project .env. The
+// API_ENDPOINT pin identifies which backend owns the binding — it wins over
+// the app's current backend config, matching context.ts data-plane precedence.
+async function readProjectEnv(cwd) {
+    try {
+        const env = await readFile(path.join(cwd, '.env'), 'utf8');
+        const read = (key) => env.match(new RegExp(`^${key}=(.+)$`, 'm'))?.[1]?.trim();
+        return { databaseName: read('DATABASE_NAME'), apiEndpoint: read('API_ENDPOINT') };
+    }
+    catch {
+        return {};
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// The codegen CLI introspects three live vhosts (admin/auth/app). Under load the
+// Constructive backend intermittently resets a connection mid-introspection
+// ("Failed to fetch schema: Connection reset"), which is transient — a retry
+// almost always clears it. Re-run the whole generate (it rebuilds all targets)
+// up to `attempts` times, only on a fetch/reset failure; any other failure is
+// real and returned immediately (CODEGEN-RETRY-001).
+async function runCodegenWithRetry(appDir, env, attempts = 4) {
+    const sdk = path.join(appDir, 'src', 'graphql', 'sdk');
+    let last = { ok: false, out: 'codegen never ran' };
+    for (let i = 1; i <= attempts; i++) {
+        for (const sub of ['admin', 'auth', 'app']) {
+            await rm(path.join(sdk, sub), { recursive: true, force: true });
+        }
+        last = await run('npx', ['@constructive-io/graphql-codegen', 'generate', '--config', './graphql-codegen.config.ts'], appDir, env);
+        if (last.ok)
+            return last;
+        if (!FETCH_RESET_RE.test(last.out))
+            return last;
+        if (i < attempts)
+            await sleep(2000 * i);
+    }
+    return last;
+}
+export const runCodegenTool = {
+    name: 'run_codegen',
+    label: 'Run codegen',
+    description: "Generate the typed GraphQL SDK for the project's Next.js app (packages/app). Runs the exact deterministic sequence — scaffold packages/app from the constructive-app template if it doesn't exist yet, hoist the graphql override to the root workspace so a single grafast resolves, pin codegen to latest, do one clean install, run codegen (retrying transient backend connection resets), and normalize SDK barrels for Turbopack. Run AFTER provisioning the database and creating schema; it scaffolds packages/app itself, so no separate `pgpm init` step is needed. The scaffold + install are usually prewarmed during provision_database, so this is fast.",
+    promptSnippet: 'run_codegen: scaffold packages/app (if missing) + regenerate the typed SDK (workspace-config + clean install + codegen-with-retry + barrel-normalize). Run after schema changes. Gated.',
+    parameters: RunCodegenZod,
+    async execute(_params, ctx) {
+        const cwd = ctx.cwd;
+        const appDir = path.join(cwd, 'packages', 'app');
+        // Materialize packages/app deterministically if it isn't there yet — this
+        // replaces the flaky `pgpm init` scaffold step (PGPM-001). When
+        // provision_database prewarmed it, this no-ops.
+        const scaffold = await ensureAppScaffold(cwd);
+        if (!scaffold.ok) {
+            return fail(scaffold.out);
+        }
+        const { databaseName: dbName, apiEndpoint: envApiEndpoint } = await readProjectEnv(cwd);
+        if (!dbName) {
+            return fail('DATABASE_NAME missing from .env — provision the database first, then re-run.');
+        }
+        const backend = getHost().backendConfig();
+        const apiEndpoint = envApiEndpoint || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
+        const planes = derivePlaneEndpoints(apiEndpoint, dbName);
+        // The dev server reads .env.local (NEXT_PUBLIC_DB_NAME + per-DB endpoint
+        // overrides so it doesn't fall back to localhost vhosts on a remote
+        // backend); the codegen config reads process.env (passed directly below).
+        try {
+            await writeFile(path.join(appDir, '.env.local'), envLocalContent(dbName, planes));
+        }
+        catch (err) {
+            return fail(`Failed to write packages/app/.env.local: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        // Hoist the graphql override to the root workspace (PNPM-GRAPHQL-OVERRIDE-001)
+        // and pin codegen to latest (TS-001) before the single clean install. When
+        // prewarmed by provision_database these are idempotent and the install is a
+        // fast no-op; otherwise this is the first install (PNPM-BUILDS-001).
+        await ensureWorkspaceConfig(cwd);
+        await pinCodegenLatest(appDir);
+        const install = await run('pnpm', ['install', '--no-frozen-lockfile'], cwd);
+        if (!install.ok && !IGNORED_BUILDS_RE.test(install.out)) {
+            return fail(`pnpm install failed:\n${install.out}`);
+        }
+        const codegen = await runCodegenWithRetry(appDir, {
+            NEXT_PUBLIC_DB_NAME: dbName,
+            ...(planes ? codegenEndpointEnv(planes) : {}),
+        });
+        if (!codegen.ok) {
+            // A reset that survives every internal retry is a backend OUTAGE, not a code
+            // or install problem — re-running run_codegen cannot fix it. Say so explicitly
+            // so the agent marks sdk-codegen `blocked` instead of looping the tool to the
+            // time cap (CODEGEN-OUTAGE-001 / THRASH-001).
+            if (FETCH_RESET_RE.test(codegen.out)) {
+                return fail('codegen failed: BACKEND OUTAGE — the Constructive backend reset the connection ' +
+                    'during schema introspection, and it stayed down across every internal retry. ' +
+                    'This is an EXTERNAL outage, not a code or install problem; re-running run_codegen ' +
+                    'will NOT fix it. Call run_preflight once — if the backend is down, mark ' +
+                    'sdk-codegen `blocked` (SERVER-001, BLOCKED-PROCEED-001) and hand back to ' +
+                    'build-orchestrator. Do NOT loop on run_codegen (THRASH-001).\n\n' +
+                    codegen.out);
+            }
+            return fail(`codegen failed:\n${codegen.out}`);
+        }
+        // Normalize directory barrels so Turbopack can resolve them (TURBOPACK-BARREL-001).
+        const sdkRoot = path.join(appDir, 'src', 'graphql', 'sdk');
+        const barrelsRewritten = normalizeSdkBarrels(sdkRoot);
+        // Report which app submodules actually generated — a bare scaffold with only
+        // index.ts means codegen had no schema to generate against.
+        const appSdk = path.join(sdkRoot, 'app');
+        const generatedSubmodules = ['hooks', 'orm', 'types'].filter((sub) => existsSync(path.join(appSdk, sub)));
+        const message = generatedSubmodules.length > 0
+            ? `Codegen complete. Generated app submodules: ${generatedSubmodules.join(', ')}. Normalized ${barrelsRewritten} barrel file(s).`
+            : `Codegen ran, but no app submodules (hooks/orm/types) were generated — the database may have no entity tables yet. Normalized ${barrelsRewritten} barrel file(s).`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: generatedSubmodules.length > 0,
+                message,
+                barrelsRewritten,
+                generatedSubmodules,
+            },
+        };
+    },
+};
+// Re-exported so provision_database can prewarm the same deterministic scaffold +
+// install concurrently with its backend mutation (kept off run_codegen's path).
+export { prewarmAppWorkspace };

package/esm/tools/templates.d.ts

@@ -0,0 +1,71 @@
+import { type ConfirmPreviewTable, type HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+import type { ProjectContext } from '../context';
+export type TemplateDetails = {
+    success: boolean;
+    message: string;
+};
+export type CreateTemplateDetails = TemplateDetails & {
+    displayName?: string;
+    blueprintName?: string;
+    tables?: ConfirmPreviewTable[];
+};
+type TemplateField = {
+    name: string;
+    type: string;
+    isRequired: boolean;
+    defaultValue: string | null;
+};
+type TemplateTable = {
+    name: string;
+    fields: TemplateField[];
+    policies: string[];
+    relationCount: number;
+};
+type TemplateInfo = {
+    displayName: string;
+    description: string | null;
+    categories: string[];
+    tables: TemplateTable[];
+};
+export type ListTemplatesDetails = {
+    templates: TemplateInfo[];
+};
+export type CreateTemplatePreview = {
+    blueprintName: string;
+    tables: ConfirmPreviewTable[];
+};
+export declare function createTemplatePreviewTables(context: ProjectContext, blueprintName: string | undefined): Promise<CreateTemplatePreview>;
+declare const ListTemplatesZod: z.ZodObject<{}, z.core.$strip>;
+export declare const listTemplatesTool: HarnessTool<typeof ListTemplatesZod, ListTemplatesDetails>;
+declare const CreateTemplateZod: z.ZodObject<{
+    displayName: z.ZodString;
+    blueprintName: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodString>;
+    categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const createTemplateTool: HarnessTool<typeof CreateTemplateZod, CreateTemplateDetails>;
+declare const ApplyTemplateZod: z.ZodObject<{
+    templateName: z.ZodString;
+    nameOverride: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const applyTemplateTool: HarnessTool<typeof ApplyTemplateZod, TemplateDetails>;
+declare const UpdateTemplateZod: z.ZodObject<{
+    templateName: z.ZodString;
+    patch: z.ZodObject<{
+        displayName: z.ZodOptional<z.ZodString>;
+        description: z.ZodOptional<z.ZodString>;
+        categories: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        visibility: z.ZodOptional<z.ZodEnum<{
+            public: "public";
+            private: "private";
+        }>>;
+    }, z.core.$strip>;
+}, z.core.$strip>;
+export declare const updateTemplateTool: HarnessTool<typeof UpdateTemplateZod, TemplateDetails>;
+declare const DeleteTemplateZod: z.ZodObject<{
+    templateName: z.ZodString;
+}, z.core.$strip>;
+export declare const deleteTemplateTool: HarnessTool<typeof DeleteTemplateZod, TemplateDetails>;
+export {};