@ductape/mcp 0.3.2 → 0.3.4

package/README.md

@@ -95,6 +95,12 @@ The server exposes runtime, schema, documentation, CLI, discovery, migration, an
    - 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.
 
+6. **`ductape_frontend_analytics_validate_project`**:
+   - Read-only audit for deployable applications using `@ductape/react`, `@ductape/vue`, or the browser client.
+   - Requires an enabled, deferred, or prohibited decision per application in `ductape/analytics/frontend.json`.
+   - When enabled, checks analytics usage, authenticated identity lifecycle, router pageviews, named events, client-failure signals, and auto-capture privacy review.
+   - Reports actionable findings without rewriting application source.
+
 The `ductape_cli` MCP tool also exposes public app discovery:
 `marketplace search <capability>`, `marketplace categories`, and
 `marketplace get <app_tag>`. Inspect the app before generating or executing an action payload.

package/dist/frontend-analytics-validator.d.ts

@@ -0,0 +1,28 @@
+export type AnalyticsDecisionStatus = 'enabled' | 'deferred' | 'prohibited';
+interface AnalyticsDecision {
+    status?: AnalyticsDecisionStatus;
+    rationale?: string;
+    autoCapture?: 'disabled' | 'reviewed';
+    privacyReviewed?: boolean;
+}
+export interface FrontendAnalyticsValidationResult {
+    valid: boolean;
+    decisionFile: string;
+    summary: {
+        applications: number;
+        errors: number;
+        warnings: number;
+    };
+    applications: Array<{
+        path: string;
+        framework: 'react' | 'vue' | 'client';
+        decision?: AnalyticsDecision;
+        signals: Record<string, boolean>;
+        errors: string[];
+        warnings: string[];
+    }>;
+    remediation: string[];
+}
+export declare function validateFrontendAnalyticsProject(projectDir: string): FrontendAnalyticsValidationResult;
+export {};
+//# sourceMappingURL=frontend-analytics-validator.d.ts.map

package/dist/frontend-analytics-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frontend-analytics-validator.d.ts","sourceRoot":"","sources":["../src/frontend-analytics-validator.ts"],"names":[],"mappings":"AASA,MAAM,MAAM,uBAAuB,GAAG,SAAS,GAAG,UAAU,GAAG,YAAY,CAAC;AAE5E,UAAU,iBAAiB;IACzB,MAAM,CAAC,EAAE,uBAAuB,CAAC;IACjC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,UAAU,GAAG,UAAU,CAAC;IACtC,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B;AAMD,MAAM,WAAW,iCAAiC;IAChD,KAAK,EAAE,OAAO,CAAC;IACf,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,YAAY,EAAE,KAAK,CAAC;QAClB,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,OAAO,GAAG,KAAK,GAAG,QAAQ,CAAC;QACtC,QAAQ,CAAC,EAAE,iBAAiB,CAAC;QAC7B,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QACjC,MAAM,EAAE,MAAM,EAAE,CAAC;QACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;KACpB,CAAC,CAAC;IACH,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AA0DD,wBAAgB,gCAAgC,CAC9C,UAAU,EAAE,MAAM,GACjB,iCAAiC,CAkGnC"}

package/dist/frontend-analytics-validator.js

@@ -0,0 +1,168 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const IGNORED_DIRECTORIES = new Set([
+    '.git', '.next', '.nuxt', '.output', 'build', 'coverage', 'dist', 'node_modules',
+]);
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.mjs', '.cjs', '.ts', '.tsx', '.vue']);
+const MAX_SOURCE_BYTES = 1_000_000;
+function walk(root, visit) {
+    if (!fs.existsSync(root))
+        return;
+    for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            continue;
+        const absolute = path.join(root, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRECTORIES.has(entry.name))
+                walk(absolute, visit);
+        }
+        else if (entry.isFile()) {
+            visit(absolute);
+        }
+    }
+}
+function readJson(file) {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+function packageFramework(manifest) {
+    const runtimeDependencies = manifest.dependencies ?? {};
+    const dependencies = {
+        ...runtimeDependencies,
+        ...(manifest.devDependencies ?? {}),
+    };
+    const scripts = Object.values(manifest.scripts ?? {}).join(' ');
+    const isApplication = Boolean(runtimeDependencies['react-dom'] ||
+        runtimeDependencies.vue ||
+        runtimeDependencies.svelte ||
+        runtimeDependencies['@angular/core'] ||
+        /(?:^|\s)(?:vite|next|nuxt|react-scripts)(?:\s|$)/.test(scripts) ||
+        manifest.browser);
+    if (!isApplication)
+        return undefined;
+    if (dependencies['@ductape/react'])
+        return 'react';
+    if (dependencies['@ductape/vue'])
+        return 'vue';
+    if (dependencies['@ductape/client'] && (dependencies.react || dependencies.vue))
+        return 'client';
+    return undefined;
+}
+function scanSource(applicationRoot) {
+    const chunks = [];
+    walk(applicationRoot, (file) => {
+        if (!SOURCE_EXTENSIONS.has(path.extname(file)))
+            return;
+        const stats = fs.statSync(file);
+        if (stats.size > MAX_SOURCE_BYTES)
+            return;
+        chunks.push(fs.readFileSync(file, 'utf8'));
+    });
+    return chunks.join('\n');
+}
+function normalizedRelative(root, target) {
+    return path.relative(root, target).split(path.sep).join('/') || '.';
+}
+export function validateFrontendAnalyticsProject(projectDir) {
+    const root = path.resolve(projectDir);
+    if (!path.isAbsolute(projectDir) || !fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        throw new Error('project_dir must be an existing absolute project directory.');
+    }
+    const decisionFile = path.join(root, 'ductape', 'analytics', 'frontend.json');
+    let decisions = {};
+    let decisionError;
+    if (fs.existsSync(decisionFile)) {
+        try {
+            const parsed = readJson(decisionFile);
+            if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                throw new Error('top level must be an object');
+            }
+            decisions = parsed;
+        }
+        catch (error) {
+            decisionError = `Invalid decision file: ${error instanceof Error ? error.message : String(error)}`;
+        }
+    }
+    const packageFiles = [];
+    walk(root, (file) => {
+        if (path.basename(file) === 'package.json')
+            packageFiles.push(file);
+    });
+    const applications = packageFiles.flatMap((manifestFile) => {
+        let manifest;
+        try {
+            manifest = readJson(manifestFile);
+        }
+        catch {
+            return [];
+        }
+        const framework = packageFramework(manifest);
+        if (!framework)
+            return [];
+        const applicationRoot = path.dirname(manifestFile);
+        const applicationPath = normalizedRelative(root, applicationRoot);
+        const source = scanSource(applicationRoot);
+        const decision = decisions.applications?.[applicationPath];
+        const signals = {
+            provider: /DuctapeProvider/.test(source),
+            authenticatedSessions: /useSession|\.sessions\.|sessionToken|refreshToken/.test(source),
+            analytics: /useAnalytics|\.analytics\./.test(source),
+            identify: /(?:analytics\.)?identify\s*\(/.test(source),
+            clearSession: /(?:analytics\.)?clearSession\s*\(/.test(source),
+            pageview: /(?:analytics\.)?pageview\s*\(/.test(source),
+            namedEvents: /(?:analytics\.)?track\s*\(/.test(source),
+            autoCapture: /enableAutoCapture\s*\(/.test(source),
+            clientFailure: /client[_\-. ]error|frontend[_\-. ]error|error_boundary|unhandledrejection/i.test(source),
+        };
+        const errors = [];
+        const warnings = [];
+        if (decisionError)
+            errors.push(decisionError);
+        if (!decision) {
+            errors.push(`Record this application in ${normalizedRelative(root, decisionFile)}.`);
+        }
+        else if (!['enabled', 'deferred', 'prohibited'].includes(String(decision.status))) {
+            errors.push('Decision status must be enabled, deferred, or prohibited.');
+        }
+        else if (decision.status !== 'enabled' && !decision.rationale?.trim()) {
+            errors.push(`${decision.status} analytics requires a non-empty rationale.`);
+        }
+        else if (decision.status === 'enabled') {
+            if (!decision.privacyReviewed)
+                errors.push('Enabled analytics requires privacyReviewed: true.');
+            if (!signals.analytics)
+                errors.push('No Ductape analytics API usage was found.');
+            if (!signals.pageview)
+                errors.push('No initial/router pageview lifecycle was found.');
+            if (!signals.namedEvents)
+                errors.push('No reviewed named product event was found.');
+            if (signals.authenticatedSessions && !signals.identify) {
+                errors.push('Authenticated sessions exist but identify(fullSessionToken) was not found.');
+            }
+            if (signals.authenticatedSessions && !signals.clearSession) {
+                errors.push('Authenticated sessions exist but clearSession() was not found.');
+            }
+            if (signals.autoCapture && decision.autoCapture !== 'reviewed') {
+                errors.push('Auto-capture is enabled without a recorded reviewed decision.');
+            }
+            if (!signals.clientFailure) {
+                warnings.push('No sanitized client-failure analytics signal was detected; review error boundaries and unhandled failures.');
+            }
+        }
+        return [{ path: applicationPath, framework, decision, signals, errors, warnings }];
+    });
+    const errors = applications.reduce((count, app) => count + app.errors.length, 0);
+    const warnings = applications.reduce((count, app) => count + app.warnings.length, 0);
+    return {
+        valid: errors === 0,
+        decisionFile,
+        summary: { applications: applications.length, errors, warnings },
+        applications,
+        remediation: [
+            'Read ductape_docs({ topic: "frontend-analytics" }) before changing application code.',
+            'Create ductape/analytics/frontend.json with one applications entry per reported relative path.',
+            'Choose enabled, deferred, or prohibited explicitly; never treat silent omission as completion.',
+            'When enabled, keep auto-capture off until consent, masking, selectors, and sensitive states are reviewed.',
+            'This validator is read-only and must not be used as an automatic codemod.',
+        ],
+    };
+}

package/dist/index.js

@@ -19,6 +19,7 @@ import { normalizeLiveActionContract } from './action-contract.js';
 import { runtimeInputRecovery } from './runtime-recovery.js';
 import { executeViaProxy, generateExecutablePayload, getAssetSchemas, } from './proxy-client.js';
 import { EVENTS_DELIVERY_SEMANTICS, EVENTS_IMPLEMENTATION_WARNING, eventsCapabilityOverview, inspectEventsComponent, searchEventsCapabilities, } from './events-capabilities.js';
+import { validateFrontendAnalyticsProject } from './frontend-analytics-validator.js';
 const MODULES = [
     'product', 'app', 'databases', 'graph', 'webhooks', 'notifications',
     'events', 'messageBrokers', 'storage', 'vector', 'caches', 'sessions', 'quotas',
@@ -365,6 +366,9 @@ SETUP — register once in AppModule:
         env: process.env.NODE_ENV === 'production' ? 'prd' : 'snd',
         redisUrl: process.env.DUCTAPE_REDIS_URL,  // required — no dispatch() works without this
         runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
+        // Resolve only the original opaque session retained by the authentication guard.
+        sessionResolver: (context) =>
+          context.switchToHttp().getRequest().actor?.ductapeSession,
       }),
     ],
   })
@@ -380,9 +384,22 @@ SETUP — register once in AppModule:
       env: cfg.get('DUCTAPE_ENV'),
       redisUrl: cfg.get('DUCTAPE_REDIS_URL'),  // required — no dispatch() works without this
       runtimeSync: { intervalMs: 30_000, jitter: 0.2 },
+      sessionResolver: (context) =>
+        context.switchToHttp().getRequest().actor?.ductapeSession,
     }),
   })
 
+  SESSION-AWARE NESTJS EXECUTION:
+  Configure sessionResolver once. It runs after guards and stores the returned opaque token in
+  request-scoped context. @Feature.Execute, @Feature.Dispatch, @Api, @ApiDispatch, Events,
+  notifications, jobs, agents, and session-capable injected resource handles inherit it without
+  adding it to business input. Do not return a session from a decorated method or put it in DTOs.
+  The resolver must return the exact original "session-tag:jwt", not decoded claims or a bearer
+  header. For intentional webhook, scheduled, or broker system work, set
+  sessionContext: "system" on session-capable decorators; this suppresses request inheritance.
+  Check the installed @ductape/nestjs types before generating this configuration: 0.1.12 does not
+  yet contain sessionResolver/sessionContext and must be upgraded to the next published release.
+
   Environment variable (add to .env and deployment secrets):
     DUCTAPE_REDIS_URL=redis://localhost:6379          # local dev
     DUCTAPE_REDIS_URL=rediss://:<password>@host:6380  # managed Redis (TLS)
@@ -857,7 +874,13 @@ ALL params are passed as a JSON array in positional order matching the SDK signa
   graph.create  [{ product, tag, name, description?, type: "neo4j"|"nebula"|"arangodb", envs: [{slug, connection_url, username?, password?}] }]
   graph.fetch   [product_tag, graph_tag]
   graph.list    [product_tag?]
-  graph.update  [product_tag, graph_tag, data: { name?: string, description?: string, type?: "neo4j"|"neptune"|"arangodb"|"memgraph", envs?: [{ slug: string, connection_url: string, username?: string, password?: string, database?: string, graphName?: string, region?: string }] }]
+  graph.update  [product_tag, graph_tag, data: { name?: string, description?: string, type?: "neo4j"|"neptune"|"arangodb"|"memgraph", envs?: [{ slug: string, connection_url?: string, username?: string, password?: string, database?: string, graphName?: string, region?: string }] }]
+    Each env entry is a PARTIAL patch merged with that env's existing persisted config — only
+    include the fields you're actually changing (e.g. just { slug, password } to rotate a
+    password). connection_url is required only when adding a brand-new env slug; omitting it on
+    an existing slug leaves the current value untouched. Field name is "password", not
+    "masterPassword" — that's a different field used only by cloud resources import-persist-all
+    (see the Neo4j Aura import flow section below), not by graph.create/graph.update.
   graph.delete  [graph_tag, product_tag?]
   graph.connect [{ product, env, graph }]
   graph.testConnection [config]
@@ -1311,7 +1334,7 @@ function buildSdkInvocationArgs(payload) {
 function operationAcceptsSession(operationFamily, method) {
     const family = operationFamily.toLowerCase();
     const sessionFamilies = new Set([
-        'action', 'features', 'feature', 'database', 'graph', 'vector', 'storage',
+        'action', 'api', 'app', 'apps', 'features', 'feature', 'database', 'graph', 'vector', 'storage',
         'notification', 'messaging', 'broker', 'events', 'event', 'quota', 'fallback',
     ]);
     if (!sessionFamilies.has(family))
@@ -1444,7 +1467,7 @@ function buildDatabaseActionFeatureExample(targets, contract) {
 let authState = 'unknown';
 let workspaceSynced = false;
 const ADMIN_SUBCOMMANDS = [
-    'login', 'logout', 'whoami',
+    'login', 'logout', 'whoami', 'doctor',
     'profiles',
     'workspaces',
     'link', 'unlink', 'init',
@@ -1469,7 +1492,7 @@ const ADMIN_SUBCOMMANDS = [
     'migration-products',
     'migration-secrets',
 ];
-function checkCli() {
+function checkCli(projectDir) {
     try {
         const out = execFileSync('ductape', ['--version'], {
             shell: false,
@@ -1477,7 +1500,7 @@ function checkCli() {
             timeout: 15000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         }).trim();
         return { available: true, version: out || 'unknown' };
     }
@@ -1489,7 +1512,7 @@ function checkCli() {
         return { available: !commandMissing };
     }
 }
-function checkLoginState() {
+function checkLoginState(projectDir) {
     try {
         // `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.
@@ -1500,7 +1523,7 @@ function checkLoginState() {
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
         authState = 'ok';
         return 'ok';
@@ -1510,7 +1533,7 @@ function checkLoginState() {
         return 'none';
     }
 }
-function syncWorkspace() {
+function syncWorkspace(projectDir) {
     const target = process.env.DUCTAPE_WORKSPACE;
     workspaceSynced = true; // mark done regardless so we don't retry on every call
     if (!target)
@@ -1522,14 +1545,14 @@ function syncWorkspace() {
             timeout: 10000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
     }
     catch {
         // best-effort; if it fails the user will see workspace-mismatch errors on subsequent commands
     }
 }
-function runCli(command) {
+function runCli(command, projectDir) {
     let argv;
     try {
         argv = parseCliCommand(command);
@@ -1558,7 +1581,7 @@ function runCli(command) {
             timeout: 90000,
             stdio: ['pipe', 'pipe', 'pipe'],
             env: cliEnvironment(),
-            cwd: cliCwd(),
+            cwd: cliCwd(projectDir),
         });
         return { success: true, output: output.trim() };
     }
@@ -1567,7 +1590,7 @@ function runCli(command) {
         if (/\bHTTP 401\b|unauthori[sz]ed|invalid token|token expired/i.test(msg)) {
             // Distinguish a genuinely expired login from a command-specific endpoint/auth bug.
             // A valid workspace read proves the CLI session and selected workspace are authenticated.
-            if (checkLoginState() === 'ok') {
+            if (checkLoginState(projectDir) === 'ok') {
                 return {
                     success: false,
                     output: [
@@ -1635,8 +1658,14 @@ function cliEnvironment() {
  * cwd is unrelated to the project). Set DUCTAPE_PROJECT_DIR explicitly in the server's env
  * (e.g. in .mcp.json) to pin it; falls back to this process's own cwd otherwise.
  */
-function cliCwd() {
-    return process.env.DUCTAPE_PROJECT_DIR || process.cwd();
+// `process.cwd()` here is the long-running MCP server process's own working directory — fixed for
+// its whole lifetime by whatever launched it, not the project the calling agent is currently
+// working in. A static DUCTAPE_PROJECT_DIR env var has the same problem: it can't track an agent
+// session that moves between projects. `override` lets a per-call `project_dir` argument (see
+// cliInputSchema, eventsProjectValidationInputSchema, eventsTopicSetupInputSchema) take precedence
+// over both, so a single long-lived MCP server can be pointed at the right project per call.
+function cliCwd(override) {
+    return override || process.env.DUCTAPE_PROJECT_DIR || process.cwd();
 }
 function shellArgument(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -1676,9 +1705,23 @@ const eventsTopicSetupInputSchema = z.object({
     sample: z.record(z.unknown()).optional(),
     idempotent: z.boolean().optional(),
     queueUrls: z.array(z.object({ env_slug: z.string().min(1), url: z.string().url() }).strict()).optional(),
+    project_dir: z.string().optional().describe('Absolute path to the project this topic asset belongs to. Without this, the returned path ' +
+        'resolves against the MCP server\'s own working directory or DUCTAPE_PROJECT_DIR, which does ' +
+        'not track which project the current session is working in — pass it whenever working in a ' +
+        'project other than wherever the MCP server happened to start.'),
 });
 const eventsProjectValidationInputSchema = z.object({
-    dir: z.string().default('ductape/events').describe('Must be ductape/events relative to DUCTAPE_PROJECT_DIR.'),
+    dir: z.string().default('ductape/events').describe('Must be ductape/events relative to the resolved project directory.'),
+    project_dir: z.string().optional().describe('Absolute path to the project to validate. Without this, resolution falls back to the MCP ' +
+        'server\'s own working directory or DUCTAPE_PROJECT_DIR, which does not track which project ' +
+        'the current session is working in — pass it whenever working in a project other than ' +
+        'wherever the MCP server happened to start.'),
+});
+const featuresProjectValidationInputSchema = z.object({
+    project_dir: z.string().describe('Absolute path to the linked Ductape project containing ductape/features/. The validator is read-only.'),
+});
+const frontendAnalyticsProjectValidationInputSchema = z.object({
+    project_dir: z.string().describe('Absolute path to a frontend project or monorepo. The validator is read-only and never modifies application code.'),
 });
 const readOnlyLocalAnnotations = {
     readOnlyHint: true,
@@ -1914,6 +1957,16 @@ SECURITY
   $Secret{tag}; manifests never embed credentials. Keep snd/stg/prd values separate.
   Use ductape_cli("secrets-import-env --env-file <local-file> --source-key <ENV_KEY> --key <secret-tag> --env <slug> --json").
   The command reads the value locally and redacts it from output; never place the value in an MCP argument.
+  Before running that import for any discovered .env-backed secret candidate, ask the user
+  explicitly whether to create a Ductape Secret from it — never decide silently either way (not
+  "migrate everything found" and not "leave .env alone"). Once a value is migrated, update the
+  consuming code to read it through Ductape rather than the environment: NestJS code uses the
+  @Secret() decorator from @ductape/nestjs (see ductape_docs({ topic: "secrets" }) for the DI
+  pattern); every other runtime calls secrets.fetch(key) (ductape_execute("secrets.fetch", [key]))
+  instead of process.env / os.Getenv / System.getenv / IConfiguration for that value. Only remove
+  the .env entry after the new code path is verified working, and never do this for bootstrap
+  config Ductape itself needs to start (DUCTAPE_ACCESS_KEY, DUCTAPE_REDIS_URL, NODE_ENV) — those
+  necessarily stay in the environment.
   secret_references are names-only navigation evidence from Docker Compose, Kubernetes secretKeyRef,
   GitHub/GitLab/Jenkins, Spring, .NET configuration, Terraform, and AWS/GCP/Azure secret managers.
   Their value is always [NOT_READ]. Inspect context before deciding whether a reference is sensitive,
@@ -2022,7 +2075,9 @@ COMPONENT DECISIONS
   represents a reusable product capability.
 
 LANGUAGE RUNTIME SHAPES
-  TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, and request-scoped context.
+  TypeScript: @ductape/sdk; NestJS uses @ductape/nestjs, @Events.Consumer, request-scoped context,
+  and @Secret() (DuctapeSecretsModule.register({ keys })) for any secret value instead of .env/
+  ConfigService — see ductape_docs({ topic: "secrets" }).
   Go: explicit services, context.Context, cancellation, typed errors, and owned worker shutdown.
   Java: DI/Spring integration where present, executor ownership, CompletableFuture boundaries.
   .NET: DI, hosted services, async/await, CancellationToken, configuration binding.
@@ -2293,13 +2348,13 @@ PARITY CLAIMS
 DUCTAPE FRONTEND SDK GUIDE
 
 Choose one integration package:
-  React 17+  — npm install @ductape/react
+  React 17+  — npm install @ductape/react@latest
                Provider and hooks built on @ductape/client.
                Continue with ductape_docs({ topic: "react" }).
-  Vue 3+     — npm install @ductape/vue
+  Vue 3+     — npm install @ductape/vue@latest
                Plugin and composables built on @ductape/client.
                Continue with ductape_docs({ topic: "vue" }).
-  Other UI   — npm install @ductape/client
+  Other UI   — npm install @ductape/client@latest
   frameworks   Use directly with Svelte, Angular, vanilla JavaScript, or a custom adapter.
                Continue with ductape_docs({ topic: "client" }).
 
@@ -2324,8 +2379,14 @@ SHARED APPLICATION LIFECYCLE
 
 PRODUCT ANALYTICS
   Frontend product analytics complements backend session propagation; neither replaces the other.
-  Continue with ductape_docs({ topic: "frontend-analytics" }) for identity lifecycle, pageviews,
-  custom events, privacy masking, hidden-state safety, trace correlation, and package-version checks.
+  This is a required design decision for every Ductape frontend, not an optional afterthought.
+  Always continue with ductape_docs({ topic: "frontend-analytics" }), then run
+  ductape_frontend_analytics_validate_project({ project_dir: "<absolute-project-root>" }). Record
+  one explicit enabled/deferred/prohibited choice per detected application in
+  ductape/analytics/frontend.json. Silent omission is a failed frontend build/audit outcome.
+  When enabled, wire identity lifecycle, router pageviews, reviewed named events, sanitized client
+  failures, privacy masking, hidden-state safety, and trace correlation. Keep auto-capture off until
+  consent, selectors, masking, and sensitive states have been reviewed.
 
 AUTHENTICATION AND SECURITY
   - Use publishableKey in browser applications. Never ship workspace private keys or privileged
@@ -2904,7 +2965,7 @@ Import an existing resource and register it on the product:
   Use import-persist-all for multi-env products (required):
     ductape_cli("cloud resources import-persist-all -f all-envs.json --json")
   File is a JSON ARRAY — one entry per env, same product + component tag across all entries.
-  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName?, masterPassword? }
+  Each entry: { cloud, service, type, product, component, env, resource, region?, dbName?, masterPassword?, username? }
   Supported service identifiers: s3, gcs, blob, rds, postgresql, cloudsql, sqs, pubsub,
     servicebus, neptune, cosmos-gremlin, opensearch, azure-search, atlas-cluster, aura-instance,
     vertex-vector-search, spanner-graph, dynamodb, keyspaces, mysql
@@ -2917,9 +2978,17 @@ Import an existing resource and register it on the product:
   without masterPassword will fail with a clear error at import time; skipping that check and
   importing anyway is not possible — always ask the user for the instance's password before
   calling import-persist-all for an aura-instance entry, the same as you would ask for an RDS
-  master password. Aura's username is always "neo4j" — never ask the user for it. Atlas
-  (atlas-cluster) does NOT need masterPassword — Ductape mints/rotates its own database user via
-  the Atlas Admin API.
+  master password. Atlas (atlas-cluster) does NOT need masterPassword — Ductape mints/rotates
+  its own database user via the Atlas Admin API.
+
+  username (aura-instance only) defaults to "neo4j" if omitted — that IS the correct value for
+  most Aura instances. But this default is NOT a hard guarantee: at least one real Aura instance
+  has been confirmed to authenticate with a different database username instead (its instance id,
+  in the one case observed) and rejects "neo4j" as unauthorized. If a fresh Aura import connects
+  successfully but then fails at runtime with a Neo4j "unauthorized"/access-denied error despite a
+  correct password, don't assume the password is wrong — try re-importing with username set
+  explicitly (ask the user what database username the instance actually uses) before concluding
+  the password itself is bad.
 
 Provision a brand-new resource and register it:
   ductape_cli("cloud resources provision-persist-all -f all-envs.json --json")
@@ -3074,6 +3143,47 @@ Important:
   - Other services (storage, broker, graph, etc.) resolve $Secret{} references automatically
     using the singleton secrets service — no manual resolution needed in most cases.
   - Never log or return resolved secret values to end users.
+
+APPLICATION CODE — PREFER DUCTAPE SECRETS OVER .env / process.env:
+  Once a workspace secret exists for a value, application code should read it through Ductape,
+  not through the process environment or a framework config layer backed by .env. This applies
+  to values the code reads for its own runtime use (API keys, DB passwords, webhook signing
+  secrets, etc.) — it does not apply to non-secret bootstrap config Ductape itself needs to start
+  (DUCTAPE_ACCESS_KEY, DUCTAPE_REDIS_URL, NODE_ENV), which necessarily stay in the environment.
+
+  NestJS: inject with the @Secret() decorator from @ductape/nestjs instead of ConfigService.get()
+  or process.env for any value that is (or should be) a Ductape secret:
+    import { DuctapeSecretsModule, Secret, SecretHandle } from '@ductape/nestjs';
+
+    @Module({ imports: [DuctapeSecretsModule.register({ keys: ['STRIPE_API_KEY'] })] })
+    class PaymentsModule {}
+
+    @Injectable()
+    class PaymentsService {
+      constructor(@Secret('STRIPE_API_KEY') private readonly stripeKey: SecretHandle) {}
+      // this.stripeKey.value holds the decrypted secret
+    }
+  Register every key the module needs via DuctapeSecretsModule.register({ keys: [...] }); each
+  registered key becomes an injectable token resolved through DuctapeContextService, not read
+  from process.env at any point.
+
+  Other runtimes (plain Node/Express/Fastify, Go, Java, .NET, etc.): call
+  ductape_execute("secrets.fetch", ["KEY"]) (or the SDK's secrets.fetch(key) directly in
+  application code) rather than reading process.env / os.Getenv / System.getenv / IConfiguration
+  for a value that is a Ductape secret. Resolve $Secret{KEY} references in config the same way —
+  through the secrets service, never by pre-substituting from the environment.
+
+  MIGRATING EXISTING .env SECRETS: when environment/codebase discovery (see ENVIRONMENTS and
+  SECURITY sections of the migrate-codebase guidance) finds .env entries that look like secrets
+  (API keys, passwords, tokens, connection strings with embedded credentials), do not silently
+  decide either way. Ask the user explicitly whether to create Ductape Secrets from those .env
+  entries — do not assume "yes, migrate everything" or "no, leave .env alone". If the user agrees,
+  import each value locally and specifically:
+    ductape_cli("secrets-import-env --env-file <local-file> --source-key <ENV_KEY> --key <secret-tag> --env <slug> --json")
+  then update application code to read the new secret through @Secret()/secrets.fetch() as above,
+  and only remove the .env entry once that code path is verified working. Never read the .env
+  value into MCP context or an MCP argument while doing this: the CLI command above reads the
+  local file directly and redacts the value from its own output.
 `.trim(),
     apps: `
 DUCTAPE APPS
@@ -3461,6 +3571,21 @@ SESSION PROPAGATION
   Feature execution should receive the same explicit actor classification. Never log, serialize
   into business payloads, or attach the raw session/refresh token to traces or error messages.
 
+  FAIL-CLOSED NORMAL SDK RULE
+  Before emitting or approving ordinary @ductape/sdk code for immediate authenticated work, verify
+  that every session-capable runtime call receives the exact ActorContext.session through its
+  top-level session option. This includes api.run/api.dispatch, feature.execute/feature.dispatch,
+  database primitives and saved actions, graph/vector primitives and saved actions, storage,
+  Events, notifications, agents, quotas, and fallbacks where the installed types accept session.
+  Never substitute a session tag, decoded claims, user ID, Authorization header, refresh token, or
+  business-input field. If the original opaque token is unavailable, stop and report the missing
+  propagation boundary; do not silently emit an unattributed user-context call. The only omission
+  allowed is an explicitly classified system context or a version-verified approved delegated flow.
+
+  A Feature receives the session at its execution boundary. Its nested ctx.api, ctx.database,
+  ctx.graph, ctx.vector, ctx.storage, ctx.events, and ctx.notifications calls inherit ctx.session;
+  do not serialize ctx.session into their input objects or hardcode it in the Feature definition.
+
   SECURITY BOUNDARY FOR DURABLE WORK
   The current SDK accepts a session string on dispatch, but it does not expose an immutable
   attribution snapshot API, an expired-token attribution contract, or a general delegated-session
@@ -4289,8 +4414,11 @@ STEP 6 — WRITE the feature into the project codebase
        exiting. Ductape cannot run this step for you generically — a Feature handler is real
        application code that typically depends on the app's own services, unlike a migration file,
        which is declarative data the Ductape backend can apply directly.
-    4. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
-       finds the linked project and runs its "features:sync" script — never automatically on boot.
+    4. Run ductape_features_validate_project({ project_dir: "<absolute-project-root>" }). This is a
+       read-only AST conformance gate. Stop on any diagnostic; do not sync or mutate remote state.
+    5. Persist Features by running "ductape features sync" (or ductape_cli("features sync")), which
+       repeats the fail-closed validator, then finds the linked project and runs its "features:sync"
+       script — never automatically on boot.
        Pass an optional filter argument to scope it: "ductape features sync payments".
 
   A NestJS service with both concerns split looks like:
@@ -4322,7 +4450,8 @@ STEP 7 — HANDLE conditionals, loops, and branching (when applicable)
     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.
+    7. Never use branchOverrides or recordScenarios in newly generated code. Existing handlers must
+       set controlFlowMode: "legacy" explicitly while they are being migrated.
 
   Prefer explicit portable branching for step results:
     const result = await ctx.step("find", () => ctx.database.execute(...));
@@ -4979,7 +5108,7 @@ connect to the proxy's /realtime gateway. Never use this package on the server
 for server-side code.
 
 INSTALL
-  npm install @ductape/client
+  npm install @ductape/client@latest
 
 INITIALIZATION
   import { createClient } from '@ductape/client';
@@ -5142,7 +5271,7 @@ React hooks and context provider for Ductape. Wraps @ductape/client.
 Requires react >= 17.
 
 INSTALL
-  npm install @ductape/react
+  npm install @ductape/react@latest
 
 SETUP — wrap your app root with DuctapeProvider
   import { DuctapeProvider } from '@ductape/react';
@@ -5346,7 +5475,7 @@ Vue 3 composables and plugin for Ductape. Wraps @ductape/client.
 Requires vue >= 3.
 
 INSTALL
-  npm install @ductape/vue
+  npm install @ductape/vue@latest
 
 SETUP — install the plugin at app root
   // main.ts
@@ -5924,8 +6053,8 @@ const eventsTopicSetupHandler = async (args) => {
     return {
         content: [{ type: 'text', text: JSON.stringify({
                     ok: true,
-                    project_root: cliCwd(),
-                    path: join(cliCwd(), relativePath),
+                    project_root: cliCwd(args.project_dir),
+                    path: join(cliCwd(args.project_dir), relativePath),
                     relative_path: relativePath,
                     definition,
                     create_command: `ductape events topics create -f ${relativePath} --json`,
@@ -5946,12 +6075,37 @@ const eventsProjectValidationHandler = async (args) => {
             isError: true,
         };
     }
-    const result = runCli('events topics validate --dir ductape/events --json');
+    const result = runCli('events topics validate --dir ductape/events --json', args.project_dir);
     return {
         content: [{ type: 'text', text: result.output || '(no output)' }],
         ...(result.success ? {} : { isError: true }),
     };
 };
+const featuresProjectValidationHandler = async (args) => {
+    const result = runCli('features validate --json', args.project_dir);
+    return {
+        content: [{ type: 'text', text: result.output || '(no output)' }],
+        ...(result.success ? {} : { isError: true }),
+    };
+};
+const frontendAnalyticsProjectValidationHandler = async (args) => {
+    try {
+        const result = validateFrontendAnalyticsProject(args.project_dir);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            ...(result.valid ? {} : { isError: true }),
+        };
+    }
+    catch (error) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: error instanceof Error ? error.message : String(error),
+                }],
+            isError: true,
+        };
+    }
+};
 const cliInputSchema = z.object({
     command: z.string().describe('The ductape CLI command to run, without the leading "ductape" word. ' +
         'Examples: "products list", "products create --name \\"My Product\\" --tag my-product", ' +
@@ -5965,13 +6119,22 @@ const cliInputSchema = z.object({
         'no linked project required — the product tag is always an explicit argument). Quotas, ' +
         'fallbacks, jobs, and healthchecks use resources commands. App actions and auths are ' +
         'configured in the Workbench UI. Features have no CLI creation command: define them in ' +
-        'application code with features.define under ductape/features/. Persist them with ' +
+        'application code with features.define under ductape/features/. Always run "features validate" first; ' +
+        'it performs read-only AST conformance checks and "features sync" repeats the same fail-closed preflight. Persist them with ' +
         '"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. 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.'),
+    project_dir: z.string().optional().describe('Absolute path to the project this command should run against (e.g. "ductape/events" is ' +
+        'resolved relative to this directory, and product/project linking state is read from it). ' +
+        'The MCP server is a long-running process — its own working directory (or a static ' +
+        'DUCTAPE_PROJECT_DIR env var, if set) does NOT follow which project the current conversation ' +
+        'is actually working in. Pass this whenever the command is project-relative (events topics, ' +
+        'anything reading ductape/ files, link/unlink) and the session is working in a project other ' +
+        'than wherever the MCP server happened to start. Omit only for purely workspace-level commands ' +
+        '(e.g. "products list") where no project directory is relevant.'),
 });
 async function loadMcpSdk() {
     try {
@@ -6116,7 +6279,7 @@ async function main() {
         ],
     }));
     const cliHandler = async (args) => {
-        const cli = checkCli();
+        const cli = checkCli(args.project_dir);
         if (!cli.available) {
             return {
                 content: [{
@@ -6165,7 +6328,7 @@ async function main() {
             // The user may complete `ductape login` in another terminal while this MCP process remains
             // alive; caching "none" would otherwise make the MCP blind to the newly written session.
             if (authState === 'unknown' || authState === 'none') {
-                checkLoginState();
+                checkLoginState(args.project_dir);
             }
             if (authState === 'none') {
                 const wsFlag = process.env.DUCTAPE_WORKSPACE ? ` --workspace "${process.env.DUCTAPE_WORKSPACE}"` : '';
@@ -6193,10 +6356,10 @@ async function main() {
             }
             // Sync to the configured workspace once per process (best-effort)
             if (!workspaceSynced) {
-                syncWorkspace();
+                syncWorkspace(args.project_dir);
             }
         }
-        const result = runCli(args.command);
+        const result = runCli(args.command, args.project_dir);
         // Update cached state after auth commands
         if (firstWord === 'login' && result.success) {
             authState = 'ok';
@@ -6786,6 +6949,23 @@ async function main() {
             inputSchema: eventsProjectValidationInputSchema,
             annotations: readOnlyLocalAnnotations,
         }, eventsProjectValidationHandler);
+        server.registerTool('ductape_features_validate_project', {
+            title: 'Validate Ductape Feature Project',
+            description: 'Read-only AST validation of code-first Features under ductape/features/. Detects native branching, loops, ' +
+                'collection callbacks, host-bound time/random/environment access, and legacy recording options before sync. ' +
+                'A failed result means features sync must not be run.',
+            inputSchema: featuresProjectValidationInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, featuresProjectValidationHandler);
+        server.registerTool('ductape_frontend_analytics_validate_project', {
+            title: 'Validate Ductape Frontend Analytics',
+            description: 'Read-only audit of every frontend package using @ductape/react, @ductape/vue, or the browser client. ' +
+                'Requires an explicit enabled/deferred/prohibited decision per application and validates analytics identity, ' +
+                'logout, pageview, named-event, client-failure, and auto-capture privacy signals when enabled. ' +
+                'Returns actionable findings and never modifies source.',
+            inputSchema: frontendAnalyticsProjectValidationInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, frontendAnalyticsProjectValidationHandler);
         server.registerTool('ductape_function_setup', {
             title: 'Ductape Portable Function Setup',
             description: 'Read-only: generate (without applying) the mandatory secure local + remote runtime setup for application functions used by Features. ' +
@@ -6971,8 +7151,14 @@ async function main() {
                 '    can never be retrieved again via the Aura API — Ductape has no way to source it automatically.\n' +
                 '    Always ask the user for the instance password before calling import-persist-all for an\n' +
                 '    aura-instance entry; do not attempt the import without it, it will fail with a clear error\n' +
-                '    naming exactly this. The username is always "neo4j" for every Aura instance — never ask the\n' +
-                '    user for it, and never put it in masterPassword by mistake.\n' +
+                '    naming exactly this.\n' +
+                '    username defaults to "neo4j" if omitted, which is correct for most Aura instances — but this\n' +
+                '    is NOT a hard guarantee. At least one real instance has been confirmed to use a different\n' +
+                '    database username instead (its instance id, in the one case observed) and rejects "neo4j" as\n' +
+                '    unauthorized. If the import succeeds but connect later fails with a Neo4j\n' +
+                '    unauthorized/access-denied error despite a correct password, re-import with username set\n' +
+                '    explicitly (ask the user what database username the instance actually uses) rather than\n' +
+                '    assuming the password is wrong.\n' +
                 '    Step 1 — discover the instance:\n' +
                 '      ductape_cli("cloud resources list -f /tmp/aura-list.json --json")\n' +
                 '      File: {"cloud": "<aura-connection-tag>", "service": "aura-instance"}\n' +
@@ -6983,7 +7169,9 @@ async function main() {
                 '      explicitly wants different Aura instances per environment):\n' +
                 '        cloud (connection tag), service: "aura-instance", type: "graphs",\n' +
                 '        product, component (new or existing graph tag), env, resource (instance id/name from\n' +
-                '        Step 1), masterPassword (the instance password — ask the user, do not guess or omit).\n' +
+                '        Step 1), masterPassword (the instance password — ask the user, do not guess or omit),\n' +
+                '        username (optional — omit for the "neo4j" default; only set if the user tells you the\n' +
+                '        instance uses a different one, or if a prior attempt with "neo4j" failed to authenticate).\n' +
                 '      Example (two envs, same Aura instance):\n' +
                 '      [{"cloud":"aura-tag","service":"aura-instance","type":"graphs",\n' +
                 '        "product":"my-product","component":"commerce-network","env":"snd",\n' +
@@ -7027,6 +7215,8 @@ async function main() {
         server.tool('ductape_events_discover', eventsDiscoveryInputSchema.shape, eventsDiscoveryHandler);
         server.tool('ductape_events_topic_setup', eventsTopicSetupInputSchema.shape, readOnlyLocalAnnotations, eventsTopicSetupHandler);
         server.tool('ductape_events_validate_project', eventsProjectValidationInputSchema.shape, readOnlyLocalAnnotations, eventsProjectValidationHandler);
+        server.tool('ductape_features_validate_project', featuresProjectValidationInputSchema.shape, readOnlyLocalAnnotations, featuresProjectValidationHandler);
+        server.tool('ductape_frontend_analytics_validate_project', frontendAnalyticsProjectValidationInputSchema.shape, readOnlyLocalAnnotations, frontendAnalyticsProjectValidationHandler);
         server.tool('ductape_function_setup', portableFunctionSetupInputSchema.shape, portableFunctionSetupAnnotations, portableFunctionSetupHandler);
         server.tool('ductape_redis_setup', redisSetupInputSchema.shape, redisSetupHandler);
         server.tool('ductape_migration_plan', migrationInputSchema.shape, migrationHandler);

package/docs/TOOLS.md

@@ -74,6 +74,19 @@ manifest, envelope registry, or custom event registry.
 
 ---
 
+## Tool: `ductape_frontend_analytics_validate_project`
+
+Audits every deployable Ductape React, Vue, or browser-client application under an absolute project
+directory. Each application must have an explicit entry in `ductape/analytics/frontend.json` with
+status `enabled`, `deferred`, or `prohibited`. Deferred and prohibited choices require a rationale.
+
+Enabled applications are checked for Ductape analytics usage, router pageviews, named events,
+`identify(fullSessionToken)` after authenticated session creation/refresh, `clearSession()` on
+logout/account switching, sanitized client-failure telemetry, and reviewed auto-capture. The tool
+is read-only and never edits application source.
+
+---
+
 ## Tool: `ductape_function_setup`
 
 Produces the mandatory local registry and signed HTTPS exposure plan for portable application

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ductape/mcp",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "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-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 && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs && node scripts/check-runtime-input-recovery.mjs && node scripts/check-resilience-health-guidance.mjs",
+    "test": "npm run build && node scripts/check-cli-command-security.mjs && node scripts/check-doctor-e2e.mjs && node scripts/check-frontend-analytics-guidance.mjs && node scripts/check-frontend-analytics-validator.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 && node scripts/check-database-action-contract-guidance.mjs && node scripts/check-runtime-sync-guidance.mjs && node scripts/check-runtime-input-recovery.mjs && node scripts/check-resilience-health-guidance.mjs && node scripts/check-session-propagation-guidance.mjs",
     "start": "node dist/index.js",
     "dev": "tsx src/index.ts"
   },