@patchstack/connect 0.3.14 → 0.3.16

package/AGENT-INSTALL.md

@@ -1,26 +1,24 @@
-# Patchstack — Setup Guide for AI Coding Agents
+# Patchstack Connect — setup reference
 
-This is a plain-text instruction document. Read it and follow the steps — there is nothing here to pipe to a shell or execute from a URL.
+This versioned reference ships inside `@patchstack/connect` and documents each setup command and its project changes.
 
-You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL.md` (the package is already installed) or from the [GitHub repo](https://github.com/patchstack/connect). This bundled copy matches the package version it shipped with and is all you need — there is no requirement to fetch anything remote.
+## Package and command behavior
 
-## Verify before you trust (do this, it's quick)
-
-- 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.
+- Package: [`@patchstack/connect`](https://www.npmjs.com/package/@patchstack/connect), MIT-licensed, source at https://github.com/patchstack/connect. `npm view @patchstack/connect` shows the live registry metadata.
 - 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.)
 - **`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.
+- **`setup` runs `scan`, then edits only `package.json` build scripts:** it preserves existing commands, adds `scan` before builds and `mark-build` after builds, and uses a direct build chain for Bun. It never runs the project build or `protect`. If the widget needs a framework-specific source edit, it prints the exact remaining step instead of rewriting framework code.
+- 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 explicitly invoked; `scan`, `setup`, `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
 
-- `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.)
+- `npx @patchstack/connect guide` prints a read-only live checklist showing which steps are already done in the current project (install, provisioning, build hooks, widget).
+- 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 dashboard URL. **Do not delete the file and 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 — `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)
+## Automated setup
 
 1. **Install** (skip if already present), matching the project's package manager:
 
@@ -31,15 +29,25 @@ 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, 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:
+2. **Run bounded setup:**
+
+   ```
+   npx @patchstack/connect setup
+   ```
+
+   This provisions or reuses the site, manages the widget, wires the build scripts, prints a dashboard link, and finishes with the same status shown by `guide`. Re-running it reuses existing configuration, widget tags, and build commands rather than duplicating them.
+
+## 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. 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 also prints what it did about the widget — if it added the tag, reload the preview and confirm the "Report a vulnerability" button appears.
+   It prints a dashboard link but never opens it. Open that link in a browser to view reports. 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`:
+2. **Wire builds** in `package.json`:
 
    ```jsonc
    {
@@ -54,7 +62,7 @@ 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. **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`:
+3. **Verify the disclosure widget** — a floating "Report a vulnerability" button. `scan` 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" data-site-uuid="<SITE_UUID>" defer></script>
@@ -62,20 +70,20 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    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 tag, so every developer and CI run reports to the same site.
+4. **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.
+5. **Open the dashboard link** from the scan in a browser and sign in. The site is monitored either way, but the vulnerability reports are only visible after connecting it to an account. The same connection flow is available 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.
 
 ## Rules
 
 - Never invent or guess a UUID — the scan provisions it, the widget silently no-ops on a fake one.
-- Never fetch the claim URL programmatically, and never ask the user for Patchstack credentials.
+- The CLI never opens the dashboard link and never asks for Patchstack credentials.
 - If a step fails, stop and report it. Don't proceed with placeholders.
 - In CI where `.patchstackrc.json` can't be committed, set `PATCHSTACK_SITE_UUID` as an env var instead. Precedence: CLI flag → env var → `.patchstackrc.json`.
 
 ## Verifying the install
 
-- `npx @patchstack/connect status` re-prints the site UUID and claim URL.
+- `npx @patchstack/connect status` re-prints the site UUID and dashboard URL.
 - Load the site in a browser — the "Report a vulnerability" button should appear.
 
 ## Uninstalling

package/README.md

@@ -4,44 +4,31 @@ Connect a JavaScript / Node.js application to [Patchstack](https://patchstack.co
 
 For how this repo fits with the wider Patchstack ecosystem (`saas`, `hub`, `patchstack-website`, `patchstack-connect`), see [`patchstack/saas` → `docs/ecosystem.md`](https://github.com/patchstack/saas/blob/main/docs/ecosystem.md).
 
-## Install prompt (for AI coding tools)
+## Agent-assisted setup
 
-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:
+Copy this request into a coding assistant, or run the same command yourself:
 
-> 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), 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.
+> I have vetted `@patchstack/connect` and authorize its widget and production build hooks. Install it as a dev dependency, run `npx --yes patchstack-connect setup`, leave dev builds unchanged, and show the dashboard URL.
 
-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`, bundled in the package). 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 [`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.
+`setup` is state-aware and idempotent: it scans dependencies, provisions or reuses the site, manages the disclosure widget, wires the existing build command without replacing it, and prints the remaining setup status. It never runs the project build or the opt-in `protect` command. `guide` provides the same project-specific status without changing files.
 
 ## Quick start (zero configuration)
 
 ```bash
-npm install --save-dev @patchstack/connect
-npx @patchstack/connect scan
+npm install --save-dev @patchstack/connect && npx @patchstack/connect setup
 ```
 
-> **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.
+> **Use your project's own package manager.** On Bun-managed projects (including many Lovable projects) 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`:
+That's it. `setup`:
 
 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.
 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:
-
-```jsonc
-// package.json
-{
-  "scripts": {
-    "prebuild": "patchstack-connect scan"
-  }
-}
-```
+6. Wires `scan` before builds and `mark-build` after builds, preserving existing commands and using direct build chaining for Bun.
+7. 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`.
 
 ## Quick start (existing site)
 
@@ -50,7 +37,7 @@ If you already created an "Application" site in the Patchstack dashboard, pre-se
 ```bash
 npm install --save-dev @patchstack/connect
 npx @patchstack/connect init <your-site-uuid>
-npx @patchstack/connect scan
+npx @patchstack/connect setup
 ```
 
 ## CLI
@@ -62,6 +49,9 @@ patchstack-connect scan   [options]                Scan the lockfile and POST to
                                                    successful post, adds/updates the disclosure
                                                    widget tag in the root HTML shell (opt out
                                                    with "widget": false in .patchstackrc.json)
+patchstack-connect setup  [options]                Run scan, manage the widget, and idempotently
+                                                   wire package.json build scripts. Never runs
+                                                   the project build or protect
 patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json with
                                                    an existing site UUID
 patchstack-connect status [options]                Show current configuration
@@ -75,7 +65,7 @@ patchstack-connect protect                         Opt-in: install the always-on
                                                    guard (currently TanStack Start + Supabase; it
                                                    patches the app's Supabase client to route
                                                    traffic through a same-origin guard). Never
-                                                   run by scan/guide/mark-build.
+                                                   run by scan/setup/guide/mark-build.
 patchstack-connect help                            Print help
 
 Options (for scan and status):

package/dist/cli.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 // src/cli.ts
-import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import { readFileSync as readFileSync5, writeFileSync as writeFileSync4 } from "fs";
 
 // src/parsers/index.ts
 import { access } from "fs/promises";
@@ -1324,11 +1324,11 @@ var INSTALL_COMMANDS = {
   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" }
+  { filename: "yarn.lock", pm: "yarn" },
+  { filename: "package-lock.json", pm: "npm" }
 ];
 var WIDGET_FILE_CANDIDATES = {
   next: [
@@ -1383,6 +1383,10 @@ var WIDGET_SCAN_MAX_FILES = 4e3;
 var WIDGET_SCAN_MAX_DEPTH = 6;
 var WIDGET_SCAN_MAX_BYTES = 512 * 1024;
 function detectPackageManager(cwd) {
+  const declared = readPackageJson(cwd)?.packageManager?.split("@")[0];
+  if (declared === "npm" || declared === "pnpm" || declared === "yarn" || declared === "bun") {
+    return declared;
+  }
   for (const { filename, pm } of PM_BY_LOCKFILE) {
     if (existsSync3(path9.join(cwd, filename))) {
       return pm;
@@ -1587,8 +1591,8 @@ function renderGuideChecklist(state, useColor) {
   } else {
     lines.push(todo("Provision the site \u2014 run the first scan"));
     lines.push(detail("Run \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."));
+    lines.push(detail("Reads the lockfile, registers the project, writes .patchstackrc.json,"));
+    lines.push(detail("and prints a dashboard link. The CLI prints the link but never opens it."));
   }
   if (state.prebuildWired && state.postbuildWired) {
     lines.push(done("Build hooks wired (scan before builds, mark-build after)"));
@@ -1626,14 +1630,14 @@ function renderGuideChecklist(state, useColor) {
   }
   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, "\u279C")} ${paint(ANSI.bold, "Dashboard link (open to view reports):")}`);
     lines.push(`   ${paint(ANSI.cyan, state.claimUrl)}`);
-    lines.push(detail("Open in a browser. AI agents: show this URL to the user verbatim."));
+    lines.push(detail("Open this link in a browser. The CLI never opens it."));
     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`)."));
+    lines.push(detail("The dashboard link appears after the first scan (re-print any time with `status`)."));
   }
   const remaining = countRemainingSteps(state);
   lines.push("");
@@ -1647,7 +1651,7 @@ function renderGuideChecklist(state, useColor) {
       )
     );
     if (state.claimUrl !== null) {
-      lines.push(detail("The only manual action left is claiming the site via the URL above (if not already claimed)."));
+      lines.push(detail("The only manual action left is opening the dashboard link above (if not already connected)."));
     }
   } else {
     lines.push(
@@ -1723,6 +1727,25 @@ function scaffold(cwd) {
   copyFileSync(join(TEMPLATES, "rules.json"), join(dst, "rules.json"));
   log("scaffolded guard.ts + rules.json");
 }
+function bakeSiteUuid(cwd) {
+  const rc = join(cwd, ".patchstackrc.json");
+  if (!existsSync4(rc)) return log("no .patchstackrc.json \u2014 guard uses PATCHSTACK_SITE_UUID env or the bundled fallback");
+  let uuid;
+  try {
+    uuid = JSON.parse(read(rc)).siteUuid;
+  } catch {
+    return log(".patchstackrc.json unreadable \u2014 skipping site-UUID bake");
+  }
+  if (!uuid || !/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(uuid)) {
+    return log(".patchstackrc.json siteUuid missing or malformed \u2014 guard uses PATCHSTACK_SITE_UUID env or the bundled fallback");
+  }
+  const p = join(cwd, "src/integrations/patchstack/guard.ts");
+  if (!existsSync4(p)) return;
+  const s = read(p);
+  if (!s.includes("__PATCHSTACK_SITE_UUID__")) return log("guard.ts site UUID already baked");
+  writeFileSync2(p, s.replace("__PATCHSTACK_SITE_UUID__", uuid));
+  log("baked site UUID into guard.ts \u2014 live rules from the Patchstack API");
+}
 function patchClient(cwd) {
   const p = join(cwd, "src/integrations/supabase/client.ts");
   let s = read(p);
@@ -1777,11 +1800,84 @@ function runProtect(cwd) {
     return;
   }
   scaffold(cwd);
+  bakeSiteUuid(cwd);
   patchClient(cwd);
   patchStart(cwd);
   log("done \u2014 guard wired and always-on (blocks by default). Set PATCHSTACK_MODE=dry-run for log-only.");
 }
 
+// src/setup.ts
+import { readFileSync as readFileSync4, writeFileSync as writeFileSync3 } from "fs";
+import path10 from "path";
+var SCAN_COMMAND = "patchstack-connect scan";
+var MARK_BUILD_COMMAND = "patchstack-connect mark-build";
+function appendHook(existing, command) {
+  if (existing === void 0 || existing.trim().length === 0) {
+    return command;
+  }
+  if (existing.includes(command)) {
+    return existing;
+  }
+  return `${existing} && ${command}`;
+}
+function wireBuildScripts(cwd, packageManager) {
+  const target = path10.join(cwd, "package.json");
+  const raw = readFileSync4(target, "utf8");
+  const pkg = JSON.parse(raw);
+  const scripts = pkg.scripts ?? {};
+  const build = scripts.build;
+  if (build === void 0 || build.trim().length === 0) {
+    return {
+      changed: false,
+      strategy: "skipped",
+      detail: "package.json has no build script; no build integration was added."
+    };
+  }
+  if (packageManager === "bun") {
+    let nextBuild = build;
+    if (!nextBuild.includes(SCAN_COMMAND)) {
+      nextBuild = `${SCAN_COMMAND} && ${nextBuild}`;
+    }
+    if (!nextBuild.includes(MARK_BUILD_COMMAND)) {
+      nextBuild = `${nextBuild} && ${MARK_BUILD_COMMAND}`;
+    }
+    if (nextBuild === build) {
+      return {
+        changed: false,
+        strategy: "build-chain",
+        detail: "build script already runs scan and mark-build."
+      };
+    }
+    scripts.build = nextBuild;
+  } else {
+    const prebuild = appendHook(scripts.prebuild, SCAN_COMMAND);
+    const postbuild = appendHook(scripts.postbuild, MARK_BUILD_COMMAND);
+    if (prebuild === scripts.prebuild && postbuild === scripts.postbuild) {
+      return {
+        changed: false,
+        strategy: "lifecycle-hooks",
+        detail: "prebuild and postbuild hooks are already wired."
+      };
+    }
+    scripts.prebuild = prebuild;
+    scripts.postbuild = postbuild;
+  }
+  pkg.scripts = scripts;
+  const indentMatch = raw.match(/^[\t ]+(?=")/m)?.[0];
+  const indent = indentMatch?.includes("	") ? "	" : indentMatch?.length ?? 2;
+  const trailingNewline = raw.endsWith("\n") ? "\n" : "";
+  writeFileSync3(target, `${JSON.stringify(pkg, null, indent)}${trailingNewline}`, "utf8");
+  return packageManager === "bun" ? {
+    changed: true,
+    strategy: "build-chain",
+    detail: "chained scan and mark-build around the existing build command."
+  } : {
+    changed: true,
+    strategy: "lifecycle-hooks",
+    detail: "added scan to prebuild and mark-build to postbuild."
+  };
+}
+
 // src/cli.ts
 var HELP = `@patchstack/connect \u2014 scan your lockfile and report packages to Patchstack.
 
@@ -1794,6 +1890,9 @@ Usage:
                                                      HTML shell (index.html, public/index.html,
                                                      or src/app.html) \u2014 opt out with
                                                      "widget": false in .patchstackrc.json
+  patchstack-connect setup  [options]                Finish the bounded project setup: run scan,
+                                                     manage the widget, and wire package.json build
+                                                     scripts. Never runs a build or protect
   patchstack-connect init   <site-uuid>              Optional: pre-seed .patchstackrc.json
                                                      with an existing site UUID
   patchstack-connect status [options]                Show current configuration
@@ -1809,7 +1908,7 @@ Usage:
                                                      guide even when setup is complete
   patchstack-connect help                            Print this message
 
-Options (for scan and status):
+Options (for scan, setup, and status):
   --site-uuid <uuid>      Override the configured site UUID
   --endpoint <url>        Override the API endpoint
   --dry-run               (scan only) Show the payload without posting
@@ -1827,6 +1926,7 @@ Environment:
 Precedence: CLI flag > environment variable > .patchstackrc.json.
 
 Examples:
+  npx @patchstack/connect setup
   npx @patchstack/connect scan
   npx @patchstack/connect scan --dry-run
   npx @patchstack/connect init 550e8400-e29b-41d4-a716-446655440000
@@ -1884,7 +1984,7 @@ async function runInit(args) {
   console.log("Next: run `npx @patchstack/connect scan` to send your first manifest.");
   return 0;
 }
-async function runScan(args) {
+async function runScan(args, options = {}) {
   const dryRun = args.flags.get("dry-run") === true;
   const config = await resolveConfig({
     cwd: process.cwd(),
@@ -1951,24 +2051,26 @@ async function runScan(args) {
   }
   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:");
+    console.log("Open this dashboard link to view vulnerability reports:");
     console.log(`  ${buildClaimUrl(config.endpoint, response.uuid)}`);
     if (config.endpoint !== DEFAULT_ENDPOINT) {
       console.log("  (this URL inherits the endpoint override above)");
     }
   }
-  try {
-    const state = await collectGuideState(process.cwd());
-    const remaining = countRemainingSteps(state);
-    if (remaining > 0) {
-      const hooksMissing = !(state.prebuildWired && state.postbuildWired);
-      console.log("");
-      console.log(
-        `Setup not complete \u2014 ${remaining} step(s) remaining${hooksMissing ? ", including the package.json build hooks (which scan can't wire)" : ""}.`
-      );
-      console.log("Run `npx @patchstack/connect guide` for the exact steps to finish for this project.");
+  if (options.showRemainingSetup !== false) {
+    try {
+      const state = await collectGuideState(process.cwd());
+      const remaining = countRemainingSteps(state);
+      if (remaining > 0) {
+        const hooksMissing = !(state.prebuildWired && state.postbuildWired);
+        console.log("");
+        console.log(
+          `Setup not complete \u2014 ${remaining} step(s) remaining${hooksMissing ? ", including the package.json build hooks (which scan can't wire)" : ""}.`
+        );
+        console.log("Run `npx @patchstack/connect guide` for the exact steps to finish for this project.");
+      }
+    } catch {
     }
-  } catch {
   }
   return 0;
 }
@@ -2033,7 +2135,46 @@ 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(readFileSync4(guidePath, "utf8"));
+  console.log(readFileSync5(guidePath, "utf8"));
+  return 0;
+}
+async function runSetup(args) {
+  if (args.flags.get("dry-run") === true) {
+    console.error("Error: setup does not support --dry-run. Use `scan --dry-run` to preview the manifest.");
+    return 1;
+  }
+  const before = await collectGuideState(process.cwd());
+  if (!before.hasPackageJson) {
+    console.error("Error: no package.json found. Run setup from the project root.");
+    return 1;
+  }
+  if (before.installed === null) {
+    console.error(
+      `Error: @patchstack/connect is not declared in package.json.
+Run: ${installCommand(before.packageManager)}`
+    );
+    return 1;
+  }
+  console.log("Patchstack setup \u2014 applying bounded project changes");
+  console.log("  1. Scan dependencies, provision/reuse the site, and manage the source widget");
+  const scanCode = await runScan(args, { showRemainingSetup: false });
+  if (scanCode !== 0) {
+    return scanCode;
+  }
+  console.log("");
+  console.log("  2. Wire scan and mark-build into package.json");
+  const wired = wireBuildScripts(process.cwd(), before.packageManager);
+  console.log(`Build integration: ${wired.detail}`);
+  console.log("");
+  console.log("  3. Verify setup status");
+  const after = await collectGuideState(process.cwd());
+  const useColor = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+  console.log(renderGuideChecklist(after, useColor));
+  const remaining = countRemainingSteps(after);
+  if (remaining > 0) {
+    console.log("");
+    console.log(`Setup applied its bounded changes; ${remaining} manual step(s) remain above.`);
+  }
   return 0;
 }
 async function runStatus(args) {
@@ -2049,7 +2190,7 @@ async function runStatus(args) {
   console.log(`Timeout:     ${config.timeoutMs}ms`);
   console.log(`Environment: ${config.environment}`);
   if (config.siteUuid !== null) {
-    console.log(`Claim URL:  ${buildClaimUrl(config.endpoint, config.siteUuid)}`);
+    console.log(`Dashboard URL: ${buildClaimUrl(config.endpoint, config.siteUuid)}`);
   }
   return 0;
 }
@@ -2109,7 +2250,7 @@ async function runMarkBuild(args) {
   let marked = 0;
   let widgetTouched = 0;
   for (const file of files) {
-    const before = readFileSync4(file, "utf8");
+    const before = readFileSync5(file, "utf8");
     let after = injectMarker(before, snippet);
     if (widgetUuid !== null) {
       const ensured = ensureWidgetInHtml(after, widgetUuid);
@@ -2119,7 +2260,7 @@ async function runMarkBuild(args) {
       after = ensured.html;
     }
     if (after !== before) {
-      writeFileSync3(file, after);
+      writeFileSync4(file, after);
       marked += 1;
     }
   }
@@ -2148,6 +2289,8 @@ async function main() {
       return runProtectCommand(args);
     case "guide":
       return runGuide(args);
+    case "setup":
+      return runSetup(args);
     default:
       console.error(`Unknown command: ${args.command}
 `);