@ductape/mcp 0.2.8 → 0.2.9

package/README.md

@@ -88,6 +88,7 @@ The server exposes runtime, schema, documentation, CLI, discovery, migration, an
    - Returns deterministic well-known routes, framework raw-body requirements, HMAC-SHA256 headers,
      runtime verification steps, and fail-closed conditions.
    - Agents must implement and verify the route; they must not claim remote availability from local registration alone.
+   - Agents must first extract native Ductape primitives from migrated code and reserve Functions for irreducible residual domain logic while preserving original transaction boundaries.
 
 The `ductape_cli` MCP tool also exposes public app discovery:
 `marketplace search <capability>`, `marketplace categories`, and

package/dist/index.js

@@ -10,7 +10,7 @@
  * the env var when provided.
  */
 import { createRequire } from 'module';
-import { execSync } from 'child_process';
+import { execFileSync, execSync } from 'child_process';
 import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
@@ -21,6 +21,60 @@ const MODULES = [
     'events', 'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
     'actions', 'features', 'jobs', 'logs', 'resilience', 'health', 'fallback', 'secrets',
 ];
+const redisSetupInputSchema = z.object({
+    approved: z.boolean().describe('Must be true only after the user explicitly approves creating/starting a local Docker Redis container.'),
+    port: z.number().int().min(1024).max(65535).default(6379),
+    container_name: z.string().regex(/^[A-Za-z0-9][A-Za-z0-9_.-]{0,62}$/).default('ductape-redis'),
+});
+const redisSetupHandler = async (args) => {
+    const port = args.port ?? 6379;
+    const name = args.container_name ?? 'ductape-redis';
+    if (!args.approved) {
+        return {
+            content: [{ type: 'text', text: [
+                        'Redis materially reduces repeated Ductape bootstrap latency and is required for dispatch().',
+                        'Ask the user whether they approve pulling redis:7-alpine and creating a local Docker container bound to 127.0.0.1.',
+                        'Only call this tool again with approved=true after explicit approval.',
+                    ].join('\n') }],
+            isError: true,
+        };
+    }
+    try {
+        execFileSync('docker', ['version', '--format', '{{.Server.Version}}'], { encoding: 'utf8', timeout: 15_000 });
+    }
+    catch {
+        return { content: [{ type: 'text', text: 'Docker is not installed or its daemon is unavailable. Install/start Docker, or supply a managed DUCTAPE_REDIS_URL.' }], isError: true };
+    }
+    let exists = false;
+    let running = false;
+    try {
+        exists = true;
+        running = execFileSync('docker', ['inspect', '-f', '{{.State.Running}}', name], { encoding: 'utf8', timeout: 10_000 }).trim() === 'true';
+    }
+    catch {
+        exists = false;
+    }
+    if (exists && !running)
+        execFileSync('docker', ['start', name], { encoding: 'utf8', timeout: 30_000 });
+    if (!exists) {
+        execFileSync('docker', [
+            'run', '-d', '--name', name, '--restart', 'unless-stopped',
+            '-p', `127.0.0.1:${port}:6379`, 'redis:7-alpine',
+            'redis-server', '--appendonly', 'yes',
+        ], { encoding: 'utf8', timeout: 120_000 });
+    }
+    execFileSync('docker', ['exec', name, 'redis-cli', 'ping'], { encoding: 'utf8', timeout: 10_000 });
+    return { content: [{ type: 'text', text: JSON.stringify({
+                    ready: true,
+                    container: name,
+                    redis_url: `redis://127.0.0.1:${port}`,
+                    next_steps: [
+                        `Set DUCTAPE_REDIS_URL=redis://127.0.0.1:${port}`,
+                        'Pass redisUrl to @ductape/nestjs or redis_url/redis_client to the installed SDK API as supported by its types.',
+                        'Add the variable to local .env only; do not commit credentials for managed Redis.',
+                    ],
+                }, null, 2) }] };
+};
 // ─── Exhaustive SDK Method & Params Reference ────────────────────────────────
 // Built from a complete read of sdk/ts/src/index.ts (Ductape class public API).
 // Each entry follows: [module].[method] → params array signature.
@@ -213,6 +267,10 @@ SETUP — register once in AppModule:
   ║                                                                          ║
   ║  *.run(), events.produce(), and @Events.Consumer do NOT need Redis.     ║
   ║  Only dispatch() does — and it is non-negotiable.                       ║
+  ║                                                                          ║
+  ║  Redis is STRONGLY RECOMMENDED even without dispatch(): every bootstrap ║
+  ║  domain uses memory + optional Redis caching, so shared/multi-process    ║
+  ║  deployments avoid repeating control-plane reads after warm-up.         ║
   ╚══════════════════════════════════════════════════════════════════════════╝
 
   import { DuctapeModule } from '@ductape/nestjs';
@@ -245,6 +303,10 @@ SETUP — register once in AppModule:
     DUCTAPE_REDIS_URL=redis://localhost:6379          # local dev
     DUCTAPE_REDIS_URL=rediss://:<password>@host:6380  # managed Redis (TLS)
 
+  If no Redis URL exists, proactively explain the latency/dispatch benefits and ask whether the
+  user wants a local Docker Redis dedicated to Ductape. After explicit approval, call
+  ductape_redis_setup({ approved: true }). Never pull an image or create/start a container before approval.
+
 INJECTING IN SERVICES AND CONTROLLERS — use @InjectContext():
 
   import { InjectContext, DuctapeContext } from '@ductape/nestjs';
@@ -773,11 +835,12 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
     queries?: { queryName: { handler?: function } },
     options?: { timeout?: number, retries?: number },
     envs?: [{ slug: string, active?: boolean }],
-    recordInput?: object,         // sample input for step-recording (run once during define)
+    recordInput?: object,         // exposed only as ctx.sampleInput while recording
     recordScenarios?: object[],   // multiple recording scenarios for branching
     branchOverrides?: object,     // force step results during recording to reach later branches
     handler: async (ctx) => {
-      // ctx.input                – typed feature input
+      // 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.api.run({ app, event, input }) – call an app action
       // ctx.database.query/insert/update/delete({ database, event, ... })
@@ -1115,6 +1178,7 @@ 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!,
+  redis_url: process.env.DUCTAPE_REDIS_URL,
 });
 
 async function run() {
@@ -1384,6 +1448,37 @@ PORTABLE APPLICATION FUNCTIONS
 Use portable functions when a Feature needs application-owned logic that cannot be expressed with
 database, action, Event, storage, graph, vector, session, quota, fallback, or transform primitives.
 
+PRIMITIVES-FIRST DECOMPOSITION — REQUIRED
+Before creating a Function, inspect the implementation, its callees, side effects, transaction
+boundary, configuration, and tests. Extract every operation already represented by a Ductape
+primitive. A Function is the residual application-owned behavior after that extraction; it is not
+a wrapper around an entire existing service method merely because that method already exists.
+
+Classify each observed behavior:
+  database read/write/transaction/index   → database primitive or database action
+  external provider/API                   → connected App action
+  publish/consume asynchronous message    → Events primitive
+  session creation/validation/revocation  → session primitive
+  file/blob operation                     → storage primitive
+  graph/vector operation                  → graph/vector primitive
+  email/SMS/push/chat delivery             → notification primitive
+  quota/fallback/health/cache              → corresponding Ductape primitive
+  multi-step product capability            → Feature orchestration
+  reusable domain decision/transformation  → portable Function candidate
+  formatting/hash/redaction with one caller→ ordinary utility unless portability is required
+
+For a mixed legacy method, split the boundary. Keep its irreducible domain decision in a Function
+and orchestrate extracted primitives as named Feature steps. Preserve atomicity: do not split a
+database transaction into independently committed steps unless the original contract permits it;
+use a database action or a Function with an explicitly authorized transactional capability instead.
+
+Every proposed Function must include evidence for:
+  - why no existing Ductape primitive expresses it;
+  - exact business input/output, errors, side effects, idempotency, and transaction semantics;
+  - whether it is pure and therefore a future signed-WASM candidate;
+  - why it needs local, Events, or HTTPS availability;
+  - which extracted primitives remain separate Feature steps.
+
 Non-negotiable rule: arbitrary JavaScript/TypeScript callbacks are not serializable. Never write
 ctx.step('x', () => applicationService.method()) and assume the method will run elsewhere. The
 Feature compiler must reject a step that records no portable operation.
@@ -1471,6 +1566,39 @@ START
   5. Call again with write=true only after confirming the destination. This writes guidance artifacts only.
   6. Call with ensure_product=true when product inventory confirms the product is absent.
 
+PRIMITIVES-FIRST CAPABILITY EXTRACTION — REQUIRED FOR EVERY MIGRATION SLICE
+  Do not translate controllers, services, handlers, or exported functions one-for-one into Features
+  or portable Functions. For each candidate capability, trace entry points, callees, state changes,
+  external calls, errors, authorization, session usage, transactions, retries, and tests, then create
+  a decomposition ledger with these classifications:
+
+    DUCTAPE_PRIMITIVE       database, App action, Events, session, storage, graph, vector,
+                           notification, cache, quota, fallback, healthcheck, secret
+    FEATURE                user/product capability coordinating multiple meaningful operations
+    PORTABLE_FUNCTION      residual reusable domain logic that primitives cannot express
+    CHILD_FEATURE          independently meaningful capability with its own contract/lifecycle
+    UTILITY                local implementation detail with no independent product contract
+    INFRASTRUCTURE_ADAPTER framework/provider plumbing replaced by a Ductape primitive
+
+  The required order is:
+    1. Extract and inventory Ductape primitives from the existing implementation.
+    2. Establish the capability and transaction boundary from behavior and tests.
+    3. Design named Feature steps around those primitives.
+    4. Put only irreducible application-owned logic behind ctx.functions.
+    5. For each Function, record pure/WASM-candidate versus framework-dependent classification.
+    6. Call ductape_function_setup and implement verified local plus remote availability.
+
+  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.
+  A mixed method may legitimately become several primitive steps plus one small Function, one database
+  action, or one capability-scoped Function when atomicity requires co-location.
+
+  Before implementation, present a decomposition table with: source behavior, evidence location,
+  classification, selected Ductape primitive/function, input/output, side effects, transaction owner,
+  session behavior, failure semantics, and verification test. If the residual Function has no clear
+  reason to exist after primitive extraction, do not create it.
+
 FINAL E2E ACCEPTANCE GATE
   End the migration by running the exact original E2E command against the migrated codebase while retaining
   the original checksum-bound suite. Do not silently edit, delete, skip, quarantine, or weaken baseline tests.
@@ -3404,7 +3532,7 @@ STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
     → 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
+    → Add recordInput: { items: [{ id: "1" }, { id: "2" }] } and iterate ctx.sampleInput.items
     → 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
@@ -3514,7 +3642,8 @@ When you call features.define({ handler }), the handler runs TWICE:
      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: use recordInput so the handler sees sample data and all iterations are recorded.
+     For loops: supply recordInput and iterate ctx.sampleInput 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.
 
   2. EXECUTION PHASE (at runtime) — handler is called with a real ExecutionContext.
@@ -4533,6 +4662,8 @@ const portableFunctionSetupHandler = async (args) => {
     return { content: [{ type: 'text', text: JSON.stringify({
                     ok: true,
                     requiredActions: [
+                        'Prove that database, App, Events, session, storage, graph, vector, notification, cache, quota, fallback, healthcheck, and secret primitives were extracted before defining this residual application Function.',
+                        'Record whether the residual logic is pure/signed-WASM-capable or framework-dependent, including transaction and side-effect boundaries.',
                         'Create or locate one defineFunctions contract with exact input/output JSON Schemas.',
                         'Register handlers with ductape.functions.register during application startup.',
                         `Set DUCTAPE_FUNCTION_BASE_URL=${JSON.stringify(base)} in the application runtime.`,
@@ -5052,14 +5183,22 @@ async function main() {
         server.registerTool('ductape_function_setup', {
             title: 'Ductape Portable Function Setup',
             description: 'Generate the mandatory secure local + remote runtime setup for application functions used by Features. ' +
-                'Use this whenever feature code calls application-owned logic. The result requires a registered local handler, ' +
+                'Use this only after a primitives-first decomposition proves residual application-owned logic remains. The result requires a registered local handler, ' +
                 'a deterministic HTTPS endpoint, raw-body HMAC verification, runtime checks, and fail-closed behavior.',
             inputSchema: portableFunctionSetupInputSchema,
         }, portableFunctionSetupHandler);
+        server.registerTool('ductape_redis_setup', {
+            title: 'Ductape Local Redis Setup',
+            description: 'Provision or start an isolated local Redis container for Ductape bootstrap caching and dispatch queues. ' +
+                'First explain the latency benefit and ask for explicit approval. Never pass approved=true before the user agrees. ' +
+                'Uses redis:7-alpine, binds only to 127.0.0.1, enables append-only persistence, and returns the redis URL to wire into Ductape initialization.',
+            inputSchema: redisSetupInputSchema,
+        }, redisSetupHandler);
         server.registerTool('ductape_migration_plan', {
             title: 'Ductape AI Migration Guidance',
             description: 'Inspect a TypeScript, Go, Java, or .NET repository without exposing secret values. ' +
                 'Builds a relevant-file review queue, secret-name inventory, checksummed migration evidence, and low-confidence navigation hints. ' +
+                'Migration review must extract Ductape primitives before classifying residual domain logic as portable Functions. ' +
                 'The review standards classify capability candidates as FEATURE, FEATURE_STEP, DOMAIN_SERVICE, UTILITY, or INFRASTRUCTURE_ADAPTER; ' +
                 'they inspect exports, public methods, entry points, consumers, jobs, repeated orchestration, typed operations, routes, and product terminology. ' +
                 'Synchronous local multi-step capabilities may be Features, while related low-level functions must be grouped rather than promoted one-by-one. ' +
@@ -5182,6 +5321,7 @@ async function main() {
         server.tool('ductape_docs', docsInputSchema.shape, docsHandler);
         server.tool('ductape_events_discover', eventsDiscoveryInputSchema.shape, eventsDiscoveryHandler);
         server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupHandler);
+        server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);
         server.tool('ductape_cli', cliInputSchema.shape, cliHandler);
     }

package/docs/TOOLS.md

@@ -8,6 +8,12 @@ Produces the mandatory local registry and signed HTTPS exposure plan for portabl
 functions referenced by Features. The route is
 `/.well-known/ductape/functions/:namespace/:version/:operation` and requests use HMAC-SHA256.
 
+Call it only after a primitives-first migration review. Extract database, App, Events, session,
+storage, graph, vector, notification, cache, quota, fallback, healthcheck, and secret behavior into
+native Ductape primitives. A Function contains only the irreducible application-owned logic unless
+the original atomic transaction requires co-location. Classify that residual logic as pure and
+future-WASM-capable or framework-dependent.
+
 ---
 
 ## Marketplace discovery

package/package.json

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