@agentic-kit/db-tools 0.11.4 → 0.12.0

package/esm/tools/provision-database.js

@@ -1,35 +1,6 @@
-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 { 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';
-    }
-}
+import { run } from '../app-workspace';
+import { boundDatabaseId, provisionFromTool, } from '../provision-database/provision';
 const ProvisionDatabaseZod = z.object({
     database_name: z
         .string()
@@ -39,216 +10,25 @@ const ProvisionDatabaseZod = z.object({
         .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;
+// `exec` runs the prewarm's child processes (clone, install); tests inject it.
+export function createProvisionDatabaseTool(exec = run) {
+    return {
+        name: 'provision_database',
+        label: 'Provision database',
+        description: 'Bootstrap a new Constructive database for the project under your account: provision the standard module set 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). If a call returns while the database is still provisioning, call it again with the same database_name to keep waiting; a different name starts a second database.',
+        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) {
+            // reprovision: true replaces the binding the project has right now; one
+            // that changes while this call waits for the project lock is not replaced.
+            const replace = params.reprovision === true;
+            const details = await provisionFromTool({
+                databaseName: params.database_name,
+                mode: replace ? 'replace' : 'ensure',
+                replaces: replace ? ((await boundDatabaseId(ctx.cwd)) ?? null) : undefined,
+            }, ctx, exec);
+            return { content: [{ type: 'text', text: details.message }], details };
+        },
+    };
 }
-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 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)}`);
-        }
-        // 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}`);
-        }
-        // 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.${prewarmNote}${reprovisionNote}`;
-        return {
-            content: [{ type: 'text', text: message }],
-            details: {
-                success: true,
-                message,
-                databaseId,
-                databaseName,
-                ownerId,
-            },
-        };
-    },
-};
+export const provisionDatabaseTool = createProvisionDatabaseTool();

package/esm/tools/run-codegen.d.ts

@@ -1,12 +1,29 @@
 import type { HarnessTool } from '@agentic-kit/harness';
 import { z } from 'zod';
-import { prewarmAppWorkspace } from '../app-workspace';
+import { prewarmAppWorkspace, type RunCommand } from '../app-workspace';
 declare const RunCodegenZod: z.ZodObject<{}, z.core.$strip>;
+/** Wall-clock milliseconds per step; a step that didn't run reports 0. */
+export type RunCodegenTimings = {
+    scaffoldMs: number;
+    installMs: number;
+    codegenMs: number;
+    barrelsMs: number;
+    totalMs: number;
+};
 export type RunCodegenDetails = {
     success: boolean;
     message: string;
     barrelsRewritten?: number;
     generatedSubmodules?: string[];
+    /** `composed` when packages/app carries .constructive/compose.json. */
+    appKind?: 'composed' | 'template';
+    /** False when a composed app's node_modules was already there. */
+    installed?: boolean;
+    codegenAttempts?: number;
+    timings?: RunCodegenTimings;
+    /** The app API answered ACCESS_SUSPENDED: the database is deleted or suspended. */
+    code?: 'database-unavailable';
 };
-export declare const runCodegenTool: HarnessTool<typeof RunCodegenZod, RunCodegenDetails>;
+export declare function createRunCodegenTool(exec?: RunCommand): HarnessTool<typeof RunCodegenZod, RunCodegenDetails>;
+export declare const runCodegenTool: HarnessTool<z.ZodObject<{}, z.core.$strip>, RunCodegenDetails>;
 export { prewarmAppWorkspace };

package/esm/tools/run-codegen.js

@@ -2,136 +2,223 @@ 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 { detectAppKind, ensureAppScaffold, ensureComposedInstall, ensureWorkspaceConfig, IGNORED_BUILDS_RE, pinCodegenLatest, prewarmAppWorkspace, run, settlePrewarm, } from '../app-workspace';
+import { classifyBackendErrors, postGraphQL } from '../graphql-http';
 import { getHost } from '../host';
+import { readEnv } from '../provision-database/env-file';
 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 } };
+function fail(message, extra) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { ...extra, success: false, message },
+    };
 }
 const FETCH_RESET_RE = /Failed to fetch schema|Connection reset|ECONNRESET|socket hang up/i;
+// A refusal is an answer, not a dropped connection: retrying it only waits.
+const REFUSED_RE = /\b403\b|Forbidden|ACCESS_SUSPENDED/;
 // 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') };
+        const env = readEnv(await readFile(path.join(cwd, '.env'), 'utf8'));
+        return {
+            databaseName: env.DATABASE_NAME?.trim() || undefined,
+            apiEndpoint: env.API_ENDPOINT?.trim() || undefined,
+        };
     }
     catch {
         return {};
     }
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+// Ask the app API itself; a 403 from codegen alone could be anything.
+async function isDatabaseUnavailable(appEndpoint) {
+    const answer = await postGraphQL({ endpoint: appEndpoint, query: '{ __typename }' });
+    return classifyBackendErrors(answer.errors) === 'suspended';
+}
+const CODEGEN_ARGS = ['generate', '--config', './graphql-codegen.config.ts'];
+// The template flow resolves codegen through npx. A composed app runs the codegen
+// its lockfile pinned: the linked bin, or the app's own `codegen` script when the
+// bin isn't linked, so nothing is resolved over the network.
+function codegenCommand(appDir, composed) {
+    if (!composed)
+        return { cmd: 'npx', args: ['@constructive-io/graphql-codegen', ...CODEGEN_ARGS] };
+    const bin = path.join(appDir, 'node_modules', '.bin', 'graphql-codegen');
+    return existsSync(bin) ? { cmd: bin, args: CODEGEN_ARGS } : { cmd: 'pnpm', args: ['run', 'codegen'] };
+}
 // 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) {
+async function runCodegenWithRetry(appDir, env, exec, composed, attempts = 4) {
     const sdk = path.join(appDir, 'src', 'graphql', 'sdk');
+    const { cmd, args } = codegenCommand(appDir, composed);
     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 });
+        // A composed app ships SDK stubs so it builds before codegen; codegen prunes
+        // its own stale files, so the stubs stay until a run replaces them.
+        if (!composed) {
+            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;
+        last = await exec(cmd, args, appDir, env);
+        if (last.ok || !FETCH_RESET_RE.test(last.out) || REFUSED_RE.test(last.out))
+            return { ...last, attempts: i };
         if (i < attempts)
             await sleep(2000 * i);
     }
-    return last;
+    return { ...last, attempts };
 }
-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);
+// `exec` runs every child process (clone, install, codegen); tests inject it.
+export function createRunCodegenTool(exec = run) {
+    return {
+        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. A composed app (packages/app/.constructive/compose.json) skips the scaffold and those fixups: it installs from its own lockfile only when node_modules is missing and runs its local codegen. 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; a composed app keeps its lockfile and local codegen). Run after schema changes. Gated.',
+        parameters: RunCodegenZod,
+        async execute(_params, ctx) {
+            const started = Date.now();
+            const since = (t) => Date.now() - t;
+            const cwd = ctx.cwd;
+            const appDir = path.join(cwd, 'packages', 'app');
+            // A prewarm provision_database started may still be installing; let it
+            // finish so this run's install never races it.
+            await settlePrewarm(cwd);
+            const app = detectAppKind(appDir);
+            if (app.kind === 'invalid') {
+                return fail(`${app.reason} Recompose packages/app, or remove the marker to use the template flow.`);
             }
-            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,
-            },
-        };
-    },
-};
+            const composed = app.kind === 'composed';
+            const appKind = composed ? 'composed' : 'template';
+            const timings = {
+                scaffoldMs: 0,
+                installMs: 0,
+                codegenMs: 0,
+                barrelsMs: 0,
+                totalMs: 0,
+            };
+            let installed;
+            let codegenAttempts;
+            const stepDetails = () => ({
+                appKind,
+                installed,
+                codegenAttempts,
+                timings: { ...timings, totalMs: since(started) },
+            });
+            // 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.
+            if (!composed) {
+                const t = Date.now();
+                const scaffold = await ensureAppScaffold(cwd, exec);
+                timings.scaffoldMs = since(t);
+                if (!scaffold.ok) {
+                    return fail(scaffold.out, stepDetails());
+                }
+            }
+            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)}`);
+            }
+            const tInstall = Date.now();
+            if (composed) {
+                const install = await ensureComposedInstall(cwd, exec);
+                timings.installMs = since(tInstall);
+                installed = install.installed;
+                if (!install.ok) {
+                    return fail(install.out, stepDetails());
+                }
+            }
+            else {
+                // 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 exec('pnpm', ['install', '--no-frozen-lockfile'], cwd);
+                timings.installMs = since(tInstall);
+                installed = true;
+                if (!install.ok && !IGNORED_BUILDS_RE.test(install.out)) {
+                    return fail(`pnpm install failed:\n${install.out}`, stepDetails());
+                }
+            }
+            const tCodegen = Date.now();
+            const codegen = await runCodegenWithRetry(appDir, {
+                NEXT_PUBLIC_DB_NAME: dbName,
+                ...(planes ? codegenEndpointEnv(planes) : {}),
+            }, exec, composed);
+            timings.codegenMs = since(tCodegen);
+            codegenAttempts = codegen.attempts;
+            if (!codegen.ok) {
+                // A refused introspection may be the database itself: deleted or
+                // suspended databases answer ACCESS_SUSPENDED on every app API.
+                if (REFUSED_RE.test(codegen.out) && planes && (await isDatabaseUnavailable(planes.app))) {
+                    return fail(`codegen failed: the app database "${dbName}" is unavailable (the backend answered ACCESS_SUSPENDED: it was deleted or is suspended). Re-running run_codegen won't help until it is restored.`, { ...stepDetails(), code: 'database-unavailable' });
+                }
+                // 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, stepDetails());
+                }
+                return fail(`codegen failed:\n${codegen.out}`, stepDetails());
+            }
+            // Normalize directory barrels so Turbopack can resolve them (TURBOPACK-BARREL-001).
+            // Only directories that exist are rewritten, so a config without an admin
+            // target leaves nothing pointing at one.
+            const tBarrels = Date.now();
+            const sdkRoot = path.join(appDir, 'src', 'graphql', 'sdk');
+            const barrelsRewritten = normalizeSdkBarrels(sdkRoot);
+            timings.barrelsMs = since(tBarrels);
+            // 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,
+                    ...stepDetails(),
+                },
+            };
+        },
+    };
+}
+export const runCodegenTool = createRunCodegenTool();
 // 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 };