@agentic-kit/db-tools 0.2.0

package/run-codegen/endpoints.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.derivePlaneEndpoints = derivePlaneEndpoints;
+exports.codegenEndpointEnv = codegenEndpointEnv;
+exports.envLocalContent = envLocalContent;
+// Codegen and the Next.js dev server default every per-DB vhost to
+// *-<db>.localhost:3000, which only exists on a local backend. Derive the real
+// vhosts from the api endpoint the binding belongs to by swapping its first
+// host label (api.launchql.dev -> admin-<db>.launchql.dev) — the same scheme
+// context.ts uses for the data plane. The app DATA plane is `api-<db>`, not
+// `app-<db>` (SUBDOMAIN-001).
+function derivePlaneEndpoints(apiEndpoint, databaseName) {
+    const derive = (label) => {
+        try {
+            const url = new URL(apiEndpoint);
+            const labels = url.hostname.split('.');
+            labels[0] = `${label}-${databaseName}`;
+            url.hostname = labels.join('.');
+            return url.toString();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const admin = derive('admin');
+    const auth = derive('auth');
+    const app = derive('api');
+    return admin && auth && app ? { admin, auth, app } : undefined;
+}
+// The template's graphql-codegen.config.ts honors CODEGEN_*_ENDPOINT for the
+// URL and CODEGEN_*_HOST for the Host header; set both so scheme and routing
+// stay in sync on any backend.
+function codegenEndpointEnv(planes) {
+    return {
+        CODEGEN_ADMIN_ENDPOINT: planes.admin,
+        CODEGEN_ADMIN_HOST: new URL(planes.admin).host,
+        CODEGEN_AUTH_ENDPOINT: planes.auth,
+        CODEGEN_AUTH_HOST: new URL(planes.auth).host,
+        CODEGEN_APP_ENDPOINT: planes.app,
+        CODEGEN_APP_HOST: new URL(planes.app).host,
+    };
+}
+// .env.local for the dev server: the template's runtime config falls back to
+// localhost vhosts unless NEXT_PUBLIC_*_ENDPOINT overrides are present.
+function envLocalContent(databaseName, planes) {
+    const lines = [`NEXT_PUBLIC_DB_NAME=${databaseName}`];
+    if (planes) {
+        lines.push(`NEXT_PUBLIC_ADMIN_ENDPOINT=${planes.admin}`, `NEXT_PUBLIC_AUTH_ENDPOINT=${planes.auth}`, `NEXT_PUBLIC_APP_ENDPOINT=${planes.app}`);
+    }
+    return `${lines.join('\n')}\n`;
+}

package/schema-resolve.d.ts

@@ -0,0 +1,23 @@
+import type { ProjectContext } from './context';
+export type ResolvedField = {
+    id: string;
+    name: string;
+    tableId: string;
+};
+export type ResolvedUniqueConstraint = {
+    id: string;
+    fieldIds: string[];
+};
+export type ResolvedTable = {
+    id: string;
+    name: string;
+    fields: ResolvedField[];
+    uniqueConstraints: ResolvedUniqueConstraint[];
+};
+export type ResolvedSchema = {
+    tables: ResolvedTable[];
+};
+export declare function resolveSchema(context: ProjectContext): Promise<ResolvedSchema>;
+export declare function resolveTable(schema: ResolvedSchema, tableName: string): ResolvedTable;
+export declare function resolveField(table: ResolvedTable, fieldName: string): ResolvedField;
+export declare function findUniqueConstraintId(table: ResolvedTable, fieldId: string): string | undefined;

package/schema-resolve.js

@@ -0,0 +1,75 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveSchema = resolveSchema;
+exports.resolveTable = resolveTable;
+exports.resolveField = resolveField;
+exports.findUniqueConstraintId = findUniqueConstraintId;
+async function resolveSchema(context) {
+    const { api, databaseId } = context;
+    const tablesResult = await api.table
+        .findMany({
+        select: { id: true, name: true },
+        where: { databaseId: { equalTo: databaseId } },
+    })
+        .execute();
+    if (!tablesResult.ok) {
+        const message = tablesResult.errors.map((e) => e.message).join('; ');
+        throw new Error(`Failed to read tables: ${message}`);
+    }
+    const tableNodes = tablesResult.data.tables?.nodes ?? [];
+    const tableIds = tableNodes.map((t) => t.id);
+    const fieldsByTable = new Map();
+    const constraintsByTable = new Map();
+    if (tableIds.length > 0) {
+        const fieldsResult = await api.field
+            .findMany({
+            select: { id: true, name: true, tableId: true },
+            where: { tableId: { in: tableIds } },
+        })
+            .execute();
+        if (!fieldsResult.ok) {
+            const message = fieldsResult.errors.map((e) => e.message).join('; ');
+            throw new Error(`Failed to read fields: ${message}`);
+        }
+        for (const field of fieldsResult.data.fields?.nodes ?? []) {
+            const list = fieldsByTable.get(field.tableId) ?? [];
+            list.push({ id: field.id, name: field.name, tableId: field.tableId });
+            fieldsByTable.set(field.tableId, list);
+        }
+        const constraintsResult = await api.uniqueConstraint
+            .findMany({
+            select: { id: true, tableId: true, fieldIds: true },
+            where: { tableId: { in: tableIds } },
+        })
+            .execute();
+        if (constraintsResult.ok) {
+            for (const c of constraintsResult.data.uniqueConstraints?.nodes ?? []) {
+                const list = constraintsByTable.get(c.tableId) ?? [];
+                list.push({ id: c.id, fieldIds: Array.isArray(c.fieldIds) ? c.fieldIds : [] });
+                constraintsByTable.set(c.tableId, list);
+            }
+        }
+    }
+    const tables = tableNodes.map((table) => ({
+        id: table.id,
+        name: table.name,
+        fields: fieldsByTable.get(table.id) ?? [],
+        uniqueConstraints: constraintsByTable.get(table.id) ?? [],
+    }));
+    return { tables };
+}
+function resolveTable(schema, tableName) {
+    const table = schema.tables.find((t) => t.name === tableName);
+    if (!table)
+        throw new Error(`Table "${tableName}" not found in current schema`);
+    return table;
+}
+function resolveField(table, fieldName) {
+    const field = table.fields.find((f) => f.name === fieldName);
+    if (!field)
+        throw new Error(`Field "${fieldName}" not found in table "${table.name}"`);
+    return field;
+}
+function findUniqueConstraintId(table, fieldId) {
+    return table.uniqueConstraints.find((c) => c.fieldIds.includes(fieldId))?.id;
+}

package/tool-schema.d.ts

@@ -0,0 +1,3 @@
+import type { TSchema } from 'typebox';
+import { z } from 'zod';
+export declare function toolSchema(schema: z.ZodType): TSchema;

package/tool-schema.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolSchema = toolSchema;
+const zod_1 = require("zod");
+// Tool parameter schemas are authored in zod; pi's ToolDefinition wants a
+// typebox TSchema. Structurally a TSchema is just a JSON Schema object, so the
+// draft-7 output of z.toJSONSchema (minus the $schema marker, matching what
+// typebox emits) is cast across the boundary. typebox itself is a type-only
+// import — it never appears in the runtime bundle.
+function toolSchema(schema) {
+    const { $schema: _$schema, ...rest } = zod_1.z.toJSONSchema(schema, { target: 'draft-7' });
+    return rest;
+}

package/tools/add-policies.d.ts

@@ -0,0 +1,24 @@
+import { type HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+declare const AddPoliciesZod: z.ZodObject<{
+    table_name: z.ZodString;
+    policies: z.ZodArray<z.ZodObject<{
+        policy_type: z.ZodString;
+        operations: z.ZodArray<z.ZodEnum<{
+            create: "create";
+            read: "read";
+            update: "update";
+            delete: "delete";
+        }>>;
+        role_name: z.ZodOptional<z.ZodString>;
+        is_permissive: z.ZodOptional<z.ZodBoolean>;
+        data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        node_data: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AddPoliciesDetails = {
+    success: boolean;
+    message: string;
+};
+export declare const addPoliciesTool: HarnessTool<typeof AddPoliciesZod, AddPoliciesDetails>;
+export {};

package/tools/add-policies.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addPoliciesTool = void 0;
+const harness_1 = require("@agentic-kit/harness");
+const zod_1 = require("zod");
+const context_1 = require("../context");
+const add_policies_to_table_1 = require("../policy/add-policies-to-table");
+const schema_resolve_1 = require("../schema-resolve");
+const DEFAULT_ROLE = 'authenticated';
+const CrudOperationSchema = zod_1.z.enum(['create', 'read', 'update', 'delete']);
+const PolicyEntrySchema = zod_1.z.object({
+    policy_type: zod_1.z
+        .string()
+        .describe('Policy type id. Supported: AuthzAllowAll, AuthzDenyAll, AuthzAppMembership, AuthzDirectOwner, AuthzEntityMembership, AuthzOrgHierarchy, AuthzPublishable (these auto-create columns via their Data* node), AuthzRelatedMemberList, AuthzRelatedEntityMembership. Not supported (use the policies UI): AuthzDirectOwnerAny, AuthzMemberList, AuthzTemporal, AuthzComposite.'),
+    operations: zod_1.z
+        .array(CrudOperationSchema)
+        .min(1)
+        .describe('CRUD operations the policy applies to: any subset of ["create","read","update","delete"].'),
+    role_name: zod_1.z
+        .string()
+        .describe('PostgreSQL role the policy applies to. Defaults to "authenticated".')
+        .optional(),
+    is_permissive: zod_1.z
+        .boolean()
+        .describe('PERMISSIVE (default true) vs RESTRICTIVE — most policies should be permissive.')
+        .optional(),
+    data: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .describe('Type-specific shared data. AuthzDirectOwner: { entity_field: "owner_id" }. AuthzAppMembership: { permission?, is_admin?, is_owner? }. Empty object {} for AuthzAllowAll / AuthzDenyAll.')
+        .optional(),
+    node_data: zod_1.z
+        .record(zod_1.z.string(), zod_1.z.unknown())
+        .describe('Optional data for the underlying Data* node (has-module policies only).')
+        .optional(),
+});
+const AddPoliciesZod = zod_1.z.object({
+    table_name: zod_1.z
+        .string()
+        .describe('Name of the existing table to attach the policies to. Use describe_schema first to verify it exists.'),
+    policies: zod_1.z
+        .array(PolicyEntrySchema)
+        .min(1)
+        .describe('One or more policies to add. Each entry becomes one secure_table_provision call.'),
+});
+function buildOperations(roleName, isPermissive) {
+    const config = { roleName, isPermissive, policyData: {}, isCustomized: false };
+    return { create: config, read: config, update: config, delete: config };
+}
+exports.addPoliciesTool = {
+    name: 'add_policies',
+    label: 'Add policies',
+    description: 'Add one or more RLS policies to an existing table. Has-module policies (AuthzDirectOwner, AuthzEntityMembership, AuthzOrgHierarchy, AuthzPublishable) auto-create the columns they need — call directly, do not add columns first.',
+    promptSnippet: 'add_policies: attach RLS policies to an existing table (one call can add many). Gated.',
+    parameters: AddPoliciesZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context) {
+            return {
+                content: [{ type: 'text', text: resolved.reason }],
+                details: { success: false, message: resolved.reason },
+            };
+        }
+        const { modules, databaseId, schemaId } = resolved.context;
+        try {
+            const schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            const table = (0, schema_resolve_1.resolveTable)(schema, params.table_name);
+            const policies = params.policies.map((entry) => {
+                const config = (0, harness_1.getPolicyProvisioningConfig)(entry.policy_type);
+                const defaults = (0, harness_1.getPolicyFieldDefaults)(entry.policy_type);
+                const mergedData = { ...defaults, ...(entry.data ?? {}) };
+                const nodeData = entry.node_data ?? (0, harness_1.buildNodeData)(entry.policy_type, mergedData);
+                return {
+                    policyType: entry.policy_type,
+                    dataNodeType: config?.dataNodeType,
+                    nodeData,
+                    sharedPolicyData: mergedData,
+                    operations: buildOperations(entry.role_name ?? DEFAULT_ROLE, entry.is_permissive ?? true),
+                    enabledOperations: entry.operations,
+                };
+            });
+            await (0, add_policies_to_table_1.addPoliciesToExistingTable)({
+                client: modules,
+                databaseId,
+                schemaId,
+                tableId: table.id,
+                policies,
+            });
+            const count = params.policies.length;
+            const message = `Added ${count} ${count === 1 ? 'policy' : 'policies'} to ${params.table_name}`;
+            return { content: [{ type: 'text', text: message }], details: { success: true, message } };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to add policies';
+            return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+        }
+    },
+};

package/tools/add-records.d.ts

@@ -0,0 +1,18 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+export type AddRecordsDetails = {
+    success: boolean;
+    message: string;
+    tableName?: string;
+    columns?: string[];
+    rows?: Record<string, unknown>[];
+    createdCount?: number;
+    asOf?: string;
+    needsAuth?: boolean;
+};
+declare const AddRecordsZod: z.ZodObject<{
+    table_name: z.ZodString;
+    records: z.ZodArray<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const addRecordsTool: HarnessTool<typeof AddRecordsZod, AddRecordsDetails>;
+export {};

package/tools/add-records.js

@@ -0,0 +1,125 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRecordsTool = void 0;
+const generators_1 = require("@constructive-io/graphql-query/generators");
+const sdk_1 = require("@constructive-io/sdk");
+const zod_1 = require("zod");
+const context_1 = require("../context");
+const meta_1 = require("../records/meta");
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+function needsAuth(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message, needsAuth: true },
+    };
+}
+// Mirror @constructive-io/data's prepareCreateInput (create semantics): drop
+// undefined/null/empty-string so server defaults apply; keep false/0/[]/objects.
+function stripForCreate(record) {
+    const out = {};
+    for (const [key, value] of Object.entries(record)) {
+        if (value === undefined || value === null || value === '')
+            continue;
+        out[key] = value;
+    }
+    return out;
+}
+const AddRecordsZod = zod_1.z.object({
+    table_name: zod_1.z
+        .string()
+        .describe('Name of the table to insert rows into (snake_case, singular or plural).'),
+    records: zod_1.z
+        .array(zod_1.z.record(zod_1.z.string(), zod_1.z.unknown()))
+        .describe('Rows to insert. Each is an object of column → value (camelCase or snake_case column names).'),
+});
+exports.addRecordsTool = {
+    name: 'add_records',
+    label: 'Add records',
+    description: "Insert one or more rows into a table in the project's app database.",
+    promptSnippet: 'add_records: insert rows into an existing table. Gated.',
+    parameters: AddRecordsZod,
+    async execute(params, ctx) {
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { dataEndpoint } = resolved.context;
+        if (!dataEndpoint) {
+            return fail('Cannot resolve the app data endpoint (DATABASE_NAME missing from .env). Re-provision the database, then retry.');
+        }
+        if (params.records.length === 0)
+            return fail('No records provided.');
+        const token = await (0, context_1.resolveDataToken)(resolved.context);
+        if (!token.token)
+            return needsAuth(token.reason ?? 'Sign in to the database to insert records.');
+        const adapter = new sdk_1.objects.FetchAdapter(dataEndpoint, {
+            Authorization: `Bearer ${token.token}`,
+        });
+        let tables;
+        try {
+            const meta = await adapter.execute(meta_1.META_QUERY);
+            if (!meta.ok) {
+                return fail(`Failed to read schema from the app database: ${meta.errors.map((e) => e.message).join('; ')}`);
+            }
+            tables = (meta.data._meta?.tables ?? []).filter((t) => Boolean(t));
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to query the app database schema.');
+        }
+        const rawTable = (0, meta_1.findMetaTable)(tables, params.table_name);
+        if (!rawTable) {
+            return fail(`Table "${params.table_name}" was not found in the app database.`);
+        }
+        const table = (0, meta_1.cleanTable)(rawTable);
+        const allTables = tables.map(meta_1.cleanTable);
+        const mutation = (0, generators_1.buildPostGraphileCreate)(table, allTables).toString();
+        const mutationName = (0, generators_1.toCreateMutationName)(table.name, table);
+        const singularName = (0, generators_1.toCamelCaseSingular)(table.name, table);
+        // Constructive app tables scope rows by entityId (the owning user's id). The
+        // create input requires it, but callers won't know it — backfill it with the
+        // signed-in user's id from the Preview session when the table has the column
+        // and the record omits it.
+        const hasEntityId = table.fields.some((f) => f.name === 'entityId');
+        const created = [];
+        const errors = [];
+        for (const record of params.records) {
+            const prepared = hasEntityId && token.userId && record.entityId == null && record.entity_id == null
+                ? { ...record, entityId: token.userId }
+                : record;
+            const variables = { input: { [singularName]: stripForCreate(prepared) } };
+            try {
+                const result = await adapter.execute(mutation, variables);
+                if (!result.ok) {
+                    errors.push(result.errors.map((e) => e.message).join('; '));
+                    continue;
+                }
+                const payload = result.data[mutationName];
+                const row = payload?.[singularName] ?? {};
+                created.push(row);
+            }
+            catch (err) {
+                errors.push(err instanceof Error ? err.message : 'Unknown error');
+            }
+        }
+        if (created.length === 0) {
+            return fail(`Failed to insert into "${params.table_name}": ${errors.join('; ') || 'unknown error'}`);
+        }
+        const columns = table.fields.map((f) => f.name);
+        const message = errors.length > 0
+            ? `Inserted ${created.length} of ${params.records.length} row(s) into ${params.table_name} (${errors.length} failed).`
+            : `Inserted ${created.length} row(s) into ${params.table_name}.`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: true,
+                message,
+                tableName: rawTable.name,
+                columns,
+                rows: created,
+                createdCount: created.length,
+                asOf: new Date().toISOString(),
+            },
+        };
+    },
+};

package/tools/add-relation-schema.d.ts

@@ -0,0 +1,29 @@
+import type { BlueprintDefinition } from '@agentic-kit/harness';
+import { z } from 'zod';
+export declare const DeleteAction: z.ZodEnum<{
+    c: "c";
+    r: "r";
+    n: "n";
+    a: "a";
+    d: "d";
+}>;
+export declare const AddRelationZod: z.ZodObject<{
+    relation_type: z.ZodOptional<z.ZodEnum<{
+        belongs_to: "belongs_to";
+        many_to_many: "many_to_many";
+    }>>;
+    source_table: z.ZodString;
+    target_table: z.ZodString;
+    field_name: z.ZodOptional<z.ZodString>;
+    junction_table_name: z.ZodOptional<z.ZodString>;
+    delete_action: z.ZodOptional<z.ZodEnum<{
+        c: "c";
+        r: "r";
+        n: "n";
+        a: "a";
+        d: "d";
+    }>>;
+    is_required: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type AddRelationParams = z.infer<typeof AddRelationZod>;
+export declare function buildRelation(params: AddRelationParams): BlueprintDefinition['relations'];

package/tools/add-relation-schema.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AddRelationZod = exports.DeleteAction = void 0;
+exports.buildRelation = buildRelation;
+const zod_1 = require("zod");
+// delete_action is intentionally always sent: the backend REJECTS a
+// RelationBelongsTo whose delete_action is absent ("PROVISION_RELATION:
+// delete_action is required"). We default it to 'a' (NO ACTION) so the model
+// never has to supply it.
+exports.DeleteAction = zod_1.z
+    .enum(['c', 'r', 'n', 'a', 'd'])
+    .describe('FK delete action: c=CASCADE, r=RESTRICT, n=SET NULL, a=NO ACTION (default), d=SET DEFAULT');
+exports.AddRelationZod = zod_1.z.object({
+    relation_type: zod_1.z
+        .enum(['belongs_to', 'many_to_many'])
+        .describe('belongs_to adds an FK column on the source table; many_to_many adds a junction table. Defaults to belongs_to.')
+        .optional(),
+    source_table: zod_1.z.string().describe('Existing source table name (snake_case).'),
+    target_table: zod_1.z.string().describe('Existing target table name (snake_case).'),
+    field_name: zod_1.z
+        .string()
+        .describe('belongs_to only: FK column name to add on the source table, e.g. "author_id".')
+        .optional(),
+    junction_table_name: zod_1.z
+        .string()
+        .describe('many_to_many only: name of the junction table to create, e.g. "post_tags".')
+        .optional(),
+    delete_action: exports.DeleteAction.optional(),
+    is_required: zod_1.z
+        .boolean()
+        .describe('belongs_to only: make the FK NOT NULL. Defaults to false — a NOT NULL FK fails if the source table already has rows.')
+        .optional(),
+});
+// Build a relation-only blueprint definition (no tables): the spike proved
+// constructBlueprint applies relations to PRE-EXISTING tables without recreating
+// them, as long as delete_action is supplied.
+function buildRelation(params) {
+    const deleteAction = params.delete_action ?? 'a';
+    if ((params.relation_type ?? 'belongs_to') === 'many_to_many') {
+        return [
+            {
+                $type: 'RelationManyToMany',
+                source_table: params.source_table,
+                target_table: params.target_table,
+                junction_table_name: params.junction_table_name,
+                delete_action: deleteAction,
+            },
+        ];
+    }
+    return [
+        {
+            $type: 'RelationBelongsTo',
+            source_table: params.source_table,
+            target_table: params.target_table,
+            field_name: params.field_name,
+            delete_action: deleteAction,
+            is_required: params.is_required ?? false,
+        },
+    ];
+}

package/tools/add-relation.d.ts

@@ -0,0 +1,10 @@
+import { type HarnessTool } from '@agentic-kit/harness';
+import { AddRelationZod } from './add-relation-schema';
+export type AddRelationDetails = {
+    success: boolean;
+    message: string;
+    sourceTable?: string;
+    targetTable?: string;
+    fieldName?: string;
+};
+export declare const addRelationTool: HarnessTool<typeof AddRelationZod, AddRelationDetails>;

package/tools/add-relation.js

@@ -0,0 +1,94 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.addRelationTool = void 0;
+const harness_1 = require("@agentic-kit/harness");
+const context_1 = require("../context");
+const schema_resolve_1 = require("../schema-resolve");
+const add_relation_schema_1 = require("./add-relation-schema");
+function fail(message) {
+    return { content: [{ type: 'text', text: message }], details: { success: false, message } };
+}
+exports.addRelationTool = {
+    name: 'add_relation',
+    label: 'Add relation',
+    description: 'Add a relation between two EXISTING tables without recreating them: belongs_to adds a foreign-key column on the source table; many_to_many creates a junction table. Use this for relations discovered after the tables were provisioned. For brand-new related tables, prefer a single provision_blueprint call.',
+    promptSnippet: 'add_relation: link two existing tables (belongs_to FK column, or many_to_many junction). Gated.',
+    parameters: add_relation_schema_1.AddRelationZod,
+    async execute(params, ctx) {
+        const type = params.relation_type ?? 'belongs_to';
+        if (type === 'belongs_to' && !params.field_name) {
+            return fail('field_name is required for a belongs_to relation (the FK column name on the source table).');
+        }
+        if (type === 'many_to_many' && !params.junction_table_name) {
+            return fail('junction_table_name is required for a many_to_many relation.');
+        }
+        const resolved = await (0, context_1.resolveProjectContext)(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { modules, databaseId, schemaId, ownerId } = resolved.context;
+        if (!ownerId)
+            return fail('Not authenticated (missing OWNER_ID in .env).');
+        // Validate both tables exist before constructing — a clearer error than the
+        // backend's, and avoids a no-op blueprint.
+        let schema;
+        try {
+            schema = await (0, schema_resolve_1.resolveSchema)(resolved.context);
+            (0, schema_resolve_1.resolveTable)(schema, params.source_table);
+            (0, schema_resolve_1.resolveTable)(schema, params.target_table);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to resolve schema.');
+        }
+        const definition = (0, harness_1.expandBlueprintDefaults)({ tables: [], relations: (0, add_relation_schema_1.buildRelation)(params) });
+        const uniqueName = `add_relation_${Date.now()}`;
+        try {
+            const created = await modules.blueprint
+                .create({
+                data: {
+                    ownerId,
+                    databaseId,
+                    name: uniqueName,
+                    displayName: `${params.source_table} → ${params.target_table}`,
+                    description: `Add ${type} relation`,
+                    definition,
+                },
+                select: { id: true },
+            })
+                .unwrap();
+            const blueprintId = created.createBlueprint?.blueprint?.id;
+            if (!blueprintId)
+                throw new Error('Failed to create relation blueprint');
+            const constructResult = await modules.mutation
+                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
+                .unwrap();
+            if (!constructResult.constructBlueprint?.result) {
+                const constructions = await modules.blueprintConstruction
+                    .findMany({
+                    where: { blueprintId: { equalTo: blueprintId } },
+                    orderBy: ['ID_DESC'],
+                    first: 1,
+                    select: { status: true, errorDetails: true },
+                })
+                    .unwrap();
+                const error = constructions?.blueprintConstructions?.nodes?.[0]?.errorDetails ?? 'Unknown error';
+                return fail(`Failed to add relation: ${typeof error === 'string' ? error : JSON.stringify(error)}`);
+            }
+        }
+        catch (err) {
+            return fail(`Failed to add relation: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        const message = type === 'many_to_many'
+            ? `Created junction table "${params.junction_table_name}" linking ${params.source_table} ↔ ${params.target_table}.`
+            : `Added FK "${params.field_name}" on ${params.source_table} → ${params.target_table}.`;
+        return {
+            content: [{ type: 'text', text: message }],
+            details: {
+                success: true,
+                message,
+                sourceTable: params.source_table,
+                targetTable: params.target_table,
+                fieldName: params.field_name,
+            },
+        };
+    },
+};

package/tools/create-api-key.d.ts

@@ -0,0 +1,25 @@
+import type { HarnessTool } from '@agentic-kit/harness';
+import { z } from 'zod';
+declare const CreateApiKeyZod: z.ZodObject<{
+    key_name: z.ZodString;
+    principal_name: z.ZodOptional<z.ZodString>;
+    entity_ids: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    read_only: z.ZodOptional<z.ZodBoolean>;
+    expires_in_days: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type CreateApiKeyDetails = {
+    success: boolean;
+    message: string;
+    keyId?: string;
+    envVar?: string;
+    expiresAt?: string;
+    principalId?: string;
+    principalName?: string;
+    scope?: string;
+    needsAuth?: boolean;
+};
+export declare function toEnvVar(keyName: string): string;
+export declare function isStepUpError(messages: string[]): boolean;
+export declare function describeScope(entityIds: string[] | undefined, readOnly: boolean): string;
+export declare const createApiKeyTool: HarnessTool<typeof CreateApiKeyZod, CreateApiKeyDetails>;
+export {};