create-pracht 0.4.2 → 0.6.0

package/skills/pracht-scaffold/SKILL.md

@@ -53,7 +53,7 @@ pracht generate api --path /health --methods GET,POST
 - `--shell`/`--middleware` names must already be registered in the app manifest — the CLI errors otherwise. Generate the shell/middleware first, then the route that references it.
 - If the pracht MCP server is registered (docs/MCP.md), call the `generate_route`/`generate_shell`/`generate_middleware`/`generate_api` MCP tools instead of Bash — same behavior, structured results.
 - Add `--json` when another agent/tool needs machine-readable output.
-- `generate route` also emits a Playwright smoke test in `e2e/` when the app has a Playwright setup (`playwright.config.*` or an `e2e/` directory). Pass `--no-test` to skip it, `--test` to force it. Keep the generated test — it is the output-level proof the route works.
+- `generate route` also emits a Playwright smoke test in `e2e/` when the app has a Playwright setup (`playwright.config.*` or an `e2e/` directory). Pass `--no-test` to skip it, `--test` to force it. The test imports `@playwright/test`; if that dependency is absent, follow the generator's install note before typechecking. Keep the generated test — it is the output-level proof the route works.
 - Use `pracht inspect routes --json` or `pracht inspect api --json` to confirm current wiring before manual edits when the existing graph matters. `pracht inspect` requires the pracht plugin registered in the project's vite config.
 - If the app has typed routes (`src/pracht-routes.ts` / `.d.ts`) or the user asks for typed links, run `pracht typegen` after adding or renaming routes.
 - If the app commits `.pracht/app-graph.json`, run `pracht plan --write` after changing routes and include the refreshed snapshot — `pracht verify` fails when it is stale.
@@ -161,6 +161,16 @@ export function GET({ params, url }: ApiRouteArgs) {
 - Use `request.json()`, `request.formData()`, etc. for body parsing.
 - Always return `Response` objects (typically `Response.json()`).
 - Dynamic segments use bracket syntax in filenames: `[id].ts`, `[...slug].ts`.
+- For live server→client updates, use Server-Sent Events:
+  `createEventStream(request, { keepAlive: 15 })` from `@pracht/core/server`
+  returns `{ response, send, close }` — return `response`, push with
+  `send({ data, event?, id? })`, and stop producing when `send()` returns
+  `false` (client disconnected). Consume in components with
+  `useEventSource(url, { json: true })` from `@pracht/core`. Works on all
+  adapters. For WebSockets use `isUpgradeRequest(request)` plus the
+  per-adapter recipes in `docs/ADAPTERS.md` (Cloudflare: API route + Durable
+  Object; Node: `nodeAdapter({ configureServerFrom })`; Vercel: unsupported —
+  use SSE).
 
 ## Wiring Into the Manifest (manual fallback only)
 

package/skills/pracht-test-api/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-test-api
-version: 1.1.0
+version: 1.2.0
 description: |
   Auto-generate Vitest request/response tests for every handler in `src/api/`.
   Each test instantiates a `Request`, calls the exported HTTP method handler
@@ -53,34 +53,28 @@ Ask the user which subset to scaffold or accept paths via `$ARGUMENTS`.
 ## Step 3: Generate one test per handler file
 
 Place tests next to the handler with `.test.ts` suffix
-(`src/api/users/[id].test.ts`). Use a small helper to construct
-`ApiRouteArgs`:
+(`src/api/users/[id].test.ts`). Use `createApiArgs()` from `@pracht/test`
+(add it as a dev dependency if missing) to construct `ApiRouteArgs`:
 
 ```ts
 import { describe, it, expect } from "vitest";
+import { createApiArgs, readJson } from "@pracht/test";
 import { GET, POST /* import only what the handler exports */ } from "./<file>";
 
-function args(url: string, init?: RequestInit, params: Record<string, string> = {}) {
-  const request = new Request(url, init);
-  return {
-    request,
-    params,
-    context: {} as never,
-    url: new URL(request.url),
-    signal: AbortSignal.timeout(5000),
-    route: {} as never,
-  };
-}
-
 describe("<METHOD> <api-path>", () => {
   it("returns 200 on a valid request", async () => {
-    const res = await GET(args("http://localhost<api-path>"));
+    const res = await GET(createApiArgs({ url: "<api-path>" }));
     expect(res).toBeInstanceOf(Response);
     expect(res.status).toBe(200);
   });
 });
 ```
 
+Pass `params` for dynamic segments, `body` for JSON payloads (plain objects
+are JSON-encoded with the right `Content-Type`), and use `submitForm()` for
+form-encoded/multipart POSTs — it drives the same `FormData` parsing path
+`defineApi()` uses.
+
 ## Step 4: Generate method-specific cases
 
 For each exported method, emit the smallest realistic case:
@@ -108,7 +102,7 @@ middleware is in that list. If it is, scaffold an extra test:
 
 ```ts
 it("rejects unauthenticated requests", async () => {
-  const res = await POST(args("http://localhost<api-path>", { method: "POST" }));
+  const res = await POST(createApiArgs({ url: "<api-path>", method: "POST" }));
   expect([401, 403, 302]).toContain(res.status);
 });
 ```
@@ -127,9 +121,9 @@ For handlers that return `Response.json(...)`, generate:
 
 ```ts
 it("returns JSON with the expected keys", async () => {
-  const res = await GET(args("http://localhost<api-path>"));
+  const res = await GET(createApiArgs({ url: "<api-path>" }));
   expect(res.headers.get("content-type")).toMatch(/application\/json/);
-  const body = await res.json();
+  const body = await readJson(res);
   expect(body).toEqual(expect.objectContaining({ /* fill in */ }));
 });
 ```

package/skills/pre-deploy/SKILL.md

@@ -1,11 +1,13 @@
 ---
 name: pre-deploy
-version: 1.2.0
+version: 1.3.0
 description: |
   Adapter-aware pre-deployment checklist for pracht apps targeting Node,
-  Cloudflare Workers, or Vercel. Catches the issues that only surface in the
-  production runtime: missing env vars, Node-only APIs in edge bundles,
-  ISG manifest absence, oversized edge bundles, missing wrangler/vercel config.
+  Cloudflare Workers, Vercel, or a pure static export. Catches the issues that
+  only surface in the production runtime: missing env vars, Node-only APIs in
+  edge bundles, ISG manifest absence, oversized edge bundles, missing
+  wrangler/vercel config, and static hosts missing clean-URL, 404, or security
+  header configuration.
   Use when asked to "pre-deploy check", "ready to ship?", "deployment
   checklist", "is my build production-safe", or before running `wrangler
   deploy` / `vercel deploy`.
@@ -27,8 +29,8 @@ 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.
 
-Read `vite.config.ts` and look for `nodeAdapter()`, `cloudflareAdapter()`, or
-`vercelAdapter()`. Confirm with:
+Read `vite.config.ts` and look for `nodeAdapter()`, `cloudflareAdapter()`,
+`vercelAdapter()`, or `staticAdapter()`. Confirm with:
 
 ```bash
 pracht inspect build --json
@@ -82,6 +84,10 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   are intentionally not trusted.
 - Reverse-proxy / TLS termination configured (out of scope for this skill —
   flag for confirmation).
+- If the proxy strips Vite's deploy base, confirm
+  `nodeAdapter({ basePathStripped: true })`; application code should still
+  observe the public base in `request.url`, and the proxy must own the public
+  bare-base redirect (`/app` to `/app/`).
 
 ### Cloudflare Workers (`@pracht/adapter-cloudflare`)
 
@@ -93,7 +99,11 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   metadata (`buildTarget`, manifests, `resolvedApp`, ...) that `server.js`
   exports for the prerender pass.
 - `assets.directory` points to `dist/client`.
-- `compatibility_date` is set and recent.
+- `compatibility_date` is set, and is a date the installed workerd supports.
+  It must not be *newer* than the runtime: workerd refuses to start with
+  "This Worker requires compatibility date X, but the newest date supported
+  by this server binary is Y". Never set it to today's date — that is by
+  construction at or beyond the newest released workerd.
 - Bindings declared in wrangler config for every `context.env.*` access in
   loaders, middleware, and API routes (grep, then cross-check).
 - **No Node-only APIs in the server bundle.** Grep the server files for:
@@ -134,22 +144,85 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
 - Required env vars are configured in the Vercel project (cannot verify from
   CLI without `vercel env pull` — run that and diff against `process.env.*`
   references).
-- Edge runtime constraints: pracht **always** writes the function's
-  `.vc-config.json` with `runtime: "edge"` — there is no Node runtime
-  variant, so run the same Node-only API check as Cloudflare
-  **unconditionally** for Vercel builds. Do not skip it based on a runtime
-  probe.
+- Edge runtime constraints: the render function's `.vc-config.json` is
+  **always** written with `runtime: "edge"`, so run the same Node-only API
+  check as Cloudflare **unconditionally** for Vercel builds. Do not skip it
+  based on a runtime probe — ISG routes run the same bundle on Node, but any
+  Node-only API still breaks the edge function.
+- ISG functions: every `<route>.prerender-config.json` must sit next to a
+  **Serverless** `<route>.func` (`.vc-config.json` with `launcherType:
+  "Nodejs"`). Vercel rejects a prerender config paired with an edge function:
+  `Unexpected function type "EdgeFunction" at path "<route>"`.
+- Region configuration: `vercelAdapter({ regions: "all" })` is valid for the
+  Edge render function, but generated Node ISG function configs must omit
+  `regions` so the project's default Serverless region applies. Node configs
+  may only contain arrays of concrete region identifiers.
 - An API route importing `@pracht/image/node` is an error for the Vercel Edge
   function. Require `vercelLoader` (with aligned allowed sizes) or
   `passthroughLoader` instead.
 - Build Output API v3 sanity: `config.json` has `version: 3`.
 
+### Static export (`@pracht/adapter-static`)
+
+`adapterTarget` is `"static"`. There is no server to get wrong, so the
+checklist is about what the *host* must do and what the build cannot enforce.
+
+- `dist/client/` exists and is the deploy root. `dist/server/` is build tooling
+  only — it must not be uploaded (it contains the prerender bundle).
+- The build itself is the gate: it fails closed on `ssr`/`isg` routes, SPA
+  loaders, non-full SPA hydration, API routes, route/not-found middleware,
+  network-exposed capabilities, and any Vite `base` that is not `/` or a
+  root-absolute path (CDN and document-relative bases are rejected). If
+  `pracht build` succeeded, those contracts already hold — do not re-derive
+  them by hand. Report a failing build verbatim; the message names the routes.
+- Host must serve `index.html` for directory URLs (clean URLs). Confirm the
+  host's setting: S3 website endpoints need an index document, nginx needs
+  `try_files $uri $uri/index.html`, GitHub Pages and Netlify do it by default.
+- Host must map `404.html` as the error document, otherwise unknown URLs get
+  the host's generic error page instead of the app's `notFound` route. Verify
+  `dist/client/404.html` exists; if it does not, the app declares no `notFound`
+  page — flag it as a `warn`.
+- **Security headers are not applied.** Every other adapter sets the four
+  default security headers at request time; a static host has no request
+  runtime. `dist/server/headers-manifest.json` records the headers each route
+  *would* have carried — mirror the ones you need in the host's own header
+  config (`_headers` on Netlify, CloudFront response header policies, nginx
+  `add_header`). This is an `error` for any app handling user input, and
+  `warn` otherwise. HSTS and CSP are host-side decisions either way.
+- If `staticAdapter({ fallback })` is configured, the host needs a rewrite of
+  unmatched URLs to that file, and the rewrite must not shadow real files.
+  Note that it makes unknown URLs answer `200` (soft 404s). Without the
+  rewrite the fallback file is inert — deep links into dynamic `render: "spa"`
+  routes will 404.
+- Smoke test the real output, not the dev server:
+  `pracht preview --skip-build` serves `dist/client/` the way a dumb host
+  would. Check `/`, one dynamic SSG path, one deep link into a SPA route, and
+  one unknown URL.
+- Routes exporting `markdown` rely on server-side `Accept` negotiation, which
+  a static host cannot do — agents asking for `text/markdown` get HTML. The
+  build prints a note when this applies; publish `.md` files under `public/`
+  if a raw-markdown corpus matters.
+- Deploying to a sub-path (GitHub Pages *project* site, S3 key prefix) needs
+  Vite `base` set to that path (`base: "/my-project/"`). Check it matches the
+  deploy path exactly — a mismatch 404s every asset. Then check the app has no
+  hand-written root-absolute internal links (`<a href="/about">`): those are
+  not base-prefixed and will leave the deploy. `grep -rn 'href="/' src/` and
+  confirm each hit is external, an asset under `public/`, or a `<Link route>`.
+  Framework-owned URLs from `@pracht/image`'s `defaultLoader` and the OpenAPI
+  companion UI/document already carry the base; do not flag their base-free
+  route declarations. Custom image loaders and OpenAPI provider asset URLs
+  still need to match the intended host.
+  CDN bases (`https://cdn…`) and document-relative bases (`""` / `"./"`) are
+  build errors, not sub-path deploys.
+
 ## Step 4: Cross-cutting checks
 
 - Run `audit-secrets` to confirm no `process.env.*` or `context.env.*` values
   flow into loader return values.
 - Run `audit-headers` to confirm `applyDefaultSecurityHeaders` is in use on
   user-facing responses (or that `headers()` exports cover the same ground).
+  On a static export this check moves entirely to the host's header config —
+  see the static section above.
 - Confirm `git status` is clean (deploying uncommitted work is a footgun).
 
 ## Step 5: Report
@@ -167,9 +240,13 @@ status. End with a one-line verdict: `READY` / `BLOCKED (N errors)` /
 3. For Cloudflare/Vercel-edge, the Node-only API check is non-negotiable; an
    API not covered by the active compatibility flags will crash the worker on
    a code path that may never hit in dev.
-4. If the app does not use generated typed route files yet, note that `pracht typegen --check` is optional; if it does, stale generated files block deployment.
-5. Do not deploy on the user's behalf. End the skill at the verdict.
-6. If `pracht doctor` reports errors, do not run any other checks until those
+4. For a static export, never report `READY` without naming the host settings
+   the deploy depends on (clean URLs, `404.html`, security headers, and the
+   fallback rewrite if configured). The build cannot verify any of them, so an
+   unqualified `READY` is the one way this skill can mislead.
+5. If the app does not use generated typed route files yet, note that `pracht typegen --check` is optional; if it does, stale generated files block deployment.
+6. Do not deploy on the user's behalf. End the skill at the verdict.
+7. If `pracht doctor` reports errors, do not run any other checks until those
    are resolved — they will produce noisy false positives.
 
 $ARGUMENTS

package/skills/scaffold-tests/SKILL.md

@@ -1,12 +1,12 @@
 ---
 name: scaffold-tests
-version: 1.1.0
+version: 1.2.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.
+  tests with `@testing-library/preact`. Wires `vitest.config.ts`, builds
+  `LoaderArgs` with `@pracht/test`, 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:
@@ -48,9 +48,14 @@ Detect the package manager from the lockfile.
 Common (both modes):
 
 ```bash
-pnpm add -D vitest @types/node
+pnpm add -D vitest @types/node @pracht/test
 ```
 
+`@pracht/test` provides the typed args factories (`createLoaderArgs`,
+`createApiArgs`, `createMiddlewareArgs`, `createApiMiddlewareArgs`), the
+`runMiddleware()` chain runner, `submitForm()`, and the
+`readJson()`/`readRedirect()` response readers used in the templates below.
+
 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`.
@@ -145,75 +150,54 @@ to scaffold, or pass paths via `$ARGUMENTS`.
 
 ```ts
 import { describe, it, expect } from "vitest";
+import { createLoaderArgs } from "@pracht/test";
 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>"));
+    const data = await loader(createLoaderArgs({ url: "/<path>" }));
     expect(data).toBeDefined();
   });
 });
 ```
 
+Pass `params`, `headers`, a partial `context`, or a JSON-encoding `body` as
+needed; the factory defaults everything else and exposes `controller` (the
+`AbortController` behind `args.signal`) for cancellation tests.
+
 ### Middleware test template
 
 ```ts
 import { describe, it, expect } from "vitest";
+import { createMiddlewareArgs, readRedirect, runMiddleware } from "@pracht/test";
 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/);
+    const response = await runMiddleware(middleware, createMiddlewareArgs({ url: "/dashboard" }));
+    expect(readRedirect(response).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,
+    const response = await runMiddleware(
+      middleware,
+      createMiddlewareArgs({ url: "/dashboard", headers: { cookie: "session=valid" } }),
+      async () => new Response("handler ran"),
     );
-    expect(response).toBe(ok);
+    expect(await response.text()).toBe("handler ran");
   });
 });
 ```
 
+`runMiddleware()` accepts an array to test a chain in manifest order,
+including `context` mutations flowing downstream and returned-response
+short-circuits. A thrown `Response` resolves by default, matching page/API
+outer normalization. For raw capability-chain behavior, pass
+`undefined, { thrownResponse: "reject" }` after the args/final-handler slots;
+prefer `createCapabilityTestHost()` so the test asserts the real typed
+`internal_error` envelope. For middleware attached through `defineApp({ api })`,
+use `createApiMiddlewareArgs()` so `route` has the API metadata shape.
+
 ### Component test template (browser mode)
 
 ```tsx
@@ -274,8 +258,8 @@ broken scaffolding.
 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.
+3. Use `@pracht/test`'s factories for `BaseRouteArgs`/`LoaderArgs`
+   construction instead of hand-building args objects.
 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.

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

@@ -141,6 +141,9 @@ on the router `mode` from Step 1:
   `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).
+  For ISG, also add a positive integer time policy such as
+  `export const REVALIDATE = 3600`; pages mode requires it and supports
+  time-based revalidation only. Eject for webhook or combined policies.
   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.
@@ -159,7 +162,7 @@ Apply the edits only after the user confirms.
    | ---------- | -------------------------------------------------------------- | ----- |
    | 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. |
+   | Vercel     | Native ISR: Build Output API prerender functions with `expiration` from the time policy; for webhook revalidation, `PRACHT_REVALIDATE_TOKEN` becomes the `bypassToken` and must be set at build time | ISG routes deploy as Node Serverless Functions (Vercel rejects ISR on an Edge Function) while SSR stays on the edge. Time-only ISR does not require the token. 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`