@patchstack/connect 0.3.30 → 0.3.32

package/dist/cli.js

@@ -1,7 +1,8 @@
 #!/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";
+import { createRequire as createRequire2 } from "module";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -330,7 +331,7 @@ async function walkNodeModules(cwd) {
     seen.set(await realpath(cwd), -1);
   } catch {
   }
-  return dedupeByShallowest(await walk(root, 0, seen));
+  return dedupeByShallowest(await walk(root, 0, seen, cwd));
 }
 function dedupeByShallowest(found) {
   const best = /* @__PURE__ */ new Map();
@@ -341,7 +342,7 @@ function dedupeByShallowest(found) {
   return [...best.values()].map(({ entry }) => entry);
 }
 var CONCURRENCY = 32;
-async function walk(dir, depth, seen) {
+async function walk(dir, depth, seen, root) {
   let names;
   try {
     names = await readdir(dir);
@@ -353,7 +354,7 @@ async function walk(dir, depth, seen) {
     const fullPath = path3.join(dir, name);
     const resolved = await claim(fullPath, seen, depth);
     if (resolved === null) return [];
-    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen);
+    if (PACKAGE_STORE_DIRS.has(name)) return walk(fullPath, depth, seen, root);
     if (name.startsWith("@")) {
       let subNames;
       try {
@@ -366,16 +367,16 @@ async function walk(dir, depth, seen) {
         const scopedDir = path3.join(fullPath, sub);
         const scopedReal = await claim(scopedDir, seen, depth);
         if (scopedReal === null) return [];
-        return packageAndNested(scopedDir, scopedReal, depth, seen);
+        return packageAndNested(scopedDir, scopedReal, depth, seen, root);
       });
       return scoped.flat();
     }
-    return packageAndNested(fullPath, resolved, depth, seen);
+    return packageAndNested(fullPath, resolved, depth, seen, root);
   });
   return perEntry.flat();
 }
-async function packageAndNested(pkgDir, resolved, depth, seen) {
-  const [own, nested] = await Promise.all([readPackage(pkgDir, depth), walkNested(pkgDir, depth, seen)]);
+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) {
@@ -390,7 +391,10 @@ async function mapLimit(items, fn) {
   await Promise.all(workers);
   return results;
 }
-async function readPackage(pkgDir, depth) {
+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 readFile4(path3.join(pkgDir, "package.json"), "utf8");
@@ -409,14 +413,14 @@ async function readPackage(pkgDir, depth) {
   if (typeof parsed.version !== "string" || parsed.version.length === 0) {
     return null;
   }
-  return { 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, depth, seen) {
+async function walkNested(pkgDir, depth, seen, root) {
   const nested = path3.join(pkgDir, "node_modules");
   if (await claim(nested, seen, depth + 1) === null) {
     return [];
   }
-  return walk(nested, depth + 1, seen);
+  return walk(nested, depth + 1, seen, root);
 }
 async function claim(dir, seen, depth) {
   let resolved;
@@ -1059,21 +1063,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);
@@ -1087,7 +1103,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,
@@ -1095,6 +1122,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;
@@ -2053,38 +2084,83 @@ var PROD_MARKER_GLOBAL = "__PATCHSTACK_PROD__";
 var REGION_OPEN = "{/* #region patchstack (managed by patchstack-connect \u2014 do not edit) */}";
 var REGION_CLOSE = "{/* #endregion patchstack */}";
 var REGION_RE = /[ \t]*\{\/\* #region patchstack[\s\S]*?#endregion patchstack \*\/\}\n?/g;
+function findJsxShellAnchor(source, tagName) {
+  const candidates = new RegExp(`^([ \\t]*)<${tagName}(?=[\\s/>])`, "gm");
+  let candidate;
+  while ((candidate = candidates.exec(source)) !== null) {
+    let quote = null;
+    let escaped = false;
+    let braces = 0;
+    let blockComment = false;
+    let lineComment = false;
+    for (let index = candidates.lastIndex; index < source.length; index += 1) {
+      const char = source[index];
+      const next = source[index + 1];
+      if (lineComment) {
+        if (char === "\n") lineComment = false;
+        continue;
+      }
+      if (blockComment) {
+        if (char === "*" && next === "/") {
+          blockComment = false;
+          index += 1;
+        }
+        continue;
+      }
+      if (quote !== null) {
+        if (escaped) {
+          escaped = false;
+        } else if (char === "\\") {
+          escaped = true;
+        } else if (char === quote) {
+          quote = null;
+        }
+        continue;
+      }
+      if (char === "'" || char === '"' || char === "`") {
+        quote = char;
+      } else if (braces > 0 && char === "/" && next === "*") {
+        blockComment = true;
+        index += 1;
+      } else if (braces > 0 && char === "/" && next === "/") {
+        lineComment = true;
+        index += 1;
+      } else if (char === "{") {
+        braces += 1;
+      } else if (char === "}") {
+        if (braces === 0) break;
+        braces -= 1;
+      } else if (char === ">" && braces === 0) {
+        const openingTag = source.slice(candidate.index, index + 1);
+        if (/\/\s*>$/.test(openingTag)) break;
+        return { end: index + 1, indent: candidate[1] ?? "" };
+      }
+    }
+  }
+  return null;
+}
 function ensureMarkerInJsxShell(source, framework) {
   if (!hasJsxShell(framework)) {
     return { source, action: "unsupported" };
   }
   const stripped = source.replace(REGION_RE, "");
   if (stripped.includes(PROD_MARKER_GLOBAL)) {
-    return { source, action: "manual" };
+    return { source: stripped, action: "manual" };
   }
   const block = (indent) => [REGION_OPEN, ...buildSourceMarkerSnippet(framework).split("\n"), REGION_CLOSE].map((line) => `${indent}${line}`).join("\n");
-  const widget = stripped.match(/^([ \t]*).*patchstack-widget.*$/m);
-  if (widget?.index !== void 0) {
-    const indent = widget[1] ?? "";
-    return {
-      source: `${stripped.slice(0, widget.index)}${block(indent)}
-${stripped.slice(widget.index)}`,
-      action: "added"
-    };
-  }
-  for (const anchor of [/^([ \t]*)<head>[ \t]*$/m, /^([ \t]*)<body>[ \t]*$/m]) {
-    const match = stripped.match(anchor);
-    if (match?.index === void 0) {
-      continue;
-    }
-    const end = match.index + match[0].length;
-    const indent = `${match[1] ?? ""}  `;
+  for (const tagName of ["head", "body"]) {
+    const anchor = findJsxShellAnchor(stripped, tagName);
+    if (anchor === null) continue;
+    const indent = `${anchor.indent}  `;
+    const remainder = stripped.slice(anchor.end);
+    const separator = remainder.startsWith("\n") || remainder.startsWith("\r") ? "" : "\n";
     return {
-      source: `${stripped.slice(0, end)}
-${block(indent)}${stripped.slice(end)}`,
+      source: `${stripped.slice(0, anchor.end)}
+${block(indent)}${separator}${remainder}`,
       action: "added"
     };
   }
-  return { source, action: "no-anchor" };
+  return { source: stripped, action: "no-anchor" };
 }
 function ensureSourceMarker(cwd, shell, framework) {
   if (shell === null) {
@@ -2093,7 +2169,7 @@ function ensureSourceMarker(cwd, shell, framework) {
   const file = path7.resolve(cwd, shell);
   const before = readFileSync(file, "utf8");
   const result = ensureMarkerInJsxShell(before, framework);
-  if (result.source !== before && result.action === "added") {
+  if (result.source !== before) {
     writeFileSync(file, result.source);
   }
   return { ...result, shell };
@@ -4078,6 +4154,9 @@ 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";
@@ -4485,7 +4564,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);
@@ -4508,9 +4610,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;
+    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);
+    if (e.isDirectory()) collectSources(full, boundary, opts, out, seen, stats, probeBudget);
     else if (e.isSymbolicLink()) {
       let st, real;
       try {
@@ -4524,7 +4635,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++;
@@ -4847,12 +4958,16 @@ var FS_PACKAGES = ["fs-extra", "graceful-fs", "memfs"];
 var isFsPackage = (pkg) => /^node:fs(\/promises)?$/.test(pkg) || FS_PACKAGES.includes(pkg);
 var EXEC_PACKAGES = ["execa", "cross-spawn", "shelljs", "zx"];
 var isExecPackage = (pkg) => pkg === "node:child_process" || EXEC_PACKAGES.includes(pkg);
+var DESERIALIZE_CALLS = /^unserialize$/;
+var DESERIALIZE_PACKAGES = ["node-serialize"];
+var isDeserializePackage = (pkg) => DESERIALIZE_PACKAGES.includes(pkg);
 function recognizedSinkKinds(pkg) {
   const kinds = [];
   if (isDbPackage(pkg)) kinds.push("db");
   if (isFsPackage(pkg)) kinds.push("fs");
   if (isExecPackage(pkg)) kinds.push("exec");
   if (isHttpPackage(pkg)) kinds.push("http");
+  if (isDeserializePackage(pkg)) kinds.push("eval");
   return kinds;
 }
 function collectLocalSinks(sf, ts, bindings, ctx) {
@@ -4966,6 +5081,9 @@ function directSinks(node, ts, bindings, ctx) {
           if (EXEC_CALLS.test(method) && b.pkg && isExecPackage(b.pkg)) {
             push({ kind: "exec", package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
           }
+          if (DESERIALIZE_CALLS.test(method) && b.pkg && isDeserializePackage(b.pkg)) {
+            push({ kind: "eval", provider: b.root, package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
+          }
           if (HTTP_MEMBER_METHODS.has(method)) {
             if (b.pkg && isHttpPackage(b.pkg)) {
               push({ kind: "http", provider: b.root, package: b.pkg, op: method, attribution: "import", ...spanOf(n) });
@@ -4993,6 +5111,9 @@ function directSinks(node, ts, bindings, ctx) {
           push({ kind: "exec", package: pkg, op: name, attribution: "import", ...spanOf(n) });
         }
         if (name === "eval" && trueGlobal) push({ kind: "eval", op: "eval", attribution: "global", ...spanOf(n) });
+        if (DESERIALIZE_CALLS.test(name) && pkg && isDeserializePackage(pkg)) {
+          push({ kind: "eval", package: pkg, op: name, attribution: "import", ...spanOf(n) });
+        }
       }
     }
     if (ts.isNewExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === "Function" && !bindings.locals.has("Function") && !isShadowedByEnclosingBinding(n, "Function", ts)) {
@@ -5069,6 +5190,7 @@ var CANDIDATE_FAMILIES = {
 };
 function argumentRoleOf(sinkKind, method, index, total = 0) {
   if (sinkKind === "eval" && method === "Function") return index === total - 1 ? "code" : "args";
+  if (sinkKind === "eval" && method === "unserialize") return index === 0 ? "code" : "unknown";
   const table = method ? ARGUMENT_ROLES[sinkKind]?.[method] : void 0;
   return table?.[index] ?? "unknown";
 }
@@ -5349,7 +5471,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();
@@ -5386,6 +5508,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));
@@ -5410,9 +5538,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);
@@ -5423,6 +5550,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) {
@@ -5437,6 +5567,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) {
@@ -6216,7 +6349,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();
@@ -6321,19 +6454,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.`);
   }
@@ -6416,8 +6561,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";
@@ -6486,7 +6711,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,
@@ -6583,10 +6808,19 @@ Usage:
                                                      the old one must be updated. Not usable in CI
   patchstack-connect help                            Print this message
 
+Global:
+  --version               Print the installed version of this package and exit
+  --help                  Print this help and exit
+
 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
@@ -6651,10 +6885,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) {
@@ -6752,77 +6982,6 @@ async function runLogin(args) {
 `);
   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({
@@ -6834,10 +6993,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).`
   );
@@ -7330,7 +7496,7 @@ async function runMarkBuild(args) {
       after = ensured.html;
     }
     if (after !== before) {
-      writeFileSync9(file, after);
+      writeFileSync10(file, after);
       marked += 1;
     }
   }
@@ -7340,8 +7506,21 @@ async function runMarkBuild(args) {
   );
   return 0;
 }
+function packageVersion() {
+  try {
+    const require2 = createRequire2(import.meta.url);
+    const manifest = require2("../package.json");
+    return typeof manifest.version === "string" && manifest.version.length > 0 ? manifest.version : "unknown";
+  } catch {
+    return "unknown";
+  }
+}
 async function main() {
   const args = parseArgs(process.argv);
+  if (args.flags.has("version") || args.command === "version") {
+    console.log(packageVersion());
+    return 0;
+  }
   if (args.flags.has("help") || args.command === "help" || args.command === null) {
     console.log(HELP);
     return 0;
@@ -7368,7 +7547,7 @@ async function main() {
     case "setup":
       return runSetup(args);
     case "map":
-      return runMap(args);
+      return runMap(args.flags);
     case "login":
       return runLogin(args);
     default: