@glasstrace/sdk 1.10.1 → 1.11.0

package/dist/chunk-KOYZJN6G.js

@@ -0,0 +1,651 @@
+import {
+  findMarkerBoundaries
+} from "./chunk-YIEXKQYP.js";
+
+// src/agent-detection/detect.ts
+import { execFile } from "node:child_process";
+import { access, stat } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { constants } from "node:fs";
+var AGENT_RULES = [
+  {
+    name: "claude",
+    markers: [".claude", "CLAUDE.md"],
+    mcpConfigPath: (dir) => join(dir, ".mcp.json"),
+    infoFilePath: (dir) => join(dir, "CLAUDE.md"),
+    cliBinary: "claude",
+    registrationCommand: "npx glasstrace mcp add --agent claude"
+  },
+  {
+    name: "codex",
+    // Codex 2026 default discovery is `AGENTS.override.md` → `AGENTS.md` →
+    // opt-in `project_doc_fallback_filenames`; `codex.md` is NOT in the
+    // default fallback list. Detection requires Codex-specific markers
+    // (`codex.md` legacy, `.codex/` config dir) — `AGENTS.md` is NOT
+    // included as a marker because the SDK now writes `AGENTS.md`
+    // broadly via the multi-target dispatcher's companion writes; if
+    // `AGENTS.md` were a Codex marker, every project with the SDK's
+    // own companion AGENTS.md would re-classify as Codex on subsequent
+    // detect runs and trigger unintended `.codex/config.toml` writes
+    // (Codex P1 + Copilot P1 review of Wave 18 PR #274). The canonical
+    // write destination remains AGENTS.md regardless of which marker
+    // classified the project.
+    markers: ["codex.md", ".codex"],
+    mcpConfigPath: (dir) => join(dir, ".codex", "config.toml"),
+    infoFilePath: (dir) => join(dir, "AGENTS.md"),
+    cliBinary: "codex",
+    registrationCommand: "npx glasstrace mcp add --agent codex"
+  },
+  {
+    name: "gemini",
+    markers: [".gemini", "GEMINI.md"],
+    mcpConfigPath: (dir) => join(dir, ".gemini", "settings.json"),
+    infoFilePath: (dir) => join(dir, "GEMINI.md"),
+    cliBinary: "gemini",
+    registrationCommand: "npx glasstrace mcp add --agent gemini"
+  },
+  {
+    name: "cursor",
+    // `.cursor/rules/*.mdc` is the current canonical format per Cursor's
+    // 2026 docs. `.cursorrules` (single file) is supported-but-deprecated
+    // and stays as a transitional fallback that the multi-target write
+    // helper writes unconditionally alongside the .mdc canonical.
+    markers: [".cursor", ".cursorrules"],
+    mcpConfigPath: (dir) => join(dir, ".cursor", "mcp.json"),
+    infoFilePath: (dir) => join(dir, ".cursor", "rules", "glasstrace.mdc"),
+    cliBinary: null,
+    registrationCommand: "npx glasstrace mcp add --agent cursor"
+  },
+  {
+    name: "windsurf",
+    // Windsurf's current canonical workspace-rules format is
+    // `.windsurf/rules/*.md`. AGENTS.md is a parallel cross-tool
+    // mechanism Windsurf also reads BUT is NOT included as a Windsurf
+    // detection marker — the SDK writes `AGENTS.md` broadly via the
+    // multi-target dispatcher's companion writes, so treating
+    // `AGENTS.md` as a Windsurf marker would re-classify every
+    // SDK-managed project as Windsurf and cause `glasstrace uninit`
+    // to mutate the global `~/.codeium/windsurf/mcp_config.json` for
+    // non-Windsurf projects (Codex P1 + Copilot P1 review of Wave 18
+    // PR #274). The single-file `.windsurfrules` is the deprecated
+    // legacy form — recognized as a marker so legacy projects classify
+    // correctly, but the SDK no longer writes to it.
+    markers: [".windsurf", ".windsurfrules"],
+    mcpConfigPath: () => join(homedir(), ".codeium", "windsurf", "mcp_config.json"),
+    infoFilePath: (dir) => join(dir, ".windsurf", "rules", "glasstrace.md"),
+    cliBinary: null,
+    registrationCommand: "npx glasstrace mcp add --agent windsurf"
+  }
+];
+async function pathExists(path, mode = constants.R_OK) {
+  try {
+    await access(path, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findGitRoot(startDir) {
+  let current = resolve(startDir);
+  while (true) {
+    if (await pathExists(join(current, ".git"), constants.F_OK)) {
+      return current;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return resolve(startDir);
+}
+function isCliAvailable(binary) {
+  return new Promise((resolve2) => {
+    const command = process.platform === "win32" ? "where" : "which";
+    execFile(command, [binary], (error) => {
+      resolve2(error === null);
+    });
+  });
+}
+async function detectAgents(projectRoot) {
+  const resolvedRoot = resolve(projectRoot);
+  let rootStat;
+  try {
+    rootStat = await stat(resolvedRoot);
+  } catch (err) {
+    const code = err.code;
+    throw new Error(
+      `projectRoot does not exist: ${resolvedRoot}` + (code ? ` (${code})` : "")
+    );
+  }
+  if (!rootStat.isDirectory()) {
+    throw new Error(`projectRoot is not a directory: ${resolvedRoot}`);
+  }
+  const gitRoot = await findGitRoot(resolvedRoot);
+  const searchDirs = [];
+  let current = resolvedRoot;
+  while (true) {
+    searchDirs.push(current);
+    if (current === gitRoot) {
+      break;
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  const detected = [];
+  const seenAgents = /* @__PURE__ */ new Set();
+  for (const rule of AGENT_RULES) {
+    let foundDir = null;
+    for (const dir of searchDirs) {
+      let markerFound = false;
+      for (const marker of rule.markers) {
+        if (await pathExists(join(dir, marker))) {
+          markerFound = true;
+          break;
+        }
+      }
+      if (markerFound) {
+        foundDir = dir;
+        break;
+      }
+    }
+    if (foundDir === null) {
+      continue;
+    }
+    if (seenAgents.has(rule.name)) {
+      continue;
+    }
+    seenAgents.add(rule.name);
+    const infoFilePath = rule.infoFilePath(foundDir);
+    const cliAvailable = rule.cliBinary ? await isCliAvailable(rule.cliBinary) : false;
+    detected.push({
+      name: rule.name,
+      mcpConfigPath: rule.mcpConfigPath(foundDir),
+      infoFilePath,
+      cliAvailable,
+      registrationCommand: rule.registrationCommand
+    });
+  }
+  detected.push({
+    name: "generic",
+    mcpConfigPath: join(resolvedRoot, ".glasstrace", "mcp.json"),
+    infoFilePath: join(resolvedRoot, "AGENTS.md"),
+    cliAvailable: false,
+    registrationCommand: null
+  });
+  return detected;
+}
+
+// src/agent-detection/agent-instruction-text.ts
+function buildAgentInstructionBody() {
+  return [
+    "",
+    "## Glasstrace MCP \u2014 Runtime Debugging Evidence",
+    "",
+    "Glasstrace is connected via MCP (`glasstrace`). It captures runtime traces from this app and exposes them through tools that disambiguate bugs source alone cannot resolve.",
+    "",
+    "### Call Glasstrace FIRST when:",
+    "- A value passed at runtime is suspect: wrong role, locale, timezone, template, tenant id, or any enum/config that branches downstream.",
+    "- The bug is in a side-effect operation: email sent, calendar event created, webhook dispatched, queued job, `after()` callback.",
+    "- The user reports a symptom but you do not yet know which code path actually executed.",
+    "- You need to confirm a route or procedure ran in the relevant time window before doing a source dive.",
+    "",
+    "### SKIP Glasstrace when:",
+    "- The bug is statically obvious from source (N+1 query, missing await, redundant query, type error, missing null check).",
+    "- The change is a refactor whose correctness does not depend on runtime behavior.",
+    "- You already have a precise traceId from another source.",
+    "",
+    "### Workflow",
+    "1. Start with `find_trace_candidates`. Pass whatever route or procedure name is natural \u2014 the server normalizes vocabulary and, on miss, returns close matches and a sample of routes actually present in the window.",
+    "2. Take the highest-confidence candidate's `suggestedFollowups` and pass them straight to `get_trace` or `get_root_cause`.",
+    "3. For side-effect bugs, read `sideEffectSummary` in the `get_trace` / `get_root_cause` response. The allowlisted fields (`templateKey`, `providerOperation`, `role`, `locale`, `timezone`, `status`, `phase`) are the ones that disambiguate payload bugs.",
+    "4. If a tool returns empty, READ the response's empty-result envelope before pivoting to source \u2014 each field disambiguates a different reason for the empty result:",
+    "   - `closeMatches` / `recentRoutesSample` \u2014 your filter vocabulary doesn't match server-side names; the server returns the closest known names + a sample of routes actually present.",
+    '   - `windowActivity` \u2014 load-bearing four-way distinguisher. `totalTracesInWindow === 0` AND `totalTracesInTenantEver > 0` means "your time window missed the activity"; `totalTracesInTenantEver === 0` means "this tenant has never produced traces" (SDK not registered, or never hit); `captureConfigBlocksRequest === true` means "the SDK\'s capture config dropped this route"; otherwise the empty result is a vocabulary miss \u2014 see `closeMatches`.',
+    "   - `humanReadable` \u2014 prose guidance written for the agent.",
+    "   - `recoveryActions` \u2014 concrete next-call shapes.",
+    "   - `diagnosticValue` / `recommendedNextStep` \u2014 whether to keep searching or stop.",
+    "   Empty results carry `notAbsenceProof: true` \u2014 they are never proof the bug did not occur.",
+    "",
+    "### Tools",
+    "- `find_trace_candidates` \u2014 discovery, vocabulary-tolerant filter",
+    "- `get_trace` \u2014 exact trace by `traceId`",
+    "- `get_root_cause` \u2014 root-cause analysis for a `traceId`",
+    "- `get_session_timeline` \u2014 events for a session",
+    "- `get_latest_error` / `get_error_list` \u2014 recent server errors",
+    "",
+    "Side-effect evidence is allowlisted and compact by design. Fields you don't see may have been omitted by policy, not absent at runtime.",
+    ""
+  ].join("\n");
+}
+
+// src/agent-detection/configs.ts
+function generateMcpConfig(agent, endpoint, bearer) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!bearer || bearer.trim() === "") {
+    throw new Error("bearer must not be empty");
+  }
+  switch (agent.name) {
+    case "claude":
+      return JSON.stringify(
+        {
+          mcpServers: {
+            glasstrace: {
+              type: "http",
+              url: endpoint,
+              headers: {
+                Authorization: `Bearer ${bearer}`
+              }
+            }
+          }
+        },
+        null,
+        2
+      );
+    case "codex": {
+      const safeEndpoint = endpoint.replace(/\\/g, "\\\\").replace(/"/g, '\\"').replace(/\n/g, "\\n").replace(/\r/g, "\\r").replace(/\t/g, "\\t");
+      return [
+        "[mcp_servers.glasstrace]",
+        `url = "${safeEndpoint}"`,
+        `bearer_token_env_var = "GLASSTRACE_API_KEY"`,
+        ""
+      ].join("\n");
+    }
+    case "gemini":
+      return JSON.stringify(
+        {
+          mcpServers: {
+            glasstrace: {
+              httpUrl: endpoint,
+              headers: {
+                Authorization: `Bearer ${bearer}`
+              }
+            }
+          }
+        },
+        null,
+        2
+      );
+    case "cursor":
+      return JSON.stringify(
+        {
+          mcpServers: {
+            glasstrace: {
+              type: "http",
+              url: endpoint,
+              headers: {
+                Authorization: `Bearer ${bearer}`
+              }
+            }
+          }
+        },
+        null,
+        2
+      );
+    case "windsurf":
+      return JSON.stringify(
+        {
+          mcpServers: {
+            glasstrace: {
+              type: "http",
+              url: endpoint,
+              headers: {
+                Authorization: `Bearer ${bearer}`
+              }
+            }
+          }
+        },
+        null,
+        2
+      );
+    case "generic":
+      return JSON.stringify(
+        {
+          mcpServers: {
+            glasstrace: {
+              type: "http",
+              url: endpoint,
+              headers: {
+                Authorization: `Bearer ${bearer}`
+              }
+            }
+          }
+        },
+        null,
+        2
+      );
+    default: {
+      const _exhaustive = agent.name;
+      throw new Error(`Unknown agent: ${_exhaustive}`);
+    }
+  }
+}
+var SDK_VERSION_STAMP_PATTERN = /^[A-Za-z0-9.+-]+$/;
+function htmlMarkers(sdkVersion) {
+  return {
+    start: `<!-- glasstrace:mcp:start v=${sdkVersion} -->`,
+    end: "<!-- glasstrace:mcp:end -->"
+  };
+}
+function hashMarkers(sdkVersion) {
+  return {
+    start: `# glasstrace:mcp:start v=${sdkVersion}`,
+    end: "# glasstrace:mcp:end"
+  };
+}
+function generateInfoSection(agent, endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
+  }
+  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {
+    throw new Error(
+      "sdkVersion must match [A-Za-z0-9.+\\-]+ (semver-shaped, no whitespace, no angle brackets)"
+    );
+  }
+  const content = buildAgentInstructionBody();
+  switch (agent.name) {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "windsurf":
+    case "generic": {
+      const m = htmlMarkers(sdkVersion);
+      return `${m.start}
+${content}${m.end}
+`;
+    }
+    case "cursor": {
+      const m = htmlMarkers(sdkVersion);
+      return `${m.start}
+${content}${m.end}
+`;
+    }
+    default: {
+      const _exhaustive = agent.name;
+      throw new Error(`Unknown agent: ${_exhaustive}`);
+    }
+  }
+}
+function generateInfoSectionForCursorrulesLegacy(endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
+  }
+  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {
+    throw new Error(
+      "sdkVersion must match [A-Za-z0-9.+\\-]+ (semver-shaped, no whitespace, no angle brackets)"
+    );
+  }
+  const content = buildAgentInstructionBody();
+  const m = hashMarkers(sdkVersion);
+  return `${m.start}
+${content}${m.end}
+`;
+}
+function generateInfoSectionForCursorMdc(endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
+  }
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
+  }
+  if (!SDK_VERSION_STAMP_PATTERN.test(sdkVersion)) {
+    throw new Error(
+      "sdkVersion must match [A-Za-z0-9.+\\-]+ (semver-shaped, no whitespace, no angle brackets)"
+    );
+  }
+  const content = buildAgentInstructionBody();
+  const m = htmlMarkers(sdkVersion);
+  return [
+    "---",
+    "description: Glasstrace MCP runtime debugging tools \u2014 runtime evidence the agent reads when source alone cannot resolve a bug",
+    "alwaysApply: true",
+    "---",
+    "",
+    `${m.start}
+${content}${m.end}
+`
+  ].join("\n");
+}
+
+// src/agent-detection/inject-all-targets.ts
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname as dirname2, join as join2 } from "node:path";
+async function injectAllTargets(agents, endpoint, sdkVersion, projectRoot) {
+  const writtenAgentsMd = /* @__PURE__ */ new Set();
+  for (const agent of agents) {
+    const targets = computeTargets(agent, projectRoot);
+    for (const target of targets) {
+      if (target.isAgentsMdCompanion) {
+        if (writtenAgentsMd.has(target.path)) {
+          continue;
+        }
+        writtenAgentsMd.add(target.path);
+      }
+      let createContent;
+      let managedSectionOnly;
+      if (target.kind === "cursor-mdc") {
+        createContent = generateInfoSectionForCursorMdc(endpoint, sdkVersion);
+        managedSectionOnly = generateInfoSection(agent, endpoint, sdkVersion);
+      } else if (target.kind === "cursorrules-legacy") {
+        createContent = generateInfoSectionForCursorrulesLegacy(
+          endpoint,
+          sdkVersion
+        );
+        managedSectionOnly = createContent;
+      } else {
+        createContent = generateInfoSection(agent, endpoint, sdkVersion);
+        managedSectionOnly = createContent;
+      }
+      if (managedSectionOnly === "") continue;
+      await writeManagedSectionToTarget(
+        target.path,
+        createContent,
+        managedSectionOnly
+      );
+    }
+  }
+}
+function foundDirFromAgent(agent) {
+  if (agent.infoFilePath === null) return null;
+  switch (agent.name) {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "generic":
+      return dirname2(agent.infoFilePath);
+    case "cursor":
+      return dirname2(dirname2(dirname2(agent.infoFilePath)));
+    case "windsurf":
+      return dirname2(dirname2(dirname2(agent.infoFilePath)));
+  }
+}
+function computeTargets(agent, projectRoot) {
+  const targets = [];
+  const foundDir = foundDirFromAgent(agent) ?? projectRoot;
+  switch (agent.name) {
+    case "claude": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: join2(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "codex": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: true
+        });
+      }
+      return targets;
+    }
+    case "gemini": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: join2(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "cursor": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "cursor-mdc",
+          isAgentsMdCompanion: false
+        });
+        targets.push({
+          path: join2(foundDir, ".cursorrules"),
+          kind: "cursorrules-legacy",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: join2(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "windsurf": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: join2(foundDir, "AGENTS.md"),
+        kind: "agents-md-companion",
+        isAgentsMdCompanion: true
+      });
+      return targets;
+    }
+    case "generic": {
+      if (agent.infoFilePath) {
+        targets.push({
+          path: agent.infoFilePath,
+          kind: "primary",
+          isAgentsMdCompanion: true
+        });
+      }
+      return targets;
+    }
+    default: {
+      const _exhaustive = agent.name;
+      throw new Error(`Unknown agent: ${_exhaustive}`);
+    }
+  }
+}
+async function writeManagedSectionToTarget(filePath, createContent, managedSectionOnly) {
+  let existingContent = null;
+  try {
+    existingContent = await readFile(filePath, "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      emitTargetWarning(filePath, "read", err);
+      return;
+    }
+  }
+  if (existingContent === null) {
+    try {
+      await mkdir(dirname2(filePath), { recursive: true });
+      await writeFile(filePath, createContent, "utf-8");
+    } catch (err) {
+      emitTargetWarning(filePath, "write", err);
+      return;
+    }
+    return;
+  }
+  const lines = existingContent.split("\n");
+  const boundaries = findMarkerBoundaries(lines);
+  let newContent;
+  if (boundaries !== null) {
+    const before = lines.slice(0, boundaries.startIdx);
+    const after = lines.slice(boundaries.endIdx + 1);
+    const contentWithoutTrailingNewline = managedSectionOnly.endsWith("\n") ? managedSectionOnly.slice(0, -1) : managedSectionOnly;
+    newContent = [...before, contentWithoutTrailingNewline, ...after].join(
+      "\n"
+    );
+  } else {
+    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+    newContent = existingContent + separator + managedSectionOnly;
+  }
+  try {
+    await writeFile(filePath, newContent, "utf-8");
+  } catch (err) {
+    emitTargetWarning(filePath, "write", err);
+  }
+}
+function emitTargetWarning(filePath, op, err) {
+  const code = err.code;
+  let qualifier;
+  switch (code) {
+    case "EACCES":
+    case "EPERM":
+      qualifier = "permission denied";
+      break;
+    case "EROFS":
+      qualifier = "filesystem read-only";
+      break;
+    case "ENOSPC":
+      qualifier = "disk full";
+      break;
+    case "ENAMETOOLONG":
+      qualifier = "path too long";
+      break;
+    case "ENOTDIR":
+      qualifier = "not a directory";
+      break;
+    case "EISDIR":
+      qualifier = "is a directory";
+      break;
+    default:
+      qualifier = "I/O error";
+      break;
+  }
+  try {
+    process.stderr.write(
+      `Warning: cannot ${op} info file ${filePath}: ${qualifier}
+`
+    );
+  } catch {
+  }
+}
+
+export {
+  detectAgents,
+  generateMcpConfig,
+  injectAllTargets
+};
+//# sourceMappingURL=chunk-KOYZJN6G.js.map