create-pracht 0.2.6 → 0.4.0

package/skills/audit-islands/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: audit-islands
+version: 1.0.0
+description: |
+  Audit pracht islands usage: find over-hydrated routes that should use
+  `hydration: "islands"` or `"none"`, dead interactivity outside the islands
+  directory, non-serializable island props, mis-tuned client strategies, and
+  invalid render/hydration combinations.
+  Use when asked to "audit islands", "reduce hydration", "why is this island
+  not interactive", "should this page be an island", or "check partial
+  hydration".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Islands
+
+Report-only audit of hydration modes and islands usage (see `docs/ISLANDS.md`).
+Pracht hydrates the whole page by default (`hydration: "full"`); routes can opt
+into `"islands"` (only components from the islands directory hydrate) or
+`"none"` (zero JS). This audit finds routes shipping JS they don't need and
+islands wired in ways that break at render time or ship dead handlers.
+
+## Step 1: Enumerate routes and hydration modes
+
+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.
+
+Each route entry carries `render` and `hydration` (`null` = framework default,
+i.e. full hydration). Also locate the islands directory: default `src/islands/`,
+configurable via `pracht({ islandsDir })` in the vite config. In pages-router
+apps (`mode: "pages"`), hydration is the per-file `export const HYDRATION =
+"islands" | "none"` constant; islands still live in `src/islands/`.
+
+## Step 2: Measure what each route actually ships
+
+```bash
+pracht build --json
+```
+
+Prerequisite: this runs a full production build (`--json` implies `--analyze`).
+Interpret the totals hydration-aware:
+
+- Full-hydration routes: route chunks + shell chunks + shared entry.
+- `hydration: "islands"` routes: islands bootstrap + island chunks only — no
+  shared client entry. The listed island chunks are an **upper bound** (every
+  island in the app); a page only downloads the islands it renders.
+- `hydration: "none"` routes report `0b`.
+
+## Step 3: Run the checks
+
+### 3a. Over-hydration (the headline check)
+
+For every route with `hydration` `null`/`"full"`: read the route module, its
+shell, and their imported components. If the page is mostly static — no
+hooks, no event handlers, or only one or two isolated widgets — flag it:
+
+- Zero interactivity → recommend `hydration: "none"` (`warn`; `info` if the
+  route's total gzip JS is already tiny).
+- A few isolated widgets → recommend `hydration: "islands"` with the widgets
+  moved into the islands directory (`warn`). Cite the Step 2 total as the
+  payload this change removes.
+
+Render-mode fit is owned by `/tune-render-mode`; deep chunk analysis is owned
+by `/audit-bundles`. Point there instead of duplicating their findings.
+
+### 3b. Dead interactivity on islands routes (`error`)
+
+On a `hydration: "islands"` route, everything outside the islands directory
+renders as inert HTML — an `onClick` in a regular component silently does
+nothing. Grep the route tree of every islands route for event handlers and
+hooks in components **not** under the islands directory and flag each one.
+Islands are auto-discovered from that directory only (default and named
+function-component exports alike; each becomes its own code-split chunk) —
+there is no wrapper to mark a component elsewhere as an island.
+
+### 3c. Island props and children (`error`)
+
+Island props are serialized to JSON in the HTML. At each island call site on
+an islands route, flag props that are functions, symbols, bigints, class
+instances (`Date`, `Map`, ...), JSX elements, or circular — rendering throws a
+descriptive error naming the offending prop path. Passing children into an
+island from a server component also throws (unsupported in v1): move the
+content inside the island or pass a serializable prop.
+
+### 3d. Hydration strategy tuning (`info`)
+
+Each island usage picks a strategy via the framework-owned `client` prop:
+`"load"` (default, chunk is `<link rel="modulepreload">`-ed), `"idle"`
+(requestIdleCallback), `"visible"` (IntersectionObserver; chunk fetched only
+when triggered). Flag default-`load` islands that are plausibly below the fold
+or not needed at first paint (comment sections, newsletter signups, footers) →
+suggest `client="visible"` or `client="idle"`.
+
+### 3e. Invalid combinations (`error`)
+
+`render: "spa"` always implies full hydration; combining it with
+`hydration: "islands"` or `"none"` is a configuration error. Flag any such
+route (manifest field or pages-router `RENDER_MODE`/`HYDRATION` pair).
+
+### 3f. MPA navigation assumptions (`warn`)
+
+Routes with `hydration: "islands"` or `"none"` never load the client router:
+navigation to, from, and between them is full-document (MPA-style), and
+route-state prefetching is skipped for them. Flag apps that rely on
+client-side state surviving navigation across such routes (in-memory stores,
+module-level caches shared between pages) — every navigation is a fresh
+document.
+
+## Step 4: Report
+
+| Route | File | Severity | Finding | Suggested fix |
+| ----- | ---- | -------- | ------- | ------------- |
+
+Severities: `error` (breaks or throws today: dead handlers, non-serializable
+props, spa+islands), `warn` (works but wasteful or fragile), `info` (tuning
+opportunity). Include the measured gzip totals for every over-hydration
+finding.
+
+## Rules
+
+1. Report only — never edit routes, components, or config. Hand changes to
+   `/tune-render-mode` (modes) or the user.
+2. Use `pracht inspect routes --json` as the source of truth for hydration
+   modes — groups inherit `hydration`, so reading `src/routes.ts` manually
+   under-counts.
+3. Islands components behave like plain components on full-hydration routes
+   and inside other islands — only flag 3b/3c on `hydration: "islands"`
+   routes.
+4. Verify hydration in a running app via `html[data-pracht-islands-hydrated="true"]`
+   (set after all `load` islands hydrate) and per-island `data-hydrated="true"`.
+
+$ARGUMENTS

package/skills/audit-loaders/SKILL.md

@@ -0,0 +1,135 @@
+---
+name: audit-loaders
+version: 1.1.0
+description: |
+  Audit pracht route loaders for serializability, leaked secrets,
+  unsafe loader caching, browser-only API misuse, and missing AbortSignal plumbing.
+  Use when asked to "audit loaders", "check loader data", "find serialization
+  bugs", "are my loaders safe", or "loader security review".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Loaders
+
+Static analysis of every loader in the project. The framework serializes loader
+return values to the client via `window.__PRACHT_STATE__`, so anything returned
+ends up in the browser — including secrets you never meant to expose.
+
+## Step 1: 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 every route entry, read `loaderFile ?? file` and inspect the `loader`
+export there. Loaders may live in a separate data module wired via the
+manifest (`RouteConfig.loader`); the inspect JSON surfaces that as
+`loaderFile` (null when the loader lives in the route module itself). Reading
+only `file` misses every externalized loader.
+
+## Step 2: Run the five checks
+
+For each `loader` (and `getStaticPaths` when present):
+
+### 2a. Serializability
+
+Flag returns that contain any of:
+
+| Construct                    | Why it breaks                       |
+| ---------------------------- | ----------------------------------- |
+| `Date`, `Map`, `Set`, `URL`  | Not preserved by `JSON.stringify`   |
+| Class instances              | Lose prototype on the client        |
+| `Function` / arrow values    | Stripped silently                   |
+| `Promise`                    | Becomes `{}`                        |
+| Circular refs                | Throws at serialize time            |
+| `Buffer` / typed arrays      | Becomes `{}` or numeric keys        |
+| `bigint`                     | `JSON.stringify` throws             |
+| `undefined` in arrays/object | Drops keys; arrays become `null`    |
+
+Recommend converting to `string` (ISO for dates), plain arrays, or plain objects
+before return.
+
+### 2b. Secret leaks
+
+Ownership note: deep secret scanning is owned by `/audit-secrets` and by
+`pracht verify`'s env scan — keep this check brief and point the user there
+rather than triple-reporting the same findings. Here, only flag what falls
+out of reading the return value anyway:
+
+Grep the loader body and anything it returns for:
+
+- `process.env.*` references that flow into the return value.
+- `context.env.*` (Cloudflare bindings) flowing into the return value.
+- Variables named `*SECRET*`, `*TOKEN*`, `*KEY*`, `*PASSWORD*`, `*PRIVATE*`,
+  `*API_KEY*` reaching the return.
+- Spreads of full DB rows containing `password_hash`, `mfa_secret`, etc.
+
+Loaders run server-side but **the return value crosses the wire**. Always
+project to a smaller shape before returning.
+
+### 2c. Browser-only APIs at module top level or in loader
+
+Flag any of these accessed unconditionally inside `loader` or at the top level
+of a route module that is rendered SSR/SSG/ISG:
+
+- `window`, `document`, `navigator`, `localStorage`, `sessionStorage`,
+  `IntersectionObserver`, `matchMedia`, `requestAnimationFrame`.
+
+These crash on the server. For SPA-only routes (`render: "spa"`) it's fine
+inside the component — but never inside `loader`.
+
+### 2d. AbortSignal plumbing
+
+For loaders that call `fetch` or any I/O:
+
+- The framework passes `signal` in `LoaderArgs`.
+- Verify it is forwarded to outbound `fetch(url, { signal })` calls and to any
+  database client that accepts cancellation.
+- A loader that ignores `signal` keeps work running after the client navigates
+  away.
+
+### 2e. Loader cache safety
+
+For routes with a positive `loaderCache` value, flag loader data whose freshness
+or visibility depends on cookies, authorization headers, sessions, user identity,
+permissions, or request-specific context. Route-state HTTP caching is `private`,
+so shared proxies cannot reuse it, but a stale response can still survive logout,
+account switching, or permission changes in the same browser.
+
+Recommend `loaderCache: false`/`0` for personalized or authorization-sensitive
+loaders. Use a positive duration only when every field in the returned data can be
+safely reused for that long. Do not confuse `loaderCache` with ISG `revalidate` or
+the short-lived in-memory prefetch cache; they are independent policies.
+
+## Step 3: Report
+
+Produce a markdown table:
+
+| Route | File | Severity | Finding | Suggested fix |
+| ----- | ---- | -------- | ------- | ------------- |
+
+Severities: `error` (secret leak, crash), `warn` (serialization risk, missing
+signal), `info` (style nit).
+
+## Rules
+
+1. Use `pracht inspect routes --json` as the source of truth — do not glob
+   `src/routes/**` and risk missing manifest wiring or catching orphan files.
+2. Read the actual loader source — do not infer from names.
+3. For each finding, point at the file and line.
+4. Do not auto-fix. Hand the user the report; let them choose.
+5. If the loader returns a typed shape from a DB ORM, recommend an explicit
+   `select` or projection step rather than spreading the row.
+
+$ARGUMENTS

package/skills/audit-redirects/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: audit-redirects
+version: 1.1.0
+description: |
+  Find open-redirect vulnerabilities in pracht loaders, middleware, and
+  navigation calls. The framework guards both ends — the client router drops
+  unsafe URL schemes, and the server `redirect()` helper rejects unsafe
+  schemes and CRLF injection — but a hand-rolled 3xx Response bypasses every
+  guard, and even a guarded redirect to an attacker-chosen origin can phish.
+  Use when asked to "audit redirects", "check for open redirects", "is my
+  ?redirect= param safe", or "review login redirect handling".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Redirects
+
+The classic open-redirect bug: `/login?redirect=https://evil.example` →
+after login, the app redirects the user to attacker territory carrying a fresh
+session.
+
+What the framework guarantees: the client router drops non-`http(s):` schemes
+at the navigation boundary, and server-side `redirect()` /
+`buildRedirectResponse()` reject non-`http(s):` schemes and CR/LF injection
+against the `Location` header. What it cannot decide is whether the target
+*origin or path* is one you trust — and a raw
+`new Response(null, { status: 302, headers: { location: userInput } })`
+bypasses all of those guards entirely.
+
+Prerequisites: `pracht inspect` requires a vite config that registers the
+pracht plugin.
+
+## Step 1: Inventory redirect sites
+
+Bound the search first — do not grep the whole repo blind:
+
+```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.
+
+The resolved graph gives you each route's `file`, `loaderFile`, and
+`middleware` names (resolve names to files via the `defineApp({ middleware })`
+map in the manifest). Grep those files plus the API handler files from
+`pracht inspect api --json`, and client components, for two distinct classes:
+
+**Class A — guarded sites** (scheme/CRLF-safe, still open-redirect capable):
+
+- Middleware/loaders/handlers returning `redirect(...)` or
+  `buildRedirectResponse(...)`.
+- `useNavigate()(value)` and `<a href={value}>` where `value` is dynamic
+  (client guard applies).
+- `prefetchRouteState(value)` calls with dynamic input.
+
+**Class B — unguarded sites** (bypass every framework guard):
+
+- Hand-rolled 3xx `Response`s: `new Response(null, { status: 302, headers:
+  { location: ... } })` or `headers.set("location", ...)` in loaders,
+  middleware, or API handlers. With user input these allow not just open
+  redirects but also unsafe schemes and header-injection attempts — flag at
+  higher severity.
+
+## Step 2: Trace the input
+
+For each site, identify whether the redirect target is:
+
+- **Static** — string literal. Safe.
+- **Internal-derived** — built from `params`, `route.path`, or a closed
+  allowlist. Safe if the allowlist is verifiable.
+- **Request-derived** — read from `url.searchParams.get(...)`,
+  `request.headers.get('referer')`, request body fields, cookie values, or
+  query parameters. **Suspect.**
+
+Common suspect names: `redirect`, `redirectTo`, `next`, `returnTo`, `continue`,
+`url`, `dest`, `goto`.
+
+## Step 3: Check the gate
+
+For each request-derived target, look for one of:
+
+| Gate                                   | Safe? |
+| -------------------------------------- | ----- |
+| Hardcoded allowlist of paths/origins   | Yes   |
+| `target.startsWith('/')` AND `!target.startsWith('//')` | Yes — same-origin path only |
+| `new URL(target, base).origin === url.origin`           | Yes — origin comparison |
+| `new URL(target).hostname === expected` | Yes if `expected` is trusted |
+| No check                                | **Open redirect** |
+| `target.includes(domain)` (substring)   | **Bypassable** (`evil.com#yourdomain.com`) |
+| Regex without anchors                   | **Likely bypassable** |
+
+`startsWith('/')` alone is **not** sufficient — `//evil.example/path` parses
+as a protocol-relative URL and most browsers treat it as cross-origin. Require
+both `startsWith('/')` AND `!startsWith('//')`, or use `URL` parsing.
+
+Remember: `redirect()`'s built-in validation covers scheme and CRLF only — it
+happily redirects to any well-formed `http(s)` origin, so Class A sites still
+need an origin/path gate for request-derived targets.
+
+## Step 4: Report
+
+| File:Line | Class (A/B) | Source | Target expression | Gate | Severity | Verdict |
+| --------- | ----------- | ------ | ----------------- | ---- | -------- | ------- |
+
+Severity is the primary scale; the verdict is a secondary domain label:
+
+- `error` / `open` — request-derived target, no check. A Class B site here is
+  the worst case (no scheme/CRLF guard either) — say so explicitly.
+- `warn` / `risky` — substring/regex check; suggest URL-parse rewrite.
+- `info` / `safe` — static or properly gated. For Class B sites that are
+  static today, still recommend migrating to `redirect()` so the scheme/CRLF
+  guards apply if the target ever becomes dynamic.
+
+For each `open`/`risky` finding, propose a fix snippet, e.g.:
+
+```ts
+const raw = url.searchParams.get("redirect") ?? "/dashboard";
+const safe = raw.startsWith("/") && !raw.startsWith("//") ? raw : "/dashboard";
+return redirect(safe, { request });
+```
+
+## Step 5: Cross-check with the framework guards
+
+Note in the report that pracht drops `javascript:`, `data:`, `vbscript:`,
+`blob:`, and `file:` schemes both in the client router (since #122) and in
+server-side `redirect()`/`buildRedirectResponse()` — so a guarded open
+redirect cannot become script execution. But it can still phish (redirect to
+a look-alike origin) and leak session/referrer headers, and Class B raw
+Responses get none of this protection.
+
+## Rules
+
+1. Default to suspicion for any request-derived target.
+2. Recommend `URL` parsing over string prefix checks for non-trivial gates.
+3. Do not trust `referer` as a gate; it is forgeable and often stripped.
+4. After-login redirects are the most dangerous — user is authenticated.
+5. Recommend `redirect()` over hand-rolled 3xx Responses so the scheme/CRLF
+   guards apply.
+6. Do not auto-fix; surface the gap and propose the patch.
+
+$ARGUMENTS

package/skills/audit-secrets/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: audit-secrets
+version: 1.1.0
+description: |
+  Detect environment variables and secrets that leak from the server into
+  the client bundle via loader return values, hydration state, or accidental
+  imports of server-only modules from client code paths.
+  Use when asked to "audit secrets", "find leaked env vars", "is my API key
+  exposed", "check client bundle for secrets", or "scan for credential leaks".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Secrets
+
+Pracht serializes loader return values into the `pracht-state` JSON script and
+hydrates the client from them. Anything a loader returns ends up readable in the
+browser. The Vite plugin also strips server-only exports from route files, but
+it cannot save you from a value that flows into the return.
+
+Prerequisites: `pracht inspect` requires a vite config that registers the
+pracht plugin; the env-safety report under `dist/client/_pracht/` requires a
+prior `pracht build`. 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.
+
+## Step 0: Run the native env safety check
+
+Pracht has built-in env leak detection (see `docs/ENV.md`):
+
+- `pracht build` fails when a client chunk references a non-public env var
+  (anything not `PRACHT_PUBLIC_`-prefixed and not a Vite built-in),
+  naming the variable, chunk, and likely source module.
+- `pracht verify` (and `pracht doctor`) check the build-time env-safety report
+  and re-run the literal chunk scan against an existing `dist/client` output.
+- Client-side imports of `@pracht/core/env/server` (`serverEnv`) fail the build.
+
+Run `pracht verify` or `pracht doctor` (or a build) first and fold the
+findings into the report.
+Check `vite.config.*` for `envSafety: { allow: [...] }` / `envSafety: false` —
+every allowlisted name and a disabled check are findings to review, since they
+bypass the native gate. The native check detects _references_, not values, so
+the dataflow steps below are still required.
+
+## Step 1: Identify "secret-shaped" identifiers
+
+Build a regex of variable names treated as sensitive:
+
+```
+SECRET|TOKEN|API[_-]?KEY|PRIVATE[_-]?KEY|PASSWORD|PASSPHRASE|SESSION[_-]?SECRET|JWT[_-]?SECRET|WEBHOOK[_-]?SECRET|DATABASE[_-]?URL|DB[_-]?URL|CONNECTION[_-]?STRING|CLIENT[_-]?SECRET|REFRESH[_-]?TOKEN
+```
+
+Also flag any direct `process.env.X` or `context.env.X` reference where `X`
+matches the above.
+
+## Step 2: Server → client flow analysis
+
+For every route file, trace whether a sensitive value reaches the loader's
+return value. Steps:
+
+1. Run `pracht inspect routes --json` to enumerate routes.
+2. For each route, read the loader.
+3. Build a small dataflow trace from sensitive identifiers (and `process.env.*`
+   / `context.env.*` reads) to the `return` statement(s).
+4. Flag any spread (`...row`, `...user`, `...env`) that originates from a
+   source containing secrets.
+5. Flag direct returns of objects that name sensitive keys.
+
+This is heuristic — favor over-flagging over silent leaks. Note false-positive
+risk in the report.
+
+## Step 3: Module import boundaries
+
+Grep client-rendered files (route components, shells, anything imported from
+them) for imports of:
+
+- `node:*` builtins
+- `@pracht/adapter-*`
+- Local `src/server/**` modules
+- Modules whose top level reads `process.env.*`
+
+The Vite plugin strips the server-only exports `loader`, `head`, `headers`,
+`getStaticPaths`, and `markdown` from route files when serving the client
+query (`middleware` is not a route-file export — middleware lives in the
+manifest); see the client module transform notes in `docs/ARCHITECTURE.md`
+and `docs/ENV.md`. But a component that imports `../server/db` will still
+pull `db` into the client bundle. Flag those imports.
+
+## Step 4: Hidden surfaces
+
+Check for accidental exposure outside loaders:
+
+- `head()` returns: rare, but a `meta` value containing a token leaks into HTML.
+- `headers()` returns: flag values that look like secrets. For SSG/ISG pages,
+  document headers can be copied into `dist/client/_pracht/headers.json`, which
+  is public client output and may be replayed on static responses. This skill
+  owns secret VALUES in headers; header policy (CSP, HSTS, weakened defaults)
+  is owned by `audit-headers` — cross-reference it.
+- `<Form>` `action` URLs containing tokens in the query string.
+- `prefetchRouteState(url)` calls with sensitive query params.
+- Inline `<script>` content emitted from custom shells.
+
+## Step 5: `.env` discipline
+
+- Confirm `.env*` is in `.gitignore`.
+- Confirm generated starters preserve `!.env.example` if they ignore `.env*`.
+- Grep tracked files for likely committed secrets (long random strings near
+  identifier names from step 1).
+- Confirm client-side env access goes through `publicEnv` (from
+  `@pracht/core`) or `import.meta.env.PRACHT_PUBLIC_*`; `VITE_*` values are
+  still exposed by Vite compatibility wiring, but Pracht does not treat them as
+  intentionally public, so flag client-side `VITE_*` references unless they are
+  explicitly allowlisted and reviewed. Warn loudly if a public env name has a
+  secret-shaped name.
+- Confirm server-side env access uses `serverEnv` (from
+  `@pracht/core/env/server`) or `context.env` rather than ad-hoc globals.
+
+## Step 6: Report
+
+| File:Line | Identifier / source | Sink (loader return / client import / etc.) | Severity |
+| --------- | ------------------- | ------------------------------------------- | -------- |
+
+Severities:
+
+- `error` — direct flow from `process.env.SECRET_*` / `serverEnv.SECRET_*` to
+  loader return.
+- `error` — `PRACHT_PUBLIC_*_SECRET` style client-public or allowlisted `VITE_*_SECRET`
+  secret-shaped name.
+- `error` — `envSafety: false` or an allowlisted name that looks secret-shaped.
+- `warn` — spread of a row that may contain secret columns.
+- `warn` — client component imports a module that reads `process.env`.
+- `info` — header value that looks like a token.
+
+## Rules
+
+1. Heuristic-first; document false-positive risk per finding.
+2. Recommend an explicit allowlist projection (`{ id, name, email }`) over
+   blocklist filtering.
+3. For Cloudflare apps, secrets live in `context.env` — same risk profile as
+   `process.env`. Treat them identically.
+4. Never print suspected secret values into the report — refer by name only.
+5. If you find a likely committed secret, recommend immediate rotation in
+   addition to removal from history.
+6. Report only — do not auto-fix. Propose the projection/rotation/config
+   change; never apply it.
+
+$ARGUMENTS