@pracht/cli 1.3.3 → 1.5.0

package/CHANGELOG.md

@@ -1,5 +1,73 @@
 # @pracht/cli
 
+## 1.5.0
+
+### Minor Changes
+
+- [#153](https://github.com/JoviDeCroock/pracht/pull/153) [`39860bd`](https://github.com/JoviDeCroock/pracht/commit/39860bd31e8559916d8f81ffa6122ac4cf1cffd1) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - **Breaking:** Middleware is now wrap-around (Hono/Koa/Astro shape). The
+  `MiddlewareFn` signature changes from `(args) => MiddlewareResult` to
+  `(args, next) => Promise<Response>`.
+
+  ```ts
+  // Before
+  export const middleware: MiddlewareFn = async ({ request }) => {
+    if (!hasSession(request)) return { redirect: "/login" };
+    return { context: { user: "jovi" } };
+  };
+
+  // After
+  import { redirect, type MiddlewareFn } from "@pracht/core";
+
+  export const middleware: MiddlewareFn = async (
+    { context, request },
+    next
+  ) => {
+    if (!hasSession(request)) return redirect("/login");
+    (context as { user?: string }).user = "jovi";
+    return next();
+  };
+  ```
+
+  Why: middleware can now wrap `try / catch / finally` around the rest of the
+  request, which is the standard shape for tracing, logging, and observability
+  libraries (Honeycomb, OpenTelemetry, Sentry). It also matches what users
+  arriving from honox / Hono / Astro / SvelteKit / Koa expect.
+
+  Migration notes:
+
+  - Replace `return { redirect: "/path" }` with `return redirect("/path")`
+    using the new `redirect` helper exported from `@pracht/core`.
+  - Replace `return { context: { ... } }` with direct mutation of
+    `args.context`. Context is shared by reference between middleware and
+    the loader/handler.
+  - Replace bare `return` (continue) with `return next()`.
+  - Middleware that returns a `Response` directly still works as a
+    short-circuit.
+  - The `MiddlewareResult` type is removed; `MiddlewareNext` is exported.
+  - One `AbortSignal` is now shared per request across all middleware and
+    the loader/handler instead of a fresh 30s timer per phase. This makes
+    long-running middleware count toward the same overall budget as the
+    loader/handler, which matches how most users reason about per-request
+    timeouts.
+
+  The CLI's `pracht generate middleware` scaffold emits the new signature.
+
+### Patch Changes
+
+- Updated dependencies [[`39860bd`](https://github.com/JoviDeCroock/pracht/commit/39860bd31e8559916d8f81ffa6122ac4cf1cffd1), [`39860bd`](https://github.com/JoviDeCroock/pracht/commit/39860bd31e8559916d8f81ffa6122ac4cf1cffd1), [`51d0de1`](https://github.com/JoviDeCroock/pracht/commit/51d0de12bcda8a1cadd3749f56f03bac2e95c3a6), [`f4763b1`](https://github.com/JoviDeCroock/pracht/commit/f4763b13dc85c7310d9a737b77b708c03a61b57c)]:
+  - @pracht/core@0.8.0
+
+## 1.4.0
+
+### Minor Changes
+
+- [#139](https://github.com/JoviDeCroock/pracht/pull/139) [`97594bd`](https://github.com/JoviDeCroock/pracht/commit/97594bd57b14fd5b527de647ba254b77f77912ca) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add typed route href helpers, `<Link route="...">`, route-object `useNavigate()`, and `pracht typegen` for generated route id/param declarations.
+
+### Patch Changes
+
+- Updated dependencies [[`5578791`](https://github.com/JoviDeCroock/pracht/commit/5578791b3abd6c808f5af78d88224667f483b32c), [`5938cb5`](https://github.com/JoviDeCroock/pracht/commit/5938cb56dd053fc8725efae0b7392dd65866b37b), [`97594bd`](https://github.com/JoviDeCroock/pracht/commit/97594bd57b14fd5b527de647ba254b77f77912ca)]:
+  - @pracht/core@0.7.0
+
 ## 1.3.3
 
 ### Patch Changes

package/README.md

@@ -79,6 +79,17 @@ pracht inspect api --json
 pracht inspect build --json
 ```
 
+### `pracht typegen`
+
+Generate `src/pracht-routes.d.ts` and `src/pracht-routes.ts` from the resolved
+route graph for typed `<Link>`, route-object `useNavigate()`, and `href()`
+helpers. Use `--check` in CI to fail when generated files are stale.
+
+```bash
+pracht typegen
+pracht typegen --check
+```
+
 ### `pracht doctor`
 
 Validate the local app wiring across the whole project. Use `--json` for

package/dist/{generate-V7pQExlW.mjs → generate-DTMte0kd.mjs}

@@ -71,8 +71,8 @@ function buildMiddlewareModuleSource() {
 	return [
 		"import type { MiddlewareFn } from \"@pracht/core\";",
 		"",
-		"export const middleware: MiddlewareFn = async (_args) => {",
-		"  return;",
+		"export const middleware: MiddlewareFn = async (_args, next) => {",
+		"  return next();",
 		"};",
 		""
 	].join("\n");

package/dist/index.mjs

@@ -44,9 +44,10 @@ runMain(defineCommand({
 		build: () => import("./build-B7_6RUBf.mjs").then((m) => m.default),
 		dev: () => import("./dev-BCFe3g38.mjs").then((m) => m.default),
 		doctor: () => import("./doctor-DyOWEA42.mjs").then((m) => m.default),
-		generate: () => import("./generate-V7pQExlW.mjs").then((m) => m.default),
-		inspect: () => import("./inspect-CFD3-dna.mjs").then((m) => m.default),
-		verify: () => import("./verify-D0pGwcyf.mjs").then((m) => m.default)
+		generate: () => import("./generate-DTMte0kd.mjs").then((m) => m.default),
+		inspect: () => import("./inspect-WF08uLOl.mjs").then((m) => m.default),
+		typegen: () => import("./typegen-Bl4fYQIy.mjs").then((m) => m.default),
+		verify: () => import("./verify-FwVbdlxh.mjs").then((m) => m.default)
 	}
 }));
 //#endregion

package/dist/{inspect-CFD3-dna.mjs → inspect-WF08uLOl.mjs}

@@ -120,4 +120,4 @@ function printInspectReport(report) {
 	}
 }
 //#endregion
-export { inspect_default as default };
+export { inspect_default as default, runInspect };

package/dist/typegen-Bl4fYQIy.mjs

@@ -0,0 +1,172 @@
+import { f as ensureTrailingNewline, n as displayPath, p as handleCliError } from "./project-voPTS9UC.mjs";
+import { runInspect } from "./inspect-WF08uLOl.mjs";
+import { defineCommand } from "citty";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, isAbsolute, relative, resolve } from "node:path";
+//#region src/commands/typegen.ts
+const DEFAULT_DECLARATION_OUT = "src/pracht-routes.d.ts";
+const DEFAULT_RUNTIME_OUT = "src/pracht-routes.ts";
+var typegen_default = defineCommand({
+	meta: {
+		name: "typegen",
+		description: "Generate typed route declarations and href helpers"
+	},
+	args: {
+		out: {
+			type: "string",
+			description: `Declaration output path (default: ${DEFAULT_DECLARATION_OUT})`
+		},
+		"runtime-out": {
+			type: "string",
+			description: `Runtime href helper output path (default: ${DEFAULT_RUNTIME_OUT})`
+		},
+		check: {
+			type: "boolean",
+			description: "Check whether generated route files are up to date without writing"
+		},
+		json: {
+			type: "boolean",
+			description: "Output as JSON"
+		}
+	},
+	async run({ args }) {
+		const json = Boolean(args.json);
+		try {
+			const result = await runTypegen({
+				check: Boolean(args.check),
+				declarationOut: typeof args.out === "string" ? args.out : DEFAULT_DECLARATION_OUT,
+				root: process.cwd(),
+				runtimeOut: typeof args["runtime-out"] === "string" ? args["runtime-out"] : DEFAULT_RUNTIME_OUT
+			});
+			if (json) {
+				console.log(JSON.stringify({
+					ok: true,
+					...result
+				}, null, 2));
+				return;
+			}
+			if (result.check) {
+				console.log("Generated route files are up to date.");
+				return;
+			}
+			console.log("Generated typed routes:");
+			for (const file of result.files) console.log(`  ${file}`);
+		} catch (error) {
+			handleCliError(error, { json });
+		}
+	}
+});
+async function runTypegen(options) {
+	const report = await runInspect(options.root, { target: "routes" });
+	const routes = report.routes ?? [];
+	validateRoutes(routes);
+	const declarationPath = resolveOutputPath(options.root, options.declarationOut);
+	const runtimePath = resolveOutputPath(options.root, options.runtimeOut);
+	const outputs = [{
+		path: declarationPath,
+		source: buildDeclarationSource(routes)
+	}, {
+		path: runtimePath,
+		source: buildRuntimeSource(routes)
+	}];
+	if (options.check) {
+		const stale = outputs.filter((output) => !fileMatches(output.path, output.source));
+		if (stale.length > 0) {
+			const files = stale.map((output) => displayPath(options.root, output.path)).join(", ");
+			throw new Error(`Generated route files are out of date: ${files}. Run \`pracht typegen\`.`);
+		}
+	} else for (const output of outputs) {
+		mkdirSync(dirname(output.path), { recursive: true });
+		writeFileSync(output.path, output.source, "utf-8");
+	}
+	return {
+		check: options.check,
+		files: outputs.map((output) => displayPath(options.root, output.path)),
+		mode: report.mode,
+		routes: routes.length
+	};
+}
+function validateRoutes(routes) {
+	const seen = /* @__PURE__ */ new Map();
+	for (const route of routes) {
+		if (!route.id) throw new Error(`Route ${route.path} resolved without an id.`);
+		const previousPath = seen.get(route.id);
+		if (previousPath) throw new Error(`Duplicate route id "${route.id}" for ${previousPath} and ${route.path}. Add explicit unique ids.`);
+		seen.set(route.id, route.path);
+		inferRouteParams(route.path);
+	}
+}
+function buildDeclarationSource(routes) {
+	const lines = [
+		"// Generated by `pracht typegen`. Do not edit manually.",
+		"import \"@pracht/core\";",
+		"import type { RouteParamInput, SearchParamsInput } from \"@pracht/core\";",
+		"",
+		"declare module \"@pracht/core\" {",
+		"  interface Register {",
+		"    routes: {"
+	];
+	for (const route of routes) {
+		lines.push(`      ${JSON.stringify(route.id)}: {`);
+		lines.push(`        path: ${JSON.stringify(route.path)};`);
+		lines.push(`        params: ${formatParamsType(inferRouteParams(route.path))};`);
+		lines.push("        search: SearchParamsInput;");
+		lines.push("      };");
+	}
+	lines.push("    };");
+	lines.push("  }");
+	lines.push("}");
+	lines.push("");
+	lines.push("export {};");
+	lines.push("");
+	return lines.join("\n");
+}
+function buildRuntimeSource(routes) {
+	const lines = [
+		"// Generated by `pracht typegen`. Do not edit manually.",
+		"import { createHref } from \"@pracht/core\";",
+		"import type { HrefRouteDefinition } from \"@pracht/core\";",
+		"",
+		"export const routes = ["
+	];
+	for (const route of routes) {
+		lines.push("  {");
+		lines.push(`    id: ${JSON.stringify(route.id)},`);
+		lines.push(`    path: ${JSON.stringify(route.path)},`);
+		lines.push("  },");
+	}
+	lines.push("] as const satisfies readonly HrefRouteDefinition[];");
+	lines.push("");
+	lines.push("export const href = createHref(routes);");
+	lines.push("");
+	return lines.join("\n");
+}
+function inferRouteParams(path) {
+	const params = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const segment of path.split("/").filter(Boolean)) {
+		let name = null;
+		if (segment === "*") name = "*";
+		else if (segment.startsWith(":")) name = segment.endsWith("*") ? segment.slice(1, -1) || "*" : segment.slice(1);
+		if (!name) continue;
+		if (seen.has(name)) throw new Error(`Route ${path} declares duplicate param "${name}".`);
+		seen.add(name);
+		params.push(name);
+	}
+	return params;
+}
+function formatParamsType(params) {
+	if (params.length === 0) return "Record<never, never>";
+	return `{ ${params.map((param) => `${JSON.stringify(param)}: RouteParamInput;`).join(" ")} }`;
+}
+function resolveOutputPath(root, outputPath) {
+	const absolutePath = isAbsolute(outputPath) ? outputPath : resolve(root, outputPath);
+	const relativePath = relative(root, absolutePath);
+	if (relativePath === "" || !relativePath.startsWith("..") && !isAbsolute(relativePath)) return absolutePath;
+	throw new Error(`Refusing to write outside the project root: ${outputPath}.`);
+}
+function fileMatches(path, source) {
+	return existsSync(path) && readFileSync(path, "utf-8") === ensureTrailingNewline(source);
+}
+//#endregion
+export { typegen_default as default };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pracht/cli",
-  "version": "1.3.3",
+  "version": "1.5.0",
   "description": "CLI for developing, building, validating, inspecting, and scaffolding Pracht apps.",
   "keywords": [
     "pracht",
@@ -39,7 +39,7 @@
   },
   "dependencies": {
     "citty": "^0.1.6",
-    "@pracht/core": "0.6.1"
+    "@pracht/core": "0.8.0"
   },
   "scripts": {
     "build": "tsdown"