@wrikka/solid-framework 0.0.0-stage → 0.15.0

package/src/cli/commands.ts

@@ -0,0 +1,145 @@
+/**
+ * CLI Commands — public surface + `runCli` dispatch.
+ * `solid dev|build|start|generate` — thin orchestration over Vite + Bun.
+ *
+ * Implementations live in the sibling modules; this file only re-exports
+ * them (the import surface is stable) and maps argv → command.
+ */
+
+import { doctor } from "./doctor";
+import type { CliResult } from "./infra";
+import { migrate } from "./migrate";
+import { bench, testNav, watch } from "./nav";
+import { build, dev, envCheck, preview, printConfig, size, start } from "./ops";
+import {
+	diffRoutes,
+	eject,
+	generate,
+	inspect,
+	manifestDump,
+	renameRoute,
+	routes,
+	sitemap,
+} from "./routes";
+import { add, adopt, scaffold, scaffoldTests } from "./scaffold";
+
+export { doctor } from "./doctor";
+export type { CliResult } from "./infra";
+export { migrate } from "./migrate";
+export { bench, testNav, watch } from "./nav";
+export {
+	build,
+	dev,
+	envCheck,
+	preview,
+	printConfig,
+	size,
+	start,
+} from "./ops";
+export {
+	diffRoutes,
+	eject,
+	generate,
+	inspect,
+	manifestDump,
+	renameRoute,
+	routes,
+	sitemap,
+} from "./routes";
+export { add, adopt, scaffold, scaffoldTests } from "./scaffold";
+
+export const runCli = (argv: string[] = process.argv.slice(2)): CliResult => {
+	const [command, ...rest] = argv;
+	switch (command) {
+		case "dev":
+			return dev();
+		case "build":
+			return build();
+		case "start":
+			return start(rest[0]);
+		case "generate":
+			return generate();
+		case "doctor":
+			return doctor(
+				"src/routes",
+				rest.includes("--fix"),
+				rest.includes("--deep"),
+			);
+		case "env":
+			return envCheck();
+		case "manifest":
+			return manifestDump("src/routes");
+		case "diff":
+			return diffRoutes("src/routes");
+		case "sitemap":
+			return sitemap(rest.find((a) => !a.startsWith("-")) ?? "");
+		case "bench":
+			return bench(rest);
+		case "watch":
+			return watch(rest[0]);
+		case "eject":
+			return eject(rest[0]);
+		case "routes":
+			return routes("src/routes", rest.includes("--json"));
+		case "inspect":
+			return inspect(
+				rest.find((a) => !a.startsWith("-")),
+				"src/routes",
+				rest.includes("--json"),
+			);
+		case "scaffold":
+			return scaffold(rest[0] ?? "");
+		case "add":
+			return add(rest[0], rest[1]);
+		case "test":
+			return scaffoldTests();
+		case "test-nav":
+			return testNav(rest);
+		case "migrate":
+			return migrate(rest);
+		case "adopt":
+			return adopt(
+				rest.find((a) => !a.startsWith("-")),
+				rest.includes("--write"),
+			);
+		case "size":
+			return size(rest[0]);
+		case "rename":
+			return renameRoute(rest[0] ?? "", rest[1] ?? "");
+		case "preview":
+			return preview(rest[0] ? Number(rest[0]) : undefined);
+		case "config":
+			return printConfig();
+		default:
+			console.log(
+				[
+					"@wrikka/solid-framework CLI",
+					"",
+					"  solid dev        Start dev server with SSR middleware",
+					"  solid build      Build client + server bundles",
+					"  solid start      Run the production server",
+					"  solid generate   Regenerate route manifest and types",
+					"  solid test       Scaffold a test file per route into test/routes/",
+					"  solid test-nav   Run every route's loader chain headlessly (--max ms)",
+					"  solid migrate    Rewrite flat route exports into page() defs (--dry)",
+					"  solid adopt      Scan an app and print the adoption scaffold",
+					"  solid doctor     Health check — routes, generated types, deps (--fix, --deep)",
+					"  solid env        Diff .env against .env.example (keys only)",
+					"  solid manifest   Dump routes + counts as JSON",
+					"  solid diff       Route files added/removed vs HEAD",
+					"  solid sitemap    Generate sitemap.xml — solid sitemap <origin>",
+					"  solid watch      Watch routes dir — regen types + test-nav on change",
+					"  solid eject      Dump resolved manifest + types to .solid/eject/",
+					"  solid routes     Print the route tree (path, kind, middleware, file) (--json)",
+					"  solid inspect    Show which route matches a URL — solid inspect /users/1",
+					"  solid scaffold   Create a minimal app — solid scaffold my-app",
+					"  solid size       Report dist/ bundle sizes (top 20)",
+					"  solid rename     Rename a route file + regen types — solid rename a.tsx b.tsx",
+					"  solid preview    Serve the production build locally (dist/)",
+					"  solid config     Print the resolved config (solid.config.ts)",
+					"  solid add        Scaffold route|api|middleware — solid add route blog",
+				].join("\n"),
+			);
+			return { code: command ? 1 : 0 };
+	}
+};

package/src/cli/doctor.ts

@@ -0,0 +1,111 @@
+/**
+ * `solid doctor` — project health check: routes dir, generated types
+ * staleness, config/entry presence, resolvable deps. `--fix` regenerates
+ * .solid types; `--deep` runs the loader chains via test-nav.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { buildRouteManifest } from "#app/modules/file-routes";
+import type { CliResult } from "./infra";
+import { listFiles } from "./infra";
+import { testNav } from "./nav";
+import { generate } from "./routes";
+
+export const doctor = (
+	routesDir = "src/routes",
+	fix = false,
+	deep = false,
+): CliResult => {
+	// Health check — routesDir, manifest, generated types staleness,
+	// optional peer deps; prints findings, exits 1 on errors.
+	// --fix regenerates .solid types when missing/stale
+	let failures = 0;
+	const ok = (msg: string) => console.log(`  ✓ ${msg}`);
+	const warn = (msg: string) => console.log(`  ! ${msg}`);
+	const fail = (msg: string) => {
+		failures += 1;
+		console.log(`  ✗ ${msg}`);
+	};
+
+	if (!existsSync(routesDir)) {
+		fail(`${routesDir} not found`);
+	} else {
+		const files = listFiles(routesDir);
+		const manifest = buildRouteManifest(files, routesDir);
+		const pages = manifest.filter((r) => r.kind !== "api");
+		const apis = manifest.filter((r) => r.kind === "api");
+		ok(`${pages.length} page route(s), ${apis.length} api route(s)`);
+		if (pages.length === 0) warn("no page routes — nothing will render");
+
+		const routesDts = join(".solid", "routes.d.ts");
+		if (!existsSync(routesDts)) {
+			if (fix) {
+				generate(routesDir);
+				ok(".solid/routes.d.ts regenerated (--fix)");
+			} else {
+				warn(".solid/routes.d.ts missing — run `solid generate`");
+			}
+		} else {
+			// staleness — newer route files than the generated types
+			const newest = Math.max(...files.map((f) => statSync(f).mtimeMs), 0);
+			const dtsMtime = statSync(routesDts).mtimeMs;
+			if (newest > dtsMtime) {
+				if (fix) {
+					generate(routesDir);
+					ok(".solid/routes.d.ts regenerated (--fix)");
+				} else {
+					warn(".solid/routes.d.ts stale — routes newer than generated types");
+				}
+			} else {
+				ok(".solid/routes.d.ts present");
+			}
+		}
+
+		// Duplicate paths after normalization (e.g. index.tsx + (grp)/index.tsx)
+		const seen = new Map<string, number>();
+		for (const r of pages) seen.set(r.path, (seen.get(r.path) ?? 0) + 1);
+		for (const [path, n] of seen) {
+			if (n > 1) fail(`duplicate route path ${path} (${n} files)`);
+		}
+
+		// Page route files need a default export (component or page() def)
+		for (const r of pages) {
+			if (r.kind === "content" || !existsSync(r.file)) continue;
+			const src = readFileSync(r.file, "utf8");
+			if (!/export\s+default/.test(src)) {
+				warn(`${r.path} has no default export — nothing renders`);
+			}
+		}
+	}
+
+	// solid.config.* presence — adopt hint when absent
+	const hasConfig = ["solid.config.tsx", "solid.config.ts"].some((f) =>
+		existsSync(f),
+	);
+	if (hasConfig) ok("solid.config present");
+	else warn("no solid.config.* — run `solid adopt` for the scaffold");
+
+	// Entry points — the vite plugin expects both
+	for (const entry of ["src/entry-server.tsx", "src/entry-client.tsx"]) {
+		if (existsSync(entry)) ok(`${entry} present`);
+		else warn(`${entry} missing — \`solid scaffold\` creates it`);
+	}
+
+	for (const pkg of ["solid-js", "@wrikka/ui", "@wrikka/web-server-toolkit"]) {
+		try {
+			import.meta.resolve(pkg);
+			ok(`${pkg} resolvable`);
+		} catch {
+			warn(`${pkg} not resolvable from here`);
+		}
+	}
+
+	if (deep) {
+		console.log("  deep: running loader chains (test-nav)");
+		const nav = testNav([routesDir]);
+		if (nav.code !== 0) failures++;
+	}
+	console.log(failures ? `doctor: ${failures} error(s)` : "doctor: healthy");
+	return { code: failures ? 1 : 0 };
+};

package/src/cli/index.ts

@@ -0,0 +1,3 @@
+// Public API - @wrikka/solid-framework/cli
+
+export * from "./commands";

package/src/cli/infra.ts

@@ -0,0 +1,38 @@
+/**
+ * CLI infrastructure — process spawning and route-dir scanning shared by
+ * every command module.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import { join, sep } from "node:path";
+
+export interface CliResult {
+	code: number;
+}
+
+export const run = (
+	cmd: string,
+	args: string[],
+	env?: NodeJS.ProcessEnv,
+): CliResult => {
+	const result = spawnSync(cmd, args, {
+		stdio: "inherit",
+		env: { ...process.env, ...env },
+	});
+	return { code: result.status ?? 1 };
+};
+
+export const vite = (args: string[], env?: NodeJS.ProcessEnv): CliResult =>
+	run("bunx", ["vite", ...args], env);
+
+export const listFiles = (dir: string): string[] => {
+	if (!existsSync(dir)) return [];
+	const out: string[] = [];
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) out.push(...listFiles(full));
+		else out.push(full.split(sep).join("/"));
+	}
+	return out;
+};

package/src/cli/migrate.ts

@@ -0,0 +1,119 @@
+/**
+ * `solid migrate [routesDir] [--dry]` — rewrite flat route modules
+ * (`export const loader`/`beforeLoad`/`schema`/`action` + default
+ * component) into the single `page({...})` definition. Skips files
+ * it cannot transform safely.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import type { CliResult } from "./infra";
+import { listFiles } from "./infra";
+
+const FLAT_EXPORTS = [
+	"loader",
+	"beforeLoad",
+	"loaderCache",
+	"schema",
+	"validateSearch",
+	"action",
+	"prerender",
+	"staticParams",
+	"head",
+	"meta",
+] as const;
+
+const migrateRouteFile = (
+	file: string,
+): { changed: boolean; skipped?: string; out?: string } => {
+	const src = readFileSync(file, "utf8");
+	if (/export\s+default\s+page\s*\(/.test(src))
+		return { changed: false, skipped: "already page()" };
+
+	let out = src;
+	let component: string | undefined;
+
+	const namedFn = out.match(/export\s+default\s+function\s+(\w+)\s*\(/);
+	if (namedFn) {
+		component = namedFn[1];
+		out = out.replace(
+			/export\s+default\s+function\s+(\w+)\s*\(/,
+			"const $1 = function $1(",
+		);
+	} else if (/export\s+default\s+function\s*\(/.test(out)) {
+		component = "__default";
+		out = out.replace(
+			/export\s+default\s+function\s*\(/,
+			"const __default = function (",
+		);
+	} else if (/export\s+default\s*[(=]|export\s+default\s+async\b/.test(out)) {
+		component = "__default";
+		out = out.replace(/export\s+default\s*/, "const __default = ");
+	} else {
+		const ident = out.match(/export\s+default\s+(\w+)\s*;/);
+		if (ident) {
+			component = ident[1];
+			out = out.replace(/export\s+default\s+\w+\s*;/, "");
+		}
+	}
+	if (!component) return { changed: false, skipped: "no default export" };
+
+	const found = FLAT_EXPORTS.filter((n) =>
+		new RegExp(`export\\s+const\\s+${n}\\b`).test(out),
+	);
+	for (const n of found) {
+		out = out.replace(new RegExp(`export\\s+(const\\s+${n}\\b)`), "$1");
+	}
+
+	const fields = [
+		`component: ${component}`,
+		found.includes("loader") && "load: loader",
+		found.includes("beforeLoad") && "before: beforeLoad",
+		found.includes("loaderCache") && "cache: loaderCache",
+		found.includes("schema") && "params: schema?.params",
+		found.includes("schema") && "body: schema?.body",
+		found.includes("validateSearch") && "search: validateSearch",
+		found.includes("action") && "actions: { default: action }",
+		found.includes("prerender") && "prerender",
+		found.includes("staticParams") && "staticParams",
+		found.includes("head") && "head",
+		found.includes("meta") && "meta",
+	].filter(Boolean);
+
+	if (
+		!/import\s*{[^}]*\bpage\b[^}]*}\s*from\s*["']@wrikka\/solid-framework\/app["']/.test(
+			out,
+		)
+	) {
+		out = `import { page } from "@wrikka/solid-framework/app";\n${out}`;
+	}
+	out = `${out.trimEnd()}\n\nexport default page({\n\t${fields.join(",\n\t")},\n});\n`;
+	return { changed: true, out };
+};
+
+export const migrate = (args: string[] = []): CliResult => {
+	const routesDir = args.find((a) => !a.startsWith("-")) ?? "src/routes";
+	const dry = args.includes("--dry");
+	const showDiff = args.includes("--diff") || dry;
+	const files = listFiles(routesDir).filter((f) => /\.tsx?$/.test(f));
+	let changed = 0;
+	let skipped = 0;
+	for (const file of files) {
+		const res = migrateRouteFile(file);
+		if (res.changed && res.out !== undefined) {
+			changed++;
+			if (showDiff) {
+				const tail = res.out.split("\n").slice(-8).join("\n");
+				console.log(`--- ${file}\n${tail}`);
+			}
+			if (!dry) writeFileSync(file, res.out);
+			console.log(`  + ${file}`);
+		} else if (res.skipped) {
+			skipped++;
+			console.log(`  - ${file}: ${res.skipped}`);
+		}
+	}
+	console.log(
+		`[solid] migrate: ${changed} rewritten, ${skipped} skipped${dry ? " (dry-run)" : ""}`,
+	);
+	return { code: 0 };
+};

package/src/cli/nav.ts

@@ -0,0 +1,164 @@
+/**
+ * Navigation commands — `solid test-nav`, `solid bench`, `solid watch`.
+ * These spawn `bun -e` with an embedded script that runs each route's
+ * loader chain headlessly.
+ */
+
+import { existsSync, watch as fsWatch } from "node:fs";
+import type { CliResult } from "./infra";
+import { run } from "./infra";
+import { generate } from "./routes";
+
+/**
+ * `solid test-nav [routesDir] [--max <ms>]` — headless navigation
+ * assertions: runs every page route's beforeLoad/loader chain in
+ * Bun and fails on throws, redirects-into-errors, or loader time
+ * over `--max` (default 1000ms)
+ */
+export const testNav = (args: string[] = []): CliResult => {
+	const routesDir = args.find((a) => !a.startsWith("-")) ?? "src/routes";
+	const maxIdx = args.indexOf("--max");
+	const maxMs = maxIdx >= 0 ? Number(args[maxIdx + 1]) || 1000 : 1000;
+	const html = args.includes("--html");
+	const filterIdx = args.indexOf("--filter");
+	const filter = filterIdx >= 0 ? args[filterIdx + 1] : undefined;
+	const json = args.includes("--json");
+	const pathsIdx = args.indexOf("--paths");
+	const onlyPaths =
+		pathsIdx >= 0 ? (args[pathsIdx + 1] ?? "").split(",") : undefined;
+	const code = `
+const { buildRouteManifest, runFileRouteLoader, normalizeRouteModule } = await import("@wrikka/solid-framework/app");
+const { readdirSync, existsSync } = await import("node:fs");
+if (!existsSync(${JSON.stringify(routesDir)})) { console.log("[solid] no routes dir: " + ${JSON.stringify(routesDir)}); process.exit(1); }
+const files = [];
+const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { const f = d + "/" + e.name; e.isDirectory() ? walk(f) : files.push(f); } };
+walk(${JSON.stringify(routesDir)});
+const manifest = buildRouteManifest(files, ${JSON.stringify(routesDir)});
+let pages = manifest.filter((r) => r.kind !== "api");
+if (${JSON.stringify(filter ?? null)}) pages = pages.filter((r) => r.path.includes(${JSON.stringify(filter ?? "")}));
+if (${JSON.stringify(onlyPaths ?? null)}) pages = pages.filter((r) => ${JSON.stringify(onlyPaths ?? [])}.includes(r.path));
+let fails = 0;
+const results = [];
+const urlFor = (p) => p.replace(/:([^/]+)/g, "1").replace(/\\*[^/]+/g, "x");
+for (const route of pages) {
+	if (route.kind === "content") {
+		try {
+			const { readFileSync } = await import("node:fs");
+			const raw = readFileSync(route.file, "utf8");
+			if (!raw.trim()) throw new Error("empty content");
+			results.push({ path: route.path, ms: 0, ok: true });
+			console.log("  ✓ " + route.path.padEnd(24) + " content");
+		} catch (e) {
+			fails++;
+			results.push({ path: route.path, ok: false, error: e.message });
+			console.log("  ✗ " + route.path.padEnd(24) + " " + e.message);
+		}
+		continue;
+	}
+	const url = urlFor(route.path);
+	const modules = {};
+	for (const f of [...(route.layouts ?? []), route.file]) {
+		try { modules[f] = normalizeRouteModule(await import("./" + f)); }
+		catch (e) { console.log("  ✗ " + route.path + "  import failed: " + e.message); fails++; continue; }
+	}
+	const t = performance.now();
+	try {
+		await runFileRouteLoader(url, manifest, modules, new Request("http://test" + url));
+		if (${JSON.stringify(html)} ) {
+			const mod = modules[route.file];
+			const Comp = mod?.default;
+			if (typeof Comp === "function") {
+				const { renderToString } = await import("solid-js/web");
+				const htmlOut = renderToString(() => Comp({ params: {}, data: () => undefined }));
+				if (!htmlOut || !htmlOut.trim()) throw new Error("empty render");
+			}
+		}
+		const ms = Math.round(performance.now() - t);
+		const slow = ms > ${maxMs};
+		if (slow) fails++;
+		results.push({ path: route.path, ms, ok: !slow });
+		console.log("  " + (slow ? "✗" : "✓") + " " + route.path.padEnd(24) + " " + ms + "ms" + (slow ? "  > ${maxMs}ms" : ""));
+	} catch (e) {
+		fails++;
+		const m = e instanceof Response ? "Response " + e.status : e.message;
+		results.push({ path: route.path, ok: false, error: m });
+		console.log("  ✗ " + route.path.padEnd(24) + " " + m);
+	}
+}
+if (${JSON.stringify(json)}) console.log(JSON.stringify(results, null, 2));
+console.log(fails ? "test-nav: " + fails + " failure(s)" : "test-nav: " + pages.length + " route(s) ok");
+process.exit(fails ? 1 : 0);`;
+	return run("bun", ["-e", code]);
+};
+
+/**
+ * `solid bench [routesDir] [--iter <n>] [--filter <s>] [--paths a,b]` —
+ * loader benchmark: runs each route's beforeLoad/loader chain N times
+ * and reports avg ms per route
+ */
+export const bench = (args: string[] = []): CliResult => {
+	const routesDir = args.find((a) => !a.startsWith("-")) ?? "src/routes";
+	const iterIdx = args.indexOf("--iter");
+	const iter = iterIdx >= 0 ? Number(args[iterIdx + 1]) || 5 : 5;
+	const filterIdx = args.indexOf("--filter");
+	const filter = filterIdx >= 0 ? args[filterIdx + 1] : undefined;
+	const pathsIdx = args.indexOf("--paths");
+	const onlyPaths =
+		pathsIdx >= 0 ? (args[pathsIdx + 1] ?? "").split(",") : undefined;
+	const code = `
+const { buildRouteManifest, runFileRouteLoader, normalizeRouteModule } = await import("@wrikka/solid-framework/app");
+const { readdirSync, existsSync } = await import("node:fs");
+if (!existsSync(${JSON.stringify(routesDir)})) { console.log("[solid] no routes dir: " + ${JSON.stringify(routesDir)}); process.exit(1); }
+const files = [];
+const walk = (d) => { for (const e of readdirSync(d, { withFileTypes: true })) { const f = d + "/" + e.name; e.isDirectory() ? walk(f) : files.push(f); } };
+walk(${JSON.stringify(routesDir)});
+const manifest = buildRouteManifest(files, ${JSON.stringify(routesDir)});
+let pages = manifest.filter((r) => r.kind === "page");
+if (${JSON.stringify(filter ?? null)}) pages = pages.filter((r) => r.path.includes(${JSON.stringify(filter ?? "")}));
+if (${JSON.stringify(onlyPaths ?? null)}) pages = pages.filter((r) => ${JSON.stringify(onlyPaths ?? [])}.includes(r.path));
+const urlFor = (p) => p.replace(/:([^/]+)/g, "1").replace(/\\*[^/]+/g, "x");
+let n = 0;
+for (const route of pages) {
+	const url = urlFor(route.path);
+	const modules = {};
+	for (const f of [...(route.layouts ?? []), route.file]) {
+		try { modules[f] = normalizeRouteModule(await import("./" + f)); }
+		catch (e) { console.log("  ✗ " + route.path + "  import failed: " + e.message); continue; }
+	}
+	let total = 0;
+	for (let i = 0; i < ${iter}; i++) {
+		const t = performance.now();
+		try { await runFileRouteLoader(url, manifest, modules, new Request("http://test" + url)); }
+		catch { /* bench measures timing, not correctness — test-nav checks that */ }
+		total += performance.now() - t;
+	}
+	n++;
+	console.log("  " + route.path.padEnd(24) + " " + (Math.round((total / ${iter}) * 100) / 100) + "ms avg (" + ${iter} + " iters)");
+}
+console.log(n ? "bench: " + n + " route(s) measured" : "bench: no routes");
+process.exit(0);`;
+	return run("bun", ["-e", code]);
+};
+
+/**
+ * `solid watch [routesDir]` — regenerate route types and re-run
+ * test-nav whenever a route file changes (dev DX without vite)
+ */
+export const watch = (routesDir = "src/routes"): CliResult => {
+	if (!existsSync(routesDir)) {
+		console.log(`[solid] no routes dir: ${routesDir}`);
+		return { code: 1 };
+	}
+	let timer: ReturnType<typeof setTimeout> | undefined;
+	const rerun = () => {
+		clearTimeout(timer);
+		timer = setTimeout(() => {
+			generate(routesDir);
+			testNav([routesDir]);
+		}, 150);
+	};
+	fsWatch(routesDir, { recursive: true }, rerun);
+	console.log(`[solid] watching ${routesDir} — generate + test-nav on change`);
+	generate(routesDir);
+	return { code: 0 };
+};