alepha 0.15.2 → 0.15.4

package/dist/cli/index.js

@@ -1370,8 +1370,13 @@ var NodeFileSystemProvider = class {
 	* await fs.mkdir("/tmp/mydir", { mode: 0o755 });
 	* ```
 	*/
-	async mkdir(path, options) {
-		await mkdir(path, options);
+	async mkdir(path, options = {}) {
+		const p = mkdir(path, {
+			recursive: options.recursive ?? true,
+			mode: options.mode
+		});
+		if (options.force === false) await p;
+		else await p.catch(() => {});
 	}
 	/**
 	* Lists files in a directory.
@@ -1912,13 +1917,24 @@ $atom$1[KIND] = "atom";
 * Build options atom for CLI build command.
 *
 * Defines the available build configuration options with their defaults.
-* Options can be overridden via vite.config.ts or CLI flags.
+* Options can be overridden via alepha.config.ts or CLI flags.
 */
 const buildOptions = $atom$1({
 	name: "alepha.cli.build.options",
 	description: "Build configuration options",
 	schema: t.object({
 		stats: t.optional(t.boolean({ default: false })),
+		target: t.optional(t.enum([
+			"bare",
+			"docker",
+			"vercel",
+			"cloudflare"
+		])),
+		runtime: t.optional(t.enum([
+			"node",
+			"bun",
+			"workerd"
+		])),
 		vercel: t.optional(t.object({
 			projectName: t.optional(t.string()),
 			orgId: t.optional(t.string()),
@@ -1930,8 +1946,13 @@ const buildOptions = $atom$1({
 		})),
 		cloudflare: t.optional(t.object({ config: t.optional(t.json()) })),
 		docker: t.optional(t.object({
-			image: t.optional(t.string({ default: "node:24-alpine" })),
-			command: t.optional(t.string({ default: "node" }))
+			from: t.optional(t.string()),
+			command: t.optional(t.string()),
+			image: t.optional(t.object({
+				tag: t.string(),
+				args: t.optional(t.string()),
+				oci: t.optional(t.boolean())
+			}))
 		})),
 		sitemap: t.optional(t.object({ hostname: t.string() }))
 	}),
@@ -2205,6 +2226,18 @@ ${models.map((it) => `export const ${it} = models["${it}"];`).join("\n")}
 	isInstalledAsync(cmd) {
 		return this.shell.isInstalled(cmd);
 	}
+	/**
+	* Get the current git revision (commit SHA).
+	*
+	* @returns The short commit SHA or "unknown" if not in a git repo
+	*/
+	async getGitRevision() {
+		try {
+			return (await this.shell.run("git rev-parse --short HEAD", { capture: true })).trim();
+		} catch {
+			return "unknown";
+		}
+	}
 };
 
 //#endregion
@@ -2220,16 +2253,19 @@ var devDependencies = {
 	"@types/react": "^19.2.10",
 	"@types/react-dom": "^19.2.3",
 	"@types/ws": "^8.18.1",
+	"@vitejs/plugin-react": "^5.1.2",
 	"cron-schedule": "^6.0.0",
 	"jose": "^6.1.3",
 	"jsdom": "^27.4.0",
+	"nodemailer": "^7.0.13",
 	"openid-client": "^6.8.1",
 	"prom-client": "^15.1.3",
 	"react": "^19.2.4",
 	"react-dom": "^19.2.4",
 	"swagger-ui-dist": "^5.31.0",
 	"tsdown": "^0.20.1",
-	"vitest": "^4.0.18"
+	"vitest": "^4.0.18",
+	"worker-mailer": "^1.2.1"
 };
 
 //#endregion
@@ -2477,6 +2513,7 @@ var PackageManagerUtils = class {
 		if (modes.react) {
 			dependencies.react = alephaDeps.react;
 			dependencies["react-dom"] = alephaDeps["react-dom"];
+			devDependencies$1["@vitejs/plugin-react"] = alephaDeps["@vitejs/plugin-react"];
 			devDependencies$1["@types/react"] = alephaDeps["@types/react"];
 		}
 		return {
@@ -2783,7 +2820,26 @@ alepha build     # Build the project
 ## Source Code Access
 
 Full framework source available at \`node_modules/alepha/src/\`.
-Read primitives directly when you need implementation details.
+
+**IMPORTANT:** When answering questions about Alepha primitives, APIs, or internals:
+1. ALWAYS read the local source code first at \`node_modules/alepha/src/\` or \`node_modules/@alepha/ui/src/\` for UI-related questions
+2. Use \`Glob\` to find relevant files: \`node_modules/alepha/src/**/primitives/$<name>.ts\`
+3. Read the implementation AND the \`.spec.ts\` test files for usage examples
+4. Use external documentation as a fallback if source code is insufficient
+`.trim();
+};
+
+//#endregion
+//#region ../../src/cli/templates/apiAppSecurityTs.ts
+const apiAppSecurityTs = () => {
+	return `
+import { $realm } from "alepha/api/users";
+
+export class AppSecurity {
+  users = $realm({
+    // configure your realm here
+  });
+}
 `.trim();
 };
 
@@ -2811,14 +2867,21 @@ export class HelloController {
 //#endregion
 //#region ../../src/cli/templates/apiIndexTs.ts
 const apiIndexTs = (options = {}) => {
-	const { appName = "app" } = options;
+	const { appName = "app", auth = false } = options;
+	const imports = ["import { $module } from \"alepha\";"];
+	const services = [];
+	if (auth) {
+		imports.push("import { AppSecurity } from \"./AppSecurity.ts\";");
+		services.push("AppSecurity");
+	}
+	imports.push("import { HelloController } from \"./controllers/HelloController.ts\";");
+	services.push("HelloController");
 	return `
-import { $module } from "alepha";
-import { HelloController } from "./controllers/HelloController.ts";
+${imports.join("\n")}
 
 export const ApiModule = $module({
   name: "${appName}.api",
-  services: [HelloController],
+  services: [${services.join(", ")}],
 });
 `.trim();
 };
@@ -3006,6 +3069,8 @@ const webAppRouterTs = (options) => {
 	const imports = [];
 	const classMembers = [];
 	if (options.ui) imports.push("import { $ui } from \"@alepha/ui\";");
+	if (options.auth) imports.push("import { $uiAuth } from \"@alepha/ui/auth\";");
+	if (options.admin) imports.push("import { $uiAdmin } from \"@alepha/ui/admin\";");
 	imports.push("import { $page } from \"alepha/react/router\";");
 	if (options.api) {
 		imports.push("import { $client } from \"alepha/server/links\";");
@@ -3014,6 +3079,8 @@ const webAppRouterTs = (options) => {
 	}
 	if (options.ui) {
 		classMembers.push("  ui = $ui();");
+		if (options.auth) classMembers.push("  uiAuth = $uiAuth();");
+		if (options.admin) classMembers.push("  uiAdmin = $uiAdmin();");
 		classMembers.push(`  layout = $page({
     parent: this.ui.root,
     children: () => [this.home],
@@ -3037,7 +3104,12 @@ ${classMembers.join("\n\n")}
 
 //#endregion
 //#region ../../src/cli/templates/webHelloComponentTsx.ts
-const webHelloComponentTsx = () => `import { useState } from "react";
+const webHelloComponentTsx = (options = {}) => {
+	const imports = [];
+	if (options.auth) imports.push("import { UserButton } from \"@alepha/ui/auth\";");
+	imports.push("import { useState } from \"react\";");
+	const userButton = options.auth ? "\n      <UserButton />" : "";
+	return `${imports.join("\n")}
 
 interface Props {
   message?: string;
@@ -3048,14 +3120,15 @@ const Hello = (props: Props) => {
   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>
+      <input value={message} onChange={(e) => setMessage(e.target.value)} />
+      <p>Edit this component in src/web/components/Hello.tsx</p>${userButton}
     </div>
   );
 };
 
 export default Hello;
-`.trim();
+`;
+};
 
 //#endregion
 //#region ../../src/cli/templates/webIndexTs.ts
@@ -3097,7 +3170,7 @@ var ProjectScaffolder = class {
 	* - Falls back to "app" if empty
 	*/
 	getAppName(root) {
-		return basename(root).toLowerCase().replace(/[\s\-_]/g, "") || "app";
+		return basename(root).toLowerCase().replace(/[\s\-_.\d]/g, "") || "app";
 	}
 	/**
 	* Ensure all configuration files exist.
@@ -3175,8 +3248,12 @@ var ProjectScaffolder = class {
 	async ensureApiProject(root, opts = {}) {
 		const appName = this.getAppName(root);
 		await this.fs.mkdir(this.fs.join(root, "src/api/controllers"), { recursive: true });
-		await this.ensureFile(root, "src/api/index.ts", apiIndexTs({ appName }), opts.force);
+		await this.ensureFile(root, "src/api/index.ts", apiIndexTs({
+			appName,
+			auth: opts.auth
+		}), opts.force);
 		await this.ensureFile(root, "src/api/controllers/HelloController.ts", apiHelloControllerTs(), opts.force);
+		if (opts.auth) await this.ensureFile(root, "src/api/AppSecurity.ts", apiAppSecurityTs(), opts.force);
 	}
 	/**
 	* Ensure web/React project structure exists.
@@ -3193,9 +3270,11 @@ var ProjectScaffolder = class {
 		await this.ensureFile(root, "src/web/index.ts", webIndexTs({ appName }), opts.force);
 		await this.ensureFile(root, "src/web/AppRouter.ts", webAppRouterTs({
 			api: opts.api,
-			ui: opts.ui
+			ui: opts.ui,
+			auth: opts.auth,
+			admin: opts.admin
 		}), opts.force);
-		await this.ensureFile(root, "src/web/components/Hello.tsx", webHelloComponentTsx(), opts.force);
+		await this.ensureFile(root, "src/web/components/Hello.tsx", webHelloComponentTsx({ auth: opts.auth }), opts.force);
 		await this.ensureFile(root, "src/main.browser.ts", mainBrowserTs(), opts.force);
 	}
 	/**
@@ -3243,17 +3322,55 @@ var BuildCommand = class {
 	boot = $inject(AppEntryProvider);
 	viteBuildProvider = $inject(ViteBuildProvider);
 	options = $use(buildOptions);
+	/**
+	* Resolve the effective runtime based on target and explicit runtime flag.
+	*
+	* Some targets force a specific runtime:
+	* - `cloudflare` always uses `workerd`
+	* - `vercel` always uses `node`
+	* - `docker` and bare deployments respect the runtime flag
+	*
+	* @throws {AlephaError} If an incompatible runtime is specified for a target
+	*/
+	resolveRuntime(target, runtime) {
+		if (target === "cloudflare") {
+			if (runtime && runtime !== "workerd") throw new AlephaError(`Target 'cloudflare' requires 'workerd' runtime, got '${runtime}'`);
+			return "workerd";
+		}
+		if (target === "vercel") {
+			if (runtime && runtime !== "node") throw new AlephaError(`Target 'vercel' requires 'node' runtime, got '${runtime}'`);
+			return "node";
+		}
+		return runtime ?? "node";
+	}
 	build = $command({
 		name: "build",
 		mode: "production",
 		description: "Build the project for production",
 		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" })),
-			bun: t.optional(t.boolean({ description: "Prioritize .bun.ts entry files for Bun runtime" }))
+			target: t.optional(t.enum([
+				"bare",
+				"docker",
+				"vercel",
+				"cloudflare"
+			], {
+				aliases: ["t"],
+				description: "Deployment target"
+			})),
+			runtime: t.optional(t.enum([
+				"node",
+				"bun",
+				"workerd"
+			], {
+				aliases: ["r"],
+				description: "JavaScript runtime"
+			})),
+			image: t.optional(t.union([t.boolean(), t.text()], {
+				aliases: ["i"],
+				description: "Build Docker image. Use -i for latest, -i=<version> for specific version"
+			})),
+			sitemap: t.optional(t.text({ description: "Generate sitemap.xml with base URL" }))
 		}),
 		handler: async ({ flags, run, root }) => {
 			process.env.NODE_ENV = "production";
@@ -3266,6 +3383,13 @@ var BuildCommand = class {
 			await run.rm("dist", { alias: "clean dist" });
 			const options = this.options;
 			await this.utils.loadEnv(root, [".env", ".env.production"]);
+			const target = flags.target ?? options.target;
+			const runtime = this.resolveRuntime(target, flags.runtime ?? options.runtime);
+			if (flags.image && target !== "docker") throw new AlephaError(`Flag '--image' requires '--target=docker', got '${target ?? "bare"}'`);
+			this.log.trace("Build configuration", {
+				target,
+				runtime
+			});
 			const stats = flags.stats ?? options.stats ?? false;
 			let template = "";
 			let hasClient = false;
@@ -3303,8 +3427,8 @@ var BuildCommand = class {
 					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");
+					if (runtime === "bun") conditions.push("bun");
+					else if (runtime === "workerd") conditions.push("workerd");
 					await buildServer({
 						silent: true,
 						entry: entry.server,
@@ -3339,7 +3463,7 @@ var BuildCommand = class {
 					run
 				});
 			}
-			if (flags.vercel || options.vercel) await run({
+			if (target === "vercel") await run({
 				name: "add Vercel config",
 				handler: () => generateVercel({
 					distDir,
@@ -3347,20 +3471,57 @@ var BuildCommand = class {
 					config: options.vercel
 				})
 			});
-			if (flags.cloudflare || options.cloudflare) await run({
+			if (target === "cloudflare") await run({
 				name: "add Cloudflare config",
 				handler: () => generateCloudflare({
 					distDir,
-					config: options.cloudflare?.config
-				})
-			});
-			if (flags.docker || options.docker) await run({
-				name: "add Docker config",
-				handler: () => generateDocker({
-					distDir,
-					...options.docker
+					config: options.cloudflare?.config,
+					alepha
 				})
 			});
+			if (target === "docker") {
+				const dockerFrom = options.docker?.from ?? (runtime === "bun" ? "oven/bun:alpine" : "node:24-alpine");
+				const dockerCommand = options.docker?.command ?? (runtime === "bun" ? "bun" : "node");
+				await run({
+					name: "add Docker config",
+					handler: () => generateDocker({
+						distDir,
+						image: dockerFrom,
+						command: dockerCommand
+					})
+				});
+				if (flags.image) {
+					const imageConfig = options.docker?.image;
+					const flagValue = typeof flags.image === "string" ? flags.image : null;
+					let imageTag;
+					let version;
+					if (!flagValue) {
+						if (!imageConfig?.tag) throw new AlephaError("Flag '--image' requires 'build.docker.image.tag' in config");
+						version = "latest";
+						imageTag = `${imageConfig.tag}:${version}`;
+					} else if (flagValue.startsWith(":")) {
+						if (!imageConfig?.tag) throw new AlephaError("Flag '--image=:version' requires 'build.docker.image.tag' in config");
+						version = flagValue.slice(1);
+						imageTag = `${imageConfig.tag}:${version}`;
+					} else if (flagValue.includes(":")) {
+						imageTag = flagValue;
+						version = flagValue.split(":")[1];
+					} else {
+						imageTag = `${flagValue}:latest`;
+						version = "latest";
+					}
+					const args = [];
+					if (imageConfig?.args) args.push(imageConfig.args);
+					if (imageConfig?.oci) {
+						const revision = await this.utils.getGitRevision();
+						const created = (/* @__PURE__ */ new Date()).toISOString();
+						args.push(`--label "org.opencontainers.image.revision=${revision}"`);
+						args.push(`--label "org.opencontainers.image.created=${created}"`);
+						args.push(`--label "org.opencontainers.image.version=${version}"`);
+					}
+					await run(`docker build ${args.length > 0 ? `${args.join(" ")} ` : ""}-t ${imageTag} ${distDir}`, { alias: `docker build ${imageTag}` });
+				}
+			}
 		}
 	});
 };
@@ -3629,9 +3790,9 @@ var DbCommand = class {
 			const accountId = process.env.CLOUDFLARE_ACCOUNT_ID;
 			if (!accountId) throw new AlephaError("CLOUDFLARE_ACCOUNT_ID environment variable is not set. https://orm.drizzle.team/docs/guides/d1-http-with-drizzle-kit");
 			const url = options.providerUrl;
-			if (!url.startsWith("cloudflare-d1://")) throw new AlephaError("D1 provider URL must start with 'cloudflare-d1://'.");
-			const [, databaseId] = url.replace("cloudflare-d1://", "").replace("cloudflare-d1:", "").split(":");
-			if (!databaseId) throw new AlephaError("Database ID is missing in the D1 provider URL. Cloudflare D1 URL format: cloudflare-d1://<database_name>:<database_id>");
+			if (!url.startsWith("d1://")) throw new AlephaError("D1 provider URL must start with 'd1://'.");
+			const [, databaseId] = url.replace("d1://", "").replace("d1:", "").split(":");
+			if (!databaseId) throw new AlephaError("Database ID is missing in the D1 provider URL. Cloudflare D1 URL format: d1://<database_name>:<database_id>");
 			config.dbCredentials = {
 				accountId,
 				databaseId,
@@ -3763,7 +3924,6 @@ var DeployCommand = class {
 var ViteDevServerProvider = class {
 	log = $logger();
 	fs = $inject(FileSystemProvider);
-	templateProvider = $inject(ViteUtils);
 	server;
 	options;
 	alepha = null;
@@ -3905,12 +4065,12 @@ var ViteDevServerProvider = class {
 		}
 	}
 	/**
-	* Setup Alepha instance with Vite middleware and template.
+	* Setup Alepha instance with Vite middleware.
 	*/
 	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);
+		const devHead = await this.generateDevHead();
+		this.alepha.store.set("alepha.react.ssr.manifest", { devHead });
 		this.alepha.events.on("server:onRequest", {
 			priority: "first",
 			callback: async ({ request }) => {
@@ -3924,6 +4084,18 @@ var ViteDevServerProvider = class {
 		});
 	}
 	/**
+	* Generate dev head content by transforming a minimal HTML through Vite.
+	* This lets Vite and all plugins inject their scripts (HMR client, React Fast Refresh, etc.).
+	*/
+	async generateDevHead() {
+		const { browser, style } = this.options.entry;
+		const scripts = [];
+		if (style) scripts.push(`<link rel="stylesheet" href="/${style}">`);
+		if (browser) scripts.push(`<script type="module" src="/${browser}"><\/script>`);
+		const minimalHtml = `<!DOCTYPE html><html><head>${scripts.join("\n")}</head><body></body></html>`;
+		return (await this.server.transformIndexHtml("/", minimalHtml)).match(/<head>([\s\S]*?)<\/head>/i)?.[1]?.trim() ?? "";
+	}
+	/**
 	* Check if request is for an HTML page (not an asset).
 	*/
 	isPageRequest(req) {
@@ -4350,10 +4522,7 @@ var InitCommand = class {
 			lowercase: true
 		})),
 		flags: t.object({
-			agent: t.optional(t.boolean({
-				aliases: ["a"],
-				description: "Add AI agent instructions (CLAUDE.md if claude CLI installed, else AGENTS.md)"
-			})),
+			ai: t.optional(t.boolean({ description: "Add AI agent instructions (CLAUDE.md if claude CLI installed, else AGENTS.md)" })),
 			pm: t.optional(t.enum([
 				"yarn",
 				"npm",
@@ -4366,6 +4535,8 @@ var InitCommand = class {
 				description: "Include React dependencies and web module (src/web/)"
 			})),
 			ui: t.optional(t.boolean({ description: "Include @alepha/ui (components, auth portal, admin portal)" })),
+			auth: t.optional(t.boolean({ description: "Include authentication (AppSecurity, $uiAuth). Implies --api --ui --react" })),
+			admin: t.optional(t.boolean({ description: "Include admin portal ($uiAdmin). Implies --auth" })),
 			test: t.optional(t.boolean({ description: "Include Vitest and create test directory" })),
 			force: t.optional(t.boolean({
 				aliases: ["f"],
@@ -4375,12 +4546,17 @@ var InitCommand = class {
 		handler: async ({ run, flags, root, args }) => {
 			if (args) {
 				root = this.fs.join(root, args);
-				await this.fs.mkdir(root);
+				await this.fs.mkdir(root, { force: true });
+			}
+			if (flags.admin) flags.auth = true;
+			if (flags.auth) {
+				flags.api = true;
+				flags.ui = true;
 			}
 			if (flags.ui) flags.react = true;
 			const workspace = await this.pm.getWorkspaceContext(root);
 			let agentType = false;
-			if (flags.agent) agentType = await this.utils.isInstalledAsync("claude") ? "claude" : "agents";
+			if (flags.ai) agentType = await this.utils.isInstalledAsync("claude") ? "claude" : "agents";
 			const isExpo = await this.pm.hasExpo(root);
 			const force = !!flags.force;
 			await run({
@@ -4406,10 +4582,15 @@ var InitCommand = class {
 						react: !!flags.react && !isExpo,
 						force
 					});
-					if (flags.api) await this.scaffolder.ensureApiProject(root, { force });
+					if (flags.api) await this.scaffolder.ensureApiProject(root, {
+						auth: !!flags.auth,
+						force
+					});
 					if (flags.react && !isExpo) await this.scaffolder.ensureWebProject(root, {
 						api: !!flags.api,
 						ui: !!flags.ui,
+						auth: !!flags.auth,
+						admin: !!flags.admin,
 						force
 					});
 				}
@@ -4648,6 +4829,7 @@ var AlephaPackageBuilderCli = class {
 				pkgData.exports[path].types = `./src/${item.name}/index.ts`;
 				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.workerd) pkgData.exports[path].workerd = `./src/${item.name}/index.workerd.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`;
@@ -4804,6 +4986,7 @@ async function analyzeModules(srcDir, packageName) {
 				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 hasEdge = await fileExists(join(modulePath, "index.workerd.ts"));
 				const files = await getAllFiles(modulePath);
 				for (const file of files) {
 					const deps = extractAlephaDependencies(await readFile(file, "utf-8"), packageName, moduleName);
@@ -4818,6 +5001,7 @@ async function analyzeModules(srcDir, packageName) {
 					dependencies: Array.from(dependencies)
 				};
 				if (hasNative) module.native = true;
+				if (hasEdge) module.workerd = true;
 				if (hasBrowser) module.browser = true;
 				if (hasBun) module.bun = true;
 				if (hasNode) module.node = true;