cdp-mcp 0.2.1 → 0.4.0

package/dist/sourcemap/store.d.ts

@@ -1,57 +0,0 @@
-import { SourceMapConsumer } from "@jridgewell/source-map";
-import type { Protocol } from "devtools-protocol";
-export interface ScriptInfo {
-    scriptId: string;
-    url: string;
-    sourceMapURL?: string;
-    startLine: number;
-    startColumn: number;
-    endLine: number;
-    endColumn: number;
-    executionContextId: number;
-    hash: string;
-    isModule?: boolean;
-    sessionId?: string;
-    consumer?: SourceMapConsumer;
-    sources?: string[];
-    loadError?: string;
-}
-export declare class ScriptStore {
-    private byKey;
-    upsert(info: Omit<ScriptInfo, "consumer" | "sources" | "loadError">): void;
-    get(scriptId: string, sessionId?: string): ScriptInfo | undefined;
-    all(): ScriptInfo[];
-    remove(scriptId: string, sessionId?: string): void;
-    clear(): void;
-    findByOriginalSource(file: string): ScriptInfo[];
-    attachMap(scriptId: string, sessionId: string | undefined, raw: string, mapUrl?: string): ScriptInfo | null;
-    setLoadError(scriptId: string, sessionId: string | undefined, err: string): void;
-}
-export declare function cdpToPublic(loc: {
-    lineNumber: number;
-    columnNumber?: number;
-}): {
-    line: number;
-    column: number;
-};
-export declare function publicToCdp(loc: {
-    line: number;
-    column?: number;
-}): {
-    lineNumber: number;
-    columnNumber: number;
-};
-export declare function mapCdpToOriginal(store: ScriptStore, frame: Pick<Protocol.Debugger.CallFrame["location"], "scriptId" | "lineNumber" | "columnNumber">, sessionId: string | undefined): {
-    file: string;
-    line: number;
-    column: number;
-} | null;
-export interface GeneratedLocation {
-    scriptId: string;
-    scriptUrl: string;
-    sessionId?: string;
-    lineNumber: number;
-    columnNumber: number;
-}
-export declare function mapOriginalToGenerated(store: ScriptStore, file: string, line: number, // 1-based
-column?: number): GeneratedLocation[];

package/dist/sourcemap/store.js

@@ -1,185 +0,0 @@
-import { SourceMapConsumer } from "@jridgewell/source-map";
-import { normalizeSourcePath, pathMatches } from "./normalize.js";
-import { log } from "../util/log.js";
-// CDP scriptIds are scoped per Debugger agent (per flat session). Two
-// targets — page + worker, or two iframes — can independently emit
-// scriptId="42". Keying the store on scriptId alone would let the second
-// upsert silently overwrite the first, attach the wrong source map, or
-// resolve paused frames to the wrong script. Compound key is sessionId
-// (or a synthetic root marker) + scriptId.
-const ROOT_KEY = "__root__";
-const keyFor = (scriptId, sessionId) => `${sessionId ?? ROOT_KEY} ${scriptId}`;
-// Indexes scripts the browser has parsed and their (optional) source maps.
-export class ScriptStore {
-    byKey = new Map();
-    // HMR / soft-reload note: when a script is re-parsed under the same
-    // (sessionId, scriptId), Object.assign(existing, info) copies the new
-    // metadata fields but does NOT overwrite `consumer`, `sources`, or
-    // `loadError` because they aren't in the upsert payload (the input type
-    // explicitly Omit<>'s them). A subsequent Debugger.scriptParsed for the
-    // *same* scriptId therefore inherits the OLD source-map consumer until
-    // attachMap() is called again. This is intentional for soft reloads
-    // (the source-map URL is usually the same), but means HMR-changed maps
-    // can leak stale mappings until the next session reset() clears them.
-    // close_session/switchTarget call ScriptStore.clear() so cross-session
-    // contamination is bounded — within a session, downstream callers must
-    // re-attachMap() after any reload that may have changed the map.
-    upsert(info) {
-        const key = keyFor(info.scriptId, info.sessionId);
-        const existing = this.byKey.get(key);
-        if (existing) {
-            Object.assign(existing, info);
-        }
-        else {
-            this.byKey.set(key, { ...info });
-        }
-    }
-    get(scriptId, sessionId) {
-        return this.byKey.get(keyFor(scriptId, sessionId));
-    }
-    all() {
-        return Array.from(this.byKey.values());
-    }
-    remove(scriptId, sessionId) {
-        this.byKey.delete(keyFor(scriptId, sessionId));
-    }
-    clear() {
-        for (const s of this.byKey.values())
-            s.consumer?.destroy();
-        this.byKey.clear();
-    }
-    // Find scripts whose source map references the given TS file.
-    findByOriginalSource(file) {
-        const matches = [];
-        for (const s of this.byKey.values()) {
-            if (!s.sources)
-                continue;
-            if (s.sources.some((src) => pathMatches(src, file))) {
-                matches.push(s);
-            }
-        }
-        return matches;
-    }
-    attachMap(scriptId, sessionId, raw, mapUrl) {
-        const script = this.byKey.get(keyFor(scriptId, sessionId));
-        if (!script)
-            return null;
-        try {
-            const consumer = new SourceMapConsumer(raw, mapUrl);
-            script.consumer = consumer;
-            script.sources = (consumer.sources ?? []).map((s) => normalizeSourcePath(s ?? ""));
-            script.loadError = undefined;
-        }
-        catch (e) {
-            script.loadError = `source-map parse failed: ${String(e)}`;
-            log.warn("source-map parse failed", { scriptId, sessionId, url: script.url, error: String(e) });
-        }
-        return script;
-    }
-    setLoadError(scriptId, sessionId, err) {
-        const s = this.byKey.get(keyFor(scriptId, sessionId));
-        if (s)
-            s.loadError = err;
-    }
-}
-// Helpers for converting CDP <-> source-map line numbering.
-// CDP: 0-based line, 0-based column.
-// source-map: 1-based line, 0-based column.
-// Public tool API: 1-based line, 0-based column.
-export function cdpToPublic(loc) {
-    return { line: loc.lineNumber + 1, column: loc.columnNumber ?? 0 };
-}
-export function publicToCdp(loc) {
-    return { lineNumber: loc.line - 1, columnNumber: loc.column ?? 0 };
-}
-// Translate a CDP-paused frame's location to a public TS location, if a map is available.
-export function mapCdpToOriginal(store, frame, sessionId) {
-    const script = store.get(frame.scriptId, sessionId);
-    if (!script?.consumer)
-        return null;
-    const orig = script.consumer.originalPositionFor({
-        line: frame.lineNumber + 1, // source-map is 1-based
-        column: frame.columnNumber ?? 0,
-    });
-    if (orig.source == null || orig.line == null)
-        return null;
-    return {
-        file: normalizeSourcePath(orig.source),
-        line: orig.line, // already 1-based
-        column: orig.column ?? 0,
-    };
-}
-// Translate a public TS coord to one or more CDP coords for setBreakpointByUrl.
-//
-// Uses `allGeneratedPositionsFor` (NOT `generatedPositionFor`) because the
-// latter requires an EXACT (line, column) match against the source map's
-// emitted mappings — and esbuild/vite typically emit mappings only at
-// statement starts (e.g., column 2 for an indented `return x;`), not at
-// column 0. Setting a breakpoint at `handlers.ts:12` should land regardless
-// of whether the caller supplied column 0 (the default) or the exact
-// column of the first statement; `allGeneratedPositionsFor` enumerates
-// every generated position for the source line, which is the contract
-// debuggers want for breakpoint resolution. (PR #11 e2e bug — line 12 of
-// the sample app has mappings at columns 2 and 9 but none at column 0.)
-//
-// If the source line has multiple generated positions across distinct
-// generated lines (rare with single-line vite bundles, common after
-// minification splits or with classic webpack), each is emitted as its
-// own GeneratedLocation — Debugger.setBreakpointByUrl ends up binding at
-// each, which is what users intuitively expect.
-export function mapOriginalToGenerated(store, file, line, // 1-based
-column = 0) {
-    const out = [];
-    for (const script of store.findByOriginalSource(file)) {
-        if (!script.consumer)
-            continue;
-        const sourceKey = pickSourceKey(script, file);
-        if (!sourceKey)
-            continue;
-        // Forward the caller's column. allGeneratedPositionsFor with column=0
-        // returns the first mapping on the source line (the line-broad case
-        // set_breakpoint uses by default). With a non-zero column it returns
-        // the mapping at-or-after that original column — honoring an
-        // explicitly-supplied column without forcing exact-match strictness.
-        // (Codex/Opus PR #11 round-2: prior version pinned column:0 here and
-        // silently ignored the caller's value.)
-        const positions = script.consumer.allGeneratedPositionsFor({
-            source: sourceKey,
-            line, // 1-based in
-            column,
-        });
-        // De-dup by (gen line, gen col) — different originalColumn mappings on
-        // the same source line can collapse to the same generated position
-        // after minification, but we only need one breakpoint binding per
-        // distinct generated location.
-        const seen = new Set();
-        for (const gen of positions) {
-            if (gen.line == null)
-                continue;
-            const key = `${gen.line}:${gen.column ?? 0}`;
-            if (seen.has(key))
-                continue;
-            seen.add(key);
-            out.push({
-                scriptId: script.scriptId,
-                scriptUrl: script.url,
-                ...(script.sessionId ? { sessionId: script.sessionId } : {}),
-                lineNumber: gen.line - 1, // back to 0-based for CDP
-                columnNumber: gen.column ?? 0,
-            });
-        }
-    }
-    return out;
-}
-function pickSourceKey(script, file) {
-    if (!script.consumer)
-        return null;
-    // We want the source as it appears in the map (with whatever prefix it had)
-    // so the consumer can look it up.
-    for (const raw of script.consumer.sources ?? []) {
-        if (raw && pathMatches(raw, file))
-            return raw;
-    }
-    return null;
-}
-//# sourceMappingURL=store.js.map

package/dist/sourcemap/store.js.map

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

package/dist/tools/_locator_runtime.d.ts

@@ -1,31 +0,0 @@
-import { type LocatorSpec } from "../locator.js";
-/**
- * Normalize a LocatorSpec for tool use, surfacing failures as the repo's
- * structured `ToolError` (historically `missing_arg`) instead of the contract's
- * plain `LocatorError`.
- */
-export declare function normalizeLocator(input: LocatorSpec): LocatorSpec;
-/**
- * In-page helper library: text/visibility utilities, the accessibility
- * heuristics (`implicitRole`, `accessibleName`, `cssPath`), `elementInfo`, and
- * `findElements(spec)`. Inject this into a `Runtime.evaluate` expression before
- * `locatorReadScript()` or `mutationHelpersScript()`.
- */
-export declare function locatorHelpersScript(): string;
-/**
- * The read-only `locate(spec, options)` entry. Compose after
- * `locatorHelpersScript()`; returns `{ ok, error?, found, count, visible_count, matches }`.
- */
-export declare function locatorReadScript(): string;
-/**
- * Mutation helpers for the form-driving tools. Compose after
- * `locatorHelpersScript()`:
- *   - `resolveOne(spec)` → `{ ok, el?, count, visible_count, error?, code? }`,
- *     preferring visible matches (the same visible-first bias `locate` reports)
- *     and picking the first match. On failure `code` distinguishes an
- *     invalid/unsupported locator (`invalid_locator`, mirroring locate/wait_for)
- *     from a valid locator that matched nothing (`not_found`).
- *   - `fireEvents(el, types)` → dispatch bubbling events (e.g. `input`/`change`)
- *     so app frameworks observe a programmatic mutation.
- */
-export declare function mutationHelpersScript(): string;

package/dist/tools/_locator_runtime.js

@@ -1,243 +0,0 @@
-/**
- * Shared, tools-side locator plumbing.
- *
- * The canonical LocatorSpec contract lives in `../locator.ts` (zod-only, public).
- * This module adds the parts that are specific to running locators *inside the
- * page* and to the cdp-mcp tool error envelope:
- *   - `normalizeLocator` — the contract normalizer, re-wrapping `LocatorError`
- *     as the repo's structured `ToolError` (preserving its error code).
- *   - `locatorHelpersScript()` — the in-page helper library (accessibility
- *     heuristics, visibility, `findElements`, `elementInfo`).
- *   - `locatorReadScript()` — the read-only `locate(spec, options)` entry.
- *   - `mutationHelpersScript()` — `resolveOne(spec)` + `fireEvents(el, types)`,
- *     used by the form-driving tools to resolve and mutate an element with the
- *     exact same matching semantics as `locate`.
- *
- * Both `dom.ts` (read) and the form-driving tools (drive) compose these so a
- * locator behaves identically whether it is queried or acted upon.
- */
-import { ToolError } from "../util/errors.js";
-import { normalizeLocator as normalizeLocatorContract, LocatorError, } from "../locator.js";
-/**
- * Normalize a LocatorSpec for tool use, surfacing failures as the repo's
- * structured `ToolError` (historically `missing_arg`) instead of the contract's
- * plain `LocatorError`.
- */
-export function normalizeLocator(input) {
-    try {
-        return normalizeLocatorContract(input);
-    }
-    catch (e) {
-        if (e instanceof LocatorError)
-            throw new ToolError(e.code, e.message);
-        throw e;
-    }
-}
-/**
- * In-page helper library: text/visibility utilities, the accessibility
- * heuristics (`implicitRole`, `accessibleName`, `cssPath`), `elementInfo`, and
- * `findElements(spec)`. Inject this into a `Runtime.evaluate` expression before
- * `locatorReadScript()` or `mutationHelpersScript()`.
- */
-export function locatorHelpersScript() {
-    return String.raw `
-    const compact = (value) => (value || "").replace(/\s+/g, " ").trim();
-    const lower = (value) => compact(value).toLowerCase();
-    const cssEscape = (value) => globalThis.CSS?.escape ? globalThis.CSS.escape(value) : String(value).replace(/["\\]/g, "\\$&");
-    const matchesText = (actual, expected, exact) => {
-      if (expected == null || expected === "") return true;
-      const a = lower(actual);
-      const e = lower(expected);
-      return exact ? a === e : a.includes(e);
-    };
-    const textOf = (el) => compact(el.innerText || el.textContent || "");
-    const isVisible = (el) => {
-      if (!el.isConnected) return false;
-      const style = getComputedStyle(el);
-      if (style.visibility === "hidden" || style.display === "none" || Number(style.opacity) === 0) return false;
-      const rect = el.getBoundingClientRect();
-      return rect.width > 0 && rect.height > 0;
-    };
-    const labelText = (el) => {
-      if ("labels" in el && el.labels && el.labels.length > 0) {
-        return compact(Array.from(el.labels).map((label) => label.innerText || label.textContent || "").join(" "));
-      }
-      return "";
-    };
-    const accessibleName = (el) => {
-      const ariaLabel = el.getAttribute("aria-label");
-      if (ariaLabel) return compact(ariaLabel);
-      const labelledBy = el.getAttribute("aria-labelledby");
-      if (labelledBy) {
-        const text = labelledBy
-          .split(/\s+/)
-          .map((id) => document.getElementById(id)?.innerText || document.getElementById(id)?.textContent || "")
-          .join(" ");
-        if (compact(text)) return compact(text);
-      }
-      const label = labelText(el);
-      if (label) return label;
-      if (el instanceof HTMLInputElement && ["button", "submit", "reset"].includes(el.type)) return compact(el.value);
-      if (el instanceof HTMLInputElement || el instanceof HTMLTextAreaElement) return compact(el.placeholder || el.value || "");
-      if (el instanceof HTMLImageElement) return compact(el.alt || "");
-      return textOf(el);
-    };
-    const implicitRole = (el) => {
-      const explicit = el.getAttribute("role");
-      if (explicit) return lower(explicit.split(/\s+/)[0]);
-      const tag = el.tagName.toLowerCase();
-      if (tag === "button") return "button";
-      if (tag === "a" && el.hasAttribute("href")) return "link";
-      if (/^h[1-6]$/.test(tag)) return "heading";
-      if (tag === "textarea") return "textbox";
-      if (tag === "select") return el.multiple ? "listbox" : "combobox";
-      if (tag === "img") return "img";
-      if (el.isContentEditable) return "textbox";
-      if (tag === "input") {
-        const type = lower(el.getAttribute("type") || "text");
-        if (["button", "submit", "reset"].includes(type)) return "button";
-        if (type === "checkbox") return "checkbox";
-        if (type === "radio") return "radio";
-        if (type === "range") return "slider";
-        if (["email", "password", "search", "tel", "text", "url", ""].includes(type)) return "textbox";
-        if (type === "number") return "spinbutton";
-      }
-      return "";
-    };
-    const cssPath = (el) => {
-      if (el.id) return "#" + cssEscape(el.id);
-      const testId = el.getAttribute("data-testid") || el.getAttribute("data-test-id") || el.getAttribute("data-test");
-      if (testId) return "[" + (el.hasAttribute("data-testid") ? "data-testid" : el.hasAttribute("data-test-id") ? "data-test-id" : "data-test") + "=\"" + cssEscape(testId) + "\"]";
-      const parts = [];
-      let node = el;
-      while (node && node.nodeType === Node.ELEMENT_NODE && parts.length < 5) {
-        const tag = node.tagName.toLowerCase();
-        const name = node.getAttribute("name");
-        if (name) {
-          parts.unshift(tag + "[name=\"" + cssEscape(name) + "\"]");
-          break;
-        }
-        const siblings = Array.from(node.parentElement?.children || []).filter((child) => child.tagName === node.tagName);
-        const index = siblings.indexOf(node) + 1;
-        parts.unshift(siblings.length > 1 ? tag + ":nth-of-type(" + index + ")" : tag);
-        node = node.parentElement;
-      }
-      return parts.join(" > ");
-    };
-    const elementInfo = (el) => {
-      const rect = el.getBoundingClientRect();
-      const info = {
-        selector: cssPath(el),
-        tag: el.tagName.toLowerCase(),
-        role: implicitRole(el) || undefined,
-        name: accessibleName(el) || undefined,
-        text: textOf(el).slice(0, 300),
-        visible: isVisible(el),
-        disabled: "disabled" in el ? !!el.disabled : undefined,
-        value: "value" in el ? el.value : undefined,
-        checked: "checked" in el ? !!el.checked : undefined,
-        bbox: { x: rect.x, y: rect.y, width: rect.width, height: rect.height },
-      };
-      return Object.fromEntries(Object.entries(info).filter(([, value]) => value !== undefined && value !== ""));
-    };
-    const queryAll = (selector) => {
-      try {
-        return { ok: true, elements: Array.from(document.querySelectorAll(selector)) };
-      } catch (error) {
-        return { ok: false, error: "Invalid CSS selector " + selector + ": " + error.message };
-      }
-    };
-    const leafTextMatches = (el, expected, exact) => {
-      if (!matchesText(textOf(el), expected, exact)) return false;
-      return !Array.from(el.children).some((child) => matchesText(textOf(child), expected, exact));
-    };
-    const findElements = (spec) => {
-      const by = spec.by || (spec.selector || spec.css ? "css" : "");
-      const exact = !!spec.exact;
-      if (by === "css") return queryAll(spec.selector || spec.css);
-      if (by === "text") {
-        return { ok: true, elements: Array.from(document.querySelectorAll("body *")).filter((el) => leafTextMatches(el, spec.text || spec.name, exact)) };
-      }
-      if (by === "role") {
-        return { ok: true, elements: Array.from(document.querySelectorAll("body *")).filter((el) => implicitRole(el) === lower(spec.role) && matchesText(accessibleName(el), spec.name, exact)) };
-      }
-      if (by === "test_id" || by === "testId") {
-        const wanted = spec.test_id || spec.testId || spec.name;
-        const candidates = Array.from(document.querySelectorAll("[data-testid], [data-test-id], [data-test]"));
-        return { ok: true, elements: candidates.filter((el) => [el.getAttribute("data-testid"), el.getAttribute("data-test-id"), el.getAttribute("data-test")].some((value) => matchesText(value, wanted, true))) };
-      }
-      if (by === "label") {
-        const wanted = spec.label || spec.name;
-        const controls = [];
-        for (const label of Array.from(document.querySelectorAll("label"))) {
-          if (!matchesText(textOf(label), wanted, exact)) continue;
-          const control = label.control || label.querySelector("input, textarea, select, button");
-          if (control) controls.push(control);
-        }
-        return { ok: true, elements: controls };
-      }
-      if (by === "placeholder") {
-        const wanted = spec.placeholder || spec.name;
-        return { ok: true, elements: Array.from(document.querySelectorAll("[placeholder]")).filter((el) => matchesText(el.getAttribute("placeholder"), wanted, exact)) };
-      }
-      if (by === "name") {
-        return { ok: true, elements: Array.from(document.querySelectorAll("[name]")).filter((el) => matchesText(el.getAttribute("name"), spec.name, true)) };
-      }
-      return { ok: false, error: "Unsupported locator strategy: " + by };
-    };
-  `;
-}
-/**
- * The read-only `locate(spec, options)` entry. Compose after
- * `locatorHelpersScript()`; returns `{ ok, error?, found, count, visible_count, matches }`.
- */
-export function locatorReadScript() {
-    return String.raw `
-    const locate = (spec, options) => {
-      const found = findElements(spec);
-      if (!found.ok) return { ok: false, error: found.error, found: false, count: 0, visible_count: 0, matches: [] };
-      const all = found.elements;
-      const visible = all.filter(isVisible);
-      const returned = (options.includeHidden ? all : visible).slice(0, options.limit || 20).map(elementInfo);
-      return {
-        ok: true,
-        found: returned.length > 0,
-        count: all.length,
-        visible_count: visible.length,
-        matches: returned,
-      };
-    };
-  `;
-}
-/**
- * Mutation helpers for the form-driving tools. Compose after
- * `locatorHelpersScript()`:
- *   - `resolveOne(spec)` → `{ ok, el?, count, visible_count, error?, code? }`,
- *     preferring visible matches (the same visible-first bias `locate` reports)
- *     and picking the first match. On failure `code` distinguishes an
- *     invalid/unsupported locator (`invalid_locator`, mirroring locate/wait_for)
- *     from a valid locator that matched nothing (`not_found`).
- *   - `fireEvents(el, types)` → dispatch bubbling events (e.g. `input`/`change`)
- *     so app frameworks observe a programmatic mutation.
- */
-export function mutationHelpersScript() {
-    return String.raw `
-    const resolveOne = (spec) => {
-      const found = findElements(spec);
-      // findElements only returns !ok for an invalid/unsupported locator (bad CSS
-      // selector or unknown strategy) — the same condition locate/wait_for report
-      // as invalid_locator. A valid locator that simply matches nothing is the
-      // distinct not_found case below.
-      if (!found.ok) return { ok: false, error: found.error, code: "invalid_locator" };
-      const all = found.elements;
-      const visible = all.filter(isVisible);
-      const pick = visible.length ? visible : all;
-      if (pick.length === 0) return { ok: false, error: "no element matches locator", code: "not_found" };
-      return { ok: true, el: pick[0], count: all.length, visible_count: visible.length };
-    };
-    const fireEvents = (el, types) => {
-      for (const t of types) el.dispatchEvent(new Event(t, { bubbles: true }));
-    };
-  `;
-}
-//# sourceMappingURL=_locator_runtime.js.map

package/dist/tools/_locator_runtime.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_locator_runtime.js","sourceRoot":"","sources":["../../src/tools/_locator_runtime.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EACL,gBAAgB,IAAI,wBAAwB,EAC5C,YAAY,GAEb,MAAM,eAAe,CAAC;AAEvB;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,IAAI,CAAC;QACH,OAAO,wBAAwB,CAAC,KAAK,CAAC,CAAC;IACzC,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,IAAI,CAAC,YAAY,YAAY;YAAE,MAAM,IAAI,SAAS,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;QACtE,MAAM,CAAC,CAAC;IACV,CAAC;AACH,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB;IAClC,OAAO,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiJhB,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;GAehB,CAAC;AACJ,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,MAAM,CAAC,GAAG,CAAA;;;;;;;;;;;;;;;;;GAiBhB,CAAC;AACJ,CAAC"}

package/dist/tools/_register.d.ts

@@ -1,2 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerJsonTool<TInput extends Record<string, any>>(server: McpServer, name: string, description: string, inputShape: Record<string, any> | undefined, handler: (input: TInput) => Promise<unknown> | unknown): void;

package/dist/tools/_register.js

@@ -1,30 +0,0 @@
-import { ToolError } from "../util/errors.js";
-import { log } from "../util/log.js";
-import { toolJson, toolText } from "../util/format.js";
-// Wrap a tool handler with consistent error handling so any thrown error
-// becomes a structured `isError: true` result rather than an MCP transport error.
-export function registerJsonTool(server, name, description, inputShape, handler) {
-    server.registerTool(name, {
-        description,
-        ...(inputShape ? { inputSchema: inputShape } : {}),
-    }, async (args) => {
-        try {
-            const result = await handler((args ?? {}));
-            if (result === undefined)
-                return toolText("ok");
-            if (typeof result === "string")
-                return toolText(result);
-            return toolJson(result);
-        }
-        catch (e) {
-            const code = e instanceof ToolError ? e.code : "internal_error";
-            const msg = e instanceof Error ? e.message : String(e);
-            log.warn(`tool error ${name}`, { code, msg });
-            return {
-                isError: true,
-                content: [{ type: "text", text: JSON.stringify({ error: code, message: msg }) }],
-            };
-        }
-    });
-}
-//# sourceMappingURL=_register.js.map

package/dist/tools/_register.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"_register.js","sourceRoot":"","sources":["../../src/tools/_register.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AAC9C,OAAO,EAAE,GAAG,EAAE,MAAM,gBAAgB,CAAC;AACrC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAEvD,yEAAyE;AACzE,kFAAkF;AAClF,MAAM,UAAU,gBAAgB,CAC9B,MAAiB,EACjB,IAAY,EACZ,WAAmB,EACnB,UAA2C,EAC3C,OAAsD;IAEtD,MAAM,CAAC,YAAY,CACjB,IAAI,EACJ;QACE,WAAW;QACX,GAAG,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,UAAiB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAC1D,EACD,KAAK,EAAE,IAAS,EAAE,EAAE;QAClB,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,CAAC,IAAI,IAAI,EAAE,CAAW,CAAC,CAAC;YACrD,IAAI,MAAM,KAAK,SAAS;gBAAE,OAAO,QAAQ,CAAC,IAAI,CAAC,CAAC;YAChD,IAAI,OAAO,MAAM,KAAK,QAAQ;gBAAE,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;YACxD,OAAO,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC1B,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,MAAM,IAAI,GAAG,CAAC,YAAY,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,gBAAgB,CAAC;YAChE,MAAM,GAAG,GAAG,CAAC,YAAY,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACvD,GAAG,CAAC,IAAI,CAAC,cAAc,IAAI,EAAE,EAAE,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,CAAC;YAC9C,OAAO;gBACL,OAAO,EAAE,IAAI;gBACb,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;aAC1F,CAAC;QACJ,CAAC;IACH,CAAC,CACF,CAAC;AACJ,CAAC"}

package/dist/tools/breakpoints.d.ts

@@ -1,4 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-export declare function registerBreakpointTools(server: McpServer): void;
-/** @internal exported for unit tests; not part of the MCP tool surface. */
-export declare function buildConditionExpression(condition?: string, logMessage?: string): string | undefined;