@agentic-kit/pi 0.17.1 → 0.18.1

package/context.js

@@ -1,282 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.CONTEXT_ENV_PREFIX = exports.CONTEXT_ENV_KEYS = void 0;
-exports.fromEnvironment = fromEnvironment;
-exports.fromEnvFile = fromEnvFile;
-exports.resolveProjectContext = resolveProjectContext;
-exports.resolveDataToken = resolveDataToken;
-exports.deriveSubdomainEndpoint = deriveSubdomainEndpoint;
-exports.resolveOrgName = resolveOrgName;
-const promises_1 = require("node:fs/promises");
-const node_path_1 = __importDefault(require("node:path"));
-const sdk_1 = require("@constructive-io/sdk");
-const dotenv_1 = require("12factor-env/dotenv");
-const db_probe_1 = require("./db-probe");
-const host_1 = require("./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
-// folder carries them in `.env` (desktop); a headless host — a container, a
-// Job, CI — injects them as real environment variables, so no credential is
-// ever written into a git clone the agent could commit. Both lanes produce the
-// same record, which is why the resolver takes VALUES, not a directory.
-exports.CONTEXT_ENV_KEYS = [
-    'ACCESS_TOKEN',
-    'DATABASE_ID',
-    'API_ENDPOINT',
-    'MODULES_ENDPOINT',
-    'DATABASE_NAME',
-    'OWNER_ID',
-];
-/** Prefix for injected variables: `ACCESS_TOKEN` is far too generic to claim in
- *  a shared process environment, `CONSTRUCTIVE_ACCESS_TOKEN` is not. Inside a
- *  project `.env` the bare names stay readable (and are what the scaffolder
- *  writes), so both spellings resolve, prefixed winning. */
-exports.CONTEXT_ENV_PREFIX = 'CONSTRUCTIVE_';
-const lookup = (source) => typeof source === 'function' ? source : (name) => source[name];
-const readContextValue = (source, key) => {
-    const get = lookup(source);
-    const value = get(`${exports.CONTEXT_ENV_PREFIX}${key}`) ?? get(key);
-    return value ? value : undefined;
-};
-/** Use the process environment (or any injected record) as the source. */
-function fromEnvironment(environment = process.env) {
-    return environment;
-}
-/** Read a project `.env` as the source. The file is authoritative here — the
- *  key in it belongs to whatever backend wrote it, so it is not merged under
- *  the ambient environment. Returns null when the file is absent. */
-async function fromEnvFile(cwd) {
-    try {
-        return (0, dotenv_1.parseDotenv)(await (0, promises_1.readFile)(node_path_1.default.join(cwd, '.env'), 'utf8'));
-    }
-    catch {
-        return null;
-    }
-}
-/**
- * Resolve the project context from injected values, or from a project folder.
- *
- * Passing a `cwd` string keeps the original behavior (read `<cwd>/.env`) so
- * existing hosts — Constructive Desktop, the confirm gate — are unchanged.
- * Headless hosts pass values instead: `fromEnvironment()` for a container or
- * Job, an explicit record for anything else.
- */
-async function resolveProjectContext(input, options = {}) {
-    const source = typeof input === 'string' ? await fromEnvFile(input) : input;
-    if (!source) {
-        return {
-            context: null,
-            reason: 'No .env found in the project. Provision a Constructive database first (scaffold the project), then retry.',
-            code: 'no-env',
-        };
-    }
-    const env = Object.fromEntries(exports.CONTEXT_ENV_KEYS.map((key) => [key, readContextValue(source, key)]));
-    const accessToken = env.ACCESS_TOKEN;
-    const databaseId = env.DATABASE_ID;
-    if (!accessToken || !databaseId) {
-        return {
-            context: null,
-            reason: `Project is not connected to a Constructive database yet (missing ${exports.CONTEXT_ENV_PREFIX}ACCESS_TOKEN/${exports.CONTEXT_ENV_PREFIX}DATABASE_ID in the environment, or ACCESS_TOKEN/DATABASE_ID in .env). Provision the database first, then retry.`,
-            code: 'missing-credentials',
-        };
-    }
-    // A source-supplied pin wins for the DATA plane (the access key belongs to
-    // whatever backend wrote it); otherwise fall back to the app's backend-config
-    // store (environment-aware) so app + harness share one endpoint source.
-    const host = (0, host_1.getHost)();
-    const backend = host.backendConfig();
-    const apiEndpoint = env.API_ENDPOINT || backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
-    const modulesEndpoint = env.MODULES_ENDPOINT || backend?.modulesEndpoint || DEFAULT_MODULES_ENDPOINT;
-    // The whole control plane (binding probe, schema resolution, blueprint/schema
-    // tools) authenticates with the ACCOUNT bearer: the platform api rejects
-    // per-database keys, so the project ACCESS_TOKEN can never act on metaschema
-    // surfaces. The source's key stays in the context for the data plane only.
-    // The bearer is only ever sent to the app-configured backend — never a
-    // source-pinned endpoint, which an untrusted cloned project controls.
-    const controlApiEndpoint = backend?.apiEndpoint || DEFAULT_API_ENDPOINT;
-    const controlModulesEndpoint = backend?.modulesEndpoint || DEFAULT_MODULES_ENDPOINT;
-    const account = host.account();
-    const accountBearer = account?.apiKey ?? account?.accessToken;
-    if (!accountBearer) {
-        return {
-            context: null,
-            reason: `No usable account credential to reach the Constructive control plane. ${host.signInHint ?? 'Sign in to the app, then retry.'}`,
-            code: 'missing-credentials',
-        };
-    }
-    const controlHeaders = { Authorization: `Bearer ${accountBearer}` };
-    const apiClient = sdk_1.api.createClient({ endpoint: controlApiEndpoint, headers: controlHeaders });
-    // Always probe the bound database — the DATABASE_ID stamp proves it WAS
-    // bound, never that the database still exists (backend refresh, deletion,
-    // revoked key). The probe is the single source of binding health.
-    const probe = await (0, db_probe_1.probeDatabase)({
-        endpoint: controlApiEndpoint,
-        bearer: accountBearer,
-        databaseId,
-        signInHint: host.signInHint,
-    });
-    if (probe.outcome === 'unreachable') {
-        return {
-            context: null,
-            reason: `Could not reach the Constructive backend at ${controlApiEndpoint} (${probe.detail}). Check it is running, then retry.`,
-            code: 'backend-unreachable',
-        };
-    }
-    if (probe.outcome === '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.`,
-            code: 'db-missing',
-        };
-    }
-    // Schemas are account-scoped: a live binding under a different account is
-    // never shown in the Schemas tab or written to by the agent. The project's
-    // local blueprint survives account changes, so recovery is a reprovision
-    // under the signed-in account. Owner truth comes from the probe (backend),
-    // not the source's stamp. Data-plane resolution skips this gate — see
-    // ResolveOptions.
-    const sessionUserId = account?.userId;
-    if (options.plane !== 'data' &&
-        probe.ownerId &&
-        sessionUserId &&
-        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.`,
-            code: 'account-mismatch',
-        };
-    }
-    const databaseName = env.DATABASE_NAME || probe.name || '';
-    const ownerId = probe.ownerId || env.OWNER_ID || undefined;
-    const dataEndpoint = databaseName
-        ? deriveSubdomainEndpoint(apiEndpoint, `api-${databaseName}`)
-        : '';
-    const schemaId = await resolveSchemaId(apiClient, databaseId);
-    if (!schemaId) {
-        return {
-            context: null,
-            reason: 'Could not resolve a schema (app_public/public) for this database. The database may not be fully provisioned yet.',
-            code: 'schema-unresolved',
-        };
-    }
-    return {
-        context: {
-            api: apiClient,
-            modules: sdk_1.modules.createClient({ endpoint: controlModulesEndpoint, headers: controlHeaders }),
-            databaseId,
-            schemaId,
-            ownerId,
-            apiEndpoint,
-            modulesEndpoint,
-            databaseName,
-            accessToken,
-            dataEndpoint,
-        },
-        reason: '',
-    };
-}
-const needsAuthReason = () => `Not signed in to the app database yet. ${(0, host_1.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
-// account while valid, otherwise harvest the token the user created by signing
-// into their app in the Preview and adopt it into the broker. Also returns the
-// signed-in user's id (used to scope rows by entityId). Returns a reason (no
-// token) when neither source has a valid token — the caller surfaces a sign-in
-// prompt.
-async function resolveDataToken(context) {
-    const host = (0, host_1.getHost)();
-    const broker = host.dataAuthBroker;
-    const active = broker?.getActiveToken(context.databaseId);
-    if (active)
-        return { token: active.token, userId: active.userId };
-    const preview = host.previewToken ? await host.previewToken() : null;
-    if (!preview)
-        return { reason: needsAuthReason() };
-    if (broker?.isInvalidToken(context.databaseId, preview.accessToken)) {
-        return { reason: needsAuthReason() };
-    }
-    const parsed = preview.accessTokenExpiresAt ? Date.parse(preview.accessTokenExpiresAt) : NaN;
-    const expiresAt = Number.isNaN(parsed) ? Date.now() + 60 * 60 * 1000 : parsed;
-    const skewMs = host.dataTokenSkewMs ?? host_1.DEFAULT_DATA_TOKEN_SKEW_MS;
-    if (expiresAt <= Date.now() + skewMs)
-        return { reason: needsAuthReason() };
-    broker?.adoptToken(context.databaseId, {
-        userId: preview.userId,
-        token: preview.accessToken,
-        expiresAt,
-        origin: 'harvest',
-    });
-    return { token: preview.accessToken, userId: preview.userId };
-}
-// Per-DB endpoints are deterministic on the provisioning subdomain (= DATABASE_NAME):
-// each plane swaps the first host label of its control-plane endpoint
-// (e.g. api.localhost -> api-myapp.localhost, auth.localhost -> auth-myapp.localhost).
-function deriveSubdomainEndpoint(baseEndpoint, firstLabel) {
-    try {
-        const url = new URL(baseEndpoint);
-        const labels = url.hostname.split('.');
-        labels[0] = firstLabel;
-        url.hostname = labels.join('.');
-        return url.toString();
-    }
-    catch {
-        return '';
-    }
-}
-// The backend hierarchy is org -> db -> tables; the owning org is the auth-plane
-// user the database's ownerId points at. Best-effort display lookup only —
-// binding health never depends on it. Authenticates with the account bearer
-// against the app-configured auth endpoint (the platform rejects per-database
-// keys, and the bearer never goes to a .env-pinned endpoint).
-async function resolveOrgName(ownerId) {
-    try {
-        const host = (0, host_1.getHost)();
-        const account = host.account();
-        const bearer = account?.apiKey ?? account?.accessToken;
-        if (!bearer)
-            return undefined;
-        const backend = host.backendConfig();
-        const authEndpoint = deriveSubdomainEndpoint(backend?.apiEndpoint || DEFAULT_API_ENDPOINT, 'auth');
-        if (!authEndpoint)
-            return undefined;
-        const client = sdk_1.auth.createClient({
-            endpoint: authEndpoint,
-            headers: { Authorization: `Bearer ${bearer}` },
-        });
-        const result = await client.user
-            .findMany({
-            select: { displayName: true, username: true },
-            where: { id: { equalTo: ownerId } },
-        })
-            .execute();
-        if (!result.ok)
-            return undefined;
-        const node = (result.data.users?.nodes ?? [])[0];
-        return node?.displayName || node?.username || undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-async function resolveSchemaId(apiClient, databaseId) {
-    const result = await apiClient.schema
-        .findMany({
-        select: { id: true, name: true },
-        where: { databaseId: { equalTo: databaseId } },
-    })
-        .execute();
-    if (!result.ok)
-        return undefined;
-    const nodes = (result.data.schemas?.nodes ?? []).filter((s) => Boolean(s && s.id));
-    const appPublic = nodes.find((s) => s.name === 'app_public');
-    if (appPublic)
-        return appPublic.id;
-    const pub = nodes.find((s) => s.name === 'public');
-    if (pub)
-        return pub.id;
-    return nodes[0]?.id;
-}

package/db-probe.d.ts

@@ -1,30 +0,0 @@
-export type DatabaseProbe = {
-    outcome: 'found';
-    name?: string;
-    ownerId?: string;
-} | {
-    outcome: 'missing';
-} | {
-    outcome: 'unreachable';
-    detail: string;
-};
-export type ProbeExecutor = {
-    execute<T>(document: string, variables?: Record<string, unknown>): Promise<{
-        ok: true;
-        data: T;
-        errors: undefined;
-    } | {
-        ok: false;
-        data: null;
-        errors: {
-            message: string;
-        }[];
-    }>;
-};
-export declare function probeDatabase(args: {
-    endpoint: string;
-    bearer: string;
-    databaseId: string;
-    executor?: ProbeExecutor;
-    signInHint?: string;
-}): Promise<DatabaseProbe>;

package/db-probe.js

@@ -1,50 +0,0 @@
-"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.
-//
-// 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.
-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)) {
-            return {
-                outcome: 'unreachable',
-                detail: `${detail} — the account credential was rejected. ${args.signInHint ?? 'Sign in again, then retry.'}`,
-            };
-        }
-        return { outcome: 'missing' };
-    }
-    catch (err) {
-        return { outcome: 'unreachable', detail: err instanceof Error ? err.message : String(err) };
-    }
-}

package/esm/app-workspace.d.ts

@@ -1,16 +0,0 @@
-export declare const NATIVE_BUILD_DEPS: string[];
-export declare const IGNORED_BUILDS_RE: RegExp;
-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<{
-    ok: boolean;
-    out: string;
-}>;
-export declare function prewarmAppWorkspace(cwd: string): Promise<{
-    ok: boolean;
-    out: string;
-}>;

package/esm/app-workspace.js

@@ -1,134 +0,0 @@
-import { execFile } from 'node:child_process';
-import { existsSync } from 'node:fs';
-import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
-import os from 'node:os';
-import path from 'node:path';
-import { promisify } from 'node:util';
-const execFileAsync = promisify(execFile);
-// pnpm 11.8 no longer reads the `pnpm` field from a non-root package.json, so the
-// template's `pnpm.overrides.graphql` (in packages/app/package.json) is silently
-// ignored. Without that override two graphql versions (16.13.0 + 16.14.0) get
-// installed, which instantiates two copies of `grafast` under DIFFERENT
-// peer-dependency hash contexts. graphile-search then resolves in one context
-// while graphile-connection-filter was linked under the other, so codegen dies
-// with `Cannot find module 'graphile-connection-filter'`. Hoisting the override
-// to the ROOT pnpm-workspace.yaml (which pnpm 11.8 DOES read) collapses graphql —
-// and therefore grafast — to a single version, and the missing module resolves
-// (PNPM-GRAPHQL-OVERRIDE-001). We also strip the nested packages/app
-// pnpm-workspace.yaml the template ships, and keep onlyBuiltDependencies so the
-// native deps build where honored (PNPM-BUILDS-001).
-export const NATIVE_BUILD_DEPS = ['esbuild', 'sharp', 'unrs-resolver'];
-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');
-export async function run(cmd, args, cwd, env) {
-    try {
-        const { stdout, stderr } = await execFileAsync(cmd, args, {
-            cwd,
-            timeout: 5 * 60_000,
-            encoding: 'utf-8',
-            maxBuffer: 32 * 1024 * 1024,
-            env: env ? { ...process.env, ...env } : process.env,
-        });
-        return { ok: true, out: `${stdout}${stderr}`.trim() };
-    }
-    catch (err) {
-        const e = err;
-        return { ok: false, out: `${e.stdout ?? ''}${e.stderr ?? ''}`.trim() || e.message || 'failed' };
-    }
-}
-// Read the graphql pin the template wants from its (now-ignored) pnpm.overrides
-// so we propagate the template's own value instead of hardcoding ours.
-async function templateGraphqlOverride(cwd) {
-    try {
-        const pkg = JSON.parse(await readFile(path.join(cwd, 'packages', 'app', 'package.json'), 'utf8'));
-        const v = pkg?.pnpm?.overrides?.graphql;
-        return typeof v === 'string' && v.length > 0 ? v : DEFAULT_GRAPHQL_OVERRIDE;
-    }
-    catch {
-        return DEFAULT_GRAPHQL_OVERRIDE;
-    }
-}
-export async function ensureWorkspaceConfig(cwd) {
-    const nested = path.join(cwd, 'packages', 'app', 'pnpm-workspace.yaml');
-    if (existsSync(nested)) {
-        await rm(nested, { force: true });
-    }
-    const graphqlPin = await templateGraphqlOverride(cwd);
-    const builds = NATIVE_BUILD_DEPS.map((d) => `  - ${d}`).join('\n');
-    const text = `packages:\n  - "packages/*"\n\n` +
-        `overrides:\n  graphql: ${graphqlPin}\n\n` +
-        `onlyBuiltDependencies:\n${builds}\n`;
-    await writeFile(path.join(cwd, 'pnpm-workspace.yaml'), text);
-}
-// Force @constructive-io/graphql-codegen to `latest` in the app package.json
-// before the single install — older 4.9.x throws on PostGraphile `filter` inputs
-// (TS-001).
-export async function pinCodegenLatest(appDir) {
-    const pkgPath = path.join(appDir, 'package.json');
-    const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
-    for (const field of ['devDependencies', 'dependencies']) {
-        if (pkg[field]?.['@constructive-io/graphql-codegen']) {
-            pkg[field]['@constructive-io/graphql-codegen'] = 'latest';
-        }
-    }
-    await writeFile(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`);
-}
-// The Constructive Next.js app is just the `nextjs/constructive-app` tree from
-// the sandbox-templates repo — it ships no `____VAR____` placeholders, so there
-// is nothing to templatize. `pgpm init` only fetches and copies that tree, but
-// 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) {
-    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);
-    if (!clone.ok) {
-        await rm(tmp, { recursive: true, force: true });
-        return { ok: false, out: `Template clone failed:\n${clone.out}` };
-    }
-    const src = path.join(tmp, TEMPLATE_SUBDIR);
-    if (!existsSync(src)) {
-        await rm(tmp, { recursive: true, force: true });
-        return { ok: false, out: `Template subdir ${TEMPLATE_SUBDIR} missing in ${TEMPLATE_REPO}` };
-    }
-    try {
-        await mkdir(path.dirname(appDir), { recursive: true });
-        await cp(src, appDir, { recursive: true });
-    }
-    catch (err) {
-        await rm(tmp, { recursive: true, force: true });
-        return {
-            ok: false,
-            out: `Copying template into packages/app failed: ${err instanceof Error ? err.message : String(err)}`,
-        };
-    }
-    await rm(tmp, { recursive: true, force: true });
-    return { ok: true, out: 'Scaffolded packages/app from the constructive-app template.' };
-}
-// 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);
-    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);
-    if (!install.ok && !IGNORED_BUILDS_RE.test(install.out)) {
-        return { ok: false, out: `pnpm install failed:\n${install.out}` };
-    }
-    return { ok: true, out: 'Prewarmed packages/app scaffold + install.' };
-}

package/esm/context.d.ts

@@ -1,62 +0,0 @@
-import { api, modules } from '@constructive-io/sdk';
-export type ApiClient = ReturnType<typeof api.createClient>;
-export type ModulesClient = ReturnType<typeof modules.createClient>;
-export type ProjectContext = {
-    api: ApiClient;
-    modules: ModulesClient;
-    databaseId: string;
-    schemaId: string;
-    ownerId: string | undefined;
-    apiEndpoint: string;
-    modulesEndpoint: string;
-    databaseName: string;
-    accessToken: string;
-    dataEndpoint: string;
-};
-export type ProjectContextFailureCode = 'no-env' | 'missing-credentials' | 'db-missing' | 'account-mismatch' | 'backend-unreachable' | 'schema-unresolved';
-export type ResolveResult = {
-    context: ProjectContext | null;
-    reason: string;
-    code?: ProjectContextFailureCode;
-};
-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];
-/** Prefix for injected variables: `ACCESS_TOKEN` is far too generic to claim in
- *  a shared process environment, `CONSTRUCTIVE_ACCESS_TOKEN` is not. Inside a
- *  project `.env` the bare names stay readable (and are what the scaffolder
- *  writes), so both spellings resolve, prefixed winning. */
-export declare const CONTEXT_ENV_PREFIX = "CONSTRUCTIVE_";
-/** Values keyed by name, or a lookup function (a host with a secret store). */
-export type ContextSource = Record<string, string | undefined> | ((name: string) => string | undefined);
-/** Use the process environment (or any injected record) as the source. */
-export declare function fromEnvironment(environment?: Record<string, string | undefined>): ContextSource;
-/** Read a project `.env` as the source. The file is authoritative here — the
- *  key in it belongs to whatever backend wrote it, so it is not merged under
- *  the ambient environment. Returns null when the file is absent. */
-export declare function fromEnvFile(cwd: string): Promise<ContextSource | null>;
-export type ResolveOptions = {
-    /** Which plane the context is for. Ownership gates the control plane only:
-     *  schema editing and provisioning act under the signed-in account, so a
-     *  foreign-owned binding is blocked ('account-mismatch'). The data plane
-     *  (real rows via app end-user tokens) never checks desktop-account
-     *  ownership — a live foreign-owned database serves data fine, exactly as
-     *  the app itself does in the Preview. */
-    plane?: 'control' | 'data';
-};
-/**
- * Resolve the project context from injected values, or from a project folder.
- *
- * Passing a `cwd` string keeps the original behavior (read `<cwd>/.env`) so
- * existing hosts — Constructive Desktop, the confirm gate — are unchanged.
- * Headless hosts pass values instead: `fromEnvironment()` for a container or
- * Job, an explicit record for anything else.
- */
-export declare function resolveProjectContext(input: string | ContextSource, options?: ResolveOptions): Promise<ResolveResult>;
-export type DataTokenResult = {
-    token?: string;
-    userId?: string;
-    reason?: string;
-};
-export declare function resolveDataToken(context: ProjectContext): Promise<DataTokenResult>;
-export declare function deriveSubdomainEndpoint(baseEndpoint: string, firstLabel: string): string;
-export declare function resolveOrgName(ownerId: string): Promise<string | undefined>;