create-pracht 0.4.2 → 0.6.0

package/src/index.js

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 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";
@@ -13,18 +13,43 @@ export class ValidationError extends Error {
 }
 
 const FALLBACK_VERSION_RANGES = {
-  "@pracht/adapter-cloudflare": "^0.2.2",
-  "@pracht/adapter-node": "^0.1.11",
-  "@pracht/adapter-vercel": "^0.0.13",
-  "@pracht/cli": "^1.3.1",
-  "@pracht/core": "^0.5.0",
-  "@pracht/vite-plugin": "^0.3.2",
+  "@pracht/adapter-cloudflare": "^0.5.8",
+  "@pracht/adapter-netlify": "^0.1.0",
+  "@pracht/adapter-node": "^0.3.8",
+  "@pracht/adapter-static": "^0.1.0",
+  "@pracht/adapter-vercel": "^0.2.8",
+  "@pracht/cli": "^1.11.0",
+  "@pracht/core": "^0.14.0",
+  "@pracht/vite-plugin": "^0.9.0",
   "@tailwindcss/vite": "^4.1.0",
+  "netlify-cli": "^21.6.0",
   tailwindcss: "^4.1.0",
   typescript: "^6.0.0",
   vercel: "^56.5.0",
 };
 
+/**
+ * Cloudflare `compatibility_date` for scaffolded apps.
+ *
+ * This has to be a date the installed workerd already knows about — workerd
+ * refuses to start when asked for a date newer than the one its binary was
+ * built with ("This Worker requires compatibility date X, but the newest date
+ * supported by this server binary is Y"). Using today's date is therefore
+ * always wrong: it is, by construction, at or beyond the newest released
+ * workerd, so a freshly scaffolded app could not run `wrangler dev` on the day
+ * it was created.
+ *
+ * Keep it at or below the ceiling of the oldest wrangler this scaffold accepts
+ * (see `devDependencies.wrangler` below). That ceiling is *not* the workerd
+ * version date — it usually runs a little ahead of it — so check it rather
+ * than infer it: install that wrangler and start a worker with a candidate
+ * date; the error message names the newest date the binary supports.
+ *
+ * `packages/start/test/index.test.js` fails once this drifts too far behind, so
+ * a new app never silently opts out of years of default-on runtime behaviour.
+ */
+const WRANGLER_COMPATIBILITY_DATE = "2026-04-06";
+
 async function fetchLatestVersion(packageName) {
   const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
   if (!res.ok) {
@@ -49,6 +74,13 @@ const ADAPTERS = {
     packageName: "@pracht/adapter-cloudflare",
     short: "cf",
   },
+  netlify: {
+    description: "Netlify Functions with durable CDN caching",
+    id: "netlify",
+    label: "Netlify",
+    packageName: "@pracht/adapter-netlify",
+    short: "netlify",
+  },
   vercel: {
     description: "Vercel Edge Functions with prebuilt deploy",
     id: "vercel",
@@ -56,10 +88,21 @@ const ADAPTERS = {
     packageName: "@pracht/adapter-vercel",
     short: "vercel",
   },
+  static: {
+    description: "Pure static export — deploy dist/client to any static host",
+    id: "static",
+    label: "Static export",
+    packageName: "@pracht/adapter-static",
+    short: "static",
+  },
 };
 
 const DEFAULT_DIRECTORY = "pracht-app";
 
+function readFileSyncSafe(path) {
+  return readFileSync(path, "utf-8");
+}
+
 const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 
 // The published package bundles a copy of the repo skills (see
@@ -68,7 +111,9 @@ const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../.
 
 export async function run(argv = process.argv.slice(2)) {
   const options = parseArgs(argv);
-  const packageManager = getPackageManager();
+  const packageManagerUserAgent = process.env.npm_config_user_agent ?? "";
+  const packageManager = getPackageManager(packageManagerUserAgent);
+  const pnpmMajor = packageManager === "pnpm" ? getPnpmMajor(packageManagerUserAgent) : null;
   const log = options.json ? () => {} : console.log.bind(console);
 
   log("create-pracht");
@@ -115,14 +160,16 @@ export async function run(argv = process.argv.slice(2)) {
   await ensureTargetDirectory(targetDir);
 
   if (options.dryRun) {
-    const files = await buildProjectFiles({
+    const { files } = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
       agentTools: resolvedAgentTools,
       packageManager,
+      pnpmMajor,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
       router: resolvedRouter,
       tailwind: resolvedTailwind,
+      targetDir,
     });
 
     const fileList = Object.keys(files).sort();
@@ -150,10 +197,11 @@ export async function run(argv = process.argv.slice(2)) {
     return;
   }
 
-  await scaffoldProject({
+  const { pnpmWorkspaceNotice } = await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
     agentTools: resolvedAgentTools,
     packageManager,
+    pnpmMajor,
     router: resolvedRouter,
     tailwind: resolvedTailwind,
     targetDir,
@@ -184,14 +232,16 @@ export async function run(argv = process.argv.slice(2)) {
   }
 
   if (options.json) {
-    const files = await buildProjectFiles({
+    const { files } = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
       agentTools: resolvedAgentTools,
       packageManager,
+      pnpmMajor,
       projectName: toPackageName(basename(targetDir)),
       resolveRemoteVersions: false,
       router: resolvedRouter,
       tailwind: resolvedTailwind,
+      targetDir,
     });
 
     console.log(
@@ -202,6 +252,10 @@ export async function run(argv = process.argv.slice(2)) {
         files: Object.keys(files).sort(),
         gitInitialized,
         installed: options.skipInstall ? false : installSucceeded,
+        // The automation path has to carry this too: an instruction printed to
+        // a terminal nobody reads is an instruction nobody applies, and the
+        // consequence is a Cloudflare app with no workerd binary.
+        pnpmWorkspaceNotice,
         router: resolvedRouter,
         tailwind: resolvedTailwind,
       }),
@@ -209,10 +263,14 @@ export async function run(argv = process.argv.slice(2)) {
   } else {
     printNextSteps({
       adapter: ADAPTERS[resolvedAdapter],
+      agentTools: resolvedAgentTools,
       dir: resolvedDir,
       installSucceeded,
       packageManager,
+      pnpmWorkspaceNotice,
+      router: resolvedRouter,
       skipInstall: options.skipInstall,
+      tailwind: resolvedTailwind,
     });
   }
 }
@@ -221,30 +279,42 @@ export async function scaffoldProject({
   adapter,
   agentTools = true,
   packageManager,
+  pnpmMajor = 11,
   resolveRemoteVersions = true,
   router = "manifest",
   tailwind = false,
   targetDir,
 }) {
   const packageName = toPackageName(basename(targetDir));
-  const files = await buildProjectFiles({
+  const { files, pnpmWorkspaceNotice } = await buildProjectFiles({
     adapter,
     agentTools,
     packageManager,
+    pnpmMajor,
     projectName: packageName,
     resolveRemoteVersions,
     router,
     tailwind,
+    targetDir,
   });
 
   await mkdir(targetDir, { recursive: true });
 
+  // pnpm resolves build-script policy from the workspace root, so inside an existing
+  // monorepo our own file would be read by nobody — and `pnpm install` run from
+  // the app directory would find it first and re-root the workspace there,
+  // detaching the app from its siblings. Tell the user what to add instead.
   for (const [relativePath, content] of Object.entries(files)) {
     const filePath = resolve(targetDir, relativePath);
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, content, "utf-8");
   }
 
+  // AGENTS.md (and the CLAUDE.md alias pointing at it) are agent tooling too —
+  // `--no-agent-tools` means a project with none of it, not "all of it except
+  // the instruction files". README.md carries the same commands for humans.
+  if (!agentTools) return { pnpmWorkspaceNotice };
+
   try {
     await symlink("AGENTS.md", resolve(targetDir, "CLAUDE.md"));
   } catch (error) {
@@ -254,6 +324,8 @@ export async function scaffoldProject({
       throw error;
     }
   }
+
+  return { pnpmWorkspaceNotice };
 }
 
 export function getPackageManager(userAgent = process.env.npm_config_user_agent ?? "") {
@@ -263,6 +335,11 @@ export function getPackageManager(userAgent = process.env.npm_config_user_agent
   return "npm";
 }
 
+export function getPnpmMajor(userAgent = process.env.npm_config_user_agent ?? "") {
+  const match = /^pnpm\/(\d+)/.exec(userAgent);
+  return match ? Number(match[1]) : 11;
+}
+
 export function parseArgs(argv) {
   const options = {
     adapter: undefined,
@@ -338,7 +415,7 @@ export function parseArgs(argv) {
       const value = normalizeAdapter(arg.slice("--adapter=".length));
       if (!value) {
         throw new ValidationError(
-          `Invalid adapter: ${arg.slice("--adapter=".length)}. Use node, cf, or vercel.`,
+          `Invalid adapter: ${arg.slice("--adapter=".length)}. Use node, cf, netlify, vercel, or static.`,
         );
       }
       options.adapter = value;
@@ -392,6 +469,8 @@ async function promptForAdapter(readline) {
   console.log("  1. Node.js");
   console.log("  2. Cloudflare Workers");
   console.log("  3. Vercel");
+  console.log("  4. Netlify");
+  console.log("  5. Static export (no server)");
 
   while (true) {
     const answer = await readline.question("Adapter (1): ");
@@ -401,14 +480,18 @@ async function promptForAdapter(readline) {
       return normalized;
     }
 
-    console.log("Choose 1/2/3 or node/cf/vercel.");
+    console.log("Choose 1/2/3/4/5 or node/cf/vercel/netlify/static.");
   }
 }
 
 async function promptForRouter(readline) {
+  // The two routers are not equivalent, and the difference is invisible until
+  // you reach for a manifest-only feature. Say so at the point of choosing.
   console.log("Router:");
-  console.log("  1. Manifest (explicit routes.ts)");
-  console.log("  2. Pages (file-system routing)");
+  console.log("  1. Manifest (explicit routes.ts) — supports middleware, capabilities,");
+  console.log("     MCP, Web Bot Auth, and constraints");
+  console.log("  2. Pages (file-system routing) — pages and API routes only; no");
+  console.log("     middleware, capabilities, MCP, or agent trust (eject later to add them)");
 
   while (true) {
     const answer = await readline.question("Router (1): ");
@@ -536,6 +619,14 @@ function normalizeAdapter(value) {
     return "vercel";
   }
 
+  if (normalized === "4" || normalized === "nf" || normalized === "netlify") {
+    return "netlify";
+  }
+
+  if (normalized === "5" || normalized === "static" || normalized === "export") {
+    return "static";
+  }
+
   return null;
 }
 
@@ -558,10 +649,12 @@ async function buildProjectFiles({
   adapter,
   agentTools = true,
   packageManager,
+  pnpmMajor = 11,
   projectName,
   resolveRemoteVersions = true,
   router,
   tailwind = false,
+  targetDir,
 }) {
   const packagesToResolve = [
     "@pracht/cli",
@@ -573,36 +666,71 @@ async function buildProjectFiles({
   if (adapter.id === "vercel") {
     packagesToResolve.push("vercel");
   }
+  if (adapter.id === "netlify") {
+    packagesToResolve.push("netlify-cli");
+  }
   if (tailwind) {
     packagesToResolve.push("tailwindcss", "@tailwindcss/vite");
   }
 
   const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
+  const policyMajor = pnpmMajor ?? 11;
+  const ancestorWorkspace = targetDir ? findAncestorPnpmWorkspace(targetDir) : null;
+  const pnpmWorkspaceNotice = ancestorWorkspace
+    ? {
+        packages: pnpmBuildAllowlist(adapter, tailwind),
+        policy: pnpmBuildPolicyName(policyMajor),
+        root: ancestorWorkspace,
+      }
+    : null;
 
   const files = {
     ".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",
+      "dist\nnode_modules\n.netlify\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,
+      pnpmMajor,
+      pnpmWorkspaceNotice,
       projectName,
       router,
       tailwind,
     }),
-    "package.json": createPackageJson({ adapter, projectName, tailwind, versions }),
-    "src/api/health.ts": createHealthRoute(adapter),
+    "package.json": createPackageJson({
+      adapter,
+      projectName,
+      tailwind,
+      versions,
+    }),
     "vite.config.ts": createViteConfig(adapter, router, tailwind),
     "tsconfig.json": createBaseTSConfig(adapter),
-    "AGENTS.md": createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }),
   };
 
+  // A static export has no server, so an API route would be a hard build
+  // error — the starter must not scaffold one it cannot build.
+  if (adapter.id !== "static") {
+    files["src/api/health.ts"] = createHealthRoute(adapter);
+  }
+
+  if (agentTools) {
+    files["AGENTS.md"] = createAgentInstructions({
+      adapter,
+      agentTools,
+      packageManager,
+      router,
+      tailwind,
+    });
+  }
+
   if (router === "pages") {
     files["src/pages/_app.tsx"] = createShellFile(projectName, tailwind);
     files["src/pages/index.tsx"] = createPagesHomeRoute(adapter);
+    files["src/pages/404.tsx"] = createNotFoundRoute();
   } else {
     files["src/routes.ts"] = createRoutesFile();
     files["src/routes/home.tsx"] = createHomeRoute(adapter);
+    files["src/routes/not-found.tsx"] = createNotFoundRoute();
     files["src/shells/public.tsx"] = createShellFile(projectName, tailwind);
   }
 
@@ -615,6 +743,10 @@ async function buildProjectFiles({
     files["src/env.d.ts"] = createCloudflareEnvDeclaration();
   }
 
+  if (adapter.id === "netlify") {
+    files["netlify.toml"] = createNetlifyConfig(packageManager);
+  }
+
   if (adapter.id === "node") {
     files["Dockerfile"] = createDockerfile(packageManager);
     files[".dockerignore"] = createDockerignore();
@@ -625,7 +757,16 @@ async function buildProjectFiles({
     Object.assign(files, await readSkillFiles());
   }
 
-  return files;
+  // pnpm resolves build-script policy from the workspace root, so inside an existing
+  // workspace our own file would be read by nobody — and `pnpm install` run
+  // from the app directory would find it first and re-root the workspace there,
+  // detaching the app from its siblings. Decided here so the `--json` and
+  // `--dry-run` listings match what is actually written.
+  if (!pnpmWorkspaceNotice) {
+    files["pnpm-workspace.yaml"] = createPnpmWorkspaceConfig(adapter, tailwind, policyMajor);
+  }
+
+  return { files, pnpmWorkspaceNotice };
 }
 
 function createMcpConfig() {
@@ -634,7 +775,13 @@ function createMcpConfig() {
       mcpServers: {
         pracht: {
           command: "npx",
-          args: ["pracht", "mcp"],
+          // `--no-install` pins this to the `@pracht/cli` the project depends
+          // on. `--yes @pracht/cli` fetched the registry's latest instead, so
+          // the MCP server an agent talked to could describe a different CLI
+          // than the one the app builds with. Not bare `npx pracht` either:
+          // that resolves to a registry package literally named `pracht`
+          // whenever the local bin is missing — `--no-install` fails loudly.
+          args: ["--no-install", "pracht", "mcp"],
         },
       },
     },
@@ -674,6 +821,10 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     scripts.start = "node dist/server/server.js";
   }
 
+  if (adapter.id === "static") {
+    scripts.preview = "pracht preview";
+  }
+
   const devDependencies = {
     "@pracht/cli": versions["@pracht/cli"],
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
@@ -689,6 +840,12 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     devDependencies.wrangler = "^4.81.0";
   }
 
+  if (adapter.id === "netlify") {
+    scripts.deploy = "netlify deploy --build --prod";
+    scripts.preview = "pracht build && netlify dev";
+    devDependencies["netlify-cli"] = versions["netlify-cli"];
+  }
+
   if (adapter.id === "vercel") {
     scripts.deploy = "pracht build && vercel deploy --prebuilt";
     devDependencies.vercel = versions["vercel"];
@@ -721,7 +878,9 @@ function createViteConfig(adapter, router, tailwind) {
   const ADAPTER_IMPORTS = {
     node: { fn: "nodeAdapter", pkg: "@pracht/adapter-node" },
     cloudflare: { fn: "cloudflareAdapter", pkg: "@pracht/adapter-cloudflare" },
+    netlify: { fn: "netlifyAdapter", pkg: "@pracht/adapter-netlify" },
     vercel: { fn: "vercelAdapter", pkg: "@pracht/adapter-vercel" },
+    static: { fn: "staticAdapter", pkg: "@pracht/adapter-static" },
   };
 
   const info = ADAPTER_IMPORTS[adapter.id] ?? ADAPTER_IMPORTS.node;
@@ -761,8 +920,12 @@ 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",',
+    "  // Rendered with a 404 status when nothing matches. Not a route: it never",
+    "  // matches a URL, so it cannot shadow static assets or later pages.",
+    "  notFound: {",
+    '    component: "./routes/not-found.tsx",',
+    '    shell: "public",',
+    "  },",
     "  // Declarative invariants enforced by `pracht verify` — uncomment to use",
     "  // (add the helpers to the @pracht/core import):",
     "  // constraints: [",
@@ -815,7 +978,9 @@ function createHomeRoute(adapter) {
     "    steps: [",
     '      "Edit src/routes/home.tsx to change this page.",',
     '      "Add more routes in src/routes.ts.",',
-    '      "Add API handlers in src/api/*.ts.",',
+    adapter.id === "static"
+      ? '      "Fetch live data from the browser — a static export runs no server.",'
+      : '      "Add API handlers in src/api/*.ts.",',
     "    ],",
     "  };",
     "}",
@@ -834,8 +999,37 @@ function createHomeRoute(adapter) {
     "        ))}",
     "      </ul>",
     '      <p style={{ marginTop: "24px" }}>',
-    "        Check <code>/api/health</code> for a simple API route.",
+    adapter.id === "static"
+      ? "        Run <code>pracht build</code>, then deploy <code>dist/client</code> anywhere."
+      : "        Check <code>/api/health</code> for a simple API route.",
+    "      </p>",
+    "    </section>",
+    "  );",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function createNotFoundRoute() {
+  return [
+    "export function head() {",
+    "  return {",
+    '    title: "Page not found",',
+    '    meta: [{ content: "noindex", name: "robots" }],',
+    "  };",
+    "}",
+    "",
+    "export function Component() {",
+    "  return (",
+    "    <section>",
+    '      <p style={{ color: "#555", marginBottom: "8px" }}>404</p>',
+    '      <h1 style={{ fontSize: "2.5rem", lineHeight: 1.1, margin: "0 0 16px" }}>Page not found.</h1>',
+    '      <p style={{ fontSize: "1.1rem", lineHeight: 1.6, marginBottom: "24px" }}>',
+    "        The page you asked for does not exist. It may have moved, or the link may be wrong.",
     "      </p>",
+    "      {/* A plain anchor keeps this page independent of the route table.",
+    "          Use a typed <Link> once you want client-side navigation. */}",
+    '      <a href="/">Back to home</a>',
     "    </section>",
     "  );",
     "}",
@@ -855,7 +1049,9 @@ function createPagesHomeRoute(adapter) {
     "    steps: [",
     '      "Edit src/pages/index.tsx to change this page.",',
     '      "Add more pages in src/pages/.",',
-    '      "Add API handlers in src/api/*.ts.",',
+    adapter.id === "static"
+      ? '      "Fetch live data from the browser — a static export runs no server.",'
+      : '      "Add API handlers in src/api/*.ts.",',
     "    ],",
     "  };",
     "}",
@@ -874,7 +1070,9 @@ function createPagesHomeRoute(adapter) {
     "        ))}",
     "      </ul>",
     '      <p style={{ marginTop: "24px" }}>',
-    "        Check <code>/api/health</code> for a simple API route.",
+    adapter.id === "static"
+      ? "        Run <code>pracht build</code>, then deploy <code>dist/client</code> anywhere."
+      : "        Check <code>/api/health</code> for a simple API route.",
     "      </p>",
     "    </section>",
     "  );",
@@ -916,18 +1114,200 @@ function createHealthRoute(adapter) {
   ].join("\n");
 }
 
+/**
+ * pnpm blocks dependency install scripts unless they are allowlisted, and
+ * esbuild and workerd both need theirs — workerd's postinstall downloads the
+ * runtime binary, so without this `wrangler dev` fails right after scaffolding
+ * with `ERR_PNPM_IGNORED_BUILDS`.
+ *
+ * This has to live in `pnpm-workspace.yaml`: pnpm 10 uses
+ * `onlyBuiltDependencies`, while pnpm 11 uses `allowBuilds` and no longer reads
+ * the `pnpm` field in package.json. npm and yarn ignore this file entirely, so
+ * it is inert for them. (npm has its own `allow-scripts` prompt, which it
+ * drives interactively.)
+ */
+function pnpmBuildAllowlist(adapter, tailwind) {
+  const packages = ["esbuild"];
+  if (adapter.id === "cloudflare") packages.push("workerd");
+  if (tailwind) packages.push("@tailwindcss/oxide");
+  return packages.sort();
+}
+
+function pnpmBuildPolicyName(pnpmMajor) {
+  return pnpmMajor <= 10 ? "onlyBuiltDependencies" : "allowBuilds";
+}
+
+function createPnpmWorkspaceConfig(adapter, tailwind, pnpmMajor) {
+  const policy = pnpmBuildPolicyName(pnpmMajor);
+  const entries = pnpmBuildAllowlist(adapter, tailwind);
+
+  return [
+    "packages:",
+    '  - "."',
+    `${policy}:`,
+    ...(policy === "onlyBuiltDependencies"
+      ? entries.map((name) => `  - ${JSON.stringify(name)}`)
+      : entries.map((name) => `  ${JSON.stringify(name)}: true`)),
+    "",
+  ].join("\n");
+}
+
+/**
+ * Nearest ancestor `pnpm-workspace.yaml` above `dir`, or null.
+ *
+ * pnpm resolves settings from the workspace *root*, so writing our own file
+ * inside an existing monorepo would be read by nobody — while also re-rooting
+ * the workspace for anyone who runs `pnpm install` from the app directory,
+ * which detaches it from its siblings.
+ */
+function findAncestorPnpmWorkspace(dir) {
+  let current = resolve(dir, "..");
+  for (;;) {
+    const configPath = resolve(current, "pnpm-workspace.yaml");
+    // An ancestor config only governs this app if its `packages:` globs cover
+    // it. Suppressing our own file for a workspace the app is *not* a member of
+    // leaves it with no install at all: pnpm re-roots to the ancestor and
+    // installs that workspace's projects instead.
+    if (existsSync(configPath) && workspaceCovers(configPath, current, dir)) return current;
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Whether `dir` matches one of the `packages:` globs in a pnpm workspace
+ * config. A deliberately small YAML reader: the block and flow list forms pnpm
+ * accepts, and `*` / `**` globs.
+ *
+ * Both failure directions matter, and they are not symmetric. Deciding "not a
+ * member" for a directory that *is* one writes a nested `pnpm-workspace.yaml`
+ * that re-roots the workspace at the app; deciding "member" for one that is
+ * not only prints instructions. So anything this reader cannot confidently
+ * decide answers `true`.
+ */
+function workspaceCovers(configPath, workspaceRoot, dir) {
+  let contents;
+  try {
+    contents = readFileSyncSafe(configPath);
+  } catch {
+    return true;
+  }
+
+  const globs = [];
+  let sawPackagesKey = false;
+  let inBlockList = false;
+
+  for (const rawLine of contents.split("\n")) {
+    const line = rawLine.replace(/#.*$/, "");
+    const packagesKey = line.match(/^packages\s*:(.*)$/);
+    if (packagesKey) {
+      sawPackagesKey = true;
+      // Flow form: `packages: ["apps/*", "tools/*"]`, which pnpm accepts.
+      const flow = packagesKey[1].trim();
+      if (flow.startsWith("[")) {
+        for (const entry of flow.replace(/^\[|\]$/g, "").split(",")) {
+          const value = entry.trim().replace(/^["']|["']$/g, "");
+          if (value) globs.push(value);
+        }
+        inBlockList = false;
+      } else {
+        inBlockList = true;
+      }
+      continue;
+    }
+    if (inBlockList) {
+      const item = line.match(/^\s+-\s*["']?([^"'\s]+)["']?\s*$/);
+      if (item) {
+        globs.push(item[1]);
+        continue;
+      }
+      if (line.trim() !== "") inBlockList = false;
+    }
+  }
+
+  // No `packages:` key at all is a single-package workspace rooted there,
+  // which does not cover a nested app. A key we could not read is a decision
+  // we cannot make — fall to "member".
+  if (!sawPackagesKey) return false;
+  if (globs.length === 0) return true;
+
+  const relative = resolve(dir)
+    .slice(resolve(workspaceRoot).length + 1)
+    .split(/[\\/]/);
+  // A negation (`!apps/legacy`) narrows the set; treat its presence as
+  // undecidable rather than as an ordinary glob.
+  if (globs.some((glob) => glob.startsWith("!"))) return true;
+  // pnpm treats a workspace-root-relative `./apps/*` the same as `apps/*`.
+  // Strip only that harmless prefix before comparing path segments.
+  const normalizedGlobs = globs.map((glob) => glob.replace(/^(?:\.\/)+/, ""));
+  // pnpm accepts the wider glob syntax supported by its workspace matcher.
+  // This intentionally small matcher cannot safely decide braces, character
+  // classes, extglobs, or single-character wildcards. Follow the conservative
+  // contract above instead of creating a nested workspace for a real member.
+  if (normalizedGlobs.some((glob) => /[?[\]{}()]/.test(glob))) return true;
+  return normalizedGlobs.some((glob) => matchesGlobSegments(glob.split("/"), relative));
+}
+
+/**
+ * Segment-wise glob match. `**` matches the rest; otherwise a segment may
+ * contain `*` wildcards (`app-*`), which pnpm supports.
+ */
+function matchesGlobSegments(globSegments, pathSegments) {
+  return matchGlobSegmentAt(globSegments, pathSegments, 0, 0);
+}
+
+function matchGlobSegmentAt(globSegments, pathSegments, globIndex, pathIndex) {
+  if (globIndex === globSegments.length) return pathIndex === pathSegments.length;
+
+  const segment = globSegments[globIndex];
+  if (segment === "**") {
+    if (globIndex === globSegments.length - 1) return true;
+    for (let nextPathIndex = pathIndex; nextPathIndex <= pathSegments.length; nextPathIndex += 1) {
+      if (matchGlobSegmentAt(globSegments, pathSegments, globIndex + 1, nextPathIndex)) return true;
+    }
+    return false;
+  }
+
+  return (
+    pathIndex < pathSegments.length &&
+    segmentMatches(segment, pathSegments[pathIndex]) &&
+    matchGlobSegmentAt(globSegments, pathSegments, globIndex + 1, pathIndex + 1)
+  );
+}
+
+function segmentMatches(glob, value) {
+  if (glob === "*") return true;
+  if (!glob.includes("*")) return glob === value;
+  const pattern = glob
+    .split("*")
+    .map((part) => part.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"))
+    .join(".*");
+  return new RegExp(`^${pattern}$`).test(value);
+}
+
 function createWranglerConfig(projectName) {
-  const compatibilityDate = new Date().toISOString().slice(0, 10);
+  const compatibilityDate = WRANGLER_COMPATIBILITY_DATE;
 
   return [
     "{",
     '  "$schema": "node_modules/wrangler/config-schema.json",',
     `  "name": ${JSON.stringify(projectName)},`,
-    '  "main": "dist/server/server.js",',
+    // `pracht build` writes this thin wrapper next to server.js. It re-exports
+    // only the default handler and any Worker entrypoint classes: workerd
+    // validates every named export of the deployed entry module and rejects the
+    // build metadata (buildTarget, manifests, ...) server.js also exports.
+    '  "main": "dist/server/worker.js",',
     `  "compatibility_date": ${JSON.stringify(compatibilityDate)},`,
     '  "assets": {',
     '    "binding": "ASSETS",',
     '    "directory": "dist/client",',
+    // The assets binding defaults to redirecting a prerendered route to its
+    // trailing-slash form, so `GET /about` would answer 307 on Cloudflare
+    // where Node and Vercel answer 200 — for the same app, and for every URL
+    // the generated llms.txt advertises. Drop the slash instead so one
+    // canonical form works across adapters.
+    '    "html_handling": "drop-trailing-slash",',
     '    "run_worker_first": true',
     "  }",
     "}",
@@ -935,6 +1315,23 @@ function createWranglerConfig(projectName) {
   ].join("\n");
 }
 
+function createNetlifyConfig(packageManager) {
+  const buildCommand =
+    packageManager === "npm" || packageManager === "bun"
+      ? `${packageManager} run build`
+      : `${packageManager} build`;
+
+  return [
+    "[build]",
+    `  command = ${JSON.stringify(buildCommand)}`,
+    '  publish = "dist/client"',
+    "",
+    "[functions]",
+    '  directory = "netlify/functions"',
+    "",
+  ].join("\n");
+}
+
 function createCloudflareEnvDeclaration() {
   return [
     'import "@pracht/core";',
@@ -1023,8 +1420,17 @@ function createDockerignore() {
   ].join("\n");
 }
 
+const PAGES_ROUTER_LIMITATIONS =
+  "**The pages router has no manifest**, so these manifest-only features are unavailable: named shells (there is one, `_app.tsx`), route middleware, capabilities (and therefore capability HTTP endpoints, WebMCP, remote MCP, and `pracht eval`), `defineApp({ constraints })`, and `agents`. If the app needs auth policy or a runtime agent surface, eject with `generateRoutesFile` from `@pracht/vite-plugin/pages-router`, remove `pagesDir`, and customize the generated manifest.";
+
+const PAGES_ROUTER_ISG_POLICY =
+  'Pages-router ISG supports time revalidation only: pair `export const RENDER_MODE = "isg"` with a positive integer such as `export const REVALIDATE = 3600`. Missing or misplaced policies fail `pracht build`, `doctor`, and `verify`. Webhook revalidation and combined policies require an explicit manifest.';
+
 function createAgentInstructions({ adapter, agentTools, packageManager, router, tailwind }) {
-  const runCmd = packageManager === "npm" ? "npm run" : packageManager;
+  // `bun build` is Bun's own bundler and shadows the package script, so bun
+  // needs the explicit `run` form the same way npm does.
+  const runCmd =
+    packageManager === "npm" || packageManager === "bun" ? `${packageManager} run` : packageManager;
 
   const lines = [
     "# Pracht App",
@@ -1035,7 +1441,12 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     `- \`${runCmd} build\` — production build`,
   ];
 
-  if (adapter.id === "node" || adapter.id === "cloudflare") {
+  if (
+    adapter.id === "node" ||
+    adapter.id === "cloudflare" ||
+    adapter.id === "netlify" ||
+    adapter.id === "static"
+  ) {
     lines.push(`- \`${runCmd} preview\` — build and serve the production build locally`);
   }
 
@@ -1043,7 +1454,7 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push(`- \`${runCmd} start\` — run the built server`);
   }
 
-  if (adapter.id === "cloudflare" || adapter.id === "vercel") {
+  if (adapter.id === "cloudflare" || adapter.id === "netlify" || adapter.id === "vercel") {
     lines.push(`- \`${runCmd} deploy\` — build and deploy`);
   }
 
@@ -1053,9 +1464,20 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   lines.push("Use the CLI to generate new files:");
   lines.push("");
   lines.push("- `pracht generate route --path /about` — add a route");
-  lines.push("- `pracht generate shell --name app` — add a shell");
-  lines.push("- `pracht generate middleware --name auth` — add middleware");
-  lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
+  if (router !== "pages") {
+    lines.push("- `pracht generate shell --name app` — add a shell");
+    if (adapter.id !== "static") {
+      lines.push("- `pracht generate middleware --name auth` — add middleware");
+    }
+  }
+  if (adapter.id !== "static") {
+    lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
+  }
+  if (router !== "pages" && adapter.id !== "static") {
+    lines.push(
+      "- `pracht generate capability --name notes.search --effect read --expose http` — add a capability (agent-callable operation)",
+    );
+  }
   lines.push("- `pracht doctor` — check project health");
   lines.push("- `pracht verify` — enforce route and constraint invariants");
   lines.push(
@@ -1073,15 +1495,27 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("");
     lines.push("- `src/pages/` — file-system routes (each file becomes a route)");
     lines.push("- `src/pages/_app.tsx` — app shell (layout and head)");
+    lines.push(
+      "- `src/pages/404.tsx` — not-found page, wired automatically (never a URL of its own)",
+    );
+    lines.push("");
+    lines.push(PAGES_ROUTER_LIMITATIONS);
+    lines.push("");
+    lines.push(PAGES_ROUTER_ISG_POLICY);
   } else {
     lines.push("This app uses **manifest routing**.");
     lines.push("");
     lines.push("- `src/routes.ts` — route manifest (defines all routes and shells)");
     lines.push("- `src/routes/` — route components and loaders");
+    lines.push(
+      "- `src/routes/not-found.tsx` — not-found page, wired via `notFound` in the manifest",
+    );
     lines.push("- `src/shells/` — shell components (layouts)");
   }
 
-  lines.push("- `src/api/` — API route handlers");
+  if (adapter.id !== "static") {
+    lines.push("- `src/api/` — API route handlers");
+  }
   lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
 
   if (tailwind) {
@@ -1097,6 +1531,10 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("- `src/env.d.ts` — TypeScript types for Cloudflare bindings");
   }
 
+  if (adapter.id === "netlify") {
+    lines.push("- `netlify.toml` — Netlify build, publish, and functions configuration");
+  }
+
   if (agentTools) {
     lines.push("");
     lines.push("## Agent tooling");
@@ -1114,9 +1552,24 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   return lines.join("\n");
 }
 
-function createReadme({ adapter, agentTools, packageManager, projectName, router, tailwind }) {
+function createReadme({
+  adapter,
+  agentTools,
+  packageManager,
+  pnpmMajor,
+  pnpmWorkspaceNotice,
+  projectName,
+  router,
+  tailwind,
+}) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
+  // `bun build` is Bun's own bundler and shadows the package script, unlike
+  // `bun dev` / `bun start` / `bun preview`, which fall through to it.
+  const buildCommand =
+    packageManager === "npm" || packageManager === "bun"
+      ? `${packageManager} run build`
+      : `${packageManager} build`;
   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`;
@@ -1132,6 +1585,7 @@ function createReadme({ adapter, agentTools, packageManager, projectName, router
     "",
     `- \`${installCommand}\``,
     `- \`${devCommand}\``,
+    `- \`${buildCommand}\``,
     `- \`${typecheckCommand}\``,
   ];
 
@@ -1149,12 +1603,36 @@ function createReadme({ adapter, agentTools, packageManager, projectName, router
     );
   }
 
+  if (adapter.id === "netlify") {
+    lines.push(`- \`${previewCommand}\``);
+    lines.push(`- \`${deployCommand}\``);
+    lines.push("");
+    lines.push(
+      "`netlify.toml` publishes `dist/client` and discovers the Pracht function generated during the build.",
+    );
+  }
+
   if (adapter.id === "vercel") {
     lines.push(`- \`${deployCommand}\``);
     lines.push("");
     lines.push("Run the deploy command after linking or logging into your Vercel account.");
   }
 
+  if (adapter.id === "static") {
+    lines.push(`- \`${previewCommand}\``);
+    lines.push("");
+    lines.push(
+      "`pracht build` writes the whole site to `dist/client`. Upload that directory to any " +
+        "static host — there is no server to run. Configure the host to serve `index.html` " +
+        "for directory URLs and to use `404.html` as its error document.",
+    );
+    lines.push("");
+    lines.push(
+      "A static export runs no server, so API routes, middleware, and `ssr`/`isg` routes are " +
+        "build errors. Fetch live data from the browser instead, or switch to a serverful adapter.",
+    );
+  }
+
   lines.push("");
   lines.push("## Files");
   lines.push("");
@@ -1163,12 +1641,32 @@ function createReadme({ adapter, agentTools, packageManager, projectName, router
     lines.push("- `src/pages/` contains your file-system routes.");
     lines.push("- `src/pages/_app.tsx` is the app shell.");
     lines.push("- `src/pages/index.tsx` is the home page.");
+    lines.push("- `src/pages/404.tsx` is the not-found page; pracht wires it automatically.");
+    lines.push("");
+    lines.push("## Pages-router boundaries");
+    lines.push("");
+    lines.push(PAGES_ROUTER_LIMITATIONS);
+    lines.push("");
+    lines.push(PAGES_ROUTER_ISG_POLICY);
   } else {
     lines.push("- `src/routes.ts` defines your app manifest.");
     lines.push("- `src/routes/home.tsx` is the first page.");
+    lines.push("- `src/routes/not-found.tsx` is the not-found page, wired via `notFound`.");
   }
 
-  lines.push("- `src/api/health.ts` is a sample API route.");
+  if (adapter.id !== "static") {
+    lines.push("- `src/api/health.ts` is a sample API route.");
+  }
+
+  if (packageManager === "pnpm") {
+    lines.push(
+      pnpmWorkspaceNotice
+        ? `- The containing pnpm workspace owns build-script policy. Add the listed dependencies to its \`${pnpmWorkspaceNotice.policy}\` block; no nested \`pnpm-workspace.yaml\` is generated.`
+        : pnpmMajor <= 10
+          ? "- `pnpm-workspace.yaml#onlyBuiltDependencies` allows only the dependency build scripts required by this starter."
+          : "- `pnpm-workspace.yaml#allowBuilds` allows only the dependency build scripts required by this starter.",
+    );
+  }
 
   if (tailwind) {
     lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
@@ -1281,13 +1779,36 @@ async function installDependencies(targetDir, packageManager) {
   });
 }
 
-function printNextSteps({ adapter, dir, installSucceeded, packageManager, skipInstall }) {
+function printNextSteps({
+  adapter,
+  agentTools,
+  dir,
+  installSucceeded,
+  packageManager,
+  pnpmWorkspaceNotice,
+  router,
+  skipInstall,
+  tailwind,
+}) {
   const installCommand = packageManager === "npm" ? "npm install" : `${packageManager} install`;
   const devCommand = packageManager === "npm" ? "npm run dev" : `${packageManager} dev`;
 
   console.log("");
   console.log(`Created a pracht app in ${dir}.`);
   console.log(`Adapter: ${adapter.label}`);
+  console.log(
+    `Router:  ${router === "pages" ? "pages (file-system)" : "manifest (src/routes.ts)"}`,
+  );
+  console.log(`Tailwind: ${tailwind ? "yes" : "no"}`);
+  console.log(`Agent tooling: ${agentTools ? "skills, .mcp.json, AGENTS.md" : "none"}`);
+  if (router === "pages") {
+    console.log("");
+    console.log(
+      "Note: the pages router has no manifest, so middleware, capabilities, constraints, and\n" +
+        "the agent surface (capability endpoints, WebMCP, remote MCP, `pracht eval`) are not\n" +
+        "available. Scaffold with --router=manifest if you need them.",
+    );
+  }
   console.log("");
   console.log("Next steps:");
   console.log(`  cd ${dir}`);
@@ -1302,6 +1823,24 @@ function printNextSteps({ adapter, dir, installSucceeded, packageManager, skipIn
     console.log("");
     console.log("Dependency installation did not complete. The project files were still created.");
   }
+
+  if (pnpmWorkspaceNotice) {
+    console.log("");
+    console.log(
+      `This app is inside the pnpm workspace at ${pnpmWorkspaceNotice.root}, which owns build\n` +
+        "permissions for every package. Add the following to its pnpm-workspace.yaml, or\n" +
+        "the starter's required dependency install scripts will not run:",
+    );
+    console.log("");
+    console.log(`  ${pnpmWorkspaceNotice.policy}:`);
+    for (const name of pnpmWorkspaceNotice.packages) {
+      console.log(
+        pnpmWorkspaceNotice.policy === "onlyBuiltDependencies"
+          ? `    - ${JSON.stringify(name)}`
+          : `    ${JSON.stringify(name)}: true`,
+      );
+    }
+  }
 }
 
 function printHelp() {
@@ -1311,10 +1850,12 @@ Usage:
   create-pracht [directory] [options]
 
 Options:
-  --adapter=node|cf|vercel     Choose hosting adapter (default: node)
+  --adapter=node|cf|netlify|vercel|static
+                               Choose hosting adapter (default: node)
   --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)
+  --tailwind / --no-tailwind   Enable or disable Tailwind CSS wiring (default: prompt).
+                               Sets the same thing as --template; the last one wins.
   --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