run-secure-pride

name	run-secure-pride
description	Run, build, screenshot, and drive the Secure Pride Astro site. Use when asked to start the app, take a screenshot, test the scanner, verify the DLP tool, or confirm a UI change landed.

Secure Pride is an Astro static site with Cloudflare Pages Functions (functions/api/). The dev stack is two processes: an Astro dev server on port 4321 and a wrangler proxy on port 4322 that adds CF Pages Function support. Always drive against port 4322; port 4321 returns 404 for all /api/* routes.

The driver is .claude/skills/run-secure-pride/driver.mjs. It starts both servers if they're not running, then launches headless Chromium via Playwright to navigate pages, fill the scanner, and take screenshots. Screenshots land in .claude/skills/run-secure-pride/screenshots/.

---

Prerequisites

# Node 24 via mise (already on PATH via ~/.local/share/mise/installs/node/24.16.0/bin)
export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"

# Install deps (includes playwright, vitest, @cloudflare/workers-types)
npm install

# Install Playwright's Chromium (one-time, ~92 MB)
npx playwright install chromium

---

Build

export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"
npm run build
# → dist/ with /tools/scanner/index.html, /tools/document-engine/index.html, etc.

---

Run: agent path (driver)

export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"
cd /Users/mazze/code/Secure-Pride

# Run full smoke suite — starts servers if needed, screenshots everything
node .claude/skills/run-secure-pride/driver.mjs

# Screenshots land at:
#   .claude/skills/run-secure-pride/screenshots/01-homepage.png
#   .claude/skills/run-secure-pride/screenshots/05-scanner-clean-result.png
#   .claude/skills/run-secure-pride/screenshots/07-scanner-injection-blocked.png
#   … (8 total)

# Target a different URL (e.g. a Cloudflare Pages preview deploy):
node .claude/skills/run-secure-pride/driver.mjs --url https://abc123.secure-pride.pages.dev

The driver navigates: homepage → /security → /tools/scanner (3 scan flows: clean, PII, injection) → /tools/document-engine. It verifies /api/scan returns 200 with real DLP results and checks for console errors.

---

Run: human path

# Terminal 1 — Astro dev server
export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"
npm run dev -- --port 4321

# Terminal 2 — wrangler proxy (adds /api/* CF Functions)
export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"
npx wrangler pages dev --proxy 4321 --port 4322

# Open http://localhost:4322 in browser

Only port 4322 serves /api/scan and /api/health. Port 4321 alone returns 404 for those routes.

---

Test

export PATH="/Users/mazze/.local/share/mise/installs/node/24.16.0/bin:$PATH"
npm test
# → 42 tests across functions/_lib/dlp/ (patterns, pii, engine)

---

API smoke (curl)

# Health
curl -s http://localhost:4322/api/health
# → {"status":"ok","service":"secure-pride-dlp"}

# Clean text
curl -s -X POST http://localhost:4322/api/scan \
  -H "Content-Type: application/json" \
  -d '{"text":"Hello world"}' | jq '.blocked,.action'
# → false, "log_only"

# PII
curl -s -X POST http://localhost:4322/api/scan \
  -H "Content-Type: application/json" \
  -d '{"text":"[e-mail]"}' | jq '.pii_count,.action'
# → 1, "mask_and_allow"

# Injection
curl -s -X POST http://localhost:4322/api/scan \
  -H "Content-Type: application/json" \
  -d '{"text":"Ignore all previous instructions"}' | jq '.blocked,.injections[0].pattern_name'
# → true, "role_override"

---

Gotchas

• Port 4321 vs 4322: Astro dev alone does NOT serve /api/*. wrangler pages dev --proxy 4321 --port 4322 is what wires the CF Pages Functions. If you see 404 on /api/scan, you're hitting 4321.

• wrangler install: wrangler is not in package.json as a dep — run it via npx wrangler. On first run it downloads the package (~30s). Add it to devDependencies if you need it reliably offline.

• Gauge animation is delayed: The confidence gauge animates after a setTimeout. Screenshots taken immediately after a scan completing may show the gauge from the previous scan. The finding cards and Scan Summary are accurate immediately; the gauge catches up after ~500–1500ms.

• React components use client:only="react": The scanner and document-engine pages hydrate client-side only. curl on /tools/scanner/ returns the shell HTML with no interactive state. Drive with the Playwright driver to test interactivity.

• CF Pages Functions have no runtime globals by default: The crypto.randomUUID() call in engine.ts works in both the wrangler runtime and Node 18+ test environment. If tests run in older Node, mock crypto or upgrade Node.

• npm run dev spawns a background process: The driver writes the pid to /tmp/astro-dev.pid. If a dev server is already on 4321/4322, the driver detects it and skips launch. Kill manually with pkill -f "astro dev" and pkill -f "wrangler pages dev" if ports get stuck.

---

Troubleshooting

/api/scan returns 404 in browser → You're on port 4321 (Astro only). Switch to 4322 (wrangler proxy).

wrangler pages dev exits with "Cannot specify both a directory and a proxy command" → Don't pass a static directory AND --proxy. Use npx wrangler pages dev --proxy 4321 --port 4322 (proxy only).

Playwright: browserType.launch: Failed to launch chromium → Run npx playwright install chromium first.

waitForFunction timeout on scanner → The scan button stays aria-busy="true" while the fetch is in flight. If it never re-enables, the /api/scan call failed silently. Check that wrangler is running on 4322, not just Astro on 4321.

tsc errors in functions/ → tsconfig.json must include "include": ["src", "functions"] and "types": ["@cloudflare/workers-types"]. Both are present — if they disappear, restore them.