@glasstrace/sdk 0.14.2 → 0.15.1

package/dist/cli/validate.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/validate.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\n\n/**\n * A single artifact-state inconsistency detected by `sdk init --validate`.\n */\nexport interface ValidationIssue {\n  /** Stable machine-readable identifier for the issue class. */\n  code:\n    | \"glasstrace-dir-without-register-import\"\n    | \"sdk-import-without-glasstrace-dir\"\n    | \"mcp-marker-without-configs\"\n    | \"mcp-configs-without-marker\";\n  /** Human-readable message describing the inconsistency. */\n  message: string;\n  /** Suggested command or manual action to resolve the issue. */\n  fix: string;\n}\n\n/** Options for `runValidate`. */\nexport interface ValidateOptions {\n  projectRoot: string;\n}\n\n/** Structured result of running the validator. */\nexport interface ValidateResult {\n  /** Zero when no issues; non-zero when any issue is detected. */\n  exitCode: number;\n  /** Ordered lines of human-friendly summary output. */\n  summary: string[];\n  /** Detailed per-issue findings. */\n  issues: ValidationIssue[];\n}\n\n/** MCP config files init may create. Used to detect stale state. */\nconst MCP_CONFIG_CANDIDATES = [\n  \".mcp.json\",\n  \".cursor/mcp.json\",\n  \".gemini/settings.json\",\n  \".codex/config.toml\",\n] as const;\n\n/**\n * Returns true when the given instrumentation file imports\n * `@glasstrace/sdk` (which includes the `registerGlasstrace` import\n * emitted by `sdk init`).\n *\n * @internal Exported for unit testing only.\n */\nexport function hasGlasstraceImport(content: string): boolean {\n  return /@glasstrace\\/sdk/.test(content);\n}\n\n/**\n * Returns true when the file imports `registerGlasstrace` specifically\n * (as opposed to other named exports such as `withGlasstraceConfig`).\n *\n * @internal Exported for unit testing only.\n */\nexport function hasRegisterGlasstraceImport(content: string): boolean {\n  // Single- or multi-specifier imports from @glasstrace/sdk that include\n  // `registerGlasstrace` as a named export.\n  const match = /import\\s*\\{([^}]+)\\}\\s*from\\s*[\"']@glasstrace\\/sdk[\"']/;\n  const importMatch = match.exec(content);\n  if (!importMatch) return false;\n  return importMatch[1]\n    .split(\",\")\n    .map((s) => s.trim())\n    .includes(\"registerGlasstrace\");\n}\n\n/**\n * Validates consistency between the filesystem artifacts that `sdk init`\n * produces (DISC-1247 Scenario 4). Detects four classes of inconsistency:\n *\n * 1. `.glasstrace/` exists but `instrumentation.ts` does not import\n *    `registerGlasstrace` from `@glasstrace/sdk`.\n * 2. `.glasstrace/` is missing but `instrumentation.ts` still imports\n *    from `@glasstrace/sdk`.\n * 3. `.glasstrace/mcp-connected` marker exists but no MCP config files.\n * 4. MCP config files exist but no `.glasstrace/mcp-connected` marker.\n *\n * Each issue includes a stable `code`, a message, and a suggested fix.\n * Exit code is non-zero whenever any issue is detected so CI pipelines\n * can gate on `sdk init --validate`.\n *\n * @param options - Configuration for the validator.\n * @returns A structured result describing detected inconsistencies.\n */\nexport function runValidate(options: ValidateOptions): ValidateResult {\n  const { projectRoot } = options;\n  const issues: ValidationIssue[] = [];\n\n  const glasstraceDir = path.join(projectRoot, \".glasstrace\");\n  const instrumentationPath = path.join(projectRoot, \"instrumentation.ts\");\n  const markerPath = path.join(glasstraceDir, \"mcp-connected\");\n\n  const glasstraceDirExists = isDirectorySafe(glasstraceDir);\n  const instrumentationExists = fs.existsSync(instrumentationPath);\n  const instrumentationContent = instrumentationExists\n    ? safeReadFile(instrumentationPath)\n    : null;\n  const markerExists = fs.existsSync(markerPath);\n\n  const mcpConfigsPresent = MCP_CONFIG_CANDIDATES.filter((rel) =>\n    fs.existsSync(path.join(projectRoot, rel)),\n  );\n\n  // 1. .glasstrace/ present but instrumentation missing the SDK import\n  if (glasstraceDirExists) {\n    if (\n      instrumentationContent === null ||\n      !hasRegisterGlasstraceImport(instrumentationContent)\n    ) {\n      issues.push({\n        code: \"glasstrace-dir-without-register-import\",\n        message:\n          \".glasstrace/ exists but instrumentation.ts is missing the registerGlasstrace import.\",\n        fix: \"Run `npx glasstrace init` to re-scaffold instrumentation.ts, or remove .glasstrace/ if the SDK is no longer in use.\",\n      });\n    }\n  }\n\n  // 2. .glasstrace/ missing but instrumentation still imports the SDK\n  if (!glasstraceDirExists && instrumentationContent !== null) {\n    if (hasGlasstraceImport(instrumentationContent)) {\n      issues.push({\n        code: \"sdk-import-without-glasstrace-dir\",\n        message:\n          \"instrumentation.ts imports from @glasstrace/sdk but .glasstrace/ is missing.\",\n        fix: \"Run `npx glasstrace init` to recreate .glasstrace/, or `npx glasstrace uninit` to fully remove the SDK.\",\n      });\n    }\n  }\n\n  // 3. MCP marker present but no MCP config files exist\n  if (markerExists && mcpConfigsPresent.length === 0) {\n    issues.push({\n      code: \"mcp-marker-without-configs\",\n      message:\n        \".glasstrace/mcp-connected marker is present but no MCP config files were found.\",\n      fix: \"Run `npx glasstrace mcp add --force` to regenerate MCP configs, or delete .glasstrace/mcp-connected.\",\n    });\n  }\n\n  // 4. MCP config files exist but no marker\n  if (!markerExists && mcpConfigsPresent.length > 0) {\n    issues.push({\n      code: \"mcp-configs-without-marker\",\n      message: `MCP config files exist (${mcpConfigsPresent.join(\", \")}) but .glasstrace/mcp-connected marker is missing.`,\n      fix: \"Run `npx glasstrace init` to re-register the marker, or `npx glasstrace uninit` to fully remove MCP configuration.\",\n    });\n  }\n\n  const summary: string[] = [];\n  if (issues.length === 0) {\n    summary.push(\"Glasstrace install state is consistent.\");\n  } else {\n    summary.push(\n      `Detected ${issues.length} inconsistenc${issues.length === 1 ? \"y\" : \"ies\"} in Glasstrace install state:`,\n    );\n  }\n\n  return {\n    exitCode: issues.length > 0 ? 1 : 0,\n    summary,\n    issues,\n  };\n}\n\n/**\n * Reads a file as UTF-8, returning `null` if the file cannot be read.\n */\nfunction safeReadFile(filePath: string): string | null {\n  try {\n    return fs.readFileSync(filePath, \"utf-8\");\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Returns true when the path exists and is a directory. Returns false\n * when the path is missing, is not a directory, or when `statSync`\n * throws (permission denied, TOCTOU race between existsSync and\n * statSync, etc). Validation is best-effort and must not throw — a\n * crash here would turn a reporting tool into a hard failure.\n */\nfunction isDirectorySafe(dirPath: string): boolean {\n  try {\n    if (!fs.existsSync(dirPath)) return false;\n    return fs.statSync(dirPath).isDirectory();\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,SAAoB;AACpB,WAAsB;AAkCtB,IAAM,wBAAwB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AASO,SAAS,oBAAoB,SAA0B;AAC5D,SAAO,mBAAmB,KAAK,OAAO;AACxC;AAQO,SAAS,4BAA4B,SAA0B;AAGpE,QAAM,QAAQ;AACd,QAAM,cAAc,MAAM,KAAK,OAAO;AACtC,MAAI,CAAC,YAAa,QAAO;AACzB,SAAO,YAAY,CAAC,EACjB,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,SAAS,oBAAoB;AAClC;AAoBO,SAAS,YAAY,SAA0C;AACpE,QAAM,EAAE,YAAY,IAAI;AACxB,QAAM,SAA4B,CAAC;AAEnC,QAAM,gBAAqB,UAAK,aAAa,aAAa;AAC1D,QAAM,sBAA2B,UAAK,aAAa,oBAAoB;AACvE,QAAM,aAAkB,UAAK,eAAe,eAAe;AAE3D,QAAM,sBAAsB,gBAAgB,aAAa;AACzD,QAAM,wBAA2B,cAAW,mBAAmB;AAC/D,QAAM,yBAAyB,wBAC3B,aAAa,mBAAmB,IAChC;AACJ,QAAM,eAAkB,cAAW,UAAU;AAE7C,QAAM,oBAAoB,sBAAsB;AAAA,IAAO,CAAC,QACnD,cAAgB,UAAK,aAAa,GAAG,CAAC;AAAA,EAC3C;AAGA,MAAI,qBAAqB;AACvB,QACE,2BAA2B,QAC3B,CAAC,4BAA4B,sBAAsB,GACnD;AACA,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SACE;AAAA,QACF,KAAK;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,CAAC,uBAAuB,2BAA2B,MAAM;AAC3D,QAAI,oBAAoB,sBAAsB,GAAG;AAC/C,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SACE;AAAA,QACF,KAAK;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,gBAAgB,kBAAkB,WAAW,GAAG;AAClD,WAAO,KAAK;AAAA,MACV,MAAM;AAAA,MACN,SACE;AAAA,MACF,KAAK;AAAA,IACP,CAAC;AAAA,EACH;AAGA,MAAI,CAAC,gBAAgB,kBAAkB,SAAS,GAAG;AACjD,WAAO,KAAK;AAAA,MACV,MAAM;AAAA,MACN,SAAS,2BAA2B,kBAAkB,KAAK,IAAI,CAAC;AAAA,MAChE,KAAK;AAAA,IACP,CAAC;AAAA,EACH;AAEA,QAAM,UAAoB,CAAC;AAC3B,MAAI,OAAO,WAAW,GAAG;AACvB,YAAQ,KAAK,yCAAyC;AAAA,EACxD,OAAO;AACL,YAAQ;AAAA,MACN,YAAY,OAAO,MAAM,gBAAgB,OAAO,WAAW,IAAI,MAAM,KAAK;AAAA,IAC5E;AAAA,EACF;AAEA,SAAO;AAAA,IACL,UAAU,OAAO,SAAS,IAAI,IAAI;AAAA,IAClC;AAAA,IACA;AAAA,EACF;AACF;AAKA,SAAS,aAAa,UAAiC;AACrD,MAAI;AACF,WAAU,gBAAa,UAAU,OAAO;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASA,SAAS,gBAAgB,SAA0B;AACjD,MAAI;AACF,QAAI,CAAI,cAAW,OAAO,EAAG,QAAO;AACpC,WAAU,YAAS,OAAO,EAAE,YAAY;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/cli/validate.d.cts

@@ -0,0 +1,60 @@
+/**
+ * A single artifact-state inconsistency detected by `sdk init --validate`.
+ */
+interface ValidationIssue {
+    /** Stable machine-readable identifier for the issue class. */
+    code: "glasstrace-dir-without-register-import" | "sdk-import-without-glasstrace-dir" | "mcp-marker-without-configs" | "mcp-configs-without-marker";
+    /** Human-readable message describing the inconsistency. */
+    message: string;
+    /** Suggested command or manual action to resolve the issue. */
+    fix: string;
+}
+/** Options for `runValidate`. */
+interface ValidateOptions {
+    projectRoot: string;
+}
+/** Structured result of running the validator. */
+interface ValidateResult {
+    /** Zero when no issues; non-zero when any issue is detected. */
+    exitCode: number;
+    /** Ordered lines of human-friendly summary output. */
+    summary: string[];
+    /** Detailed per-issue findings. */
+    issues: ValidationIssue[];
+}
+/**
+ * Returns true when the given instrumentation file imports
+ * `@glasstrace/sdk` (which includes the `registerGlasstrace` import
+ * emitted by `sdk init`).
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function hasGlasstraceImport(content: string): boolean;
+/**
+ * Returns true when the file imports `registerGlasstrace` specifically
+ * (as opposed to other named exports such as `withGlasstraceConfig`).
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function hasRegisterGlasstraceImport(content: string): boolean;
+/**
+ * Validates consistency between the filesystem artifacts that `sdk init`
+ * produces (DISC-1247 Scenario 4). Detects four classes of inconsistency:
+ *
+ * 1. `.glasstrace/` exists but `instrumentation.ts` does not import
+ *    `registerGlasstrace` from `@glasstrace/sdk`.
+ * 2. `.glasstrace/` is missing but `instrumentation.ts` still imports
+ *    from `@glasstrace/sdk`.
+ * 3. `.glasstrace/mcp-connected` marker exists but no MCP config files.
+ * 4. MCP config files exist but no `.glasstrace/mcp-connected` marker.
+ *
+ * Each issue includes a stable `code`, a message, and a suggested fix.
+ * Exit code is non-zero whenever any issue is detected so CI pipelines
+ * can gate on `sdk init --validate`.
+ *
+ * @param options - Configuration for the validator.
+ * @returns A structured result describing detected inconsistencies.
+ */
+declare function runValidate(options: ValidateOptions): ValidateResult;
+
+export { type ValidateOptions, type ValidateResult, type ValidationIssue, hasGlasstraceImport, hasRegisterGlasstraceImport, runValidate };

package/dist/cli/validate.d.ts

@@ -0,0 +1,60 @@
+/**
+ * A single artifact-state inconsistency detected by `sdk init --validate`.
+ */
+interface ValidationIssue {
+    /** Stable machine-readable identifier for the issue class. */
+    code: "glasstrace-dir-without-register-import" | "sdk-import-without-glasstrace-dir" | "mcp-marker-without-configs" | "mcp-configs-without-marker";
+    /** Human-readable message describing the inconsistency. */
+    message: string;
+    /** Suggested command or manual action to resolve the issue. */
+    fix: string;
+}
+/** Options for `runValidate`. */
+interface ValidateOptions {
+    projectRoot: string;
+}
+/** Structured result of running the validator. */
+interface ValidateResult {
+    /** Zero when no issues; non-zero when any issue is detected. */
+    exitCode: number;
+    /** Ordered lines of human-friendly summary output. */
+    summary: string[];
+    /** Detailed per-issue findings. */
+    issues: ValidationIssue[];
+}
+/**
+ * Returns true when the given instrumentation file imports
+ * `@glasstrace/sdk` (which includes the `registerGlasstrace` import
+ * emitted by `sdk init`).
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function hasGlasstraceImport(content: string): boolean;
+/**
+ * Returns true when the file imports `registerGlasstrace` specifically
+ * (as opposed to other named exports such as `withGlasstraceConfig`).
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function hasRegisterGlasstraceImport(content: string): boolean;
+/**
+ * Validates consistency between the filesystem artifacts that `sdk init`
+ * produces (DISC-1247 Scenario 4). Detects four classes of inconsistency:
+ *
+ * 1. `.glasstrace/` exists but `instrumentation.ts` does not import
+ *    `registerGlasstrace` from `@glasstrace/sdk`.
+ * 2. `.glasstrace/` is missing but `instrumentation.ts` still imports
+ *    from `@glasstrace/sdk`.
+ * 3. `.glasstrace/mcp-connected` marker exists but no MCP config files.
+ * 4. MCP config files exist but no `.glasstrace/mcp-connected` marker.
+ *
+ * Each issue includes a stable `code`, a message, and a suggested fix.
+ * Exit code is non-zero whenever any issue is detected so CI pipelines
+ * can gate on `sdk init --validate`.
+ *
+ * @param options - Configuration for the validator.
+ * @returns A structured result describing detected inconsistencies.
+ */
+declare function runValidate(options: ValidateOptions): ValidateResult;
+
+export { type ValidateOptions, type ValidateResult, type ValidationIssue, hasGlasstraceImport, hasRegisterGlasstraceImport, runValidate };

package/dist/cli/validate.js

@@ -0,0 +1,103 @@
+import {
+  init_esm_shims
+} from "../chunk-BGZ7J74D.js";
+
+// src/cli/validate.ts
+init_esm_shims();
+import * as fs from "fs";
+import * as path from "path";
+var MCP_CONFIG_CANDIDATES = [
+  ".mcp.json",
+  ".cursor/mcp.json",
+  ".gemini/settings.json",
+  ".codex/config.toml"
+];
+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 = path.join(projectRoot, ".glasstrace");
+  const instrumentationPath = path.join(projectRoot, "instrumentation.ts");
+  const markerPath = path.join(glasstraceDir, "mcp-connected");
+  const glasstraceDirExists = isDirectorySafe(glasstraceDir);
+  const instrumentationExists = fs.existsSync(instrumentationPath);
+  const instrumentationContent = instrumentationExists ? safeReadFile(instrumentationPath) : null;
+  const markerExists = fs.existsSync(markerPath);
+  const mcpConfigsPresent = MCP_CONFIG_CANDIDATES.filter(
+    (rel) => fs.existsSync(path.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 fs.readFileSync(filePath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function isDirectorySafe(dirPath) {
+  try {
+    if (!fs.existsSync(dirPath)) return false;
+    return fs.statSync(dirPath).isDirectory();
+  } catch {
+    return false;
+  }
+}
+export {
+  hasGlasstraceImport,
+  hasRegisterGlasstraceImport,
+  runValidate
+};
+//# sourceMappingURL=validate.js.map

package/dist/cli/validate.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/cli/validate.ts"],"sourcesContent":["import * as fs from \"node:fs\";\nimport * as path from \"node:path\";\n\n/**\n * A single artifact-state inconsistency detected by `sdk init --validate`.\n */\nexport interface ValidationIssue {\n  /** Stable machine-readable identifier for the issue class. */\n  code:\n    | \"glasstrace-dir-without-register-import\"\n    | \"sdk-import-without-glasstrace-dir\"\n    | \"mcp-marker-without-configs\"\n    | \"mcp-configs-without-marker\";\n  /** Human-readable message describing the inconsistency. */\n  message: string;\n  /** Suggested command or manual action to resolve the issue. */\n  fix: string;\n}\n\n/** Options for `runValidate`. */\nexport interface ValidateOptions {\n  projectRoot: string;\n}\n\n/** Structured result of running the validator. */\nexport interface ValidateResult {\n  /** Zero when no issues; non-zero when any issue is detected. */\n  exitCode: number;\n  /** Ordered lines of human-friendly summary output. */\n  summary: string[];\n  /** Detailed per-issue findings. */\n  issues: ValidationIssue[];\n}\n\n/** MCP config files init may create. Used to detect stale state. */\nconst MCP_CONFIG_CANDIDATES = [\n  \".mcp.json\",\n  \".cursor/mcp.json\",\n  \".gemini/settings.json\",\n  \".codex/config.toml\",\n] as const;\n\n/**\n * Returns true when the given instrumentation file imports\n * `@glasstrace/sdk` (which includes the `registerGlasstrace` import\n * emitted by `sdk init`).\n *\n * @internal Exported for unit testing only.\n */\nexport function hasGlasstraceImport(content: string): boolean {\n  return /@glasstrace\\/sdk/.test(content);\n}\n\n/**\n * Returns true when the file imports `registerGlasstrace` specifically\n * (as opposed to other named exports such as `withGlasstraceConfig`).\n *\n * @internal Exported for unit testing only.\n */\nexport function hasRegisterGlasstraceImport(content: string): boolean {\n  // Single- or multi-specifier imports from @glasstrace/sdk that include\n  // `registerGlasstrace` as a named export.\n  const match = /import\\s*\\{([^}]+)\\}\\s*from\\s*[\"']@glasstrace\\/sdk[\"']/;\n  const importMatch = match.exec(content);\n  if (!importMatch) return false;\n  return importMatch[1]\n    .split(\",\")\n    .map((s) => s.trim())\n    .includes(\"registerGlasstrace\");\n}\n\n/**\n * Validates consistency between the filesystem artifacts that `sdk init`\n * produces (DISC-1247 Scenario 4). Detects four classes of inconsistency:\n *\n * 1. `.glasstrace/` exists but `instrumentation.ts` does not import\n *    `registerGlasstrace` from `@glasstrace/sdk`.\n * 2. `.glasstrace/` is missing but `instrumentation.ts` still imports\n *    from `@glasstrace/sdk`.\n * 3. `.glasstrace/mcp-connected` marker exists but no MCP config files.\n * 4. MCP config files exist but no `.glasstrace/mcp-connected` marker.\n *\n * Each issue includes a stable `code`, a message, and a suggested fix.\n * Exit code is non-zero whenever any issue is detected so CI pipelines\n * can gate on `sdk init --validate`.\n *\n * @param options - Configuration for the validator.\n * @returns A structured result describing detected inconsistencies.\n */\nexport function runValidate(options: ValidateOptions): ValidateResult {\n  const { projectRoot } = options;\n  const issues: ValidationIssue[] = [];\n\n  const glasstraceDir = path.join(projectRoot, \".glasstrace\");\n  const instrumentationPath = path.join(projectRoot, \"instrumentation.ts\");\n  const markerPath = path.join(glasstraceDir, \"mcp-connected\");\n\n  const glasstraceDirExists = isDirectorySafe(glasstraceDir);\n  const instrumentationExists = fs.existsSync(instrumentationPath);\n  const instrumentationContent = instrumentationExists\n    ? safeReadFile(instrumentationPath)\n    : null;\n  const markerExists = fs.existsSync(markerPath);\n\n  const mcpConfigsPresent = MCP_CONFIG_CANDIDATES.filter((rel) =>\n    fs.existsSync(path.join(projectRoot, rel)),\n  );\n\n  // 1. .glasstrace/ present but instrumentation missing the SDK import\n  if (glasstraceDirExists) {\n    if (\n      instrumentationContent === null ||\n      !hasRegisterGlasstraceImport(instrumentationContent)\n    ) {\n      issues.push({\n        code: \"glasstrace-dir-without-register-import\",\n        message:\n          \".glasstrace/ exists but instrumentation.ts is missing the registerGlasstrace import.\",\n        fix: \"Run `npx glasstrace init` to re-scaffold instrumentation.ts, or remove .glasstrace/ if the SDK is no longer in use.\",\n      });\n    }\n  }\n\n  // 2. .glasstrace/ missing but instrumentation still imports the SDK\n  if (!glasstraceDirExists && instrumentationContent !== null) {\n    if (hasGlasstraceImport(instrumentationContent)) {\n      issues.push({\n        code: \"sdk-import-without-glasstrace-dir\",\n        message:\n          \"instrumentation.ts imports from @glasstrace/sdk but .glasstrace/ is missing.\",\n        fix: \"Run `npx glasstrace init` to recreate .glasstrace/, or `npx glasstrace uninit` to fully remove the SDK.\",\n      });\n    }\n  }\n\n  // 3. MCP marker present but no MCP config files exist\n  if (markerExists && mcpConfigsPresent.length === 0) {\n    issues.push({\n      code: \"mcp-marker-without-configs\",\n      message:\n        \".glasstrace/mcp-connected marker is present but no MCP config files were found.\",\n      fix: \"Run `npx glasstrace mcp add --force` to regenerate MCP configs, or delete .glasstrace/mcp-connected.\",\n    });\n  }\n\n  // 4. MCP config files exist but no marker\n  if (!markerExists && mcpConfigsPresent.length > 0) {\n    issues.push({\n      code: \"mcp-configs-without-marker\",\n      message: `MCP config files exist (${mcpConfigsPresent.join(\", \")}) but .glasstrace/mcp-connected marker is missing.`,\n      fix: \"Run `npx glasstrace init` to re-register the marker, or `npx glasstrace uninit` to fully remove MCP configuration.\",\n    });\n  }\n\n  const summary: string[] = [];\n  if (issues.length === 0) {\n    summary.push(\"Glasstrace install state is consistent.\");\n  } else {\n    summary.push(\n      `Detected ${issues.length} inconsistenc${issues.length === 1 ? \"y\" : \"ies\"} in Glasstrace install state:`,\n    );\n  }\n\n  return {\n    exitCode: issues.length > 0 ? 1 : 0,\n    summary,\n    issues,\n  };\n}\n\n/**\n * Reads a file as UTF-8, returning `null` if the file cannot be read.\n */\nfunction safeReadFile(filePath: string): string | null {\n  try {\n    return fs.readFileSync(filePath, \"utf-8\");\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Returns true when the path exists and is a directory. Returns false\n * when the path is missing, is not a directory, or when `statSync`\n * throws (permission denied, TOCTOU race between existsSync and\n * statSync, etc). Validation is best-effort and must not throw — a\n * crash here would turn a reporting tool into a hard failure.\n */\nfunction isDirectorySafe(dirPath: string): boolean {\n  try {\n    if (!fs.existsSync(dirPath)) return false;\n    return fs.statSync(dirPath).isDirectory();\n  } catch {\n    return false;\n  }\n}\n"],"mappings":";;;;;AAAA;AAAA,YAAY,QAAQ;AACpB,YAAY,UAAU;AAkCtB,IAAM,wBAAwB;AAAA,EAC5B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AASO,SAAS,oBAAoB,SAA0B;AAC5D,SAAO,mBAAmB,KAAK,OAAO;AACxC;AAQO,SAAS,4BAA4B,SAA0B;AAGpE,QAAM,QAAQ;AACd,QAAM,cAAc,MAAM,KAAK,OAAO;AACtC,MAAI,CAAC,YAAa,QAAO;AACzB,SAAO,YAAY,CAAC,EACjB,MAAM,GAAG,EACT,IAAI,CAAC,MAAM,EAAE,KAAK,CAAC,EACnB,SAAS,oBAAoB;AAClC;AAoBO,SAAS,YAAY,SAA0C;AACpE,QAAM,EAAE,YAAY,IAAI;AACxB,QAAM,SAA4B,CAAC;AAEnC,QAAM,gBAAqB,UAAK,aAAa,aAAa;AAC1D,QAAM,sBAA2B,UAAK,aAAa,oBAAoB;AACvE,QAAM,aAAkB,UAAK,eAAe,eAAe;AAE3D,QAAM,sBAAsB,gBAAgB,aAAa;AACzD,QAAM,wBAA2B,cAAW,mBAAmB;AAC/D,QAAM,yBAAyB,wBAC3B,aAAa,mBAAmB,IAChC;AACJ,QAAM,eAAkB,cAAW,UAAU;AAE7C,QAAM,oBAAoB,sBAAsB;AAAA,IAAO,CAAC,QACnD,cAAgB,UAAK,aAAa,GAAG,CAAC;AAAA,EAC3C;AAGA,MAAI,qBAAqB;AACvB,QACE,2BAA2B,QAC3B,CAAC,4BAA4B,sBAAsB,GACnD;AACA,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SACE;AAAA,QACF,KAAK;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,CAAC,uBAAuB,2BAA2B,MAAM;AAC3D,QAAI,oBAAoB,sBAAsB,GAAG;AAC/C,aAAO,KAAK;AAAA,QACV,MAAM;AAAA,QACN,SACE;AAAA,QACF,KAAK;AAAA,MACP,CAAC;AAAA,IACH;AAAA,EACF;AAGA,MAAI,gBAAgB,kBAAkB,WAAW,GAAG;AAClD,WAAO,KAAK;AAAA,MACV,MAAM;AAAA,MACN,SACE;AAAA,MACF,KAAK;AAAA,IACP,CAAC;AAAA,EACH;AAGA,MAAI,CAAC,gBAAgB,kBAAkB,SAAS,GAAG;AACjD,WAAO,KAAK;AAAA,MACV,MAAM;AAAA,MACN,SAAS,2BAA2B,kBAAkB,KAAK,IAAI,CAAC;AAAA,MAChE,KAAK;AAAA,IACP,CAAC;AAAA,EACH;AAEA,QAAM,UAAoB,CAAC;AAC3B,MAAI,OAAO,WAAW,GAAG;AACvB,YAAQ,KAAK,yCAAyC;AAAA,EACxD,OAAO;AACL,YAAQ;AAAA,MACN,YAAY,OAAO,MAAM,gBAAgB,OAAO,WAAW,IAAI,MAAM,KAAK;AAAA,IAC5E;AAAA,EACF;AAEA,SAAO;AAAA,IACL,UAAU,OAAO,SAAS,IAAI,IAAI;AAAA,IAClC;AAAA,IACA;AAAA,EACF;AACF;AAKA,SAAS,aAAa,UAAiC;AACrD,MAAI;AACF,WAAU,gBAAa,UAAU,OAAO;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AASA,SAAS,gBAAgB,SAA0B;AACjD,MAAI;AACF,QAAI,CAAI,cAAW,OAAO,EAAG,QAAO;AACpC,WAAU,YAAS,OAAO,EAAE,YAAY;AAAA,EAC1C,QAAQ;AACN,WAAO;AAAA,EACT;AACF;","names":[]}

package/dist/index.cjs

@@ -17228,6 +17228,7 @@ async function saveCachedConfig(response, projectRoot) {
   const root = projectRoot ?? process.cwd();
   const dirPath = modules.path.join(root, GLASSTRACE_DIR2);
   const configPath = modules.path.join(dirPath, CONFIG_FILE);
+  const tmpPath = `${configPath}.tmp`;
   try {
     await modules.fs.mkdir(dirPath, { recursive: true, mode: 448 });
     await modules.fs.chmod(dirPath, 448);
@@ -17235,7 +17236,20 @@ async function saveCachedConfig(response, projectRoot) {
       response,
       cachedAt: Date.now()
     };
-    await modules.fs.writeFile(configPath, JSON.stringify(cached2), { encoding: "utf-8", mode: 384 });
+    await modules.fs.writeFile(tmpPath, JSON.stringify(cached2), {
+      encoding: "utf-8",
+      mode: 384
+    });
+    try {
+      await modules.fs.chmod(tmpPath, 384);
+      await modules.fs.rename(tmpPath, configPath);
+    } catch (renameErr) {
+      try {
+        await modules.fs.unlink(tmpPath);
+      } catch {
+      }
+      throw renameErr;
+    }
     await modules.fs.chmod(configPath, 384);
   } catch (err) {
     console.warn(
@@ -21383,7 +21397,6 @@ async function configureOtel(config2, sessionManager) {
       await provider.shutdown();
     }
   });
-  registerSignalHandlers();
   registerBeforeExitTrigger();
   const prismaModule = await tryImport("@prisma/instrumentation");
   if (prismaModule) {
@@ -21444,12 +21457,15 @@ var HEARTBEAT_INTERVAL_MS = 5 * 60 * 1e3;
 var BACKOFF_BASE_MS = HEARTBEAT_INTERVAL_MS;
 var BACKOFF_MAX_MS = 30 * 60 * 1e3;
 var BACKOFF_JITTER = 0.2;
+var HEARTBEAT_SHUTDOWN_PRIORITY = 10;
+var SHUTDOWN_MARKER_RELPATH = ".glasstrace/shutdown-requested";
 var heartbeatTimer = null;
 var heartbeatGeneration = 0;
 var backoffAttempts = 0;
 var backoffUntil = 0;
 var tickInProgress = false;
-var _shutdownHandler = null;
+var shutdownHookRegistered = false;
+var shutdownFired = false;
 function startHeartbeat(config2, anonKey, sdkVersion, generation, onClaimTransition) {
   if (heartbeatTimer !== null) return;
   heartbeatGeneration = generation;
@@ -21457,7 +21473,7 @@ function startHeartbeat(config2, anonKey, sdkVersion, generation, onClaimTransit
     void heartbeatTick(config2, anonKey, sdkVersion, generation, onClaimTransition);
   }, HEARTBEAT_INTERVAL_MS);
   heartbeatTimer.unref();
-  registerShutdownHandlers(config2, anonKey, sdkVersion);
+  registerHeartbeatShutdownHook(config2, anonKey, sdkVersion);
   if (config2.verbose) {
     sdkLog("info", "[glasstrace] Heartbeat started (5-minute interval).");
   }
@@ -21467,7 +21483,26 @@ function stopHeartbeat() {
     clearInterval(heartbeatTimer);
     heartbeatTimer = null;
   }
-  removeShutdownHandlers();
+}
+function checkShutdownMarker(projectRoot) {
+  let fsSync2 = null;
+  let pathSync = null;
+  try {
+    fsSync2 = require("fs");
+    pathSync = require("path");
+  } catch {
+    return { triggered: false };
+  }
+  const root = projectRoot ?? (typeof process !== "undefined" ? process.cwd() : ".");
+  const markerPath = pathSync.join(root, SHUTDOWN_MARKER_RELPATH);
+  if (!fsSync2.existsSync(markerPath)) return { triggered: false };
+  try {
+    fsSync2.unlinkSync(markerPath);
+  } catch {
+  }
+  const shutdown = executeShutdown().catch(() => {
+  });
+  return { triggered: true, shutdown };
 }
 async function heartbeatTick(config2, anonKey, sdkVersion, generation, onClaimTransition) {
   if (tickInProgress) return;
@@ -21477,6 +21512,14 @@ async function heartbeatTick(config2, anonKey, sdkVersion, generation, onClaimTr
       stopHeartbeat();
       return;
     }
+    const markerResult = checkShutdownMarker();
+    if (markerResult.triggered) {
+      stopHeartbeat();
+      if (markerResult.shutdown) {
+        await markerResult.shutdown;
+      }
+      return;
+    }
     if (Date.now() < backoffUntil) {
       if (config2.verbose) {
         sdkLog("info", "[glasstrace] Heartbeat skipped (rate-limit backoff).");
@@ -21511,35 +21554,26 @@ async function heartbeatTick(config2, anonKey, sdkVersion, generation, onClaimTr
     tickInProgress = false;
   }
 }
-function registerShutdownHandlers(config2, anonKey, sdkVersion) {
-  if (typeof process === "undefined" || typeof process.once !== "function") {
-    return;
-  }
-  let shutdownFired = false;
-  const handler = (signal) => {
-    if (shutdownFired) return;
-    shutdownFired = true;
-    if (heartbeatTimer !== null) {
-      clearInterval(heartbeatTimer);
-      heartbeatTimer = null;
+function registerHeartbeatShutdownHook(config2, anonKey, sdkVersion) {
+  if (shutdownHookRegistered) return;
+  shutdownHookRegistered = true;
+  registerShutdownHook({
+    name: "heartbeat-final-report",
+    priority: HEARTBEAT_SHUTDOWN_PRIORITY,
+    fn: async () => {
+      if (shutdownFired) return;
+      shutdownFired = true;
+      if (heartbeatTimer !== null) {
+        clearInterval(heartbeatTimer);
+        heartbeatTimer = null;
+      }
+      try {
+        const healthReport = collectHealthReport(sdkVersion);
+        await performInit(config2, anonKey, sdkVersion, healthReport);
+      } catch {
+      }
     }
-    const healthReport = collectHealthReport(sdkVersion);
-    void performInit(config2, anonKey, sdkVersion, healthReport).catch(() => {
-    }).finally(() => {
-      removeShutdownHandlers();
-      process.kill(process.pid, signal);
-    });
-  };
-  _shutdownHandler = handler;
-  process.once("SIGTERM", _shutdownHandler);
-  process.once("SIGINT", _shutdownHandler);
-}
-function removeShutdownHandlers() {
-  if (_shutdownHandler && typeof process !== "undefined") {
-    process.removeListener("SIGTERM", _shutdownHandler);
-    process.removeListener("SIGINT", _shutdownHandler);
-    _shutdownHandler = null;
-  }
+  });
 }
 
 // src/runtime-state.ts
@@ -21641,7 +21675,7 @@ function registerGlasstrace(options) {
     setCoreState(CoreState.REGISTERING);
     startRuntimeStateWriter({
       projectRoot: process.cwd(),
-      sdkVersion: "0.14.2"
+      sdkVersion: "0.15.1"
     });
     const config2 = resolveConfig(options);
     if (config2.verbose) {
@@ -21657,6 +21691,11 @@ function registerGlasstrace(options) {
     if (config2.verbose) {
       console.info("[glasstrace] Not production-disabled.");
     }
+    const existingProbe = trace.getTracerProvider().getTracer("glasstrace-probe");
+    const anotherProviderRegistered = existingProbe.constructor.name !== "ProxyTracer";
+    if (!anotherProviderRegistered) {
+      registerSignalHandlers();
+    }
     const anonymous = isAnonymousMode(config2);
     let effectiveKey = config2.apiKey;
     initAuthState(anonymous ? AuthState.ANONYMOUS : AuthState.AUTHENTICATED);
@@ -21687,8 +21726,6 @@ function registerGlasstrace(options) {
     }
     setCoreState(CoreState.KEY_PENDING);
     const currentGeneration = registrationGeneration;
-    const existingProbe = trace.getTracerProvider().getTracer("glasstrace-probe");
-    const anotherProviderRegistered = existingProbe.constructor.name !== "ProxyTracer";
     if (anotherProviderRegistered) {
       if (config2.verbose) {
         console.info("[glasstrace] Another OTel provider detected \u2014 using existing context manager.");
@@ -21803,8 +21840,8 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   if (config2.verbose) {
     console.info("[glasstrace] Background init firing.");
   }
-  const healthReport = collectHealthReport("0.14.2");
-  const initResult = await performInit(config2, anonKeyForInit, "0.14.2", healthReport);
+  const healthReport = collectHealthReport("0.15.1");
+  const initResult = await performInit(config2, anonKeyForInit, "0.15.1", healthReport);
   if (generation !== registrationGeneration) return;
   const currentState = getCoreState();
   if (currentState === CoreState.SHUTTING_DOWN || currentState === CoreState.SHUTDOWN) {
@@ -21827,7 +21864,7 @@ async function backgroundInit(config2, anonKeyForInit, generation) {
   }
   maybeInstallConsoleCapture();
   if (didLastInitSucceed()) {
-    startHeartbeat(config2, anonKeyForInit, "0.14.2", generation, (newApiKey, accountId) => {
+    startHeartbeat(config2, anonKeyForInit, "0.15.1", generation, (newApiKey, accountId) => {
       setAuthState(AuthState.CLAIMING);
       emitLifecycleEvent("auth:claim_started", { accountId });
       setResolvedApiKey(newApiKey);