alepha 0.14.4 → 0.15.1

package/dist/cli/index.js

@@ -1,14 +1,14 @@
 import { $atom, $hook, $inject, $module, $use, Alepha, AlephaError, t } from "alepha";
 import { FileSystemProvider } from "alepha/file";
-import { access, mkdir, readFile, readdir, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { $command, CliProvider, EnvUtils } from "alepha/command";
 import { $logger, ConsoleColorProvider } from "alepha/logger";
-import { boot, buildClient, buildServer, copyAssets, devServer, generateCloudflare, generateDocker, generateSitemap, generateVercel, prerenderPages } from "alepha/vite";
+import { buildClient, buildServer, copyAssets, generateCloudflare, generateDocker, generateSitemap, generateVercel, importVite, importViteReact, prerenderPages, viteAlephaSsrPreload } from "alepha/vite";
 import { exec, spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { promisify } from "node:util";
 import { ServerSwaggerProvider } from "alepha/server/swagger";
+import { access, readFile, readdir } from "node:fs/promises";
 import * as os from "node:os";
 
 //#region ../../src/core/constants/KIND.ts
@@ -79,7 +79,7 @@ $atom$1[KIND] = "atom";
 * Options can be overridden via vite.config.ts or CLI flags.
 */
 const buildOptions = $atom$1({
-	name: "alepha.build.options",
+	name: "alepha.cli.build.options",
 	description: "Build configuration options",
 	schema: t.object({
 		stats: t.optional(t.boolean({ default: false })),
@@ -103,168 +103,203 @@ const buildOptions = $atom$1({
 });
 
 //#endregion
-//#region ../../src/cli/assets/appRouterTs.ts
-const appRouterTs = () => `
-import { $page } from "@alepha/react/router";
-
-export class AppRouter {
-  home = $page({
-    component: () => "Hello World",
-  });
-}
-`.trim();
-
-//#endregion
-//#region ../../src/cli/assets/biomeJson.ts
-const biomeJson = `
-{
-  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
-  "vcs": {
-    "enabled": true,
-    "clientKind": "git"
-  },
-  "files": {
-    "ignoreUnknown": true,
-    "includes": ["**", "!node_modules", "!dist"]
-  },
-  "formatter": {
-    "enabled": true,
-    "useEditorconfig": true
-  },
-  "linter": {
-    "enabled": true,
-    "rules": {
-      "recommended": true
-    },
-    "domains": {
-      "react": "recommended"
-    }
-  },
-  "assist": {
-    "actions": {
-      "source": {
-        "organizeImports": "on"
-      }
-    }
-  }
-}
-`.trim();
-
-//#endregion
-//#region ../../src/cli/assets/dummySpecTs.ts
-const dummySpecTs = () => `
-import { test, expect } from "vitest";
-
-test("dummy test", () => {
-  expect(1 + 1).toBe(2);
+//#region ../../src/cli/atoms/appEntryOptions.ts
+const appEntryOptions = $atom({
+	name: "alepha.cli.appEntry.options",
+	schema: t.object({
+		server: t.optional(t.text()),
+		browser: t.optional(t.text()),
+		style: t.optional(t.text())
+	}),
+	default: {}
 });
-`.trim();
 
 //#endregion
-//#region ../../src/cli/assets/editorconfig.ts
-const editorconfig = `
-# https://editorconfig.org
-
-root = true
-
-[*]
-charset = utf-8
-end_of_line = lf
-insert_final_newline = true
-trim_trailing_whitespace = true
-indent_style = space
-indent_size = 2
-`.trim();
+//#region ../../src/cli/providers/AppEntryProvider.ts
+/**
+* Service for locating entry files in Alepha projects.
+*
+* Originally in alepha/vite, moved to CLI to avoid cli -> vite dependency.
+*/
+var AppEntryProvider = class {
+	fs = $inject(FileSystemProvider);
+	options = $use(appEntryOptions);
+	serverEntries = [
+		"main.server.ts",
+		"main.server.tsx",
+		"main.ts",
+		"main.tsx"
+	];
+	browserEntries = [
+		"main.browser.ts",
+		"main.browser.tsx",
+		"main.ts",
+		"main.tsx"
+	];
+	styleEntries = [
+		"main.css",
+		"styles.css",
+		"style.css"
+	];
+	/**
+	* Get application entry points.
+	*
+	* Server entry is required, an error is thrown if not found.
+	* Browser entry is optional.
+	*
+	* It will first check for custom entries in options, see appEntryOptions.
+	*/
+	async getAppEntry(root) {
+		const appEntry = {
+			root,
+			server: ""
+		};
+		if (this.options.server) {
+			if (!await this.fs.exists(this.fs.join(root, this.options.server))) throw new AlephaError(`Custom server entry "${this.options.server}" not found.`);
+			appEntry.server = this.options.server;
+		}
+		if (this.options.browser) {
+			if (!await this.fs.exists(this.fs.join(root, this.options.browser))) throw new AlephaError(`Custom browser entry "${this.options.browser}" not found.`);
+			appEntry.browser = this.options.browser;
+		}
+		if (this.options.style) {
+			if (!await this.fs.exists(this.fs.join(root, this.options.style))) throw new AlephaError(`Custom style entry "${this.options.style}" not found.`);
+			appEntry.style = this.options.style;
+		}
+		const srcFiles = await this.fs.ls(this.fs.join(root, "src"));
+		if (!appEntry.server) {
+			for (const entry of this.serverEntries) if (srcFiles.includes(entry)) {
+				appEntry.server = this.fs.join("src", entry);
+				break;
+			}
+		}
+		if (!appEntry.server) throw new AlephaError("No server entry found. Please, add a main.server.ts file in the src/ directory or configure a custom entry in alepha.config.ts.");
+		if (!appEntry.browser) {
+			for (const entry of this.browserEntries) if (srcFiles.includes(entry)) {
+				appEntry.browser = this.fs.join("src", entry);
+				break;
+			}
+		}
+		if (!appEntry.style) {
+			for (const entry of this.styleEntries) if (srcFiles.includes(entry)) {
+				appEntry.style = this.fs.join("src", entry);
+				break;
+			}
+		}
+		return appEntry;
+	}
+};
 
 //#endregion
-//#region ../../src/cli/assets/indexHtml.ts
-const indexHtml = (browserEntry) => `
+//#region ../../src/cli/providers/ViteTemplateProvider.ts
+var ViteTemplateProvider = class {
+	fs = $inject(FileSystemProvider);
+	generateIndexHtml(entry) {
+		const style = entry.style;
+		const browser = entry.browser ?? entry.server;
+		return `
 <!DOCTYPE html>
 <html lang="en">
 <head>
-  <meta charset="UTF-8">
-  <title>App</title>
+<meta charset="UTF-8" />
+<title>App</title>
+<meta name="viewport" content="width=device-width, initial-scale=1"/>
+${style ? `<link rel="stylesheet" href="/${style}" />` : ""}
 </head>
 <body>
 <div id="root"></div>
-<script type="module" src="${browserEntry}"><\/script>
+<script type="module" src="/${browser}"><\/script>
 </body>
 </html>
 `.trim();
+	}
+};
 
 //#endregion
-//#region ../../src/cli/assets/mainBrowserTs.ts
-const mainBrowserTs = () => `
-import { Alepha, run } from "alepha";
-import { AppRouter } from "./AppRouter.ts";
-
-const alepha = Alepha.create();
-
-alepha.with(AppRouter);
-
-run(alepha);
-`.trim();
-
-//#endregion
-//#region ../../src/cli/assets/mainTs.ts
-const mainTs = () => `
-import { run } from "alepha";
-import { $route } from "alepha/server";
-
-class App {
-  root = $route({
-    path: "/",
-    handler: () => "Hello, Alepha!",
-  });
-}
-
-run(App);
-`.trim();
-
-//#endregion
-//#region ../../src/cli/assets/tsconfigJson.ts
-const tsconfigJson = `
-{
-  "extends": "alepha/tsconfig.base"
-}
-`.trim();
-
-//#endregion
-//#region ../../src/cli/version.ts
-const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8"));
-const version = packageJson.version;
+//#region ../../src/cli/providers/ViteBuildProvider.ts
+var ViteBuildProvider = class {
+	alepha;
+	appEntry;
+	viteDevServer;
+	templateProvider = $inject(ViteTemplateProvider);
+	/**
+	* We need to close the Vite dev server after build is done.
+	*/
+	onReady = $hook({
+		on: "ready",
+		priority: "last",
+		handler: async () => {
+			await this.viteDevServer?.close();
+		}
+	});
+	onStop = $hook({
+		on: "stop",
+		handler: async () => {
+			await this.viteDevServer?.close();
+		}
+	});
+	async init(opts) {
+		const { createServer } = await importVite();
+		process.env.ALEPHA_CLI_IMPORT = "true";
+		process.env.NODE_ENV = "production";
+		process.env.LOG_LEVEL ??= "warn";
+		/**
+		* 01/26 Vite 7
+		* "runnerImport" doesn't work as expected here. (e.g. build docs fail)
+		* -> We still use devServer and ssrLoadModule for now.
+		* -> This is clearly a bad stuff, we need to find better way.
+		*/
+		this.viteDevServer = await createServer({
+			server: { middlewareMode: true },
+			appType: "custom",
+			logLevel: "silent"
+		});
+		await this.viteDevServer.ssrLoadModule(opts.entry.server);
+		const alepha = globalThis.__alepha;
+		if (!alepha) throw new AlephaError("Alepha instance not found after loading entry module");
+		this.alepha = alepha;
+		this.appEntry = opts.entry;
+		return alepha;
+	}
+	hasClient() {
+		if (!this.alepha) throw new AlephaError("ViteBuildProvider not initialized");
+		try {
+			this.alepha.inject("ReactServerProvider");
+			return true;
+		} catch {
+			return false;
+		}
+	}
+	generateIndexHtml() {
+		if (!this.appEntry) throw new AlephaError("ViteBuildProvider not initialized");
+		return this.templateProvider.generateIndexHtml(this.appEntry);
+	}
+};
 
 //#endregion
 //#region ../../src/cli/services/AlephaCliUtils.ts
 /**
-* Utility service for common project operations used by CLI commands.
+* Core utility service for CLI commands.
 *
-* This service provides helper methods for:
-* - Project configuration file management (tsconfig.json, package.json, etc.)
-* - Package manager setup (Yarn, npm, pnpm)
-* - Sample project downloading
-* - Drizzle ORM/Kit utilities
-* - Alepha instance loading
+* Provides:
+* - Command execution
+* - File editing helpers
+* - Drizzle/ORM utilities
+* - Environment loading
 */
 var AlephaCliUtils = class {
 	log = $logger();
 	fs = $inject(FileSystemProvider);
 	envUtils = $inject(EnvUtils);
-	alepha = $inject(Alepha);
+	boot = $inject(AppEntryProvider);
 	/**
-	* Execute a command using npx with inherited stdio.
-	*
-	* @example
-	* ```ts
-	* const runner = alepha.inject(ProcessRunner);
-	* await runner.exec("tsx watch src/index.ts");
-	* ```
+	* Execute a command with inherited stdio.
 	*/
 	async exec(command, options = {}) {
-		const root = process.cwd();
+		const root = options.root ?? process.cwd();
 		this.log.debug(`Executing command: ${command}`, { cwd: root });
-		const runExec = async (app$1, args$1) => {
-			const prog = spawn(app$1, args$1, {
+		const runExec = async (app, args) => {
+			const prog = spawn(app, args, {
 				stdio: "inherit",
 				cwd: root,
 				env: {
@@ -277,120 +312,276 @@ var AlephaCliUtils = class {
 			}));
 		};
 		if (options.global) {
-			const [app$1, ...args$1] = command.split(" ");
-			await runExec(app$1, args$1);
+			const [app, ...args] = command.split(" ");
+			await runExec(app, args);
 			return;
 		}
 		const suffix = process.platform === "win32" ? ".cmd" : "";
 		const [app, ...args] = command.split(" ");
-		let execPath = await this.checkFileExists(root, `node_modules/.bin/${app}${suffix}`, true);
-		if (!execPath) execPath = await this.checkFileExists(root, `node_modules/alepha/node_modules/.bin/${app}${suffix}`, true);
+		let execPath = await this.checkFileExists(root, `node_modules/.bin/${app}${suffix}`);
+		if (!execPath) execPath = await this.checkFileExists(root, `node_modules/alepha/node_modules/.bin/${app}${suffix}`);
+		if (!execPath) {
+			let parentDir = this.fs.join(root, "..");
+			for (let i = 0; i < 3; i++) {
+				execPath = await this.checkFileExists(parentDir, `node_modules/.bin/${app}${suffix}`);
+				if (execPath) break;
+				parentDir = this.fs.join(parentDir, "..");
+			}
+		}
 		if (!execPath) throw new AlephaError(`Could not find executable for command '${app}'. Make sure the package is installed.`);
 		await runExec(execPath, args);
 	}
 	/**
 	* Write a configuration file to node_modules/.alepha directory.
-	*
-	* Creates the .alepha directory if it doesn't exist and writes the file with the given content.
-	*
-	* @param name - The name of the config file to create
-	* @param content - The content to write to the file
-	* @param root - The root directory (defaults to process.cwd())
-	* @returns The absolute path to the created file
-	*
-	* @example
-	* ```ts
-	* const runner = alepha.inject(ProcessRunner);
-	* const configPath = await runner.writeConfigFile("biome.json", biomeConfig);
-	* ```
 	*/
 	async writeConfigFile(name, content, root = process.cwd()) {
-		const dir = join(root, "node_modules", ".alepha");
-		await mkdir(dir, { recursive: true }).catch(() => null);
-		const path = join(dir, name);
-		await writeFile(path, content);
+		const dir = this.fs.join(root, "node_modules", ".alepha");
+		await this.fs.mkdir(dir, { recursive: true }).catch(() => null);
+		const path = this.fs.join(dir, name);
+		await this.fs.writeFile(path, content);
 		this.log.debug(`Config file written: ${path}`);
 		return path;
 	}
-	async editFile(root, name, editFn) {
-		const filePath = join(root, name);
-		try {
-			await writeFile(filePath, await editFn(await readFile(filePath, "utf8")));
-		} catch (error) {
-			this.log.debug("Could not edit file", error);
+	/**
+	* Load Alepha instance from a server entry file.
+	*/
+	async loadAlephaFromServerEntryFile(rootDir, explicitEntry) {
+		process.env.ALEPHA_CLI_IMPORT = "true";
+		const root = rootDir ?? process.cwd();
+		let entry;
+		if (explicitEntry) {
+			entry = this.fs.join(root, explicitEntry);
+			if (!await this.fs.exists(entry)) throw new AlephaError(`Explicit server entry file "${explicitEntry}" not found.`);
+		} else {
+			const appEntry = await this.boot.getAppEntry(root);
+			entry = this.fs.join(root, appEntry.server);
 		}
-	}
-	async editJsonFile(root, name, editFn) {
-		return await this.editFile(root, name, async (content) => {
-			const newObj = await editFn(JSON.parse(content));
-			return JSON.stringify(newObj, null, 2);
-		});
-	}
-	async removeFiles(root, files) {
-		await Promise.all(files.map((file) => this.fs.rm(join(root, file), {
-			force: true,
-			recursive: true
-		})));
-	}
-	async removeYarn(root) {
-		await this.removeFiles(root, [
-			".yarn",
-			".yarnrc.yml",
-			"yarn.lock"
-		]);
-		await this.editJsonFile(root, "package.json", (pkg) => {
-			delete pkg.packageManager;
-		});
-	}
-	async removePnpm(root) {
-		await this.removeFiles(root, ["pnpm-lock.yaml", "pnpm-workspace.yaml"]);
-		await this.editJsonFile(root, "package.json", (pkg) => {
-			delete pkg.packageManager;
-		});
-	}
-	async removeNpm(root) {
-		await this.removeFiles(root, ["package-lock.json"]);
-	}
-	async removeBun(root) {
-		await this.removeFiles(root, ["bun.lockb", "bun.lock"]);
-	}
-	async removeAllPmFilesExcept(root, except) {
-		if (except !== "yarn") await this.removeYarn(root);
-		if (except !== "pnpm") await this.removePnpm(root);
-		if (except !== "npm") await this.removeNpm(root);
-		if (except !== "bun") await this.removeBun(root);
+		delete global.__alepha;
+		const mod = await import(entry);
+		this.log.debug(`Load entry: ${entry}`);
+		if (mod.default instanceof Alepha) return {
+			alepha: mod.default,
+			entry
+		};
+		const g = global;
+		if (g.__alepha) return {
+			alepha: g.__alepha,
+			entry
+		};
+		throw new AlephaError(`Could not find Alepha instance in entry file: ${entry}`);
 	}
 	/**
-	* Ensure Yarn is configured in the project directory.
-	*
-	* Creates a .yarnrc.yml file with node-modules linker if it doesn't exist.
-	*
-	* @param root - The root directory of the project
+	* Generate JavaScript code for Drizzle entities export.
 	*/
-	async ensureYarn(root) {
-		await this.ensureFileExists(root, ".yarnrc.yml", "nodeLinker: node-modules", false);
-		await this.removeAllPmFilesExcept(root, "yarn");
+	generateEntitiesJs(entry, provider, models = []) {
+		return `
+import "${entry}";
+import { DrizzleKitProvider, Repository } from "alepha/orm";
+
+const alepha = globalThis.__alepha;
+const kit = alepha.inject(DrizzleKitProvider);
+const provider = alepha.services(Repository).find((it) => it.provider.name === "${provider}").provider;
+const models = kit.getModels(provider);
+
+${models.map((it) => `export const ${it} = models["${it}"];`).join("\n")}
+
+`.trim();
 	}
-	async ensureBun(root) {
-		await this.removeAllPmFilesExcept(root, "bun");
+	/**
+	* Load environment variables from a .env file.
+	*/
+	async loadEnv(root, files = [".env"]) {
+		await this.envUtils.loadEnv(root, files);
 	}
-	async ensurePnpm(root) {
-		await this.removeAllPmFilesExcept(root, "pnpm");
+	async exists(root, path) {
+		return this.fs.exists(this.fs.join(root, path));
 	}
-	async ensureNpm(root) {
-		await this.removeAllPmFilesExcept(root, "npm");
+	async checkFileExists(root, name) {
+		const configPath = this.fs.join(root, name);
+		if (await this.fs.exists(configPath)) return configPath;
 	}
+};
+
+//#endregion
+//#region ../../src/cli/version.ts
+const packageJson = JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf-8"));
+const version = packageJson.version;
+
+//#endregion
+//#region ../../src/cli/services/PackageManagerUtils.ts
+/**
+* Utility service for package manager operations.
+*
+* Handles detection, installation, and cleanup for:
+* - Yarn
+* - npm
+* - pnpm
+* - Bun
+*/
+var PackageManagerUtils = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
+	alepha = $inject(Alepha);
 	/**
-	* Generate package.json content with Alepha dependencies.
-	*
-	* @param modes - Configuration for which dependencies to include
-	* @returns Package.json partial with dependencies, devDependencies, and scripts
+	* Detect the package manager used in the project.
 	*/
-	generatePackageJsonContent(modes) {
-		const dependencies = { alepha: `^${version}` };
-		const devDependencies = {};
-		const scripts = {
-			dev: "alepha dev",
+	async getPackageManager(root, flags) {
+		if (flags?.yarn) return "yarn";
+		if (flags?.pnpm) return "pnpm";
+		if (flags?.npm) return "npm";
+		if (flags?.bun) return "bun";
+		if (this.alepha.isBun()) return "bun";
+		if (await this.fs.exists(this.fs.join(root, "bun.lock"))) return "bun";
+		if (await this.fs.exists(this.fs.join(root, "yarn.lock"))) return "yarn";
+		if (await this.fs.exists(this.fs.join(root, "pnpm-lock.yaml"))) return "pnpm";
+		return "npm";
+	}
+	/**
+	* Get the install command for a package.
+	*/
+	async getInstallCommand(root, packageName, dev = true) {
+		const pm = await this.getPackageManager(root);
+		let cmd;
+		switch (pm) {
+			case "yarn":
+				cmd = `yarn add ${dev ? "-D" : ""} ${packageName}`;
+				break;
+			case "pnpm":
+				cmd = `pnpm add ${dev ? "-D" : ""} ${packageName}`;
+				break;
+			case "bun":
+				cmd = `bun add ${dev ? "-d" : ""} ${packageName}`;
+				break;
+			default: cmd = `npm install ${dev ? "--save-dev" : ""} ${packageName}`;
+		}
+		return cmd.replace(/\s+/g, " ").trim();
+	}
+	/**
+	* Check if a dependency is installed in the project.
+	*/
+	async hasDependency(root, packageName) {
+		try {
+			const pkg = await this.readPackageJson(root);
+			return !!(pkg.dependencies?.[packageName] || pkg.devDependencies?.[packageName]);
+		} catch {
+			return false;
+		}
+	}
+	/**
+	* Check if Expo is present in the project.
+	*/
+	async hasExpo(root) {
+		return this.hasDependency(root, "expo");
+	}
+	/**
+	* Check if React is present in the project.
+	*/
+	async hasReact(root) {
+		return this.hasDependency(root, "react");
+	}
+	/**
+	* Install a dependency if it's missing from the project.
+	*/
+	async ensureDependency(root, packageName, options = {}) {
+		const { dev = true } = options;
+		if (await this.hasDependency(root, packageName)) {
+			this.log.debug(`Dependency '${packageName}' is already installed`);
+			return;
+		}
+		const cmd = await this.getInstallCommand(root, packageName, dev);
+		if (options.run) await options.run(cmd, {
+			alias: `add ${packageName}`,
+			root
+		});
+		else if (options.exec) {
+			this.log.debug(`Installing ${packageName}`);
+			await options.exec(cmd, {
+				global: true,
+				root
+			});
+		}
+	}
+	async ensureYarn(root) {
+		const yarnrcPath = this.fs.join(root, ".yarnrc.yml");
+		if (!await this.fs.exists(yarnrcPath)) await this.fs.writeFile(yarnrcPath, "nodeLinker: node-modules");
+		await this.removeAllPmFilesExcept(root, "yarn");
+	}
+	async ensureBun(root) {
+		await this.removeAllPmFilesExcept(root, "bun");
+	}
+	async ensurePnpm(root) {
+		await this.removeAllPmFilesExcept(root, "pnpm");
+	}
+	async ensureNpm(root) {
+		await this.removeAllPmFilesExcept(root, "npm");
+	}
+	async removeAllPmFilesExcept(root, except) {
+		if (except !== "yarn") await this.removeYarn(root);
+		if (except !== "pnpm") await this.removePnpm(root);
+		if (except !== "npm") await this.removeNpm(root);
+		if (except !== "bun") await this.removeBun(root);
+	}
+	async removeYarn(root) {
+		await this.removeFiles(root, [
+			".yarn",
+			".yarnrc.yml",
+			"yarn.lock"
+		]);
+		await this.editPackageJson(root, (pkg) => {
+			delete pkg.packageManager;
+			return pkg;
+		});
+	}
+	async removePnpm(root) {
+		await this.removeFiles(root, ["pnpm-lock.yaml", "pnpm-workspace.yaml"]);
+		await this.editPackageJson(root, (pkg) => {
+			delete pkg.packageManager;
+			return pkg;
+		});
+	}
+	async removeNpm(root) {
+		await this.removeFiles(root, ["package-lock.json"]);
+	}
+	async removeBun(root) {
+		await this.removeFiles(root, ["bun.lockb", "bun.lock"]);
+	}
+	async readPackageJson(root) {
+		const content = await this.fs.createFile({ path: this.fs.join(root, "package.json") }).text();
+		return JSON.parse(content);
+	}
+	async writePackageJson(root, content) {
+		await this.fs.writeFile(this.fs.join(root, "package.json"), JSON.stringify(content, null, 2));
+	}
+	async editPackageJson(root, editFn) {
+		try {
+			const updated = editFn(await this.readPackageJson(root));
+			await this.writePackageJson(root, updated);
+		} catch {}
+	}
+	async ensurePackageJson(root, modes) {
+		const packageJsonPath = this.fs.join(root, "package.json");
+		if (!await this.fs.exists(packageJsonPath)) {
+			const content = this.generatePackageJsonContent(modes);
+			await this.writePackageJson(root, content);
+			return content;
+		}
+		const packageJson = await this.readPackageJson(root);
+		const newContent = this.generatePackageJsonContent(modes);
+		packageJson.type = "module";
+		packageJson.dependencies ??= {};
+		packageJson.devDependencies ??= {};
+		packageJson.scripts ??= {};
+		Object.assign(packageJson.dependencies, newContent.dependencies);
+		Object.assign(packageJson.devDependencies, newContent.devDependencies);
+		Object.assign(packageJson.scripts, newContent.scripts);
+		await this.writePackageJson(root, packageJson);
+		return packageJson;
+	}
+	generatePackageJsonContent(modes) {
+		const dependencies = { alepha: `^${version}` };
+		const devDependencies = {};
+		const scripts = {
+			dev: "alepha dev",
 			build: "alepha build",
 			lint: "alepha lint",
 			typecheck: "alepha typecheck",
@@ -413,220 +604,626 @@ var AlephaCliUtils = class {
 			scripts
 		};
 	}
-	/**
-	* Ensure package.json exists and has correct configuration.
-	*
-	* Creates a new package.json if none exists, or updates an existing one to:
-	* - Set "type": "module"
-	* - Add Alepha dependencies
-	* - Add standard scripts
-	*
-	* @param root - The root directory of the project
-	* @param modes - Configuration for which dependencies to include
-	*/
-	async ensurePackageJson(root, modes) {
-		const packageJsonPath = join(root, "package.json");
-		try {
-			await access(packageJsonPath);
-		} catch (error) {
-			const obj = this.generatePackageJsonContent(modes);
-			await writeFile(packageJsonPath, JSON.stringify(obj, null, 2));
-			return obj;
-		}
-		const content = await readFile(packageJsonPath, "utf8");
-		const packageJson$1 = JSON.parse(content);
-		const newPackageJson = this.generatePackageJsonContent(modes);
-		packageJson$1.type = "module";
-		packageJson$1.dependencies ??= {};
-		packageJson$1.devDependencies ??= {};
-		packageJson$1.scripts ??= {};
-		Object.assign(packageJson$1.dependencies, newPackageJson.dependencies);
-		Object.assign(packageJson$1.devDependencies, newPackageJson.devDependencies);
-		Object.assign(packageJson$1.scripts, newPackageJson.scripts);
-		await writeFile(packageJsonPath, JSON.stringify(packageJson$1, null, 2));
-		return packageJson$1;
-	}
-	async ensureConfig(root, opts) {
-		const tasks = [];
-		if (opts.packageJson) tasks.push(this.ensurePackageJson(root, typeof opts.packageJson === "boolean" ? {} : opts.packageJson));
-		if (opts.tsconfigJson) tasks.push(this.ensureTsConfig(root));
-		if (opts.indexHtml) tasks.push(this.ensureIndexHtml(root));
-		if (opts.biomeJson) tasks.push(this.ensureBiomeConfig(root));
-		if (opts.editorconfig) tasks.push(this.ensureEditorConfig(root));
-		return await Promise.all(tasks);
-	}
-	/**
-	* Ensure tsconfig.json exists in the project.
-	*
-	* Creates a standard Alepha tsconfig.json if none exists.
-	*
-	* @param root - The root directory of the project
-	*/
-	async ensureTsConfig(root) {
-		await this.ensureFileExists(root, "tsconfig.json", tsconfigJson, true);
-	}
-	async checkFileExists(root, name, checkParentDirectories = false) {
-		const configPath = join(root, name);
-		if (!checkParentDirectories) try {
-			await access(configPath);
-			return configPath;
-		} catch {
-			return;
-		}
-		let currentDir = root;
-		const maxIterations = 10;
-		let level = 0;
-		while (level < maxIterations) {
-			try {
-				const maybe = join(currentDir, name);
-				await access(maybe);
-				return maybe;
-			} catch {
-				const parentDir = join(currentDir, "..");
-				if (parentDir === currentDir) break;
-				currentDir = parentDir;
-			}
-			level += 1;
-		}
-	}
-	async ensureFileExists(root, name, content, checkParentDirectories = false) {
-		if (!await this.checkFileExists(root, name, checkParentDirectories)) await writeFile(join(root, name), content);
+	async removeFiles(root, files) {
+		await Promise.all(files.map((file) => this.fs.rm(this.fs.join(root, file), {
+			force: true,
+			recursive: true
+		})));
 	}
+};
+
+//#endregion
+//#region ../../src/cli/assets/apiHelloControllerTs.ts
+const apiHelloControllerTs = () => `
+import { t } from "alepha";
+import { $action } from "alepha/server";
+
+export class HelloController {
+  hello = $action({
+    path: "/hello",
+    schema: {
+      response: t.object({
+        message: t.string(),
+      }),
+    },
+    handler: () => ({
+      message: "Hello, Alepha!",
+    }),
+  });
+}
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/apiIndexTs.ts
+const apiIndexTs = (options = {}) => {
+	const { appName = "app" } = options;
+	return `
+import { $module } from "alepha";
+import { HelloController } from "./controllers/HelloController.ts";
+
+export const ApiModule = $module({
+  name: "${appName}.api",
+  services: [HelloController],
+});
+`.trim();
+};
+
+//#endregion
+//#region ../../src/cli/assets/biomeJson.ts
+const biomeJson = () => `
+{
+  "$schema": "https://biomejs.dev/schemas/latest/schema.json",
+  "vcs": {
+    "enabled": true,
+    "clientKind": "git"
+  },
+  "files": {
+    "ignoreUnknown": true,
+    "includes": ["**", "!node_modules", "!dist"]
+  },
+  "formatter": {
+    "enabled": true,
+    "useEditorconfig": true
+  },
+  "linter": {
+    "enabled": true,
+    "rules": {
+      "recommended": true
+    },
+    "domains": {
+      "react": "recommended"
+    }
+  },
+  "assist": {
+    "actions": {
+      "source": {
+        "organizeImports": "on"
+      }
+    }
+  }
+}
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/claudeMd.ts
+const claudeMd = (options = {}) => {
+	const { react = false, projectName = "my-app" } = options;
+	const reactSection = react ? `
+## React & Frontend
+
+### Pages with \`$page\`
+\`\`\`tsx
+import { $page } from "@alepha/react/router";
+import { $client } from "alepha/server/links";
+import type { UserController } from "./UserController.ts";
+
+class AppRouter {
+  api = $client<UserController>();
+
+  users = $page({
+    path: "/users",
+    loader: async () => ({ users: await this.api.listUsers() }),
+    component: ({ users }) => (
+      <ul>{users.map(u => <li key={u.id}>{u.email}</li>)}</ul>
+    ),
+  });
+
+  userDetail = $page({
+    path: "/users/:id",
+    schema: { params: t.object({ id: t.uuid() }) },
+    loader: async ({ params }) => ({ user: await this.api.getUser({ params }) }),
+    lazy: () => import("./UserDetail.tsx"), // Code splitting
+  });
+}
+\`\`\`
+
+### React Hooks
+\`\`\`typescript
+import { useAlepha, useClient, useStore, useAction, useInject } from "@alepha/react";
+import { useRouter, useActive } from "@alepha/react/router";
+import { useForm } from "@alepha/react/form";
+\`\`\`
+
+- \`useClient<Controller>()\` - Type-safe API calls
+- \`useStore(atom)\` - Global state (returns \`[value, setValue]\`)
+- \`useAction({ handler })\` - Async operations with loading/error state
+- \`useRouter<AppRouter>()\` - Type-safe navigation
+- \`useForm({ schema, handler })\` - Type-safe forms with validation
+` : "";
+	const projectStructure = react ? `
+\`\`\`
+${projectName}/
+├── src/
+│   ├── api/              # Backend
+│   │   ├── controllers/  # API controllers with $action
+│   │   ├── services/     # Business logic
+│   │   ├── entities/     # Database entities with $entity
+│   │   ├── providers/    # External service wrappers
+│   │   └── index.ts      # API module definition with $module
+│   ├── web/              # Frontend (React only)
+│   │   ├── components/   # React components
+│   │   ├── atoms/        # State atoms with $atom
+│   │   ├── AppRouter.ts  # Routes with $page
+│   │   └── index.ts      # Web module definition with $module
+│   ├── main.server.ts    # Server entry
+│   ├── main.browser.ts   # Browser entry (React only)
+│   └── main.css          # CSS entry (React only)
+├── package.json
+└── tsconfig.json
+\`\`\`
+` : `
+\`\`\`
+${projectName}/
+├── src/
+│   ├── api/              # Backend
+│   │   ├── controllers/  # API controllers with $action
+│   │   ├── services/     # Business logic
+│   │   ├── entities/     # Database entities with $entity
+│   │   ├── providers/    # External service wrappers
+│   │   └── index.ts      # API module definition with $module
+│   └── main.server.ts    # Server entry (always use main.server.ts)
+├── package.json
+└── tsconfig.json
+\`\`\`
+`;
+	return `# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this Alepha project.
+
+## Overview
+
+This is an **Alepha** project - a convention-driven TypeScript framework for type-safe full-stack applications.
+
+**Key Concepts:**
+- **Primitives**: Features defined with \`$\`-prefixed functions (\`$action\`, \`$entity\`, \`$page\`)
+- **Class-Based**: Services are classes, primitives are class properties
+- **Zero-Config**: Code structure IS the configuration
+- **End-to-End Types**: Types flow from database → API → ${react ? "React" : "client"}
+
+## Rules
+
+- Use TypeScript strict mode
+- Use Biome for formatting (\`alepha lint\`)
+- Use Vitest for testing
+- One file = one class
+- Primitives are class properties (except \`$entity\`, \`$atom\`)
+- No decorators, no Express/Fastify patterns
+- No manual instantiation - use dependency injection
+- Use \`protected\` instead of \`private\` for class members
+- Import with file extensions: \`import { User } from "./User.ts"\`
+- Use \`t\` from Alepha for schemas (not Zod)
+- Prefer \`t.text()\` over \`t.string()\` for user input (has default max length, auto-trim, supports lowercase option)
+
+## Project Structure
+${projectStructure}
+## Core Primitives
+
+### API with \`$action\`
+\`\`\`typescript
+import { t } from "alepha";
+import { $action } from "alepha/server";
+
+class UserController {
+  getUser = $action({
+    path: "/users/:id",  // → GET /api/users/:id
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: t.object({ id: t.uuid(), email: t.email() }),
+    },
+    handler: async ({ params }) => this.userRepo.findById(params.id),
+  });
+
+  createUser = $action({
+    // POST inferred from body schema
+    schema: {
+      body: t.object({ email: t.email() }),
+      response: userEntity.schema,
+    },
+    handler: async ({ body }) => this.userRepo.create(body),
+  });
+}
+\`\`\`
+
+### Database with \`$entity\` and \`$repository\`
+\`\`\`typescript
+import { $entity, $repository, db } from "alepha/orm";
+
+// Entity defined at module level (for drizzle-kit compatibility)
+export const userEntity = $entity({
+  name: "users",
+  schema: t.object({
+    id: db.primaryKey(),
+    email: t.email(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+  }),
+  indexes: [{ column: "email", unique: true }],
+});
+
+class UserService {
+  repo = $repository(userEntity);
+
+  async findById(id: string) {
+    return this.repo.findById(id);
+  }
+}
+\`\`\`
+
+### Dependency Injection
+\`\`\`typescript
+import { $inject } from "alepha";
+
+class OrderService {
+  userService = $inject(UserService);  // Within same module
+
+  async createOrder(userId: string) {
+    const user = await this.userService.findById(userId);
+    // ...
+  }
+}
+
+// Cross-module: use $client instead of $inject
+class AppRouter {
+  api = $client<OrderController>();  // Type-safe HTTP client
+}
+\`\`\`
+
+### Modules with \`$module\`
+\`\`\`typescript
+// src/api/index.ts - Groups all API services
+import { $module } from "alepha";
+
+export const ApiModule = $module({
+  name: "app.api",
+  services: [
+    UserController,
+    OrderController,
+    UserService,
+  ],
+});
+
+// src/web/index.ts - Groups all web services (React only)
+export const WebModule = $module({
+  name: "app.web",
+  services: [AppRouter, Toaster],
+  register(alepha) {
+    // Optional: configure additional services
+    alepha.with(SomeLibrary);
+  },
+});
+\`\`\`
+
+### Environment Variables
+\`\`\`typescript
+import { $env, t } from "alepha";
+
+class AppConfig {
+  env = $env(t.object({
+    DATABASE_URL: t.string(),
+    API_KEY: t.optional(t.string()),
+  }));
+}
+\`\`\`
+${reactSection}
+## Quick Reference
+
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| \`$inject\` | \`alepha\` | Dependency injection |
+| \`$env\` | \`alepha\` | Environment variables |
+| \`$hook\` | \`alepha\` | Lifecycle hooks |
+| \`$logger\` | \`alepha/logger\` | Structured logging |
+| \`$action\` | \`alepha/server\` | REST API endpoints |
+| \`$route\` | \`alepha/server\` | Low-level HTTP routes |
+| \`$entity\` | \`alepha/orm\` | Database tables |
+| \`$repository\` | \`alepha/orm\` | Type-safe data access |
+| \`$queue\` | \`alepha/queue\` | Background jobs |
+| \`$scheduler\` | \`alepha/scheduler\` | Cron tasks |
+| \`$cache\` | \`alepha/cache\` | Cached computations |
+| \`$bucket\` | \`alepha/bucket\` | File storage |
+| \`$issuer\` | \`alepha/security\` | JWT tokens |
+| \`$command\` | \`alepha/command\` | CLI commands |${react ? `
+| \`$page\` | \`@alepha/react/router\` | React pages with SSR |
+| \`$atom\` | \`alepha\` | Global state |` : ""}
+
+## Testing
+
+\`\`\`typescript
+import { describe, it, expect } from "vitest";
+import { Alepha } from "alepha";
+
+describe("UserService", () => {
+  it("should create user", async () => {
+    const alepha = Alepha.create().with(UserService);
+    const service = alepha.inject(UserService);
+
+    const user = await service.create({ email: "test@example.com" });
+    expect(user.email).toBe("test@example.com");
+  });
+
+  it("should mock dependencies", async () => {
+    const alepha = Alepha.create()
+      .with(OrderService)
+      .with({ provide: PaymentGateway, use: MockPaymentGateway });
+
+    const service = alepha.inject(OrderService);
+    // PaymentGateway is now mocked
+  });
+});
+\`\`\`
+
+## Common Mistakes
+
+1. **DON'T use decorators** - Use primitives (\`$action\`, not \`@Get()\`)
+2. **DON'T use Zod** - Use TypeBox via \`t\` from Alepha
+3. **DON'T use Express patterns** - No \`app.get()\`, \`router.use()\`
+4. **DON'T inject across modules** - Use \`$client\` for cross-module calls
+5. **DON'T use async constructors** - Use \`$hook({ on: "start" })\`
+6. **DON'T instantiate manually** - Let DI container manage instances
+
+## After Code Changes
+
+Always run:
+\`\`\`bash
+alepha lint      # Format and lint
+alepha typecheck # Type checking
+alepha test      # Run tests (if applicable)
+alepha build     # Build the project
+\`\`\`
+
+## Documentation
+
+- Full docs: https://alepha.dev/llms.txt
+- Detailed docs: https://alepha.dev/llms-full.txt
+`.trim();
+};
+
+//#endregion
+//#region ../../src/cli/assets/dummySpecTs.ts
+const dummySpecTs = () => `
+import { test, expect } from "vitest";
+
+test("dummy test", () => {
+  expect(1 + 1).toBe(2);
+});
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/editorconfig.ts
+const editorconfig = () => `
+# https://editorconfig.org
+
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/mainBrowserTs.ts
+const mainBrowserTs = () => `
+import { Alepha, run } from "alepha";
+import { WebModule } from "./web/index.ts";
+
+const alepha = Alepha.create();
+
+alepha.with(WebModule);
+
+run(alepha);
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/mainCss.ts
+const mainCss = () => `
+* {
+  box-sizing: border-box;
+  margin: 0;
+  padding: 0;
+}
+
+html,
+body {
+  height: 100%;
+}
+
+body {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+#root {
+  height: 100%;
+}
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/mainServerTs.ts
+const mainServerTs = (options = {}) => {
+	const { react = false } = options;
+	return `
+import { Alepha, run } from "alepha";
+import { ApiModule } from "./api/index.ts";
+${react ? `import { WebModule } from "./web/index.ts";\n` : ""}
+const alepha = Alepha.create();
+
+alepha.with(ApiModule);
+${react ? `alepha.with(WebModule);\n` : ""}
+run(alepha);
+`.trim();
+};
+
+//#endregion
+//#region ../../src/cli/assets/tsconfigJson.ts
+const tsconfigJson = () => `
+{
+  "extends": "alepha/tsconfig.base"
+}
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/webAppRouterTs.ts
+const webAppRouterTs = () => `
+import { $page } from "@alepha/react/router";
+import { $client } from "alepha/server/links";
+import type { HelloController } from "../api/controllers/HelloController.ts";
+
+export class AppRouter {
+  api = $client<HelloController>();
+
+  home = $page({
+    path: "/",
+    lazy: () => import("./components/Hello.tsx"),
+    loader: () => this.api.hello(),
+  });
+}
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/webHelloComponentTsx.ts
+const webHelloComponentTsx = () => `import { useState } from "react";
+
+interface Props {
+  message: string;
+}
+
+const Hello = (props: Props) => {
+  const [message, setMessage] = useState(props.message);
+  return (
+    <div>
+      <h1>{message}</h1>
+      <input value={message} onChange={e => setMessage(e.target.value)} />
+      <p>Edit this component in src/web/components/Hello.tsx</p>
+    </div>
+  );
+};
+
+export default Hello;
+`.trim();
+
+//#endregion
+//#region ../../src/cli/assets/webIndexTs.ts
+const webIndexTs = (options = {}) => {
+	const { appName = "app" } = options;
+	return `
+import { $module } from "alepha";
+import { AppRouter } from "./AppRouter.ts";
+
+export const WebModule = $module({
+  name: "${appName}.web",
+  services: [AppRouter],
+});
+`.trim();
+};
+
+//#endregion
+//#region ../../src/cli/services/ProjectScaffolder.ts
+/**
+* Service for scaffolding new Alepha projects.
+*
+* Handles creation of:
+* - Project structure (src/api, src/web)
+* - Configuration files (tsconfig, biome, editorconfig)
+* - Entry points (main.server.ts, main.browser.ts)
+* - Example code (HelloController, Hello component)
+*/
+var ProjectScaffolder = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
+	pm = $inject(PackageManagerUtils);
 	/**
-	* Get the path to Biome configuration file.
+	* Get the app name from the directory name.
 	*
-	* Looks for an existing biome.json in the project root, or creates one if it doesn't exist.
+	* Converts the directory name to a valid module name:
+	* - Converts to lowercase
+	* - Replaces spaces, dashes, underscores with nothing
+	* - Falls back to "app" if empty
 	*/
-	async ensureBiomeConfig(root) {
-		await this.ensureFileExists(root, "biome.json", biomeJson, true);
+	getAppName(root) {
+		return basename(root).toLowerCase().replace(/[\s\-_]/g, "") || "app";
 	}
 	/**
-	* Ensure .editorconfig exists in the project.
-	*
-	* Creates a standard .editorconfig if none exists.
-	*
-	* @param root - The root directory of the project
+	* Ensure all configuration files exist.
 	*/
-	async ensureEditorConfig(root) {
-		await this.ensureFileExists(root, ".editorconfig", editorconfig, true);
+	async ensureConfig(root, opts) {
+		const tasks = [];
+		const force = opts.force ?? false;
+		if (opts.packageJson) tasks.push(this.pm.ensurePackageJson(root, typeof opts.packageJson === "boolean" ? {} : opts.packageJson).then(() => {}));
+		if (opts.tsconfigJson) tasks.push(this.ensureTsConfig(root, { force }));
+		if (opts.indexHtml) tasks.push(this.ensureReactProject(root, { force }));
+		if (opts.biomeJson) tasks.push(this.ensureBiomeConfig(root, { force }));
+		if (opts.editorconfig) tasks.push(this.ensureEditorConfig(root, { force }));
+		if (opts.claudeMd) tasks.push(this.ensureClaudeMd(root, typeof opts.claudeMd === "boolean" ? { force } : {
+			...opts.claudeMd,
+			force
+		}));
+		await Promise.all(tasks);
 	}
-	/**
-	* Load Alepha instance from a server entry file.
-	*
-	* Dynamically imports the server entry file and extracts the Alepha instance.
-	* Skips the automatic start process.
-	*
-	* @param rootDir - The root directory of the project
-	* @param explicitEntry - Optional explicit path to the entry file
-	* @returns Object containing the Alepha instance and the entry file path
-	* @throws {AlephaError} If the Alepha instance cannot be found
-	*/
-	async loadAlephaFromServerEntryFile(rootDir, explicitEntry) {
-		process.env.ALEPHA_CLI_IMPORT = "true";
-		const entry = await boot.getServerEntry(rootDir, explicitEntry);
-		delete global.__alepha;
-		const mod = await import(entry);
-		this.log.debug(`Load entry: ${entry}`);
-		if (mod.default instanceof Alepha) return {
-			alepha: mod.default,
-			entry
-		};
-		const g = global;
-		if (g.__alepha) return {
-			alepha: g.__alepha,
-			entry
-		};
-		throw new AlephaError(`Could not find Alepha instance in entry file: ${entry}`);
+	async ensureTsConfig(root, opts = {}) {
+		if (!opts.force && await this.existsInParents(root, "tsconfig.json")) return;
+		await this.fs.writeFile(this.fs.join(root, "tsconfig.json"), tsconfigJson());
 	}
-	/**
-	* Generate JavaScript code for Drizzle entities export.
-	*
-	* Creates a temporary entities.js file that imports from the entry file
-	* and exports database models for Drizzle Kit to process.
-	*
-	* @param entry - Path to the server entry file
-	* @param provider - Name of the database provider
-	* @param models - Array of model names to export
-	* @returns JavaScript code as a string
-	*/
-	generateEntitiesJs(entry, provider, models = []) {
-		return `
-import "${entry}";
-import { DrizzleKitProvider, Repository } from "alepha/orm";
-
-const alepha = globalThis.__alepha;
-const kit = alepha.inject(DrizzleKitProvider);
-const provider = alepha.services(Repository).find((it) => it.provider.name === "${provider}").provider;
-const models = kit.getModels(provider);
-
-${models.map((it) => `export const ${it} = models["${it}"];`).join("\n")}
-
-`.trim();
+	async ensureBiomeConfig(root, opts = {}) {
+		await this.ensureFile(root, "biome.json", biomeJson(), opts.force);
+	}
+	async ensureEditorConfig(root, opts = {}) {
+		await this.ensureFile(root, ".editorconfig", editorconfig(), opts.force);
+	}
+	async ensureClaudeMd(root, options = {}) {
+		await this.ensureFile(root, "CLAUDE.md", claudeMd(options), options.force);
 	}
 	/**
-	* Load environment variables from a .env file.
+	* Ensure src/main.server.ts exists with full API structure.
 	*
-	* Reads the .env file in the specified root directory and sets
-	* the environment variables in process.env.
+	* Creates:
+	* - src/main.server.ts (entry point)
+	* - src/api/index.ts (API module)
+	* - src/api/controllers/HelloController.ts (example controller)
 	*/
-	async loadEnv(root, files = [".env"]) {
-		await this.envUtils.loadEnv(root, files);
-	}
-	async getPackageManager(root, flags) {
-		if (flags?.yarn) return "yarn";
-		if (flags?.pnpm) return "pnpm";
-		if (flags?.npm) return "npm";
-		if (flags?.bun) return "bun";
-		if (this.alepha.isBun()) return "bun";
-		if (await this.checkFileExists(root, "yarn.lock", true)) return "yarn";
-		if (await this.checkFileExists(root, "pnpm-lock.yaml", true)) return "pnpm";
-		return "npm";
-	}
-	async ensureIndexHtml(root) {
-		if (await this.fs.exists(join(root, "index.html"))) return;
-		const serverEntry = "src/main.server.ts";
-		const browserEntry = "src/main.browser.ts";
-		const appRouter = "src/AppRouter.ts";
-		await this.fs.writeFile(join(root, "index.html"), indexHtml(browserEntry));
-		try {
-			await this.fs.mkdir(join(root, "src"), { recursive: true });
-		} catch {}
-		if (!await this.fs.exists(join(root, browserEntry))) await this.fs.writeFile(join(root, browserEntry), mainBrowserTs());
-		if (!await this.fs.exists(join(root, serverEntry))) await this.fs.writeFile(join(root, serverEntry), mainBrowserTs());
-		if (!await this.fs.exists(join(root, appRouter))) await this.fs.writeFile(join(root, appRouter), appRouterTs());
-	}
-	async exists(root, dirName) {
-		return this.fs.exists(join(root, dirName));
+	async ensureApiProject(root, opts = {}) {
+		const srcDir = this.fs.join(root, "src");
+		if (!opts.force && await this.fs.exists(srcDir)) {
+			if ((await this.fs.ls(srcDir)).length > 0) return;
+		}
+		const appName = this.getAppName(root);
+		await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), { recursive: true });
+		await this.ensureFile(srcDir, "main.server.ts", mainServerTs(), opts.force);
+		await this.ensureFile(srcDir, "api/index.ts", apiIndexTs({ appName }), opts.force);
+		await this.ensureFile(srcDir, "api/controllers/HelloController.ts", apiHelloControllerTs(), opts.force);
 	}
 	/**
-	* Ensure src/main.ts exists with a minimal Alepha bootstrap.
+	* Ensure full React project structure exists.
 	*
-	* Creates the src directory and main.ts file if the src directory
-	* doesn't exist or is empty.
-	*
-	* @param root - The root directory of the project
+	* Creates:
+	* - src/main.server.ts, src/main.browser.ts
+	* - src/api/index.ts, src/api/controllers/HelloController.ts
+	* - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
 	*/
-	async ensureSrcMain(root) {
-		const srcDir = join(root, "src");
-		const mainPath = join(srcDir, "main.ts");
-		if (!await this.fs.exists(srcDir)) {
-			await this.fs.mkdir(srcDir, { recursive: true });
-			await this.fs.writeFile(mainPath, mainTs());
-			return;
-		}
-		if ((await this.fs.ls(srcDir)).length === 0) await this.fs.writeFile(mainPath, mainTs());
+	async ensureReactProject(root, opts = {}) {
+		const appName = this.getAppName(root);
+		await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), { recursive: true });
+		await this.fs.mkdir(this.fs.join(root, "src/web/components"), { recursive: true });
+		await this.ensureFile(root, "src/main.css", mainCss(), opts.force);
+		await this.ensureFile(root, "src/api/index.ts", apiIndexTs({ appName }), opts.force);
+		await this.ensureFile(root, "src/api/controllers/HelloController.ts", apiHelloControllerTs(), opts.force);
+		await this.ensureFile(root, "src/main.server.ts", mainServerTs({ react: true }), opts.force);
+		await this.ensureFile(root, "src/web/index.ts", webIndexTs({ appName }), opts.force);
+		await this.ensureFile(root, "src/web/AppRouter.ts", webAppRouterTs(), opts.force);
+		await this.ensureFile(root, "src/web/components/Hello.tsx", webHelloComponentTsx(), opts.force);
+		await this.ensureFile(root, "src/main.browser.ts", mainBrowserTs(), opts.force);
 	}
 	/**
 	* Ensure test directory exists with a dummy test file.
-	*
-	* Creates the test directory and a dummy.spec.ts file if the test directory
-	* doesn't exist or is empty.
-	*
-	* @param root - The root directory of the project
 	*/
 	async ensureTestDir(root) {
-		const testDir = join(root, "test");
-		const dummyPath = join(testDir, "dummy.spec.ts");
+		const testDir = this.fs.join(root, "test");
+		const dummyPath = this.fs.join(testDir, "dummy.spec.ts");
 		if (!await this.fs.exists(testDir)) {
 			await this.fs.mkdir(testDir, { recursive: true });
 			await this.fs.writeFile(dummyPath, dummySpecTs());
@@ -634,68 +1231,23 @@ ${models.map((it) => `export const ${it} = models["${it}"];`).join("\n")}
 		}
 		if ((await this.fs.ls(testDir)).length === 0) await this.fs.writeFile(dummyPath, dummySpecTs());
 	}
-	async readPackageJson(root) {
-		const packageJson$1 = await this.fs.createFile({ path: this.fs.join(root, "package.json") }).text();
-		return JSON.parse(packageJson$1);
-	}
-	/**
-	* Check if a dependency is installed in the project.
-	*
-	* @param root - The root directory of the project
-	* @param packageName - The name of the package to check
-	* @returns True if the package is in dependencies or devDependencies
-	*/
-	async hasDependency(root, packageName) {
-		try {
-			const pkg = await this.readPackageJson(root);
-			return !!(pkg.dependencies?.[packageName] || pkg.devDependencies?.[packageName]);
-		} catch {
-			return false;
-		}
-	}
 	/**
-	* Check if Expo is present in the project.
-	*
-	* @param root - The root directory of the project
-	* @returns True if expo is in dependencies or devDependencies
+	* Write a file, optionally overriding if it exists.
 	*/
-	async hasExpo(root) {
-		return this.hasDependency(root, "expo");
-	}
-	async getInstallCommand(root, packageName, dev = true) {
-		const pm = await this.getPackageManager(root);
-		let cmd;
-		switch (pm) {
-			case "yarn":
-				cmd = `yarn add ${dev ? "-D" : ""} ${packageName}`;
-				break;
-			case "pnpm":
-				cmd = `pnpm add ${dev ? "-D" : ""} ${packageName}`;
-				break;
-			case "bun":
-				cmd = `bun add ${dev ? "-d" : ""} ${packageName}`;
-				break;
-			default: cmd = `npm install ${dev ? "--save-dev" : ""} ${packageName}`;
-		}
-		return cmd.replace(/\s+/g, " ").trim();
+	async ensureFile(root, relativePath, content, force) {
+		const fullPath = this.fs.join(root, relativePath);
+		if (force || !await this.fs.exists(fullPath)) await this.fs.writeFile(fullPath, content);
 	}
 	/**
-	* Install a dependency if it's missing from the project.
-	*
-	* Automatically detects the package manager (yarn, pnpm, npm) and installs
-	* the package as a dev dependency if not already present.
+	* Check if a file exists in the given directory or any parent directory.
 	*/
-	async ensureDependency(root, packageName, options = {}) {
-		const { dev = true } = options;
-		if (await this.hasDependency(root, packageName)) {
-			this.log.debug(`Dependency '${packageName}' is already installed`);
-			return;
-		}
-		const cmd = await this.getInstallCommand(root, packageName, dev);
-		if (options.run) await options.run(cmd, { alias: `installing ${packageName}` });
-		else {
-			this.log.debug(`Installing ${packageName}`);
-			await this.exec(cmd, { global: true });
+	async existsInParents(root, filename) {
+		let current = root;
+		while (true) {
+			if (await this.fs.exists(this.fs.join(current, filename))) return true;
+			const parent = dirname(current);
+			if (parent === current) return false;
+			current = parent;
 		}
 	}
 };
@@ -704,70 +1256,93 @@ ${models.map((it) => `export const ${it} = models["${it}"];`).join("\n")}
 //#region ../../src/cli/commands/build.ts
 var BuildCommand = class {
 	log = $logger();
+	fs = $inject(FileSystemProvider);
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
+	scaffolder = $inject(ProjectScaffolder);
+	boot = $inject(AppEntryProvider);
+	viteBuildProvider = $inject(ViteBuildProvider);
 	options = $use(buildOptions);
 	build = $command({
 		name: "build",
 		mode: "production",
 		description: "Build the project for production",
-		args: t.optional(t.text({
-			title: "path",
-			description: "Filepath to build"
-		})),
 		flags: t.object({
 			stats: t.optional(t.boolean({ description: "Generate build stats report" })),
 			vercel: t.optional(t.boolean({ description: "Generate Vercel deployment configuration" })),
 			cloudflare: t.optional(t.boolean({ description: "Generate Cloudflare Workers configuration" })),
 			docker: t.optional(t.boolean({ description: "Generate Docker configuration" })),
-			sitemap: t.optional(t.text({ description: "Generate sitemap.xml with base URL" }))
+			sitemap: t.optional(t.text({ description: "Generate sitemap.xml with base URL" })),
+			bun: t.optional(t.boolean({ description: "Prioritize .bun.ts entry files for Bun runtime" }))
 		}),
-		handler: async ({ flags, args, run, root }) => {
-			process.env.ALEPHA_BUILD_MODE = "cli";
+		handler: async ({ flags, run, root }) => {
 			process.env.NODE_ENV = "production";
-			if (await this.utils.hasExpo(root)) return;
-			await this.utils.ensureConfig(root, { tsconfigJson: true });
-			const entry = await boot.getServerEntry(root, args);
+			if (await this.pm.hasExpo(root)) return;
+			await this.scaffolder.ensureConfig(root, { tsconfigJson: true });
+			const entry = await this.boot.getAppEntry(root);
 			this.log.trace("Entry file found", { entry });
 			const distDir = "dist";
-			const clientDir = "public";
-			await this.utils.ensureDependency(root, "vite", { run });
+			const publicDir = "public";
+			await this.pm.ensureDependency(root, "vite", {
+				run,
+				exec: (cmd, opts) => this.utils.exec(cmd, opts)
+			});
 			await run.rm("dist", { alias: "clean dist" });
 			const options = this.options;
 			await this.utils.loadEnv(root, [".env", ".env.production"]);
 			const stats = flags.stats ?? options.stats ?? false;
+			let template = "";
 			let hasClient = false;
-			try {
-				await access(join(root, "index.html"));
-				hasClient = true;
-			} catch {}
-			if (hasClient) await run({
-				name: "vite build client",
-				handler: () => buildClient({
-					silent: true,
-					dist: `${distDir}/${clientDir}`,
-					stats,
-					precompress: true
-				})
+			let alepha;
+			await run({
+				name: "analyze app",
+				handler: async () => {
+					alepha = await this.viteBuildProvider.init({ entry });
+					hasClient = this.viteBuildProvider.hasClient();
+					if (hasClient) template = this.viteBuildProvider.generateIndexHtml();
+				}
 			});
+			if (!alepha) throw new AlephaError("Alepha instance not found");
+			if (hasClient) {
+				const indexHtmlPath = this.fs.join(root, "index.html");
+				await this.fs.writeFile(indexHtmlPath, template);
+				try {
+					await run({
+						name: "vite build client",
+						handler: () => buildClient({
+							silent: true,
+							dist: `${distDir}/${publicDir}`,
+							stats,
+							precompress: true
+						})
+					});
+				} finally {
+					await this.fs.rm(indexHtmlPath);
+				}
+			}
 			await run({
 				name: "vite build server",
 				handler: async () => {
-					let clientBuilt = false;
-					try {
-						await readFile(`${distDir}/${clientDir}/index.html`, "utf-8");
-						clientBuilt = true;
-					} catch {}
+					if (!alepha) throw new AlephaError("Alepha instance not found");
+					const clientIndexPath = `${distDir}/${publicDir}/index.html`;
+					const clientBuilt = await this.fs.exists(clientIndexPath);
+					const conditions = [];
+					if (flags.bun) conditions.push("bun");
+					if (options.cloudflare) conditions.push("workerd");
 					await buildServer({
 						silent: true,
-						entry,
+						entry: entry.server,
 						distDir,
-						clientDir: clientBuilt ? clientDir : void 0,
-						stats
+						clientDir: clientBuilt ? publicDir : void 0,
+						stats,
+						conditions,
+						alepha
 					});
-					if (clientBuilt) await unlink(`${distDir}/${clientDir}/index.html`);
+					if (clientBuilt) await this.fs.rm(clientIndexPath);
 				}
 			});
 			await copyAssets({
+				alepha,
 				root,
 				entry: `${distDir}/index.js`,
 				distDir,
@@ -775,31 +1350,24 @@ var BuildCommand = class {
 			});
 			if (hasClient) {
 				const sitemapHostname = flags.sitemap ?? options.sitemap?.hostname;
-				if (sitemapHostname) await run({
-					name: "add sitemap",
-					handler: async () => {
-						await writeFile(`${distDir}/${clientDir}/sitemap.xml`, await generateSitemap({
-							entry: `${distDir}/index.js`,
-							baseUrl: sitemapHostname
-						}));
-					}
+				if (sitemapHostname) await generateSitemap({
+					alepha,
+					baseUrl: sitemapHostname,
+					output: `${distDir}/${publicDir}/sitemap.xml`,
+					run
 				});
-				await run({
-					name: "pre-render pages",
-					handler: async () => {
-						await prerenderPages({
-							dist: `${distDir}/${clientDir}`,
-							entry: `${distDir}/index.js`,
-							compress: true
-						});
-					}
+				await prerenderPages({
+					alepha,
+					dist: `${distDir}/${publicDir}`,
+					compress: true,
+					run
 				});
 			}
 			if (flags.vercel || options.vercel) await run({
 				name: "add Vercel config",
 				handler: () => generateVercel({
 					distDir,
-					clientDir,
+					clientDir: publicDir,
 					config: options.vercel
 				})
 			});
@@ -844,6 +1412,7 @@ const drizzleCommandFlags = t.object({
 });
 var DbCommand = class {
 	log = $logger();
+	fs = $inject(FileSystemProvider);
 	utils = $inject(AlephaCliUtils);
 	/**
 	* Check if database migrations are up to date.
@@ -868,15 +1437,16 @@ var DbCommand = class {
 				const providerName = provider.name;
 				if (accepted.has(providerName)) continue;
 				accepted.add(providerName);
-				const migrationDir = join(rootDir, "migrations", providerName);
-				const journalFile = await readFile(`${migrationDir}/meta/_journal.json`, "utf-8").catch(() => null);
-				if (!journalFile) {
+				const migrationDir = this.fs.join(rootDir, "migrations", providerName);
+				const journalBuffer = await this.fs.readFile(`${migrationDir}/meta/_journal.json`).catch(() => null);
+				if (!journalBuffer) {
 					this.log.info("No migration journal found.");
 					return;
 				}
-				const journal = JSON.parse(journalFile);
+				const journal = JSON.parse(journalBuffer.toString("utf-8"));
 				const lastMigration = journal.entries[journal.entries.length - 1];
-				const lastSnapshot = JSON.parse(await readFile(`${migrationDir}/meta/${String(lastMigration.idx).padStart(4, "0")}_snapshot.json`, "utf-8"));
+				const snapshotBuffer = await this.fs.readFile(`${migrationDir}/meta/${String(lastMigration.idx).padStart(4, "0")}_snapshot.json`);
+				const lastSnapshot = JSON.parse(snapshotBuffer.toString("utf-8"));
 				const models = drizzleKitProvider.getModels(provider);
 				const kit = drizzleKitProvider.importDrizzleKit();
 				const now = kit.generateDrizzleJson(models, lastSnapshot.id);
@@ -1030,6 +1600,7 @@ var DbCommand = class {
 			const provider = primitive.provider;
 			const providerName = provider.name;
 			const dialect = provider.dialect;
+			if (providerName === "") continue;
 			if (accepted.has(providerName)) continue;
 			accepted.add(providerName);
 			if (options.provider && options.provider !== providerName) {
@@ -1043,6 +1614,7 @@ var DbCommand = class {
 				provider,
 				providerName,
 				providerUrl: provider.url,
+				providerDriver: provider.driver,
 				dialect,
 				entry,
 				rootDir
@@ -1064,9 +1636,9 @@ var DbCommand = class {
 			dbCredentials: { url: options.providerUrl }
 		};
 		if (options.provider.schema) config.schemaFilter = options.provider.schema;
-		if (options.providerName === "d1") config.driver = "d1-http";
-		if (options.providerName === "pglite") config.driver = "pglite";
-		if (options.dialect === "sqlite") if (options.providerName === "d1") {
+		if (options.providerDriver === "d1") config.driver = "d1-http";
+		if (options.providerDriver === "pglite") config.driver = "pglite";
+		if (options.dialect === "sqlite") if (options.providerDriver === "d1") {
 			const token = process.env.CLOUDFLARE_API_TOKEN;
 			if (!token) throw new AlephaError("CLOUDFLARE_API_TOKEN environment variable is not set. https://orm.drizzle.team/docs/guides/d1-http-with-drizzle-kit");
 			const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
@@ -1083,7 +1655,7 @@ var DbCommand = class {
 		} else {
 			let url = options.providerUrl;
 			url = url.replace("sqlite://", "").replace("file://", "");
-			url = join(options.rootDir, url);
+			url = this.fs.join(options.rootDir, url);
 			config.dbCredentials = { url };
 		}
 		const drizzleConfigJs = `export default ${JSON.stringify(config, null, 2)}`;
@@ -1095,7 +1667,9 @@ var DbCommand = class {
 //#region ../../src/cli/commands/deploy.ts
 var DeployCommand = class {
 	log = $logger();
+	fs = $inject(FileSystemProvider);
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
 	/**
 	* Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)
 	*
@@ -1143,7 +1717,10 @@ var DeployCommand = class {
 					this.log.debug("Running database migrations before deployment...");
 					await this.utils.exec(`alepha db migrate --mode=${mode}`);
 				}
-				await this.utils.ensureDependency(root, "vercel", { dev: true });
+				await this.pm.ensureDependency(root, "vercel", {
+					dev: true,
+					exec: (cmd, opts) => this.utils.exec(cmd, opts)
+				});
 				const command = `vercel . --cwd=dist ${mode === "production" ? "--prod" : ""}`.trim();
 				this.log.debug(`Deploying to Vercel with command: ${command}`);
 				await this.utils.exec(command);
@@ -1154,15 +1731,21 @@ var DeployCommand = class {
 					this.log.debug("Running database migrations before deployment...");
 					await this.utils.exec(`alepha db migrate --mode=${mode}`);
 				}
-				await this.utils.ensureDependency(root, "wrangler", { dev: true });
+				await this.pm.ensureDependency(root, "wrangler", {
+					dev: true,
+					exec: (cmd, opts) => this.utils.exec(cmd, opts)
+				});
 				const command = `wrangler deploy ${mode === "production" ? "" : "--env preview"} --config=dist/wrangler.jsonc`.trim();
 				this.log.info(`Deploying to Cloudflare with command: ${command}`);
 				await this.utils.exec(command);
 				return;
 			}
 			if (await this.utils.exists(root, "dist/public/404.html")) {
-				await this.utils.ensureDependency(root, "surge", { dev: true });
-				const distPath = join(root, "dist/public");
+				await this.pm.ensureDependency(root, "surge", {
+					dev: true,
+					exec: (cmd, opts) => this.utils.exec(cmd, opts)
+				});
+				const distPath = this.fs.join(root, "dist/public");
 				this.log.debug(`Deploying to Surge from directory: ${distPath}`);
 				await this.utils.exec(`surge ${distPath}`);
 				return;
@@ -1173,75 +1756,271 @@ var DeployCommand = class {
 };
 
 //#endregion
-//#region ../../src/cli/commands/dev.ts
-var DevCommand = class {
+//#region ../../src/cli/providers/ViteDevServerProvider.ts
+/**
+* Vite development server with Alepha integration.
+*
+* Architecture:
+* - Vite runs in middleware mode (no HTTP server)
+* - Alepha is the HTTP server via server:onRequest event
+* - Request flow: Page requests → Alepha SSR, Assets → Vite middleware
+*
+* HMR Strategy:
+* - Browser-only changes (CSS, client components) → Vite HMR (React Fast Refresh)
+* - Server-only changes → Restart Alepha → Full browser reload
+* - Shared changes → Restart Alepha → Let Vite HMR propagate
+*
+* Features:
+* - Automatic .env reload detection
+* - Error recovery on next file change
+* - Optimized module invalidation (only changed files + importers)
+*/
+var ViteDevServerProvider = class {
 	log = $logger();
-	utils = $inject(AlephaCliUtils);
-	alepha = $inject(Alepha);
+	fs = $inject(FileSystemProvider);
+	templateProvider = $inject(ViteTemplateProvider);
+	server;
+	options;
+	alepha = null;
+	hasError = false;
+	changedFiles = /* @__PURE__ */ new Set();
+	async init(options) {
+		this.options = options;
+		await this.createViteServer();
+		return await this.loadAlepha(true);
+	}
+	async start() {
+		await this.alepha?.start();
+	}
 	/**
-	* Will run the project in watch mode.
-	*
-	* - If an index.html file is found in the project root, it will run Vite in dev mode.
-	* - Otherwise, it will look for a server entry file and run it with tsx in watch mode.
+	* Create the Vite server in middleware mode.
 	*/
-	dev = $command({
-		name: "dev",
-		description: "Run the project in development mode",
-		args: t.optional(t.text({
-			title: "path",
-			description: "Filepath to run"
-		})),
-		handler: async ({ args, root }) => {
-			const expo = await this.utils.hasExpo(root);
-			await this.utils.ensureConfig(root, { tsconfigJson: true });
-			if (expo) {
-				await this.utils.exec("expo start");
-				return;
+	async createViteServer() {
+		const { createServer } = await importVite();
+		const viteReact = await importViteReact();
+		const plugins = [];
+		if (viteReact) plugins.push(viteReact());
+		plugins.push(viteAlephaSsrPreload());
+		plugins.push(this.createHmrPlugin());
+		this.server = await createServer({
+			root: this.options.root,
+			plugins,
+			server: { middlewareMode: true },
+			appType: "custom",
+			customLogger: {
+				info: () => {},
+				warn: this.log.warn.bind(this.log),
+				error: this.log.error.bind(this.log),
+				warnOnce: this.log.warn.bind(this.log),
+				clearScreen: () => {},
+				hasWarned: false,
+				hasErrorLogged: () => false
 			}
-			const entry = await boot.getServerEntry(root, args);
-			this.log.trace("Entry file found", { entry });
-			if (!await this.isFullstackProject(root)) {
-				const exe = await this.isBunProject(root) ? "bun" : "tsx";
-				let cmd = `${exe} --watch`;
-				if (await this.utils.exists(root, ".env")) cmd += " --env-file=./.env";
-				cmd += ` ${entry}`;
-				await this.utils.exec(cmd, { global: exe === "bun" });
-				return;
+		});
+		this.server.restart = async () => {
+			const startTime = Date.now();
+			try {
+				this.hasError = true;
+				await this.loadAlepha(false);
+				await this.alepha?.start();
+				this.log.debug(`Env reloaded in ${Date.now() - startTime}ms`);
+				this.sendBrowserReload();
+			} catch (err) {
+				this.hasError = true;
+				this.log.error("Reload failed", err);
+				this.log.warn("Waiting for file changes to retry...");
+				this.alepha = null;
+			}
+		};
+	}
+	/**
+	* Vite plugin to handle HMR for Alepha.
+	*/
+	createHmrPlugin() {
+		return {
+			name: "alepha-hmr",
+			handleHotUpdate: async (ctx) => {
+				if (ctx.file.includes("/.idea/")) return [];
+				const firstModule = ctx.modules[0];
+				const isBrowserOnly = firstModule && !firstModule._ssrModule;
+				const isServerOnly = firstModule && !firstModule._clientModule;
+				if (isBrowserOnly) return;
+				const startTime = Date.now();
+				try {
+					this.changedFiles.add(ctx.file);
+					await this.loadAlepha(false);
+					await this.alepha?.start();
+					this.log.debug(`Reloaded in ${Date.now() - startTime}ms`);
+					if (isServerOnly) {
+						this.sendBrowserReload();
+						return [];
+					}
+					return;
+				} catch (err) {
+					this.hasError = true;
+					this.log.error("Reload failed", err);
+					this.log.warn("Waiting for file changes to retry...");
+					this.alepha = null;
+					return [];
+				}
 			}
-			await this.utils.ensureDependency(root, "vite");
-			await devServer();
+		};
+	}
+	/**
+	* Send browser reload signal via custom event.
+	* Browser listens for 'alepha:reload' and does window.location.reload()
+	*/
+	sendBrowserReload() {
+		this.server.ws.send({
+			type: "custom",
+			event: "alepha:reload",
+			data: {}
+		});
+	}
+	/**
+	* Setup environment variables for dev mode.
+	*/
+	async setupEnvironment() {
+		const { loadEnv } = await importVite();
+		const env = loadEnv(process.env.NODE_ENV || "development", this.options.root, "");
+		process.env.NODE_ENV ??= "development";
+		process.env.VITE_ALEPHA_DEV = "true";
+		process.env.SERVER_HOST ??= this.options.host?.toString() ?? "localhost";
+		process.env.SERVER_PORT ??= String(this.options.port ?? (process.env.SERVER_PORT ? Number(process.env.SERVER_PORT) : 3e3));
+		for (const [key, value] of Object.entries(env)) process.env[key] ??= value;
+	}
+	/**
+	* Load or reload the Alepha instance.
+	*/
+	async loadAlepha(isInitialLoad = false) {
+		if (this.alepha) {
+			await this.alepha.stop().catch((err) => this.log.warn("Error stopping Alepha", err));
+			this.alepha = null;
 		}
-	});
-	async isBunProject(root) {
-		if (this.alepha.isBun()) return true;
+		if (isInitialLoad || this.hasError) this.server.moduleGraph.invalidateAll();
+		else this.invalidateModulesWithImporters();
+		this.changedFiles.clear();
+		const envSnapshot = { ...process.env };
+		await this.setupEnvironment();
+		await this.server.ssrLoadModule(this.options.entry.server);
+		const alepha = globalThis.__alepha;
+		if (!alepha) throw new AlephaError("Alepha instance not found after loading entry module");
+		this.alepha = alepha;
+		await this.setupAlepha();
+		this.hasError = false;
+		process.env = envSnapshot;
+		return alepha;
+	}
+	hasReact() {
 		try {
-			await access(join(root, "bun.lock"));
+			this.alepha?.inject("ReactServerProvider");
 			return true;
 		} catch {
 			return false;
 		}
 	}
-	async isFullstackProject(root) {
-		try {
-			await access(join(root, "index.html"));
-			return true;
-		} catch {
-			return false;
+	/**
+	* Setup Alepha instance with Vite middleware and template.
+	*/
+	async setupAlepha() {
+		if (!this.alepha || !this.hasReact()) return;
+		const template = await this.server.transformIndexHtml("/", this.templateProvider.generateIndexHtml(this.options.entry));
+		this.alepha.store.set("alepha.react.server.template", template);
+		this.alepha.events.on("server:onRequest", {
+			priority: "first",
+			callback: async ({ request }) => {
+				const node = request.raw.node;
+				if (!node || this.isPageRequest(node.req)) return;
+				if (await this.runViteMiddleware(node.req, node.res, request)) {
+					request.reply.status = node.res.statusCode || 200;
+					request.reply.body = null;
+				}
+			}
+		});
+	}
+	/**
+	* Check if request is for an HTML page (not an asset).
+	*/
+	isPageRequest(req) {
+		const url = req.url || "/";
+		if (url === "/" || url === "/index.html") return true;
+		if (url.startsWith("/@") || url.startsWith("/__vite")) return false;
+		if (/\.\w+$/.test(url.split("?")[0])) return false;
+		return true;
+	}
+	/**
+	* Run Vite middleware and detect if it handled the request.
+	*/
+	async runViteMiddleware(req, res, ctx) {
+		return new Promise((resolve) => {
+			let resolved = false;
+			const done = (handled) => {
+				if (resolved) return;
+				resolved = true;
+				if (handled) ctx.metadata.vite = true;
+				resolve(handled);
+			};
+			res.on("finish", () => done(true));
+			res.on("close", () => res.headersSent && done(true));
+			this.server.middlewares(req, res, () => done(false));
+			setImmediate(() => {
+				if (res.headersSent || res.writableEnded) done(true);
+			});
+		});
+	}
+	/**
+	* Invalidate modules and all their importers.
+	*/
+	invalidateModulesWithImporters() {
+		const invalidated = /* @__PURE__ */ new Set();
+		const queue = [...this.changedFiles];
+		while (queue.length > 0) {
+			const file = queue.pop();
+			if (invalidated.has(file)) continue;
+			const mod = this.server.moduleGraph.getModuleById(file);
+			if (!mod) continue;
+			this.server.moduleGraph.invalidateModule(mod);
+			invalidated.add(file);
+			for (const importer of mod.importers) if (importer.id && !invalidated.has(importer.id)) queue.push(importer.id);
 		}
 	}
 };
 
 //#endregion
-//#region ../../src/cli/commands/format.ts
-var FormatCommand = class {
+//#region ../../src/cli/commands/dev.ts
+var DevCommand = class {
+	log = $logger();
+	fs = $inject(FileSystemProvider);
 	utils = $inject(AlephaCliUtils);
-	format = $command({
-		name: "format",
-		description: "Format the codebase using Biome",
+	pm = $inject(PackageManagerUtils);
+	scaffolder = $inject(ProjectScaffolder);
+	alepha = $inject(Alepha);
+	viteDevServer = $inject(ViteDevServerProvider);
+	boot = $inject(AppEntryProvider);
+	/**
+	* Will run the project in watch mode.
+	*
+	* - If an index.html file is found in the project root, it will run Vite in dev mode.
+	* - Otherwise, it will look for a server entry file and run it with tsx in watch mode.
+	*/
+	dev = $command({
+		name: "dev",
+		description: "Run the project in development mode",
 		handler: async ({ root }) => {
-			await this.utils.ensureConfig(root, { biomeJson: true });
-			await this.utils.ensureDependency(root, "@biomejs/biome");
-			await this.utils.exec("biome format --fix");
+			const [expo, react] = await Promise.all([this.pm.hasExpo(root), this.pm.hasReact(root)]);
+			await this.scaffolder.ensureConfig(root, { tsconfigJson: true });
+			if (expo) {
+				await this.utils.exec("expo start");
+				return;
+			}
+			const entry = await this.boot.getAppEntry(root);
+			this.log.debug("Entry file found", { entry });
+			await this.pm.ensureDependency(root, "vite", { exec: (cmd, opts) => this.utils.exec(cmd, opts) });
+			await this.viteDevServer.init({
+				root,
+				entry
+			});
+			await this.viteDevServer.start();
 		}
 	});
 };
@@ -1276,7 +2055,7 @@ const DEFAULT_IGNORE = [
 * ```
 */
 const changelogOptions = $atom({
-	name: "alepha.changelog",
+	name: "alepha.cli.changelog.options",
 	schema: t.object({ ignore: t.optional(t.array(t.string())) }),
 	default: { ignore: DEFAULT_IGNORE }
 });
@@ -1484,7 +2263,7 @@ var GenEnvCommand = class {
 					if (value.description) dotEnvFile += `# ${value.description.split("\n").join("\n# ")}\n`;
 					if (value.required && !value.default) dotEnvFile += `# (required)\n`;
 					if (value.enum) dotEnvFile += `# Possible values: ${value.enum.join(", ")}\n`;
-					dotEnvFile += `${key}=${value.default || ""}\n\n`;
+					dotEnvFile += `#${key}=${value.default || ""}\n\n`;
 				}
 				if (flags.out) await this.fs.writeFile(this.fs.join(root, flags.out), dotEnvFile);
 				else this.log.info(dotEnvFile);
@@ -1560,6 +2339,9 @@ var GenCommand = class {
 //#region ../../src/cli/commands/init.ts
 var InitCommand = class {
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
+	scaffolder = $inject(ProjectScaffolder);
+	fs = $inject(FileSystemProvider);
 	/**
 	* Ensure the project has the necessary Alepha configuration files.
 	* Add the correct dependencies to package.json and install them.
@@ -1567,45 +2349,84 @@ var InitCommand = class {
 	init = $command({
 		name: "init",
 		description: "Add missing Alepha configuration files to the project",
+		args: t.optional(t.text({
+			title: "path",
+			trim: true,
+			lowercase: true
+		})),
 		flags: t.object({
+			agent: t.optional(t.boolean({
+				aliases: ["a"],
+				description: "Add CLAUDE.md for Claude Code AI assistant"
+			})),
 			yarn: t.optional(t.boolean({ description: "Use Yarn package manager" })),
 			pnpm: t.optional(t.boolean({ description: "Use pnpm package manager" })),
 			npm: t.optional(t.boolean({ description: "Use npm package manager" })),
 			bun: t.optional(t.boolean({ description: "Use Bun package manager" })),
-			react: t.optional(t.boolean({ description: "Include Alepha React dependencies" })),
+			react: t.optional(t.boolean({
+				aliases: ["r"],
+				description: "Include Alepha React dependencies"
+			})),
 			ui: t.optional(t.boolean({ description: "Include Alepha UI dependencies" })),
-			test: t.optional(t.boolean({ description: "Include Vitest and create test directory" }))
+			test: t.optional(t.boolean({ description: "Include Vitest and create test directory" })),
+			force: t.optional(t.boolean({
+				aliases: ["f"],
+				description: "Override existing files"
+			}))
 		}),
-		handler: async ({ run, flags, root }) => {
-			if (flags.ui) flags.react = true;
-			const isExpo = await this.utils.hasExpo(root);
+		handler: async ({ run, flags, root, args }) => {
+			if (flags.react) flags.ui = true;
+			if (args) {
+				root = this.fs.join(root, args);
+				await this.fs.mkdir(root);
+			}
+			const isExpo = await this.pm.hasExpo(root);
+			const force = !!flags.force;
 			await run({
 				name: "ensuring configuration files",
 				handler: async () => {
-					await this.utils.ensureConfig(root, {
+					await this.scaffolder.ensureConfig(root, {
+						force,
 						tsconfigJson: true,
 						packageJson: flags,
 						biomeJson: true,
 						editorconfig: true,
-						indexHtml: !!flags.react && !isExpo
+						indexHtml: !!flags.react && !isExpo,
+						claudeMd: flags.agent ? {
+							react: !!flags.react,
+							ui: !!flags.ui
+						} : false
 					});
-					if (!flags.react) await this.utils.ensureSrcMain(root);
+					if (!flags.react) await this.scaffolder.ensureApiProject(root, { force });
 				}
 			});
-			const pm = await this.utils.getPackageManager(root, flags);
-			if (pm === "yarn") {
-				await this.utils.ensureYarn(root);
-				await run("yarn set version stable");
-			} else if (pm === "bun") await this.utils.ensureBun(root);
-			else if (pm === "pnpm") await this.utils.ensurePnpm(root);
-			else await this.utils.ensureNpm(root);
-			await run(`${pm} install`, { alias: `installing dependencies with ${pm}` });
-			if (!isExpo) await this.utils.ensureDependency(root, "vite", { run });
-			await this.utils.ensureDependency(root, "@biomejs/biome", { run });
+			const pmName = await this.pm.getPackageManager(root, flags);
+			if (pmName === "yarn") {
+				await this.pm.ensureYarn(root);
+				await run("yarn set version stable", { root });
+			} else if (pmName === "bun") await this.pm.ensureBun(root);
+			else if (pmName === "pnpm") await this.pm.ensurePnpm(root);
+			else await this.pm.ensureNpm(root);
+			await run(`${pmName} install`, {
+				alias: `installing dependencies with ${pmName}`,
+				root
+			});
+			if (!isExpo) await this.pm.ensureDependency(root, "vite", {
+				run,
+				exec: (cmd, opts) => this.utils.exec(cmd, opts)
+			});
+			await this.pm.ensureDependency(root, "@biomejs/biome", {
+				run,
+				exec: (cmd, opts) => this.utils.exec(cmd, opts)
+			});
 			if (flags.test) {
-				await this.utils.ensureTestDir(root);
-				await run(`${pm} ${pm === "yarn" ? "add" : "install"} -D vitest`, { alias: "setup testing with Vitest" });
+				await this.scaffolder.ensureTestDir(root);
+				await run(`${pmName} ${pmName === "yarn" ? "add" : "install"} -D vitest`, { alias: "setup testing with Vitest" });
 			}
+			await run(`${pmName} run lint`, {
+				alias: "running linter",
+				root
+			});
 		}
 	});
 };
@@ -1614,13 +2435,15 @@ var InitCommand = class {
 //#region ../../src/cli/commands/lint.ts
 var LintCommand = class {
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
+	scaffolder = $inject(ProjectScaffolder);
 	lint = $command({
 		name: "lint",
 		description: "Run linter across the codebase using Biome",
 		handler: async ({ root }) => {
-			await this.utils.ensureConfig(root, { biomeJson: true });
-			await this.utils.ensureDependency(root, "@biomejs/biome");
-			await this.utils.exec("biome check --formatter-enabled=false --fix");
+			await this.scaffolder.ensureConfig(root, { biomeJson: true });
+			await this.pm.ensureDependency(root, "@biomejs/biome", { exec: (cmd, opts) => this.utils.exec(cmd, opts) });
+			await this.utils.exec("biome check --fix");
 		}
 	});
 };
@@ -1657,6 +2480,8 @@ var RootCommand = class {
 //#region ../../src/cli/commands/test.ts
 var TestCommand = class {
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
+	scaffolder = $inject(ProjectScaffolder);
 	test = $command({
 		name: "test",
 		description: "Run tests using Vitest",
@@ -1669,8 +2494,8 @@ var TestCommand = class {
 			description: "Additional arguments to pass to Vitest. E.g., --coverage"
 		})) }),
 		handler: async ({ root, flags, env }) => {
-			await this.utils.ensureConfig(root, { tsconfigJson: true });
-			await this.utils.ensureDependency(root, "vitest");
+			await this.scaffolder.ensureConfig(root, { tsconfigJson: true });
+			await this.pm.ensureDependency(root, "vitest", { exec: (cmd, opts) => this.utils.exec(cmd, opts) });
 			const config = flags.config ? `--config=${flags.config}` : "";
 			await this.utils.exec(`vitest run ${config} ${env.VITEST_ARGS}`);
 		}
@@ -1681,6 +2506,7 @@ var TestCommand = class {
 //#region ../../src/cli/commands/typecheck.ts
 var TypecheckCommand = class {
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
 	log = $logger();
 	/**
 	* Run TypeScript type checking across the codebase with no emit.
@@ -1691,7 +2517,7 @@ var TypecheckCommand = class {
 		description: "Check TypeScript types across the codebase",
 		handler: async ({ root }) => {
 			this.log.info("Starting TypeScript type checking...");
-			await this.utils.ensureDependency(root, "typescript");
+			await this.pm.ensureDependency(root, "typescript", { exec: (cmd, opts) => this.utils.exec(cmd, opts) });
 			await this.utils.exec("tsc --noEmit");
 			this.log.info("TypeScript type checking completed successfully.");
 		}
@@ -1702,6 +2528,7 @@ var TypecheckCommand = class {
 //#region ../../src/cli/commands/verify.ts
 var VerifyCommand = class {
 	utils = $inject(AlephaCliUtils);
+	pm = $inject(PackageManagerUtils);
 	/**
 	* Run a series of verification commands to ensure code quality and correctness.
 	*
@@ -1723,9 +2550,9 @@ var VerifyCommand = class {
 			await run("alepha format");
 			await run("alepha lint");
 			await run("alepha typecheck");
-			if ((await this.utils.readPackageJson(root)).devDependencies?.vitest) await run("alepha test");
+			if ((await this.pm.readPackageJson(root)).devDependencies?.vitest) await run("alepha test");
 			if (await this.utils.exists(root, "migrations")) await run("alepha db check-migrations");
-			if (!await this.utils.hasExpo(root)) await run("alepha build");
+			if (!await this.pm.hasExpo(root)) await run("alepha build");
 			await run("alepha clean");
 		}
 	});
@@ -1769,7 +2596,6 @@ const AlephaCli = $module({
 		DbCommand,
 		DeployCommand,
 		DevCommand,
-		FormatCommand,
 		InitCommand,
 		LintCommand,
 		RootCommand,
@@ -1777,6 +2603,7 @@ const AlephaCli = $module({
 		TypecheckCommand,
 		VerifyCommand,
 		GenCommand,
+		AppEntryProvider,
 		GitProvider
 	]
 });
@@ -1791,11 +2618,11 @@ var AlephaPackageBuilderCli = class {
 		root: true,
 		handler: async ({ run, root }) => {
 			const modules = [];
-			const pkg = await readFile("package.json", "utf-8");
-			const pkgData = JSON.parse(pkg);
+			const pkgBuffer = await this.fs.readFile("package.json");
+			const pkgData = JSON.parse(pkgBuffer.toString("utf-8"));
 			const packageName = pkgData.name;
 			await run("analyze modules", async () => {
-				modules.push(...await analyzeModules(join(root, this.src), packageName));
+				modules.push(...await analyzeModules(this.fs.join(root, this.src), packageName));
 			});
 			pkgData.exports = {};
 			for (const item of modules) {
@@ -1807,6 +2634,7 @@ var AlephaPackageBuilderCli = class {
 				if (item.native) pkgData.exports[path]["react-native"] = `./src/${item.name}/index.native.ts`;
 				else if (item.browser) pkgData.exports[path]["react-native"] = `./src/${item.name}/index.browser.ts`;
 				if (item.browser) pkgData.exports[path].browser = `./src/${item.name}/index.browser.ts`;
+				if (item.bun) pkgData.exports[path].bun = `./src/${item.name}/index.bun.ts`;
 				pkgData.exports[path].import = `./src/${item.name}/index.ts`;
 				pkgData.exports[path].default = `./src/${item.name}/index.ts`;
 			}
@@ -1819,48 +2647,58 @@ var AlephaPackageBuilderCli = class {
 				pkgData.exports["./json/styles"] = "./src/json/styles.css";
 			}
 			await this.fs.writeFile("package.json", JSON.stringify(pkgData, null, 2));
-			const tmpDir = join(root, "node_modules/.alepha");
+			const tmpDir = this.fs.join(root, "node_modules/.alepha");
 			await this.fs.mkdir(tmpDir, { recursive: true }).catch(() => {});
-			await this.fs.writeFile(join(tmpDir, "module-dependencies.json"), JSON.stringify(modules, null, 2));
-			const tsconfig = await readFile(join(root, "../../tsconfig.json"), "utf-8");
-			const external = Object.keys(JSON.parse(tsconfig).compilerOptions.paths);
+			await this.fs.writeFile(this.fs.join(tmpDir, "module-dependencies.json"), JSON.stringify(modules, null, 2));
+			const tsconfigBuffer = await this.fs.readFile(this.fs.join(root, "../../tsconfig.json"));
+			const external = Object.keys(JSON.parse(tsconfigBuffer.toString("utf-8")).compilerOptions.paths);
 			external.push("bun");
 			external.push("bun:sqlite");
 			await run.rm(this.dist);
 			const build = async (item) => {
 				const entries = [];
-				const src = join(root, this.src, item.name);
-				const dest = join(root, this.dist, item.name);
+				const src = this.fs.join(root, this.src, item.name);
+				const dest = this.fs.join(root, this.dist, item.name);
 				entries.push({
-					entry: join(src, "index.ts"),
+					entry: this.fs.join(src, "index.ts"),
 					outDir: dest,
 					format: ["esm"],
 					sourcemap: true,
 					fixedExtension: false,
 					platform: "node",
+					inlineOnly: false,
 					external,
-					dts: {
-						sourcemap: true,
-						resolve: false
-					}
+					dts: { sourcemap: true }
 				});
 				if (item.native) entries.push({
-					entry: join(src, "index.native.ts"),
+					entry: this.fs.join(src, "index.native.ts"),
 					outDir: dest,
 					platform: "neutral",
 					sourcemap: true,
 					dts: false,
+					inlineOnly: false,
 					external
 				});
 				if (item.browser) entries.push({
-					entry: join(src, "index.browser.ts"),
+					entry: this.fs.join(src, "index.browser.ts"),
 					outDir: dest,
 					platform: "browser",
 					sourcemap: true,
 					dts: false,
+					inlineOnly: false,
+					external
+				});
+				if (item.bun) entries.push({
+					entry: this.fs.join(src, "index.bun.ts"),
+					outDir: dest,
+					platform: "node",
+					sourcemap: true,
+					fixedExtension: false,
+					dts: false,
+					inlineOnly: false,
 					external
 				});
-				const config = join(tmpDir, `tsdown-${item.name.replace("/", "-")}.config.js`);
+				const config = this.fs.join(tmpDir, `tsdown-${item.name.replace("/", "-")}.config.js`);
 				await this.fs.writeFile(config, `export default ${JSON.stringify(entries, null, 2)};`);
 				await run(`npx tsdown -c=${config}`);
 			};
@@ -1881,6 +2719,7 @@ var AlephaPackageBuilderCli = class {
 		}
 	});
 };
+var AlephaPackageBuilderCli_default = AlephaPackageBuilderCli;
 async function getAllFiles(dir) {
 	const files = [];
 	async function scan(currentDir) {
@@ -1934,7 +2773,7 @@ function detectCircularDependencies(modules) {
 	}
 	for (const module of modules) {
 		const cycle = hasCycle(module.name);
-		if (cycle) throw new Error(`Circular dependency detected: ${cycle.join(" -> ")}`);
+		if (cycle) throw new AlephaError(`Circular dependency detected: ${cycle.join(" -> ")}`);
 	}
 }
 async function analyzeModules(srcDir, packageName) {
@@ -1948,6 +2787,7 @@ async function analyzeModules(srcDir, packageName) {
 				const dependencies = /* @__PURE__ */ new Set();
 				const hasBrowser = await fileExists(join(modulePath, "index.browser.ts"));
 				const hasNative = await fileExists(join(modulePath, "index.native.ts"));
+				const hasBun = await fileExists(join(modulePath, "index.bun.ts"));
 				const hasNode = await fileExists(join(modulePath, "index.node.ts"));
 				const files = await getAllFiles(modulePath);
 				for (const file of files) {
@@ -1964,6 +2804,7 @@ async function analyzeModules(srcDir, packageName) {
 				};
 				if (hasNative) module.native = true;
 				if (hasBrowser) module.browser = true;
+				if (hasBun) module.bun = true;
 				if (hasNode) module.node = true;
 				modules.push(module);
 			} else await scanDirectory(modulePath, moduleName);
@@ -1982,6 +2823,7 @@ const defineConfig = (runConfig) => {
 		if (config.services) for (const it of config.services) alepha.with(it);
 		if (config.env) for (const [key, value] of Object.entries(config.env)) process.env[key] = String(value);
 		if (config.build) alepha.set(buildOptions, config.build);
+		if (config.entry) alepha.set(appEntryOptions, config.entry);
 		return { ...config.commands };
 	};
 };
@@ -1991,5 +2833,5 @@ const defineConfig = (runConfig) => {
 const defineAlephaConfig = defineConfig;
 
 //#endregion
-export { AlephaCli, AlephaCliUtils, AlephaPackageBuilderCli, BuildCommand, ChangelogCommand, CleanCommand, DEFAULT_IGNORE, DbCommand, DeployCommand, DevCommand, FormatCommand, GitMessageParser, GitProvider, InitCommand, LintCommand, OpenApiCommand, RootCommand, TestCommand, TypecheckCommand, VerifyCommand, analyzeModules, changelogOptions, defineAlephaConfig, defineConfig, version };
+export { AlephaCli, AlephaCliUtils, AlephaPackageBuilderCli_default as AlephaPackageBuilderCli, AppEntryProvider, BuildCommand, ChangelogCommand, CleanCommand, DEFAULT_IGNORE, DbCommand, DeployCommand, DevCommand, GitMessageParser, GitProvider, InitCommand, LintCommand, OpenApiCommand, RootCommand, TestCommand, TypecheckCommand, VerifyCommand, analyzeModules, changelogOptions, defineAlephaConfig, defineConfig, version };
 //# sourceMappingURL=index.js.map