@jaypie/dynamodb 0.2.0 → 0.4.0

package/dist/esm/mcp/index.js

@@ -1,5 +1,5 @@
-import { registerMcpTool } from '@jaypie/vocabulary/mcp';
-import { getModelIndexes, populateIndexKeys, SEPARATOR, serviceHandler, ARCHIVED_SUFFIX, DELETED_SUFFIX, DEFAULT_INDEXES, getAllRegisteredIndexes } from '@jaypie/vocabulary';
+import { fabricMcp } from '@jaypie/fabric/mcp';
+import { getModelIndexes, populateIndexKeys, SEPARATOR, fabricService, ARCHIVED_SUFFIX, DELETED_SUFFIX, DEFAULT_INDEXES, getAllRegisteredIndexes } from '@jaypie/fabric';
 import { DynamoDBClient, DescribeTableCommand, CreateTableCommand } from '@aws-sdk/client-dynamodb';
 import { DynamoDBDocumentClient, GetCommand, PutCommand, DeleteCommand, QueryCommand } from '@aws-sdk/lib-dynamodb';
 import { ConfigurationError } from '@jaypie/errors';
@@ -75,11 +75,11 @@ function isInitialized() {
     return docClient !== null && tableName !== null;
 }
 
-// Re-export shared constants from vocabulary
+// Re-export shared constants from fabric
 // GSI names (derived from DEFAULT_INDEXES)
 const INDEX_ALIAS = "indexAlias";
 const INDEX_CLASS = "indexClass";
-const INDEX_OU = "indexOu";
+const INDEX_SCOPE = "indexScope";
 const INDEX_TYPE = "indexType";
 const INDEX_XID = "indexXid";
 
@@ -87,53 +87,53 @@ const INDEX_XID = "indexXid";
 // Key Builders
 // =============================================================================
 /**
- * Build the indexOu key for hierarchical queries
- * @param ou - The organizational unit (APEX or "{parent.model}#{parent.id}")
+ * Build the indexScope key for hierarchical queries
+ * @param scope - The scope (APEX or "{parent.model}#{parent.id}")
  * @param model - The entity model name
- * @returns Composite key: "{ou}#{model}"
+ * @returns Composite key: "{scope}#{model}"
  */
-function buildIndexOu(ou, model) {
-    return `${ou}${SEPARATOR}${model}`;
+function buildIndexScope(scope, model) {
+    return `${scope}${SEPARATOR}${model}`;
 }
 /**
  * Build the indexAlias key for human-friendly lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param alias - The human-friendly alias
- * @returns Composite key: "{ou}#{model}#{alias}"
+ * @returns Composite key: "{scope}#{model}#{alias}"
  */
-function buildIndexAlias(ou, model, alias) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${alias}`;
+function buildIndexAlias(scope, model, alias) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${alias}`;
 }
 /**
  * Build the indexClass key for category filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param recordClass - The category classification
- * @returns Composite key: "{ou}#{model}#{class}"
+ * @returns Composite key: "{scope}#{model}#{class}"
  */
-function buildIndexClass(ou, model, recordClass) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
+function buildIndexClass(scope, model, recordClass) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${recordClass}`;
 }
 /**
  * Build the indexType key for type filtering
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param type - The type classification
- * @returns Composite key: "{ou}#{model}#{type}"
+ * @returns Composite key: "{scope}#{model}#{type}"
  */
-function buildIndexType(ou, model, type) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${type}`;
+function buildIndexType(scope, model, type) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${type}`;
 }
 /**
  * Build the indexXid key for external ID lookups
- * @param ou - The organizational unit
+ * @param scope - The scope
  * @param model - The entity model name
  * @param xid - The external ID
- * @returns Composite key: "{ou}#{model}#{xid}"
+ * @returns Composite key: "{scope}#{model}#{xid}"
  */
-function buildIndexXid(ou, model, xid) {
-    return `${ou}${SEPARATOR}${model}${SEPARATOR}${xid}`;
+function buildIndexXid(scope, model, xid) {
+    return `${scope}${SEPARATOR}${model}${SEPARATOR}${xid}`;
 }
 /**
  * Auto-populate GSI index keys on an entity
@@ -141,7 +141,7 @@ function buildIndexXid(ou, model, xid) {
  * Uses the model's registered indexes (from vocabulary registry) or
  * DEFAULT_INDEXES if no custom indexes are registered.
  *
- * - indexOu is always populated from ou + model
+ * - indexScope is always populated from scope + model
  * - indexAlias is populated only when alias is present
  * - indexClass is populated only when class is present
  * - indexType is populated only when type is present
@@ -153,7 +153,7 @@ function buildIndexXid(ou, model, xid) {
  */
 function indexEntity(entity, suffix = "") {
     const indexes = getModelIndexes(entity.model);
-    // Cast through unknown to bridge the type gap between StorableEntity and IndexableEntity
+    // Cast through unknown to bridge the type gap between StorableEntity and IndexableModel
     return populateIndexKeys(entity, indexes, suffix);
 }
 
@@ -177,7 +177,7 @@ function calculateEntitySuffix(entity) {
 /**
  * Get a single entity by primary key
  */
-const getEntity = serviceHandler({
+const getEntity = fabricService({
     alias: "getEntity",
     description: "Get a single entity by primary key",
     input: {
@@ -199,7 +199,7 @@ const getEntity = serviceHandler({
  * Put (create or replace) an entity
  * Auto-populates GSI index keys via indexEntity
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) because it accepts
  * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function putEntity({ entity, }) {
@@ -218,7 +218,7 @@ async function putEntity({ entity, }) {
  * Update an existing entity
  * Auto-populates GSI index keys and sets updatedAt
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) because it accepts
  * complex StorableEntity objects that can't be coerced by vocabulary's type system.
  */
 async function updateEntity({ entity, }) {
@@ -240,7 +240,7 @@ async function updateEntity({ entity, }) {
  * Soft delete an entity by setting deletedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const deleteEntity = serviceHandler({
+const deleteEntity = fabricService({
     alias: "deleteEntity",
     description: "Soft delete an entity (sets deletedAt timestamp)",
     input: {
@@ -277,7 +277,7 @@ const deleteEntity = serviceHandler({
  * Archive an entity by setting archivedAt timestamp
  * Re-indexes with appropriate suffix based on archived/deleted state
  */
-const archiveEntity = serviceHandler({
+const archiveEntity = fabricService({
     alias: "archiveEntity",
     description: "Archive an entity (sets archivedAt timestamp)",
     input: {
@@ -314,7 +314,7 @@ const archiveEntity = serviceHandler({
  * Hard delete an entity (permanently removes from table)
  * Use with caution - prefer deleteEntity for soft delete
  */
-const destroyEntity = serviceHandler({
+const destroyEntity = fabricService({
     alias: "destroyEntity",
     description: "Hard delete an entity (permanently removes from table)",
     input: {
@@ -377,16 +377,16 @@ async function executeQuery(indexName, keyValue, options = {}) {
     };
 }
 /**
- * Query entities by organizational unit (parent hierarchy)
- * Uses indexOu GSI
+ * Query entities by scope (parent hierarchy)
+ * Uses indexScope GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByOu({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, }) {
+async function queryByScope({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexOu(ou, model) + suffix;
-    return executeQuery(INDEX_OU, keyValue, {
+    const keyValue = buildIndexScope(scope, model) + suffix;
+    return executeQuery(INDEX_SCOPE, keyValue, {
         ascending,
         limit,
         startKey,
@@ -396,7 +396,7 @@ async function queryByOu({ archived = false, ascending = false, deleted = false,
  * Query a single entity by human-friendly alias
  * Uses indexAlias GSI
  */
-const queryByAlias = serviceHandler({
+const queryByAlias = fabricService({
     alias: "queryByAlias",
     description: "Query a single entity by human-friendly alias",
     input: {
@@ -414,16 +414,19 @@ const queryByAlias = serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
     },
-    service: async ({ alias, archived, deleted, model, ou, }) => {
+    service: async ({ alias, archived, deleted, model, scope, }) => {
         const aliasStr = alias;
         const archivedBool = archived;
         const deletedBool = deleted;
         const modelStr = model;
-        const ouStr = ou;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
-        const keyValue = buildIndexAlias(ouStr, modelStr, aliasStr) + suffix;
+        const scopeStr = scope;
+        const suffix = calculateSuffix({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexAlias(scopeStr, modelStr, aliasStr) + suffix;
         const result = await executeQuery(INDEX_ALIAS, keyValue, {
             limit: 1,
         });
@@ -434,12 +437,12 @@ const queryByAlias = serviceHandler({
  * Query entities by category classification
  * Uses indexClass GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, ou, recordClass, startKey, }) {
+async function queryByClass({ archived = false, ascending = false, deleted = false, limit, model, scope, recordClass, startKey, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexClass(ou, model, recordClass) + suffix;
+    const keyValue = buildIndexClass(scope, model, recordClass) + suffix;
     return executeQuery(INDEX_CLASS, keyValue, {
         ascending,
         limit,
@@ -450,12 +453,12 @@ async function queryByClass({ archived = false, ascending = false, deleted = fal
  * Query entities by type classification
  * Uses indexType GSI
  *
- * Note: This is a regular async function (not serviceHandler) because it accepts
+ * Note: This is a regular async function (not fabricService) because it accepts
  * complex startKey objects that can't be coerced by vocabulary's type system.
  */
-async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, ou, startKey, type, }) {
+async function queryByType({ archived = false, ascending = false, deleted = false, limit, model, scope, startKey, type, }) {
     const suffix = calculateSuffix({ archived, deleted });
-    const keyValue = buildIndexType(ou, model, type) + suffix;
+    const keyValue = buildIndexType(scope, model, type) + suffix;
     return executeQuery(INDEX_TYPE, keyValue, {
         ascending,
         limit,
@@ -466,7 +469,7 @@ async function queryByType({ archived = false, ascending = false, deleted = fals
  * Query a single entity by external ID
  * Uses indexXid GSI
  */
-const queryByXid = serviceHandler({
+const queryByXid = fabricService({
     alias: "queryByXid",
     description: "Query a single entity by external ID",
     input: {
@@ -483,17 +486,20 @@ const queryByXid = serviceHandler({
             description: "Query deleted entities instead of active ones",
         },
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         xid: { type: String, description: "External ID" },
     },
-    service: async ({ archived, deleted, model, ou, xid, }) => {
+    service: async ({ archived, deleted, model, scope, xid, }) => {
         const archivedBool = archived;
         const deletedBool = deleted;
         const modelStr = model;
-        const ouStr = ou;
+        const scopeStr = scope;
         const xidStr = xid;
-        const suffix = calculateSuffix({ archived: archivedBool, deleted: deletedBool });
-        const keyValue = buildIndexXid(ouStr, modelStr, xidStr) + suffix;
+        const suffix = calculateSuffix({
+            archived: archivedBool,
+            deleted: deletedBool,
+        });
+        const keyValue = buildIndexXid(scopeStr, modelStr, xidStr) + suffix;
         const result = await executeQuery(INDEX_XID, keyValue, {
             limit: 1,
         });
@@ -614,7 +620,7 @@ function createTableParams(tableName, billingMode) {
 /**
  * Create DynamoDB table with Jaypie GSI schema
  */
-const createTableHandler = serviceHandler({
+const createTableHandler = fabricService({
     alias: "dynamodb_create_table",
     description: "Create DynamoDB table with Jaypie GSI schema",
     input: {
@@ -678,7 +684,7 @@ const DEFAULT_TABLE_NAME = "jaypie-local";
 /**
  * Generate docker-compose.yml for local DynamoDB development
  */
-const dockerComposeHandler = serviceHandler({
+const dockerComposeHandler = fabricService({
     alias: "dynamodb_generate_docker_compose",
     description: "Generate docker-compose.yml for local DynamoDB development",
     input: {
@@ -776,7 +782,7 @@ function ensureInitialized() {
 /**
  * Check DynamoDB connection status and configuration
  */
-const statusHandler = serviceHandler({
+const statusHandler = fabricService({
     alias: "dynamodb_status",
     description: "Check DynamoDB connection status and configuration",
     service: async () => {
@@ -807,12 +813,12 @@ function wrapWithInit(handler) {
     return wrapped;
 }
 // MCP-specific serviceHandler wrappers for functions with complex inputs
-// Note: These wrap the regular async functions to make them work with registerMcpTool
+// Note: These wrap the regular async functions to make them work with fabricMcp
 /**
  * MCP wrapper for putEntity
  * Accepts entity JSON directly from LLM
  */
-const mcpPutEntity = serviceHandler({
+const mcpPutEntity = fabricService({
     alias: "dynamodb_put",
     description: "Create or replace an entity in DynamoDB (auto-indexes GSI keys)",
     input: {
@@ -820,10 +826,18 @@ const mcpPutEntity = serviceHandler({
         id: { type: String, description: "Entity ID (sort key)" },
         model: { type: String, description: "Entity model name (partition key)" },
         name: { type: String, description: "Entity name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         // Optional fields
-        alias: { type: String, required: false, description: "Human-friendly alias" },
-        class: { type: String, required: false, description: "Category classification" },
+        alias: {
+            type: String,
+            required: false,
+            description: "Human-friendly alias",
+        },
+        class: {
+            type: String,
+            required: false,
+            description: "Category classification",
+        },
         type: { type: String, required: false, description: "Type classification" },
         xid: { type: String, required: false, description: "External ID" },
     },
@@ -836,7 +850,7 @@ const mcpPutEntity = serviceHandler({
             id: input.id,
             model: input.model,
             name: input.name,
-            ou: input.ou,
+            scope: input.scope,
             sequence: Date.now(),
             type: input.type,
             updatedAt: now,
@@ -849,7 +863,7 @@ const mcpPutEntity = serviceHandler({
  * MCP wrapper for updateEntity
  * Accepts entity JSON directly from LLM
  */
-const mcpUpdateEntity = serviceHandler({
+const mcpUpdateEntity = fabricService({
     alias: "dynamodb_update",
     description: "Update an entity in DynamoDB (sets updatedAt, re-indexes GSI keys)",
     input: {
@@ -858,9 +872,17 @@ const mcpUpdateEntity = serviceHandler({
         model: { type: String, description: "Entity model name (partition key)" },
         // Fields that can be updated
         name: { type: String, required: false, description: "Entity name" },
-        ou: { type: String, required: false, description: "Organizational unit" },
-        alias: { type: String, required: false, description: "Human-friendly alias" },
-        class: { type: String, required: false, description: "Category classification" },
+        scope: { type: String, required: false, description: "Scope" },
+        alias: {
+            type: String,
+            required: false,
+            description: "Human-friendly alias",
+        },
+        class: {
+            type: String,
+            required: false,
+            description: "Category classification",
+        },
         type: { type: String, required: false, description: "Type classification" },
         xid: { type: String, required: false, description: "External ID" },
     },
@@ -879,7 +901,7 @@ const mcpUpdateEntity = serviceHandler({
             ...(input.alias !== undefined && { alias: input.alias }),
             ...(input.class !== undefined && { class: input.class }),
             ...(input.name !== undefined && { name: input.name }),
-            ...(input.ou !== undefined && { ou: input.ou }),
+            ...(input.scope !== undefined && { scope: input.scope }),
             ...(input.type !== undefined && { type: input.type }),
             ...(input.xid !== undefined && { xid: input.xid }),
         };
@@ -887,15 +909,15 @@ const mcpUpdateEntity = serviceHandler({
     },
 });
 /**
- * MCP wrapper for queryByOu
+ * MCP wrapper for queryByScope
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByOu = serviceHandler({
-    alias: "dynamodb_query_ou",
-    description: "Query entities by organizational unit (parent hierarchy)",
+const mcpQueryByScope = fabricService({
+    alias: "dynamodb_query_scope",
+    description: "Query entities by scope (parent hierarchy)",
     input: {
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         archived: {
             type: Boolean,
             default: false,
@@ -921,13 +943,13 @@ const mcpQueryByOu = serviceHandler({
         },
     },
     service: async (input) => {
-        return queryByOu({
+        return queryByScope({
             archived: input.archived,
             ascending: input.ascending,
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
         });
     },
 });
@@ -935,12 +957,12 @@ const mcpQueryByOu = serviceHandler({
  * MCP wrapper for queryByClass
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByClass = serviceHandler({
+const mcpQueryByClass = fabricService({
     alias: "dynamodb_query_class",
     description: "Query entities by category classification",
     input: {
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         recordClass: { type: String, description: "Category classification" },
         archived: {
             type: Boolean,
@@ -973,7 +995,7 @@ const mcpQueryByClass = serviceHandler({
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
             recordClass: input.recordClass,
         });
     },
@@ -982,12 +1004,12 @@ const mcpQueryByClass = serviceHandler({
  * MCP wrapper for queryByType
  * Note: Pagination via startKey is not exposed to MCP; use limit instead
  */
-const mcpQueryByType = serviceHandler({
+const mcpQueryByType = fabricService({
     alias: "dynamodb_query_type",
     description: "Query entities by type classification",
     input: {
         model: { type: String, description: "Entity model name" },
-        ou: { type: String, description: "Organizational unit (@ for root)" },
+        scope: { type: String, description: "Scope (@ for root)" },
         type: { type: String, description: "Type classification" },
         archived: {
             type: Boolean,
@@ -1020,7 +1042,7 @@ const mcpQueryByType = serviceHandler({
             deleted: input.deleted,
             limit: input.limit,
             model: input.model,
-            ou: input.ou,
+            scope: input.scope,
             type: input.type,
         });
     },
@@ -1032,80 +1054,80 @@ function registerDynamoDbTools(config) {
     const { includeAdmin = true, server } = config;
     const tools = [];
     // Entity operations
-    registerMcpTool({
-        handler: wrapWithInit(getEntity),
+    fabricMcp({
+        service: wrapWithInit(getEntity),
         name: "dynamodb_get",
         server,
     });
     tools.push("dynamodb_get");
-    registerMcpTool({
-        handler: wrapWithInit(mcpPutEntity),
+    fabricMcp({
+        service: wrapWithInit(mcpPutEntity),
         name: "dynamodb_put",
         server,
     });
     tools.push("dynamodb_put");
-    registerMcpTool({
-        handler: wrapWithInit(mcpUpdateEntity),
+    fabricMcp({
+        service: wrapWithInit(mcpUpdateEntity),
         name: "dynamodb_update",
         server,
     });
     tools.push("dynamodb_update");
-    registerMcpTool({
-        handler: wrapWithInit(deleteEntity),
+    fabricMcp({
+        service: wrapWithInit(deleteEntity),
         name: "dynamodb_delete",
         server,
     });
     tools.push("dynamodb_delete");
-    registerMcpTool({
-        handler: wrapWithInit(archiveEntity),
+    fabricMcp({
+        service: wrapWithInit(archiveEntity),
         name: "dynamodb_archive",
         server,
     });
     tools.push("dynamodb_archive");
-    registerMcpTool({
-        handler: wrapWithInit(destroyEntity),
+    fabricMcp({
+        service: wrapWithInit(destroyEntity),
         name: "dynamodb_destroy",
         server,
     });
     tools.push("dynamodb_destroy");
     // Query operations
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByOu),
-        name: "dynamodb_query_ou",
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByScope),
+        name: "dynamodb_query_scope",
         server,
     });
-    tools.push("dynamodb_query_ou");
-    registerMcpTool({
-        handler: wrapWithInit(queryByAlias),
+    tools.push("dynamodb_query_scope");
+    fabricMcp({
+        service: wrapWithInit(queryByAlias),
         name: "dynamodb_query_alias",
         server,
     });
     tools.push("dynamodb_query_alias");
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByClass),
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByClass),
         name: "dynamodb_query_class",
         server,
     });
     tools.push("dynamodb_query_class");
-    registerMcpTool({
-        handler: wrapWithInit(mcpQueryByType),
+    fabricMcp({
+        service: wrapWithInit(mcpQueryByType),
         name: "dynamodb_query_type",
         server,
     });
     tools.push("dynamodb_query_type");
-    registerMcpTool({
-        handler: wrapWithInit(queryByXid),
+    fabricMcp({
+        service: wrapWithInit(queryByXid),
         name: "dynamodb_query_xid",
         server,
     });
     tools.push("dynamodb_query_xid");
     // Admin tools (MCP-only)
     if (includeAdmin) {
-        registerMcpTool({ handler: statusHandler, server });
+        fabricMcp({ service: statusHandler, server });
         tools.push("dynamodb_status");
-        registerMcpTool({ handler: createTableHandler, server });
+        fabricMcp({ service: createTableHandler, server });
         tools.push("dynamodb_create_table");
-        registerMcpTool({ handler: dockerComposeHandler, server });
+        fabricMcp({ service: dockerComposeHandler, server });
         tools.push("dynamodb_generate_docker_compose");
     }
     return { tools };