create-pracht 0.2.6 → 0.4.0

package/skills/pre-deploy/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: pre-deploy
+version: 1.1.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.
+- 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.
+- 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.
+- 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

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