@pracht/cli 1.1.5 → 1.2.1

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

@@ -1,40 +1,76 @@
-import { readFileSync } from "node:fs";
+import { existsSync, 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) {
@@ -49,9 +85,7 @@ export async function runInspect(root, { target = "all" } = {}) {
 
   if (project.mode === "manifest") {
     const manifestPath = resolveProjectPath(project.root, project.appFile);
-    try {
-      readFileSync(manifestPath, "utf-8");
-    } catch {
+    if (!existsSync(manifestPath)) {
       throw new Error(`App manifest is missing at ${project.appFile}.`);
     }
   }
@@ -66,7 +100,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 +110,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 +134,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 +160,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 +178,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/src/constants.ts

@@ -0,0 +1,26 @@
+import type { HttpMethod } from "@pracht/core";
+
+export type { HttpMethod };
+
+export const VERSION = "0.0.0";
+
+export const PROJECT_DEFAULTS = {
+  apiDir: "/src/api",
+  appFile: "/src/routes.ts",
+  middlewareDir: "/src/middleware",
+  pagesDefaultRender: "ssr",
+  pagesDir: "",
+  routesDir: "/src/routes",
+  serverDir: "/src/server",
+  shellsDir: "/src/shells",
+};
+
+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);

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

@@ -1,4 +1,4 @@
-export function ensureCoreNamedImport(source, name) {
+export function ensureCoreNamedImport(source: string, name: string): string {
   const match = source.match(/import\s*\{([^}]+)\}\s*from\s*["']@pracht\/core["'];?/);
   if (!match) {
     return `import { ${name} } from "@pracht/core";\n${source}`;
@@ -15,7 +15,7 @@ export function ensureCoreNamedImport(source, name) {
   return source.replace(match[0], `import { ${names.join(", ")} } from "@pracht/core";`);
 }
 
-export function upsertObjectEntry(source, key, entry) {
+export function upsertObjectEntry(source: string, key: string, entry: string): string {
   const property = findNamedBlock(source, key, "{", "}");
   if (!property) {
     const routesMatch = source.match(/^(\s*)routes\s*:/m);
@@ -31,7 +31,7 @@ export function upsertObjectEntry(source, key, entry) {
   return insertBlockEntry(source, property, entry);
 }
 
-export function insertArrayItem(source, key, item) {
+export function insertArrayItem(source: string, key: string, item: string): string {
   const property = findNamedBlock(source, key, "[", "]");
   if (!property) {
     throw new Error(`Could not find "${key}" in the app manifest.`);
@@ -40,7 +40,7 @@ export function insertArrayItem(source, key, item) {
   return insertBlockEntry(source, property, item);
 }
 
-export function toManifestModulePath(manifestPath, targetFilePath) {
+export function toManifestModulePath(manifestPath: string, targetFilePath: string): string {
   const relativePath = targetFilePath
     .replaceAll("\\", "/")
     .replace(manifestPath.replaceAll("\\", "/").replace(/\/[^/]+$/, ""), "")
@@ -49,11 +49,14 @@ export function toManifestModulePath(manifestPath, targetFilePath) {
   return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
 }
 
-export function extractRegistryEntries(source, key) {
+export function extractRegistryEntries(
+  source: string,
+  key: string,
+): { name: string; path: string }[] {
   const block = findNamedBlock(source, key, "{", "}");
   if (!block) return [];
   const inner = source.slice(block.openIndex + 1, block.closeIndex);
-  const entries = [];
+  const entries: { name: string; path: string }[] = [];
   const pattern =
     /([A-Za-z0-9_-]+)\s*:\s*(?:(["'`])([^"'`]+)\2|\(\)\s*=>\s*import\(\s*(["'`])([^"'`]+)\4\s*\))/g;
 
@@ -64,15 +67,21 @@ export function extractRegistryEntries(source, key) {
   return entries;
 }
 
-export function extractRelativeModulePaths(source) {
-  const results = new Set();
+export function extractRelativeModulePaths(source: string): Set<string> {
+  const results = new Set<string>();
   for (const match of source.matchAll(/["'`]((?:\.\.\/|\.\/)[^"'`]+)["'`]/g)) {
     results.add(match[1]);
   }
   return results;
 }
 
-function insertBlockEntry(source, block, entry) {
+interface BlockLocation {
+  closeIndex: number;
+  indent: string;
+  openIndex: number;
+}
+
+function insertBlockEntry(source: string, block: BlockLocation, entry: string): string {
   const inner = source.slice(block.openIndex + 1, block.closeIndex);
   const closingIndent = block.indent;
   const childIndent = `${closingIndent}  `;
@@ -87,7 +96,12 @@ function insertBlockEntry(source, block, entry) {
   return `${source.slice(0, block.closeIndex)}${insertPrefix}\n${indentMultiline(entry, childIndent)}\n${closingIndent}${source.slice(block.closeIndex)}`;
 }
 
-function findNamedBlock(source, key, openChar, closeChar) {
+function findNamedBlock(
+  source: string,
+  key: string,
+  openChar: string,
+  closeChar: string,
+): BlockLocation | null {
   const pattern = new RegExp(`^([ \\t]*)${key}\\s*:\\s*\\${openChar}`, "m");
   const match = source.match(pattern);
   if (!match || match.index == null) {
@@ -103,9 +117,14 @@ function findNamedBlock(source, key, openChar, closeChar) {
   };
 }
 
-function findMatchingDelimiter(source, openIndex, openChar, closeChar) {
+function findMatchingDelimiter(
+  source: string,
+  openIndex: number,
+  openChar: string,
+  closeChar: string,
+): number {
   let depth = 0;
-  let quoteChar = null;
+  let quoteChar: string | null = null;
   let escaping = false;
 
   for (let index = openIndex; index < source.length; index += 1) {
@@ -139,7 +158,7 @@ function findMatchingDelimiter(source, openIndex, openChar, closeChar) {
   throw new Error(`Could not find matching ${closeChar} for ${openChar}.`);
 }
 
-function indentMultiline(value, indent) {
+function indentMultiline(value: string, indent: string): string {
   return value
     .split("\n")
     .map((line) => `${indent}${line}`)

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

@@ -1,16 +1,33 @@
 import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { basename, dirname, relative, resolve } from "node:path";
 
-import { ensureTrailingNewline } from "./cli.js";
+import { ensureTrailingNewline } from "./utils.js";
 import { PROJECT_DEFAULTS } from "./constants.js";
 
-export function readProjectConfig(root) {
+export interface ProjectConfig {
+  apiDir: string;
+  appFile: string;
+  configFile: string | null;
+  hasPrachtPlugin: boolean;
+  middlewareDir: string;
+  mode: "manifest" | "pages";
+  pagesDefaultRender: string;
+  pagesDir: string;
+  rawConfig: string;
+  root: string;
+  routesDir: string;
+  serverDir: string;
+  shellsDir: string;
+}
+
+export function readProjectConfig(root: string): ProjectConfig {
   const configFile = findConfigFile(root);
   const rawConfig = configFile ? readFileSync(configFile, "utf-8") : "";
-  const config = {
+  const config: Record<string, unknown> = {
     ...PROJECT_DEFAULTS,
     configFile,
     hasPrachtPlugin: /\bpracht\s*\(/.test(rawConfig),
+    mode: "manifest" as const,
     rawConfig,
     root,
   };
@@ -23,45 +40,56 @@ export function readProjectConfig(root) {
   }
 
   config.mode = config.pagesDir ? "pages" : "manifest";
-  return config;
+  return config as unknown as ProjectConfig;
 }
 
-export function resolveProjectPath(root, configPath) {
+export function resolveProjectPath(root: string, configPath: string): string {
   return resolve(root, `.${configPath}`);
 }
 
-export function resolveScopedFile(root, configDir, fileName) {
+export function resolveScopedFile(root: string, configDir: string, fileName: string): string {
   return resolve(resolveProjectPath(root, configDir), fileName);
 }
 
-export function resolveRouteModulePath(project, routePath, extension) {
-  const segments = segmentsFromRoutePath(routePath);
+export function resolveRouteModulePath(
+  project: ProjectConfig,
+  routePath: string,
+  extension: string,
+): { absolutePath: string; relativePath: string } {
+  const segments = segmentsFromPath(routePath);
   const relativePath =
     segments.length === 0 ? `index${extension}` : `${segments.join("/")}${extension}`;
   const absolutePath = resolve(resolveProjectPath(project.root, project.routesDir), relativePath);
   return { absolutePath, relativePath };
 }
 
-export function resolvePagesRouteModulePath(project, routePath, extension) {
-  const segments = segmentsFromRoutePath(routePath);
+export function resolvePagesRouteModulePath(
+  project: ProjectConfig,
+  routePath: string,
+  extension: string,
+): { absolutePath: string; relativePath: string } {
+  const segments = segmentsFromPath(routePath);
   const relativePath =
     segments.length === 0 ? `index${extension}` : `${segments.join("/")}${extension}`;
   const absolutePath = resolve(resolveProjectPath(project.root, project.pagesDir), relativePath);
   return { absolutePath, relativePath };
 }
 
-export function resolveApiModulePath(project, endpointPath) {
-  const segments = segmentsFromApiPath(endpointPath);
+export function resolveApiModulePath(
+  project: ProjectConfig,
+  endpointPath: string,
+): { absolutePath: string; relativePath: string } {
+  const segments = segmentsFromPath(endpointPath);
   const relativePath = segments.length === 0 ? "index.ts" : `${segments.join("/")}.ts`;
   const absolutePath = resolve(resolveProjectPath(project.root, project.apiDir), relativePath);
   return { absolutePath, relativePath };
 }
 
-export function displayPath(root, filePath) {
+export function displayPath(root: string, filePath: string): string {
   return relative(root, filePath) || ".";
 }
 
-export function writeGeneratedFile(filePath, source) {
+export function writeGeneratedFile(filePath: string, source: string): void {
   if (existsSync(filePath)) {
     throw new Error(`Refusing to overwrite existing file ${filePath}.`);
   }
@@ -70,14 +98,14 @@ export function writeGeneratedFile(filePath, source) {
   writeFileSync(filePath, ensureTrailingNewline(source), "utf-8");
 }
 
-export function assertFileExists(filePath, message) {
+export function assertFileExists(filePath: string, message: string): void {
   if (!existsSync(filePath)) {
     throw new Error(message);
   }
 }
 
-export function listFilesRecursively(dir) {
-  const files = [];
+export function listFilesRecursively(dir: string): string[] {
+  const files: string[] = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const fullPath = resolve(dir, entry.name);
     if (entry.isDirectory()) {
@@ -89,11 +117,11 @@ export function listFilesRecursively(dir) {
   return files;
 }
 
-export function hasPagesAppShell(filePath) {
+export function hasPagesAppShell(filePath: string): boolean {
   return /^_app\.(ts|tsx|js|jsx)$/.test(basename(filePath));
 }
 
-function findConfigFile(root) {
+function findConfigFile(root: string): string | null {
   for (const name of [
     "vite.config.ts",
     "vite.config.mts",
@@ -108,31 +136,20 @@ function findConfigFile(root) {
   return null;
 }
 
-function readQuotedConfigValue(source, key) {
+function readQuotedConfigValue(source: string, key: string): string | null {
   if (!source) return null;
   const pattern = new RegExp(`${key}\\s*:\\s*(["'\\\`])([^"'\\\`]+)\\1`);
   const match = source.match(pattern);
   return match ? match[2] : null;
 }
 
-function normalizeConfigPath(value) {
+function normalizeConfigPath(value: string): string {
   if (!value) return value;
   return value.startsWith("/") ? value : `/${value}`;
 }
 
-function segmentsFromRoutePath(routePath) {
-  return routePath
-    .split("/")
-    .filter(Boolean)
-    .map((segment) => {
-      if (segment.startsWith(":")) return `[${segment.slice(1)}]`;
-      if (segment === "*") return "[...slug]";
-      return segment;
-    });
-}
-
-function segmentsFromApiPath(endpointPath) {
-  return endpointPath
+function segmentsFromPath(path: string): string[] {
+  return path
     .split("/")
     .filter(Boolean)
     .map((segment) => {

package/src/utils.ts

@@ -0,0 +1,72 @@
+import { HTTP_METHODS, type HttpMethod } from "./constants.js";
+
+export function quote(value: string): string {
+  return JSON.stringify(value);
+}
+
+export function ensureTrailingNewline(value: string): string {
+  return value.endsWith("\n") ? value : `${value}\n`;
+}
+
+export function parseCommaList(value: string | string[] | boolean | undefined): string[] {
+  if (!value || typeof value === "boolean") 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: string | string[] | boolean | undefined): HttpMethod[] {
+  const methods = parseCommaList(value);
+  const normalized =
+    methods.length === 0
+      ? (["GET"] as HttpMethod[])
+      : methods.map((entry) => entry.toUpperCase() as HttpMethod);
+
+  for (const method of normalized) {
+    if (!HTTP_METHODS.has(method)) {
+      throw new Error(`Unsupported HTTP method "${method}".`);
+    }
+  }
+
+  return [...new Set(normalized)];
+}
+
+export function requireEnum(
+  value: string | undefined,
+  key: string,
+  allowed: string[],
+  fallback: string,
+): string {
+  const val = value ?? fallback;
+  if (!allowed.includes(val)) {
+    throw new Error(`Invalid value for --${key}. Expected one of ${allowed.join(", ")}.`);
+  }
+  return val;
+}
+
+export function requirePositiveInteger(
+  value: string | undefined,
+  key: string,
+  fallback: number,
+): number {
+  const parsed = value == null ? fallback : Number.parseInt(value, 10);
+  if (!Number.isInteger(parsed) || parsed <= 0) {
+    throw new Error(`--${key} must be a positive integer.`);
+  }
+  return parsed;
+}
+
+export function handleCliError(error: unknown, { json }: { json: boolean }): never {
+  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);
+}