create-pracht 0.2.6 → 0.4.0

package/skills/pracht-deploy/SKILL.md

@@ -0,0 +1,208 @@
+---
+name: pracht-deploy
+version: 1.1.0
+description: |
+  Pracht deployment guide. Walks through adapter configuration, building, and
+  deploying to Node.js, Cloudflare Workers, or Vercel. Handles wrangler config,
+  Docker and production checklist.
+  Use when asked to "deploy", "set up deployment", "configure adapter",
+  "deploy to cloudflare", "deploy to vercel", or "production build".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Deploy
+
+Guided adapter setup and deployment for pracht applications.
+
+## Step 1: Determine the target
+
+Read `vite.config.ts` and `package.json` first — don't assume the current adapter.
+Ask the user where they want to deploy if not already clear from their message.
+
+If the pracht MCP server is registered (docs/MCP.md), prefer the `inspect_build`/`doctor`/`verify` MCP tools over shelling out. Note: `inspect_build` (like `pracht inspect build`) needs a prior `pracht build`, and `pracht inspect` requires the pracht plugin registered in the vite config.
+
+## Supported Adapters
+
+| Adapter            | Package                      | Status |
+| ------------------ | ---------------------------- | ------ |
+| Node.js            | `@pracht/adapter-node`       | Stable |
+| Cloudflare Workers | `@pracht/adapter-cloudflare` | Stable |
+| Vercel             | `@pracht/adapter-vercel`     | Stable |
+
+---
+
+## Node.js Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-node` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { nodeAdapter } from "@pracht/adapter-node";
+   export default { plugins: [pracht({ adapter: nodeAdapter() })] };
+   ```
+
+### Build
+
+```bash
+pracht build
+```
+
+Produces:
+
+- `dist/client/` — static assets (JS, CSS, prerendered HTML)
+- `dist/server/server.js` — Node server entry
+- `dist/server/isg-manifest.json` — ISG revalidation config (if ISG routes exist)
+- `dist/client/.vite/manifest.json` — asset manifest for script/style injection
+
+### Run
+
+```bash
+node dist/server/server.js
+```
+
+Port 3000 by default. For a local production smoke test, `pracht preview` builds and runs the server in one step (`--port <n>`, `--skip-build` to reuse an existing build). For production: reverse proxy (nginx, Caddy), process manager (PM2, systemd), `NODE_ENV=production`.
+
+### Docker
+
+```dockerfile
+FROM node:22-alpine
+WORKDIR /app
+COPY dist/ dist/
+COPY package.json .
+EXPOSE 3000
+CMD ["node", "dist/server/server.js"]
+```
+
+---
+
+## Cloudflare Workers Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-cloudflare` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { cloudflareAdapter } from "@pracht/adapter-cloudflare";
+   export default { plugins: [pracht({ adapter: cloudflareAdapter() })] };
+   ```
+
+### Build & Deploy
+
+```bash
+pracht build
+npx wrangler deploy
+```
+
+To smoke-test the built worker locally first, run `pracht preview` — it builds and then delegates to `wrangler dev`, which serves the wrangler config's `main` entry, `dist/server/worker.js`.
+
+### Wrangler Configuration
+
+```jsonc
+// wrangler.jsonc
+{
+  "name": "my-pracht-app",
+  "main": "dist/server/worker.js",
+  "compatibility_date": "2024-01-01",
+  "assets": {
+    "binding": "ASSETS",
+    "directory": "dist/client",
+    "run_worker_first": true,
+  },
+}
+```
+
+`"binding": "ASSETS"` and `"run_worker_first": true` are required. Without the binding, the worker's `env.ASSETS` resolves to nothing and the runtime silently falls back to `null` — headers and ISG manifests load empty, so SSG serving, ISG revalidation, and per-route headers all silently no-op. The canonical config lives at `examples/cloudflare/wrangler.jsonc`. If you rename the binding with `assetsBinding` (below), the wrangler `binding` value must match.
+
+### Bindings (KV, D1, R2)
+
+```ts
+export async function loader({ context }: LoaderArgs) {
+  const value = await context.env.MY_KV.get("key");
+  return { value };
+}
+```
+
+### Custom Assets Binding
+
+```ts
+pracht({ adapter: cloudflareAdapter({ assetsBinding: "STATIC" }) });
+```
+
+### ISG via Workers Caching
+
+ISG works out of the box: without any cache option, the default worker-managed path serves the build-time snapshot, detects staleness, and regenerates pages in the background via the Workers Cache API — per colo — and `POST /__pracht/revalidate` triggers on-demand regeneration. Enabling `cache: true` moves ISG from that per-colo worker-managed path to edge-tier Workers Caching, on both sides:
+
+```ts
+pracht({ adapter: cloudflareAdapter({ cache: true }) });
+```
+
+```jsonc
+// wrangler.jsonc
+{ "cache": { "enabled": true } }
+```
+
+Before enabling it, audit ISG URLs for unbounded query strings. Workers Caching
+keys the exact path and query string, including parameter order and trailing
+slashes; use a bounded query allowlist/canonical redirect or an uncached gateway
+with a pathname-only `cf.cacheKey`, and normalize `Accept` there for routes that
+export markdown. See `docs/ADAPTERS.md#cache-key-cardinality`.
+
+Time-revalidated ISG pages then render on demand, are cached at the edge for
+their `revalidate` window (stale pages served instantly while the Worker
+re-renders in the background), and can be purged early with `purgeCache()` from
+`@pracht/adapter-cloudflare/cache`. Webhook-only ISG routes keep their
+build-time snapshots and the worker-managed path either way.
+
+---
+
+## Vercel Deployment
+
+### Setup
+
+1. Ensure `@pracht/adapter-vercel` is installed.
+2. In `vite.config.ts`:
+   ```ts
+   import { pracht } from "@pracht/vite-plugin";
+   import { vercelAdapter } from "@pracht/adapter-vercel";
+   export default { plugins: [pracht({ adapter: vercelAdapter() })] };
+   ```
+
+### Build & Deploy
+
+```bash
+pracht build
+npx vercel deploy --prebuilt
+```
+
+Produces: `.vercel/output/config.json`, `.vercel/output/static/`, `.vercel/output/functions/render.func/server.js`
+
+---
+
+## Deployment Checklist
+
+1. **Build**: Run `pracht build` and verify `dist/` output.
+2. **Environment variables**: Ensure secrets/config needed by loaders are available at runtime.
+3. **Static assets**: Verify `dist/client/` contains prerendered HTML for SSG routes (and ISG routes — except time-revalidated ISG routes on Cloudflare with Workers Caching enabled, which render on demand; webhook-only ISG routes keep their build-time snapshots).
+4. **ISG routes**: Confirm the ISG manifest (`dist/server/isg-manifest.json`; on Cloudflare also `dist/client/_pracht/isg.json`) exists if using incremental static generation.
+5. **API routes**: Test API endpoints work in the production runtime. For Node.js, run `pracht preview` (or `node dist/server/server.js`).
+6. **Middleware**: Verify auth/redirect middleware behaves correctly in production.
+
+## Rules
+
+1. Read `vite.config.ts` and `package.json` before giving advice.
+2. Run `pracht build` to verify the build succeeds before deploying.
+3. Smoke-test the production runtime before pushing to production. For Node.js and Cloudflare, run `pracht preview`.
+4. If the user needs an adapter that isn't installed, help them add it (`pnpm add @pracht/adapter-*`).
+5. Don't push to production without the user's explicit confirmation.
+
+$ARGUMENTS

package/skills/pracht-scaffold/SKILL.md

@@ -0,0 +1,191 @@
+---
+name: pracht-scaffold
+version: 1.1.0
+description: |
+  Pracht code scaffolding. Prefer the framework-native CLI generators
+  (`pracht generate route|shell|middleware|api`) and only fall back to manual
+  edits when the CLI flags cannot express the requested shape. Knows pracht
+  conventions (Preact idioms, render modes, route manifest).
+  Use when asked to "scaffold", "generate a route", "create a new page",
+  "add middleware", "add an API route", or "create a shell".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Scaffold
+
+Generate pracht framework modules with correct types, exports, and manifest wiring.
+
+## First Choice
+
+Use the CLI first:
+
+```bash
+pracht generate route --path /dashboard --render ssr
+pracht generate shell --name app
+pracht generate middleware --name auth
+pracht generate api --path /health --methods GET,POST
+```
+
+`pracht generate route` supports the full flag matrix below — do not fall back to manual edits for shapes it already covers:
+
+| Flag               | Meaning                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------ |
+| `--path` (required) | Route path, e.g. `/dashboard` or `/blog/:slug`                                       |
+| `--render`         | Render mode: `ssr` (default), `spa`, `ssg`, or `isg`                                 |
+| `--shell`          | Registered shell name (manifest apps only)                                           |
+| `--middleware`     | Registered middleware names, comma-separated (manifest apps only)                    |
+| `--loader`         | Include a `loader` export                                                            |
+| `--error-boundary` | Include an `ErrorBoundary` export                                                    |
+| `--static-paths`   | Include `getStaticPaths` (added automatically for dynamic `ssg`/`isg` paths)         |
+| `--title`          | Page title used in the `head()` export                                               |
+| `--revalidate`     | ISG revalidation window in seconds (`isg` only, default 3600)                        |
+| `--json`           | Machine-readable output                                                              |
+
+`generate shell` and `generate middleware` take `--name`; `generate api` takes `--path` and `--methods` (comma-separated). All subcommands accept `--json`.
+
+- `--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.
+- 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.
+- If `src/routes.ts` declares `constraints:`, respect them (e.g. put new `/app/**` routes behind the required middleware). Never delete or weaken a constraint to make `pracht verify` pass — that is a policy change the user must approve.
+- If the CLI can express the request, do not reimplement the scaffold by hand.
+- Only edit files manually when the CLI cannot cover the requested shape.
+
+The user will describe what they want to create. Parse their request and generate the appropriate module(s). Always ask if anything is ambiguous (e.g. render mode, shell assignment).
+
+## What You Can Scaffold
+
+| Kind       | Directory         | Key exports                                                          | Example                        |
+| ---------- | ----------------- | -------------------------------------------------------------------- | ------------------------------ |
+| Route      | `src/routes/`     | `loader`, `head`, `Component`, `ErrorBoundary`, `getStaticPaths`     | `src/routes/blog.tsx`          |
+| Shell      | `src/shells/`     | `Shell`, `head`                                                      | `src/shells/marketing.tsx`     |
+| Middleware | `src/middleware/` | `middleware`                                                         | `src/middleware/rate-limit.ts` |
+| API route  | `src/api/`        | Named HTTP method handlers (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) or one default method dispatcher           | `src/api/users/[id].ts`        |
+
+## Templates (manual fallback)
+
+Use these only when the CLI cannot express the requested shape.
+
+### Route
+
+```tsx
+export function head() {
+  return { title: "Page Title" };
+}
+
+export function Component() {
+  return <section>{/* route UI */}</section>;
+}
+```
+
+- Include a `loader` only when the route needs server data (matches the CLI, which omits it unless `--loader` is passed):
+
+  ```tsx
+  import type { LoaderArgs, RouteComponentProps } from "@pracht/core";
+
+  export async function loader(_args: LoaderArgs) {
+    return {
+      /* loader data */
+    };
+  }
+
+  export function Component({ data }: RouteComponentProps<typeof loader>) {
+    return <section>{/* route UI */}</section>;
+  }
+  ```
+
+- Include `ErrorBoundary` only if requested.
+- Include `getStaticPaths` only for SSG/ISG routes with dynamic segments.
+- Use `RouteComponentProps<typeof loader>` for typed `data` prop.
+
+### Shell
+
+```tsx
+import type { ShellProps } from "@pracht/core";
+
+export function Shell({ children }: ShellProps) {
+  return (
+    <div class="shell-name">
+      <nav>{/* navigation */}</nav>
+      <main>{children}</main>
+    </div>
+  );
+}
+
+export function head() {
+  return { title: "Shell Title" };
+}
+```
+
+### Middleware
+
+Middleware wraps the rest of the request via `next()`:
+
+```ts
+import { redirect, type MiddlewareFn } from "@pracht/core";
+
+export const middleware: MiddlewareFn = async ({ context, request }, next) => {
+  // Mutate context, validate auth, etc.
+  // - Call `return next()` to continue
+  // - Return `redirect("/path", { request })` to short-circuit with a redirect
+  // - Return any `Response` to short-circuit
+  // - Wrap `await next()` in try/catch/finally for tracing/logging
+  return next();
+};
+```
+
+### API Route
+
+```ts
+import type { ApiRouteArgs } from "@pracht/core";
+
+export function GET({ params, url }: ApiRouteArgs) {
+  return Response.json({
+    /* response data */
+  });
+}
+```
+
+- Only include the HTTP methods the user needs.
+- Use a default export only when the user wants to branch on `request.method` manually.
+- 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`.
+
+## Wiring Into the Manifest (manual fallback only)
+
+The CLI generators wire the manifest themselves: `pracht generate route` inserts the `route(...)` call into `src/routes.ts` (adding `route`/`timeRevalidate` imports as needed), and `generate shell`/`generate middleware` upsert their registry entries. **Do not re-edit the manifest after a successful `pracht generate` run.**
+
+Only when you created module files by hand, update `src/routes.ts` to register the new module:
+
+- **Routes**: Add a `route("/path", () => import("./routes/filename.tsx"), { id: "name", render: "ssr" })` call inside the appropriate group or at the top level. Plain strings like `"./routes/filename.tsx"` also work.
+- **Shells**: Add to the `shells` record: `shellName: () => import("./shells/filename.tsx")` (or `"./shells/filename.tsx"`).
+- **Middleware**: Add to the `middleware` record: `mwName: () => import("./middleware/filename.ts")` (or `"./middleware/filename.ts"`).
+- **API routes**: No manifest change needed — auto-discovered from `src/api/` by the Vite plugin.
+
+Available render modes: `"ssr"` (default), `"ssg"` (static at build), `"isg"` (incremental static with `revalidate: timeRevalidate(seconds)`), `"spa"` (client-only).
+
+Import `timeRevalidate` from `"@pracht/core"` when using ISG.
+
+## Rules
+
+1. Prefer `pracht generate ...` over manual edits.
+2. Read the project's existing `src/routes.ts` to determine current shells, middleware, and route structure before adding when the CLI cannot finish the job on its own.
+3. Place files in the conventional directories (`src/routes/`, `src/shells/`, `src/middleware/`, `src/api/`).
+4. Keep generated code minimal — only include exports the user actually needs.
+5. Use Preact idioms: `class` not `className`, functional components, `import type` for type-only imports.
+6. When route ids/paths change in a typed-routes app, run `pracht typegen` and include the generated route files.
+7. Finish with `pracht verify` (and `pracht plan --write` when the app commits an app-graph snapshot).
+8. After scaffolding, summarize what was created and how it was wired.
+
+$ARGUMENTS

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

@@ -0,0 +1,165 @@
+---
+name: pracht-test-api
+version: 1.1.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
+  directly, and asserts on the returned `Response` — no server boot required.
+  Use when asked to "test my API routes", "scaffold API tests", "generate
+  tests for src/api", or "add tests for this endpoint".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Test API
+
+Pracht API handlers are plain functions: `(args: ApiRouteArgs) => Response |
+Promise<Response>` (`ApiRouteArgs` is `BaseRouteArgs` with `route` narrowed
+to `ResolvedApiRoute`). They test cleanly in Vitest without booting the
+framework.
+
+## Step 1: Confirm Vitest is installed
+
+If the project has no `vitest` dependency, run `scaffold-tests` first (or
+prompt the user to). This skill does not handle Vitest setup.
+
+## Step 2: Enumerate API handlers
+
+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 api --json
+```
+
+For each entry, capture: `path` (URL), `file` (source path), and the exported
+`methods` (e.g., `["GET", "POST"]`). Note: `methods` only lists named HTTP
+method exports — a default-export dispatcher yields `methods: []`, never
+`["default"]`. Current `@pracht/cli` versions also report a
+`hasDefaultHandler` boolean; use it when present. If the field is absent
+(older CLI) and `methods` is empty, fall back to the grep in Step 7 to detect
+a default dispatcher.
+
+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`:
+
+```ts
+import { describe, it, expect } from "vitest";
+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>"));
+    expect(res).toBeInstanceOf(Response);
+    expect(res.status).toBe(200);
+  });
+});
+```
+
+## Step 4: Generate method-specific cases
+
+For each exported method, emit the smallest realistic case:
+
+| Method  | Default case                                                    |
+| ------- | --------------------------------------------------------------- |
+| `GET`   | Plain GET → `expect(res.status).toBeLessThan(400)`              |
+| `POST`  | POST with empty `FormData` → assert validation behavior         |
+| `PUT`   | PUT with JSON body → assert 200 or auth-required (401/403)      |
+| `PATCH` | PATCH with partial body → assert 200 or 422                     |
+| `DELETE`| DELETE on a real-shaped path → assert 200/204 or 401            |
+
+For dynamic segments (`[id].ts` → `/api/users/:id`), pick a placeholder param
+(e.g., `id: "test-1"`) and pass it via `params`. Surface in the report that
+the user may need to provide a real fixture.
+
+## Step 5: Detect auth-gated APIs
+
+API routes do NOT appear in `pracht inspect routes --json` (that report
+covers page routes only) and `pracht inspect api --json` has no middleware
+field. API middleware is the single global list configured as
+`defineApp({ api: { middleware: [...] } })` — read the manifest source
+(`src/routes.ts` or wherever `defineApp` lives) to see whether an auth
+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" }));
+  expect([401, 403, 302]).toContain(res.status);
+});
+```
+
+Note: middleware does NOT run when calling the handler directly — this test
+verifies the handler's own defense if it has one. If the only defense is
+middleware, mention that in the report and recommend an integration test that
+goes through the framework's request pipeline (out of scope for this skill).
+The same applies to the framework's built-in CSRF check: `requireSameOrigin`
+(on by default) rejects cross-origin state-changing API requests in the real
+pipeline but never runs in direct-invocation tests.
+
+## Step 6: Validate JSON shape
+
+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>"));
+  expect(res.headers.get("content-type")).toMatch(/application\/json/);
+  const body = await res.json();
+  expect(body).toEqual(expect.objectContaining({ /* fill in */ }));
+});
+```
+
+## Step 7: Default-handler dispatchers
+
+If the handler exports `default` (one function dispatching on
+`request.method`), generate a test per HTTP method the handler appears to
+support (grep for `request.method ===` patterns inside the file).
+
+## Step 8: Run
+
+```bash
+pnpm test
+pracht verify --json
+```
+
+Report passes/failures. Mark generated assertions as TODO so the user knows
+to tighten them.
+
+## Rules
+
+1. Use `pracht inspect api --json` as the inventory — do not glob.
+2. Only import methods the handler actually exports; otherwise the test fails
+   to load.
+3. Direct-handler invocation skips middleware AND the default-on
+   `requireSameOrigin` CSRF check. Be explicit in the report.
+4. Test files live next to handlers with `.test.ts` suffix unless the
+   project already uses a `__tests__/` convention (detect and match).
+5. Never overwrite existing test files; emit a `.next.test.ts` and tell the
+   user to merge.
+
+$ARGUMENTS