@ductape/mcp 0.3.3 → 0.3.5

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,29 @@
+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>;
+        evidence: Record<string, string[]>;
+        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,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;QACnC,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,CA2HnC"}

package/dist/frontend-analytics-validator.js

@@ -0,0 +1,198 @@
+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(projectRoot, roots) {
+    const chunks = [];
+    for (const sourceRoot of roots)
+        walk(sourceRoot, (file) => {
+            if (!SOURCE_EXTENSIONS.has(path.extname(file)))
+                return;
+            const stats = fs.statSync(file);
+            if (stats.size > MAX_SOURCE_BYTES)
+                return;
+            chunks.push({ file: normalizedRelative(projectRoot, file), source: fs.readFileSync(file, 'utf8') });
+        });
+    return chunks;
+}
+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 packages = new Map();
+    for (const manifestFile of packageFiles) {
+        try {
+            const manifest = readJson(manifestFile);
+            if (typeof manifest.name === 'string')
+                packages.set(manifest.name, { root: path.dirname(manifestFile), manifest });
+        }
+        catch { /* Invalid manifests are ignored as application candidates below. */ }
+    }
+    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 sourceRoots = [applicationRoot];
+        const visited = new Set([applicationRoot]);
+        for (let index = 0; index < sourceRoots.length; index += 1) {
+            const currentRoot = sourceRoots[index];
+            const current = index === 0
+                ? manifest
+                : [...packages.values()].find((entry) => entry.root === currentRoot)?.manifest;
+            if (!current)
+                continue;
+            const dependencies = { ...(current.dependencies ?? {}), ...(current.devDependencies ?? {}) };
+            const directSource = scanSource(root, [currentRoot]).map((item) => item.source).join('\n');
+            for (const dependencyName of Object.keys(dependencies)) {
+                const dependency = packages.get(dependencyName);
+                if (!dependency || visited.has(dependency.root))
+                    continue;
+                const escaped = dependencyName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+                if (!new RegExp(`['\"]${escaped}(?:/[^'\"]*)?['\"]`).test(directSource))
+                    continue;
+                visited.add(dependency.root);
+                sourceRoots.push(dependency.root);
+            }
+        }
+        const files = scanSource(root, sourceRoots);
+        const decision = decisions.applications?.[applicationPath];
+        const patterns = {
+            provider: /DuctapeProvider/, authenticatedSessions: /useSession|\.sessions\.|sessionToken|refreshToken/,
+            analytics: /useAnalytics|\.analytics\./, identify: /(?:analytics\.)?identify\s*\(/,
+            clearSession: /(?:analytics\.)?clearSession\s*\(/, pageview: /(?:analytics\.)?pageview\s*\(/,
+            namedEvents: /(?:analytics\.)?track\s*\(/, autoCapture: /enableAutoCapture\s*\(/,
+            clientFailure: /client[_\-. ]error|frontend[_\-. ]error|error_boundary|unhandledrejection/i,
+        };
+        const evidence = Object.fromEntries(Object.entries(patterns).map(([name, pattern]) => [name, files.filter((item) => pattern.test(item.source)).map((item) => item.file)]));
+        const signals = Object.fromEntries(Object.entries(evidence).map(([name, matches]) => [name, matches.length > 0]));
+        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, evidence, 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)
@@ -1317,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))
@@ -1450,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',
@@ -1703,6 +1720,12 @@ const eventsProjectValidationInputSchema = z.object({
 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 sessionProjectValidationInputSchema = z.object({
+    project_dir: z.string().describe('Absolute path to the project. Performs a read-only SDK session-propagation audit.'),
+});
 const readOnlyLocalAnnotations = {
     readOnlyHint: true,
     destructiveHint: false,
@@ -2328,13 +2351,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" }).
 
@@ -2359,8 +2382,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
@@ -3545,6 +3574,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
@@ -5067,7 +5111,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';
@@ -5230,7 +5274,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';
@@ -5434,7 +5478,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
@@ -6047,6 +6091,28 @@ const featuresProjectValidationHandler = async (args) => {
         ...(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 sessionProjectValidationHandler = async (args) => {
+    const result = runCli('sessions validate --json', args.project_dir);
+    return { content: [{ type: 'text', text: result.output || '(no output)' }], ...(result.success ? {} : { 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", ' +
@@ -6898,6 +6964,21 @@ async function main() {
             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_sessions_validate_project', {
+            title: 'Validate Ductape Session Propagation',
+            description: 'Read-only project-wide audit. Every supported SDK call must explicitly pass a session, inherit it from Feature context, or carry a reasoned delegated/system marker.',
+            inputSchema: sessionProjectValidationInputSchema,
+            annotations: readOnlyLocalAnnotations,
+        }, sessionProjectValidationHandler);
         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. ' +
@@ -7148,6 +7229,8 @@ async function main() {
         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_sessions_validate_project', sessionProjectValidationInputSchema.shape, readOnlyLocalAnnotations, sessionProjectValidationHandler);
         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.3",
+  "version": "0.3.5",
   "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"
   },