@agentic-kit/db-tools 0.2.0

package/esm/context.js

@@ -0,0 +1,270 @@
+import { readFile } from 'node:fs/promises';
+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';
+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.
+export const 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. */
+export const 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(`${CONTEXT_ENV_PREFIX}${key}`) ?? get(key);
+    return value ? value : undefined;
+};
+/** Use the process environment (or any injected record) as the source. */
+export 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. */
+export async function fromEnvFile(cwd) {
+    try {
+        return parseDotenv(await readFile(path.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.
+ */
+export 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(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 ${CONTEXT_ENV_PREFIX}ACCESS_TOKEN/${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 = 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 = 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 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: 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. ${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.
+export async function resolveDataToken(context) {
+    const host = 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 ?? 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).
+export 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).
+export async function resolveOrgName(ownerId) {
+    try {
+        const host = 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 = 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/esm/db-probe.d.ts

@@ -0,0 +1,30 @@
+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/esm/db-probe.js

@@ -0,0 +1,47 @@
+import { api } from '@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.
+export async function probeDatabase(args) {
+    const executor = args.executor ??
+        new 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/host.d.ts

@@ -0,0 +1,115 @@
+/**
+ * Host contract for the Constructive database tools.
+ *
+ * The typed db tools were extracted from Constructive Desktop, where they read
+ * an Electron-side `runtime` singleton (account store, backend config, data-auth
+ * broker, preview token). Hosts now inject the same surface here once at
+ * startup (`configureHost`); the tool modules stay module-level `HarnessTool`
+ * consts and read it lazily via `getHost()`.
+ *
+ * Nothing here is harness-specific: the host is the *application* a tool acts
+ * on behalf of, so the same contract serves whichever adapter runs the tools.
+ */
+export type HostAccount = {
+    userId: string;
+    accessToken: string;
+    apiKey?: string;
+};
+export type HostBackendConfig = {
+    apiEndpoint?: string;
+    modulesEndpoint?: string;
+};
+export type ActiveDataToken = {
+    token: string;
+    userId?: string;
+    expiresAt: number;
+    origin?: string;
+};
+/**
+ * Optional data-plane token broker: remembers per-database end-user tokens
+ * across tool calls and invalidates declined/expired ones. Hosts without a
+ * broker fall back to the preview-token harvest on every call.
+ */
+export interface DataAuthBroker {
+    getActiveToken(databaseId: string): ActiveDataToken | undefined | null;
+    isInvalidToken(databaseId: string, token: string): boolean;
+    adoptToken(databaseId: string, token: ActiveDataToken): void;
+}
+/** Token harvested from the host's app preview (end-user sign-in). */
+export type PreviewToken = {
+    accessToken: string;
+    accessTokenExpiresAt?: string;
+    userId?: string;
+};
+/**
+ * Overlay layered over the pinned base preset when provisioning a database.
+ * Structurally the `ProvisionOverlay` from `provision-database/resolve`; typed
+ * loosely here to keep `host.ts` free of provision-internal imports.
+ */
+export interface HostProvisionOverlay {
+    preset?: string;
+    add?: (string | [string, Record<string, unknown>])[];
+    remove?: string[];
+}
+/**
+ * A minted secret handed to the host for out-of-band delivery (.env write +
+ * one-time reveal). The plaintext never enters tool results or the transcript;
+ * the harness forgets it after this call.
+ */
+export type SecretDelivery = {
+    databaseId: string;
+    /** Project directory whose `.env` receives the key. */
+    cwd: string;
+    envVar: string;
+    plaintext: string;
+    keyId: string;
+    expiresAt?: string;
+};
+/**
+ * Context for a host-side step-up: enough to derive the per-database auth
+ * endpoint and look up the app session without re-resolving the project.
+ */
+export type StepUpRequest = {
+    databaseId: string;
+    databaseName: string;
+    apiEndpoint: string;
+};
+export interface ToolsHost {
+    /** Signed-in platform account, or null/undefined when signed out. */
+    account(): HostAccount | null | undefined;
+    /** Host-configured backend endpoints (env-aware). */
+    backendConfig(): HostBackendConfig | null | undefined;
+    /** Optional data-plane token broker (see DataAuthBroker). */
+    dataAuthBroker?: DataAuthBroker;
+    /**
+     * Host-specific sign-in instruction, substituted into signed-out failure
+     * reasons (e.g. the CLI's "Run `agent login` to sign in."). Absent hosts get
+     * the desktop wording.
+     */
+    signInHint?: string;
+    /** Harvest an end-user token from the host's app preview, if it has one. */
+    previewToken?(): Promise<PreviewToken | null>;
+    /** Treat tokens expiring within this window as already expired. Default 30s. */
+    dataTokenSkewMs?: number;
+    /**
+     * Optional provision overlay: pick a base preset and/or layer module
+     * add/remove on top of it. The base module list always comes from the pinned
+     * `node-type-registry` preset — this only customizes it. Distributed as data
+     * (e.g. materialized from appstash / a pinned git ref), never as code.
+     */
+    provisionOverlay?(): HostProvisionOverlay | null | undefined | Promise<HostProvisionOverlay | null | undefined>;
+    /**
+     * Complete MFA step-up for the database's app session in the host's own
+     * process (password dialog + verifyPassword). The password never passes
+     * through the harness or the model. Resolve true when step-up succeeded.
+     */
+    requestStepUp?(request: StepUpRequest): Promise<boolean>;
+    /**
+     * Deliver a minted secret to the user (.env write + one-time reveal).
+     * Required for create_api_key — without it the tool refuses to mint.
+     */
+    deliverSecret?(delivery: SecretDelivery): Promise<void>;
+}
+export declare const DEFAULT_DATA_TOKEN_SKEW_MS = 30000;
+export declare function configureHost(host: ToolsHost): void;
+export declare function getHost(): ToolsHost;

package/esm/host.js

@@ -0,0 +1,23 @@
+/**
+ * Host contract for the Constructive database tools.
+ *
+ * The typed db tools were extracted from Constructive Desktop, where they read
+ * an Electron-side `runtime` singleton (account store, backend config, data-auth
+ * broker, preview token). Hosts now inject the same surface here once at
+ * startup (`configureHost`); the tool modules stay module-level `HarnessTool`
+ * consts and read it lazily via `getHost()`.
+ *
+ * Nothing here is harness-specific: the host is the *application* a tool acts
+ * on behalf of, so the same contract serves whichever adapter runs the tools.
+ */
+export const DEFAULT_DATA_TOKEN_SKEW_MS = 30_000;
+let currentHost = null;
+export function configureHost(host) {
+    currentHost = host;
+}
+export function getHost() {
+    if (!currentHost) {
+        throw new Error('@agentic-kit/db-tools host not configured. Call configureHost() (or createDbTools(host)) before using the db tools.');
+    }
+    return currentHost;
+}

package/esm/index.d.ts

@@ -0,0 +1,20 @@
+import type { AnyHarnessTool } from '@agentic-kit/harness';
+import { type ToolsHost } from './host';
+/**
+ * The Constructive database tools, in registration order.
+ *
+ * Plain `HarnessTool`s: a harness gets them by mapping them into its own tool
+ * shape, which is the adapter's job, so this package stays free of any harness
+ * dependency (see `toPiTool` in `@agentic-kit/pi` for that binding).
+ */
+export declare const constructiveDbTools: readonly AnyHarnessTool[];
+/** Configure the host and get the tools in one call. */
+export declare function createConstructiveDbTools(host: ToolsHost): readonly AnyHarnessTool[];
+export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, type ContextEnvKey, type ContextSource, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, type ModulesClient, type ProjectContext, type ProjectContextFailureCode, resolveDataToken, resolveProjectContext, } from './context';
+export { type ActiveDataToken, configureHost, type DataAuthBroker, DEFAULT_DATA_TOKEN_SKEW_MS, getHost, type HostAccount, type HostBackendConfig, type HostProvisionOverlay, type PreviewToken, type SecretDelivery, type StepUpRequest, type ToolsHost, } from './host';
+export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, type ProvisionManifest, } from './provision-database/manifest';
+export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, type ModulePreset, type ProvisionModule, } from './provision-database/presets';
+export { moduleKey, type ProvisionOverlay, resolveProvisionModules, } from './provision-database/resolve';
+export { toolSchema } from './tool-schema';
+export { createTemplatePreviewTables } from './tools/templates';
+export default constructiveDbTools;

package/esm/index.js

@@ -0,0 +1,52 @@
+import { configureHost } from './host';
+import { addPoliciesTool } from './tools/add-policies';
+import { addRecordsTool } from './tools/add-records';
+import { addRelationTool } from './tools/add-relation';
+import { createApiKeyTool } from './tools/create-api-key';
+import { describeSchemaTool } from './tools/describe-schema';
+import { manageEntityTypesTool } from './tools/manage-entity-types';
+import { createFieldTool, deleteFieldTool, deleteTableTool, updateFieldTool } from './tools/mutations';
+import { provisionBlueprintTool } from './tools/provision-blueprint';
+import { provisionDatabaseTool } from './tools/provision-database';
+import { runCodegenTool } from './tools/run-codegen';
+import { applyTemplateTool, createTemplateTool, deleteTemplateTool, listTemplatesTool, updateTemplateTool, } from './tools/templates';
+/**
+ * The Constructive database tools, in registration order.
+ *
+ * Plain `HarnessTool`s: a harness gets them by mapping them into its own tool
+ * shape, which is the adapter's job, so this package stays free of any harness
+ * dependency (see `toPiTool` in `@agentic-kit/pi` for that binding).
+ */
+export const constructiveDbTools = [
+    provisionDatabaseTool,
+    describeSchemaTool,
+    listTemplatesTool,
+    provisionBlueprintTool,
+    addRelationTool,
+    deleteTableTool,
+    createFieldTool,
+    updateFieldTool,
+    deleteFieldTool,
+    addPoliciesTool,
+    applyTemplateTool,
+    createTemplateTool,
+    updateTemplateTool,
+    deleteTemplateTool,
+    addRecordsTool,
+    manageEntityTypesTool,
+    createApiKeyTool,
+    runCodegenTool,
+];
+/** Configure the host and get the tools in one call. */
+export function createConstructiveDbTools(host) {
+    configureHost(host);
+    return constructiveDbTools;
+}
+export { CONTEXT_ENV_KEYS, CONTEXT_ENV_PREFIX, deriveSubdomainEndpoint, fromEnvFile, fromEnvironment, resolveDataToken, resolveProjectContext, } from './context';
+export { configureHost, DEFAULT_DATA_TOKEN_SKEW_MS, getHost, } from './host';
+export { loadProvisionManifest, parseProvisionManifest, PROVISION_MANIFEST_FILE, } from './provision-database/manifest';
+export { allModulePresets, DEFAULT_PROVISION_PRESET, getModulePreset, } from './provision-database/presets';
+export { moduleKey, resolveProvisionModules, } from './provision-database/resolve';
+export { toolSchema } from './tool-schema';
+export { createTemplatePreviewTables } from './tools/templates';
+export default constructiveDbTools;

package/esm/policy/add-policies-to-table.d.ts

@@ -0,0 +1,26 @@
+import { type PolicyProvisioningCategory } from '@agentic-kit/harness';
+import type { ModulesClient } from '../context';
+import { type CrudOperation, type CrudPolicyConfigs } from './provision-helpers';
+export interface AddPoliciesToTablePolicyEntry {
+    policyType: string;
+    dataNodeType?: string;
+    nodeData?: Record<string, unknown>;
+    sharedPolicyData: Record<string, unknown>;
+    operations: CrudPolicyConfigs;
+    enabledOperations?: CrudOperation[];
+}
+export interface AddPoliciesToTableInput {
+    client: ModulesClient;
+    databaseId: string;
+    schemaId: string;
+    tableId: string;
+    policies: AddPoliciesToTablePolicyEntry[];
+}
+export declare class UnsupportedPolicyCategoryError extends Error {
+    readonly policyType: string;
+    readonly category: PolicyProvisioningCategory;
+    constructor(policyType: string, category: PolicyProvisioningCategory);
+}
+export declare function addPoliciesToExistingTable(input: AddPoliciesToTableInput): Promise<{
+    success: true;
+}>;

package/esm/policy/add-policies-to-table.js

@@ -0,0 +1,66 @@
+import { getPolicyCategory } from '@agentic-kit/harness';
+import { buildGrants, buildPolicyEntry, CRUD_OPERATIONS, groupOperationsByConfig, } from './provision-helpers';
+const SUPPORTED_CATEGORIES = new Set([
+    'has-module',
+    'no-fields',
+    'needs-table',
+]);
+export class UnsupportedPolicyCategoryError extends Error {
+    policyType;
+    category;
+    constructor(policyType, category) {
+        super(`Policy type "${policyType}" has category "${category}" which requires column creation or composite handling — use the policies UI instead.`);
+        this.policyType = policyType;
+        this.category = category;
+        this.name = 'UnsupportedPolicyCategoryError';
+    }
+}
+export async function addPoliciesToExistingTable(input) {
+    const { client } = input;
+    for (const entry of input.policies) {
+        const category = getPolicyCategory(entry.policyType);
+        if (!SUPPORTED_CATEGORIES.has(category)) {
+            throw new UnsupportedPolicyCategoryError(entry.policyType, category);
+        }
+    }
+    const policiesArray = [];
+    const nodesByType = new Map();
+    for (const entry of input.policies) {
+        const groups = groupOperationsByConfig(entry.enabledOperations ?? CRUD_OPERATIONS, entry.operations);
+        for (const group of groups) {
+            const ops = group.privileges.join('_');
+            const rand = Math.random().toString(36).slice(2, 8);
+            policiesArray.push(buildPolicyEntry(entry.policyType, {
+                privileges: group.privileges,
+                policy_role: group.roleName,
+                permissive: group.isPermissive,
+                data: entry.sharedPolicyData,
+                policy_name: `${ops}_${rand}`,
+            }));
+        }
+        if (entry.dataNodeType && !nodesByType.has(entry.dataNodeType)) {
+            const nodeData = entry.nodeData ?? {};
+            nodesByType.set(entry.dataNodeType, {
+                $type: entry.dataNodeType,
+                ...(Object.keys(nodeData).length > 0 ? { data: nodeData } : {}),
+            });
+        }
+    }
+    const provisionInput = {
+        databaseId: input.databaseId,
+        schemaId: input.schemaId,
+        tableId: input.tableId,
+        grants: buildGrants(),
+        policies: policiesArray,
+    };
+    if (nodesByType.size > 0) {
+        provisionInput.nodes = [...nodesByType.values()];
+    }
+    await client.secureTableProvision
+        .create({
+        data: provisionInput,
+        select: { id: true, tableId: true, tableName: true },
+    })
+        .unwrap();
+    return { success: true };
+}