@agentic-kit/pi 0.2.0

package/esm/tools/describe-schema.js

@@ -0,0 +1,132 @@
+import { fieldTypeToTypeName, isInternalPolicy } from '@agentic-kit/harness';
+import { z } from 'zod';
+import { resolveProjectContext } from '../context';
+import { toolSchema } from '../tool-schema';
+const ParamZod = z.object({});
+const ParamSchema = toolSchema(ParamZod);
+function toDefaultValueString(value) {
+    if (value == null)
+        return null;
+    if (typeof value === 'string')
+        return value;
+    return JSON.stringify(value);
+}
+function formatText(details) {
+    const lines = [];
+    if (details.tables.length === 0) {
+        lines.push('No application tables yet.');
+    }
+    else {
+        lines.push(`Tables (${details.tables.length}):`);
+        for (const table of details.tables) {
+            lines.push(`  ${table.name}`);
+            for (const field of table.fields) {
+                const req = field.isRequired ? ' required' : '';
+                const def = field.defaultValue != null ? ` default=${field.defaultValue}` : '';
+                lines.push(`    - ${field.name}: ${field.type}${req}${def}`);
+            }
+            if (table.policies.length > 0) {
+                lines.push(`    policies: ${table.policies.join(', ')}`);
+            }
+        }
+    }
+    return lines.join('\n');
+}
+export const describeSchemaTool = {
+    name: 'describe_schema',
+    label: 'Describe schema',
+    description: 'Inspect the current Constructive database schema for this project: application tables with their fields (name, type, required, default). Read-only.',
+    promptSnippet: 'describe_schema: list the project database tables and their fields. Read-only — call before modifying schema.',
+    parameters: ParamSchema,
+    async execute(_toolCallId, _params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context) {
+            return {
+                content: [{ type: 'text', text: resolved.reason }],
+                details: { tables: [] },
+            };
+        }
+        const { api, databaseId } = resolved.context;
+        const tablesResult = await api.table
+            .findMany({
+            select: { id: true, name: true, category: true },
+            where: {
+                databaseId: { equalTo: databaseId },
+                or: [{ category: { equalTo: 'APP' } }, { name: { equalTo: 'users' } }],
+            },
+            orderBy: ['NAME_ASC'],
+        })
+            .execute();
+        if (!tablesResult.ok) {
+            const message = tablesResult.errors.map((e) => e.message).join('; ');
+            return {
+                content: [{ type: 'text', text: `Failed to read schema: ${message}` }],
+                details: { tables: [] },
+            };
+        }
+        const tableNodes = tablesResult.data.tables?.nodes ?? [];
+        const tableIds = tableNodes.map((t) => t.id);
+        const fieldsByTable = new Map();
+        const policiesByTable = new Map();
+        if (tableIds.length > 0) {
+            const [fieldsResult, policiesResult] = await Promise.all([
+                api.field
+                    .findMany({
+                    select: {
+                        name: true,
+                        type: true,
+                        isRequired: true,
+                        defaultValue: true,
+                        tableId: true,
+                    },
+                    where: { tableId: { in: tableIds } },
+                })
+                    .execute(),
+                api.policy
+                    .findMany({
+                    select: { tableId: true, policyType: true },
+                    where: { tableId: { in: tableIds } },
+                })
+                    .execute(),
+            ]);
+            if (!fieldsResult.ok) {
+                const message = fieldsResult.errors.map((e) => e.message).join('; ');
+                return {
+                    content: [{ type: 'text', text: `Failed to read fields: ${message}` }],
+                    details: { tables: [] },
+                };
+            }
+            for (const field of fieldsResult.data.fields?.nodes ?? []) {
+                const list = fieldsByTable.get(field.tableId) ?? [];
+                list.push({
+                    name: field.name,
+                    type: fieldTypeToTypeName(field.type),
+                    isRequired: Boolean(field.isRequired),
+                    defaultValue: toDefaultValueString(field.defaultValue),
+                });
+                fieldsByTable.set(field.tableId, list);
+            }
+            // One policy spans CRUD as several rows; collapse to distinct types per table.
+            if (policiesResult.ok) {
+                for (const policy of policiesResult.data.policies?.nodes ?? []) {
+                    if (isInternalPolicy(policy.policyType))
+                        continue;
+                    const list = policiesByTable.get(policy.tableId) ?? [];
+                    if (!list.includes(policy.policyType))
+                        list.push(policy.policyType);
+                    policiesByTable.set(policy.tableId, list);
+                }
+            }
+        }
+        const tables = tableNodes.map((table) => ({
+            name: table.name,
+            fields: fieldsByTable.get(table.id) ?? [],
+            policies: policiesByTable.get(table.id) ?? [],
+        }));
+        const details = { tables };
+        return {
+            content: [{ type: 'text', text: formatText(details) }],
+            details,
+        };
+    },
+};

package/esm/tools/mutations.d.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+export type MutationDetails = {
+    success: boolean;
+    message: string;
+};
+declare const DeleteTableSchema: import("typebox/type").TSchema;
+export declare const deleteTableTool: ToolDefinition<typeof DeleteTableSchema, MutationDetails>;
+declare const CreateFieldSchema: import("typebox/type").TSchema;
+export declare const createFieldTool: ToolDefinition<typeof CreateFieldSchema, MutationDetails>;
+declare const UpdateFieldSchema: import("typebox/type").TSchema;
+export declare const updateFieldTool: ToolDefinition<typeof UpdateFieldSchema, MutationDetails>;
+declare const DeleteFieldSchema: import("typebox/type").TSchema;
+export declare const deleteFieldTool: ToolDefinition<typeof DeleteFieldSchema, MutationDetails>;
+export {};

package/esm/tools/mutations.js

@@ -0,0 +1,235 @@
+import { toFieldDefault, toFieldType } from '@agentic-kit/harness';
+import { z } from 'zod';
+import { resolveProjectContext } from '../context';
+import { findUniqueConstraintId, resolveField, resolveSchema, resolveTable } from '../schema-resolve';
+import { toolSchema } from '../tool-schema';
+function ok(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: true, message },
+    };
+}
+function fail(message) {
+    return {
+        content: [{ type: 'text', text: message }],
+        details: { success: false, message },
+    };
+}
+// ── delete_table ──────────────────────────────────────────────────────────
+const DeleteTableZod = z.object({
+    table_name: z.string().describe('Name of the table to delete (snake_case)'),
+});
+const DeleteTableSchema = toolSchema(DeleteTableZod);
+export const deleteTableTool = {
+    name: 'delete_table',
+    label: 'Delete table',
+    description: 'Permanently delete a table and its data from the project database.',
+    promptSnippet: 'delete_table: drop an existing table by name. Destructive — gated.',
+    parameters: DeleteTableSchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        try {
+            const schema = await resolveSchema(resolved.context);
+            const table = resolveTable(schema, params.table_name);
+            await resolved.context.api.table
+                .delete({ where: { id: table.id }, select: { id: true } })
+                .unwrap();
+            return ok(`Deleted table ${params.table_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to delete table');
+        }
+    },
+};
+// ── create_field ──────────────────────────────────────────────────────────
+const CreateFieldZod = z.object({
+    table_name: z.string().describe('Name of the table to add the field to'),
+    field_name: z.string().describe('Field name in snake_case'),
+    type: z
+        .string()
+        .describe('PostgreSQL type: text, integer, smallint, numeric, boolean, date, timestamp, timestamptz, time, json, jsonb, inet, email, url, image, upload'),
+    is_required: z.boolean().describe('Whether the field is NOT NULL. Defaults to false.').optional(),
+    default_value: z
+        .union([z.string(), z.null()])
+        .describe('SQL default expression, e.g. "now()", "\'draft\'"')
+        .optional(),
+    is_unique: z
+        .boolean()
+        .describe('Whether the field has a unique constraint. Defaults to false.')
+        .optional(),
+});
+const CreateFieldSchema = toolSchema(CreateFieldZod);
+export const createFieldTool = {
+    name: 'create_field',
+    label: 'Create field',
+    description: 'Add a new field (column) to an existing table in the project database.',
+    promptSnippet: 'create_field: add a column to an existing table. Gated.',
+    parameters: CreateFieldSchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { api, databaseId } = resolved.context;
+        try {
+            const schema = await resolveSchema(resolved.context);
+            const table = resolveTable(schema, params.table_name);
+            const result = await api.field
+                .create({
+                data: {
+                    name: params.field_name,
+                    type: toFieldType(params.type),
+                    tableId: table.id,
+                    databaseId,
+                    isRequired: params.is_required ?? false,
+                    defaultValue: toFieldDefault(params.default_value),
+                },
+                select: { id: true, name: true, type: true },
+            })
+                .unwrap();
+            const createdId = result.createField?.field?.id;
+            if (params.is_unique && createdId) {
+                try {
+                    await api.uniqueConstraint
+                        .create({
+                        data: {
+                            tableId: table.id,
+                            databaseId,
+                            fieldIds: [createdId],
+                            name: `${table.name}_${params.field_name}_key`,
+                            type: 'u',
+                        },
+                        select: { id: true },
+                    })
+                        .unwrap();
+                }
+                catch (err) {
+                    console.warn('Failed to create unique constraint:', err);
+                }
+            }
+            return ok(`Added field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to create field');
+        }
+    },
+};
+// ── update_field ──────────────────────────────────────────────────────────
+const UpdateFieldZod = z.object({
+    table_name: z.string().describe('Name of the table containing the field'),
+    field_name: z.string().describe('Current field name'),
+    new_name: z.string().describe('New field name in snake_case (if renaming)').optional(),
+    new_type: z.string().describe('New PostgreSQL type (if changing type)').optional(),
+    is_required: z.boolean().describe('Set NOT NULL constraint').optional(),
+    default_value: z
+        .union([z.string(), z.null()])
+        .describe('New SQL default expression, or null to remove')
+        .optional(),
+    is_unique: z.boolean().describe('Set or remove unique constraint').optional(),
+});
+const UpdateFieldSchema = toolSchema(UpdateFieldZod);
+export const updateFieldTool = {
+    name: 'update_field',
+    label: 'Update field',
+    description: 'Modify an existing field: rename, change type, toggle required/unique, or set default.',
+    promptSnippet: 'update_field: rename/retype/toggle an existing column. Gated.',
+    parameters: UpdateFieldSchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        const { api, databaseId } = resolved.context;
+        try {
+            const schema = await resolveSchema(resolved.context);
+            const table = resolveTable(schema, params.table_name);
+            const field = resolveField(table, params.field_name);
+            const patch = {};
+            if (params.new_name)
+                patch.name = params.new_name;
+            if (params.new_type)
+                patch.type = toFieldType(params.new_type);
+            if (params.is_required !== undefined)
+                patch.isRequired = params.is_required;
+            if (params.default_value !== undefined) {
+                patch.defaultValue =
+                    params.default_value === null ? null : (toFieldDefault(params.default_value) ?? null);
+            }
+            if (Object.keys(patch).length > 0) {
+                await api.field
+                    .update({
+                    where: { id: field.id },
+                    data: patch,
+                    select: { id: true, name: true, type: true },
+                })
+                    .unwrap();
+            }
+            if (params.is_unique !== undefined) {
+                const existingUniqueId = findUniqueConstraintId(table, field.id);
+                if (params.is_unique && !existingUniqueId) {
+                    try {
+                        await api.uniqueConstraint
+                            .create({
+                            data: {
+                                tableId: table.id,
+                                databaseId,
+                                fieldIds: [field.id],
+                                name: `${table.name}_${params.new_name ?? field.name}_key`,
+                                type: 'u',
+                            },
+                            select: { id: true },
+                        })
+                            .unwrap();
+                    }
+                    catch (err) {
+                        console.warn('Failed to create unique constraint:', err);
+                    }
+                }
+                else if (!params.is_unique && existingUniqueId) {
+                    try {
+                        await api.uniqueConstraint
+                            .delete({ where: { id: existingUniqueId }, select: { id: true } })
+                            .unwrap();
+                    }
+                    catch (err) {
+                        console.warn('Failed to delete unique constraint:', err);
+                    }
+                }
+            }
+            return ok(`Updated field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to update field');
+        }
+    },
+};
+// ── delete_field ──────────────────────────────────────────────────────────
+const DeleteFieldZod = z.object({
+    table_name: z.string().describe('Name of the table containing the field'),
+    field_name: z.string().describe('Name of the field to delete'),
+});
+const DeleteFieldSchema = toolSchema(DeleteFieldZod);
+export const deleteFieldTool = {
+    name: 'delete_field',
+    label: 'Delete field',
+    description: 'Permanently delete a field (column) from an existing table.',
+    promptSnippet: 'delete_field: drop a column from a table by name. Destructive — gated.',
+    parameters: DeleteFieldSchema,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context)
+            return fail(resolved.reason);
+        try {
+            const schema = await resolveSchema(resolved.context);
+            const table = resolveTable(schema, params.table_name);
+            const field = resolveField(table, params.field_name);
+            await resolved.context.api.field
+                .delete({ where: { id: field.id }, select: { id: true } })
+                .unwrap();
+            return ok(`Deleted field ${params.table_name}.${params.field_name}`);
+        }
+        catch (err) {
+            return fail(err instanceof Error ? err.message : 'Failed to delete field');
+        }
+    },
+};

package/esm/tools/provision-blueprint.d.ts

@@ -0,0 +1,22 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+declare const BlueprintSchema: import("typebox/type").TSchema;
+type ProvisionedField = {
+    name: string;
+    type: string;
+    isRequired: boolean;
+    defaultValue: string | null;
+};
+type ProvisionedTable = {
+    name: string;
+    fields: ProvisionedField[];
+    policies: string[];
+    relationCount: number;
+};
+export type ProvisionBlueprintDetails = {
+    created: number;
+    total: number;
+    tables: ProvisionedTable[];
+    error: string | null;
+};
+export declare const provisionBlueprintTool: ToolDefinition<typeof BlueprintSchema, ProvisionBlueprintDetails>;
+export {};

package/esm/tools/provision-blueprint.js

@@ -0,0 +1,111 @@
+import { BlueprintZod, expandBlueprintDefaults, filterInternalPolicies, } from '@agentic-kit/harness';
+import { resolveProjectContext } from '../context';
+import { toolSchema } from '../tool-schema';
+const BlueprintSchema = toolSchema(BlueprintZod);
+function formatText(name, details) {
+    if (details.error)
+        return `Failed to provision "${name}": ${details.error}`;
+    const lines = [`Created ${details.created} table${details.created === 1 ? '' : 's'} from "${name}":`];
+    for (const table of details.tables) {
+        const parts = [`${table.fields.length} field${table.fields.length === 1 ? '' : 's'}`];
+        if (table.relationCount > 0) {
+            parts.push(`${table.relationCount} relation${table.relationCount === 1 ? '' : 's'}`);
+        }
+        if (table.policies.length > 0) {
+            parts.push(`policies: ${table.policies.map((policy) => policy.replace(/^Authz/, '')).join(', ')}`);
+        }
+        lines.push(`  - ${table.name} (${parts.join(', ')})`);
+    }
+    return lines.join('\n');
+}
+export const provisionBlueprintTool = {
+    name: 'provision_blueprint',
+    label: 'Provision blueprint',
+    description: 'Create one or more related tables (with fields, RLS policies, and relations) in the project database from a blueprint definition. Always put related tables in a SINGLE call so relations are created together.',
+    promptSnippet: 'provision_blueprint: create new tables from scratch in a single call (fields + policies + relations). Call describe_schema first.',
+    parameters: BlueprintSchema,
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+        const empty = { created: 0, total: 0, tables: [], error: null };
+        const resolved = await resolveProjectContext(ctx.cwd);
+        if (!resolved.context) {
+            return { content: [{ type: 'text', text: resolved.reason }], details: empty };
+        }
+        const { modules, databaseId, schemaId, ownerId } = resolved.context;
+        if (!ownerId) {
+            return {
+                content: [{ type: 'text', text: 'Not authenticated (missing OWNER_ID in .env).' }],
+                details: empty,
+            };
+        }
+        const definition = expandBlueprintDefaults(params.definition);
+        const uniqueName = `${params.name}_${Date.now()}`;
+        try {
+            const createResult = await modules.blueprint
+                .create({
+                data: {
+                    ownerId,
+                    databaseId,
+                    name: uniqueName,
+                    displayName: params.name,
+                    description: params.description,
+                    definition,
+                },
+                select: { id: true, name: true },
+            })
+                .unwrap();
+            const blueprintId = createResult.createBlueprint?.blueprint?.id;
+            if (!blueprintId)
+                throw new Error('Failed to create blueprint');
+            const constructResult = await modules.mutation
+                .constructBlueprint({ input: { blueprintId, schemaId } }, { select: { result: true } })
+                .unwrap();
+            const result = constructResult.constructBlueprint?.result;
+            if (!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';
+                const details = {
+                    created: 0,
+                    total: params.definition.tables.length,
+                    tables: [],
+                    error: typeof error === 'string' ? error : JSON.stringify(error),
+                };
+                return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+            }
+            const relations = params.definition.relations ?? [];
+            const details = {
+                created: params.definition.tables.length,
+                total: params.definition.tables.length,
+                tables: params.definition.tables.map((t) => ({
+                    name: t.table_name,
+                    fields: (t.fields ?? []).map((f) => ({
+                        name: f.name,
+                        type: f.type,
+                        isRequired: f.is_required ?? false,
+                        defaultValue: f.default ?? null,
+                    })),
+                    policies: filterInternalPolicies(t.policies.map((p) => p.$type)),
+                    relationCount: relations.filter((r) => r.source_table === t.table_name).length,
+                })),
+                error: null,
+            };
+            return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : 'Failed to provision blueprint';
+            const details = {
+                created: 0,
+                total: params.definition.tables.length,
+                tables: [],
+                error: message,
+            };
+            return { content: [{ type: 'text', text: formatText(params.name, details) }], details };
+        }
+    },
+};

package/esm/tools/provision-database.d.ts

@@ -0,0 +1,14 @@
+import type { ToolDefinition } from '@earendil-works/pi-coding-agent';
+declare const ProvisionDatabaseSchema: import("typebox/type").TSchema;
+export type ProvisionDatabaseDetails = {
+    success: boolean;
+    message: string;
+    databaseId?: string;
+    databaseName?: string;
+    ownerId?: string;
+    fixupNote?: string;
+    /** True when an existing live binding was kept — nothing changed. */
+    skipped?: boolean;
+};
+export declare const provisionDatabaseTool: ToolDefinition<typeof ProvisionDatabaseSchema, ProvisionDatabaseDetails>;
+export {};