@pracht/cli 1.1.5 → 1.2.0

package/{lib/commands/generate.js → src/commands/generate.ts}

@@ -1,17 +1,15 @@
 import { readFileSync, writeFileSync } from "node:fs";
 
+import { defineCommand } from "citty";
+
 import {
   ensureTrailingNewline,
   parseApiMethods,
   parseCommaList,
-  parseFlags,
-  printGenerateHelp,
   quote,
-  requireEnumOption,
-  requireOptionalString,
-  requirePositiveIntegerOption,
-  requireStringOption,
-} from "../cli.js";
+  requireEnum,
+  requirePositiveInteger,
+} from "../utils.js";
 import {
   extractRegistryEntries,
   insertArrayItem,
@@ -29,20 +27,103 @@ import {
   resolveRouteModulePath,
   resolveScopedFile,
   writeGeneratedFile,
+  type ProjectConfig,
 } from "../project.js";
 
-export async function generateCommand(args) {
-  const [kind, ...rest] = args;
-  if (!kind || kind === "--help" || kind === "-h") {
-    printGenerateHelp();
-    return;
-  }
-
-  const options = parseFlags(rest);
-  const project = readProjectConfig(process.cwd());
-  const result = runGenerate(kind, options, project);
+interface GenerateResult {
+  created: string[];
+  kind: string;
+  updated: string[];
+}
 
-  if (options.json) {
+const routeCommand = defineCommand({
+  meta: {
+    name: "route",
+    description: "Scaffold a route module",
+  },
+  args: {
+    path: { type: "string", required: true, description: "Route path (e.g. /dashboard)" },
+    render: { type: "string", description: "Render mode: ssr, spa, ssg, or isg" },
+    shell: { type: "string", description: "Shell name" },
+    middleware: { type: "string", description: "Middleware names (comma-separated)" },
+    loader: { type: "boolean", description: "Include loader" },
+    "error-boundary": { type: "boolean", description: "Include error boundary" },
+    "static-paths": { type: "boolean", description: "Include static paths" },
+    title: { type: "string", description: "Page title" },
+    revalidate: { type: "string", description: "ISG revalidation seconds" },
+    json: { type: "boolean", description: "Output as JSON" },
+  },
+  async run({ args }) {
+    const project = readProjectConfig(process.cwd());
+    const result = generateRoute(args, project);
+    outputResult(result, Boolean(args.json));
+  },
+});
+
+const shellCommand = defineCommand({
+  meta: {
+    name: "shell",
+    description: "Scaffold a shell component",
+  },
+  args: {
+    name: { type: "string", required: true, description: "Shell name" },
+    json: { type: "boolean", description: "Output as JSON" },
+  },
+  async run({ args }) {
+    const project = readProjectConfig(process.cwd());
+    const result = generateShell(args.name, project);
+    outputResult(result, Boolean(args.json));
+  },
+});
+
+const middlewareCommand = defineCommand({
+  meta: {
+    name: "middleware",
+    description: "Scaffold a middleware function",
+  },
+  args: {
+    name: { type: "string", required: true, description: "Middleware name" },
+    json: { type: "boolean", description: "Output as JSON" },
+  },
+  async run({ args }) {
+    const project = readProjectConfig(process.cwd());
+    const result = generateMiddleware(args.name, project);
+    outputResult(result, Boolean(args.json));
+  },
+});
+
+const apiCommand = defineCommand({
+  meta: {
+    name: "api",
+    description: "Scaffold an API route",
+  },
+  args: {
+    path: { type: "string", required: true, description: "API endpoint path" },
+    methods: { type: "string", description: "HTTP methods (comma-separated, e.g. GET,POST)" },
+    json: { type: "boolean", description: "Output as JSON" },
+  },
+  async run({ args }) {
+    const project = readProjectConfig(process.cwd());
+    const result = generateApi(args, project);
+    outputResult(result, Boolean(args.json));
+  },
+});
+
+export default defineCommand({
+  meta: {
+    name: "generate",
+    description: "Scaffold framework files",
+  },
+  subCommands: {
+    route: routeCommand,
+    shell: shellCommand,
+    middleware: middlewareCommand,
+    api: apiCommand,
+  },
+});
+
+function outputResult(result: GenerateResult, json: boolean): void {
+  if (json) {
     console.log(JSON.stringify({ ok: true, ...result }, null, 2));
     return;
   }
@@ -56,36 +137,31 @@ export async function generateCommand(args) {
   }
 }
 
-function runGenerate(kind, options, project) {
-  if (kind === "route") {
-    return generateRoute(options, project);
-  }
-  if (kind === "shell") {
-    return generateShell(options, project);
-  }
-  if (kind === "middleware") {
-    return generateMiddleware(options, project);
-  }
-  if (kind === "api") {
-    return generateApi(options, project);
-  }
-
-  throw new Error(`Unknown generate kind: ${kind}`);
+interface RouteArgs {
+  "error-boundary"?: boolean;
+  loader?: boolean;
+  middleware?: string;
+  path: string;
+  render?: string;
+  revalidate?: string;
+  shell?: string;
+  "static-paths"?: boolean;
+  title?: string;
 }
 
-function generateRoute(options, project) {
-  const routePath = normalizeRoutePathString(requireStringOption(options, "path"));
-  const render = requireEnumOption(options, "render", ["spa", "ssr", "ssg", "isg"], "ssr");
-  const includeLoader = Boolean(options.loader);
-  const includeErrorBoundary = Boolean(options["error-boundary"]);
-  const middleware = parseCommaList(options.middleware);
+function generateRoute(args: RouteArgs, project: ProjectConfig): GenerateResult {
+  const routePath = normalizeRoutePathString(args.path);
+  const render = requireEnum(args.render, "render", ["spa", "ssr", "ssg", "isg"], "ssr");
+  const includeLoader = Boolean(args.loader);
+  const includeErrorBoundary = Boolean(args["error-boundary"]);
+  const middleware = parseCommaList(args.middleware);
   const includeStaticPaths =
-    Boolean(options["static-paths"]) ||
+    Boolean(args["static-paths"]) ||
     (hasDynamicSegments(routePath) && (render === "ssg" || render === "isg"));
-  const title = requireOptionalString(options, "title") ?? titleFromPath(routePath);
+  const title = args.title ?? titleFromPath(routePath);
 
   if (project.mode === "pages") {
-    if (options.shell) {
+    if (args.shell) {
       throw new Error("`pracht generate route --shell` is only available for manifest apps.");
     }
     if (middleware.length > 0) {
@@ -113,7 +189,7 @@ function generateRoute(options, project) {
     extractRegistryEntries(manifestSource, "middleware").map((entry) => entry.name),
   );
 
-  const shellName = requireOptionalString(options, "shell");
+  const shellName = args.shell;
   if (shellName && !registeredShells.has(shellName)) {
     throw new Error(`Shell "${shellName}" is not registered in ${project.appFile}.`);
   }
@@ -152,7 +228,7 @@ function generateRoute(options, project) {
     meta.push(`middleware: [${middleware.map((item) => quote(item)).join(", ")}]`);
   }
   if (render === "isg") {
-    const seconds = requirePositiveIntegerOption(options, "revalidate", 3600);
+    const seconds = requirePositiveInteger(args.revalidate, "revalidate", 3600);
     meta.push(`revalidate: timeRevalidate(${seconds})`);
   }
 
@@ -182,7 +258,15 @@ function generatePagesRoute({
   render,
   routePath,
   title,
-}) {
+}: {
+  includeErrorBoundary: boolean;
+  includeLoader: boolean;
+  includeStaticPaths: boolean;
+  project: ProjectConfig;
+  render: string;
+  routePath: string;
+  title: string;
+}): GenerateResult {
   const routeFile = resolvePagesRouteModulePath(project, routePath, ".tsx");
   writeGeneratedFile(
     routeFile.absolutePath,
@@ -203,14 +287,13 @@ function generatePagesRoute({
   };
 }
 
-function generateShell(options, project) {
+function generateShell(name: string, project: ProjectConfig): GenerateResult {
   if (project.mode === "pages") {
     throw new Error(
       "Pages router apps use a single `_app` shell. `pracht generate shell` is only available for manifest apps.",
     );
   }
 
-  const name = requireStringOption(options, "name");
   const manifestPath = resolveProjectPath(project.root, project.appFile);
   assertFileExists(manifestPath, `App manifest not found at ${project.appFile}.`);
 
@@ -232,14 +315,13 @@ function generateShell(options, project) {
   };
 }
 
-function generateMiddleware(options, project) {
+function generateMiddleware(name: string, project: ProjectConfig): GenerateResult {
   if (project.mode === "pages") {
     throw new Error(
       "Pages router apps do not use manifest middleware registration. `pracht generate middleware` is only available for manifest apps.",
     );
   }
 
-  const name = requireStringOption(options, "name");
   const manifestPath = resolveProjectPath(project.root, project.appFile);
   assertFileExists(manifestPath, `App manifest not found at ${project.appFile}.`);
 
@@ -261,9 +343,14 @@ function generateMiddleware(options, project) {
   };
 }
 
-function generateApi(options, project) {
-  const endpointPath = normalizeApiPath(requireStringOption(options, "path"));
-  const methods = parseApiMethods(options.methods);
+interface ApiArgs {
+  methods?: string;
+  path: string;
+}
+
+function generateApi(args: ApiArgs, project: ProjectConfig): GenerateResult {
+  const endpointPath = normalizeApiPath(args.path);
+  const methods = parseApiMethods(args.methods);
   const apiFile = resolveApiModulePath(project, endpointPath);
   writeGeneratedFile(apiFile.absolutePath, buildApiRouteSource({ endpointPath, methods }));
 
@@ -280,10 +367,16 @@ function buildManifestRouteModuleSource({
   includeStaticPaths,
   routePath,
   title,
-}) {
+}: {
+  includeErrorBoundary: boolean;
+  includeLoader: boolean;
+  includeStaticPaths: boolean;
+  routePath: string;
+  title: string;
+}): string {
   const params = dynamicParamNames(routePath);
-  const imports = [];
-  const sections = [];
+  const imports: string[] = [];
+  const sections: string[] = [];
 
   if (includeLoader) {
     imports.push("LoaderArgs", "RouteComponentProps");
@@ -359,10 +452,17 @@ function buildPagesRouteModuleSource({
   render,
   routePath,
   title,
-}) {
+}: {
+  includeErrorBoundary: boolean;
+  includeLoader: boolean;
+  includeStaticPaths: boolean;
+  render: string;
+  routePath: string;
+  title: string;
+}): string {
   const params = dynamicParamNames(routePath);
-  const imports = [];
-  const sections = [];
+  const imports: string[] = [];
+  const sections: string[] = [];
 
   if (includeLoader) {
     imports.push("LoaderArgs", "RouteComponentProps");
@@ -431,7 +531,7 @@ function buildPagesRouteModuleSource({
   return `${sections.join("\n")}\n`;
 }
 
-function buildShellModuleSource(name) {
+function buildShellModuleSource(name: string): string {
   const title = titleCase(name);
   return [
     'import type { ShellProps } from "@pracht/core";',
@@ -451,7 +551,7 @@ function buildShellModuleSource(name) {
   ].join("\n");
 }
 
-function buildMiddlewareModuleSource() {
+function buildMiddlewareModuleSource(): string {
   return [
     'import type { MiddlewareFn } from "@pracht/core";',
     "",
@@ -462,7 +562,13 @@ function buildMiddlewareModuleSource() {
   ].join("\n");
 }
 
-function buildApiRouteSource({ endpointPath, methods }) {
+function buildApiRouteSource({
+  endpointPath,
+  methods,
+}: {
+  endpointPath: string;
+  methods: string[];
+}): string {
   const methodLines = methods.flatMap((method, index) => {
     const lines = buildApiMethodSource(method, methods, endpointPath);
     if (index === methods.length - 1) return lines;
@@ -472,7 +578,7 @@ function buildApiRouteSource({ endpointPath, methods }) {
   return ['import type { BaseRouteArgs } from "@pracht/core";', "", ...methodLines, ""].join("\n");
 }
 
-function buildApiMethodSource(method, methods, endpointPath) {
+function buildApiMethodSource(method: string, methods: string[], endpointPath: string): string[] {
   if (method === "DELETE" || method === "HEAD") {
     return [
       `export function ${method}(_args: BaseRouteArgs) {`,
@@ -509,22 +615,22 @@ function buildApiMethodSource(method, methods, endpointPath) {
   ];
 }
 
-function normalizeRoutePathString(value) {
+function normalizeRoutePathString(value: string): string {
   if (!value || value === "/") return "/";
   const normalized = `/${value}`.replace(/\/+/g, "/");
   return normalized !== "/" && normalized.endsWith("/") ? normalized.slice(0, -1) : normalized;
 }
 
-function normalizeApiPath(value) {
+function normalizeApiPath(value: string): string {
   const normalized = normalizeRoutePathString(value).replace(/^\/api(?=\/|$)/, "");
   return normalized || "/";
 }
 
-function hasDynamicSegments(routePath) {
+function hasDynamicSegments(routePath: string): boolean {
   return routePath.split("/").some((segment) => segment.startsWith(":") || segment === "*");
 }
 
-function dynamicParamNames(routePath) {
+function dynamicParamNames(routePath: string): string[] {
   return routePath
     .split("/")
     .filter(Boolean)
@@ -533,10 +639,10 @@ function dynamicParamNames(routePath) {
       if (segment === "*") return "slug";
       return null;
     })
-    .filter(Boolean);
+    .filter((s): s is string => s !== null);
 }
 
-function routeIdFromPath(routePath) {
+function routeIdFromPath(routePath: string): string {
   if (routePath === "/") return "index";
   return routePath
     .split("/")
@@ -545,13 +651,13 @@ function routeIdFromPath(routePath) {
     .join("-");
 }
 
-function titleFromPath(routePath) {
+function titleFromPath(routePath: string): string {
   if (routePath === "/") return "Home";
   const lastSegment = routePath.split("/").filter(Boolean).at(-1) ?? "Page";
   return titleCase(lastSegment.replace(/^:/, "").replace(/\*/g, "slug"));
 }
 
-function titleCase(value) {
+function titleCase(value: string): string {
   return value
     .split(/[-_/]/)
     .filter(Boolean)
@@ -559,7 +665,7 @@ function titleCase(value) {
     .join(" ");
 }
 
-function buildStaticPathsStub(params) {
+function buildStaticPathsStub(params: string[]): string {
   if (params.length === 0) {
     return "{}";
   }
@@ -567,6 +673,6 @@ function buildStaticPathsStub(params) {
   return `{ ${params.map((name) => `${name}: ${quote(`example-${name}`)}`).join(", ")} }`;
 }
 
-function escapeJsxText(value) {
+function escapeJsxText(value: string): string {
   return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
 }

package/{lib/commands/inspect.js → src/commands/inspect.ts}

@@ -1,40 +1,76 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
-import { createServer } from "vite";
+import { defineCommand } from "citty";
+import { createServer, type ViteDevServer } from "vite";
 
-import { handleCliError, parseFlags, printInspectHelp, requireOptionalString } from "../cli.js";
+import { handleCliError } from "../utils.js";
 import { readClientBuildAssets } from "../build-metadata.js";
-import { HTTP_METHODS } from "../constants.js";
+import { HTTP_METHODS, type HttpMethod } from "../constants.js";
 import { readProjectConfig, resolveProjectPath } from "../project.js";
 
 const INSPECT_TARGETS = new Set(["routes", "api", "build", "all"]);
-const METHOD_ORDER = [...HTTP_METHODS];
-
-export async function inspectCommand(args) {
-  const options = parseFlags(args);
-  const target = requireOptionalString(options, "target") ?? options._[0] ?? "all";
-
-  if (options.help || target === "help") {
-    printInspectHelp();
-    return;
-  }
-
-  if (!INSPECT_TARGETS.has(target)) {
-    handleCliError(new Error(`Unknown inspect target: ${target}`), { json: !!options.json });
-  }
+const METHOD_ORDER: HttpMethod[] = [...HTTP_METHODS];
+
+export default defineCommand({
+  meta: {
+    name: "inspect",
+    description: "Inspect resolved app graph",
+  },
+  args: {
+    target: {
+      type: "positional",
+      description: "Inspect target: routes, api, build, or all",
+      required: false,
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON",
+    },
+  },
+  async run({ args }) {
+    const target = args.target || "all";
+
+    if (!INSPECT_TARGETS.has(target)) {
+      handleCliError(new Error(`Unknown inspect target: ${target}`), {
+        json: Boolean(args.json),
+      });
+    }
 
-  const report = await runInspect(process.cwd(), { target });
+    const report = await runInspect(process.cwd(), { target });
 
-  if (options.json) {
-    console.log(JSON.stringify(report, null, 2));
-    return;
-  }
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
 
-  printInspectReport(report);
+    printInspectReport(report);
+  },
+});
+
+interface InspectReport {
+  api?: { file: string; methods: string[]; path: string }[];
+  build?: {
+    adapterTarget: string;
+    clientEntryUrl: string | null;
+    cssManifest: Record<string, string[]>;
+    jsManifest: Record<string, string[]>;
+  };
+  mode: string;
+  routes?: {
+    file: string;
+    id: string;
+    loaderFile: string | null;
+    middleware: string[];
+    path: string;
+    render: string | null;
+    revalidate: unknown;
+    shell: string | null;
+    shellFile: string | null;
+  }[];
 }
 
-export async function runInspect(root, { target = "all" } = {}) {
+async function runInspect(root: string, { target = "all" } = {}): Promise<InspectReport> {
   const project = readProjectConfig(root);
 
   if (!project.configFile) {
@@ -66,7 +102,7 @@ export async function runInspect(root, { target = "all" } = {}) {
 
   try {
     const serverModule = await server.ssrLoadModule("virtual:pracht/server");
-    const report = {
+    const report: InspectReport = {
       mode: project.mode,
     };
 
@@ -76,7 +112,7 @@ export async function runInspect(root, { target = "all" } = {}) {
 
     if (target === "api" || target === "all") {
       report.api = await Promise.all(
-        serverModule.apiRoutes.map(async (route) => ({
+        serverModule.apiRoutes.map(async (route: { file: string; path: string }) => ({
           file: route.file,
           methods: await detectApiMethods(server, root, route.file),
           path: route.path,
@@ -100,7 +136,19 @@ export async function runInspect(root, { target = "all" } = {}) {
   }
 }
 
-function serializeRoutes(routes) {
+interface RouteEntry {
+  file: string;
+  id: string;
+  loaderFile?: string;
+  middleware: string[];
+  path: string;
+  render?: string;
+  revalidate?: unknown;
+  shell?: string;
+  shellFile?: string;
+}
+
+function serializeRoutes(routes: RouteEntry[]) {
   return routes.map((route) => ({
     file: route.file,
     id: route.id,
@@ -114,11 +162,14 @@ function serializeRoutes(routes) {
   }));
 }
 
-async function detectApiMethods(server, root, file) {
+async function detectApiMethods(
+  server: ViteDevServer,
+  root: string,
+  file: string,
+): Promise<string[]> {
   const resolvedFile = resolve(root, `.${file}`);
   const source = readFileSync(resolvedFile, "utf-8");
 
-  // Use module evaluation first so re-exported handlers are reflected too.
   try {
     const module = await server.ssrLoadModule(file);
     return METHOD_ORDER.filter((method) => typeof module[method] === "function");
@@ -129,7 +180,7 @@ async function detectApiMethods(server, root, file) {
   }
 }
 
-function printInspectReport(report) {
+function printInspectReport(report: InspectReport): void {
   console.log(`Pracht inspect (${report.mode} mode)`);
 
   if (report.routes) {

package/src/commands/verify.ts

@@ -0,0 +1,37 @@
+import { defineCommand } from "citty";
+
+import { runVerification } from "../verification.js";
+
+export default defineCommand({
+  meta: {
+    name: "verify",
+    description: "Fast framework-aware verification",
+  },
+  args: {
+    changed: {
+      type: "boolean",
+      description: "Only check changed files",
+    },
+    json: {
+      type: "boolean",
+      description: "Output as JSON",
+    },
+  },
+  async run({ args }) {
+    const report = runVerification(process.cwd(), { changed: Boolean(args.changed) });
+
+    if (args.json) {
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      console.log(`Pracht verify (${report.mode} mode, ${report.scope} scope)`);
+      for (const check of report.checks) {
+        console.log(`${check.status.toUpperCase().padEnd(7)} ${check.message}`);
+      }
+      console.log(report.ok ? "\nNo blocking issues found." : "\nBlocking issues found.");
+    }
+
+    if (!report.ok) {
+      process.exitCode = 1;
+    }
+  },
+});

package/{lib/constants.js → src/constants.ts}

@@ -1,4 +1,4 @@
-export const DEFAULT_SECURITY_HEADERS = {
+export const DEFAULT_SECURITY_HEADERS: Record<string, string> = {
   "permissions-policy":
     "accelerometer=(), camera=(), geolocation=(), gyroscope=(), magnetometer=(), microphone=(), payment=(), usb=()",
   "referrer-policy": "strict-origin-when-cross-origin",
@@ -19,4 +19,14 @@ export const PROJECT_DEFAULTS = {
   shellsDir: "/src/shells",
 };
 
-export const HTTP_METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
+export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD" | "OPTIONS";
+
+export const HTTP_METHODS = new Set<HttpMethod>([
+  "GET",
+  "POST",
+  "PUT",
+  "PATCH",
+  "DELETE",
+  "HEAD",
+  "OPTIONS",
+]);

package/src/index.ts

@@ -0,0 +1,21 @@
+import { defineCommand, runMain } from "citty";
+
+import { VERSION } from "./constants.js";
+
+const main = defineCommand({
+  meta: {
+    name: "pracht",
+    version: VERSION,
+    description: "The pracht CLI",
+  },
+  subCommands: {
+    build: () => import("./commands/build.js").then((m) => m.default),
+    dev: () => import("./commands/dev.js").then((m) => m.default),
+    doctor: () => import("./commands/doctor.js").then((m) => m.default),
+    generate: () => import("./commands/generate.js").then((m) => m.default),
+    inspect: () => import("./commands/inspect.js").then((m) => m.default),
+    verify: () => import("./commands/verify.js").then((m) => m.default),
+  },
+});
+
+runMain(main);