create-pracht 0.3.0 → 0.4.1

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

package/skills/pre-deploy/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: pre-deploy
+version: 1.2.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.
+  Use when asked to "pre-deploy check", "ready to ship?", "deployment
+  checklist", "is my build production-safe", or before running `wrangler
+  deploy` / `vercel deploy`.
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Pre-Deploy
+
+Run this before every production deploy. Each adapter has a different runtime
+contract; this skill enforces the contract that matches your build.
+
+## Step 1: Detect the adapter
+
+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:
+
+```bash
+pracht inspect build --json
+```
+
+The `adapterTarget` field is authoritative. Prerequisites: `pracht inspect`
+needs a vite config with the pracht plugin, and `inspect build` reads
+artifacts from a prior build — if `pracht build` has not been run recently,
+run it first:
+
+```bash
+pracht build
+```
+
+## Step 2: Run framework-wide checks
+
+```bash
+pracht doctor --json
+pracht verify --json
+```
+
+If the app uses generated typed routes (`src/pracht-routes.ts` or
+`src/pracht.d.ts` exists), also run:
+
+```bash
+pracht typegen --check
+```
+
+These catch app-graph wiring problems independent of the adapter — including
+`defineApp({ constraints })` violations and a stale `.pracht/app-graph.json`
+snapshot (fix the latter with `pracht plan --write`, then re-review the plan
+output). Resolve all `status: "error"` entries before continuing.
+
+When the deploy corresponds to a PR, `pracht report --base origin/main` produces
+a markdown summary (graph diff + verify + budgets) worth attaching to it.
+
+## Step 3: Adapter-specific checklist
+
+### Node (`@pracht/adapter-node`)
+
+- `dist/server/server.js` exists.
+- `dist/client/.vite/manifest.json` exists.
+- `dist/server/isg-manifest.json` exists if any route has `render: "isg"`.
+- Smoke test: `pracht preview --skip-build` (or `node dist/server/server.js`) boots and `curl localhost:3000` returns 200.
+- Required env vars (grep `process.env.*` across `src/`) are set in the
+  deployment environment. List them for the user.
+- If the app mounts `createImageHandler()` from `@pracht/image/node`, confirm
+  `sharp` is installed and `localOrigin` is the same trusted public origin as
+  `nodeAdapter({ canonicalOrigin })`. A production-relative image endpoint
+  without both values is an error.
+- Reverse-proxy / TLS termination configured (out of scope for this skill —
+  flag for confirmation).
+
+### Cloudflare Workers (`@pracht/adapter-cloudflare`)
+
+- `wrangler.toml` (or `wrangler.jsonc`) present at repo root.
+- `main` points to `dist/server/worker.js` — the thin deploy wrapper that
+  re-exports only the default handler and Cloudflare entrypoint classes.
+  Pointing `main` at `dist/server/server.js` is an **error**: workerd
+  validates every named export of the deploy entry and rejects the build
+  metadata (`buildTarget`, manifests, `resolvedApp`, ...) that `server.js`
+  exports for the prerender pass.
+- `assets.directory` points to `dist/client`.
+- `compatibility_date` is set and recent.
+- 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:
+  `fs`, `path` (Node form), `process.cwd`, `Buffer`, `__dirname`,
+  `__filename`, `crypto.createHash` (use `crypto.subtle` instead),
+  `child_process`, `cluster`, `worker_threads`. Two nuances before flagging:
+  - Consult `compatibility_flags` in the wrangler config first — with
+    `nodejs_compat`, `Buffer` and several `node:` modules are legal in
+    workerd. Only flag APIs the active flags don't cover.
+  - Dev already runs inside workerd via `@cloudflare/vite-plugin`, so most
+    incompatibilities surface in dev; this check is the backstop for code
+    paths dev never hit.
+- An API route importing `@pracht/image/node` is an error on Workers because
+  its optimizer requires `sharp`. Require `cloudflareLoader` (or
+  `passthroughLoader`) instead.
+- ISG: worker-managed ISG via the per-colo Workers Cache API works out of the
+  box. If time-revalidated routes should use the edge-tier Workers Caching
+  upgrade instead, confirm both sides — `cloudflareAdapter({ cache: true })`
+  in vite config and `"cache": { "enabled": true }` in wrangler config.
+- When Workers Caching is enabled, flag ISG routes reachable through unbounded
+  query strings. Require a bounded allowlist/canonical redirect or an uncached
+  gateway with a normalized `cf.cacheKey`; also check that markdown-capable
+  routes normalize `Accept` at the gateway when variant fan-out matters.
+- Bundle size: measure what actually deploys — `dist/server/worker.js` plus
+  its `dist/server/server.js` import (wrangler bundles the import graph of
+  `main`; `worker.js` alone is a few lines). Workers limit is ~1 MB
+  compressed for free tier, ~10 MB on paid. Warn at 80% of the active limit.
+
+### Vercel (`@pracht/adapter-vercel`)
+
+- `.vercel/output/config.json` exists post-build.
+- The render function exists at
+  `.vercel/output/functions/<functionName>.func/server.js`. The name defaults
+  to `render` but is configurable via `vercelAdapter({ functionName })` —
+  read the configured name from `vite.config.ts` instead of hardcoding
+  `render.func`.
+- `.vercel/output/static/` populated.
+- 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.
+- 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`.
+
+## 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).
+- Confirm `git status` is clean (deploying uncommitted work is a footgun).
+
+## Step 5: Report
+
+Produce a checklist grouped by `Framework`, `Adapter`, `Cross-cutting`. Tag
+each item with a primary severity — `error` (blocks deploy), `warn` (deploy
+proceeds but risky), `info` — and keep pass/fail as the secondary per-item
+status. End with a one-line verdict: `READY` / `BLOCKED (N errors)` /
+`READY WITH WARNINGS (N warnings)`.
+
+## Rules
+
+1. Always run `pracht build` first. Do not lint a stale `dist/`.
+2. Detect the adapter — never assume.
+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
+   are resolved — they will produce noisy false positives.
+
+$ARGUMENTS

package/skills/scaffold-e2e/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: scaffold-e2e
+version: 1.1.0
+description: |
+  Scaffold Playwright end-to-end tests for a pracht app: install Playwright,
+  generate `playwright.config.ts` that boots `pracht dev` (or the production
+  build via `pracht preview`), and emit a smoke test for every route in the
+  manifest that asserts 200, head/title, no console errors, and basic
+  navigation.
+  Use when asked to "scaffold E2E", "set up Playwright", "add browser tests",
+  or "create smoke tests for my routes".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Scaffold E2E
+
+Generate a Playwright suite that exercises the live app. Aligns with
+`recipes-testing.md`.
+
+## Step 1: Decide which build the tests run against
+
+Ask the user (default: `dev`):
+
+1. **`pracht dev`** — fast, HMR, but can mask production-only bugs (different
+   bundling, different SSG/ISG flow).
+2. **Production runtime** — `pracht preview`: purpose-built, it builds and
+   serves the production output locally for both Node and Cloudflare targets
+   (Vercel prints guidance instead). Use `pracht preview --skip-build` to
+   serve an existing build after an explicit `pracht build`. Prefer this over
+   hand-rolling `node dist/server/server.js`, which is Node-adapter-only and
+   skips the build.
+3. **External URL** — user provides `BASE_URL`; tests do not boot the server.
+
+## Step 2: Install
+
+```bash
+pnpm add -D @playwright/test
+pnpm exec playwright install chromium
+```
+
+Add `firefox` and `webkit` only if the user requests them.
+
+## Step 3: Write `playwright.config.ts`
+
+```ts
+import { defineConfig, devices } from "@playwright/test";
+
+const PORT = Number(process.env.PORT ?? 3000);
+
+export default defineConfig({
+  testDir: "./e2e",
+  fullyParallel: true,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI ? "github" : "list",
+  use: {
+    baseURL: process.env.BASE_URL ?? `http://localhost:${PORT}`,
+    trace: "on-first-retry",
+    screenshot: "only-on-failure",
+  },
+  webServer: process.env.BASE_URL
+    ? undefined
+    : {
+        command: "pnpm dev", // or "pracht preview" for the production runtime — choose at scaffold time
+        url: `http://localhost:${PORT}`,
+        reuseExistingServer: !process.env.CI,
+        timeout: 120_000,
+      },
+  projects: [
+    { name: "chromium", use: devices["Desktop Chrome"] },
+  ],
+});
+```
+
+If `playwright.config.ts` already exists, merge — do not clobber.
+
+## Step 4: Generate per-route smoke 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.
+
+```bash
+pracht inspect routes --json
+```
+
+For every route entry, generate one spec under `e2e/smoke/`. Skip routes with
+dynamic segments unless the user provides example params (ask via
+`AskUserQuestion`).
+
+Per-route template:
+
+```ts
+import { test, expect } from "@playwright/test";
+
+test.describe("smoke: <path>", () => {
+  test("loads with 200 and a title", async ({ page }) => {
+    const errors: string[] = [];
+    page.on("console", (msg) => {
+      if (msg.type() === "error") errors.push(msg.text());
+    });
+    page.on("pageerror", (err) => errors.push(err.message));
+
+    const response = await page.goto("<path>");
+    expect(response?.status(), "HTTP status").toBeLessThan(400);
+    await expect(page).toHaveTitle(/.+/);
+    expect(errors, "no console errors").toEqual([]);
+  });
+});
+```
+
+## Step 5: Generate a navigation crawl
+
+A single `e2e/navigation.spec.ts` that:
+
+1. Visits the home route.
+2. Waits for hydration with the documented readiness idiom before touching
+   anything — otherwise the crawl races hydration and clicks fall through to
+   full page loads:
+   ```ts
+   await page.waitForFunction(() => (window as any).__PRACHT_ROUTER_READY__);
+   ```
+3. Collects every same-origin `<a href>`.
+4. Clicks each in turn, asserts no console errors, no 4xx/5xx.
+
+This catches client-router intercept regressions and broken links.
+
+## Step 6: Generate a hydration check (optional)
+
+If any route is `render: "ssr"` or `"ssg"`/`"isg"`:
+
+```ts
+test("server HTML matches client render", async ({ page }) => {
+  const errors: string[] = [];
+  page.on("console", (m) => m.type() === "error" && errors.push(m.text()));
+  await page.goto("<path>");
+  await page.waitForLoadState("networkidle");
+  expect(errors.filter((e) => /Hydration|hydrat/i.test(e))).toEqual([]);
+});
+```
+
+## Step 7: Wire `package.json`
+
+```json
+{
+  "scripts": {
+    "e2e": "playwright test",
+    "e2e:ui": "playwright test --ui"
+  }
+}
+```
+
+If an `e2e` script already exists in the project, confirm before
+overwriting.
+
+## Step 8: Run
+
+```bash
+pnpm e2e
+pracht verify --json
+```
+
+If specs fail on first run, report. Common first-run failures:
+- Port collision (already-running dev server).
+- Missing browser binary (`playwright install chromium`).
+- Strict CSP blocking inline test scripts (rare).
+
+## Rules
+
+1. Source of routes is `pracht inspect routes --json`. Do not glob
+   `src/routes/**`.
+2. Skip dynamic-segment routes unless example params are provided.
+3. Never overwrite an existing `playwright.config.ts` without diffing first.
+4. If the app uses typed routes, run `pracht typegen --check` before generating specs and prefer imported `href()` for test URLs in app-owned route fixtures.
+5. Use `webServer` to boot `pracht dev` or `pracht preview` so CI works
+   out-of-the-box.
+6. Console-error capture is mandatory — silent JS errors are the most common
+   pracht hydration regression.
+7. Wait for `window.__PRACHT_ROUTER_READY__` before interacting with the
+   page in any spec that relies on client-side navigation.
+
+$ARGUMENTS