copilot-tap-extension 2.0.7 → 2.0.9

package/providers/detour/src/provider-core.js

@@ -0,0 +1,233 @@
+import { MESSAGE_TYPES } from "./contracts.js";
+
+export const MAX_LOG_BUFFER = 500;
+export const BRIDGE_TOKEN_PLACEHOLDER = "__DET0UR_WS_URL__";
+export const AUTH_HEADER = "x-detour-token";
+export const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "[::1]"]);
+
+export function firstClientIdFrom(clients) {
+  const first = clients.keys().next();
+  return first.done ? null : first.value;
+}
+
+export function clientLabelFrom(clients, id) {
+  const client = clients.get(id);
+  return client ? `${client.title} (${client.url})` : id;
+}
+
+export function listBrowserClients(clients) {
+  return [...clients].map(([id, client]) => ({
+    id,
+    url: client.url,
+    title: client.title,
+    connectedAt: client.connectedAt,
+  }));
+}
+
+export function selectConsoleLogs(consoleLogs, args = {}, max = MAX_LOG_BUFFER) {
+  let logs = [...consoleLogs];
+  if (args.client_id) logs = logs.filter((log) => log.clientId === args.client_id);
+  if (args.level) logs = logs.filter((log) => log.level === args.level);
+  return logs.slice(-(Math.min(args.limit || 50, max)));
+}
+
+export function selectPageMessages(pageMessages, args = {}) {
+  return pageMessages.slice(-(args.limit || 20));
+}
+
+export function buildMessagesResponse(pageMessages, requestUrl) {
+  const url = new URL(requestUrl, "http://localhost");
+  const ack = parseInt(url.searchParams.get("ack") || "0", 10);
+  return {
+    total: pageMessages.length,
+    messages: pageMessages.slice(ack),
+  };
+}
+
+export function routeHttpRequest(method, requestUrl) {
+  const { pathname } = new URL(requestUrl || "/", "http://localhost");
+  if (method === "OPTIONS") return "options";
+  if ((pathname === "/bridge.js" || pathname === "/") && method === "GET") return "bridge";
+  if (pathname === "/eval" && method === "POST") return "eval";
+  if (pathname === "/clients" && method === "GET") return "clients";
+  if (pathname === "/logs" && method === "GET") return "logs";
+  if (pathname === "/messages" && method === "GET") return "messages";
+  if (pathname === "/reply" && method === "POST") return "reply";
+  return "notFound";
+}
+
+export function renderBridgeScript(template, browserPort, token) {
+  const wsUrl = `ws://127.0.0.1:${browserPort}?token=${encodeURIComponent(token)}`;
+  return template.replaceAll(BRIDGE_TOKEN_PLACEHOLDER, wsUrl);
+}
+
+export function getRequestToken(req) {
+  const url = new URL(req.url || "/", "http://localhost");
+  const queryToken = url.searchParams.get("token");
+  if (queryToken) return queryToken;
+
+  const headerToken = req.headers?.[AUTH_HEADER];
+  if (Array.isArray(headerToken)) return headerToken[0] || "";
+  if (typeof headerToken === "string") return headerToken;
+
+  const authorization = req.headers?.authorization;
+  const value = Array.isArray(authorization) ? authorization[0] : authorization;
+  const match = typeof value === "string" ? /^Bearer\s+(.+)$/i.exec(value) : null;
+  return match ? match[1] : "";
+}
+
+export function isAuthorizedRequest(req, expectedToken) {
+  return Boolean(expectedToken) && getRequestToken(req) === expectedToken;
+}
+
+export function isLoopbackHostHeader(hostHeader) {
+  if (typeof hostHeader !== "string" || !hostHeader) return false;
+  const lowerHost = hostHeader.toLowerCase();
+  if (lowerHost === "[::1]" || lowerHost.startsWith("[::1]:")) return true;
+  const host = lowerHost.split(":")[0];
+  return LOOPBACK_HOSTS.has(host);
+}
+
+export function isLoopbackAddress(address) {
+  return address === "127.0.0.1" || address === "::1" || address === "::ffff:127.0.0.1";
+}
+
+export function isAllowedCorsOrigin(origin) {
+  return typeof origin === "string" && origin.startsWith("chrome-extension://");
+}
+
+export function applyCorsHeaders(req, res) {
+  const origin = req.headers?.origin;
+  if (!isAllowedCorsOrigin(origin)) return;
+  res.setHeader("Access-Control-Allow-Origin", origin);
+  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
+  res.setHeader("Access-Control-Allow-Headers", `Content-Type, Authorization, ${AUTH_HEADER}`);
+  res.setHeader("Vary", "Origin");
+}
+
+export function planBrowserMessage(raw, { clientId, from, nowIso }) {
+  let msg;
+  try {
+    msg = JSON.parse(raw);
+  } catch {
+    return { kind: "ignore" };
+  }
+
+  switch (msg.type) {
+    case MESSAGE_TYPES.IDENTIFY:
+      return {
+        kind: "identify",
+        url: msg.url || "unknown",
+        title: msg.title || "unknown",
+        logText: `   → ${msg.title} (${msg.url})`,
+      };
+
+    case MESSAGE_TYPES.CONSOLE:
+      return {
+        kind: "console",
+        entry: {
+          clientId,
+          level: msg.level || "log",
+          args: msg.args || [],
+          timestamp: msg.timestamp || nowIso(),
+        },
+      };
+
+    case MESSAGE_TYPES.EVAL_RESULT:
+      return {
+        kind: "evalResult",
+        id: msg.id,
+        error: msg.error,
+        value: msg.value,
+      };
+
+    case MESSAGE_TYPES.PAGE_MESSAGE:
+      return {
+        kind: "pageMessage",
+        logText: `📨 [${from}] ${msg.message}`,
+        pageMessage: { clientId, from, message: msg.message, timestamp: nowIso() },
+        pushText: `[${from}] ${msg.message}`,
+      };
+
+    case MESSAGE_TYPES.PAGE_ASK:
+      return {
+        kind: "pageAsk",
+        askId: msg.id,
+        logText: `❓ [ASK from ${from}] ${msg.message}`,
+        pendingAsk: { clientId, message: msg.message, from, timestamp: nowIso() },
+        pageMessage: { clientId, from, message: msg.message, type: "ask", askId: msg.id, timestamp: nowIso() },
+        pushText: `[ASK from ${from}] ${msg.message} (reply with reply_to_page tool, askId: "${msg.id}")`,
+      };
+
+    case MESSAGE_TYPES.PAGE_CONTEXT: {
+      const chatMsg = msg.message ? ` — "${msg.message}"` : "";
+      const annotationCount = msg.annotations?.length || 0;
+      return {
+        kind: "pageContext",
+        logText: `📋 [CONTEXT from ${from}] ${annotationCount} annotations${chatMsg}`,
+        pageMessage: {
+          clientId,
+          from,
+          message: msg.markdown || `${annotationCount} annotations from ${from}${chatMsg}`,
+          type: "context",
+          timestamp: nowIso(),
+        },
+        pushText: `[CONTEXT from ${from}]${chatMsg}\n${msg.markdown || ""}`,
+      };
+    }
+
+    case MESSAGE_TYPES.PAGE_ANNOTATE: {
+      const ann = msg.annotation || {};
+      return {
+        kind: "pageAnnotate",
+        logText: `📌 [${from}] ${ann.context?.displayName || "element"}: ${ann.intent} — ${ann.comment || "(no comment)"}`,
+      };
+    }
+
+    default:
+      return { kind: "ignore" };
+  }
+}
+
+export function planToolCall(toolName, args = {}, state) {
+  switch (toolName) {
+    case "inject_js": {
+      const clientId = args.client_id || state.firstClientId;
+      if (!clientId) return { kind: "result", value: { error: "No browser clients connected." } };
+      return {
+        kind: "eval",
+        clientId,
+        code: args.code,
+        timeoutMs: args.timeout_ms || 15000,
+      };
+    }
+
+    case "get_console_logs":
+      return {
+        kind: "consoleLogs",
+        logs: selectConsoleLogs(state.consoleLogs, args),
+        clear: args.clear,
+      };
+
+    case "list_browser_clients":
+      return { kind: "result", value: listBrowserClients(state.clients) };
+
+    case "get_page_messages":
+      return { kind: "result", value: selectPageMessages(state.pageMessages, args) };
+
+    case "reply_to_page": {
+      const pending = state.pendingPageAsks.get(args.ask_id);
+      if (!pending) return { kind: "result", value: { error: "No pending ask with that ID" } };
+      return {
+        kind: "replyToPage",
+        askId: args.ask_id,
+        pending,
+        payload: { type: MESSAGE_TYPES.ASK_REPLY, id: args.ask_id, reply: args.reply },
+        result: { ok: true, repliedTo: pending.from },
+      };
+    }
+
+    default:
+      return { kind: "unknown", toolName };
+  }
+}

package/providers/detour/src/provider-core.test.mjs

@@ -0,0 +1,185 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { MESSAGE_TYPES } from "./contracts.js";
+import {
+  AUTH_HEADER,
+  BRIDGE_TOKEN_PLACEHOLDER,
+  MAX_LOG_BUFFER,
+  applyCorsHeaders,
+  buildMessagesResponse,
+  clientLabelFrom,
+  firstClientIdFrom,
+  getRequestToken,
+  isAllowedCorsOrigin,
+  isAuthorizedRequest,
+  isLoopbackAddress,
+  isLoopbackHostHeader,
+  listBrowserClients,
+  planBrowserMessage,
+  planToolCall,
+  renderBridgeScript,
+  routeHttpRequest,
+  selectConsoleLogs,
+  selectPageMessages,
+} from "./provider-core.js";
+
+test("client helpers preserve map ordering and labels", () => {
+  const clients = new Map([
+    ["tab-1", { title: "Cart", url: "https://example.test/cart", connectedAt: "t1" }],
+    ["tab-2", { title: "Checkout", url: "https://example.test/checkout", connectedAt: "t2" }],
+  ]);
+
+  assert.equal(MAX_LOG_BUFFER, 500);
+  assert.equal(firstClientIdFrom(clients), "tab-1");
+  assert.equal(clientLabelFrom(clients, "tab-2"), "Checkout (https://example.test/checkout)");
+  assert.equal(clientLabelFrom(clients, "missing"), "missing");
+  assert.deepEqual(listBrowserClients(clients), [
+    { id: "tab-1", title: "Cart", url: "https://example.test/cart", connectedAt: "t1" },
+    { id: "tab-2", title: "Checkout", url: "https://example.test/checkout", connectedAt: "t2" },
+  ]);
+});
+
+test("selectors match Detour buffer read behavior", () => {
+  const logs = [
+    { clientId: "tab-1", level: "log", message: "first" },
+    { clientId: "tab-2", level: "warn", message: "second" },
+    { clientId: "tab-1", level: "warn", message: "third" },
+  ];
+  assert.deepEqual(selectConsoleLogs(logs, { client_id: "tab-1", level: "warn", limit: 5 }), [
+    { clientId: "tab-1", level: "warn", message: "third" },
+  ]);
+  assert.deepEqual(selectPageMessages(["a", "b", "c"], { limit: 2 }), ["b", "c"]);
+});
+
+test("HTTP request helpers keep route and message response semantics", () => {
+  assert.equal(routeHttpRequest("OPTIONS", "/anything"), "options");
+  assert.equal(routeHttpRequest("GET", "/bridge.js?token=t"), "bridge");
+  assert.equal(routeHttpRequest("POST", "/eval?token=t"), "eval");
+  assert.equal(routeHttpRequest("GET", "/clients?token=t"), "clients");
+  assert.equal(routeHttpRequest("GET", "/logs?level=warn"), "logs");
+  assert.equal(routeHttpRequest("GET", "/messages?ack=1"), "messages");
+  assert.equal(routeHttpRequest("POST", "/reply?token=t"), "reply");
+  assert.equal(routeHttpRequest("GET", "/missing"), "notFound");
+
+  assert.deepEqual(buildMessagesResponse(["zero", "one", "two"], "/messages?ack=1"), {
+    total: 3,
+    messages: ["one", "two"],
+  });
+});
+
+test("bridge auth helpers require loopback and explicit token", () => {
+  const reqFromQuery = { url: "/bridge.js?token=secret", headers: { host: "127.0.0.1:9401" } };
+  const reqFromHeader = { url: "/messages", headers: { host: "localhost:9401", [AUTH_HEADER]: "secret" } };
+  const reqFromBearer = { url: "/messages", headers: { host: "[::1]:9401", authorization: "Bearer secret" } };
+
+  assert.equal(getRequestToken(reqFromQuery), "secret");
+  assert.equal(getRequestToken(reqFromHeader), "secret");
+  assert.equal(getRequestToken(reqFromBearer), "secret");
+  assert.equal(isAuthorizedRequest(reqFromQuery, "secret"), true);
+  assert.equal(isAuthorizedRequest({ url: "/bridge.js", headers: {} }, "secret"), false);
+  assert.equal(isLoopbackHostHeader("127.0.0.1:9401"), true);
+  assert.equal(isLoopbackHostHeader("localhost:9401"), true);
+  assert.equal(isLoopbackHostHeader("[::1]:9401"), true);
+  assert.equal(isLoopbackHostHeader("evil.test:9401"), false);
+  assert.equal(isLoopbackAddress("127.0.0.1"), true);
+  assert.equal(isLoopbackAddress("::ffff:127.0.0.1"), true);
+  assert.equal(isLoopbackAddress("10.0.0.5"), false);
+});
+
+test("bridge script rendering injects an unexposed loopback websocket token", () => {
+  const script = `var WS_URL = "${BRIDGE_TOKEN_PLACEHOLDER}";`;
+  assert.equal(
+    renderBridgeScript(script, 9401, "token with spaces"),
+    'var WS_URL = "ws://127.0.0.1:9401?token=token%20with%20spaces";',
+  );
+});
+
+test("CORS helper only reflects chrome-extension origins", () => {
+  assert.equal(isAllowedCorsOrigin("chrome-extension://abc"), true);
+  assert.equal(isAllowedCorsOrigin("https://evil.test"), false);
+
+  const headers = new Map();
+  const res = { setHeader: (name, value) => headers.set(name, value) };
+  applyCorsHeaders({ headers: { origin: "chrome-extension://abc" } }, res);
+  assert.equal(headers.get("Access-Control-Allow-Origin"), "chrome-extension://abc");
+
+  headers.clear();
+  applyCorsHeaders({ headers: { origin: "https://evil.test" } }, res);
+  assert.equal(headers.has("Access-Control-Allow-Origin"), false);
+});
+
+test("browser message planner preserves Detour push and log text", () => {
+  const timestamps = ["pending-time", "message-time"];
+  const plan = planBrowserMessage(JSON.stringify({
+    type: MESSAGE_TYPES.PAGE_ASK,
+    id: "ask-1",
+    message: "Can you review this button?",
+  }), {
+    clientId: "tab-1",
+    from: "Checkout (https://example.test)",
+    nowIso: () => timestamps.shift(),
+  });
+
+  assert.deepEqual(plan, {
+    kind: "pageAsk",
+    askId: "ask-1",
+    logText: "❓ [ASK from Checkout (https://example.test)] Can you review this button?",
+    pendingAsk: {
+      clientId: "tab-1",
+      message: "Can you review this button?",
+      from: "Checkout (https://example.test)",
+      timestamp: "pending-time",
+    },
+    pageMessage: {
+      clientId: "tab-1",
+      from: "Checkout (https://example.test)",
+      message: "Can you review this button?",
+      type: "ask",
+      askId: "ask-1",
+      timestamp: "message-time",
+    },
+    pushText: "[ASK from Checkout (https://example.test)] Can you review this button? (reply with reply_to_page tool, askId: \"ask-1\")",
+  });
+});
+
+test("tool-call planner keeps public tool responses side-effect free", () => {
+  const clients = new Map([
+    ["tab-1", { title: "Cart", url: "https://example.test/cart", connectedAt: "t1" }],
+  ]);
+  const pending = { from: "Cart (https://example.test/cart)", ws: { readyState: 1 } };
+  const state = {
+    firstClientId: "tab-1",
+    clients,
+    consoleLogs: [{ clientId: "tab-1", level: "warn", message: "careful" }],
+    pageMessages: ["older", "latest"],
+    pendingPageAsks: new Map([["ask-1", pending]]),
+  };
+
+  assert.deepEqual(planToolCall("inject_js", { code: "1 + 1", timeout_ms: 0 }, state), {
+    kind: "eval",
+    clientId: "tab-1",
+    code: "1 + 1",
+    timeoutMs: 15000,
+  });
+  assert.deepEqual(planToolCall("get_console_logs", { level: "warn", clear: true }, state), {
+    kind: "consoleLogs",
+    logs: [{ clientId: "tab-1", level: "warn", message: "careful" }],
+    clear: true,
+  });
+  assert.deepEqual(planToolCall("get_page_messages", { limit: 1 }, state), {
+    kind: "result",
+    value: ["latest"],
+  });
+  assert.deepEqual(planToolCall("reply_to_page", { ask_id: "ask-1", reply: "Looks good" }, state), {
+    kind: "replyToPage",
+    askId: "ask-1",
+    pending,
+    payload: { type: MESSAGE_TYPES.ASK_REPLY, id: "ask-1", reply: "Looks good" },
+    result: { ok: true, repliedTo: "Cart (https://example.test/cart)" },
+  });
+  assert.deepEqual(planToolCall("missing_tool", {}, state), {
+    kind: "unknown",
+    toolName: "missing_tool",
+  });
+});

package/providers/detour/src/react-context-core.js

@@ -0,0 +1,143 @@
+// Internal React component names to skip
+const INTERNAL_NAMES = new Set([
+  "Fragment", "Suspense", "StrictMode", "Profiler", "Portal",
+  "Provider", "Consumer", "Context", "ForwardRef", "Memo",
+  "InnerLayoutRouter", "ErrorBoundary", "AppRouter", "RenderFromTemplateContext",
+  "ScrollAndFocusHandler", "RedirectBoundary", "NotFoundBoundary",
+  "HotReload", "Router", "RouterContext",
+]);
+
+const LIBRARY_PREFIXES = [
+  "motion.", "styled.", "chakra.", "ark.", "radix.",
+  "Transition", "AnimatePresence",
+];
+
+function isUsefulComponentName(name) {
+  if (!name || typeof name !== "string") return false;
+  if (INTERNAL_NAMES.has(name)) return false;
+  if (LIBRARY_PREFIXES.some((prefix) => name.startsWith(prefix))) return false;
+  if (name.length <= 1) return false;
+  return true;
+}
+
+/**
+ * Check if React is present on the page.
+ */
+export function isReactDetectedWithBippy(bippy, documentRef) {
+  if (!bippy) return false;
+  // Check for React root markers
+  const roots = documentRef.querySelectorAll("[data-reactroot], #__next, #root, #app");
+  for (const root of roots) {
+    const keys = Object.keys(root);
+    if (keys.some((key) => key.startsWith("__reactFiber") || key.startsWith("__reactInternalInstance"))) {
+      return true;
+    }
+  }
+  // Broader check — any element with fiber
+  try {
+    const fiber = bippy.getFiberFromHostInstance(documentRef.body);
+    return fiber != null;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Get React Fiber from a DOM element.
+ */
+function getFiber(bippy, element) {
+  if (!bippy || !element) return null;
+  try {
+    return bippy.getFiberFromHostInstance(element);
+  } catch {
+    // Manual fallback: check __reactFiber$ keys
+    const keys = Object.keys(element);
+    const fiberKey = keys.find((key) => key.startsWith("__reactFiber$") || key.startsWith("__reactInternalInstance$"));
+    return fiberKey ? element[fiberKey] : null;
+  }
+}
+
+/**
+ * Get the display name of a fiber.
+ */
+function getFiberName(fiber) {
+  if (!fiber || !fiber.type) return null;
+  if (typeof fiber.type === "string") return null; // HTML element, not component
+  return fiber.type.displayName || fiber.type.name || null;
+}
+
+/**
+ * Walk up the fiber tree to find useful component names.
+ */
+function getComponentHierarchy(bippy, element, maxDepth = 10) {
+  const fiber = getFiber(bippy, element);
+  if (!fiber) return [];
+
+  const components = [];
+  let current = fiber;
+  let depth = 0;
+
+  while (current && depth < maxDepth) {
+    const name = getFiberName(current);
+    if (isUsefulComponentName(name)) {
+      components.push(name);
+    }
+    current = current.return;
+    depth++;
+  }
+
+  return components;
+}
+
+/**
+ * Get the nearest useful React component name for an element.
+ */
+export function getNearestComponentNameWithBippy(bippy, element) {
+  const hierarchy = getComponentHierarchy(bippy, element, 20);
+  return hierarchy.length > 0 ? hierarchy[0] : null;
+}
+
+/**
+ * Get source file location from React fiber debug info.
+ * Only available in development builds.
+ */
+function getSourceLocation(bippy, element) {
+  const fiber = getFiber(bippy, element);
+  if (!fiber) return null;
+
+  let current = fiber;
+  let depth = 0;
+  while (current && depth < 20) {
+    const source = current._debugSource;
+    if (source && source.fileName) {
+      return {
+        fileName: source.fileName,
+        lineNumber: source.lineNumber || null,
+        columnNumber: source.columnNumber || null,
+      };
+    }
+    current = current.return;
+    depth++;
+  }
+  return null;
+}
+
+/**
+ * Get full React context for an element — component hierarchy, source, props summary.
+ */
+export function getReactContextWithBippy(bippy, element) {
+  if (!bippy && !getFiber(bippy, element)) return null;
+
+  const hierarchy = getComponentHierarchy(bippy, element, 15);
+  const source = getSourceLocation(bippy, element);
+  const nearest = hierarchy.length > 0 ? hierarchy[0] : null;
+
+  if (!nearest && !source) return null;
+
+  return {
+    component: nearest,
+    hierarchy: hierarchy.length > 0 ? hierarchy : undefined,
+    source: source || undefined,
+    reactDetected: true,
+  };
+}

package/providers/detour/src/react-context.js

@@ -0,0 +1,44 @@
+/**
+ * React Context Extraction — best-effort React component info from DOM elements.
+ *
+ * Uses bippy for React Fiber traversal when React is detected on the page.
+ * Gracefully degrades to null when React is not present or fibers are inaccessible.
+ */
+
+import {
+  getNearestComponentNameWithBippy,
+  getReactContextWithBippy,
+  isReactDetectedWithBippy,
+} from "./react-context-core.js";
+
+let bippy = null;
+
+// bippy is bundled at build time via esbuild
+try {
+  // Dynamic require at bundle time — esbuild will resolve this
+  bippy = require("bippy");
+} catch {
+  // bippy not available — React extraction will be skipped
+}
+
+/**
+ * Check if React is present on the page.
+ */
+export function isReactDetected() {
+  if (!bippy) return false;
+  return isReactDetectedWithBippy(bippy, document);
+}
+
+/**
+ * Get the nearest useful React component name for an element.
+ */
+export function getNearestComponentName(element) {
+  return getNearestComponentNameWithBippy(bippy, element);
+}
+
+/**
+ * Get full React context for an element — component hierarchy, source, props summary.
+ */
+export function getReactContext(element) {
+  return getReactContextWithBippy(bippy, element);
+}

package/providers/detour/src/react-context.test.mjs

@@ -0,0 +1,41 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { getNearestComponentName, getReactContext, isReactDetected } from "./react-context.js";
+
+function reactFiberLikeElement() {
+  const appFiber = {
+    type: { name: "CheckoutPage" },
+    _debugSource: { fileName: "/src/CheckoutPage.jsx", lineNumber: 12, columnNumber: 4 },
+    return: null,
+  };
+  const buttonFiber = {
+    type: { displayName: "PayButton" },
+    return: appFiber,
+  };
+  return {
+    "__reactFiber$detour": {
+      type: "button",
+      return: buttonFiber,
+    },
+  };
+}
+
+test("React detection degrades to false without bundled bippy", () => {
+  const root = reactFiberLikeElement();
+  globalThis.document = {
+    querySelectorAll: () => [root],
+    body: root,
+  };
+
+  // In Node ESM, react-context.js intentionally imports with bippy unavailable;
+  // these browserless tests lock the public graceful-degradation behavior.
+  assert.equal(isReactDetected(), false);
+});
+
+test("React context exports return null for fiber-like elements without bippy", () => {
+  const element = reactFiberLikeElement();
+
+  assert.equal(getNearestComponentName(element), null);
+  assert.equal(getReactContext(element), null);
+});

package/providers/templates/README.md

@@ -0,0 +1,23 @@
+# Tap provider templates
+
+These templates are intentionally dependency-free starting points for external
+providers. They normalize events and tool shapes; real credentials and API calls
+belong in environment-specific adapters.
+
+Each template follows the same contract:
+
+1. Read provider token from `TAP_PROVIDER_TOKEN` or the tap token file.
+2. Connect to `ws://127.0.0.1:9400`.
+3. Authenticate and declare tools.
+4. Emit normalized event JSON suitable for EventFilter rules.
+
+Templates:
+
+- `ci-review-provider.mjs` — structured code review findings.
+- `jira-github-provider.mjs` — Jira issue and GitHub PR handoff shape.
+- `sast-triage-provider.mjs` — security finding triage and fingerprinting.
+- `detour-workflow-provider.mjs` — browser/Detour event normalization.
+
+These are not production integrations by themselves. They are safe scaffolds for
+turning CI, issue trackers, SAST scanners, and browser instrumentation into tap
+provider workflows.