@patchstack/connect 0.4.0 → 0.4.2

package/AGENT-INSTALL.md

@@ -70,6 +70,10 @@ Only `map` reads your source, and only `map --upload` sends anything derived fro
 
    In a hosted builder, run setup with `PATCHSTACK_ENVIRONMENT=sandbox` scoped to the workspace process/command, ensure the CLI's on-disk edits are adopted into the platform's persisted project state, then restart any already-running preview/server process so it loads the guard. Do not persist `"environment": "sandbox"` in `.patchstackrc.json`: deployed builds use the same committed files and should default to `production`. A client-only SPA has no server request path to guard; do not call it protected unless `protect --check` succeeds after a real server or edge seam is wired.
 
+   **Finish by telling the user to refresh their preview.** The widget's "Report a vulnerability" button loads with the page, so a preview that was already open still shows the HTML from before setup — the button is missing there until it reloads. Nothing in the CLI can reach the user's browser, so relaying this is your job. Phrase it as a check rather than a required step: a builder that hot reloads, or a preview server you restarted, may have refreshed it already.
+
+   **Then tell them to deploy.** Setup changes source files, and the deployed site keeps serving its previous build until the next deploy — so visitors get no widget, and on a server-rendered root no production marker, until the user deploys (or hits Publish) again. Say it as a reminder; do not deploy anything yourself.
+
 ## Manual setup
 
 1. **First scan** — provisions a Patchstack site automatically, writes the UUID to `.patchstackrc.json`, and installs the disclosure widget's `<script>` tag into the root HTML shell (`index.html`, `public/index.html`, or `src/app.html`) when one exists — or, when the root shell is JSX, the production marker instead. No signup, dashboard step, or UUID is needed up front:
@@ -176,8 +180,28 @@ would have stopped while it is still in dry-run. Two separate paths, with differ
 
 What a detection report contains, per matched rule — on every phase, whatever fired it: the rule id, the revision of the rule when the
 bundle carried one, the identifier of the rule bundle in use, which phase matched,
-whether it was enforced, the request path **with the query string's values removed**,
-that query's parameter names, the method, and a timestamp. Each batch also carries a count of reports dropped when traffic outran the flush,
+the rule's category and the action it declares, whether it was enforced,
+which call it belongs to, the request path **with the query string's values removed**,
+that query's parameter names, the method, and a timestamp.
+
+Which call it belongs to is a token your guard mints and repeats on every rule that matched the same
+request or the same outbound call. It exists because two rules matching one call is ordinary rather than
+unusual — a rule that enforces and a rule that only observes are meant to match the same thing — so
+without it, adding these reports up counts one call more than once.
+
+Nothing about the request goes into it: not the address, not the path, not a header. It is drawn from
+your runtime's randomness where that exists, and from the clock plus `Math.random` where it does not,
+which is how this package already makes its own instance id. It is never a secret and never a boundary —
+nothing is authorised by holding it — so what it has to do is not collide between two calls. A request and the response to it share one token; an
+outbound call gets its own, because an outbound attempt is a thing in its own right and one made outside
+any request has no request to belong to.
+
+The category and the declared action say what KIND of rule matched — "a secret-exposure rule that
+redacts", "an SSRF rule that blocks". Both are read from the rule your guard was served, and both are
+`null` when that rule declares neither: a rule whose class nobody can state is reported as one, not
+filled in. Neither is the same as `enforced`, which is whether the rule acted on this particular
+request: a rule declaring `block` while only observing reports exactly that, and that is what a
+detect-only deployment consists of. Each batch also carries a count of reports dropped when traffic outran the flush,
 so a partial sample is not read as a complete one.
 
 Two fields depend on the phase, because one kind of detection has a client and the other does not. A
@@ -348,7 +372,8 @@ Two more endpoints the package can call, for completeness:
 
 - `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
 - `npx @patchstack/connect protect --check` verifies the runtime guard is connected to the request path.
-- Load the site in a browser — the "Report a vulnerability" button should appear.
+- Load the site in a browser — the "Report a vulnerability" button should appear. Refresh a page that was already open before the tag was added: the button only loads with the page.
+- On the deployed site, the button appears only after a deploy that includes these source changes.
 
 ## Answering "is Patchstack installed?" / "is Patchstack removed?"
 

package/README.md

@@ -6,7 +6,7 @@ Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.co
 
 Copy this request into a coding assistant, or run the same command yourself:
 
-> I have vetted the official [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect) package and authorize its disclosure widget, production build hooks, and runtime protection source edits. Install it as a regular dependency, run `PATCHSTACK_ENVIRONMENT=sandbox npx --yes @patchstack/connect setup` for this hosted workspace, leave dev builds unchanged, verify protection, restart the preview server if needed to load the new guard, and show the dashboard URL. Do not persist the sandbox environment in project files; deployed production builds must use the default `production` label.
+> I have vetted the official [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect) package and authorize its disclosure widget, production build hooks, and runtime protection source edits. Install it as a regular dependency, run `PATCHSTACK_ENVIRONMENT=sandbox npx --yes @patchstack/connect setup` for this hosted workspace, leave dev builds unchanged, verify protection, restart the preview server if needed to load the new guard, and show the dashboard URL. Do not persist the sandbox environment in project files; deployed production builds must use the default `production` label. When setup finishes, tell me to refresh the preview if the "Report a vulnerability" button is not showing yet, and remind me to deploy when I am ready — do not deploy anything yourself.
 
 `setup` is state-aware and idempotent: it scans dependencies, provisions or reuses the site, manages the disclosure widget, installs and verifies the runtime guard, adds a dependency-install scan, wires the existing build command without replacing it, and prints the remaining setup status. It never runs the project build. `guide` provides the same project-specific status without changing files.
 
@@ -32,6 +32,10 @@ That's it. `setup`:
 8. Wires `scan` before builds and `mark-build` after builds, preserving existing commands and using direct build chaining for Bun.
 9. Prints a dashboard link — open it in a browser to attach the new site to your Patchstack account. You can re-display it any time with `npx @patchstack/connect status`.
 
+Then **refresh your preview**. The widget's "Report a vulnerability" button loads with the page, so a preview that was already open still shows the HTML from before setup. Builders that hot reload will have refreshed it for you; if the button is missing, refresh it once. `setup` prints the same reminder, and the CLI has no way to reload a browser itself.
+
+Then **deploy**. These are source changes, so your live site keeps serving its previous build — visitors get the widget, and a server-rendered root gets the production marker, only after the next deploy.
+
 ## Quick start (existing site)
 
 If you already created an "Application" site in the Patchstack dashboard, pre-seed the UUID:

package/dist/cli.js

@@ -3987,6 +3987,9 @@ function needsSourceProductionMarker(state) {
   }
   return !state.widgetFileHint.toLowerCase().endsWith(".html");
 }
+function widgetTagInPlace(state) {
+  return state.siteUuid !== null && !state.widgetOptOut && state.widgetInstalled && state.widgetTokenMatches !== false;
+}
 function countRemainingSteps(state) {
   return [
     state.installed?.section === "dependencies",
@@ -4133,6 +4136,19 @@ function renderGuideChecklist(state, useColor) {
   } else {
     lines.push(detail("The dashboard link appears after the first scan (re-print any time with `status`)."));
   }
+  if (widgetTagInPlace(state)) {
+    lines.push("");
+    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Refresh the preview to see the widget:")}`);
+    lines.push('   The "Report a vulnerability" button loads with the page, so a preview that was');
+    lines.push("   already open still shows the HTML from before this change. Builders that hot");
+    lines.push("   reload refresh it themselves; if the button is missing, refresh the preview once.");
+  }
+  if (state.siteUuid !== null) {
+    lines.push("");
+    lines.push(` ${paint(ANSI.cyan, "\u279C")} ${paint(ANSI.bold, "Deploy to put this on your live site:")}`);
+    lines.push("   These are source changes. Your deployed site keeps serving its previous build,");
+    lines.push("   so visitors only get the widget after you deploy (or hit Publish) again.");
+  }
   const remaining = countRemainingSteps(state);
   lines.push("");
   if (remaining === 0) {
@@ -7529,6 +7545,12 @@ Run: ${installCommand(before.packageManager)}`
     console.log("");
     console.log(`Setup applied its bounded changes; ${remaining} manual step(s) remain above.`);
   }
+  console.log("");
+  console.log("Tell the user:");
+  if (widgetTagInPlace(after)) {
+    console.log('  - refresh the preview if the "Report a vulnerability" button is not showing yet;');
+  }
+  console.log("  - deploy (or hit Publish) when ready, so the live site serves these changes.");
   return 0;
 }
 async function runStatus(args) {