@ductape/mcp 0.2.36 → 0.3.0

package/dist/action-contract.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"action-contract.d.ts","sourceRoot":"","sources":["../src/action-contract.ts"],"names":[],"mappings":"AAiFA,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYnE"}
+{"version":3,"file":"action-contract.d.ts","sourceRoot":"","sources":["../src/action-contract.ts"],"names":[],"mappings":"AAoFA,wBAAgB,2BAA2B,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAYnE"}

package/dist/action-contract.js

@@ -61,8 +61,11 @@ function schemaFromLocation(value) {
             property.description = String(item.description);
         if (item.sampleValue !== undefined && item.sampleValue !== '')
             property.example = item.sampleValue;
+        const defaultValue = item.defaultValue ?? item.default_value ?? item.default ?? item.value;
+        if (defaultValue !== undefined && defaultValue !== '')
+            property.default = defaultValue;
         properties[key] = property;
-        if (item.required === true)
+        if (item.required === true || String(item.required).toLowerCase() === 'true')
             required.push(key);
     }
     for (const row of legacyRows) {
@@ -77,6 +80,7 @@ function schemaFromLocation(value) {
             type: 'string',
             ...(description ? { description } : {}),
             ...(item.value !== undefined ? { example: item.value } : {}),
+            ...(item.value !== undefined && item.value !== '' ? { default: item.value } : {}),
         };
         if (/\(required\)|^required\b/i.test(description))
             required.push(key);

package/dist/index.js

@@ -16,6 +16,7 @@ import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
 import { normalizeLiveActionContract } from './action-contract.js';
+import { runtimeInputRecovery } from './runtime-recovery.js';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 import { EVENTS_DELIVERY_SEMANTICS, EVENTS_IMPLEMENTATION_WARNING, eventsCapabilityOverview, inspectEventsComponent, searchEventsCapabilities, } from './events-capabilities.js';
 const MODULES = [
@@ -527,6 +528,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     ductape_cli("apps actions list --app <app_tag> --json")
     ductape_cli("apps actions get --app <app_tag> --action <action_tag> --json")
     ductape_cli("apps actions delete --app <app_tag> --action <action_tag>")
+  Reuse the same canonical full action asset for create and update. An unchanged top-level tag is
+  accepted and stripped locally before the immutable action is patched; never create a second
+  partial-update file. A tag that differs from --action is rejected before any mutation.
   NOTE: the flag is --action-file, NOT -f/--file — that flag belongs to the parent "apps" command
   (used by "apps create"/"apps update"), and Commander resolves a flag shared by an ancestor and a
   descendant against the ancestor, so -f here would silently never reach this subcommand. Verified
@@ -1352,7 +1356,7 @@ const ductape = new Ductape({
   product: String(payload.product),
   env: String(payload.env),
   redis_url: process.env.DUCTAPE_REDIS_URL,
-  runtime_sync: { interval_ms: 30_000, jitter: 0.2 },
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2, warm_connections: true },
 });
 
 async function run() {
@@ -1445,6 +1449,7 @@ const ADMIN_SUBCOMMANDS = [
     'workspaces',
     'link', 'unlink', 'init',
     'products', 'apps', 'marketplace',
+    'features',
     'resources',
     'notifications',
     'events',
@@ -2560,7 +2565,7 @@ and env, then await ready() before accepting work:
     accessKey: process.env.DUCTAPE_ACCESS_KEY!,
     product: "payments",
     env: "prd",
-    runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000 },
+  runtime_sync: { interval_ms: 30_000, jitter: 0.2, max_backoff_ms: 300_000, warm_connections: true },
   });
   await ductape.ready();
 
@@ -2575,7 +2580,10 @@ Runtime synchronization is automatic when product + env are supplied:
     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.
+  - await ready() before accepting traffic. It now waits for the initial snapshot and database pool
+    warm-up, so first Feature/Database execution does not absorb MongoDB TLS/pool establishment.
+  - runtime_sync.warm_connections defaults to true; disable it only when lazy connections are intentional.
+  - Use runtimeSnapshotStatus() for revision/error/warm-up phase 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
@@ -3124,6 +3132,21 @@ CONNECTION FILE — REQUIRED SHAPE:
   auth and credentials absent when the environment does not require authentication. Never create a
   fake auth_tag merely to store a header.
 
+  OAUTH/TOKEN ACCESS: OAuth grants and shared tokens belong to the product App connection, not to
+  Feature input and not to repeated api.oauth() calls in application code. Inspect the App auth
+  scheme; when it uses oauth2, token_access, credential_access, or fetch_credential_access, direct
+  the user through the provider-consent/login flow in Workbench and preserve the resulting encrypted
+  connection auth for every mapped product environment. Agents must never request, print, or write
+  access/refresh tokens into the repository. Application code initializes Ductape with product+env,
+  awaits ready(), and calls the action; runtime auth injection and token refresh are platform-managed.
+  api.oauth() remains only an explicit process-local override for a connection the user deliberately
+  has not persisted.
+
+  SHARED CONFIG: derive candidate keys from the selected App version's action schemas across headers,
+  query, params, and body. Deduplicate by <location>:<key>, prefer fields reused by several actions,
+  and present the exact candidates to the user. Never ask the user to invent or type a key name that
+  is already declared by an action. Only the value/$Secret reference is user-supplied.
+
   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
@@ -3205,6 +3228,22 @@ Action input — flat input format:
     input: { "headers:X-Idempotency-Key": "..." } → request header
   Always use ductape_generate_payload or actions.fetch to know the exact field names — never guess.
 
+UNIVERSAL HTTP 400 / MISSING-INPUT SELF-HEALING:
+  This applies equally to actions.run, a Feature API step, a Quota option, and every Fallback provider.
+  The outer component does not hide or replace the referenced App Action contract.
+  1. Do not retry an unchanged payload and never invent the missing value.
+  2. Read the deepest provider error and identify app, action, field, and body/query/params/headers location.
+  3. MUST call ductape_schema({ product_tag, env_slug, app_tag, action_tag }) for each failing action.
+     For Feature/Quota/Fallback, fetch the outer component too, follow its step/option mapping, and
+     schema-check the referenced action that actually returned 400.
+  4. Compare every location separately. Restore schema defaults and required constant query values.
+     Use explicit input keys such as "query:type" when location is ambiguous.
+  5. If the action definition lost the required/default metadata, repair the canonical
+     ductape/actions/<app-tag>/<action-tag>.action.json and update the App Action via ductape_cli.
+     Do not hardcode a provider-specific workaround into one Feature, Quota, or Fallback.
+  6. Call ductape_generate_payload, validate it against the looked-up contract, and retry once.
+     If it still returns 400, stop and report the remaining provider/schema mismatch.
+
 Run an action at runtime:
   → CALL ductape_generate_payload FIRST (operation_family="action", method="run", targets={app, action})
   ductape_execute("actions.run", [{ product, env, app, action, input: { "body:field": value } }])
@@ -3314,7 +3353,9 @@ Product structure (IProduct fields):
 
 Bootstrap (single API call returning product context + component config + private key):
   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
+  runtime snapshot and warms its database connection pools before the process is marked ready. Do
+  not start the HTTP server or worker consumer before ready() resolves. The environment-scoped
+  snapshot 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" }).
@@ -4654,7 +4695,7 @@ Import (register an EXISTING cloud resource):
       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 },
+      runtime_sync: { interval_ms: 30_000, jitter: 0.2, warm_connections: true },
     });
     await ductape.ready();
     await ductape.events.produce({
@@ -6310,7 +6351,15 @@ async function main() {
                     'Enable it in Workbench → Tokens → Publishable Key. ' +
                     'If write access cannot be granted to the publishable key, perform this operation server-side using a full Ductape SDK instance initialized with an access key.';
             }
-            return { content: [{ type: 'text', text: `Error: ${message}` }], isError: true };
+            const recovery = runtimeInputRecovery(message, {
+                module: args.module,
+                method: args.method,
+                params: args.params,
+            });
+            const text = recovery
+                ? JSON.stringify({ error: message, recovery }, null, 2)
+                : `Error: ${message}`;
+            return { content: [{ type: 'text', text }], isError: true };
         }
     };
     const payloadGenerateHandler = async (args) => {

package/dist/runtime-recovery.d.ts

@@ -0,0 +1,9 @@
+type RuntimeContext = {
+    module: string;
+    method: string;
+    params: unknown[];
+};
+export declare function isRepairableClientInputError(message: string): boolean;
+export declare function runtimeInputRecovery(message: string, context: RuntimeContext): Record<string, unknown> | null;
+export {};
+//# sourceMappingURL=runtime-recovery.d.ts.map

package/dist/runtime-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-recovery.d.ts","sourceRoot":"","sources":["../src/runtime-recovery.ts"],"names":[],"mappings":"AAAA,KAAK,cAAc,GAAG;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,OAAO,EAAE,CAAC;CACnB,CAAC;AAeF,wBAAgB,4BAA4B,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAErE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAkC7G"}

package/dist/runtime-recovery.js

@@ -0,0 +1,53 @@
+function visit(value, found) {
+    if (!value || typeof value !== 'object')
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((item) => visit(item, found));
+        return;
+    }
+    const record = value;
+    const app = String(record.app ?? record.provider ?? '').trim();
+    const action = String(record.action ?? record.event ?? '').trim();
+    if (app && action)
+        found.set(`${app}:${action}`, { app, action });
+    Object.values(record).forEach((item) => visit(item, found));
+}
+export function isRepairableClientInputError(message) {
+    return /(?:status(?: code)?\s*400|http\s*400|err_bad_request|bad request|\bis required\b|required field|missing (?:input|field|parameter|value)|invalid (?:input|payload|parameter|payment type)|validation (?:error|failed))/i.test(message);
+}
+export function runtimeInputRecovery(message, context) {
+    if (!isRepairableClientInputError(message))
+        return null;
+    const actions = new Map();
+    visit(context.params, actions);
+    const appMatches = [...message.matchAll(/(?:app|provider)["'\s:=]+([\w:.-]+)/gi)].map((match) => match[1]);
+    const actionMatches = [...message.matchAll(/(?:action|event)["'\s:=]+([\w.-]+)/gi)].map((match) => match[1]);
+    for (const app of appMatches)
+        for (const action of actionMatches)
+            actions.set(`${app}:${action}`, { app, action });
+    return {
+        classification: 'repairable_client_input_error',
+        failed_operation: `${context.module}.${context.method}`,
+        implicated_actions: [...actions.values()],
+        rules: [
+            'Do not retry the unchanged payload and do not guess a missing value.',
+            'Treat the deepest provider/API 400 envelope as authoritative, even when wrapped by a Feature, Quota, or Fallback error.',
+            'Redact credentials and never move authentication values into ordinary Feature or runtime input.',
+        ],
+        repair_steps: [
+            'Read the complete nested error envelope and identify the failing provider, action, HTTP status, field, and input location.',
+            'Call ductape_schema for the exact implicated app action using product_tag, env_slug, app_tag, and action_tag. This lookup is mandatory before changing input.',
+            'For Feature, Quota, or Fallback execution, also fetch that component definition and follow its selected option/step to every referenced app action. Schema-check each failing action, not only the outer component.',
+            'Compare supplied input against body, query, params, and headers separately. Restore schema-declared defaults and required constant query values; preserve explicit location prefixes when a name is ambiguous.',
+            'If the live action contract itself omitted a required/default value, update its canonical ductape/actions/<app-tag>/<action-tag>.action.json and update the action through ductape_cli. Do not patch only generated Feature code.',
+            'Call ductape_generate_payload for the repaired operation, validate the generated payload against the looked-up schema, then retry once.',
+            'If the corrected call still returns 400, stop automatic retries and report the provider response plus the schema/payload mismatch that remains.',
+        ],
+        scope_notes: {
+            actions: 'Repair the direct app-action input.',
+            features: 'Repair the failing Feature step mapping or referenced action contract; do not special-case one Feature tag.',
+            fallback: 'Repair the input mapping/action contract for the failing provider option while retaining bounded failover.',
+            quotas: 'Repair the selected Quota option/action mapping; a Quota wrapper does not make a provider 400 retryable.',
+        },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.36",
+  "version": "0.3.0",
   "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 && node scripts/check-runtime-sync-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 && node scripts/check-runtime-input-recovery.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },