create-pracht 0.3.0 → 0.4.1

package/skills/upgrade-pracht/SKILL.md

@@ -0,0 +1,152 @@
+---
+name: upgrade-pracht
+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
+  changes to actual usage in the codebase, apply the upgrade, and walk the
+  verification ladder (doctor, typegen, verify, build, tests).
+  Use when asked to "upgrade pracht", "update @pracht packages", "bump the
+  framework", "what changed in the new pracht version", or "is this pracht
+  upgrade safe".
+allowed-tools:
+  - Bash
+  - Read
+  - Edit
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+# Pracht Upgrade
+
+Upgrade `@pracht/*` dependencies with the changelog read *before* the install,
+not after the build breaks.
+
+## Step 1: Inventory
+
+List every installed pracht package and its resolved version:
+
+```bash
+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/image`. Get the latest published
+versions with `npm view <pkg> version`.
+
+## Step 2: Understand the versioning model
+
+Pracht packages are **independently versioned** (the repo's changesets config
+has empty `fixed`/`linked` groups) — `@pracht/core` can be at 0.9.x while
+`@pracht/cli` is at 1.6.x. There is no "one framework version". Two
+consequences:
+
+1. **Internal dependencies are pinned exact.** Published packages depend on
+   their siblings at exact versions (e.g. `@pracht/vite-plugin@0.5.0` depends
+   on `@pracht/core@0.9.0`, not a range). Upgrade the whole family in one
+   move; upgrading only one package can drag in a second copy of
+   `@pracht/core` and split the runtime.
+2. **Most packages are 0.x**, so under semver a *minor* bump may be breaking —
+   treat `### Minor Changes` entries on 0.x packages with the same care as
+   majors.
+
+After any upgrade, confirm a single core resolution:
+
+```bash
+pnpm why @pracht/core   # exactly one version may appear
+```
+
+## Step 3: Read the changelogs between installed and target
+
+Only `@pracht/cli` ships `CHANGELOG.md` in its npm tarball
+(`node_modules/@pracht/cli/CHANGELOG.md`); the other packages publish `dist/`
+only. Fetch their changelogs from the repo instead:
+
+```
+https://raw.githubusercontent.com/JoviDeCroock/pracht/main/packages/<dir>/CHANGELOG.md
+```
+
+| Package | Repo directory |
+| ------- | -------------- |
+| `@pracht/core` | `packages/framework` |
+| `@pracht/cli` | `packages/cli` |
+| `@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
+section between the installed and target version of every installed package.
+
+## Step 4: Map changes onto this app
+
+Classify each entry as **breaking** / **feature** / **fix**. For each breaking
+(or 0.x minor) entry, grep the app for the APIs, exports, config options, and
+generated-file shapes it names, and record: affected files, the migration the
+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).
+
+Present the plan as a table:
+
+| Package | Installed → Target | Breaking entries | App impact | Migration |
+| ------- | ------------------ | ---------------- | ---------- | --------- |
+
+## Step 5: Confirm, then apply
+
+Use `AskUserQuestion` before touching anything when breaking migrations are
+required: confirm the target versions and which migrations to apply. Then:
+
+```bash
+pnpm up '@pracht/core@<v>' '@pracht/cli@<v>' '@pracht/vite-plugin@<v>' <adapters...>
+```
+
+Upgrade every installed `@pracht/*` package in the same command. Apply the
+agreed code migrations with minimal diffs, one changelog entry at a time.
+
+## Step 6: Verification ladder
+
+Run in order; stop and fix at the first failure:
+
+```bash
+pracht doctor --json          # wiring still valid
+pracht typegen --check        # generated route types up to date?
+pracht typegen                # regenerate if --check failed or routes changed
+pracht verify --json          # framework-aware checks
+pracht build                  # full production build (budgets included)
+pnpm test                     # the app's own suite
+```
+
+`pracht doctor`, `verify`, and `typegen --check` exit non-zero on failure, so
+they gate CI cleanly.
+
+## Step 7: Rollback note
+
+If the ladder cannot be made green, roll back rather than shipping a
+half-upgrade:
+
+```bash
+git restore package.json pnpm-lock.yaml && pnpm install
+git checkout -- <migrated files>   # or revert the upgrade commit
+```
+
+Because internal deps are exact-pinned, a *partial* rollback (one package
+back, the rest forward) recreates the duplicate-core problem from Step 2 —
+roll the whole family back together.
+
+## Rules
+
+1. Never mix `@pracht/*` versions from different release waves — upgrade and
+   roll back the family as a unit, and verify with `pnpm why @pracht/core`.
+2. Read changelogs before installing, not after something breaks.
+3. Never apply a breaking-change migration without explicit user confirmation
+   via `AskUserQuestion`.
+4. Treat 0.x minor bumps as potentially breaking.
+5. Do not hand-edit lockfiles; let the package manager resolve.
+
+$ARGUMENTS

package/src/index.js

@@ -1,8 +1,9 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { copyFile, mkdir, readdir, stat, symlink, writeFile } from "node:fs/promises";
+import { copyFile, mkdir, readFile, readdir, stat, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
 
 export class ValidationError extends Error {
   constructor(message) {
@@ -20,7 +21,7 @@ const FALLBACK_VERSION_RANGES = {
   "@pracht/vite-plugin": "^0.3.2",
   "@tailwindcss/vite": "^4.1.0",
   tailwindcss: "^4.1.0",
-  vercel: "latest",
+  vercel: "^56.5.0",
 };
 
 async function fetchLatestVersion(packageName) {
@@ -58,6 +59,12 @@ const ADAPTERS = {
 
 const DEFAULT_DIRECTORY = "pracht-app";
 
+const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+// The published package bundles a copy of the repo skills (see
+// scripts/sync-skills.js); inside the monorepo we fall back to the source.
+const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../../skills")];
+
 export async function run(argv = process.argv.slice(2)) {
   const options = parseArgs(argv);
   const packageManager = getPackageManager();
@@ -71,17 +78,20 @@ export async function run(argv = process.argv.slice(2)) {
   const adapterId = options.adapter ?? (options.yes ? "node" : null);
   const router = options.router ?? (options.yes ? "manifest" : null);
   const tailwind = options.tailwind ?? (options.yes ? false : null);
+  const agentTools = options.agentTools ?? (options.yes ? true : null);
 
   let resolvedDir = dir;
   let resolvedAdapter = adapterId;
   let resolvedRouter = router;
   let resolvedTailwind = tailwind;
+  let resolvedAgentTools = agentTools;
 
   if (
     resolvedDir == null ||
     resolvedAdapter == null ||
     resolvedRouter == null ||
-    resolvedTailwind == null
+    resolvedTailwind == null ||
+    resolvedAgentTools == null
   ) {
     const readline = createInterface({
       input: process.stdin,
@@ -93,6 +103,7 @@ export async function run(argv = process.argv.slice(2)) {
       resolvedAdapter = resolvedAdapter ?? (await promptForAdapter(readline));
       resolvedRouter = resolvedRouter ?? (await promptForRouter(readline));
       resolvedTailwind = resolvedTailwind ?? (await promptForTailwind(readline));
+      resolvedAgentTools = resolvedAgentTools ?? (await promptForAgentTools(readline));
     } finally {
       readline.close();
     }
@@ -105,6 +116,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (options.dryRun) {
     const files = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentTools: resolvedAgentTools,
       packageManager,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
@@ -118,6 +130,7 @@ export async function run(argv = process.argv.slice(2)) {
       console.log(
         JSON.stringify({
           adapter: resolvedAdapter,
+          agentTools: resolvedAgentTools,
           directory: resolvedDir,
           dryRun: true,
           files: fileList,
@@ -138,6 +151,7 @@ export async function run(argv = process.argv.slice(2)) {
 
   await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
+    agentTools: resolvedAgentTools,
     packageManager,
     router: resolvedRouter,
     tailwind: resolvedTailwind,
@@ -171,6 +185,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (options.json) {
     const files = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentTools: resolvedAgentTools,
       packageManager,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
@@ -181,6 +196,7 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(
       JSON.stringify({
         adapter: resolvedAdapter,
+        agentTools: resolvedAgentTools,
         directory: resolvedDir,
         files: Object.keys(files).sort(),
         gitInitialized,
@@ -202,7 +218,9 @@ export async function run(argv = process.argv.slice(2)) {
 
 export async function scaffoldProject({
   adapter,
+  agentTools = true,
   packageManager,
+  resolveRemoteVersions = true,
   router = "manifest",
   tailwind = false,
   targetDir,
@@ -210,8 +228,10 @@ export async function scaffoldProject({
   const packageName = toPackageName(basename(targetDir));
   const files = await buildProjectFiles({
     adapter,
+    agentTools,
     packageManager,
     projectName: packageName,
+    resolveRemoteVersions,
     router,
     tailwind,
   });
@@ -245,6 +265,7 @@ export function getPackageManager(userAgent = process.env.npm_config_user_agent
 export function parseArgs(argv) {
   const options = {
     adapter: undefined,
+    agentTools: undefined,
     dir: undefined,
     dryRun: false,
     git: true,
@@ -276,6 +297,16 @@ export function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--agent-tools") {
+      options.agentTools = true;
+      continue;
+    }
+
+    if (arg === "--no-agent-tools") {
+      options.agentTools = false;
+      continue;
+    }
+
     if (arg.startsWith("--template=")) {
       const value = normalizeTemplate(arg.slice("--template=".length));
       if (!value) {
@@ -403,6 +434,19 @@ async function promptForTailwind(readline) {
   }
 }
 
+async function promptForAgentTools(readline) {
+  while (true) {
+    const answer = await readline.question("Set up Claude Code skills + MCP? (Y/n): ");
+    const normalized = normalizeYesNo(answer.trim() || "yes");
+
+    if (normalized != null) {
+      return normalized;
+    }
+
+    console.log("Answer y/yes or n/no.");
+  }
+}
+
 function normalizeYesNo(value) {
   const normalized = value.toLowerCase();
 
@@ -511,6 +555,7 @@ async function resolveVersions(packageNames, { remote = true } = {}) {
 
 async function buildProjectFiles({
   adapter,
+  agentTools = true,
   packageManager,
   projectName,
   resolveRemoteVersions = true,
@@ -533,13 +578,21 @@ async function buildProjectFiles({
   const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
 
   const files = {
-    ".gitignore": "dist\nnode_modules\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n",
-    "README.md": createReadme({ adapter, packageManager, projectName, router, tailwind }),
+    ".gitignore":
+      "dist\nnode_modules\n.wrangler\n.vercel\n.env*\n!.env.example\n.dev.vars\n# Keep .pracht/app-graph.json committed — it is the `pracht plan` snapshot.\n",
+    "README.md": createReadme({
+      adapter,
+      agentTools,
+      packageManager,
+      projectName,
+      router,
+      tailwind,
+    }),
     "package.json": createPackageJson({ adapter, projectName, tailwind, versions }),
     "src/api/health.ts": createHealthRoute(adapter),
     "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
-    "AGENTS.md": createAgentInstructions({ adapter, packageManager, router, tailwind }),
+    "AGENTS.md": createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }),
   };
 
   if (router === "pages") {
@@ -565,6 +618,45 @@ async function buildProjectFiles({
     files[".dockerignore"] = createDockerignore();
   }
 
+  if (agentTools) {
+    files[".mcp.json"] = createMcpConfig();
+    Object.assign(files, await readSkillFiles());
+  }
+
+  return files;
+}
+
+function createMcpConfig() {
+  return `${JSON.stringify(
+    {
+      mcpServers: {
+        pracht: {
+          command: "npx",
+          args: ["pracht", "mcp"],
+        },
+      },
+    },
+    null,
+    2,
+  )}\n`;
+}
+
+async function readSkillFiles() {
+  const skillsDir = SKILL_DIRS.find((dir) => existsSync(dir));
+
+  if (!skillsDir) {
+    return {};
+  }
+
+  const files = {};
+  for (const name of await readdir(skillsDir)) {
+    const skillFile = resolve(skillsDir, name, "SKILL.md");
+    if (!existsSync(skillFile)) {
+      continue;
+    }
+    files[`.claude/skills/${name}/SKILL.md`] = await readFile(skillFile, "utf-8");
+  }
+
   return files;
 }
 
@@ -632,8 +724,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()]`
@@ -665,6 +757,13 @@ function createRoutesFile() {
     "  routes: [",
     '    route("/", "./routes/home.tsx", { id: "home", render: "ssg", shell: "public" }),',
     "  ],",
+    "  // Custom 404 page — any module in ./routes, rendered when nothing matches:",
+    '  // notFound: "./routes/not-found.tsx",',
+    "  // Declarative invariants enforced by `pracht verify` — uncomment to use",
+    "  // (add the helpers to the @pracht/core import):",
+    "  // constraints: [",
+    '  //   requireHead("**"),',
+    "  // ],",
     "});",
     "",
   ].join("\n");
@@ -920,7 +1019,7 @@ function createDockerignore() {
   ].join("\n");
 }
 
-function createAgentInstructions({ adapter, packageManager, router, tailwind }) {
+function createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }) {
   const runCmd = packageManager === "npm" ? "npm run" : packageManager;
 
   const lines = [
@@ -954,6 +1053,12 @@ function createAgentInstructions({ adapter, packageManager, router, tailwind })
   lines.push("- `pracht generate middleware --name auth` — add middleware");
   lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
   lines.push("- `pracht doctor` — check project health");
+  lines.push("- `pracht verify` — enforce route and constraint invariants");
+  lines.push(
+    "- `pracht plan --write` — refresh the committed `.pracht/app-graph.json` snapshot after route changes",
+  );
+  lines.push("- `pracht report` — PR-ready markdown summary (plan diff, verify, budgets)");
+  lines.push("- `pracht llms --write` — write an `llms.txt` authoring guide for coding agents");
 
   lines.push("");
   lines.push("## Project structure");
@@ -988,12 +1093,24 @@ function createAgentInstructions({ adapter, packageManager, router, tailwind })
     lines.push("- `src/env.d.ts` — TypeScript types for Cloudflare bindings");
   }
 
+  if (agentTools) {
+    lines.push("");
+    lines.push("## Agent tooling");
+    lines.push("");
+    lines.push(
+      "- `.claude/skills/` — pracht Claude Code skills (audits, scaffolds, testing, debugging); invoke with `/<skill-name>`",
+    );
+    lines.push(
+      "- `.mcp.json` — registers the `pracht mcp` server so MCP clients can inspect the app graph, run doctor/verify, and scaffold natively",
+    );
+  }
+
   lines.push("");
 
   return lines.join("\n");
 }
 
-function createReadme({ adapter, packageManager, projectName, router, tailwind }) {
+function createReadme({ adapter, agentTools, packageManager, projectName, router, tailwind }) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
   const previewCommand = packageManager === "npm" ? "npm run preview" : `${packageManager} preview`;
@@ -1050,6 +1167,25 @@ function createReadme({ adapter, packageManager, projectName, router, tailwind }
     lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
   }
 
+  if (agentTools) {
+    lines.push(
+      "- `.claude/skills/` and `.mcp.json` wire up the pracht Claude Code skills and MCP server.",
+    );
+  }
+
+  lines.push("");
+  lines.push("## Checks");
+  lines.push("");
+  lines.push(
+    router === "pages"
+      ? "- `pracht verify` validates routes."
+      : "- `pracht verify` validates routes and constraints.",
+  );
+  lines.push(
+    "- `pracht plan --write` commits an app-graph snapshot to `.pracht/`; `pracht plan` diffs against it.",
+  );
+  lines.push("- `pracht report` prints a PR-ready summary of both.");
+
   if (adapter.id === "node") {
     lines.push("");
     lines.push("## Docker");
@@ -1172,6 +1308,8 @@ Options:
   --router=manifest|pages      Choose routing system (default: manifest)
   --template=minimal|tailwind  Choose starter template (minimal, or minimal + Tailwind CSS)
   --tailwind / --no-tailwind   Enable or disable Tailwind CSS wiring (default: prompt)
+  --agent-tools / --no-agent-tools
+                               Seed Claude Code skills and a pracht MCP config (default: prompt, yes)
   --no-git                     Skip git init and the initial commit
   --skip-install               Skip dependency installation
   --yes, -y                    Accept defaults, skip all prompts