create-pracht 0.2.6 → 0.4.0

package/skills/audit-seo/SKILL.md

@@ -0,0 +1,164 @@
+---
+name: audit-seo
+version: 1.1.0
+description: |
+  Per-route SEO audit for a pracht app: `head()` coverage, title/description
+  presence, Open Graph and Twitter card completeness, canonical URLs, robots
+  rules, and a generated `sitemap.xml` derived from the route manifest.
+  Use when asked to "audit SEO", "check meta tags", "generate a sitemap",
+  "are my OG cards set", or "review robots.txt".
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Grep
+  - Glob
+---
+
+# Pracht Audit SEO
+
+Pracht owns the document. Per-route SEO lives in the `head()` export
+returning `{ title?, lang?, meta?, link?, script? }`. This skill audits
+coverage and generates the static SEO artifacts.
+
+## Step 1: Inventory
+
+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; run from the app root.
+
+For every route file, read the `head()` export (and the shell's `head()` for
+inherited values).
+
+## Step 2: Per-route checklist
+
+For each route, capture presence and quality:
+
+| Field                                    | Expected                          |
+| ---------------------------------------- | --------------------------------- |
+| `title`                                  | 30-60 chars, unique per route     |
+| `meta` `description`                     | 70-160 chars, unique per route    |
+| `meta` `og:title`                        | Present (often = `title`)         |
+| `meta` `og:description`                  | Present                           |
+| `meta` `og:image`                        | Absolute URL, ≥ 1200×630          |
+| `meta` `og:url`                          | Absolute, canonical               |
+| `meta` `twitter:card`                    | `summary_large_image` for content |
+| `link` `canonical`                       | Absolute URL                      |
+| `script` (JSON-LD)                       | Optional; see Step 6              |
+| `lang`                                   | Set on root or via shell          |
+
+Skip SPA-only / non-indexable routes (admin, dashboard) — flag as "noindex
+candidate" if they don't already declare it.
+
+## Step 3: Cross-route checks
+
+- **Duplicate titles** across routes — list collisions.
+- **Duplicate descriptions** — same.
+- **Missing canonical** on any route that has any `?query` variants.
+- **Missing OG image** — most common issue; recommend a default image at
+  shell level so every route inherits one.
+
+## Step 4: `robots.txt`
+
+`robots.txt` MUST be served at the origin root (`/robots.txt`) — crawlers
+never look anywhere else. Pracht API routes are always mounted under `/api/`
+(a `src/api/robots.ts` handler serves `/api/robots`, never `/robots.txt`), so
+an API handler cannot provide it. The workable option is the static asset:
+
+- `public/robots.txt` (Vite static asset, served at `/robots.txt`).
+
+If absent, recommend creating `public/robots.txt`:
+
+```
+User-agent: *
+Allow: /
+Disallow: /api/
+Disallow: /admin/
+Sitemap: https://<domain>/sitemap.xml
+```
+
+If present, validate:
+- A `Sitemap:` line referencing an existing endpoint (see Step 5 — if the
+  sitemap is an API route, this must point at `/api/sitemap`).
+- No accidental `Disallow: /` (full-site block).
+- Path patterns match real routes (cross-reference with the manifest).
+- Flag any `src/api/robots.ts` found in the repo as `warn`: it is dead
+  weight at `/api/robots` and does not serve `/robots.txt`.
+
+## Step 5: sitemap
+
+Generate (or recommend generating) a sitemap from the route manifest:
+
+- Include routes by **indexability**, not prefetch strategy: public
+  `render: "ssg"`/`"isg"` routes (and public SSR routes worth indexing),
+  minus routes under auth middleware, minus routes declaring a
+  `robots`/`noindex` meta. (`prefetch` is a client navigation hint —
+  orthogonal to indexability; do not use it as a criterion.)
+- Skip dynamic-segment routes unless `getStaticPaths` resolved them at build
+  time — pull resolved paths from the prerender output, which is laid out as
+  `dist/client/<route>/index.html` (clean URLs; e.g. `/about` →
+  `dist/client/about/index.html`).
+- Default `<changefreq>` from the route's revalidate policy: `timeRevalidate`
+  → `weekly` if `> 86400s`, `daily` if `> 3600s`, `hourly` otherwise.
+
+Offer two output forms:
+
+1. Static `public/sitemap.xml` regenerated at build time via a small script
+   (served at `/sitemap.xml`).
+2. A pracht API route at `src/api/sitemap.ts` that emits XML on each request
+   from the inspected manifest. It is served at `/api/sitemap` (API routes
+   always mount under `/api/`), so the robots `Sitemap:` line must point at
+   `https://<domain>/api/sitemap`.
+
+## Step 6: Structured data (optional)
+
+If the user asks, scaffold JSON-LD via the `head()` export's native `script`
+field — `HeadMetadata` supports `script?: HeadScriptDescriptor[]`, where each
+descriptor takes attributes plus `children` for the inline body:
+
+```ts
+export function head() {
+  return {
+    script: [
+      {
+        type: "application/ld+json",
+        children: JSON.stringify({ "@context": "https://schema.org", ... }),
+      },
+    ],
+  };
+}
+```
+
+No shell-level custom `<script>` JSX is needed. This is opt-in — do not push
+it on every audit.
+
+## Step 7: Report
+
+| Route | Severity | Title | Description | OG image | Canonical | Verdict |
+| ----- | -------- | ----- | ----------- | -------- | --------- | ------- |
+
+Primary severity per finding: `error` (site blocked by robots, auth-gated
+route in sitemap), `warn` (missing title/description/OG image/canonical on an
+indexable route), `info` (nice-to-haves like JSON-LD). Keep the
+`complete`/`partial`/`missing` verdict as a secondary per-route rollup,
+grouped by verdict.
+
+## Rules
+
+1. Use the resolved manifest — shell `head()` inheritance matters.
+2. Never auto-write `sitemap.xml` to the deployed site without user
+   confirmation; offer the file as a draft.
+3. Recommend a default OG image at the shell level — single highest-leverage
+   fix.
+4. Auth-gated routes should NOT appear in sitemaps.
+5. Cross-reference with `tune-render-mode` — SSG routes are the sitemap
+   candidates; SSR routes need decision per case.
+
+$ARGUMENTS

package/skills/audit-shells/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: audit-shells
+version: 1.1.0
+description: |
+  Audit pracht shells for composition bugs: missing `Loading()` on SPA-using
+  shells, accidental `<html>`/`<head>`/`<body>` rendering, shells that swallow
+  children, unused shells, and redundant `ErrorBoundary` exports (shell-level
+  boundaries are valid fallbacks; routes win when both declare one).
+  Use when asked to "audit shells", "check shell composition", "find unused
+  shells", or "is my layout structured correctly".
+allowed-tools:
+  - Bash
+  - Read
+  - Grep
+  - Glob
+---
+
+# Pracht Audit Shells
+
+Shells in pracht are named layout components composed around routes. The
+framework owns the document — shells must not render `<html>`, `<head>`, or
+`<body>`. They sit between the framework's HTML scaffold and the route
+component.
+
+## 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; run it from the app root.
+
+For every shell used by the app, read its source file. Also list which routes
+use which shell (the JSON output includes resolved `shell` and `shellFile` per
+route). The JSON's top-level `mode` field tells you which router the app uses
+— see Step 3 for how that changes shell discovery.
+
+## Step 2: Per-shell checks
+
+For each shell file:
+
+### 2a. Document-level tag misuse
+
+Grep for `<html`, `<head>`, `<body>`, `<meta`, `<title>`, `<link rel`. Any of
+these inside a shell is a bug — the framework injects them based on `head()`
+exports. Recommend moving meta/title to the shell's `head()` export and
+removing the JSX tags.
+
+### 2b. `Shell` export shape
+
+- Must be a function component named `Shell`.
+- Must accept `{ children }: ShellProps`.
+- Must render `{children}` somewhere — flag shells that never render
+  `children` (hard to spot, blank page everywhere).
+
+### 2c. `Loading()` for SPA routes
+
+If any route assigned to this shell has `render: "spa"`, the shell SHOULD
+export a `Loading()` function that renders a placeholder during the
+client-only data fetch. Without it, users see blank content during navigation.
+
+### 2d. `head()` export
+
+- Optional, but recommended if the shell sets shared meta tags.
+- Verify return shape matches `{ title?, lang?, meta?, link?, script? }`.
+- Flag shells whose `head()` returns `undefined` unconditionally — delete the
+  export.
+
+### 2e. `ErrorBoundary` export
+
+`ErrorBoundary` is a valid export on **both** shells and routes (see
+`ShellModule` and `RouteModule` in `packages/framework/src/types.ts`). The
+runtime resolves `routeMod.ErrorBoundary ?? shellModule.ErrorBoundary` — a
+shell-level boundary is the fallback for every route under that shell when
+the route doesn't declare its own.
+
+- A shell exporting `ErrorBoundary` is fine — often the right place for a
+  shared error fallback.
+- If **both** the shell and a route declare one, the route wins. Flag as
+  `info` at most, and only if the shell boundary is thereby unreachable for
+  every route under it (dead code).
+
+### 2f. `headers()` export
+
+Shells may export `headers()` to contribute response headers (merged with
+route `headers()`). Optional, but if present:
+- Verify the return shape is a plain `HeadersInit`.
+- Flag shells whose `headers()` returns `undefined` unconditionally — delete
+  the export.
+
+## Step 3: Coverage and waste
+
+Shell registration is mode-aware — check the `mode` field from the Step 1
+JSON first:
+
+- **Manifest apps** (`mode: "manifest"`): shells are
+  registered in `defineApp({ shells })`. Diff that registry against the
+  per-route resolved `shell`/`shellFile` values from the inspect JSON — the
+  JSON has no shell registry of its own, so "unused" means "registered in
+  `defineApp` but referenced by no route or group".
+- **Pages apps** (`mode: "pages"`): there is no `defineApp` shell registry.
+  The shell is `src/pages/_app.tsx`, auto-registered under the name `"pages"`
+  and applied to every route (see docs/ROUTING.md). "Unused shells" analysis
+  does not apply; instead verify `_app.tsx` (if present) shows up as the
+  resolved shell on every route.
+
+Then report:
+
+- **Unused shells** (manifest apps only): registered but referenced by no
+  route or group. Recommend removal.
+- **Single-use shells**: shells used by exactly one route — sometimes a
+  signal the layout should be inlined. Flag as `info`.
+- **Routes without shells**: routes resolved to no shell. Usually intentional
+  for raw HTML responses, but worth listing.
+
+## Step 4: Report
+
+| Shell | File | Used by | Issue | Severity |
+| ----- | ---- | ------- | ----- | -------- |
+
+Severities: `error` (document tags, missing children), `warn` (no `Loading`
+on SPA routes, empty `headers()`), `info` (unused, single-use, shell
+`ErrorBoundary` shadowed by route-level boundaries on every route).
+
+## Rules
+
+1. Source of truth is `pracht inspect routes --json` — it shows resolved
+   shell-per-route after group inheritance.
+2. Read the shell source — do not infer from names.
+3. `Loading()` is a shell export (SPA-only fallback). `ErrorBoundary` is
+   valid on both shells and routes: the shell's boundary is the fallback,
+   the route's wins when both exist. Do not flag shell boundaries as bugs.
+4. Recommend deletions for unused shells; do not delete automatically.
+5. When in doubt about render mode interaction, cross-reference with
+   `tune-render-mode`.
+
+$ARGUMENTS

package/skills/configure-isg/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: configure-isg
+version: 1.0.0
+description: |
+  Wire ISG (incremental static generation) revalidation correctly for the
+  project's adapter: route-level timeRevalidate/webhookRevalidate policies,
+  the authenticated /__pracht/revalidate webhook, Cloudflare Workers Caching,
+  Vercel native ISR, and cache-key pitfalls — then verify it locally.
+  Use when asked to "set up ISG", "configure revalidation", "add a
+  revalidation webhook", "my ISG page never updates", or "cache this page at
+  the edge".
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Write
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Configure ISG
+
+ISG renders at build time and regenerates after a time window or an
+authenticated webhook (`docs/RENDERING_MODES.md`, `docs/ADAPTERS.md`). The
+mechanics differ per adapter, and a route with `render: "isg"` but **no
+`revalidate` policy never regenerates** — the prerenderer only writes an ISG
+manifest entry when a policy exists. This skill wires the policy, the
+webhook, and the adapter-specific cache correctly.
+
+## Step 1: Identify adapter and candidate routes
+
+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    # render + revalidate per route
+pracht inspect build --json     # adapterTarget (requires a prior `pracht build`)
+```
+
+Prerequisite: `pracht inspect` needs a vite config with the pracht plugin
+wired up. If unsure *which* routes deserve ISG at all, run
+`/tune-render-mode` first — this skill assumes the mode choice is made.
+
+## Step 2: Wire the revalidate policy (manifest router)
+
+```typescript
+// src/routes.ts
+import { timeRevalidate, webhookRevalidate } from "@pracht/core";
+
+route("/pricing", () => import("./routes/pricing.tsx"), {
+  render: "isg",
+  revalidate: [timeRevalidate(3600), webhookRevalidate()],
+});
+```
+
+- `timeRevalidate(seconds)` — requires a positive **integer**; anything else
+  throws at manifest evaluation.
+- `webhookRevalidate()` — no arguments; opts the route into the webhook
+  endpoint.
+- `revalidate` accepts one policy or an array (`RouteRevalidate`); the array
+  above means "hourly, or sooner when a webhook names this path".
+
+**Pages router caveat:** `export const RENDER_MODE = "isg"` exists, but there
+is no `REVALIDATE` page constant — the pages scanner only extracts
+`RENDER_MODE` and `HYDRATION`, so pages-router ISG routes are frozen
+build-time snapshots. To attach a policy, eject to an explicit manifest with
+`generateRoutesFile` from `@pracht/vite-plugin/pages-router` (see
+docs/ROUTING.md "Ejecting to Explicit Manifest") and edit the generated route.
+
+For dynamic routes, `getStaticPaths()` enumerates the prerendered params.
+Paths it did not enumerate render per-request without a cached copy, and
+webhooks naming them are `skipped` on Node/Cloudflare (nothing to refresh).
+
+## Step 3: The revalidation webhook
+
+All adapters expose `POST /__pracht/revalidate` (`PRACHT_REVALIDATE_ENDPOINT`
+from `@pracht/core`):
+
+```sh
+curl -X POST https://example.com/__pracht/revalidate \
+  -H "Authorization: Bearer $PRACHT_REVALIDATE_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"paths":["/pricing"]}'
+```
+
+- Auth: `PRACHT_REVALIDATE_TOKEN` env var; fails closed with `401` when unset
+  or wrong. Providers that can't send bearer auth may use the
+  `x-pracht-revalidate-token` header instead.
+- Body: `paths` array, max 64 entries (else `400`). Response reports
+  `revalidated` / `skipped` / `failed` arrays; failed paths keep serving the
+  previous copy. Regeneration is single-flighted per path and never replays
+  the caller's cookies/auth headers.
+
+## Step 4: Adapter mechanics
+
+| Adapter | Time revalidation | Webhook revalidation |
+| ------- | ----------------- | -------------------- |
+| Node | File mtime vs window; serves stale, refreshes in background | Regenerates the on-disk HTML synchronously |
+| Cloudflare (default) | Worker-managed Cache API timestamp, `env.ASSETS` fallback — **per colo** | Overwrites the Cache API entry in the receiving colo only |
+| Cloudflare (`cache: true`) | Edge-tier Workers Caching in front of the Worker for time-revalidated routes | Webhook-only routes keep the worker-managed path; time+webhook routes also get their edge entry purged |
+| Vercel | Build Output prerender functions: `.prerender-config.json` with `expiration` from the time policy and build HTML as fallback | `x-vercel-cache`-verified bypass; `PRACHT_REVALIDATE_TOKEN` becomes the `bypassToken` and **must be set at build time** (runtime-only setting → webhook paths report `failed` until you rebuild) |
+
+Cloudflare specifics (`docs/ADAPTERS.md#isg-via-workers-caching-cache`):
+
+- The default per-colo path needs **no extra config**. The `cache: true`
+  upgrade needs both `cloudflareAdapter({ cache: true })` in vite config
+  (optionally `{ cache: { staleWhileRevalidate: <seconds> } }`) **and**
+  `{ "cache": { "enabled": true } }` in wrangler config.
+- With it on, time-revalidated pages are no longer emitted as build-time
+  snapshots (first request after deploy renders cold); webhook-only routes
+  keep their snapshots.
+- Programmatic purge: `purgeCache` / `routeCacheTag` from
+  `@pracht/adapter-cloudflare/cache` — protect any purge API route with a
+  secret.
+- Cache safety: responses with `Set-Cookie`, `Cache-Control:
+  private`/`no-store`, or `Vary: Cookie`/`Authorization`/`*` are never stored
+  in the shared edge cache.
+
+## Step 5: Cache-key cardinality caveats
+
+See `docs/ADAPTERS.md#cache-key-cardinality`. Node and worker-managed
+Cloudflare ISG key generated pages by **pathname**. Workers Caching keys by
+exact path **plus query string** (param order and trailing slash included), so
+`/pricing?ref=a` and `/pricing?ref=b` are independent entries with independent
+revalidation — and attacker-chosen query values create unbounded cold entries.
+Before enabling `cache: true`, canonicalize or reject stray query params (the
+docs describe an uncached-gateway pattern), and note that routes exporting
+`markdown` carry `Vary: Accept`, which multiplies variants per `Accept`
+string. Vercel prerender functions are generated with `allowQuery: []`, so
+query strings do not fragment that cache. Middleware never runs for cached ISG
+hits on any adapter — keep per-visitor logic on SSR routes.
+
+## Step 6: Verify locally
+
+- **Node**: `PRACHT_REVALIDATE_TOKEN=dev-secret pracht preview --port 3000`
+  (builds, then runs `dist/server/server.js` with inherited env;
+  `--skip-build` reuses a build). Then curl the Step 3 command against
+  `localhost:3000` and check the JSON reports your path under `revalidated`;
+  re-fetch the page and confirm the change. For time policies, use a short
+  window (e.g. `timeRevalidate(5)`), request after expiry — first response is
+  the stale copy, the next one is fresh.
+- **Cloudflare**: `pracht preview` delegates to `wrangler dev`; put
+  `PRACHT_REVALIDATE_TOKEN` in `.dev.vars` so the worker sees it.
+- **Vercel**: no faithful local production runtime — `pracht preview` points
+  at `vercel build`/`vercel dev`; verify webhook behavior on a real
+  deployment built with `PRACHT_REVALIDATE_TOKEN` set.
+
+Finish with the standard gate — and run `/pre-deploy` before shipping:
+
+```bash
+pracht verify --json
+pracht typegen   # if src/routes.ts changed
+```
+
+## Rules
+
+1. Never overwrite `wrangler.jsonc`/`wrangler.toml` or `vercel.json` — diff
+   and merge, confirming collisions with `AskUserQuestion`.
+2. Never propose ISG for personalized responses: `Set-Cookie` or
+   `Cache-Control: private`/`no-store` output fails regeneration, and
+   `Vary: Cookie`/`Authorization`/`*` is kept out of shared caches by design.
+3. Always pair `render: "isg"` with an explicit `revalidate` policy — without
+   one the route silently behaves like SSG.
+4. On Vercel, set `PRACHT_REVALIDATE_TOKEN` in the build environment, not
+   just at runtime.
+5. Cloudflare webhook invalidation on the default path is per-colo, not a
+   global purge — use shorter time windows (or `cache: true` + purge) when
+   global freshness matters.
+
+$ARGUMENTS