create-pracht 0.3.0 → 0.4.0

package/skills/tune-render-mode/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: tune-render-mode
+version: 1.1.0
+description: |
+  Recommend the right pracht render mode (ssg, isg, ssr, spa) for each route
+  based on what its loader actually does. Most apps pick a mode once and never
+  revisit; this skill surfaces routes that are mis-tuned.
+  Use when asked to "tune render modes", "make my site faster", "should this
+  route be SSG", "audit render modes", or "review SSG/ISG/SSR choices".
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Grep
+  - Glob
+---
+
+# Pracht Tune Render Mode
+
+Walk every route, read its loader, and recommend the cheapest render mode that
+still satisfies the route's data dependencies.
+
+This is a **tune** skill, not a report-only audit: it ends by applying edits.
+The contract is propose-then-apply — produce the recommendation table and the
+exact diffs first, then apply them **only after the user explicitly confirms**
+(per route or as a batch). Never edit before that confirmation.
+
+## Decision Tree
+
+For each route:
+
+1. **No `loader`, no `getStaticPaths`, no per-request data** → **`ssg`**
+   - Pure UI. Build once, serve from CDN. Highest performance.
+
+2. **Loader reads only build-time-stable data** (filesystem, static config,
+   typed CMS export, no `request`/`params`/`context.env` use) → **`ssg`** or
+   **`isg`**
+   - Pick `isg` with `timeRevalidate(seconds)` if the source can change between
+     deploys (CMS, pricing pages, public catalog).
+   - Pick `ssg` if the source only changes when you redeploy.
+
+3. **Loader reads `params` to fetch data, but not `request`/cookies** →
+   **`ssg`** with `getStaticPaths`, or **`isg`** if the universe of params is
+   open-ended (millions of slugs).
+
+4. **Loader reads `request`, but the data is shareable** (`request-static`:
+   request used only for cache keys like `Accept-Language`, never for
+   identity) → **`ssr`** by default; **`isg`** is possible on adapters whose
+   cache can key on the varying dimension (e.g. a normalized cache key at a
+   Cloudflare gateway). If the variant fan-out is unbounded or the adapter
+   cache can't express the Vary, stay on `ssr`.
+
+5. **Loader reads cookies, auth headers, `context.env` per-request, or
+   anything personalized** → **`ssr`**
+   - Auth dashboards, anything user-specific, anything that varies by user
+     identity at request time.
+
+6. **Heavy client interactivity, no SEO need, auth-gated** → **`spa`**
+   - Internal admin tools, post-login dashboards where the first paint can be a
+     skeleton.
+
+## Step 1: Enumerate
+
+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.
+
+Capture: `path`, `file`, current `render`, `revalidate`, `middleware`, and
+the top-level `mode` field (manifest vs pages router — Step 4 depends on it).
+
+## Step 2: Read each loader
+
+For each route, open the file and look at the `loader`/`getStaticPaths`
+exports. Tag the loader with one of:
+
+- `none` — no loader at all
+- `static` — only reads imports / pure data
+- `param-static` — reads `params` only
+- `request-static` — reads `request` for cache keys but data is shareable
+  (e.g. `Accept-Language`) — decision-tree branch 4
+- `request-personalized` — reads cookies, auth headers, user-specific
+  `context.env` lookups — decision-tree branch 5
+
+## Step 3: Recommend
+
+Produce a table:
+
+| Route | Current | Recommended | Severity | Reason |
+| ----- | ------- | ----------- | -------- | ------ |
+
+Severity: `error` (broken today, e.g. `ssg` with a loader that reads
+`request` — cannot be prerendered correctly), `warn` (works but mis-tuned,
+e.g. `ssr` with no loader), `info` (optional improvement, e.g. hydration
+tuning).
+
+Examples of recommendations:
+- `ssr` → `ssg` when loader is empty: "no loader; no per-request data — make it
+  static." (`warn`)
+- `ssr` → `isg(3600)` when loader fetches a public CMS: "shared data, freshness
+  acceptable at 1 hour." (`warn`)
+- `ssg` → `ssr` when loader reads `request.headers.get('cookie')`: "reads
+  request — cannot be prerendered." (`error`)
+- `spa` → `ssr` when route has SEO-relevant `head()` and unauthenticated
+  visitors should see content. (`warn`)
+
+## Step 3b: Consider the hydration mode too
+
+Render mode controls when HTML is generated; **hydration mode** controls how
+much JavaScript ships afterwards (`hydration: "full" | "islands" | "none"`,
+default `"full"` — see `docs/ISLANDS.md`). A current `@pracht/cli` emits the
+resolved `hydration` per route in the inspect JSON; if your CLI predates the
+field (absent from the JSON), grep the manifest for `hydration:` (pages apps:
+`HYDRATION` exports) instead. While tuning, also flag:
+
+- Routes with **no interactivity at all** (no event handlers, no hooks) →
+  `hydration: "none"` — zero JS shipped.
+- Content-heavy routes with **one or two isolated widgets** (counter, search
+  box, newsletter form) → `hydration: "islands"` with the widgets moved to
+  `src/islands/`.
+- Caveats: islands routes use MPA-style full-document navigation (no client
+  router), island props must be JSON-serializable, and `render: "spa"` cannot
+  combine with `"islands"`/`"none"`.
+
+## Step 4: Propose diffs, then apply on confirmation
+
+Present the exact edits and wait for approval. Where the edit lands depends
+on the router `mode` from Step 1:
+
+- **Manifest apps**: edit `src/routes.ts` to update the `render` field. For
+  ISG, add `revalidate: timeRevalidate(N)` and import `timeRevalidate` from
+  `@pracht/core`. Hydration changes update the `hydration` field the same
+  way.
+- **Pages apps**: render mode is a per-file constant —
+  `export const RENDER_MODE = "ssg"` in the page module (valid values
+  `"ssr" | "ssg" | "isg" | "spa"`; the default is `"ssr"`, overridable
+  globally via `pracht({ pagesDefaultRender: "..." })` in vite config).
+  Hydration is `export const HYDRATION = "..."` in the same file. If most
+  pages want the same mode, prefer changing `pagesDefaultRender` over adding
+  a constant to every file.
+
+Apply the edits only after the user confirms.
+
+## Rules
+
+1. Never silently change render modes. Always present the recommendation and
+   the exact diff first; apply only after explicit user approval.
+2. If a route uses `auth` middleware, default to `ssr` — auth implies cookies.
+3. All three adapters support ISG — the mechanisms differ. Confirm which
+   adapter is in play, then use this capability table:
+
+   | Adapter    | ISG mechanism (default)                                        | Notes |
+   | ---------- | -------------------------------------------------------------- | ----- |
+   | Node       | Filesystem: `isg-manifest.json` + file-mtime revalidation      | Serves stale immediately, refreshes in place. |
+   | Cloudflare | Worker-managed Workers Cache API, **per colo** — works without any extra config | `cloudflareAdapter({ cache: true })` + `"cache": { "enabled": true }` in wrangler config is an **optional upgrade** that moves time-revalidated routes to an edge-tier cache in front of the Worker; webhook-only routes stay worker-managed. Webhook invalidation on the default path is per-colo, not a global purge. |
+   | Vercel     | Native ISR: Build Output API prerender functions with `expiration` from the time policy; `PRACHT_REVALIDATE_TOKEN` becomes the `bypassToken` (must be set at build time) | See docs/ADAPTERS.md. |
+
+4. For dynamic SSG/ISG routes, ensure `getStaticPaths` exists. Flag if missing.
+5. Use `pracht inspect routes --json` rather than reading `src/routes.ts`
+   manually — the resolved graph already accounts for groups and inheritance.
+
+$ARGUMENTS

package/skills/typed-routes/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: typed-routes
+version: 1.1.0
+description: |
+  Add or maintain pracht typed routes, typed links, route-object navigation,
+  and generated href helpers. Use when asked to "add typed routes", "fix typed
+  links", "replace hard-coded hrefs", "run typegen", or make navigation route-id
+  based instead of string based.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Typed Routes
+
+Use this workflow to keep route ids, params, links, and navigation type-safe.
+
+## Step 1: Inspect the resolved graph
+
+The resolved app graph is the source of truth — not a manual glob of `src/`.
+
+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.
+
+```bash
+pracht inspect routes --json
+```
+
+Check every route has a stable id. Explicit `id` fields are preferred for routes
+that app code links to, because fallback ids change when paths change.
+
+```ts
+route("/products/:id", () => import("./routes/products/[id].tsx"), {
+  id: "product",
+  render: "ssr",
+});
+```
+
+Any route without an explicit `id` — manifest apps included, not just
+pages-router apps — gets a fallback id derived from the route path (`/` →
+`index`, `/blog/:slug` → `blog-slug`, `/*` → `splat`).
+
+## Step 2: Generate route types and helpers
+
+Run:
+
+```bash
+pracht typegen
+```
+
+This writes:
+
+- `src/pracht.d.ts` — module augmentation for route ids, params, loader data
+  types, and API route request/response types (consumed by `apiFetch()`).
+- `src/pracht-routes.ts` — runtime `href()` helper backed by the same route map.
+
+Earlier versions wrote the declaration to `src/pracht-routes.d.ts`; typegen
+removes that stale file automatically (TypeScript silently ignored it next to
+the same-named `.ts` helper).
+
+Do not hand-edit generated files. If they are stale, update the route graph and
+run typegen again — or rely on `pracht dev`, which refreshes them when route
+files are added, removed, or renamed and when the route manifest or an imported
+definition module changes. The dev banner prompts for the initial typegen run
+when `src/pracht.d.ts` does not exist. In CI, prefer:
+
+```bash
+pracht typegen --check
+```
+
+## Step 3: Replace string navigation where it matters
+
+### Components
+
+```tsx
+import { Link, useNavigate } from "@pracht/core";
+
+export function ProductLink({ id }: { id: string }) {
+  const navigate = useNavigate();
+
+  return (
+    <>
+      <Link route="product" params={{ id }} search={{ ref: "home" }}>
+        View product
+      </Link>
+      <button onClick={() => void navigate({ route: "product", params: { id } })}>
+        Open product
+      </button>
+    </>
+  );
+}
+```
+
+`<Link>` renders a normal `<a>` and the client router intercepts it like any
+same-origin anchor. It also accepts navigation-behavior props:
+`prefetch="none" | "hover" | "intent" | "viewport" | "render"` (per-link
+prefetch strategy, default `"intent"`), `preserveScroll` (keep the scroll
+position), and `viewTransition` (animate the navigation with the View Transitions API
+where supported). There is also an imperative `prefetch()` export and a
+`useNavigation()` hook for pending navigation/submission state.
+
+### Outside components
+
+```ts
+import { href } from "./pracht-routes";
+
+const productUrl = href("product", {
+  params: { id: "123" },
+  search: { tab: "details" },
+});
+```
+
+Use `href()` in loaders that return URLs, sitemap helpers, menu config, test
+fixtures, and other non-component code.
+
+### Loader data
+
+After typegen, `useRouteData(routeId)` returns that route's loader data with
+no generic — route ids autocomplete and the type follows the route's loader
+(or its separate loader file from the manifest):
+
+```tsx
+import { useRouteData } from "@pracht/core";
+
+export function Component() {
+  const data = useRouteData("product");
+  return <h1>{data.product.name}</h1>;
+}
+```
+
+Prefer this over `useRouteData<typeof loader>()` when typegen runs; keep the
+generic form for projects that do not generate route types. Routes without a
+loader type their data as `undefined`. The id must be the active route — dev
+mode warns on mismatches.
+
+### API routes
+
+After typegen, `apiFetch()` type-checks API calls end to end — paths,
+methods, params, bodies and queries (for `defineApi()` routes), and response
+types:
+
+```ts
+import { apiFetch } from "@pracht/core";
+
+const item = await apiFetch("/api/items/:id", { params: { id: "42" } });
+```
+
+See docs/API_VALIDATION.md for `defineApi()` and validation error handling.
+Typegen discovers API route files without importing them, so it is safe for
+route modules that initialize runtime-only services at module scope.
+
+Query and params values cross the wire as strings — write schemas that accept
+string input (`z.coerce.number()`, not `z.number()`); `apiFetch()` rejects
+query and params keys without a string representation at compile time when the
+schema exposes a concrete input type. Handlers that need a custom status keep
+typed payloads with `json(value, { status })`.
+
+## Step 4: Param and search rules
+
+Generated param types accept `RouteParamInput = string | number | boolean`
+(values are stringified into the path), so:
+
+- `:id` requires `params: { id: RouteParamInput }` — a `string` is typical,
+  but `number`/`boolean` also typecheck.
+- `*` requires `params: { "*": RouteParamInput }`.
+- `:path*` requires `params: { path: RouteParamInput }`.
+- Routes with no dynamic segments should omit `params`.
+- Missing and extra params should fail at typecheck time.
+- `search` currently accepts `string`, `URLSearchParams`, or an object of
+  primitive values/arrays; route-specific search schemas can be added later.
+
+## Step 5: Verify
+
+Run at least:
+
+```bash
+pracht typegen --check
+pnpm typecheck
+pracht verify --json
+```
+
+If navigation changed, add or update Playwright coverage for both the rendered
+anchor `href` and client-side navigation without a full page reload.
+
+## Rules
+
+1. Always start from `pracht inspect routes --json` or `pracht typegen`; do not
+   infer the full route map from files by hand.
+2. Prefer adding explicit ids before converting links for important routes.
+3. Never edit `src/pracht.d.ts` or `src/pracht-routes.ts` manually.
+4. Keep plain `<a href="...">` where a URL is genuinely external, opaque, or
+   user-provided.
+5. After adding/removing/renaming routes, run `pracht typegen` and include the
+   generated file changes in the same commit.
+
+$ARGUMENTS

package/skills/upgrade-pracht/SKILL.md

@@ -0,0 +1,151 @@
+---
+name: upgrade-pracht
+version: 1.0.0
+description: |
+  Upgrade the @pracht/* packages in an app safely: inventory installed
+  versions, read the changelogs between installed and target, map breaking
+  changes to actual usage in the codebase, apply the upgrade, and walk the
+  verification ladder (doctor, typegen, verify, build, tests).
+  Use when asked to "upgrade pracht", "update @pracht packages", "bump the
+  framework", "what changed in the new pracht version", or "is this pracht
+  upgrade safe".
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Upgrade
+
+Upgrade `@pracht/*` dependencies with the changelog read *before* the install,
+not after the build breaks.
+
+## Step 1: Inventory
+
+List every installed pracht package and its resolved version:
+
+```bash
+pnpm list --depth 1 --json | grep -A2 '@pracht/'   # or read package.json + lockfile
+```
+
+The family: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
+`@pracht/adapter-node`, `@pracht/adapter-cloudflare`, `@pracht/adapter-vercel`,
+`@pracht/preact-ssr-precompile`. Get the latest published versions with
+`npm view <pkg> version`.
+
+## Step 2: Understand the versioning model
+
+Pracht packages are **independently versioned** (the repo's changesets config
+has empty `fixed`/`linked` groups) — `@pracht/core` can be at 0.9.x while
+`@pracht/cli` is at 1.6.x. There is no "one framework version". Two
+consequences:
+
+1. **Internal dependencies are pinned exact.** Published packages depend on
+   their siblings at exact versions (e.g. `@pracht/vite-plugin@0.5.0` depends
+   on `@pracht/core@0.9.0`, not a range). Upgrade the whole family in one
+   move; upgrading only one package can drag in a second copy of
+   `@pracht/core` and split the runtime.
+2. **Most packages are 0.x**, so under semver a *minor* bump may be breaking —
+   treat `### Minor Changes` entries on 0.x packages with the same care as
+   majors.
+
+After any upgrade, confirm a single core resolution:
+
+```bash
+pnpm why @pracht/core   # exactly one version may appear
+```
+
+## Step 3: Read the changelogs between installed and target
+
+Only `@pracht/cli` ships `CHANGELOG.md` in its npm tarball
+(`node_modules/@pracht/cli/CHANGELOG.md`); the other packages publish `dist/`
+only. Fetch their changelogs from the repo instead:
+
+```
+https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGELOG.md
+```
+
+| Package | Repo directory |
+| ------- | -------------- |
+| `@pracht/core` | `packages/framework` |
+| `@pracht/cli` | `packages/cli` |
+| `@pracht/vite-plugin` | `packages/vite-plugin` |
+| `@pracht/adapter-node` / `-cloudflare` / `-vercel` | `packages/adapter-*` |
+| `@pracht/preact-ssr-precompile` | `packages/preact-ssr-precompile` |
+
+Changelogs are changesets-generated: `## X.Y.Z` sections containing
+`### Major Changes` / `### Minor Changes` / `### Patch Changes`. Read every
+section between the installed and target version of every installed package.
+
+## Step 4: Map changes onto this app
+
+Classify each entry as **breaking** / **feature** / **fix**. For each breaking
+(or 0.x minor) entry, grep the app for the APIs, exports, config options, and
+generated-file shapes it names, and record: affected files, the migration the
+changelog prescribes, and whether it can be applied mechanically. Also
+re-check peer ranges after a major target bump — `@pracht/vite-plugin`
+requires `vite` (^8), `@pracht/adapter-cloudflare` requires `vite` and
+`wrangler` (^4.81), `@pracht/core` requires `preact` (^10) and
+`preact-render-to-string` (^6).
+
+Present the plan as a table:
+
+| Package | Installed → Target | Breaking entries | App impact | Migration |
+| ------- | ------------------ | ---------------- | ---------- | --------- |
+
+## Step 5: Confirm, then apply
+
+Use `AskUserQuestion` before touching anything when breaking migrations are
+required: confirm the target versions and which migrations to apply. Then:
+
+```bash
+pnpm up '@pracht/core@<v>' '@pracht/cli@<v>' '@pracht/vite-plugin@<v>' <adapters...>
+```
+
+Upgrade every installed `@pracht/*` package in the same command. Apply the
+agreed code migrations with minimal diffs, one changelog entry at a time.
+
+## Step 6: Verification ladder
+
+Run in order; stop and fix at the first failure:
+
+```bash
+pracht doctor --json          # wiring still valid
+pracht typegen --check        # generated route types up to date?
+pracht typegen                # regenerate if --check failed or routes changed
+pracht verify --json          # framework-aware checks
+pracht build                  # full production build (budgets included)
+pnpm test                     # the app's own suite
+```
+
+`pracht doctor`, `verify`, and `typegen --check` exit non-zero on failure, so
+they gate CI cleanly.
+
+## Step 7: Rollback note
+
+If the ladder cannot be made green, roll back rather than shipping a
+half-upgrade:
+
+```bash
+git restore package.json pnpm-lock.yaml && pnpm install
+git checkout -- <migrated files>   # or revert the upgrade commit
+```
+
+Because internal deps are exact-pinned, a *partial* rollback (one package
+back, the rest forward) recreates the duplicate-core problem from Step 2 —
+roll the whole family back together.
+
+## Rules
+
+1. Never mix `@pracht/*` versions from different release waves — upgrade and
+   roll back the family as a unit, and verify with `pnpm why @pracht/core`.
+2. Read changelogs before installing, not after something breaks.
+3. Never apply a breaking-change migration without explicit user confirmation
+   via `AskUserQuestion`.
+4. Treat 0.x minor bumps as potentially breaking.
+5. Do not hand-edit lockfiles; let the package manager resolve.
+
+$ARGUMENTS