@enfyra/mcp-server 0.1.31 → 0.1.33

package/dist/lib/table-tools.js

@@ -44,6 +44,21 @@ const FALLBACK_COLUMN_TYPES = [
     'richtext',
     'float',
 ];
+const RELATION_TYPE_ALIASES = {
+    many_to_one: 'many-to-one',
+    manyToOne: 'many-to-one',
+    manytoone: 'many-to-one',
+    one_to_many: 'one-to-many',
+    oneToMany: 'one-to-many',
+    onetomany: 'one-to-many',
+    one_to_one: 'one-to-one',
+    oneToOne: 'one-to-one',
+    onetoone: 'one-to-one',
+    many_to_many: 'many-to-many',
+    manyToMany: 'many-to-many',
+    manytomany: 'many-to-many',
+};
+const VALID_RELATION_TYPES = new Set(['many-to-one', 'one-to-many', 'one-to-one', 'many-to-many']);
 const AUTO_MANAGED_COLUMN_NAMES = new Set(['id', '_id', 'createdAt', 'updatedAt']);
 const COLUMN_TYPE_ALIAS_HINTS = [
     'Use varchar for short strings; text or richtext for long prose.',
@@ -207,6 +222,34 @@ function assertNoDuplicateFieldNames(fieldNames, context) {
         throw new Error(`${context} has duplicate field name(s): ${[...duplicates].join(', ')}. Column names and relation propertyName values share one namespace.`);
     }
 }
+function assertNoColumnRelationNameCollision(columnNames, relationNames, context) {
+    const relationNameSet = new Set(relationNames.filter(Boolean));
+    const collisions = columnNames.filter((name) => relationNameSet.has(name));
+    if (collisions.length > 0) {
+        throw new Error(`${context} has column/relation namespace collision(s): ${[...new Set(collisions)].join(', ')}. ` +
+            `Column names and relation propertyName values share one namespace; remove the scalar column(s) and keep the relation propertyName(s) ${[...new Set(collisions)].join(', ')}. Do not create physical FK columns.`);
+    }
+    assertNoDuplicateFieldNames([...columnNames, ...relationNames], context);
+}
+function formatConstraintFieldHints(fields, relationNames, logicalFieldNames) {
+    const relationNameSet = new Set(relationNames);
+    const logicalNameSet = new Set(logicalFieldNames);
+    const normalizeName = (value) => value.replace(/[_\-\s]/gu, '').toLowerCase();
+    return fields
+        .map((field) => {
+        const normalized = String(field)
+            .replace(/_?ids?$/iu, '')
+            .replace(/_id$/iu, '')
+            .replace(/Id$/u, '')
+            .replace(/Ids$/u, '');
+        const match = [...relationNameSet].find((name) => name.toLowerCase() === normalized.toLowerCase());
+        if (match)
+            return `${field} -> use relation propertyName "${match}" in indexes/uniques, not physical FK "${field}"`;
+        const logicalMatch = [...logicalNameSet].find((name) => normalizeName(name) === normalizeName(String(field)));
+        return logicalMatch ? `${field} -> did you mean "${logicalMatch}"? Constraint fields must match column/relation names exactly.` : null;
+    })
+        .filter(Boolean);
+}
 function preflightCreateTableDefinitions(items) {
     items.forEach((item, index) => {
         const columns = Array.isArray(item.columns) ? item.columns : parseJsonArrayParam(`items[${index}].columns`, item.columns || '[]');
@@ -214,7 +257,7 @@ function preflightCreateTableDefinitions(items) {
         const { columns: userColumns } = stripAutoManagedColumns(columns);
         const columnNames = userColumns.map((column) => String(column?.name ?? '')).filter(Boolean);
         const relationNames = relations.map((relation) => String(relation?.propertyName ?? '')).filter(Boolean);
-        assertNoDuplicateFieldNames([...columnNames, ...relationNames], `create_tables items[${index}] (${item.name || '<unnamed>'})`);
+        assertNoColumnRelationNameCollision(columnNames, relationNames, `create_tables items[${index}] (${item.name || '<unnamed>'})`);
         const logicalFields = new Set([...AUTO_MANAGED_COLUMN_NAMES, ...columnNames, ...relationNames]);
         const indexes = normalizeConstraintGroupsValue(`items[${index}].indexes`, item.indexes ?? []);
         const uniques = normalizeConstraintGroupsValue(`items[${index}].uniques`, item.uniques ?? []);
@@ -223,11 +266,50 @@ function preflightCreateTableDefinitions(items) {
             .flat()
             .filter((field) => !logicalFields.has(field));
         if (unknownConstraintFields.length > 0) {
-            throw new Error(`create_tables items[${index}] (${item.name || '<unnamed>'}) has indexes/uniques referencing undeclared field(s): ${[...new Set(unknownConstraintFields)].join(', ')}. ` +
-                'Declare each field as a column or relation propertyName in the same table item. For relation-based unique pairs added after create, first create the relations, then call update_tables with the unique group.');
+            const uniqueUnknownFields = [...new Set(unknownConstraintFields)];
+            const hints = formatConstraintFieldHints(uniqueUnknownFields, relationNames, [...logicalFields]);
+            throw new Error(`create_tables items[${index}] (${item.name || '<unnamed>'}) has indexes/uniques referencing undeclared field(s): ${uniqueUnknownFields.join(', ')}. ` +
+                'Declare each field as a column or relation propertyName in the same table item. ' +
+                (hints.length ? `Hint(s): ${hints.join('; ')}. ` : '') +
+                'For relation-based unique pairs added after create, first create the relations, then call update_tables with the unique group.');
         }
     });
 }
+function relationTargetName(relation) {
+    const target = relation?.targetTable ?? relation?.targetTableId;
+    if (target && typeof target === 'object')
+        return target.name ?? target.alias ?? target.id ?? target._id;
+    return target;
+}
+export function computeBatchCleanupOrder(items) {
+    const tableNames = items.map((item) => String(item?.name || '')).filter(Boolean);
+    const tableSet = new Set(tableNames);
+    const edges = [];
+    for (const item of items) {
+        const source = String(item?.name || '');
+        if (!source)
+            continue;
+        const relations = Array.isArray(item.relations) ? item.relations : parseJsonArrayParam(`${source}.relations`, item.relations || '[]');
+        for (const relation of relations) {
+            const target = String(relationTargetName(relation) || '');
+            if (target && tableSet.has(target) && target !== source)
+                edges.push([source, target]);
+        }
+    }
+    const remaining = new Set(tableNames);
+    const ordered = [];
+    while (remaining.size > 0) {
+        const leaves = [...remaining]
+            .filter((name) => !edges.some(([source, target]) => target === name && remaining.has(source) && remaining.has(target)))
+            .sort();
+        const batch = leaves.length ? leaves : [[...remaining].sort()[0]];
+        for (const name of batch) {
+            remaining.delete(name);
+            ordered.push(name);
+        }
+    }
+    return ordered;
+}
 function splitRelationConstraintGroups(groups, relationNames) {
     const immediate = [];
     const deferred = [];
@@ -268,20 +350,38 @@ function resolveRelationConstraintGroups(table, groups, groupName) {
     }));
 }
 export function assertIndexesDoNotReferenceUniqueFields(indexes, uniques) {
-    const uniqueFields = new Set(uniques.flat());
     const conflicts = indexes
-        .map((group) => ({
-        index: group,
-        uniqueFields: group.filter((field) => uniqueFields.has(field)),
+        .map((indexGroup) => ({
+        indexGroup,
+        uniqueGroups: uniques
+            .map((uniqueGroup) => ({
+            uniqueGroup,
+            overlappingFields: indexGroup.filter((field) => uniqueGroup.includes(field)),
+        }))
+            .filter((conflict) => conflict.overlappingFields.length > 0),
     }))
-        .filter((conflict) => conflict.uniqueFields.length > 0);
+        .filter((conflict) => conflict.uniqueGroups.length > 0);
     if (conflicts.length > 0) {
         const groups = conflicts
-            .map((conflict) => `${JSON.stringify(conflict.index)} uses unique field(s) ${JSON.stringify(conflict.uniqueFields)}`)
+            .map((conflict) => `${JSON.stringify(conflict.indexGroup)} overlaps unique group(s) ${conflict.uniqueGroups.map((item) => `${JSON.stringify(item.uniqueGroup)} via ${JSON.stringify(item.overlappingFields)}`).join(', ')}`)
             .join('; ');
         throw new Error(`Invalid schema constraints: indexes must not include fields that appear in uniques, including composite unique groups. Conflict(s): ${groups}. Unique constraints already create indexed lookups for their fields; remove those fields from indexes and keep them only in uniques.`);
     }
 }
+function pruneIndexesThatOverlapUniques(indexes, uniques) {
+    const uniqueFields = new Set(uniques.flat());
+    const kept = [];
+    const removed = [];
+    for (const indexGroup of indexes) {
+        if (indexGroup.some((field) => uniqueFields.has(field))) {
+            removed.push(indexGroup);
+        }
+        else {
+            kept.push(indexGroup);
+        }
+    }
+    return { indexes: kept, removed };
+}
 export function normalizeRelationForTablePatch(relation) {
     for (const key of FORBIDDEN_RELATION_KEYS) {
         if (Object.prototype.hasOwnProperty.call(relation, key)) {
@@ -290,6 +390,12 @@ export function normalizeRelationForTablePatch(relation) {
     }
     const { sourceTable, targetTable, targetTableId, mappedBy, fkCol, fkColumn, foreignKeyColumn, sourceColumn, targetColumn, junctionSourceColumn, junctionTargetColumn, ...rest } = relation;
     const normalized = { ...rest };
+    if (rest.type !== undefined) {
+        normalized.type = normalizeRelationType(rest.type);
+    }
+    if (normalized.type === 'one-to-many' && mappedBy !== undefined && mappedBy !== null && mappedBy !== '') {
+        delete normalized.inversePropertyName;
+    }
     const resolvedTargetTable = targetTableId ??
         (targetTable && typeof targetTable === 'object'
             ? targetTable.id ?? targetTable._id ?? targetTable
@@ -304,6 +410,14 @@ export function normalizeRelationForTablePatch(relation) {
     }
     return normalized;
 }
+export function normalizeRelationType(type) {
+    const raw = String(type ?? '').trim();
+    const normalized = RELATION_TYPE_ALIASES[raw] ?? raw;
+    if (!VALID_RELATION_TYPES.has(normalized)) {
+        throw new Error(`Invalid relation type "${raw || '<missing>'}". Use one of many-to-one, one-to-many, one-to-one, or many-to-many. Common aliases such as many_to_one are normalized by the tool.`);
+    }
+    return normalized;
+}
 function assertNoForbiddenRelationKeys(args) {
     for (const key of FORBIDDEN_RELATION_KEYS) {
         if (Object.prototype.hasOwnProperty.call(args, key)) {
@@ -554,7 +668,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         assertGlobalRulesAck(args.globalRulesAckKey);
         return withSchemaQueue(async () => {
             assertNoForbiddenRelationKeys(args);
-            const { sourceTableId, targetTableId, targetTable, type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = args;
+            const { sourceTableId, targetTableId, targetTable } = args;
+            const relationPatch = normalizeRelationForTablePatch(args);
+            const { type, propertyName, inversePropertyName, mappedBy, isNullable, onDelete, description } = relationPatch;
             const targetRef = targetTableId ?? targetTable;
             if (targetRef === undefined || targetRef === null || targetRef === '') {
                 throw new Error('create_relations requires targetTableId or targetTable. Pass an existing table id, name, or alias.');
@@ -694,7 +810,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         sourceTableId: z.string().describe('Source table id, exact table name, or alias. For many-to-one, this is the table that owns the relation property.'),
         targetTableId: z.string().optional().describe('Target table id, exact table name, or alias. MCP resolves names/aliases to ids before mutation. Optional when targetTable is provided.'),
         targetTable: z.string().optional().describe('Alias for targetTableId when naturally using a target table name/alias such as enfyra_user. Optional when targetTableId is provided.'),
-        type: z.enum(['many-to-one', 'one-to-many', 'one-to-one', 'many-to-many']).describe('Relation type.'),
+        type: z.string().describe('Relation type. Use many-to-one, one-to-many, one-to-one, or many-to-many. Common aliases such as many_to_one are normalized by the tool.'),
         propertyName: z.string().describe('Property name on source table (e.g., "customer", "items").'),
         inversePropertyName: z.string().optional().describe('Property name on target table for bidirectional relation (e.g., "orders"). Omit unless a concrete response, UI, deep query, aggregate sort/count, or parent-to-child traversal will use the reverse field. Do not add inverses merely because a parent table exists.'),
         mappedBy: z.string().optional().describe('Mapped-by property for inverse relation shapes when required by the backend. Do not use physical FK names.'),
@@ -736,10 +852,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         const { columns: normalizedUserColumns, normalizations } = normalizeColumnsForLiveMetadata(userColumnsWithoutAuto, supportedTypes);
         const deferredRelations = arrayValue('relations', args.relations).map(normalizeRelationForTablePatch);
         const relationNames = new Set(deferredRelations.map((relation) => relation.propertyName).filter(Boolean));
-        assertNoDuplicateFieldNames([
-            ...normalizedUserColumns.map((column) => String(column.name || '')).filter(Boolean),
-            ...deferredRelations.map((relation) => String(relation.propertyName || '')).filter(Boolean),
-        ], `create_tables item "${args.name}"`);
+        assertNoColumnRelationNameCollision(normalizedUserColumns.map((column) => String(column.name || '')).filter(Boolean), deferredRelations.map((relation) => String(relation.propertyName || '')).filter(Boolean), `create_tables item "${args.name}"`);
         const indexes = normalizeConstraintGroupsValue('indexes', args.indexes ?? []);
         const uniques = normalizeConstraintGroupsValue('uniques', args.uniques ?? []);
         assertIndexesDoNotReferenceUniqueFields(indexes, uniques);
@@ -815,8 +928,9 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         const mappedUniques = resolveRelationConstraintGroups(tableData, deferredUniques, 'uniques');
         const existingIndexes = normalizeConstraintGroupsValue('indexes', tableData.indexes || []);
         const existingUniques = normalizeConstraintGroupsValue('uniques', tableData.uniques || []);
-        const indexes = mergeConstraintGroups(existingIndexes, mappedIndexes);
         const uniques = mergeConstraintGroups(existingUniques, mappedUniques);
+        const prunedExistingIndexes = pruneIndexesThatOverlapUniques(existingIndexes, uniques);
+        const indexes = mergeConstraintGroups(prunedExistingIndexes.indexes, mappedIndexes);
         assertIndexesDoNotReferenceUniqueFields(indexes, uniques);
         const result = await patchTableAutoConfirm(ENFYRA_API_URL, tableId, { indexes, uniques });
         return {
@@ -831,11 +945,13 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 indexes: mappedIndexes,
                 uniques: mappedUniques,
             },
+            prunedExistingIndexes: prunedExistingIndexes.removed,
             result,
         };
     }
     async function updateOneTable(args) {
         const body = {};
+        let schemaConstraintNormalization;
         if (args.name !== undefined)
             body.name = args.name;
         if (args.alias !== undefined)
@@ -860,12 +976,22 @@ export function registerTableTools(server, ENFYRA_API_URL) {
                 if (uniques === undefined)
                     uniques = normalizeConstraintGroupsValue('uniques', existing.uniques);
             }
+            if (args.uniques !== undefined && args.indexes === undefined) {
+                const prunedExistingIndexes = pruneIndexesThatOverlapUniques(indexes ?? [], uniques ?? []);
+                indexes = prunedExistingIndexes.indexes;
+                body.indexes = indexes;
+                schemaConstraintNormalization = {
+                    prunedExistingIndexes: prunedExistingIndexes.removed,
+                    reason: 'Unique constraints already provide indexed lookups; MCP removed existing non-unique indexes that used fields now covered by uniques.',
+                };
+            }
             assertIndexesDoNotReferenceUniqueFields(indexes ?? [], uniques ?? []);
         }
         const result = await patchTableAutoConfirm(ENFYRA_API_URL, args.tableId, body);
         return {
             action: 'table_updated',
             tableId: args.tableId,
+            schemaConstraintNormalization,
             result,
         };
     }
@@ -937,14 +1063,17 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         };
     }
     // ─── READ ───
-    server.tool('get_all_tables', 'List table definitions from metadata. Every call must pass either limit or all=true. Use search to narrow by table name or alias.', {
-        limit: z.number().int().positive().optional().describe('Maximum tables returned after search. Required unless all=true.'),
+    server.tool('get_all_tables', 'List table definitions from metadata. Complete lists must pass either limit or all=true. If search is provided without limit, the tool returns a bounded lookup window of 10 matches.', {
+        limit: z.number().int().positive().optional().describe('Maximum tables returned after search. Required unless all=true or search is provided.'),
         all: z.boolean().optional().describe('Return all matched tables. Use this when a complete table list is required.'),
         search: z.string().optional().describe('Optional table name, alias, or description substring filter.'),
     }, async ({ limit, all, search }) => {
-        if (!all && limit === undefined) {
+        if (!all && limit === undefined && !search?.trim()) {
             throw new Error('get_all_tables requires either limit or all=true. Do not invent arbitrary limits for complete table lists; use all=true.');
         }
+        if (all && limit !== undefined) {
+            throw new Error('get_all_tables accepts either all=true or limit, not both.');
+        }
         const metadata = await fetchAPI(ENFYRA_API_URL, '/metadata');
         const needle = search?.trim().toLowerCase();
         const tables = normalizeTablesFromMetadata(metadata)
@@ -964,13 +1093,16 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             return [table.name, table.alias, table.description]
                 .some((value) => String(value || '').toLowerCase().includes(needle));
         });
-        const returnedTables = all ? tables : tables.slice(0, limit);
+        const effectiveLimit = all ? tables.length : (limit ?? 10);
+        const returnedTables = all ? tables : tables.slice(0, effectiveLimit);
         return jsonContent({
             action: 'get_all_tables',
             totalTableCount: normalizeTablesFromMetadata(metadata).length,
             matchedTableCount: tables.length,
             returnedTableCount: returnedTables.length,
             all: Boolean(all),
+            implicitSearchLimit: Boolean(!all && limit === undefined && search?.trim()),
+            hardCap: all ? null : effectiveLimit,
             search: search || null,
             tables: returnedTables,
             detailHint: 'Use inspect_table with a table id/name for columns, relations, indexes, routes, permissions, and GraphQL state.',
@@ -1071,6 +1203,8 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         'Do not include id, _id, createdAt, or updatedAt in columns; Enfyra manages them and create_tables strips them before save.',
         'Every field named in indexes/uniques must be a scalar column, auto-managed column, or relation propertyName in the same table item; otherwise the tool rejects the whole batch before creating tables.',
         'Use get_schema_design_context first for live column types and relation rules. Do not include physical FK fields.',
+        'The response includes cleanupHints.recordCreateOrder; use it when seeding records so parent/target rows are created before child/source rows.',
+        'The response includes cleanupHints.recordDeleteOrder; use it when deleting seeded test records so child/source rows are removed before parent/target rows.',
     ].join(' '), {
         items: bulkObjectArrayParam(z, 'Table definitions').optional().describe('Native JSON array of table definitions. Pass one object in the array for a single table.'),
         tables: bulkObjectArrayParam(z, 'Table definitions').optional().describe('Alias for items when the caller naturally names the batch tables. Pass either items or tables, not both.'),
@@ -1083,6 +1217,7 @@ export function registerTableTools(server, ENFYRA_API_URL) {
         const parsedItems = parseBulkItemsParam('items', items ?? tables);
         assertBulkLimit('create_tables', parsedItems, maxItems);
         preflightCreateTableDefinitions(parsedItems);
+        const recordDeleteOrder = computeBatchCleanupOrder(parsedItems);
         const created = [];
         const deferredRelations = [];
         const deferredConstraints = [];
@@ -1101,6 +1236,11 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             }
         }
         const createdRelations = [];
+        deferredRelations.sort((left, right) => {
+            const leftPriority = normalizeRelationType(left.type) === 'one-to-many' ? 1 : 0;
+            const rightPriority = normalizeRelationType(right.type) === 'one-to-many' ? 1 : 0;
+            return leftPriority - rightPriority;
+        });
         for (const relation of deferredRelations) {
             const relationResult = await appendRelationToTable({
                 sourceTableId: relation.sourceTableId,
@@ -1136,6 +1276,14 @@ export function registerTableTools(server, ENFYRA_API_URL) {
             sequential: true,
             relationPhaseAfterTables: true,
             constraintPhaseAfterRelations: true,
+            cleanupHints: {
+                recordCreateOrder: [...recordDeleteOrder].reverse(),
+                recordDeleteOrder,
+                tableDeleteOrder: recordDeleteOrder,
+                recordCreateRule: 'When seeding sample data, create records sequentially in recordCreateOrder; parent/target rows must exist before child/source rows reference them.',
+                recordRule: 'If you delete seeded records before deleting test tables, delete record batches sequentially in recordDeleteOrder; do not parallelize parent/child deletes.',
+                tableRule: 'For full test cleanup, prefer delete_tables with tableDeleteOrder after deleting custom routes/flows; table deletion removes the remaining table data.',
+            },
             created,
             createdRelations,
             appliedDeferredConstraints,