create-pracht 0.6.0 → 0.6.2

package/skills/pracht-debug/SKILL.md

@@ -1,14 +1,12 @@
 ---
 name: pracht-debug
-version: 1.3.0
+version: 1.4.0
 description: |
-  Pracht framework-aware debugging. Systematically investigates route matching,
-  loader/API route errors, rendering issues, middleware, API routes, HMR, and build
-  problems. Uses pracht's architecture knowledge to find root causes fast.
-  Use when asked to "debug this", "fix this bug", "why is this broken",
-  "blank page", "hydration mismatch", or "404 on my route".
-  Proactively suggest when the user reports errors or unexpected behavior
-  in a pracht application.
+  Framework-aware debugging for pracht: route matching, loader and API errors,
+  rendering and hydration, middleware, HMR, and build failures — root cause first.
+  Use for "debug this", "fix this bug", "why is this broken", "blank page",
+  "hydration mismatch", "404 on my route"; suggest it when the user reports
+  unexpected pracht behavior.
 allowed-tools:
   - Bash
   - Read
@@ -21,126 +19,173 @@ allowed-tools:
 
 # Pracht Debug
 
-Framework-aware debugging for pracht applications — a full-stack Preact framework built on Vite.
+**Iron law: no fixes without root-cause investigation first.** Read the
+relevant source before diagnosing, start from the most likely cause for the
+symptom rather than a full audit, and when you find the root cause explain
+*why* it breaks. After fixing, prove the fix — run the test, check the dev
+server. Never say "this should fix it."
 
-The user will describe a symptom (error, unexpected behavior, blank page, etc.). Investigate systematically using the checklist below, stopping when you find the root cause.
+## Instruments
 
-Before deep manual inspection, prefer running `pracht verify` (add `--changed` to scope the checks to git-changed files) for a fast agent loop or `pracht doctor` when the problem could be caused by broader broken app wiring or missing files.
-When another agent/tool needs the framework's resolved graph, prefer `pracht inspect routes --json`, `pracht inspect api --json`, or `pracht inspect build --json` over reconstructing it from source files. Prerequisites: `pracht inspect` needs the pracht plugin registered in the project's vite config, and `pracht inspect build` needs a prior `pracht build`.
-If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools over shelling out — same payloads, structured results.
-While the dev server is running, `GET /_pracht` serves a devtools page with the same resolved route/API graph (raw JSON at `/_pracht.json`) — useful when you have a browser or `curl` handy but no CLI access. Under a Vite deploy base, prefix both paths with that base; links from the devtools and dev-404 pages already do so. Dev SSR responses also carry a `Server-Timing` header (`mw`, `loader`, `render` durations in ms) — check it in the browser Network panel or with `curl -sI` to see which phase makes a route slow.
+Reach for these before deep manual inspection:
 
-## Iron Law
+| Tool | Use |
+| ---- | --- |
+| `pracht verify` (`--changed` to scope to git-changed files) | Fast confidence check |
+| `pracht doctor` | Broader broken wiring or missing files |
+| `pracht inspect routes\|api\|build --json` | The resolved graph — never reconstruct it from source |
+| `GET /_pracht` (JSON at `/_pracht.json`) | Same graph from a running dev server, no CLI needed |
+| `Server-Timing` on dev SSR responses | `mw` / `loader` / `render` durations in ms — which phase is slow |
 
-**NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST.**
+`pracht inspect` needs the pracht plugin in the vite config; `inspect build`
+needs a prior `pracht build`. Under a Vite deploy base, prefix `/_pracht` with
+that base (links from the devtools and dev-404 pages already do). When the
+pracht MCP server is registered (docs/MCP.md), prefer the
+`inspect_routes`/`inspect_api`/`doctor`/`verify` MCP tools — same payloads,
+structured results.
 
-## Debugging Checklist
+## Checklist
 
-Work through these in order, stopping when you find the root cause:
+Work in order; stop at the root cause.
 
 ### 1. Route matching
 
-- Run `pracht verify --changed` first if you want a cheap changed-file confidence check.
-- Run `pracht doctor` if the route might be missing, miswired, or pointing at a missing module across the project.
-- For machine-readable route wiring, run `pracht inspect routes --json`. With a running dev server, `curl http://localhost:5173/_pracht.json` returns the same graph.
-- Read `src/routes.ts` — is the route defined? Is the path correct?
-- Check for typos in file paths (the manifest uses relative paths like `"./routes/home.tsx"`).
-- For dynamic segments, verify bracket syntax: `route("/users/:id", ...)` in manifest, `[id].ts` in filenames.
-- Grep for the route path across the manifest and check `matchAppRoute()` logic if needed.
-
-### 2. Typed route/link issues
-
-- If `<Link route="...">`, `href("...")`, or route-object `useNavigate()` fails to typecheck, run `pracht typegen --check` to detect stale generated files.
-- Run `pracht inspect routes --json` and confirm the route id exists. If it is a fallback id, remember path changes can rename it.
-- Check generated `src/pracht.d.ts` for inferred params. `:id`, `*`, and `:path*` params are required; extra params should fail at typecheck time.
-- If runtime navigation throws `Unknown pracht route id "..."`, in dev the error includes a `Did you mean "..."?` suggestion and the list of registered route ids (production builds tree-shake this and throw the bare error) — check for a typo first, then ensure `pracht typegen` was run and the component is rendered inside the pracht route tree.
-- For unexpected URLs, reproduce with `href(routeId, options)` and compare against the route's resolved path and params.
-
-### 3. Loader / API route errors
-
-- For slow pages, read the dev `Server-Timing` response header (`mw`/`loader`/`render` in ms) to see which phase dominates before reading code.
-- Read the route module's `loader` function or the matching API route handler.
-- Check that `loader` returns serializable data (no functions, no circular refs).
-- Check that API route handlers return `Response` objects and branch on `request.method` when using a default export.
-- Look for unhandled promise rejections or thrown errors.
-- Verify `LoaderArgs` destructuring matches what the framework provides: `{ request, params, context, signal, url, route }`.
-
-### 4. Rendering issues
-
-- **Blank page**: Check if the route has `render: "spa"` (no SSR content expected) vs `"ssr"`.
-- **Hydration mismatch**: In dev, pracht surfaces a fixed-position red banner at the top of the page listing each mismatched component (via Preact's `options.__m` hook). Compare server-rendered HTML vs client component output. Common causes:
-  - Date/time rendering differences
-  - Browser-only APIs used during SSR (`window`, `document`, `localStorage`)
-  - Conditional rendering based on client state
-- **Missing shell**: Referencing an unregistered shell name throws at manifest resolution — `Unknown shell "..." for route "...". Did you mean "..."? Registered shells: ...` — and shows up in the dev error overlay as soon as the server loads the manifest. Verify the shell is registered in `defineApp({ shells: { ... } })` and assigned to the route/group.
-- **404 page**: Route not matched — check manifest wiring (step 1). In `pracht dev`, unmatched navigations render a dev-only 404 page listing every registered route with its render mode; compare the requested path against that table. The route table is also printed on dev-server startup and available via `pracht inspect routes`. Apps that declare `defineApp({ notFound })` render their own 404 page instead (in dev and production alike), so the route table is not shown — check `pracht inspect routes` directly. A 404 on a URL you *do* expect to work usually means the loader threw `notFound()`, not that matching failed.
-
-### 5. Middleware issues
-
-- Verify middleware is registered in `defineApp({ middleware: { ... } })`. An
-  unregistered name (on a route, group, or `api.middleware`) throws at manifest
-  resolution — `Unknown middleware "..." for route "...". Did you mean "..."? Registered middleware: ...`
-- Verify middleware is applied to the route/group: `middleware: ["name"]`.
-- Middleware is wrap-around: it must always return a `Response`, either by
-  calling `await next()` (to continue down the chain) or short-circuiting.
-- Common bugs:
-  - Forgetting `return next()` → `Middleware "..." did not return a Response`
-  - Calling `next()` twice → `Middleware "..." called next() multiple times`
-  - Mutating a non-object `context` → mutations don't propagate; always pass
-    an object as the request context.
-- Middleware runs server-side only, wrapping loaders and API handlers.
-
-### 6. API route issues
-
-- API routes live in `src/api/` and are auto-discovered (no manifest entry needed).
-- For machine-readable API inventory, run `pracht inspect api --json`.
-- File path maps to URL: `src/api/health.ts` → `/api/health`, `src/api/users/[id].ts` → `/api/users/:id`.
-- Each file exports named HTTP method handlers (`GET`, `POST`, etc.) or one default handler.
-- Missing method handler → 405 response when there is no default handler.
-- Default handlers receive the same route args and can branch on `request.method`.
-- Handlers must return `Response` objects.
-
-### 7. Vite plugin / HMR issues
-
-- Check `vite.config.ts` — is `pracht()` plugin included?
-- Virtual modules: `virtual:pracht/client` (hydration), `virtual:pracht/server` (SSR), `virtual:pracht/islands-client` (islands hydration).
-- HMR: changes to `src/routes.ts` restart the dev server (`server.restart()`, not a browser-side full reload); changes to route/shell/middleware/API/server/islands files invalidate the server module.
-- If HMR seems broken, check that the file is in one of the watched directories (`src/routes/`, `src/shells/`, `src/middleware/`, `src/api/`, `src/server/`, `src/islands/`).
-
-### 8. Build / deployment issues
-
-- `pracht build` runs client + server builds, then prerenders SSG/ISG routes.
-- `pracht preview` builds and serves the production output locally (Node runs `dist/server/server.js`, Cloudflare delegates to `wrangler dev`).
-- `pracht inspect build --json` reports the resolved adapter target plus client/CSS/JS manifests from the latest build output (requires a prior `pracht build`).
-- Check `dist/client/` for client assets and `dist/server/` for server bundle.
-- ISG manifest: `dist/server/isg-manifest.json`. On Cloudflare the build also copies it to `dist/client/_pracht/isg.json` for the worker runtime to read via the assets binding.
-- Adapter mismatch: ensure `pracht({ adapter: nodeAdapter() })` or `cloudflareAdapter()` matches deployment target.
-
-## Key Files
-
-| File                  | Purpose                                               |
-| --------------------- | ----------------------------------------------------- |
-| `src/routes.ts`       | App manifest — all route/shell/middleware definitions |
-| `vite.config.ts`      | Vite config with `pracht()` plugin                    |
-| `src/routes/*.tsx`    | Route modules (loader, Component)                     |
-| `src/shells/*.tsx`    | Shell layout components                               |
-| `src/middleware/*.ts` | Server-side middleware                                |
-| `src/api/*.ts`        | API route handlers                                    |
-
-## Framework Internals
-
-- `handlePrachtRequest()` dispatches: API routes → middleware → loader → render → HTML assembly
-- Route state JSON: returned when `x-pracht-route-state-request` header is present (client-side navigation)
-- Hydration state: injected as `window.__PRACHT_STATE__` in the HTML
-- Client router: `initClientRouter()` intercepts link clicks and fetches route state JSON
-
-## Rules
-
-1. Always read the relevant source files before diagnosing.
-2. Start with the most likely cause based on the symptom, not a full audit.
-3. When you find the root cause, explain _why_ it breaks and fix it.
-4. If wiring looks suspicious, run `pracht verify` first, then `pracht doctor` if you need the full-project view. If running the dev server or tests would help, do so (`pracht dev`, `pnpm test`, `pnpm e2e`).
-5. After fixing, verify the fix works (run relevant test or check dev server output).
-6. Never say "this should fix it." Verify and prove it.
+- `pracht inspect routes --json` (or `curl http://localhost:5173/_pracht.json`)
+  for the resolved wiring; `pracht doctor` if a route may be missing, miswired,
+  or pointing at a missing module.
+- Is the route in `src/routes.ts` with the right path? The manifest uses
+  relative paths like `"./routes/home.tsx"` — check for typos.
+- Dynamic segments: `route("/users/:id", ...)` in the manifest, `[id].ts` in
+  filenames.
+- If needed, grep the route path across the manifest and check
+  `matchAppRoute()`.
+
+### 2. Typed routes and links
+
+- A `<Link route="...">`, `href("...")`, or route-object `useNavigate()` that
+  fails to typecheck usually means stale generated files: `pracht typegen
+  --check`.
+- Confirm the route id exists in `pracht inspect routes --json`. Fallback ids
+  get renamed by path changes.
+- `src/pracht.d.ts` carries the inferred params. `:id`, `*`, and `:path*` are
+  required; extra params should fail at typecheck time.
+- Runtime `Unknown pracht route id "..."`: dev appends `Did you mean "..."?`
+  plus the registered ids (production tree-shakes that and throws bare). Check
+  the typo first, then that `pracht typegen` ran and the component renders
+  inside the pracht route tree.
+- For unexpected URLs, reproduce with `href(routeId, options)` and compare
+  against the route's resolved path and params.
+
+### 3. Loader / API errors
+
+- On slow pages, read `Server-Timing` before reading code.
+- Loaders must return serializable data — no functions, no circular refs.
+- API handlers must return `Response` objects, and a default export must branch
+  on `request.method`.
+- Look for unhandled rejections or thrown errors.
+- `LoaderArgs` destructuring must match what the framework provides:
+  `{ request, params, context, signal, url, route }`.
+
+### 4. Rendering
+
+- **Blank page** — check whether the route is `render: "spa"` (no SSR content
+  expected) rather than `"ssr"`.
+- **Hydration mismatch** — dev shows a fixed red banner listing each mismatched
+  component (via Preact's `options.__m` hook). Compare server HTML against
+  client output. Usual causes: date/time differences, browser-only APIs during
+  SSR (`window`, `document`, `localStorage`), conditional rendering on client
+  state — or two copies of `@pracht/core` in the SSR module graph. The tell for
+  that last one: in the server-rendered HTML of *every* page, `useLocation()`
+  returns `/`, `useParams()` returns `{}`, and `useRouteData()` returns
+  `undefined`, while the hydrated client is correct — provider and hooks hold
+  different `createContext()` objects. The plugin prevents it by keeping
+  `@pracht/*` in `ssr.noExternal`; listing a `@pracht/*` package in
+  `ssr.external` overrides that and brings the split back.
+- **Missing shell** — an unregistered shell name throws at manifest resolution
+  (`Unknown shell "..." for route "...". Did you mean "..."? Registered shells:
+  ...`) and appears in the dev error overlay as soon as the manifest loads.
+  Check `defineApp({ shells })` and the route/group assignment.
+- **404** — usually step 1, but a 404 on a URL you *do* expect means the loader
+  threw `notFound()`, not that matching failed. In `pracht dev`, unmatched
+  navigations render a dev-only 404 listing every registered route and its
+  render mode (also printed at dev-server startup, also in `pracht inspect
+  routes`). Apps declaring `defineApp({ notFound })` render their own 404 page
+  in dev and production alike, so that table is not shown — read `pracht
+  inspect routes` directly.
+
+### 5. Middleware
+
+- It must be registered in `defineApp({ middleware })` and applied via
+  `middleware: ["name"]` on the route or group. An unregistered name (route,
+  group, or `api.middleware`) throws at manifest resolution: `Unknown
+  middleware "..." for route "...". Did you mean "..."? Registered middleware:
+  ...`
+- Middleware is wrap-around and server-side only, wrapping loaders and API
+  handlers. It must always return a `Response`, either from `await next()` or
+  by short-circuiting. Common failures:
+
+| Bug | Error |
+| --- | ----- |
+| Forgetting `return next()` | `Middleware "..." did not return a Response` |
+| Calling `next()` twice | `Middleware "..." called next() multiple times` |
+| Mutating a non-object `context` | Silent — mutations don't propagate; always pass an object |
+
+### 6. API routes
+
+- They live in `src/api/`, auto-discovered, no manifest entry.
+  `pracht inspect api --json` for the inventory.
+- Path maps to URL: `src/api/health.ts` → `/api/health`,
+  `src/api/users/[id].ts` → `/api/users/:id`.
+- Each file exports named method handlers (`GET`, `POST`, …) or one default
+  handler that branches on `request.method`. A missing method handler is a 405
+  when there is no default.
+
+### 7. Vite plugin and HMR
+
+- Is `pracht()` in `vite.config.ts`? Virtual modules are
+  `virtual:pracht/client` (hydration), `virtual:pracht/server` (SSR),
+  `virtual:pracht/islands-client` (islands hydration).
+- HMR only watches `src/routes/`, `src/shells/`, `src/middleware/`,
+  `src/api/`, `src/server/`, `src/islands/`.
+- What each change does: editing `src/routes.ts` restarts the dev server
+  (`server.restart()`, not a browser reload). Route, shell, and island
+  components use Preact Fast Refresh; route/shell edits and client-reachable
+  loader dependencies also re-fetch active route data, with rapid saves
+  coalesced so the newest result settles last and a failed latest refresh
+  falling back to a reload. Adding or removing a route `loader` or route/shell
+  `head` export reloads so generated client hints stay current, and editing a
+  route/shell exporting document `headers()` reloads because CSP and other
+  response headers cannot be patched. Compiled formats get refresh
+  instrumentation after their companion Vite plugin runs, but Markdown, MDX,
+  and configured additional formats reload conservatively because a transform
+  may synthesize `headers()` from metadata; default `.tsrx` preserves state
+  when its source is headerless. Everything else invalidates the server module.
+
+### 8. Build and deployment
+
+- `pracht build` runs the client and server builds, then prerenders SSG/ISG
+  routes. On serverful adapters a failed path is warned about and skipped, but
+  the build fails if *every* attempted prerender returns non-200 — use the
+  reported underlying error to fix the shared loader/render dependency; partial
+  output stays valid. Static exports fail on any bad path.
+- `pracht preview` builds and serves production output locally (Node runs
+  `dist/server/server.js`; Cloudflare delegates to `wrangler dev`).
+- `pracht inspect build --json` reports the resolved adapter target plus the
+  client/CSS/JS manifests from the last build.
+- Client assets land in `dist/client/`, the server bundle in `dist/server/`.
+  The ISG manifest is `dist/server/isg-manifest.json`; on Cloudflare the build
+  also copies it to `dist/client/_pracht/isg.json` for the worker to read via
+  the assets binding.
+- Confirm the adapter in `pracht({ adapter: … })` matches the deployment
+  target.
+
+## Framework internals
+
+- `handlePrachtRequest()` dispatches: API routes → middleware → loader →
+  render → HTML assembly.
+- Route-state JSON is returned when the `x-pracht-route-state-request` header
+  is present (client-side navigation).
+- Hydration state is injected as `window.__PRACHT_STATE__`.
+- `initClientRouter()` intercepts link clicks and fetches that route state.
 
 $ARGUMENTS