@ductape/mcp 0.1.23 → 0.1.25

package/dist/index.js

@@ -54,6 +54,67 @@ There are THREE categories of operations. Use the right tool for each:
            ductape_cli("db migrate rollback")          # roll back last migration
            ductape_cli("db migrate rollback -n 3")     # roll back last 3 migrations
 
+       DATABASE SCHEMA FILE — ductape/database/schema.json
+       ─────────────────────────────────────────────────────────────────────────
+       IMPORTANT: "db schema generate" READS schema.json and emits migration files.
+       It does NOT create schema.json from scratch. You must write this file first.
+
+       If schema.json does not exist, "db schema generate" now auto-creates it and
+       attempts to hydrate it from the cloud (pass --db <tag> to enable cloud hydration):
+           ductape_cli("db schema generate --db statecraft-core")
+       If the cloud database is empty, schema.json will be created as [] and you must
+       populate it before running the command again.
+
+       FILE FORMAT — ductape/database/schema.json is a JSON array:
+       [
+         {
+           "db": "<database-component-tag>",
+           "tables": {
+             "<collection_name>": {
+               "<field_name>": {
+                 "type": "string|number|boolean|date|datetime|timestamp|uuid|object|array|json|text|decimal|bigint|smallint|double|binary|blob|time",
+                 "required": true,          // false by default (nullable)
+                 "unique": true,            // unique constraint on this field
+                 "index": true,             // create an index on this field (use with unique for unique index)
+                 "default": "value",        // default value ("now"/"NOW" → CURRENT_TIMESTAMP)
+                 "maxlength": 255,          // max length for string fields
+                 "enum": ["a", "b", "c"],   // restrict to enum values (sets type to string automatically)
+                 "primaryKey": true,        // mark as primary key
+                 "autoGenerate": true,      // auto-generate value on insert
+                 "float": true             // treat number as float (use with type: "number")
+               }
+             }
+           }
+         }
+       ]
+
+       SINGLE-FIELD INDEX: set index: true (+ unique: true for unique constraint)
+         "matchId": { "type": "string", "required": true, "unique": true, "index": true }
+
+       COMPOSITE INDEX: schema.json does not support composite indexes.
+       After running db schema generate, add a manual migration file in
+       ductape/migrations/<db-tag>/ with type "createIndex" and a fields array:
+         {
+           "tag": "create_map_events_match_seq_idx",
+           "name": "Composite unique index on matchId+sequence",
+           "up": [{
+             "type": "createIndex",
+             "collection": "map_events",
+             "name": "map_events_matchId_sequence_idx",
+             "fields": [{ "name": "matchId" }, { "name": "sequence" }],
+             "unique": true,
+             "ifNotExists": true
+           }],
+           "down": [{ "type": "dropIndex", "collection": "map_events", "name": "map_events_matchId_sequence_idx", "ifExists": true }],
+           "createdAt": "<ISO timestamp>"
+         }
+
+       WORKFLOW:
+         1. Create/edit ductape/database/schema.json with your collection definitions
+         2. ductape_cli("db schema generate --db <tag>")  → writes migration files
+         3. ductape_cli("db migrate --db <tag>")          → applies pending migrations
+         4. Add manual migration files for composite/partial indexes not expressible in schema.json
+
   1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
        ALL creation and update operations require an access key and CANNOT go through ductape_execute.
        → Use ductape_cli for every create/update operation. Examples:
@@ -111,6 +172,107 @@ There are THREE categories of operations. Use the right tool for each:
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+━━━ NESTJS INTEGRATION — use @ductape/nestjs ━━━
+
+When the target application is a NestJS service or controller, always use @ductape/nestjs
+instead of instantiating @ductape/sdk directly. It provides NestJS DI integration,
+global interceptors, decorators, and type-safe resource handles.
+
+SETUP — register once in AppModule:
+
+  import { DuctapeModule } from '@ductape/nestjs';
+
+  @Module({
+    imports: [
+      DuctapeModule.forIntegration({
+        accessKey: process.env.DUCTAPE_ACCESS_KEY,
+        product: 'my-product',   // optional default — overridable per controller
+        env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
+      }),
+    ],
+  })
+  export class AppModule {}
+
+  // Async (e.g. pulling key from ConfigService):
+  DuctapeModule.forRootAsync({
+    imports: [ConfigModule],
+    inject: [ConfigService],
+    useFactory: (cfg: ConfigService) => ({
+      accessKey: cfg.get('DUCTAPE_ACCESS_KEY'),
+      product: cfg.get('DUCTAPE_PRODUCT'),
+      env: cfg.get('DUCTAPE_ENV'),
+    }),
+  })
+
+INJECTING IN SERVICES AND CONTROLLERS — use @InjectContext():
+
+  import { InjectContext, DuctapeContext } from '@ductape/nestjs';
+
+  @Injectable()
+  export class MatchService {
+    constructor(@InjectContext() private readonly ductape: DuctapeContext) {}
+
+    async publishMatchState(matchId: string, state: object) {
+      await this.ductape.sdk.events.produce({
+        product: 'my-product',
+        env: 'prd',
+        event: 'statecraft-events:match-state',
+        message: { matchId, ...state },
+      });
+    }
+
+    async queryDatabase(env: string) {
+      const db = await this.ductape.database('core-db', { env });
+      return db.query({ table: 'matches', where: { active: true } });
+    }
+  }
+
+AVAILABLE ON DuctapeContext:
+
+  ctx.sdk                          — full @ductape/sdk instance (events, sessions, etc.)
+  ctx.database(tag, overrides?)    — connected DatabaseHandle (query, insert, update, delete)
+  ctx.storage(tag, overrides?)     — StorageHandle (upload, download, remove)
+  ctx.cache(tag, overrides?)       — CacheHandle (get, set, delete)
+  ctx.graph(tag, overrides?)       — GraphHandle
+  ctx.vector(tag, overrides?)      — VectorHandle
+  ctx.agent(tag, overrides?)       — AgentHandle
+  ctx.warehouse(overrides?)        — WarehouseHandle
+  ctx.cloudTiers(query?)           — query available cloud resource tiers and pricing
+  ctx.runJob({ product, env, event, input? })  — trigger a product job
+
+CONTROLLER DECORATORS:
+
+  @Product('my-product')   — override default product at class or method level
+  @Env('prd')              — override default env
+  @ApiRun({ app, action }) — bind a controller method to an app action (interceptor runs it automatically)
+  @ApiConfig({ app, ... }) — shared app credentials at class level
+  @Webhook.Register(...)   — register a webhook consumer URL
+  @Webhook.Consumer(...)   — mark inbound handler for forwarded webhook payloads
+
+FOR MESSAGING (events.produce / events.consume):
+
+  Access via ctx.sdk.events — no dedicated NestJS handle, the SDK instance is sufficient:
+
+  await this.ductape.sdk.events.produce({
+    product: 'my-product', env: 'prd',
+    event: 'broker-tag:topic-tag',
+    message: { ... },
+  });
+
+  await this.ductape.sdk.events.consume({
+    product: 'my-product', env: 'prd',
+    event: 'broker-tag:topic-tag',
+    callback: async (message) => { /* handle */ },
+  });
+
+SPECIALIZED MODULES (for injecting handles directly without @InjectContext):
+
+  DuctapeDatabaseModule.forTags(['core-db'])   → inject with @Database('core-db')
+  DuctapeStorageModule.forTags(['assets'])     → inject with @Storage('assets')
+  DuctapeCacheModule, DuctapeGraphModule, DuctapeVectorModule — same pattern
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 ALL params are passed as a JSON array in positional order matching the SDK signature.
 
 ━━━ MODULE: product ━━━
@@ -340,11 +502,23 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   storage.dispatch [{ product, env, storage, operation, input, retries?, session?, cache?, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="storage", method="dispatch", targets={storage})
 
 ━━━ MODULE: databases ━━━
-  databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite", envs: [{slug, connection_url}] }]
+  databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite",
+                       envs: [{ slug, connection_url?,
+                                cloud?,        ← workspace cloud-connection tag (omit connection_url when using this)
+                                authMode?,     ← "cloud_connection" when using cloud field
+                                dbName?,       ← REQUIRED for MongoDB cloud connections — the database name inside the cluster (e.g. "myapp_snd")
+                                instance?,     ← RDS/Cloud SQL instance id (provision flow only)
+                                region? }] }]
+  MONGODB CLOUD CONNECTION RULE: when type="mongodb" and cloud is set, dbName is MANDATORY.
+    Without dbName the Atlas API returns a URL with no database name and the adapter will throw
+    at migrate/connect time. Provide one dbName per env — they typically differ per environment:
+    e.g. { slug:"snd", cloud:"atlas-conn", authMode:"cloud_connection", dbName:"myapp_snd" }
+        { slug:"prd", cloud:"atlas-conn", authMode:"cloud_connection", dbName:"myapp_prd" }
   databases.register [product_tag, data: IProductDatabase]
   databases.list    [product_tag]
   databases.fetch   [product_tag, database_tag]
-  databases.updateDatabase [product_tag, database_tag, data: { name?: string, description?: string, type?: "postgresql"|"mongodb"|"mysql", envs?: [{ slug: string, connection_url: string, description?: string }] }]
+  databases.updateDatabase [product_tag, database_tag, data: { name?, description?, type?,
+                             envs?: [{ slug, connection_url?, cloud?, authMode?, dbName?, instance?, region? }] }]
   databases.connect [{ product, env, database }]
   databases.testConnection [{ product, env, database }]
   databases.disconnect []
@@ -2490,6 +2664,8 @@ async function main() {
                 '    azure-blob→storage, cloud-sql→database, neptune→graph, opensearch→vector. Attempting an unsupported pair\n' +
                 '    will return an error; do not retry with a different tier — report the limitation to the user.\n' +
                 '  - Atlas (MongoDB Atlas) import flow — service identifier is "atlas-cluster" (required, not optional):\n' +
+                '    IMPORTANT: dbName is mandatory for every MongoDB env — see "MONGODB CLOUD CONNECTION RULE" in the\n' +
+                '    databases module above. The SDK enforces this at create time; omitting it throws a validation error.\n' +
                 '    Step 1 — discover the cluster name:\n' +
                 '      ductape_cli("cloud resources list -f /tmp/atlas-list.json --json")\n' +
                 '      File: {"cloud": "<atlas-connection-tag>", "service": "atlas-cluster"}\n' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",

package/src/index.ts

@@ -65,6 +65,67 @@ There are THREE categories of operations. Use the right tool for each:
            ductape_cli("db migrate rollback")          # roll back last migration
            ductape_cli("db migrate rollback -n 3")     # roll back last 3 migrations
 
+       DATABASE SCHEMA FILE — ductape/database/schema.json
+       ─────────────────────────────────────────────────────────────────────────
+       IMPORTANT: "db schema generate" READS schema.json and emits migration files.
+       It does NOT create schema.json from scratch. You must write this file first.
+
+       If schema.json does not exist, "db schema generate" now auto-creates it and
+       attempts to hydrate it from the cloud (pass --db <tag> to enable cloud hydration):
+           ductape_cli("db schema generate --db statecraft-core")
+       If the cloud database is empty, schema.json will be created as [] and you must
+       populate it before running the command again.
+
+       FILE FORMAT — ductape/database/schema.json is a JSON array:
+       [
+         {
+           "db": "<database-component-tag>",
+           "tables": {
+             "<collection_name>": {
+               "<field_name>": {
+                 "type": "string|number|boolean|date|datetime|timestamp|uuid|object|array|json|text|decimal|bigint|smallint|double|binary|blob|time",
+                 "required": true,          // false by default (nullable)
+                 "unique": true,            // unique constraint on this field
+                 "index": true,             // create an index on this field (use with unique for unique index)
+                 "default": "value",        // default value ("now"/"NOW" → CURRENT_TIMESTAMP)
+                 "maxlength": 255,          // max length for string fields
+                 "enum": ["a", "b", "c"],   // restrict to enum values (sets type to string automatically)
+                 "primaryKey": true,        // mark as primary key
+                 "autoGenerate": true,      // auto-generate value on insert
+                 "float": true             // treat number as float (use with type: "number")
+               }
+             }
+           }
+         }
+       ]
+
+       SINGLE-FIELD INDEX: set index: true (+ unique: true for unique constraint)
+         "matchId": { "type": "string", "required": true, "unique": true, "index": true }
+
+       COMPOSITE INDEX: schema.json does not support composite indexes.
+       After running db schema generate, add a manual migration file in
+       ductape/migrations/<db-tag>/ with type "createIndex" and a fields array:
+         {
+           "tag": "create_map_events_match_seq_idx",
+           "name": "Composite unique index on matchId+sequence",
+           "up": [{
+             "type": "createIndex",
+             "collection": "map_events",
+             "name": "map_events_matchId_sequence_idx",
+             "fields": [{ "name": "matchId" }, { "name": "sequence" }],
+             "unique": true,
+             "ifNotExists": true
+           }],
+           "down": [{ "type": "dropIndex", "collection": "map_events", "name": "map_events_matchId_sequence_idx", "ifExists": true }],
+           "createdAt": "<ISO timestamp>"
+         }
+
+       WORKFLOW:
+         1. Create/edit ductape/database/schema.json with your collection definitions
+         2. ductape_cli("db schema generate --db <tag>")  → writes migration files
+         3. ductape_cli("db migrate --db <tag>")          → applies pending migrations
+         4. Add manual migration files for composite/partial indexes not expressible in schema.json
+
   1. ASSET CREATION / UPDATE  (create, update, add, register… for ANY asset type)
        ALL creation and update operations require an access key and CANNOT go through ductape_execute.
        → Use ductape_cli for every create/update operation. Examples:
@@ -122,6 +183,107 @@ There are THREE categories of operations. Use the right tool for each:
 
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
+━━━ NESTJS INTEGRATION — use @ductape/nestjs ━━━
+
+When the target application is a NestJS service or controller, always use @ductape/nestjs
+instead of instantiating @ductape/sdk directly. It provides NestJS DI integration,
+global interceptors, decorators, and type-safe resource handles.
+
+SETUP — register once in AppModule:
+
+  import { DuctapeModule } from '@ductape/nestjs';
+
+  @Module({
+    imports: [
+      DuctapeModule.forIntegration({
+        accessKey: process.env.DUCTAPE_ACCESS_KEY,
+        product: 'my-product',   // optional default — overridable per controller
+        env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
+      }),
+    ],
+  })
+  export class AppModule {}
+
+  // Async (e.g. pulling key from ConfigService):
+  DuctapeModule.forRootAsync({
+    imports: [ConfigModule],
+    inject: [ConfigService],
+    useFactory: (cfg: ConfigService) => ({
+      accessKey: cfg.get('DUCTAPE_ACCESS_KEY'),
+      product: cfg.get('DUCTAPE_PRODUCT'),
+      env: cfg.get('DUCTAPE_ENV'),
+    }),
+  })
+
+INJECTING IN SERVICES AND CONTROLLERS — use @InjectContext():
+
+  import { InjectContext, DuctapeContext } from '@ductape/nestjs';
+
+  @Injectable()
+  export class MatchService {
+    constructor(@InjectContext() private readonly ductape: DuctapeContext) {}
+
+    async publishMatchState(matchId: string, state: object) {
+      await this.ductape.sdk.events.produce({
+        product: 'my-product',
+        env: 'prd',
+        event: 'statecraft-events:match-state',
+        message: { matchId, ...state },
+      });
+    }
+
+    async queryDatabase(env: string) {
+      const db = await this.ductape.database('core-db', { env });
+      return db.query({ table: 'matches', where: { active: true } });
+    }
+  }
+
+AVAILABLE ON DuctapeContext:
+
+  ctx.sdk                          — full @ductape/sdk instance (events, sessions, etc.)
+  ctx.database(tag, overrides?)    — connected DatabaseHandle (query, insert, update, delete)
+  ctx.storage(tag, overrides?)     — StorageHandle (upload, download, remove)
+  ctx.cache(tag, overrides?)       — CacheHandle (get, set, delete)
+  ctx.graph(tag, overrides?)       — GraphHandle
+  ctx.vector(tag, overrides?)      — VectorHandle
+  ctx.agent(tag, overrides?)       — AgentHandle
+  ctx.warehouse(overrides?)        — WarehouseHandle
+  ctx.cloudTiers(query?)           — query available cloud resource tiers and pricing
+  ctx.runJob({ product, env, event, input? })  — trigger a product job
+
+CONTROLLER DECORATORS:
+
+  @Product('my-product')   — override default product at class or method level
+  @Env('prd')              — override default env
+  @ApiRun({ app, action }) — bind a controller method to an app action (interceptor runs it automatically)
+  @ApiConfig({ app, ... }) — shared app credentials at class level
+  @Webhook.Register(...)   — register a webhook consumer URL
+  @Webhook.Consumer(...)   — mark inbound handler for forwarded webhook payloads
+
+FOR MESSAGING (events.produce / events.consume):
+
+  Access via ctx.sdk.events — no dedicated NestJS handle, the SDK instance is sufficient:
+
+  await this.ductape.sdk.events.produce({
+    product: 'my-product', env: 'prd',
+    event: 'broker-tag:topic-tag',
+    message: { ... },
+  });
+
+  await this.ductape.sdk.events.consume({
+    product: 'my-product', env: 'prd',
+    event: 'broker-tag:topic-tag',
+    callback: async (message) => { /* handle */ },
+  });
+
+SPECIALIZED MODULES (for injecting handles directly without @InjectContext):
+
+  DuctapeDatabaseModule.forTags(['core-db'])   → inject with @Database('core-db')
+  DuctapeStorageModule.forTags(['assets'])     → inject with @Storage('assets')
+  DuctapeCacheModule, DuctapeGraphModule, DuctapeVectorModule — same pattern
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
 ALL params are passed as a JSON array in positional order matching the SDK signature.
 
 ━━━ MODULE: product ━━━
@@ -351,11 +513,23 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   storage.dispatch [{ product, env, storage, operation, input, retries?, session?, cache?, schedule? }]  ← CALL ductape_generate_payload FIRST (operation_family="storage", method="dispatch", targets={storage})
 
 ━━━ MODULE: databases ━━━
-  databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite", envs: [{slug, connection_url}] }]
+  databases.create  [{ product, tag, name, description?, type: "mongodb"|"postgresql"|"mysql"|"sqlite",
+                       envs: [{ slug, connection_url?,
+                                cloud?,        ← workspace cloud-connection tag (omit connection_url when using this)
+                                authMode?,     ← "cloud_connection" when using cloud field
+                                dbName?,       ← REQUIRED for MongoDB cloud connections — the database name inside the cluster (e.g. "myapp_snd")
+                                instance?,     ← RDS/Cloud SQL instance id (provision flow only)
+                                region? }] }]
+  MONGODB CLOUD CONNECTION RULE: when type="mongodb" and cloud is set, dbName is MANDATORY.
+    Without dbName the Atlas API returns a URL with no database name and the adapter will throw
+    at migrate/connect time. Provide one dbName per env — they typically differ per environment:
+    e.g. { slug:"snd", cloud:"atlas-conn", authMode:"cloud_connection", dbName:"myapp_snd" }
+        { slug:"prd", cloud:"atlas-conn", authMode:"cloud_connection", dbName:"myapp_prd" }
   databases.register [product_tag, data: IProductDatabase]
   databases.list    [product_tag]
   databases.fetch   [product_tag, database_tag]
-  databases.updateDatabase [product_tag, database_tag, data: { name?: string, description?: string, type?: "postgresql"|"mongodb"|"mysql", envs?: [{ slug: string, connection_url: string, description?: string }] }]
+  databases.updateDatabase [product_tag, database_tag, data: { name?, description?, type?,
+                             envs?: [{ slug, connection_url?, cloud?, authMode?, dbName?, instance?, region? }] }]
   databases.connect [{ product, env, database }]
   databases.testConnection [{ product, env, database }]
   databases.disconnect []
@@ -2616,6 +2790,8 @@ async function main() {
           '    azure-blob→storage, cloud-sql→database, neptune→graph, opensearch→vector. Attempting an unsupported pair\n' +
           '    will return an error; do not retry with a different tier — report the limitation to the user.\n' +
           '  - Atlas (MongoDB Atlas) import flow — service identifier is "atlas-cluster" (required, not optional):\n' +
+          '    IMPORTANT: dbName is mandatory for every MongoDB env — see "MONGODB CLOUD CONNECTION RULE" in the\n' +
+          '    databases module above. The SDK enforces this at create time; omitting it throws a validation error.\n' +
           '    Step 1 — discover the cluster name:\n' +
           '      ductape_cli("cloud resources list -f /tmp/atlas-list.json --json")\n' +
           '      File: {"cloud": "<atlas-connection-tag>", "service": "atlas-cluster"}\n' +