Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 6 additions & 4 deletions AGENT-INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,7 +89,7 @@ Every command at a glance — what it does, whether it reads your source, what i
| `next` | Say where the project stands and the one thing to do now: connect the account (with the link), or go live (with the same steps `go-live` prints, or asking where the app is hosted when the project does not say). Answers the "done" the summary ends on. | Reads the project files `guide` and `go-live` read | The connected note in `.patchstackrc.json`, when it changed | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is) |
| `doctor [--url <live app>]` | Check that everything Patchstack needs works, and print each problem with its fix: the install, the site, the account, the guard's wiring, its rules file, the read-only rules credential, the map link, the build steps, and whether the published app fetches its rules. A problem only the app's owner can fix (connecting the account, publishing) is marked as theirs. Exits 1 when it finds a problem. | Reads the project files `guide` and `protect --check` read | Nothing | The site UUID, to the public claim page that says whether it is connected (skipped once `.patchstackrc.json` records that it is); the read-only rules credential from the guard's rules file, and the site key when this machine holds one, each once to `monitor/pulse/token`, to check Patchstack accepts them; one GET with that token to `monitor/pulse/sync-status/<your site uuid>`, which answers only when the published app (read-only credential) and a key-holding copy last fetched rules, and how many (doctor never fetches rules itself, which would be recorded as a fetch); with `--url`, two GET requests to that address: its page, and the same page with a test attack in a `file` parameter, which another firewall in front of the app may also flag |
| `vulns` | Show what Patchstack found in this project's packages: vulnerabilities by severity and outdated packages, as counts, with the link that shows the details. Package names are shown in the dashboard once the site is connected. | No | Nothing | The site UUID, to the public claim page that returns the counts |
| `go-live [--host <name>]` | Show how to add the project's API key to its host and deploy, in three steps. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, a Lovable project's packages) or named with `--host`. The commands it prints read the key from `.patchstackrc.local.json` as they run; it never prints the key. | Reads those project files only | Nothing | Nothing |
| `go-live [--host <name>]` | Show how to add the project's API key to its host and deploy, in three steps. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, a Lovable project's packages) or named with `--host`. The commands it prints read the key from `.patchstackrc.local.json` as they run; it never prints the key. | Reads those project files only | On Vercel only, a `.vercelignore` entry for `.patchstackrc.local.json` (the file is created if missing): the Vercel CLI uploads the project folder and does not read `.gitignore` | Nothing |
| `widget [--remove]` | Add the Patchstack Connector widget tag to the root page (in a workspace repo, the app package's root page), or take the tag Connect added out with `--remove` (a tag added by hand is left alone). Saves the choice as `"widget"` in `.patchstackrc.json`, which `scan` and `mark-build` follow; `setup --widget` saves the same choice. | Reads the root page to find where the tag goes | `.patchstackrc.json`; the widget `<script>` tag in the root HTML shell or framework root | Nothing |
| `init <site-uuid>` | Optional: pre-seed `.patchstackrc.json` with an existing UUID. | No | `.patchstackrc.json` only | Nothing |
| `mark-build` | Ensure the widget tag in built pages, and — **on a production build only** — stamp the live-site flag + build fingerprint. A local or preview build is stamped with neither, and has a stale marker removed; `--production` forces it for a build published by hand. Run as a `postbuild` step. | No | Build output only (`dist/ build/ out/ .output/public/ _site/`) — never source | The same manifest `scan` sent, plus one word for what it did with the marker — and only for a site already registered |
Expand Down Expand Up @@ -218,13 +218,15 @@ Only when the person asks you to publish the site. Start with `npx @patchstack/c
```

A preview deploy runs without the prefix.
- **A deploy that builds on the host** (`vercel --prod`, or any git-connected Netlify or Vercel site) labels production by itself, but the host never receives `.patchstackrc.local.json`. Before the first production deploy, put the key in the host's production settings, read straight from the file so it is never printed:
- **A deploy that builds on the host** (`vercel --prod`, or any git-connected Netlify or Vercel site) labels production by itself, but the host must not receive `.patchstackrc.local.json`. Before the first production deploy, put the key in the host's production settings, read straight from the file so it is never printed:

```
node -p "require('./.patchstackrc.local.json').apiKey" | npx vercel env add PATCHSTACK_API_KEY production --sensitive
node -p "require('./.patchstackrc.local.json').apiKey" | npx vercel env add PATCHSTACK_API_KEY --environment production --sensitive
npx netlify env:set PATCHSTACK_API_KEY "$(node -p "require('./.patchstackrc.local.json').apiKey")" --context production --secret
```

`vercel --prod` uploads the project folder, and the Vercel CLI reads `.vercelignore`, not `.gitignore`. `go-live` on a Vercel project adds `.patchstackrc.local.json` to `.vercelignore`; if it says it could not, add the line yourself before deploying.

An app with a server needs this for runtime protection: the guard fetches its rules with the key. Without it the deploy is still recognised as long as the packages have not changed since the last scan, but nothing is protected. Never put the key in a committed file, in a public variable (`NEXT_PUBLIC_*`, `VITE_*`), or in your reply.
- **A host that builds the site itself but is not named under "How each environment is labelled"** — ChatGPT Sites (`*.chatgpt.site`, published from Codex) is one — gives Patchstack nothing that says "production", so its builds report `local` and the live site is never recognised as deployed. In that host's environment settings for the published site, set two variables: `PATCHSTACK_API_KEY`, read from `.patchstackrc.local.json` as above, and `PATCHSTACK_ENVIRONMENT=production`. Set the label only where the published build reads it, never in a committed file, and not in settings a preview or the local dev server also reads. Then publish again: the deployed site keeps serving the build from before setup until it is rebuilt.
- **Give Patchstack the live address when the host does not.** Patchstack confirms a deploy by reading the build marker off the live page, either when a visitor's browser loads the widget or through its own scheduled check of the site's address. A new site may get no visitors for days, so the scheduled check is often the only confirmation, and it can only read an address Patchstack has. Vercel, Netlify, Render and Railway production builds report their address themselves (see "Package and command behavior"). Anywhere else, including ChatGPT Sites, Lovable or Bolt, a custom domain, GitHub Pages, Cloudflare Pages or a folder uploaded by hand, take the public address from the deploy output or ask the person for it. Then:
Expand Down Expand Up @@ -1139,7 +1141,7 @@ Remove only the pieces that are actually present — check for each first. If no
4. **Remove the hooks from `package.json` scripts.** If a hook was chained (e.g. `"postbuild": "existing-command && patchstack-connect mark-build"`), remove only the `patchstack-connect …` part and keep the rest; if removal leaves a script empty, delete the key.
5. **Signal Patchstack that the package is being removed**: run `npx @patchstack/connect uninstall` (while the package is still installed and `.patchstackrc.json` still exists). If the site was never claimed, this deletes its anonymous record on Patchstack; if the site is claimed, it is only flagged — the record stays until its owner removes it in the dashboard. A failed signal must not stop the uninstall; continue with the remaining steps.
6. **Uninstall the package** with the manager matching the lockfile: `npm uninstall` / `pnpm remove` / `yarn remove` / `bun remove` `@patchstack/connect`. Don't hand-edit `node_modules` or the lockfile.
7. **Delete `.patchstackrc.json` and `.patchstackrc.local.json`** (the second holds the API key and is git-ignored, so it is present locally even when the repo shows nothing), remove the `.gitignore` entry setup added for it, and remove `PATCHSTACK_SITE_UUID`, `PATCHSTACK_API_KEY` (and public-prefixed variants like `NEXT_PUBLIC_PATCHSTACK_SITE_UUID`) from env files and CI variables.
7. **Delete `.patchstackrc.json` and `.patchstackrc.local.json`** (the second holds the API key and is git-ignored, so it is present locally even when the repo shows nothing), remove the `.gitignore` entry setup added for it (and the `.vercelignore` entry `go-live` added on Vercel), and remove `PATCHSTACK_SITE_UUID`, `PATCHSTACK_API_KEY` (and public-prefixed variants like `NEXT_PUBLIC_PATCHSTACK_SITE_UUID`) from env files and CI variables.
8. **Commit** the changes. Reporting stops immediately. On HTML shells the `window.__PATCHSTACK_PROD__` flag that `mark-build` stamped on production builds lives only in build output — the next build simply won't contain it (rebuild if build output is committed). On JSX roots and Astro layouts `scan` wrote the same marker into source; remove that managed `#region patchstack` block (or the hand-pasted equivalent) with the widget tag in step 2.

The `uninstall` signal is the only account-side effect local removal can have: it deletes an *unclaimed* (anonymous) record and merely flags a *claimed* one. A claimed site keeps using a site slot until its owner removes it in the dashboard at https://app.patchstack.com — end your report by telling the user this, alongside the site UUID from step 1. Never attempt to authenticate or remove a claimed site on the user's behalf.
Expand Down
4 changes: 3 additions & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -195,7 +195,9 @@ patchstack-connect vulns Show vulnerabilities by sever
packages, with the link to the details
patchstack-connect go-live [--host <name>] Show how to add your API key to your host
(Vercel, Netlify, Cloudflare, Render, Railway,
Fly.io, Heroku, Amplify, Replit, Lovable) and deploy
Fly.io, Heroku, Amplify, Replit, Lovable) and deploy.
On Vercel it adds .patchstackrc.local.json to
.vercelignore
patchstack-connect widget [--remove] Add the Patchstack widget to your page, or
remove the tag Connect added; saved for builds
patchstack-connect mark-build [--production] Stamp built HTML with a production flag +
Expand Down
2 changes: 1 addition & 1 deletion claude-plugin/skills/next/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,6 +29,6 @@ Run the command that matches what the person said, in the project root, and show
| "What did Patchstack find?", "show me the vulnerabilities" | `npx @patchstack/connect vulns` |
| "Show my Patchstack summary" | `npx @patchstack/connect summary` |

`next` checks with Patchstack whether the account is connected, so it sends the project's site ID; the others read the project only. None of them starts, builds or deploys the app, and you should not either: deploying is the person's step, and `go-live` prints how to do it on their host.
`next` checks with Patchstack whether the account is connected, so it sends the project's site ID; the others read the project only, except that `go-live` on a Vercel project adds `.patchstackrc.local.json` to `.vercelignore` so a `vercel` deploy does not upload the key. None of them starts, builds or deploys the app, and you should not either: deploying is the person's step, and `go-live` prints how to do it on their host.

If the project has no `.patchstackrc.json`, Patchstack is not set up here yet: use the `setup` skill.
12 changes: 9 additions & 3 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,7 @@ import {
} from './demo.js';
import {
SECRET_CONFIG_FILENAME,
ensureVercelIgnored,
credentialInCommittedConfig,
persistApiKey,
secretFileIgnored,
Expand Down Expand Up @@ -227,7 +228,8 @@ Usage:
host and deploy: the host is found from project
files (vercel.json, netlify.toml, fly.toml, ...)
or named with --host. Never prints the key.
Sends nothing; writes nothing
Sends nothing. On Vercel it adds
.patchstackrc.local.json to .vercelignore
patchstack-connect widget [--remove] Add the Patchstack widget to the project's page,
or take the Connect-added tag out with --remove.
Saves the choice in .patchstackrc.json so the
Expand Down Expand Up @@ -1953,7 +1955,10 @@ async function runWidget(args: ParsedArgs): Promise<number> {
return 0;
}

/** How to add the key to this project's host and deploy. Reads project files only; sends nothing. */
/**
* How to add the key to this project's host and deploy. Sends nothing; on Vercel it adds the credential file
* to `.vercelignore`, because the Vercel CLI uploads whatever that file does not exclude.
*/
async function runGoLive(args: ParsedArgs): Promise<number> {
const named = getStringFlag(args.flags, 'host');
let host = null;
Expand All @@ -1970,7 +1975,8 @@ async function runGoLive(args: ParsedArgs): Promise<number> {
console.error(`No ${SECRET_CONFIG_FILENAME} here yet. Run setup first: npx @patchstack/connect setup`);
return 1;
}
for (const line of renderGoLive(host, { useColor: useColor() })) console.log(line);
const vercelIgnore = host === 'vercel' ? await ensureVercelIgnored(process.cwd()) : undefined;
for (const line of renderGoLive(host, { useColor: useColor(), vercelIgnore })) console.log(line);
return 0;
}

Expand Down
35 changes: 26 additions & 9 deletions src/config.ts
Original file line number Diff line number Diff line change
Expand Up @@ -350,25 +350,31 @@ async function writeAtomicFile(target: string, content: string, mode: number): P
}

/**
* Add a line to the project's `.gitignore` if it is not already covered, and report whether it now is.
* Add a line to the project's `.gitignore` (or another ignore file in the same syntax) if it is not
* already covered, and report whether it now is.
*
* Deliberately conservative about the file: it appends one entry and never rewrites or reorders what is
* there. A missing `.gitignore` is created, because a project without one is exactly the project that
* would commit this.
* there. A missing file is created, because a project without one is exactly the project that would
* commit (or upload) this.
*
* Not conservative about the ANSWER. Every failure — unreadable file, unwritable file, an entry that is
* there but negated further down — comes back as `ignored: false` with a reason, because the caller's next
* line is either an assurance or a warning and it has to be the right one.
*/
export async function ensureIgnored(cwd: string, entry: string, label = 'Patchstack credential — never commit this'): Promise<{ ignored: boolean; reason?: string }> {
const target = path.join(cwd, '.gitignore');
export async function ensureIgnored(
cwd: string,
entry: string,
label = 'Patchstack credential — never commit this',
file = '.gitignore',
): Promise<{ ignored: boolean; reason?: string }> {
const target = path.join(cwd, file);
let existing = '';
try {
existing = await readFile(target, 'utf8');
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;
if (code !== 'ENOENT') {
return { ignored: false, reason: `.gitignore could not be read (${code ?? 'unknown error'})` };
return { ignored: false, reason: `${file} could not be read (${code ?? 'unknown error'})` };
}
}

Expand All @@ -381,7 +387,7 @@ export async function ensureIgnored(cwd: string, entry: string, label = 'Patchst
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;

return { ignored: false, reason: `.gitignore could not be written (${code ?? 'unknown error'})` };
return { ignored: false, reason: `${file} could not be written (${code ?? 'unknown error'})` };
}

// Read back rather than assume. The write can succeed and still not produce coverage — a symlink into a
Expand All @@ -390,14 +396,25 @@ export async function ensureIgnored(cwd: string, entry: string, label = 'Patchst
const written = await readFile(target, 'utf8');
if (ignoresEntry(written, entry)) return { ignored: true };

return { ignored: false, reason: '.gitignore does not cover the file after writing it' };
return { ignored: false, reason: `${file} does not cover the file after writing it` };
} catch (err) {
const code = (err as NodeJS.ErrnoException).code;

return { ignored: false, reason: `.gitignore could not be read back (${code ?? 'unknown error'})` };
return { ignored: false, reason: `${file} could not be read back (${code ?? 'unknown error'})` };
}
}

/**
* Keep the credential file out of a `vercel` CLI deploy.
*
* The Vercel CLI uploads the project folder and reads `.vercelignore`, not `.gitignore`, and its built-in
* ignore list does not cover this file — so without the entry, `vercel --prod` ships the API key with the
* deployment's source.
*/
export async function ensureVercelIgnored(cwd: string): Promise<{ ignored: boolean; reason?: string }> {
return ensureIgnored(cwd, SECRET_FILENAME, 'Patchstack credential — never upload this', '.vercelignore');
}

/**
* Whether the project currently ignores the credential file.
*
Expand Down
Loading