@ductape/mcp 0.2.33 → 0.2.35

package/dist/index.js

@@ -311,6 +311,31 @@ 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. It also hydrates the selected Workbench App
+  connection for product+env (variables and token_access credentials). Do not emit api.config()
+  or api.oauth() boilerplate when that connection is already configured on the product. Explicit
+  api.config() is only a process-local override and has higher precedence. credential_access login
+  material remains isolated to the auth action and its encrypted refresh path. External provider/
+  database connections remain lazy and pooled.
+
+  Features, Quotas, Fallbacks, health checks, and direct api.run calls all reuse this same hydrated
+  connection through the action processor. Never create a second connection or copy secrets into a
+  Feature/Quota/Fallback definition. Reference the existing connected App access_tag and action tag.
+
+  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 +363,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 +378,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 },
     }),
   })
 
@@ -473,6 +500,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     ductape_cli("products apps list --product <id_or_tag> --json") ← compact linked apps only
     ductape_cli("products apps actions list --product <id_or_tag> --app <app_tag> --json")
     ductape_cli("products apps actions get --product <id_or_tag> --app <app_tag> --action <action_tag> --json")
+    ductape_cli("products apps configure --product <id_or_tag> --app <app_or_access_tag> --connection-file ductape/apps/<app_tag>/connection.json --json")
 
   SDK method signatures (for reference, admin key only):
   product.create        [data: { name, description, tag?, envs?: [{slug, name}] }]
@@ -484,6 +512,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   product.apps.add      [product_tag, app: { access_tag, envs: [{ app_env_slug, product_env_slug, variables?, auth? }] }]
   product.apps.list     [product_tag]
   product.apps.fetch    [product_tag, access_tag]
+  product.apps.update   [product_tag, access_tag, { envs }]  ← prefer CLI configure; it preserves omitted auth/variables
 
 ━━━ MODULE: app ━━━
   app.create    [data: { app_name: string, description: string, unique?: boolean }]
@@ -1186,6 +1215,11 @@ const marketplaceConnectInputSchema = z.object({
         product_env_slug: z.string().min(1),
     })).min(1).describe('Explicit app-to-product environment mappings. Include every product environment that will use the app.'),
 });
+const appConnectionConfigureInputSchema = z.object({
+    product_tag: z.string().min(1).describe('Product containing the existing App connection.'),
+    app_tag: z.string().min(1).describe('Connected App tag or exact product access tag returned by products apps list.'),
+    file: z.string().min(1).describe('Canonical JSON file under ductape/apps/<app-tag>/connection.json containing { envs: [...] }.'),
+});
 const marketplaceInspectInputSchema = z.object({
     app_tag: z.string().min(1).describe('Exact public app tag returned by ductape_marketplace_discover.'),
 });
@@ -1312,18 +1346,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 +1638,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 +2549,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
@@ -3015,20 +3088,49 @@ CONNECT A DISCOVERED APP THROUGH MCP:
   4. Match each product environment explicitly to one environment exposed by the app.
   5. Call ductape_marketplace_connect({ product_tag, app_tag, environments }).
   6. Verify with ductape_cli("products apps list --product <product_tag> --json").
+  7. If the App requires variables or auth, create the canonical file at
+     ductape/apps/<app_tag>/connection.json and call ductape_app_connection_configure. A bare
+     connect only establishes access + environment mapping; it does not invent configuration.
   Never guess environment mappings or action tags. Connecting mutates product configuration;
   obtain user approval when the user has not already requested the connection.
 
-  CONFIRMED LIMITATION (2026-08-17): both ductape_marketplace_connect and the equivalent
-  ductape_cli("products apps connect --product <tag> --app <app-tag> --env-map ...") reject any
-  app that is not marked public in the marketplace, with error
-  App "<tag>" is not public in the marketplace. This includes apps a user creates themselves under
-  their own tag (e.g. a private "ductape:paystack") — private/workspace-owned apps CANNOT be
-  connected to a product through MCP or CLI at all, only through Workbench, even though
-  ductape_marketplace_inspect can still read a private app's full action catalogue (inspect and
-  connect have different visibility rules). If you hit this, do not keep retrying — tell the user
-  the app must be connected via Workbench, and once they confirm it's connected, verify with
-  ductape_cli("products apps list --product <product_tag> --json") rather than attempting the
-  connect call again.
+  Visibility: public marketplace Apps and private Apps owned by the current workspace can be
+  connected. A private App owned by another workspace must be rejected; do not retry around that
+  ownership boundary.
+
+CONNECTION FILE — REQUIRED SHAPE:
+  File: ductape/apps/<app_tag>/connection.json
+  {
+    "envs": [{
+      "product_env_slug": "prd",
+      "app_env_slug": "production",
+      "variables": [{ "key": "region", "value": "ng" }],
+      "auth": {
+        "auth_tag": "secret-key",
+        "data": {
+          "headers": { "Authorization": "$Secret{PAYSTACK_SECRET_KEY}" },
+          "query": {}, "params": {}, "body": {}
+        }
+      }
+    }]
+  }
+
+  Before writing this file, inspect the exact App version/auth/action schemas. auth.data must have
+  headers/query/params/body objects and must match the selected auth schema. Never guess an auth_tag,
+  variable key, input location, or required field. Store credentials with secrets.create first and
+  write $Secret{KEY}, never plaintext, into the connection file.
+
+CREATE/REPAIR/ROTATE:
+  ductape_cli("products apps configure --product <product_tag> --app <app_or_access_tag> \
+    --connection-file ductape/apps/<app_tag>/connection.json --json")
+  The command is merge-safe: an omitted auth or variables field preserves the existing saved field.
+  Providing auth or variables explicitly replaces that field for the named product environment.
+  It never returns saved credential values. Include only environments intentionally being changed;
+  other existing mappings are retained. To repair an old connection with no mapping, add its row.
+
+  After configuration, verify the non-secret summary with products apps list, then inspect the exact
+  action contract. Do not test a payment or other side-effecting action merely to verify connection
+  persistence unless the user explicitly requests a safe test and supplies appropriate test input.
 
 ONLY after all five steps can any code call:
   ctx.api.run({ app: '<app_tag>', action: '<action_tag>', input: { ... } })   ← in a feature handler
@@ -3202,8 +3304,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 +4642,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 +4670,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)
@@ -5665,6 +5775,12 @@ const integrateEndpointHandler = async (args) => {
             'Run: ductape_cli("products apps connect --product <product_tag> --app <app_tag> --env-map ' +
                 '<app_env>:<product_env> [repeat --env-map per environment] --json"). If the app is a public ' +
                 'marketplace app, ductape_marketplace_connect does the same thing in one call.',
+            'If the App declares variables or auth, connecting is not the end: call ductape_schema for the ' +
+                'exact app/auth contract, store credential values with secrets.create, write ' +
+                'ductape/apps/<app_tag>/connection.json using $Secret{KEY} references, and call ' +
+                'ductape_app_connection_configure. Never put plaintext secrets in the asset file.',
+            'For an already-connected App, skip connect and use configure. Omitted auth/variables preserve ' +
+                'the current encrypted values, so mapping-only repairs must not force credential rotation.',
         ],
     });
     stages.push({
@@ -5867,6 +5983,11 @@ const DUCTAPE_FIRST_DOCTRINE = 'Follow this checklist before defaulting to plain
     '(ductape.functions.register/use) — register portable business logic once and reuse it across ' +
     'every Feature that needs it. Call ductape_schema before constructing any new resource file, ' +
     'so you match the exact required shape rather than guessing.\n\n' +
+    '7. A Workbench App connection is perpetual product+environment runtime configuration. Once its ' +
+    'environment mapping, variables, and auth are saved, generated server code must initialize the ' +
+    'SDK with product+env and await ready(); do not repeat api.config/api.oauth in every codebase. ' +
+    'Direct actions, Features, Quotas, Fallbacks, and health checks reuse that hydrated connection. ' +
+    'Use api.config only when the user explicitly asks for a local override.\n\n' +
     'Default assumption for any backend built through this MCP server: orchestration goes through ' +
     'Features, provider risk goes through Quotas/Fallback, credentials go through Secrets, shared ' +
     'capability goes through reuse, and the ductape/ folder is what ships — not a database table ' +
@@ -6613,6 +6734,28 @@ async function main() {
                 command: `products apps connect --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)}${mappings} --json`,
             });
         });
+        server.registerTool('ductape_app_connection_configure', {
+            title: 'Configure a Connected Ductape App',
+            description: 'Configure, repair, or rotate an existing product App connection from its canonical JSON asset. ' +
+                'Inspect the App/auth schema first, store secrets separately, use $Secret{KEY} references, and ' +
+                'keep the file under ductape/apps/<app-tag>/connection.json. Omitted auth or variables preserve ' +
+                'the saved encrypted field; the tool never reads credential values back.',
+            inputSchema: appConnectionConfigureInputSchema,
+        }, async (args) => {
+            const normalized = args.file.replace(/\\/g, '/');
+            if (!/(^|\/)ductape\/apps\/[^/]+\/connection\.json$/.test(normalized)) {
+                return {
+                    content: [{ type: 'text', text: JSON.stringify({
+                                error: 'INVALID_ASSET_PATH',
+                                message: 'Connection assets must be permanent JSON files at ductape/apps/<app-tag>/connection.json.',
+                            }, null, 2) }],
+                    isError: true,
+                };
+            }
+            return cliHandler({
+                command: `products apps configure --product ${shellArgument(args.product_tag)} --app ${shellArgument(args.app_tag)} --connection-file ${shellArgument(args.file)} --json`,
+            });
+        });
         server.registerTool('ductape_integrate_endpoint', {
             title: 'Integrate a New Endpoint',
             description: 'Call this FIRST whenever the user wants to integrate a new API endpoint — before writing any ' +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.33",
+  "version": "0.2.35",
   "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"
   },