create-pracht 0.0.2 → 0.2.0

package/README.md

@@ -43,7 +43,10 @@ Cloudflare scaffolds also include:
 
 - `dev` -> `pracht dev`
 - `build` -> `pracht build`
-- `preview` -> `pracht preview`
+
+Node starters also include:
+
+- `start` -> `node dist/server/server.js`
 
 Cloudflare starters also include:
 
@@ -52,9 +55,3 @@ Cloudflare starters also include:
 Vercel starters also include:
 
 - `deploy` -> `pracht build && vercel deploy --prebuilt`
-
-Node starters can be run in production with:
-
-```bash
-node dist/server/server.js
-```

package/bin/create-pracht.js

@@ -3,7 +3,10 @@
 import { run } from "../src/index.js";
 
 run().catch((error) => {
-  console.error("Failed to create a pracht app.");
-  console.error(error instanceof Error ? error.message : error);
-  process.exit(1);
+  const code = error && error.code === 2 ? 2 : 1;
+  console.error(code === 2 ? error.message : "Failed to create a pracht app.");
+  if (code !== 2) {
+    console.error(error instanceof Error ? error.message : error);
+  }
+  process.exit(code);
 });

package/package.json

@@ -1,6 +1,15 @@
 {
   "name": "create-pracht",
-  "version": "0.0.2",
+  "version": "0.2.0",
+  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/start",
+  "bugs": {
+    "url": "https://github.com/JoviDeCroock/pracht/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JoviDeCroock/pracht",
+    "directory": "packages/start"
+  },
   "bin": {
     "create-pracht": "./bin/create-pracht.js"
   },
@@ -10,6 +19,9 @@
     "README.md"
   ],
   "type": "module",
+  "publishConfig": {
+    "provenance": true
+  },
   "scripts": {
     "build": "node -e \"\""
   }

package/src/index.js

@@ -1,12 +1,28 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
-import { mkdir, readdir, stat, writeFile } from "node:fs/promises";
+import { mkdir, readdir, stat, symlink, writeFile } from "node:fs/promises";
 import { basename, dirname, resolve } from "node:path";
 import { createInterface } from "node:readline/promises";
 
+export class ValidationError extends Error {
+  constructor(message) {
+    super(message);
+    this.code = 2;
+  }
+}
+
+async function fetchLatestVersion(packageName) {
+  const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
+  if (!res.ok) {
+    throw new Error(`Failed to fetch version for ${packageName}: ${res.statusText}`);
+  }
+  const data = await res.json();
+  return data.version;
+}
+
 const ADAPTERS = {
   node: {
-    description: "Node.js server with pracht preview",
+    description: "Node.js server with a generated server entry",
     id: "node",
     label: "Node.js",
     packageName: "@pracht/adapter-node",
@@ -33,54 +49,119 @@ const DEFAULT_DIRECTORY = "pracht-app";
 export async function run(argv = process.argv.slice(2)) {
   const options = parseArgs(argv);
   const packageManager = getPackageManager();
+  const log = options.json ? () => {} : console.log.bind(console);
 
-  console.log("create-pracht");
-  console.log(`Using ${packageManager} for this scaffold.`);
-  console.log("");
+  log("create-pracht");
+  log(`Using ${packageManager} for this scaffold.`);
+  log("");
 
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
+  const dir = options.dir ?? (options.yes ? DEFAULT_DIRECTORY : null);
+  const adapterId = options.adapter ?? (options.yes ? "node" : null);
+  const router = options.router ?? (options.yes ? "manifest" : null);
 
-  try {
-    const dir = options.dir ?? (await promptForDirectory(readline));
-    const adapterId = options.adapter ?? (await promptForAdapter(readline));
-    const targetDir = resolve(process.cwd(), dir);
+  let resolvedDir = dir;
+  let resolvedAdapter = adapterId;
+  let resolvedRouter = router;
 
-    await ensureTargetDirectory(targetDir);
+  if (resolvedDir == null || resolvedAdapter == null || resolvedRouter == null) {
+    const readline = createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
 
-    await scaffoldProject({
-      adapter: ADAPTERS[adapterId],
+    try {
+      resolvedDir = resolvedDir ?? (await promptForDirectory(readline));
+      resolvedAdapter = resolvedAdapter ?? (await promptForAdapter(readline));
+      resolvedRouter = resolvedRouter ?? (await promptForRouter(readline));
+    } finally {
+      readline.close();
+    }
+  }
+
+  const targetDir = resolve(process.cwd(), resolvedDir);
+
+  await ensureTargetDirectory(targetDir);
+
+  if (options.dryRun) {
+    const files = await buildProjectFiles({
+      adapter: ADAPTERS[resolvedAdapter],
       packageManager,
-      targetDir,
+      projectName: toPackageName(basename(targetDir)),
+      router: resolvedRouter,
     });
 
-    let installSucceeded = false;
-    if (!options.skipInstall) {
-      console.log("");
-      console.log(`Installing dependencies with ${packageManager}...`);
-      installSucceeded = await installDependencies(targetDir, packageManager);
+    const fileList = Object.keys(files).sort();
+
+    if (options.json) {
+      console.log(
+        JSON.stringify({
+          adapter: resolvedAdapter,
+          directory: resolvedDir,
+          dryRun: true,
+          files: fileList,
+          router: resolvedRouter,
+        }),
+      );
+    } else {
+      log("Dry run — the following files would be created:");
+      log("");
+      for (const file of fileList) {
+        log(`  ${file}`);
+      }
     }
 
+    return;
+  }
+
+  await scaffoldProject({
+    adapter: ADAPTERS[resolvedAdapter],
+    packageManager,
+    router: resolvedRouter,
+    targetDir,
+  });
+
+  let installSucceeded = false;
+  if (!options.skipInstall) {
+    log("");
+    log(`Installing dependencies with ${packageManager}...`);
+    installSucceeded = await installDependencies(targetDir, packageManager);
+  }
+
+  if (options.json) {
+    const files = await buildProjectFiles({
+      adapter: ADAPTERS[resolvedAdapter],
+      packageManager,
+      projectName: toPackageName(basename(targetDir)),
+      router: resolvedRouter,
+    });
+
+    console.log(
+      JSON.stringify({
+        adapter: resolvedAdapter,
+        directory: resolvedDir,
+        files: Object.keys(files).sort(),
+        installed: options.skipInstall ? false : installSucceeded,
+        router: resolvedRouter,
+      }),
+    );
+  } else {
     printNextSteps({
-      adapter: ADAPTERS[adapterId],
-      dir,
+      adapter: ADAPTERS[resolvedAdapter],
+      dir: resolvedDir,
       installSucceeded,
       packageManager,
       skipInstall: options.skipInstall,
     });
-  } finally {
-    readline.close();
   }
 }
 
-export async function scaffoldProject({ adapter, packageManager, targetDir }) {
+export async function scaffoldProject({ adapter, packageManager, router = "manifest", targetDir }) {
   const packageName = toPackageName(basename(targetDir));
-  const files = buildProjectFiles({
+  const files = await buildProjectFiles({
     adapter,
     packageManager,
     projectName: packageName,
+    router,
   });
 
   await mkdir(targetDir, { recursive: true });
@@ -90,6 +171,8 @@ export async function scaffoldProject({ adapter, packageManager, targetDir }) {
     await mkdir(dirname(filePath), { recursive: true });
     await writeFile(filePath, content, "utf-8");
   }
+
+  await symlink("AGENTS.md", resolve(targetDir, "CLAUDE.md"));
 }
 
 export function getPackageManager(userAgent = process.env.npm_config_user_agent ?? "") {
@@ -103,7 +186,11 @@ export function parseArgs(argv) {
   const options = {
     adapter: undefined,
     dir: undefined,
+    dryRun: false,
+    json: false,
+    router: undefined,
     skipInstall: false,
+    yes: false,
   };
 
   for (const arg of argv) {
@@ -112,8 +199,40 @@ export function parseArgs(argv) {
       continue;
     }
 
+    if (arg === "--yes" || arg === "-y") {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === "--json") {
+      options.json = true;
+      continue;
+    }
+
+    if (arg === "--dry-run") {
+      options.dryRun = true;
+      continue;
+    }
+
     if (arg.startsWith("--adapter=")) {
-      options.adapter = normalizeAdapter(arg.slice("--adapter=".length));
+      const value = normalizeAdapter(arg.slice("--adapter=".length));
+      if (!value) {
+        throw new ValidationError(
+          `Invalid adapter: ${arg.slice("--adapter=".length)}. Use node, cf, or vercel.`,
+        );
+      }
+      options.adapter = value;
+      continue;
+    }
+
+    if (arg.startsWith("--router=")) {
+      const value = normalizeRouter(arg.slice("--router=".length));
+      if (!value) {
+        throw new ValidationError(
+          `Invalid router: ${arg.slice("--router=".length)}. Use manifest or pages.`,
+        );
+      }
+      options.router = value;
       continue;
     }
 
@@ -166,11 +285,28 @@ async function promptForAdapter(readline) {
   }
 }
 
+async function promptForRouter(readline) {
+  console.log("Router:");
+  console.log("  1. Manifest (explicit routes.ts)");
+  console.log("  2. Pages (file-system routing)");
+
+  while (true) {
+    const answer = await readline.question("Router (1): ");
+    const normalized = normalizeRouter(answer.trim() || "1");
+
+    if (normalized) {
+      return normalized;
+    }
+
+    console.log("Choose 1/2 or manifest/pages.");
+  }
+}
+
 async function ensureTargetDirectory(targetDir) {
   const error = await validateTargetDirectory(targetDir);
 
   if (error) {
-    throw new Error(error);
+    throw new ValidationError(error);
   }
 }
 
@@ -192,6 +328,20 @@ async function validateTargetDirectory(targetDir) {
   return null;
 }
 
+function normalizeRouter(value) {
+  const normalized = value.toLowerCase();
+
+  if (normalized === "1" || normalized === "manifest") {
+    return "manifest";
+  }
+
+  if (normalized === "2" || normalized === "pages") {
+    return "pages";
+  }
+
+  return null;
+}
+
 function normalizeAdapter(value) {
   const normalized = value.toLowerCase();
 
@@ -215,18 +365,45 @@ function normalizeAdapter(value) {
   return null;
 }
 
-function buildProjectFiles({ adapter, packageManager, projectName }) {
+async function resolveVersions(packageNames) {
+  const entries = await Promise.all(
+    packageNames.map(async (name) => [name, `^${await fetchLatestVersion(name)}`]),
+  );
+  return Object.fromEntries(entries);
+}
+
+async function buildProjectFiles({ adapter, packageManager, projectName, router }) {
+  const packagesToResolve = [
+    "@pracht/cli",
+    "@pracht/vite-plugin",
+    "@pracht/core",
+    adapter.packageName,
+  ];
+  if (adapter.id === "vercel") {
+    packagesToResolve.push("vercel");
+  }
+
+  const versions = await resolveVersions(packagesToResolve);
+
   const files = {
     ".gitignore": "dist\nnode_modules\n.wrangler\n.vercel\n",
-    "README.md": createReadme({ adapter, packageManager, projectName }),
-    "package.json": createPackageJson({ adapter, projectName }),
+    "README.md": createReadme({ adapter, packageManager, projectName, router }),
+    "package.json": createPackageJson({ adapter, projectName, versions }),
     "src/api/health.ts": createHealthRoute(adapter),
-    "src/routes.ts": createRoutesFile(),
-    "src/routes/home.tsx": createHomeRoute(adapter),
-    "src/shells/public.tsx": createShellFile(projectName),
-    "vite.config.ts": createViteConfig(adapter),
+    "vite.config.ts": createViteConfig(adapter, router),
+    "tsconfig.json": createBaseTSConfig(adapter),
+    "AGENTS.md": createAgentInstructions({ adapter, packageManager, router }),
   };
 
+  if (router === "pages") {
+    files["src/pages/_app.tsx"] = createShellFile(projectName);
+    files["src/pages/index.tsx"] = createPagesHomeRoute(adapter);
+  } else {
+    files["src/routes.ts"] = createRoutesFile();
+    files["src/routes/home.tsx"] = createHomeRoute(adapter);
+    files["src/shells/public.tsx"] = createShellFile(projectName);
+  }
+
   if (adapter.id === "cloudflare") {
     files["wrangler.jsonc"] = createWranglerConfig(projectName);
     files["src/env.d.ts"] = createCloudflareEnvDeclaration();
@@ -235,16 +412,19 @@ function buildProjectFiles({ adapter, packageManager, projectName }) {
   return files;
 }
 
-function createPackageJson({ adapter, projectName }) {
+function createPackageJson({ adapter, projectName, versions }) {
   const scripts = {
     build: "pracht build",
     dev: "pracht dev",
-    preview: "pracht preview",
   };
 
+  if (adapter.id === "node") {
+    scripts.start = "node dist/server/server.js";
+  }
+
   const devDependencies = {
-    "@pracht/cli": "latest",
-    "@pracht/vite-plugin": "latest",
+    "@pracht/cli": versions["@pracht/cli"],
+    "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
     preact: "^10.26.9",
     "preact-render-to-string": "^6.5.13",
     vite: "^8.0.0",
@@ -257,14 +437,14 @@ function createPackageJson({ adapter, projectName }) {
 
   if (adapter.id === "vercel") {
     scripts.deploy = "pracht build && vercel deploy --prebuilt";
-    devDependencies.vercel = "latest";
+    devDependencies.vercel = versions["vercel"];
   }
 
   return `${JSON.stringify(
     {
       dependencies: {
-        [adapter.packageName]: "latest",
-        "@pracht/core": "latest",
+        [adapter.packageName]: versions[adapter.packageName],
+        "@pracht/core": versions["@pracht/core"],
       },
       devDependencies,
       name: projectName,
@@ -278,7 +458,7 @@ function createPackageJson({ adapter, projectName }) {
   )}\n`;
 }
 
-function createViteConfig(adapter) {
+function createViteConfig(adapter, router) {
   const ADAPTER_IMPORTS = {
     node: { fn: "nodeAdapter", pkg: "@pracht/adapter-node" },
     cloudflare: { fn: "cloudflareAdapter", pkg: "@pracht/adapter-cloudflare" },
@@ -287,13 +467,18 @@ function createViteConfig(adapter) {
 
   const info = ADAPTER_IMPORTS[adapter.id] ?? ADAPTER_IMPORTS.node;
 
+  const prachtOptions =
+    router === "pages"
+      ? `{ pagesDir: "/src/pages", adapter: ${info.fn}() }`
+      : `{ adapter: ${info.fn}() }`;
+
   return [
     'import { defineConfig } from "vite";',
     'import { pracht } from "@pracht/vite-plugin";',
     `import { ${info.fn} } from "${info.pkg}";`,
     "",
     "export default defineConfig({",
-    `  plugins: [pracht({ adapter: ${info.fn}() })],`,
+    `  plugins: [pracht(${prachtOptions})],`,
     "});",
     "",
   ].join("\n");
@@ -379,6 +564,57 @@ function createHomeRoute(adapter) {
   ].join("\n");
 }
 
+function createPagesHomeRoute(adapter) {
+  return [
+    'import type { LoaderArgs, RouteComponentProps } from "@pracht/core";',
+    "",
+    'export const RENDER_MODE = "ssg";',
+    "",
+    "export async function loader(_args: LoaderArgs) {",
+    "  return {",
+    `    adapter: ${JSON.stringify(adapter.label)},`,
+    "    steps: [",
+    '      "Edit src/pages/index.tsx to change this page.",',
+    '      "Add more pages in src/pages/.",',
+    '      "Add API handlers in src/api/*.ts.",',
+    "    ],",
+    "  };",
+    "}",
+    "",
+    "export function Component({ data }: RouteComponentProps<typeof loader>) {",
+    "  return (",
+    "    <section>",
+    '      <p style={{ color: "#555", marginBottom: "8px" }}>Starter ready.</p>',
+    '      <h1 style={{ fontSize: "2.5rem", lineHeight: 1.1, margin: "0 0 16px" }}>Your pracht app is up and running.</h1>',
+    '      <p style={{ fontSize: "1.1rem", lineHeight: 1.6, marginBottom: "24px" }}>',
+    "        This starter is configured for <strong>{data.adapter}</strong>.",
+    "      </p>",
+    '      <ul style={{ lineHeight: 1.8, paddingLeft: "20px" }}>',
+    "        {data.steps.map((step) => (",
+    "          <li key={step}>{step}</li>",
+    "        ))}",
+    "      </ul>",
+    '      <p style={{ marginTop: "24px" }}>',
+    "        Check <code>/api/health</code> for a simple API route.",
+    "      </p>",
+    "    </section>",
+    "  );",
+    "}",
+    "",
+  ].join("\n");
+}
+
+function createBaseTSConfig(_adapter) {
+  const config = {
+    compilerOptions: {
+      jsx: "react-jsx",
+      jsxImportSource: "preact",
+      lib: ["ES2022"],
+    },
+  };
+  return JSON.stringify(config, null, 4);
+}
+
 function createHealthRoute(adapter) {
   return [
     "export function GET() {",
@@ -426,10 +662,71 @@ function createCloudflareEnvDeclaration() {
   ].join("\n");
 }
 
-function createReadme({ adapter, packageManager, projectName }) {
+function createAgentInstructions({ adapter, packageManager, router }) {
+  const runCmd = packageManager === "npm" ? "npm run" : packageManager;
+
+  const lines = [
+    "# Pracht App",
+    "",
+    "## Commands",
+    "",
+    `- \`${runCmd} dev\` — start the dev server`,
+    `- \`${runCmd} build\` — production build`,
+  ];
+
+  if (adapter.id === "node") {
+    lines.push(`- \`${runCmd} start\` — run the built server`);
+  }
+
+  if (adapter.id === "cloudflare" || adapter.id === "vercel") {
+    lines.push(`- \`${runCmd} deploy\` — build and deploy`);
+  }
+
+  lines.push("");
+  lines.push("## Scaffolding");
+  lines.push("");
+  lines.push("Use the CLI to generate new files:");
+  lines.push("");
+  lines.push("- `pracht generate route <name>` — add a route");
+  lines.push("- `pracht generate shell <name>` — add a shell");
+  lines.push("- `pracht generate middleware <name>` — add middleware");
+  lines.push("- `pracht generate api <name>` — add an API route");
+  lines.push("- `pracht doctor` — check project health");
+
+  lines.push("");
+  lines.push("## Project structure");
+  lines.push("");
+
+  if (router === "pages") {
+    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)");
+  } 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/shells/` — shell components (layouts)");
+  }
+
+  lines.push("- `src/api/` — API route handlers");
+  lines.push(`- \`vite.config.ts\` — Vite config with the ${adapter.label} adapter`);
+
+  if (adapter.id === "cloudflare") {
+    lines.push("- `wrangler.jsonc` — Cloudflare Workers configuration");
+    lines.push("- `src/env.d.ts` — TypeScript types for Cloudflare bindings");
+  }
+
+  lines.push("");
+
+  return lines.join("\n");
+}
+
+function createReadme({ adapter, packageManager, projectName, router }) {
   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`;
+  const startCommand = packageManager === "npm" ? "npm run start" : `${packageManager} start`;
   const deployCommand = packageManager === "npm" ? "npm run deploy" : `${packageManager} deploy`;
 
   const lines = [
@@ -441,9 +738,12 @@ function createReadme({ adapter, packageManager, projectName }) {
     "",
     `- \`${installCommand}\``,
     `- \`${devCommand}\``,
-    `- \`${previewCommand}\``,
   ];
 
+  if (adapter.id === "node") {
+    lines.push(`- \`${startCommand}\``);
+  }
+
   if (adapter.id === "cloudflare") {
     lines.push(`- \`${deployCommand}\``);
     lines.push("");
@@ -461,8 +761,16 @@ function createReadme({ adapter, packageManager, projectName }) {
   lines.push("");
   lines.push("## Files");
   lines.push("");
-  lines.push("- `src/routes.ts` defines your app manifest.");
-  lines.push("- `src/routes/home.tsx` is the first page.");
+
+  if (router === "pages") {
+    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.");
+  } else {
+    lines.push("- `src/routes.ts` defines your app manifest.");
+    lines.push("- `src/routes/home.tsx` is the first page.");
+  }
+
   lines.push("- `src/api/health.ts` is a sample API route.");
 
   return `${lines.join("\n")}\n`;
@@ -514,7 +822,16 @@ function printHelp() {
   console.log(`create-pracht
 
 Usage:
-  create-pracht [directory] [--adapter=node|cf|vercel] [--skip-install]
+  create-pracht [directory] [options]
+
+Options:
+  --adapter=node|cf|vercel   Choose hosting adapter (default: node)
+  --router=manifest|pages    Choose routing system (default: manifest)
+  --skip-install             Skip dependency installation
+  --yes, -y                  Accept defaults, skip all prompts
+  --json                     Output JSON summary instead of prose
+  --dry-run                  Show which files would be created without writing
+  -h, --help                 Show this help message
 `);
 }