From 897f396f58a80bfdab6317c741b3c57d4aeade8b Mon Sep 17 00:00:00 2001
From: Elliot Taylor <ejntaylor@me.com>
Date: Wed, 15 Jul 2026 20:10:14 +0200
Subject: [PATCH 1/2] feat: add production virtual patch demo

---
 AGENT-INSTALL.md     |   1 +
 README.md            |  30 ++++++--
 src/cli.ts           |  96 ++++++++++++++++++++++++-
 src/client.ts        |  12 ++++
 src/demo.ts          | 160 +++++++++++++++++++++++++++++++++++++++++
 tests/client.test.ts |  21 +++++-
 tests/demo.test.ts   | 168 +++++++++++++++++++++++++++++++++++++++++++
 7 files changed, 479 insertions(+), 9 deletions(-)
 create mode 100644 src/demo.ts
 create mode 100644 tests/demo.test.ts

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index c48d595..a35843f 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -9,6 +9,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - **`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`.
 - **`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; its templates live under `dist/protect/`). It runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it, and it writes only local files. It auto-wires known stacks — **TanStack Start + Supabase** (patches the Supabase client + `src/start.ts`), **Next.js** (scaffolds `middleware.ts`), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **NestJS** (`app.use(patchstackMiddleware)` in the bootstrap), **Fastify** (`app.register(patchstackFastify)`), and **Express** (`app.use(patchstackMiddleware)`). On **any other stack** it scaffolds a framework-agnostic guard under `src/patchstack/` and prints a wiring plan — then you finish the install by importing that guard into your server entry (`protectFetch(handler)` for a Web-Fetch server, or `app.use(patchstackMiddleware)` for Node/Express) and running `patchstack-connect protect --check` to confirm it is wired (exit 1 until it is). Passing `--demo` seeds a broad sample rule set (for demonstrations, not production).
+- **`demo node-serialize` is an explicit production-backed walkthrough.** It requires `node-serialize@0.0.4` to already be present in the lockfile; it does not install the vulnerable dependency. It runs the same production `scan`, polls the configured site's public Pulse rules endpoint until rule `18843` is served, runs `protect`, verifies the generated guard, and prints exploit/benign test requests. It writes the same manifest/widget and guard files as those underlying commands. It does not start/restart the app and does not send the printed requests.
 - 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
diff --git a/README.md b/README.md
index 29a3c70..569e443 100644
--- a/README.md
+++ b/README.md
@@ -62,16 +62,23 @@ patchstack-connect guide                           Show this project's setup sta
                                                    what's missing, with tailored commands), then
                                                    print the full setup guide
 patchstack-connect protect                         Opt-in: install the always-on runtime exploit
-                                                   guard (currently TanStack Start + Supabase; it
-                                                   patches the app's Supabase client to route
-                                                   traffic through a same-origin guard). Never
-                                                   run by scan/setup/guide/mark-build.
+                                                   guard. Auto-wires supported server stacks;
+                                                   use --check to verify or --demo for local rules.
+                                                   Never run by scan/setup/guide/mark-build.
+patchstack-connect demo node-serialize             Production-backed walkthrough: require
+                                                   node-serialize@0.0.4, scan it, wait for live
+                                                   rule 18843, install + verify the runtime guard,
+                                                   and print exploit/benign test requests.
 patchstack-connect help                            Print help
 
-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) Print the payload without posting
+
+Options (for demo):
+  --url <url>             Test endpoint printed at the end
+                          (default: http://localhost:3000/api/tasks)
 ```
 
 ## Configuration
@@ -101,6 +108,19 @@ Environment variables:
 
 The site UUID identifies the site; it is not a secret — the disclosure widget ships the same UUID in client-side HTML, and committing `.patchstackrc.json` is the intended workflow so every developer and CI run reports to the same site. Possession of the UUID lets someone submit dependency manifests for that site (noise, not data access). In CI setups where the file isn't committed, set `PATCHSTACK_SITE_UUID` instead.
 
+## Production virtual-patch demo
+
+The `node-serialize` scenario demonstrates dependency detection and a live, version-scoped virtual patch against a throwaway Express application. Connect/provision the project first, deliberately add the known-vulnerable package, then run:
+
+```bash
+npm install --save-exact node-serialize@0.0.4
+npx @patchstack/connect demo node-serialize
+```
+
+The demo command does not install the vulnerable package. It verifies the exact version in the lockfile, posts the production npm manifest to the configured site, polls the corresponding Pulse rules endpoint for rule `18843`, runs the normal `protect` installer, checks that the guard is wired, and prints one exploit request plus one benign control request. It never starts or restarts the application and never sends either test request itself.
+
+Use `--url http://localhost:PORT/api/tasks` when the app does not use the default `http://localhost:3000/api/tasks`. Remove the deliberately vulnerable dependency after the walkthrough.
+
 ## The disclosure widget
 
 The widget is a floating "Report a vulnerability" button — a disclosure channel for anyone who spots a bug on the site. The connector manages its install so the UUID never has to be copied by hand:
diff --git a/src/cli.ts b/src/cli.ts
index 31d46a3..a60f5e5 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -4,6 +4,14 @@ import { scanLockfile } from './parsers/index.js';
 import { buildWirePayload } from './normalize.js';
 import { computeManifestChecksum } from './checksum.js';
 import { DEFAULT_ENDPOINT, buildClaimUrl, postManifest } from './client.js';
+import {
+  assertDemoDependency,
+  assertPersistedSiteUuid,
+  DemoError,
+  renderDemoTestCommands,
+  resolveDemoScenario,
+  waitForDemoRule,
+} from './demo.js';
 import { persistSiteUuid, resolveConfig, writeConfigFile } from './config.js';
 import {
   buildInjectionSnippet,
@@ -44,13 +52,18 @@ Usage:
                                                      build fingerprint, and ensure the widget
                                                      tag in built pages (run as a postbuild step)
   patchstack-connect protect [--demo|--check]        Install always-on runtime protection (the
-                                                     guard). Auto-wires known stacks (TanStack
-                                                     Start + Supabase); for others it scaffolds a
+                                                     guard). Auto-wires supported server stacks;
+                                                     for others it scaffolds a
                                                      generic guard + prints a wiring plan.
                                                      --demo seeds a broad sample rule set (for
                                                      demonstrations, not production).
                                                      --check verifies the guard is wired (exit 1
                                                      if not) — for the wire-then-verify loop.
+  patchstack-connect demo node-serialize [--url URL] Run the production-backed node-serialize
+                                                     walkthrough: verify the vulnerable package,
+                                                     scan it, wait for live rule 18843, install +
+                                                     verify the guard, and print test requests.
+                                                     Does not install vulnerable dependencies.
   patchstack-connect guide [--full]                  Show this project's setup status (what's done,
                                                      what's missing, with tailored commands), then
                                                      print the full setup guide. --full prints the
@@ -66,6 +79,10 @@ Options (for mark-build):
   --dir <path>            Build output directory (default: auto-detect
                           dist/ build/ out/ .output/public)
 
+Options (for demo):
+  --url <url>             Test endpoint printed at the end
+                          (default: http://localhost:3000/api/tasks)
+
 Environment:
   PATCHSTACK_SITE_UUID    Site UUID
   PATCHSTACK_ENDPOINT     API endpoint (default: https://api.patchstack.com/monitor/pulse/manifest)
@@ -82,9 +99,10 @@ Examples:
   npx @patchstack/connect scan --dry-run
   npx @patchstack/connect init 550e8400-e29b-41d4-a716-446655440000
   npx @patchstack/connect scan --site-uuid 550e8400-...-446655440000
+  npx @patchstack/connect demo node-serialize
 `;
 
-const VALUE_FLAGS = new Set(['site-uuid', 'endpoint', 'dir']);
+const VALUE_FLAGS = new Set(['site-uuid', 'endpoint', 'dir', 'url']);
 
 interface ParsedArgs {
   command: string | null;
@@ -328,6 +346,76 @@ async function runProtectCommand(args: ParsedArgs): Promise<number> {
   return 0;
 }
 
+async function runDemoCommand(args: ParsedArgs): Promise<number> {
+  try {
+    const scenario = resolveDemoScenario(args.positional[0]);
+    const cwd = process.cwd();
+    const config = await resolveConfig({
+      cwd,
+      cliSiteUuid: getStringFlag(args.flags, 'site-uuid'),
+      cliEndpoint: getStringFlag(args.flags, 'endpoint'),
+      requireSiteUuid: true,
+    });
+    if (config.environment !== 'production') {
+      throw new DemoError(
+        'The production-backed demo requires PATCHSTACK_ENVIRONMENT=production. Unset the sandbox override and try again.',
+      );
+    }
+
+    await assertPersistedSiteUuid(cwd, config.siteUuid!);
+    await assertDemoDependency(cwd, scenario);
+    console.log(`Patchstack production demo — ${scenario.packageName}@${scenario.packageVersion}`);
+    console.log(`  Site: ${config.siteUuid}`);
+    console.log('');
+    console.log('1. Report the current npm manifest');
+    const scanCode = await runScan(args, { showRemainingSetup: false });
+    if (scanCode !== 0) return scanCode;
+
+    console.log('');
+    console.log(`2. Wait for live virtual-patch rule ${scenario.ruleId}`);
+    const rule = await waitForDemoRule(config.endpoint, config.siteUuid!, scenario, {
+      requestTimeoutMs: config.timeoutMs,
+    });
+    console.log(`Rule ready: ${rule.id}${rule.title ? ` — ${rule.title}` : ''}`);
+
+    console.log('');
+    console.log('3. Install and verify the runtime guard');
+    const result = runProtect(cwd);
+    if (result.status === 'unsupported') {
+      throw new DemoError(
+        `Runtime protection is not supported for this stack. Supported: ${result.supported.join(', ')}.`,
+      );
+    }
+    console.log(`Guard installer: ${result.adapter} (${result.status})`);
+    const report = runVerify(cwd);
+    for (const check of report.checks) {
+      console.log(`  ${check.ok ? '✓' : '✗'} ${check.label}${!check.ok && check.hint ? ` — ${check.hint}` : ''}`);
+    }
+    if (!report.wired) {
+      throw new DemoError(
+        `The ${report.stack} guard is not fully wired. Complete the failed check above, then run this command again.`,
+      );
+    }
+
+    console.log('');
+    console.log('Production virtual patch is ready.');
+    console.log('');
+    console.log(
+      renderDemoTestCommands(
+        getStringFlag(args.flags, 'url') ?? 'http://localhost:3000/api/tasks',
+        scenario,
+      ),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof DemoError) {
+      console.error(`Demo error: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
 async function runGuide(args: ParsedArgs): Promise<number> {
   // The live checklist first: what this project already has and what's missing,
   // with commands tailored to it. Best-effort — a project we can't inspect
@@ -540,6 +628,8 @@ async function main(): Promise<number> {
       return runMarkBuild(args);
     case 'protect':
       return runProtectCommand(args);
+    case 'demo':
+      return runDemoCommand(args);
     case 'guide':
       return runGuide(args);
     case 'setup':
diff --git a/src/client.ts b/src/client.ts
index 9774127..2071c26 100644
--- a/src/client.ts
+++ b/src/client.ts
@@ -11,6 +11,18 @@ export function buildEndpointUrl(base: string, siteUuid?: string | null): string
     : trimmed;
 }
 
+/** Build the live Pulse rules URL corresponding to a manifest endpoint override. */
+export function buildRulesUrl(manifestEndpoint: string, siteUuid: string): string {
+  const url = new URL(manifestEndpoint);
+  const path = url.pathname.replace(/\/$/, '');
+  url.pathname = path.endsWith('/manifest')
+    ? `${path.slice(0, -'/manifest'.length)}/rules/${encodeURIComponent(siteUuid)}`
+    : `/monitor/pulse/rules/${encodeURIComponent(siteUuid)}`;
+  url.search = '';
+  url.hash = '';
+  return url.toString();
+}
+
 /**
  * Build the claim URL for a site. The claim page lives on the same origin as
  * the API endpoint, at `/monitor/claim?site=<uuid>`. Using the API endpoint's
diff --git a/src/demo.ts b/src/demo.ts
new file mode 100644
index 0000000..a1d6927
--- /dev/null
+++ b/src/demo.ts
@@ -0,0 +1,160 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+import { scanLockfile } from './parsers/index.js';
+import { buildRulesUrl } from './client.js';
+
+export interface DemoScenario {
+  name: string;
+  packageName: string;
+  packageVersion: string;
+  ruleId: number;
+  maliciousBody: Record<string, string>;
+  benignBody: Record<string, string>;
+}
+
+export interface PulseRule {
+  id?: string | number;
+  title?: string;
+  rule_v2?: unknown[];
+}
+
+export const NODE_SERIALIZE_DEMO: DemoScenario = {
+  name: 'node-serialize',
+  packageName: 'node-serialize',
+  packageVersion: '0.0.4',
+  ruleId: 18843,
+  maliciousBody: {
+    text: "_$$ND_FUNC$$_function(){require('child_process').exec('id')}()",
+  },
+  benignBody: { text: 'buy milk' },
+};
+
+const SCENARIOS = new Map([[NODE_SERIALIZE_DEMO.name, NODE_SERIALIZE_DEMO]]);
+
+export class DemoError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DemoError';
+  }
+}
+
+export function resolveDemoScenario(name: string | undefined): DemoScenario {
+  if (!name) {
+    throw new DemoError(
+      'A demo scenario is required. Available scenario: node-serialize.\n' +
+        'Usage: patchstack-connect demo node-serialize',
+    );
+  }
+  const scenario = SCENARIOS.get(name);
+  if (!scenario) {
+    throw new DemoError(`Unknown demo scenario "${name}". Available scenario: node-serialize.`);
+  }
+  return scenario;
+}
+
+export async function assertDemoDependency(cwd: string, scenario: DemoScenario): Promise<void> {
+  const manifest = await scanLockfile(cwd);
+  const versions = [
+    ...new Set(
+      manifest.packages
+        .filter((entry) => entry.name === scenario.packageName)
+        .map((entry) => entry.version),
+    ),
+  ].sort();
+  if (versions.includes(scenario.packageVersion)) return;
+
+  const found = versions.length > 0 ? ` Found: ${versions.join(', ')}.` : '';
+  throw new DemoError(
+    `${scenario.packageName}@${scenario.packageVersion} is not installed in the lockfile.${found}\n` +
+      `Add this deliberately vulnerable package first: npm install --save-exact ${scenario.packageName}@${scenario.packageVersion}`,
+  );
+}
+
+export async function assertPersistedSiteUuid(cwd: string, expectedUuid: string): Promise<void> {
+  let persisted: unknown;
+  try {
+    persisted = JSON.parse(await readFile(join(cwd, '.patchstackrc.json'), 'utf8')).siteUuid;
+  } catch {
+    throw new DemoError(
+      'The demo requires the Host-connected .patchstackrc.json. Connect Patchstack in Bolt first, then try again.',
+    );
+  }
+  if (persisted !== expectedUuid) {
+    throw new DemoError(
+      `The active site UUID (${expectedUuid}) does not match .patchstackrc.json (${String(persisted)}). ` +
+        'Remove the UUID override or reconnect this Bolt project before running the demo.',
+    );
+  }
+}
+
+interface WaitForRuleOptions {
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  requestTimeoutMs?: number;
+  fetchFn?: typeof fetch;
+  sleep?: (ms: number) => Promise<void>;
+  now?: () => number;
+}
+
+export async function waitForDemoRule(
+  manifestEndpoint: string,
+  siteUuid: string,
+  scenario: DemoScenario,
+  options: WaitForRuleOptions = {},
+): Promise<PulseRule> {
+  const timeoutMs = options.timeoutMs ?? 30_000;
+  const pollIntervalMs = options.pollIntervalMs ?? 1_000;
+  const requestTimeoutMs = options.requestTimeoutMs ?? 10_000;
+  const fetchFn = options.fetchFn ?? fetch;
+  const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+  const now = options.now ?? Date.now;
+  const started = now();
+  const rulesUrl = buildRulesUrl(manifestEndpoint, siteUuid);
+  let lastDetail = 'the rule list was empty';
+
+  do {
+    try {
+      const response = await fetchFn(rulesUrl, {
+        headers: { Accept: 'application/json', 'User-Agent': '@patchstack/connect' },
+        signal: AbortSignal.timeout(requestTimeoutMs),
+      });
+      if (response.ok) {
+        const data = (await response.json()) as { firewall?: PulseRule[] };
+        const rules = Array.isArray(data.firewall) ? data.firewall : [];
+        const matched = rules.find((rule) => String(rule.id) === String(scenario.ruleId));
+        if (matched) return matched;
+        lastDetail = `${rules.length} firewall rule(s) returned without rule ${scenario.ruleId}`;
+      } else {
+        lastDetail = `the rules API returned HTTP ${response.status}`;
+      }
+    } catch (error) {
+      lastDetail = `the rules request failed: ${(error as Error).message}`;
+    }
+
+    const remaining = timeoutMs - (now() - started);
+    if (remaining <= 0) break;
+    await sleep(Math.min(pollIntervalMs, remaining));
+  } while (now() - started <= timeoutMs);
+
+  throw new DemoError(
+    `Timed out waiting for Patchstack rule ${scenario.ruleId} for site ${siteUuid}; ${lastDetail}.`,
+  );
+}
+
+export function renderDemoTestCommands(url: string, scenario: DemoScenario): string {
+  const shellUrl = `'${url.replace(/'/g, `'\\''`)}'`;
+  const command = (body: Record<string, string>) => {
+    const encoded = Buffer.from(JSON.stringify(body)).toString('base64');
+    return `node -e "process.stdout.write(Buffer.from('${encoded}','base64'))" | curl -i -X POST --url ${shellUrl} -H "Content-Type: application/json" --data-binary @-`;
+  };
+  return [
+    'Restart the dev server so it loads the generated guard, then run:',
+    '',
+    `Blocked exploit (expect HTTP 403 and rule ${scenario.ruleId}):`,
+    command(scenario.maliciousBody),
+    '',
+    'Benign request (expect HTTP 201):',
+    command(scenario.benignBody),
+  ].join('\n');
+}
diff --git a/tests/client.test.ts b/tests/client.test.ts
index dffad57..b515dce 100644
--- a/tests/client.test.ts
+++ b/tests/client.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, describe, expect, it, vi } from 'vitest';
-import { buildClaimUrl, buildEndpointUrl, postManifest } from '../src/client.js';
+import { buildClaimUrl, buildEndpointUrl, buildRulesUrl, postManifest } from '../src/client.js';
 import { PatchstackError } from '../src/types.js';
 
 describe('buildEndpointUrl', () => {
@@ -24,6 +24,25 @@ describe('buildEndpointUrl', () => {
   });
 });
 
+describe('buildRulesUrl', () => {
+  it('maps the production manifest endpoint to the per-site rules endpoint', () => {
+    expect(
+      buildRulesUrl(
+        'https://api.patchstack.com/monitor/pulse/manifest',
+        '550e8400-e29b-41d4-a716-446655440000',
+      ),
+    ).toBe(
+      'https://api.patchstack.com/monitor/pulse/rules/550e8400-e29b-41d4-a716-446655440000',
+    );
+  });
+
+  it('preserves custom manifest paths and removes query/hash fragments', () => {
+    expect(buildRulesUrl('http://localhost:8000/custom/manifest?x=1#test', 'site/id')).toBe(
+      'http://localhost:8000/custom/rules/site%2Fid',
+    );
+  });
+});
+
 describe('buildClaimUrl', () => {
   it('uses the API endpoint origin plus /monitor/claim?site=<uuid>', () => {
     expect(
diff --git a/tests/demo.test.ts b/tests/demo.test.ts
new file mode 100644
index 0000000..4f940ec
--- /dev/null
+++ b/tests/demo.test.ts
@@ -0,0 +1,168 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import {
+  assertDemoDependency,
+  assertPersistedSiteUuid,
+  DemoError,
+  NODE_SERIALIZE_DEMO,
+  renderDemoTestCommands,
+  resolveDemoScenario,
+  waitForDemoRule,
+} from '../src/demo.js';
+
+const UUID = '550e8400-e29b-41d4-a716-446655440000';
+
+describe('demo scenarios', () => {
+  it('resolves the supported node-serialize scenario', () => {
+    expect(resolveDemoScenario('node-serialize')).toBe(NODE_SERIALIZE_DEMO);
+  });
+
+  it('rejects missing and unknown scenarios with the available name', () => {
+    expect(() => resolveDemoScenario(undefined)).toThrow(/node-serialize/);
+    expect(() => resolveDemoScenario('other')).toThrow(/node-serialize/);
+  });
+});
+
+describe('assertPersistedSiteUuid', () => {
+  let cwd: string;
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(path.join(tmpdir(), 'patchstack-demo-site-'));
+  });
+
+  afterEach(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  it('accepts the Host-created UUID in .patchstackrc.json', async () => {
+    await writeFile(path.join(cwd, '.patchstackrc.json'), JSON.stringify({ siteUuid: UUID }));
+    await expect(assertPersistedSiteUuid(cwd, UUID)).resolves.toBeUndefined();
+  });
+
+  it('rejects missing and overridden site configuration', async () => {
+    await expect(assertPersistedSiteUuid(cwd, UUID)).rejects.toThrow(
+      /Connect Patchstack in Bolt first/,
+    );
+    await writeFile(
+      path.join(cwd, '.patchstackrc.json'),
+      JSON.stringify({ siteUuid: '11111111-1111-1111-1111-111111111111' }),
+    );
+    await expect(assertPersistedSiteUuid(cwd, UUID)).rejects.toThrow(/does not match/);
+  });
+});
+
+describe('assertDemoDependency', () => {
+  let cwd: string;
+
+  beforeEach(async () => {
+    cwd = await mkdtemp(path.join(tmpdir(), 'patchstack-demo-'));
+  });
+
+  afterEach(async () => {
+    await rm(cwd, { recursive: true, force: true });
+  });
+
+  async function writeProject(version?: string) {
+    const dependencies = version ? { 'node-serialize': version } : { express: '4.21.2' };
+    await writeFile(path.join(cwd, 'package.json'), JSON.stringify({ dependencies }));
+    const packages: Record<string, object> = { '': { dependencies } };
+    if (version) packages['node_modules/node-serialize'] = { version };
+    else packages['node_modules/express'] = { version: '4.21.2' };
+    await writeFile(
+      path.join(cwd, 'package-lock.json'),
+      JSON.stringify({ name: 'demo', lockfileVersion: 3, packages }),
+    );
+  }
+
+  it('accepts the exact vulnerable version in the lockfile', async () => {
+    await writeProject('0.0.4');
+    await expect(assertDemoDependency(cwd, NODE_SERIALIZE_DEMO)).resolves.toBeUndefined();
+  });
+
+  it('does not install the package and prints the explicit prerequisite', async () => {
+    await writeProject();
+    await expect(assertDemoDependency(cwd, NODE_SERIALIZE_DEMO)).rejects.toThrow(
+      /npm install --save-exact node-serialize@0\.0\.4/,
+    );
+  });
+
+  it('rejects a different installed version', async () => {
+    await writeProject('0.0.3');
+    await expect(assertDemoDependency(cwd, NODE_SERIALIZE_DEMO)).rejects.toThrow(/Found: 0\.0\.3/);
+  });
+});
+
+describe('waitForDemoRule', () => {
+  it('polls until production rule 18843 is served', async () => {
+    const fetchFn = vi
+      .fn()
+      .mockResolvedValueOnce(new Response(JSON.stringify({ firewall: [] })))
+      .mockResolvedValueOnce(
+        new Response(JSON.stringify({ firewall: [{ id: 18843, title: 'Block node-serialize Vulnerability' }] })),
+      );
+    let now = 0;
+
+    const rule = await waitForDemoRule(
+      'https://api.patchstack.com/monitor/pulse/manifest',
+      UUID,
+      NODE_SERIALIZE_DEMO,
+      {
+        timeoutMs: 5_000,
+        pollIntervalMs: 100,
+        fetchFn,
+        now: () => now,
+        sleep: async (ms) => {
+          now += ms;
+        },
+      },
+    );
+
+    expect(rule.id).toBe(18843);
+    expect(fetchFn).toHaveBeenCalledTimes(2);
+    expect(fetchFn.mock.calls[0]?.[0]).toBe(
+      `https://api.patchstack.com/monitor/pulse/rules/${UUID}`,
+    );
+  });
+
+  it('times out with the last observed rule state', async () => {
+    const fetchFn = vi.fn().mockImplementation(async () =>
+      new Response(JSON.stringify({ firewall: [{ id: 999 }] })),
+    );
+    let now = 0;
+
+    await expect(
+      waitForDemoRule('https://api.patchstack.com/monitor/pulse/manifest', UUID, NODE_SERIALIZE_DEMO, {
+        timeoutMs: 200,
+        pollIntervalMs: 100,
+        fetchFn,
+        now: () => now,
+        sleep: async (ms) => {
+          now += ms;
+        },
+      }),
+    ).rejects.toEqual(expect.objectContaining<Partial<DemoError>>({
+      name: 'DemoError',
+      message: expect.stringContaining('1 firewall rule(s) returned without rule 18843'),
+    }));
+  });
+});
+
+describe('renderDemoTestCommands', () => {
+  it('prints a configurable endpoint and shell-safe base64 bodies', () => {
+    const output = renderDemoTestCommands(
+      "http://localhost:4000/api/tasks?name=it's",
+      NODE_SERIALIZE_DEMO,
+    );
+    expect(output).toContain("'http://localhost:4000/api/tasks?name=it'\\''s'");
+    expect(output).toContain('expect HTTP 403 and rule 18843');
+    expect(output).toContain('expect HTTP 201');
+
+    const encodedBodies = [...output.matchAll(/Buffer\.from\('([^']+)'/g)].map((match) => match[1]!);
+    expect(encodedBodies.map((body) => JSON.parse(Buffer.from(body, 'base64').toString('utf8')))).toEqual([
+      NODE_SERIALIZE_DEMO.maliciousBody,
+      NODE_SERIALIZE_DEMO.benignBody,
+    ]);
+  });
+});

From ef7f2a51e091011a33665db0bbbe296936483720 Mon Sep 17 00:00:00 2001
From: Elliot Taylor <ejntaylor@me.com>
Date: Wed, 15 Jul 2026 20:28:39 +0200
Subject: [PATCH 2/2] feat: add guided virtual patch demo

---
 AGENT-INSTALL.md   |   1 +
 README.md          |  13 ++++-
 src/cli.ts         |  41 ++++++++++++-
 src/demo.ts        | 143 +++++++++++++++++++++++++++++++++++++++++++--
 tests/demo.test.ts |  56 ++++++++++++++++++
 5 files changed, 246 insertions(+), 8 deletions(-)

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index a35843f..0697c26 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -10,6 +10,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - **`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; its templates live under `dist/protect/`). It runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it, and it writes only local files. It auto-wires known stacks — **TanStack Start + Supabase** (patches the Supabase client + `src/start.ts`), **Next.js** (scaffolds `middleware.ts`), **SvelteKit** (`src/hooks.server.ts`), **Astro** (`src/middleware.ts`), **NestJS** (`app.use(patchstackMiddleware)` in the bootstrap), **Fastify** (`app.register(patchstackFastify)`), and **Express** (`app.use(patchstackMiddleware)`). On **any other stack** it scaffolds a framework-agnostic guard under `src/patchstack/` and prints a wiring plan — then you finish the install by importing that guard into your server entry (`protectFetch(handler)` for a Web-Fetch server, or `app.use(patchstackMiddleware)` for Node/Express) and running `patchstack-connect protect --check` to confirm it is wired (exit 1 until it is). Passing `--demo` seeds a broad sample rule set (for demonstrations, not production).
 - **`demo node-serialize` is an explicit production-backed walkthrough.** It requires `node-serialize@0.0.4` to already be present in the lockfile; it does not install the vulnerable dependency. It runs the same production `scan`, polls the configured site's public Pulse rules endpoint until rule `18843` is served, runs `protect`, verifies the generated guard, and prints exploit/benign test requests. It writes the same manifest/widget and guard files as those underlying commands. It does not start/restart the app and does not send the printed requests.
+- **`demo-guide node-serialize` is the read-only companion.** It checks the Host-created site configuration and vulnerable lockfile entry, explains the complete local prepare/run/restart/prove/cleanup sequence, and prints the next exact command. It does not require a deployment and does not change files or contact Patchstack.
 - 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
diff --git a/README.md b/README.md
index 569e443..1259b1c 100644
--- a/README.md
+++ b/README.md
@@ -69,6 +69,9 @@ patchstack-connect demo node-serialize             Production-backed walkthrough
                                                    node-serialize@0.0.4, scan it, wait for live
                                                    rule 18843, install + verify the runtime guard,
                                                    and print exploit/benign test requests.
+patchstack-connect demo-guide node-serialize       Read-only, state-aware instructions for the
+                                                   local demo, including the next exact command,
+                                                   expected proof, and cleanup.
 patchstack-connect help                            Print help
 
 Options (for scan, setup, and status):
@@ -76,7 +79,7 @@ Options (for scan, setup, and status):
   --endpoint <url>        Override the API endpoint
   --dry-run               (scan only) Print the payload without posting
 
-Options (for demo):
+Options (for demo and demo-guide):
   --url <url>             Test endpoint printed at the end
                           (default: http://localhost:3000/api/tasks)
 ```
@@ -119,6 +122,14 @@ npx @patchstack/connect demo node-serialize
 
 The demo command does not install the vulnerable package. It verifies the exact version in the lockfile, posts the production npm manifest to the configured site, polls the corresponding Pulse rules endpoint for rule `18843`, runs the normal `protect` installer, checks that the guard is wired, and prints one exploit request plus one benign control request. It never starts or restarts the application and never sends either test request itself.
 
+For a read-only walkthrough that can be run before or during the demo, use:
+
+```bash
+npx @patchstack/connect demo-guide node-serialize
+```
+
+The guide inspects the Host-created site configuration and lockfile, explains that no deployment is required, shows the complete prepare → run → restart → prove → clean-up sequence, and ends with the next exact command for the project's current state. Pass the same `--url` option when the test endpoint differs from the default.
+
 Use `--url http://localhost:PORT/api/tasks` when the app does not use the default `http://localhost:3000/api/tasks`. Remove the deliberately vulnerable dependency after the walkthrough.
 
 ## The disclosure widget
diff --git a/src/cli.ts b/src/cli.ts
index a60f5e5..9deed15 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -8,6 +8,9 @@ import {
   assertDemoDependency,
   assertPersistedSiteUuid,
   DemoError,
+  inspectDemoDependency,
+  readPersistedSiteUuid,
+  renderDemoGuide,
   renderDemoTestCommands,
   resolveDemoScenario,
   waitForDemoRule,
@@ -22,6 +25,7 @@ import {
 import {
   collectGuideState,
   countRemainingSteps,
+  detectPackageManager,
   installCommand,
   renderGuideChecklist,
 } from './guide.js';
@@ -64,6 +68,9 @@ Usage:
                                                      scan it, wait for live rule 18843, install +
                                                      verify the guard, and print test requests.
                                                      Does not install vulnerable dependencies.
+  patchstack-connect demo-guide node-serialize       Show a read-only, state-aware walkthrough for
+                                                     preparing, running, proving, and cleaning up
+                                                     the production-backed local demo.
   patchstack-connect guide [--full]                  Show this project's setup status (what's done,
                                                      what's missing, with tailored commands), then
                                                      print the full setup guide. --full prints the
@@ -79,7 +86,7 @@ Options (for mark-build):
   --dir <path>            Build output directory (default: auto-detect
                           dist/ build/ out/ .output/public)
 
-Options (for demo):
+Options (for demo and demo-guide):
   --url <url>             Test endpoint printed at the end
                           (default: http://localhost:3000/api/tasks)
 
@@ -100,6 +107,7 @@ Examples:
   npx @patchstack/connect init 550e8400-e29b-41d4-a716-446655440000
   npx @patchstack/connect scan --site-uuid 550e8400-...-446655440000
   npx @patchstack/connect demo node-serialize
+  npx @patchstack/connect demo-guide node-serialize
 `;
 
 const VALUE_FLAGS = new Set(['site-uuid', 'endpoint', 'dir', 'url']);
@@ -416,6 +424,35 @@ async function runDemoCommand(args: ParsedArgs): Promise<number> {
   }
 }
 
+async function runDemoGuideCommand(args: ParsedArgs): Promise<number> {
+  try {
+    const scenario = resolveDemoScenario(args.positional[0]);
+    const cwd = process.cwd();
+    const config = await resolveConfig({ cwd });
+    const [siteUuid, dependency] = await Promise.all([
+      readPersistedSiteUuid(cwd),
+      inspectDemoDependency(cwd, scenario),
+    ]);
+    console.log(
+      renderDemoGuide({
+        scenario,
+        packageManager: detectPackageManager(cwd),
+        siteUuid,
+        dependency,
+        environment: config.environment,
+        url: getStringFlag(args.flags, 'url') ?? 'http://localhost:3000/api/tasks',
+      }),
+    );
+    return 0;
+  } catch (error) {
+    if (error instanceof DemoError) {
+      console.error(`Demo guide error: ${error.message}`);
+      return 1;
+    }
+    throw error;
+  }
+}
+
 async function runGuide(args: ParsedArgs): Promise<number> {
   // The live checklist first: what this project already has and what's missing,
   // with commands tailored to it. Best-effort — a project we can't inspect
@@ -630,6 +667,8 @@ async function main(): Promise<number> {
       return runProtectCommand(args);
     case 'demo':
       return runDemoCommand(args);
+    case 'demo-guide':
+      return runDemoGuideCommand(args);
     case 'guide':
       return runGuide(args);
     case 'setup':
diff --git a/src/demo.ts b/src/demo.ts
index a1d6927..5c7d7db 100644
--- a/src/demo.ts
+++ b/src/demo.ts
@@ -3,6 +3,7 @@ import { join } from 'node:path';
 
 import { scanLockfile } from './parsers/index.js';
 import { buildRulesUrl } from './client.js';
+import type { PackageManager } from './guide.js';
 
 export interface DemoScenario {
   name: string;
@@ -39,6 +40,34 @@ export class DemoError extends Error {
   }
 }
 
+export interface DemoDependencyState {
+  ready: boolean;
+  versions: string[];
+}
+
+export interface DemoGuideState {
+  scenario: DemoScenario;
+  packageManager: PackageManager;
+  siteUuid: string | null;
+  dependency: DemoDependencyState;
+  environment: 'production' | 'sandbox';
+  url: string;
+}
+
+const DEMO_INSTALL_COMMANDS: Record<PackageManager, string> = {
+  npm: 'npm install --save-exact node-serialize@0.0.4',
+  pnpm: 'pnpm add --save-exact node-serialize@0.0.4',
+  yarn: 'yarn add --exact node-serialize@0.0.4',
+  bun: 'bun add --exact node-serialize@0.0.4',
+};
+
+const DEMO_REMOVE_COMMANDS: Record<PackageManager, string> = {
+  npm: 'npm uninstall node-serialize',
+  pnpm: 'pnpm remove node-serialize',
+  yarn: 'yarn remove node-serialize',
+  bun: 'bun remove node-serialize',
+};
+
 export function resolveDemoScenario(name: string | undefined): DemoScenario {
   if (!name) {
     throw new DemoError(
@@ -53,7 +82,10 @@ export function resolveDemoScenario(name: string | undefined): DemoScenario {
   return scenario;
 }
 
-export async function assertDemoDependency(cwd: string, scenario: DemoScenario): Promise<void> {
+async function collectDemoDependency(
+  cwd: string,
+  scenario: DemoScenario,
+): Promise<DemoDependencyState> {
   const manifest = await scanLockfile(cwd);
   const versions = [
     ...new Set(
@@ -62,7 +94,23 @@ export async function assertDemoDependency(cwd: string, scenario: DemoScenario):
         .map((entry) => entry.version),
     ),
   ].sort();
-  if (versions.includes(scenario.packageVersion)) return;
+  return { ready: versions.includes(scenario.packageVersion), versions };
+}
+
+export async function inspectDemoDependency(
+  cwd: string,
+  scenario: DemoScenario,
+): Promise<DemoDependencyState> {
+  try {
+    return await collectDemoDependency(cwd, scenario);
+  } catch {
+    return { ready: false, versions: [] };
+  }
+}
+
+export async function assertDemoDependency(cwd: string, scenario: DemoScenario): Promise<void> {
+  const { ready, versions } = await collectDemoDependency(cwd, scenario);
+  if (ready) return;
 
   const found = versions.length > 0 ? ` Found: ${versions.join(', ')}.` : '';
   throw new DemoError(
@@ -71,11 +119,18 @@ export async function assertDemoDependency(cwd: string, scenario: DemoScenario):
   );
 }
 
-export async function assertPersistedSiteUuid(cwd: string, expectedUuid: string): Promise<void> {
-  let persisted: unknown;
+export async function readPersistedSiteUuid(cwd: string): Promise<string | null> {
   try {
-    persisted = JSON.parse(await readFile(join(cwd, '.patchstackrc.json'), 'utf8')).siteUuid;
+    const value = JSON.parse(await readFile(join(cwd, '.patchstackrc.json'), 'utf8')).siteUuid;
+    return typeof value === 'string' && value.length > 0 ? value : null;
   } catch {
+    return null;
+  }
+}
+
+export async function assertPersistedSiteUuid(cwd: string, expectedUuid: string): Promise<void> {
+  const persisted = await readPersistedSiteUuid(cwd);
+  if (persisted === null) {
     throw new DemoError(
       'The demo requires the Host-connected .patchstackrc.json. Connect Patchstack in Bolt first, then try again.',
     );
@@ -88,6 +143,82 @@ export async function assertPersistedSiteUuid(cwd: string, expectedUuid: string)
   }
 }
 
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+
+export function renderDemoGuide(state: DemoGuideState): string {
+  const { scenario } = state;
+  const install = DEMO_INSTALL_COMMANDS[state.packageManager].replace(
+    'node-serialize@0.0.4',
+    `${scenario.packageName}@${scenario.packageVersion}`,
+  );
+  const remove = DEMO_REMOVE_COMMANDS[state.packageManager].replace(
+    'node-serialize',
+    scenario.packageName,
+  );
+  const demo =
+    state.url === 'http://localhost:3000/api/tasks'
+      ? `npx @patchstack/connect demo ${scenario.name}`
+      : `npx @patchstack/connect demo ${scenario.name} --url ${shellQuote(state.url)}`;
+  const siteReady = state.siteUuid !== null;
+  const envReady = state.environment === 'production';
+  const dependencyDetail = state.dependency.ready
+    ? `${scenario.packageName}@${scenario.packageVersion} is in the lockfile`
+    : state.dependency.versions.length > 0
+      ? `found ${scenario.packageName}@${state.dependency.versions.join(', ')}; ${scenario.packageVersion} is required`
+      : `${scenario.packageName}@${scenario.packageVersion} is not in the lockfile`;
+
+  let next: string;
+  if (!siteReady) {
+    next = 'Click “Connect Patchstack” in Bolt, then run this guide again.';
+  } else if (!envReady) {
+    next = 'Unset PATCHSTACK_ENVIRONMENT (or set it to production), then run this guide again.';
+  } else if (!state.dependency.ready) {
+    next = install;
+  } else {
+    next = demo;
+  }
+
+  return [
+    `Patchstack demo guide — ${scenario.name}`,
+    '',
+    'Goal: prove that a live Patchstack virtual patch blocks the vulnerable payload while normal traffic still succeeds.',
+    'Deployment required: no. Keep the app running locally; the connector and generated guard contact Patchstack’s production API.',
+    '',
+    `1. ${siteReady ? '✓' : '○'} Connect this project from Bolt’s Host account dropdown`,
+    siteReady
+      ? `   Ready — .patchstackrc.json contains site ${state.siteUuid}.`
+      : '   Click “Connect Patchstack” in Bolt. This creates .patchstackrc.json; no separate CLI login is needed.',
+    '',
+    `2. ${state.dependency.ready ? '✓' : '○'} Add the deliberately vulnerable demo dependency`,
+    `   ${dependencyDetail}.`,
+    `   ${install}`,
+    '   Do not import or execute this package; its lockfile entry is enough for detection.',
+    '',
+    '3. ○ Run the production-backed demo setup',
+    `   ${demo}`,
+    ...(envReady
+      ? []
+      : ['   Blocked for now: this walkthrough needs PATCHSTACK_ENVIRONMENT=production.']),
+    `   This scans the npm manifest, waits for live rule ${scenario.ruleId}, installs the server guard, verifies its wiring, and prints two test requests.`,
+    '   It does not start the server or send the requests.',
+    '',
+    '4. ○ Restart the local dev server',
+    '   Restart after the demo command so the application loads the generated guard.',
+    '',
+    '5. ○ Run both requests printed by the demo command',
+    `   Exploit: expect HTTP 403 with Patchstack rule ${scenario.ruleId}.`,
+    '   Control (“buy milk”): expect HTTP 201. This proves normal traffic is not blocked.',
+    '',
+    '6. ○ Clean up the throwaway vulnerability after the demonstration',
+    `   ${remove}`,
+    '   Re-run `npx @patchstack/connect scan` so the clean manifest is reported.',
+    '',
+    `Next: ${next}`,
+  ].join('\n');
+}
+
 interface WaitForRuleOptions {
   timeoutMs?: number;
   pollIntervalMs?: number;
@@ -143,7 +274,7 @@ export async function waitForDemoRule(
 }
 
 export function renderDemoTestCommands(url: string, scenario: DemoScenario): string {
-  const shellUrl = `'${url.replace(/'/g, `'\\''`)}'`;
+  const shellUrl = shellQuote(url);
   const command = (body: Record<string, string>) => {
     const encoded = Buffer.from(JSON.stringify(body)).toString('base64');
     return `node -e "process.stdout.write(Buffer.from('${encoded}','base64'))" | curl -i -X POST --url ${shellUrl} -H "Content-Type: application/json" --data-binary @-`;
diff --git a/tests/demo.test.ts b/tests/demo.test.ts
index 4f940ec..378f763 100644
--- a/tests/demo.test.ts
+++ b/tests/demo.test.ts
@@ -6,7 +6,9 @@ import {
   assertDemoDependency,
   assertPersistedSiteUuid,
   DemoError,
+  inspectDemoDependency,
   NODE_SERIALIZE_DEMO,
+  renderDemoGuide,
   renderDemoTestCommands,
   resolveDemoScenario,
   waitForDemoRule,
@@ -79,6 +81,10 @@ describe('assertDemoDependency', () => {
   it('accepts the exact vulnerable version in the lockfile', async () => {
     await writeProject('0.0.4');
     await expect(assertDemoDependency(cwd, NODE_SERIALIZE_DEMO)).resolves.toBeUndefined();
+    await expect(inspectDemoDependency(cwd, NODE_SERIALIZE_DEMO)).resolves.toEqual({
+      ready: true,
+      versions: ['0.0.4'],
+    });
   });
 
   it('does not install the package and prints the explicit prerequisite', async () => {
@@ -94,6 +100,56 @@ describe('assertDemoDependency', () => {
   });
 });
 
+describe('renderDemoGuide', () => {
+  const base = {
+    scenario: NODE_SERIALIZE_DEMO,
+    packageManager: 'npm' as const,
+    siteUuid: UUID,
+    dependency: { ready: true, versions: ['0.0.4'] },
+    environment: 'production' as const,
+    url: 'http://localhost:3000/api/tasks',
+  };
+
+  it('explains the entire local workflow and chooses the ready next command', () => {
+    const output = renderDemoGuide(base);
+    expect(output).toContain('Deployment required: no');
+    expect(output).toContain('expect HTTP 403 with Patchstack rule 18843');
+    expect(output).toContain('expect HTTP 201');
+    expect(output).toContain('npm uninstall node-serialize');
+    expect(output).toContain('Next: npx @patchstack/connect demo node-serialize');
+  });
+
+  it('directs an unconnected project to the Bolt button first', () => {
+    const output = renderDemoGuide({ ...base, siteUuid: null });
+    expect(output).toContain('Next: Click “Connect Patchstack” in Bolt');
+    expect(output).toContain('no separate CLI login is needed');
+  });
+
+  it('uses the detected package manager when the dependency is missing', () => {
+    const output = renderDemoGuide({
+      ...base,
+      packageManager: 'pnpm',
+      dependency: { ready: false, versions: ['0.0.3'] },
+    });
+    expect(output).toContain('found node-serialize@0.0.3; 0.0.4 is required');
+    expect(output).toContain('Next: pnpm add --save-exact node-serialize@0.0.4');
+    expect(output).toContain('pnpm remove node-serialize');
+  });
+
+  it('stops on a sandbox environment before suggesting the active demo', () => {
+    const output = renderDemoGuide({ ...base, environment: 'sandbox' });
+    expect(output).toContain('Blocked for now');
+    expect(output).toContain('Next: Unset PATCHSTACK_ENVIRONMENT');
+  });
+
+  it('shell-quotes a custom endpoint in the next command', () => {
+    const output = renderDemoGuide({ ...base, url: "http://localhost:4000/api/tasks?name=it's" });
+    expect(output).toContain(
+      "demo node-serialize --url 'http://localhost:4000/api/tasks?name=it'\\''s'",
+    );
+  });
+});
+
 describe('waitForDemoRule', () => {
   it('polls until production rule 18843 is served', async () => {
     const fetchFn = vi