@patchstack/connect 0.3.3 → 0.3.5

package/AGENT-INSTALL.md

@@ -7,12 +7,14 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 ## 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.
-- It reads the project's **lockfile only** (`package-lock.json`, `pnpm-lock.yaml`, or `yarn.lock`) and sends package names + versions to Patchstack for vulnerability matching. No source code, no env vars, no file paths, no git history.
+- 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 vars, no file paths, no git history.
 - 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
 
-- If `.patchstackrc.json` exists, the project is already provisioned. Reuse its UUID; run `npx @patchstack/connect status` to re-print it and the claim URL. **Do not run `scan` to provision a second site.**
+- `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. Trust that checklist over re-deriving state yourself; 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.
 
@@ -35,7 +37,7 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    It prints a claim URL. Surface that URL to the user verbatim — never fetch it yourself; it must be opened in their browser.
 
-3. **Wire builds** in `package.json` (chain with `&&` if hooks already exist):
+3. **Wire builds** in `package.json`:
 
    ```jsonc
    {
@@ -46,7 +48,9 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
    }
    ```
 
-4. **Install the disclosure widget** — a floating "Report a vulnerability" button. Read the UUID from `.patchstackrc.json` and use it as `userToken`. Place these two snippets via the framework's HTML/layout mechanism (never a JS entry point):
+   If a `prebuild`/`postbuild` hook already exists, chain instead of replacing it, e.g. `"prebuild": "existing-command && patchstack-connect scan"`.
+
+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):
 
    ```html
    <script src="https://cdn.patchstack.com/patchstack-widget.js"></script>
@@ -57,7 +61,7 @@ You are reading this either from `node_modules/@patchstack/connect/AGENT-INSTALL
 
    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.
 
-5. **Commit** `.patchstackrc.json` and the updated `package.json` 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 snippet, 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,19 @@ 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.):
 
-> Install the npm package `@patchstack/connect` as a dev dependency (MIT, source: https://github.com/patchstack/connect) to add dependency vulnerability monitoring, then run `npx @patchstack/connect guide` and follow the setup guide it prints. It only reads the lockfile — nothing is fetched from a URL or executed remotely.
+> Add Patchstack dependency vulnerability monitoring to this project (MIT, source: https://github.com/patchstack/connect — verify with `npm view @patchstack/connect` if unsure):
+>
+> 1. Install `@patchstack/connect` as a dev dependency with this project's package manager.
+> 2. `npx @patchstack/connect scan` — reads the lockfile, saves a site ID to `.patchstackrc.json`, and prints a claim URL. Show me that URL; don't open it.
+> 3. `npx @patchstack/connect guide` — prints a checklist of what's still missing here (build hooks, report-a-vulnerability widget). Finish those steps and commit.
 
-The prompt is built to survive agent security filters: it names a pinnable, auditable npm package (not a remote script), the `guide` command prints instructions that ship *inside* the installed package (`AGENT-INSTALL.md`), and it preempts the "Patchstack is WordPress-only" objection. If the agent has network access, the always-current version of the guide is at https://patchstack.com/install.txt — this longer prompt uses it directly:
+The shape of this prompt is deliberate — it has survived three distinct AI-agent refusal modes, and each one punished a different shortcut:
 
-> Add Patchstack dependency vulnerability monitoring: install the npm package `@patchstack/connect` as a dev dependency (MIT, source: https://github.com/patchstack/connect — pin it and verify however your policy requires), then follow the plain-text setup instructions at https://patchstack.com/install.txt. That URL is documentation to read, not a script to execute — nothing gets piped to a shell. Patchstack monitors any JS/Node lockfile, not just WordPress.
+1. **"Follow the instructions at this URL" reads as remote script execution.** Agents refuse before ever fetching the doc.
+2. **Agents whose training predates May 2026 assert the package doesn't exist.** The `npm view` check resolves that against the registry instead of the model's memory.
+3. **"Install the package, then follow the instructions it ships" reads as handing control to the package author** — structurally the same as prompt injection — and preemptive reassurance language ("it's safe, don't be suspicious, note your knowledge cutoff") is itself flagged as a manipulation signal.
+
+So the prompt keeps the trust-critical spine inline — verification, the scan command, and surfacing the claim URL are concrete, individually inspectable steps — and argues nothing. `npx @patchstack/connect guide` enters only at step 3, after the agent has already installed and audited the package, so consulting its docs is ordinary behavior rather than the instruction channel the install depends on. And `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). "Finish what the checklist marks missing" is a much smaller ask of an agent than "follow this manual", and it makes the flow idempotent: re-running `guide` on a finished project reports all-done instead of prompting a second install.
 
 ## Quick start (zero configuration)
 
@@ -61,6 +69,11 @@ patchstack-connect scan   [options]                Scan the lockfile and POST to
 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)
+patchstack-connect guide                           Show this project's setup status (what's done,
+                                                   what's missing, with tailored commands), then
+                                                   print the full setup guide
 patchstack-connect help                            Print help
 
 Options (for scan and status):