alepha 0.15.0 → 0.15.1

package/src/cli/assets/apiHelloControllerTs.ts

@@ -1,4 +1,5 @@
-export const apiHelloControllerTs = () => `
+export const apiHelloControllerTs = () =>
+  `
 import { t } from "alepha";
 import { $action } from "alepha/server";
 

package/src/cli/assets/biomeJson.ts

@@ -1,4 +1,5 @@
-export const biomeJson = `
+export const biomeJson = () =>
+  `
 {
   "$schema": "https://biomejs.dev/schemas/latest/schema.json",
   "vcs": {

package/src/cli/assets/claudeMd.ts

@@ -69,8 +69,8 @@ ${projectName}/
 │   │   ├── AppRouter.ts  # Routes with $page
 │   │   └── index.ts      # Web module definition with $module
 │   ├── main.server.ts    # Server entry
-│   └── main.browser.ts   # Browser entry (React only)
-├── index.html            # (React only)
+│   ├── main.browser.ts   # Browser entry (React only)
+│   └── main.css          # CSS entry (React only)
 ├── package.json
 └── tsconfig.json
 \`\`\`
@@ -117,6 +117,7 @@ This is an **Alepha** project - a convention-driven TypeScript framework for typ
 - 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}
@@ -246,9 +247,13 @@ ${reactSection}
 | \`$cache\` | \`alepha/cache\` | Cached computations |
 | \`$bucket\` | \`alepha/bucket\` | File storage |
 | \`$issuer\` | \`alepha/security\` | JWT tokens |
-| \`$command\` | \`alepha/command\` | CLI commands |${react ? `
+| \`$command\` | \`alepha/command\` | CLI commands |${
+    react
+      ? `
 | \`$page\` | \`@alepha/react/router\` | React pages with SSR |
-| \`$atom\` | \`alepha\` | Global state |` : ""}
+| \`$atom\` | \`alepha\` | Global state |`
+      : ""
+  }
 
 ## Testing
 

package/src/cli/assets/dummySpecTs.ts

@@ -1,4 +1,5 @@
-export const dummySpecTs = () => `
+export const dummySpecTs = () =>
+  `
 import { test, expect } from "vitest";
 
 test("dummy test", () => {

package/src/cli/assets/editorconfig.ts

@@ -1,4 +1,5 @@
-export const editorconfig = `
+export const editorconfig = () =>
+  `
 # https://editorconfig.org
 
 root = true

package/src/cli/assets/mainBrowserTs.ts

@@ -1,4 +1,5 @@
-export const mainBrowserTs = () => `
+export const mainBrowserTs = () =>
+  `
 import { Alepha, run } from "alepha";
 import { WebModule } from "./web/index.ts";
 

package/src/cli/assets/mainCss.ts

@@ -0,0 +1,24 @@
+export 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();

package/src/cli/assets/tsconfigJson.ts

@@ -1,4 +1,5 @@
-export const tsconfigJson = `
+export const tsconfigJson = () =>
+  `
 {
   "extends": "alepha/tsconfig.base"
 }

package/src/cli/assets/webAppRouterTs.ts

@@ -1,4 +1,5 @@
-export const webAppRouterTs = () => `
+export const webAppRouterTs = () =>
+  `
 import { $page } from "@alepha/react/router";
 import { $client } from "alepha/server/links";
 import type { HelloController } from "../api/controllers/HelloController.ts";

package/src/cli/assets/webHelloComponentTsx.ts

@@ -1,12 +1,16 @@
-export const webHelloComponentTsx = () => `
+export const webHelloComponentTsx = () =>
+  `import { useState } from "react";
+
 interface Props {
   message: string;
 }
 
 const Hello = (props: Props) => {
+  const [message, setMessage] = useState(props.message);
   return (
     <div>
-      <h1>{props.message}</h1>
+      <h1>{message}</h1>
+      <input value={message} onChange={e => setMessage(e.target.value)} />
       <p>Edit this component in src/web/components/Hello.tsx</p>
     </div>
   );

package/src/cli/atoms/appEntryOptions.ts

@@ -0,0 +1,13 @@
+import { $atom, type Static, t } from "alepha";
+
+export 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: {},
+});
+
+export type AppEntryOptions = Static<typeof appEntryOptions.schema>;

package/src/cli/atoms/buildOptions.ts

@@ -8,7 +8,7 @@ import { $atom } from "../../core/primitives/$atom.ts";
  * Options can be overridden via vite.config.ts or CLI flags.
  */
 export const buildOptions = $atom({
-  name: "alepha.build.options",
+  name: "alepha.cli.build.options",
   description: "Build configuration options",
   schema: t.object({
     /**

package/src/cli/atoms/changelogOptions.ts

@@ -29,7 +29,7 @@ export const DEFAULT_IGNORE = [
  * ```
  */
 export const changelogOptions = $atom({
-  name: "alepha.changelog",
+  name: "alepha.cli.changelog.options",
   schema: t.object({
     /**
      * Scopes to ignore (e.g., "project", "release", "chore").

package/src/cli/commands/build.ts

@@ -1,9 +1,8 @@
-import { $inject, $use, t } from "alepha";
+import { $inject, $use, type Alepha, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import {
-  boot,
   buildClient,
   buildServer,
   copyAssets,
@@ -14,6 +13,8 @@ import {
   prerenderPages,
 } from "alepha/vite";
 import { buildOptions } from "../atoms/buildOptions.ts";
+import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
+import { ViteBuildProvider } from "../providers/ViteBuildProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
@@ -24,15 +25,14 @@ export class BuildCommand {
   protected readonly utils = $inject(AlephaCliUtils);
   protected readonly pm = $inject(PackageManagerUtils);
   protected readonly scaffolder = $inject(ProjectScaffolder);
+  protected readonly boot = $inject(AppEntryProvider);
+  protected readonly viteBuildProvider = $inject(ViteBuildProvider);
   protected readonly options = $use(buildOptions);
 
   public readonly 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({
@@ -65,9 +65,7 @@ export class BuildCommand {
         }),
       ),
     }),
-    handler: async ({ flags, args, run, root }) => {
-      // Tell viteAlephaBuild plugin to skip - CLI handles all tasks
-      process.env.ALEPHA_BUILD_MODE = "cli";
+    handler: async ({ flags, run, root }) => {
       process.env.NODE_ENV = "production";
 
       if (await this.pm.hasExpo(root)) {
@@ -79,11 +77,11 @@ export class BuildCommand {
         tsconfigJson: true,
       });
 
-      const entry = await boot.getServerEntry(root, args);
+      const entry = await this.boot.getAppEntry(root);
       this.log.trace("Entry file found", { entry });
 
       const distDir = "dist";
-      const clientDir = "public";
+      const publicDir = "public";
 
       await this.pm.ensureDependency(root, "vite", {
         run,
@@ -95,27 +93,55 @@ export class BuildCommand {
       await this.utils.loadEnv(root, [".env", ".env.production"]);
 
       const stats = flags.stats ?? options.stats ?? false;
-      const hasClient = await this.fs.exists(this.fs.join(root, "index.html"));
+      let template = "";
+      let hasClient = false;
+      let alepha: Alepha | undefined;
+
+      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");
+      }
 
       // Build client (precompress always enabled)
       if (hasClient) {
-        await run({
-          name: "vite build client",
-          handler: () =>
-            buildClient({
-              silent: true,
-              dist: `${distDir}/${clientDir}`,
-              stats,
-              precompress: true,
-            }),
-        });
+        // TODO: find a way to avoid writing index.html to disk
+        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);
+        }
       }
 
       // Build server
       await run({
         name: "vite build server",
         handler: async () => {
-          const clientIndexPath = `${distDir}/${clientDir}/index.html`;
+          if (!alepha) {
+            throw new AlephaError("Alepha instance not found");
+          }
+
+          const clientIndexPath = `${distDir}/${publicDir}/index.html`;
           const clientBuilt = await this.fs.exists(clientIndexPath);
 
           const conditions: string[] = [];
@@ -131,19 +157,18 @@ export class BuildCommand {
           // workerd:
           // - react-dom
           // - postgres
-
-          // TODO: investigate if we have more conditions like 'edge' to add here
           if (options.cloudflare) {
             conditions.push("workerd");
           }
 
           await buildServer({
             silent: true,
-            entry,
+            entry: entry.server,
             distDir,
-            clientDir: clientBuilt ? clientDir : undefined,
+            clientDir: clientBuilt ? publicDir : undefined,
             stats,
             conditions,
+            alepha,
           });
 
           // Server will handle index.html if both client & server are built
@@ -155,6 +180,7 @@ export class BuildCommand {
 
       // Copy assets
       await copyAssets({
+        alepha,
         root,
         entry: `${distDir}/index.js`,
         distDir,
@@ -165,30 +191,20 @@ export class BuildCommand {
         // Generate sitemap
         const sitemapHostname = flags.sitemap ?? options.sitemap?.hostname;
         if (sitemapHostname) {
-          await run({
-            name: "add sitemap",
-            handler: async () => {
-              await this.fs.writeFile(
-                `${distDir}/${clientDir}/sitemap.xml`,
-                await generateSitemap({
-                  entry: `${distDir}/index.js`,
-                  baseUrl: sitemapHostname,
-                }),
-              );
-            },
+          await generateSitemap({
+            alepha,
+            baseUrl: sitemapHostname,
+            output: `${distDir}/${publicDir}/sitemap.xml`,
+            run,
           });
         }
 
         // Pre-render static pages (always enabled)
-        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,
         });
       }
 
@@ -199,7 +215,7 @@ export class BuildCommand {
           handler: () =>
             generateVercel({
               distDir,
-              clientDir,
+              clientDir: publicDir,
               config: options.vercel,
             }),
         });

package/src/cli/commands/dev.ts

@@ -1,8 +1,9 @@
-import { $inject, Alepha, t } from "alepha";
+import { $inject, Alepha } from "alepha";
 import { $command } from "alepha/command";
 import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
-import { boot, devServer } from "alepha/vite";
+import { AppEntryProvider } from "../providers/AppEntryProvider.ts";
+import { ViteDevServerProvider } from "../providers/ViteDevServerProvider.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
 import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
@@ -14,6 +15,8 @@ export class DevCommand {
   protected readonly pm = $inject(PackageManagerUtils);
   protected readonly scaffolder = $inject(ProjectScaffolder);
   protected readonly alepha = $inject(Alepha);
+  protected readonly viteDevServer = $inject(ViteDevServerProvider);
+  protected readonly boot = $inject(AppEntryProvider);
 
   /**
    * Will run the project in watch mode.
@@ -24,9 +27,11 @@ export class DevCommand {
   public readonly 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.pm.hasExpo(root);
+    handler: async ({ root }) => {
+      const [expo, react] = await Promise.all([
+        this.pm.hasExpo(root),
+        this.pm.hasReact(root),
+      ]);
 
       await this.scaffolder.ensureConfig(root, {
         tsconfigJson: true,
@@ -37,41 +42,19 @@ export class DevCommand {
         return;
       }
 
-      const entry = await boot.getServerEntry(root, args);
-      this.log.trace("Entry file found", { entry });
+      const entry = await this.boot.getAppEntry(root);
+      this.log.debug("Entry file found", { entry });
 
-      const isFullstack = await this.isFullstackProject(root);
-
-      if (!isFullstack) {
-        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;
-      }
+      // -> here, we assume we use Vite as runner (api or fullstack)
+      // but it's planned to support Bun runner in the future as well
 
       // Ensure vite is installed before running
       await this.pm.ensureDependency(root, "vite", {
         exec: (cmd, opts) => this.utils.exec(cmd, opts),
       });
 
-      await devServer();
+      await this.viteDevServer.init({ root, entry });
+      await this.viteDevServer.start();
     },
   });
-
-  protected async isBunProject(root: string): Promise<boolean> {
-    if (this.alepha.isBun()) {
-      return true;
-    }
-    return this.fs.exists(this.fs.join(root, "bun.lock"));
-  }
-
-  protected async isFullstackProject(root: string): Promise<boolean> {
-    return this.fs.exists(this.fs.join(root, "index.html"));
-  }
 }

package/src/cli/commands/gen/env.ts

@@ -37,7 +37,7 @@ export class GenEnvCommand {
           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) {

package/src/cli/commands/init.ts

@@ -38,22 +38,28 @@ export class InitCommand {
       npm: t.optional(t.boolean({ description: "Use npm package manager" })),
       bun: t.optional(t.boolean({ description: "Use Bun package manager" })),
       // choose which dependencies to add
-      web: t.optional(
+      react: t.optional(
         t.boolean({
           aliases: ["r"],
           description: "Include Alepha React dependencies",
         }),
       ),
-      admin: t.optional(
+      ui: t.optional(
         t.boolean({ description: "Include Alepha UI dependencies" }),
       ),
       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, args }) => {
-      if (flags.admin) {
-        flags.web = true;
+      if (flags.react) {
+        flags.ui = true;
       }
 
       if (args) {
@@ -63,23 +69,26 @@ export class InitCommand {
 
       const isExpo = await this.pm.hasExpo(root);
 
+      const force = !!flags.force;
+
       await run({
         name: "ensuring configuration files",
         handler: async () => {
           await this.scaffolder.ensureConfig(root, {
+            force,
             tsconfigJson: true,
             packageJson: flags,
             biomeJson: true,
             editorconfig: true,
-            indexHtml: !!flags.web && !isExpo,
+            indexHtml: !!flags.react && !isExpo,
             claudeMd: flags.agent
-              ? { react: !!flags.web, ui: !!flags.admin }
+              ? { react: !!flags.react, ui: !!flags.ui }
               : false,
           });
 
           // Create API project structure if not React
-          if (!flags.web) {
-            await this.scaffolder.ensureApiProject(root);
+          if (!flags.react) {
+            await this.scaffolder.ensureApiProject(root, { force });
           }
         },
       });

package/src/cli/commands/lint.ts

@@ -17,7 +17,7 @@ export class LintCommand {
       await this.pm.ensureDependency(root, "@biomejs/biome", {
         exec: (cmd, opts) => this.utils.exec(cmd, opts),
       });
-      await this.utils.exec("biome check --formatter-enabled=false --fix");
+      await this.utils.exec("biome check --fix");
     },
   });
 }

package/src/cli/defineConfig.ts

@@ -1,8 +1,13 @@
 import type { Alepha } from "alepha";
 import type { CommandPrimitive } from "alepha/command";
+import {
+  type AppEntryOptions,
+  appEntryOptions,
+} from "./atoms/appEntryOptions.ts";
 import { type BuildOptions, buildOptions } from "./atoms/buildOptions.ts";
 
 export interface AlephaCliConfig {
+  entry?: AppEntryOptions;
   /**
    * Add custom commands to the Alepha CLI.
    *
@@ -54,6 +59,10 @@ export const defineConfig = (
       alepha.set(buildOptions, config.build);
     }
 
+    if (config.entry) {
+      alepha.set(appEntryOptions, config.entry);
+    }
+
     return {
       ...config.commands,
     };

package/src/cli/index.ts

@@ -1,12 +1,12 @@
 export * from "./apps/AlephaCli.ts";
 export * from "./apps/AlephaPackageBuilderCli.ts";
+export { default as AlephaPackageBuilderCli } from "./apps/AlephaPackageBuilderCli.ts";
 export * from "./atoms/changelogOptions.ts";
 export * from "./commands/build.ts";
 export * from "./commands/clean.ts";
 export * from "./commands/db.ts";
 export * from "./commands/deploy.ts";
 export * from "./commands/dev.ts";
-export * from "./commands/format.ts";
 export * from "./commands/gen/changelog.ts";
 export * from "./commands/gen/openapi.ts";
 export * from "./commands/init.ts";
@@ -16,6 +16,7 @@ export * from "./commands/test.ts";
 export * from "./commands/typecheck.ts";
 export * from "./commands/verify.ts";
 export * from "./defineConfig.ts";
+export * from "./providers/AppEntryProvider.ts";
 export * from "./services/AlephaCliUtils.ts";
 export * from "./services/GitMessageParser.ts";
 export * from "./version.ts";