@glasstrace/sdk 1.10.2 → 1.12.0

package/dist/cli/uninit.js

@@ -12,11 +12,11 @@ import {
   unwrapCJSExport,
   unwrapExport,
   writeShutdownMarker
-} from "../chunk-UMGZJYC4.js";
-import "../chunk-RL43PU2X.js";
-import "../chunk-6RKS3DNA.js";
+} from "../chunk-V75ZB4G4.js";
+import "../chunk-J3ZCVE67.js";
+import "../chunk-BN5DVIUO.js";
 import "../chunk-NB7GJE4S.js";
-import "../chunk-ZBQQXVHD.js";
+import "../chunk-YIEXKQYP.js";
 import "../chunk-NSBPE2FW.js";
 export {
   findMatchingDelimiter,

package/dist/cli/upgrade-instructions.cjs

@@ -46,33 +46,61 @@ var AGENT_RULES = [
   },
   {
     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) => (0, import_node_path.join)(dir, ".codex", "config.toml"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, "codex.md"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, "AGENTS.md"),
     cliBinary: "codex",
     registrationCommand: "npx glasstrace mcp add --agent codex"
   },
   {
     name: "gemini",
-    markers: [".gemini"],
+    markers: [".gemini", "GEMINI.md"],
     mcpConfigPath: (dir) => (0, import_node_path.join)(dir, ".gemini", "settings.json"),
-    infoFilePath: () => null,
+    infoFilePath: (dir) => (0, import_node_path.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) => (0, import_node_path.join)(dir, ".cursor", "mcp.json"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".cursorrules"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".cursor", "rules", "glasstrace.mdc"),
     cliBinary: null,
     registrationCommand: "npx glasstrace mcp add --agent cursor"
   },
   {
     name: "windsurf",
-    markers: [".windsurfrules", ".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: () => (0, import_node_path.join)((0, import_node_os.homedir)(), ".codeium", "windsurf", "mcp_config.json"),
-    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".windsurfrules"),
+    infoFilePath: (dir) => (0, import_node_path.join)(dir, ".windsurf", "rules", "glasstrace.md"),
     cliBinary: null,
     registrationCommand: "npx glasstrace mcp add --agent windsurf"
   }
@@ -159,10 +187,7 @@ async function detectAgents(projectRoot) {
       continue;
     }
     seenAgents.add(rule.name);
-    let infoFilePath = rule.infoFilePath(foundDir);
-    if (infoFilePath !== null && !await pathExists(infoFilePath)) {
-      infoFilePath = null;
-    }
+    const infoFilePath = rule.infoFilePath(foundDir);
     const cliAvailable = rule.cliBinary ? await isCliAvailable(rule.cliBinary) : false;
     detected.push({
       name: rule.name,
@@ -175,13 +200,62 @@ async function detectAgents(projectRoot) {
   detected.push({
     name: "generic",
     mcpConfigPath: (0, import_node_path.join)(resolvedRoot, ".glasstrace", "mcp.json"),
-    infoFilePath: null,
+    infoFilePath: (0, import_node_path.join)(resolvedRoot, "AGENTS.md"),
     cliAvailable: false,
     registrationCommand: null
   });
   return detected;
 }
 
+// src/agent-detection/inject.ts
+var import_promises2 = require("node:fs/promises");
+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 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 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/agent-detection/inject-all-targets.ts
+var import_promises3 = require("node:fs/promises");
+var import_node_path2 = require("node:path");
+
 // src/agent-detection/agent-instruction-text.ts
 function buildAgentInstructionBody() {
   return [
@@ -253,110 +327,235 @@ function generateInfoSection(agent, endpoint, sdkVersion) {
   }
   const content = buildAgentInstructionBody();
   switch (agent.name) {
-    case "claude": {
-      const m = htmlMarkers(sdkVersion);
-      return `${m.start}
-${content}${m.end}
-`;
-    }
-    case "codex": {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "windsurf":
+    case "generic": {
       const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "cursor": {
-      const m = hashMarkers(sdkVersion);
+      const m = htmlMarkers(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 };
+function generateInfoSectionForCursorrulesLegacy(endpoint, sdkVersion) {
+  if (!endpoint || endpoint.trim() === "") {
+    throw new Error("endpoint must not be empty");
   }
-  const hash = HASH_START_RE.exec(trimmed);
-  if (hash !== null) {
-    return { kind: "hash", stamp: hash[1] ?? null };
+  if (!sdkVersion || sdkVersion.trim() === "") {
+    throw new Error("sdkVersion must not be empty");
   }
-  return null;
-}
-function isEndMarker(line) {
-  const trimmed = line.trim();
-  return trimmed === HTML_END || trimmed === HASH_END;
+  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 isPermissionError(err) {
-  const code = err.code;
-  return code === "EACCES" || code === "EPERM" || code === "EROFS";
+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");
 }
-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 };
+
+// src/agent-detection/inject-all-targets.ts
+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
+      );
     }
   }
-  return null;
 }
-async function injectInfoSection(agent, content, projectRoot) {
-  if (agent.infoFilePath === null) {
-    return;
+function foundDirFromAgent(agent) {
+  if (agent.infoFilePath === null) return null;
+  switch (agent.name) {
+    case "claude":
+    case "codex":
+    case "gemini":
+    case "generic":
+      return (0, import_node_path2.dirname)(agent.infoFilePath);
+    case "cursor":
+      return (0, import_node_path2.dirname)((0, import_node_path2.dirname)((0, import_node_path2.dirname)(agent.infoFilePath)));
+    case "windsurf":
+      return (0, import_node_path2.dirname)((0, import_node_path2.dirname)((0, import_node_path2.dirname)(agent.infoFilePath)));
   }
-  if (content === "") {
-    return;
+}
+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: (0, import_node_path2.join)(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: (0, import_node_path2.join)(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: (0, import_node_path2.join)(foundDir, ".cursorrules"),
+          kind: "cursorrules-legacy",
+          isAgentsMdCompanion: false
+        });
+      }
+      targets.push({
+        path: (0, import_node_path2.join)(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: (0, import_node_path2.join)(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}`);
+    }
   }
-  const filePath = agent.infoFilePath;
+}
+async function writeManagedSectionToTarget(filePath, createContent, managedSectionOnly) {
   let existingContent = null;
   try {
-    existingContent = await (0, import_promises2.readFile)(filePath, "utf-8");
+    existingContent = await (0, import_promises3.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;
+      emitTargetWarning(filePath, "read", err);
+      return;
     }
   }
   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");
+      await (0, import_promises3.mkdir)((0, import_node_path2.dirname)(filePath), { recursive: true });
+      await (0, import_promises3.writeFile)(filePath, createContent, "utf-8");
     } catch (err) {
-      if (isPermissionError(err)) {
-        process.stderr.write(
-          `Warning: cannot write info file ${filePath}: permission denied
-`
-        );
-        return;
-      }
-      throw err;
+      emitTargetWarning(filePath, "write", err);
+      return;
     }
     return;
   }
@@ -366,38 +565,89 @@ async function injectInfoSection(agent, content, projectRoot) {
   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");
+    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 + content;
+    newContent = existingContent + separator + managedSectionOnly;
   }
   try {
-    await (0, import_promises2.writeFile)(filePath, newContent, "utf-8");
+    await (0, import_promises3.writeFile)(filePath, newContent, "utf-8");
   } catch (err) {
-    if (isPermissionError(err)) {
-      process.stderr.write(
-        `Warning: cannot write info file ${filePath}: permission denied
-`
-      );
-      return;
-    }
-    throw err;
+    emitTargetWarning(filePath, "write", err);
   }
 }
-async function hasManagedSection(filePath) {
-  let content;
+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 {
-    content = await (0, import_promises2.readFile)(filePath, "utf-8");
-  } catch (err) {
-    const code = err.code;
-    if (code === "ENOENT") return false;
-    throw err;
+    process.stderr.write(
+      `Warning: cannot ${op} info file ${filePath}: ${qualifier}
+`
+    );
+  } catch {
   }
-  return findMarkerBoundaries(content.split("\n")) !== null;
 }
 
 // src/cli/upgrade-instructions.ts
+function legacyDestinationsForAgent(agent) {
+  if (agent.infoFilePath === null) {
+    return [];
+  }
+  switch (agent.name) {
+    case "codex":
+      return [(0, import_node_path3.join)((0, import_node_path3.dirname)(agent.infoFilePath), "codex.md")];
+    case "cursor":
+      return [
+        (0, import_node_path3.join)((0, import_node_path3.dirname)((0, import_node_path3.dirname)((0, import_node_path3.dirname)(agent.infoFilePath))), ".cursorrules")
+      ];
+    case "windsurf":
+      return [
+        (0, import_node_path3.join)(
+          (0, import_node_path3.dirname)((0, import_node_path3.dirname)((0, import_node_path3.dirname)(agent.infoFilePath))),
+          ".windsurfrules"
+        )
+      ];
+    case "claude":
+    case "gemini":
+    case "generic":
+      return [];
+  }
+}
+async function anyHasManagedSection(paths) {
+  for (const p of paths) {
+    if (await hasManagedSection(p)) {
+      return true;
+    }
+  }
+  return false;
+}
 function formatPathForOutput(filePath, projectRoot) {
   const rel = (0, import_node_path3.relative)(projectRoot, filePath);
   if (rel === "" || rel.startsWith("..") || (0, import_node_path3.isAbsolute)(rel)) {
@@ -419,7 +669,8 @@ async function runUpgradeInstructions(options) {
     );
     return { exitCode: 1, refreshed, skipped, warnings, errors };
   }
-  const sdkVersion = true ? "1.10.2" : "0.0.0-dev";
+  const sdkVersion = true ? "1.12.0" : "0.0.0-dev";
+  const optedInAgents = [];
   for (const agent of agents) {
     if (agent.infoFilePath === null) {
       continue;
@@ -428,34 +679,54 @@ async function runUpgradeInstructions(options) {
       agent.infoFilePath,
       options.projectRoot
     );
-    let containsSection;
+    const legacyDestinations = legacyDestinationsForAgent(agent);
+    let optedIn;
     try {
-      containsSection = await hasManagedSection(agent.infoFilePath);
+      optedIn = await anyHasManagedSection([
+        agent.infoFilePath,
+        ...legacyDestinations
+      ]);
     } catch (err) {
       warnings.push(
         `Could not inspect ${displayPath}: ${err instanceof Error ? err.message : String(err)}`
       );
       continue;
     }
-    if (!containsSection) {
+    if (!optedIn) {
       skipped.push(displayPath);
       continue;
     }
-    const content = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
-    if (content === "") {
-      continue;
-    }
+    optedInAgents.push(agent);
+  }
+  if (optedInAgents.length > 0) {
     try {
-      await injectInfoSection(agent, content, options.projectRoot);
-      refreshed.push(displayPath);
+      await injectAllTargets(
+        optedInAgents,
+        MCP_ENDPOINT,
+        sdkVersion,
+        options.projectRoot
+      );
+      for (const a of optedInAgents) {
+        if (a.infoFilePath !== null) {
+          refreshed.push(formatPathForOutput(a.infoFilePath, options.projectRoot));
+        }
+      }
     } catch (err) {
       errors.push(
-        `Failed to refresh ${displayPath}: ${err instanceof Error ? err.message : String(err)}`
+        `Failed to refresh agent-instruction files: ${err instanceof Error ? err.message : String(err)}`
       );
     }
   }
+  const refreshedSet = new Set(refreshed);
+  const dedupedSkipped = skipped.filter((p) => !refreshedSet.has(p));
   const exitCode = errors.length === 0 ? 0 : 1;
-  return { exitCode, refreshed, skipped, warnings, errors };
+  return {
+    exitCode,
+    refreshed,
+    skipped: dedupedSkipped,
+    warnings,
+    errors
+  };
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {