@patchstack/connect 0.3.29 → 0.3.31

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync14, writeFileSync as writeFileSync9 } from "fs";
+import { readFileSync as readFileSync14, writeFileSync as writeFileSync10 } 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,125 @@ 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, cwd));
+}
+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, root) {
   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, root);
     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, root);
+      });
+      return scoped.flat();
     }
-    await readPackage(fullPath, depth, acc);
-    await walkNested(fullPath, acc, depth);
-  }
+    return packageAndNested(fullPath, resolved, depth, seen, root);
+  });
+  return perEntry.flat();
+}
+async function packageAndNested(pkgDir, resolved, depth, seen, root) {
+  const [own, nested] = await Promise.all([readPackage(pkgDir, depth, root), walkNested(pkgDir, depth, seen, root)]);
+  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, acc) {
+function installLocation(root, pkgDir, impl = path3) {
+  return impl.relative(root, pkgDir).split(impl.sep).join("/");
+}
+async function readPackage(pkgDir, depth, root) {
   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, path: installLocation(root, pkgDir), direct: depth === 0 };
 }
-async function walkNested(pkgDir, acc, depth) {
+async function walkNested(pkgDir, depth, seen, root) {
   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, root);
 }
-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 +464,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 +692,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 +705,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 +734,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 +763,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 +824,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 +879,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 +908,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,34 +946,58 @@ 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(", ");
     throw new PatchstackError(
@@ -775,6 +1013,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 +1036,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);
   }
@@ -811,21 +1062,33 @@ async function exists(filePath) {
 }
 
 // src/normalize.ts
-function buildWirePayload(manifest) {
+function buildWirePayload(manifest, options = {}) {
+  const withPaths = options.installPaths === true;
   const seen = /* @__PURE__ */ new Map();
   const wirePackages = [];
+  const byIdentity = /* @__PURE__ */ new Map();
+  let entriesWithoutPath = 0;
   for (const entry of manifest.packages) {
+    const identity = `${entry.name}@${entry.version}`;
+    const location = withPaths && entry.path !== void 0 && entry.path !== "" ? entry.path : void 0;
+    if (location === void 0) entriesWithoutPath++;
+    const existing = byIdentity.get(identity);
+    if (existing) {
+      if (location !== void 0) addPath(existing, location);
+      continue;
+    }
     const versions = seen.get(entry.name);
     if (versions) {
-      if (versions.has(entry.version)) {
-        continue;
-      }
       versions.add(entry.version);
     } else {
       seen.set(entry.name, /* @__PURE__ */ new Set([entry.version]));
     }
-    wirePackages.push({ name: entry.name, version: entry.version });
+    const wire6 = { name: entry.name, version: entry.version };
+    if (location !== void 0) addPath(wire6, location);
+    byIdentity.set(identity, wire6);
+    wirePackages.push(wire6);
   }
+  for (const wire6 of wirePackages) wire6.paths?.sort();
   wirePackages.sort((a, b) => {
     if (a.name === b.name) {
       return compareVersions(a.version, b.version);
@@ -839,7 +1102,18 @@ function buildWirePayload(manifest) {
     }
   }
   return {
-    payload: { ecosystem: manifest.ecosystem, packages: wirePackages },
+    payload: {
+      ecosystem: manifest.ecosystem,
+      packages: wirePackages,
+      // Every entry had a location, so a missing path anywhere means the package is not installed there.
+      // One entry without one forfeits that for the whole payload: a consumer reading a short `paths` has
+      // no way to tell which entry was the incomplete one.
+      //
+      // No separate check for "locations were not requested": with them off every entry counts as without
+      // one, so this is already false — which is the default, and the safe direction. An explicit
+      // `withPaths &&` here was a guard no test could distinguish from its absence.
+      installPathsComplete: entriesWithoutPath === 0 && manifest.packages.length > 0
+    },
     stats: {
       uniqueNames: seen.size,
       duplicateNames,
@@ -847,6 +1121,10 @@ function buildWirePayload(manifest) {
     }
   };
 }
+function addPath(wire6, installPath) {
+  if (wire6.paths === void 0) wire6.paths = [installPath];
+  else if (!wire6.paths.includes(installPath)) wire6.paths.push(installPath);
+}
 function compareVersions(a, b) {
   if (a === b) {
     return 0;
@@ -1228,7 +1506,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 +1576,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 +1661,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 +1710,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 +1742,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 +1760,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 {};
@@ -1767,7 +2130,7 @@ function ensureSourceMarker(cwd, shell, framework) {
 }
 
 // src/guide.ts
-import { existsSync as existsSync10, readFileSync as readFileSync6, 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
@@ -1784,6 +2147,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) {
@@ -1858,7 +2235,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");
@@ -2252,9 +2630,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();
@@ -2262,7 +2640,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;
@@ -2281,12 +2658,65 @@ function findAppInstance(cwd, re) {
           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, "/");
@@ -2296,28 +2726,252 @@ function importSpecifier(fromRel, toRel, preserveExtension = false) {
 }
 
 // src/protect/install/register.ts
-import { writeFileSync as writeFileSync5, 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 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
-import { readFileSync as readFileSync4, 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";
+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 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 = "generic-guard.ts", guardFile = "guard.ts") {
+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 };
@@ -2338,17 +2992,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;
@@ -2357,34 +3011,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;
@@ -2396,8 +3156,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);
@@ -2408,7 +3168,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 (readFileSync4(p, "utf8").includes(GUARD_MARKER)) found = true;
+          if (importsAndUsesGuard(readFileSync4(p, "utf8"), p, guardDir, packageIsModule)) found = true;
         } catch {
         }
       }
@@ -2419,6 +3179,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") {
@@ -2447,11 +3216,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) {
@@ -2459,14 +3265,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);
@@ -2479,40 +3298,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");
   }
-  writeFileSync5(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`
+        }
+      ] : []
     ]
   };
 }
@@ -2609,18 +3473,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 readFileSync5, writeFileSync as writeFileSync6 } 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";
@@ -2659,7 +3540,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;
     }
   }
@@ -2753,7 +3634,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;
     }
   }
@@ -2850,7 +3731,7 @@ function resolveWidgetFileHint(cwd, framework) {
     ...GENERIC_WIDGET_FILES
   ];
   for (const candidate of candidates) {
-    if (existsSync10(path9.join(cwd, candidate))) {
+    if (existsSync11(path9.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -3087,7 +3968,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."
         )
       )
     );
@@ -3227,13 +4108,16 @@ async function login(config, onPrompt, deps = {}) {
   return waitForApproval(config, started.pending, deps);
 }
 
+// src/map-command.ts
+import { writeFileSync as writeFileSync8 } from "fs";
+
 // 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;
@@ -3505,7 +4389,7 @@ function npmPackageOf(spec) {
 
 // src/map/sources.ts
 import { readFileSync as readFileSync8, readdirSync as readdirSync5, realpathSync, statSync as statSync3 } from "fs";
-import { join as join12, relative as relative2, isAbsolute } from "path";
+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"];
@@ -3589,7 +4473,7 @@ function hasEntrySignal(text) {
 }
 function detectFramework(cwd) {
   try {
-    const pkg = JSON.parse(readFileSync8(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";
@@ -3601,11 +4485,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";
@@ -3634,7 +4518,30 @@ var SKIP_DIRS2 = /* @__PURE__ */ new Set([
   "temp",
   "__pycache__"
 ]);
-function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ new Set(), stats = { discovered: 0, unwalked: 0 }) {
+var SKIP_IS_DEFINITIONAL = /* @__PURE__ */ new Set(["node_modules", ".git"]);
+var PROBE_BUDGET = 4096;
+function probeForSource(dir, budget) {
+  let entries;
+  try {
+    entries = readdirSync5(dir, { withFileTypes: true });
+  } catch {
+    return "unknown";
+  }
+  const dirs = [];
+  for (const e of entries) {
+    if (budget.left-- <= 0) return "unknown";
+    if (e.isDirectory()) {
+      if (!SKIP_IS_DEFINITIONAL.has(e.name)) dirs.push(join13(dir, e.name));
+    } else if (isSourceFile(e.name)) return true;
+    else if (e.isSymbolicLink()) return "unknown";
+  }
+  for (const sub of dirs) {
+    const found = probeForSource(sub, budget);
+    if (found !== false) return found;
+  }
+  return false;
+}
+function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ new Set(), stats = { discovered: 0, unwalked: 0, skippedWithSource: [], skippedUnknown: 0 }, probeBudget = { left: PROBE_BUDGET }) {
   let key;
   try {
     key = realpathSync(dir);
@@ -3657,9 +4564,18 @@ 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);
-    if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats);
+    if (SKIP_DIRS2.has(e.name) || e.name.startsWith(".") && e.name !== ".") {
+      const probeable = !SKIP_IS_DEFINITIONAL.has(e.name);
+      if (probeable && !e.isDirectory() && e.isSymbolicLink()) stats.skippedUnknown++;
+      else if (probeable && e.isDirectory()) {
+        const held = probeForSource(join13(dir, e.name), probeBudget);
+        if (held === true) stats.skippedWithSource.push(join13(dir, e.name));
+        else if (held === "unknown") stats.skippedUnknown++;
+      }
+      continue;
+    }
+    const full = join13(dir, e.name);
+    if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
     else if (e.isSymbolicLink()) {
       let st, real;
       try {
@@ -3673,7 +4589,7 @@ function collectSources(dir, boundary, opts, out = [], seen = /* @__PURE__ */ ne
         if (st.isDirectory() || isSourceFile(e.name)) stats.unwalked++;
         continue;
       }
-      if (st.isDirectory()) collectSources(full, boundary, opts, out, seen, stats);
+      if (st.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
       else if (st.isFile() && isSourceFile(e.name)) {
         out.push(full);
         stats.discovered++;
@@ -3728,7 +4644,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 });
@@ -3738,7 +4654,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 {
@@ -3757,7 +4673,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 {
@@ -3773,7 +4689,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 {
@@ -3787,7 +4703,7 @@ function holdsSourceFile(dir) {
 
 // src/map/surface.ts
 import { readFileSync as readFileSync9 } from "fs";
-import { join as join13 } from "path";
+import { join as join14 } from "path";
 var STATIC_GENERATORS = [
   { dep: "vite", label: "vite" },
   { dep: "react-scripts", label: "create-react-app" },
@@ -3825,7 +4741,7 @@ var SHAPE_SIGNAL = {
 };
 function readManifest(cwd) {
   try {
-    const parsed = JSON.parse(readFileSync9(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;
@@ -3838,7 +4754,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 = readFileSync9(join13(cwd, file), "utf8");
+      text = readFileSync9(join14(cwd, file), "utf8");
     } catch {
       continue;
     }
@@ -4239,7 +5155,7 @@ function dedupeSinks(sinks, owner) {
 
 // src/map/module-graph.ts
 import { readFileSync as readFileSync10, realpathSync as realpathSync2, statSync as statSync4 } from "fs";
-import { dirname as dirname4, join as join14, relative as relative3, resolve as resolvePath } from "path";
+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();
@@ -4307,7 +5223,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);
@@ -4317,7 +5233,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;
@@ -4498,7 +5414,7 @@ function zodShape(node, ts) {
   }
   return shape;
 }
-var REQ_SOURCES = ["body", "query", "params"];
+var REQ_SOURCES = ["body", "query", "params", "headers", "cookies", "files"];
 function requestMemberAccesses(params, body, ts, opts = {}) {
   if (!body) return [];
   const out = /* @__PURE__ */ new Map();
@@ -4535,6 +5451,12 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
     if (ts.isPropertyAccessExpression(n) && isReqSourceExpr(n.expression)) {
       record(n.name.text, sourceOfExpr(n.expression));
     }
+    if (ts.isElementAccessExpression(n) && isReqSourceExpr(n.expression) && n.argumentExpression && ts.isStringLiteral(n.argumentExpression)) {
+      record(n.argumentExpression.text, sourceOfExpr(n.expression));
+    }
+    if (ts.isCallExpression(n) && ts.isPropertyAccessExpression(n.expression) && n.expression.name.text === "get" && isReqSourceExpr(n.expression.expression) && n.arguments.length === 1 && n.arguments[0] && ts.isStringLiteral(n.arguments[0])) {
+      record(n.arguments[0].text, sourceOfExpr(n.expression.expression));
+    }
     if (ts.isVariableDeclaration(n) && n.initializer) {
       const init = unwrap(n.initializer);
       if (ts.isIdentifier(n.name) && isBodyReadCall(n.initializer)) sourceNames.set(n.name.text, bodyReadSource(n.initializer));
@@ -4559,9 +5481,8 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
   function sourceOfExpr(e) {
     if (isPayloadExpr(e)) return "server-fn-data";
     if (ts.isPropertyAccessExpression(e)) {
-      if (e.name.text === "query") return "query";
-      if (e.name.text === "params") return "route-param";
-      if (e.name.text === "body") return "body";
+      const named = namespaceSource(e.name.text);
+      if (REQ_SOURCES.includes(e.name.text)) return named;
     }
     if (ts.isIdentifier(e)) {
       const recorded = sourceNames.get(e.text);
@@ -4572,6 +5493,9 @@ function requestMemberAccesses(params, body, ts, opts = {}) {
   function namespaceSource(key) {
     if (key === "query") return "query";
     if (key === "params") return "route-param";
+    if (key === "headers") return "header";
+    if (key === "cookies") return "cookie";
+    if (key === "files") return "file";
     return "body";
   }
   function bodyReadSource(init) {
@@ -4586,6 +5510,9 @@ function spaceOfKey(key) {
   if (key === "params") return "route-param";
   if (key === "body") return "post";
   if (key === "data" || key === "input" || key === "payload") return "post";
+  if (key === "headers") return "server";
+  if (key === "cookies") return "cookie";
+  if (key === "files") return "files";
   return void 0;
 }
 function linkedFlows(body, params, inputs, sinks, ts) {
@@ -4990,7 +5917,7 @@ function handlerEntry(name, kindLabel, params, body, ts, localSinks, bindings, c
 
 // src/map/imports.ts
 import { readFileSync as readFileSync11 } from "fs";
-import { join as join15 } from "path";
+import { join as join16 } from "path";
 var MAX_SITES = 5;
 var NPM_NAME = /^(?:@[^/@\s~][^/@\s]*\/)?[^/@\s.~][^/@\s]*$/;
 function isNpmPackageName(pkg) {
@@ -5001,7 +5928,7 @@ function readPathAliases(cwd) {
   for (const name of ["tsconfig.json", "jsconfig.json"]) {
     let paths;
     try {
-      const raw = readFileSync11(join15(cwd, name), "utf8");
+      const raw = readFileSync11(join16(cwd, name), "utf8");
       const parsed = JSON.parse(stripJsonComments(raw));
       paths = parsed.compilerOptions?.paths;
     } catch {
@@ -5365,7 +6292,7 @@ async function extractInputMap(cwd, ts, options = {}) {
   } catch {
   }
   const graph = createModuleGraph(ts, { cwd, boundary, followOutside: options.followSymlinks });
-  const stats = { discovered: 0, unwalked: 0 };
+  const stats = { discovered: 0, unwalked: 0, skippedWithSource: [], skippedUnknown: 0 };
   const files = collectSources(cwd, boundary, { followOutside: options.followSymlinks }, [], /* @__PURE__ */ new Set(), stats);
   const imports = createImportInventory(readPathAliases(cwd));
   const invocations = createInvocationInventory();
@@ -5470,19 +6397,31 @@ async function extractInputMap(cwd, ts, options = {}) {
   if (endpoints.length === 0) notes.push("No recognized server-side entry points found under the analyzed roots.");
   const importList = imports.list();
   const unmodelled = importList.filter((d) => d.recognizedSinkKinds.length === 0).length;
+  const skippedDirsWithSource = stats.skippedWithSource.map((d) => relative4(cwd, d));
   const importCoverageGaps = {
     unreadableFiles: failed.length,
     unscannableFiles: importScanFailures,
     unwalkedPaths: stats.unwalked,
-    unresolvableImports
+    unresolvableImports,
+    // A directory skipped by NAME that turned out to hold source. It moved no other counter, so before
+    // this an app whose server lived under `vendor/` was indistinguishable from one with no such
+    // directory — and the inventory still claimed to be complete.
+    skippedDirsWithSource,
+    skippedDirsUnsettled: stats.skippedUnknown
   };
-  const environmentalGaps = failed.length + importScanFailures + stats.unwalked;
+  const environmentalGaps = failed.length + importScanFailures + stats.unwalked + stats.skippedWithSource.length + stats.skippedUnknown;
   const importsComplete = environmentalGaps === 0 && unresolvableImports === 0;
   notes.push("`imports` lists every package the app imports, from ALL source files \u2014 not only files holding an entry point. Absence of a SINK for a package is never evidence; absence of the PACKAGE is evidence only when coverage.importsComplete is true.");
   notes.push(`${unmodelled} of ${importList.length} imported package(s) have no recognized sink family (recognizedSinkKinds: []). The extractor models a small set of API families, so for those packages it cannot tell whether input reaches them: a vulnerability in one must stay "needs review" and can never be closed as unreachable using this map.`);
   if (environmentalGaps > 0) {
     notes.push(`The import inventory is INCOMPLETE: ${failed.length} file(s) could not be read, ${importScanFailures} could not be scanned, and ${stats.unwalked} path(s) could not be walked at all (unreadable directory, broken link, or a symlink leaving the project). A package may therefore be imported without appearing in \`imports\`. Do not read a package's absence as "not imported" while coverage.importsComplete is false.`);
   }
+  if (stats.skippedWithSource.length > 0) {
+    notes.push(`${stats.skippedWithSource.length} director(ies) skipped by name hold source that was NOT analyzed: ${skippedDirsWithSource.slice(0, 10).join(", ")}${skippedDirsWithSource.length > 10 ? ", \u2026" : ""}. The walk excludes these names because they are usually generated or vendored, which is a guess about where app source lives \u2014 and here the guess was wrong. Code in them can import, and serve, anything. Point the scan at the directory, or move the app source out of it, before reading any package's absence as evidence.`);
+  }
+  if (stats.skippedUnknown > 0) {
+    notes.push(`${stats.skippedUnknown} skipped director(ies) could not be settled either way \u2014 the probe for source hit its budget or the directory could not be read. Counted against completeness deliberately: "we stopped looking" is not the same answer as "nothing there".`);
+  }
   if (unresolvableImports > 0) {
     notes.push(`The import inventory is INCOMPLETE for a reason no re-run can fix: ${unresolvableImports} import(s) do not name a resolvable module \u2014 either the specifier is computed at runtime (\`require(REGISTRY[kind])\`) or the loader itself was aliased (\`const r = require\`), so which package is loaded is not knowable from the source. Those imports appear NOWHERE in \`imports\` \u2014 not as an unresolved entry, simply absent \u2014 so a package's absence is not evidence of it being unused. This is a property of the application's code, not a scan failure. Reported conservatively: an aliased loader counts even if every call through it uses a literal.`);
   }
@@ -5565,8 +6504,88 @@ async function buildInputMap(cwd, options = {}) {
   return { map };
 }
 
+// src/flags.ts
+function getStringFlag(flags, name) {
+  const value = flags.get(name);
+  return typeof value === "string" ? value : void 0;
+}
+
+// src/map-command.ts
+async function runMap(flags) {
+  const cwd = getStringFlag(flags, "dir") ?? process.cwd();
+  const { map, error } = await buildInputMap(cwd, {
+    followSymlinks: flags.get("follow-symlinks") === true
+  });
+  if (!map) {
+    console.error(`patchstack: ${error}`);
+    return 1;
+  }
+  const inputs = map.endpoints.reduce((n, e) => n + e.inputs.length, 0);
+  const sinks = map.endpoints.reduce((n, e) => n + e.sinks.length, 0);
+  const proven = map.endpoints.reduce((n, e) => n + e.flows.filter((f) => isProvenFlow(f.confidence)).length, 0);
+  const c = map.coverage;
+  console.error(
+    `patchstack: ${map.endpoints.length} entry point(s), ${inputs} input(s), ${sinks} sink(s), ${proven} proven input\u2192sink flow(s) [${map.framework}].`
+  );
+  console.error(
+    // All three buckets, explicitly: "6/66 parsed" reads as "91% unanalysed" when the other 60 files
+    // simply contain no server entry point (most of a project is client code). Only `skipped` is a
+    // failure to analyse.
+    `patchstack: ${c.filesDiscovered} file(s) found \u2014 ${c.filesParsed} analysed, ${c.filesPreFiltered} skipped (no server entry point)` + (c.filesSkipped ? `, ${c.filesSkipped} could not be analysed` : "") + `. DETECTED surface only \u2014 static analysis is best-effort; every flow carries the tier it was established at ("exact-local" and "transformed-local" are proven; "imported", "heuristic" and "unknown" are not).`
+  );
+  const invoked = map.apiInvocations ?? [];
+  if (invoked.length > 0) {
+    const c2 = map.coverage;
+    const dependency = c2.callsDependency ?? 0;
+    const ambiguous = c2.callsAmbiguous ?? 0;
+    const denominator = dependency + ambiguous;
+    const quality = denominator > 0 ? Math.round(100 * dependency / denominator) : 100;
+    console.error(
+      `patchstack: ${invoked.length} dependency API call(s) resolved across ${new Set(invoked.map((i) => i.package)).size} package(s) from ${c2.callsTotal ?? 0} call site(s) \u2014 ${quality}% of dependency-candidate receivers resolved (${c2.callsLocal ?? 0} local, ${ambiguous} ambiguous). Positive evidence only: absence here never means an API is not called.`
+    );
+  }
+  const imported = map.imports ?? [];
+  if (imported.length > 0) {
+    const unmodelled = imported.filter((d) => d.recognizedSinkKinds.length === 0).length;
+    console.error(
+      `patchstack: ${imported.length} package(s) imported \u2014 ${unmodelled} with no recognized sink family, so a vulnerability in those cannot be judged reachable or unreachable from this map.`
+    );
+  }
+  const json = JSON.stringify(map, null, 2);
+  const out = getStringFlag(flags, "out");
+  if (out) {
+    writeFileSync8(out, json);
+    console.error(`patchstack: wrote ${out}`);
+  } else if (flags.get("upload") !== true) {
+    console.log(json);
+  }
+  if (flags.get("upload") === true) {
+    if (map.endpoints.length === 0) {
+      console.error(
+        "patchstack: no server entry points were recognized \u2014 uploading the import inventory and coverage notes anyway, so a vulnerability can still be judged imported or not. Nothing here can decide whether a request reaches it."
+      );
+    }
+    const config = await resolveConfig({
+      cwd,
+      cliSiteUuid: getStringFlag(flags, "site-uuid"),
+      cliEndpoint: getStringFlag(flags, "endpoint")
+    });
+    const outcome = await postInputMap(config, map);
+    if (outcome.result === "stored") {
+      console.error(`patchstack: uploaded the attack surface (revision ${outcome.revision}).`);
+    } else if (outcome.result === "unchanged") {
+      console.error(`patchstack: attack surface unchanged since revision ${outcome.revision} \u2014 nothing to store.`);
+    } else if (outcome.result === "skipped") {
+      console.error(`patchstack: did not upload the attack surface \u2014 ${outcome.message}`);
+    } else {
+      console.error(`patchstack: could not upload the attack surface \u2014 ${outcome.message}`);
+    }
+  }
+  return 0;
+}
+
 // src/setup.ts
-import { readFileSync as readFileSync13, writeFileSync as writeFileSync8 } from "fs";
+import { readFileSync as readFileSync13, writeFileSync as writeFileSync9 } from "fs";
 import path11 from "path";
 var SCAN_COMMAND = "patchstack-connect scan";
 var MARK_BUILD_COMMAND = "patchstack-connect mark-build";
@@ -5635,7 +6654,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" : "";
-  writeFileSync8(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
+  writeFileSync9(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
   if (build === void 0 || build.trim().length === 0) {
     return {
       changed: true,
@@ -5714,7 +6733,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
@@ -5734,6 +6755,11 @@ Options (for scan, setup, status, and uninstall):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
   --dry-run               (scan only) Show the payload without posting
+  --install-paths         (scan only) Also send where each package is installed
+                          in the dependency tree (node_modules/lodash, and the
+                          same under a workspace that pins its own copy), so an
+                          advisory can be matched to the copy your code actually
+                          loads. Off by default; never source file paths
 
 Options (for mark-build):
   --dir <path>            Build output directory (default: auto-detect
@@ -5755,7 +6781,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
@@ -5797,10 +6824,6 @@ function parseArgs(argv) {
     flags
   };
 }
-function getStringFlag(flags, name) {
-  const value = flags.get(name);
-  return typeof value === "string" ? value : void 0;
-}
 async function runInit(args) {
   const uuid = args.positional[0];
   if (!uuid) {
@@ -5828,8 +6851,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;
@@ -5841,7 +6869,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."}
 `);
@@ -5860,7 +6888,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(`
@@ -5887,83 +6915,12 @@ 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."}
 `);
   return 1;
 }
-async function runMap(args) {
-  const cwd = getStringFlag(args.flags, "dir") ?? process.cwd();
-  const { map, error } = await buildInputMap(cwd, {
-    followSymlinks: args.flags.get("follow-symlinks") === true
-  });
-  if (!map) {
-    console.error(`patchstack: ${error}`);
-    return 1;
-  }
-  const inputs = map.endpoints.reduce((n, e) => n + e.inputs.length, 0);
-  const sinks = map.endpoints.reduce((n, e) => n + e.sinks.length, 0);
-  const proven = map.endpoints.reduce((n, e) => n + e.flows.filter((f) => isProvenFlow(f.confidence)).length, 0);
-  const c = map.coverage;
-  console.error(
-    `patchstack: ${map.endpoints.length} entry point(s), ${inputs} input(s), ${sinks} sink(s), ${proven} proven input\u2192sink flow(s) [${map.framework}].`
-  );
-  console.error(
-    // All three buckets, explicitly: "6/66 parsed" reads as "91% unanalysed" when the other 60 files
-    // simply contain no server entry point (most of a project is client code). Only `skipped` is a
-    // failure to analyse.
-    `patchstack: ${c.filesDiscovered} file(s) found \u2014 ${c.filesParsed} analysed, ${c.filesPreFiltered} skipped (no server entry point)` + (c.filesSkipped ? `, ${c.filesSkipped} could not be analysed` : "") + `. DETECTED surface only \u2014 static analysis is best-effort; every flow carries the tier it was established at ("exact-local" and "transformed-local" are proven; "imported", "heuristic" and "unknown" are not).`
-  );
-  const invoked = map.apiInvocations ?? [];
-  if (invoked.length > 0) {
-    const c2 = map.coverage;
-    const dependency = c2.callsDependency ?? 0;
-    const ambiguous = c2.callsAmbiguous ?? 0;
-    const denominator = dependency + ambiguous;
-    const quality = denominator > 0 ? Math.round(100 * dependency / denominator) : 100;
-    console.error(
-      `patchstack: ${invoked.length} dependency API call(s) resolved across ${new Set(invoked.map((i) => i.package)).size} package(s) from ${c2.callsTotal ?? 0} call site(s) \u2014 ${quality}% of dependency-candidate receivers resolved (${c2.callsLocal ?? 0} local, ${ambiguous} ambiguous). Positive evidence only: absence here never means an API is not called.`
-    );
-  }
-  const imported = map.imports ?? [];
-  if (imported.length > 0) {
-    const unmodelled = imported.filter((d) => d.recognizedSinkKinds.length === 0).length;
-    console.error(
-      `patchstack: ${imported.length} package(s) imported \u2014 ${unmodelled} with no recognized sink family, so a vulnerability in those cannot be judged reachable or unreachable from this map.`
-    );
-  }
-  const json = JSON.stringify(map, null, 2);
-  const out = getStringFlag(args.flags, "out");
-  if (out) {
-    writeFileSync9(out, json);
-    console.error(`patchstack: wrote ${out}`);
-  } else if (args.flags.get("upload") !== true) {
-    console.log(json);
-  }
-  if (args.flags.get("upload") === true) {
-    if (map.endpoints.length === 0) {
-      console.error("patchstack: nothing to upload \u2014 no server entry points were detected.");
-      return 0;
-    }
-    const config = await resolveConfig({
-      cwd,
-      cliSiteUuid: getStringFlag(args.flags, "site-uuid"),
-      cliEndpoint: getStringFlag(args.flags, "endpoint")
-    });
-    const outcome = await postInputMap(config, map);
-    if (outcome.result === "stored") {
-      console.error(`patchstack: uploaded the attack surface (revision ${outcome.revision}).`);
-    } else if (outcome.result === "unchanged") {
-      console.error(`patchstack: attack surface unchanged since revision ${outcome.revision} \u2014 nothing to store.`);
-    } else if (outcome.result === "skipped") {
-      console.error(`patchstack: did not upload the attack surface \u2014 ${outcome.message}`);
-    } else {
-      console.error(`patchstack: could not upload the attack surface \u2014 ${outcome.message}`);
-    }
-  }
-  return 0;
-}
 async function runScan(args, options = {}) {
   const dryRun = args.flags.get("dry-run") === true;
   const config = await resolveConfig({
@@ -5975,10 +6932,17 @@ async function runScan(args, options = {}) {
   for (const warning of manifest.warnings ?? []) {
     console.warn(`patchstack: ${warning}`);
   }
-  const { payload, stats } = buildWirePayload(manifest);
+  const installPaths = args.flags.get("install-paths") === true;
+  const { payload, stats } = buildWirePayload(manifest, { installPaths });
   console.log(
     `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names (${manifest.ecosystem} ecosystem).`
   );
+  if (installPaths) {
+    const located = payload.packages.filter((pkg) => pkg.paths !== void 0).length;
+    console.log(
+      payload.installPathsComplete ? `Including each package's install location in the dependency tree (--install-paths), for all ${located}.` : `Including install locations (--install-paths), for ${located} of ${payload.packages.length} \u2014 this lockfile format does not record them for the rest, which will be reported as "not recorded" rather than "not installed there".`
+    );
+  }
   console.log(
     `Reporting under the ${config.environment} environment (override with PATCHSTACK_ENVIRONMENT).`
   );
@@ -6022,8 +6986,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}).`);
@@ -6134,9 +7107,14 @@ async function runProtectCommand(args) {
     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;
@@ -6457,7 +7435,7 @@ async function runMarkBuild(args) {
       after = ensured.html;
     }
     if (after !== before) {
-      writeFileSync9(file, after);
+      writeFileSync10(file, after);
       marked += 1;
     }
   }
@@ -6495,7 +7473,7 @@ async function main() {
     case "setup":
       return runSetup(args);
     case "map":
-      return runMap(args);
+      return runMap(args.flags);
     case "login":
       return runLogin(args);
     default: