@ductape/mcp 0.2.31 → 0.2.32

package/dist/index.js

@@ -945,6 +945,9 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
       // ctx.input                – typed runtime input; always compiles to $Input{} operators
       // ctx.sampleInput          – compile-time sample for loop/branch discovery only
       // ctx.step(tag, fn, rollback?, opts?)  – define a durable step
+      // ctx.when.eq/ne/gt/gte/lt/lte/truthy/falsy(...) – build portable runtime conditions
+      // ctx.branch(condition, { then, else? }) – record both paths as conditioned steps
+      // ctx.each(ctx.sampleInput.items, async (item, index) => ...) – deterministic compile-time expansion
       // ctx.api.run({ app, action, input }) – call an app action (NOT 'event' -- that field name
       //   only applies to ctx.database/ctx.notification/ctx.storage below, never ctx.api/ctx.action)
       // ctx.database.execute({ database, action, input }) for a saved database action
@@ -3373,6 +3376,20 @@ CONFIGURATION BOUNDARY
   Workbench is also supported. Never route their administrative create/update methods through
   ductape_execute: its publishable-key runtime proxy will fail.
 
+CLI COMMANDS (aliases are normalized; use these exact shapes):
+  ductape resources feature list --product <product> --json
+  ductape resources feature get -t <feature> --product <product> --json
+  ductape resources quota list --product <product> --json
+  ductape resources quota get -t <quota> --product <product> --json
+  ductape resources fallback list --product <product> --json
+  ductape resources fallback get -t <fallback> --product <product> --json
+  ductape resources health list --product <product> --json
+  ductape resources health get -t <healthcheck> --product <product> --json
+  Create/update use the same resource type plus -f <asset.json>. Singular/plural feature(s),
+  fallback(s), and healthcheck(s) aliases are accepted, but canonical generated commands should
+  use feature, quota, fallback, and health. These commands are administrative catalogue CRUD;
+  runtime run/execute operations belong to the SDK or authenticated execution surface.
+
 QUOTAS — weighted/provider-capacity routing pools (NOT request rate limiting):
   Workbench definition shape:
   {
@@ -3929,15 +3946,83 @@ STEP 6 — WRITE the feature into the project codebase
   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
-    → At runtime the executor evaluates the real result and skips or runs later steps accordingly
+  MANDATORY CONTROL-FLOW RULES:
+    1. A stored Feature executes its compiled steps. The JavaScript handler is NOT rerun at runtime.
+    2. Never use if/else, switch, ?:, ??, &&, ||, optional chaining, map, filter, find, some,
+       every, reduce, for, for..of, forEach, or while on a ctx.step() result or ctx.input proxy.
+       JavaScript would evaluate the recording proxy, not the future runtime value.
+    3. Use ctx.branch(ctx.when.*, { then, else }) for runtime decisions.
+    4. Use ctx.each only with a concrete ctx.sampleInput array to expand a fixed step graph.
+    5. Put runtime-sized collection algorithms and arbitrary business logic in a registered
+       portable Function, then invoke it through ctx.functions inside a step.
+    6. Direct Date.now() and Math.random() are forbidden in handlers. Use ctx.transform.now(),
+       ctx.transform.uuid(), and ctx.transform.concat/replace/substring/upper/lower/trim so values
+       are generated at execution time. Use a portable Function for domain-specific generators.
+    7. Never use branchOverrides in newly generated code. It exists only to migrate old handlers.
+
+  Prefer explicit portable branching for step results:
+    const result = await ctx.step("find", () => ctx.database.execute(...));
+    await ctx.branch(ctx.when.eq(result.count, 0), {
+      then: () => ctx.step("create", () => ctx.database.execute(...)),
+      else: () => ctx.step("reuse", () => ctx.database.execute(...)),
+    });
+    → ctx.when also supports ne, gt, gte, lt, lte, truthy, falsy, and/or.
+    → Do not use ordinary if/else, ternary, or ?? directly on an unresolved step result.
+    → branchOverrides remains a compatibility escape hatch for older Feature source.
+    → If both paths must feed a later common step, do not assume ctx.branch returns a selected
+      value. Either record the downstream operation inside each path, persist a shared result that
+      the later step can read, or move the find-or-create algorithm into one portable Function.
   Loop over input array:
-    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and iterate ctx.sampleInput.items
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and call
+      ctx.each(ctx.sampleInput.items, async (item, index) => { ... })
     → Use unique step tags per iteration (e.g. "process-" + item.id)
+    → map/filter/find/indexing on ctx.sampleInput are compile-time graph discovery only.
+    → Runtime-sized map/filter/find/some/every and arbitrary loops belong in a registered portable
+      Function invoked through ctx.functions; never guess or freeze their results during recording.
   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
+    → Prefer ctx.branch(ctx.when.eq(ctx.input.type, "a"), { then, else }).
+    → recordScenarios is for legacy compile-time graph discovery, not a runtime branch primitive.
+
+  SAFE COPY-READY PATTERNS:
+    Runtime input branch:
+      await ctx.branch(ctx.when.eq(ctx.input.kind, "refund"), {
+        then: () => ctx.step("refund", () => ctx.api.run({ app, action: "refund", input: {...} })),
+        else: () => ctx.step("charge", () => ctx.api.run({ app, action: "charge", input: {...} })),
+      });
+    Nested/indexed result check:
+      await ctx.branch(ctx.when.eq(search.data.length, 0), { then: ..., else: ... });
+    Compound condition:
+      await ctx.branch(ctx.when.and(
+        ctx.when.eq(result.status, "ready"),
+        ctx.when.gt(result.count, 0),
+      ), { then: ..., else: ... });
+    Runtime payment/reference string (never frozen at sync time):
+      const reference = ctx.transform.concat(
+        "pay_", ctx.transform.now(), "_", ctx.transform.uuid(),
+      );
+      await ctx.step("charge", () => ctx.fallback.execute({
+        fallback: "charge-payment", input: { reference, ... },
+      }));
+    Fixed graph expansion:
+      recordInput: { regions: ["ng", "gh"] },
+      handler: async (ctx) => ctx.each(ctx.sampleInput.regions, async (region, index) => {
+        await ctx.step("sync-region-" + index, () => ctx.functions.invoke(syncFn, "run", { region }));
+      });
+
+  UNSAFE — NEVER GENERATE:
+    if (result.count === 0) await ctx.step(...);
+    const customer = found[0] ?? await ctx.step(...);
+    ctx.input.items.map(item => ctx.step(...));
+    for (const item of ctx.input.items) await ctx.step(...);
+    const reference = "pay_" + Date.now() + "_" + Math.random();
+
+  BEFORE SYNCING A FEATURE:
+    → Confirm every runtime decision uses ctx.branch + ctx.when.
+    → Confirm every ctx.step tag is unique across both paths and every expanded iteration.
+    → Confirm no runtime proxy is consumed by native JavaScript control flow or array iteration.
+    → Confirm every ctx.step contains a portable ctx component/function call.
+    → Compile locally, inspect schema.steps, and verify both branch paths, condition, depends_on,
+      and operator-valued inputs are present before persisting.
 
 STEP 8 — SET rollbacks for reversible steps
   Any step that allocates a resource should undo it if a later step fails.
@@ -4047,16 +4132,18 @@ Feature statuses: pending | running | completed | failed | rolled_back | rolling
 
 ━━━ FEATURE RECORDING SEMANTICS ━━━
 
-When you call features.define({ handler }), the handler runs TWICE:
+When you call features.define({ handler }), there are two distinct phases, but the handler itself
+runs only during compilation/recording:
 
   1. RECORDING PHASE (at define time) — handler is called with a RecordingContext.
      All ctx.step() calls return lightweight proxy objects, not real data.
      This phase captures the step graph: which steps exist, their types, tags, and declared
      inputs/outputs. No real API calls, DB queries, or side effects occur.
      Arbitrary JS code OUTSIDE ctx.step() ALSO runs during recording — with proxy values.
-     For loops: supply recordInput and iterate ctx.sampleInput so all iterations are recorded.
+     For loops: supply recordInput and use ctx.each(ctx.sampleInput.items, ...) so all iterations are recorded.
      ctx.input is always the runtime operator surface and must never expose recordInput literals.
-     For branches: use branchOverrides so each path is captured.
+     For branches: use ctx.branch(ctx.when.*, { then, else }) so both paths are captured. Use
+     branchOverrides only for compatibility with existing Feature handlers.
      Never make an authorization, validation, tenancy, or other security decision by branching on
      ctx.input during recording. Use ctx.sampleInput only to discover graph shape; enforce security
      invariants inside a runtime portable Function or recorded step.
@@ -4066,11 +4153,15 @@ When you call features.define({ handler }), the handler runs TWICE:
      integrations and project readiness hooks must not start HTTP listeners, provider probes,
      schedulers, or Event consumers. Apply the filter before booting unrelated service modules.
 
-  2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
-     ctx.step() actually executes. All real Ductape component calls happen.
-     Arbitrary JS logic (math, string ops, conditionals on step results) runs for real.
+  2. EXECUTION PHASE (at runtime) — the stored schema.steps graph is interpreted by FeatureExecutor.
+     The original JavaScript handler is NOT called. Step inputs and conditions resolve operators
+     such as $Input{}, $Sequence{}, $Step{}, and $Now against runtime state. Only recorded portable
+     component/function operations execute.
 
-  Implication: put all meaningful business logic INSIDE ctx.step() handlers, not in the
+  Implication: arbitrary JavaScript control flow never becomes runtime behavior merely because it
+  appears in the handler. Express runtime branches through ctx.branch/ctx.when, fixed graph expansion
+  through ctx.each(ctx.sampleInput...), and runtime-sized algorithms through ctx.functions. Put all
+  meaningful business logic INSIDE recorded portable operations, not in the
   outer handler body. Code in the outer body runs during recording with proxy values and
   may behave unexpectedly (e.g. typeof proxy === 'object' is true but .someField is a proxy).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.31",
+  "version": "0.2.32",
   "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-project-link-guidance.mjs && node scripts/check-graph-vector-projection-guidance.mjs && node scripts/check-asset-file-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",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },