webmcp-cli 1.2.2 → 1.2.3

package/dist/rules/accessibility/AXE-005.d.ts

@@ -0,0 +1,9 @@
+/**
+ * AXE-005: Focus Management
+ *
+ * Checks that tool activation properly manages keyboard focus.
+ * Execute functions that modify the DOM should move focus to
+ * the changed element or a relevant target.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const AXE_005: Rule;

package/dist/rules/accessibility/AXE-005.js

@@ -0,0 +1,89 @@
+/**
+ * AXE-005: Focus Management
+ *
+ * Checks that tool activation properly manages keyboard focus.
+ * Execute functions that modify the DOM should move focus to
+ * the changed element or a relevant target.
+ */
+import { createRuleResult } from '../runner.js';
+const FOCUS_PATTERNS = [
+    /\.focus\s*\(\s*\)/,
+    /\.scrollIntoView\s*\(/,
+    /aria-live/,
+    /role\s*=\s*["']alert["']/,
+    /\.setAttribute\s*\(\s*['"]tabindex["']/,
+    /tabIndex/,
+];
+const DOM_MUTATION_PATTERNS = [
+    /\.innerHTML\s*=/,
+    /\.appendChild\s*\(/,
+    /\.insertBefore\s*\(/,
+    /\.replaceChild\s*\(/,
+    /\.removeChild\s*\(/,
+    /\.replaceWith\s*\(/,
+    /\.insertAdjacentHTML\s*\(/,
+    /\.insertAdjacentElement\s*\(/,
+    /\.after\s*\(/,
+    /\.before\s*\(/,
+    /\.prepend\s*\(/,
+    /\.append\s*\(/,
+];
+export const AXE_005 = {
+    id: 'AXE-005',
+    category: 'accessibility',
+    name: 'Focus Management',
+    description: 'Tool activation should properly manage keyboard focus after DOM changes',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('AXE-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithExecute = tools.filter((t) => t.executeSource && t.executeSource.length > 0);
+        if (toolsWithExecute.length === 0) {
+            return createRuleResult('AXE-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'No execute functions available for analysis',
+            });
+        }
+        const violations = [];
+        for (const tool of toolsWithExecute) {
+            const src = tool.executeSource ?? '';
+            const mutatesDOM = DOM_MUTATION_PATTERNS.some((p) => p.test(src));
+            if (!mutatesDOM)
+                continue;
+            const managesFocus = FOCUS_PATTERNS.some((p) => p.test(src));
+            if (!managesFocus) {
+                violations.push(tool.name);
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('AXE-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'Tools that modify DOM properly manage focus',
+            });
+        }
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('AXE-005', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) modify DOM without managing focus`,
+            details: violations.map((name) => `Tool "${name}" modifies the DOM but doesn't manage keyboard focus`),
+            suggestions: [
+                'Call .focus() on the new or changed element after DOM updates',
+                'Use aria-live regions to announce changes to screen readers',
+                'Set tabindex="-1" on non-interactive elements before calling .focus()',
+            ],
+            affectedTools: violations,
+        });
+    },
+};
+//# sourceMappingURL=AXE-005.js.map

package/dist/rules/accessibility/AXE-005.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AXE-005.js","sourceRoot":"","sources":["../../../src/rules/accessibility/AXE-005.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-004.d.ts

@@ -0,0 +1,9 @@
+/**
+ * BP-004: Error Recovery Info
+ *
+ * Checks that error responses from execute functions include
+ * enough information for an agent to understand what went wrong
+ * and potentially retry the operation.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_004: Rule;

package/dist/rules/best-practices/BP-004.js

@@ -0,0 +1,96 @@
+/**
+ * BP-004: Error Recovery Info
+ *
+ * Checks that error responses from execute functions include
+ * enough information for an agent to understand what went wrong
+ * and potentially retry the operation.
+ */
+import { createRuleResult } from '../runner.js';
+const ERROR_HANDLING_PATTERNS = [
+    /catch\s*\(/,
+    /\.catch\s*\(/,
+    /try\s*\{/,
+];
+const GOOD_ERROR_PATTERNS = [
+    /message\s*:/,
+    /error\s*:/,
+    /reason\s*:/,
+    /code\s*:/,
+    /statusCode\s*:/,
+    /retryable\s*:/,
+    /retry/i,
+    /suggestion\s*:/,
+    /hint\s*:/,
+];
+const BARE_THROW_PATTERN = /throw\s+(?:new\s+Error\s*\(\s*\)|['"`]['"`]|e\b|err\b)/;
+export const BP_004 = {
+    id: 'BP-004',
+    category: 'best-practices',
+    name: 'Error Recovery Info',
+    description: 'Error responses should include enough information for agents to retry',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-004', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithExecute = tools.filter((t) => t.executeSource && t.executeSource.length > 0);
+        if (toolsWithExecute.length === 0) {
+            return createRuleResult('BP-004', 5, {
+                passed: true,
+                score: 5,
+                message: 'No execute functions available for analysis',
+            });
+        }
+        const violations = [];
+        const noErrorHandling = [];
+        for (const tool of toolsWithExecute) {
+            const src = tool.executeSource ?? '';
+            const hasErrorHandling = ERROR_HANDLING_PATTERNS.some((p) => p.test(src));
+            if (!hasErrorHandling) {
+                noErrorHandling.push(tool.name);
+                continue;
+            }
+            const hasGoodErrorInfo = GOOD_ERROR_PATTERNS.some((p) => p.test(src));
+            const hasBareThrow = BARE_THROW_PATTERN.test(src);
+            if (hasBareThrow && !hasGoodErrorInfo) {
+                violations.push(tool.name);
+            }
+        }
+        const allIssues = [...violations, ...noErrorHandling];
+        if (allIssues.length === 0) {
+            return createRuleResult('BP-004', 5, {
+                passed: true,
+                score: 5,
+                message: 'Execute functions provide good error recovery information',
+            });
+        }
+        const penalty = Math.min(allIssues.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        const details = [];
+        for (const name of noErrorHandling) {
+            details.push(`Tool "${name}" has no error handling (try/catch)`);
+        }
+        for (const name of violations) {
+            details.push(`Tool "${name}" has error handling but throws bare errors without context`);
+        }
+        return createRuleResult('BP-004', 5, {
+            passed: false,
+            score,
+            message: `${allIssues.length} tool(s) have poor error recovery information`,
+            details,
+            suggestions: [
+                'Include descriptive error messages with context about what failed',
+                'Add a "retryable" flag to indicate if the agent can retry the operation',
+                'Return structured error objects: { error: true, message: "...", code: "..." }',
+            ],
+            affectedTools: allIssues,
+        });
+    },
+};
+//# sourceMappingURL=BP-004.js.map

package/dist/rules/best-practices/BP-004.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-004.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-004.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-005.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BP-005: UI Sync After Execution
+ *
+ * Checks that execute functions update the DOM/UI after state changes,
+ * ensuring the page reflects the result of tool execution.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_005: Rule;

package/dist/rules/best-practices/BP-005.js

@@ -0,0 +1,94 @@
+/**
+ * BP-005: UI Sync After Execution
+ *
+ * Checks that execute functions update the DOM/UI after state changes,
+ * ensuring the page reflects the result of tool execution.
+ */
+import { createRuleResult } from '../runner.js';
+const STATE_CHANGE_PATTERNS = [
+    /fetch\s*\(.*method\s*:\s*['"](?:POST|PUT|DELETE|PATCH)/i,
+    /localStorage\.setItem/,
+    /sessionStorage\.setItem/,
+    /\.save\s*\(/,
+    /\.update\s*\(/,
+    /\.create\s*\(/,
+    /\.submit\s*\(/,
+];
+const UI_UPDATE_PATTERNS = [
+    /\.innerHTML\s*=/,
+    /\.textContent\s*=/,
+    /\.innerText\s*=/,
+    /\.classList\./,
+    /\.style\./,
+    /\.setAttribute\s*\(/,
+    /\.appendChild\s*\(/,
+    /\.replaceChild\s*\(/,
+    /\.removeChild\s*\(/,
+    /\.insertBefore\s*\(/,
+    /setState\s*\(/,
+    /\.render\s*\(/,
+    /\.forceUpdate\s*\(/,
+    /dispatchEvent\s*\(/,
+    /\.value\s*=/,
+    /document\.querySelector/,
+    /\.replaceWith\s*\(/,
+];
+export const BP_005 = {
+    id: 'BP-005',
+    category: 'best-practices',
+    name: 'UI Sync After Execution',
+    description: 'Execute functions should update the DOM/UI after state changes',
+    severity: 'warning',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithExecute = tools.filter((t) => t.executeSource && t.executeSource.length > 0);
+        if (toolsWithExecute.length === 0) {
+            return createRuleResult('BP-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'No execute functions available for analysis',
+            });
+        }
+        const violations = [];
+        for (const tool of toolsWithExecute) {
+            const src = tool.executeSource ?? '';
+            const hasStateChange = STATE_CHANGE_PATTERNS.some((p) => p.test(src));
+            if (!hasStateChange)
+                continue;
+            const hasUIUpdate = UI_UPDATE_PATTERNS.some((p) => p.test(src));
+            if (!hasUIUpdate) {
+                violations.push(tool.name);
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('BP-005', 5, {
+                passed: true,
+                score: 5,
+                message: 'Execute functions update UI after state changes',
+            });
+        }
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-005', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) change state without updating UI`,
+            details: violations.map((name) => `Tool "${name}" modifies state (POST/save/update) but has no visible DOM update`),
+            suggestions: [
+                'Update the DOM to reflect state changes after execute completes',
+                'Use dispatchEvent to notify UI components of data changes',
+                'Ensure the user sees confirmation of the tool\'s action in the page',
+            ],
+            affectedTools: violations,
+        });
+    },
+};
+//# sourceMappingURL=BP-005.js.map

package/dist/rules/best-practices/BP-005.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-005.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-005.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-006.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BP-006: Returns After UI Update
+ *
+ * Checks that execute functions return after the UI has been updated,
+ * not before. The return value should reflect the final state.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_006: Rule;

package/dist/rules/best-practices/BP-006.js

@@ -0,0 +1,80 @@
+/**
+ * BP-006: Returns After UI Update
+ *
+ * Checks that execute functions return after the UI has been updated,
+ * not before. The return value should reflect the final state.
+ */
+import { createRuleResult } from '../runner.js';
+const ASYNC_AWAIT_PATTERN = /\basync\b/;
+const EARLY_RETURN_PATTERN = /return\s+[^;]*;\s*(?:.*(?:fetch|\.then|await)\s*\()/s;
+const FIRE_AND_FORGET_PATTERN = /(?:fetch|\.send|\.post)\s*\([^)]*\)\s*;?\s*\n\s*return\b/;
+export const BP_006 = {
+    id: 'BP-006',
+    category: 'best-practices',
+    name: 'Returns After UI Update',
+    description: 'Execute functions should return after the UI has been updated, not before',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-006', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithExecute = tools.filter((t) => t.executeSource && t.executeSource.length > 0);
+        if (toolsWithExecute.length === 0) {
+            return createRuleResult('BP-006', 5, {
+                passed: true,
+                score: 5,
+                message: 'No execute functions available for analysis',
+            });
+        }
+        const violations = [];
+        for (const tool of toolsWithExecute) {
+            const src = tool.executeSource ?? '';
+            // Check for fire-and-forget patterns (fetch then immediate return)
+            if (FIRE_AND_FORGET_PATTERN.test(src)) {
+                violations.push({
+                    name: tool.name,
+                    issue: 'Returns immediately after firing async request (fire-and-forget)',
+                });
+                continue;
+            }
+            // If async function, check that it awaits before returning
+            if (ASYNC_AWAIT_PATTERN.test(src)) {
+                // Check for patterns where return comes before async work
+                if (EARLY_RETURN_PATTERN.test(src)) {
+                    violations.push({
+                        name: tool.name,
+                        issue: 'Returns before async operations complete',
+                    });
+                }
+            }
+        }
+        if (violations.length === 0) {
+            return createRuleResult('BP-006', 5, {
+                passed: true,
+                score: 5,
+                message: 'Execute functions return after UI updates complete',
+            });
+        }
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-006', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) may return before UI is updated`,
+            details: violations.map((v) => `Tool "${v.name}": ${v.issue}`),
+            suggestions: [
+                'Use await to ensure async operations complete before returning',
+                'Return after the DOM/UI has been updated to reflect the new state',
+                'Avoid fire-and-forget patterns — agents rely on return values for next steps',
+            ],
+            affectedTools: violations.map((v) => v.name),
+        });
+    },
+};
+//# sourceMappingURL=BP-006.js.map

package/dist/rules/best-practices/BP-006.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-006.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-006.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-007.d.ts

@@ -0,0 +1,8 @@
+/**
+ * BP-007: Graceful Rate Limit
+ *
+ * Checks that tools handle rate limiting with meaningful error messages
+ * rather than generic failures.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_007: Rule;

package/dist/rules/best-practices/BP-007.js

@@ -0,0 +1,92 @@
+/**
+ * BP-007: Graceful Rate Limit
+ *
+ * Checks that tools handle rate limiting with meaningful error messages
+ * rather than generic failures.
+ */
+import { createRuleResult } from '../runner.js';
+const RATE_LIMIT_STATUS_PATTERNS = [
+    /429/,
+    /rate.?limit/i,
+    /too.?many.?requests/i,
+    /throttl/i,
+];
+const GRACEFUL_HANDLING_PATTERNS = [
+    /retry.?after/i,
+    /retryAfter/i,
+    /wait/i,
+    /backoff/i,
+    /cooldown/i,
+    /rate.?limit.*message/i,
+    /too.?many.*try.?again/i,
+];
+export const BP_007 = {
+    id: 'BP-007',
+    category: 'best-practices',
+    name: 'Graceful Rate Limit',
+    description: 'Tools should handle rate limiting with meaningful errors and retry guidance',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-007', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        const toolsWithExecute = tools.filter((t) => t.executeSource && t.executeSource.length > 0);
+        if (toolsWithExecute.length === 0) {
+            return createRuleResult('BP-007', 5, {
+                passed: true,
+                score: 5,
+                message: 'No execute functions available for analysis',
+            });
+        }
+        const violations = [];
+        let toolsWithFetch = 0;
+        for (const tool of toolsWithExecute) {
+            const src = tool.executeSource ?? '';
+            // Only relevant for tools that make network requests
+            const makesFetchCalls = /fetch\s*\(|XMLHttpRequest|\.ajax\s*\(/.test(src);
+            if (!makesFetchCalls)
+                continue;
+            toolsWithFetch++;
+            const checksRateLimit = RATE_LIMIT_STATUS_PATTERNS.some((p) => p.test(src));
+            const handlesGracefully = GRACEFUL_HANDLING_PATTERNS.some((p) => p.test(src));
+            if (!checksRateLimit && !handlesGracefully) {
+                violations.push(tool.name);
+            }
+        }
+        if (toolsWithFetch === 0) {
+            return createRuleResult('BP-007', 5, {
+                passed: true,
+                score: 5,
+                message: 'No network-calling tools detected (rule not applicable)',
+            });
+        }
+        if (violations.length === 0) {
+            return createRuleResult('BP-007', 5, {
+                passed: true,
+                score: 5,
+                message: 'Network-calling tools handle rate limiting gracefully',
+            });
+        }
+        const penalty = Math.min(violations.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-007', 5, {
+            passed: false,
+            score,
+            message: `${violations.length} tool(s) don't handle rate limiting gracefully`,
+            details: violations.map((name) => `Tool "${name}" makes network requests but doesn't handle 429/rate-limit responses`),
+            suggestions: [
+                'Check for HTTP 429 responses and provide meaningful error messages',
+                'Include retry-after timing in error responses when rate-limited',
+                'Return { error: true, retryable: true, retryAfter: seconds } for rate limits',
+            ],
+            affectedTools: violations,
+        });
+    },
+};
+//# sourceMappingURL=BP-007.js.map

package/dist/rules/best-practices/BP-007.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-007.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-007.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-008.d.ts

@@ -0,0 +1,12 @@
+/**
+ * BP-008: State-Appropriate Tools
+ *
+ * Checks that tools are only registered when they make sense for
+ * the current UI state (e.g., a "submit order" tool shouldn't be
+ * registered before the cart has items).
+ *
+ * This is a heuristic check — looks for tools with state-dependent names
+ * that are registered at page load rather than dynamically.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_008: Rule;

package/dist/rules/best-practices/BP-008.js

@@ -0,0 +1,86 @@
+/**
+ * BP-008: State-Appropriate Tools
+ *
+ * Checks that tools are only registered when they make sense for
+ * the current UI state (e.g., a "submit order" tool shouldn't be
+ * registered before the cart has items).
+ *
+ * This is a heuristic check — looks for tools with state-dependent names
+ * that are registered at page load rather than dynamically.
+ */
+import { createRuleResult } from '../runner.js';
+const STATE_DEPENDENT_KEYWORDS = [
+    'submit',
+    'confirm',
+    'checkout',
+    'finalize',
+    'complete',
+    'next step',
+    'proceed',
+    'approve',
+    'publish',
+    'deploy',
+];
+export const BP_008 = {
+    id: 'BP-008',
+    category: 'best-practices',
+    name: 'State-Appropriate Tools',
+    description: 'Tools should be registered only when they make sense for the current UI state',
+    severity: 'info',
+    maxScore: 5,
+    async check(context) {
+        const tools = context.tools;
+        if (tools.length === 0) {
+            return createRuleResult('BP-008', 5, {
+                passed: true,
+                score: 5,
+                message: 'No tools detected (rule not applicable)',
+            });
+        }
+        // Only check imperative tools (declarative forms are always in the DOM)
+        const imperativeTools = tools.filter((t) => t.source === 'imperative');
+        if (imperativeTools.length === 0) {
+            return createRuleResult('BP-008', 5, {
+                passed: true,
+                score: 5,
+                message: 'No imperative tools detected (rule not applicable)',
+            });
+        }
+        const warnings = [];
+        for (const tool of imperativeTools) {
+            const nameAndDesc = `${tool.name} ${tool.description}`.toLowerCase();
+            const isStateDep = STATE_DEPENDENT_KEYWORDS.some((kw) => nameAndDesc.includes(kw));
+            if (!isStateDep)
+                continue;
+            // Check if the tool's execute source has state guards
+            const src = tool.executeSource ?? '';
+            const hasStateGuard = /if\s*\(/.test(src) &&
+                (/disabled|enabled|ready|valid|empty|length\s*[=><!]|\.items|\.count/.test(src));
+            if (!hasStateGuard) {
+                warnings.push(tool.name);
+            }
+        }
+        if (warnings.length === 0) {
+            return createRuleResult('BP-008', 5, {
+                passed: true,
+                score: 5,
+                message: 'State-dependent tools have appropriate guards',
+            });
+        }
+        const penalty = Math.min(warnings.length, 5);
+        const score = Math.max(0, 5 - penalty);
+        return createRuleResult('BP-008', 5, {
+            passed: false,
+            score,
+            message: `${warnings.length} tool(s) may be registered before the UI state supports them`,
+            details: warnings.map((name) => `Tool "${name}" has a state-dependent name but no visible state guard in execute`),
+            suggestions: [
+                'Register tools dynamically when their preconditions are met',
+                'Add state validation at the start of execute functions',
+                'Use navigator.modelContext.unregisterTool() when a tool becomes invalid',
+            ],
+            affectedTools: warnings,
+        });
+    },
+};
+//# sourceMappingURL=BP-008.js.map

package/dist/rules/best-practices/BP-008.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BP-008.js","sourceRoot":"","sources":["../../../src/rules/best-practices/BP-008.ts"],"names":[],"mappings":"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"}

package/dist/rules/best-practices/BP-009.d.ts

@@ -0,0 +1,9 @@
+/**
+ * BP-009: No Orphaned Tools
+ *
+ * Checks that all registered tools are reachable through some UI path.
+ * An orphaned tool is one that exists in the MCP registry but has no
+ * corresponding UI element on the page.
+ */
+import type { Rule } from '../../core/types/rule.js';
+export declare const BP_009: Rule;