@patchstack/connect 0.2.7 → 0.2.9

package/README.md

@@ -17,9 +17,11 @@ npm install --save-dev @patchstack/connect
 npx @patchstack/connect scan
 ```
 
+> **Use your project's own package manager.** On bun-managed projects (Lovable, Bolt, most vibe-coding platforms) install with `bun add -d @patchstack/connect` instead — running `npm install` there plants a `package-lock.json` that the platform's native dependency flow never updates again, leaving a stale lockfile next to the live one. The connector detects and works around that (see *Stale lockfiles* below), but not creating the fossil is better.
+
 That's it. The first `scan`:
 
-1. Reads your `package-lock.json`.
+1. Reads your lockfile (see *Supported lockfiles*).
 2. POSTs the package list to Patchstack with **no** UUID.
 3. Patchstack provisions a fresh site and returns its UUID.
 4. The connector writes the UUID to `.patchstackrc.json` so the next `scan` targets the same site.
@@ -123,6 +125,10 @@ That's the entire payload. No source code, no environment variables, no file pat
 
 If both a Bun lockfile and `node_modules/` are present, the connector walks `node_modules/` to enumerate the installed packages. Run `bun install` (or `npm install`) before scanning so the directory is populated.
 
+### Stale lockfiles
+
+Every scanned source is validated against `package.json`: if the chosen lockfile is missing dependencies that `package.json` declares, it is treated as a fossil (e.g. a `package-lock.json` created by a one-off `npm install` in a bun-managed project) and the connector falls through to the next source — ultimately walking `node_modules/`, the installed truth — and prints a warning naming the stale file. Delete the stale lockfile to silence the warning. Without this, the manifest and the build fingerprint would silently freeze while the real dependency set drifts.
+
 ## Development
 
 ```bash
@@ -132,6 +138,22 @@ npm test
 npm run build
 ```
 
+### Manifest endpoint testing
+
+To post the current lockfile manifest to a local Patchstack API endpoint and provision a new site:
+
+```bash
+bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest
+```
+
+The response should include the new site UUID. To re-test an existing site, pass that UUID explicitly:
+
+```bash
+bun run test:manifest -- --endpoint http://localhost:8000/monitor/pulse/manifest --site-uuid YOUR_REAL_UUID
+```
+
+Use `--dry-run` to preview the payload without posting.
+
 ## Release process
 
 Pull requests run typecheck, tests, build, package verification, and a production dependency audit in GitHub Actions.

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync, writeFileSync } from "fs";
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
-import path4 from "path";
+import path5 from "path";
 
 // src/types.ts
 var PatchstackError = class extends Error {
@@ -19,13 +19,52 @@ var PatchstackError = class extends Error {
   cause;
 };
 
-// src/parsers/npm.ts
+// src/parsers/consistency.ts
 import { readFile } from "fs/promises";
 import path from "path";
+async function readDeclaredDependencyNames(cwd) {
+  let raw;
+  try {
+    raw = await readFile(path.join(cwd, "package.json"), "utf8");
+  } catch {
+    return [];
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return [];
+  }
+  const names = /* @__PURE__ */ new Set();
+  for (const group of ["dependencies", "devDependencies"]) {
+    const deps = parsed[group];
+    if (typeof deps !== "object" || deps === null) {
+      continue;
+    }
+    for (const [name, spec] of Object.entries(deps)) {
+      if (typeof spec === "string" && /^(file|link|workspace|portal):/.test(spec)) {
+        continue;
+      }
+      names.add(name);
+    }
+  }
+  return [...names];
+}
+function missingDependencies(declared, packages) {
+  const present = new Set(packages.map((entry) => entry.name));
+  return declared.filter((name) => !present.has(name));
+}
+
+// src/parsers/npm.ts
+import { readFile as readFile2 } from "fs/promises";
+import path2 from "path";
 async function parseNpmLockfile(lockfilePath) {
   let raw;
   try {
-    raw = await readFile(lockfilePath, "utf8");
+    raw = await readFile2(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(`Could not read lockfile at ${lockfilePath}`, "LOCKFILE_NOT_FOUND", cause);
   }
@@ -83,7 +122,7 @@ function extractFromV1(deps, acc = [], depth = 0) {
   return acc;
 }
 function extractNameFromPath(pkgPath) {
-  const segments = pkgPath.split("node_modules" + path.sep === pkgPath ? path.sep : "/");
+  const segments = pkgPath.split("node_modules" + path2.sep === pkgPath ? path2.sep : "/");
   const parts = pkgPath.split("/");
   const nmIndex = parts.lastIndexOf("node_modules");
   if (nmIndex === -1 || nmIndex >= parts.length - 1) {
@@ -106,10 +145,10 @@ function isDirectV2(pkgPath) {
 }
 
 // src/parsers/node_modules.ts
-import { lstat, readFile as readFile2, readdir, stat } from "fs/promises";
-import path2 from "path";
+import { lstat, readFile as readFile3, readdir, stat } from "fs/promises";
+import path3 from "path";
 async function walkNodeModules(cwd) {
-  const root = path2.join(cwd, "node_modules");
+  const root = path3.join(cwd, "node_modules");
   try {
     const info = await stat(root);
     if (!info.isDirectory()) {
@@ -143,7 +182,7 @@ async function walk(dir, acc, depth) {
     if (name.startsWith(".")) {
       continue;
     }
-    const fullPath = path2.join(dir, name);
+    const fullPath = path3.join(dir, name);
     if (!await isPlainDirectory(fullPath)) {
       continue;
     }
@@ -158,7 +197,7 @@ async function walk(dir, acc, depth) {
         if (sub.startsWith(".")) {
           continue;
         }
-        const scopedDir = path2.join(fullPath, sub);
+        const scopedDir = path3.join(fullPath, sub);
         if (!await isPlainDirectory(scopedDir)) {
           continue;
         }
@@ -174,7 +213,7 @@ async function walk(dir, acc, depth) {
 async function readPackage(pkgDir, depth, acc) {
   let raw;
   try {
-    raw = await readFile2(path2.join(pkgDir, "package.json"), "utf8");
+    raw = await readFile3(path3.join(pkgDir, "package.json"), "utf8");
   } catch {
     return;
   }
@@ -197,7 +236,7 @@ async function readPackage(pkgDir, depth, acc) {
   });
 }
 async function walkNested(pkgDir, acc, depth) {
-  const nested = path2.join(pkgDir, "node_modules");
+  const nested = path3.join(pkgDir, "node_modules");
   if (!await isPlainDirectory(nested)) {
     return;
   }
@@ -213,11 +252,11 @@ async function isPlainDirectory(dir) {
 }
 
 // src/parsers/pnpm.ts
-import { readFile as readFile3 } from "fs/promises";
+import { readFile as readFile4 } from "fs/promises";
 async function parsePnpmLockfile(lockfilePath) {
   let raw;
   try {
-    raw = await readFile3(lockfilePath, "utf8");
+    raw = await readFile4(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -465,12 +504,12 @@ function extractLeafName(trimmed) {
 }
 
 // src/parsers/yarn.ts
-import { readFile as readFile4 } from "fs/promises";
-import path3 from "path";
+import { readFile as readFile5 } from "fs/promises";
+import path4 from "path";
 async function parseYarnLockfile(lockfilePath) {
   let raw;
   try {
-    raw = await readFile4(lockfilePath, "utf8");
+    raw = await readFile5(lockfilePath, "utf8");
   } catch (cause) {
     throw new PatchstackError(
       `Could not read lockfile at ${lockfilePath}`,
@@ -485,7 +524,7 @@ async function parseYarnLockfile(lockfilePath) {
       "LOCKFILE_PARSE_ERROR"
     );
   }
-  const directNames = await readDirectDepNames(path3.dirname(lockfilePath));
+  const directNames = await readDirectDepNames(path4.dirname(lockfilePath));
   const entries = [];
   const seen = /* @__PURE__ */ new Set();
   for (const block of blocks) {
@@ -629,7 +668,7 @@ async function readDirectDepNames(cwd) {
   const names = /* @__PURE__ */ new Set();
   let raw;
   try {
-    raw = await readFile4(path3.join(cwd, "package.json"), "utf8");
+    raw = await readFile5(path4.join(cwd, "package.json"), "utf8");
   } catch {
     return names;
   }
@@ -666,7 +705,7 @@ var LOCKFILE_CANDIDATES = [
 async function detectLockfile(cwd) {
   const probed = await Promise.all(
     LOCKFILE_CANDIDATES.map(async (candidate) => {
-      const filePath = path4.join(cwd, candidate.filename);
+      const filePath = path5.join(cwd, candidate.filename);
       return { ...candidate, filePath, present: await exists(filePath) };
     })
   );
@@ -686,9 +725,69 @@ async function detectLockfile(cwd) {
   );
 }
 async function scanLockfile(cwd) {
-  const detected = await detectLockfile(cwd);
-  const packages = await runStrategy(detected, cwd);
-  return { ecosystem: detected.ecosystem, packages };
+  const candidates = await presentLockfiles(cwd);
+  if (candidates.length === 0) {
+    await detectLockfile(cwd);
+  }
+  const declared = await readDeclaredDependencyNames(cwd);
+  const warnings = [];
+  let firstParsed = null;
+  let walkTried = false;
+  for (const candidate of candidates) {
+    let packages;
+    try {
+      packages = await runStrategy(candidate, cwd);
+    } catch {
+      continue;
+    }
+    walkTried ||= candidate.strategy === "node-modules-walk";
+    firstParsed ??= { packages, filename: candidate.filename };
+    const missing = missingDependencies(declared, packages);
+    if (missing.length === 0) {
+      return manifestWith(packages, warnings);
+    }
+    warnings.push(staleWarning(candidate.filename, missing));
+  }
+  if (!walkTried) {
+    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);
+    } catch {
+    }
+  }
+  if (firstParsed === null) {
+    const expected = LOCKFILE_CANDIDATES.map((candidate) => candidate.filename).join(", ");
+    throw new PatchstackError(
+      `No readable lockfile found in ${cwd}. Expected one of: ${expected}.`,
+      "LOCKFILE_NOT_FOUND"
+    );
+  }
+  warnings.push(
+    `No fully-consistent source found; reporting ${firstParsed.filename}. The manifest may understate the real dependency set.`
+  );
+  return manifestWith(firstParsed.packages, warnings);
+}
+function manifestWith(packages, warnings) {
+  return warnings.length > 0 ? { ecosystem: "npm", packages, warnings } : { ecosystem: "npm", packages };
+}
+function staleWarning(source, missing) {
+  const sample = missing.slice(0, 3).join(", ");
+  const suffix = missing.length > 3 ? `, +${missing.length - 3} more` : "";
+  return `${source} looks stale: package.json declares ${missing.length} dependenc${missing.length === 1 ? "y" : "ies"} it does not contain (${sample}${suffix}).`;
+}
+async function presentLockfiles(cwd) {
+  const probed = await Promise.all(
+    LOCKFILE_CANDIDATES.map(async (candidate) => {
+      const filePath = path5.join(cwd, candidate.filename);
+      return { ...candidate, filePath, present: await exists(filePath) };
+    })
+  );
+  return probed.filter((candidate) => candidate.present).map(({ filename, strategy, filePath }) => ({ ecosystem: "npm", filename, strategy, filePath }));
 }
 async function runStrategy(detected, cwd) {
   switch (detected.strategy) {
@@ -906,8 +1005,8 @@ function isTimeoutError(cause) {
 }
 
 // src/config.ts
-import { readFile as readFile5, writeFile } from "fs/promises";
-import path5 from "path";
+import { readFile as readFile6, writeFile } from "fs/promises";
+import path6 from "path";
 var CONFIG_FILENAME = ".patchstackrc.json";
 var DEFAULT_ENVIRONMENT = "production";
 async function resolveConfig(options) {
@@ -944,7 +1043,7 @@ async function resolveConfig(options) {
   };
 }
 async function writeConfigFile(cwd, config) {
-  const target = path5.join(cwd, CONFIG_FILENAME);
+  const target = path6.join(cwd, CONFIG_FILENAME);
   const content = JSON.stringify(config, null, 2) + "\n";
   await writeFile(target, content, "utf8");
   return target;
@@ -954,10 +1053,10 @@ async function persistSiteUuid(cwd, siteUuid) {
   return writeConfigFile(cwd, { ...existing, siteUuid });
 }
 async function readConfigFile(cwd) {
-  const target = path5.join(cwd, CONFIG_FILENAME);
+  const target = path6.join(cwd, CONFIG_FILENAME);
   let raw;
   try {
-    raw = await readFile5(target, "utf8");
+    raw = await readFile6(target, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       return {};
@@ -1008,16 +1107,16 @@ function isEnvironment(value) {
 
 // src/mark-build.ts
 import { existsSync, readdirSync, statSync } from "fs";
-import path6 from "path";
+import path7 from "path";
 var MARKER_ATTR = "data-patchstack-build";
 var BUILD_DIR_CANDIDATES = ["dist", "build", "out", ".output/public"];
 function resolveBuildDir(cwd, override) {
   if (override !== void 0 && override !== "") {
-    const abs = path6.resolve(cwd, override);
+    const abs = path7.resolve(cwd, override);
     return existsSync(abs) && statSync(abs).isDirectory() ? abs : null;
   }
   for (const candidate of BUILD_DIR_CANDIDATES) {
-    const abs = path6.resolve(cwd, candidate);
+    const abs = path7.resolve(cwd, candidate);
     if (existsSync(abs) && statSync(abs).isDirectory()) {
       return abs;
     }
@@ -1028,7 +1127,7 @@ function findHtmlFiles(dir) {
   const out = [];
   const walk2 = (current) => {
     for (const entry of readdirSync(current, { withFileTypes: true })) {
-      const full = path6.join(current, entry.name);
+      const full = path7.join(current, entry.name);
       if (entry.isDirectory()) {
         walk2(full);
       } else if (entry.isFile() && entry.name.toLowerCase().endsWith(".html")) {
@@ -1060,6 +1159,151 @@ function injectMarker(html, snippet) {
   return stripped + snippet;
 }
 
+// src/protect/install.ts
+import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync, copyFileSync } from "fs";
+import { join } from "path";
+import { fileURLToPath } from "url";
+var TEMPLATES = fileURLToPath(new URL("./protect/templates/", import.meta.url));
+var CLIENT_TUNNEL = [
+  "",
+  "    // PATCHSTACK auto-guard: in the browser, tunnel Supabase traffic through the app's own",
+  "    // server guard (same-origin) so payloads are inspected before they reach Supabase.",
+  "    if (typeof window !== 'undefined') {",
+  "      const target = typeof input === 'string' ? input : input instanceof Request ? input.url : String(input);",
+  "      const method = init?.method ?? (input instanceof Request ? input.method : 'GET');",
+  "      headers.set('x-ps-target', target);",
+  "      const guardUrl = new URL('/_patchstack/guard', window.location.origin).toString();",
+  "      return fetch(guardUrl, { ...init, method, headers });",
+  "    }",
+  ""
+].join("\n");
+var START_IMPORTS = [
+  'import { getRequest } from "@tanstack/react-start/server";',
+  'import { GUARD_PATH, handleGuardRequest } from "@/integrations/patchstack/guard";'
+].join("\n");
+var START_MIDDLEWARE = [
+  "",
+  "// Patchstack auto-guard: intercept the tunneled data traffic before anything else runs.",
+  "const patchstackGuard = createMiddleware().server(async ({ next }) => {",
+  "  const request = getRequest();",
+  "  if (request) {",
+  "    const { pathname } = new URL(request.url);",
+  "    if (pathname === GUARD_PATH) return handleGuardRequest(request);",
+  "  }",
+  "  return next();",
+  "});",
+  ""
+].join("\n");
+var PS_DIR_REL = "src/integrations/patchstack";
+function log(msg) {
+  console.log(`patchstack protect: ${msg}`);
+}
+function detectSupportedStack(cwd) {
+  const pkgPath = join(cwd, "package.json");
+  if (!existsSync2(pkgPath)) return false;
+  const pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  return Boolean(deps["@tanstack/react-start"]) && existsSync2(join(cwd, "src/start.ts")) && existsSync2(join(cwd, "src/integrations/supabase/client.ts"));
+}
+function generateManifest(cwd) {
+  const pkg = JSON.parse(readFileSync(join(cwd, "package.json"), "utf8"));
+  const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+  const packages = {};
+  for (const name of Object.keys(deps)) {
+    let version = String(deps[name]).replace(/^[^\d]*/, "");
+    const installed = join(cwd, "node_modules", name, "package.json");
+    if (existsSync2(installed)) {
+      try {
+        version = JSON.parse(readFileSync(installed, "utf8")).version;
+      } catch {
+      }
+    }
+    packages[name] = version;
+  }
+  mkdirSync(join(cwd, PS_DIR_REL), { recursive: true });
+  const body = "// Patchstack auto-guard manifest \u2014 generated from the lockfile.\n// Do not edit; regenerated by `patchstack-connect protect --manifest` (wired into prebuild).\nexport const manifest = " + JSON.stringify({ packages }, null, 2) + ";\n";
+  writeFileSync(join(cwd, PS_DIR_REL, "manifest.js"), body);
+  log(`wrote manifest.js (${Object.keys(packages).length} packages)`);
+}
+function scaffold(cwd) {
+  const dst = join(cwd, PS_DIR_REL);
+  mkdirSync(dst, { recursive: true });
+  copyFileSync(join(TEMPLATES, "engine.js"), join(dst, "engine.js"));
+  copyFileSync(join(TEMPLATES, "engine.d.ts"), join(dst, "engine.d.ts"));
+  copyFileSync(join(TEMPLATES, "manifest.d.ts"), join(dst, "manifest.d.ts"));
+  copyFileSync(join(TEMPLATES, "rules.json"), join(dst, "rules.json"));
+  copyFileSync(join(TEMPLATES, "guard.ts"), join(dst, "guard.ts"));
+  log("scaffolded engine.js (+types), rules.json, guard.ts");
+}
+function patchClient(cwd) {
+  const p = join(cwd, "src/integrations/supabase/client.ts");
+  let s = readFileSync(p, "utf8");
+  if (s.includes("x-ps-target")) {
+    log("client.ts already wired");
+    return;
+  }
+  const anchor = "headers.set('apikey', supabaseKey);";
+  if (!s.includes(anchor)) {
+    log("client.ts anchor not found (template changed?) \u2014 skipping client patch");
+    return;
+  }
+  s = s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL);
+  writeFileSync(p, s);
+  log("patched client.ts (tunnel Supabase through the guard)");
+}
+function patchStart(cwd) {
+  const p = join(cwd, "src/start.ts");
+  let s = readFileSync(p, "utf8");
+  if (s.includes("patchstackGuard")) {
+    log("start.ts already wired");
+    return;
+  }
+  const importAnchor = 'import { createStart, createMiddleware } from "@tanstack/react-start";';
+  const exportAnchor = "export const startInstance";
+  const rmAnchor = "requestMiddleware: [";
+  if (!s.includes(importAnchor) || !s.includes(exportAnchor) || !s.includes(rmAnchor)) {
+    log("start.ts anchors not found (template changed?) \u2014 skipping start patch");
+    return;
+  }
+  s = s.replace(importAnchor, importAnchor + "\n" + START_IMPORTS);
+  s = s.replace(exportAnchor, START_MIDDLEWARE + "\n" + exportAnchor);
+  s = s.replace(rmAnchor, rmAnchor + "patchstackGuard, ");
+  writeFileSync(p, s);
+  log("patched start.ts (registered the guard as request middleware)");
+}
+function wirePrebuild(cwd) {
+  const p = join(cwd, "package.json");
+  const pkg = JSON.parse(readFileSync(p, "utf8"));
+  pkg.scripts = pkg.scripts || {};
+  const step = "patchstack-connect protect --manifest";
+  const prebuild = pkg.scripts.prebuild || "";
+  if (prebuild.includes(step)) {
+    log("prebuild already refreshes the manifest");
+    return;
+  }
+  pkg.scripts.prebuild = prebuild ? prebuild + " && " + step : step;
+  writeFileSync(p, JSON.stringify(pkg, null, 2) + "\n");
+  log("wired manifest refresh into prebuild");
+}
+function runProtect(cwd, opts = {}) {
+  if (opts.manifestOnly) {
+    generateManifest(cwd);
+    return;
+  }
+  if (!detectSupportedStack(cwd)) {
+    log(
+      "runtime protection currently supports TanStack Start + Supabase apps; stack not detected \u2014 skipping."
+    );
+    return;
+  }
+  scaffold(cwd);
+  patchClient(cwd);
+  patchStart(cwd);
+  generateManifest(cwd);
+  wirePrebuild(cwd);
+  log("done \u2014 guard wired. Set PATCHSTACK_MODE=block to enforce (default dry-run).");
+}
+
 // src/cli.ts
 var HELP = `@patchstack/connect \u2014 scan your lockfile and report packages to Patchstack.
 
@@ -1072,6 +1316,9 @@ Usage:
   patchstack-connect status [options]                Show current configuration
   patchstack-connect mark-build [options]            Stamp built HTML with a production flag +
                                                      build fingerprint (run as a postbuild step)
+  patchstack-connect protect [--manifest]            Install runtime protection (the guard) into
+                                                     a server-side JS app. --manifest only
+                                                     regenerates the package manifest (prebuild).
   patchstack-connect help                            Print this message
 
 Options (for scan and status):
@@ -1157,6 +1404,9 @@ async function runScan(args) {
     cliEndpoint: getStringFlag(args.flags, "endpoint")
   });
   const manifest = await scanLockfile(process.cwd());
+  for (const warning of manifest.warnings ?? []) {
+    console.warn(`patchstack: ${warning}`);
+  }
   const { payload, stats } = buildWirePayload(manifest);
   console.log(
     `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names in ${manifest.ecosystem} lockfile.`
@@ -1206,6 +1456,14 @@ async function runScan(args) {
   }
   return 0;
 }
+async function runProtectCommand(args) {
+  try {
+    runProtect(process.cwd(), { manifestOnly: args.flags.get("manifest") === true });
+  } catch (err) {
+    console.warn(`patchstack protect: skipped (${err.message}).`);
+  }
+  return 0;
+}
 async function runStatus(args) {
   const config = await resolveConfig({
     cwd: process.cwd(),
@@ -1226,6 +1484,9 @@ async function runMarkBuild(args) {
   let checksum = null;
   try {
     const manifest = await scanLockfile(cwd);
+    for (const warning of manifest.warnings ?? []) {
+      console.warn(`mark-build: ${warning}`);
+    }
     const { payload } = buildWirePayload(manifest);
     checksum = computeManifestChecksum(payload.packages);
   } catch (err) {
@@ -1248,10 +1509,10 @@ async function runMarkBuild(args) {
   const snippet = buildInjectionSnippet(checksum);
   let marked = 0;
   for (const file of files) {
-    const before = readFileSync(file, "utf8");
+    const before = readFileSync2(file, "utf8");
     const after = injectMarker(before, snippet);
     if (after !== before) {
-      writeFileSync(file, after);
+      writeFileSync2(file, after);
       marked += 1;
     }
   }
@@ -1275,6 +1536,8 @@ async function main() {
       return runStatus(args);
     case "mark-build":
       return runMarkBuild(args);
+    case "protect":
+      return runProtectCommand(args);
     default:
       console.error(`Unknown command: ${args.command}
 `);