@glasstrace/sdk 1.4.0 → 1.5.0

package/dist/cli/uninit.d.cts

@@ -125,8 +125,16 @@ declare function isInitCreatedInstrumentation(content: string): boolean;
 declare function removeRegisterGlasstrace(content: string): string;
 /**
  * Removes content between glasstrace marker comments from a file.
- * Supports both HTML markers (`<!-- glasstrace:mcp:start/end -->`) and
- * hash markers (`# glasstrace:mcp:start/end`).
+ * Supports both legacy unstamped markers (pre-SDK-050) and SDK-050+
+ * stamped markers (`<!-- glasstrace:mcp:start v=<sdkVersion> -->` /
+ * `# glasstrace:mcp:start v=<sdkVersion>`) for both HTML and hash
+ * conventions, by deferring marker recognition to the shared parser
+ * in `agent-detection/inject.ts`.
+ *
+ * Anchoring matches `findMarkerBoundaries` in inject.ts: when multiple
+ * start markers appear before the first end marker (e.g. a quoted
+ * example marker line followed by the real managed block), the
+ * removal window anchors to the MOST RECENT start preceding the end.
  *
  * @internal Exported for unit testing only.
  */

package/dist/cli/uninit.d.ts

@@ -125,8 +125,16 @@ declare function isInitCreatedInstrumentation(content: string): boolean;
 declare function removeRegisterGlasstrace(content: string): string;
 /**
  * Removes content between glasstrace marker comments from a file.
- * Supports both HTML markers (`<!-- glasstrace:mcp:start/end -->`) and
- * hash markers (`# glasstrace:mcp:start/end`).
+ * Supports both legacy unstamped markers (pre-SDK-050) and SDK-050+
+ * stamped markers (`<!-- glasstrace:mcp:start v=<sdkVersion> -->` /
+ * `# glasstrace:mcp:start v=<sdkVersion>`) for both HTML and hash
+ * conventions, by deferring marker recognition to the shared parser
+ * in `agent-detection/inject.ts`.
+ *
+ * Anchoring matches `findMarkerBoundaries` in inject.ts: when multiple
+ * start markers appear before the first end marker (e.g. a quoted
+ * example marker line followed by the real managed block), the
+ * removal window anchors to the MOST RECENT start preceding the end.
  *
  * @internal Exported for unit testing only.
  */

package/dist/cli/uninit.js

@@ -12,10 +12,11 @@ import {
   unwrapCJSExport,
   unwrapExport,
   writeShutdownMarker
-} from "../chunk-VJQIFY33.js";
+} from "../chunk-YLY7AGLC.js";
 import "../chunk-MFYOQOD7.js";
 import "../chunk-4WI7B5FQ.js";
 import "../chunk-NB7GJE4S.js";
+import "../chunk-ZBQQXVHD.js";
 import "../chunk-NSBPE2FW.js";
 export {
   findMatchingDelimiter,

package/dist/cli/upgrade-instructions.cjs

@@ -0,0 +1,440 @@
+#!/usr/bin/env node
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/cli/upgrade-instructions.ts
+var upgrade_instructions_exports = {};
+__export(upgrade_instructions_exports, {
+  runUpgradeInstructions: () => runUpgradeInstructions
+});
+module.exports = __toCommonJS(upgrade_instructions_exports);
+var import_node_path3 = require("node:path");
+
+// src/mcp-runtime.ts
+var MCP_ENDPOINT = "https://api.glasstrace.dev/mcp";
+
+// src/agent-detection/detect.ts
+var import_node_child_process = require("node:child_process");
+var import_promises = require("node:fs/promises");
+var import_node_path = require("node:path");
+var import_node_os = require("node:os");
+var import_node_fs = require("node:fs");
+var AGENT_RULES = [
+  {
+    name: "claude",
+    markers: [".claude", "CLAUDE.md"],
+    mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".mcp.json"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, "CLAUDE.md"),
+    cliBinary: "claude",
+    registrationCommand: "npx glasstrace mcp add --agent claude"
+  },
+  {
+    name: "codex",
+    markers: ["codex.md", ".codex"],
+    mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".codex", "config.toml"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, "codex.md"),
+    cliBinary: "codex",
+    registrationCommand: "npx glasstrace mcp add --agent codex"
+  },
+  {
+    name: "gemini",
+    markers: [".gemini"],
+    mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".gemini", "settings.json"),
+    infoFilePath: () => null,
+    cliBinary: "gemini",
+    registrationCommand: "npx glasstrace mcp add --agent gemini"
+  },
+  {
+    name: "cursor",
+    markers: [".cursor", ".cursorrules"],
+    mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".cursor", "mcp.json"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".cursorrules"),
+    cliBinary: null,
+    registrationCommand: "npx glasstrace mcp add --agent cursor"
+  },
+  {
+    name: "windsurf",
+    markers: [".windsurfrules", ".windsurf"],
+    mcpConfigPath: () => (0, import_node_path.join)((0, import_node_os.homedir)(), ".codeium", "windsurf", "mcp_config.json"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".windsurfrules"),
+    cliBinary: null,
+    registrationCommand: "npx glasstrace mcp add --agent windsurf"
+  }
+];
+async function pathExists(path, mode = import_node_fs.constants.R_OK) {
+  try {
+    await (0, import_promises.access)(path, mode);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function findGitRoot(startDir) {
+  let current = (0, import_node_path.resolve)(startDir);
+  while (true) {
+    if (await pathExists((0, import_node_path.join)(current, ".git"), import_node_fs.constants.F_OK)) {
+      return current;
+    }
+    const parent = (0, import_node_path.dirname)(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+  return (0, import_node_path.resolve)(startDir);
+}
+function isCliAvailable(binary) {
+  return new Promise((resolve2) => {
+    const command = process.platform === "win32" ? "where" : "which";
+    (0, import_node_child_process.execFile)(command, [binary], (error) => {
+      resolve2(error === null);
+    });
+  });
+}
+async function detectAgents(projectRoot) {
+  const resolvedRoot = (0, import_node_path.resolve)(projectRoot);
+  let rootStat;
+  try {
+    rootStat = await (0, import_promises.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 = (0, import_node_path.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((0, import_node_path.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);
+    let infoFilePath = rule.infoFilePath(foundDir);
+    if (infoFilePath !== null && !await pathExists(infoFilePath)) {
+      infoFilePath = null;
+    }
+    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: (0, import_node_path.join)(resolvedRoot, ".glasstrace", "mcp.json"),
+    infoFilePath: null,
+    cliAvailable: false,
+    registrationCommand: null
+  });
+  return detected;
+}
+
+// src/agent-detection/configs.ts
+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 = [
+    "",
+    "## Glasstrace MCP Integration",
+    "",
+    `Glasstrace is configured as an MCP server at: ${endpoint}`,
+    "",
+    "Glasstrace MCP is available when runtime evidence would materially reduce uncertainty. Use it when there is a failing request, stack trace, unclear runtime behavior, race/data-flow symptom, side effect, or performance issue that source inspection alone does not explain. For a current error, `get_latest_error` or `get_error_list` is usually the cheapest orientation call. For a known route/procedure with no exact error, use `find_trace_candidates` and follow returned exact `get_trace` or `get_root_cause` arguments only if the candidates look relevant. Do not call trace tools for trivial source-local fixes. Treat **no candidates** or **no_traces_found** as a scoped retrieval result, not proof the bug is absent.",
+    "",
+    "Available tools:",
+    "- `get_latest_error` - Get the most recent error trace from the current session",
+    "- `find_trace_candidates` - First-contact route/procedure/URL candidate selection when you have a route fragment, tRPC procedure, method, status, or rough recent activity window but not the exact trace ID. Returns candidate traces plus suggested `get_trace` / `get_root_cause` follow-up call arguments. Candidate discovery, not root-cause proof.",
+    "- `get_error_list` - List recent errors with filtering and pagination",
+    "- `get_trace` - Get a specific trace by ID or URL pattern",
+    "- `get_root_cause` - Get the root cause analysis for a specific error trace (requires a `traceId` from `get_latest_error`, `get_error_list`, or `get_trace`)",
+    "- `get_test_suggestions` - Get test suggestions based on recent errors",
+    "- `get_session_timeline` - Get the timeline of all traces in the current session",
+    "",
+    "To refresh this managed section after a `@glasstrace/sdk` upgrade, run: `npx glasstrace upgrade-instructions`. To reconfigure MCP credentials, run: `npx glasstrace mcp add`.",
+    ""
+  ].join("\n");
+  switch (agent.name) {
+    case "claude": {
+      const m = htmlMarkers(sdkVersion);
+      return `${m.start}
+${content}${m.end}
+`;
+    }
+    case "codex": {
+      const m = htmlMarkers(sdkVersion);
+      return `${m.start}
+${content}${m.end}
+`;
+    }
+    case "cursor": {
+      const m = hashMarkers(sdkVersion);
+      return `${m.start}
+${content}${m.end}
+`;
+    }
+    case "gemini":
+    case "windsurf":
+    case "generic":
+      return "";
+    default: {
+      const _exhaustive = agent.name;
+      throw new Error(`Unknown agent: ${_exhaustive}`);
+    }
+  }
+}
+
+// src/agent-detection/inject.ts
+var import_promises2 = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+var HTML_START_RE = /^<!--\s*glasstrace:mcp:start(?:\s+v=([^\s>]+))?\s*-->$/;
+var HTML_END = "<!-- glasstrace:mcp:end -->";
+var HASH_START_RE = /^#\s*glasstrace:mcp:start(?:\s+v=(\S+))?$/;
+var HASH_END = "# glasstrace:mcp:end";
+function parseStartMarkerLine(line) {
+  const trimmed = line.trim();
+  const html = HTML_START_RE.exec(trimmed);
+  if (html !== null) {
+    return { kind: "html", stamp: html[1] ?? null };
+  }
+  const hash = HASH_START_RE.exec(trimmed);
+  if (hash !== null) {
+    return { kind: "hash", stamp: hash[1] ?? null };
+  }
+  return null;
+}
+function isEndMarker(line) {
+  const trimmed = line.trim();
+  return trimmed === HTML_END || trimmed === HASH_END;
+}
+function isPermissionError(err) {
+  const code = err.code;
+  return code === "EACCES" || code === "EPERM" || code === "EROFS";
+}
+function findMarkerBoundaries(lines) {
+  let startIdx = -1;
+  for (let i = 0; i < lines.length; i++) {
+    if (parseStartMarkerLine(lines[i]) !== null) {
+      startIdx = i;
+    } else if (startIdx !== -1 && isEndMarker(lines[i])) {
+      return { startIdx, endIdx: i };
+    }
+  }
+  return null;
+}
+async function injectInfoSection(agent, content, projectRoot) {
+  if (agent.infoFilePath === null) {
+    return;
+  }
+  if (content === "") {
+    return;
+  }
+  const filePath = agent.infoFilePath;
+  let existingContent = null;
+  try {
+    existingContent = await (0, import_promises2.readFile)(filePath, "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      if (isPermissionError(err)) {
+        process.stderr.write(
+          `Warning: cannot read info file ${filePath}: permission denied
+`
+        );
+        return;
+      }
+      throw err;
+    }
+  }
+  if (existingContent === null) {
+    try {
+      await (0, import_promises2.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true });
+      await (0, import_promises2.writeFile)(filePath, content, "utf-8");
+    } catch (err) {
+      if (isPermissionError(err)) {
+        process.stderr.write(
+          `Warning: cannot write info file ${filePath}: permission denied
+`
+        );
+        return;
+      }
+      throw err;
+    }
+    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 = content.endsWith("\n") ? content.slice(0, -1) : content;
+    newContent = [...before, contentWithoutTrailingNewline, ...after].join("\n");
+  } else {
+    const separator = existingContent.endsWith("\n") ? "\n" : "\n\n";
+    newContent = existingContent + separator + content;
+  }
+  try {
+    await (0, import_promises2.writeFile)(filePath, newContent, "utf-8");
+  } catch (err) {
+    if (isPermissionError(err)) {
+      process.stderr.write(
+        `Warning: cannot write info file ${filePath}: permission denied
+`
+      );
+      return;
+    }
+    throw err;
+  }
+}
+async function hasManagedSection(filePath) {
+  let content;
+  try {
+    content = await (0, import_promises2.readFile)(filePath, "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") return false;
+    throw err;
+  }
+  return findMarkerBoundaries(content.split("\n")) !== null;
+}
+
+// src/cli/upgrade-instructions.ts
+function formatPathForOutput(filePath, projectRoot) {
+  const rel = (0, import_node_path3.relative)(projectRoot, filePath);
+  if (rel === "" || rel.startsWith("..") || (0, import_node_path3.isAbsolute)(rel)) {
+    return filePath;
+  }
+  return rel;
+}
+async function runUpgradeInstructions(options) {
+  const refreshed = [];
+  const skipped = [];
+  const warnings = [];
+  const errors = [];
+  let agents;
+  try {
+    agents = await detectAgents(options.projectRoot);
+  } catch (err) {
+    errors.push(
+      `Failed to detect agents: ${err instanceof Error ? err.message : String(err)}`
+    );
+    return { exitCode: 1, refreshed, skipped, warnings, errors };
+  }
+  const sdkVersion = true ? "1.5.0" : "0.0.0-dev";
+  for (const agent of agents) {
+    if (agent.infoFilePath === null) {
+      continue;
+    }
+    const displayPath = formatPathForOutput(
+      agent.infoFilePath,
+      options.projectRoot
+    );
+    let containsSection;
+    try {
+      containsSection = await hasManagedSection(agent.infoFilePath);
+    } catch (err) {
+      warnings.push(
+        `Could not inspect ${displayPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+      continue;
+    }
+    if (!containsSection) {
+      skipped.push(displayPath);
+      continue;
+    }
+    const content = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
+    if (content === "") {
+      continue;
+    }
+    try {
+      await injectInfoSection(agent, content, options.projectRoot);
+      refreshed.push(displayPath);
+    } catch (err) {
+      errors.push(
+        `Failed to refresh ${displayPath}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+  }
+  const exitCode = errors.length === 0 ? 0 : 1;
+  return { exitCode, refreshed, skipped, warnings, errors };
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  runUpgradeInstructions
+});
+//# sourceMappingURL=upgrade-instructions.cjs.map