@ductape/mcp 0.2.33 → 0.2.34

package/dist/index.js

@@ -311,6 +311,23 @@ When the target application is a NestJS service or controller, always use @ducta
 instead of instantiating @ductape/sdk directly. It provides NestJS DI integration,
 global interceptors, decorators, and type-safe resource handles.
 
+PRODUCT RUNTIME SNAPSHOT — REQUIRED FOR SERVER INITIALIZATION:
+  Always provide both product and env at module initialization. Nest awaits the SDK's initial
+  product runtime snapshot during onModuleInit, before the application accepts traffic. The
+  snapshot preloads connected App versions/actions plus database actions/schema metadata, graphs,
+  vectors, storage, brokers/topics, sessions, notifications, resilience assets, agents, functions,
+  and caches into the execution bootstrap cache. External provider/database connections remain
+  lazy and pooled.
+
+  Runtime synchronization is enabled by default when product + env are present. Do not set
+  runtimeSync:false merely to simplify generated code. Configure it only when the user has an
+  explicit operational reason:
+    runtimeSync: { intervalMs: 30_000, jitter: 0.2, maxBackoffMs: 300_000 }
+
+  Polling uses runtimeRevision + HTTP ETag/304. databaseRevision is a refresh hint included in the
+  umbrella runtimeRevision, so schema and Database Action changes are detected. Failed refreshes
+  retain the last-known-good snapshot. Nest stops polling through onModuleDestroy automatically.
+
 SETUP — register once in AppModule:
 
   ╔══════════════════════════════════════════════════════════════════════════╗
@@ -338,6 +355,7 @@ SETUP — register once in AppModule:
         product: 'my-product',
         env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
         redisUrl: process.env.DUCTAPE_REDIS_URL,  // required — no dispatch() works without this
+        runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
       }),
     ],
   })
@@ -352,6 +370,7 @@ SETUP — register once in AppModule:
       product: cfg.get('DUCTAPE_PRODUCT'),
       env: cfg.get('DUCTAPE_ENV'),
       redisUrl: cfg.get('DUCTAPE_REDIS_URL'),  // required — no dispatch() works without this
+      runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
     }),
   })
 
@@ -1312,18 +1331,24 @@ function buildTypeScriptSnippet(payload, operationFamily, method) {
     const invocationArgs = buildSdkInvocationArgs(payload);
     return `import Ductape from "@ductape/sdk";
 
+const payload = ${toPrettyJson(payload)};
 const ductape = new Ductape({
-  workspace_id: process.env.DUCTAPE_WORKSPACE_ID!,
-  user_id: process.env.DUCTAPE_USER_ID!,
-  public_key: process.env.DUCTAPE_PUBLIC_KEY!,
+  accessKey: process.env.DUCTAPE_ACCESS_KEY!,
+  product: String(payload.product),
+  env: String(payload.env),
   redis_url: process.env.DUCTAPE_REDIS_URL,
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
 });
 
 async function run() {
-  const payload = ${toPrettyJson(payload)};
+  await ductape.ready();
   const args = ${toPrettyJson(invocationArgs)};
-  const result = await ductape.${callPath}(args);
-  return { payload, result };
+  try {
+    const result = await ductape.${callPath}(args);
+    return { payload, result };
+  } finally {
+    await ductape.close();
+  }
 }
 
 run().catch(console.error);
@@ -1598,7 +1623,7 @@ function shellArgument(value) {
 }
 const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
-        'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
+        'transactions, presave, triggers, aggregations, migrations, indexes, performance, runtime-sync, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
         'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue'),
 });
@@ -2509,6 +2534,39 @@ DUCTAPE DATABASE PERFORMANCE GUIDANCE
 5. Caching
    - For read-heavy, rarely-changing data use caches.get before databases.query.
    - Invalidate cache keys in an afterWrite trigger (see ductape_docs({ topic: "triggers" })).
+`.trim(),
+    'runtime-sync': `
+DUCTAPE PRODUCT RUNTIME SNAPSHOTS
+
+For every long-lived TypeScript/Node backend, initialize @ductape/sdk with accessKey, product,
+and env, then await ready() before accepting work:
+
+  const ductape = new Ductape({
+    accessKey: process.env.DUCTAPE_ACCESS_KEY!,
+    product: "payments",
+    env: "prd",
+    runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000 },
+  });
+  await ductape.ready();
+
+This fetches one environment-scoped product snapshot and primes the existing bootstrap cache with
+connected App versions/actions, databases/actions/table schemas, graphs, vectors, storage,
+brokers/topics, sessions, notifications, resilience assets, agents, functions, and caches.
+Connections remain lazy and pooled; snapshot bootstrap does not call external providers.
+
+Runtime synchronization is automatic when product + env are supplied:
+  - Conditional polling sends If-None-Match with runtimeRevision; unchanged state returns HTTP 304.
+  - runtimeRevision is authoritative. databaseRevision, connectionRevision, secretRevision, and
+    assetRevision are narrower change hints. Any databaseRevision change also changes runtimeRevision.
+  - A changed snapshot is loaded off-path and atomically replaces cache entries. Deleted assets are removed.
+  - Refresh failure retains the last-known-good snapshot and retries with jittered exponential backoff.
+  - Use runtimeSnapshotStatus() for revision/error telemetry and refreshRuntime() for an explicit pull.
+  - Call close() during process shutdown. Do not create one Ductape instance per request.
+
+For NestJS, use DuctapeModule.forIntegration({ accessKey, product, env, runtimeSync }) instead of
+new Ductape(). @ductape/nestjs awaits ready() in onModuleInit and closes the poller in
+onModuleDestroy. Never omit product/env when the service has stable defaults: doing so disables
+product snapshot bootstrap and returns execution to lazy per-asset bootstrap misses.
 `.trim(),
     actions: `
 DUCTAPE DATABASE ACTIONS
@@ -3202,8 +3260,11 @@ Product structure (IProduct fields):
   workflows[] (features), models[], agents[], jobs[]
 
 Bootstrap (single API call returning product context + component config + private key):
-  Each service makes a single bootstrap call at first use; results are cached in BootstrapCache
-  (Redis when available). This avoids repeated round-trips in high-frequency paths.
+  Initialize @ductape/sdk with product + env and await ductape.ready(). It fetches the full
+  environment-scoped product runtime snapshot and primes BootstrapCache for connected App actions
+  and product components. A service falls back to its targeted bootstrap endpoint only when the
+  requested asset is absent. Polling uses ETag/304 and atomically refreshes changed state.
+  See ductape_docs({ topic: "runtime-sync" }).
 `.trim(),
     sessions: `
 DUCTAPE SESSIONS
@@ -4537,8 +4598,12 @@ Import (register an EXISTING cloud resource):
     // dispatch() requires redis_url in the Ductape initialization options — it throws at runtime without it.
     const ductape = new Ductape({
       accessKey: process.env.DUCTAPE_ACCESS_KEY,
+      product: "my-product",
+      env: "prd",
       redis_url: process.env.DUCTAPE_REDIS_URL,  // required for any dispatch(); omit only if never dispatching
+      runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
     });
+    await ductape.ready();
     await ductape.events.produce({
       product: "my-product",
       env: "prd",
@@ -4561,6 +4626,7 @@ Import (register an EXISTING cloud resource):
         product: 'my-product',
         env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
         redisUrl: process.env.DUCTAPE_REDIS_URL,  // required — dispatch() throws without this
+        runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
       }),
     });
     // Environment: DUCTAPE_REDIS_URL=redis://localhost:6379 (local) or rediss://:<pw>@host:6380 (managed)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.33",
+  "version": "0.2.34",
   "description": "MCP server that exposes Ductape SDK operations via the backend proxy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
   ],
   "scripts": {
     "build": "tsc",
-    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-paystack-action-schema.mjs && node scripts/check-portable-functions.mjs && node scripts/check-feature-control-flow.mjs && node scripts/check-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-guidance.mjs && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },