@pracht/cli 0.0.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,54 @@
+# @pracht/cli
+
+## 1.0.0
+
+### Major Changes
+
+- [#58](https://github.com/JoviDeCroock/pracht/pull/58) [`6bf6738`](https://github.com/JoviDeCroock/pracht/commit/6bf6738469c8533db2890a89b4edcb92bbbb1011) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add framework-native `pracht generate route|shell|middleware|api` scaffolding commands, add `pracht doctor` with optional JSON output, and remove the Node-specific `pracht preview` command.
+
+### Minor Changes
+
+- [#69](https://github.com/JoviDeCroock/pracht/pull/69) [`527e030`](https://github.com/JoviDeCroock/pracht/commit/527e030017f269b7cff51e96a0bcb98bbd1bff3d) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add a fast `pracht verify` command with optional `--changed` and `--json`
+  output for framework-aware manifest, pages-router, and API route validation.
+
+### Patch Changes
+
+- [#63](https://github.com/JoviDeCroock/pracht/pull/63) [`cf71d67`](https://github.com/JoviDeCroock/pracht/commit/cf71d6781012cc5f79bf5e557658c9fb9112832e) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Separate HTML and route-state cache variants across framework responses and build outputs.
+
+  Page responses now vary on `x-pracht-route-state-request`, framework-generated
+  route-state responses default to `Cache-Control: no-store`, and Node/preview
+  cached HTML paths no longer intercept route-state fetches. Vercel build output
+  now routes route-state requests to the edge function before static rewrites.
+
+- [#62](https://github.com/JoviDeCroock/pracht/pull/62) [`4017a4a`](https://github.com/JoviDeCroock/pracht/commit/4017a4a59ef702de14a3eb835b0d7bf0967509f8) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Serve static assets directly from the Node adapter with proper Cache-Control headers. Hashed assets under /assets/ get immutable caching; HTML gets must-revalidate. Preview server now mirrors production caching behavior.
+
+- [#51](https://github.com/JoviDeCroock/pracht/pull/51) [`db5f6d0`](https://github.com/JoviDeCroock/pracht/commit/db5f6d0a6770cd36fbcdaea708d2f161d2be23d3) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Apply default security headers to static asset responses across adapters
+
+  Cloudflare static assets now inherit the same permissions-policy, referrer-policy, x-content-type-options, and x-frame-options headers that dynamic responses already receive. Vercel build output config now emits a headers section so static files served by Vercel's CDN also get the baseline security headers.
+
+- Updated dependencies [[`b34695f`](https://github.com/JoviDeCroock/pracht/commit/b34695f8e6cfaf2e00b77c451395351565ff3b7c), [`bb9480e`](https://github.com/JoviDeCroock/pracht/commit/bb9480ee6a22b3bbb744f174e9132fd8dda446b4), [`4c885be`](https://github.com/JoviDeCroock/pracht/commit/4c885be049049fe2f1b0bbcfe3a39aa63f7364c0), [`cf71d67`](https://github.com/JoviDeCroock/pracht/commit/cf71d6781012cc5f79bf5e557658c9fb9112832e), [`8b71a9f`](https://github.com/JoviDeCroock/pracht/commit/8b71a9f3a7d6fd8d43bea6767d59bfa2d5b28abb), [`4e9b705`](https://github.com/JoviDeCroock/pracht/commit/4e9b7053b5bedadedd39e6343e7a887864e094dd), [`9fc392f`](https://github.com/JoviDeCroock/pracht/commit/9fc392f132b5d34ee9da72f389c6ac15fe2f1161), [`12829ec`](https://github.com/JoviDeCroock/pracht/commit/12829ec075d269e2511387543c4ad592ae5d8c2a)]:
+  - @pracht/core@0.1.0
+
+## 0.0.1
+
+### Patch Changes
+
+- [#21](https://github.com/JoviDeCroock/pracht/pull/21) [`1243610`](https://github.com/JoviDeCroock/pracht/commit/12436100f9ce4a6dd749190570bf3b0dd1170308) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add README files to all packages
+
+- [`c95bb72`](https://github.com/JoviDeCroock/pracht/commit/c95bb72c53a2d9012fde847139c276808ba5a9c3) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Fix SSG prerendered pages missing client JS script tag and framework context
+
+  Two issues caused prerendered (SSG) pages to ship without working hydration:
+
+  1. **Vite 8 environment nesting**: The `@cloudflare/vite-plugin` outputs client assets
+     to `<outDir>/client/`, so `outDir: "dist/client"` produced `dist/client/client/`.
+     The CLI then couldn't find the Vite manifest, resulting in no `<script>` tag in
+     prerendered HTML. Fixed by setting `outDir: "dist"`.
+
+  2. **Dual Preact context copies**: The CLI imported `prerenderApp` from its own
+     `@pracht/core`, while the server bundle had its own bundled copy. Different
+     `createContext` instances meant `useLocation()` returned `/` during prerendering,
+     breaking shell features like active link highlighting. Fixed by re-exporting
+     `prerenderApp` from the server module so the CLI uses the same bundled copy.
+
+- Updated dependencies [[`1243610`](https://github.com/JoviDeCroock/pracht/commit/12436100f9ce4a6dd749190570bf3b0dd1170308), [`d64d7fc`](https://github.com/JoviDeCroock/pracht/commit/d64d7fc1e4a7b134259d1dfbb3d5a939599e42fc)]:
+  - @pracht/core@0.0.1

package/README.md

@@ -0,0 +1,79 @@
+# @pracht/cli
+
+Command-line tool for developing, building, validating, and scaffolding pracht apps.
+
+## Install
+
+```bash
+npm install @pracht/cli
+```
+
+## Commands
+
+### `pracht dev`
+
+Start the local development server with SSR and HMR.
+
+### `pracht build`
+
+Create a production build with client/server output and SSG/ISG prerendering.
+
+For Node.js targets, run the built server with:
+
+```bash
+node dist/server/server.js
+```
+
+### `pracht verify`
+
+Run fast framework-aware verification checks without paying for a full build or
+test loop. Use `--changed` to focus on changed manifest-managed files and
+`--json` for machine-readable output.
+
+```bash
+pracht verify
+pracht verify --changed
+pracht verify --json
+```
+
+### `pracht generate route`
+
+Create a new route module. In manifest apps this also updates `src/routes.ts`.
+
+```bash
+pracht generate route --path /dashboard --render ssr --shell app --middleware auth
+```
+
+### `pracht generate shell`
+
+Create a shell module and register it in the app manifest.
+
+```bash
+pracht generate shell --name app
+```
+
+### `pracht generate middleware`
+
+Create a middleware module and register it in the app manifest.
+
+```bash
+pracht generate middleware --name auth
+```
+
+### `pracht generate api`
+
+Create an API route under `src/api/`.
+
+```bash
+pracht generate api --path /health --methods GET,POST
+```
+
+### `pracht doctor`
+
+Validate the local app wiring across the whole project. Use `--json` for
+machine-readable output.
+
+```bash
+pracht doctor
+pracht doctor --json
+```

package/bin/pracht.js

@@ -1,29 +1,16 @@
 #!/usr/bin/env node
 
-import { createServer as createHttpServer } from "node:http";
-import { resolve, join, dirname, extname } from "node:path";
-import {
-  existsSync,
-  statSync,
-  mkdirSync,
-  writeFileSync,
-  createReadStream,
-  readFileSync,
-  rmSync,
-  cpSync,
-} from "node:fs";
-import { createServer, build as viteBuild } from "vite";
-
-const DEFAULT_SECURITY_HEADERS = {
-  "permissions-policy":
-    "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
-  "referrer-policy": "strict-origin-when-cross-origin",
-  "x-content-type-options": "nosniff",
-  "x-frame-options": "SAMEORIGIN",
-};
-
-const VERSION = "0.0.0";
-const command = process.argv[2];
+import { doctorCommand } from "../lib/commands/doctor.js";
+import { buildCommand } from "../lib/commands/build.js";
+import { devCommand } from "../lib/commands/dev.js";
+import { generateCommand } from "../lib/commands/generate.js";
+import { verifyCommand } from "../lib/commands/verify.js";
+import { handleCliError, printHelp } from "../lib/cli.js";
+import { VERSION } from "../lib/constants.js";
+
+const argv = process.argv.slice(2);
+const command = argv[0];
+const jsonOutput = argv.includes("--json");
 
 if (!command || command === "help" || command === "--help" || command === "-h") {
   printHelp();
@@ -35,431 +22,18 @@ if (command === "--version" || command === "-v") {
   process.exit(0);
 }
 
-const handlers = { dev, build, preview };
+const handlers = {
+  build: buildCommand,
+  dev: devCommand,
+  doctor: doctorCommand,
+  generate: generateCommand,
+  verify: verifyCommand,
+};
 
 if (!(command in handlers)) {
-  console.error(`Unknown pracht command: ${command}`);
-  printHelp();
-  process.exit(1);
+  handleCliError(new Error(`Unknown pracht command: ${command}`), { json: false });
 }
 
-handlers[command]().catch((err) => {
-  console.error(err);
-  process.exit(1);
+handlers[command](argv.slice(1)).catch((error) => {
+  handleCliError(error, { json: jsonOutput });
 });
-
-// ---------------------------------------------------------------------------
-// Commands
-// ---------------------------------------------------------------------------
-
-async function dev() {
-  const port = parseInt(process.env.PORT || process.argv[3] || "3000", 10);
-
-  const server = await createServer({
-    root: process.cwd(),
-    server: { port },
-  });
-
-  await server.listen();
-  server.printUrls();
-}
-
-async function build() {
-  // 1. Client build
-  console.log("\n  Building client...\n");
-  await viteBuild({
-    root: process.cwd(),
-    build: {
-      outDir: "dist/client",
-      manifest: true,
-      rollupOptions: {
-        input: "virtual:pracht/client",
-      },
-    },
-  });
-
-  // 2. SSR build
-  console.log("\n  Building server...\n");
-  await viteBuild({
-    root: process.cwd(),
-    build: {
-      ssr: "virtual:pracht/server",
-      outDir: "dist/server",
-    },
-  });
-
-  // 3. SSG prerendering
-  const root = process.cwd();
-  const serverEntry = resolve(root, "dist/server/server.js");
-  const clientDir = resolve(root, "dist/client");
-
-  if (existsSync(serverEntry)) {
-    const serverMod = await import(serverEntry);
-    const { prerenderApp } = await import("@pracht/core");
-
-    // Read the Vite manifest for asset URLs
-    const manifestPath = resolve(clientDir, ".vite/manifest.json");
-    const viteManifest = existsSync(manifestPath)
-      ? JSON.parse(readFileSync(manifestPath, "utf-8"))
-      : {};
-
-    const clientEntry = viteManifest["virtual:pracht/client"];
-    const clientEntryUrl = clientEntry ? `/${clientEntry.file}` : undefined;
-
-    // Build per-source-file CSS manifest by walking static imports transitively.
-    // This ensures each page gets only the CSS it actually needs.
-    function collectTransitiveCss(key) {
-      const css = new Set();
-      const visited = new Set();
-      function collect(k) {
-        if (visited.has(k)) return;
-        visited.add(k);
-        const entry = viteManifest[k];
-        if (!entry) return;
-        for (const c of entry.css ?? []) css.add(c);
-        for (const imp of entry.imports ?? []) collect(imp);
-      }
-      collect(key);
-      return [...css];
-    }
-
-    const cssManifest = {};
-    for (const [key, entry] of Object.entries(viteManifest)) {
-      if (!entry.src) continue;
-      const css = collectTransitiveCss(key);
-      if (css.length > 0) {
-        cssManifest[key] = css.map((f) => `/${f}`);
-      }
-    }
-
-    const { pages, isgManifest } = await prerenderApp({
-      app: serverMod.resolvedApp,
-      registry: serverMod.registry,
-      clientEntryUrl,
-      cssManifest,
-      withISGManifest: true,
-    });
-
-    if (pages.length > 0) {
-      console.log(`\n  Prerendering ${pages.length} SSG/ISG route(s)...\n`);
-      for (const page of pages) {
-        const filePath =
-          page.path === "/"
-            ? join(clientDir, "index.html")
-            : join(clientDir, page.path, "index.html");
-
-        mkdirSync(dirname(filePath), { recursive: true });
-        writeFileSync(filePath, page.html, "utf-8");
-        console.log(`    ${page.path} → ${filePath.replace(root + "/", "")}`);
-      }
-    }
-
-    // Write ISG manifest for the preview/production server
-    if (Object.keys(isgManifest).length > 0) {
-      const isgManifestPath = resolve(root, "dist/server/isg-manifest.json");
-      writeFileSync(isgManifestPath, JSON.stringify(isgManifest, null, 2), "utf-8");
-      console.log(
-        `\n  ISG manifest → dist/server/isg-manifest.json (${Object.keys(isgManifest).length} route(s))\n`,
-      );
-    }
-
-    if (serverMod.buildTarget === "cloudflare") {
-      console.log(`\n  Cloudflare worker → dist/server/server.js\n`);
-      console.log(`  Deploy with: wrangler deploy\n`);
-    }
-
-    if (serverMod.buildTarget === "vercel") {
-      const outputPath = writeVercelBuildOutput({
-        functionName: serverMod.vercelFunctionName,
-        regions: serverMod.vercelRegions,
-        root,
-        staticRoutes: pages.map((page) => page.path).filter((path) => !(path in isgManifest)),
-        isgRoutes: Object.keys(isgManifest),
-      });
-
-      console.log(`\n  Vercel build output → ${outputPath}\n`);
-    }
-  }
-
-  console.log("\n  Build complete.\n");
-}
-
-async function preview() {
-  const root = process.cwd();
-  const clientDir = resolve(root, "dist/client");
-  const serverEntry = resolve(root, "dist/server/server.js");
-
-  if (!existsSync(serverEntry)) {
-    console.error("Server build not found at dist/server/. Run `pracht build` first.");
-    process.exit(1);
-  }
-
-  const serverMod = await import(serverEntry);
-  const { handlePrachtRequest } = await import("@pracht/core");
-
-  // Load ISG manifest if it exists
-  const isgManifestPath = resolve(root, "dist/server/isg-manifest.json");
-  const isgManifest = existsSync(isgManifestPath)
-    ? JSON.parse(readFileSync(isgManifestPath, "utf-8"))
-    : {};
-
-  // Read the Vite manifest for asset URLs
-  const manifestPath = resolve(clientDir, ".vite/manifest.json");
-  const viteManifest = existsSync(manifestPath)
-    ? JSON.parse(readFileSync(manifestPath, "utf-8"))
-    : {};
-
-  // Find the client entry asset from the manifest
-  const clientEntry = viteManifest["virtual:pracht/client"];
-  const clientEntryUrl = clientEntry ? `/${clientEntry.file}` : undefined;
-  const cssUrls = (clientEntry?.css ?? []).map((f) => `/${f}`);
-
-  const MIME_TYPES = {
-    ".html": "text/html",
-    ".js": "application/javascript",
-    ".css": "text/css",
-    ".json": "application/json",
-    ".png": "image/png",
-    ".jpg": "image/jpeg",
-    ".svg": "image/svg+xml",
-    ".woff": "font/woff",
-    ".woff2": "font/woff2",
-  };
-
-  const port = parseInt(process.argv[3] || "3000", 10);
-
-  const server = createHttpServer(async (req, res) => {
-    const url = req.url ?? "/";
-
-    const parsedUrl = new URL(url, "http://localhost");
-
-    // ISG stale-while-revalidate check
-    if (req.method === "GET" && parsedUrl.pathname in isgManifest) {
-      const entry = isgManifest[parsedUrl.pathname];
-      const htmlPath =
-        parsedUrl.pathname === "/"
-          ? join(clientDir, "index.html")
-          : join(clientDir, parsedUrl.pathname, "index.html");
-
-      if (existsSync(htmlPath) && statSync(htmlPath).isFile()) {
-        const stat = statSync(htmlPath);
-        const ageMs = Date.now() - stat.mtimeMs;
-        const isStale = entry.revalidate.kind === "time" && ageMs > entry.revalidate.seconds * 1000;
-
-        setDefaultSecurityHeaders(res, {
-          "content-type": "text/html; charset=utf-8",
-          "x-pracht-isg": isStale ? "stale" : "fresh",
-        });
-        createReadStream(htmlPath).pipe(res);
-
-        if (isStale) {
-          // Background regeneration
-          const regenRequest = new Request(new URL(parsedUrl.pathname, "http://localhost"), {
-            method: "GET",
-          });
-          handlePrachtRequest({
-            app: serverMod.resolvedApp,
-            registry: serverMod.registry,
-            request: regenRequest,
-            clientEntryUrl,
-            cssUrls,
-          })
-            .then(async (response) => {
-              if (response.status === 200) {
-                const { mkdirSync, writeFileSync } = await import("node:fs");
-                mkdirSync(dirname(htmlPath), { recursive: true });
-                writeFileSync(htmlPath, await response.text(), "utf-8");
-              }
-            })
-            .catch((err) => {
-              console.error(`ISG regeneration failed for ${parsedUrl.pathname}:`, err);
-            });
-        }
-        return;
-      }
-    }
-
-    // Try static file first
-    const filePath = resolve(clientDir, "." + url);
-    if (!filePath.startsWith(clientDir + "/") && filePath !== clientDir) {
-      res.statusCode = 403;
-      res.end("Forbidden");
-      return;
-    }
-    if (existsSync(filePath) && statSync(filePath).isFile()) {
-      const ext = extname(filePath);
-      const headers = {
-        "content-type": MIME_TYPES[ext] || "application/octet-stream",
-      };
-      if (ext === ".html") {
-        setDefaultSecurityHeaders(res, headers);
-      } else {
-        for (const [key, value] of Object.entries(headers)) {
-          res.setHeader(key, value);
-        }
-      }
-      createReadStream(filePath).pipe(res);
-      return;
-    }
-
-    // SSR fallback
-    try {
-      const headers = new Headers();
-      for (const [key, value] of Object.entries(req.headers)) {
-        if (value === undefined) continue;
-        if (Array.isArray(value)) {
-          for (const v of value) headers.append(key, v);
-        } else {
-          headers.set(key, value);
-        }
-      }
-
-      const protocol = req.headers["x-forwarded-proto"] || "http";
-      const host = req.headers.host || "localhost";
-      const webRequest = new Request(new URL(url, `${protocol}://${host}`), {
-        method: req.method,
-        headers,
-      });
-
-      const response = await handlePrachtRequest({
-        app: serverMod.resolvedApp,
-        registry: serverMod.registry,
-        request: webRequest,
-        clientEntryUrl,
-        cssUrls,
-        apiRoutes: serverMod.apiRoutes,
-      });
-
-      res.statusCode = response.status;
-      response.headers.forEach((value, key) => {
-        res.setHeader(key, value);
-      });
-
-      if (!response.body) {
-        res.end();
-        return;
-      }
-
-      const body = Buffer.from(await response.arrayBuffer());
-      res.end(body);
-    } catch (err) {
-      console.error("SSR error:", err);
-      res.statusCode = 500;
-      res.end("Internal Server Error");
-    }
-  });
-
-  server.listen(port, () => {
-    console.log(`\n  pracht preview server running at http://localhost:${port}\n`);
-  });
-}
-
-function printHelp() {
-  console.log(`pracht ${VERSION}
-
-Usage:
-  pracht dev       Start development server with HMR
-  pracht build     Production build (client + server)
-  pracht preview   Preview the production build
-`);
-}
-
-function setDefaultSecurityHeaders(res, headers = {}) {
-  for (const [key, value] of Object.entries({
-    ...DEFAULT_SECURITY_HEADERS,
-    ...headers,
-  })) {
-    res.setHeader(key, value);
-  }
-}
-
-function writeVercelBuildOutput({ functionName, regions, root, staticRoutes, isgRoutes }) {
-  const outputDir = join(root, ".vercel/output");
-  const staticDir = join(outputDir, "static");
-  const functionDir = join(outputDir, "functions", `${functionName || "render"}.func`);
-
-  rmSync(outputDir, { force: true, recursive: true });
-  mkdirSync(outputDir, { recursive: true });
-  cpSync(join(root, "dist/client"), staticDir, { recursive: true });
-  cpSync(join(root, "dist/server"), functionDir, { recursive: true });
-
-  writeFileSync(
-    join(outputDir, "config.json"),
-    `${JSON.stringify(createVercelOutputConfig({ functionName, staticRoutes, isgRoutes }), null, 2)}\n`,
-    "utf-8",
-  );
-  writeFileSync(
-    join(functionDir, ".vc-config.json"),
-    `${JSON.stringify(createVercelFunctionConfig({ regions }), null, 2)}\n`,
-    "utf-8",
-  );
-
-  return ".vercel/output";
-}
-
-function createVercelOutputConfig({ functionName, staticRoutes, isgRoutes }) {
-  const target = `/${functionName || "render"}`;
-  const routes = [];
-
-  for (const route of sortStaticRoutes(staticRoutes)) {
-    routes.push({
-      src: routeToRouteExpression(route),
-      dest: routeToStaticHtmlPath(route),
-    });
-  }
-
-  for (const route of isgRoutes) {
-    routes.push({
-      src: routeToRouteExpression(route),
-      dest: target,
-    });
-  }
-
-  routes.push({ handle: "filesystem" });
-  routes.push({ src: "/(.*)", dest: target });
-
-  return {
-    version: 3,
-    routes,
-    framework: {
-      version: VERSION,
-    },
-  };
-}
-
-function createVercelFunctionConfig({ regions }) {
-  const config = {
-    runtime: "edge",
-    entrypoint: "server.js",
-  };
-
-  if (regions) {
-    config.regions = regions;
-  }
-
-  return config;
-}
-
-function sortStaticRoutes(routes) {
-  return [...new Set(routes)].sort((left, right) => right.length - left.length);
-}
-
-function routeToRouteExpression(route) {
-  if (route === "/") {
-    return "^/$";
-  }
-
-  return `^${escapeRegex(route)}/?$`;
-}
-
-function routeToStaticHtmlPath(route) {
-  if (route === "/") {
-    return "/index.html";
-  }
-
-  return `${route}/index.html`;
-}
-
-function escapeRegex(value) {
-  return value.replace(/[|\\{}()[\]^$+*?.-]/g, "\\$&");
-}