@agentic-kit/db-tools 0.11.5 → 0.12.0

package/tools/run-codegen.js

@@ -4,138 +4,226 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.prewarmAppWorkspace = exports.runCodegenTool = void 0;
+exports.createRunCodegenTool = createRunCodegenTool;
 const node_fs_1 = require("node:fs");
 const promises_1 = require("node:fs/promises");
 const node_path_1 = __importDefault(require("node:path"));
 const zod_1 = require("zod");
 const app_workspace_1 = require("../app-workspace");
 Object.defineProperty(exports, "prewarmAppWorkspace", { enumerable: true, get: function () { return app_workspace_1.prewarmAppWorkspace; } });
+const graphql_http_1 = require("../graphql-http");
 const host_1 = require("../host");
+const env_file_1 = require("../provision-database/env-file");
 const barrels_1 = require("../run-codegen/barrels");
 const endpoints_1 = require("../run-codegen/endpoints");
 const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
 const RunCodegenZod = zod_1.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 (0, promises_1.readFile)(node_path_1.default.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 = (0, env_file_1.readEnv)(await (0, promises_1.readFile)(node_path_1.default.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 (0, graphql_http_1.postGraphQL)({ endpoint: appEndpoint, query: '{ __typename }' });
+    return (0, graphql_http_1.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 = node_path_1.default.join(appDir, 'node_modules', '.bin', 'graphql-codegen');
+    return (0, node_fs_1.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 = node_path_1.default.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 (0, promises_1.rm)(node_path_1.default.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 (0, promises_1.rm)(node_path_1.default.join(sdk, sub), { recursive: true, force: true });
+            }
         }
-        last = await (0, app_workspace_1.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 };
 }
-exports.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 = node_path_1.default.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 (0, app_workspace_1.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 = (0, host_1.getHost)().backendConfig();
-        const apiEndpoint = envApiEndpoint || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
-        const planes = (0, endpoints_1.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 (0, promises_1.writeFile)(node_path_1.default.join(appDir, '.env.local'), (0, endpoints_1.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 (0, app_workspace_1.ensureWorkspaceConfig)(cwd);
-        await (0, app_workspace_1.pinCodegenLatest)(appDir);
-        const install = await (0, app_workspace_1.run)('pnpm', ['install', '--no-frozen-lockfile'], cwd);
-        if (!install.ok && !app_workspace_1.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 ? (0, endpoints_1.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.
+function createRunCodegenTool(exec = app_workspace_1.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 = node_path_1.default.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 (0, app_workspace_1.settlePrewarm)(cwd);
+            const app = (0, app_workspace_1.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 = node_path_1.default.join(appDir, 'src', 'graphql', 'sdk');
-        const barrelsRewritten = (0, barrels_1.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 = node_path_1.default.join(sdkRoot, 'app');
-        const generatedSubmodules = ['hooks', 'orm', 'types'].filter((sub) => (0, node_fs_1.existsSync)(node_path_1.default.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 (0, app_workspace_1.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 = (0, host_1.getHost)().backendConfig();
+            const apiEndpoint = envApiEndpoint || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
+            const planes = (0, endpoints_1.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 (0, promises_1.writeFile)(node_path_1.default.join(appDir, '.env.local'), (0, endpoints_1.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 (0, app_workspace_1.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 (0, app_workspace_1.ensureWorkspaceConfig)(cwd);
+                await (0, app_workspace_1.pinCodegenLatest)(appDir);
+                const install = await exec('pnpm', ['install', '--no-frozen-lockfile'], cwd);
+                timings.installMs = since(tInstall);
+                installed = true;
+                if (!install.ok && !app_workspace_1.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 ? (0, endpoints_1.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 = node_path_1.default.join(appDir, 'src', 'graphql', 'sdk');
+            const barrelsRewritten = (0, barrels_1.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 = node_path_1.default.join(sdkRoot, 'app');
+            const generatedSubmodules = ['hooks', 'orm', 'types'].filter((sub) => (0, node_fs_1.existsSync)(node_path_1.default.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(),
+                },
+            };
+        },
+    };
+}
+exports.runCodegenTool = createRunCodegenTool();

package/tools/templates.js

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