Skip to content
Open
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
12 changes: 6 additions & 6 deletions AGENT-INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,7 +85,7 @@ Every command at a glance — what it does, whether it reads your source, what i
| `demo node-serialize` | Production-backed walkthrough: confirm the vulnerable package is present, scan, wait for live rule `18843`, install + verify the guard, print test requests. Does not install the package or start/restart the app. | Local integration reads via `scan` and `protect` | Same files as `scan` + `protect` | `scan` payload; polls the public Patchstack for JavaScript rules endpoint (never the printed test requests) |
| `demo-guide node-serialize` | Read-only companion: explains the prepare/run/prove/cleanup sequence and prints the next command. | Reads local protection wiring for verification | Nothing | Nothing |
| `guide` | Print this project's setup status: what is left to do and the four steps, with tailored commands. `--full` adds this reference. | Reads local protection wiring for verification | Nothing | Nothing |
| `status` | Re-print the site UUID + dashboard URL and check whether the site still exists (active / removed / could not verify) and whether it is connected to an account. | No | The connected note in `.patchstackrc.json`, when it changed | Site-existence and connection checks |
| `status` | Re-print the site UUID and its link (to connect it, or to its dashboard once connected) and check whether the site still exists (active / removed / could not verify) and whether it is connected to an account. | No | The connected note in `.patchstackrc.json`, when it changed | Site-existence and connection checks |
| `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 |
Expand Down Expand Up @@ -126,7 +126,7 @@ Runtime rule polling also has a request-triggered check, for hosts that freeze i
## Before you start — never install twice

- `npx @patchstack/connect guide` prints a read-only live checklist of the four steps (install, connect, sync, deploy) and the one next step, with any missing build hook, widget tag or runtime protection wiring listed under `To do`. Add `--verbose` to `guide`, `scan` or `setup` for the technical detail (site UUID, endpoint, environment and what decided it, checksum, files written, the exact package.json lines and the runtime protection checks).
- 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.) In a workspace repo, check the root's `.patchstackrc.json`: an app package without a `siteUuid` of its own belongs to the root's site, not to a new one.
- 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 its link. **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.) In a workspace repo, check the root's `.patchstackrc.json`: an app package without a `siteUuid` of its own belongs to the root's site, not to a new one.
- If `@patchstack/connect` is already in `dependencies`, skip the install command. If it is only in `devDependencies`, move it with the matching package manager so production runtimes that prune dev dependencies can load the generated guard.
- 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.

Expand Down Expand Up @@ -166,7 +166,7 @@ When you've connected, say **done**.
#### What Patchstack found
🔴 High **1** · 🟠 Medium **3** · 🔵 Low **1** · 12 packages outdated · 12 protection rules available

**Refresh your app's preview** to see the Patchstack widget.
**Reload your app's preview page** to see the Patchstack widget on it.

_Patchstack is now part of your install and build. Your API key is in `.patchstackrc.local.json`: git ignores it, so never share it._
````
Expand All @@ -175,9 +175,9 @@ The parts always come in that order. Fill each from the output, and leave out a

1. **Mark.** The two-line Patchstack mark in a code block, as in the layout above.
2. **Headline.** What was checked and found, as the heading. When the output gives no counts, write "Patchstack is now watching your app." Never estimate a count the output did not print.
3. **What to do now.** The next step from the `Next:` line, as the heading, with its link or command written out in full on its own line. Only that step: the items under `To do` are yours to finish, not the person's. Then: "When you've connected, say **done**." (or "When that's done, say **done**." for any other step).
3. **What to do now.** The next step from the `Next:` line, as the heading, with its link or command written out in full on its own line. Only that step: the items under `To do` are yours to finish, not the person's. Then: "When you've connected, say **done**." (or "When that's done, say **done**." for any other step). When the `Next:` step's command is `npx @patchstack/connect go-live`, write "Say **done** to get the steps for your host." instead of both the command and "When that's done, say **done**."
4. **What Patchstack found.** The severity counts, outdated packages and protection rules exactly as the output lists them. Leave it out when nothing was found: the headline already says so.
5. **Notes.** "**Refresh your app's preview** to see the Patchstack widget." when setup added the widget; any line the output marks `ℹ`, except the one about no server.
5. **Notes.** "**Reload your app's preview page** to see the Patchstack widget on it." when setup added the widget; any line the output marks `ℹ`, except the one about no server.
6. **What changed.** One line in italics: that Patchstack is now part of the install and build, and where the API key is (git ignores it; never share it).

### Commands for later
Expand Down Expand Up @@ -999,7 +999,7 @@ Three more endpoints the package can call, for completeness:

## Verifying the install

- `npx @patchstack/connect status` re-prints the site UUID and dashboard URL, and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
- `npx @patchstack/connect status` re-prints the site UUID and its link (to connect it, or to its dashboard once connected), and checks whether the site still exists on Patchstack (`Site status: active / removed / could not be verified`).
- `npx @patchstack/connect doctor` runs every check at once and prints each problem with its fix; `--url <live app>` adds the live app: whether its page names the build it runs (without that, the dashboard has to guess what is published), the widget, and a test attack.
- `npx @patchstack/connect protect --check` verifies from the source that the runtime guard is connected to the request path. It does not run the app. When the project records a site, it also fails if a guard Connect wrote does not carry it (`the guard carries this project's Patchstack site`): such a guard blocks with the rules it shipped with but fetches no rule updates and reports nothing. Run `npx @patchstack/connect protect` from the project root to fill the site in, then deploy.
- `npx @patchstack/connect protect --check --runtime` additionally **starts the app** on a loopback port and sends it one request, to establish that a request reaches the guard seam. Opt-in, and the only command that runs the application; exit `0`/`1`/`2` as described in step 4.
Expand Down
2 changes: 1 addition & 1 deletion GETTING-STARTED.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,7 +42,7 @@ Run commands from the application's package directory. In a hosted workspace, se

## 4. You're done when

- `npx @patchstack/connect status` prints a site UUID and dashboard URL.
- `npx @patchstack/connect status` prints a site UUID and its link: to connect it, or to its dashboard once connected.
- You've opened the dashboard URL in your browser and the site shows in your Patchstack dashboard.
- `npx @patchstack/connect guide` reports the expected build hooks and the Patchstack Connector, and `npx @patchstack/connect protect --check` confirms the guard's source wiring. A client-only or static project can report runtime protection as not applicable; describe it as dependency monitoring and the Patchstack Connector, not runtime protection. A source check alone does not prove deployed traffic reaches the guard.
- Your preview shows the widget (refresh it once if it does not). Before the site is attached to your account it shows the "Connect this website" panel.
Expand Down
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
Expand Up @@ -30,7 +30,7 @@ Have the assistant work in the application's package directory, reuse any existi
| Yarn | `yarn add @patchstack/connect` | `yarn exec patchstack-connect setup` | `yarn exec patchstack-connect protect --check` |
| Bun | `bun add @patchstack/connect` | `bun run patchstack-connect setup` | `bun run patchstack-connect protect --check` |

Use the same invocation with `guide --verbose` to inspect the environment, build hooks, widget, and remaining setup work, and with `status` to recover the dashboard URL. Read the actual command results before reporting completion. A declared dependency, generated scaffold, or proposed command alone does not establish a completed install. Resolve source-check failures on server applications; for a client-only site, state the protection limitation. Restart an already-running app to load the new guard and refresh the page to check the widget.
Use the same invocation with `guide --verbose` to inspect the environment, build hooks, widget, and remaining setup work, and with `status` to recover the site's link. Read the actual command results before reporting completion. A declared dependency, generated scaffold, or proposed command alone does not establish a completed install. Resolve source-check failures on server applications; for a client-only site, state the protection limitation. Restart an already-running app to load the new guard and refresh the page to check the widget.

Before an authorized deployment, preserve `.patchstackrc.json`, the dependency and lockfile changes, the install/build hooks, and the generated guard and layout edits. Keep `.patchstackrc.local.json` out of Git and configure `PATCHSTACK_API_KEY` through the deployment host's secret settings. Remove any local or workspace-only environment override from the deployment process; use the host's tier signals or the explicit [DigitalOcean build settings](#sandbox-and-production-manifests). Run the project's existing build command so both `scan` and `mark-build` execute. A successful source check establishes wiring, not that the deployed server loaded it; verify the deployed widget and server protection separately. Setup itself does not deploy the application.

Expand Down
27 changes: 18 additions & 9 deletions src/cli.ts
Original file line number Diff line number Diff line change
Expand Up @@ -1949,7 +1949,7 @@ async function runWidget(args: ParsedArgs): Promise<number> {
console.log(` ${buildWidgetTag(state.siteUuid)}`);
break;
}
console.log(` ${paint('dim', 'Refresh your preview to see it. Your live site gets it with your next deploy.')}`);
console.log(` ${paint('dim', "Reload your app's preview page to see it. Your live site gets it with your next deploy.")}`);
return 0;
}

Expand Down Expand Up @@ -1981,21 +1981,30 @@ async function runStatus(args: ParsedArgs): Promise<number> {
`Endpoint: ${config.endpoint}${config.endpoint === DEFAULT_ENDPOINT ? '' : ' (override)'}`,
);
console.log(`Timeout: ${config.timeoutMs}ms`);
console.log(`Environment: ${config.environment}`);
const describesThisMachine = config.environment !== 'production';
console.log(`Environment: ${config.environment}${describesThisMachine ? ' (where this command runs, not your live app)' : ''}`);
if (config.siteUuid !== null) {
console.log(`Dashboard URL: ${buildClaimUrl(config.endpoint, config.siteUuid)}`);

const claimState = await fetchClaimState(config);
const [claimState, siteStatus] = await Promise.all([fetchClaimState(config), fetchSiteStatus(config)]);
if (claimState !== 'unknown') await recordClaimState(config, config.siteUuid, claimState === 'claimed');
const siteLink =
config.endpointTrusted !== false && siteStatus !== 'removed' ? buildClaimUrl(config.endpoint, config.siteUuid) : null;
if (claimState === 'claimed') {
if (siteLink !== null) console.log(`Dashboard link: ${siteLink}`);
console.log('Connected: yes, to a Patchstack account');
} else if (claimState === 'unclaimed') {
console.log('Connected: not yet. Open the link above or run `npx @patchstack/connect claim`.');
} else {
console.log('Connected: could not be verified. Not connected yet? Open the link above.');
if (siteLink !== null) console.log(`Connect link: ${siteLink}`);
if (claimState === 'unclaimed') {
console.log(
siteLink !== null
? 'Connected: not yet. Open the link above or run `npx @patchstack/connect claim`.'
: 'Connected: not yet. Run `npx @patchstack/connect claim`.',
);
} else {
console.log(`Connected: could not be verified.${siteLink !== null ? ' Not connected yet? Open the link above.' : ''}`);
}
}

switch (await fetchSiteStatus(config)) {
switch (siteStatus) {
case 'active':
console.log('Site status: active on Patchstack');
break;
Expand Down
2 changes: 2 additions & 0 deletions src/protect/runtime.js
Original file line number Diff line number Diff line change
Expand Up @@ -333,6 +333,8 @@ export async function createProtection(options = {}) {
const noteRuleSource = (source) => {
ruleSource = { ...(source ?? { ok: true, origin: ruleSource.origin }) };
if (!hasLiveSource || typeof onError === 'function' || ruleSource.ok !== false) return;
const prerenderingInNextBuild = typeof process !== 'undefined' && process.env?.NEXT_PHASE === 'phase-production-build';
if (prerenderingInNextBuild) return;
const cause = `${ruleSource.origin}:${ruleSource.reason ?? ''}`;
if (warnedSources.has(cause)) return;
warnedSources.add(cause);
Expand Down
18 changes: 12 additions & 6 deletions src/report.ts
Original file line number Diff line number Diff line change
Expand Up @@ -346,11 +346,17 @@ export function renderSummary(report: StatusReport, progress: Progress, context:
const rest =
next !== 'connected' ? '' : !canProtect ? ' to see the details' : vulnerable ? ' to see the details and turn on protection' : ' to turn on protection';
const lead = next === 'connected' ? 'Connect your Patchstack account' : capitalise(plainNextStepTitle(next, context));
const [first] = plainNextStepLines(next, context);
const action = first?.startsWith('Open ') === true ? first.slice('Open '.length) : first;
// The link goes in a paragraph of its own, so it renders on its own line.
lines.push(`#### 👉 ${lead}${rest}`, '', ...(action !== undefined ? [action, ''] : []));
lines.push(next === 'connected' ? `When you've connected, say **${NEXT_REPLY}**.` : `When that's done, say **${NEXT_REPLY}**.`, '');
lines.push(`#### 👉 ${lead}${rest}`, '');
const nextAnswersWithGoLiveSteps = next === 'deployed' && context.environment !== 'production';
if (nextAnswersWithGoLiveSteps) {
lines.push(`Say **${NEXT_REPLY}** to get the steps for your host.`, '');
} else {
const [first] = plainNextStepLines(next, context);
const action = first?.startsWith('Open ') === true ? first.slice('Open '.length) : first;
// The link goes in a paragraph of its own, so it renders on its own line.
if (action !== undefined) lines.push(action, '');
lines.push(next === 'connected' ? `When you've connected, say **${NEXT_REPLY}**.` : `When that's done, say **${NEXT_REPLY}**.`, '');
}
}

if (canProtect && report.confirmed?.length) {
Expand Down Expand Up @@ -378,7 +384,7 @@ export function renderSummary(report: StatusReport, progress: Progress, context:
lines.push('#### What Patchstack found', parts.join(' · '), '');
}

if (options.widgetOnPage) lines.push("**Refresh your app's preview** to see the Patchstack widget.", '');
if (options.widgetOnPage) lines.push("**Reload your app's preview page** to see the Patchstack widget on it.", '');
// A fact about the app, not a step: the ones that matter here are what protection does not cover.
for (const item of report.missing.filter((entry) => entry.note === true && entry.key !== 'runtime-protection')) {
lines.push(item.plain?.text ?? item.text, '');
Expand Down
Loading