From 34871032b7567ab8641218d983af46771514597f Mon Sep 17 00:00:00 2001
From: Dave Jong <dave.jong@patchstack.com>
Date: Wed, 15 Jul 2026 17:00:59 +0200
Subject: [PATCH] feat(protect): generic scaffold + wiring plan + `protect
 --check` (infra-free agent loop)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Close the "unmatched stack" gap without a hosted server or saas/hub: the CLI itself is the
channel to the builder's agent (it already runs the CLI and reads stdout).

- Unmatched stack no longer returns bare "unsupported" — `runProtect` scaffolds a
  framework-agnostic guard (templates/generic-guard.ts → src/patchstack/{guard.ts,rules.json})
  and prints a wiring plan with best-effort server-entry detection (candidate files + Express).
  The generic guard exposes protectFetch(handler) (Web-Fetch) and patchstackMiddleware (Node/Express).
- `protect --check` (runVerify): inspects the app and reports whether the guard is wired, exit 1
  if not — the feedback half of a wire-then-verify loop the agent (or CI) drives. Adapters own
  their verify(); the generic path checks the guard is scaffolded AND imported into a source file.
- Adapter interface gains verify(); tanstack-supabase implements it (guard/client/start checks).
- AGENT-INSTALL documents the loop: auto-wire known stacks; otherwise scaffold → wire per plan →
  `--check` to confirm. No MCP, no backend — all in the npm package.

+3 tests (generic scaffold+plan, verify not-wired→wired, tanstack verify). Verified end-to-end via
the shipped CLI. 447 tests pass, typecheck + build clean.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
---
 AGENT-INSTALL.md                              |   2 +-
 src/cli.ts                                    |  21 ++-
 .../install/adapters/tanstack-supabase.ts     |  20 ++-
 src/protect/install/generic.ts                | 123 ++++++++++++++++++
 src/protect/install/index.ts                  |  31 +++--
 src/protect/install/types.ts                  |  20 +++
 src/protect/templates/generic-guard.ts        |  48 +++++++
 tests/protect/install.test.ts                 |  25 ++--
 tests/protect/verify-and-plan.test.ts         |  53 ++++++++
 9 files changed, 314 insertions(+), 29 deletions(-)
 create mode 100644 src/protect/install/generic.ts
 create mode 100644 src/protect/templates/generic-guard.ts
 create mode 100644 tests/protect/verify-and-plan.test.ts

diff --git a/AGENT-INSTALL.md b/AGENT-INSTALL.md
index 2b556bf..7c72d2e 100644
--- a/AGENT-INSTALL.md
+++ b/AGENT-INSTALL.md
@@ -8,7 +8,7 @@ This versioned reference ships inside `@patchstack/connect` and documents each s
 - It reads the project's **dependency list only** — from the lockfile (`package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`) or, on bun projects (`bun.lock`/`bun.lockb`), by enumerating the installed packages under `node_modules/` — and sends package names + versions to Patchstack for vulnerability matching. No source code, no env var values, no file paths, no git history. (`mark-build` additionally stamps built HTML with a coarse stack descriptor that may include hosting-related env variable *names* — e.g. `VERCEL`, `CF_PAGES` — never their values.)
 - **`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, currently for TanStack Start + Supabase apps; its templates live under `dist/protect/`). It patches the app's Supabase client to route traffic through a same-origin guard — and it runs **only** when explicitly invoked; `scan`, `setup`, `guide`, `status`, and `mark-build` never invoke it. Passing `--demo` seeds a broad sample rule set (for demonstrations, not production) instead of the default starter rules; it writes only local files.
+- 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. On a **TanStack Start + Supabase** app it auto-wires the guard (patches the Supabase client + `src/start.ts`). 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).
 - 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/src/cli.ts b/src/cli.ts
index 7f7db3b..31d46a3 100644
--- a/src/cli.ts
+++ b/src/cli.ts
@@ -17,7 +17,7 @@ import {
   installCommand,
   renderGuideChecklist,
 } from './guide.js';
-import { runProtect } from './protect/install/index.js';
+import { runProtect, runVerify } from './protect/install/index.js';
 import { wireBuildScripts } from './setup.js';
 import { detectStack, type StackDescriptor } from './stack.js';
 import { PatchstackError } from './types.js';
@@ -43,11 +43,14 @@ Usage:
   patchstack-connect mark-build [options]            Stamp built HTML with a production flag +
                                                      build fingerprint, and ensure the widget
                                                      tag in built pages (run as a postbuild step)
-  patchstack-connect protect [--demo]                Install always-on runtime protection (the
-                                                     guard) into a TanStack Start + Supabase app.
-                                                     Covers the browser + server-function paths.
+  patchstack-connect protect [--demo|--check]        Install always-on runtime protection (the
+                                                     guard). Auto-wires known stacks (TanStack
+                                                     Start + Supabase); 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 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
@@ -305,6 +308,16 @@ function reportSourceWidget(siteUuid: string): void {
 }
 
 async function runProtectCommand(args: ParsedArgs): Promise<number> {
+  // `--check`: verify the guard is wired (for the agent/CI loop). Non-zero exit if not.
+  if (args.flags.get('check') === true) {
+    const report = runVerify(process.cwd());
+    console.log(`patchstack protect --check (${report.stack}):`);
+    for (const c of report.checks) {
+      console.log(`  ${c.ok ? '✓' : '✗'} ${c.label}${!c.ok && c.hint ? ` — ${c.hint}` : ''}`);
+    }
+    console.log(report.wired ? 'guard is wired ✓' : 'guard is NOT fully wired ✗');
+    return report.wired ? 0 : 1;
+  }
   // Best-effort: like mark-build, this runs during builds and must never fail one.
   const demo = args.flags.get('demo') === true;
   try {
diff --git a/src/protect/install/adapters/tanstack-supabase.ts b/src/protect/install/adapters/tanstack-supabase.ts
index d4768f0..6da6a0d 100644
--- a/src/protect/install/adapters/tanstack-supabase.ts
+++ b/src/protect/install/adapters/tanstack-supabase.ts
@@ -8,7 +8,7 @@
 import { writeFileSync, existsSync, mkdirSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
 import { read, log, templatesDir } from '../util.js';
-import type { Adapter, WireOptions, WireResult } from '../types.js';
+import type { Adapter, WireOptions, WireResult, VerifyResult } from '../types.js';
 
 const CLIENT_TUNNEL = [
   '',
@@ -249,9 +249,27 @@ function wire(cwd: string, opts: WireOptions): WireResult {
   return { ok: true, changed: [...new Set(changed)] };
 }
 
+function verify(cwd: string): VerifyResult {
+  const guardPath = join(cwd, GUARD_FILE);
+  const clientPath = join(cwd, 'src/integrations/supabase/client.ts');
+  const startPath = join(cwd, 'src/start.ts');
+  const guard = existsSync(guardPath) ? read(guardPath) : '';
+  const client = existsSync(clientPath) ? read(clientPath) : '';
+  const start = existsSync(startPath) ? read(startPath) : '';
+
+  const checks = [
+    { label: 'guard.ts scaffolded', ok: guard.length > 0, hint: 'run `patchstack-connect protect`' },
+    { label: 'Supabase client tunnels through the guard', ok: client.includes('x-ps-target'), hint: 'run `patchstack-connect protect` to re-patch src/integrations/supabase/client.ts' },
+    { label: 'request middleware defined + registered', ok: start.includes('const patchstackGuard =') && start.includes('requestMiddleware: [patchstackGuard'), hint: 'run `patchstack-connect protect` to re-patch src/start.ts' },
+    { label: 'server-function middleware defined + registered', ok: start.includes('const patchstackFunctionGuard =') && start.includes('functionMiddleware: [patchstackFunctionGuard'), hint: 'run `patchstack-connect protect` to re-patch src/start.ts' },
+  ];
+  return { wired: checks.every((c) => c.ok), checks };
+}
+
 export const tanstackSupabaseAdapter: Adapter = {
   name: 'tanstack-supabase',
   label: 'TanStack Start + Supabase',
   detect,
   wire,
+  verify,
 };
diff --git a/src/protect/install/generic.ts b/src/protect/install/generic.ts
new file mode 100644
index 0000000..70178f7
--- /dev/null
+++ b/src/protect/install/generic.ts
@@ -0,0 +1,123 @@
+// Generic fallback for stacks no built-in adapter matches. Rather than silently skip, we scaffold
+// a framework-agnostic guard, print a wiring plan (with best-effort entry-point detection), and
+// provide a `--check` verifier — so the builder's own agent can finish the wiring and confirm it,
+// entirely through the CLI (no server, no hosted infra).
+
+import { readFileSync, existsSync, mkdirSync, copyFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { read, templatesDir } from './util.js';
+import type { WireOptions, VerifyResult } from './types.js';
+
+const GUARD_MARKER = 'patchstack/guard';
+
+function genericDir(cwd: string): string {
+  return existsSync(join(cwd, 'src')) ? 'src/patchstack' : 'patchstack';
+}
+
+export function scaffoldGeneric(cwd: string, opts: WireOptions): { changed: string[]; dir: string } {
+  const templates = templatesDir();
+  const dir = genericDir(cwd);
+  const dst = join(cwd, dir);
+  mkdirSync(dst, { recursive: true });
+  copyFileSync(join(templates, 'generic-guard.ts'), join(dst, 'guard.ts'));
+  const changed = [`${dir}/guard.ts`];
+  const rulesDst = join(dst, 'rules.json');
+  if (opts.demo || !existsSync(rulesDst)) {
+    copyFileSync(join(templates, opts.demo ? 'demo-rules.json' : 'rules.json'), rulesDst);
+    changed.push(`${dir}/rules.json`);
+  }
+  return { changed, dir };
+}
+
+// Best-effort: likely server entry files + whether Express is a dependency.
+function candidateEntries(cwd: string): string[] {
+  const names = [
+    'src/server.ts', 'src/server.js', 'src/index.ts', 'src/index.js', 'src/app.ts', 'src/app.js',
+    'src/main.ts', 'server.ts', 'server.js', 'index.ts', 'index.js', 'app.ts', 'app.js',
+  ];
+  const hits = names.filter((n) => existsSync(join(cwd, n)));
+  try {
+    const pkg = JSON.parse(read(join(cwd, 'package.json')));
+    if (typeof pkg.main === 'string' && existsSync(join(cwd, pkg.main))) hits.push(pkg.main);
+  } catch {
+    /* ignore */
+  }
+  return [...new Set(hits)];
+}
+
+function usesExpress(cwd: string): boolean {
+  try {
+    const pkg = JSON.parse(read(join(cwd, 'package.json')));
+    return Boolean({ ...pkg.dependencies, ...pkg.devDependencies }.express);
+  } catch {
+    return false;
+  }
+}
+
+export function wiringPlan(cwd: string, dir: string): string {
+  const entries = candidateEntries(cwd);
+  const express = usesExpress(cwd);
+  const lines = [
+    `no built-in adapter matched this stack — scaffolded a generic guard at ${dir}/guard.ts + ${dir}/rules.json.`,
+    'Finish by wiring it into your server (pick the one that fits):',
+    `  • Web-Fetch entry:  export default { fetch: protectFetch(yourHandler) }   // import from "${dir}/guard"`,
+    `  • Node / Express:   app.use(patchstackMiddleware)                          // add before your routes`,
+    entries.length
+      ? `Likely server ${entries.length === 1 ? 'entry' : 'entries'}: ${entries.join(', ')}${express ? '  (Express detected)' : ''}.`
+      : 'Could not locate a server entry — wire it wherever requests enter your app.',
+    'Then confirm it is hooked up:  npx patchstack-connect protect --check',
+  ];
+  return lines.join('\n');
+}
+
+export function genericVerify(cwd: string): VerifyResult {
+  const dir = genericDir(cwd);
+  const scaffolded = existsSync(join(cwd, dir, 'guard.ts'));
+  const imported = scaffolded && guardIsImported(cwd, join(cwd, dir, 'guard.ts'));
+  return {
+    wired: scaffolded && imported,
+    checks: [
+      { label: 'generic guard scaffolded', ok: scaffolded, hint: 'run `patchstack-connect protect`' },
+      {
+        label: 'guard imported into a server entry',
+        ok: imported,
+        hint: `import { protectFetch } (or patchstackMiddleware) from "${dir}/guard" and wire it into your request path`,
+      },
+    ],
+  };
+}
+
+function guardIsImported(cwd: string, guardPath: string): boolean {
+  const root = existsSync(join(cwd, 'src')) ? join(cwd, 'src') : cwd;
+  let found = false;
+  const walk = (d: string): void => {
+    if (found) return;
+    let entries: string[];
+    try {
+      entries = readdirSync(d);
+    } catch {
+      return;
+    }
+    for (const name of entries) {
+      if (found) return;
+      if (name === 'node_modules' || name.startsWith('.')) continue;
+      const p = join(d, name);
+      let st;
+      try {
+        st = statSync(p);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) walk(p);
+      else if (/\.(?:ts|tsx|js|jsx|mjs|cjs)$/.test(name) && p !== guardPath) {
+        try {
+          if (readFileSync(p, 'utf8').includes(GUARD_MARKER)) found = true;
+        } catch {
+          /* ignore */
+        }
+      }
+    }
+  };
+  walk(root);
+  return found;
+}
diff --git a/src/protect/install/index.ts b/src/protect/install/index.ts
index 60d2c06..7fcf3e9 100644
--- a/src/protect/install/index.ts
+++ b/src/protect/install/index.ts
@@ -8,7 +8,8 @@
 
 import { log } from './util.js';
 import { tanstackSupabaseAdapter } from './adapters/tanstack-supabase.js';
-import type { Adapter, WireOptions, ProtectResult } from './types.js';
+import { scaffoldGeneric, wiringPlan, genericVerify } from './generic.js';
+import type { Adapter, WireOptions, ProtectResult, VerifyReport } from './types.js';
 
 // Registry — order = match priority. Add new stacks here.
 const ADAPTERS: Adapter[] = [tanstackSupabaseAdapter];
@@ -16,18 +17,24 @@ const ADAPTERS: Adapter[] = [tanstackSupabaseAdapter];
 /** Scaffold + wire the runtime guard into the app at `cwd`. Best-effort — never throws. */
 export function runProtect(cwd: string, opts: WireOptions = {}): ProtectResult {
   const adapter = ADAPTERS.find((a) => a.detect(cwd));
-
-  if (!adapter) {
-    log(
-      `no built-in adapter matched this app's stack. Auto-wire currently supports: ` +
-        `${ADAPTERS.map((a) => a.label).join(', ')}. The guard engine is stack-agnostic; ` +
-        `wiring for this stack needs a new adapter or an agent-assisted install (see AGENT-INSTALL.md) — not skipped silently.`,
-    );
-    return { status: 'unsupported', supported: ADAPTERS.map((a) => a.name) };
+  if (adapter) {
+    const result = adapter.wire(cwd, opts);
+    return { status: 'wired', adapter: adapter.name, changed: result.changed };
   }
 
-  const result = adapter.wire(cwd, opts);
-  return { status: 'wired', adapter: adapter.name, changed: result.changed };
+  // No adapter matched — DON'T silently skip. Scaffold the framework-agnostic guard and print a
+  // wiring plan the builder's agent (or user) can finish, then verify with `protect --check`.
+  const { changed, dir } = scaffoldGeneric(cwd, opts);
+  const plan = wiringPlan(cwd, dir);
+  log(plan);
+  return { status: 'scaffolded', adapter: 'generic', changed, plan };
+}
+
+/** Verify the guard is correctly wired (backs `protect --check`). Fail-open — never throws. */
+export function runVerify(cwd: string): VerifyReport {
+  const adapter = ADAPTERS.find((a) => a.detect(cwd));
+  if (adapter) return { stack: adapter.label, ...adapter.verify(cwd) };
+  return { stack: 'generic', ...genericVerify(cwd) };
 }
 
-export type { Adapter, WireOptions, WireResult, ProtectResult } from './types.js';
+export type { Adapter, WireOptions, WireResult, VerifyResult, VerifyReport, ProtectResult } from './types.js';
diff --git a/src/protect/install/types.ts b/src/protect/install/types.ts
index 27acb78..57c249a 100644
--- a/src/protect/install/types.ts
+++ b/src/protect/install/types.ts
@@ -16,6 +16,18 @@ export interface WireResult {
   changed: string[];
 }
 
+export interface VerifyCheck {
+  label: string;
+  ok: boolean;
+  /** How to fix it, shown when `ok` is false. */
+  hint?: string;
+}
+
+export interface VerifyResult {
+  wired: boolean;
+  checks: VerifyCheck[];
+}
+
 export interface Adapter {
   /** Stable id, e.g. "tanstack-supabase". */
   name: string;
@@ -25,8 +37,16 @@ export interface Adapter {
   detect(cwd: string): boolean;
   /** Scaffold + wire the guard. Only called when `detect()` returned true. */
   wire(cwd: string, opts: WireOptions): WireResult;
+  /** Inspect the app and report whether the guard is correctly wired (for `protect --check`). */
+  verify(cwd: string): VerifyResult;
 }
 
 export type ProtectResult =
   | { status: 'wired'; adapter: string; changed: string[] }
+  | { status: 'scaffolded'; adapter: string; changed: string[]; plan: string }
   | { status: 'unsupported'; supported: string[] };
+
+export interface VerifyReport extends VerifyResult {
+  /** Which adapter/stack the verification ran against (or "generic"). */
+  stack: string;
+}
diff --git a/src/protect/templates/generic-guard.ts b/src/protect/templates/generic-guard.ts
new file mode 100644
index 0000000..14e523f
--- /dev/null
+++ b/src/protect/templates/generic-guard.ts
@@ -0,0 +1,48 @@
+// Patchstack runtime protection — GENERIC guard (framework-agnostic).
+//
+// Scaffolded by `patchstack-connect protect` when no built-in adapter matched your stack. Wire
+// whichever helper below fits your server into your request path (see the plan the CLI printed),
+// then run `patchstack-connect protect --check` to confirm it's hooked up. The engine ships inside
+// @patchstack/connect — nothing else to install.
+import { createProtection } from "@patchstack/connect/protect";
+import fallbackRules from "./rules.json";
+
+let _protection: Awaited<ReturnType<typeof createProtection>> | undefined;
+
+/** One memoized protection policy. Rules come from the Patchstack API per-site (cached); the
+ *  bundled rules.json is the fallback until a site UUID / token is configured. */
+export async function getProtection() {
+  if (!_protection) {
+    const mode = process.env.PATCHSTACK_MODE === "dry-run" ? "dry-run" : "block";
+    const token = process.env.PATCHSTACK_WAF_TOKEN;
+    const siteUuid = process.env.PATCHSTACK_SITE_UUID;
+    const common = { mode, egress: true } as const;
+    _protection = await createProtection(
+      siteUuid
+        ? { ...common, siteUuid, rules: fallbackRules as never, cacheDir: ".patchstack" }
+        : token
+          ? { ...common, token, cacheDir: ".patchstack" }
+          : { ...common, rules: fallbackRules as never },
+    );
+  }
+  return _protection;
+}
+
+// --- Web Fetch (Cloudflare Workers, Bun, Deno, Hono, Next edge, TanStack server.ts) ---------
+// Wrap your fetch handler:  export default { fetch: protectFetch(originalFetch) }
+export function protectFetch<H extends (request: Request, ...rest: unknown[]) => unknown>(handler: H): H {
+  return (async (request: Request, ...rest: unknown[]) => {
+    const protection = await getProtection();
+    const blocked = await protection.fetchGuard()(request);
+    if (blocked) return blocked;
+    return protection.screenResponse(await handler(request, ...rest) as Response);
+  }) as H;
+}
+
+// --- Node / Express -------------------------------------------------------------------------
+// Add before your routes:  app.use(patchstackMiddleware)
+export function patchstackMiddleware(req: unknown, res: unknown, next: (err?: unknown) => void) {
+  getProtection()
+    .then((protection) => (protection.node() as (a: unknown, b: unknown, c: (e?: unknown) => void) => void)(req, res, next))
+    .catch(() => next()); // fail open
+}
diff --git a/tests/protect/install.test.ts b/tests/protect/install.test.ts
index 3d62d90..26e01e2 100644
--- a/tests/protect/install.test.ts
+++ b/tests/protect/install.test.ts
@@ -2,7 +2,7 @@ import { describe, expect, it, beforeEach } from 'vitest';
 import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
-import { runProtect } from '../../src/protect/install/index.js';
+import { runProtect, runVerify } from '../../src/protect/install/index.js';
 
 // Scaffolder coverage for `patchstack-connect protect` (runProtect): it must detect a TanStack
 // Start + Supabase app, scaffold the guard, and patch client.ts + start.ts at the right anchors —
@@ -188,11 +188,13 @@ export const startInstance = createStart(() => ({
     expect(count(client, 'x-ps-target')).toBe(1);
   });
 
-  it('skips an unsupported stack (no @tanstack/react-start)', () => {
+  it('does not take the tanstack path for an unmatched stack (scaffolds generic instead)', () => {
     const plain = mkdtempSync(path.join(tmpdir(), 'ps-plain-'));
     writeFileSync(path.join(plain, 'package.json'), JSON.stringify({ name: 'x', dependencies: {} }));
-    runProtect(plain);
-    expect(existsSync(path.join(plain, 'src/integrations/patchstack/guard.ts'))).toBe(false);
+    const res: any = runProtect(plain);
+    expect(res.status).toBe('scaffolded'); // generic fallback, not silent skip
+    expect(existsSync(path.join(plain, 'src/integrations/patchstack/guard.ts'))).toBe(false); // not the tanstack path
+    expect(existsSync(path.join(plain, 'patchstack/guard.ts'))).toBe(true); // generic guard scaffolded
     rmSync(plain, { recursive: true, force: true });
   });
 
@@ -204,12 +206,13 @@ export const startInstance = createStart(() => ({
     expect(res.changed).toContain('src/start.ts');
   });
 
-  it('escalates (does not silently skip) on an unmatched stack', () => {
-    const plain = mkdtempSync(path.join(tmpdir(), 'ps-plain-'));
-    writeFileSync(path.join(plain, 'package.json'), JSON.stringify({ name: 'x', dependencies: {} }));
-    const res: any = runProtect(plain);
-    expect(res.status).toBe('unsupported');
-    expect(res.supported).toContain('tanstack-supabase');
-    rmSync(plain, { recursive: true, force: true });
+  it('verify reports not-wired before install and wired after (tanstack adapter)', () => {
+    let report: any = runVerify(dir);
+    expect(report.stack).toBe('TanStack Start + Supabase');
+    expect(report.wired).toBe(false); // fresh fixture, guard not installed yet
+    runProtect(dir);
+    report = runVerify(dir);
+    expect(report.wired).toBe(true);
+    expect(report.checks.every((c: any) => c.ok)).toBe(true);
   });
 });
diff --git a/tests/protect/verify-and-plan.test.ts b/tests/protect/verify-and-plan.test.ts
new file mode 100644
index 0000000..5831fc0
--- /dev/null
+++ b/tests/protect/verify-and-plan.test.ts
@@ -0,0 +1,53 @@
+import { describe, expect, it, beforeEach } from 'vitest';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync, existsSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { runProtect, runVerify } from '../../src/protect/install/index.js';
+
+// For a stack no adapter matches, `protect` scaffolds a generic guard + prints a wiring plan
+// (never silently skips), and `protect --check` (runVerify) drives the wire-then-verify loop.
+
+function genericApp(): string {
+  const dir = mkdtempSync(path.join(tmpdir(), 'ps-generic-'));
+  writeFileSync(path.join(dir, 'package.json'), JSON.stringify({ name: 'x', dependencies: { express: '^4.19.0' } }));
+  mkdirSync(path.join(dir, 'src'), { recursive: true });
+  writeFileSync(path.join(dir, 'src/server.ts'), 'export const app = {};\n');
+  return dir;
+}
+
+describe('generic scaffold + wiring plan (unmatched stack)', () => {
+  let dir: string;
+  beforeEach(() => {
+    dir = genericApp();
+    return () => rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('scaffolds a generic guard + returns a plan instead of silently skipping', () => {
+    const res: any = runProtect(dir);
+    expect(res.status).toBe('scaffolded');
+    expect(res.adapter).toBe('generic');
+    expect(res.changed).toContain('src/patchstack/guard.ts');
+    expect(existsSync(path.join(dir, 'src/patchstack/guard.ts'))).toBe(true);
+    expect(res.plan).toContain('protectFetch'); // wiring instructions
+    expect(res.plan).toContain('src/server.ts'); // detected entry
+    expect(res.plan).toContain('Express detected');
+    expect(res.plan).toContain('--check');
+  });
+
+  it('reports NOT wired until the guard is imported into a server entry, then wired', () => {
+    runProtect(dir);
+    let report: any = runVerify(dir);
+    expect(report.stack).toBe('generic');
+    expect(report.wired).toBe(false);
+    expect(report.checks.find((c: any) => c.label.includes('scaffolded')).ok).toBe(true);
+    expect(report.checks.find((c: any) => c.label.includes('imported')).ok).toBe(false);
+
+    // Simulate the agent wiring it into the entry point.
+    writeFileSync(
+      path.join(dir, 'src/server.ts'),
+      'import { protectFetch } from "./patchstack/guard";\nexport default { fetch: protectFetch(() => new Response("ok")) };\n',
+    );
+    report = runVerify(dir);
+    expect(report.wired).toBe(true);
+  });
+});