create-pracht 0.4.0 → 0.4.2

package/README.md

@@ -17,7 +17,7 @@ npm run dev
 - Detects the active package manager from the current environment.
 - Lets the user choose between the Node.js, Cloudflare, and Vercel adapters.
 - Optionally wires up Tailwind CSS (`tailwindcss` + `@tailwindcss/vite`, a global stylesheet, and the shell import).
-- Scaffolds a minimal app with a route manifest or pages router, shell, home route, sample API route, runnable project README, and agent instructions.
+- Scaffolds a minimal app with a route manifest or pages router, shell, home route, sample API route, runnable project README, TypeScript typecheck script, and agent instructions.
 - Manifest scaffolds include a commented-out `constraints` example in `src/routes.ts`, ready for `pracht verify`.
 - The generated `.gitignore` keeps `.pracht/app-graph.json` committable, and the README and agent instructions cover the `pracht verify` / `pracht plan` / `pracht report` loop.
 - Seeds the pracht Claude Code skills into `.claude/skills/` and writes a `.mcp.json` registering the `pracht mcp` server (yes-default prompt; skipped with `--no-agent-tools`).
@@ -80,6 +80,7 @@ Cloudflare scaffolds also include:
 
 - `dev` -> `pracht dev`
 - `build` -> `pracht build`
+- `typecheck` -> `tsc --noEmit`
 
 Node starters also include:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-pracht",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Interactive and scriptable starter CLI for creating full-stack Preact apps with Pracht.",
   "keywords": [
     "pracht",

package/skills/audit-auth/SKILL.md

@@ -91,9 +91,11 @@ target. From `pracht inspect api --json`:
   serves ALL methods but reports `methods: []` — treat
   `hasDefaultHandler: true` as "every method exposed". On older CLIs where
   the field is missing, grep the handler file for `export default` instead.
-- For each mutation handler (named method export or default handler), check
-  whether `defineApp({ api: { middleware } })` applies a Gate, OR the handler
-  reads/validates a session itself.
+- For each mutation handler (named method export or default handler) and each
+  HTTP-exposed capability, check whether
+  `defineApp({ api: { middleware } })` applies a Gate, OR the handler/capability
+  reads and validates a session itself. App-level API middleware wraps generated
+  capability endpoints before capability-specific middleware.
 - Common bug: dashboard route is protected by middleware, but
   `POST /api/items` is not — attacker bypasses the UI entirely.
 

package/skills/audit-csrf/SKILL.md

@@ -128,7 +128,8 @@ The canonical shape is in `recipes-auth.md` (the `origin-check.ts` example).
 
 Verify the wiring: the middleware name must appear in
 `defineApp({ api: { middleware: [...] } })` — that single global list applies
-to every API route. There is no per-group API middleware, and
+to every API route and generated capability HTTP endpoint. There is no
+per-group API middleware, and
 `pracht inspect api --json` output has no middleware field, so the manifest is
 the only place to check.
 

package/skills/audit-secrets/SKILL.md

@@ -115,6 +115,12 @@ Check for accidental exposure outside loaders:
   intentionally public, so flag client-side `VITE_*` references unless they are
   explicitly allowlisted and reviewed. Warn loudly if a public env name has a
   secret-shaped name.
+- Flag any client-side read of `import.meta.env` that is not a single-key
+  access — a bare reference, destructuring, a spread, or bracket access such as
+  `const env = import.meta.env` or `import.meta.env["MODE"]`. Vite replaces
+  those with an object literal holding **every** exposed variable, so the
+  `VITE_*` values land in the bundle with no accessor text left for a
+  name-based grep to find. Use `publicEnv` to enumerate public values.
 - Confirm server-side env access uses `serverEnv` (from
   `@pracht/core/env/server`) or `context.env` rather than ad-hoc globals.
 

package/skills/migrate-nextjs/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: migrate-nextjs
-version: 1.1.0
+version: 1.2.0
 description: |
   Migrate a Next.js application to Pracht. Converts App Router pages, layouts,
   middleware, API routes, data fetching, and metadata to pracht equivalents.
@@ -83,7 +83,7 @@ For pages router projects, you can **skip manual manifest wiring entirely** (Pha
 | `next/link` `<Link>`            | `<Link route="...">` or plain `<a>`                            | Prefer typed `<Link>` for known app routes after `pracht typegen`; plain anchors still work |
 | `next/link` `prefetch={false}`  | `<Link prefetch="none">`                                        | Pracht prefetches on hover/focus by default; also `"viewport"`, `"render"` |
 | `useLinkStatus()` / pending UI  | `useNavigation()`                                               | `{ state, location, formData }` — powers progress bars and optimistic UI |
-| `next/image`                    | Standard `<img>`                                                | Use `vite-imagetools` plugin if optimization needed                   |
+| `next/image`                    | `<Image>` from `@pracht/image`                                  | Responsive srcsets plus Node, Cloudflare, Vercel, or passthrough loaders |
 | `next/head` or Metadata API     | `head()` export on route/shell                                  | Per-route and per-shell head merging                                  |
 | `className`                     | `class`                                                         | Preact uses `class` attribute                                         |
 | `React.useState` etc.           | `import { useState } from "preact/hooks"`                       | Preact hooks API is compatible                                        |
@@ -117,6 +117,7 @@ For pages router projects, you can **skip manual manifest wiring entirely** (Pha
 3. Update `package.json`:
    - Replace `react`, `react-dom` → `preact`
    - Replace `next` → `@pracht/core` (framework runtime), `@pracht/cli` (provides the `pracht` bin), `@pracht/vite-plugin`, and `@pracht/adapter-node` (or target adapter). There is no package named `pracht`.
+   - If the app imports `next/image`, add `@pracht/image`; add `sharp` only for the built-in Node optimization endpoint.
    - Update scripts: `dev` → `pracht dev`, `build` → `pracht build`, `start` → `node dist/server/server.js` (Node.js) or a platform-specific deploy command; add `preview` → `pracht preview` to serve the production build locally
 4. Remove Next.js config files: `next.config.*`, `next-env.d.ts`, `.next/`
 5. If `tsconfig.json` has `"jsx": "preserve"`, change to `"jsx": "react-jsx"` and add `"jsxImportSource": "preact"`.
@@ -388,7 +389,7 @@ Plain anchors still work for simple, external, or user-provided URLs because the
 
 `<Link>` also accepts navigation-behavior props: `prefetch` (`"none" | "intent" | "viewport" | "render"`, default `"intent"` on hover/focus — the equivalent of `next/link`'s `prefetch` tuning), `preserveScroll` (skip the scroll-to-top reset), and `viewTransition` (wrap the navigation in `document.startViewTransition()` where supported). Scroll restoration on back/forward works out of the box, like Next.js.
 
-#### `next/image` → `<img>`
+#### `next/image` → `@pracht/image`
 
 ```tsx
 // Next.js
@@ -396,9 +397,24 @@ import Image from "next/image";
 <Image src="/photo.jpg" width={500} height={300} alt="Photo" />
 
 // Pracht
-<img src="/photo.jpg" width={500} height={300} alt="Photo" />
+import { Image } from "@pracht/image";
+<Image src="/photo.jpg" width={500} height={300} alt="Photo" />
 ```
 
+Choose the loader for the deployment target:
+
+- Node: mount `createImageHandler()` from `@pracht/image/node`, install
+  `sharp`, and set its `localOrigin` to the same trusted value as
+  `nodeAdapter({ canonicalOrigin })`.
+- Cloudflare Workers: configure `cloudflareLoader`; do not bundle the Node
+  handler because `sharp` does not run in Workers.
+- Vercel Edge: configure `vercelLoader` and keep Vercel's allowed image sizes
+  aligned with the Pracht breakpoints.
+- Static hosts: configure `passthroughLoader`.
+
+Preserve the original `width`, `height`, `fill`, `sizes`, `quality`, and
+priority intent. See `docs/IMAGES.md` for the endpoint and loader wiring.
+
 #### `useRouter` → navigation
 
 ```tsx
@@ -483,6 +499,7 @@ export async function loader({ request }: LoaderArgs) {
 | Next.js package | Pracht equivalent                                                            |
 | --------------- | ---------------------------------------------------------------------------- |
 | `next`          | `@pracht/core` + `@pracht/cli` + `@pracht/vite-plugin` + `@pracht/adapter-node` (or target adapter) |
+| `next/image`    | `@pracht/image`                                         |
 | `react`         | `preact`                                                |
 | `react-dom`     | `preact`                                                |
 | `@next/font`    | CSS `@font-face` or `fontsource` packages               |

package/skills/pre-deploy/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pre-deploy
-version: 1.1.0
+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
@@ -75,6 +75,11 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
 - 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 relative image endpoint without both
+  values is an error in every environment; loopback-looking request origins
+  are intentionally not trusted.
 - Reverse-proxy / TLS termination configured (out of scope for this skill —
   flag for confirmation).
 
@@ -101,6 +106,9 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   - 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 })`
@@ -131,6 +139,9 @@ a markdown summary (graph diff + verify + budgets) worth attaching to it.
   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

package/skills/typed-routes/SKILL.md

@@ -60,6 +60,10 @@ This writes:
 - `src/pracht.d.ts` — module augmentation for route ids, params, loader data
   types, and API route request/response types (consumed by `apiFetch()`).
 - `src/pracht-routes.ts` — runtime `href()` helper backed by the same route map.
+- `src/pracht-capabilities.d.ts` — only when the app registers capabilities:
+  input/output types from the capability schemas, so `invokeCapability()`,
+  `callCapability()`, and `<Form capability>`'s `onCapabilityResult` infer
+  types from the capability name.
 
 Earlier versions wrote the declaration to `src/pracht-routes.d.ts`; typegen
 removes that stale file automatically (TypeScript silently ignored it next to

package/skills/upgrade-pracht/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upgrade-pracht
-version: 1.0.0
+version: 1.0.1
 description: |
   Upgrade the @pracht/* packages in an app safely: inventory installed
   versions, read the changelogs between installed and target, map breaking
@@ -33,8 +33,8 @@ pnpm list --depth 1 --json | grep -A2 '@pracht/'   # or read package.json + lock
 
 The family: `@pracht/core`, `@pracht/cli`, `@pracht/vite-plugin`,
 `@pracht/adapter-node`, `@pracht/adapter-cloudflare`, `@pracht/adapter-vercel`,
-`@pracht/preact-ssr-precompile`. Get the latest published versions with
-`npm view <pkg> version`.
+`@pracht/preact-ssr-precompile`, `@pracht/image`. Get the latest published
+versions with `npm view <pkg> version`.
 
 ## Step 2: Understand the versioning model
 
@@ -75,6 +75,7 @@ https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGE
 | `@pracht/vite-plugin` | `packages/vite-plugin` |
 | `@pracht/adapter-node` / `-cloudflare` / `-vercel` | `packages/adapter-*` |
 | `@pracht/preact-ssr-precompile` | `packages/preact-ssr-precompile` |
+| `@pracht/image` | `packages/image` |
 
 Changelogs are changesets-generated: `## X.Y.Z` sections containing
 `### Major Changes` / `### Minor Changes` / `### Patch Changes`. Read every

package/src/index.js

@@ -21,6 +21,7 @@ const FALLBACK_VERSION_RANGES = {
   "@pracht/vite-plugin": "^0.3.2",
   "@tailwindcss/vite": "^4.1.0",
   tailwindcss: "^4.1.0",
+  typescript: "^6.0.0",
   vercel: "^56.5.0",
 };
 
@@ -567,6 +568,7 @@ async function buildProjectFiles({
     "@pracht/vite-plugin",
     "@pracht/core",
     adapter.packageName,
+    "typescript",
   ];
   if (adapter.id === "vercel") {
     packagesToResolve.push("vercel");
@@ -664,6 +666,7 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
   const scripts = {
     build: "pracht build",
     dev: "pracht dev",
+    typecheck: "tsc --noEmit",
   };
 
   if (adapter.id === "node") {
@@ -676,6 +679,7 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
     preact: "^10.26.9",
     "preact-render-to-string": "^6.5.13",
+    typescript: versions["typescript"],
     vite: "^8.0.0",
   };
 
@@ -724,8 +728,8 @@ function createViteConfig(adapter, router, tailwind) {
 
   const prachtOptions =
     router === "pages"
-      ? `{ pagesDir: "/src/pages", adapter: ${info.fn}() }`
-      : `{ adapter: ${info.fn}() }`;
+      ? `{ pagesDir: "/src/pages", adapter: ${info.fn}(), llmsTxt: {} }`
+      : `{ adapter: ${info.fn}(), llmsTxt: {} }`;
 
   const plugins = tailwind
     ? `[pracht(${prachtOptions}), tailwindcss()]`
@@ -1116,6 +1120,8 @@ function createReadme({ adapter, agentTools, packageManager, projectName, router
   const previewCommand = packageManager === "npm" ? "npm run preview" : `${packageManager} preview`;
   const startCommand = packageManager === "npm" ? "npm run start" : `${packageManager} start`;
   const deployCommand = packageManager === "npm" ? "npm run deploy" : `${packageManager} deploy`;
+  const typecheckCommand =
+    packageManager === "npm" ? "npm run typecheck" : `${packageManager} typecheck`;
 
   const lines = [
     `# ${projectName}`,
@@ -1126,6 +1132,7 @@ function createReadme({ adapter, agentTools, packageManager, projectName, router
     "",
     `- \`${installCommand}\``,
     `- \`${devCommand}\``,
+    `- \`${typecheckCommand}\``,
   ];
 
   if (adapter.id === "node") {