create-pracht 0.3.0 → 0.4.1

package/skills/scaffold-tests/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: scaffold-tests
+version: 1.1.0
+description: |
+  Scaffold Vitest unit/integration tests for pracht routes, loaders, and
+  middleware. Asks the user once whether to use vitest browser mode with
+  `vitest-browser-preact` (real DOM, real events) or classic JSDOM-based
+  tests with `@testing-library/preact`. Wires `vitest.config.ts`, mocks
+  `LoaderArgs`, and emits ready-to-run files.
+  Use when asked to "scaffold tests", "set up Vitest", "add unit tests",
+  "test this loader", or "test this route".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Scaffold Tests
+
+Generate Vitest tests aligned with pracht's testing recipe
+(`examples/docs/src/routes/docs/recipes-testing.md`). Loaders and API handlers
+are plain async functions — they test directly with no framework bootstrap.
+Component tests need a renderer; the user picks the flavor.
+
+## Step 1: Pick the rendering strategy
+
+Use `AskUserQuestion` to choose between:
+
+1. **Browser mode** — `vitest` with `@vitest/browser` and
+   `vitest-browser-preact`.
+   - Pros: real browser, real events, fewer hydration false positives,
+     screenshots, works for SPA-mode interaction tests.
+   - Cons: slower, heavier setup, requires a browser binary on CI.
+2. **JSDOM** — `vitest` with `@testing-library/preact`.
+   - Pros: fast, lightweight, runs anywhere.
+   - Cons: JSDOM lacks layout, certain DOM APIs; brittle for complex UIs.
+
+If the project already has one configured, default to it and confirm.
+
+## Step 2: Install dependencies
+
+Detect the package manager from the lockfile.
+
+Common (both modes):
+
+```bash
+pnpm add -D vitest @types/node
+```
+
+Component-test extras — `@preact/preset-vite` must be an explicit dev
+dependency: the configs in Step 3 import it, and a transitive-only copy
+fails under pnpm's strict `node_modules`.
+
+**Browser mode**:
+
+```bash
+pnpm add -D @vitest/browser playwright vitest-browser-preact @preact/preset-vite
+```
+
+**JSDOM mode**:
+
+```bash
+pnpm add -D jsdom @testing-library/preact @testing-library/jest-dom @preact/preset-vite
+```
+
+If the project only needs loader/middleware tests (no component rendering),
+skip the extras entirely and use the plugin-less config in Step 3.
+
+## Step 3: Wire `vitest.config.ts`
+
+**Browser mode**:
+
+```ts
+import { defineConfig } from "vitest/config";
+import preact from "@preact/preset-vite";
+
+export default defineConfig({
+  plugins: [preact()],
+  test: {
+    browser: {
+      enabled: true,
+      provider: "playwright",
+      instances: [{ browser: "chromium" }],
+    },
+  },
+});
+```
+
+**JSDOM mode**:
+
+```ts
+import { defineConfig } from "vitest/config";
+import preact from "@preact/preset-vite";
+
+export default defineConfig({
+  plugins: [preact()],
+  test: {
+    environment: "jsdom",
+    setupFiles: ["./test/setup.ts"],
+  },
+});
+```
+
+`test/setup.ts` (JSDOM only):
+
+```ts
+import "@testing-library/jest-dom/vitest";
+```
+
+**Loader/middleware-only mode** (no components) — matches the minimal config
+in `recipes-testing.md`; no preset, no extra deps:
+
+```ts
+import { defineConfig } from "vitest/config";
+
+export default defineConfig({
+  test: {
+    // Exclude E2E tests (run those with Playwright)
+    exclude: ["e2e/**", "node_modules/**"],
+  },
+});
+```
+
+If `vitest.config.ts` already exists, merge — never clobber.
+
+## Step 4: Generate the tests
+
+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.
+
+This skill covers **loaders, middleware, and components**. For API handlers
+(`src/api/**`), delegate to `/pracht-test-api` — it owns handler enumeration and
+per-method test generation; don't duplicate a weaker version here.
+
+Use `pracht inspect routes --json` to find targets. Ask the user which subset
+to scaffold, or pass paths via `$ARGUMENTS`.
+
+### Loader test template
+
+```ts
+import { describe, it, expect } from "vitest";
+import { loader } from "./<route-file>";
+
+function args(url: string, init?: RequestInit) {
+  const request = new Request(url, init);
+  return {
+    request,
+    params: {} as Record<string, string>,
+    context: {} as never,
+    url: new URL(request.url),
+    signal: AbortSignal.timeout(5000),
+    route: {} as never,
+  };
+}
+
+describe("<route> loader", () => {
+  it("returns the expected shape", async () => {
+    const data = await loader(args("http://localhost/<path>"));
+    expect(data).toBeDefined();
+  });
+});
+```
+
+### Middleware test template
+
+```ts
+import { describe, it, expect } from "vitest";
+import { middleware } from "./<middleware-file>";
+
+describe("<name> middleware", () => {
+  const ok = new Response("ok", { status: 200 });
+  const next = async () => ok;
+
+  it("redirects unauthenticated requests", async () => {
+    const request = new Request("http://localhost/dashboard");
+    const response = await middleware(
+      {
+        request,
+        params: {},
+        context: {} as never,
+        url: new URL(request.url),
+        signal: AbortSignal.timeout(5000),
+        route: {} as never,
+      },
+      next,
+    );
+    expect(response.status).toBe(302);
+    expect(response.headers.get("location")).toMatch(/^\/login/);
+  });
+
+  it("calls through when authenticated", async () => {
+    const request = new Request("http://localhost/dashboard", {
+      headers: { cookie: "session=valid" },
+    });
+    const response = await middleware(
+      {
+        request,
+        params: {},
+        context: {} as never,
+        url: new URL(request.url),
+        signal: AbortSignal.timeout(5000),
+        route: {} as never,
+      },
+      next,
+    );
+    expect(response).toBe(ok);
+  });
+});
+```
+
+### Component test template (browser mode)
+
+```tsx
+import { describe, it, expect } from "vitest";
+import { render } from "vitest-browser-preact";
+import { Component } from "./<route-file>";
+
+describe("<route> component", () => {
+  it("renders the heading", async () => {
+    const screen = render(<Component data={{ /* mock loader data */ }} params={{}} />);
+    await expect.element(screen.getByRole("heading")).toBeVisible();
+  });
+});
+```
+
+### Component test template (JSDOM)
+
+```tsx
+import { describe, it, expect } from "vitest";
+import { render, screen } from "@testing-library/preact";
+import { Component } from "./<route-file>";
+
+describe("<route> component", () => {
+  it("renders the heading", () => {
+    render(<Component data={{ /* mock loader data */ }} params={{}} />);
+    expect(screen.getByRole("heading")).toBeInTheDocument();
+  });
+});
+```
+
+## Step 5: Wire `package.json`
+
+Add (or merge) scripts:
+
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}
+```
+
+If `pnpm test` already exists, do not overwrite.
+
+## Step 6: Verify
+
+```bash
+pnpm test
+pracht verify --json
+```
+
+If anything fails on first run, report the failure and the fix. Do not commit
+broken scaffolding.
+
+## Rules
+
+1. Ask the rendering-strategy question once per project; persist by
+   inspecting `vitest.config.ts` on subsequent runs.
+2. Only test exports that exist — read the route file before generating.
+3. Use the recipe's `args()` helper shape for `BaseRouteArgs`/`LoaderArgs`
+   construction.
+4. For routes with `getStaticPaths`, scaffold a separate test that calls it.
+5. Generated tests should pass on first run with a placeholder assertion;
+   the user fills in real expectations.
+
+$ARGUMENTS

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,207 @@
+---
+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.
+- `src/pracht-capabilities.d.ts` — only when the app registers capabilities:
+  input/output types from the capability schemas, so `invokeCapability()`,
+  `callCapability()`, and `<Form capability>`'s `onCapabilityResult` infer
+  types from the capability name.
+
+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