@glasstrace/sdk 1.3.9 → 1.5.0

package/dist/cli/init.cjs

@@ -14482,7 +14482,18 @@ var init_dist = __esm({
       fullConsoleOutput: external_exports.boolean(),
       importGraph: external_exports.boolean(),
       consoleErrors: external_exports.boolean().optional().default(false),
-      errorResponseBodies: external_exports.boolean().optional().default(false)
+      errorResponseBodies: external_exports.boolean().optional().default(false),
+      /**
+       * Account opt-in for side-effect evidence emission (SDK-049).
+       *
+       * When `false` (default), `recordSideEffect()` is a silent no-op:
+       * no allowlist evaluation runs and no `glasstrace.side_effect.*`
+       * attribute reaches the wire. When `true`, allowlisted side-effect
+       * metadata is attached to the active OTel span subject to the
+       * client-side allowlist enforcement layered with the product's
+       * storage-time filter as defense-in-depth.
+       */
+      sideEffectEvidence: external_exports.boolean().optional().default(false)
     });
     SdkCachedConfigSchema = external_exports.object({
       response: external_exports.record(external_exports.string(), external_exports.unknown()),
@@ -15392,28 +15403,38 @@ function generateMcpConfig(agent, endpoint, bearer) {
     }
   }
 }
-function htmlMarkers() {
+function htmlMarkers(sdkVersion) {
   return {
-    start: "<!-- glasstrace:mcp:start -->",
+    start: `<!-- glasstrace:mcp:start v=${sdkVersion} -->`,
     end: "<!-- glasstrace:mcp:end -->"
   };
 }
-function hashMarkers() {
+function hashMarkers(sdkVersion) {
   return {
-    start: "# glasstrace:mcp:start",
+    start: `# glasstrace:mcp:start v=${sdkVersion}`,
     end: "# glasstrace:mcp:end"
   };
 }
-function generateInfoSection(agent, endpoint) {
+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.",
@@ -15423,24 +15444,24 @@ function generateInfoSection(agent, endpoint) {
     "- `get_test_suggestions` - Get test suggestions based on recent errors",
     "- `get_session_timeline` - Get the timeline of all traces in the current session",
     "",
-    "To reconfigure, run: `npx glasstrace mcp add`",
+    "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();
+      const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "codex": {
-      const m = htmlMarkers();
+      const m = htmlMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
     }
     case "cursor": {
-      const m = hashMarkers();
+      const m = hashMarkers(sdkVersion);
       return `${m.start}
 ${content}${m.end}
 `;
@@ -15455,13 +15476,34 @@ ${content}${m.end}
     }
   }
 }
+var SDK_VERSION_STAMP_PATTERN;
 var init_configs = __esm({
   "src/agent-detection/configs.ts"() {
     "use strict";
+    SDK_VERSION_STAMP_PATTERN = /^[A-Za-z0-9.+-]+$/;
   }
 });
 
 // src/agent-detection/inject.ts
+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 hash2 = HASH_START_RE.exec(trimmed);
+  if (hash2 !== null) {
+    return { kind: "hash", stamp: hash2[1] ?? null };
+  }
+  return null;
+}
+function isEndMarker(line) {
+  const trimmed = line.trim();
+  return trimmed === HTML_END || trimmed === HASH_END;
+}
+function isEndMarkerLine(line) {
+  return isEndMarker(line);
+}
 function isPermissionError(err) {
   const code = err.code;
   return code === "EACCES" || code === "EPERM" || code === "EROFS";
@@ -15503,22 +15545,14 @@ async function writeMcpConfig(agent, content, projectRoot) {
 }
 function findMarkerBoundaries(lines) {
   let startIdx = -1;
-  let endIdx = -1;
   for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (trimmed === HTML_START || trimmed === HASH_START) {
+    if (parseStartMarkerLine(lines[i]) !== null) {
       startIdx = i;
-    } else if (trimmed === HTML_END || trimmed === HASH_END) {
-      if (startIdx !== -1) {
-        endIdx = i;
-        break;
-      }
+    } else if (startIdx !== -1 && isEndMarker(lines[i])) {
+      return { startIdx, endIdx: i };
     }
   }
-  if (startIdx === -1 || endIdx === -1) {
-    return null;
-  }
-  return { startIdx, endIdx };
+  return null;
 }
 async function injectInfoSection(agent, content, projectRoot) {
   if (agent.infoFilePath === null) {
@@ -15585,6 +15619,17 @@ async function injectInfoSection(agent, content, projectRoot) {
     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;
+}
 async function updateGitignore(paths, projectRoot) {
   const gitignorePath = (0, import_node_path2.join)(projectRoot, ".gitignore");
   const relativePaths = paths.filter((p) => !(0, import_node_path2.isAbsolute)(p));
@@ -15631,15 +15676,15 @@ async function updateGitignore(paths, projectRoot) {
     throw err;
   }
 }
-var import_promises2, import_node_path2, HTML_START, HTML_END, HASH_START, HASH_END;
+var import_promises2, import_node_path2, HTML_START_RE, HTML_END, HASH_START_RE, HASH_END;
 var init_inject = __esm({
   "src/agent-detection/inject.ts"() {
     "use strict";
     import_promises2 = require("node:fs/promises");
     import_node_path2 = require("node:path");
-    HTML_START = "<!-- glasstrace:mcp:start -->";
+    HTML_START_RE = /^<!--\s*glasstrace:mcp:start(?:\s+v=([^\s>]+))?\s*-->$/;
     HTML_END = "<!-- glasstrace:mcp:end -->";
-    HASH_START = "# glasstrace:mcp:start";
+    HASH_START_RE = /^#\s*glasstrace:mcp:start(?:\s+v=(\S+))?$/;
     HASH_END = "# glasstrace:mcp:end";
   }
 });
@@ -16339,10 +16384,9 @@ function removeMarkerSection(content) {
   let startIdx = -1;
   let endIdx = -1;
   for (let i = 0; i < lines.length; i++) {
-    const trimmed = lines[i].trim();
-    if (trimmed === "<!-- glasstrace:mcp:start -->" || trimmed === "# glasstrace:mcp:start") {
+    if (parseStartMarkerLine(lines[i]) !== null) {
       startIdx = i;
-    } else if ((trimmed === "<!-- glasstrace:mcp:end -->" || trimmed === "# glasstrace:mcp:end") && startIdx !== -1) {
+    } else if (isEndMarkerLine(lines[i]) && startIdx !== -1) {
       endIdx = i;
       break;
     }
@@ -16794,6 +16838,7 @@ var init_uninit = __esm({
     init_mcp_runtime();
     init_atomic_write();
     init_discovery_file();
+    init_inject();
     MCP_CONFIG_FILES = [".mcp.json", ".cursor/mcp.json", ".gemini/settings.json"];
     AGENT_INFO_FILES = [
       "CLAUDE.md",
@@ -16949,10 +16994,11 @@ async function mcpAdd(options) {
   const bearer = resolved.effective.key;
   for (const agent of targetAgents) {
     const name = formatAgentName(agent.name);
+    const sdkVersion = true ? "1.5.0" : "0.0.0-dev";
     if (agent.name !== "generic") {
       const cliSuccess = await registerViaCli(agent, bearer);
       if (cliSuccess) {
-        const infoContent = generateInfoSection(agent, MCP_ENDPOINT);
+        const infoContent = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
         if (infoContent !== "") {
           await injectInfoSection(agent, infoContent, projectRoot);
         }
@@ -16970,7 +17016,7 @@ async function mcpAdd(options) {
         const configContent = generateMcpConfig(agent, MCP_ENDPOINT, bearer);
         await writeMcpConfig(agent, configContent, projectRoot);
         if (fs6.existsSync(agent.mcpConfigPath)) {
-          const infoContent = generateInfoSection(agent, MCP_ENDPOINT);
+          const infoContent = generateInfoSection(agent, MCP_ENDPOINT, sdkVersion);
           if (infoContent !== "") {
             await injectInfoSection(agent, infoContent, projectRoot);
           }
@@ -17190,6 +17236,82 @@ var init_validate = __esm({
   }
 });
 
+// src/cli/upgrade-instructions.ts
+var upgrade_instructions_exports = {};
+__export(upgrade_instructions_exports, {
+  runUpgradeInstructions: () => runUpgradeInstructions
+});
+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 };
+}
+var import_node_path3;
+var init_upgrade_instructions = __esm({
+  "src/cli/upgrade-instructions.ts"() {
+    "use strict";
+    import_node_path3 = require("node:path");
+    init_mcp_runtime();
+    init_detect();
+    init_configs();
+    init_inject();
+  }
+});
+
 // src/cli/status.ts
 var status_exports = {};
 __export(status_exports, {
@@ -17286,9 +17408,14 @@ function checkAgents(root) {
   for (const name of AGENT_INFO_FILES2) {
     try {
       const content = fs8.readFileSync(path8.join(root, name), "utf-8");
-      const hasHtmlMarkers = content.includes("<!-- glasstrace:mcp:start -->") && content.includes("<!-- glasstrace:mcp:end -->");
-      const hasHashMarkers = content.includes("# glasstrace:mcp:start") && content.includes("# glasstrace:mcp:end");
-      if (hasHtmlMarkers || hasHashMarkers) {
+      let hasStart = false;
+      let hasEnd = false;
+      for (const line of content.split("\n")) {
+        if (parseStartMarkerLine(line) !== null) hasStart = true;
+        else if (isEndMarkerLine(line)) hasEnd = true;
+        if (hasStart && hasEnd) break;
+      }
+      if (hasStart && hasEnd) {
         found.push(name);
       }
     } catch {
@@ -17365,6 +17492,7 @@ var init_status = __esm({
     fs8 = __toESM(require("node:fs"), 1);
     path8 = __toESM(require("node:path"), 1);
     init_constants();
+    init_inject();
     MCP_JSON_FILES = [".mcp.json", ".cursor/mcp.json", ".gemini/settings.json", ".glasstrace/mcp.json"];
     MCP_TOML_FILES = [".codex/config.toml"];
     AGENT_INFO_FILES2 = [
@@ -18770,7 +18898,12 @@ Then add this as the first statement in your register() function:
           }
           anyConfigWritten = true;
           anyConfigRewrittenWithBearer = true;
-          const infoContent = generateInfoSection(agent, MCP_ENDPOINT);
+          const sdkVersionForInject = true ? "1.5.0" : "0.0.0-dev";
+          const infoContent = generateInfoSection(
+            agent,
+            MCP_ENDPOINT,
+            sdkVersionForInject
+          );
           if (infoContent !== "") {
             await injectInfoSection(agent, infoContent, projectRoot);
           }
@@ -18868,7 +19001,7 @@ async function verifyAnonKeyRegistration(projectRoot) {
   }
   const baseConfig = resolveConfig({ apiKey: devKey });
   const config2 = { ...baseConfig, apiKey: devKey };
-  const sdkVersion = true ? "1.3.9" : "0.0.0-dev";
+  const sdkVersion = true ? "1.5.0" : "0.0.0-dev";
   const result = await verifyInitReachable(config2, anonKey, sdkVersion);
   if (result.ok) {
     return { outcome: "verified" };
@@ -19057,6 +19190,55 @@ Usage: glasstrace mcp add [--force] [--dry-run]
     }).catch((err) => {
       process.stderr.write(
         `Fatal error: ${err instanceof Error ? err.message : String(err)}
+`
+      );
+      process.exit(1);
+    });
+  } else if (subcommand === "upgrade-instructions") {
+    Promise.all([
+      Promise.resolve().then(() => (init_upgrade_instructions(), upgrade_instructions_exports)),
+      Promise.resolve().then(() => (init_monorepo(), monorepo_exports))
+    ]).then(([{ runUpgradeInstructions: runUpgradeInstructions2 }, { resolveProjectRoot: resolve2 }]) => {
+      let projectRoot = process.cwd();
+      try {
+        projectRoot = resolve2(projectRoot).projectRoot;
+      } catch {
+      }
+      return runUpgradeInstructions2({ projectRoot });
+    }).then((result) => {
+      for (const err of result.errors) {
+        process.stderr.write(`Error: ${err}
+`);
+      }
+      for (const warn of result.warnings) {
+        process.stderr.write(`Warning: ${warn}
+`);
+      }
+      if (result.refreshed.length > 0) {
+        process.stderr.write("\nRefreshed agent instruction files:\n");
+        for (const file2 of result.refreshed) {
+          process.stderr.write(`  - ${file2}
+`);
+        }
+      }
+      if (result.skipped.length > 0) {
+        process.stderr.write(
+          "\nSkipped (no Glasstrace managed section present):\n"
+        );
+        for (const file2 of result.skipped) {
+          process.stderr.write(`  - ${file2}
+`);
+        }
+      }
+      if (result.refreshed.length === 0 && result.skipped.length === 0 && result.errors.length === 0) {
+        process.stderr.write(
+          "\nNo agent instruction files detected with a Glasstrace managed section. Run `npx glasstrace init` or `npx glasstrace mcp add` to install one.\n"
+        );
+      }
+      process.exit(result.exitCode);
+    }).catch((err) => {
+      process.stderr.write(
+        `Fatal error: ${err instanceof Error ? err.message : String(err)}
 `
       );
       process.exit(1);
@@ -19110,6 +19292,7 @@ Usage:
   glasstrace uninit [--dry-run] [--force]
   glasstrace status [--json]
   glasstrace mcp add [--force] [--dry-run]
+  glasstrace upgrade-instructions
 `
     );
     process.exit(1);