@patchstack/connect 0.3.3 → 0.3.5

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -1250,15 +1250,339 @@ function injectMarker(html, snippet) {
   return stripped + snippet;
 }
 
+// src/guide.ts
+import { existsSync as existsSync2, readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import path8 from "path";
+var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
+var WIDGET_NEEDLE = "patchstack-widget";
+var INSTALL_COMMANDS = {
+  npm: "npm install --save-dev @patchstack/connect",
+  pnpm: "pnpm add -D @patchstack/connect",
+  yarn: "yarn add -D @patchstack/connect",
+  bun: "bun add -d @patchstack/connect"
+};
+var PM_BY_LOCKFILE = [
+  { filename: "package-lock.json", pm: "npm" },
+  { filename: "bun.lock", pm: "bun" },
+  { filename: "bun.lockb", pm: "bun" },
+  { filename: "pnpm-lock.yaml", pm: "pnpm" },
+  { filename: "yarn.lock", pm: "yarn" }
+];
+var WIDGET_FILE_CANDIDATES = {
+  next: [
+    "app/layout.tsx",
+    "app/layout.jsx",
+    "src/app/layout.tsx",
+    "src/app/layout.jsx",
+    "pages/_document.tsx",
+    "pages/_document.jsx",
+    "src/pages/_document.tsx"
+  ],
+  nuxt: ["app.vue", "src/app.vue", "app/app.vue"],
+  remix: ["app/root.tsx", "app/root.jsx"],
+  "react-router": ["app/root.tsx", "src/root.tsx"],
+  "tanstack-start": ["src/routes/__root.tsx", "app/routes/__root.tsx"],
+  sveltekit: ["src/app.html"],
+  astro: ["src/layouts/Layout.astro"],
+  gatsby: ["src/html.js"]
+};
+var GENERIC_WIDGET_FILES = ["index.html", "public/index.html"];
+var SKIPPED_DIRS = /* @__PURE__ */ new Set([
+  "node_modules",
+  ".git",
+  "dist",
+  "build",
+  "out",
+  ".output",
+  ".next",
+  ".nuxt",
+  ".svelte-kit",
+  ".vercel",
+  ".netlify",
+  "coverage",
+  "vendor"
+]);
+var WIDGET_EXTENSIONS = /* @__PURE__ */ new Set([
+  ".html",
+  ".htm",
+  ".tsx",
+  ".jsx",
+  ".ts",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".vue",
+  ".svelte",
+  ".astro",
+  ".ejs",
+  ".hbs"
+]);
+var WIDGET_SCAN_MAX_FILES = 4e3;
+var WIDGET_SCAN_MAX_DEPTH = 6;
+var WIDGET_SCAN_MAX_BYTES = 512 * 1024;
+function detectPackageManager(cwd) {
+  for (const { filename, pm } of PM_BY_LOCKFILE) {
+    if (existsSync2(path8.join(cwd, filename))) {
+      return pm;
+    }
+  }
+  return "npm";
+}
+function installCommand(pm) {
+  return INSTALL_COMMANDS[pm];
+}
+function readPackageJson(cwd) {
+  try {
+    return JSON.parse(readFileSync(path8.join(cwd, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+function installedVersion(cwd, declaredRange) {
+  try {
+    const pkg = JSON.parse(
+      readFileSync(path8.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
+    );
+    if (typeof pkg.version === "string" && pkg.version.length > 0) {
+      return pkg.version;
+    }
+  } catch {
+  }
+  return declaredRange;
+}
+function findWidgetMarker(cwd, siteUuid) {
+  let budget = WIDGET_SCAN_MAX_FILES;
+  let sawWidget = false;
+  let sawTokenMatch = false;
+  const settled = () => sawTokenMatch || sawWidget && siteUuid == null;
+  const walk2 = (dir, depth) => {
+    if (depth > WIDGET_SCAN_MAX_DEPTH || budget <= 0) {
+      return;
+    }
+    let entries;
+    try {
+      entries = readdirSync2(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (budget <= 0 || settled()) {
+        return;
+      }
+      const full = path8.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (SKIPPED_DIRS.has(entry.name) || entry.name.startsWith(".")) {
+          continue;
+        }
+        walk2(full, depth + 1);
+        continue;
+      }
+      if (!entry.isFile() || !WIDGET_EXTENSIONS.has(path8.extname(entry.name).toLowerCase())) {
+        continue;
+      }
+      budget -= 1;
+      try {
+        if (statSync2(full).size > WIDGET_SCAN_MAX_BYTES) {
+          continue;
+        }
+        const content = readFileSync(full, "utf8");
+        if (!content.includes(WIDGET_NEEDLE)) {
+          continue;
+        }
+        sawWidget = true;
+        if (siteUuid != null && content.includes(siteUuid)) {
+          sawTokenMatch = true;
+        }
+      } catch {
+      }
+    }
+  };
+  walk2(cwd, 0);
+  return {
+    found: sawWidget,
+    uuidMatches: sawWidget && siteUuid != null ? sawTokenMatch : null
+  };
+}
+function resolveWidgetFileHint(cwd, framework) {
+  const candidates = [
+    ...framework !== null ? WIDGET_FILE_CANDIDATES[framework] ?? [] : [],
+    ...GENERIC_WIDGET_FILES
+  ];
+  for (const candidate of candidates) {
+    if (existsSync2(path8.join(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+async function collectGuideState(cwd) {
+  const pkg = readPackageJson(cwd);
+  const packageManager = detectPackageManager(cwd);
+  let installed = null;
+  if (pkg?.devDependencies?.["@patchstack/connect"] !== void 0) {
+    installed = {
+      version: installedVersion(cwd, pkg.devDependencies["@patchstack/connect"]),
+      section: "devDependencies"
+    };
+  } else if (pkg?.dependencies?.["@patchstack/connect"] !== void 0) {
+    installed = {
+      version: installedVersion(cwd, pkg.dependencies["@patchstack/connect"]),
+      section: "dependencies"
+    };
+  }
+  let siteUuid = null;
+  let claimUrl = null;
+  let endpointOverride = null;
+  try {
+    const config = await resolveConfig({ cwd });
+    siteUuid = config.siteUuid;
+    if (siteUuid !== null) {
+      claimUrl = buildClaimUrl(config.endpoint, siteUuid);
+    }
+    if (config.endpoint !== DEFAULT_ENDPOINT) {
+      endpointOverride = config.endpoint;
+    }
+  } catch {
+  }
+  const declaredNames = Object.keys({ ...pkg?.dependencies, ...pkg?.devDependencies });
+  const stack = detectStack(
+    declaredNames.map((name) => ({ name, version: "" })),
+    {}
+  );
+  const widget = findWidgetMarker(cwd, siteUuid);
+  return {
+    projectName: pkg?.name ?? null,
+    hasPackageJson: pkg !== null,
+    packageManager,
+    installed,
+    siteUuid,
+    claimUrl,
+    endpointOverride,
+    prebuildWired: (pkg?.scripts?.prebuild ?? "").includes("patchstack-connect scan"),
+    postbuildWired: (pkg?.scripts?.postbuild ?? "").includes("patchstack-connect mark-build"),
+    widgetInstalled: widget.found,
+    widgetTokenMatches: widget.uuidMatches,
+    framework: stack.framework,
+    widgetFileHint: resolveWidgetFileHint(cwd, stack.framework)
+  };
+}
+var ANSI = {
+  reset: "\x1B[0m",
+  bold: "\x1B[1m",
+  dim: "\x1B[2m",
+  green: "\x1B[32m",
+  yellow: "\x1B[33m",
+  cyan: "\x1B[36m"
+};
+function renderGuideChecklist(state, useColor) {
+  const paint = (code, text) => useColor ? `${code}${text}${ANSI.reset}` : text;
+  const done = (text) => ` ${paint(ANSI.green, "\u2714")} ${text}`;
+  const todo = (text) => ` ${paint(ANSI.yellow, "\u2716")} ${paint(ANSI.bold, text)}`;
+  const detail = (text) => `     ${paint(ANSI.dim, text)}`;
+  const lines = [];
+  const headerParts = [state.framework, state.packageManager].filter(
+    (part) => part !== null
+  );
+  const name = state.projectName ?? path8.basename(process.cwd());
+  lines.push(paint(ANSI.bold, `Patchstack setup status \u2014 ${name} (${headerParts.join(" \xB7 ")})`));
+  if (state.endpointOverride !== null) {
+    lines.push(
+      detail(
+        `endpoint override in effect: ${state.endpointOverride} (set via .patchstackrc.json, PATCHSTACK_ENDPOINT, or --endpoint)`
+      )
+    );
+  }
+  lines.push("");
+  if (!state.hasPackageJson) {
+    lines.push(todo("No package.json found in this directory."));
+    lines.push(detail("Run the guide from the project root."));
+    return lines.join("\n");
+  }
+  if (state.installed !== null) {
+    lines.push(done(`@patchstack/connect installed (${state.installed.version}, ${state.installed.section})`));
+  } else {
+    lines.push(todo("Install @patchstack/connect as a dev dependency"));
+    lines.push(detail(`\u2192 ${installCommand(state.packageManager)}`));
+    if (state.packageManager === "bun") {
+      lines.push(detail(`(if bun isn't available here, ${INSTALL_COMMANDS.npm} works too)`));
+    }
+  }
+  if (state.siteUuid !== null) {
+    lines.push(done(`Site provisioned (${state.siteUuid})`));
+  } else {
+    lines.push(todo("Provision the site \u2014 run the first scan"));
+    lines.push(detail("\u2192 npx @patchstack/connect scan"));
+    lines.push(detail("Reads the lockfile, registers the project, writes .patchstackrc.json,"));
+    lines.push(detail("and prints a claim URL \u2014 show that URL to the user; never open it yourself."));
+  }
+  if (state.prebuildWired && state.postbuildWired) {
+    lines.push(done("Build hooks wired (prebuild scan, postbuild mark-build)"));
+  } else {
+    lines.push(todo("Wire builds \u2014 add to package.json scripts (chain with && if a hook exists)"));
+    if (!state.prebuildWired) {
+      lines.push(detail('\u2192 "prebuild": "patchstack-connect scan"'));
+    }
+    if (!state.postbuildWired) {
+      lines.push(detail('\u2192 "postbuild": "patchstack-connect mark-build"'));
+    }
+  }
+  const widgetOk = state.widgetInstalled && state.widgetTokenMatches !== false;
+  if (widgetOk) {
+    lines.push(done("Disclosure widget installed"));
+  } else if (state.widgetInstalled) {
+    lines.push(todo("Disclosure widget found, but its userToken doesn't match this project's site UUID"));
+    lines.push(detail(`\u2192 a wrong userToken makes the widget silently no-op; set it to '${state.siteUuid}'`));
+  } else {
+    lines.push(todo('Add the "Report a vulnerability" widget'));
+    const placement = state.widgetFileHint !== null ? `\u2192 add to ${state.widgetFileHint} (via the framework's HTML/layout mechanism):` : "\u2192 add via the framework's HTML/layout mechanism (never a JS entry point):";
+    lines.push(detail(placement));
+    lines.push(detail(`  <script src="${WIDGET_SCRIPT_URL}"></script>`));
+    const token = state.siteUuid ?? "<SITE_UUID from .patchstackrc.json \u2014 run scan first>";
+    lines.push(detail(`  <script>PatchstackWidget.init({ userToken: '${token}' });</script>`));
+    lines.push(detail("The userToken is public by design \u2014 it ships in client-side HTML."));
+  }
+  lines.push("");
+  if (state.claimUrl !== null) {
+    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Claim the site (free, opens the dashboard):")}`);
+    lines.push(`   ${paint(ANSI.cyan, state.claimUrl)}`);
+    lines.push(detail("Open in a browser. AI agents: show this URL to the user verbatim."));
+    if (state.endpointOverride !== null) {
+      lines.push(detail("(this URL inherits the endpoint override above)"));
+    }
+  } else {
+    lines.push(detail("The claim URL appears after the first scan (re-print any time with `status`)."));
+  }
+  const remaining = [
+    state.installed !== null,
+    state.siteUuid !== null,
+    state.prebuildWired && state.postbuildWired,
+    widgetOk
+  ].filter((step) => !step).length;
+  lines.push("");
+  lines.push(
+    remaining === 0 ? done(
+      paint(
+        ANSI.bold,
+        "All setup steps complete. Commit .patchstackrc.json, package.json, and the file carrying the widget snippet."
+      )
+    ) : ` ${paint(ANSI.yellow, String(remaining))} step(s) remaining \u2014 details in the reference guide below.`
+  );
+  return lines.join("\n");
+}
+
 // src/protect/install.ts
-import { readFileSync, writeFileSync, existsSync as existsSync2, mkdirSync, copyFileSync } from "fs";
-import { join } from "path";
+import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3, mkdirSync, copyFileSync } from "fs";
+import { join, dirname } from "path";
 import { fileURLToPath } from "url";
-var TEMPLATES = fileURLToPath(new URL("./protect/templates/", import.meta.url));
+var TEMPLATES = join(dirname(fileURLToPath(import.meta.url)), "protect", "templates");
+var APP = process.cwd();
+var PS_DIR = join(APP, "src/integrations/patchstack");
+var read = (p) => readFileSync2(p, "utf8");
+var log = (msg) => console.log(`patchstack protect: ${msg}`);
 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.",
+  "    // PATCHSTACK: 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');",
@@ -1270,11 +1594,11 @@ var CLIENT_TUNNEL = [
 ].join("\n");
 var START_IMPORTS = [
   'import { getRequest } from "@tanstack/react-start/server";',
-  'import { GUARD_PATH, handleGuardRequest } from "@/integrations/patchstack/guard";'
+  'import { GUARD_PATH, handleGuardRequest, inspectServerFn } from "@/integrations/patchstack/guard";'
 ].join("\n");
-var START_MIDDLEWARE = [
+var REQUEST_MIDDLEWARE_DEF = [
   "",
-  "// Patchstack auto-guard: intercept the tunneled data traffic before anything else runs.",
+  "// Patchstack guard (browser tunnel): intercept tunneled Supabase traffic before anything else.",
   "const patchstackGuard = createMiddleware().server(async ({ next }) => {",
   "  const request = getRequest();",
   "  if (request) {",
@@ -1285,113 +1609,87 @@ var START_MIDDLEWARE = [
   "});",
   ""
 ].join("\n");
-var PS_DIR_REL = "src/integrations/patchstack";
-function log(msg) {
-  console.log(`patchstack protect: ${msg}`);
-}
+var FUNCTION_MIDDLEWARE_DEF = [
+  "",
+  "// Patchstack guard (server functions): inspect server-fn args before they reach the database,",
+  "// covering apps that mutate via TanStack server functions (which bypass the browser tunnel).",
+  'const patchstackFunctionGuard = createMiddleware({ type: "function" }).server(async ({ next, data }) => {',
+  "  const blocked = await inspectServerFn(data);",
+  "  if (blocked) throw new Error(blocked.message);",
+  "  return next();",
+  "});",
+  ""
+].join("\n");
 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"));
+  if (!existsSync3(pkgPath)) return false;
+  const pkg = JSON.parse(read(pkgPath));
   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)`);
+  return Boolean(deps["@tanstack/react-start"]) && existsSync3(join(cwd, "src/start.ts")) && existsSync3(join(cwd, "src/integrations/supabase/client.ts"));
 }
 function scaffold(cwd) {
-  const dst = join(cwd, PS_DIR_REL);
+  const dst = join(cwd, "src/integrations/patchstack");
   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");
+  copyFileSync(join(TEMPLATES, "rules.json"), join(dst, "rules.json"));
+  log("scaffolded guard.ts + rules.json");
 }
 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;
-  }
+  let s = read(p);
+  if (s.includes("x-ps-target")) return log("client.ts already wired");
   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);
+  if (!s.includes(anchor)) return log("client.ts anchor not found \u2014 skipping (template changed?)");
+  writeFileSync(p, s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL));
   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;
-  }
+  let s = read(p);
   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;
+  if (!s.includes(importAnchor) || !s.includes(exportAnchor)) {
+    return log("start.ts anchors not found \u2014 skipping (template changed?)");
+  }
+  const original = s;
+  if (!s.includes("@/integrations/patchstack/guard")) {
+    s = s.replace(importAnchor, importAnchor + "\n" + START_IMPORTS);
+  } else if (!s.includes("inspectServerFn")) {
+    s = s.replace(
+      'import { GUARD_PATH, handleGuardRequest } from "@/integrations/patchstack/guard";',
+      'import { GUARD_PATH, handleGuardRequest, inspectServerFn } from "@/integrations/patchstack/guard";'
+    );
   }
-  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;
+  if (!s.includes("const patchstackGuard =")) {
+    s = s.replace(exportAnchor, REQUEST_MIDDLEWARE_DEF + "\n" + exportAnchor);
   }
-  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 (!s.includes("const patchstackFunctionGuard =")) {
+    s = s.replace(exportAnchor, FUNCTION_MIDDLEWARE_DEF + "\n" + exportAnchor);
   }
+  if (s.includes(rmAnchor) && !s.includes("requestMiddleware: [patchstackGuard")) {
+    s = s.replace(rmAnchor, rmAnchor + "patchstackGuard, ");
+  }
+  if (!s.includes("functionMiddleware: [patchstackFunctionGuard")) {
+    const fmAnchor = "functionMiddleware: [";
+    if (s.includes(fmAnchor)) {
+      s = s.replace(fmAnchor, fmAnchor + "patchstackFunctionGuard, ");
+    } else if (s.includes(rmAnchor)) {
+      s = s.replace(rmAnchor, "functionMiddleware: [patchstackFunctionGuard],\n    " + rmAnchor);
+    }
+  }
+  if (s === original) return log("start.ts already wired");
+  writeFileSync(p, s);
+  log("patched start.ts (guard registered as request + function middleware)");
+}
+function runProtect(cwd) {
   if (!detectSupportedStack(cwd)) {
-    log(
-      "runtime protection currently supports TanStack Start + Supabase apps; stack not detected \u2014 skipping."
-    );
+    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 and always-on (blocks by default). Set PATCHSTACK_MODE=dry-run for log-only.");
 }
 
@@ -1407,11 +1705,13 @@ 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 guide                           Print the full setup guide for AI coding
-                                                     agents (also at https://patchstack.com/install.txt)
+  patchstack-connect protect                         Install always-on runtime protection (the
+                                                     guard) into a TanStack Start + Supabase app.
+                                                     Covers the browser + server-function paths.
+  patchstack-connect guide                           Show this project's setup status (what's done,
+                                                     what's missing, with tailored commands), then
+                                                     print the full setup guide
+                                                     (also at https://patchstack.com/install.txt)
   patchstack-connect help                            Print this message
 
 Options (for scan and status):
@@ -1502,14 +1802,22 @@ async function runScan(args) {
   }
   const { payload, stats } = buildWirePayload(manifest);
   console.log(
-    `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names in ${manifest.ecosystem} lockfile.`
+    `Found ${payload.packages.length} unique package versions across ${stats.uniqueNames} package names (${manifest.ecosystem} ecosystem).`
+  );
+  console.log(
+    `Reporting under the ${config.environment} environment (override with PATCHSTACK_ENVIRONMENT).`
   );
-  console.log(`Reporting under the ${config.environment} environment.`);
+  if (config.endpoint !== DEFAULT_ENDPOINT) {
+    console.log(
+      `Using endpoint override: ${config.endpoint} (set via --endpoint, PATCHSTACK_ENDPOINT, or .patchstackrc.json).`
+    );
+  }
   if (stats.duplicateNames.length > 0) {
-    console.log(`${stats.duplicateNames.length} package(s) appear at multiple versions:`);
-    if (stats.duplicateNames.length <= 10) {
-      console.log(`  ${stats.duplicateNames.join(", ")}`);
-    }
+    const sample = stats.duplicateNames.slice(0, 10).join(", ");
+    const more = stats.duplicateNames.length > 10 ? `, +${stats.duplicateNames.length - 10} more` : "";
+    console.log(
+      `${stats.duplicateNames.length} package(s) appear at multiple versions: ${sample}${more}`
+    );
   }
   if (dryRun) {
     console.log("");
@@ -1546,20 +1854,32 @@ async function runScan(args) {
     console.log("");
     console.log("Claim this site to view vulnerability reports in your Patchstack dashboard:");
     console.log(`  ${buildClaimUrl(config.endpoint, response.uuid)}`);
+    if (config.endpoint !== DEFAULT_ENDPOINT) {
+      console.log("  (this URL inherits the endpoint override above)");
+    }
   }
   return 0;
 }
-async function runProtectCommand(args) {
+async function runProtectCommand(_args) {
   try {
-    runProtect(process.cwd(), { manifestOnly: args.flags.get("manifest") === true });
+    runProtect(process.cwd());
   } catch (err) {
     console.warn(`patchstack protect: skipped (${err.message}).`);
   }
   return 0;
 }
 async function runGuide() {
+  try {
+    const state = await collectGuideState(process.cwd());
+    const useColor = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+    console.log(renderGuideChecklist(state, useColor));
+    console.log("");
+    console.log("\u2014\u2014\u2014\u2014 Full reference guide (ships as AGENT-INSTALL.md) \u2014\u2014\u2014\u2014");
+    console.log("");
+  } catch {
+  }
   const guidePath = new URL("../AGENT-INSTALL.md", import.meta.url);
-  console.log(readFileSync2(guidePath, "utf8"));
+  console.log(readFileSync3(guidePath, "utf8"));
   return 0;
 }
 async function runStatus(args) {
@@ -1569,7 +1889,9 @@ async function runStatus(args) {
     cliEndpoint: getStringFlag(args.flags, "endpoint")
   });
   console.log(`Site UUID:   ${config.siteUuid ?? "(none yet \u2014 the next `scan` will provision one)"}`);
-  console.log(`Endpoint:    ${config.endpoint}`);
+  console.log(
+    `Endpoint:    ${config.endpoint}${config.endpoint === DEFAULT_ENDPOINT ? "" : " (override)"}`
+  );
   console.log(`Timeout:     ${config.timeoutMs}ms`);
   console.log(`Environment: ${config.environment}`);
   if (config.siteUuid !== null) {
@@ -1618,7 +1940,7 @@ async function runMarkBuild(args) {
   const snippet = buildInjectionSnippet(checksum, stack);
   let marked = 0;
   for (const file of files) {
-    const before = readFileSync2(file, "utf8");
+    const before = readFileSync3(file, "utf8");
     const after = injectMarker(before, snippet);
     if (after !== before) {
       writeFileSync2(file, after);