@glasstrace/sdk 0.19.0 → 0.20.0

package/dist/cli/init.d.cts

@@ -53,7 +53,7 @@ declare function decideMcpConfigAction(options: {
  * Identifies a scaffolding step that can be reversed during rollback.
  * Steps are tracked in execution order and rolled back in reverse.
  */
-type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignore";
+type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignore" | "discovery-file";
 /**
  * Tracks state needed for accurate rollback of init steps.
  * Separating this from the step list allows rollback to restore
@@ -74,6 +74,52 @@ interface RollbackState {
      *  When present, rollback restores this instead of using removeRegisterGlasstrace. */
     originalInstrumentationContent?: string;
 }
+/**
+ * Returns true when the given `.gitignore` content would exclude the
+ * static discovery file at `<root>/public/.well-known/glasstrace.json`
+ * or `<root>/static/.well-known/glasstrace.json` (depending on `layout`)
+ * from being committed.
+ *
+ * Model: the file has three ancestors in its committed path — the
+ * static root directory (`public/` or `static/`), the `.well-known/`
+ * sub-directory, and the file itself. Each pattern in `.gitignore` is
+ * classified by which ancestor paths it matches, and each ancestor
+ * carries its own current ignore state that later patterns can flip.
+ * Patterns that don't match any of the three ancestors are ignored.
+ *
+ * Per `gitignore(5)`:
+ *
+ * > It is not possible to re-include a file if a parent directory of
+ * > that file is excluded.
+ *
+ * Consequently, the file is reported as ignored when the final state
+ * of ANY ancestor (static root, `.well-known/`, or the file itself)
+ * is ignored — a `!<file>` negation alone cannot "escape" an ignored
+ * ancestor.
+ *
+ * Per-ancestor tracking is what distinguishes overlapping patterns:
+ *
+ *   - `public/` then `!public/`                       — root re-included, file OK.
+ *   - `public/` then `!public/.well-known/`           — root still ignored (scope-2
+ *     negation doesn't match the scope-1 ancestor path), file ignored.
+ *   - `.well-known/` then `!public/.well-known/`      — `.well-known/` re-included
+ *     (both patterns match the scope-2 ancestor), file OK.
+ *   - `.well-known/` then `!public/`                  — `!public/` matches the
+ *     scope-1 ancestor only; the scope-2 ancestor (`.well-known/`) is still
+ *     ignored, so the file is ignored.
+ *   - `<file>` then `!<file>`                         — file-level ignore flipped.
+ *   - `<file>` then `!public/.well-known/`            — directory negation does
+ *     not match the file path; file still ignored.
+ *
+ * Not-modeled rules — glob wildcards (star, question mark, character
+ * classes), overlapping any-depth matches across multiple parents, and
+ * nested `.gitignore` files — skew the heuristic toward false positives
+ * (extra warning output) rather than false negatives. The warning is
+ * advisory.
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function gitignoreExcludesDiscoveryFile(gitignoreContent: string, layout: "public" | "static"): boolean;
 /**
  * Best-effort rollback of completed init steps in reverse order.
  * Each step is individually try/caught so that a failure in one
@@ -132,4 +178,4 @@ type VerifyAnonKeyOutcome = {
  */
 declare function verifyAnonKeyRegistration(projectRoot: string): Promise<VerifyAnonKeyOutcome>;
 
-export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };
+export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, gitignoreExcludesDiscoveryFile, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };

package/dist/cli/init.d.ts

@@ -53,7 +53,7 @@ declare function decideMcpConfigAction(options: {
  * Identifies a scaffolding step that can be reversed during rollback.
  * Steps are tracked in execution order and rolled back in reverse.
  */
-type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignore";
+type CompletedStep = "instrumentation" | "next-config" | "env-local" | "gitignore" | "discovery-file";
 /**
  * Tracks state needed for accurate rollback of init steps.
  * Separating this from the step list allows rollback to restore
@@ -74,6 +74,52 @@ interface RollbackState {
      *  When present, rollback restores this instead of using removeRegisterGlasstrace. */
     originalInstrumentationContent?: string;
 }
+/**
+ * Returns true when the given `.gitignore` content would exclude the
+ * static discovery file at `<root>/public/.well-known/glasstrace.json`
+ * or `<root>/static/.well-known/glasstrace.json` (depending on `layout`)
+ * from being committed.
+ *
+ * Model: the file has three ancestors in its committed path — the
+ * static root directory (`public/` or `static/`), the `.well-known/`
+ * sub-directory, and the file itself. Each pattern in `.gitignore` is
+ * classified by which ancestor paths it matches, and each ancestor
+ * carries its own current ignore state that later patterns can flip.
+ * Patterns that don't match any of the three ancestors are ignored.
+ *
+ * Per `gitignore(5)`:
+ *
+ * > It is not possible to re-include a file if a parent directory of
+ * > that file is excluded.
+ *
+ * Consequently, the file is reported as ignored when the final state
+ * of ANY ancestor (static root, `.well-known/`, or the file itself)
+ * is ignored — a `!<file>` negation alone cannot "escape" an ignored
+ * ancestor.
+ *
+ * Per-ancestor tracking is what distinguishes overlapping patterns:
+ *
+ *   - `public/` then `!public/`                       — root re-included, file OK.
+ *   - `public/` then `!public/.well-known/`           — root still ignored (scope-2
+ *     negation doesn't match the scope-1 ancestor path), file ignored.
+ *   - `.well-known/` then `!public/.well-known/`      — `.well-known/` re-included
+ *     (both patterns match the scope-2 ancestor), file OK.
+ *   - `.well-known/` then `!public/`                  — `!public/` matches the
+ *     scope-1 ancestor only; the scope-2 ancestor (`.well-known/`) is still
+ *     ignored, so the file is ignored.
+ *   - `<file>` then `!<file>`                         — file-level ignore flipped.
+ *   - `<file>` then `!public/.well-known/`            — directory negation does
+ *     not match the file path; file still ignored.
+ *
+ * Not-modeled rules — glob wildcards (star, question mark, character
+ * classes), overlapping any-depth matches across multiple parents, and
+ * nested `.gitignore` files — skew the heuristic toward false positives
+ * (extra warning output) rather than false negatives. The warning is
+ * advisory.
+ *
+ * @internal Exported for unit testing only.
+ */
+declare function gitignoreExcludesDiscoveryFile(gitignoreContent: string, layout: "public" | "static"): boolean;
 /**
  * Best-effort rollback of completed init steps in reverse order.
  * Each step is individually try/caught so that a failure in one
@@ -132,4 +178,4 @@ type VerifyAnonKeyOutcome = {
  */
 declare function verifyAnonKeyRegistration(projectRoot: string): Promise<VerifyAnonKeyOutcome>;
 
-export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };
+export { type InitOptions, type InitResult, type VerifyAnonKeyOutcome, decideMcpConfigAction, gitignoreExcludesDiscoveryFile, meetsNodeVersion, rollbackSteps, runInit, verifyAnonKeyRegistration };

package/dist/cli/init.js

@@ -11,11 +11,15 @@ import {
 } from "../chunk-VUZCLMIX.js";
 import {
   isInitCreatedInstrumentation,
+  relativeDiscoveryPath,
+  removeDiscoveryFile,
   removeGlasstraceConfigImport,
   removeRegisterGlasstrace,
+  resolveStaticRoot,
   unwrapCJSExport,
-  unwrapExport
-} from "../chunk-XNDHQN4S.js";
+  unwrapExport,
+  writeDiscoveryFile
+} from "../chunk-6JRI4OGB.js";
 import {
   detectAgents,
   generateInfoSection,
@@ -28,7 +32,6 @@ import {
   getOrCreateAnonKey,
   readAnonKey
 } from "../chunk-YPXW2TN3.js";
-import "../chunk-5N2IR4EO.js";
 import {
   addCoverageMapEnv,
   isDevApiKey,
@@ -41,6 +44,7 @@ import {
   scaffoldMcpMarker,
   scaffoldNextConfig
 } from "../chunk-O63DJKIJ.js";
+import "../chunk-5N2IR4EO.js";
 import {
   MCP_ENDPOINT,
   NEXT_CONFIG_NAMES,
@@ -105,6 +109,53 @@ async function promptYesNo(question, defaultValue) {
 function cleanLeadingBlankLines(content) {
   return content.replace(/^\n{2,}/, "\n");
 }
+function gitignoreExcludesDiscoveryFile(gitignoreContent, layout) {
+  const staticRoot = layout === "static" ? "static" : "public";
+  const rootTargets = [staticRoot, `${staticRoot}/`];
+  const wellKnownTargets = [
+    `${staticRoot}/.well-known`,
+    `${staticRoot}/.well-known/`,
+    ".well-known",
+    ".well-known/"
+  ];
+  const fileTargets = [
+    `${staticRoot}/.well-known/glasstrace.json`,
+    ".well-known/glasstrace.json"
+  ];
+  let rootIgnored = false;
+  let wellKnownIgnored = false;
+  let fileIgnored = false;
+  for (const rawLine of gitignoreContent.split("\n")) {
+    const line = rawLine.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const negation = line.startsWith("!");
+    const pattern = negation ? line.slice(1).trim() : line;
+    if (pattern === "") continue;
+    const normalized = pattern.startsWith("/") ? pattern.slice(1) : pattern;
+    const matchesRoot = matchesDiscoveryPath(normalized, rootTargets);
+    const matchesWellKnown = matchesDiscoveryPath(normalized, wellKnownTargets);
+    const matchesFile = matchesDiscoveryPath(normalized, fileTargets);
+    if (!matchesRoot && !matchesWellKnown && !matchesFile) continue;
+    const newState = !negation;
+    if (matchesRoot) rootIgnored = newState;
+    if (matchesWellKnown) wellKnownIgnored = newState;
+    if (matchesFile) fileIgnored = newState;
+  }
+  return rootIgnored || wellKnownIgnored || fileIgnored;
+}
+function matchesDiscoveryPath(pattern, targets) {
+  const bare = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+  for (const target of targets) {
+    const tBare = target.endsWith("/") ? target.slice(0, -1) : target;
+    if (bare === tBare) return true;
+    if (pattern.startsWith("**/")) {
+      const suffix = pattern.slice(3);
+      const sBare = suffix.endsWith("/") ? suffix.slice(0, -1) : suffix;
+      if (tBare === sBare || tBare.endsWith(`/${sBare}`)) return true;
+    }
+  }
+  return false;
+}
 async function rollbackSteps(steps, projectRoot, state) {
   for (const step of [...steps].reverse()) {
     try {
@@ -185,6 +236,10 @@ async function rollbackSteps(steps, projectRoot, state) {
           }
           break;
         }
+        case "discovery-file": {
+          removeDiscoveryFile(projectRoot);
+          break;
+        }
       }
     } catch {
     }
@@ -348,6 +403,50 @@ Then add this as the first statement in your register() function:
     if (preExistingAnonKey !== null) {
       summary.push("Preserved existing .glasstrace/anon_key");
     }
+    try {
+      const discoveryResult = writeDiscoveryFile(projectRoot, anonKey);
+      const relPath = relativeDiscoveryPath(discoveryResult.layout);
+      switch (discoveryResult.action) {
+        case "created":
+          summary.push(`Created ${relPath}`);
+          rollbackState.steps.push("discovery-file");
+          break;
+        case "updated-stale":
+          summary.push(`Updated ${relPath} (anon key had changed)`);
+          break;
+        case "skipped-matches":
+          summary.push(`Skipped ${relPath} (already matches anon key)`);
+          break;
+        case "skipped-foreign":
+          summary.push(
+            `Rewrote ${relPath} (existing file was malformed or not SDK-managed)`
+          );
+          break;
+        case "failed":
+          warnings.push(
+            `Failed to write ${relPath}${discoveryResult.error !== void 0 ? `: ${discoveryResult.error}` : ""}. The Glasstrace browser extension will fall back to the runtime handler until the file is written.`
+          );
+          break;
+      }
+      const gitignorePath = path.join(projectRoot, ".gitignore");
+      if (fs.existsSync(gitignorePath)) {
+        try {
+          const gitignoreContent = fs.readFileSync(gitignorePath, "utf-8");
+          if (gitignoreExcludesDiscoveryFile(gitignoreContent, discoveryResult.layout)) {
+            warnings.push(
+              `Your .gitignore excludes ${relPath} (directly or via a parent rule). The discovery file must be committed for the Glasstrace browser extension to find it in deployed builds. Remove the matching line from .gitignore or add an explicit negation (e.g. \`!` + relPath + "`)."
+            );
+          }
+        } catch {
+        }
+      }
+    } catch (err) {
+      warnings.push(
+        `Failed to write ${relativeDiscoveryPath(
+          resolveStaticRoot(projectRoot).layout
+        )}: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
     let anyConfigWritten = false;
     if (isCI) {
       const genericAgent = {
@@ -509,7 +608,7 @@ async function verifyAnonKeyRegistration(projectRoot) {
   }
   const baseConfig = resolveConfig({ apiKey: devKey });
   const config = { ...baseConfig, apiKey: devKey };
-  const sdkVersion = true ? "0.19.0" : "0.0.0-dev";
+  const sdkVersion = true ? "0.20.0" : "0.0.0-dev";
   const result = await verifyInitReachable(config, anonKey, sdkVersion);
   if (result.ok) {
     return { outcome: "verified" };
@@ -758,6 +857,7 @@ Usage:
 }
 export {
   decideMcpConfigAction,
+  gitignoreExcludesDiscoveryFile,
   meetsNodeVersion,
   rollbackSteps,
   runInit,