create-pracht 0.2.6 → 0.4.0

package/skills/add-observability/SKILL.md

@@ -0,0 +1,270 @@
+---
+name: add-observability
+version: 1.1.0
+description: |
+  Wire error tracking, request tracing, and Web Vitals into a pracht app.
+  Supports Sentry or OpenTelemetry on the server side (loader/middleware
+  boundaries, API routes), and client-side Web Vitals reporting via the
+  `web-vitals` package.
+  Use when asked to "add observability", "wire Sentry", "set up tracing",
+  "add OpenTelemetry", "monitor Web Vitals", or "track errors".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Add Observability
+
+Three layers, each opt-in:
+
+1. **Server error tracking** — capture loader/middleware/API exceptions.
+2. **Request tracing** — span per request with child spans per loader/db call.
+3. **Web Vitals (LCP/CLS/INP/FCP/TTFB)** — client-side, posted to a beacon
+   endpoint.
+
+If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
+(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`,
+`generate_*`) over shelling out. Prerequisite: `pracht inspect` needs a vite
+config with the pracht plugin registered.
+
+## Step 1: Pick the stack
+
+Use `AskUserQuestion`:
+
+- **Sentry** — easiest end-to-end (errors + traces + Web Vitals).
+- **OpenTelemetry + your backend** (Honeycomb, Grafana, Datadog, Jaeger).
+- **Custom beacon** — minimal `fetch('/api/telemetry')` setup, no SaaS.
+
+The skill below shows Sentry and OTel patterns. Custom beacon is mentioned
+but trivial.
+
+## Step 2: Server error tracking
+
+### Sentry path (Node adapter)
+
+The pattern below uses `@sentry/node` and works on the **Node adapter only**
+— see the caveat box below for Cloudflare and Vercel Edge before installing
+anything.
+
+```bash
+pnpm add @sentry/node    # Node adapter only
+```
+
+Create `src/server/observability.ts`:
+
+```ts
+import { serverEnv } from "@pracht/core/env/server";
+import * as Sentry from "@sentry/node";
+
+let initialized = false;
+export function initObservability() {
+  if (initialized) return;
+  initialized = true;
+  // serverEnv is read INSIDE this function, not at module scope — module-level
+  // env reads break on runtimes where env arrives per request (docs/ENV.md).
+  Sentry.init({
+    dsn: serverEnv.SENTRY_DSN,
+    tracesSampleRate: Number(serverEnv.SENTRY_TRACES_SAMPLE_RATE ?? 0.1),
+    environment: serverEnv.NODE_ENV,
+  });
+}
+```
+
+Add a global middleware that calls `initObservability()` once (from inside
+the handler, never at module scope) and wraps the downstream call:
+
+```ts
+// src/middleware/observability.ts
+import type { MiddlewareFn } from "@pracht/core";
+import * as Sentry from "@sentry/node";
+import { initObservability } from "../server/observability";
+
+export const middleware: MiddlewareFn = async ({ request, route }, next) => {
+  initObservability();
+  return Sentry.startSpan(
+    {
+      name: `${request.method} ${route.path}`,
+      op: "http.server",
+    },
+    () => next(),
+  );
+};
+```
+
+> **Cloudflare / Vercel Edge caveat — be honest here.** `@sentry/cloudflare`
+> requires wrapping the worker's fetch handler with `withSentry()`, but
+> pracht's Cloudflare adapter owns that handler — there is no user hook to
+> wrap it today, so the middleware-init pattern above **cannot work** with
+> `@sentry/cloudflare`, and `@sentry/node` does not run on Workers at all.
+> Do not scaffold a pattern that can't work. Options on Cloudflare:
+> 1. Plain fetch-based event forwarding: catch errors in a wrap-around
+>    middleware and `fetch` them to Sentry's store/envelope endpoint (or any
+>    HTTP sink) yourself. Read the DSN via `serverEnv` inside the middleware.
+> 2. Wait for pracht to expose a handler-wrap hook for the adapter, then use
+>    Sentry's Cloudflare SDK properly.
+>
+> The same applies to `@sentry/vercel-edge`: verify how the init hooks into
+> the runtime before installing; if it needs to own the handler, fall back to
+> option 1. (This mirrors the OTel-edge honesty note below.)
+
+Pracht middleware is wrap-around: `await next()` invokes the rest of the
+request and resolves to the final `Response`, so the span naturally covers
+the loader/handler and ends when they finish.
+
+Register it in `defineApp({ middleware: { observability: "./..." } })` (the
+top-level `middleware` field is a *registry* keyed by name — not an ordered
+chain). To actually wrap requests, place `"observability"` first in every
+chain that should cover them:
+
+```ts
+defineApp({
+  middleware: { observability: "./middleware/observability.ts", auth: "./middleware/auth.ts" },
+  api: { middleware: ["observability"] },           // all API routes
+  routes: [
+    group({ middleware: ["observability"] }, [      // all pages
+      group({ middleware: ["auth"] }, [ /* protected routes */ ]),
+    ]),
+  ],
+});
+```
+
+Ordering lives in these `middleware: [...]` arrays — always place
+observability first so it spans the rest of the chain.
+
+### OpenTelemetry path
+
+```bash
+pnpm add @opentelemetry/api @opentelemetry/sdk-trace-node @opentelemetry/auto-instrumentations-node
+```
+
+Create a SDK init module that runs at server entry — for Node, use the
+`--require ./otel.cjs` flag; for Cloudflare/Vercel edge, OTel is more limited
+(use HTTP exporter directly). Surface this trade-off; don't pretend OTel
+edge is plug-and-play.
+
+## Step 3: Loader/API tracing
+
+For each loader and API handler, wrap the body in a span.
+
+```ts
+import * as Sentry from "@sentry/node";
+
+export async function loader({ request }) {
+  return Sentry.startSpan({ name: "loader: dashboard", op: "function" }, async () => {
+    return { /* ... */ };
+  });
+}
+```
+
+Auto-injection is out of scope; provide a snippet, recommend wrapping the 5-10
+slowest loaders (cross-reference with `audit-bundles` perf hotspots).
+
+## Step 4: Web Vitals on the client
+
+```bash
+pnpm add web-vitals
+```
+
+Create `src/client/vitals.ts` — export a function, **no module-level
+side effects**:
+
+```ts
+import { onCLS, onINP, onLCP, onFCP, onTTFB, type Metric } from "web-vitals";
+
+function send(metric: Metric) {
+  navigator.sendBeacon?.(
+    "/api/telemetry/vitals",
+    JSON.stringify({ name: metric.name, value: metric.value, id: metric.id, path: location.pathname }),
+  );
+}
+
+export function reportVitals() {
+  onCLS(send);
+  onINP(send);
+  onLCP(send);
+  onFCP(send);
+  onTTFB(send);
+}
+```
+
+Do NOT import this statically from a shell: shells render on the **server**
+too, so module-level `onCLS(...)` calls would execute during SSR. The primary
+pattern is a lazy `import()` inside an effect, guarded by `useIsHydrated`
+(exported from `@pracht/core`), placed in a shell or top-level component:
+
+```tsx
+import { useIsHydrated } from "@pracht/core";
+import { useEffect } from "preact/hooks";
+
+export function Vitals() {
+  const hydrated = useIsHydrated();
+  useEffect(() => {
+    if (!hydrated) return;
+    void import("../client/vitals").then((m) => m.reportVitals());
+  }, [hydrated]);
+  return null;
+}
+```
+
+This keeps `web-vitals` out of the critical bundle (lazy chunk) and only
+starts observers after hydration has fully settled.
+
+## Step 5: Beacon endpoint
+
+```ts
+// src/api/telemetry/vitals.ts
+import type { ApiRouteArgs } from "@pracht/core";
+
+export async function POST({ request }: ApiRouteArgs) {
+  const body = await request.text();
+  // Forward to your destination (Sentry, Honeycomb, custom store).
+  // Keep body small; do not block on the upstream.
+  console.log("vitals", body);
+  return new Response(null, { status: 204 });
+}
+```
+
+For Sentry users, Sentry's browser SDK can capture Web Vitals natively —
+prefer that over a custom beacon if you've gone the Sentry route.
+
+## Step 6: Sampling and PII
+
+- Set `SENTRY_TRACES_SAMPLE_RATE` to a small number (0.05–0.10) in
+  production.
+- Scrub auth headers and cookies from breadcrumbs:
+  ```ts
+  Sentry.init({ beforeSend(event) { delete event.request?.headers?.cookie; return event; } });
+  ```
+- Never send loader return values verbatim — they often contain user data.
+
+## Step 7: Verify
+
+- Trigger a deliberate error in dev and confirm it lands in Sentry/OTel.
+- Open a route, check the Web Vitals beacon fires (Network tab).
+- Confirm `pnpm test` and `pnpm e2e` still pass.
+- Run `pracht typegen` if any routes were added (the beacon API route does
+  not affect page-route types, but re-run when in doubt).
+- Run `pracht verify --json` and confirm no failures.
+
+## Rules
+
+1. Confirm adapter compatibility before installing the SDK package
+   (Sentry has separate packages per runtime), and never scaffold a pattern
+   the runtime can't actually run — see the Cloudflare/Vercel-edge caveat in
+   Step 2. Read `SENTRY_DSN` and friends via `serverEnv` inside functions,
+   never `process.env` at module scope.
+2. Top-level `middleware` in `defineApp` is a name→path *registry*, not an
+   ordered chain. Place `"observability"` first in every `group({
+   middleware: [...] })` and in `api.middleware` so it wraps the rest.
+3. Web Vitals only matter for SSR/SSG/ISG routes that hydrate; SPA-only
+   routes still benefit but the values reflect the post-bootstrap state.
+4. Sample traces (≤ 10%) in production; full sampling in dev.
+5. Never send raw cookies, auth headers, or full loader payloads to a
+   third-party SaaS.
+
+$ARGUMENTS

package/skills/audit-a11y/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: audit-a11y
+version: 1.1.0
+description: |
+  Per-route accessibility audit for a pracht app. Drives a headless browser
+  through every route in the manifest, runs axe-core, and reports issues
+  grouped by severity and route. Catches alt-text gaps, contrast failures,
+  missing landmarks, focus-order bugs, and form-label problems.
+  Use when asked to "audit a11y", "check accessibility", "axe my app",
+  "WCAG compliance", or "screen reader test".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Audit A11y
+
+Static linting cannot prove a route is accessible — many issues only appear
+in the rendered DOM. This skill renders each route in a real browser and
+runs axe-core against the result.
+
+## Step 1: Boot the app
+
+Prefer the production build/runtime — production HTML is what users actually
+receive. `pracht preview` builds and serves it for **Node and Cloudflare**
+targets. It refuses Vercel targets (it prints guidance and exits nonzero):
+for a Vercel app, run `vercel dev` yourself or point `BASE_URL` at a deployed
+preview instead. Fall back to `pracht dev` only if the user can't build.
+
+Run the server as a managed background process, wait for readiness, and clean
+it up when the audit ends:
+
+```bash
+pracht preview &   # run in the background (use the Bash tool's background mode)
+# wait for readiness before auditing:
+until curl -sf http://localhost:3000 > /dev/null; do sleep 1; done
+```
+
+After Step 5 (or on any failure), kill the background process — do not leave
+a stray server holding the port.
+
+Or, if `BASE_URL` is set, target the deployed app and skip the local server
+entirely.
+
+## Step 2: Install runner
+
+If Playwright is already wired (see `scaffold-e2e`), reuse it. Install the
+axe adapter plus `tsx` (the Step 5 runner — it is not a pracht dependency):
+
+```bash
+pnpm add -D @axe-core/playwright tsx
+```
+
+If Playwright is not wired, scaffold a one-off script using `playwright`
+directly. Prefer Playwright over Puppeteer for consistency with existing
+project tooling.
+
+## Step 3: Enumerate routes
+
+If the pracht MCP server is registered (see docs/MCP.md), prefer its tools
+(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`) over
+shelling out.
+
+```bash
+pracht inspect routes --json
+```
+
+Prerequisite: `pracht inspect` needs a vite config with the pracht plugin
+wired up.
+
+For dynamic-segment routes, ask the user once for example params (or skip
+with a note in the report).
+
+## Step 4: Generate the audit script
+
+`scripts/audit-a11y.ts`:
+
+```ts
+import { chromium } from "playwright";
+import AxeBuilder from "@axe-core/playwright";
+
+const BASE = process.env.BASE_URL ?? "http://localhost:3000";
+const ROUTES: string[] = [/* injected from pracht inspect routes */];
+
+const browser = await chromium.launch();
+const context = await browser.newContext();
+const page = await context.newPage();
+
+const results = [];
+for (const path of ROUTES) {
+  await page.goto(`${BASE}${path}`, { waitUntil: "networkidle" });
+  const axe = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21aa", "best-practice"])
+    .analyze();
+  results.push({ path, violations: axe.violations });
+}
+
+await browser.close();
+console.log(JSON.stringify(results, null, 2));
+```
+
+## Step 5: Run and aggregate
+
+```bash
+pnpm exec tsx scripts/audit-a11y.ts > a11y-report.json
+```
+
+Then stop the background server from Step 1.
+
+Aggregate by:
+
+- **Per-route summary**: violation count, worst severity.
+- **Per-rule summary**: which rule fires most across the app — usually
+  reveals a single component (header, footer, form) that authors every page.
+
+## Step 6: Report
+
+Report findings with a primary severity of `error` / `warn` / `info`,
+mapping axe impacts: critical + serious → `error`, moderate → `warn`,
+minor → `info`. Keep the raw axe impact as a secondary column.
+
+```
+## Per-route summary
+
+| Route       | Critical | Serious | Moderate | Minor |
+| ----------- | -------- | ------- | -------- | ----- |
+| /           | 0        | 1       | 2        | 0     |
+
+## Per-rule summary (top offenders)
+
+- `color-contrast` — 12 violations across 8 routes
+  → Likely source: shared Button component (src/components/Button.tsx)
+- `image-alt` — 5 violations across 3 routes
+  → Likely source: <img> in shells/marketing.tsx
+
+## Detail
+
+[per-route violations with selectors and help URLs]
+```
+
+## Step 7: Targeted fixes
+
+For the top 3 issues, propose concrete patches:
+
+- `color-contrast` → suggest tokenized color pairs from existing CSS vars.
+- `image-alt` → list every `<img>` missing `alt` and propose either a
+  description or `alt=""` (decorative).
+- `landmark-one-main` → confirm shells render exactly one `<main>` element.
+- `label` → list inputs without associated `<label>` and propose
+  `htmlFor`/`for` or wrapping pattern.
+
+## Rules
+
+1. Run against the production build/runtime if at all possible — minified production
+   markup is what real users hit.
+2. axe with WCAG 2.1 AA + best-practice tags is the default; ask before
+   downgrading.
+3. Aggregate by rule before per-route — the same component is usually
+   responsible for most violations.
+4. Do not auto-fix. Suggest, then let the user review per component.
+5. For SPA routes that need interaction before content appears, ask the user
+   for a setup hook (e.g., a script that logs in and lands on the dashboard).
+6. Always clean up background servers you started, even when the audit fails
+   partway.
+
+$ARGUMENTS

package/skills/audit-auth/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: audit-auth
+version: 1.1.0
+description: |
+  Find pracht routes that look protected but aren't — missing auth middleware,
+  middleware that augments context but never gates, client-side auth checks
+  with no server enforcement, and API mutations exposed without guards.
+  Use when asked to "audit auth", "check route protection", "is my dashboard
+  protected", "find unauthenticated routes", or "review middleware coverage".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Auth
+
+What the framework guarantees: middleware runs wrap-around style — every
+middleware must return a `Response` (the runtime throws if it doesn't), either
+`return next()` to continue the chain or a short-circuit `Response` to stop it.
+The `redirect()` helper from `@pracht/core` returns a scheme/CRLF-validated
+redirect `Response`. What the framework does NOT decide is *which* routes get
+an auth gate — that is app wiring, and this skill audits it.
+
+The pracht auth pattern (see `examples/docs/src/routes/docs/recipes-auth.md`):
+middleware checks the session, short-circuits with a redirect on absence, and
+forwards user info via request headers; loaders downstream read the headers.
+
+Prerequisites: `pracht inspect` requires a vite config that registers the
+pracht plugin.
+
+## Step 1: Identify the auth middleware(s)
+
+```bash
+pracht inspect routes --json
+```
+
+If the pracht MCP server is registered (see `docs/MCP.md`), prefer its tools
+(`inspect_routes`, `inspect_api`, `inspect_build`, `doctor`, `verify`) over
+shelling out.
+
+Middleware is registered by name in the app manifest —
+`defineApp({ middleware: { auth: () => import("./middleware/auth.ts") } })` —
+and `inspect` reports those names, not files. Read the name→file map from
+`src/routes.ts` (or the configured manifest) to resolve each name, then read
+each middleware file and classify it:
+
+- **Gate** — on auth failure, returns a short-circuit `Response`
+  (`redirect("/login", { request })`, or a 401/403 `Response`) WITHOUT calling
+  `next()`; on success, `return next()`.
+- **Augmenter** — mutates request headers/context with user info, then always
+  returns `next()`. Never short-circuits.
+- **Other** — non-auth middleware (rate limit, logging, CORS, etc.).
+
+The "Augmenter" category is the silent killer: it makes loaders *think*
+auth is enforced because `request.headers.get('x-user-id')` returns a value
+when present, but unauthenticated requests just get `null` and the loader has
+to handle it. Flag every loader downstream of an Augmenter that doesn't.
+
+## Step 2: Identify protected routes
+
+A route is "expected protected" if any of:
+
+- It has `auth`/`session`/`requireUser`/similar middleware applied.
+- Its loader reads `x-user-id`/`x-user-email`/`getSession`/equivalent.
+- It lives under conventional protected paths: `/dashboard*`, `/admin*`,
+  `/account*`, `/settings*`, `/app*` (ask the user to confirm the
+  convention if unclear).
+- The user has flagged it explicitly.
+
+Build a list of expected-protected routes.
+
+## Step 3: Check coverage per protected route
+
+For each expected-protected route:
+
+1. From `pracht inspect routes --json`, read the resolved `middleware` array.
+2. Confirm at least one **Gate** middleware is present.
+3. Confirm the gate runs **before** any other middleware that depends on
+   identity (order matters).
+4. If only an Augmenter is present, mark as `augmented-only`.
+
+## Step 4: Check the API surface
+
+Mutation endpoints (`POST`, `PUT`, `PATCH`, `DELETE`) are the highest-impact
+target. From `pracht inspect api --json`:
+
+- Each API route reports `path`, `file`, `methods`, and `hasDefaultHandler`
+  (the last requires a current `@pracht/cli`). A `default`-export handler
+  serves ALL methods but reports `methods: []` — treat
+  `hasDefaultHandler: true` as "every method exposed". On older CLIs where
+  the field is missing, grep the handler file for `export default` instead.
+- For each mutation handler (named method export or default handler), check
+  whether `defineApp({ api: { middleware } })` applies a Gate, OR the handler
+  reads/validates a session itself.
+- Common bug: dashboard route is protected by middleware, but
+  `POST /api/items` is not — attacker bypasses the UI entirely.
+
+## Step 5: Client/server enforcement parity
+
+Grep client components for patterns like `if (!user) return <Login />`. For
+each occurrence, confirm that **the data path is also gated server-side**.
+Client-side gating without a server gate is purely cosmetic and a common
+source of "I see the data flash before redirect" or worse, leaked data via
+SPA route loaders.
+
+## Step 6: Session cookie sanity
+
+Cross-reference with `audit-csrf`: the same cookies that authorize the user
+are the CSRF target. Recommend running `audit-csrf` after this skill.
+
+## Step 7: Report
+
+| Route/API | Expected | Resolved middleware | Gate present? | Severity | Verdict |
+| --------- | -------- | ------------------- | ------------- | -------- | ------- |
+
+Severity is the primary scale; the verdict is a secondary domain label:
+
+- `error` / `unprotected` — no auth middleware on a route the user expects
+  protected.
+- `error` / `inconsistent` — UI route is gated; sibling API is not.
+- `warn` / `augmented-only` — middleware reads session but never blocks;
+  loader must handle null user.
+- `warn` / `client-only` — server allows; client hides UI.
+- `info` / `protected` — gate confirmed.
+- `info` / `public-by-design` — deliberately exposed (login, signup,
+  marketing).
+
+## Rules
+
+1. The framework's `pracht inspect routes --json` and `pracht inspect api
+   --json` are the source of truth — group inheritance is already resolved.
+2. Recognize Gates by behavior (short-circuits with a `Response` without
+   calling `next()` on failure), not by filename — projects use `auth.ts`,
+   `requireUser.ts`, `session.ts`, etc.
+3. An Augmenter is a valid pattern when paired with a separate Gate or a
+   loader that explicitly handles the unauthenticated case. Flag it; don't
+   condemn it.
+4. Public routes deliberately exposed (login, signup, marketing) should be
+   listed but not flagged.
+5. Do not auto-add middleware. Auth wiring is policy.
+
+$ARGUMENTS