@shawnowen/comet-mcp 2.3.0 → 2.4.1

package/dist/discovery/safety.js

@@ -0,0 +1,59 @@
+/**
+ * safety.ts
+ * Safety taxonomy loader for the Comet Discovery Layer (Spec 042, T007).
+ *
+ * Reads the three valid safety classes (SAFE | SESSION | CAUTION) from
+ * docs/TOOL-SAFETY-REFERENCE.md as the canonical authority. Exports a
+ * validator that rejects any value outside the taxonomy at runtime.
+ *
+ * This module deliberately does NOT import the taxonomy from TOOL-SAFETY-REFERENCE.md
+ * at file-read time (the doc is prose, not machine-readable JSON). Instead we
+ * hard-code the three classes here and note the canonical source in JSDoc so
+ * T061 can add a pointer from the doc back to this file.
+ */
+/**
+ * The three valid safety classes.
+ * Canonical authority: docs/TOOL-SAFETY-REFERENCE.md
+ *
+ * SAFE     — Read-only, zero side effects, no active session required.
+ *            Examples: comet_observe, comet_peek, comet_tab_groups(action=list).
+ * SESSION  — Requires an active Comet CDP session (comet_connect first).
+ *            Scoped to the calling agent's own tab group.
+ *            Examples: comet_screenshot, comet_read_page, comet_navigate.
+ * CAUTION  — Cross-session side effects possible; can modify shared browser state.
+ *            Must carry an explicit multi-agent rule reminder in its description.
+ *            Examples: comet_stop, comet_automate (when interacting across groups).
+ */
+export const VALID_SAFETY_CLASSES = new Set([
+    "SAFE",
+    "SESSION",
+    "CAUTION",
+]);
+/**
+ * Assert that `value` is a valid SafetyClass.
+ * Throws a descriptive TypeError if not.
+ * Used by source readers to reject entries missing or misconfigured safety.
+ *
+ * @param value - The candidate safety string from a source definition.
+ * @param context - Optional label (tool name, file path) for error messages.
+ * @returns The validated SafetyClass.
+ */
+export function assertSafety(value, context) {
+    if (VALID_SAFETY_CLASSES.has(value)) {
+        return value;
+    }
+    const ctxStr = context ? ` (context: ${context})` : "";
+    throw new TypeError(`Invalid safety class "${value}"${ctxStr}. ` +
+        `Valid classes are: ${[...VALID_SAFETY_CLASSES].join(" | ")}. ` +
+        `See docs/TOOL-SAFETY-REFERENCE.md for definitions.`);
+}
+/**
+ * Safe version of assertSafety — returns null instead of throwing.
+ * Useful when the caller wants to route errors through SourceError rather than throw.
+ */
+export function parseSafety(value) {
+    if (typeof value !== "string")
+        return null;
+    return VALID_SAFETY_CLASSES.has(value) ? value : null;
+}
+//# sourceMappingURL=safety.js.map

package/dist/discovery/schema-validator.d.ts

@@ -0,0 +1,36 @@
+/**
+ * schema-validator.ts
+ * Lightweight JSON / YAML Schema validator for the Comet Discovery Layer (Spec 042, T009).
+ *
+ * Loads schema files from ./contracts/ and validates arbitrary values against them.
+ * Uses a minimal built-in validator so the discovery module has no heavy runtime
+ * dependency (ajv is not in the dependency list). Only the subset of JSON Schema
+ * draft 2020-12 actually used by the four contracts is implemented.
+ *
+ * Supported keywords:
+ *   type, enum, const, pattern, minLength, maxLength, minimum, minItems,
+ *   required, properties, additionalProperties, oneOf, allOf, if/then/else,
+ *   $ref (intra-document only), items, format (date, date-time — format:true check only)
+ */
+export interface ValidationResult {
+    valid: boolean;
+    errors: ValidationError[];
+}
+export interface ValidationError {
+    path: string;
+    message: string;
+}
+/**
+ * Validate `value` against the named contract file in ./contracts/.
+ * Filename must be one of the four contract files committed at T003.
+ *
+ * @example
+ *   const result = validateContract("capability-entry.schema.json", entry);
+ *   if (!result.valid) console.error(result.errors);
+ */
+export declare function validateContract(contractFile: string, value: unknown): ValidationResult;
+/**
+ * Throw if validation fails. Formats errors as readable path-messages.
+ */
+export declare function assertValid(contractFile: string, value: unknown, context?: string): void;
+//# sourceMappingURL=schema-validator.d.ts.map

package/dist/discovery/schema-validator.js

@@ -0,0 +1,257 @@
+/**
+ * schema-validator.ts
+ * Lightweight JSON / YAML Schema validator for the Comet Discovery Layer (Spec 042, T009).
+ *
+ * Loads schema files from ./contracts/ and validates arbitrary values against them.
+ * Uses a minimal built-in validator so the discovery module has no heavy runtime
+ * dependency (ajv is not in the dependency list). Only the subset of JSON Schema
+ * draft 2020-12 actually used by the four contracts is implemented.
+ *
+ * Supported keywords:
+ *   type, enum, const, pattern, minLength, maxLength, minimum, minItems,
+ *   required, properties, additionalProperties, oneOf, allOf, if/then/else,
+ *   $ref (intra-document only), items, format (date, date-time — format:true check only)
+ */
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { parse as parseYaml } from "yaml";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const CONTRACTS_DIR = join(__dirname, "contracts");
+const schemaCache = new Map();
+function loadSchema(filename) {
+    if (schemaCache.has(filename))
+        return schemaCache.get(filename);
+    const filePath = join(CONTRACTS_DIR, filename);
+    const raw = readFileSync(filePath, "utf-8");
+    const schema = filename.endsWith(".yaml") || filename.endsWith(".yml")
+        ? parseYaml(raw)
+        : JSON.parse(raw);
+    schemaCache.set(filename, schema);
+    return schema;
+}
+/**
+ * Validate `value` against the named contract file in ./contracts/.
+ * Filename must be one of the four contract files committed at T003.
+ *
+ * @example
+ *   const result = validateContract("capability-entry.schema.json", entry);
+ *   if (!result.valid) console.error(result.errors);
+ */
+export function validateContract(contractFile, value) {
+    const schema = loadSchema(contractFile);
+    const errors = [];
+    validateNode(schema, value, "$", errors, schema);
+    return { valid: errors.length === 0, errors };
+}
+/**
+ * Throw if validation fails. Formats errors as readable path-messages.
+ */
+export function assertValid(contractFile, value, context) {
+    const result = validateContract(contractFile, value);
+    if (!result.valid) {
+        const prefix = context ? `${context}: ` : "";
+        const lines = result.errors.map((e) => `  ${e.path}: ${e.message}`).join("\n");
+        throw new Error(`${prefix}Schema validation failed against ${contractFile}:\n${lines}`);
+    }
+}
+// ---------------------------------------------------------------------------
+// Internal validator
+// ---------------------------------------------------------------------------
+function validateNode(schema, value, path, errors, rootSchema) {
+    if (typeof schema !== "object" || schema === null)
+        return;
+    const s = schema;
+    // $ref — intra-document only
+    if ("$ref" in s) {
+        const ref = s["$ref"];
+        const resolved = resolveRef(ref, rootSchema);
+        if (resolved)
+            validateNode(resolved, value, path, errors, rootSchema);
+        return;
+    }
+    // type
+    if ("type" in s) {
+        const t = s["type"];
+        if (!checkType(t, value)) {
+            errors.push({ path, message: `expected type ${JSON.stringify(t)}, got ${getType(value)}` });
+            return; // further checks are meaningless
+        }
+    }
+    // enum
+    if ("enum" in s) {
+        const vals = s["enum"];
+        if (!vals.some((v) => deepEqual(v, value))) {
+            errors.push({ path, message: `must be one of ${JSON.stringify(vals)}` });
+        }
+    }
+    // const
+    if ("const" in s) {
+        if (!deepEqual(s["const"], value)) {
+            errors.push({ path, message: `must equal ${JSON.stringify(s["const"])}` });
+        }
+    }
+    // pattern (string)
+    if ("pattern" in s && typeof value === "string") {
+        const re = new RegExp(s["pattern"]);
+        if (!re.test(value)) {
+            errors.push({ path, message: `must match pattern ${s["pattern"]}` });
+        }
+    }
+    // minLength / maxLength (string)
+    if ("minLength" in s && typeof value === "string") {
+        if (value.length < s["minLength"]) {
+            errors.push({ path, message: `must be at least ${s["minLength"]} characters` });
+        }
+    }
+    if ("maxLength" in s && typeof value === "string") {
+        if (value.length > s["maxLength"]) {
+            errors.push({ path, message: `must be at most ${s["maxLength"]} characters` });
+        }
+    }
+    // minimum (number)
+    if ("minimum" in s && typeof value === "number") {
+        if (value < s["minimum"]) {
+            errors.push({ path, message: `must be >= ${s["minimum"]}` });
+        }
+    }
+    // minItems (array)
+    if ("minItems" in s && Array.isArray(value)) {
+        if (value.length < s["minItems"]) {
+            errors.push({ path, message: `must have at least ${s["minItems"]} items` });
+        }
+    }
+    // required (object)
+    if ("required" in s && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const obj = value;
+        for (const key of s["required"]) {
+            if (!(key in obj)) {
+                errors.push({ path: `${path}.${key}`, message: `is required` });
+            }
+        }
+    }
+    // properties (object)
+    if ("properties" in s && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const obj = value;
+        const props = s["properties"];
+        for (const [key, propSchema] of Object.entries(props)) {
+            if (key in obj) {
+                validateNode(propSchema, obj[key], `${path}.${key}`, errors, rootSchema);
+            }
+        }
+    }
+    // additionalProperties: false
+    if (s["additionalProperties"] === false && typeof value === "object" && value !== null && !Array.isArray(value)) {
+        const obj = value;
+        const allowed = new Set([
+            ...Object.keys((s["properties"] ?? {})),
+            ...Object.keys((s["$defs"] ?? {})),
+        ]);
+        for (const key of Object.keys(obj)) {
+            if (!allowed.has(key)) {
+                errors.push({ path: `${path}.${key}`, message: `additional property not allowed` });
+            }
+        }
+    }
+    // items (array)
+    if ("items" in s && Array.isArray(value)) {
+        const itemSchema = s["items"];
+        for (let i = 0; i < value.length; i++) {
+            validateNode(itemSchema, value[i], `${path}[${i}]`, errors, rootSchema);
+        }
+    }
+    // oneOf
+    if ("oneOf" in s) {
+        const schemas = s["oneOf"];
+        let matched = 0;
+        for (const sub of schemas) {
+            const subErrors = [];
+            validateNode(sub, value, path, subErrors, rootSchema);
+            if (subErrors.length === 0)
+                matched++;
+        }
+        if (matched !== 1) {
+            errors.push({ path, message: `must match exactly one of the oneOf schemas (matched ${matched})` });
+        }
+    }
+    // allOf
+    if ("allOf" in s) {
+        for (const sub of s["allOf"]) {
+            validateNode(sub, value, path, errors, rootSchema);
+        }
+    }
+    // if / then / else
+    if ("if" in s) {
+        const ifErrors = [];
+        validateNode(s["if"], value, path, ifErrors, rootSchema);
+        if (ifErrors.length === 0 && "then" in s) {
+            validateNode(s["then"], value, path, errors, rootSchema);
+        }
+        else if (ifErrors.length > 0 && "else" in s) {
+            validateNode(s["else"], value, path, errors, rootSchema);
+        }
+    }
+    // format — date and date-time (basic regex checks)
+    if ("format" in s && typeof value === "string") {
+        const fmt = s["format"];
+        if (fmt === "date" && !/^\d{4}-\d{2}-\d{2}$/.test(value)) {
+            errors.push({ path, message: `must be an ISO 8601 date (YYYY-MM-DD)` });
+        }
+        if (fmt === "date-time" && !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}/.test(value)) {
+            errors.push({ path, message: `must be an ISO 8601 date-time` });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function resolveRef(ref, root) {
+    if (!ref.startsWith("#/"))
+        return null;
+    const parts = ref.slice(2).split("/");
+    let node = root;
+    for (const part of parts) {
+        if (typeof node !== "object" || node === null)
+            return null;
+        node = node[part];
+    }
+    return node;
+}
+function checkType(type, value) {
+    const types = Array.isArray(type) ? type : [type];
+    return types.some((t) => {
+        switch (t) {
+            case "string": return typeof value === "string";
+            case "number": return typeof value === "number";
+            case "integer": return typeof value === "number" && Number.isInteger(value);
+            case "boolean": return typeof value === "boolean";
+            case "null": return value === null;
+            case "array": return Array.isArray(value);
+            case "object": return typeof value === "object" && value !== null && !Array.isArray(value);
+            default: return false;
+        }
+    });
+}
+function getType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b)
+        return false;
+    if (typeof a === "object" && a !== null && b !== null) {
+        const ka = Object.keys(a).sort();
+        const kb = Object.keys(b).sort();
+        if (ka.join() !== kb.join())
+            return false;
+        return ka.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+//# sourceMappingURL=schema-validator.js.map

package/dist/discovery/source-error.d.ts

@@ -0,0 +1,47 @@
+/**
+ * source-error.ts
+ * SourceError aggregator + stable-format warning emitter (Spec 042, T008).
+ *
+ * Implements the FR-008a warn-and-continue contract:
+ * - Source readers call `aggregateError()` when a source is unavailable.
+ * - The registry composer calls `emitSourceWarnings()` once after all sources run.
+ * - Output is one-line per missing source, emitted to stderr (R7).
+ * - MCP startup never throws because of a missing source.
+ */
+import type { SourceError, SourceLayer } from "./capability-entry.js";
+/**
+ * Build a SourceError record from a SourceLayer + reason + optional raw error.
+ */
+export declare function makeSourceError(source: SourceLayer, reason: string, originalError?: unknown): SourceError;
+/**
+ * Build a SourceError from a caught exception, normalizing the message.
+ */
+export declare function errorFromException(source: SourceLayer, err: unknown): SourceError;
+/**
+ * In-memory accumulator used by the registry composer during one startup cycle.
+ * Not a singleton — callers construct and pass this around so tests can inspect it.
+ */
+export declare class SourceErrorAggregator {
+    private readonly _errors;
+    add(err: SourceError): void;
+    get errors(): readonly SourceError[];
+    get hasErrors(): boolean;
+    unavailableSources(): SourceLayer[];
+}
+/**
+ * Emit one warning line per SourceError to stderr.
+ * Format: [comet-discovery] WARN source=<layer> reason=<reason>
+ *
+ * This format is stable across versions so external log parsers can key on it.
+ * Full JSON details are emitted only when COMET_DISCOVERY_VERBOSE=1.
+ */
+export declare function emitSourceWarnings(errors: readonly SourceError[]): void;
+/**
+ * Emit a session-start warning when the registry is incomplete.
+ * Called by index.ts after composeRegistry(); format matches DriftReport.status.
+ */
+export declare function emitSessionStartWarning(unavailable: Array<{
+    source: SourceLayer;
+    reason: string;
+}>): void;
+//# sourceMappingURL=source-error.d.ts.map

package/dist/discovery/source-error.js

@@ -0,0 +1,95 @@
+/**
+ * source-error.ts
+ * SourceError aggregator + stable-format warning emitter (Spec 042, T008).
+ *
+ * Implements the FR-008a warn-and-continue contract:
+ * - Source readers call `aggregateError()` when a source is unavailable.
+ * - The registry composer calls `emitSourceWarnings()` once after all sources run.
+ * - Output is one-line per missing source, emitted to stderr (R7).
+ * - MCP startup never throws because of a missing source.
+ */
+// ---------------------------------------------------------------------------
+// Builder helpers
+// ---------------------------------------------------------------------------
+/**
+ * Build a SourceError record from a SourceLayer + reason + optional raw error.
+ */
+export function makeSourceError(source, reason, originalError) {
+    return { source, reason, originalError };
+}
+/**
+ * Build a SourceError from a caught exception, normalizing the message.
+ */
+export function errorFromException(source, err) {
+    const reason = err instanceof Error ? err.message : typeof err === "string" ? err : String(err);
+    return makeSourceError(source, reason, err);
+}
+// ---------------------------------------------------------------------------
+// Aggregator
+// ---------------------------------------------------------------------------
+/**
+ * In-memory accumulator used by the registry composer during one startup cycle.
+ * Not a singleton — callers construct and pass this around so tests can inspect it.
+ */
+export class SourceErrorAggregator {
+    _errors = [];
+    add(err) {
+        this._errors.push(err);
+    }
+    get errors() {
+        return this._errors;
+    }
+    get hasErrors() {
+        return this._errors.length > 0;
+    }
+    unavailableSources() {
+        return [...new Set(this._errors.map((e) => e.source))];
+    }
+}
+// ---------------------------------------------------------------------------
+// Stable-format warning emitter (R7)
+// ---------------------------------------------------------------------------
+/**
+ * Emit one warning line per SourceError to stderr.
+ * Format: [comet-discovery] WARN source=<layer> reason=<reason>
+ *
+ * This format is stable across versions so external log parsers can key on it.
+ * Full JSON details are emitted only when COMET_DISCOVERY_VERBOSE=1.
+ */
+export function emitSourceWarnings(errors) {
+    if (errors.length === 0)
+        return;
+    for (const err of errors) {
+        const line = `[comet-discovery] WARN source=${err.source} reason=${sanitize(err.reason)}`;
+        process.stderr.write(line + "\n");
+        if (process.env.COMET_DISCOVERY_VERBOSE === "1") {
+            const detail = {
+                source: err.source,
+                reason: err.reason,
+                error: err.originalError instanceof Error
+                    ? { message: err.originalError.message, stack: err.originalError.stack }
+                    : err.originalError,
+            };
+            process.stderr.write("[comet-discovery] VERBOSE " + JSON.stringify(detail) + "\n");
+        }
+    }
+}
+/**
+ * Emit a session-start warning when the registry is incomplete.
+ * Called by index.ts after composeRegistry(); format matches DriftReport.status.
+ */
+export function emitSessionStartWarning(unavailable) {
+    if (unavailable.length === 0)
+        return;
+    const sources = unavailable.map((u) => u.source).join(", ");
+    process.stderr.write(`[comet-discovery] WARN session-start: incomplete registry — unavailable sources: ${sources}. ` +
+        `Run COMET_DISCOVERY_VERBOSE=1 for details.\n`);
+}
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+/** Strip newlines and truncate long reason strings for single-line stderr. */
+function sanitize(s) {
+    return s.replace(/[\r\n]+/g, " ").slice(0, 200);
+}
+//# sourceMappingURL=source-error.js.map

package/dist/discovery/tool-meta.d.ts

@@ -0,0 +1,41 @@
+/**
+ * tool-meta.ts
+ * Discovery metadata catalog for the 25 native Comet MCP tools (Spec 042, T024).
+ *
+ * Each entry provides the discovery-layer fields that are NOT present in the
+ * existing TOOLS array in index.ts: canonicalId, safety, preconditions,
+ * intentKeywords, and a description following the R10 template.
+ *
+ * AUTHORITATIVE SOURCES:
+ *   - Safety classes: docs/TOOL-SAFETY-REFERENCE.md
+ *   - Preconditions: same doc, safety class descriptions
+ *
+ * This file is the single source of truth for native-tool discovery metadata.
+ * When a new tool is added to TOOLS in index.ts, add a matching entry here.
+ */
+import type { SafetyClass, Precondition } from "./capability-entry.js";
+export interface ToolMeta {
+    /** Must match the `name` field in the TOOLS array in index.ts */
+    toolName: string;
+    /** Shared canonicalId used for dedup grouping across layers */
+    canonicalId: string;
+    /** Safety class — from docs/TOOL-SAFETY-REFERENCE.md */
+    safety: SafetyClass;
+    /** Prerequisites before calling this tool */
+    preconditions: Precondition[];
+    /**
+     * At least 3 lowercase keywords for ToolSearch ranking.
+     * Think: what would an agent type to find this tool?
+     */
+    intentKeywords: string[];
+    /** R10 description template: "<verb> <object> [<modifier>]. Source: mcp. Safety: <class>." */
+    description: string;
+}
+/**
+ * Discovery metadata for the 25 native MCP tools.
+ * Order matches the TOOLS array in index.ts for readability.
+ */
+export declare const TOOL_META: ToolMeta[];
+/** Lookup map: toolName → ToolMeta */
+export declare const TOOL_META_MAP: ReadonlyMap<string, ToolMeta>;
+//# sourceMappingURL=tool-meta.d.ts.map