@pracht/cli 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @pracht/cli
 
+## 1.1.0
+
+### Minor Changes
+
+- [#70](https://github.com/JoviDeCroock/pracht/pull/70) [`ddd50a1`](https://github.com/JoviDeCroock/pracht/commit/ddd50a1edf82a6884881a91ce7172d87ec571cde) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add `pracht inspect` as a machine-readable app graph command.
+
+  The CLI can now emit resolved routes, API handlers, and build metadata via:
+
+  - `pracht inspect routes --json`
+  - `pracht inspect api --json`
+  - `pracht inspect build --json`
+  - `pracht inspect --json`
+
+### Patch Changes
+
+- Updated dependencies [[`0d33c3d`](https://github.com/JoviDeCroock/pracht/commit/0d33c3dee00bf3940dc56bef3a171249a3d73e21), [`ba1eaea`](https://github.com/JoviDeCroock/pracht/commit/ba1eaeaf68ab63b47b08411fbdafae2fd98e5f09)]:
+  - @pracht/core@0.2.0
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -68,6 +68,17 @@ Create an API route under `src/api/`.
 pracht generate api --path /health --methods GET,POST
 ```
 
+### `pracht inspect`
+
+Inspect the resolved app graph. Use `--json` for agent/tool consumption.
+
+```bash
+pracht inspect --json
+pracht inspect routes --json
+pracht inspect api --json
+pracht inspect build --json
+```
+
 ### `pracht doctor`
 
 Validate the local app wiring across the whole project. Use `--json` for

package/bin/pracht.js

@@ -5,6 +5,7 @@ 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 { inspectCommand } from "../lib/commands/inspect.js";
 import { handleCliError, printHelp } from "../lib/cli.js";
 import { VERSION } from "../lib/constants.js";
 
@@ -28,6 +29,7 @@ const handlers = {
   doctor: doctorCommand,
   generate: generateCommand,
   verify: verifyCommand,
+  inspect: inspectCommand,
 };
 
 if (!(command in handlers)) {

package/lib/build-metadata.js

@@ -0,0 +1,73 @@
+import { existsSync, readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const MANIFEST_PATHS = ["dist/client/.vite/manifest.json", "dist/.vite/manifest.json"];
+
+export function readClientBuildAssets(root = process.cwd()) {
+  const manifestPath = MANIFEST_PATHS.map((candidate) => resolve(root, candidate)).find((path) =>
+    existsSync(path),
+  );
+
+  if (!manifestPath) {
+    return {
+      clientEntryUrl: null,
+      cssManifest: {},
+      jsManifest: {},
+    };
+  }
+
+  const rawManifest = readFileSync(manifestPath, "utf-8");
+  const manifest = JSON.parse(rawManifest);
+  const clientEntry = manifest["virtual:pracht/client"];
+
+  function collectTransitiveDeps(key) {
+    const css = new Set();
+    const js = new Set();
+    const visited = new Set();
+
+    function collect(currentKey) {
+      if (visited.has(currentKey)) return;
+      visited.add(currentKey);
+
+      const entry = manifest[currentKey];
+      if (!entry) return;
+
+      for (const cssFile of entry.css ?? []) {
+        css.add(cssFile);
+      }
+
+      js.add(entry.file);
+
+      for (const importedKey of entry.imports ?? []) {
+        collect(importedKey);
+      }
+    }
+
+    collect(key);
+    return {
+      css: [...css],
+      js: [...js],
+    };
+  }
+
+  const cssManifest = {};
+  const jsManifest = {};
+
+  for (const [key, entry] of Object.entries(manifest)) {
+    if (!entry.src) continue;
+
+    const deps = collectTransitiveDeps(key);
+    if (deps.css.length > 0) {
+      cssManifest[key] = deps.css.map((file) => `/${file}`);
+    }
+    if (deps.js.length > 0) {
+      jsManifest[key] = deps.js.map((file) => `/${file}`);
+    }
+  }
+
+  return {
+    clientEntryUrl: clientEntry ? `/${clientEntry.file}` : null,
+    cssManifest,
+    jsManifest,
+  };
+}

package/lib/cli.js

@@ -8,6 +8,7 @@ Usage:
   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:
@@ -18,6 +19,13 @@ Generate kinds:
 `);
 }
 
+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]

package/lib/commands/build.js

@@ -1,16 +1,9 @@
-import {
-  cpSync,
-  existsSync,
-  mkdirSync,
-  readFileSync,
-  readdirSync,
-  rmSync,
-  writeFileSync,
-} from "node:fs";
+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() {
@@ -57,43 +50,11 @@ export async function buildCommand() {
   if (existsSync(serverEntry)) {
     const serverMod = await import(serverEntry);
     const { prerenderApp } = serverMod;
-    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;
-
-    function collectTransitiveCss(key) {
-      const css = new Set();
-      const visited = new Set();
-
-      function collect(currentKey) {
-        if (visited.has(currentKey)) return;
-        visited.add(currentKey);
-        const entry = viteManifest[currentKey];
-        if (!entry) return;
-        for (const cssFile of entry.css ?? []) css.add(cssFile);
-        for (const importedKey of entry.imports ?? []) collect(importedKey);
-      }
-
-      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((file) => `/${file}`);
-      }
-    }
+    const { clientEntryUrl, cssManifest } = readClientBuildAssets(root);
 
     const { pages, isgManifest } = await prerenderApp({
       app: serverMod.resolvedApp,
-      clientEntryUrl,
+      clientEntryUrl: clientEntryUrl ?? undefined,
       cssManifest,
       registry: serverMod.registry,
       withISGManifest: true,

package/lib/commands/inspect.js

@@ -0,0 +1,163 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { createServer } from "vite";
+
+import { handleCliError, parseFlags, printInspectHelp, requireOptionalString } from "../cli.js";
+import { readClientBuildAssets } from "../build-metadata.js";
+import { HTTP_METHODS } 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 report = await runInspect(process.cwd(), { target });
+
+  if (options.json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+
+  printInspectReport(report);
+}
+
+export async function runInspect(root, { target = "all" } = {}) {
+  const project = readProjectConfig(root);
+
+  if (!project.configFile) {
+    throw new Error(
+      "Missing vite config. `pracht inspect` requires a project with pracht configured.",
+    );
+  }
+
+  if (!project.hasPrachtPlugin) {
+    throw new Error("vite.config does not appear to register the pracht plugin.");
+  }
+
+  if (project.mode === "manifest") {
+    const manifestPath = resolveProjectPath(project.root, project.appFile);
+    try {
+      readFileSync(manifestPath, "utf-8");
+    } catch {
+      throw new Error(`App manifest is missing at ${project.appFile}.`);
+    }
+  }
+
+  const server = await createServer({
+    root,
+    logLevel: "silent",
+    server: {
+      middlewareMode: true,
+    },
+  });
+
+  try {
+    const serverModule = await server.ssrLoadModule("virtual:pracht/server");
+    const report = {
+      mode: project.mode,
+    };
+
+    if (target === "routes" || target === "all") {
+      report.routes = serializeRoutes(serverModule.resolvedApp.routes);
+    }
+
+    if (target === "api" || target === "all") {
+      report.api = await Promise.all(
+        serverModule.apiRoutes.map(async (route) => ({
+          file: route.file,
+          methods: await detectApiMethods(server, root, route.file),
+          path: route.path,
+        })),
+      );
+    }
+
+    if (target === "build" || target === "all") {
+      const buildAssets = readClientBuildAssets(root);
+      report.build = {
+        adapterTarget: serverModule.buildTarget,
+        clientEntryUrl: buildAssets.clientEntryUrl,
+        cssManifest: buildAssets.cssManifest,
+        jsManifest: buildAssets.jsManifest,
+      };
+    }
+
+    return report;
+  } finally {
+    await server.close();
+  }
+}
+
+function serializeRoutes(routes) {
+  return routes.map((route) => ({
+    file: route.file,
+    id: route.id,
+    loaderFile: route.loaderFile ?? null,
+    middleware: route.middleware,
+    path: route.path,
+    render: route.render ?? null,
+    revalidate: route.revalidate ?? null,
+    shell: route.shell ?? null,
+    shellFile: route.shellFile ?? null,
+  }));
+}
+
+async function detectApiMethods(server, root, file) {
+  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");
+  } catch {
+    return METHOD_ORDER.filter((method) =>
+      new RegExp(`export\\s+(?:async\\s+)?(?:function|const|let|var)\\s+${method}\\b`).test(source),
+    );
+  }
+}
+
+function printInspectReport(report) {
+  console.log(`Pracht inspect (${report.mode} mode)`);
+
+  if (report.routes) {
+    console.log("\nRoutes");
+    for (const route of report.routes) {
+      console.log(
+        `  ${route.path}  id=${route.id}  render=${route.render ?? "n/a"}  file=${route.file}`,
+      );
+    }
+  }
+
+  if (report.api) {
+    console.log("\nAPI");
+    if (report.api.length === 0) {
+      console.log("  No API routes found.");
+    } else {
+      for (const route of report.api) {
+        const methods = route.methods.length > 0 ? route.methods.join(",") : "none";
+        console.log(`  ${route.path}  methods=${methods}  file=${route.file}`);
+      }
+    }
+  }
+
+  if (report.build) {
+    console.log("\nBuild");
+    console.log(`  adapterTarget=${report.build.adapterTarget}`);
+    console.log(`  clientEntryUrl=${report.build.clientEntryUrl ?? "null"}`);
+    console.log(`  cssManifestKeys=${Object.keys(report.build.cssManifest).length}`);
+    console.log(`  jsManifestKeys=${Object.keys(report.build.jsManifest).length}`);
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/cli",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/cli",
   "bugs": {
     "url": "https://github.com/JoviDeCroock/pracht/issues"
@@ -18,6 +18,6 @@
     "provenance": true
   },
   "dependencies": {
-    "@pracht/core": "0.1.0"
+    "@pracht/core": "0.2.0"
   }
 }

package/test/pracht-cli.test.js

@@ -2,11 +2,16 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { tmpdir } from "node:os";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath, pathToFileURL } from "node:url";
 
 import { afterEach, describe, expect, it } from "vitest";
 
 const cliPath = fileURLToPath(new URL("../bin/pracht.js", import.meta.url));
+const repoRoot = resolve(dirname(cliPath), "../../..");
+const repoTempRoot = resolve(dirname(cliPath), "../test/.tmp");
+const coreImportPath = resolve(repoRoot, "packages/framework/src/index.ts");
+const nodeAdapterImportPath = resolve(repoRoot, "packages/adapter-node/src/index.ts");
+const vitePluginImportPath = resolve(repoRoot, "packages/vite-plugin/src/index.ts");
 const tempDirs = [];
 
 afterEach(() => {
@@ -266,6 +271,69 @@ export const app = defineApp({
     ).toBe(true);
   });
 
+  it("inspects resolved routes, api handlers, and build metadata as JSON", () => {
+    const appDir = createRepoTempDir("pracht-cli-inspect-");
+    writeInspectableManifestApp(appDir);
+
+    const routes = JSON.parse(runCli(["inspect", "routes", "--json"], { cwd: appDir }).stdout);
+    const api = JSON.parse(runCli(["inspect", "api", "--json"], { cwd: appDir }).stdout);
+    const build = JSON.parse(runCli(["inspect", "build", "--json"], { cwd: appDir }).stdout);
+    const all = JSON.parse(runCli(["inspect", "--json"], { cwd: appDir }).stdout);
+
+    expect(routes).toEqual({
+      mode: "manifest",
+      routes: [
+        {
+          file: "./routes/dashboard.tsx",
+          id: "dashboard",
+          loaderFile: "./server/dashboard-loader.ts",
+          middleware: ["auth"],
+          path: "/dashboard",
+          render: "isg",
+          revalidate: {
+            kind: "time",
+            seconds: 60,
+          },
+          shell: "app",
+          shellFile: "./shells/app.tsx",
+        },
+      ],
+    });
+
+    expect(api).toEqual({
+      api: [
+        {
+          file: "/src/api/health.ts",
+          methods: ["GET", "POST"],
+          path: "/api/health",
+        },
+      ],
+      mode: "manifest",
+    });
+
+    expect(build).toEqual({
+      build: {
+        adapterTarget: "node",
+        clientEntryUrl: "/assets/client.js",
+        cssManifest: {
+          "src/routes/dashboard.tsx": ["/assets/dashboard.css"],
+          "src/shells/app.tsx": ["/assets/app.css"],
+        },
+        jsManifest: {
+          "src/routes/dashboard.tsx": ["/assets/dashboard.js", "/assets/vendor.js"],
+          "src/shells/app.tsx": ["/assets/app.js", "/assets/vendor.js"],
+        },
+      },
+      mode: "manifest",
+    });
+
+    expect(all).toEqual({
+      ...routes,
+      ...api,
+      ...build,
+    });
+  });
+
   it("scaffolds pages-router routes without touching a manifest", () => {
     const appDir = createTempDir("pracht-cli-pages-");
     writePagesApp(appDir);
@@ -290,6 +358,13 @@ function createTempDir(prefix) {
   return dir;
 }
 
+function createRepoTempDir(prefix) {
+  mkdirSync(repoTempRoot, { recursive: true });
+  const dir = mkdtempSync(join(repoTempRoot, prefix));
+  tempDirs.push(dir);
+  return dir;
+}
+
 function runCli(args, { cwd }) {
   return {
     stdout: execFileSync(process.execPath, [cliPath, ...args], {
@@ -378,6 +453,149 @@ export const app = defineApp({
   );
 }
 
+function writeInspectableManifestApp(appDir) {
+  const vitePluginImport = pathToFileURL(vitePluginImportPath).href;
+
+  writeProjectFile(
+    appDir,
+    "package.json",
+    JSON.stringify(
+      {
+        name: "fixture-inspect-app",
+        private: true,
+        type: "module",
+      },
+      null,
+      2,
+    ),
+  );
+  writeProjectFile(
+    appDir,
+    "vite.config.ts",
+    `import { defineConfig } from "vite";
+import { pracht } from ${JSON.stringify(vitePluginImport)};
+
+export default defineConfig(async () => ({
+  plugins: [await pracht()],
+  resolve: {
+    alias: {
+      "@pracht/adapter-node": ${JSON.stringify(nodeAdapterImportPath)},
+      "@pracht/core": ${JSON.stringify(coreImportPath)},
+    },
+  },
+}));
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/routes.ts",
+    `import { defineApp, group, route, timeRevalidate } from "@pracht/core";
+
+export const app = defineApp({
+  shells: {
+    app: () => import("./shells/app.tsx"),
+  },
+  middleware: {
+    auth: () => import("./middleware/auth.ts"),
+  },
+  routes: [
+    group({ shell: "app", middleware: ["auth"] }, [
+      route("/dashboard", {
+        component: () => import("./routes/dashboard.tsx"),
+        loader: () => import("./server/dashboard-loader.ts"),
+        render: "isg",
+        revalidate: timeRevalidate(60),
+      }),
+    ]),
+  ],
+});
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/routes/dashboard.tsx",
+    `import type { RouteComponentProps } from "@pracht/core";
+
+export function Component({ data }: RouteComponentProps) {
+  return <main>{JSON.stringify(data)}</main>;
+}
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/server/dashboard-loader.ts",
+    `import type { LoaderArgs } from "@pracht/core";
+
+export async function loader(_args: LoaderArgs) {
+  return { ok: true };
+}
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/shells/app.tsx",
+    `import type { ShellProps } from "@pracht/core";
+
+export function Shell({ children }: ShellProps) {
+  return <div>{children}</div>;
+}
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/middleware/auth.ts",
+    `import type { MiddlewareFn } from "@pracht/core";
+
+export const middleware: MiddlewareFn = async () => {
+  return;
+};
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "src/api/health.ts",
+    `import type { BaseRouteArgs } from "@pracht/core";
+
+export function GET(_args: BaseRouteArgs) {
+  return Response.json({ ok: true });
+}
+
+export async function POST(_args: BaseRouteArgs) {
+  return Response.json({ created: true }, { status: 201 });
+}
+`,
+  );
+  writeProjectFile(
+    appDir,
+    "dist/client/.vite/manifest.json",
+    JSON.stringify(
+      {
+        "virtual:pracht/client": {
+          file: "assets/client.js",
+          imports: ["assets/vendor.js"],
+        },
+        "src/routes/dashboard.tsx": {
+          css: ["assets/dashboard.css"],
+          file: "assets/dashboard.js",
+          imports: ["assets/vendor.js"],
+          src: "src/routes/dashboard.tsx",
+        },
+        "src/shells/app.tsx": {
+          css: ["assets/app.css"],
+          file: "assets/app.js",
+          imports: ["assets/vendor.js"],
+          src: "src/shells/app.tsx",
+        },
+        "assets/vendor.js": {
+          file: "assets/vendor.js",
+        },
+      },
+      null,
+      2,
+    ),
+  );
+}
+
 function writePagesApp(appDir) {
   writeProjectFile(
     appDir,