webmcp-cli 1.0.0 → 1.2.1

package/dist/core/types/rule.d.ts

@@ -0,0 +1,190 @@
+/**
+ * Rule Types
+ */
+import type { Page } from 'playwright';
+import type { DetectedTool, UnregisteredForm } from './tool.js';
+import type { PageInfo } from './audit.js';
+/**
+ * Rule categories
+ */
+export type RuleCategory = 'implementation' | 'description' | 'schema' | 'security' | 'best-practices' | 'coverage';
+/**
+ * Rule severity levels
+ */
+export type RuleSeverity = 'critical' | 'warning' | 'info';
+/**
+ * Context provided to rules for evaluation
+ */
+export interface RuleContext {
+    /**
+     * The URL being audited
+     */
+    url: string;
+    /**
+     * All detected tools
+     */
+    tools: DetectedTool[];
+    /**
+     * All unregistered forms
+     */
+    opportunities: UnregisteredForm[];
+    /**
+     * All pages crawled
+     */
+    pages: PageInfo[];
+    /**
+     * The Playwright page object (for dynamic checks)
+     */
+    page?: Page;
+    /**
+     * Raw HTML content of the current page
+     */
+    html?: string;
+    /**
+     * Whether WebMCP API exists
+     */
+    hasWebMCP: boolean;
+    /**
+     * JavaScript files/snippets for analysis
+     */
+    scripts?: ScriptInfo[];
+}
+/**
+ * Information about a JavaScript file or snippet
+ */
+export interface ScriptInfo {
+    /**
+     * URL or identifier of the script
+     */
+    src: string;
+    /**
+     * Script content
+     */
+    content: string;
+    /**
+     * Whether this is an inline script
+     */
+    inline: boolean;
+}
+/**
+ * Result of evaluating a single rule
+ */
+export interface RuleResult {
+    /**
+     * Rule ID
+     */
+    ruleId: string;
+    /**
+     * Whether the rule passed
+     */
+    passed: boolean;
+    /**
+     * Score achieved (0 to rule's maxScore)
+     */
+    score: number;
+    /**
+     * Maximum possible score for this rule
+     */
+    maxScore: number;
+    /**
+     * Human-readable message
+     */
+    message: string;
+    /**
+     * Additional details
+     */
+    details?: string[];
+    /**
+     * Suggestions for fixing issues
+     */
+    suggestions?: string[];
+    /**
+     * Tools that triggered this rule
+     */
+    affectedTools?: string[];
+    /**
+     * Pages where issues were found
+     */
+    affectedPages?: string[];
+}
+/**
+ * A finding (issue) from the audit
+ */
+export interface Finding {
+    /**
+     * Rule ID that generated this finding
+     */
+    ruleId: string;
+    /**
+     * Severity level
+     */
+    severity: RuleSeverity;
+    /**
+     * Short message
+     */
+    message: string;
+    /**
+     * Tool name if applicable
+     */
+    tool?: string;
+    /**
+     * Page URL if applicable
+     */
+    page?: string;
+    /**
+     * Suggested fix
+     */
+    fix?: string;
+    /**
+     * Score impact (points deducted)
+     */
+    scoreImpact: number;
+}
+/**
+ * Rule definition
+ */
+export interface Rule {
+    /**
+     * Unique rule ID (e.g., "IMP-001")
+     */
+    id: string;
+    /**
+     * Rule category
+     */
+    category: RuleCategory;
+    /**
+     * Short name
+     */
+    name: string;
+    /**
+     * Detailed description of what the rule checks
+     */
+    description: string;
+    /**
+     * Severity level
+     */
+    severity: RuleSeverity;
+    /**
+     * Maximum points for this rule
+     */
+    maxScore: number;
+    /**
+     * Evaluate the rule against the given context
+     */
+    check(context: RuleContext): Promise<RuleResult>;
+}
+/**
+ * Rule registry entry
+ */
+export interface RuleRegistryEntry {
+    rule: Rule;
+    enabled: boolean;
+}
+/**
+ * Score weights by category
+ */
+export declare const CATEGORY_WEIGHTS: Record<RuleCategory, number>;
+/**
+ * Category display names
+ */
+export declare const CATEGORY_NAMES: Record<RuleCategory, string>;

package/dist/core/types/rule.js

@@ -0,0 +1,26 @@
+/**
+ * Rule Types
+ */
+/**
+ * Score weights by category
+ */
+export const CATEGORY_WEIGHTS = {
+    implementation: 25,
+    description: 15,
+    schema: 20,
+    security: 25,
+    'best-practices': 10,
+    coverage: 5,
+};
+/**
+ * Category display names
+ */
+export const CATEGORY_NAMES = {
+    implementation: 'Implementation',
+    description: 'Description Quality',
+    schema: 'Schema Validation',
+    security: 'Security',
+    'best-practices': 'Best Practices',
+    coverage: 'Coverage',
+};
+//# sourceMappingURL=rule.js.map

package/dist/core/types/rule.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rule.js","sourceRoot":"","sources":["../../../src/core/types/rule.ts"],"names":[],"mappings":"AAAA;;GAEG;AAiOH;;GAEG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAiC;IAC5D,cAAc,EAAE,EAAE;IAClB,WAAW,EAAE,EAAE;IACf,MAAM,EAAE,EAAE;IACV,QAAQ,EAAE,EAAE;IACZ,gBAAgB,EAAE,EAAE;IACpB,QAAQ,EAAE,CAAC;CACZ,CAAC;AAEF;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAiC;IAC1D,cAAc,EAAE,gBAAgB;IAChC,WAAW,EAAE,qBAAqB;IAClC,MAAM,EAAE,mBAAmB;IAC3B,QAAQ,EAAE,UAAU;IACpB,gBAAgB,EAAE,gBAAgB;IAClC,QAAQ,EAAE,UAAU;CACrB,CAAC"}

package/dist/core/types/tool.d.ts

@@ -0,0 +1,312 @@
+/**
+ * WebMCP Tool Types
+ * Based on the Web Model Context Protocol specification
+ */
+/**
+ * JSON Schema property definition (simplified for tool schemas)
+ */
+export interface JsonSchemaProperty {
+    type?: string | string[];
+    description?: string;
+    enum?: unknown[];
+    const?: unknown;
+    default?: unknown;
+    format?: string;
+    minimum?: number;
+    maximum?: number;
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    items?: JsonSchemaProperty;
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean | JsonSchemaProperty;
+    oneOf?: JsonSchemaProperty[];
+    anyOf?: JsonSchemaProperty[];
+    allOf?: JsonSchemaProperty[];
+    [key: string]: unknown;
+}
+/**
+ * Tool annotations that provide hints about the tool's behavior
+ */
+export interface ToolAnnotations {
+    /**
+     * If true, the tool only reads data and has no side effects
+     */
+    readOnlyHint?: boolean;
+    /**
+     * If true, the tool may have irreversible side effects (delete, purchase, etc.)
+     */
+    destructiveHint?: boolean;
+    /**
+     * If true, the tool may take a long time to complete
+     */
+    longRunningHint?: boolean;
+    /**
+     * If true, the tool may require human confirmation before executing
+     */
+    requiresConfirmation?: boolean;
+    /**
+     * Human-readable title for the tool
+     */
+    title?: string;
+    /**
+     * Additional custom annotations
+     */
+    [key: string]: unknown;
+}
+/**
+ * Input schema for a WebMCP tool (JSON Schema format)
+ */
+export interface ToolInputSchema {
+    type: 'object';
+    properties?: Record<string, JsonSchemaProperty>;
+    required?: string[];
+    additionalProperties?: boolean;
+    [key: string]: unknown;
+}
+/**
+ * A WebMCP tool definition as captured from the page
+ */
+export interface CapturedTool {
+    /**
+     * Unique name for the tool (snake_case recommended)
+     */
+    name: string;
+    /**
+     * Human-readable description of what the tool does
+     */
+    description: string;
+    /**
+     * JSON Schema defining the tool's input parameters
+     */
+    inputSchema?: ToolInputSchema;
+    /**
+     * Annotations providing hints about the tool's behavior
+     */
+    annotations?: ToolAnnotations;
+    /**
+     * Whether the tool has an execute function defined
+     */
+    hasExecute: boolean;
+    /**
+     * Source code of the execute function (if available)
+     */
+    executeSource: string | null;
+    /**
+     * Timestamp when the tool was registered
+     */
+    registeredAt: number;
+    /**
+     * Method used to register the tool
+     */
+    registrationMethod: 'registerTool' | 'provideContext';
+    /**
+     * URL of the page where the tool was registered
+     */
+    pageUrl?: string;
+}
+/**
+ * A declarative tool detected from HTML form attributes
+ */
+export interface DeclarativeTool {
+    /**
+     * Tool name from the toolname attribute
+     */
+    toolname: string;
+    /**
+     * Tool description from the tooldescription attribute
+     */
+    tooldescription: string;
+    /**
+     * Whether the form has the toolautosubmit attribute
+     */
+    autosubmit: boolean;
+    /**
+     * Form action URL
+     */
+    formAction: string;
+    /**
+     * Form method (GET, POST, etc.)
+     */
+    formMethod: string;
+    /**
+     * Parameters detected from form inputs
+     */
+    parameters: DeclarativeToolParameter[];
+    /**
+     * Outer HTML of the form element (truncated)
+     */
+    formElement: string;
+    /**
+     * URL of the page where the form was found
+     */
+    pageUrl?: string;
+}
+/**
+ * A parameter detected from a form input element
+ */
+export interface DeclarativeToolParameter {
+    /**
+     * Parameter name from the input name attribute
+     */
+    name: string;
+    /**
+     * Human-friendly title from toolparamtitle attribute
+     */
+    toolparamtitle: string | null;
+    /**
+     * Description from toolparamdescription attribute
+     */
+    toolparamdescription: string | null;
+    /**
+     * JSON Schema type inferred from input type
+     */
+    type: 'string' | 'number' | 'boolean' | 'array' | 'object';
+    /**
+     * Whether the input has the required attribute
+     */
+    required: boolean;
+    /**
+     * Original HTML input type
+     */
+    inputType: string;
+    /**
+     * Options for select/radio inputs
+     */
+    options: {
+        value: string;
+        text: string;
+        selected: boolean;
+    }[] | null;
+    /**
+     * Constraints from HTML attributes
+     */
+    constraints: {
+        min?: string | null;
+        max?: string | null;
+        minlength?: string | null;
+        maxlength?: string | null;
+        pattern?: string | null;
+        step?: string | null;
+    };
+    /**
+     * Text from the associated label element
+     */
+    labelText: string | null;
+    /**
+     * Text from aria-description attribute
+     */
+    ariaDescription: string | null;
+}
+/**
+ * A form detected without WebMCP attributes (opportunity for improvement)
+ */
+export interface UnregisteredForm {
+    /**
+     * Index of the form on the page
+     */
+    index: number;
+    /**
+     * Context clues for generating tool suggestions
+     */
+    contextClues: {
+        formId: string | null;
+        formAction: string | null;
+        formMethod: string;
+        formClass: string | null;
+        submitText: string | null;
+        nearestHeading: string | null;
+        pageTitle: string;
+        ariaLabel: string | null;
+        fieldNames: string[];
+        fieldTypes: string[];
+        hasPasswordField: boolean;
+        hasEmailField: boolean;
+        hasPaymentFields: boolean;
+        fieldCount: number;
+    };
+    /**
+     * Estimated sensitivity level
+     */
+    sensitivity: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Estimated value for AI agent interaction
+     */
+    agenticValue: 'low' | 'medium' | 'high' | 'critical';
+    /**
+     * Number of fields in the form
+     */
+    fieldCount: number;
+    /**
+     * Outer HTML of the form (truncated)
+     */
+    formOuterHTML: string;
+    /**
+     * Fields detected in the form
+     */
+    fields: {
+        name: string;
+        type: string;
+        required: boolean;
+        placeholder: string | null;
+        label: string | null;
+        options: {
+            value: string;
+            text: string;
+        }[] | null;
+    }[];
+    /**
+     * URL of the page where the form was found
+     */
+    pageUrl?: string;
+}
+/**
+ * Unified detected tool (either imperative or declarative)
+ */
+export interface DetectedTool {
+    /**
+     * Tool name
+     */
+    name: string;
+    /**
+     * Tool description
+     */
+    description: string;
+    /**
+     * Input schema (JSON Schema format)
+     */
+    inputSchema?: ToolInputSchema;
+    /**
+     * Tool annotations
+     */
+    annotations?: ToolAnnotations;
+    /**
+     * Detection source
+     */
+    source: 'imperative' | 'declarative';
+    /**
+     * Registration method for imperative tools
+     */
+    registrationMethod?: 'registerTool' | 'provideContext';
+    /**
+     * Whether the tool has an execute function
+     */
+    hasExecute?: boolean;
+    /**
+     * Execute function source code
+     */
+    executeSource?: string | null;
+    /**
+     * URL where the tool was found
+     */
+    pageUrl: string;
+    /**
+     * Additional form-specific data for declarative tools
+     */
+    formData?: {
+        autosubmit: boolean;
+        formAction: string;
+        formMethod: string;
+    };
+}

package/dist/core/types/tool.js

@@ -0,0 +1,6 @@
+/**
+ * WebMCP Tool Types
+ * Based on the Web Model Context Protocol specification
+ */
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/core/types/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../../src/core/types/tool.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/detection/declarative.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Declarative Tool Detection
+ *
+ * Scans HTML for WebMCP form attributes (toolname, tooldescription, etc.)
+ */
+import type { DeclarativeTool, DetectedTool, UnregisteredForm } from '../core/types/tool.js';
+/**
+ * Scan HTML for declarative WebMCP tools (forms with toolname attribute)
+ */
+export declare function scanDeclarativeTools(html: string, pageUrl: string): DeclarativeTool[];
+/**
+ * Convert a declarative tool to a detected tool
+ */
+export declare function toDetectedTool(declarative: DeclarativeTool): DetectedTool;
+/**
+ * Scan HTML for unregistered forms (opportunities)
+ */
+export declare function scanUnregisteredForms(html: string, pageUrl: string): UnregisteredForm[];
+/**
+ * Get statistics about declarative tools on a page
+ */
+export declare function getDeclarativeStats(html: string): {
+    totalForms: number;
+    registeredForms: number;
+    unregisteredForms: number;
+    autosubmitForms: number;
+};