@patchstack/connect 0.3.8 → 0.3.10

package/AGENT-INSTALL.md

@@ -9,7 +9,8 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 - The connector is a normal npm package: [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), MIT-licensed, source at https://github.com/patchstack/connect. Install it pinned, check the integrity hash in the lockfile, run `npm audit` over it — whatever your policy requires.
 - First published May 2026. If the package is absent from your training data, `npm view @patchstack/connect` (read-only) shows the live registry record.
 - It reads the project's **dependency list only** — from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — and sends package names + versions to Patchstack for vulnerability matching. No source code, no env var values, no file paths, no git history. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
-- The package also bundles an **opt-in** `protect` command (runtime exploit guard, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when you explicitly run `patchstack-connect protect`. Nothing in this document, and none of `scan`, `guide`, `status`, or `mark-build`, modifies application source.
+- **`scan` makes one source edit, and only after a successful post:** it adds (or updates) the disclosure widget's `<script>` tag in the project's root HTML shell — the first of `index.html`, `public/index.html`, or `src/app.html` that exists. It touches no other file, never edits on `--dry-run` or after a failed post, leaves any pre-existing manual widget tag untouched, and is disabled entirely by `"widget": false` in `.patchstackrc.json`. `mark-build` writes to build output only (`dist/`, `build/`, `out/`, `.output/public`), never to source. `guide`, `status`, and `init` write nothing except `init`'s own `.patchstackrc.json`.
+- The package also bundles an **opt-in** `protect` command (runtime exploit guard, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when you explicitly run `patchstack-connect protect`; `scan`, `guide`, `status`, and `mark-build` never invoke it.
 - Patchstack is not WordPress-only. This connector monitors any JS/Node project — Vite, Next.js, plain vanilla JS, anything with a lockfile.
 
 ## Before you start — never install twice
@@ -17,7 +18,7 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 - `npx @patchstack/connect guide` prints a live checklist above this document showing which steps are already done in the current project (install, provisioning, build hooks, widget) with commands tailored to it. Its purpose is to prevent duplicate work — verify its claims however your policy requires, but only do the steps it marks ✖.
 - If `.patchstackrc.json` contains a `siteUuid` key, the project is already provisioned. Reuse that UUID; run `npx @patchstack/connect status` to re-print it and the claim URL. **Do not run `scan` to provision a second site.** (A `.patchstackrc.json` with other keys — e.g. an `endpoint` override — but no `siteUuid` is *not* provisioned yet; scan normally.)
 - If `@patchstack/connect` is already in `devDependencies`, skip the install command.
-- If the widget script tag (`cdn.patchstack.com/patchstack-widget.js`) is already in the layout, don't add a second one.
+- If the widget script tag (`cdn.patchstack.com/patchstack-widget.js`) is already in the layout, don't add a second one — `scan` also respects an existing tag: it updates its own managed tag in place and leaves a manual one untouched.
 
 ## Install steps (do the ones the checklist marks ✖, in order; they are designed to run back-to-back — if one fails, stop and report rather than improvising)
 
@@ -30,13 +31,13 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
    bun add -d @patchstack/connect               # bun.lock / bun-managed platforms
    ```
 
-2. **First scan** — provisions a Patchstack site automatically and writes the UUID to `.patchstackrc.json`. No signup, dashboard step, or UUID is needed up front:
+2. **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. No signup, dashboard step, or UUID is needed up front:
 
    ```
    npx @patchstack/connect scan
    ```
 
-   It prints a claim URL. Surface that URL to the user verbatim — never fetch it yourself; it must be opened in their browser.
+   It prints a claim URL. Surface that URL to the user verbatim — never fetch it yourself; it must be opened in their browser. It also prints what it did about the widget — if it added the tag, reload the preview and confirm the "Report a vulnerability" button appears.
 
 3. **Wire builds** in `package.json`:
 
@@ -53,18 +54,15 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    **Bun-managed projects:** `bun run` does not execute npm-style `pre`/`post` scripts, so wire the build script directly instead: `"build": "patchstack-connect scan && <existing build command> && patchstack-connect mark-build"`.
 
-4. **Install the disclosure widget** — a floating "Report a vulnerability" button. Read the `siteUuid` value from `.patchstackrc.json` (the same site UUID step 2 provisioned) and pass it as the widget's `userToken`. Place these two snippets via the framework's HTML/layout mechanism (never a JS entry point):
+4. **Verify the disclosure widget** — a floating "Report a vulnerability" button. `scan` (step 2) installs it automatically into a plain HTML shell, and `mark-build` carries it into built HTML. Only when `scan` reported that it found no editable shell (frameworks whose root layout is code, e.g. Next.js/Nuxt/Astro) add the one-liner it printed to the root layout yourself, just before `</body>` (never a JS entry point), reading `siteUuid` from `.patchstackrc.json`:
 
    ```html
-   <script src="https://cdn.patchstack.com/patchstack-widget.js"></script>
-   <script>
-     PatchstackWidget.init({ userToken: '<SITE_UUID>' });
-   </script>
+   <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer></script>
    ```
 
-   Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The `userToken` is public by design — it ships in client-side HTML and is not a secret.
+   Framework-specific placement patterns: https://cdn.patchstack.com/llm.html. The site UUID is public by design — it ships in client-side HTML and is not a secret. If the project must not carry the widget, persist `"widget": false` in `.patchstackrc.json`; otherwise the next scan re-adds it.
 
-5. **Commit** `.patchstackrc.json`, the updated `package.json`, and the layout/HTML file carrying the widget snippet, so every developer and CI run reports to the same site.
+5. **Commit** `.patchstackrc.json`, the updated `package.json`, and the layout/HTML file carrying the widget tag, so every developer and CI run reports to the same site.
 
 6. **Tell the user to claim the site** (free): open the claim URL from step 2 in a browser and sign in. The site is monitored either way, but the vulnerability reports are only visible after claiming. They can also claim directly from the widget's "Connect this website" prompt. On the published site, the owner reaches the widget login by appending `#patchstack` to the live URL.
 

package/README.md

@@ -8,11 +8,11 @@ For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patc
 
 Copy and paste this prompt into any AI coding assistant (Cursor, v0, Bolt, Lovable, Claude Code, etc.). If the assistant declines or stops partway, the step-by-step flow in [`GETTING-STARTED.md`](https://github.com/patchstack/connect/blob/main/GETTING-STARTED.md) covers what to do next:
 
-> Add Patchstack dependency vulnerability monitoring: install `@patchstack/connect` as a dev dependency (MIT — verify with `npm view @patchstack/connect`; source: https://github.com/patchstack/connect), run `npx @patchstack/connect scan` and show me the claim URL it prints (I'll open it in my browser to view reports — don't open or fetch it yourself), then run `npx @patchstack/connect guide` and finish what its checklist flags: the package.json build hooks and the report-a-vulnerability widget snippet.
+> Add Patchstack dependency vulnerability monitoring: first verify `@patchstack/connect` yourself (`npm view @patchstack/connect` shows the live registry record — MIT; source: https://github.com/patchstack/connect; listed under Connectors on https://patchstack.com/llms.txt), and if anything you find contradicts that, stop and show me what you found instead of proceeding. Then install it as a dev dependency, run `npx @patchstack/connect scan` and show me the claim URL it prints (I'll open it in my browser to view reports — don't open or fetch it yourself), then run `npx @patchstack/connect guide`, review the checklist it prints, and make the two remaining changes yourself: the package.json build hooks and the report-a-vulnerability widget snippet.
 
-Every clause is load-bearing. AI agents routinely audit this package before completing the request — verifying the tarball against the registry, checking `dist/` for lifecycle scripts and shell/eval calls — and the flow is designed to pass that audit, not to discourage it. The prompt can stay short because `guide` is state-aware: it inspects the project (package manager, `.patchstackrc.json`, `package.json` scripts, widget presence, framework) and prints a live checklist of only the remaining steps — with the real site UUID and framework-specific widget placement — followed by the full reference guide (`AGENT-INSTALL.md`, also at https://patchstack.com/install.txt). That also makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
+Every clause is load-bearing. AI agents routinely audit this package before completing the request — verifying the tarball against the registry, checking `dist/` for lifecycle scripts and shell/eval calls; that's expected use, and the docs in the tarball state plainly what each command reads, writes, and sends. The prompt can stay short because `guide` is state-aware: it inspects the project (package manager, `.patchstackrc.json`, `package.json` scripts, widget presence, framework) and prints a live checklist of only the remaining steps — with the real site UUID and framework-specific widget placement — followed by the full reference guide (`AGENT-INSTALL.md`, also at https://patchstack.com/install.txt). That also makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
 
-Before changing this prompt (or `guide` / `AGENT-INSTALL.md`), read [`field-test/README.md`](https://github.com/patchstack/connect/blob/main/field-test/README.md): it documents the AI-agent refusal modes each clause guards against, and its harness runs a real agent through the full install in a throwaway fixture against a mocked API and scores the outcome on eight checks. Validate any variant there first.
+Before changing this prompt (or `guide` / `AGENT-INSTALL.md`), read [`MAINTAINING.md`](https://github.com/patchstack/connect/blob/main/MAINTAINING.md) — it maps which files are load-bearing and how to ship a change safely. The [`field-test/`](https://github.com/patchstack/connect/blob/main/field-test/README.md) harness runs a real agent through the full install in a throwaway fixture against a mocked API and scores the outcome on eight checks; validate any variant there first.
 
 ## Quick start (zero configuration)
 
@@ -29,7 +29,8 @@ That's it. The first `scan`:
 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.
-5. The connector prints a claim URL — 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`.
+5. The connector installs the disclosure widget's `<script>` tag into your root HTML shell (see *The disclosure widget* below) so the "Report a vulnerability" button shows up on the next preview reload.
+6. The connector prints a claim URL — 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 wire it into builds:
 
@@ -57,12 +58,16 @@ npx @patchstack/connect scan
 ```
 patchstack-connect scan   [options]                Scan the lockfile and POST to Patchstack.
                                                    If no UUID is configured the server provisions
-                                                   one and the connector persists it.
+                                                   one and the connector persists it. After a
+                                                   successful post, adds/updates the disclosure
+                                                   widget tag in the root HTML shell (opt out
+                                                   with "widget": false in .patchstackrc.json)
 patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
                                                    an existing site UUID
 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)
+                                                   build fingerprint and ensure the widget tag
+                                                   in built pages (run as a postbuild step)
 patchstack-connect guide                           Show this project's setup status (what's done,
                                                    what's missing, with tailored commands), then
                                                    print the full setup guide
@@ -97,11 +102,30 @@ Environment variables:
 
 ```json
 {
-  "siteUuid": "550e8400-e29b-41d4-a716-446655440000"
+  "siteUuid": "550e8400-e29b-41d4-a716-446655440000",
+  "widget": true
 }
 ```
 
-The site UUID identifies the site; it is not a secret — the disclosure widget ships the same UUID in client-side HTML as its `userToken`, and committing `.patchstackrc.json` is the intended workflow so every developer and CI run reports to the same site. Possession of the UUID lets someone submit dependency manifests for that site (noise, not data access). In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` instead.
+`"widget"` is optional and defaults to `true`; set it to `false` to stop the connector from managing the disclosure-widget tag (see *The disclosure widget*).
+
+The site UUID identifies the site; it is not a secret — the disclosure widget ships the same UUID in client-side HTML, and committing `.patchstackrc.json` is the intended workflow so every developer and CI run reports to the same site. Possession of the UUID lets someone submit dependency manifests for that site (noise, not data access). In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` instead.
+
+## The disclosure widget
+
+The widget is a floating "Report a vulnerability" button — a disclosure channel for anyone who spots a bug on the site. The connector manages its install so the UUID never has to be copied by hand:
+
+- **`scan`** (after a successful post) adds this managed tag to the first root HTML shell it finds — `index.html`, `public/index.html`, or `src/app.html` — immediately before `</body>`:
+
+  ```html
+  <script src="https://cdn.patchstack.com/patchstack-widget.js" data-site-uuid="<SITE_UUID>" defer data-patchstack-connect-widget="true"></script>
+  ```
+
+  Re-runs update the tag in place (the `data-patchstack-connect-widget` attribute marks it as connector-managed); a pre-existing manual widget tag is left untouched. `--dry-run` and failed posts never edit anything. Projects whose root layout is code rather than HTML (Next.js, Nuxt, Astro, …) get the exact snippet and target file printed instead — `guide` shows framework-specific placement.
+
+- **`mark-build`** ensures the same tag in built HTML output, covering builds whose source shell the connector couldn't edit, and stamps `window.__PATCHSTACK_PROD__` so the widget hides the claim/login UI on the published site (owners reach it by appending `#patchstack` to the live URL).
+
+- **Opting out:** persist `"widget": false` in `.patchstackrc.json` to disable both passes (dependency scanning only). Without it, the next successful scan re-adds the managed tag.
 
 ## Programmatic API
 

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync3, writeFileSync as writeFileSync2 } from "fs";
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -1039,7 +1039,8 @@ async function resolveConfig(options) {
     siteUuid: siteUuid === null || siteUuid.length === 0 ? null : siteUuid,
     endpoint,
     timeoutMs,
-    environment
+    environment,
+    widget: fromFile.widget !== false
   };
 }
 async function writeConfigFile(cwd, config) {
@@ -1251,10 +1252,71 @@ function injectMarker(html, snippet) {
 }
 
 // src/guide.ts
-import { existsSync as existsSync2, readFileSync, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import { existsSync as existsSync3, readFileSync as readFileSync2, readdirSync as readdirSync2, statSync as statSync2 } from "fs";
+import path9 from "path";
+
+// src/widget.ts
+import { existsSync as existsSync2, readFileSync, writeFileSync } from "fs";
 import path8 from "path";
 var WIDGET_SCRIPT_URL = "https://cdn.patchstack.com/patchstack-widget.js";
+var WIDGET_MARKER_ATTR = "data-patchstack-connect-widget";
 var WIDGET_NEEDLE = "patchstack-widget";
+var SOURCE_SHELL_CANDIDATES = ["index.html", "public/index.html", "src/app.html"];
+function buildWidgetTag(siteUuid) {
+  return `<script src="${WIDGET_SCRIPT_URL}" data-site-uuid="${siteUuid}" defer ${WIDGET_MARKER_ATTR}="true"></script>`;
+}
+var MANAGED_TAG_RE = new RegExp(
+  `<script[^>]*${WIDGET_MARKER_ATTR}[^>]*>\\s*</script>`,
+  "i"
+);
+function ensureWidgetInHtml(html, siteUuid) {
+  const tag = buildWidgetTag(siteUuid);
+  const managed = html.match(MANAGED_TAG_RE);
+  if (managed !== null) {
+    if (managed[0].includes(`data-site-uuid="${siteUuid}"`)) {
+      return { html, action: "unchanged" };
+    }
+    return { html: html.replace(MANAGED_TAG_RE, tag), action: "updated" };
+  }
+  if (html.includes(WIDGET_NEEDLE)) {
+    return { html, action: "manual" };
+  }
+  const bodyClose = html.match(/([ \t]*)<\/body>/i);
+  if (bodyClose === null || bodyClose.index === void 0) {
+    return { html, action: "no-body" };
+  }
+  const indent = bodyClose[1] ?? "";
+  const insertion = `${indent}  ${tag}
+${indent}</body>`;
+  return {
+    html: html.slice(0, bodyClose.index) + insertion + html.slice(bodyClose.index + bodyClose[0].length),
+    action: "added"
+  };
+}
+function findSourceShell(cwd) {
+  for (const candidate of SOURCE_SHELL_CANDIDATES) {
+    if (existsSync2(path8.join(cwd, candidate))) {
+      return candidate;
+    }
+  }
+  return null;
+}
+function ensureSourceWidget(cwd, siteUuid) {
+  const shell = findSourceShell(cwd);
+  if (shell === null) {
+    return { shell: null, action: "no-shell" };
+  }
+  const file = path8.join(cwd, shell);
+  const before = readFileSync(file, "utf8");
+  const { html, action } = ensureWidgetInHtml(before, siteUuid);
+  if (html !== before) {
+    writeFileSync(file, html);
+  }
+  return { shell, action };
+}
+
+// src/guide.ts
+var WIDGET_NEEDLE2 = "patchstack-widget";
 var INSTALL_COMMANDS = {
   npm: "npm install --save-dev @patchstack/connect",
   pnpm: "pnpm add -D @patchstack/connect",
@@ -1322,7 +1384,7 @@ 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))) {
+    if (existsSync3(path9.join(cwd, filename))) {
       return pm;
     }
   }
@@ -1333,7 +1395,7 @@ function installCommand(pm) {
 }
 function readPackageJson(cwd) {
   try {
-    return JSON.parse(readFileSync(path8.join(cwd, "package.json"), "utf8"));
+    return JSON.parse(readFileSync2(path9.join(cwd, "package.json"), "utf8"));
   } catch {
     return null;
   }
@@ -1341,7 +1403,7 @@ function readPackageJson(cwd) {
 function installedVersion(cwd, declaredRange) {
   try {
     const pkg = JSON.parse(
-      readFileSync(path8.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
+      readFileSync2(path9.join(cwd, "node_modules", "@patchstack", "connect", "package.json"), "utf8")
     );
     if (typeof pkg.version === "string" && pkg.version.length > 0) {
       return pkg.version;
@@ -1369,7 +1431,7 @@ function findWidgetMarker(cwd, siteUuid) {
       if (budget <= 0 || settled()) {
         return;
       }
-      const full = path8.join(dir, entry.name);
+      const full = path9.join(dir, entry.name);
       if (entry.isDirectory()) {
         if (SKIPPED_DIRS.has(entry.name) || entry.name.startsWith(".")) {
           continue;
@@ -1377,7 +1439,7 @@ function findWidgetMarker(cwd, siteUuid) {
         walk2(full, depth + 1);
         continue;
       }
-      if (!entry.isFile() || !WIDGET_EXTENSIONS.has(path8.extname(entry.name).toLowerCase())) {
+      if (!entry.isFile() || !WIDGET_EXTENSIONS.has(path9.extname(entry.name).toLowerCase())) {
         continue;
       }
       budget -= 1;
@@ -1385,8 +1447,8 @@ function findWidgetMarker(cwd, siteUuid) {
         if (statSync2(full).size > WIDGET_SCAN_MAX_BYTES) {
           continue;
         }
-        const content = readFileSync(full, "utf8");
-        if (!content.includes(WIDGET_NEEDLE)) {
+        const content = readFileSync2(full, "utf8");
+        if (!content.includes(WIDGET_NEEDLE2)) {
           continue;
         }
         sawWidget = true;
@@ -1409,7 +1471,7 @@ function resolveWidgetFileHint(cwd, framework) {
     ...GENERIC_WIDGET_FILES
   ];
   for (const candidate of candidates) {
-    if (existsSync2(path8.join(cwd, candidate))) {
+    if (existsSync3(path9.join(cwd, candidate))) {
       return candidate;
     }
   }
@@ -1433,6 +1495,7 @@ async function collectGuideState(cwd) {
   let siteUuid = null;
   let claimUrl = null;
   let endpointOverride = null;
+  let widgetOptOut = false;
   try {
     const config = await resolveConfig({ cwd });
     siteUuid = config.siteUuid;
@@ -1442,6 +1505,7 @@ async function collectGuideState(cwd) {
     if (config.endpoint !== DEFAULT_ENDPOINT) {
       endpointOverride = config.endpoint;
     }
+    widgetOptOut = !config.widget;
   } catch {
   }
   const declaredNames = Object.keys({ ...pkg?.dependencies, ...pkg?.devDependencies });
@@ -1464,6 +1528,7 @@ async function collectGuideState(cwd) {
     postbuildWired: (pkg?.scripts?.postbuild ?? "").includes("patchstack-connect mark-build") || (pkg?.scripts?.build ?? "").includes("patchstack-connect mark-build"),
     widgetInstalled: widget.found,
     widgetTokenMatches: widget.uuidMatches,
+    widgetOptOut,
     framework: stack.framework,
     widgetFileHint: resolveWidgetFileHint(cwd, stack.framework)
   };
@@ -1481,7 +1546,7 @@ function countRemainingSteps(state) {
     state.installed !== null,
     state.siteUuid !== null,
     state.prebuildWired && state.postbuildWired,
-    state.widgetInstalled && state.widgetTokenMatches !== false
+    state.widgetOptOut || state.widgetInstalled && state.widgetTokenMatches !== false
   ].filter((step) => !step).length;
 }
 function renderGuideChecklist(state, useColor) {
@@ -1493,7 +1558,7 @@ function renderGuideChecklist(state, useColor) {
   const headerParts = [state.framework, state.packageManager].filter(
     (part) => part !== null
   );
-  const name = state.projectName ?? path8.basename(process.cwd());
+  const name = state.projectName ?? path9.basename(process.cwd());
   lines.push(paint(ANSI.bold, `Patchstack setup status \u2014 ${name} (${headerParts.join(" \xB7 ")})`));
   if (state.endpointOverride !== null) {
     lines.push(
@@ -1540,19 +1605,24 @@ function renderGuideChecklist(state, useColor) {
     }
   }
   const widgetOk = state.widgetInstalled && state.widgetTokenMatches !== false;
-  if (widgetOk) {
+  if (state.widgetOptOut && !widgetOk) {
+    lines.push(done('Disclosure widget disabled by config ("widget": false in .patchstackrc.json)'));
+  } else 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}'`));
+    lines.push(todo("Disclosure widget found, but its site UUID doesn't match this project's"));
+    lines.push(detail(`\u2192 a wrong site UUID makes the widget silently no-op; set data-site-uuid (or userToken) to '${state.siteUuid}'`));
+  } else if (state.siteUuid === null) {
+    lines.push(todo('Add the "Report a vulnerability" widget \u2014 the first scan does this for you'));
+    lines.push(detail("\u2192 `npx @patchstack/connect scan` provisions the site and adds the widget tag"));
+    lines.push(detail("  to the root HTML shell (index.html / public/index.html / src/app.html)."));
   } else {
     lines.push(todo('Add the "Report a vulnerability" widget'));
-    const placement = state.widgetFileHint !== null ? `\u2192 add to ${state.widgetFileHint}, just before </body> (via the framework's HTML/layout mechanism):` : "\u2192 add just before </body> via the framework's HTML/layout mechanism (never a JS entry point):";
+    lines.push(detail("\u2192 a normal `scan` adds this tag to a plain HTML shell automatically;"));
+    const placement = state.widgetFileHint !== null ? `  for this project put it in ${state.widgetFileHint}, just before </body>:` : "  put it just before </body> 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(detail(`  ${buildWidgetTag(state.siteUuid)}`));
+    lines.push(detail("The site UUID is public by design \u2014 it ships in client-side HTML."));
   }
   lines.push("");
   if (state.claimUrl !== null) {
@@ -1588,13 +1658,13 @@ function renderGuideChecklist(state, useColor) {
 }
 
 // src/protect/install.ts
-import { readFileSync as readFileSync2, writeFileSync, existsSync as existsSync3, mkdirSync, copyFileSync } from "fs";
+import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync as existsSync4, mkdirSync, copyFileSync } from "fs";
 import { join, dirname } from "path";
 import { fileURLToPath } from "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 read = (p) => readFileSync3(p, "utf8");
 var log = (msg) => console.log(`patchstack protect: ${msg}`);
 var CLIENT_TUNNEL = [
   "",
@@ -1639,10 +1709,10 @@ var FUNCTION_MIDDLEWARE_DEF = [
 ].join("\n");
 function detectSupportedStack(cwd) {
   const pkgPath = join(cwd, "package.json");
-  if (!existsSync3(pkgPath)) return false;
+  if (!existsSync4(pkgPath)) return false;
   const pkg = JSON.parse(read(pkgPath));
   const deps = { ...pkg.dependencies, ...pkg.devDependencies };
-  return Boolean(deps["@tanstack/react-start"]) && existsSync3(join(cwd, "src/start.ts")) && existsSync3(join(cwd, "src/integrations/supabase/client.ts"));
+  return Boolean(deps["@tanstack/react-start"]) && existsSync4(join(cwd, "src/start.ts")) && existsSync4(join(cwd, "src/integrations/supabase/client.ts"));
 }
 function scaffold(cwd) {
   const dst = join(cwd, "src/integrations/patchstack");
@@ -1657,7 +1727,7 @@ function patchClient(cwd) {
   if (s.includes("x-ps-target")) return log("client.ts already wired");
   const anchor = "headers.set('apikey', supabaseKey);";
   if (!s.includes(anchor)) return log("client.ts anchor not found \u2014 skipping (template changed?)");
-  writeFileSync(p, s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL));
+  writeFileSync2(p, s.replace(anchor, anchor + "\n" + CLIENT_TUNNEL));
   log("patched client.ts (tunnel Supabase through the guard)");
 }
 function patchStart(cwd) {
@@ -1696,7 +1766,7 @@ function patchStart(cwd) {
     }
   }
   if (s === original) return log("start.ts already wired");
-  writeFileSync(p, s);
+  writeFileSync2(p, s);
   log("patched start.ts (guard registered as request + function middleware)");
 }
 function runProtect(cwd) {
@@ -1716,12 +1786,18 @@ var HELP = `@patchstack/connect \u2014 scan your lockfile and report packages to
 Usage:
   patchstack-connect scan   [options]                Scan lockfile and POST to Patchstack.
                                                      If no UUID is configured, the server
-                                                     provisions one and we persist it.
+                                                     provisions one and we persist it. After a
+                                                     successful post it also adds/updates the
+                                                     disclosure-widget <script> tag in the root
+                                                     HTML shell (index.html, public/index.html,
+                                                     or src/app.html) \u2014 opt out with
+                                                     "widget": false in .patchstackrc.json
   patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json
                                                      with an existing site UUID
   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)
+                                                     build fingerprint, and ensure the widget
+                                                     tag in built pages (run as a postbuild step)
   patchstack-connect protect                         Install always-on runtime protection (the
                                                      guard) into a TanStack Start + Supabase app.
                                                      Covers the browser + server-function paths.
@@ -1868,6 +1944,10 @@ async function runScan(args) {
   } else {
     console.log(`Server response: ${response.message ?? JSON.stringify(response)}`);
   }
+  const effectiveUuid = config.siteUuid ?? response.uuid ?? null;
+  if (config.widget && effectiveUuid !== null && effectiveUuid.length > 0) {
+    reportSourceWidget(effectiveUuid);
+  }
   if (provisioning && response.uuid !== void 0 && response.uuid.length > 0) {
     console.log("");
     console.log("Claim this site to view vulnerability reports in your Patchstack dashboard:");
@@ -1878,6 +1958,39 @@ async function runScan(args) {
   }
   return 0;
 }
+function reportSourceWidget(siteUuid) {
+  try {
+    const result = ensureSourceWidget(process.cwd(), siteUuid);
+    switch (result.action) {
+      case "added":
+        console.log(`Widget: added the "Report a vulnerability" tag to ${result.shell}. Reload your preview to see it.`);
+        break;
+      case "updated":
+        console.log(`Widget: updated the managed tag in ${result.shell} to site ${siteUuid}.`);
+        break;
+      case "unchanged":
+        console.log(`Widget: already installed in ${result.shell}.`);
+        break;
+      case "manual":
+        console.log(`Widget: found an existing (manual) install in ${result.shell} \u2014 left untouched.`);
+        break;
+      case "no-body":
+        console.log(`Widget: ${result.shell} has no </body> tag to anchor on. Add this tag to your root layout manually:`);
+        console.log(`  ${buildWidgetTag(siteUuid)}`);
+        break;
+      case "no-shell":
+        console.log("Widget: no plain HTML shell found (index.html / public/index.html / src/app.html).");
+        console.log("Add this tag to your root layout before </body> (run `guide` for framework-specific placement):");
+        console.log(`  ${buildWidgetTag(siteUuid)}`);
+        break;
+    }
+    if (result.action === "added" || result.action === "updated") {
+      console.log('  (opt out any time with "widget": false in .patchstackrc.json)');
+    }
+  } catch (err) {
+    console.warn(`Widget: skipped (${err.message}).`);
+  }
+}
 async function runProtectCommand(_args) {
   try {
     runProtect(process.cwd());
@@ -1906,7 +2019,7 @@ async function runGuide(args) {
   console.log("\u2014\u2014\u2014\u2014 Full reference guide (ships as AGENT-INSTALL.md) \u2014\u2014\u2014\u2014");
   console.log("");
   const guidePath = new URL("../AGENT-INSTALL.md", import.meta.url);
-  console.log(readFileSync3(guidePath, "utf8"));
+  console.log(readFileSync4(guidePath, "utf8"));
   return 0;
 }
 async function runStatus(args) {
@@ -1952,6 +2065,20 @@ async function runMarkBuild(args) {
       `mark-build: could not compute the build fingerprint (${err.message}). Stamping the production flag only.`
     );
   }
+  let widgetUuid = null;
+  try {
+    const config = await resolveConfig({
+      cwd,
+      cliSiteUuid: getStringFlag(args.flags, "site-uuid")
+    });
+    if (config.widget) {
+      widgetUuid = config.siteUuid;
+    }
+  } catch (err) {
+    console.warn(
+      `mark-build: could not resolve the site UUID (${err.message}). Skipping the widget pass.`
+    );
+  }
   const dir = resolveBuildDir(cwd, getStringFlag(args.flags, "dir"));
   if (dir === null) {
     console.warn(
@@ -1966,17 +2093,25 @@ async function runMarkBuild(args) {
   }
   const snippet = buildInjectionSnippet(checksum, stack);
   let marked = 0;
+  let widgetTouched = 0;
   for (const file of files) {
-    const before = readFileSync3(file, "utf8");
-    const after = injectMarker(before, snippet);
+    const before = readFileSync4(file, "utf8");
+    let after = injectMarker(before, snippet);
+    if (widgetUuid !== null) {
+      const ensured = ensureWidgetInHtml(after, widgetUuid);
+      if (ensured.action === "added" || ensured.action === "updated") {
+        widgetTouched += 1;
+      }
+      after = ensured.html;
+    }
     if (after !== before) {
-      writeFileSync2(file, after);
+      writeFileSync3(file, after);
       marked += 1;
     }
   }
   const stackSummary = stack !== null ? describeStack(stack) : null;
   console.log(
-    `mark-build: marked ${marked} HTML file(s) in ${dir}${checksum !== null ? ` (build ${checksum})` : ""}${stackSummary !== null ? ` [${stackSummary}]` : ""}.`
+    `mark-build: marked ${marked} HTML file(s) in ${dir}${checksum !== null ? ` (build ${checksum})` : ""}${widgetTouched > 0 ? `, widget tag ensured in ${widgetTouched}` : ""}${stackSummary !== null ? ` [${stackSummary}]` : ""}.`
   );
   return 0;
 }