create-pracht 0.6.2 → 0.7.0

package/src/index.js

@@ -109,6 +109,31 @@ const PACKAGE_ROOT = fileURLToPath(new URL("..", import.meta.url));
 // scripts/sync-skills.js); inside the monorepo we fall back to the source.
 const SKILL_DIRS = [resolve(PACKAGE_ROOT, "skills"), resolve(PACKAGE_ROOT, "../../skills")];
 
+/**
+ * The skills a brand-new app can actually use, seeded by default.
+ *
+ * The full catalog is ~33 SKILL.md files, about 360 KB, against a starter with
+ * eight source files. Every `description` is in the agent's system prompt for
+ * every session whether the skill runs or not, so seeding all of them spends
+ * the app's context budget on audits that have nothing to audit yet and on
+ * additive scaffolds for decisions the author has not made.
+ *
+ * These five cover the lifecycle of the app as scaffolded — write it, fix it,
+ * ship it, keep it current — plus the one thing pracht does that an agent will
+ * not infer from any other framework it knows. Everything else is one
+ * `pracht skills add <name>` away, and the generated README and AGENTS.md say
+ * so.
+ */
+const CORE_SKILLS = [
+  "pracht-scaffold",
+  "pracht-debug",
+  "pracht-deploy",
+  "upgrade-pracht",
+  "add-capabilities",
+];
+
+const SKILL_CATALOG_URL = "https://pracht.resynapse.dev/.well-known/agent-skills/index.json";
+
 export async function run(argv = process.argv.slice(2)) {
   const options = parseArgs(argv);
   const packageManagerUserAgent = process.env.npm_config_user_agent ?? "";
@@ -125,6 +150,7 @@ export async function run(argv = process.argv.slice(2)) {
   const router = options.router ?? (options.yes ? "manifest" : null);
   const tailwind = options.tailwind ?? (options.yes ? false : null);
   const agentTools = options.agentTools ?? (options.yes ? true : null);
+  const agentSkills = options.agentSkills ?? "core";
 
   let resolvedDir = dir;
   let resolvedAdapter = adapterId;
@@ -162,6 +188,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (options.dryRun) {
     const { files } = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentSkills,
       agentTools: resolvedAgentTools,
       packageManager,
       pnpmMajor,
@@ -178,6 +205,7 @@ export async function run(argv = process.argv.slice(2)) {
       console.log(
         JSON.stringify({
           adapter: resolvedAdapter,
+          agentSkills: resolvedAgentTools ? agentSkills : null,
           agentTools: resolvedAgentTools,
           directory: resolvedDir,
           dryRun: true,
@@ -199,6 +227,7 @@ export async function run(argv = process.argv.slice(2)) {
 
   const { pnpmWorkspaceNotice } = await scaffoldProject({
     adapter: ADAPTERS[resolvedAdapter],
+    agentSkills,
     agentTools: resolvedAgentTools,
     packageManager,
     pnpmMajor,
@@ -234,6 +263,7 @@ export async function run(argv = process.argv.slice(2)) {
   if (options.json) {
     const { files } = await buildProjectFiles({
       adapter: ADAPTERS[resolvedAdapter],
+      agentSkills,
       agentTools: resolvedAgentTools,
       packageManager,
       pnpmMajor,
@@ -247,6 +277,7 @@ export async function run(argv = process.argv.slice(2)) {
     console.log(
       JSON.stringify({
         adapter: resolvedAdapter,
+        agentSkills: resolvedAgentTools ? agentSkills : null,
         agentTools: resolvedAgentTools,
         directory: resolvedDir,
         files: Object.keys(files).sort(),
@@ -263,6 +294,7 @@ export async function run(argv = process.argv.slice(2)) {
   } else {
     printNextSteps({
       adapter: ADAPTERS[resolvedAdapter],
+      agentSkills,
       agentTools: resolvedAgentTools,
       dir: resolvedDir,
       installSucceeded,
@@ -277,6 +309,7 @@ export async function run(argv = process.argv.slice(2)) {
 
 export async function scaffoldProject({
   adapter,
+  agentSkills = "core",
   agentTools = true,
   packageManager,
   pnpmMajor = 11,
@@ -288,6 +321,7 @@ export async function scaffoldProject({
   const packageName = toPackageName(basename(targetDir));
   const { files, pnpmWorkspaceNotice } = await buildProjectFiles({
     adapter,
+    agentSkills,
     agentTools,
     packageManager,
     pnpmMajor,
@@ -343,6 +377,7 @@ export function getPnpmMajor(userAgent = process.env.npm_config_user_agent ?? ""
 export function parseArgs(argv) {
   const options = {
     adapter: undefined,
+    agentSkills: undefined,
     agentTools: undefined,
     dir: undefined,
     dryRun: false,
@@ -380,6 +415,16 @@ export function parseArgs(argv) {
       continue;
     }
 
+    if (arg.startsWith("--agent-tools=")) {
+      const value = arg.slice("--agent-tools=".length).toLowerCase();
+      if (value !== "core" && value !== "full") {
+        throw new ValidationError(`Invalid --agent-tools value: ${value}. Use core or full.`);
+      }
+      options.agentTools = true;
+      options.agentSkills = value;
+      continue;
+    }
+
     if (arg === "--no-agent-tools") {
       options.agentTools = false;
       continue;
@@ -488,10 +533,11 @@ 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) — 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)");
+  console.log("  1. Manifest (explicit routes.ts) — per-route middleware and shells,");
+  console.log("     path-prefix groups, explicit route ids");
+  console.log("  2. Pages (file-system routing) — routes, `_app.tsx` shells, one root");
+  console.log("     _middleware.ts, src/capabilities/, and _app.config.ts for agents");
+  console.log("     and constraints; no per-route middleware or shell overrides");
 
   while (true) {
     const answer = await readline.question("Router (1): ");
@@ -647,6 +693,7 @@ async function resolveVersions(packageNames, { remote = true } = {}) {
 
 async function buildProjectFiles({
   adapter,
+  agentSkills = "core",
   agentTools = true,
   packageManager,
   pnpmMajor = 11,
@@ -675,7 +722,8 @@ async function buildProjectFiles({
 
   const versions = await resolveVersions(packagesToResolve, { remote: resolveRemoteVersions });
   const policyMajor = pnpmMajor ?? 11;
-  const ancestorWorkspace = targetDir ? findAncestorPnpmWorkspace(targetDir) : null;
+  const ancestorWorkspace =
+    targetDir && packageManager === "pnpm" ? findAncestorPnpmWorkspace(targetDir) : null;
   const pnpmWorkspaceNotice = ancestorWorkspace
     ? {
         packages: pnpmBuildAllowlist(adapter, tailwind),
@@ -689,6 +737,7 @@ async function buildProjectFiles({
       "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,
+      agentSkills,
       agentTools,
       packageManager,
       pnpmMajor,
@@ -716,6 +765,7 @@ async function buildProjectFiles({
   if (agentTools) {
     files["AGENTS.md"] = createAgentInstructions({
       adapter,
+      agentSkills,
       agentTools,
       packageManager,
       router,
@@ -754,15 +804,19 @@ async function buildProjectFiles({
 
   if (agentTools) {
     files[".mcp.json"] = createMcpConfig();
-    Object.assign(files, await readSkillFiles());
-  }
-
-  // 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) {
+    Object.assign(files, await readSkillFiles(agentSkills));
+  }
+
+  // Only pnpm reads this file; npm, yarn, and bun ignore it entirely, so
+  // emitting it for them leaves a config in the repo that nothing in the repo
+  // obeys and that a reader has to look up to dismiss.
+  //
+  // pnpm itself 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 (packageManager === "pnpm" && !pnpmWorkspaceNotice) {
     files["pnpm-workspace.yaml"] = createPnpmWorkspaceConfig(adapter, tailwind, policyMajor);
   }
 
@@ -781,7 +835,7 @@ function createMcpConfig() {
           // 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"],
+          args: ["--no-install", "pracht", "dev-mcp"],
         },
       },
     },
@@ -790,15 +844,19 @@ function createMcpConfig() {
   )}\n`;
 }
 
-async function readSkillFiles() {
+async function readSkillFiles(scope = "core") {
   const skillsDir = SKILL_DIRS.find((dir) => existsSync(dir));
 
   if (!skillsDir) {
     return {};
   }
 
+  const wanted = scope === "full" ? null : new Set(CORE_SKILLS);
   const files = {};
   for (const name of await readdir(skillsDir)) {
+    if (wanted && !wanted.has(name)) {
+      continue;
+    }
     const skillFile = resolve(skillsDir, name, "SKILL.md");
     if (!existsSync(skillFile)) {
       continue;
@@ -856,18 +914,20 @@ function createPackageJson({ adapter, projectName, tailwind, versions }) {
     devDependencies.tailwindcss = versions["tailwindcss"];
   }
 
+  // Conventional key order, not alphabetical: `name` belongs at the top of a
+  // package.json, not between devDependencies and private.
   return `${JSON.stringify(
     {
+      name: projectName,
+      version: "0.0.0",
+      private: true,
+      type: "module",
+      scripts,
       dependencies: {
         [adapter.packageName]: versions[adapter.packageName],
         "@pracht/core": versions["@pracht/core"],
       },
       devDependencies,
-      name: projectName,
-      private: true,
-      scripts,
-      type: "module",
-      version: "0.0.0",
     },
     null,
     2,
@@ -1082,23 +1142,26 @@ function createPagesHomeRoute(adapter) {
 }
 
 function createBaseTSConfig(_adapter) {
+  // Two-space and trailing-newline like every other generated file, and grouped
+  // the way tsconfig documentation presents these options rather than
+  // alphabetically.
   const config = {
     compilerOptions: {
-      allowImportingTsExtensions: true,
-      jsx: "react-jsx",
-      jsxImportSource: "preact",
+      target: "ES2022",
       lib: ["ES2022", "DOM", "DOM.Iterable"],
       module: "ESNext",
       moduleResolution: "Bundler",
-      noEmit: true,
-      skipLibCheck: true,
-      strict: true,
-      target: "ES2022",
-      types: ["vite/client"],
+      jsx: "react-jsx",
+      jsxImportSource: "preact",
+      types: ["vite/client", "@pracht/vite-plugin/virtual"],
+      allowImportingTsExtensions: true,
       verbatimModuleSyntax: true,
+      strict: true,
+      skipLibCheck: true,
+      noEmit: true,
     },
   };
-  return JSON.stringify(config, null, 4);
+  return `${JSON.stringify(config, null, 2)}\n`;
 }
 
 function createHealthRoute(adapter) {
@@ -1426,16 +1489,26 @@ function createDockerignore() {
 }
 
 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.";
+  "**The pages router has no manifest.** Everything a manifest registers by name is registered by file instead: an `_app.tsx` per directory (the nearest one wraps that subtree), one root `_middleware.ts` applied to every page route, every module in `src/capabilities/`, and `agents` / `constraints` as named exports of `src/pages/_app.config.ts`. A `pages/404.tsx` file supplies the not-found page. Capability HTTP endpoints, WebMCP, remote MCP, typed clients, and `pracht eval` all work. What still needs a manifest: per-route middleware assignment, per-route shell overrides, `group({ pathPrefix })`, explicit route ids, and webhook ISG policies. Pure static exports have no request runtime, so `_middleware.ts` and capability endpoints do not apply there. To move over, 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 }) {
+function createAgentInstructions({
+  adapter,
+  agentSkills = "core",
+  agentTools,
+  packageManager,
+  router,
+  tailwind,
+}) {
   // `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;
+  // `pnpm deploy` is pnpm's own workspace-deploy command and shadows the
+  // package script, so this one script needs `run` for pnpm too.
+  const deployCmd = packageManager === "pnpm" ? "pnpm run" : runCmd;
   // The pages router derives route ids from filenames, so the home page of a
   // pages app is `index` (`src/pages/index.tsx`); the manifest scaffold names
   // it `home` explicitly. Every id in the instructions below has to be one the
@@ -1466,7 +1539,7 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
   }
 
   if (adapter.id === "cloudflare" || adapter.id === "netlify" || adapter.id === "vercel") {
-    lines.push(`- \`${runCmd} deploy\` — build and deploy`);
+    lines.push(`- \`${deployCmd} deploy\` — build and deploy`);
   }
 
   lines.push("");
@@ -1480,6 +1553,10 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     if (adapter.id !== "static") {
       lines.push("- `pracht generate middleware --name auth` — add middleware");
     }
+  } else if (adapter.id !== "static") {
+    lines.push(
+      "- `pracht generate middleware --name _middleware` — add root middleware for every page route",
+    );
   }
   if (adapter.id !== "static") {
     lines.push("- `pracht generate api --path /health --methods GET` — add an API route");
@@ -1505,7 +1582,8 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("This app uses **pages routing** (file-system based).");
     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/_app.tsx` — app shell (layout and head); an `_app.tsx` in a");
+    lines.push("  subdirectory replaces it for that subtree");
     lines.push(
       "- `src/pages/404.tsx` — not-found page, wired automatically (never a URL of its own)",
     );
@@ -1566,10 +1644,19 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
     lines.push("## Agent tooling");
     lines.push("");
     lines.push(
-      "- `.claude/skills/` — pracht Claude Code skills (audits, scaffolds, testing, debugging); invoke with `/<skill-name>`",
+      agentSkills === "full"
+        ? "- `.claude/skills/` — the full pracht skill catalog (audits, scaffolds, testing, debugging); invoke with `/<skill-name>`"
+        : `- \`.claude/skills/\` — the ${CORE_SKILLS.length} core pracht skills (${CORE_SKILLS.join(", ")}); invoke with \`/<skill-name>\``,
     );
+    if (agentSkills !== "full") {
+      lines.push(
+        "- More skills — audits, testing scaffolds, and the `add-*` integrations — are published at " +
+          `${SKILL_CATALOG_URL}. Run \`pracht skills list\` to see the catalog and ` +
+          "`pracht skills add <name...>` to install one; do not hand-write a SKILL.md that already exists there.",
+      );
+    }
     lines.push(
-      "- `.mcp.json` — registers the `pracht mcp` server so MCP clients can inspect the app graph, run doctor/verify, and scaffold natively",
+      "- `.mcp.json` — registers the `pracht dev-mcp` server so MCP clients can inspect the app graph, run doctor/verify, and scaffold natively",
     );
   }
 
@@ -1580,6 +1667,7 @@ function createAgentInstructions({ adapter, agentTools, packageManager, router,
 
 function createReadme({
   adapter,
+  agentSkills = "core",
   agentTools,
   packageManager,
   pnpmMajor,
@@ -1598,7 +1686,13 @@ function createReadme({
       : `${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`;
+  // `pnpm deploy` is pnpm's own workspace-deploy command and shadows the
+  // package script exactly the way `bun build` shadows `build`, so both need
+  // the explicit `run` form. `yarn deploy` has no builtin to collide with.
+  const deployCommand =
+    packageManager === "npm" || packageManager === "pnpm" || packageManager === "bun"
+      ? `${packageManager} run deploy`
+      : `${packageManager} deploy`;
   const typecheckCommand =
     packageManager === "npm" ? "npm run typecheck" : `${packageManager} typecheck`;
   // The pages router derives route ids from filenames, so its home page is
@@ -1687,19 +1781,15 @@ function createReadme({
     lines.push("- `src/api/health.ts` is a sample API route.");
   }
 
-  // The one convention a new app trips over before it writes anything else,
-  // and AGENTS.md — where the same note lives for coding agents — is only
-  // seeded when agent tooling is enabled.
-  lines.push("");
-  lines.push("## Navigating");
-  lines.push("");
-  lines.push(
-    `Pracht navigates by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
-      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes ` +
-      "take their segments through `params`. The id survives a path change, and `pracht " +
-      "typegen` types both the id and its params — so `<Link href>` is a compile error. Use a " +
-      "plain `<a href>` for external and user-provided URLs.",
-  );
+  if (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.",
+    );
+  }
 
   if (packageManager === "pnpm") {
     lines.push(
@@ -1711,16 +1801,46 @@ function createReadme({
     );
   }
 
-  if (tailwind) {
-    lines.push("- `src/styles/global.css` is the Tailwind CSS entry, imported by the shell.");
-  }
-
   if (agentTools) {
+    lines.push("");
+    lines.push("## Skills");
+    lines.push("");
     lines.push(
-      "- `.claude/skills/` and `.mcp.json` wire up the pracht Claude Code skills and MCP server.",
+      agentSkills === "full"
+        ? "The whole pracht skill catalog is in `.claude/skills/`. Browse it with `pracht skills list`."
+        : `\`.claude/skills/\` holds the ${CORE_SKILLS.length} core skills: ` +
+            `${CORE_SKILLS.map((name) => `\`/${name}\``).join(", ")}.`,
     );
+    if (agentSkills !== "full") {
+      lines.push("");
+      lines.push(
+        "The rest of the catalog — audits, testing scaffolds, and the `add-*` " +
+          "integrations — is published at " +
+          `[\`/.well-known/agent-skills/index.json\`](${SKILL_CATALOG_URL}). ` +
+          "Install what you need:",
+      );
+      lines.push("");
+      lines.push("```bash");
+      lines.push("pracht skills list");
+      lines.push("pracht skills add audit-loaders add-db");
+      lines.push("```");
+    }
   }
 
+  // The one convention a new app trips over before it writes anything else,
+  // and AGENTS.md — where the same note lives for coding agents — is only
+  // seeded when agent tooling is enabled.
+  lines.push("");
+  lines.push("## Navigating");
+  lines.push("");
+  lines.push(
+    `Pracht navigates by route id, not by path: \`<Link route="${homeRouteId}">\`, ` +
+      `\`href("${homeRouteId}")\`, \`navigate({ route: "${homeRouteId}" })\`. Dynamic routes ` +
+      "take their segments through `params`. The id survives a path change, and `pracht " +
+      "typegen` types both the id and its params — so `<Link href>` is a compile error. Use a " +
+      "plain `<a href>` for external and user-provided URLs.",
+  );
+
   lines.push("");
   lines.push("## Checks");
   lines.push("");
@@ -1824,6 +1944,7 @@ async function installDependencies(targetDir, packageManager) {
 
 function printNextSteps({
   adapter,
+  agentSkills = "core",
   agentTools,
   dir,
   installSucceeded,
@@ -1843,13 +1964,21 @@ function printNextSteps({
     `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"}`);
+  console.log(
+    `Agent tooling: ${
+      agentTools
+        ? `${agentSkills === "full" ? "full skill catalog" : `${CORE_SKILLS.length} core 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.",
+      "Note: the pages router registers by file — `_app.tsx` per directory, one root\n" +
+        "`_middleware.ts` for every page route, `src/capabilities/`, and\n" +
+        "`src/pages/_app.config.ts` for agents and constraints. Per-route middleware\n" +
+        "assignment, per-route shell overrides, path-prefix groups, and webhook ISG\n" +
+        "still need a manifest; scaffold with --router=manifest, or eject later.",
     );
   }
   console.log("");
@@ -1899,8 +2028,10 @@ Options:
   --template=minimal|tailwind  Choose starter template (minimal, or minimal + Tailwind CSS)
   --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)
+  --agent-tools[=core|full] / --no-agent-tools
+                               Seed Claude Code skills and a pracht MCP config (default: prompt, yes).
+                               core (the default) seeds ${CORE_SKILLS.length} skills; full seeds the whole catalog.
+                               Add more later with \`pracht skills add <name>\`.
   --no-git                     Skip git init and the initial commit
   --skip-install               Skip dependency installation
   --yes, -y                    Accept defaults, skip all prompts