@glasstrace/sdk 0.14.1 → 0.15.1

package/dist/cli/init.cjs

@@ -83,14 +83,14 @@ function injectRegisterGlasstrace(content) {
   const indentMatch = /\n([ \t]+)/.exec(afterBrace);
   const indent = indentMatch ? indentMatch[1] : "  ";
   const importLine = 'import { registerGlasstrace } from "@glasstrace/sdk";\n';
-  const hasGlasstraceImport = content.includes("@glasstrace/sdk");
+  const hasGlasstraceImport2 = content.includes("@glasstrace/sdk");
   const insertPoint = match.index + match[0].length;
   const callInjection = `
 ${indent}// Glasstrace must be registered before other instrumentation
 ${indent}registerGlasstrace();
 `;
   let modified;
-  if (hasGlasstraceImport) {
+  if (hasGlasstraceImport2) {
     const importRegex = /import\s*\{([^}]+)\}\s*from\s*["']@glasstrace\/sdk["']/;
     const importMatch = importRegex.exec(content);
     if (importMatch) {
@@ -230,6 +230,23 @@ function wrapCJSExport(content) {
     wrapped: true
   };
 }
+function readEnvLocalApiKey(content) {
+  let last = null;
+  const regex = /^\s*GLASSTRACE_API_KEY\s*=\s*(.*)$/gm;
+  let match;
+  while ((match = regex.exec(content)) !== null) {
+    const raw = match[1].trim();
+    if (raw === "") continue;
+    const unquoted = raw.replace(/^(['"])(.*)\1$/, "$2");
+    if (unquoted === "" || unquoted === "your_key_here") continue;
+    last = unquoted;
+  }
+  return last;
+}
+function isDevApiKey(value) {
+  if (value === null || value === void 0) return false;
+  return value.trim().startsWith("gt_dev_");
+}
 async function scaffoldEnvLocal(projectRoot) {
   const filePath = path.join(projectRoot, ".env.local");
   if (fs.existsSync(filePath)) {
@@ -281,6 +298,30 @@ async function scaffoldGitignore(projectRoot) {
   fs.writeFileSync(filePath, ".glasstrace/\n", "utf-8");
   return true;
 }
+function mcpConfigMatches(existingContent, expectedContent) {
+  const trimmedExpected = expectedContent.trim();
+  try {
+    const existingParsed = JSON.parse(existingContent);
+    const expectedParsed = JSON.parse(trimmedExpected);
+    return JSON.stringify(canonicalize(existingParsed)) === JSON.stringify(canonicalize(expectedParsed));
+  } catch {
+  }
+  return existingContent.trim() === trimmedExpected;
+}
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === "object") {
+    const obj = value;
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = canonicalize(obj[key]);
+    }
+    return sorted;
+  }
+  return value;
+}
 async function scaffoldMcpMarker(projectRoot, anonKey) {
   const dirPath = path.join(projectRoot, ".glasstrace");
   const markerPath = path.join(dirPath, "mcp-connected");
@@ -570,10 +611,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path8) {
-  if (!path8)
+function getElementAtPath(obj, path9) {
+  if (!path9)
     return obj;
-  return path8.reduce((acc, key) => acc?.[key], obj);
+  return path9.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -885,11 +926,11 @@ function aborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path8, issues) {
+function prefixIssues(path9, issues) {
   return issues.map((iss) => {
     var _a2;
     (_a2 = iss).path ?? (_a2.path = []);
-    iss.path.unshift(path8);
+    iss.path.unshift(path9);
     return iss;
   });
 }
@@ -1133,7 +1174,7 @@ function formatError(error48, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error48, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error49, path8 = []) => {
+  const processError = (error49, path9 = []) => {
     var _a2, _b;
     for (const issue2 of error49.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
@@ -1143,7 +1184,7 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
       } else if (issue2.code === "invalid_element") {
         processError({ issues: issue2.issues }, issue2.path);
       } else {
-        const fullpath = [...path8, ...issue2.path];
+        const fullpath = [...path9, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -1175,8 +1216,8 @@ function treeifyError(error48, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path8 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path8) {
+  const path9 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path9) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -14010,13 +14051,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path8 = ref.slice(1).split("/").filter(Boolean);
-  if (path8.length === 0) {
+  const path9 = ref.slice(1).split("/").filter(Boolean);
+  if (path9.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path8[0] === defsKey) {
-    const key = path8[1];
+  if (path9[0] === defsKey) {
+    const key = path9[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -14935,11 +14976,11 @@ var init_dist = __esm({
 async function loadFsPath() {
   if (fsPathCache !== void 0) return fsPathCache;
   try {
-    const [fs8, path8] = await Promise.all([
+    const [fs9, path9] = await Promise.all([
       import("fs/promises"),
       import("path")
     ]);
-    fsPathCache = { fs: fs8, path: path8 };
+    fsPathCache = { fs: fs9, path: path9 };
     return fsPathCache;
   } catch {
     fsPathCache = null;
@@ -15027,9 +15068,9 @@ var init_anon_key = __esm({
 });
 
 // src/agent-detection/detect.ts
-async function pathExists(path8, mode = import_node_fs.constants.R_OK) {
+async function pathExists(path9, mode = import_node_fs.constants.R_OK) {
   try {
-    await (0, import_promises.access)(path8, mode);
+    await (0, import_promises.access)(path9, mode);
     return true;
   } catch {
     return false;
@@ -15798,7 +15839,8 @@ __export(uninit_exports, {
   runUninit: () => runUninit,
   skipString: () => skipString,
   unwrapCJSExport: () => unwrapCJSExport,
-  unwrapExport: () => unwrapExport
+  unwrapExport: () => unwrapExport,
+  writeShutdownMarker: () => writeShutdownMarker
 });
 function skipString(text, start, quote) {
   let i = start + 1;
@@ -16099,12 +16141,75 @@ function processTomlMcpConfig(content) {
   }
   return { action: "removed-section", content: result + "\n" };
 }
+function writeShutdownMarker(projectRoot) {
+  const dirPath = path4.join(projectRoot, ".glasstrace");
+  if (!fs4.existsSync(dirPath)) {
+    return false;
+  }
+  const markerPath = path4.join(dirPath, "shutdown-requested");
+  const tmpPath = `${markerPath}.tmp`;
+  const body = JSON.stringify({ requestedAt: (/* @__PURE__ */ new Date()).toISOString() });
+  try {
+    fs4.writeFileSync(tmpPath, body, { encoding: "utf-8", mode: 384 });
+    try {
+      fs4.chmodSync(tmpPath, 384);
+    } catch {
+    }
+    fs4.renameSync(tmpPath, markerPath);
+    return true;
+  } catch {
+    try {
+      fs4.unlinkSync(tmpPath);
+    } catch {
+    }
+    return false;
+  }
+}
+async function defaultPrompt(question, defaultValue) {
+  if (!process.stdin.isTTY) return defaultValue;
+  const readline2 = await import("readline");
+  const rl = readline2.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise((resolve2) => {
+    const suffix = defaultValue ? " [Y/n] " : " [y/N] ";
+    rl.question(question + suffix, (answer) => {
+      rl.close();
+      const trimmed = answer.trim().toLowerCase();
+      if (trimmed === "") {
+        resolve2(defaultValue);
+        return;
+      }
+      resolve2(trimmed === "y" || trimmed === "yes");
+    });
+  });
+}
 async function runUninit(options) {
   const { projectRoot, dryRun } = options;
+  const force = options.force === true;
+  const prompt = options.prompt ?? defaultPrompt;
   const summary = [];
   const warnings = [];
   const errors = [];
   const prefix = dryRun ? "[dry run] " : "";
+  try {
+    if (!dryRun) {
+      const markerWritten = writeShutdownMarker(projectRoot);
+      if (markerWritten) {
+        summary.push("Wrote .glasstrace/shutdown-requested marker");
+      }
+    } else {
+      const dirPath = path4.join(projectRoot, ".glasstrace");
+      if (fs4.existsSync(dirPath)) {
+        summary.push(`${prefix}Would write .glasstrace/shutdown-requested marker`);
+      }
+    }
+  } catch (err) {
+    warnings.push(
+      `Shutdown marker write failed: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
   try {
     let configHandled = false;
     for (const name of NEXT_CONFIG_NAMES) {
@@ -16187,23 +16292,57 @@ async function runUninit(options) {
     const envPath = path4.join(projectRoot, ".env.local");
     if (fs4.existsSync(envPath)) {
       const content = fs4.readFileSync(envPath, "utf-8");
-      const lines = content.split("\n");
-      const filtered = lines.filter((line) => {
-        const trimmed = line.trim();
-        return !(/^\s*#?\s*GLASSTRACE_API_KEY\s*=/.test(trimmed) || /^\s*#?\s*GLASSTRACE_COVERAGE_MAP\s*=/.test(trimmed));
-      });
-      if (filtered.length !== lines.length) {
-        const result = filtered.join("\n");
-        if (result.trim().length === 0) {
-          if (!dryRun) {
-            fs4.unlinkSync(envPath);
-          }
-          summary.push(`${prefix}Deleted .env.local (no remaining entries)`);
+      const existingKey = readEnvLocalApiKey(content);
+      const hasDevKey = isDevApiKey(existingKey);
+      let proceed = true;
+      let devKeyPath = "none";
+      if (hasDevKey) {
+        if (dryRun) {
+          devKeyPath = "dry-run-preview";
+        } else if (force) {
+          devKeyPath = "force-bypass";
         } else {
-          if (!dryRun) {
-            fs4.writeFileSync(envPath, result, "utf-8");
+          const confirmed = await prompt(
+            ".env.local contains a claimed Glasstrace developer API key (gt_dev_...). Removing it will require you to re-authenticate. Continue?",
+            false
+          );
+          proceed = confirmed;
+          if (confirmed) devKeyPath = "interactive-confirmed";
+        }
+      }
+      if (!proceed) {
+        warnings.push(
+          "Preserved GLASSTRACE_API_KEY in .env.local (claimed dev key; re-run with --force to remove)"
+        );
+      } else {
+        const lines = content.split("\n");
+        const filtered = lines.filter((line) => {
+          const trimmed = line.trim();
+          return !(/^\s*#?\s*GLASSTRACE_API_KEY\s*=/.test(trimmed) || /^\s*#?\s*GLASSTRACE_COVERAGE_MAP\s*=/.test(trimmed));
+        });
+        if (filtered.length !== lines.length) {
+          const result = filtered.join("\n");
+          if (result.trim().length === 0) {
+            if (!dryRun) {
+              fs4.unlinkSync(envPath);
+            }
+            summary.push(`${prefix}Deleted .env.local (no remaining entries)`);
+          } else {
+            if (!dryRun) {
+              fs4.writeFileSync(envPath, result, "utf-8");
+            }
+            let devKeyAnnotation = "";
+            if (devKeyPath === "interactive-confirmed") {
+              devKeyAnnotation = " (dev key confirmed)";
+            } else if (devKeyPath === "force-bypass") {
+              devKeyAnnotation = " (dev key removed via --force)";
+            } else if (devKeyPath === "dry-run-preview") {
+              devKeyAnnotation = " (dev key would be removed; real run would require confirmation)";
+            }
+            summary.push(
+              `${prefix}Removed GLASSTRACE entries from .env.local${devKeyAnnotation}`
+            );
           }
-          summary.push(`${prefix}Removed GLASSTRACE entries from .env.local`);
         }
       }
     }
@@ -16359,6 +16498,7 @@ var init_uninit = __esm({
     os = __toESM(require("os"), 1);
     path4 = __toESM(require("path"), 1);
     init_constants();
+    init_scaffolder();
     MCP_CONFIG_FILES = [".mcp.json", ".cursor/mcp.json", ".gemini/settings.json"];
     AGENT_INFO_FILES = [
       "CLAUDE.md",
@@ -16599,6 +16739,112 @@ var init_mcp_add = __esm({
   }
 });
 
+// src/cli/validate.ts
+var validate_exports = {};
+__export(validate_exports, {
+  hasGlasstraceImport: () => hasGlasstraceImport,
+  hasRegisterGlasstraceImport: () => hasRegisterGlasstraceImport,
+  runValidate: () => runValidate
+});
+function hasGlasstraceImport(content) {
+  return /@glasstrace\/sdk/.test(content);
+}
+function hasRegisterGlasstraceImport(content) {
+  const match = /import\s*\{([^}]+)\}\s*from\s*["']@glasstrace\/sdk["']/;
+  const importMatch = match.exec(content);
+  if (!importMatch) return false;
+  return importMatch[1].split(",").map((s) => s.trim()).includes("registerGlasstrace");
+}
+function runValidate(options) {
+  const { projectRoot } = options;
+  const issues = [];
+  const glasstraceDir = path6.join(projectRoot, ".glasstrace");
+  const instrumentationPath = path6.join(projectRoot, "instrumentation.ts");
+  const markerPath = path6.join(glasstraceDir, "mcp-connected");
+  const glasstraceDirExists = isDirectorySafe(glasstraceDir);
+  const instrumentationExists = fs6.existsSync(instrumentationPath);
+  const instrumentationContent = instrumentationExists ? safeReadFile(instrumentationPath) : null;
+  const markerExists = fs6.existsSync(markerPath);
+  const mcpConfigsPresent = MCP_CONFIG_CANDIDATES.filter(
+    (rel) => fs6.existsSync(path6.join(projectRoot, rel))
+  );
+  if (glasstraceDirExists) {
+    if (instrumentationContent === null || !hasRegisterGlasstraceImport(instrumentationContent)) {
+      issues.push({
+        code: "glasstrace-dir-without-register-import",
+        message: ".glasstrace/ exists but instrumentation.ts is missing the registerGlasstrace import.",
+        fix: "Run `npx glasstrace init` to re-scaffold instrumentation.ts, or remove .glasstrace/ if the SDK is no longer in use."
+      });
+    }
+  }
+  if (!glasstraceDirExists && instrumentationContent !== null) {
+    if (hasGlasstraceImport(instrumentationContent)) {
+      issues.push({
+        code: "sdk-import-without-glasstrace-dir",
+        message: "instrumentation.ts imports from @glasstrace/sdk but .glasstrace/ is missing.",
+        fix: "Run `npx glasstrace init` to recreate .glasstrace/, or `npx glasstrace uninit` to fully remove the SDK."
+      });
+    }
+  }
+  if (markerExists && mcpConfigsPresent.length === 0) {
+    issues.push({
+      code: "mcp-marker-without-configs",
+      message: ".glasstrace/mcp-connected marker is present but no MCP config files were found.",
+      fix: "Run `npx glasstrace mcp add --force` to regenerate MCP configs, or delete .glasstrace/mcp-connected."
+    });
+  }
+  if (!markerExists && mcpConfigsPresent.length > 0) {
+    issues.push({
+      code: "mcp-configs-without-marker",
+      message: `MCP config files exist (${mcpConfigsPresent.join(", ")}) but .glasstrace/mcp-connected marker is missing.`,
+      fix: "Run `npx glasstrace init` to re-register the marker, or `npx glasstrace uninit` to fully remove MCP configuration."
+    });
+  }
+  const summary = [];
+  if (issues.length === 0) {
+    summary.push("Glasstrace install state is consistent.");
+  } else {
+    summary.push(
+      `Detected ${issues.length} inconsistenc${issues.length === 1 ? "y" : "ies"} in Glasstrace install state:`
+    );
+  }
+  return {
+    exitCode: issues.length > 0 ? 1 : 0,
+    summary,
+    issues
+  };
+}
+function safeReadFile(filePath) {
+  try {
+    return fs6.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function isDirectorySafe(dirPath) {
+  try {
+    if (!fs6.existsSync(dirPath)) return false;
+    return fs6.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+var fs6, path6, MCP_CONFIG_CANDIDATES;
+var init_validate = __esm({
+  "src/cli/validate.ts"() {
+    "use strict";
+    init_cjs_shims();
+    fs6 = __toESM(require("fs"), 1);
+    path6 = __toESM(require("path"), 1);
+    MCP_CONFIG_CANDIDATES = [
+      ".mcp.json",
+      ".cursor/mcp.json",
+      ".gemini/settings.json",
+      ".codex/config.toml"
+    ];
+  }
+});
+
 // src/cli/status.ts
 var status_exports = {};
 __export(status_exports, {
@@ -16619,8 +16865,8 @@ function runStatus(options) {
 }
 function checkInstalled(root) {
   try {
-    const pkgPath = path6.join(root, "package.json");
-    const content = fs6.readFileSync(pkgPath, "utf-8");
+    const pkgPath = path7.join(root, "package.json");
+    const content = fs7.readFileSync(pkgPath, "utf-8");
     const pkg = JSON.parse(content);
     const deps = pkg["dependencies"];
     const devDeps = pkg["devDependencies"];
@@ -16631,7 +16877,7 @@ function checkInstalled(root) {
 }
 function checkInitialized(root) {
   try {
-    return fs6.statSync(path6.join(root, ".glasstrace")).isDirectory();
+    return fs7.statSync(path7.join(root, ".glasstrace")).isDirectory();
   } catch {
     return false;
   }
@@ -16639,7 +16885,7 @@ function checkInitialized(root) {
 function checkInstrumentation(root) {
   for (const name of INSTRUMENTATION_FILES) {
     try {
-      const content = fs6.readFileSync(path6.join(root, name), "utf-8");
+      const content = fs7.readFileSync(path7.join(root, name), "utf-8");
       if (content.includes("registerGlasstrace")) {
         return true;
       }
@@ -16651,7 +16897,7 @@ function checkInstrumentation(root) {
 function checkConfigWrapped(root) {
   for (const name of NEXT_CONFIG_NAMES) {
     try {
-      const content = fs6.readFileSync(path6.join(root, name), "utf-8");
+      const content = fs7.readFileSync(path7.join(root, name), "utf-8");
       if (content.includes("withGlasstraceConfig")) {
         return true;
       }
@@ -16662,7 +16908,7 @@ function checkConfigWrapped(root) {
 }
 function checkAnonKey(root) {
   try {
-    return fs6.statSync(path6.join(root, ".glasstrace", "anon_key")).isFile();
+    return fs7.statSync(path7.join(root, ".glasstrace", "anon_key")).isFile();
   } catch {
     return false;
   }
@@ -16670,7 +16916,7 @@ function checkAnonKey(root) {
 function checkMcpConfigured(root) {
   for (const name of MCP_JSON_FILES) {
     try {
-      const content = fs6.readFileSync(path6.join(root, name), "utf-8");
+      const content = fs7.readFileSync(path7.join(root, name), "utf-8");
       const parsed = JSON.parse(content);
       const mcpServers = parsed["mcpServers"];
       if (mcpServers && typeof mcpServers === "object" && "glasstrace" in mcpServers) {
@@ -16681,7 +16927,7 @@ function checkMcpConfigured(root) {
   }
   for (const name of MCP_TOML_FILES) {
     try {
-      const content = fs6.readFileSync(path6.join(root, name), "utf-8");
+      const content = fs7.readFileSync(path7.join(root, name), "utf-8");
       if (content.includes("[mcp_servers.glasstrace]")) {
         return true;
       }
@@ -16694,7 +16940,7 @@ function checkAgents(root) {
   const found = [];
   for (const name of AGENT_INFO_FILES2) {
     try {
-      const content = fs6.readFileSync(path6.join(root, name), "utf-8");
+      const content = fs7.readFileSync(path7.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) {
@@ -16717,8 +16963,8 @@ function readRuntimeState(root) {
     pid: null
   };
   try {
-    const filePath = path6.join(root, ".glasstrace", "runtime-state.json");
-    const content = fs6.readFileSync(filePath, "utf-8");
+    const filePath = path7.join(root, ".glasstrace", "runtime-state.json");
+    const content = fs7.readFileSync(filePath, "utf-8");
     const parsed = JSON.parse(content);
     const updatedAt = typeof parsed.updatedAt === "string" ? parsed.updatedAt : null;
     const pid = typeof parsed.pid === "number" ? parsed.pid : null;
@@ -16767,13 +17013,13 @@ function readRuntimeState(root) {
     return empty;
   }
 }
-var fs6, path6, MCP_JSON_FILES, MCP_TOML_FILES, AGENT_INFO_FILES2, INSTRUMENTATION_FILES, STALE_THRESHOLD_MS;
+var fs7, path7, MCP_JSON_FILES, MCP_TOML_FILES, AGENT_INFO_FILES2, INSTRUMENTATION_FILES, STALE_THRESHOLD_MS;
 var init_status = __esm({
   "src/cli/status.ts"() {
     "use strict";
     init_cjs_shims();
-    fs6 = __toESM(require("fs"), 1);
-    path6 = __toESM(require("path"), 1);
+    fs7 = __toESM(require("fs"), 1);
+    path7 = __toESM(require("path"), 1);
     init_constants();
     MCP_JSON_FILES = [".mcp.json", ".cursor/mcp.json", ".gemini/settings.json", ".glasstrace/mcp.json"];
     MCP_TOML_FILES = [".codex/config.toml"];
@@ -16797,14 +17043,15 @@ var init_status = __esm({
 // src/cli/init.ts
 var init_exports = {};
 __export(init_exports, {
+  decideMcpConfigAction: () => decideMcpConfigAction,
   meetsNodeVersion: () => meetsNodeVersion,
   rollbackSteps: () => rollbackSteps,
   runInit: () => runInit
 });
 module.exports = __toCommonJS(init_exports);
 init_cjs_shims();
-var fs7 = __toESM(require("fs"), 1);
-var path7 = __toESM(require("path"), 1);
+var fs8 = __toESM(require("fs"), 1);
+var path8 = __toESM(require("path"), 1);
 var readline = __toESM(require("readline"), 1);
 init_scaffolder();
 
@@ -16990,6 +17237,31 @@ function meetsNodeVersion(minMajor) {
   const [major] = process.versions.node.split(".").map(Number);
   return major >= minMajor;
 }
+async function decideMcpConfigAction(options) {
+  const { configPath, expectedContent, force } = options;
+  if (configPath === null) return "write";
+  const exists = options.existsSync ?? fs8.existsSync;
+  const read = options.readFile ?? ((p) => fs8.readFileSync(p, "utf-8"));
+  const prompt = options.prompt ?? promptYesNo;
+  if (!exists(configPath)) return "write";
+  let existingContent;
+  try {
+    existingContent = read(configPath);
+  } catch {
+    return "write";
+  }
+  if (mcpConfigMatches(existingContent, expectedContent)) {
+    return "write";
+  }
+  if (force) {
+    return "force-overwrite";
+  }
+  const answer = await prompt(
+    `Existing MCP config at ${configPath} differs from Glasstrace's template. Overwrite?`,
+    false
+  );
+  return answer ? "force-overwrite" : "skip";
+}
 async function promptYesNo(question, defaultValue) {
   if (!process.stdin.isTTY) {
     return defaultValue;
@@ -17019,17 +17291,17 @@ async function rollbackSteps(steps, projectRoot, state) {
     try {
       switch (step) {
         case "instrumentation": {
-          const instrPath = path7.join(projectRoot, "instrumentation.ts");
-          if (fs7.existsSync(instrPath)) {
-            const content = fs7.readFileSync(instrPath, "utf-8");
+          const instrPath = path8.join(projectRoot, "instrumentation.ts");
+          if (fs8.existsSync(instrPath)) {
+            const content = fs8.readFileSync(instrPath, "utf-8");
             if (isInitCreatedInstrumentation(content)) {
-              fs7.unlinkSync(instrPath);
+              fs8.unlinkSync(instrPath);
             } else if (state?.originalInstrumentationContent !== void 0) {
-              fs7.writeFileSync(instrPath, state.originalInstrumentationContent, "utf-8");
+              fs8.writeFileSync(instrPath, state.originalInstrumentationContent, "utf-8");
             } else {
               const cleaned = removeRegisterGlasstrace(content);
               if (cleaned !== content) {
-                fs7.writeFileSync(instrPath, cleaned, "utf-8");
+                fs8.writeFileSync(instrPath, cleaned, "utf-8");
               }
             }
           }
@@ -17037,11 +17309,11 @@ async function rollbackSteps(steps, projectRoot, state) {
         }
         case "next-config": {
           for (const name of NEXT_CONFIG_NAMES) {
-            const configPath = path7.join(projectRoot, name);
-            if (!fs7.existsSync(configPath)) {
+            const configPath = path8.join(projectRoot, name);
+            if (!fs8.existsSync(configPath)) {
               continue;
             }
-            const content = fs7.readFileSync(configPath, "utf-8");
+            const content = fs8.readFileSync(configPath, "utf-8");
             if (!content.includes("withGlasstraceConfig")) {
               continue;
             }
@@ -17049,16 +17321,16 @@ async function rollbackSteps(steps, projectRoot, state) {
             const unwrapResult = isESM ? unwrapExport(content) : unwrapCJSExport(content);
             if (unwrapResult.unwrapped) {
               const cleaned = removeGlasstraceConfigImport(unwrapResult.content);
-              fs7.writeFileSync(configPath, cleanLeadingBlankLines2(cleaned), "utf-8");
+              fs8.writeFileSync(configPath, cleanLeadingBlankLines2(cleaned), "utf-8");
             }
             break;
           }
           break;
         }
         case "env-local": {
-          const envPath = path7.join(projectRoot, ".env.local");
-          if (fs7.existsSync(envPath)) {
-            const content = fs7.readFileSync(envPath, "utf-8");
+          const envPath = path8.join(projectRoot, ".env.local");
+          if (fs8.existsSync(envPath)) {
+            const content = fs8.readFileSync(envPath, "utf-8");
             const lines = content.split("\n");
             const filtered = lines.filter((line) => {
               const trimmed = line.trim();
@@ -17067,18 +17339,18 @@ async function rollbackSteps(steps, projectRoot, state) {
             if (filtered.length !== lines.length) {
               const result = filtered.join("\n");
               if (result.trim().length === 0) {
-                fs7.unlinkSync(envPath);
+                fs8.unlinkSync(envPath);
               } else {
-                fs7.writeFileSync(envPath, result, "utf-8");
+                fs8.writeFileSync(envPath, result, "utf-8");
               }
             }
           }
           break;
         }
         case "gitignore": {
-          const gitignorePath = path7.join(projectRoot, ".gitignore");
-          if (fs7.existsSync(gitignorePath)) {
-            const content = fs7.readFileSync(gitignorePath, "utf-8");
+          const gitignorePath = path8.join(projectRoot, ".gitignore");
+          if (fs8.existsSync(gitignorePath)) {
+            const content = fs8.readFileSync(gitignorePath, "utf-8");
             const lines = content.split("\n");
             const filtered = lines.filter(
               (line) => line.trim() !== ".glasstrace/"
@@ -17086,9 +17358,9 @@ async function rollbackSteps(steps, projectRoot, state) {
             if (filtered.length !== lines.length) {
               const result = filtered.join("\n");
               if (result.trim().length === 0) {
-                fs7.unlinkSync(gitignorePath);
+                fs8.unlinkSync(gitignorePath);
               } else {
-                fs7.writeFileSync(gitignorePath, result, "utf-8");
+                fs8.writeFileSync(gitignorePath, result, "utf-8");
               }
             }
           }
@@ -17115,16 +17387,16 @@ async function runInit(options) {
     errors.push(err instanceof Error ? err.message : String(err));
     return { exitCode: 1, summary, warnings, errors };
   }
-  const packageJsonPath = path7.join(projectRoot, "package.json");
-  if (!fs7.existsSync(packageJsonPath)) {
+  const packageJsonPath = path8.join(projectRoot, "package.json");
+  if (!fs8.existsSync(packageJsonPath)) {
     errors.push("No package.json found. Run this command from a Node.js project root.");
     return { exitCode: 1, summary, warnings, errors };
   }
   const rollbackState = { steps: [] };
   try {
-    const instrPath = path7.join(projectRoot, "instrumentation.ts");
-    if (fs7.existsSync(instrPath)) {
-      rollbackState.originalInstrumentationContent = fs7.readFileSync(instrPath, "utf-8");
+    const instrPath = path8.join(projectRoot, "instrumentation.ts");
+    if (fs8.existsSync(instrPath)) {
+      rollbackState.originalInstrumentationContent = fs8.readFileSync(instrPath, "utf-8");
     }
     const instrResult = await scaffoldInstrumentation(projectRoot);
     switch (instrResult.action) {
@@ -17170,10 +17442,20 @@ async function runInit(options) {
     return { exitCode: 1, summary, warnings, errors };
   }
   try {
+    const envPathForCheck = path8.join(projectRoot, ".env.local");
+    let existingDevKey = false;
+    if (fs8.existsSync(envPathForCheck)) {
+      const existingContent = fs8.readFileSync(envPathForCheck, "utf-8");
+      existingDevKey = isDevApiKey(readEnvLocalApiKey(existingContent));
+    }
     const envCreated = await scaffoldEnvLocal(projectRoot);
     if (envCreated) {
       summary.push("Updated .env.local with Glasstrace configuration");
       rollbackState.steps.push("env-local");
+    } else if (existingDevKey) {
+      summary.push(
+        "Preserved existing .env.local (GLASSTRACE_API_KEY contains a claimed dev key)"
+      );
     } else {
       summary.push("Skipped .env.local (GLASSTRACE_API_KEY already configured)");
     }
@@ -17198,19 +17480,30 @@ async function runInit(options) {
   const ciEnv = process.env["CI"];
   const isCI = typeof ciEnv === "string" && ciEnv.trim() !== "" && ciEnv.toLowerCase() !== "false" && ciEnv.trim() !== "0" || process.env["GITHUB_ACTIONS"] === "true";
   try {
+    const preExistingAnonKey = await readAnonKey(projectRoot);
     const anonKey = await getOrCreateAnonKey(projectRoot);
+    if (preExistingAnonKey !== null) {
+      summary.push("Preserved existing .glasstrace/anon_key");
+    }
     let anyConfigWritten = false;
     if (isCI) {
       const genericAgent = {
         name: "generic",
-        mcpConfigPath: path7.join(projectRoot, ".glasstrace", "mcp.json"),
+        mcpConfigPath: path8.join(projectRoot, ".glasstrace", "mcp.json"),
         infoFilePath: null,
         cliAvailable: false,
         registrationCommand: null
       };
       const genericConfig = generateMcpConfig(genericAgent, MCP_ENDPOINT, anonKey);
-      await writeMcpConfig(genericAgent, genericConfig, projectRoot);
-      if (genericAgent.mcpConfigPath !== null && fs7.existsSync(genericAgent.mcpConfigPath)) {
+      const decision = await decideMcpConfigAction({
+        configPath: genericAgent.mcpConfigPath,
+        expectedContent: genericConfig,
+        force: true
+      });
+      if (decision !== "skip") {
+        await writeMcpConfig(genericAgent, genericConfig, projectRoot);
+      }
+      if (genericAgent.mcpConfigPath !== null && fs8.existsSync(genericAgent.mcpConfigPath)) {
         anyConfigWritten = true;
         summary.push("Created .glasstrace/mcp.json (CI mode)");
       }
@@ -17224,14 +17517,14 @@ async function runInit(options) {
         );
         const genericAgent = {
           name: "generic",
-          mcpConfigPath: path7.join(projectRoot, ".glasstrace", "mcp.json"),
+          mcpConfigPath: path8.join(projectRoot, ".glasstrace", "mcp.json"),
           infoFilePath: null,
           cliAvailable: false,
           registrationCommand: null
         };
         const genericConfig = generateMcpConfig(genericAgent, MCP_ENDPOINT, anonKey);
         await writeMcpConfig(genericAgent, genericConfig, projectRoot);
-        if (genericAgent.mcpConfigPath !== null && fs7.existsSync(genericAgent.mcpConfigPath)) {
+        if (genericAgent.mcpConfigPath !== null && fs8.existsSync(genericAgent.mcpConfigPath)) {
           anyConfigWritten = true;
         }
         agents = [];
@@ -17240,8 +17533,22 @@ async function runInit(options) {
       for (const agent of agents) {
         try {
           const configContent = generateMcpConfig(agent, MCP_ENDPOINT, anonKey);
+          const decision = await decideMcpConfigAction({
+            configPath: agent.mcpConfigPath,
+            expectedContent: configContent,
+            force: options.force === true || options.yes
+          });
+          if (decision === "skip") {
+            summary.push(
+              `Preserved existing ${agent.mcpConfigPath ?? agent.name} (user declined overwrite)`
+            );
+            if (agent.mcpConfigPath !== null && fs8.existsSync(agent.mcpConfigPath)) {
+              anyConfigWritten = true;
+            }
+            continue;
+          }
           await writeMcpConfig(agent, configContent, projectRoot);
-          const configExists = agent.mcpConfigPath !== null && fs7.existsSync(agent.mcpConfigPath);
+          const configExists = agent.mcpConfigPath !== null && fs8.existsSync(agent.mcpConfigPath);
           if (!configExists) {
             continue;
           }
@@ -17311,11 +17618,14 @@ function parseArgs(argv) {
   const args = argv.slice(2);
   let yes = false;
   let coverageMap = false;
+  let force = false;
   for (const arg of args) {
     if (arg === "--yes" || arg === "-y") {
       yes = true;
     } else if (arg === "--coverage-map") {
       coverageMap = true;
+    } else if (arg === "--force") {
+      force = true;
     }
   }
   if (!process.stdin.isTTY) {
@@ -17324,11 +17634,12 @@ function parseArgs(argv) {
   return {
     projectRoot: process.cwd(),
     yes,
-    coverageMap
+    coverageMap,
+    force
   };
 }
 var scriptPath = typeof process !== "undefined" && process.argv[1] !== void 0 ? process.argv[1].replace(/\\/g, "/") : void 0;
-var scriptBasename = scriptPath !== void 0 ? path7.basename(scriptPath) : void 0;
+var scriptBasename = scriptPath !== void 0 ? path8.basename(scriptPath) : void 0;
 var isDirectExecution = scriptPath !== void 0 && (scriptPath.endsWith("/cli/init.js") || scriptPath.endsWith("/cli/init.ts") || scriptBasename === "glasstrace");
 if (isDirectExecution) {
   if (!meetsNodeVersion(20)) {
@@ -17366,47 +17677,78 @@ Usage: glasstrace mcp add [--force] [--dry-run]
       process.exit(1);
     }
   } else if (subcommand === void 0 || subcommand === "init" || subcommand.startsWith("-")) {
-    const options = parseArgs(process.argv);
-    runInit(options).then((result) => {
-      if (result.errors.length > 0) {
-        for (const err of result.errors) {
-          process.stderr.write(`Error: ${err}
-`);
-        }
+    const forwardedArgs = process.argv.slice(subcommand === "init" ? 3 : 2);
+    if (forwardedArgs.includes("--validate")) {
+      let validateProjectRoot = process.cwd();
+      try {
+        validateProjectRoot = resolveProjectRoot(validateProjectRoot).projectRoot;
+      } catch {
       }
-      if (result.warnings.length > 0) {
-        for (const warn of result.warnings) {
-          process.stderr.write(`Warning: ${warn}
+      Promise.resolve().then(() => (init_validate(), validate_exports)).then(({ runValidate: runValidate2 }) => runValidate2({ projectRoot: validateProjectRoot })).then((result) => {
+        for (const line of result.summary) {
+          process.stderr.write(`${line}
 `);
         }
-      }
-      if (result.summary.length > 0) {
-        process.stderr.write("\nGlasstrace initialized successfully!\n\n");
-        for (const line of result.summary) {
-          process.stderr.write(`  - ${line}
+        for (const issue2 of result.issues) {
+          process.stderr.write(`  - ${issue2.message}
+`);
+          if (issue2.fix) {
+            process.stderr.write(`      Fix: ${issue2.fix}
 `);
+          }
         }
-        process.stderr.write("\nNext steps:\n");
-        process.stderr.write("  1. Start your Next.js dev server\n");
+        process.exit(result.exitCode);
+      }).catch((err) => {
         process.stderr.write(
-          "  2. Glasstrace works immediately in anonymous mode\n"
+          `Fatal error: ${err instanceof Error ? err.message : String(err)}
+`
         );
+        process.exit(1);
+      });
+    } else {
+      const options = parseArgs(process.argv);
+      runInit(options).then((result) => {
+        if (result.errors.length > 0) {
+          for (const err of result.errors) {
+            process.stderr.write(`Error: ${err}
+`);
+          }
+        }
+        if (result.warnings.length > 0) {
+          for (const warn of result.warnings) {
+            process.stderr.write(`Warning: ${warn}
+`);
+          }
+        }
+        if (result.summary.length > 0) {
+          process.stderr.write("\nGlasstrace initialized successfully!\n\n");
+          for (const line of result.summary) {
+            process.stderr.write(`  - ${line}
+`);
+          }
+          process.stderr.write("\nNext steps:\n");
+          process.stderr.write("  1. Start your Next.js dev server\n");
+          process.stderr.write(
+            "  2. Glasstrace works immediately in anonymous mode\n"
+          );
+          process.stderr.write(
+            "  3. To link to your account, set GLASSTRACE_API_KEY in .env.local\n\n"
+          );
+        }
+        process.exit(result.exitCode);
+      }).catch((err) => {
         process.stderr.write(
-          "  3. To link to your account, set GLASSTRACE_API_KEY in .env.local\n\n"
-        );
-      }
-      process.exit(result.exitCode);
-    }).catch((err) => {
-      process.stderr.write(
-        `Fatal error: ${err instanceof Error ? err.message : String(err)}
+          `Fatal error: ${err instanceof Error ? err.message : String(err)}
 `
-      );
-      process.exit(1);
-    });
+        );
+        process.exit(1);
+      });
+    }
   } else if (subcommand === "uninit") {
     const remainingArgs = process.argv.slice(3);
     const dryRun = remainingArgs.includes("--dry-run");
-    Promise.resolve().then(() => (init_uninit(), uninit_exports)).then(({ runUninit: runUninit2 }) => runUninit2({ projectRoot: process.cwd(), dryRun })).then((result) => {
+    const force = remainingArgs.includes("--force");
+    Promise.resolve().then(() => (init_uninit(), uninit_exports)).then(({ runUninit: runUninit2 }) => runUninit2({ projectRoot: process.cwd(), dryRun, force })).then((result) => {
       if (result.errors.length > 0) {
         for (const err of result.errors) {
           process.stderr.write(`Error: ${err}
@@ -17480,8 +17822,8 @@ Usage: glasstrace mcp add [--force] [--dry-run]
       `Unknown command: ${subcommand}
 
 Usage:
-  glasstrace init [--yes] [--coverage-map]
-  glasstrace uninit [--dry-run]
+  glasstrace init [--yes] [--coverage-map] [--force] [--validate]
+  glasstrace uninit [--dry-run] [--force]
   glasstrace status [--json]
   glasstrace mcp add [--force] [--dry-run]
 `
@@ -17491,6 +17833,7 @@ Usage:
 }
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  decideMcpConfigAction,
   meetsNodeVersion,
   rollbackSteps,
   runInit