@ductape/mcp 0.2.21 → 0.2.22

package/dist/index.js

@@ -203,7 +203,9 @@ There are THREE categories of operations. Use the right tool for each:
        App actions and auths are configured in the Workbench UI. Quotas, fallbacks, jobs, and
        healthchecks are administrative resources managed with ductape_cli("resources <type> ...").
        Features have no CLI create command because their definitions are code-first through
-       features.define.
+       features.define. They DO have a CLI persistence command — ductape_cli("features sync") —
+       which runs the project's own "features:sync" npm script to register ductape/features/
+       definitions against the live product; see the DEPLOYING features.define CALLS section below.
 
        ⚠ MULTI-ENV REQUIREMENT — applies to ALL product assets (storage, database, cache,
        messageBroker, graph, vector, and any other resource with an envs array):
@@ -1679,6 +1681,15 @@ PRIMITIVES-FIRST CAPABILITY EXTRACTION — REQUIRED FOR EVERY MIGRATION SLICE
     5. For each Function, record pure/WASM-candidate versus framework-dependent classification.
     6. Call ductape_function_setup and implement verified local plus remote availability.
 
+  Persist migrated Features the same way as newly designed ones: define every Feature under
+  ductape/features/ (e.g. ductape/features/src/my-feature.ts), never inline in the app's normal
+  startup path. Register only local function/operation handlers (ductape.sdk.functions.register(...))
+  at boot — no network call. Persist Feature definitions to the live product with
+  "ductape features sync" (ductape_cli("features sync")), which runs the project's own
+  "features:sync" npm script — never automatically on app boot, the same way a migrated database
+  schema is applied via "ductape db migrate" rather than at startup. See "DEPLOYING features.define
+  CALLS" below for the full convention and required "features:sync" script shape.
+
   Never create a Function that merely hides database, session, Events, storage, notification, graph,
   vector, quota, fallback, healthcheck, cache, secret, or connected-App work that the Feature can
   express directly. Never fragment an original atomic transaction just to maximize primitive count.
@@ -1742,6 +1753,17 @@ ENVIRONMENTS
   Report matched, missing, extra, and ambiguous normalized aliases. Never guess an ambiguous mapping.
   Environment mutation is administrative CLI work and must never be routed through ductape_execute.
 
+  INACTIVE ENVIRONMENTS (e.g. an auto-created "snd"): whether an inactive environment needs a real
+  physical provider resource behind it, or can stay a placeholder with no live infrastructure, is
+  not settled platform behavior — do not assume either way. Resource-create payloads that require
+  complete environment coverage (see above) still need an entry for every environment returned by
+  "products environments list", active or not; whether that entry must point at a real backing
+  resource for an inactive env is a product-owner decision to surface explicitly, not infer.
+  Separately: "products environments update <product> <slug>" with {"active":false} may report
+  "updated": true without the change actually persisting — confirmed via independent read-back,
+  not just replication lag. If deactivating an environment is important, verify with a follow-up
+  "products environments get" rather than trusting the update response.
+
 PRODUCT AND ASSET BOOTSTRAP
   Product creation is idempotent: fetch by tag, create only when absent, then link the destination.
   Use ductape_cli for products, apps, resources, cloud connections, secrets, apply, and migrations.
@@ -1798,6 +1820,8 @@ COMPONENT DECISIONS
   Pinecone/Qdrant/Weaviate/OpenSearch → Vector; JWT/session middleware → Sessions.
   Named reusable product capabilities with a stable managed-execution boundary → code-first Features,
   including synchronous multi-step capabilities and durable/scheduled/signal-driven orchestration.
+  Define Features under ductape/features/ and persist them via "ductape features sync", never at
+  app boot — see PRIMITIVES-FIRST CAPABILITY EXTRACTION above.
   Retries, health checks, fallbacks, quotas, circuit breakers → Resilience.
   Keep low-level deterministic rules as ordinary domain functions when they do not form a useful
   independent capability boundary. Wrap or compose them into Features when the combined operation
@@ -1841,8 +1865,10 @@ AI EDITING STANDARD
   rules in code, while allowing a coherent synchronous capability composed from those rules to be a Feature.
   Immediate work propagates the full session; durable work uses approved actor metadata or system context.
   Consumers are idempotent, retry ownership is singular and bounded, and external effects are not duplicated.
-  After each slice: format, build, test, rescan, reconcile assets through ductape_cli, smoke-test in snd,
-  and report unresolved findings. A clean scanner result alone never proves a correct migration.
+  After each slice: format, build, test, rescan, persist any migrated Feature definitions via
+  ductape_cli("features sync") (never automatically on app boot), reconcile assets through
+  ductape_cli, smoke-test in snd, and report unresolved findings. A clean scanner result alone
+  never proves a correct migration.
 
 CONTEXTUAL FILE REVIEW PROTOCOL
   Use review_queue as a coverage aid. Review relevant files individually, starting with repository
@@ -2695,6 +2721,18 @@ CONNECT A DISCOVERED APP THROUGH MCP:
   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.
+
 ONLY after all five steps can any code call:
   ctx.api.run({ app: '<app_tag>', action: '<action_tag>', input: { ... } })   ← in a feature handler
   actions.run([{ product, env, app: '<app_tag>', action: '<action_tag>', input }])   ← at runtime
@@ -3079,6 +3117,23 @@ TAG AND SMTP RULES
   emails.smtp.secure is a boolean and cannot be a $Secret{...} string.
   Credential strings such as auth.user and auth.pass may use $Secret{...}.
 
+  notifications messages create/update/get had NO --product override before CLI 0.3.17 — it
+  silently resolved the product from whatever is linked in the current working directory, with
+  no way to override. Confirmed root cause of a real multi-hour misdiagnosis: it kept resolving
+  to a different product than intended, and the resulting "Notification X not found" error never
+  named which product it actually checked. If seeing this on an older CLI, verify which project
+  is linked in cwd before assuming the notification component itself is missing.
+
+  SendGrid field names (confirmed against the live Joi validator, not just this doc — cross-check
+  the SDK source when in doubt): { provider: "sendgrid", sendgrid: { apiKey: "$Secret{...}",
+  sender_email: "$Secret{...}" } }. The field is sender_email, not sender — "sender" is silently
+  rejected with a required-field error naming sender_email specifically, not a helpful diff.
+
+  Nexmo/Vonage SMS field names: { provider: "nexmo", apiKey: "$Secret{...}",
+  apiSecret: "$Secret{...}", sender: "YourSenderId" }. The credential fields are apiKey/apiSecret
+  — NOT accountSid (that is a Twilio-only field name and is rejected with "not allowed" if used
+  for nexmo).
+
 Send at runtime (one channel at a time):
   → CALL ductape_generate_payload FIRST (operation_family="notification", method="email.send")
   notifications.email.send    [{ product, env, notification, input: { recipients, subject?, template? } }]
@@ -3130,6 +3185,16 @@ FIREBASE THROUGH A GCP CLOUD CONNECTION
   intent; creating a notification does not prove Google-side FCM permission. Runtime delivery
   requires fcm.googleapis.com and roles/firebasecloudmessaging.admin, so validate the connection
   and perform a delivery test.
+
+  CONFIRMED CONTRADICTION (2026-08-17): despite the "never put the private key in the file"
+  guidance above, resources notifications create with authMode: "cloud_connection" currently
+  rejects the payload progressively demanding envs[].push_notifications.credentials.project_id,
+  then .private_key_id, then .client_email, then finally the raw .private_key itself — the full
+  manual service-account shape, defeating the documented purpose of cloud_connection mode. Do NOT
+  fabricate a placeholder private_key to satisfy this — that field is genuinely sensitive and a
+  fake value risks being mistaken for real credential material later. If you hit this, drop the
+  push_notifications block and register email/SMS only until this is fixed, and tell the user
+  explicitly rather than working around it with fake data.
 Notification tag and message tag are ALWAYS passed together as "notification_tag:message_tag".
 `.trim(),
     resilience: `
@@ -3660,6 +3725,55 @@ STEP 6 — WRITE the feature into the project codebase
   - Write rollback handlers inline as the third argument to ctx.step()
   - Return a plain object as the feature's output
 
+━━━ DEPLOYING features.define CALLS — DO NOT run them on every app boot ━━━
+
+  features.define() has a network-bound RECORDING PHASE (see FEATURE RECORDING SEMANTICS below) that
+  calls the live Ductape API to compile and register the Feature's step graph. This is administrative
+  configuration work, not a request-serving concern — treat it exactly like a database migration:
+  defined in source, but APPLIED via an explicit, separate command, never automatically on every
+  process start.
+
+  Calling features.define() from inside a framework's normal startup lifecycle hook (NestJS
+  onModuleInit, Express app bootstrap, a Lambda cold-start path, etc.) makes ordinary app startup
+  depend on Ductape API reachability and latency for every single boot/restart/replica — including
+  local dev restarts, autoscaling events, and health-check-triggered restarts. A slow or unreachable
+  Ductape API then blocks the app from ever starting to serve requests, even for routes that have
+  nothing to do with the affected Feature.
+
+  REQUIRED CONVENTION — this is what "ductape features sync" (CLI) expects:
+    1. Put every Feature definition under ductape/features/ (e.g. ductape/features/src/my-feature.ts),
+       each calling ductape.feature.define({ ... }) from a registerXFeature(ductape) export. This
+       mirrors ductape/database/migrations/ — a fixed, discoverable location for Ductape-managed
+       source, regardless of the surrounding project structure.
+    2. In the app's normal startup path, register ONLY local function/operation handlers
+       (ductape.sdk.functions.register(...)) — no network call, safe on every boot. Never call
+       features.define(...) here.
+    3. Add a "features:sync" script to package.json. It owns booting just enough of the app to
+       construct real dependencies (in NestJS, use NestFactory.createApplicationContext(module) —
+       same DI container, no HTTP listener) and calling every registerXFeature(...) once, then
+       exiting. Ductape cannot run this step for you generically — a Feature handler is real
+       application code that typically depends on the app's own services, unlike a migration file,
+       which is declarative data the Ductape backend can apply directly.
+    4. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
+       finds the linked project and runs its "features:sync" script — never automatically on boot.
+       Pass an optional filter argument to scope it: "ductape features sync payments".
+
+  A NestJS service with both concerns split looks like:
+    async onModuleInit() {
+      this.ductape.sdk.functions.register({ ...myFunctions, operations: { ... /* local handlers */ } });
+    }
+    async syncFeatures(): Promise<void> {
+      await registerMyFeature(this.ductape.sdk);   // the features.define(...) call
+    }
+  The project's own "features:sync" script resolves each service with a syncFeatures() method via a
+  headless application context and calls it — mirroring how a migration runner applies pending
+  migrations explicitly. "ductape features sync" is a thin, framework-agnostic front door onto that
+  script; it does not itself execute application code.
+
+  This applies to any framework, not just NestJS — the only requirement is that whatever construct
+  the app boots FOR REQUESTS never itself calls features.define(); the project's own "features:sync"
+  script does, invoked only through the explicit CLI command.
+
 STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
   Branch on step result (early return in handler):
     → Add branchOverrides: { stepTag: { field: value } } so all branches are recorded
@@ -5096,9 +5210,11 @@ const cliInputSchema = z.object({
         'Note: environments have their own CLI commands (products environments list/get/create/update, ' +
         'no linked project required — the product tag is always an explicit argument). Quotas, ' +
         'fallbacks, jobs, and healthchecks use resources commands. App actions and auths are ' +
-        'configured in the Workbench UI. Features have no CLI ' +
-        'creation command: define them in application code with features.define so application ' +
-        'boot/runtime registration makes them available.\n\n' +
+        'configured in the Workbench UI. Features have no CLI creation command: define them in ' +
+        'application code with features.define under ductape/features/. Persist them with ' +
+        '"features sync" (runs the project\'s own "features:sync" npm script) — never call ' +
+        'features.define from the app\'s normal startup path, since that blocks every boot on ' +
+        'Ductape API reachability. See ductape_docs for the full convention.\n\n' +
         'The CLI uses the user\'s local logged-in session (ductape login) — no key is required.'),
 });
 async function loadMcpSdk() {
@@ -5374,6 +5490,26 @@ async function main() {
                     return p;
                 });
             }
+            // Most non-setup publishable-key runtime calls require params[0] to carry a "session" field
+            // (confirmed 2026-08-18 against live backend logs: the proxy's own error is "When using
+            // publishable key, params must include a session (session token from backend)." — the HTTP
+            // response to the client only ever says the much vaguer "Authentication failed", so this
+            // failure mode is otherwise very hard to diagnose from the client side alone). Fail fast
+            // locally with a specific message instead of making a doomed network call.
+            const sessionRequiredModules = new Set([
+                'actions', 'features', 'databases', 'graph', 'vector', 'storage',
+                'notifications', 'messageBrokers', 'events', 'quotas', 'fallback', 'health',
+            ]);
+            const sessionExemptMethods = new Set(['consume', 'status', 'check', 'fetch', 'list']);
+            const requiresSession = sessionRequiredModules.has(proxyModule) && !sessionExemptMethods.has(args.method.toLowerCase());
+            const paramsHaveSession = params.some((p) => p && typeof p === 'object' && !Array.isArray(p) && 'session' in p);
+            if (requiresSession && !paramsHaveSession) {
+                throw new Error(`"${args.module}.${args.method}" is a runtime operation and requires a "session" field in ` +
+                    'params[0] — none was provided. ductape_execute cannot supply a session on your behalf. ' +
+                    'Call ductape_generate_payload for this operation to see the exact param shape, obtain a ' +
+                    'real session token (e.g. via sessions.start against this product/env — not a placeholder ' +
+                    'string), and include it as params[0].session before retrying.');
+            }
             let result;
             try {
                 result = await executeViaProxy(key, proxyModule, args.method, params);
@@ -5381,8 +5517,17 @@ async function main() {
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
                 if (/authentication failed|unauthorized|invalid.*key/i.test(message)) {
-                    throw new Error('The DUCTAPE_PUBLISHABLE_KEY was rejected by the runtime proxy. ' +
-                        'Use a publishable key for the same workspace/product. The MCP server never accepts or forwards access keys.');
+                    const sessionHint = !paramsHaveSession
+                        ? ' No "session" field was present in params — most non-setup publishable-key runtime ' +
+                            'calls require one (a real token from sessions.start, not a placeholder). This is the ' +
+                            'most common cause of an opaque "Authentication failed" response; call ' +
+                            'ductape_generate_payload first to see whether this operation expects a session field, ' +
+                            'then obtain a real session token before retrying.'
+                        : ' A "session" field was present, so a missing session is likely not the cause here — ' +
+                            'check that the publishable key itself belongs to the same workspace/product, and that ' +
+                            'any module/action restrictions on the key (Workbench → Tokens → Publishable Key) ' +
+                            'permit this operation.';
+                    throw new Error(`Runtime authentication was rejected (backend said: "${message}").` + sessionHint);
                 }
                 throw error;
             }
@@ -5559,7 +5704,15 @@ async function main() {
                 'Two-step rule for runtime operations:\n' +
                 '  1. Call ductape_generate_payload first to get the canonical payload template.\n' +
                 '     This reveals the exact "input" field keys — they are product/env/operation-specific.\n' +
-                '  2. Fill in the values from the template, then call ductape_execute.',
+                '  2. Fill in the values from the template, then call ductape_execute.\n\n' +
+                'Session requirement: most non-setup operations on actions, features, databases, graph, ' +
+                'vector, storage, notifications, message brokers/events, quotas, fallback, and health ' +
+                'require a real session token in params[0].session (from sessions.start against the same ' +
+                'product/env — never a placeholder string). This tool checks for that locally and fails ' +
+                'fast with a specific error before calling the backend if it is missing for an operation ' +
+                'that needs one. The backend itself only reports a generic "Authentication failed" for ' +
+                'this case, so a missing session and a genuinely bad key look identical unless you read ' +
+                'this local check first.',
             inputSchema: executeInputSchema,
         }, executeHandler);
         server.registerTool('ductape_generate_payload', {

package/package.json

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