create-pracht 0.6.2 → 0.7.0

package/skills/migrate-nextjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-nextjs
-version: 1.3.0
+version: 1.7.0
 description: |
   Migrate a Next.js app to pracht: App or Pages Router pages, layouts, middleware,
   API routes, data fetching, and metadata — plus React→Preact, `className`→`class`,
@@ -25,11 +25,8 @@ before converting it; never infer from the filename. Prefer the simplest
 pracht equivalent, and when a Next.js feature has no equivalent, say so and
 propose an alternative instead of inventing one.
 
-MCP: when the pracht MCP server is registered (docs/MCP.md), use
-`generate_route`/`generate_shell`/`generate_middleware`/`generate_api` to
-scaffold and `inspect_routes`/`inspect_api`/`doctor`/`verify` to check
-progress, instead of Bash. `pracht inspect` needs the pracht plugin in the
-vite config; `inspect_build` needs a prior `pracht build`.
+With the Pracht MCP server, prefer its generate/inspect/doctor/verify tools;
+`inspect_build` needs a prior `pracht build`.
 
 ## Step 0: Assess the source
 
@@ -40,6 +37,9 @@ the tree: `app/` (App Router), `pages/` (Pages Router), `middleware.ts`,
 `"use server"` actions — and the third-party integrations (auth, CMS, DB,
 analytics). Confirm scope with the user if the app has more than ~20 routes.
 
+Agent tools alone do not require a router migration; use the standalone host:
+<https://pracht.resynapse.dev/docs/standalone-capabilities>.
+
 ## Fast path: Pages Router
 
 `pagesDir` makes a pages-router source near-drop-in — **Phase 7 is then
@@ -47,13 +47,25 @@ automatic**:
 
 1. `pracht({ pagesDir: "/src/pages" })` in `vite.config.ts`; copy `pages/` to
    `src/pages/`.
-2. `_app.tsx` → pracht shell shape (`Shell` export taking `children`).
+2. `_app.tsx` → pracht shell shape (`Shell` export taking `children`). A
+   subdirectory `_app` scopes a shell to that subtree (`blog/_app.tsx` →
+   `"pages:blog"`), where App Router `layout.tsx` lands — but shells replace
+   rather than nest, so it repeats the chrome, `head()`, and `headers()` it
+   needs.
 3. `getServerSideProps`/`getStaticProps` → `loader` export.
 4. `export const RENDER_MODE = "ssg"` on static pages (`"ssr"` is the
    default). For time-revalidated pages export `RENDER_MODE = "isg"` plus a
    positive integer `REVALIDATE` in seconds; webhook policies require ejecting
    to a manifest.
-5. Run the dev server, iterate, and optionally eject later with
+5. `middleware.ts` → a root-level `src/pages/_middleware.ts` exporting a
+   `MiddlewareFn` (Phase 6). It runs on every page route; API routes are not
+   wrapped. Move `config.matcher` checks into the body and compare
+   `stripBase(url.pathname)`. A nested `_middleware`, a `_middleware/`
+   directory, and a missing export are build/doctor/verify errors.
+6. Other `_`-prefixed files and directories are reserved: pracht ignores the
+   subtree. Capabilities live in `src/capabilities/` (auto-discovered,
+   self-named); `agents` / `constraints` in `src/pages/_app.config.ts`.
+7. Run the dev server, iterate, and optionally eject later with
    `generateRoutesFile`.
 
 ## Concept mapping
@@ -62,11 +74,11 @@ automatic**:
 | ------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------- |
 | `pages/` directory              | `pagesDir` plugin option                                        | Auto-discovers routes from the file system                            |
 | `app/page.tsx`                  | `src/routes/*.tsx` + `route()` in manifest                      | File is a module; wiring is explicit                                  |
-| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp`                    | Shells are named, not directory-nested                                |
+| `app/layout.tsx`                | `src/shells/*.tsx` + `shells` in `defineApp` (pages: `_app.tsx` per directory) | Named shells; a directory `_app` replaces its parent instead of nesting |
 | `app/loading.tsx`               | `Loading` export on the shell                                   | SSR placeholder for SPA routes until the client router takes over     |
 | `app/error.tsx`                 | `ErrorBoundary` export in route module                          | Same concept, different wiring                                        |
 | `app/not-found.tsx`             | `notFound:` in `defineApp` (or `pages/404.tsx` in pagesDir mode) | Not a route — never matches a URL, so it cannot shadow static assets  |
-| `middleware.ts`                 | `src/middleware/*.ts` + `middleware` in `defineApp`             | Named, applied per route/group                                        |
+| `middleware.ts`                 | `src/middleware/*.ts` + `middleware` in `defineApp` (or `src/pages/_middleware.ts` in pagesDir mode) | Named, applied per route/group; the pages-mode file runs on every page route |
 | `app/api/*/route.ts`            | `src/api/*.ts` with `GET`/`POST` exports                        | Auto-discovered, no manifest entry                                    |
 | `generateStaticParams`          | `getStaticPaths()` export                                       | Returns `RouteParams[]` of param objects                              |
 | `generateMetadata`              | `head()` export                                                 | Returns `{ title, meta }`                                             |
@@ -204,6 +216,14 @@ export const middleware: MiddlewareFn = async ({ request }, next) => {
 is wrap-around (Hono/Koa/Astro shape), so you can `await next()` and observe
 the response — useful for tracing.
 
+In `pagesDir` mode the same `MiddlewareFn` goes in a root-level
+`src/pages/_middleware.ts`, applied to every page route (API routes stay
+unwrapped). Do not migrate a per-request auth matcher onto an `ssg`/`isg` page
+and call it protected: that document runs middleware only at
+build/revalidation, with a sanitized request. Keep such pages `ssr`/`spa`, or
+keep a separately verified edge gate. Pure static exports have no request
+runtime.
+
 ## Phase 7: Route manifest
 
 Skip this phase for `pagesDir` projects. Prefer

package/skills/pracht-scaffold/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pracht-scaffold
-version: 1.2.0
+version: 1.4.0
 description: |
   Scaffold pracht code with the native generators (`pracht generate
   route|shell|middleware|api`), falling back to manual edits only when the CLI
@@ -57,6 +57,16 @@ agent or tool consumes the output. When the pracht MCP server is registered
 
 - `--shell`/`--middleware` names must already be registered or the CLI errors.
   Generate the shell or middleware first, then the route referencing it.
+- Pages-router apps have one middleware seam: `pracht generate middleware
+  --name _middleware` scaffolds the root `src/pages/_middleware.ts`, which runs
+  on every page route (API routes are not wrapped). Other names error in pages
+  mode, pure static exports cannot use request middleware, and `generate shell`
+  stays manifest-only — pages apps add an `_app.tsx` to the directory they want
+  it to wrap (`src/pages/blog/_app.tsx` registers `pages:blog`).
+- `generate capability` works in both modes. Manifest apps get a `capabilities`
+  registry entry; pages apps auto-discover `src/capabilities/`, so the module
+  declares its own `name` and no manifest is written. Pages `agents` and
+  `constraints` are named exports in `src/pages/_app.config.ts`.
 - `generate route` also emits a Playwright smoke test in `e2e/` when the app
   has a Playwright setup (`playwright.config.*` or an `e2e/` directory);
   `--no-test` skips it, `--test` forces it. The test imports

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

@@ -127,6 +127,42 @@ field (absent from the JSON), grep the manifest for `hydration:` (pages apps:
   router), island props must be JSON-serializable, and `render: "spa"` cannot
   combine with `"islands"`/`"none"`.
 
+## Step 3c: Consider streaming for slow SSR routes
+
+An `ssr` route whose loader has one slow call and several fast ones is a
+candidate for `defer()` plus `streaming: true`. Flag it when the loader awaits
+more than one independent source and at least one is materially slower — the
+whole document currently waits on the slowest.
+
+```ts
+// before: TTFB waits on getReviews()
+return { product: await getProduct(id), reviews: await getReviews(id) };
+
+// after: shell flushes without reviews, which stream in
+return { product: await getProduct(id), reviews: defer(getReviews(id)) };
+```
+
+Pages routes use `export const STREAMING = true` with SSR and full hydration.
+
+Recommend `streaming: true` only alongside a `<Suspense>` boundary reading the
+deferred value with `use()`; without a boundary there is nothing to flush
+early. Do not recommend it for:
+
+- `ssg` / `isg` routes — they write files and the manifest rejects the
+  combination
+- routes with `hydration` other than `"full"` — no client runtime resumes a
+  boundary, and the manifest rejects it
+- routes whose loader is a single slow call with nothing else to show — the
+  shell would be empty and the user sees a skeleton rather than content
+
+Also mention the tradeoffs when proposing it: a deferred rejection surfaces at
+the read site rather than as an error document (the response is already
+committed at `200`), and streaming needs a `script-src` that allows the
+renderer's inline bootstrap script. Route `head()` and `headers()` hooks run
+before deferred work settles, so any data they need must stay awaited. Confirm
+the app uses
+`preact-render-to-string` 6.7 or newer before enabling streaming.
+
 ## Step 4: Propose diffs, then apply on confirmation
 
 Present the exact edits and wait for approval. Where the edit lands depends

package/skills/typed-routes/SKILL.md

@@ -145,8 +145,9 @@ export function Component() {
 
 Prefer this over `useRouteData<typeof loader>()` when typegen runs; keep the
 generic form for projects that do not generate route types. Routes without a
-loader type their data as `undefined`. The id must be the active route — dev
-mode warns on mismatches.
+loader type their data as `undefined`. The id must be the active route: a
+mismatch throws (with a descriptive message in dev), so a shell or island that
+needs another route's data must receive it as props instead.
 
 ### API routes
 

package/skills/upgrade-pracht/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upgrade-pracht
-version: 1.0.2
+version: 1.1.0
 description: |
   Upgrade the `@pracht/*` packages safely: inventory installed versions, read the
   changelogs between installed and target, map breaking changes to real usage,
@@ -30,11 +30,15 @@ List every installed pracht package and its resolved version:
 pnpm list --depth 1 --json | grep -A2 '@pracht/'   # or read package.json + lockfile
 ```
 
-The family: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
-`@pracht/adapter-node`, `@pracht/adapter-cloudflare`, `@pracht/adapter-vercel`,
-`@pracht/preact-ssr-precompile`, `@pracht/content`, `@pracht/markdown`,
-`@pracht/image`. Get the latest published versions with
-`npm view <pkg> version`.
+The family, in full: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
+`@pracht/adapter-node`, `@pracht/adapter-cloudflare`,
+`@pracht/adapter-netlify`, `@pracht/adapter-vercel`,
+`@pracht/adapter-static`, `@pracht/preact-ssr-precompile`,
+`@pracht/capabilities`, `@pracht/content`, `@pracht/markdown`,
+`@pracht/openapi`, `@pracht/image`, `@pracht/i18n`, `@pracht/session`,
+`@pracht/test`, plus the `create-pracht` scaffolder (which is not a runtime
+dependency and does not need to move with the rest). Get the latest published
+versions with `npm view <pkg> version`.
 
 ## Step 2: Understand the versioning model
 
@@ -73,11 +77,17 @@ https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGE
 | `@pracht/core` | `packages/framework` |
 | `@pracht/cli` | `packages/cli` |
 | `@pracht/vite-plugin` | `packages/vite-plugin` |
-| `@pracht/adapter-node` / `-cloudflare` / `-vercel` | `packages/adapter-*` |
+| `@pracht/adapter-node` / `-cloudflare` / `-netlify` / `-vercel` / `-static` | `packages/adapter-*` |
 | `@pracht/preact-ssr-precompile` | `packages/preact-ssr-precompile` |
+| `@pracht/capabilities` | `packages/capabilities` |
 | `@pracht/content` | `packages/content` |
 | `@pracht/markdown` | `packages/markdown` |
+| `@pracht/openapi` | `packages/openapi` |
 | `@pracht/image` | `packages/image` |
+| `@pracht/i18n` | `packages/i18n` |
+| `@pracht/session` | `packages/session` |
+| `@pracht/test` | `packages/test` |
+| `create-pracht` | `packages/start` |
 
 Changelogs are changesets-generated: `## X.Y.Z` sections containing
 `### Major Changes` / `### Minor Changes` / `### Patch Changes`. Read every
@@ -92,7 +102,7 @@ changelog prescribes, and whether it can be applied mechanically. Also
 re-check peer ranges after a major target bump — `@pracht/vite-plugin`
 requires `vite` (^8), `@pracht/adapter-cloudflare` requires `vite` and
 `wrangler` (^4.81), `@pracht/core` requires `preact` (^10) and
-`preact-render-to-string` (^6).
+`preact-render-to-string` (^6.7).
 
 Present the plan as a table: