@patchstack/connect 0.3.28 → 0.3.30

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -39,7 +39,7 @@ async function readDeclaredDependencyNames(cwd) {
     return [];
   }
   const names = /* @__PURE__ */ new Set();
-  for (const group of ["dependencies", "devDependencies"]) {
+  for (const group of ["dependencies", "devDependencies", "optionalDependencies"]) {
     const deps = parsed[group];
     if (typeof deps !== "object" || deps === null) {
       continue;
@@ -57,14 +57,171 @@ function missingDependencies(declared, packages) {
   const present = new Set(packages.map((entry) => entry.name));
   return declared.filter((name) => !present.has(name));
 }
+function disagreements(packages, other) {
+  const otherVersions = /* @__PURE__ */ new Map();
+  for (const entry of other) {
+    if (!otherVersions.has(entry.name)) otherVersions.set(entry.name, entry.version);
+  }
+  const seen = /* @__PURE__ */ new Set();
+  const conflicts = [];
+  for (const entry of packages) {
+    if (seen.has(entry.name)) continue;
+    seen.add(entry.name);
+    const otherVersion = otherVersions.get(entry.name);
+    if (otherVersion !== void 0 && otherVersion !== entry.version) {
+      conflicts.push({ name: entry.name, version: entry.version, otherVersion });
+    }
+  }
+  return conflicts;
+}
 
-// src/parsers/npm.ts
+// src/parsers/bun.ts
 import { readFile as readFile2 } from "fs/promises";
+
+// src/parsers/report.ts
+var MAX_SAMPLES = 3;
+function newReport() {
+  return { unreadable: 0, samples: [] };
+}
+function recordUnreadable(report, sample) {
+  if (!report) return;
+  report.unreadable++;
+  if (report.samples.length < MAX_SAMPLES) report.samples.push(sample);
+}
+function unreadableWarning(filename, report) {
+  if (report.unreadable === 0) return null;
+  const shown = report.samples.join(", ");
+  const one = report.unreadable === 1;
+  return `${filename}: ${report.unreadable} entr${one ? "y was" : "ies were"} not in a form this scanner reads (${shown}${report.unreadable > report.samples.length ? ", \u2026" : ""}), so ${one ? "it is" : "they are"} absent from this manifest. Anything installed only through ${one ? "that entry" : "those entries"} is not being checked.`;
+}
+
+// src/parsers/bun.ts
+async function parseBunLockfile(lockfilePath, report) {
+  let raw;
+  try {
+    raw = await readFile2(lockfilePath, "utf8");
+  } catch (cause) {
+    throw new PatchstackError(`Could not read lockfile at ${lockfilePath}`, "LOCKFILE_NOT_FOUND", cause);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stripTrailingCommas(raw));
+  } catch (cause) {
+    throw new PatchstackError(`Lockfile at ${lockfilePath} is not valid JSON`, "LOCKFILE_PARSE_ERROR", cause);
+  }
+  const packages = parsed?.packages;
+  if (typeof packages !== "object" || packages === null) {
+    throw new PatchstackError(`Lockfile at ${lockfilePath} has no "packages" entries`, "LOCKFILE_PARSE_ERROR");
+  }
+  const direct = directDependencyNames(parsed);
+  const entries = [];
+  let skipped = 0;
+  for (const [key, value] of Object.entries(packages)) {
+    const descriptor = Array.isArray(value) ? value[0] : value;
+    if (typeof descriptor !== "string") {
+      skipped++;
+      recordUnreadable(report, key);
+      continue;
+    }
+    const split = splitDescriptor(descriptor);
+    if (split === null) {
+      skipped++;
+      if (!isDeliberatelyExcluded(descriptor)) recordUnreadable(report, key);
+      continue;
+    }
+    entries.push({
+      name: split.name,
+      version: split.version,
+      ...direct.has(split.name) ? { direct: true } : {},
+      ...key === split.name ? {} : { path: key }
+    });
+  }
+  if (entries.length === 0) {
+    throw new PatchstackError(
+      `Lockfile at ${lockfilePath} lists no registry packages${skipped > 0 ? ` (${skipped} non-registry entr${skipped === 1 ? "y" : "ies"} skipped)` : ""}`,
+      "LOCKFILE_PARSE_ERROR"
+    );
+  }
+  return entries;
+}
+function splitDescriptor(descriptor) {
+  const at = descriptor.lastIndexOf("@");
+  if (at <= 0) return null;
+  const name = descriptor.slice(0, at);
+  const version = descriptor.slice(at + 1);
+  if (name === "" || version === "") return null;
+  if (NON_REGISTRY_VERSION.test(version)) return null;
+  return { name, version };
+}
+var NON_REGISTRY_VERSION = /^[a-z][a-z0-9+.-]*:|\//i;
+function isDeliberatelyExcluded(descriptor) {
+  const at = descriptor.lastIndexOf("@");
+  if (at <= 0) return false;
+  return NON_REGISTRY_VERSION.test(descriptor.slice(at + 1));
+}
+function directDependencyNames(parsed) {
+  const names = /* @__PURE__ */ new Set();
+  const workspaces = parsed?.workspaces;
+  if (typeof workspaces !== "object" || workspaces === null) return names;
+  for (const workspace of Object.values(workspaces)) {
+    if (typeof workspace !== "object" || workspace === null) continue;
+    for (const group of ["dependencies", "devDependencies", "optionalDependencies", "peerDependencies"]) {
+      const deps = workspace[group];
+      if (typeof deps !== "object" || deps === null) continue;
+      for (const name of Object.keys(deps)) names.add(name);
+    }
+  }
+  return names;
+}
+function stripTrailingCommas(source) {
+  const out = [];
+  let inString = false;
+  let pendingComma = -1;
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (inString) {
+      out.push(ch);
+      if (ch === "\\") {
+        const next = source[i + 1];
+        if (next !== void 0) {
+          out.push(next);
+          i++;
+        }
+      } else if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      pendingComma = -1;
+      out.push(ch);
+      continue;
+    }
+    if (ch === ",") {
+      pendingComma = out.length;
+      out.push(ch);
+      continue;
+    }
+    if (ch === "}" || ch === "]") {
+      if (pendingComma !== -1) out[pendingComma] = " ";
+      pendingComma = -1;
+      out.push(ch);
+      continue;
+    }
+    if (!/\s/.test(ch)) pendingComma = -1;
+    out.push(ch);
+  }
+  return out.join("");
+}
+
+// src/parsers/npm.ts
+import { readFile as readFile3 } from "fs/promises";
 import path2 from "path";
 async function parseNpmLockfile(lockfilePath) {
   let raw;
   try {
-    raw = await readFile2(lockfilePath, "utf8");
+    raw = await readFile3(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(`Could not read lockfile at ${lockfilePath}`, "LOCKFILE_NOT_FOUND", cause);
   }
@@ -145,8 +302,9 @@ function isDirectV2(pkgPath) {
 }
 
 // src/parsers/node_modules.ts
-import { lstat, readFile as readFile3, readdir, stat } from "fs/promises";
+import { lstat, readFile as readFile4, readdir, realpath, stat } from "fs/promises";
 import path3 from "path";
+var PACKAGE_STORE_DIRS = /* @__PURE__ */ new Set([".bun", ".pnpm", ".store"]);
 async function walkNodeModules(cwd) {
   const root = path3.join(cwd, "node_modules");
   try {
@@ -167,96 +325,122 @@ async function walkNodeModules(cwd) {
       cause
     );
   }
-  const entries = [];
-  await walk(root, entries, 0);
-  return entries;
+  const seen = /* @__PURE__ */ new Map();
+  try {
+    seen.set(await realpath(cwd), -1);
+  } catch {
+  }
+  return dedupeByShallowest(await walk(root, 0, seen));
+}
+function dedupeByShallowest(found) {
+  const best = /* @__PURE__ */ new Map();
+  for (const item of found) {
+    const current = best.get(item.realpath);
+    if (current === void 0 || item.depth < current.depth) best.set(item.realpath, item);
+  }
+  return [...best.values()].map(({ entry }) => entry);
 }
-async function walk(dir, acc, depth) {
+var CONCURRENCY = 32;
+async function walk(dir, depth, seen) {
   let names;
   try {
     names = await readdir(dir);
   } catch {
-    return;
+    return [];
   }
-  for (const name of names) {
-    if (name.startsWith(".")) {
-      continue;
-    }
+  const perEntry = await mapLimit(names, async (name) => {
+    if (name.startsWith(".") && !PACKAGE_STORE_DIRS.has(name)) return [];
     const fullPath = path3.join(dir, name);
-    if (!await isPlainDirectory(fullPath)) {
-      continue;
-    }
+    const resolved = await claim(fullPath, seen, depth);
+    if (resolved === null) return [];
+    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen);
     if (name.startsWith("@")) {
       let subNames;
       try {
         subNames = await readdir(fullPath);
       } catch {
-        continue;
+        return [];
       }
-      for (const sub of subNames) {
-        if (sub.startsWith(".")) {
-          continue;
-        }
+      const scoped = await mapLimit(subNames, async (sub) => {
+        if (sub.startsWith(".")) return [];
         const scopedDir = path3.join(fullPath, sub);
-        if (!await isPlainDirectory(scopedDir)) {
-          continue;
-        }
-        await readPackage(scopedDir, depth, acc);
-        await walkNested(scopedDir, acc, depth);
-      }
-      continue;
+        const scopedReal = await claim(scopedDir, seen, depth);
+        if (scopedReal === null) return [];
+        return packageAndNested(scopedDir, scopedReal, depth, seen);
+      });
+      return scoped.flat();
     }
-    await readPackage(fullPath, depth, acc);
-    await walkNested(fullPath, acc, depth);
-  }
+    return packageAndNested(fullPath, resolved, depth, seen);
+  });
+  return perEntry.flat();
 }
-async function readPackage(pkgDir, depth, acc) {
+async function packageAndNested(pkgDir, resolved, depth, seen) {
+  const [own, nested] = await Promise.all([readPackage(pkgDir, depth), walkNested(pkgDir, depth, seen)]);
+  return own === null ? nested : [{ entry: own, realpath: resolved, depth }, ...nested];
+}
+async function mapLimit(items, fn) {
+  const results = new Array(items.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(CONCURRENCY, items.length) }, async () => {
+    while (next < items.length) {
+      const index = next++;
+      results[index] = await fn(items[index]);
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+async function readPackage(pkgDir, depth) {
   let raw;
   try {
-    raw = await readFile3(path3.join(pkgDir, "package.json"), "utf8");
+    raw = await readFile4(path3.join(pkgDir, "package.json"), "utf8");
   } catch {
-    return;
+    return null;
   }
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch {
-    return;
+    return null;
   }
   if (typeof parsed.name !== "string" || parsed.name.length === 0) {
-    return;
+    return null;
   }
   if (typeof parsed.version !== "string" || parsed.version.length === 0) {
-    return;
+    return null;
   }
-  acc.push({
-    name: parsed.name,
-    version: parsed.version,
-    direct: depth === 0
-  });
+  return { name: parsed.name, version: parsed.version, direct: depth === 0 };
 }
-async function walkNested(pkgDir, acc, depth) {
+async function walkNested(pkgDir, depth, seen) {
   const nested = path3.join(pkgDir, "node_modules");
-  if (!await isPlainDirectory(nested)) {
-    return;
+  if (await claim(nested, seen, depth + 1) === null) {
+    return [];
   }
-  await walk(nested, acc, depth + 1);
+  return walk(nested, depth + 1, seen);
 }
-async function isPlainDirectory(dir) {
+async function claim(dir, seen, depth) {
+  let resolved;
   try {
     const info = await lstat(dir);
-    return info.isDirectory() && !info.isSymbolicLink();
+    if (!info.isDirectory() && !info.isSymbolicLink()) return null;
+    resolved = await realpath(dir);
+    const target = await stat(resolved);
+    if (!target.isDirectory()) return null;
   } catch {
-    return false;
+    return null;
   }
+  const claimed = seen.get(resolved);
+  if (claimed !== void 0 && claimed <= depth) return null;
+  seen.set(resolved, depth);
+  return resolved;
 }
 
 // src/parsers/pnpm.ts
-import { readFile as readFile4 } from "fs/promises";
-async function parsePnpmLockfile(lockfilePath) {
+import { readFile as readFile5 } from "fs/promises";
+async function parsePnpmLockfile(lockfilePath, report) {
   let raw;
   try {
-    raw = await readFile4(lockfilePath, "utf8");
+    raw = await readFile5(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -277,6 +461,7 @@ async function parsePnpmLockfile(lockfilePath) {
   for (const key of packageKeys) {
     const parsed = parsePackageKey(key);
     if (parsed === null) {
+      recordUnreadable(report, key);
       continue;
     }
     entries.push({
@@ -504,12 +689,12 @@ function extractLeafName(trimmed) {
 }
 
 // src/parsers/yarn.ts
-import { readFile as readFile5 } from "fs/promises";
+import { readFile as readFile6 } from "fs/promises";
 import path4 from "path";
-async function parseYarnLockfile(lockfilePath) {
+async function parseYarnLockfile(lockfilePath, report) {
   let raw;
   try {
-    raw = await readFile5(lockfilePath, "utf8");
+    raw = await readFile6(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -517,7 +702,7 @@ async function parseYarnLockfile(lockfilePath) {
       cause
     );
   }
-  const blocks = parseBlocks(raw);
+  const blocks = parseBlocks(raw, report);
   if (blocks.length === 0) {
     throw new PatchstackError(
       `Lockfile at ${lockfilePath} contains no package entries`,
@@ -546,13 +731,19 @@ async function parseYarnLockfile(lockfilePath) {
   }
   return entries;
 }
-function parseBlocks(raw) {
+var NON_PACKAGE_KEYS = /* @__PURE__ */ new Set(["__metadata"]);
+function parseBlocks(raw, report) {
   const lines = raw.split(/\r?\n/);
   const blocks = [];
   let current = null;
   const finalize = () => {
-    if (current !== null && current.version.length > 0 && current.names.size > 0) {
+    if (current === null) {
+      return;
+    }
+    if (current.version.length > 0 && current.names.size > 0) {
       blocks.push(current);
+    } else if (current.unreadable) {
+      recordUnreadable(report, current.key);
     }
     current = null;
   };
@@ -569,13 +760,13 @@ function parseBlocks(raw) {
       }
       const keyLine = trimmed.slice(0, -1);
       const names = /* @__PURE__ */ new Set();
+      let unreadable = false;
       for (const spec of splitDescriptors(keyLine)) {
-        const name = extractName(spec);
-        if (name !== null) {
-          names.add(name);
-        }
+        const classified = classifyDescriptor(spec);
+        if (classified.name !== void 0) names.add(classified.name);
+        else if (!classified.excluded) unreadable = true;
       }
-      current = { names, version: "" };
+      current = { names, version: "", key: keyLine, unreadable: unreadable && names.size === 0 };
       continue;
     }
     if (current === null) {
@@ -630,20 +821,37 @@ function splitDescriptors(keyLine) {
   }
   return parts;
 }
-function extractName(rawSpec) {
+var NON_REGISTRY_PROTOCOLS = /^(?:workspace|patch|virtual|portal|file|link|exec|git|github|https?|ssh):/i;
+function classifyDescriptor(rawSpec) {
   let s = rawSpec.trim();
   if (s.length === 0) {
-    return null;
+    return { excluded: true };
   }
   if (s.startsWith('"') && s.endsWith('"') || s.startsWith("'") && s.endsWith("'")) {
     s = s.slice(1, -1);
   }
-  const atIdx = s.lastIndexOf("@");
+  if (NON_PACKAGE_KEYS.has(s)) {
+    return { excluded: true };
+  }
+  const atIdx = s.indexOf("@", 1);
   if (atIdx <= 0) {
-    return null;
+    return {};
   }
   const name = s.slice(0, atIdx);
-  return name.length > 0 ? name : null;
+  const range = s.slice(atIdx + 1);
+  if (name.length === 0) {
+    return {};
+  }
+  if (NON_REGISTRY_PROTOCOLS.test(range)) {
+    return { excluded: true };
+  }
+  const alias = /^npm:(.+)$/i.exec(range);
+  if (alias !== null) {
+    const target = alias[1] ?? "";
+    const targetAt = target.indexOf("@", 1);
+    return { name: targetAt > 0 ? target.slice(0, targetAt) : name };
+  }
+  return { name };
 }
 function parseVersionField(content) {
   if (!content.startsWith("version")) {
@@ -668,7 +876,7 @@ async function readDirectDepNames(cwd) {
   const names = /* @__PURE__ */ new Set();
   let raw;
   try {
-    raw = await readFile5(path4.join(cwd, "package.json"), "utf8");
+    raw = await readFile6(path4.join(cwd, "package.json"), "utf8");
   } catch {
     return names;
   }
@@ -697,7 +905,10 @@ async function readDirectDepNames(cwd) {
 // src/parsers/index.ts
 var LOCKFILE_CANDIDATES = [
   { filename: "package-lock.json", strategy: "npm-lockfile" },
-  { filename: "bun.lock", strategy: "node-modules-walk" },
+  // Read directly, not walked. Bun's isolated layout puts packages under a dot-directory and makes the
+  // top level symlinks into it, so a `node_modules` walk finds nothing there — and isolated is the default
+  // for new workspaces.
+  { filename: "bun.lock", strategy: "bun-lockfile" },
   { filename: "bun.lockb", strategy: "node-modules-walk" },
   { filename: "pnpm-lock.yaml", strategy: "pnpm-lockfile" },
   { filename: "yarn.lock", strategy: "yarn-lockfile" }
@@ -732,33 +943,57 @@ async function scanLockfile(cwd) {
   const declared = await readDeclaredDependencyNames(cwd);
   const warnings = [];
   let firstParsed = null;
-  let walkTried = false;
+  let walked = null;
+  let walkWasCandidate = false;
+  const parsedSources = [];
   for (const candidate of candidates) {
     let packages;
+    const report = newReport();
     try {
-      packages = await runStrategy(candidate, cwd);
+      packages = await runStrategy(candidate, cwd, report);
     } catch {
       continue;
     }
-    walkTried ||= candidate.strategy === "node-modules-walk";
+    const unreadable = unreadableWarning(candidate.filename, report);
+    if (unreadable !== null) warnings.push(unreadable);
+    if (candidate.strategy === "node-modules-walk") {
+      walked = packages;
+      walkWasCandidate = true;
+    }
     firstParsed ??= { packages, filename: candidate.filename };
-    const missing = missingDependencies(declared, packages);
-    if (missing.length === 0) {
-      return manifestWith(packages, warnings);
+    parsedSources.push({ packages, filename: candidate.filename });
+  }
+  for (const source of parsedSources) {
+    const missing = missingDependencies(declared, source.packages);
+    if (missing.length > 0) {
+      warnings.push(staleWarning(source.filename, missing));
+      continue;
     }
-    warnings.push(staleWarning(candidate.filename, missing));
+    const conflicts = otherCompleteSources(parsedSources, source, declared).flatMap(
+      (other) => disagreements(source.packages, other.packages).map((conflict) => ({ other: other.filename, conflict }))
+    );
+    if (conflicts.length === 0) {
+      return manifestWith(source.packages, warnings);
+    }
+    warnings.push(conflictWarning(source.filename, conflicts));
+    break;
   }
-  if (!walkTried) {
+  if (walked === null) {
     try {
-      const packages = await walkNodeModules(cwd);
-      const missing = missingDependencies(declared, packages);
-      if (missing.length > 0) {
-        warnings.push(staleWarning("node_modules/", missing));
-      }
-      warnings.push("Scanned node_modules/ instead. Delete the stale lockfile to silence this warning.");
-      return manifestWith(packages, warnings);
+      walked = await walkNodeModules(cwd);
     } catch {
+      walked = null;
+    }
+  }
+  if (walked !== null) {
+    const missing = missingDependencies(declared, walked);
+    if (missing.length > 0) {
+      warnings.push(staleWarning("node_modules/", missing));
     }
+    warnings.push(
+      walkWasCandidate ? "Reporting node_modules/, which is what the build loads." : "Scanned node_modules/ instead. Delete the stale lockfile to silence this warning."
+    );
+    return manifestWith(walked, warnings);
   }
   if (firstParsed === null) {
     const expected = LOCKFILE_CANDIDATES.map((candidate) => candidate.filename).join(", ");
@@ -775,6 +1010,15 @@ async function scanLockfile(cwd) {
 function manifestWith(packages, warnings) {
   return warnings.length > 0 ? { ecosystem: "npm", packages, warnings } : { ecosystem: "npm", packages };
 }
+function otherCompleteSources(all, current, declared) {
+  return all.filter(
+    (source) => source.filename !== current.filename && missingDependencies(declared, source.packages).length === 0
+  );
+}
+function conflictWarning(filename, conflicts) {
+  const shown = conflicts.slice(0, 3).map(({ other, conflict }) => `${conflict.name} ${conflict.version} vs ${conflict.otherVersion} in ${other}`).join("; ");
+  return `${filename} and another lockfile disagree about installed versions (${shown}${conflicts.length > 3 ? `, +${conflicts.length - 3} more` : ""}). Scanned node_modules/ instead. Remove whichever lockfile your package manager does not maintain.`;
+}
 function staleWarning(source, missing) {
   const sample = missing.slice(0, 3).join(", ");
   const suffix = missing.length > 3 ? `, +${missing.length - 3} more` : "";
@@ -789,14 +1033,18 @@ async function presentLockfiles(cwd) {
   );
   return probed.filter((candidate) => candidate.present).map(({ filename, strategy, filePath }) => ({ ecosystem: "npm", filename, strategy, filePath }));
 }
-async function runStrategy(detected, cwd) {
+async function runStrategy(detected, cwd, report) {
   switch (detected.strategy) {
     case "npm-lockfile":
       return parseNpmLockfile(detected.filePath);
+    case "bun-lockfile":
+      return parseBunLockfile(detected.filePath, report);
+    // The hand-written scanners. Each meets entries it was not written for, and each is asked to say how
+    // many it dropped, because a manifest short a package reads exactly like a project without it.
     case "pnpm-lockfile":
-      return parsePnpmLockfile(detected.filePath);
+      return parsePnpmLockfile(detected.filePath, report);
     case "yarn-lockfile":
-      return parseYarnLockfile(detected.filePath);
+      return parseYarnLockfile(detected.filePath, report);
     case "node-modules-walk":
       return walkNodeModules(cwd);
   }
@@ -1228,7 +1476,7 @@ function isTimeoutError(cause) {
 }
 
 // src/demo.ts
-import { readFile as readFile6 } from "fs/promises";
+import { readFile as readFile7 } from "fs/promises";
 import { join } from "path";
 var NODE_SERIALIZE_DEMO = {
   name: "node-serialize",
@@ -1298,7 +1546,7 @@ Add this deliberately vulnerable package first: npm install --save-exact ${scena
 }
 async function readPersistedSiteUuid(cwd) {
   try {
-    const value = JSON.parse(await readFile6(join(cwd, ".patchstackrc.json"), "utf8")).siteUuid;
+    const value = JSON.parse(await readFile7(join(cwd, ".patchstackrc.json"), "utf8")).siteUuid;
     return typeof value === "string" && value.length > 0 ? value : null;
   } catch {
     return null;
@@ -1383,7 +1631,7 @@ async function waitForDemoRule(manifestEndpoint, siteUuid, scenario, options = {
   const pollIntervalMs = options.pollIntervalMs ?? 1e3;
   const requestTimeoutMs = options.requestTimeoutMs ?? 1e4;
   const fetchFn = options.fetchFn ?? fetch;
-  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve3) => setTimeout(resolve3, ms)));
   const now = options.now ?? Date.now;
   const started = now();
   const rulesUrl = buildRulesUrl(manifestEndpoint, siteUuid);
@@ -1432,12 +1680,14 @@ function renderDemoTestCommands(url, scenario) {
 }
 
 // src/config.ts
-import { readFile as readFile7, writeFile } from "fs/promises";
+import { readFile as readFile8, writeFile, chmod } from "fs/promises";
 import path6 from "path";
 var CONFIG_FILENAME = ".patchstackrc.json";
+var SECRET_FILENAME = ".patchstackrc.local.json";
 var DEFAULT_ENVIRONMENT = "production";
 async function resolveConfig(options) {
   const fromFile = await readConfigFile(options.cwd);
+  const fromSecretFile = await readSecretFile(options.cwd);
   const fromEnv = readEnv();
   const siteUuid = options.cliSiteUuid ?? fromEnv.siteUuid ?? fromFile.siteUuid ?? null;
   const endpoint = options.cliEndpoint ?? fromEnv.endpoint ?? fromFile.endpoint ?? DEFAULT_ENDPOINT;
@@ -1462,8 +1712,8 @@ async function resolveConfig(options) {
       "CONFIG_MISSING"
     );
   }
-  const apiKeyRaw = fromEnv.apiKey ?? fromFile.apiKey ?? null;
-  const pulseAuthRaw = fromEnv.pulseAuth ?? fromFile.pulseAuth ?? apiKeyRaw;
+  const apiKeyRaw = fromEnv.apiKey ?? fromSecretFile.apiKey ?? fromFile.apiKey ?? null;
+  const pulseAuthRaw = fromEnv.pulseAuth ?? fromSecretFile.pulseAuth ?? fromFile.pulseAuth ?? apiKeyRaw;
   return {
     siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
     apiKey: apiKeyRaw === null || apiKeyRaw.length === 0 ? null : apiKeyRaw,
@@ -1480,19 +1730,102 @@ async function writeConfigFile(cwd, config) {
   await writeFile(target, content, "utf8");
   return target;
 }
+var SECRET_CONFIG_FILENAME = SECRET_FILENAME;
+async function writeSecretFile(cwd, secrets) {
+  const target = path6.join(cwd, SECRET_FILENAME);
+  await writeFile(target, JSON.stringify(secrets, null, 2) + "\n", { encoding: "utf8", mode: 384 });
+  try {
+    await chmod(target, 384);
+  } catch {
+  }
+  const ignore = await ensureIgnored(cwd, SECRET_FILENAME);
+  return { path: target, ...ignore };
+}
+async function ensureIgnored(cwd, entry) {
+  const target = path6.join(cwd, ".gitignore");
+  let existing = "";
+  try {
+    existing = await readFile8(target, "utf8");
+  } catch (err) {
+    const code = err.code;
+    if (code !== "ENOENT") {
+      return { ignored: false, reason: `.gitignore could not be read (${code ?? "unknown error"})` };
+    }
+  }
+  if (ignoresEntry(existing, entry)) return { ignored: true };
+  const separator = existing === "" || existing.endsWith("\n") ? "" : "\n";
+  const block = `${separator}
+# Patchstack credential \u2014 never commit this
+${entry}
+`;
+  try {
+    await writeFile(target, existing + block, "utf8");
+  } catch (err) {
+    const code = err.code;
+    return { ignored: false, reason: `.gitignore could not be written (${code ?? "unknown error"})` };
+  }
+  try {
+    const written = await readFile8(target, "utf8");
+    if (ignoresEntry(written, entry)) return { ignored: true };
+    return { ignored: false, reason: ".gitignore does not cover the file after writing it" };
+  } catch (err) {
+    const code = err.code;
+    return { ignored: false, reason: `.gitignore could not be read back (${code ?? "unknown error"})` };
+  }
+}
+async function secretFileIgnored(cwd) {
+  try {
+    const contents = await readFile8(path6.join(cwd, ".gitignore"), "utf8");
+    if (ignoresEntry(contents, SECRET_FILENAME)) return { ignored: true };
+    return { ignored: false, reason: `.gitignore does not cover ${SECRET_FILENAME}` };
+  } catch (err) {
+    const code = err.code;
+    return {
+      ignored: false,
+      reason: code === "ENOENT" ? "this project has no .gitignore" : `.gitignore could not be read (${code ?? "unknown error"})`
+    };
+  }
+}
+function ignoresEntry(contents, entry) {
+  let ignored = false;
+  for (const raw of contents.split("\n")) {
+    const line = raw.trim();
+    if (line === "" || line.startsWith("#")) continue;
+    const negated = line.startsWith("!");
+    const pattern = negated ? line.slice(1).trim() : line;
+    if (pattern === entry || pattern === `/${entry}`) ignored = !negated;
+  }
+  return ignored;
+}
 async function persistSiteUuid(cwd, siteUuid) {
   const existing = await readConfigFile(cwd);
   return writeConfigFile(cwd, { ...existing, siteUuid });
 }
 async function persistApiKey(cwd, apiKey) {
-  const { pulseAuth: _dropped, ...existing } = await readConfigFile(cwd);
-  return writeConfigFile(cwd, { ...existing, apiKey });
+  const { apiKey: _movedKey, pulseAuth: _movedPulse, ...publicConfig } = await readConfigFile(cwd);
+  const existingSecrets = await readSecretFile(cwd);
+  const target = await writeSecretFile(cwd, { ...existingSecrets, apiKey, pulseAuth: void 0 });
+  if (_movedKey !== void 0 || _movedPulse !== void 0) {
+    await writeConfigFile(cwd, publicConfig);
+  }
+  return target;
+}
+async function credentialInCommittedConfig(cwd) {
+  const config = await readConfigFile(cwd);
+  return config.apiKey !== void 0 || config.pulseAuth !== void 0;
+}
+async function readSecretFile(cwd) {
+  const file = await readJsonFile(cwd, SECRET_FILENAME);
+  return { apiKey: file.apiKey, pulseAuth: file.pulseAuth };
 }
 async function readConfigFile(cwd) {
-  const target = path6.join(cwd, CONFIG_FILENAME);
+  return readJsonFile(cwd, CONFIG_FILENAME);
+}
+async function readJsonFile(cwd, filename) {
+  const target = path6.join(cwd, filename);
   let raw;
   try {
-    raw = await readFile7(target, "utf8");
+    raw = await readFile8(target, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return {};
@@ -1544,7 +1877,7 @@ function isEnvironment(value) {
 }
 
 // src/mark-build.ts
-import { existsSync, readdirSync, statSync } from "fs";
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "fs";
 import path7 from "path";
 
 // src/stack.ts
@@ -1687,16 +2020,94 @@ function injectMarker(html, snippet) {
   }
   return stripped + snippet;
 }
+var JSX_SHELL_FRAMEWORKS = /* @__PURE__ */ new Set([
+  "next",
+  "remix",
+  "react-router",
+  "tanstack-start",
+  "gatsby"
+]);
+var PRODUCTION_GATES = {
+  next: "process.env.NODE_ENV === 'production'",
+  gatsby: "process.env.NODE_ENV === 'production'",
+  nuxt: "!import.meta.dev"
+};
+var DEFAULT_PRODUCTION_GATE = "import.meta.env.PROD";
+function productionGate(framework) {
+  const mapped = framework !== null ? PRODUCTION_GATES[framework] : void 0;
+  return mapped ?? DEFAULT_PRODUCTION_GATE;
+}
+function hasJsxShell(framework) {
+  return framework !== null && JSX_SHELL_FRAMEWORKS.has(framework);
+}
+function buildSourceMarkerSnippet(framework) {
+  const gate = productionGate(framework);
+  return `{${gate} && (
+  <script
+    ${MARKER_ATTR}="true"
+    dangerouslySetInnerHTML={{ __html: 'window.__PATCHSTACK_PROD__=true;' }}
+  />
+)}`;
+}
+var PROD_MARKER_GLOBAL = "__PATCHSTACK_PROD__";
+var REGION_OPEN = "{/* #region patchstack (managed by patchstack-connect \u2014 do not edit) */}";
+var REGION_CLOSE = "{/* #endregion patchstack */}";
+var REGION_RE = /[ \t]*\{\/\* #region patchstack[\s\S]*?#endregion patchstack \*\/\}\n?/g;
+function ensureMarkerInJsxShell(source, framework) {
+  if (!hasJsxShell(framework)) {
+    return { source, action: "unsupported" };
+  }
+  const stripped = source.replace(REGION_RE, "");
+  if (stripped.includes(PROD_MARKER_GLOBAL)) {
+    return { source, action: "manual" };
+  }
+  const block = (indent) => [REGION_OPEN, ...buildSourceMarkerSnippet(framework).split("\n"), REGION_CLOSE].map((line) => `${indent}${line}`).join("\n");
+  const widget = stripped.match(/^([ \t]*).*patchstack-widget.*$/m);
+  if (widget?.index !== void 0) {
+    const indent = widget[1] ?? "";
+    return {
+      source: `${stripped.slice(0, widget.index)}${block(indent)}
+${stripped.slice(widget.index)}`,
+      action: "added"
+    };
+  }
+  for (const anchor of [/^([ \t]*)<head>[ \t]*$/m, /^([ \t]*)<body>[ \t]*$/m]) {
+    const match = stripped.match(anchor);
+    if (match?.index === void 0) {
+      continue;
+    }
+    const end = match.index + match[0].length;
+    const indent = `${match[1] ?? ""}  `;
+    return {
+      source: `${stripped.slice(0, end)}
+${block(indent)}${stripped.slice(end)}`,
+      action: "added"
+    };
+  }
+  return { source, action: "no-anchor" };
+}
+function ensureSourceMarker(cwd, shell, framework) {
+  if (shell === null) {
+    return { shell: null, source: "", action: "no-anchor" };
+  }
+  const file = path7.resolve(cwd, shell);
+  const before = readFileSync(file, "utf8");
+  const result = ensureMarkerInJsxShell(before, framework);
+  if (result.source !== before && result.action === "added") {
+    writeFileSync(file, result.source);
+  }
+  return { ...result, shell };
+}
 
 // src/guide.ts
-import { existsSync as existsSync10, readFileSync as readFileSync5, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
+import { existsSync as existsSync11, readFileSync as readFileSync6, readdirSync as readdirSync4, statSync as statSync2 } from "fs";
 import path9 from "path";
 
 // src/protect/install/util.ts
-import { readFileSync, existsSync as existsSync2, writeFileSync } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, writeFileSync as writeFileSync2 } from "fs";
 import { join as join2, dirname } from "path";
 import { fileURLToPath } from "url";
-var read = (p) => readFileSync(p, "utf8");
+var read = (p) => readFileSync2(p, "utf8");
 var log = (msg) => console.log(`patchstack protect: ${msg}`);
 function hasDependency(cwd, name) {
   try {
@@ -1706,6 +2117,20 @@ function hasDependency(cwd, name) {
     return false;
   }
 }
+function hasResolvableCredential(cwd) {
+  if ((process.env.PATCHSTACK_API_KEY ?? "") !== "" || (process.env.PATCHSTACK_PULSE_AUTH ?? "") !== "") {
+    return true;
+  }
+  for (const file of [".patchstackrc.local.json", ".patchstackrc.json"]) {
+    try {
+      const parsed = JSON.parse(read(join2(cwd, file)));
+      if (typeof parsed.apiKey === "string" && parsed.apiKey !== "") return true;
+      if (typeof parsed.pulseAuth === "string" && parsed.pulseAuth !== "") return true;
+    } catch {
+    }
+  }
+  return false;
+}
 var SITE_UUID_PLACEHOLDER = "__PATCHSTACK_SITE_UUID__";
 var UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 function bakeSiteUuid(cwd, guardRelPath) {
@@ -1732,7 +2157,7 @@ function bakeSiteUuid(cwd, guardRelPath) {
     log(`${guardRelPath} site UUID already baked`);
     return false;
   }
-  writeFileSync(guardPath, source.replace(SITE_UUID_PLACEHOLDER, uuid));
+  writeFileSync2(guardPath, source.replace(SITE_UUID_PLACEHOLDER, uuid));
   log(`baked site UUID into ${guardRelPath} \u2014 live rules from the Patchstack API`);
   return true;
 }
@@ -1749,7 +2174,7 @@ function templatesDir() {
 }
 
 // src/protect/install/adapters/tanstack-supabase.ts
-import { writeFileSync as writeFileSync2, existsSync as existsSync3, mkdirSync, copyFileSync } from "fs";
+import { writeFileSync as writeFileSync3, existsSync as existsSync3, mkdirSync, copyFileSync } from "fs";
 import { join as join3 } from "path";
 var CLIENT_TUNNEL = [
   "",
@@ -1780,7 +2205,8 @@ var REQUEST_MIDDLEWARE_BLOCK = [
   "      if (blocked) return blocked;",
   "    }",
   "  }",
-  "  return screenResponse(await next());",
+  "  // The request is passed so route/method-scoped response rules can apply their scope.",
+  "  return screenResponse(await next(), request);",
   "});",
   "// #endregion patchstack-guard"
 ].join("\n");
@@ -1863,7 +2289,7 @@ function patchClient(cwd) {
     log("client.ts anchor not found \u2014 skipping (template changed?)");
     return false;
   }
-  writeFileSync2(p, s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL));
+  writeFileSync3(p, s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL));
   log("patched client.ts (tunnel Supabase through the guard)");
   return true;
 }
@@ -1900,7 +2326,7 @@ function patchStart(cwd) {
     log("start.ts already wired");
     return false;
   }
-  writeFileSync2(p, s);
+  writeFileSync3(p, s);
   log("patched start.ts (guard registered as request + function middleware)");
   return true;
 }
@@ -2151,7 +2577,7 @@ var nuxtAdapter = {
 };
 
 // src/protect/install/find-app.ts
-import { readFileSync as readFileSync2, existsSync as existsSync6, readdirSync as readdirSync2, lstatSync } from "fs";
+import { readFileSync as readFileSync3, existsSync as existsSync6, readdirSync as readdirSync2, lstatSync } from "fs";
 import { join as join8, relative, dirname as dirname3 } from "path";
 var SKIP_DIRS = /* @__PURE__ */ new Set([
   "node_modules",
@@ -2174,9 +2600,9 @@ var SKIP_DIRS = /* @__PURE__ */ new Set([
 var MAX_DEPTH = 8;
 function findAppInstance(cwd, re) {
   const root = existsSync6(join8(cwd, "src")) ? join8(cwd, "src") : cwd;
-  let hit = null;
+  const found = [];
   const walk2 = (dir, depth) => {
-    if (hit || depth > MAX_DEPTH) return;
+    if (depth > MAX_DEPTH) return;
     let entries;
     try {
       entries = readdirSync2(dir).sort();
@@ -2184,7 +2610,6 @@ function findAppInstance(cwd, re) {
       return;
     }
     for (const name of entries) {
-      if (hit) return;
       if (SKIP_DIRS.has(name) || name.startsWith(".")) continue;
       const p = join8(dir, name);
       let st;
@@ -2198,17 +2623,70 @@ function findAppInstance(cwd, re) {
       else if (/\.(?:ts|js|mjs|cjs)$/.test(name)) {
         let src;
         try {
-          src = readFileSync2(p, "utf8");
+          src = readFileSync3(p, "utf8");
         } catch {
           continue;
         }
         const m = re.exec(src);
-        if (m) hit = { relPath: relative(cwd, p).replace(/\\/g, "/"), appVar: m[1] };
+        if (!m) continue;
+        const appVar = m[1];
+        found.push({
+          relPath: relative(cwd, p).replace(/\\/g, "/"),
+          appVar,
+          listens: listensOn(src, appVar)
+        });
       }
     }
   };
   walk2(root, 0);
-  return hit;
+  if (found.length === 0) return null;
+  const declared = declaredEntries(cwd);
+  const chosen = found.slice().sort((a, b) => rankEntry({ ...a, declared: declared.has(a.relPath) }, { ...b, declared: declared.has(b.relPath) }))[0];
+  return {
+    relPath: chosen.relPath,
+    appVar: chosen.appVar,
+    others: found.filter((f) => f !== chosen && f.listens).map((f) => ({ relPath: f.relPath, appVar: f.appVar }))
+  };
+}
+function listensOn(source, appVar) {
+  return new RegExp(`\\b${appVar}\\s*\\.\\s*listen\\s*\\(`).test(source);
+}
+var ENTRY_NAMES = ["server", "index", "main", "app"];
+function rankEntry(a, b) {
+  if (a.declared !== b.declared) return a.declared ? -1 : 1;
+  if (a.listens !== b.listens) return a.listens ? -1 : 1;
+  const named = entryRank(a.relPath) - entryRank(b.relPath);
+  if (named !== 0) return named;
+  const depth = a.relPath.split("/").length - b.relPath.split("/").length;
+  if (depth !== 0) return depth;
+  return a.relPath < b.relPath ? -1 : 1;
+}
+function entryRank(relPath) {
+  const base = (relPath.split("/").pop() ?? "").replace(/\.(?:ts|js|mjs|cjs)$/, "");
+  const index = ENTRY_NAMES.indexOf(base);
+  return index === -1 ? ENTRY_NAMES.length : index;
+}
+function declaredEntries(cwd) {
+  const paths = /* @__PURE__ */ new Set();
+  let pkg;
+  try {
+    pkg = JSON.parse(readFileSync3(join8(cwd, "package.json"), "utf8"));
+  } catch {
+    return paths;
+  }
+  const add = (value) => {
+    if (typeof value !== "string") return;
+    for (const match of value.matchAll(/[\w./@-]+\.(?:ts|js|mjs|cjs)/g)) {
+      paths.add(match[0].replace(/^\.\//, ""));
+    }
+  };
+  add(pkg.main);
+  add(pkg.module);
+  const scripts = pkg.scripts;
+  if (typeof scripts === "object" && scripts !== null) {
+    for (const name of ["start", "serve", "dev"]) add(scripts[name]);
+  }
+  return paths;
 }
 function importSpecifier(fromRel, toRel, preserveExtension = false) {
   let spec = relative(dirname3(fromRel), toRel).replace(/\\/g, "/");
@@ -2218,28 +2696,252 @@ function importSpecifier(fromRel, toRel, preserveExtension = false) {
 }
 
 // src/protect/install/register.ts
-import { writeFileSync as writeFileSync4, existsSync as existsSync8 } from "fs";
-import { join as join10 } from "path";
+import { writeFileSync as writeFileSync5, existsSync as existsSync9 } from "fs";
+import { join as join11, resolve as resolve2 } from "path";
 
 // src/protect/install/generic.ts
-import { readFileSync as readFileSync3, existsSync as existsSync7, mkdirSync as mkdirSync4, copyFileSync as copyFileSync4, readdirSync as readdirSync3, lstatSync as lstatSync2 } from "fs";
-import { join as join9 } from "path";
-var GUARD_MARKER = "patchstack/guard";
+import { readFileSync as readFileSync4, existsSync as existsSync8, mkdirSync as mkdirSync4, copyFileSync as copyFileSync4, readdirSync as readdirSync3, lstatSync as lstatSync2 } from "fs";
+import { join as join10, dirname as dirname5 } from "path";
+
+// src/protect/install/source-scope.ts
+import { execFileSync } from "child_process";
+import { existsSync as existsSync7 } from "fs";
+import { dirname as dirname4, join as join9, resolve } from "path";
+var IMPORT_LINE = /^\s*(?:import\b|export\s+(?:\*|\{)|(?:const|let|var)\s+[^=]+=\s*require\()/;
+function lastTopLevelImportLine(source) {
+  const lines = source.split("\n");
+  let depth = 0;
+  let last = -1;
+  let inBlockComment = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i] ?? "";
+    if (!inBlockComment && depth === 0 && IMPORT_LINE.test(line)) last = i;
+    inBlockComment = advanceDepth(line, inBlockComment, (delta) => {
+      depth += delta;
+    });
+    if (depth < 0) return -1;
+  }
+  return depth === 0 ? last : -1;
+}
+function isTopLevelLine(source, index) {
+  const lines = source.split("\n");
+  let depth = 0;
+  let inBlockComment = false;
+  for (let i = 0; i < lines.length && i < index; i++) {
+    inBlockComment = advanceDepth(lines[i] ?? "", inBlockComment, (delta) => {
+      depth += delta;
+    });
+  }
+  return depth === 0;
+}
+function inSameBlockAfter(source, appIndex, callIndex) {
+  if (appIndex < 0 || callIndex <= appIndex) return false;
+  const lines = source.split("\n");
+  let depth = 0;
+  let inBlockComment = false;
+  for (let i = appIndex; i < callIndex; i++) {
+    inBlockComment = advanceDepth(lines[i] ?? "", inBlockComment, (delta) => {
+      depth += delta;
+    });
+    if (depth < 0) return false;
+  }
+  return depth === 0;
+}
+function advanceDepth(line, inBlockComment, add) {
+  let quote = null;
+  for (let i = 0; i < line.length; i++) {
+    const ch = line[i];
+    const next = line[i + 1];
+    if (inBlockComment) {
+      if (ch === "*" && next === "/") {
+        inBlockComment = false;
+        i++;
+      }
+      continue;
+    }
+    if (quote !== null) {
+      if (ch === "\\") {
+        i++;
+        continue;
+      }
+      if (ch === quote) quote = null;
+      continue;
+    }
+    if (ch === "/" && next === "/") return inBlockComment;
+    if (ch === "/" && next === "*") {
+      inBlockComment = true;
+      i++;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      continue;
+    }
+    if (ch === "{" || ch === "(" || ch === "[") add(1);
+    else if (ch === "}" || ch === ")" || ch === "]") add(-1);
+  }
+  return inBlockComment;
+}
+function parses(filePath) {
+  if (!/\.(?:js|cjs|mjs)$/.test(filePath)) return null;
+  try {
+    execFileSync(process.execPath, ["--check", filePath], { stdio: "pipe" });
+    return true;
+  } catch (error) {
+    return isSyntaxError(error) ? false : null;
+  }
+}
+function isSyntaxError(error) {
+  const status = error?.status;
+  return typeof status === "number" && status !== 0;
+}
+function stripComments(source) {
+  let out = "";
+  let quote = null;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    const next = source[i + 1];
+    if (inLine) {
+      if (ch === "\n") {
+        inLine = false;
+        out += ch;
+      }
+      continue;
+    }
+    if (inBlock) {
+      if (ch === "*" && next === "/") {
+        inBlock = false;
+        i++;
+      } else if (ch === "\n") {
+        out += ch;
+      }
+      continue;
+    }
+    if (quote !== null) {
+      out += ch;
+      if (ch === "\\") {
+        if (next !== void 0) {
+          out += next;
+          i++;
+        }
+      } else if (ch === quote) {
+        quote = null;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      quote = ch;
+      out += ch;
+      continue;
+    }
+    if (ch === "/" && next === "/") {
+      inLine = true;
+      i++;
+      continue;
+    }
+    if (ch === "/" && next === "*") {
+      inBlock = true;
+      i++;
+      continue;
+    }
+    out += ch;
+  }
+  return out;
+}
+var MASKED_CHAR = "
";
+function maskStringContents(source) {
+  let out = "";
+  let quote = null;
+  for (let i = 0; i < source.length; i++) {
+    const ch = source[i];
+    if (quote === null) {
+      out += ch;
+      if (ch === '"' || ch === "'" || ch === "`") quote = ch;
+      continue;
+    }
+    if (ch === "\\") {
+      out += MASKED_CHAR;
+      if (i + 1 < source.length) {
+        out += source[i + 1] === "\n" ? "\n" : MASKED_CHAR;
+        i++;
+      }
+      continue;
+    }
+    if (ch === quote) {
+      out += ch;
+      quote = null;
+      continue;
+    }
+    out += ch === "\n" ? "\n" : MASKED_CHAR;
+  }
+  return out;
+}
+var GUARD_FILENAMES = ["guard.ts", "guard.js", "guard.mjs", "guard.cjs"];
+function moduleKindOf(filePath, packageIsModule) {
+  if (/\.(?:ts|tsx|mts|cts|jsx)$/.test(filePath)) return "ts";
+  if (/\.mjs$/.test(filePath)) return "esm";
+  if (/\.cjs$/.test(filePath)) return "cjs";
+  return packageIsModule ? "esm" : "cjs";
+}
+function resolvesToGuardModule(specifier, query) {
+  const resolved = resolve(dirname4(query.fromFile), specifier);
+  if (withoutModuleExtension(resolved) !== join9(query.guardDir, "guard")) return false;
+  const existing = GUARD_FILENAMES.filter((name) => existsSync7(join9(query.guardDir, name)));
+  if (existing.length === 0) return false;
+  const extension = /(\.[A-Za-z0-9]+)$/.exec(specifier)?.[1] ?? "";
+  if (!query.strictExtensions) return true;
+  if (extension === "") {
+    if (query.kind === "esm") return false;
+    if (query.kind === "cjs") return existing.includes("guard.js");
+    return true;
+  }
+  if (existsSync7(resolved)) return true;
+  return query.kind === "ts" && extension === ".js" && existing.includes("guard.ts");
+}
+function withoutModuleExtension(filePath) {
+  return filePath.replace(/\.(?:ts|tsx|js|jsx|mjs|cjs)$/, "");
+}
+
+// src/protect/install/generic.ts
+function packageIsEsm(cwd) {
+  try {
+    return JSON.parse(read(join10(cwd, "package.json"))).type === "module";
+  } catch {
+    return false;
+  }
+}
 function genericDir(cwd) {
-  return existsSync7(join9(cwd, "src")) ? "src/patchstack" : "patchstack";
+  return existsSync8(join10(cwd, "src")) ? "src/patchstack" : "patchstack";
 }
-function scaffoldGeneric(cwd, opts, guardTemplate = "generic-guard.ts", guardFile = "guard.ts") {
+function hasTypeScript(cwd) {
+  return existsSync8(join10(cwd, "tsconfig.json")) || candidateEntries(cwd).some((entry) => /\.tsx?$/.test(entry));
+}
+function genericGuardTarget(cwd) {
+  if (hasTypeScript(cwd)) {
+    return { template: "generic-guard.ts", file: "guard.ts", specifier: "guard" };
+  }
+  if (packageIsEsm(cwd)) {
+    return { template: "generic-guard.js", file: "guard.js", specifier: "guard.js" };
+  }
+  return { template: "generic-guard.cjs", file: "guard.cjs", specifier: "guard.cjs" };
+}
+function scaffoldGeneric(cwd, opts, guardTemplate, guardFile) {
+  const target = genericGuardTarget(cwd);
+  guardTemplate ??= target.template;
+  guardFile ??= target.file;
   const templates = templatesDir();
   const dir = genericDir(cwd);
-  const dst = join9(cwd, dir);
+  const dst = join10(cwd, dir);
   mkdirSync4(dst, { recursive: true });
-  copyFileSync4(join9(templates, guardTemplate), join9(dst, guardFile));
+  copyFileSync4(join10(templates, guardTemplate), join10(dst, guardFile));
   const guardRel = `${dir}/${guardFile}`;
   const changed = [guardRel];
   if (!opts.demo) bakeSiteUuid(cwd, guardRel);
-  const rulesDst = join9(dst, "rules.json");
-  if (opts.demo || !existsSync7(rulesDst)) {
-    copyFileSync4(join9(templates, opts.demo ? "demo-rules.json" : "rules.json"), rulesDst);
+  const rulesDst = join10(dst, "rules.json");
+  if (opts.demo || !existsSync8(rulesDst)) {
+    copyFileSync4(join10(templates, opts.demo ? "demo-rules.json" : "rules.json"), rulesDst);
     changed.push(`${dir}/rules.json`);
   }
   return { changed, dir };
@@ -2260,17 +2962,17 @@ function candidateEntries(cwd) {
     "app.ts",
     "app.js"
   ];
-  const hits = names.filter((n) => existsSync7(join9(cwd, n)));
+  const hits = names.filter((n) => existsSync8(join10(cwd, n)));
   try {
-    const pkg = JSON.parse(read(join9(cwd, "package.json")));
-    if (typeof pkg.main === "string" && existsSync7(join9(cwd, pkg.main))) hits.push(pkg.main);
+    const pkg = JSON.parse(read(join10(cwd, "package.json")));
+    if (typeof pkg.main === "string" && existsSync8(join10(cwd, pkg.main))) hits.push(pkg.main);
   } catch {
   }
   return [...new Set(hits)];
 }
 function usesExpress(cwd) {
   try {
-    const pkg = JSON.parse(read(join9(cwd, "package.json")));
+    const pkg = JSON.parse(read(join10(cwd, "package.json")));
     return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.express);
   } catch {
     return false;
@@ -2279,34 +2981,140 @@ function usesExpress(cwd) {
 function wiringPlan(cwd, dir) {
   const entries = candidateEntries(cwd);
   const express = usesExpress(cwd);
+  const target = genericGuardTarget(cwd);
   const lines = [
-    `no built-in adapter matched this stack \u2014 scaffolded a generic guard at ${dir}/guard.ts + ${dir}/rules.json.`,
+    `no built-in adapter matched this stack \u2014 scaffolded a generic guard at ${dir}/${target.file} + ${dir}/rules.json.`,
     "Finish by wiring it into your server (pick the one that fits):",
-    `  \u2022 Web-Fetch entry:  export default { fetch: protectFetch(yourHandler) }   // import from "${dir}/guard"`,
-    `  \u2022 Node / Express:   app.use(patchstackMiddleware)                          // add before your routes`,
+    // The specifier is the one this project's loader resolves — a bare path is right for a compiler and
+    // wrong for `require()`, which never guesses `.cjs`.
+    `  \u2022 Web-Fetch entry:  export default { fetch: protectFetch(yourHandler) }   // import from "${dir}/${target.specifier}"`,
+    `  \u2022 Node / Connect:   app.use(patchstackMiddleware)                          // before any body parser`,
     entries.length ? `Likely server ${entries.length === 1 ? "entry" : "entries"}: ${entries.join(", ")}${express ? "  (Express detected)" : ""}.` : "Could not locate a server entry \u2014 wire it wherever requests enter your app.",
     "Then confirm it is hooked up:  npx patchstack-connect protect --check"
   ];
   return lines.join("\n");
 }
+var GUARD_EXPORTS = ["protectFetch", "patchstackMiddleware"];
+function importsAndUsesGuard(source, sourcePath, guardDir, packageIsModule) {
+  const code = stripComments(source);
+  const masked = maskStringContents(code);
+  const declarations = guardImportDeclarations(code, masked, {
+    fromFile: sourcePath,
+    guardDir,
+    kind: moduleKindOf(sourcePath, packageIsModule),
+    // The scaffold now matches the project's module format and the printed plan names the specifier that
+    // format resolves, so there is nothing left to excuse: a specifier this file's loader would not find is
+    // not a wired guard here either.
+    strictExtensions: true
+  });
+  if (declarations.length === 0) return false;
+  const direct = /* @__PURE__ */ new Set();
+  const namespaces = /* @__PURE__ */ new Set();
+  for (const declaration of declarations) {
+    const bound = boundNames(declaration.text);
+    for (const name of bound.direct) direct.add(name);
+    for (const name of bound.namespaces) namespaces.add(name);
+  }
+  if (direct.size === 0 && namespaces.size === 0) return false;
+  let body = masked;
+  for (const declaration of declarations) {
+    body = body.slice(0, declaration.start) + " ".repeat(declaration.text.length) + body.slice(declaration.start + declaration.text.length);
+  }
+  const members = GUARD_EXPORTS.map(escapeForRegExp).join("|");
+  return [...direct].some((name) => new RegExp(`\\b${escapeForRegExp(name)}\\s*[(),]`).test(body)) || [...namespaces].some(
+    (name) => new RegExp(`\\b${escapeForRegExp(name)}\\s*\\.\\s*(?:${members})\\s*[(),]`).test(body)
+  );
+}
+function guardImportDeclarations(code, masked, query) {
+  const pattern = /import\s+[^;]*?from\s*(['"`])[^'"`]*\1|(?:const|let|var)\s+[^;=]+=\s*require\(\s*(['"`])[^'"`]*\2\s*\)/g;
+  const found = [];
+  for (const match of masked.matchAll(pattern)) {
+    const start = match.index ?? -1;
+    if (start < 0) continue;
+    const text = code.slice(start, start + match[0].length);
+    const specifier = specifierOf(text);
+    if (specifier !== null && resolvesToGuardModule(specifier, query)) found.push({ text, start });
+  }
+  return found;
+}
+function specifierOf(declaration) {
+  return /(['"`])([^'"`]*)\1/.exec(declaration)?.[2] ?? null;
+}
+function boundNames(declaration) {
+  const direct = [];
+  const namespaces = [];
+  const clause = /^import\s+([^]*?)\s+from\b/.exec(declaration)?.[1] ?? /^(?:const|let|var)\s+([^]*?)=\s*require\b/.exec(declaration)?.[1] ?? "";
+  const braced = /\{([^}]*)\}/.exec(clause)?.[1];
+  if (braced !== void 0) {
+    for (const part of braced.split(",")) {
+      const [exported, local] = splitBinding(part);
+      if (!isGuardExport(exported)) continue;
+      if (/^[A-Za-z_$][\w$]*$/.test(local)) direct.push(local);
+    }
+  }
+  const bare = clause.replace(/\{[^}]*\}/g, "").replace(/^\*\s*as\s*/, "").replace(/,/g, " ").trim();
+  for (const token of bare.split(/\s+/)) {
+    if (/^[A-Za-z_$][\w$]*$/.test(token) && token !== "as") namespaces.push(token);
+  }
+  return { direct, namespaces };
+}
+function splitBinding(part) {
+  const separator = part.includes(" as ") ? " as " : part.includes(":") ? ":" : null;
+  if (separator === null) {
+    const name = part.trim();
+    return [name, name];
+  }
+  const [exported, ...rest] = part.split(separator);
+  return [(exported ?? "").trim(), (rest.join(separator) ?? "").trim()];
+}
+function isGuardExport(name) {
+  return GUARD_EXPORTS.includes(name);
+}
+function escapeForRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
 function genericVerify(cwd) {
   const dir = genericDir(cwd);
-  const scaffolded = existsSync7(join9(cwd, dir, "guard.ts"));
-  const imported = scaffolded && guardIsImported(cwd, join9(cwd, dir, "guard.ts"));
+  const target = genericGuardTarget(cwd);
+  const present = GUARD_FILENAMES.find((name) => existsSync8(join10(cwd, dir, name)));
+  const scaffolded = present !== void 0;
+  const imported = scaffolded && guardIsImported(cwd, join10(cwd, dir, present));
   return {
     wired: scaffolded && imported,
     checks: [
       { label: "generic guard scaffolded", ok: scaffolded, hint: "run `patchstack-connect protect`" },
       {
-        label: "guard imported into a server entry",
+        label: "guard imported and called in a server entry",
         ok: imported,
-        hint: `import { protectFetch } (or patchstackMiddleware) from "${dir}/guard" and wire it into your request path`
+        hint: `import { protectFetch } (or patchstackMiddleware) from "${dir}/${present ?? target.specifier}" and wire it into your request path \u2014 an import that is never called screens nothing`
       }
     ]
   };
 }
+var NON_RUNTIME_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  "patchstack",
+  "dist",
+  "build",
+  "out",
+  "coverage",
+  ".next",
+  ".output",
+  ".svelte-kit",
+  "test",
+  "tests",
+  "__tests__",
+  "e2e",
+  "examples",
+  "fixtures",
+  "__fixtures__",
+  "stories",
+  "__mocks__"
+]);
 function guardIsImported(cwd, guardPath) {
-  const root = existsSync7(join9(cwd, "src")) ? join9(cwd, "src") : cwd;
+  const guardDir = dirname5(guardPath);
+  const packageIsModule = packageIsEsm(cwd);
+  const root = existsSync8(join10(cwd, "src")) ? join10(cwd, "src") : cwd;
   let found = false;
   const walk2 = (d, depth) => {
     if (found || depth > 8) return;
@@ -2318,8 +3126,8 @@ function guardIsImported(cwd, guardPath) {
     }
     for (const name of entries) {
       if (found) return;
-      if (name === "node_modules" || name === "patchstack" || name.startsWith(".")) continue;
-      const p = join9(d, name);
+      if (NON_RUNTIME_DIRS.has(name) || name.startsWith(".")) continue;
+      const p = join10(d, name);
       let st;
       try {
         st = lstatSync2(p);
@@ -2330,7 +3138,7 @@ function guardIsImported(cwd, guardPath) {
       if (st.isDirectory()) walk2(p, depth + 1);
       else if (/\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(name) && p !== guardPath) {
         try {
-          if (readFileSync3(p, "utf8").includes(GUARD_MARKER)) found = true;
+          if (importsAndUsesGuard(readFileSync4(p, "utf8"), p, guardDir, packageIsModule)) found = true;
         } catch {
         }
       }
@@ -2341,6 +3149,15 @@ function guardIsImported(cwd, guardPath) {
 }
 
 // src/protect/install/register.ts
+var routeRegistration = (appVar) => new RegExp(
+  `^\\s*${appVar}\\.(?:get|post|put|patch|delete|head|options|all|route)\\(|^\\s*${appVar}\\.use\\(\\s*['"\`]`,
+  "m"
+);
+function routesBefore(source, appVar, guardIndex) {
+  if (guardIndex < 0) return [];
+  const pattern = routeRegistration(appVar);
+  return source.split("\n").map((line, index) => ({ line, index })).filter(({ line, index }) => index < guardIndex && pattern.test(line)).map(({ index }) => index + 1);
+}
 var REGION = "// #region patchstack (managed by patchstack-connect protect \u2014 do not edit)";
 function guardTarget(cwd, entryRel, spec) {
   if (/\.cjs$/.test(entryRel) || /\.js$/.test(entryRel) && packageType(cwd) !== "module") {
@@ -2369,11 +3186,48 @@ function guardTarget(cwd, entryRel, spec) {
 }
 function packageType(cwd) {
   try {
-    return JSON.parse(read(join10(cwd, "package.json"))).type;
+    return JSON.parse(read(join11(cwd, "package.json"))).type;
   } catch {
     return void 0;
   }
 }
+function wiringState(source, spec, appVar, fileRel, guard) {
+  const code = stripComments(source);
+  const masked = maskStringContents(code);
+  const lines = code.split("\n");
+  const maskedLines = masked.split("\n");
+  const call = spec.call(appVar);
+  const callIndex = maskedLines.findIndex((line) => line.includes(call));
+  const importIndex = maskedLines.findIndex(
+    (line, index) => bindsGuard(lines[index] ?? "", line, spec.importName, call, fileRel, guard)
+  );
+  const appIndex = maskedLines.findIndex((line) => spec.appRe.test(line));
+  const anchor = spec.callAfter ? spec.callAfter(appVar) : null;
+  const anchorIndex = anchor ? maskedLines.findIndex((line) => anchor.test(line)) : -1;
+  return {
+    importAtTopLevel: importIndex !== -1 && isTopLevelLine(code, importIndex),
+    callInAppScope: callIndex !== -1 && inSameBlockAfter(code, appIndex, callIndex),
+    ordered: anchor ? anchorIndex !== -1 && callIndex > anchorIndex : callIndex !== -1,
+    callIndex,
+    appIndex
+  };
+}
+function bindsGuard(line, maskedLine, importName, call, fileRel, guard) {
+  if (!maskedLine.includes(importName) || maskedLine.includes(call)) return false;
+  if (/^\s*export\b[^=]*\bfrom\b/.test(maskedLine)) return false;
+  if (!/^\s*(?:import\b|(?:export\s+)?(?:const|let|var)\s+[^=]+=\s*require\()/.test(maskedLine)) return false;
+  const specifier = /(['"`])([^'"`]*)\1/.exec(line)?.[2];
+  if (specifier === void 0 || specifier === "") return false;
+  return namesGuardModule(specifier, fileRel, guard);
+}
+function namesGuardModule(specifier, fileRel, guard) {
+  return resolvesToGuardModule(specifier, {
+    fromFile: join11(guard.cwd, fileRel),
+    guardDir: resolve2(join11(guard.cwd, guard.guardDir)),
+    kind: moduleKindOf(fileRel, packageType(guard.cwd) === "module"),
+    strictExtensions: true
+  });
+}
 function wireRegister(cwd, opts, spec) {
   const entry = findAppInstance(cwd, spec.appRe);
   if (!entry) {
@@ -2381,14 +3235,27 @@ function wireRegister(cwd, opts, spec) {
     log(`${spec.label} not located \u2014 scaffolded guard; ${spec.manualHint}`);
     return { ok: true, changed: changed2 };
   }
+  if (entry.others.length > 0) {
+    log(
+      `${entry.others.map((other) => other.relPath).join(", ")} also start${entry.others.length === 1 ? "s" : ""} a server \u2014 wired ${entry.relPath} only; ${spec.manualHint} there too`
+    );
+  }
   const target = guardTarget(cwd, entry.relPath, spec);
   const { changed, dir } = scaffoldGeneric(cwd, opts, target.template, target.file);
-  const p = join10(cwd, entry.relPath);
+  const p = join11(cwd, entry.relPath);
   const s = read(p);
-  if (s.includes(spec.importName)) {
-    log(`${entry.relPath} already wired`);
+  const state = wiringState(s, spec, entry.appVar, entry.relPath, { cwd, guardDir: dir });
+  if (state.importAtTopLevel && state.callInAppScope) {
+    log(
+      state.ordered ? `${entry.relPath} already wired` : `${entry.relPath} has the guard registered before the body parser, where it cannot read the body \u2014 move \`${spec.call(entry.appVar).trim()}\` below the parser`
+    );
     return { ok: true, changed };
   }
+  if (state.importAtTopLevel || state.callInAppScope) {
+    log(
+      `${entry.relPath} has the guard ${state.importAtTopLevel ? "imported but not registered" : "registered but not imported"} \u2014 completing it`
+    );
+  }
   const sourceLines = s.split("\n");
   const sourceAppIdx = sourceLines.findIndex((line) => spec.appRe.test(line));
   const requiredAnchor = spec.callAfter?.(entry.appVar);
@@ -2401,40 +3268,85 @@ function wireRegister(cwd, opts, spec) {
     importSpecifier(entry.relPath, `${dir}/${target.file}`, target.preserveExtension)
   );
   const lines = s.split("\n");
-  let lastImport = -1;
-  for (let i = 0; i < lines.length; i++) {
-    if (/^\s*(?:import\b|(?:const|let|var)\s+.+?=\s*require\()/.test(lines[i] ?? "")) lastImport = i;
+  if (!state.importAtTopLevel) {
+    const lastImport = lastTopLevelImportLine(s);
+    const importIdx = lastImport === -1 ? firstStatementLine(lines) : lastImport + 1;
+    lines.splice(importIdx, 0, importLine);
   }
-  lines.splice(lastImport + 1, 0, importLine);
   const appIdx = lines.findIndex((l) => spec.appRe.test(l));
-  if (appIdx !== -1) {
+  if (appIdx !== -1 && !state.callInAppScope) {
     const preferred = spec.callAfter?.(entry.appVar);
     const preferredIdx = preferred ? lines.findIndex((line, index) => index > appIdx && preferred.test(line)) : -1;
     const callIdx = preferredIdx === -1 ? appIdx : preferredIdx;
     lines.splice(callIdx + 1, 0, REGION, spec.call(entry.appVar), "// #endregion patchstack");
   }
-  writeFileSync4(p, lines.join("\n"));
+  const patched = lines.join("\n");
+  writeFileSync5(p, patched);
+  if (spec.callAfter) {
+    const guardIndex = lines.findIndex((line) => line.includes(spec.call(entry.appVar)));
+    const early = routesBefore(patched, entry.appVar, guardIndex);
+    if (early.length > 0) {
+      log(
+        `${entry.relPath}: ${early.length} route${early.length === 1 ? "" : "s"} registered before the guard (line${early.length === 1 ? "" : "s"} ${early.join(", ")}) \u2014 those are not screened. Move them below the guard, or move your body parser above them.`
+      );
+    }
+  }
+  const parsed = parses(p);
+  if (parsed === false) {
+    writeFileSync5(p, s);
+    log(`${entry.relPath} would not parse after patching \u2014 reverted; ${spec.manualHint}`);
+    return { ok: true, changed };
+  }
   changed.push(entry.relPath);
   log(`patched ${entry.relPath} (${spec.call(entry.appVar).trim()})`);
   return { ok: true, changed: [...new Set(changed)] };
 }
+function firstStatementLine(lines) {
+  let i = 0;
+  if ((lines[0] ?? "").startsWith("#!")) i = 1;
+  while (i < lines.length) {
+    const line = (lines[i] ?? "").trim();
+    if (line !== "" && !line.startsWith("//") && !line.startsWith("/*") && !line.startsWith("*")) break;
+    i++;
+  }
+  return i;
+}
+function serverIsGuarded(cwd, spec, server, guardDir) {
+  const source = read(join11(cwd, server.relPath));
+  const state = wiringState(source, spec, server.appVar, server.relPath, { cwd, guardDir });
+  if (!state.importAtTopLevel || !state.callInAppScope || !state.ordered) return false;
+  return !spec.callAfter || routesBefore(source, server.appVar, state.callIndex).length === 0;
+}
 function verifyRegister(cwd, spec) {
-  const dir = existsSync8(join10(cwd, "src")) ? "src/patchstack" : "patchstack";
+  const dir = existsSync9(join11(cwd, "src")) ? "src/patchstack" : "patchstack";
   const entry = findAppInstance(cwd, spec.appRe);
   const target = entry ? guardTarget(cwd, entry.relPath, spec) : null;
-  const scaffolded = target ? existsSync8(join10(cwd, dir, target.file)) : false;
-  const entrySource = entry ? read(join10(cwd, entry.relPath)) : "";
-  const entryLines = entrySource.split("\n");
-  const anchor = entry && spec.callAfter ? spec.callAfter(entry.appVar) : null;
-  const anchorIndex = anchor ? entryLines.findIndex((line) => anchor.test(line)) : -1;
-  const callIndex = entry ? entryLines.findIndex((line) => line.includes(spec.call(entry.appVar))) : -1;
-  const ordered = anchor ? anchorIndex !== -1 && callIndex > anchorIndex : callIndex !== -1;
-  const wired = entrySource.includes(spec.importName) && ordered;
+  const scaffolded = target ? existsSync9(join11(cwd, dir, target.file)) : false;
+  const entrySource = entry ? read(join11(cwd, entry.relPath)) : "";
+  const state = entry ? wiringState(entrySource, spec, entry.appVar, entry.relPath, { cwd, guardDir: dir }) : { importAtTopLevel: false, callInAppScope: false, ordered: false, callIndex: -1, appIndex: -1 };
+  const wired = state.importAtTopLevel && state.callInAppScope && state.ordered;
+  const early = spec.callAfter && entry ? routesBefore(entrySource, entry.appVar, state.callIndex) : [];
+  const noEarlyRoutes = early.length === 0;
+  const unguarded = (entry?.others ?? []).filter((other) => !serverIsGuarded(cwd, spec, other, dir)).map((other) => other.relPath);
   return {
-    wired: scaffolded && wired,
+    wired: scaffolded && wired && noEarlyRoutes && unguarded.length === 0,
     checks: [
       { label: `${spec.label} guard scaffolded`, ok: scaffolded, hint: "run `patchstack-connect protect`" },
-      { label: `guard registered on the ${spec.label}`, ok: wired, hint: spec.manualHint }
+      { label: `guard registered on the ${spec.label}`, ok: wired, hint: spec.manualHint },
+      ...entry && entry.others.length > 0 ? [
+        {
+          label: "every server in this project has a guard",
+          ok: unguarded.length === 0,
+          hint: unguarded.length === 0 ? "nothing to do" : `${unguarded.join(", ")} start${unguarded.length === 1 ? "s" : ""} a server without one \u2014 ${spec.manualHint} there`
+        }
+      ] : [],
+      ...spec.callAfter ? [
+        {
+          label: "every route registered after the guard",
+          ok: noEarlyRoutes,
+          hint: noEarlyRoutes ? "nothing to do" : `move the route${early.length === 1 ? "" : "s"} on line${early.length === 1 ? "" : "s"} ${early.join(", ")} below the guard, or move your body parser above them`
+        }
+      ] : []
     ]
   };
 }
@@ -2531,18 +3443,35 @@ function runProtect(cwd, opts = {}) {
     return { status: "scaffolded", adapter: "generic", changed: [], plan: "" };
   }
 }
+var RUNTIMES_WITHOUT_CONFIG_FILE = /* @__PURE__ */ new Set(["next", "sveltekit", "astro", "nuxt", "generic"]);
+function credentialNote(cwd, adapterName) {
+  if (!RUNTIMES_WITHOUT_CONFIG_FILE.has(adapterName)) return [];
+  const localHint = hasResolvableCredential(cwd) ? "a credential is configured here; set the same one in your deployment" : "no credential found here either \u2014 run `npx @patchstack/connect scan` to provision one";
+  return [
+    {
+      label: "live rule updates need PATCHSTACK_API_KEY in the deployment environment",
+      ok: true,
+      unverifiable: true,
+      hint: `this runtime cannot read .patchstackrc.local.json \u2014 ${localHint}. Without it the guard keeps running on the rules it shipped with.`
+    }
+  ];
+}
 function runVerify(cwd) {
   try {
     const adapter = ADAPTERS.find((a) => a.detect(cwd));
-    if (adapter) return { stack: adapter.label, ...adapter.verify(cwd) };
-    return { stack: "generic", ...genericVerify(cwd) };
+    if (adapter) {
+      const result = adapter.verify(cwd);
+      return { stack: adapter.label, ...result, checks: [...result.checks, ...credentialNote(cwd, adapter.name)] };
+    }
+    const generic = genericVerify(cwd);
+    return { stack: "generic", ...generic, checks: [...generic.checks, ...credentialNote(cwd, "generic")] };
   } catch (err) {
     return { stack: "unknown", wired: false, checks: [{ label: "verification failed", ok: false, hint: String(err?.message ?? err) }] };
   }
 }
 
 // src/widget.ts
-import { existsSync as existsSync9, readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "fs";
+import { existsSync as existsSync10, readFileSync as readFileSync5, writeFileSync as writeFileSync6 } from "fs";
 import path8 from "path";
 var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
 var WIDGET_MARKER_ATTR = "data-patchstack-connect-widget";
@@ -2581,7 +3510,7 @@ ${indent}</body>`;
 }
 function findSourceShell(cwd) {
   for (const candidate of SOURCE_SHELL_CANDIDATES) {
-    if (existsSync9(path8.join(cwd, candidate))) {
+    if (existsSync10(path8.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -2593,15 +3522,16 @@ function ensureSourceWidget(cwd, siteUuid) {
     return { shell: null, action: "no-shell" };
   }
   const file = path8.join(cwd, shell);
-  const before = readFileSync4(file, "utf8");
+  const before = readFileSync5(file, "utf8");
   const { html, action } = ensureWidgetInHtml(before, siteUuid);
   if (html !== before) {
-    writeFileSync5(file, html);
+    writeFileSync6(file, html);
   }
   return { shell, action };
 }
 
 // src/guide.ts
+var PROD_MARKER_NEEDLE = "__PATCHSTACK_PROD__";
 var WIDGET_NEEDLE2 = "patchstack-widget";
 var INSTALL_COMMANDS = {
   npm: "npm install --save @patchstack/connect",
@@ -2674,7 +3604,7 @@ function detectPackageManager(cwd) {
     return declared;
   }
   for (const { filename, pm } of PM_BY_LOCKFILE) {
-    if (existsSync10(path9.join(cwd, filename))) {
+    if (existsSync11(path9.join(cwd, filename))) {
       return pm;
     }
   }
@@ -2685,7 +3615,7 @@ function installCommand(pm) {
 }
 function readPackageJson(cwd) {
   try {
-    return JSON.parse(readFileSync5(path9.join(cwd, "package.json"), "utf8"));
+    return JSON.parse(readFileSync6(path9.join(cwd, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -2693,7 +3623,7 @@ function readPackageJson(cwd) {
 function installedVersion(cwd, declaredRange) {
   try {
     const pkg = JSON.parse(
-      readFileSync5(path9.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
+      readFileSync6(path9.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
     );
     if (typeof pkg.version === "string" && pkg.version.length > 0) {
       return pkg.version;
@@ -2737,7 +3667,7 @@ function findWidgetMarker(cwd, siteUuid) {
         if (statSync2(full).size > WIDGET_SCAN_MAX_BYTES) {
           continue;
         }
-        const content = readFileSync5(full, "utf8");
+        const content = readFileSync6(full, "utf8");
         if (!content.includes(WIDGET_NEEDLE2)) {
           continue;
         }
@@ -2755,13 +3685,23 @@ function findWidgetMarker(cwd, siteUuid) {
     uuidMatches: sawWidget && siteUuid != null ? sawTokenMatch : null
   };
 }
+function findProductionMarker(cwd, widgetFileHint) {
+  if (widgetFileHint === null) {
+    return false;
+  }
+  try {
+    return readFileSync6(path9.join(cwd, widgetFileHint), "utf8").includes(PROD_MARKER_NEEDLE);
+  } catch {
+    return false;
+  }
+}
 function resolveWidgetFileHint(cwd, framework) {
   const candidates = [
     ...framework !== null ? WIDGET_FILE_CANDIDATES[framework] ?? [] : [],
     ...GENERIC_WIDGET_FILES
   ];
   for (const candidate of candidates) {
-    if (existsSync10(path9.join(cwd, candidate))) {
+    if (existsSync11(path9.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -2804,6 +3744,7 @@ async function collectGuideState(cwd) {
     {}
   );
   const widget = findWidgetMarker(cwd, siteUuid);
+  const widgetFileHint = resolveWidgetFileHint(cwd, stack.framework);
   const protection = runVerify(cwd);
   return {
     projectName: pkg?.name ?? null,
@@ -2823,7 +3764,8 @@ async function collectGuideState(cwd) {
     widgetTokenMatches: widget.uuidMatches,
     widgetOptOut,
     framework: stack.framework,
-    widgetFileHint: resolveWidgetFileHint(cwd, stack.framework),
+    widgetFileHint,
+    productionMarkerWired: findProductionMarker(cwd, widgetFileHint),
     protectionWired: protection.wired,
     protectionStack: protection.stack,
     protectionChecks: protection.checks
@@ -2837,6 +3779,12 @@ var ANSI = {
   yellow: "\x1B[33m",
   cyan: "\x1B[36m"
 };
+function needsSourceProductionMarker(state) {
+  if (state.siteUuid === null || state.widgetOptOut || state.widgetFileHint === null) {
+    return false;
+  }
+  return !state.widgetFileHint.toLowerCase().endsWith(".html");
+}
 function countRemainingSteps(state) {
   return [
     state.installed?.section === "dependencies",
@@ -2844,6 +3792,7 @@ function countRemainingSteps(state) {
     state.installScanWired,
     !state.hasBuildScript || state.prebuildWired && state.postbuildWired,
     state.widgetOptOut || state.widgetInstalled && state.widgetTokenMatches !== false,
+    !needsSourceProductionMarker(state) || state.productionMarkerWired,
     state.protectionWired
   ].filter((step) => !step).length;
 }
@@ -2934,6 +3883,34 @@ function renderGuideChecklist(state, useColor) {
     lines.push(detail(`  ${buildWidgetTag(state.siteUuid)}`));
     lines.push(detail("The site UUID is public by design \u2014 it ships in client-side HTML."));
   }
+  if (needsSourceProductionMarker(state)) {
+    if (state.productionMarkerWired) {
+      lines.push(done("Production marker wired (widget switches to report mode on the published site)"));
+    } else {
+      lines.push(todo("Add the production marker \u2014 this root is server-rendered, so mark-build cannot stamp it"));
+      lines.push(
+        detail(
+          "Without it the widget treats the published site as build mode and shows the claim flow to visitors."
+        )
+      );
+      const gate = productionGate(state.framework);
+      if (hasJsxShell(state.framework)) {
+        lines.push(detail(`Run \u2192 npx @patchstack/connect scan  (adds it to ${state.widgetFileHint} automatically)`));
+        lines.push(detail("Or add it by hand, in <head> above the widget tag:"));
+        for (const snippetLine of buildSourceMarkerSnippet(state.framework).split("\n")) {
+          lines.push(detail(`  ${snippetLine}`));
+        }
+      } else {
+        lines.push(
+          detail(
+            `Edit ${state.widgetFileHint} \u2192 using the framework's head mechanism, emit an inline`
+          )
+        );
+        lines.push(detail(`  <script>window.__PATCHSTACK_PROD__=true;</script> only when ${gate}.`));
+      }
+      lines.push(detail(`The ${gate} guard is required \u2014 an ungated marker also hides the claim flow in preview.`));
+    }
+  }
   if (state.protectionWired) {
     lines.push(done(`Runtime protection wired (${state.protectionStack})`));
   } else {
@@ -2961,7 +3938,7 @@ function renderGuideChecklist(state, useColor) {
       done(
         paint(
           ANSI.bold,
-          "All setup steps complete. Commit .patchstackrc.json, package.json, the runtime guard changes, and the file carrying the widget snippet."
+          "All setup steps complete. Commit .patchstackrc.json, package.json, the runtime guard changes, and the file carrying the widget snippet. Never commit .patchstackrc.local.json \u2014 it holds the API key, and setup has already added it to .gitignore."
         )
       )
     );
@@ -2977,7 +3954,7 @@ function renderGuideChecklist(state, useColor) {
 }
 
 // src/login.ts
-import { mkdtempSync, readFileSync as readFileSync6, rmSync, writeFileSync as writeFileSync6 } from "fs";
+import { mkdtempSync, readFileSync as readFileSync7, rmSync, writeFileSync as writeFileSync7 } from "fs";
 import { tmpdir } from "os";
 import path10 from "path";
 import { createHash as createHash2 } from "crypto";
@@ -2994,11 +3971,11 @@ function pendingPath(siteUuid) {
   return path10.join(tmpdir(), `patchstack-login-${key}.json`);
 }
 function savePendingLogin(siteUuid, pending) {
-  writeFileSync6(pendingPath(siteUuid), JSON.stringify(pending), { encoding: "utf8", mode: 384 });
+  writeFileSync7(pendingPath(siteUuid), JSON.stringify(pending), { encoding: "utf8", mode: 384 });
 }
 function readPendingLogin(siteUuid) {
   try {
-    return JSON.parse(readFileSync6(pendingPath(siteUuid), "utf8"));
+    return JSON.parse(readFileSync7(pendingPath(siteUuid), "utf8"));
   } catch {
     return null;
   }
@@ -3104,10 +4081,10 @@ async function login(config, onPrompt, deps = {}) {
 // src/map/ts-loader.ts
 import { createRequire } from "module";
 import { pathToFileURL } from "url";
-import { join as join11 } from "path";
+import { join as join12 } from "path";
 async function loadTypeScript(cwd) {
   try {
-    const req = createRequire(pathToFileURL(join11(cwd, "package.json")));
+    const req = createRequire(pathToFileURL(join12(cwd, "package.json")));
     const resolved = req.resolve("typescript");
     const mod = await import(pathToFileURL(resolved).href);
     return mod.default ?? mod;
@@ -3122,7 +4099,7 @@ async function loadTypeScript(cwd) {
 }
 
 // src/map/extract.ts
-import { readFileSync as readFileSync11, realpathSync as realpathSync3 } from "fs";
+import { readFileSync as readFileSync12, realpathSync as realpathSync3 } from "fs";
 import { createHash as createHash4 } from "crypto";
 import { relative as relative4 } from "path";
 
@@ -3378,8 +4355,8 @@ function npmPackageOf(spec) {
 }
 
 // src/map/sources.ts
-import { readFileSync as readFileSync7, readdirSync as readdirSync5, realpathSync, statSync as statSync3 } from "fs";
-import { join as join12, relative as relative2, isAbsolute } from "path";
+import { readFileSync as readFileSync8, readdirSync as readdirSync5, realpathSync, statSync as statSync3 } from "fs";
+import { join as join13, relative as relative2, isAbsolute } from "path";
 
 // src/map/routes.ts
 var ROUTE_REGISTER_NAMES = ["get", "post", "put", "patch", "delete", "options", "all", "head", "use"];
@@ -3463,7 +4440,7 @@ function hasEntrySignal(text) {
 }
 function detectFramework(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync7(join12(cwd, "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync8(join13(cwd, "package.json"), "utf8"));
     const d = { ...pkg.dependencies, ...pkg.devDependencies };
     if (d["@tanstack/react-start"] || d["@tanstack/start"] || d["@tanstack/solid-start"]) return "tanstack-start";
     if (d["next"]) return "next";
@@ -3475,11 +4452,11 @@ function detectFramework(cwd) {
   } catch {
   }
   try {
-    if (statSync3(join12(cwd, "supabase", "functions")).isDirectory()) return "supabase-functions";
+    if (statSync3(join13(cwd, "supabase", "functions")).isDirectory()) return "supabase-functions";
   } catch {
   }
   try {
-    if (statSync3(join12(cwd, "functions")).isDirectory()) return "deno-functions";
+    if (statSync3(join13(cwd, "functions")).isDirectory()) return "deno-functions";
   } catch {
   }
   return "unknown";
@@ -3532,7 +4509,7 @@ function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ ne
   entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
   for (const e of entries) {
     if (SKIP_DIRS2.has(e.name) || e.name.startsWith(".") && e.name !== ".") continue;
-    const full = join12(dir, e.name);
+    const full = join13(dir, e.name);
     if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats);
     else if (e.isSymbolicLink()) {
       let st, real;
@@ -3602,7 +4579,7 @@ function detectDeploymentShapes(cwd, opts = {}) {
   const found = [];
   for (const candidate of DEPLOYMENT_SHAPES) {
     for (const file of candidate.files ?? []) {
-      const full = join12(cwd, file);
+      const full = join13(cwd, file);
       try {
         if (statSync3(full).isFile() && inProject(full)) {
           found.push({ shape: candidate.shape, source: file, evidence: candidate.evidence });
@@ -3612,7 +4589,7 @@ function detectDeploymentShapes(cwd, opts = {}) {
       }
     }
     for (const dir of candidate.dirs ?? []) {
-      const full = join12(cwd, dir);
+      const full = join13(cwd, dir);
       try {
         if (!statSync3(full).isDirectory() || !inProject(full)) continue;
       } catch {
@@ -3631,7 +4608,7 @@ function holdsFunctionEntry(dir) {
     for (const entry of readdirSync5(dir, { withFileTypes: true })) {
       if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
       try {
-        for (const nested of readdirSync5(join12(dir, entry.name), { withFileTypes: true })) {
+        for (const nested of readdirSync5(join13(dir, entry.name), { withFileTypes: true })) {
           if (nested.isFile() && /^index\.(ts|tsx|mts|cts|js|jsx|mjs|cjs)$/.test(nested.name)) return true;
         }
       } catch {
@@ -3647,7 +4624,7 @@ function holdsSourceFile(dir) {
       if (entry.isFile() && isSourceFile(entry.name)) return true;
       if (entry.isDirectory()) {
         try {
-          for (const nested of readdirSync5(join12(dir, entry.name), { withFileTypes: true })) {
+          for (const nested of readdirSync5(join13(dir, entry.name), { withFileTypes: true })) {
             if (nested.isFile() && isSourceFile(nested.name)) return true;
           }
         } catch {
@@ -3660,8 +4637,8 @@ function holdsSourceFile(dir) {
 }
 
 // src/map/surface.ts
-import { readFileSync as readFileSync8 } from "fs";
-import { join as join13 } from "path";
+import { readFileSync as readFileSync9 } from "fs";
+import { join as join14 } from "path";
 var STATIC_GENERATORS = [
   { dep: "vite", label: "vite" },
   { dep: "react-scripts", label: "create-react-app" },
@@ -3699,7 +4676,7 @@ var SHAPE_SIGNAL = {
 };
 function readManifest(cwd) {
   try {
-    const parsed = JSON.parse(readFileSync8(join13(cwd, "package.json"), "utf8"));
+    const parsed = JSON.parse(readFileSync9(join14(cwd, "package.json"), "utf8"));
     return typeof parsed === "object" && parsed !== null ? parsed : null;
   } catch {
     return null;
@@ -3712,7 +4689,7 @@ function nextExportsStatically(cwd, manifest, ts) {
   for (const file of ["next.config.js", "next.config.mjs", "next.config.ts", "next.config.cjs"]) {
     let text;
     try {
-      text = readFileSync8(join13(cwd, file), "utf8");
+      text = readFileSync9(join14(cwd, file), "utf8");
     } catch {
       continue;
     }
@@ -4112,8 +5089,8 @@ function dedupeSinks(sinks, owner) {
 }
 
 // src/map/module-graph.ts
-import { readFileSync as readFileSync9, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
-import { dirname as dirname4, join as join14, relative as relative3, resolve as resolvePath } from "path";
+import { readFileSync as readFileSync10, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
+import { dirname as dirname7, join as join15, relative as relative3, resolve as resolvePath } from "path";
 var RESOLVE_EXTS = [".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"];
 function createModuleGraph(ts, opts) {
   const cache = /* @__PURE__ */ new Map();
@@ -4121,7 +5098,7 @@ function createModuleGraph(ts, opts) {
     if (cache.has(file)) return cache.get(file) ?? null;
     let entry = null;
     try {
-      const text = readFileSync9(file, "utf8");
+      const text = readFileSync10(file, "utf8");
       const sf = ts.createSourceFile(file, text, ts.ScriptTarget.Latest, true, guessScriptKind(ts, file));
       const bindings = buildModuleBindings(sf, ts);
       entry = { fnSinks: collectLocalSinks(sf, ts, bindings), calleesOf: collectCallees(sf, ts), bindings };
@@ -4181,7 +5158,7 @@ function createModuleGraph(ts, opts) {
 }
 function resolveRelativeModule(fromFile, spec) {
   if (!spec.startsWith(".")) return void 0;
-  const dir = dirname4(fromFile);
+  const dir = dirname7(fromFile);
   const base = resolvePath(dir, spec);
   const candidates = [];
   const jsLike = /\.(js|jsx|mjs|cjs)$/.exec(base);
@@ -4191,7 +5168,7 @@ function resolveRelativeModule(fromFile, spec) {
   }
   candidates.push(base);
   for (const e of RESOLVE_EXTS) candidates.push(base + e);
-  for (const e of RESOLVE_EXTS) candidates.push(join14(base, "index" + e));
+  for (const e of RESOLVE_EXTS) candidates.push(join15(base, "index" + e));
   for (const c of candidates) {
     try {
       if (statSync4(c).isFile()) return c;
@@ -4863,8 +5840,8 @@ function handlerEntry(name, kindLabel, params, body, ts, localSinks, bindings, c
 }
 
 // src/map/imports.ts
-import { readFileSync as readFileSync10 } from "fs";
-import { join as join15 } from "path";
+import { readFileSync as readFileSync11 } from "fs";
+import { join as join16 } from "path";
 var MAX_SITES = 5;
 var NPM_NAME = /^(?:@[^/@\s~][^/@\s]*\/)?[^/@\s.~][^/@\s]*$/;
 function isNpmPackageName(pkg) {
@@ -4875,7 +5852,7 @@ function readPathAliases(cwd) {
   for (const name of ["tsconfig.json", "jsconfig.json"]) {
     let paths;
     try {
-      const raw = readFileSync10(join15(cwd, name), "utf8");
+      const raw = readFileSync11(join16(cwd, name), "utf8");
       const parsed = JSON.parse(stripJsonComments(raw));
       paths = parsed.compilerOptions?.paths;
     } catch {
@@ -5254,7 +6231,7 @@ async function extractInputMap(cwd, ts, options = {}) {
   const hopTargets = /* @__PURE__ */ new Set();
   for (const file of files) {
     try {
-      const text = readFileSync11(file, "utf8");
+      const text = readFileSync12(file, "utf8");
       const relFile = relative4(cwd, file);
       sourceBytes += text.length;
       if (!hasEntrySignal(text)) {
@@ -5309,7 +6286,7 @@ async function extractInputMap(cwd, ts, options = {}) {
   for (const target of hopTargets) {
     if (entryFiles.has(target)) continue;
     try {
-      const text = readFileSync11(target, "utf8");
+      const text = readFileSync12(target, "utf8");
       const sf = ts.createSourceFile(target, text, ts.ScriptTarget.Latest, true, guessScriptKind(ts, target));
       const bindings = buildModuleBindings(sf, ts);
       const called = collectInvocations(sf, ts, bindings, { file: target, owner: relative4(cwd, target), graph });
@@ -5440,7 +6417,7 @@ async function buildInputMap(cwd, options = {}) {
 }
 
 // src/setup.ts
-import { readFileSync as readFileSync12, writeFileSync as writeFileSync7 } from "fs";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
 import path11 from "path";
 var SCAN_COMMAND = "patchstack-connect scan";
 var MARK_BUILD_COMMAND = "patchstack-connect mark-build";
@@ -5460,7 +6437,7 @@ function appendHook(existing, command) {
 }
 function wireBuildScripts(cwd, packageManager) {
   const target = path11.join(cwd, "package.json");
-  const raw = readFileSync12(target, "utf8");
+  const raw = readFileSync13(target, "utf8");
   const pkg = JSON.parse(raw);
   const scripts = pkg.scripts ?? {};
   const build = scripts.build;
@@ -5509,7 +6486,7 @@ function wireBuildScripts(cwd, packageManager) {
   const indentMatch = raw.match(/^[\t ]+(?=")/m)?.[0];
   const indent = indentMatch?.includes("	") ? "	" : indentMatch?.length ?? 2;
   const trailingNewline = raw.endsWith("\n") ? "\n" : "";
-  writeFileSync7(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
+  writeFileSync8(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
   if (build === void 0 || build.trim().length === 0) {
     return {
       changed: true,
@@ -5588,7 +6565,9 @@ Usage:
                                                      print the full setup guide. --full prints the
                                                      guide even when setup is complete
   patchstack-connect login  [--wait]                 Recover this site's credential when
-                                                     .patchstackrc.json has been lost. Prints a link
+                                                     .patchstackrc.local.json has been lost. Needs the
+                                                     site UUID, which lives in the committed
+                                                     .patchstackrc.json. Prints a link
                                                      for the site's OWNER to approve in the dashboard.
                                                      In a terminal it then waits. When the output is
                                                      piped or captured \u2014 an assistant running it \u2014 it
@@ -5629,7 +6608,8 @@ Environment:
   PATCHSTACK_MODE         (protect) Runtime guard mode: block (default) | dry-run
   PATCHSTACK_ROUTE_WAF    (protect) Set to 1 to also screen every request at the route level (opt-in)
 
-Precedence: CLI flag > environment variable > .patchstackrc.json.
+Precedence, site UUID and settings: CLI flag > environment variable > .patchstackrc.json (committed).
+Precedence, API key: environment variable > .patchstackrc.local.json (git-ignored) > .patchstackrc.json.
 
 Examples:
   npx @patchstack/connect setup
@@ -5702,8 +6682,13 @@ async function runLogin(args) {
     cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
     cliEndpoint: getStringFlag(args.flags, "endpoint")
   });
-  const approved = () => {
-    console.log("\n  \u2713 Credential restored and saved to .patchstackrc.json.");
+  const approved = async () => {
+    const ignore = await secretFileIgnored(process.cwd());
+    console.log(`
+  \u2713 Credential restored and saved to ${SECRET_CONFIG_FILENAME}.`);
+    console.log(
+      ignore.ignored ? "    Added to .gitignore." : `    NOT ignored by git \u2014 ${ignore.reason ?? "unknown reason"}. Add it to .gitignore yourself before committing.`
+    );
     console.log("    The previous credential no longer works. Update it anywhere else it was set:");
     console.log("    CI secrets, hosting env vars, preview environments, other checkouts.\n");
     return 0;
@@ -5715,7 +6700,7 @@ async function runLogin(args) {
       return 1;
     }
     const resumed = await waitForApproval(config, pending);
-    if (resumed.status === "approved") return approved();
+    if (resumed.status === "approved") return await approved();
     console.error(`
   ${resumed.message ?? "Login failed."}
 `);
@@ -5734,7 +6719,7 @@ async function runLogin(args) {
     const existing = config.siteUuid === null ? null : readPendingLogin(config.siteUuid);
     if (existing !== null && Date.now() < existing.expiresAt) {
       const outcome = await redeemIfApproved(config, existing);
-      if (outcome === "approved") return approved();
+      if (outcome === "approved") return await approved();
       if (outcome === "pending") {
         const secondsLeft = Math.round((existing.expiresAt - Date.now()) / 1e3);
         console.log(`
@@ -5761,7 +6746,7 @@ async function runLogin(args) {
     prompt(userCode, verificationUri);
     console.log("  Waiting for approval (the code expires in 10 minutes)\u2026");
   });
-  if (result.status === "approved") return approved();
+  if (result.status === "approved") return await approved();
   console.error(`
   ${result.message ?? "Login failed."}
 `);
@@ -5810,7 +6795,7 @@ async function runMap(args) {
   const json = JSON.stringify(map, null, 2);
   const out = getStringFlag(args.flags, "out");
   if (out) {
-    writeFileSync8(out, json);
+    writeFileSync9(out, json);
     console.error(`patchstack: wrote ${out}`);
   } else if (args.flags.get("upload") !== true) {
     console.log(json);
@@ -5883,6 +6868,9 @@ async function runScan(args, options = {}) {
     }
     return 0;
   }
+  if (config.widget) {
+    reportSourceMarker(detectStack(payload.packages).framework);
+  }
   const provisioning = config.siteUuid === null;
   if (provisioning) {
     console.log("No site UUID configured \u2014 provisioning a new Patchstack site from this manifest\u2026");
@@ -5893,8 +6881,17 @@ async function runScan(args, options = {}) {
     console.log(`Provisioned site ${response.uuid}. Saved UUID to ${target}.`);
   }
   if (typeof response.api_key === "string" && response.api_key.length > 0) {
-    const target = await persistApiKey(process.cwd(), response.api_key);
-    console.log(`Saved API key to ${target} (authenticates Pulse ingest and block-log reporting; keep out of the public widget).`);
+    const hadCredentialInConfig = await credentialInCommittedConfig(process.cwd());
+    const saved = await persistApiKey(process.cwd(), response.api_key);
+    console.log(`Saved API key to ${saved.path}. Do not commit it.`);
+    console.log(
+      saved.ignored ? "  Added to .gitignore." : `  NOT ignored by git \u2014 ${saved.reason ?? "unknown reason"}. Add \`${SECRET_CONFIG_FILENAME}\` to .gitignore yourself before committing.`
+    );
+    if (hadCredentialInConfig) {
+      console.log(
+        "A credential was also present in .patchstackrc.json and has been removed from it. If that file was ever committed, rotate the credential from the dashboard."
+      );
+    }
   }
   if (response.stored) {
     console.log(`Stored manifest #${response.manifest_id} (checksum ${response.checksum}).`);
@@ -5965,14 +6962,54 @@ function reportSourceWidget(siteUuid) {
     console.warn(`Widget: skipped (${err.message}).`);
   }
 }
+function reportSourceMarker(framework) {
+  try {
+    const shell = resolveWidgetFileHint(process.cwd(), framework);
+    if (shell === null || shell.toLowerCase().endsWith(".html")) {
+      return;
+    }
+    const result = ensureSourceMarker(process.cwd(), shell, framework);
+    switch (result.action) {
+      case "added":
+        console.log(`Production marker: added to ${shell} (guarded by ${productionGate(framework)}).`);
+        console.log("  This root is server-rendered, so the marker ships in source rather than built HTML.");
+        break;
+      case "manual":
+        console.log(`Production marker: already set in ${shell} \u2014 left untouched.`);
+        break;
+      case "no-anchor":
+      case "unsupported":
+        console.log(
+          `Production marker: ${shell} needs it by hand \u2014 without it the widget reads the published site as build mode.`
+        );
+        if (hasJsxShell(framework)) {
+          for (const line of buildSourceMarkerSnippet(framework).split("\n")) {
+            console.log(`  ${line}`);
+          }
+        } else {
+          console.log(
+            `  Emit <script>window.__PATCHSTACK_PROD__=true;</script> only when ${productionGate(framework)}.`
+          );
+        }
+        break;
+    }
+  } catch (err) {
+    console.warn(`Production marker: skipped (${err.message}).`);
+  }
+}
 async function runProtectCommand(args) {
   if (args.flags.get("check") === true) {
     const report = runVerify(process.cwd());
     console.log(`patchstack protect --check (${report.stack}):`);
     for (const c of report.checks) {
-      console.log(`  ${c.ok ? "\u2713" : "\u2717"} ${c.label}${!c.ok && c.hint ? ` \u2014 ${c.hint}` : ""}`);
+      const mark = c.unverifiable ? "?" : c.ok ? "\u2713" : "\u2717";
+      const note = c.unverifiable || !c.ok ? c.hint : void 0;
+      console.log(`  ${mark} ${c.label}${note ? ` \u2014 ${note}` : ""}`);
     }
     console.log(report.wired ? "guard is wired \u2713" : "guard is NOT fully wired \u2717");
+    if (report.checks.some((c) => c.unverifiable)) {
+      console.log("One or more checks could not be answered from here \u2014 see the `?` lines above.");
+    }
     return report.wired ? 0 : 1;
   }
   const demo = args.flags.get("demo") === true;
@@ -6096,7 +7133,7 @@ async function runGuide(args) {
   console.log("\u2014\u2014\u2014\u2014 Full reference guide (ships as AGENT-INSTALL.md) \u2014\u2014\u2014\u2014");
   console.log("");
   const guidePath = new URL("../AGENT-INSTALL.md", import.meta.url);
-  console.log(readFileSync13(guidePath, "utf8"));
+  console.log(readFileSync14(guidePath, "utf8"));
   return 0;
 }
 async function runSetup(args) {
@@ -6270,14 +7307,20 @@ async function runMarkBuild(args) {
   }
   const files = findHtmlFiles(dir);
   if (files.length === 0) {
-    console.warn(`mark-build: no HTML files found under ${dir}. Nothing to mark.`);
+    console.warn(`mark-build: found ${dir} but no HTML files in it.`);
+    console.warn(
+      "mark-build: this build looks server-rendered, so the production flag has nothing to stamp."
+    );
+    console.warn(
+      "mark-build: add the marker to your root shell instead \u2014 run `patchstack-connect guide` for the snippet."
+    );
     return 0;
   }
   const snippet = buildInjectionSnippet(checksum, stack);
   let marked = 0;
   let widgetTouched = 0;
   for (const file of files) {
-    const before = readFileSync13(file, "utf8");
+    const before = readFileSync14(file, "utf8");
     let after = injectMarker(before, snippet);
     if (widgetUuid !== null) {
       const ensured = ensureWidgetInHtml(after, widgetUuid);
@@ -6287,7 +7330,7 @@ async function runMarkBuild(args) {
       after = ensured.html;
     }
     if (after !== before) {
-      writeFileSync8(file, after);
+      writeFileSync9(file, after);
       marked += 1;
     }
   }