@ductape/mcp 0.2.8 → 0.2.10

package/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.2.9
+
+- Security: execute `ductape_cli` with an argument array and no shell, reject shell operators/substitutions, and validate quoted command input before checking the administrative subcommand allowlist.
+
 ## Unreleased
 
 - Broadened Feature guidance from durable/event-driven workflows to synchronous or asynchronous named product capabilities.

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/cli-command.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Parse the user-facing command string into an argv array without invoking a shell.
+ * Supports ordinary single/double quoting and backslash escaping for paths/values.
+ */
+export declare function parseCliCommand(command: string): string[];
+//# sourceMappingURL=cli-command.d.ts.map

package/dist/cli-command.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli-command.d.ts","sourceRoot":"","sources":["../src/cli-command.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAmDzD"}

package/dist/cli-command.js

@@ -0,0 +1,66 @@
+/** Characters with shell control/expansion meaning are never valid in ductape_cli input. */
+const SHELL_META = /[;&|`$<>()\r\n\0]/;
+/**
+ * Parse the user-facing command string into an argv array without invoking a shell.
+ * Supports ordinary single/double quoting and backslash escaping for paths/values.
+ */
+export function parseCliCommand(command) {
+    if (typeof command !== 'string' || command.trim() === '') {
+        throw new Error('A non-empty Ductape CLI command is required.');
+    }
+    if (SHELL_META.test(command)) {
+        throw new Error('Shell operators, substitutions, redirects, and control characters are not allowed.');
+    }
+    const argv = [];
+    let token = '';
+    let quote = null;
+    let tokenStarted = false;
+    for (let index = 0; index < command.length; index += 1) {
+        const char = command[index];
+        if (quote) {
+            if (char === quote) {
+                quote = null;
+            }
+            else if (char === '\\' && quote === '"') {
+                index += 1;
+                if (index >= command.length)
+                    throw new Error('Trailing escape in Ductape CLI command.');
+                token += command[index];
+            }
+            else {
+                token += char;
+            }
+            tokenStarted = true;
+            continue;
+        }
+        if (char === "'" || char === '"') {
+            quote = char;
+            tokenStarted = true;
+        }
+        else if (char === '\\') {
+            index += 1;
+            if (index >= command.length)
+                throw new Error('Trailing escape in Ductape CLI command.');
+            token += command[index];
+            tokenStarted = true;
+        }
+        else if (/\s/.test(char)) {
+            if (tokenStarted) {
+                argv.push(token);
+                token = '';
+                tokenStarted = false;
+            }
+        }
+        else {
+            token += char;
+            tokenStarted = true;
+        }
+    }
+    if (quote)
+        throw new Error('Unterminated quote in Ductape CLI command.');
+    if (tokenStarted)
+        argv.push(token);
+    if (argv.length === 0)
+        throw new Error('A non-empty Ductape CLI command is required.');
+    return argv;
+}

package/dist/index.js

@@ -10,7 +10,8 @@
  * the env var when provided.
  */
 import { createRequire } from 'module';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
+import { parseCliCommand } from './cli-command.js';
 import { homedir } from 'os';
 import { delimiter, join } from 'path';
 import { z } from 'zod';
@@ -21,6 +22,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 +268,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 +304,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 +836,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 +1179,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() {
@@ -1186,7 +1251,8 @@ const ADMIN_SUBCOMMANDS = [
 ];
 function checkCli() {
     try {
-        const out = execSync('ductape --version', {
+        const out = execFileSync('ductape', ['--version'], {
+            shell: false,
             encoding: 'utf8',
             timeout: 15000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -1208,7 +1274,8 @@ function checkLoginState() {
         // `ductape whoami` only reports whether a local credentials file exists. It does not validate
         // the stored token, so an expired token would be cached as authenticated and fail later with 401.
         // Use a harmless authenticated read to validate the credential against the API.
-        execSync('ductape workspaces list --json', {
+        execFileSync('ductape', ['workspaces', 'list', '--json'], {
+            shell: false,
             encoding: 'utf8',
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -1229,7 +1296,8 @@ function syncWorkspace() {
     if (!target)
         return;
     try {
-        execSync(`ductape workspaces use "${target}"`, {
+        execFileSync('ductape', ['workspaces', 'use', target], {
+            shell: false,
             encoding: 'utf8',
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
@@ -1242,7 +1310,14 @@ function syncWorkspace() {
     }
 }
 function runCli(command) {
-    const first = command.trim().split(/\s+/)[0];
+    let argv;
+    try {
+        argv = parseCliCommand(command);
+    }
+    catch (error) {
+        return { success: false, output: `Rejected unsafe ductape_cli command: ${error.message}` };
+    }
+    const first = argv[0];
     if (!ADMIN_SUBCOMMANDS.includes(first)) {
         return {
             success: false,
@@ -1250,13 +1325,13 @@ function runCli(command) {
         };
     }
     // Auto-inject --workspace on login if DUCTAPE_WORKSPACE is set and caller hasn't specified one
-    let finalCommand = command;
     const ws = process.env.DUCTAPE_WORKSPACE;
-    if (first === 'login' && ws && !command.includes('--workspace') && !command.includes('--skip-workspace-select')) {
-        finalCommand = `${command} --workspace "${ws}"`;
+    if (first === 'login' && ws && !argv.includes('--workspace') && !argv.includes('--skip-workspace-select')) {
+        argv.push('--workspace', ws);
     }
     try {
-        const output = execSync(`ductape ${finalCommand}`, {
+        const output = execFileSync('ductape', argv, {
+            shell: false,
             encoding: 'utf8',
             // Must exceed the proxy's operation timeout so stderr can preserve the structured timeout
             // instead of this wrapper killing the CLI first and reducing it to "(no data)".
@@ -1384,6 +1459,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 +1577,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 +3543,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 +3653,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 +4673,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 +5194,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 +5332,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.10",
   "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-frontend-analytics-guidance.mjs && node scripts/check-events-discovery.mjs && node scripts/check-schema-fallback.mjs && node scripts/check-portable-functions.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-portable-functions.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },