@pracht/cli 0.0.1 → 1.1.0

package/lib/build-shared.js

@@ -0,0 +1,127 @@
+import { cpSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+import { DEFAULT_SECURITY_HEADERS, VERSION } from "./constants.js";
+
+const ROUTE_STATE_REQUEST_HEADER = "x-pracht-route-state-request";
+
+export function setDefaultSecurityHeaders(res, headers = {}) {
+  for (const [key, value] of Object.entries({
+    ...DEFAULT_SECURITY_HEADERS,
+    ...headers,
+  })) {
+    res.setHeader(key, value);
+  }
+}
+
+export 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 = [
+    {
+      dest: target,
+      has: [{ type: "header", key: ROUTE_STATE_REQUEST_HEADER, value: "1" }],
+      src: "/(.*)",
+    },
+  ];
+
+  for (const route of sortStaticRoutes(staticRoutes)) {
+    routes.push({
+      dest: routeToStaticHtmlPath(route),
+      src: routeToRouteExpression(route),
+    });
+  }
+
+  for (const route of isgRoutes) {
+    routes.push({
+      dest: target,
+      src: routeToRouteExpression(route),
+    });
+  }
+
+  routes.push({ handle: "filesystem" });
+  routes.push({ dest: target, src: "/(.*)" });
+
+  return {
+    headers: [
+      {
+        headers: [
+          {
+            key: "permissions-policy",
+            value:
+              "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
+          },
+          { key: "referrer-policy", value: "strict-origin-when-cross-origin" },
+          { key: "x-content-type-options", value: "nosniff" },
+          { key: "x-frame-options", value: "SAMEORIGIN" },
+        ],
+        source: "/(.*)",
+      },
+    ],
+    framework: {
+      version: VERSION,
+    },
+    routes,
+    version: 3,
+  };
+}
+
+function createVercelFunctionConfig({ regions }) {
+  const config = {
+    entrypoint: "server.js",
+    runtime: "edge",
+  };
+
+  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, "\\$&");
+}

package/lib/cli.js

@@ -0,0 +1,164 @@
+import { HTTP_METHODS, VERSION } from "./constants.js";
+
+export function printHelp() {
+  console.log(`pracht ${VERSION}
+
+Usage:
+  pracht dev [port]                 Start development server with HMR
+  pracht build                      Production build (client + server)
+  pracht generate <kind> [flags]    Scaffold framework files
+  pracht verify [--changed] [--json] Fast framework-aware verification
+  pracht inspect [target] [--json]  Inspect resolved app graph
+  pracht doctor [--json]            Validate app wiring
+
+Generate kinds:
+  route       --path /dashboard [--render ssr|spa|ssg|isg] [--shell app] [--middleware auth] [--loader]
+  shell       --name app
+  middleware  --name auth
+  api         --path /health [--methods GET,POST]
+`);
+}
+
+export function printInspectHelp() {
+  console.log(`Usage:
+  pracht inspect [routes|api|build] [--json]
+  pracht inspect --json
+`);
+}
+
+export function printGenerateHelp() {
+  console.log(`Usage:
+  pracht generate route --path /dashboard [--render ssr|spa|ssg|isg] [--shell app] [--middleware auth] [--loader] [--json]
+  pracht generate shell --name app [--json]
+  pracht generate middleware --name auth [--json]
+  pracht generate api --path /health [--methods GET,POST] [--json]
+`);
+}
+
+export function parseFlags(args) {
+  const options = { _: [] };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const token = args[index];
+    if (!token.startsWith("--")) {
+      options._.push(token);
+      continue;
+    }
+
+    if (token.startsWith("--no-")) {
+      options[token.slice(5)] = false;
+      continue;
+    }
+
+    const equalsIndex = token.indexOf("=");
+    if (equalsIndex !== -1) {
+      const key = token.slice(2, equalsIndex);
+      const value = token.slice(equalsIndex + 1);
+      assignOption(options, key, value);
+      continue;
+    }
+
+    const key = token.slice(2);
+    const next = args[index + 1];
+    if (next && !next.startsWith("--")) {
+      assignOption(options, key, next);
+      index += 1;
+      continue;
+    }
+
+    assignOption(options, key, true);
+  }
+
+  return options;
+}
+
+export function requireStringOption(options, key) {
+  const value = requireOptionalString(options, key);
+  if (!value) {
+    throw new Error(`Missing required flag --${key}.`);
+  }
+  return value;
+}
+
+export function requireOptionalString(options, key) {
+  const value = options[key];
+  if (Array.isArray(value)) {
+    return String(value[value.length - 1]);
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+}
+
+export function requireEnumOption(options, key, allowed, fallback) {
+  const value = requireOptionalString(options, key) ?? fallback;
+  if (!allowed.includes(value)) {
+    throw new Error(`Invalid value for --${key}. Expected one of ${allowed.join(", ")}.`);
+  }
+  return value;
+}
+
+export function requirePositiveIntegerOption(options, key, fallback) {
+  const raw = requireOptionalString(options, key);
+  const value = raw == null ? fallback : Number.parseInt(raw, 10);
+  if (!Number.isInteger(value) || value <= 0) {
+    throw new Error(`--${key} must be a positive integer.`);
+  }
+  return value;
+}
+
+export function parseCommaList(value) {
+  if (!value) return [];
+  const values = Array.isArray(value) ? value : [value];
+  return values
+    .flatMap((entry) => String(entry).split(","))
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+}
+
+export function parseApiMethods(value) {
+  const methods = parseCommaList(value);
+  const normalized = methods.length === 0 ? ["GET"] : methods.map((entry) => entry.toUpperCase());
+
+  for (const method of normalized) {
+    if (!HTTP_METHODS.has(method)) {
+      throw new Error(`Unsupported HTTP method "${method}".`);
+    }
+  }
+
+  return [...new Set(normalized)];
+}
+
+export function quote(value) {
+  return JSON.stringify(value);
+}
+
+export function ensureTrailingNewline(value) {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+export function handleCliError(error, { json }) {
+  const message = error instanceof Error ? error.message : String(error);
+  if (json) {
+    console.error(JSON.stringify({ ok: false, error: message }, null, 2));
+  } else {
+    console.error(message);
+    if (error instanceof Error && error.stack && process.env.DEBUG) {
+      console.error(error.stack);
+    }
+  }
+  process.exit(1);
+}
+
+function assignOption(options, key, value) {
+  if (!(key in options)) {
+    options[key] = value;
+    return;
+  }
+
+  if (!Array.isArray(options[key])) {
+    options[key] = [options[key]];
+  }
+  options[key].push(value);
+}

package/lib/commands/build.js

@@ -0,0 +1,104 @@
+import { cpSync, existsSync, mkdirSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+import { build as viteBuild } from "vite";
+
+import { readClientBuildAssets } from "../build-metadata.js";
+import { writeVercelBuildOutput } from "../build-shared.js";
+
+export async function buildCommand() {
+  const root = process.cwd();
+
+  console.log("\n  Building client...\n");
+  await viteBuild({
+    root,
+    build: {
+      outDir: "dist",
+      manifest: true,
+      rollupOptions: {
+        input: "virtual:pracht/client",
+      },
+    },
+  });
+
+  console.log("\n  Building server...\n");
+  await viteBuild({
+    root,
+    build: {
+      outDir: "dist/server",
+      ssr: "virtual:pracht/server",
+    },
+  });
+
+  const serverEntry = resolve(root, "dist/server/server.js");
+  let clientDir;
+  if (existsSync(resolve(root, "dist/client/.vite/manifest.json"))) {
+    clientDir = resolve(root, "dist/client");
+  } else {
+    clientDir = resolve(root, "dist/client");
+    const distRoot = resolve(root, "dist");
+    mkdirSync(clientDir, { recursive: true });
+    for (const entry of readdirSync(distRoot)) {
+      if (entry === "server" || entry === "client") continue;
+      const sourcePath = join(distRoot, entry);
+      const destinationPath = join(clientDir, entry);
+      cpSync(sourcePath, destinationPath, { recursive: true });
+      rmSync(sourcePath, { force: true, recursive: true });
+    }
+  }
+
+  if (existsSync(serverEntry)) {
+    const serverMod = await import(serverEntry);
+    const { prerenderApp } = serverMod;
+    const { clientEntryUrl, cssManifest } = readClientBuildAssets(root);
+
+    const { pages, isgManifest } = await prerenderApp({
+      app: serverMod.resolvedApp,
+      clientEntryUrl: clientEntryUrl ?? undefined,
+      cssManifest,
+      registry: serverMod.registry,
+      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 + "/", "")}`);
+      }
+    }
+
+    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,
+        isgRoutes: Object.keys(isgManifest),
+        regions: serverMod.vercelRegions,
+        root,
+        staticRoutes: pages.map((page) => page.path).filter((path) => !(path in isgManifest)),
+      });
+
+      console.log(`\n  Vercel build output → ${outputPath}\n`);
+    }
+  }
+
+  console.log("\n  Build complete.\n");
+}

package/lib/commands/dev.js

@@ -0,0 +1,16 @@
+import { createServer } from "vite";
+
+import { parseFlags } from "../cli.js";
+
+export async function devCommand(args) {
+  const options = parseFlags(args);
+  const port = parseInt(process.env.PORT || options._[0] || "3000", 10);
+
+  const server = await createServer({
+    root: process.cwd(),
+    server: { port },
+  });
+
+  await server.listen();
+  server.printUrls();
+}

package/lib/commands/doctor.js

@@ -0,0 +1,21 @@
+import { parseFlags } from "../cli.js";
+import { runDoctor } from "../verification.js";
+
+export async function doctorCommand(args) {
+  const options = parseFlags(args);
+  const report = runDoctor(process.cwd());
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    console.log(`Pracht doctor (${report.mode} mode)`);
+    for (const check of report.checks) {
+      console.log(`${check.status.toUpperCase().padEnd(5)} ${check.message}`);
+    }
+    console.log(report.ok ? "\nNo blocking issues found." : "\nBlocking issues found.");
+  }
+
+  if (!report.ok) {
+    process.exitCode = 1;
+  }
+}