@ductape/mcp 0.2.30 → 0.2.32

package/CHANGELOG.md

@@ -6,6 +6,7 @@
 
 ## Unreleased
 
+- Added `cli-authentication` guidance for automatic Google/GitHub browser OAuth, validated loopback callbacks, trusted-terminal handoff, credential non-disclosure, and external session refresh.
 - Added source-verified graph/vector projection guidance to the `features`, `events`, `graphs`, and `vector` docs topics, including exact graph/vector payloads, NestJS consumer routing, replay/idempotency, projection-state ordering, rebuild/drift repair, and an explicit stop condition for the currently missing code-first `ctx.vector` API.
 - Added read-only `ductape_events_topic_setup` and `ductape_events_validate_project` tools and made the canonical one-topic-per-file `ductape/events/<topic-tag>.topic.json` layout explicit and enforceable through the CLI.
 - Mark `ductape_function_setup` as read-only, non-destructive, idempotent, and closed-world in both MCP registration APIs so hosts do not incorrectly require mutation approval for its pure setup-plan generation.

package/dist/index.js

@@ -909,12 +909,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   vector.deleteIndex    [{ product, env, vector, name }]
   vector.listIndexes    [{ product, env, vector }]
   vector.count          [{ product, env, vector, namespace? }]
-  vector.actions.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
-  vector.actions.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
-  vector.actions.fetch  [{ product, vector, actionTag }]
-  vector.actions.fetchAll [{ product, vector }]
-  vector.actions.delete [{ product, vector, actionTag }]
-  vector.actions.execute [{ product, env, vector, action, input }]
+  vector.action.create [{ product, vector, actionTag, name, operation, template, description?, parameters? }]
+  vector.action.update [{ product, vector, actionTag, name?, description?, template?, parameters? }]
+  vector.action.fetch  [{ product, vector, actionTag }]
+  vector.action.fetchAll [{ product, vector }]
+  vector.action.delete [{ product, vector, actionTag }]
+  vector.action.execute [{ product, env, vector, action, input, session? }]
+    ← synchronous saved-action execution. Do not use vector.query for a saved action.
 
 ━━━ MODULE: features ━━━
   Feature definitions are code-first. Use features.define in application source; do not call
@@ -944,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
@@ -1500,6 +1504,7 @@ function runCli(command) {
                     'or use an OAuth flow:',
                     '  ductape login --browser google',
                     '  ductape login --browser github',
+                    'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                     '',
                     'Do not paste a password, OAuth callback token, or stored CLI credential into an agent prompt.',
                     'After login succeeds, retry the same ductape_cli command.',
@@ -1551,7 +1556,7 @@ const docsInputSchema = z.object({
     topic: z.string().describe('Feature topic to look up. Supported: ' +
         'transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
         'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-        'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue'),
+        'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue'),
 });
 const eventsDiscoveryInputSchema = z.object({
     query: z.string().optional().describe('Capability or recovery search, including DLQ, dead letter, failed messages, retry, poison message, replay, or consumer failure.'),
@@ -1607,6 +1612,34 @@ const migrationInputSchema = z.object({
     write: z.boolean().optional().default(false).describe('Write redacted advisory artifacts only. This never writes application code or executable Ductape assets.'),
 });
 const DOCS = {
+    'cli-authentication': `
+DUCTAPE CLI AUTHENTICATION
+
+For an interactive local login, prefer browser OAuth:
+  ductape login --browser google
+  ductape login --browser github
+
+The CLI opens the provider in the user's browser, starts a temporary loopback listener on
+127.0.0.1, validates the returned OAuth state, exchanges the callback token, stores the resulting
+session in the local Ductape credential store, and then continues workspace selection. The user
+does not copy a callback token or share credentials with an agent.
+
+Run browser login only in the user's trusted local terminal. An MCP tool, agent subprocess, CI
+runner, container, SSH session, or remote development host may not own the browser's loopback
+interface. Do not invoke interactive login through ductape_cli and do not ask the user to paste a
+password, OAuth callback token, auth token, or stored credential into chat.
+
+Use email/password login only when the user deliberately chooses it in their own terminal:
+  ductape login
+
+Use --token only as a compatibility or automation fallback when the user already possesses a
+valid OAuth callback token through a trusted flow. Never solicit that token in an agent prompt.
+
+After login succeeds, retry the original ductape_cli operation. The MCP re-reads a previously
+missing or expired external CLI session without requiring an MCP restart. If a command returns
+HTTP 401 while workspace reads still succeed, treat it as endpoint authorization or command
+routing failure, not as a reason to re-authenticate.
+`.trim(),
     'portable-functions': `
 PORTABLE APPLICATION FUNCTIONS
 
@@ -2551,10 +2584,12 @@ Schema management:
   graph.dropIndex / dropConstraint / listIndexes / listConstraints
 
 Saved actions (parameterized queries stored on the product):
-  graph.createAction [{ graphTag?, name, description?, operation, query, parameters: [{ name, type, required?, defaultValue?, description? }] }, productTag?]
-  graph.listActions  [graphTag?, productTag?]
-  graph.execute      [{ product, env, graph, action, input?, session?, cache? }]
-  graph.dispatch     [data]  ← call ductape_generate_payload FIRST
+  graph.action.create   [{ product, graph|graphTag, name, description?, operation, query, parameters? }]
+  graph.action.fetchAll [{ product, graph|graphTag }]
+  graph.action.fetch    [{ product, graph|graphTag, action|actionTag }]
+  graph.action.execute  [{ product, env, graph, action, input, session? }]
+  graph.action.dispatch [{ product, env, graph, event, input, schedule? }]  ← call ductape_generate_payload FIRST
+  Use graph.action.execute for a saved action. graph.query is only for a direct provider-native query.
 
 Supported index types: btree | fulltext | vector | range | point | text
 Supported constraint types: UNIQUE | EXISTS | NODE_KEY
@@ -3341,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:
   {
@@ -3897,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.
@@ -4015,22 +4132,36 @@ 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.
-
-  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.
-
-  Implication: put all meaningful business logic INSIDE ctx.step() handlers, not in the
+     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.
+
+     ductape features sync [filter] sets DUCTAPE_SYNC_MODE=1 and, when filtered,
+     DUCTAPE_FEATURE_FILTER=<filter>. This is an administrative catalogue-only lifecycle: framework
+     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) — 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: 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).
 
@@ -5100,8 +5231,10 @@ EXACT CODE-FIRST VECTOR CONTEXT:
     ductape vector actions get <action-tag> --vector <vector-tag> --json
   Always list and inspect first. Reuse an existing action when operation, namespace/filter/template,
   parameters, and output semantics match; do not create a duplicate action under a new name.
-  Update/delete/list use the same \`ductape vector actions\` surface. At runtime the SDK namespace is
-  \`ductape.vector.actions.*\` (plural), while Feature reuse is singular \`ctx.vector.execute(...)\`.
+  Update/delete/list use the same plural \`ductape vector actions\` CLI surface. Runtime SDK/MCP calls
+  use the singular \`ductape.vector.action.*\` namespace; execute saved actions with
+  \`ductape.vector.action.execute({ product, env, vector, action, input })\`. Feature handlers instead
+  use \`ctx.vector.execute({ vector, action, input })\` because product/env/session are inherited.
   Vertex AI Vector Search stores and searches supplied vectors. It does NOT generate embeddings.
   Do not claim that a Vertex Vector Search index embeds text.
 
@@ -5461,7 +5594,9 @@ const cliInputSchema = z.object({
         '"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.'),
+        'The CLI uses the user\'s local logged-in session. Prefer browser OAuth in a trusted local terminal: ' +
+        'ductape login --browser google (or github). It returns automatically through a validated loopback callback. ' +
+        'Never invoke interactive login through MCP or ask the user for credentials.'),
 });
 async function loadMcpSdk() {
     try {
@@ -5626,6 +5761,25 @@ async function main() {
         const isLocalMigrationGuidance = (firstWord === 'migrate-codebase' && !args.command.includes('--ensure-product')) ||
             firstWord.startsWith('migration-');
         const isDiagnostic = firstWord === 'doctor';
+        if (firstWord === 'login') {
+            return {
+                content: [{
+                        type: 'text',
+                        text: [
+                            'Ductape login must be completed by the user in a trusted local terminal, not through an MCP tool process.',
+                            '',
+                            'Preferred browser OAuth:',
+                            '  ductape login --browser google',
+                            '  ductape login --browser github',
+                            '',
+                            'The browser returns to the CLI automatically through a validated 127.0.0.1 callback; no token copying is required.',
+                            'Never ask the user to paste a password, OAuth callback token, auth token, or stored CLI credential into the agent.',
+                            'After login succeeds, retry the original ductape_cli operation. The MCP will detect the new session.',
+                        ].join('\n'),
+                    }],
+                isError: true,
+            };
+        }
         if (!isAuthCommand && !isLocalMigrationGuidance && !isDiagnostic) {
             // Cache successful authentication, but re-check a missing/expired session on every call.
             // The user may complete `ductape login` in another terminal while this MCP process remains
@@ -5648,6 +5802,7 @@ async function main() {
                                 'or:',
                                 `  ductape login --browser google${wsFlag}`,
                                 `  ductape login --browser github${wsFlag}`,
+                                'Browser OAuth returns to the CLI automatically through a validated 127.0.0.1 callback.',
                                 '',
                                 'Never ask the user to paste their password, OAuth callback token, or stored CLI credential into the agent.',
                                 'After login succeeds, retry the original ductape_cli command.',
@@ -6082,7 +6237,7 @@ async function main() {
                 'index strategy, operation types) that should be confirmed with the user first.\n\n' +
                 'Available topics: transactions, presave, triggers, aggregations, migrations, indexes, performance, actions, ' +
                 'graphs, storage, cloud, vector, warehouse, secrets, apps, products, sessions, caches, ' +
-                'notifications, resilience, features, portable-functions, events, logs, migration, frontend, frontend-analytics, client, react, vue',
+                'notifications, resilience, features, portable-functions, events, logs, migration, cli-authentication, frontend, frontend-analytics, client, react, vue',
             inputSchema: docsInputSchema,
         }, docsHandler);
         server.registerTool('ductape_events_discover', {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.2.30",
+  "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"
   },