@ductape/mcp 0.1.34 → 0.1.36

package/dist/index.js

@@ -722,7 +722,7 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     handler: async (ctx) => {
       // ctx.input                – typed feature input
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
-      // ctx.action.run({ app, event, input }) – call an app action
+      // ctx.api.run({ app, event, input }) – call an app action
       // ctx.database.query/insert/update/delete({ database, event, ... })
       // ctx.graph.execute({ graph, action, input })
       // ctx.notification.send/email/push/sms({ notification, event, ... })
@@ -2069,34 +2069,109 @@ A feature is an orchestrated workflow of durable steps. Steps can call app actio
 operations, graph queries, storage uploads, notifications, broker publishes, child features,
 quotas, fallbacks, and more. Features support rollback, signals, checkpoints, and sleep.
 
+━━━ AI DESIGN WORKFLOW — follow this process every time a user asks you to build or plan a feature ━━━
+
+ALWAYS use features.define (code-first). NEVER use features.create.
+The feature handler is real code written into the project's source files — find the project's
+language and framework, write the feature into an appropriate file in the codebase, and call
+features.define from there. Do not generate inline snippets and stop — write the actual file.
+
+STEP 1 — UNDERSTAND the goal
+  Ask clarifying questions if the user's intent is unclear. Do not start designing until you
+  understand: what the feature does, what it returns, what can fail and how failures should behave.
+
+STEP 2 — INVENTORY existing Ductape components
+  Call ductape_execute("products.fetch", [product_tag]) to read the product.
+  Note what already exists:
+    - databases[]      → available for ctx.database.insert/query/update/delete steps
+    - apps[]           → available for ctx.api.run steps (check app.events[] for event tags)
+    - notifications[]  → available for ctx.notification.email/sms/push steps
+    - storage[]        → available for ctx.storage.upload/download steps
+    - messageBrokers[] → available for ctx.messaging.produce steps
+    - graphs[]         → available for ctx.graph steps
+    - features[]       → can be called as child features via ctx.feature()
+    - caches[], sessions[]
+  Do NOT assume a component or event tag exists — verify from the product before using it.
+
+STEP 3 — PLAN each step
+  For every logical step:
+    a. Identify which existing component handles it, or flag it as needing creation
+    b. Note how inputs flow: ctx.input fields, or return values from earlier steps (plain JS variables — no special notation needed)
+    c. Decide if a rollback handler is needed (e.g. charge → refund on later failure)
+    d. Decide allow_fail: true for non-critical steps (email, analytics, audit logs)
+
+STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating anything
+  Show the user:
+    Feature: <name> (<tag>)
+    Input fields: list them with types
+    Steps (in order):
+      1. <step-tag> — <what it does> — <component> [rollback: yes/no] [allow_fail: yes/no]
+      2. ...
+    Return value: describe what the handler returns
+    Components to create: list anything missing with a short description
+  Ask: "Should I proceed? Shall I create the missing components first?"
+  Wait for confirmation before writing code or calling any create tool.
+
+STEP 5 — CREATE missing components (only with user approval)
+  Use ductape_execute for any missing databases, apps, database actions, notification events, etc.
+  For a missing database action:
+    ductape_execute("databases.action.create", [product_tag, db_tag, { tag, name, type, query }])
+  For a missing child feature, recursively apply this same workflow.
+  Tell the user what you are about to create before each tool call.
+
+STEP 6 — WRITE the feature into the project codebase
+  - Locate or create an appropriate file in the project (e.g. src/features/feature-name.ts, features/feature_name.py)
+  - Use features.define with an async handler
+  - Step results are plain variables — just await ctx.step(...) and use the return value in the next step
+  - No special notation needed: const user = await ctx.step('create-user', async () => { ... }); then use user.id directly in the next step
+  - Write rollback handlers inline as the third argument to ctx.step()
+  - Return a plain object as the feature's output
+
+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
+    → At runtime the executor evaluates the real result and skips or runs later steps accordingly
+  Loop over input array:
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } so the loop runs during recording
+    → Use unique step tags per iteration (e.g. "process-" + item.id)
+  Switch/if-else on feature input values:
+    → Add recordScenarios: [{ type: "a" }, { type: "b" }] — handler runs once per scenario
+    → Only the scenario whose input matches runs at execution time
+
+STEP 8 — SET rollbacks for reversible steps
+  Any step that allocates a resource should undo it if a later step fails:
+    const charge = await ctx.step(
+      'charge',
+      async () => ctx.api.run({ app: 'stripe', event: 'create-charge', input: { amount: ctx.input.amount } }),
+      async (result) => ctx.api.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
+    );
+
 Step types: action | database | graph | notification | storage | produce | quota | fallback |
   vector | child_feature | sleep | wait_for_signal | checkpoint
 
-Create a feature (admin — ductape_execute):
-  ductape_execute("features.create", [product_tag, {
+Define a feature (write this into the project's source files — do NOT use features.create):
+  // src/features/onboard-user.ts  (or the equivalent path/language for the project)
+  await ductape.features.define({
     tag: "onboard-user",
     name: "Onboard User",
-    input: { userId: { type: "string", required: true }, email: { type: "string" } },
-    steps: [
-      {
-        tag: "create-account",
-        type: "database",
-        database: "core-db",
-        event: "insert-user",
-        input: { "body:userId": "$Input{userId}", "body:email": "$Input{email}" },
-        options: { retries: 2, timeout: 5000 },
-      },
-      {
-        tag: "send-welcome",
-        type: "notification",
-        notification: "welcome-email",
-        event: "welcome-email:default",
-        input: { "body:email": "$Input{email}" },
-        dependsOn: ["create-account"],
-        options: { allow_fail: true },   // welcome email failure won't abort the feature
-      },
-    ],
-  }])
+    handler: async (ctx) => {
+      const account = await ctx.step("create-account", async () =>
+        ctx.database.insert({ database: "core-db", event: "insert-user",
+          data: { userId: ctx.input.userId, email: ctx.input.email } }),
+        async (result) => ctx.database.delete({ database: "core-db", event: "delete-user",
+          where: { id: result.id } })   // rollback
+      );
+
+      await ctx.step("send-welcome", async () =>
+        ctx.notification.email({ notification: "welcome-email", event: "welcome",
+          recipients: [ctx.input.email], subject: {}, template: {} }),
+        null,
+        { allow_fail: true }
+      );
+
+      return { userId: account.id };
+    },
+  });
 
 Execute at runtime:
   → CALL ductape_generate_payload FIRST (operation_family="features", method="execute", targets={tag})
@@ -2122,21 +2197,8 @@ Signals and queries (for long-running features):
   features.signal [{ product, env, feature_id, signal: "payment-confirmed", payload? }]
   features.query  [{ product, env, feature_id, query: "current-status", params? }]
 
-Step input references:
-  $Input{field}               → map from feature's declared input
-  $Step{stepTag}{field}       → output field from a prior step
-  $StepOutput{field}          → current step's own return value
-  $Concat([...parts], delim)  → string interpolation
-
 Rollback strategies: reverse_all | reverse_critical | compensate | none
 Feature statuses: pending | running | completed | failed | rolled_back | rolling_back | paused
-
-Code-first (define API — compiles async handler to JSON step schema):
-  features.define({ tag, name, input, handler: async (ctx) => { ... } })
-  ctx provides: ctx.step(), ctx.action.run(), ctx.database.query/insert(),
-    ctx.graph.execute(), ctx.notification.send(), ctx.storage.upload(),
-    ctx.messaging.produce(), ctx.quota.execute(), ctx.fallback.execute(),
-    ctx.sleep(), ctx.waitForSignal(), ctx.setState/getState(), ctx.feature()
 `.trim(),
     events: `
 DUCTAPE EVENTS (MESSAGE BROKERS)

package/package.json

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

package/src/index.ts

@@ -2141,34 +2141,109 @@ A feature is an orchestrated workflow of durable steps. Steps can call app actio
 operations, graph queries, storage uploads, notifications, broker publishes, child features,
 quotas, fallbacks, and more. Features support rollback, signals, checkpoints, and sleep.
 
+━━━ AI DESIGN WORKFLOW — follow this process every time a user asks you to build or plan a feature ━━━
+
+ALWAYS use features.define (code-first). NEVER use features.create.
+The feature handler is real code written into the project's source files — find the project's
+language and framework, write the feature into an appropriate file in the codebase, and call
+features.define from there. Do not generate inline snippets and stop — write the actual file.
+
+STEP 1 — UNDERSTAND the goal
+  Ask clarifying questions if the user's intent is unclear. Do not start designing until you
+  understand: what the feature does, what it returns, what can fail and how failures should behave.
+
+STEP 2 — INVENTORY existing Ductape components
+  Call ductape_execute("products.fetch", [product_tag]) to read the product.
+  Note what already exists:
+    - databases[]      → available for ctx.database.insert/query/update/delete steps
+    - apps[]           → available for ctx.action.run steps (check app.events[] for event tags)
+    - notifications[]  → available for ctx.notification.email/sms/push steps
+    - storage[]        → available for ctx.storage.upload/download steps
+    - messageBrokers[] → available for ctx.messaging.produce steps
+    - graphs[]         → available for ctx.graph steps
+    - features[]       → can be called as child features via ctx.feature()
+    - caches[], sessions[]
+  Do NOT assume a component or event tag exists — verify from the product before using it.
+
+STEP 3 — PLAN each step
+  For every logical step:
+    a. Identify which existing component handles it, or flag it as needing creation
+    b. Note how inputs flow: ctx.input fields, or return values from earlier steps (plain JS variables — no special notation needed)
+    c. Decide if a rollback handler is needed (e.g. charge → refund on later failure)
+    d. Decide allow_fail: true for non-critical steps (email, analytics, audit logs)
+
+STEP 4 — PRESENT the plan and get approval BEFORE writing any code or creating anything
+  Show the user:
+    Feature: <name> (<tag>)
+    Input fields: list them with types
+    Steps (in order):
+      1. <step-tag> — <what it does> — <component> [rollback: yes/no] [allow_fail: yes/no]
+      2. ...
+    Return value: describe what the handler returns
+    Components to create: list anything missing with a short description
+  Ask: "Should I proceed? Shall I create the missing components first?"
+  Wait for confirmation before writing code or calling any create tool.
+
+STEP 5 — CREATE missing components (only with user approval)
+  Use ductape_execute for any missing databases, apps, database actions, notification events, etc.
+  For a missing database action:
+    ductape_execute("databases.action.create", [product_tag, db_tag, { tag, name, type, query }])
+  For a missing child feature, recursively apply this same workflow.
+  Tell the user what you are about to create before each tool call.
+
+STEP 6 — WRITE the feature into the project codebase
+  - Locate or create an appropriate file in the project (e.g. src/features/feature-name.ts, features/feature_name.py)
+  - Use features.define with an async handler
+  - Step results are plain variables — just await ctx.step(...) and use the return value in the next step
+  - No special notation needed: const user = await ctx.step('create-user', async () => { ... }); then use user.id directly in the next step
+  - Write rollback handlers inline as the third argument to ctx.step()
+  - Return a plain object as the feature's output
+
+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
+    → At runtime the executor evaluates the real result and skips or runs later steps accordingly
+  Loop over input array:
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } so the loop runs during recording
+    → Use unique step tags per iteration (e.g. "process-" + item.id)
+  Switch/if-else on feature input values:
+    → Add recordScenarios: [{ type: "a" }, { type: "b" }] — handler runs once per scenario
+    → Only the scenario whose input matches runs at execution time
+
+STEP 8 — SET rollbacks for reversible steps
+  Any step that allocates a resource should undo it if a later step fails:
+    const charge = await ctx.step(
+      'charge',
+      async () => ctx.action.run({ app: 'stripe', event: 'create-charge', input: { amount: ctx.input.amount } }),
+      async (result) => ctx.action.run({ app: 'stripe', event: 'refund', input: { chargeId: result.id } })
+    );
+
 Step types: action | database | graph | notification | storage | produce | quota | fallback |
   vector | child_feature | sleep | wait_for_signal | checkpoint
 
-Create a feature (admin — ductape_execute):
-  ductape_execute("features.create", [product_tag, {
+Define a feature (write this into the project's source files — do NOT use features.create):
+  // src/features/onboard-user.ts  (or the equivalent path/language for the project)
+  await ductape.features.define({
     tag: "onboard-user",
     name: "Onboard User",
-    input: { userId: { type: "string", required: true }, email: { type: "string" } },
-    steps: [
-      {
-        tag: "create-account",
-        type: "database",
-        database: "core-db",
-        event: "insert-user",
-        input: { "body:userId": "$Input{userId}", "body:email": "$Input{email}" },
-        options: { retries: 2, timeout: 5000 },
-      },
-      {
-        tag: "send-welcome",
-        type: "notification",
-        notification: "welcome-email",
-        event: "welcome-email:default",
-        input: { "body:email": "$Input{email}" },
-        dependsOn: ["create-account"],
-        options: { allow_fail: true },   // welcome email failure won't abort the feature
-      },
-    ],
-  }])
+    handler: async (ctx) => {
+      const account = await ctx.step("create-account", async () =>
+        ctx.database.insert({ database: "core-db", event: "insert-user",
+          data: { userId: ctx.input.userId, email: ctx.input.email } }),
+        async (result) => ctx.database.delete({ database: "core-db", event: "delete-user",
+          where: { id: result.id } })   // rollback
+      );
+
+      await ctx.step("send-welcome", async () =>
+        ctx.notification.email({ notification: "welcome-email", event: "welcome",
+          recipients: [ctx.input.email], subject: {}, template: {} }),
+        null,
+        { allow_fail: true }
+      );
+
+      return { userId: account.id };
+    },
+  });
 
 Execute at runtime:
   → CALL ductape_generate_payload FIRST (operation_family="features", method="execute", targets={tag})
@@ -2194,21 +2269,8 @@ Signals and queries (for long-running features):
   features.signal [{ product, env, feature_id, signal: "payment-confirmed", payload? }]
   features.query  [{ product, env, feature_id, query: "current-status", params? }]
 
-Step input references:
-  $Input{field}               → map from feature's declared input
-  $Step{stepTag}{field}       → output field from a prior step
-  $StepOutput{field}          → current step's own return value
-  $Concat([...parts], delim)  → string interpolation
-
 Rollback strategies: reverse_all | reverse_critical | compensate | none
 Feature statuses: pending | running | completed | failed | rolled_back | rolling_back | paused
-
-Code-first (define API — compiles async handler to JSON step schema):
-  features.define({ tag, name, input, handler: async (ctx) => { ... } })
-  ctx provides: ctx.step(), ctx.action.run(), ctx.database.query/insert(),
-    ctx.graph.execute(), ctx.notification.send(), ctx.storage.upload(),
-    ctx.messaging.produce(), ctx.quota.execute(), ctx.fallback.execute(),
-    ctx.sleep(), ctx.waitForSignal(), ctx.setState/getState(), ctx.feature()
 `.trim(),
 
   events: `