create-pracht 0.1.0 → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jovi De Croock
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,15 +1,16 @@
 {
   "name": "create-pracht",
-  "version": "0.1.0",
+  "version": "0.2.1",
+  "license": "MIT",
+  "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"
   },
-  "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/start",
-  "bugs": {
-    "url": "https://github.com/JoviDeCroock/pracht/issues"
-  },
   "bin": {
     "create-pracht": "./bin/create-pracht.js"
   },

package/src/index.js

@@ -1,17 +1,20 @@
 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`,
-  );
+  const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`);
   if (!res.ok) {
-    throw new Error(
-      `Failed to fetch version for ${packageName}: ${res.statusText}`,
-    );
+    throw new Error(`Failed to fetch version for ${packageName}: ${res.statusText}`);
   }
   const data = await res.json();
   return data.version;
@@ -19,7 +22,7 @@ async function fetchLatestVersion(packageName) {
 
 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",
@@ -46,47 +49,109 @@ 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 router = options.router ?? (await promptForRouter(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,
-      router,
-      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();
   }
 }
 
@@ -106,6 +171,8 @@ export async function scaffoldProject({ adapter, packageManager, router = "manif
     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 ?? "") {
@@ -119,8 +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) {
@@ -129,13 +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=")) {
-      options.router = normalizeRouter(arg.slice("--router=".length));
+      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;
     }
 
@@ -209,7 +306,7 @@ async function ensureTargetDirectory(targetDir) {
   const error = await validateTargetDirectory(targetDir);
 
   if (error) {
-    throw new Error(error);
+    throw new ValidationError(error);
   }
 }
 
@@ -270,10 +367,7 @@ function normalizeAdapter(value) {
 
 async function resolveVersions(packageNames) {
   const entries = await Promise.all(
-    packageNames.map(async (name) => [
-      name,
-      `^${await fetchLatestVersion(name)}`,
-    ]),
+    packageNames.map(async (name) => [name, `^${await fetchLatestVersion(name)}`]),
   );
   return Object.fromEntries(entries);
 }
@@ -297,6 +391,8 @@ async function buildProjectFiles({ adapter, packageManager, projectName, router
     "package.json": createPackageJson({ adapter, projectName, versions }),
     "src/api/health.ts": createHealthRoute(adapter),
     "vite.config.ts": createViteConfig(adapter, router),
+    "tsconfig.json": createBaseTSConfig(adapter),
+    "AGENTS.md": createAgentInstructions({ adapter, packageManager, router }),
   };
 
   if (router === "pages") {
@@ -320,9 +416,12 @@ 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": versions["@pracht/cli"],
     "@pracht/vite-plugin": versions["@pracht/vite-plugin"],
@@ -505,6 +604,17 @@ function createPagesHomeRoute(adapter) {
   ].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() {",
@@ -552,10 +662,71 @@ function createCloudflareEnvDeclaration() {
   ].join("\n");
 }
 
+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 = [
@@ -567,9 +738,12 @@ function createReadme({ adapter, packageManager, projectName, router }) {
     "",
     `- \`${installCommand}\``,
     `- \`${devCommand}\``,
-    `- \`${previewCommand}\``,
   ];
 
+  if (adapter.id === "node") {
+    lines.push(`- \`${startCommand}\``);
+  }
+
   if (adapter.id === "cloudflare") {
     lines.push(`- \`${deployCommand}\``);
     lines.push("");
@@ -648,7 +822,16 @@ function printHelp() {
   console.log(`create-pracht
 
 Usage:
-  create-pracht [directory] [--adapter=node|cf|vercel] [--router=manifest|pages] [--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
 `);
 }