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: 5 additions & 5 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 | 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 |
| `go-live [--host <name>]` | Show how to deploy on the project's host. In a hosted builder (Lovable, Replit, Bolt) that is one step, the builder's own publish button, and no key is involved. On a host the person manages it is three steps: add the project's API key, commit, deploy. Adding the key is optional there: the live app gets protection rules without it, and with it what the app reports is verified. The host is read from project files (`vercel.json`, `netlify.toml`, `wrangler.toml`, `fly.toml`, `render.yaml`, `railway.json`, `amplify.yml`, `Procfile`, `.replit`, `.bolt`, 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 @@ -191,13 +191,13 @@ When the person asks for any of these after setup, run the command and pass on w
| "Check that my account is connected" / "Is it connected?" / "show me the link again" | `npx @patchstack/connect status` | The link, and whether the site is connected to an account |
| "Add the Patchstack widget to my app" / "Add the widget" | `npx @patchstack/connect widget` | Adds the Patchstack widget to the page and saves the choice |
| "Remove the widget" | `npx @patchstack/connect widget --remove` | Takes out the tag Connect added; a hand-added tag is left alone |
| The name of their host, after `next` asks where the app is hosted ("Vercel", "Netlify", …) | `npx @patchstack/connect go-live --host <name>` | The three steps for that host |
| "Help me put my app live" / "How do I go live?" / "set up my host" | `npx @patchstack/connect go-live` | Three steps for the project's host: add the key, commit, deploy |
| The name of their host, after `next` asks where the app is hosted ("Vercel", "Netlify", …) | `npx @patchstack/connect go-live --host <name>` | The steps for that host |
| "Help me put my app live" / "How do I go live?" / "set up my host" | `npx @patchstack/connect go-live` | The steps for the project's host. In a hosted builder, the one publish button and no key |
| "What is left to do?" | `npx @patchstack/connect guide` | The four steps and the next one |
| "Show my Patchstack summary" / "Show me the summary again" | `npx @patchstack/connect summary` | The summary the last setup wrote, from `.patchstack/summary.md`. Sends nothing; writes nothing |
| "Check my packages again" | `npx @patchstack/connect scan` | A fresh check of the project's packages |

Say only what the output says. Do not explain why setup could not finish a part, and do not add steps the output did not print. Never ask the person to copy their API key into a builder's settings or secrets: in an app that runs in the browser, a key saved there can end up in the published page. Never offer to wire protection in by hand when the output says no server was found. `go-live` prints the steps for the person's host when they are ready.
Say only what the output says. Do not explain why setup could not finish a part, and do not add steps the output did not print. Never ask the person for an API key or a token, and never ask them to copy one into a builder's settings or secrets. Setup creates the project's credential itself and never shows it, so the person has none to give, and none is needed to publish: the published app carries a read-only credential for its protection rules. In an app that runs in the browser, a key saved in the builder's settings can also end up in the published page. Never offer to wire protection in by hand when the output says no server was found. `go-live` prints the steps for the person's host when they are ready.

If a later `scan` says the project's API key is missing or was not accepted, run `login` as in "Recovering a lost credential — `login`". Do not ask the person for the key.

Expand Down Expand Up @@ -1078,7 +1078,7 @@ Use this when the project **already has a site** but its credential is gone or r

### In a hosted builder

In Lovable, Replit, Bolt and similar builders, `login` is the fix. In a Lovable or Replit project the CLI's missing-key and rejected-key messages say so. Elsewhere they also name `PATCHSTACK_API_KEY`: that is for CI and for hosts the person deploys to themselves, not for a builder's workspace.
In Lovable, Replit, Bolt and similar builders, `login` is the fix. In a Lovable or Replit project the CLI's missing-key and rejected-key messages say so. Elsewhere they also name `PATCHSTACK_API_KEY`: that is for CI and for hosts the person deploys to themselves, not for a builder's workspace. Publishing from a builder needs no key at all, and `go-live` there says so.

- Do not ask the person for the key, do not open the builder's secrets or environment settings for it, and do not tell them to create or copy one in the Patchstack dashboard. Setup never shows the key, so the person has none to give you; `login` writes a new one.
- If a `PATCHSTACK_API_KEY` secret was already added in the workspace, ask the person to remove it first. It is read before `.patchstackrc.local.json`, so a wrong value keeps being used after `login`.
Expand Down
7 changes: 4 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -193,9 +193,10 @@ patchstack-connect doctor [--url <live app>] Check that everything Patchst
say how to fix each problem
patchstack-connect vulns Show vulnerabilities by severity and outdated
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.
patchstack-connect go-live [--host <name>] Show how to deploy on your host (Vercel, Netlify,
Cloudflare, Render, Railway, Fly.io, Heroku,
Amplify, Replit, Bolt, Lovable). A hosted builder
needs no key; elsewhere adding it is optional.
On Vercel it adds .patchstackrc.local.json to
.vercelignore
patchstack-connect widget [--remove] Add the Patchstack widget to your page, or
Expand Down
3 changes: 2 additions & 1 deletion claude-plugin/skills/next/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,7 @@ allowed-tools:
- Bash(npx @patchstack/connect go-live --host heroku)
- Bash(npx @patchstack/connect go-live --host amplify)
- Bash(npx @patchstack/connect go-live --host replit)
- Bash(npx @patchstack/connect go-live --host bolt)
- Bash(npx @patchstack/connect go-live --host lovable)
---

Expand All @@ -25,7 +26,7 @@ Run the command that matches what the person said, in the project root, and show
| The person says | Run |
|---|---|
| "done", "next", "what now?", "is it connected?" | `npx @patchstack/connect next` |
| The name of their host, after `next` asked where the app is hosted | `npx @patchstack/connect go-live --host <name>`, with `<name>` one of `vercel`, `netlify`, `cloudflare-pages`, `cloudflare-workers`, `render`, `railway`, `fly`, `heroku`, `amplify`, `replit`, `lovable` |
| The name of their host, after `next` asked where the app is hosted | `npx @patchstack/connect go-live --host <name>`, with `<name>` one of `vercel`, `netlify`, `cloudflare-pages`, `cloudflare-workers`, `render`, `railway`, `fly`, `heroku`, `amplify`, `replit`, `bolt`, `lovable` |
| "What did Patchstack find?", "show me the vulnerabilities" | `npx @patchstack/connect vulns` |
| "Show my Patchstack summary" | `npx @patchstack/connect summary` |

Expand Down
16 changes: 9 additions & 7 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ import {
hasWidgetChoice,
} from './config.js';
import { painter, renderBox, renderFindings, renderLogo } from './art.js';
import { detectHost, HOST_NAMES, parseHost, renderGoLive } from './go-live.js';
import { detectHost, HOST_NAMES, parseHost, renderGoLive, stepsReadKeyFile } from './go-live.js';
import { createSiteProject, installedCli, installSelf, isPlainHtmlSite, runInstalledSetup } from './bootstrap.js';
import {
buildInjectionSnippet,
Expand Down Expand Up @@ -224,11 +224,13 @@ Usage:
outdated packages, with the link to the
details. Sends the site UUID to the public
claim page; writes nothing
patchstack-connect go-live [--host <name>] Show how to add the project's API key to its
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. On Vercel it adds
patchstack-connect go-live [--host <name>] Show how to deploy on the project's host. A
hosted builder (Lovable, Replit, Bolt) needs no
key; elsewhere adding the project's API key is
an optional first step. The host is found from
project files (vercel.json, netlify.toml,
fly.toml, ...) or named with --host. Never
prints the key. 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.
Expand Down Expand Up @@ -1971,7 +1973,7 @@ async function runGoLive(args: ParsedArgs): Promise<number> {
} else {
host = detectHost(process.cwd());
}
if (host !== 'lovable' && !existsSync(path.join(process.cwd(), SECRET_CONFIG_FILENAME))) {
if (stepsReadKeyFile(host) && !existsSync(path.join(process.cwd(), SECRET_CONFIG_FILENAME))) {
console.error(`No ${SECRET_CONFIG_FILENAME} here yet. Run setup first: npx @patchstack/connect setup`);
return 1;
}
Expand Down
52 changes: 38 additions & 14 deletions src/go-live.ts
Original file line number Diff line number Diff line change
@@ -1,4 +1,9 @@
// `go-live`: how to put the project's API key on its host and deploy, for the host this project uses.
// `go-live`: how to deploy, for the host this project uses, and how to put the project's API key on a host
// that takes one.
//
// The key is optional everywhere. A published app carries a read-only credential in its guard's rules file,
// which is enough to fetch protection rules. A hosted builder publishes without the key, so its steps never
// mention one: the person there has never been shown a key and has nothing to paste.
//
// The key is never printed. Every command reads it from the git-ignored credential file at the moment it
// runs, and a host that is set up in its dashboard is told where the value is, so the key does not pass
Expand All @@ -22,6 +27,7 @@ export type Host =
| 'heroku'
| 'amplify'
| 'replit'
| 'bolt'
| 'lovable';

export const HOST_NAMES: Record<Host, string> = {
Expand All @@ -35,6 +41,7 @@ export const HOST_NAMES: Record<Host, string> = {
heroku: 'Heroku',
amplify: 'AWS Amplify',
replit: 'Replit',
bolt: 'Bolt',
lovable: 'Lovable',
};

Expand All @@ -58,6 +65,8 @@ const HOST_ALIASES: Record<string, Host> = {
aws: 'amplify',
'aws amplify': 'amplify',
replit: 'replit',
bolt: 'bolt',
'bolt.new': 'bolt',
lovable: 'lovable',
};

Expand Down Expand Up @@ -92,6 +101,7 @@ export function detectHost(cwd: string, env: EnvLike = process.env): Host | null
if (has('amplify.yml')) return 'amplify';
if (has('Procfile')) return 'heroku';
if (has('.replit')) return 'replit';
if (has('.bolt')) return 'bolt';

const builder = detectHostedBuilder(cwd);
if (builder === 'lovable') return 'lovable';
Expand Down Expand Up @@ -124,7 +134,25 @@ interface HostGuide {

const DASHBOARD_VALUE = 'Use the apiKey value from .patchstackrc.local.json.';

const GUIDES: Record<Exclude<Host, 'lovable'>, HostGuide> = {
/**
* Hosted builders, which publish the app themselves and without the project's key. Each has the one
* button its owner presses.
*/
const BUILDER_PUBLISH: Record<'lovable' | 'replit' | 'bolt', string> = {
lovable: 'Click Publish in Lovable',
replit: 'Click Deploy (or Redeploy) in Replit',
bolt: 'Click Publish in Bolt',
};

/**
* Whether this host's steps read the key from the credential file. Only then does the file have to exist:
* a builder's workspace may not keep it, and its steps never use it.
*/
export function stepsReadKeyFile(host: Host | null): boolean {
return host !== null && !(host in BUILDER_PUBLISH);
}

const GUIDES: Record<Exclude<Host, keyof typeof BUILDER_PUBLISH>, HostGuide> = {
vercel: {
addKey: { command: `${KEY_PIPE} npx vercel env add PATCHSTACK_API_KEY --environment production --sensitive` },
deploy: 'Push to your production branch, or run: npx vercel --prod',
Expand Down Expand Up @@ -161,10 +189,6 @@ const GUIDES: Record<Exclude<Host, 'lovable'>, HostGuide> = {
addKey: { steps: 'In the Amplify console, open your app → Environment variables, and add PATCHSTACK_API_KEY.' },
deploy: 'Push to your production branch',
},
replit: {
addKey: { steps: 'In Replit, open Secrets and add PATCHSTACK_API_KEY. Deployments use the same Secrets.' },
deploy: 'Click Deploy (or Redeploy)',
},
};

export interface GoLiveOptions {
Expand Down Expand Up @@ -197,26 +221,26 @@ export function renderGoLive(host: Host | null, options: GoLiveOptions): string[
'',
...hostMenu().map(({ command, name }) => ` ${paint('cyan', command)} ${paint('dim', name)}`),
'',
paint('dim', 'Somewhere else? Add PATCHSTACK_API_KEY to its environment variables, then deploy.'),
paint('dim', DASHBOARD_VALUE),
paint('dim', 'Somewhere else? Deploy as you normally do. No key is needed.'),
paint('dim', 'On a host you manage yourself, adding PATCHSTACK_API_KEY to its environment variables is optional.'),
];
}

const name = HOST_NAMES[host];
const lines: string[] = [paint('bold', `Go live on ${name}`), ''];

if (host === 'lovable') {
if (host in BUILDER_PUBLISH) {
lines.push(
` ${paint('cyan', '1.')} ${paint('bold', 'Click Publish in Lovable')}`,
` ${paint('dim', 'Lovable publishes without your key, so Patchstack recognises a publish of packages it has already seen.')}`,
` ${paint('dim', 'Changed your packages since? Run npx @patchstack/connect scan in Lovable first.')}`,
` ${paint('cyan', '1.')} ${paint('bold', BUILDER_PUBLISH[host as keyof typeof BUILDER_PUBLISH])}`,
` ${paint('dim', `There is no key to add. ${name} publishes without one, and your app already carries what it needs to get protection rules.`)}`,
` ${paint('dim', `Changed your packages since? Run npx @patchstack/connect scan in ${name} first.`)}`,
);
return lines;
}

const guide = GUIDES[host];
const guide = GUIDES[host as keyof typeof GUIDES];
lines.push(` ${paint('cyan', '1.')} ${paint('bold', `Add your Patchstack key to ${name}`)}`);
lines.push(` ${paint('dim', 'Your live app uses it to report its packages and fetch protection rules.')}`);
lines.push(` ${paint('dim', 'Optional. Your live app gets protection rules without it; with the key, what it reports is verified.')}`);
if ('command' in guide.addKey) {
lines.push(` ${paint('cyan', guide.addKey.command)}`);
} else {
Expand Down
Loading