@pracht/cli 1.3.2 → 1.4.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @pracht/cli
 
+## 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
+
+- [`64242a9`](https://github.com/JoviDeCroock/pracht/commit/64242a9dd01348c29e08e22b54581ebce28208d6) Thanks [@JoviDeCroock](https://github.com/JoviDeCroock)! - Add npm package descriptions and keywords so Pracht packages are easier to discover in registries and AI-assisted tooling.
+
+- Updated dependencies [[`64242a9`](https://github.com/JoviDeCroock/pracht/commit/64242a9dd01348c29e08e22b54581ebce28208d6)]:
+  - @pracht/core@0.6.1
+
 ## 1.3.2
 
 ### 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/index.mjs

@@ -45,8 +45,9 @@ runMain(defineCommand({
 		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)
+		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,18 @@
 {
   "name": "@pracht/cli",
-  "version": "1.3.2",
+  "version": "1.4.0",
+  "description": "CLI for developing, building, validating, inspecting, and scaffolding Pracht apps.",
+  "keywords": [
+    "pracht",
+    "preact",
+    "cli",
+    "vite",
+    "ssr",
+    "scaffold",
+    "inspect",
+    "doctor",
+    "framework"
+  ],
   "license": "MIT",
   "homepage": "https://github.com/JoviDeCroock/pracht/tree/main/packages/cli",
   "bugs": {
@@ -27,7 +39,7 @@
   },
   "dependencies": {
     "citty": "^0.1.6",
-    "@pracht/core": "0.6.0"
+    "@pracht/core": "0.7.0"
   },
   "scripts": {
     "build": "tsdown"