@agentic-kit/db-tools 0.11.5 → 0.12.0

package/db-probe.js

@@ -1,50 +1,110 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.probeDatabase = probeDatabase;
-const sdk_1 = require("@constructive-io/sdk");
-const AUTH_ERROR_RE = /unauthenticated|unauthorized|permission denied|jwt|http 401|http 403/i;
-// Liveness probe for a bound database. The split drives recovery: 'missing'
-// means the backend answered and the binding is dead (database deleted,
-// backend refreshed) — recovery is reprovision. 'unreachable' means no usable
-// answer (backend down, network error, rejected credential) — recovery is
-// retry/re-sign-in, never reprovision.
+exports.probeBoundDatabase = probeBoundDatabase;
+const graphql_http_1 = require("./graphql-http");
+const host_1 = require("./host");
+const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
+const FIELDS = 'id name ownerId hash suspendedAt suspendedReason';
+// A backend from before `hash` and the suspension columns.
+const BASIC_FIELDS = 'id name ownerId';
+const NEWER_FIELD_RE = /\b(hash|suspended_?at|suspended_?reason)\b/i;
+const document = (databaseId, fields) => `
+    query ProbeDatabase {
+      databases(where: { id: { equalTo: ${JSON.stringify(databaseId)} } }, first: 1) {
+        nodes { ${fields} }
+      }
+    }`;
+// Liveness probe for a bound database, on the platform api. Only 'missing'
+// means the binding is dead: the backend answered and the account can't see
+// the database (deleted, or access to it lost). 'suspended' means it exists
+// and is held, so its data must not be replaced. 'unreachable' is any answer
+// that says nothing about the database (no response, a failing backend, a
+// rejected account credential, an error this probe doesn't know); recovery is
+// a retry or a sign-in, never a reprovision.
 //
 // The probe authenticates with the ACCOUNT bearer, not the project's .env key:
 // the platform api rejects per-database keys, and the singular `database(id:)`
 // field is gone from the current contract, so the lookup goes through the
-// `databases` collection filter via the SDK's raw FetchAdapter.
+// `databases` collection filter.
 async function probeDatabase(args) {
-    const executor = args.executor ??
-        new sdk_1.api.FetchAdapter(args.endpoint, { Authorization: `Bearer ${args.bearer}` });
-    const document = `
-    query ProbeDatabase {
-      databases(where: { id: { equalTo: ${JSON.stringify(args.databaseId)} } }) {
-        nodes { id name ownerId }
-      }
-    }`;
-    try {
-        const result = await executor.execute(document);
-        if (result.ok) {
-            const node = result.data.databases?.nodes?.[0];
-            if (!node)
-                return { outcome: 'missing' };
-            return { outcome: 'found', name: node.name ?? undefined, ownerId: node.ownerId ?? undefined };
-        }
-        const detail = result.errors?.[0]?.message ?? 'unknown error';
-        // A 5xx is the backend failing, not an answer about this database. An auth
-        // rejection is a dead ACCOUNT credential — never evidence the binding is
-        // dead, so it must not push toward reprovision.
-        if (/^HTTP 5\d\d/i.test(detail))
-            return { outcome: 'unreachable', detail };
-        if (AUTH_ERROR_RE.test(detail)) {
+    const post = args.post ?? graphql_http_1.postGraphQL;
+    const { databaseId } = args;
+    const ask = (fields) => post({
+        endpoint: args.endpoint,
+        headers: { Authorization: `Bearer ${args.bearer}` },
+        query: document(databaseId, fields),
+    });
+    let result = await ask(FIELDS);
+    if (result.errors.length > 0 && result.errors.some((e) => NEWER_FIELD_RE.test(e?.message ?? ''))) {
+        result = await ask(BASIC_FIELDS);
+    }
+    if (result.errors.length > 0)
+        return unreachable(databaseId, result.errors, args.signInHint);
+    const nodes = result.data?.databases?.nodes;
+    if (!Array.isArray(nodes)) {
+        return { status: 'unreachable', databaseId, cause: 'error', detail: 'the backend answered without a databases list' };
+    }
+    const node = nodes[0];
+    if (!node)
+        return { status: 'missing', databaseId };
+    const found = {
+        databaseId,
+        name: node.name ?? undefined,
+        ownerId: node.ownerId ?? undefined,
+        hash: node.hash ?? undefined,
+    };
+    if (node.suspendedAt) {
+        return {
+            status: 'suspended',
+            ...found,
+            suspendedAt: node.suspendedAt,
+            suspendedReason: node.suspendedReason ?? undefined,
+        };
+    }
+    return { status: 'found', ...found };
+}
+function unreachable(databaseId, errors, signInHint) {
+    const detail = (0, graphql_http_1.errorsText)(errors);
+    switch ((0, graphql_http_1.classifyBackendErrors)(errors)) {
+        case 'network':
+            return { status: 'unreachable', databaseId, cause: 'network', detail };
+        case 'server':
+            return { status: 'unreachable', databaseId, cause: 'server', detail };
+        case 'auth':
+        case 'forbidden':
+            // A rejected ACCOUNT credential is never evidence the binding is dead.
             return {
-                outcome: 'unreachable',
-                detail: `${detail} — the account credential was rejected. ${args.signInHint ?? 'Sign in again, then retry.'}`,
+                status: 'unreachable',
+                databaseId,
+                cause: 'auth',
+                detail: `${detail}: the account credential was rejected. ${signInHint ?? 'Sign in again, then retry.'}`,
             };
-        }
-        return { outcome: 'missing' };
+        default:
+            return { status: 'unreachable', databaseId, cause: 'error', detail };
     }
-    catch (err) {
-        return { outcome: 'unreachable', detail: err instanceof Error ? err.message : String(err) };
+}
+/**
+ * Probe a database with the host's account bearer on its configured control
+ * endpoint (never a project-pinned one). Without a bearer the answer is
+ * unreachable with cause 'auth'.
+ */
+async function probeBoundDatabase(databaseId) {
+    const host = (0, host_1.getHost)();
+    const account = host.account();
+    const bearer = account?.apiKey ?? account?.accessToken;
+    if (!bearer) {
+        return {
+            status: 'unreachable',
+            databaseId,
+            cause: 'auth',
+            detail: `No usable account credential. ${host.signInHint ?? 'Sign in to the app, then retry.'}`,
+        };
     }
+    return probeDatabase({
+        endpoint: host.backendConfig()?.apiEndpoint || DEFAULT_API_ENDPOINT,
+        bearer,
+        databaseId,
+        signInHint: host.signInHint,
+    });
 }

package/esm/app-workspace.d.ts

@@ -1,16 +1,43 @@
 export declare const NATIVE_BUILD_DEPS: string[];
 export declare const IGNORED_BUILDS_RE: RegExp;
+export declare const COMPOSE_MARKER: string;
+export type AppKind = {
+    kind: 'composed';
+} | {
+    kind: 'template';
+} | {
+    kind: 'invalid';
+    reason: string;
+};
+/**
+ * Which flow packages/app takes. Composed needs the marker to be a JSON object
+ * and the app's own lockfile beside it. A marker that fails either check is
+ * neither: running the template fixups would rewrite a composed app, so
+ * callers stop and report the reason instead.
+ */
+export declare function detectAppKind(appDir: string): AppKind;
+export type RunCommand = (cmd: string, args: string[], cwd: string, env?: Record<string, string>) => Promise<{
+    ok: boolean;
+    out: string;
+}>;
 export declare function run(cmd: string, args: string[], cwd: string, env?: Record<string, string>): Promise<{
     ok: boolean;
     out: string;
 }>;
 export declare function ensureWorkspaceConfig(cwd: string): Promise<void>;
 export declare function pinCodegenLatest(appDir: string): Promise<void>;
-export declare function ensureAppScaffold(cwd: string): Promise<{
+export declare function ensureAppScaffold(cwd: string, exec?: RunCommand): Promise<{
+    ok: boolean;
+    out: string;
+}>;
+export declare function ensureComposedInstall(cwd: string, exec?: RunCommand): Promise<{
     ok: boolean;
     out: string;
+    installed: boolean;
 }>;
-export declare function prewarmAppWorkspace(cwd: string): Promise<{
+export declare function prewarmAppWorkspace(cwd: string, exec?: RunCommand): Promise<{
     ok: boolean;
     out: string;
 }>;
+/** Wait for a prewarm still running for `cwd`; its outcome doesn't matter here. */
+export declare function settlePrewarm(cwd: string): Promise<void>;

package/esm/app-workspace.js

@@ -1,5 +1,5 @@
 import { execFile } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
 import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
@@ -22,6 +22,38 @@ export const IGNORED_BUILDS_RE = /ERR_PNPM_IGNORED_BUILDS|Ignored build scripts/
 const DEFAULT_GRAPHQL_OVERRIDE = '16.14.0';
 const TEMPLATE_REPO = 'https://github.com/constructive-io/sandbox-templates';
 const TEMPLATE_SUBDIR = path.join('nextjs', 'constructive-app');
+// A composed app carries this marker, written when its template was composed.
+// It ships its own pinned package.json and pnpm-lock.yaml, so none of the
+// constructive-app fixups below apply to it.
+export const COMPOSE_MARKER = path.join('.constructive', 'compose.json');
+/**
+ * Which flow packages/app takes. Composed needs the marker to be a JSON object
+ * and the app's own lockfile beside it. A marker that fails either check is
+ * neither: running the template fixups would rewrite a composed app, so
+ * callers stop and report the reason instead.
+ */
+export function detectAppKind(appDir) {
+    const marker = path.join(appDir, COMPOSE_MARKER);
+    if (!existsSync(marker))
+        return { kind: 'template' };
+    let parsed;
+    try {
+        parsed = JSON.parse(readFileSync(marker, 'utf8'));
+    }
+    catch {
+        return { kind: 'invalid', reason: `packages/app/${COMPOSE_MARKER} is not valid JSON.` };
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        return { kind: 'invalid', reason: `packages/app/${COMPOSE_MARKER} is not a JSON object.` };
+    }
+    if (!existsSync(path.join(appDir, 'pnpm-lock.yaml'))) {
+        return {
+            kind: 'invalid',
+            reason: `packages/app has ${COMPOSE_MARKER} but no pnpm-lock.yaml, so it can't be installed as composed.`,
+        };
+    }
+    return { kind: 'composed' };
+}
 export async function run(cmd, args, cwd, env) {
     try {
         const { stdout, stderr } = await execFileAsync(cmd, args, {
@@ -81,14 +113,14 @@ export async function pinCodegenLatest(appDir) {
 // its CLI is unreliable in the non-TTY agent shell, which made the agent thrash
 // for minutes. Materialize `packages/app` deterministically by shallow-cloning
 // the template instead (PGPM-001).
-export async function ensureAppScaffold(cwd) {
+export async function ensureAppScaffold(cwd, exec = run) {
     const appDir = path.join(cwd, 'packages', 'app');
     if (existsSync(path.join(appDir, 'package.json'))) {
         return { ok: true, out: 'packages/app already scaffolded' };
     }
     const tmp = path.join(os.tmpdir(), `airpage-app-template-${process.pid}`);
     await rm(tmp, { recursive: true, force: true });
-    const clone = await run('git', ['clone', '--depth', '1', TEMPLATE_REPO, tmp], cwd);
+    const clone = await exec('git', ['clone', '--depth', '1', TEMPLATE_REPO, tmp], cwd);
     if (!clone.ok) {
         await rm(tmp, { recursive: true, force: true });
         return { ok: false, out: `Template clone failed:\n${clone.out}` };
@@ -112,21 +144,77 @@ export async function ensureAppScaffold(cwd) {
     await rm(tmp, { recursive: true, force: true });
     return { ok: true, out: 'Scaffolded packages/app from the constructive-app template.' };
 }
+// pnpm writes node_modules/.modules.yaml once an install finishes linking, so a
+// partial install (interrupted, or failed mid-way) lacks it. Codegen also
+// needs its bin, so both must be there to skip the install.
+function composedInstallComplete(appDir) {
+    const modules = path.join(appDir, 'node_modules');
+    return (existsSync(path.join(modules, '.modules.yaml')) &&
+        existsSync(path.join(modules, '.bin', 'graphql-codegen')));
+}
+// Install a composed app exactly as its lockfile pins it, unless a finished
+// install is already there. The install runs in packages/app against its own
+// lockfile, from the store where it can. A nested pnpm-workspace.yaml makes the
+// app its own workspace root, so the config is left alone; without one, a root
+// pnpm-workspace.yaml would pull the install up to the project root, where no
+// lockfile exists, so pnpm is told to ignore it instead of rewriting it.
+export async function ensureComposedInstall(cwd, exec = run) {
+    const appDir = path.join(cwd, 'packages', 'app');
+    if (composedInstallComplete(appDir)) {
+        return { ok: true, out: 'packages/app dependencies already installed.', installed: false };
+    }
+    const args = ['install', '--frozen-lockfile', '--prefer-offline'];
+    const ownsWorkspace = existsSync(path.join(appDir, 'pnpm-workspace.yaml'));
+    if (!ownsWorkspace && existsSync(path.join(cwd, 'pnpm-workspace.yaml'))) {
+        args.push('--ignore-workspace');
+    }
+    const install = await exec('pnpm', args, appDir);
+    if (!install.ok && !IGNORED_BUILDS_RE.test(install.out)) {
+        return { ok: false, out: `pnpm install failed:\n${install.out}`, installed: true };
+    }
+    return { ok: true, out: 'Installed packages/app from its lockfile.', installed: true };
+}
 // Scaffold packages/app, hoist the workspace config, pin codegen, and run the one
 // clean install. All of this is database-INDEPENDENT, so it can be prewarmed
 // concurrently with the ~90s provision_database backend mutation to keep clone +
 // install off run_codegen's critical path. Best-effort and fully idempotent:
 // run_codegen re-runs the same steps, finding the scaffold present and the install
 // already satisfied (a fast no-op). Errors are swallowed by callers that prewarm —
-// run_codegen surfaces any real failure later.
-export async function prewarmAppWorkspace(cwd) {
-    const scaffold = await ensureAppScaffold(cwd);
+// run_codegen surfaces any real failure later. A composed app only gets its
+// frozen install, and an invalid marker leaves the app untouched.
+//
+// One prewarm runs per project at a time: a call while one is in flight gets
+// that same run, so a retried provision_database (or run_codegen, via
+// settlePrewarm) never starts a second install beside it.
+const prewarmsInFlight = new Map();
+export function prewarmAppWorkspace(cwd, exec = run) {
+    const key = path.resolve(cwd);
+    const inFlight = prewarmsInFlight.get(key);
+    if (inFlight)
+        return inFlight;
+    const started = prewarm(cwd, exec).finally(() => prewarmsInFlight.delete(key));
+    prewarmsInFlight.set(key, started);
+    return started;
+}
+/** Wait for a prewarm still running for `cwd`; its outcome doesn't matter here. */
+export async function settlePrewarm(cwd) {
+    await prewarmsInFlight.get(path.resolve(cwd))?.catch(() => undefined);
+}
+async function prewarm(cwd, exec) {
+    const appDir = path.join(cwd, 'packages', 'app');
+    const app = detectAppKind(appDir);
+    if (app.kind === 'invalid')
+        return { ok: false, out: app.reason };
+    if (app.kind === 'composed') {
+        const install = await ensureComposedInstall(cwd, exec);
+        return install.ok ? { ok: true, out: 'Prewarmed packages/app install.' } : install;
+    }
+    const scaffold = await ensureAppScaffold(cwd, exec);
     if (!scaffold.ok)
         return scaffold;
-    const appDir = path.join(cwd, 'packages', 'app');
     await ensureWorkspaceConfig(cwd);
     await pinCodegenLatest(appDir);
-    const install = await run('pnpm', ['install', '--no-frozen-lockfile'], cwd);
+    const install = await exec('pnpm', ['install', '--no-frozen-lockfile'], cwd);
     if (!install.ok && !IGNORED_BUILDS_RE.test(install.out)) {
         return { ok: false, out: `pnpm install failed:\n${install.out}` };
     }

package/esm/blueprint-construction.d.ts

@@ -0,0 +1,60 @@
+import type { ModulesClient } from './context';
+/**
+ * How long a tool waits for its build: the build's own 120 s statement
+ * timeout, plus as long again for the builds queued ahead of it (a cold build
+ * of a curated blueprint takes 15-40 s). It stays under the 5-minute limit
+ * hosts put on the long database tools, so the tool reports the wait itself
+ * instead of being cut off.
+ */
+export declare const CONSTRUCTION_DEADLINE_MS = 240000;
+export declare const CONSTRUCTION_POLL_MS = 2000;
+/**
+ * Unreadable statuses in a row tolerated before giving up. The build goes on
+ * whether or not a read gets through, so a dropped request or a momentary 502
+ * must not end the wait.
+ */
+export declare const MAX_CONSECUTIVE_READ_FAILURES = 3;
+/** Table name → id, for the tables a construction created. */
+export type ConstructionTableMap = Record<string, string>;
+export type WaitForConstructionOptions = {
+    signal?: AbortSignal;
+    deadlineMs?: number;
+    pollMs?: number;
+    now?: () => number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+/**
+ * Why a construction failed, from its `error` column. That column came with
+ * the queued build, and the modules SDK predates it, so it is read on its own
+ * after a failure: the status reads stay valid on a backend without it. The
+ * SDK's select type doesn't list `error`, but the ORM writes each select key
+ * as the field name.
+ */
+export declare function readConstructionFailure(modules: ModulesClient, constructionId: string): Promise<string>;
+/**
+ * Wait for a construction to finish. Resolves with its table map once it is
+ * constructed, and throws with the backend's coded error once it failed, or
+ * when the deadline passes, the signal aborts, or its status can't be read.
+ */
+export declare function waitForConstruction(modules: ModulesClient, constructionId: string, options?: WaitForConstructionOptions): Promise<ConstructionTableMap>;
+/**
+ * A build that failed after the backend queued it, or that the wait gave up
+ * on. The construction carries on without the caller, so constructing again
+ * would queue the same tables a second time.
+ */
+export declare class BlueprintBuildError extends Error {
+    readonly constructionId: string;
+    constructor(message: string, constructionId: string);
+}
+/**
+ * Construct a blueprint into a schema and wait for the build. Resolves with
+ * the construction and the created tables. Once the backend has queued the
+ * build, every failure is a BlueprintBuildError with its construction id.
+ */
+export declare function buildBlueprint(modules: ModulesClient, input: {
+    blueprintId: string;
+    schemaId: string;
+}, options?: WaitForConstructionOptions): Promise<{
+    constructionId: string;
+    tables: ConstructionTableMap;
+}>;

package/esm/blueprint-construction.js

@@ -0,0 +1,154 @@
+// Building a blueprint: constructBlueprint enqueues a `blueprint:construct`
+// job and returns the construction id at once (constructive-db#4156). A worker
+// builds one blueprint at a time, each under a 120 s statement timeout, and
+// moves the construction row pending → constructing → constructed | failed,
+// with a failed build's coded error in `error`. A backend from before that
+// builds inside the mutation and raises the build's error from it, so the
+// first read already says constructed, and the same wait serves both.
+import { isTransientProvisionError } from './provision-database/request-database';
+/**
+ * How long a tool waits for its build: the build's own 120 s statement
+ * timeout, plus as long again for the builds queued ahead of it (a cold build
+ * of a curated blueprint takes 15-40 s). It stays under the 5-minute limit
+ * hosts put on the long database tools, so the tool reports the wait itself
+ * instead of being cut off.
+ */
+export const CONSTRUCTION_DEADLINE_MS = 240_000;
+export const CONSTRUCTION_POLL_MS = 2_000;
+/**
+ * Unreadable statuses in a row tolerated before giving up. The build goes on
+ * whether or not a read gets through, so a dropped request or a momentary 502
+ * must not end the wait.
+ */
+export const MAX_CONSECUTIVE_READ_FAILURES = 3;
+const MAY_STILL_FINISH = 'The build may still finish on the backend: read the schema before you call again.';
+const errorText = (err) => (err instanceof Error ? err.message : String(err));
+function stopped() {
+    return new Error(`Stopped waiting for the blueprint build. ${MAY_STILL_FINISH}`);
+}
+function abortableSleep(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted)
+            return reject(stopped());
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(stopped());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener('abort', onAbort);
+            resolve();
+        }, ms);
+        signal?.addEventListener('abort', onAbort, { once: true });
+    });
+}
+function tableMapOf(raw) {
+    if (!raw || typeof raw !== 'object')
+        return {};
+    return Object.fromEntries(Object.entries(raw).filter((entry) => typeof entry[1] === 'string'));
+}
+/**
+ * A failed construction's coded error on one line: `CODE: message` for a
+ * database error, `CODE {context}` for one raised through errors.raise_error.
+ */
+function describeConstructionError(error) {
+    if (!error || typeof error !== 'object')
+        return null;
+    const { code, message, context } = error;
+    const head = [code, message].filter((part) => typeof part === 'string' && part).join(': ');
+    const hasContext = Boolean(context && typeof context === 'object' && Object.keys(context).length);
+    const tail = hasContext ? JSON.stringify(context) : '';
+    return [head, tail].filter(Boolean).join(' ') || null;
+}
+/**
+ * Why a construction failed, from its `error` column. That column came with
+ * the queued build, and the modules SDK predates it, so it is read on its own
+ * after a failure: the status reads stay valid on a backend without it. The
+ * SDK's select type doesn't list `error`, but the ORM writes each select key
+ * as the field name.
+ */
+export async function readConstructionFailure(modules, constructionId) {
+    try {
+        const result = await modules.blueprintConstruction
+            .findOne({ id: constructionId, select: { error: true } })
+            .unwrap();
+        const row = result.blueprintConstruction;
+        return describeConstructionError(row?.error) ?? 'the backend gave no reason';
+    }
+    catch (err) {
+        return `the backend gave no reason (reading it failed: ${errorText(err)})`;
+    }
+}
+/**
+ * Wait for a construction to finish. Resolves with its table map once it is
+ * constructed, and throws with the backend's coded error once it failed, or
+ * when the deadline passes, the signal aborts, or its status can't be read.
+ */
+export async function waitForConstruction(modules, constructionId, options = {}) {
+    const { signal, deadlineMs = CONSTRUCTION_DEADLINE_MS, pollMs = CONSTRUCTION_POLL_MS, now = Date.now, sleep = abortableSleep, } = options;
+    const deadline = now() + deadlineMs;
+    let status = 'pending';
+    let readFailures = 0;
+    for (;;) {
+        if (signal?.aborted)
+            throw stopped();
+        let row;
+        try {
+            const result = await modules.blueprintConstruction
+                .findOne({ id: constructionId, select: { status: true, tableMap: true } })
+                .unwrap();
+            row = result.blueprintConstruction;
+            readFailures = 0;
+        }
+        catch (err) {
+            // A GraphQL error is the backend's answer and won't change on a reread.
+            if (!isTransientProvisionError(err) || ++readFailures >= MAX_CONSECUTIVE_READ_FAILURES) {
+                throw new Error(`Could not read the blueprint build's status: ${errorText(err)}. ${MAY_STILL_FINISH}`);
+            }
+        }
+        if (row === null)
+            throw new Error(`The backend has no blueprint construction ${constructionId}.`);
+        if (row?.status === 'constructed')
+            return tableMapOf(row.tableMap);
+        if (row?.status === 'failed') {
+            throw new Error(`The blueprint build failed: ${await readConstructionFailure(modules, constructionId)}`);
+        }
+        status = row?.status ?? status;
+        if (now() >= deadline) {
+            const where = status === 'pending' ? "waiting in the backend's build queue" : 'building';
+            throw new Error(`The blueprint build was still ${where} after ${Math.round(deadlineMs / 1000)} s. ${MAY_STILL_FINISH}`);
+        }
+        await sleep(pollMs, signal);
+    }
+}
+/**
+ * A build that failed after the backend queued it, or that the wait gave up
+ * on. The construction carries on without the caller, so constructing again
+ * would queue the same tables a second time.
+ */
+export class BlueprintBuildError extends Error {
+    constructionId;
+    constructor(message, constructionId) {
+        super(message);
+        this.name = 'BlueprintBuildError';
+        this.constructionId = constructionId;
+    }
+}
+/**
+ * Construct a blueprint into a schema and wait for the build. Resolves with
+ * the construction and the created tables. Once the backend has queued the
+ * build, every failure is a BlueprintBuildError with its construction id.
+ */
+export async function buildBlueprint(modules, input, options = {}) {
+    const result = await modules.mutation
+        .constructBlueprint({ input }, { select: { result: true } })
+        .unwrap();
+    const constructionId = result.constructBlueprint?.result;
+    if (!constructionId)
+        throw new Error('constructBlueprint returned no construction id');
+    try {
+        return { constructionId, tables: await waitForConstruction(modules, constructionId, options) };
+    }
+    catch (err) {
+        throw new BlueprintBuildError(errorText(err), constructionId);
+    }
+}

package/esm/context.d.ts

@@ -1,4 +1,5 @@
 import { api, modules } from '@constructive-io/sdk';
+import { type UnreachableCause } from './db-probe';
 export type ApiClient = ReturnType<typeof api.createClient>;
 export type ModulesClient = ReturnType<typeof modules.createClient>;
 export type ProjectContext = {
@@ -12,12 +13,15 @@ export type ProjectContext = {
     databaseName: string;
     accessToken: string;
     dataEndpoint: string;
+    hash?: string;
 };
-export type ProjectContextFailureCode = 'no-env' | 'missing-credentials' | 'db-missing' | 'account-mismatch' | 'backend-unreachable' | 'schema-unresolved';
+export type ProjectContextFailureCode = 'no-env' | 'missing-credentials' | 'db-missing' | 'db-suspended' | 'account-mismatch' | 'backend-unreachable' | 'schema-unresolved';
 export type ResolveResult = {
     context: ProjectContext | null;
     reason: string;
     code?: ProjectContextFailureCode;
+    /** Why the backend couldn't answer, with code 'backend-unreachable'. */
+    cause?: UnreachableCause;
 };
 export declare const CONTEXT_ENV_KEYS: readonly ["ACCESS_TOKEN", "DATABASE_ID", "API_ENDPOINT", "MODULES_ENDPOINT", "DATABASE_NAME", "OWNER_ID"];
 export type ContextEnvKey = (typeof CONTEXT_ENV_KEYS)[number];

package/esm/context.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { api, auth, modules } from '@constructive-io/sdk';
 import { parseDotenv } from '12factor-env/dotenv';
 import { probeDatabase } from './db-probe';
-import { DEFAULT_DATA_TOKEN_SKEW_MS, getHost } from './host';
+import { DEFAULT_DATA_TOKEN_SKEW_MS, getHost, reprovisionAdvice } from './host';
 const DEFAULT_API_ENDPOINT = 'http://api.localhost:3000/graphql';
 const DEFAULT_MODULES_ENDPOINT = 'http://modules.localhost:3000/graphql';
 // The project values pi needs, and where they come from. A scaffolded project
@@ -107,17 +107,18 @@ export async function resolveProjectContext(input, options = {}) {
         databaseId,
         signInHint: host.signInHint,
     });
-    if (probe.outcome === 'unreachable') {
+    if (probe.status === 'unreachable') {
         return {
             context: null,
-            reason: `Could not reach the Constructive backend at ${controlApiEndpoint} (${probe.detail}). Check it is running, then retry.`,
+            reason: unreachableReason(controlApiEndpoint, probe.cause, probe.detail),
             code: 'backend-unreachable',
+            cause: probe.cause,
         };
     }
-    if (probe.outcome === 'missing') {
+    if (probe.status === 'missing') {
         return {
             context: null,
-            reason: `The bound database (DATABASE_ID=${databaseId}) no longer exists on this backend. Re-provision with provision_database (reprovision: true) — the schema is rebuilt from the project; records do not carry over.`,
+            reason: `The bound database (DATABASE_ID=${databaseId}) no longer exists on this backend, or this account lost access to it. ${reprovisionAdvice(host)}`,
             code: 'db-missing',
         };
     }
@@ -134,10 +135,20 @@ export async function resolveProjectContext(input, options = {}) {
         probe.ownerId !== sessionUserId) {
         return {
             context: null,
-            reason: `The bound database (DATABASE_ID=${databaseId}) was provisioned under a different account than the one signed in. Re-provision with provision_database (reprovision: true) to rebuild it under this account — the schema is rebuilt from the project; records do not carry over.`,
+            reason: `The bound database (DATABASE_ID=${databaseId}) was provisioned under a different account than the one signed in. ${reprovisionAdvice(host)}`,
             code: 'account-mismatch',
         };
     }
+    // A suspended database still holds its data, so it is never a reason to
+    // reprovision: nothing can read or change it until the hold is lifted.
+    if (probe.status === 'suspended') {
+        const why = probe.suspendedReason ? ` (${probe.suspendedReason})` : '';
+        return {
+            context: null,
+            reason: `The bound database (DATABASE_ID=${databaseId}) is suspended${why} since ${probe.suspendedAt}. Its data is kept, but nothing can read or change it until the suspension is lifted.`,
+            code: 'db-suspended',
+        };
+    }
     const databaseName = env.DATABASE_NAME || probe.name || '';
     const ownerId = probe.ownerId || env.OWNER_ID || undefined;
     const dataEndpoint = databaseName
@@ -160,10 +171,24 @@ export async function resolveProjectContext(input, options = {}) {
             databaseName,
             accessToken,
             dataEndpoint,
+            hash: probe.hash,
         },
         reason: '',
     };
 }
+function unreachableReason(endpoint, cause, detail) {
+    switch (cause) {
+        case 'auth':
+            // The probe's detail says the credential was rejected and how to sign in.
+            return `Could not check the bound database on the Constructive backend at ${endpoint}: ${detail}`;
+        case 'error':
+            return `The Constructive backend at ${endpoint} answered with an error while checking the bound database (${detail}). Retry; if it keeps failing, check the backend's logs.`;
+        case 'server':
+            return `The Constructive backend at ${endpoint} is failing (${detail}). Check it is running, then retry.`;
+        default:
+            return `Could not reach the Constructive backend at ${endpoint} (${detail}). Check it is running, then retry.`;
+    }
+}
 const needsAuthReason = () => `Not signed in to the app database yet. ${getHost().signInHint ??
     'Sign in from the Sheets tab, or open the Preview and sign in to your app, then try again.'}`;
 // Resolve a data-plane token for record operations: serve the broker's active