alepha 0.15.0 → 0.15.2

package/dist/cli/index.d.ts

@@ -1,16 +1,374 @@
 import * as alepha0 from "alepha";
-import { Alepha, Static } from "alepha";
-import { FileSystemProvider } from "alepha/file";
-import * as alepha_command0 from "alepha/command";
-import { CliProvider, CommandPrimitive, EnvUtils, RunnerMethod } from "alepha/command";
+import { Alepha, FileLike, Json, Static, StreamLike } from "alepha";
+import { Readable } from "node:stream";
 import * as alepha_logger7 from "alepha/logger";
 import { ConsoleColorProvider } from "alepha/logger";
+import * as alepha_command0 from "alepha/command";
+import { CliProvider, CommandPrimitive, EnvUtils, RunnerMethod } from "alepha/command";
 import * as typebox0 from "typebox";
+import { Plugin, ViteDevServer } from "vite";
 import { DatabaseProvider } from "alepha/orm";
 
 //#region ../../src/cli/apps/AlephaCli.d.ts
 declare const AlephaCli: alepha0.Service<alepha0.Module>;
 //#endregion
+//#region ../../src/system/providers/FileSystemProvider.d.ts
+/**
+ * Options for creating a file from a URL
+ */
+interface CreateFileFromUrlOptions {
+  /**
+   * The URL to load the file from (file://, http://, or https://)
+   */
+  url: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a path (URL with file:// scheme)
+ */
+interface CreateFileFromPathOptions {
+  /**
+   * The path to the file on the local filesystem
+   */
+  path: string;
+  /**
+   * The MIME type of the file (optional, will be detected from filename if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (optional, will be extracted from URL if not provided)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a Buffer
+ */
+interface CreateFileFromBufferOptions {
+  /**
+   * The Buffer containing the file data
+   */
+  buffer: Buffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Options for creating a file from a stream
+ */
+interface CreateFileFromStreamOptions {
+  /**
+   * The readable stream containing the file data
+   */
+  stream: StreamLike;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+  /**
+   * The size of the file in bytes (optional)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from text content
+ */
+interface CreateFileFromTextOptions {
+  /**
+   * The text content to create the file from
+   */
+  text: string;
+  /**
+   * The MIME type of the file (default: text/plain)
+   */
+  type?: string;
+  /**
+   * The name of the file (default: "file.txt")
+   */
+  name?: string;
+}
+interface CreateFileFromResponseOptions {
+  /**
+   * The Response object containing the file data
+   */
+  response: Response;
+  /**
+   * Override the name (optional, uses filename from Content-Disposition header if not provided)
+   */
+  name?: string;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+}
+/**
+ * Options for creating a file from a Web File object
+ */
+interface CreateFileFromWebFileOptions {
+  /**
+   * The Web File object
+   */
+  file: File;
+  /**
+   * Override the MIME type (optional, uses file.type if not provided)
+   */
+  type?: string;
+  /**
+   * Override the name (optional, uses file.name if not provided)
+   */
+  name?: string;
+  /**
+   * Override the size (optional, uses file.size if not provided)
+   */
+  size?: number;
+}
+/**
+ * Options for creating a file from an ArrayBuffer
+ */
+interface CreateFileFromArrayBufferOptions {
+  /**
+   * The ArrayBuffer containing the file data
+   */
+  arrayBuffer: ArrayBuffer;
+  /**
+   * The MIME type of the file (optional, will be detected from name if not provided)
+   */
+  type?: string;
+  /**
+   * The name of the file (required for proper content type detection)
+   */
+  name?: string;
+}
+/**
+ * Union type for all createFile options
+ */
+type CreateFileOptions = CreateFileFromUrlOptions | CreateFileFromPathOptions | CreateFileFromBufferOptions | CreateFileFromStreamOptions | CreateFileFromTextOptions | CreateFileFromWebFileOptions | CreateFileFromResponseOptions | CreateFileFromArrayBufferOptions;
+/**
+ * Options for rm (remove) operation
+ */
+interface RmOptions {
+  /**
+   * If true, removes directories and their contents recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, no error will be thrown if the path does not exist
+   */
+  force?: boolean;
+}
+/**
+ * Options for cp (copy) operation
+ */
+interface CpOptions {
+  /**
+   * If true, copy directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, overwrite existing destination
+   */
+  force?: boolean;
+}
+/**
+ * Options for mkdir operation
+ */
+interface MkdirOptions {
+  /**
+   * If true, creates parent directories as needed
+   */
+  recursive?: boolean;
+  /**
+   * File mode (permission and sticky bits)
+   */
+  mode?: number;
+}
+/**
+ * Options for ls (list) operation
+ */
+interface LsOptions {
+  /**
+   * If true, list contents of directories recursively
+   */
+  recursive?: boolean;
+  /**
+   * If true, include hidden files (starting with .)
+   */
+  hidden?: boolean;
+}
+/**
+ * FileSystem interface providing utilities for working with files.
+ */
+declare abstract class FileSystemProvider {
+  /**
+   * Joins multiple path segments into a single path.
+   *
+   * @param paths - The path segments to join
+   * @returns The joined path
+   */
+  abstract join(...paths: string[]): string;
+  /**
+   * Creates a FileLike object from various sources.
+   *
+   * @param options - Options for creating the file
+   * @returns A FileLike object
+   */
+  abstract createFile(options: CreateFileOptions): FileLike;
+  /**
+   * Removes a file or directory.
+   *
+   * @param path - The path to remove
+   * @param options - Remove options
+   */
+  abstract rm(path: string, options?: RmOptions): Promise<void>;
+  /**
+   * Copies a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   * @param options - Copy options
+   */
+  abstract cp(src: string, dest: string, options?: CpOptions): Promise<void>;
+  /**
+   * Moves/renames a file or directory.
+   *
+   * @param src - Source path
+   * @param dest - Destination path
+   */
+  abstract mv(src: string, dest: string): Promise<void>;
+  /**
+   * Creates a directory.
+   *
+   * @param path - The directory path to create
+   * @param options - Mkdir options
+   */
+  abstract mkdir(path: string, options?: MkdirOptions): Promise<void>;
+  /**
+   * Lists files in a directory.
+   *
+   * @param path - The directory path to list
+   * @param options - List options
+   * @returns Array of filenames
+   */
+  abstract ls(path: string, options?: LsOptions): Promise<string[]>;
+  /**
+   * Checks if a file or directory exists.
+   *
+   * @param path - The path to check
+   * @returns True if the path exists, false otherwise
+   */
+  abstract exists(path: string): Promise<boolean>;
+  /**
+   * Reads the content of a file.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a Buffer
+   */
+  abstract readFile(path: string): Promise<Buffer>;
+  /**
+   * Writes data to a file.
+   *
+   * @param path - The file path to write to
+   * @param data - The data to write (Buffer or string)
+   */
+  abstract writeFile(path: string, data: Uint8Array | Buffer | string | FileLike): Promise<void>;
+  /**
+   * Reads the content of a file as a string.
+   *
+   * @param path - The file path to read
+   * @returns The file content as a string
+   */
+  abstract readTextFile(path: string): Promise<string>;
+  /**
+   * Reads the content of a file as JSON.
+   *
+   * @param path - The file path to read
+   * @returns The parsed JSON content
+   */
+  abstract readJsonFile<T = unknown>(path: string): Promise<T>;
+}
+//#endregion
+//#region ../../src/system/providers/ShellProvider.d.ts
+interface ShellRunOptions {
+  /**
+   * Working directory for the command.
+   */
+  root?: string;
+  /**
+   * Additional environment variables.
+   */
+  env?: Record<string, string>;
+  /**
+   * Resolve the executable from node_modules/.bin.
+   * Supports local project, pnpm nested, and monorepo structures.
+   * @default false
+   */
+  resolve?: boolean;
+  /**
+   * Capture stdout instead of inheriting stdio.
+   * When true, returns stdout as string.
+   * When false, streams output to terminal.
+   * @default false
+   */
+  capture?: boolean;
+}
+/**
+ * Abstract provider for executing shell commands and binaries.
+ *
+ * Implementations:
+ * - `NodeShellProvider` - Real shell execution using Node.js child_process
+ * - `MemoryShellProvider` - In-memory mock for testing
+ *
+ * @example
+ * ```typescript
+ * class MyService {
+ *   protected readonly shell = $inject(ShellProvider);
+ *
+ *   async build() {
+ *     // Run shell command directly
+ *     await this.shell.run("yarn install");
+ *
+ *     // Run local binary with resolution
+ *     await this.shell.run("vite build", { resolve: true });
+ *
+ *     // Capture output
+ *     const output = await this.shell.run("echo hello", { capture: true });
+ *   }
+ * }
+ * ```
+ */
+declare abstract class ShellProvider {
+  /**
+   * Run a shell command or binary.
+   *
+   * @param command - The command to run
+   * @param options - Execution options
+   * @returns stdout if capture is true, empty string otherwise
+   */
+  abstract run(command: string, options?: ShellRunOptions): Promise<string>;
+  /**
+   * Check if a command is installed and available in the system PATH.
+   *
+   * @param command - The command name to check
+   * @returns true if the command is available
+   */
+  abstract isInstalled(command: string): Promise<boolean>;
+}
+//#endregion
 //#region ../../src/cli/apps/AlephaPackageBuilderCli.d.ts
 interface Module {
   name: string;
@@ -48,13 +406,74 @@ declare const DEFAULT_IGNORE: string[];
  */
 declare const changelogOptions: alepha0.Atom<alepha0.TObject<{
   /**
-       * Scopes to ignore (e.g., "project", "release", "chore").
-       * Commits like `feat(chore): ...` will be excluded from changelog.
-       */
+   * Scopes to ignore (e.g., "project", "release", "chore").
+   * Commits like `feat(chore): ...` will be excluded from changelog.
+   */
   ignore: alepha0.TOptional<alepha0.TArray<alepha0.TString>>;
-}>, "alepha.changelog">;
+}>, "alepha.cli.changelog.options">;
 type ChangelogOptions = Static<typeof changelogOptions.schema>;
 //#endregion
+//#region ../../src/cli/providers/AppEntryProvider.d.ts
+/**
+ * Service for locating entry files in Alepha projects.
+ *
+ * Originally in alepha/vite, moved to CLI to avoid cli -> vite dependency.
+ */
+declare class AppEntryProvider {
+  protected readonly fs: FileSystemProvider;
+  protected readonly options: Readonly<{
+    style?: string | undefined;
+    server?: string | undefined;
+    browser?: string | undefined;
+  }>;
+  protected readonly serverEntries: readonly ["main.server.ts", "main.server.tsx", "main.ts", "main.tsx"];
+  protected readonly browserEntries: readonly ["main.browser.ts", "main.browser.tsx", "main.ts", "main.tsx"];
+  protected readonly styleEntries: readonly ["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.
+   */
+  getAppEntry(root: string): Promise<AppEntry>;
+}
+interface AppEntry {
+  root: string;
+  server: string;
+  browser?: string;
+  style?: string;
+}
+//#endregion
+//#region ../../src/cli/services/ViteUtils.d.ts
+declare class ViteUtils {
+  protected readonly fs: FileSystemProvider;
+  protected viteDevServer?: ViteDevServer;
+  generateIndexHtml(entry: AppEntry): string;
+  /**
+   * We need to close the Vite dev server after build is done.
+   */
+  protected onReady: alepha0.HookPrimitive<"ready">;
+  protected onStop: alepha0.HookPrimitive<"stop">;
+  runAlepha(opts: {
+    entry: AppEntry;
+    mode: "production" | "development";
+  }): Promise<Alepha>;
+}
+//#endregion
+//#region ../../src/cli/providers/ViteBuildProvider.d.ts
+declare class ViteBuildProvider {
+  protected alepha?: Alepha;
+  protected appEntry?: AppEntry;
+  protected readonly viteUtils: ViteUtils;
+  init(opts: {
+    entry: AppEntry;
+  }): Promise<Alepha>;
+  hasClient(): boolean;
+  generateIndexHtml(): string;
+}
+//#endregion
 //#region ../../src/cli/services/AlephaCliUtils.d.ts
 /**
  * Core utility service for CLI commands.
@@ -69,38 +488,75 @@ declare class AlephaCliUtils {
   protected readonly log: alepha_logger7.Logger;
   protected readonly fs: FileSystemProvider;
   protected readonly envUtils: EnvUtils;
+  protected readonly boot: AppEntryProvider;
+  protected readonly shell: ShellProvider;
+  protected readonly viteUtils: ViteUtils;
   /**
-       * Execute a command with inherited stdio.
-       */
+   * Execute a command with inherited stdio.
+   *
+   * @param command - The command to execute
+   * @param options.root - Working directory
+   * @param options.env - Additional environment variables
+   * @param options.global - If true, run command directly without resolving from node_modules
+   */
   exec(command: string, options?: {
     root?: string;
     env?: Record<string, string>;
     global?: boolean;
   }): Promise<void>;
   /**
-       * Write a configuration file to node_modules/.alepha directory.
-       */
+   * Write a configuration file to node_modules/.alepha directory.
+   */
   writeConfigFile(name: string, content: string, root?: string): Promise<string>;
+  loadAlephaFromServerEntryFile(opts: {
+    mode: "production" | "development";
+  } & ({
+    entry: AppEntry;
+  } | {
+    root: string;
+  })): Promise<Alepha>;
   /**
-       * Load Alepha instance from a server entry file.
-       */
-  loadAlephaFromServerEntryFile(rootDir?: string, explicitEntry?: string): Promise<{
-    alepha: Alepha;
-    entry: string;
-  }>;
-  /**
-       * Generate JavaScript code for Drizzle entities export.
-       */
+   * Generate JavaScript code for Drizzle entities export.
+   */
   generateEntitiesJs(entry: string, provider: string, models?: string[]): string;
   /**
-       * Load environment variables from a .env file.
-       */
+   * Load environment variables from a .env file.
+   */
   loadEnv(root: string, files?: string[]): Promise<void>;
   exists(root: string, path: string): Promise<boolean>;
-  protected checkFileExists(root: string, name: string): Promise<string | undefined>;
+  /**
+   * Check if a command is installed and available in the system PATH.
+   */
+  isInstalledAsync(cmd: string): Promise<boolean>;
 }
 //#endregion
 //#region ../../src/cli/services/PackageManagerUtils.d.ts
+/**
+ * Context information about a workspace root.
+ * Used when initializing a package inside a monorepo.
+ */
+interface WorkspaceContext {
+  /**
+   * Whether we're inside a workspace package.
+   */
+  isPackage: boolean;
+  /**
+   * The workspace root directory (e.g., ../.. from packages/my-pkg).
+   */
+  workspaceRoot: string | null;
+  /**
+   * Package manager detected at workspace root.
+   */
+  packageManager: "yarn" | "pnpm" | "npm" | "bun" | null;
+  /**
+   * Config files present at workspace root.
+   */
+  config: {
+    biomeJson: boolean;
+    editorconfig: boolean;
+    tsconfigJson: boolean;
+  };
+}
 /**
  * Utility service for package manager operations.
  *
@@ -115,31 +571,45 @@ declare class PackageManagerUtils {
   protected readonly fs: FileSystemProvider;
   protected readonly alepha: Alepha;
   /**
-       * Detect the package manager used in the project.
-       */
-  getPackageManager(root: string, flags?: {
-    yarn?: boolean;
-    pnpm?: boolean;
-    npm?: boolean;
-    bun?: boolean;
-  }): Promise<"yarn" | "pnpm" | "npm" | "bun">;
-  /**
-       * Get the install command for a package.
-       */
+   * Detect the package manager used in the project.
+   */
+  getPackageManager(root: string, pm?: "yarn" | "pnpm" | "npm" | "bun"): Promise<"yarn" | "pnpm" | "npm" | "bun">;
+  /**
+   * Detect workspace context when inside a monorepo package.
+   *
+   * Checks if we're inside a workspace package (e.g., packages/my-pkg or apps/my-app)
+   * by looking 2 levels up for workspace indicators like lockfiles and config files.
+   *
+   * @param root - The current package directory
+   * @returns Workspace context with root path, PM, and config presence
+   */
+  getWorkspaceContext(root: string): Promise<WorkspaceContext>;
+  /**
+   * Get the install command for a package.
+   */
   getInstallCommand(root: string, packageName: string, dev?: boolean): Promise<string>;
   /**
-       * Check if a dependency is installed in the project.
-       */
+   * Check if a dependency is installed in the project.
+   */
   hasDependency(root: string, packageName: string): Promise<boolean>;
   /**
-       * Check if Expo is present in the project.
-       */
+   * Check if Expo is present in the project.
+   */
   hasExpo(root: string): Promise<boolean>;
   /**
-       * Install a dependency if it's missing from the project.
-       */
+   * Check if React is present in the project.
+   */
+  hasReact(root: string): Promise<boolean>;
+  /**
+   * Install a dependency if it's missing from the project.
+   * Optionally checks workspace root for the dependency in monorepo setups.
+   */
   ensureDependency(root: string, packageName: string, options?: {
     dev?: boolean;
+    /**
+     * Also check workspace root for the dependency (for monorepo setups).
+     */
+    checkWorkspace?: boolean;
     run?: RunnerMethod;
     exec?: (cmd: string, opts?: {
       global?: boolean;
@@ -168,17 +638,23 @@ declare class PackageManagerUtils {
   protected removeFiles(root: string, files: string[]): Promise<void>;
 }
 interface DependencyModes {
-  web?: boolean;
-  admin?: boolean;
+  react?: boolean;
+  ui?: boolean;
   expo?: boolean;
+  test?: boolean;
+  /**
+   * Skip biome/vitest when inside a workspace package (they're at root).
+   */
+  isPackage?: boolean;
 }
 //#endregion
-//#region ../../src/cli/assets/claudeMd.d.ts
-interface ClaudeMdOptions {
+//#region ../../src/cli/templates/agentMd.d.ts
+interface AgentMdOptions {
   react?: boolean;
   ui?: boolean;
   projectName?: string;
 }
+type AgentMdType = "claude" | "agents";
 //#endregion
 //#region ../../src/cli/services/ProjectScaffolder.d.ts
 /**
@@ -194,57 +670,98 @@ declare class ProjectScaffolder {
   protected readonly log: alepha_logger7.Logger;
   protected readonly fs: FileSystemProvider;
   protected readonly pm: PackageManagerUtils;
+  protected readonly utils: AlephaCliUtils;
   /**
-       * Get the app name from the directory name.
-       *
-       * Converts the directory name to a valid module name:
-       * - Converts to lowercase
-       * - Replaces spaces, dashes, underscores with nothing
-       * - Falls back to "app" if empty
-       */
+   * Get the app name from the directory name.
+   *
+   * Converts the directory name to a valid module name:
+   * - Converts to lowercase
+   * - Replaces spaces, dashes, underscores with nothing
+   * - Falls back to "app" if empty
+   */
   getAppName(root: string): string;
   /**
-       * Ensure all configuration files exist.
-       */
+   * Ensure all configuration files exist.
+   */
   ensureConfig(root: string, opts: {
+    force?: boolean;
+    /**
+     * Check workspace root for existing config files.
+     */
+    checkWorkspace?: boolean;
     packageJson?: boolean | DependencyModes;
     tsconfigJson?: boolean;
-    indexHtml?: boolean;
     biomeJson?: boolean;
     editorconfig?: boolean;
-    claudeMd?: boolean | ClaudeMdOptions;
+    agentMd?: false | (AgentMdOptions & {
+      type: AgentMdType;
+    });
+  }): Promise<void>;
+  ensureTsConfig(root: string, opts?: {
+    force?: boolean;
+  }): Promise<void>;
+  ensureBiomeConfig(root: string, opts?: {
+    force?: boolean;
+    checkWorkspace?: boolean;
+  }): Promise<void>;
+  ensureEditorConfig(root: string, opts?: {
+    force?: boolean;
+    checkWorkspace?: boolean;
+  }): Promise<void>;
+  /**
+   * Ensure git repository is initialized with .gitignore.
+   *
+   * @returns true if git was initialized, false if already exists or git unavailable
+   */
+  ensureGitRepo(root: string, opts?: {
+    force?: boolean;
+  }): Promise<boolean>;
+  ensureAgentMd(root: string, options: AgentMdOptions & {
+    type: AgentMdType;
+    force?: boolean;
+  }): Promise<void>;
+  /**
+   * Ensure src/main.server.ts exists with correct module imports.
+   */
+  ensureMainServerTs(root: string, opts?: {
+    api?: boolean;
+    react?: boolean;
+    force?: boolean;
+  }): Promise<void>;
+  /**
+   * Ensure API module structure exists.
+   *
+   * Creates:
+   * - src/api/index.ts (API module)
+   * - src/api/controllers/HelloController.ts (example controller)
+   */
+  ensureApiProject(root: string, opts?: {
+    force?: boolean;
+  }): Promise<void>;
+  /**
+   * Ensure web/React project structure exists.
+   *
+   * Creates:
+   * - src/main.browser.ts
+   * - src/main.css
+   * - src/web/index.ts, src/web/AppRouter.ts, src/web/components/Hello.tsx
+   */
+  ensureWebProject(root: string, opts?: {
+    api?: boolean;
+    ui?: boolean;
+    force?: boolean;
   }): Promise<void>;
-  ensureTsConfig(root: string): Promise<void>;
-  ensureBiomeConfig(root: string): Promise<void>;
-  ensureEditorConfig(root: string): Promise<void>;
-  ensureClaudeMd(root: string, options?: ClaudeMdOptions): Promise<void>;
-  /**
-       * Ensure src/main.server.ts exists with full API structure.
-       *
-       * Creates:
-       * - src/main.server.ts (entry point)
-       * - src/api/index.ts (API module)
-       * - src/api/controllers/HelloController.ts (example controller)
-       */
-  ensureApiProject(root: string): Promise<void>;
-  /**
-       * Ensure full React project structure exists.
-       *
-       * Creates:
-       * - index.html
-       * - 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
-       */
-  ensureReactProject(root: string): Promise<void>;
-  /**
-       * Ensure test directory exists with a dummy test file.
-       */
+  /**
+   * Ensure test directory exists with a dummy test file.
+   */
   ensureTestDir(root: string): Promise<void>;
-  protected ensureFileIfNotExists(root: string, relativePath: string, content: string): Promise<void>;
   /**
-       * Check if a file exists in the given directory or any parent directory.
-       */
+   * Write a file, optionally overriding if it exists.
+   */
+  protected ensureFile(root: string, relativePath: string, content: string, force?: boolean): Promise<void>;
+  /**
+   * Check if a file exists in the given directory or any parent directory.
+   */
   protected existsInParents(root: string, filename: string): Promise<boolean>;
 }
 //#endregion
@@ -255,6 +772,8 @@ declare class BuildCommand {
   protected readonly utils: AlephaCliUtils;
   protected readonly pm: PackageManagerUtils;
   protected readonly scaffolder: ProjectScaffolder;
+  protected readonly boot: AppEntryProvider;
+  protected readonly viteBuildProvider: ViteBuildProvider;
   protected readonly options: Readonly<{
     stats?: boolean | undefined;
     vercel?: {
@@ -288,14 +807,14 @@ declare class BuildCommand {
     docker: alepha0.TOptional<alepha0.TBoolean>;
     sitemap: alepha0.TOptional<alepha0.TString>;
     bun: alepha0.TOptional<alepha0.TBoolean>;
-  }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
+  }>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
 }
 //#endregion
 //#region ../../src/cli/commands/clean.d.ts
 declare class CleanCommand {
   /**
-       * Clean the project, removing the "dist" directory
-       */
+   * Clean the project, removing the "dist" directory
+   */
   readonly clean: alepha_command0.CommandPrimitive<typebox0.TObject<typebox0.TProperties>, typebox0.TSchema, typebox0.TObject<typebox0.TProperties>>;
 }
 //#endregion
@@ -304,49 +823,50 @@ declare class DbCommand {
   protected readonly log: alepha_logger7.Logger;
   protected readonly fs: FileSystemProvider;
   protected readonly utils: AlephaCliUtils;
+  protected readonly entryProvider: AppEntryProvider;
   /**
-       * Check if database migrations are up to date.
-       */
+   * Check if database migrations are up to date.
+   */
   protected readonly check: alepha_command0.CommandPrimitive<alepha0.TObject<{
     provider: alepha0.TOptional<alepha0.TString>;
     mode: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Generate database migration files
-       */
+   * Generate database migration files
+   */
   protected readonly generate: alepha_command0.CommandPrimitive<alepha0.TObject<{
     provider: alepha0.TOptional<alepha0.TString>;
     mode: alepha0.TOptional<alepha0.TString>;
     custom: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Push database schema changes directly to the database
-       */
+   * Push database schema changes directly to the database
+   */
   protected readonly push: alepha_command0.CommandPrimitive<alepha0.TObject<{
     provider: alepha0.TOptional<alepha0.TString>;
     mode: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Apply pending database migrations
-       */
+   * Apply pending database migrations
+   */
   protected readonly migrate: alepha_command0.CommandPrimitive<alepha0.TObject<{
     provider: alepha0.TOptional<alepha0.TString>;
     mode: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Launch Drizzle Studio database browser
-       */
+   * Launch Drizzle Studio database browser
+   */
   protected readonly studio: alepha_command0.CommandPrimitive<alepha0.TObject<{
     provider: alepha0.TOptional<alepha0.TString>;
     mode: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Parent command for database operations.
-       */
+   * Parent command for database operations.
+   */
   readonly db: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
   /**
-       * Run a drizzle-kit command for all database providers in an Alepha instance.
-       */
+   * Run a drizzle-kit command for all database providers in an Alepha instance.
+   */
   runDrizzleKitCommand(options: {
     root: string;
     args?: string;
@@ -357,8 +877,8 @@ declare class DbCommand {
     env?: string;
   }): Promise<void>;
   /**
-       * Prepare Drizzle configuration files for a database provider.
-       */
+   * Prepare Drizzle configuration files for a database provider.
+   */
   prepareDrizzleConfig(options: {
     kit: any;
     provider: DatabaseProvider;
@@ -378,24 +898,24 @@ declare class DeployCommand {
   protected readonly utils: AlephaCliUtils;
   protected readonly pm: PackageManagerUtils;
   /**
-       * Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)
-       *
-       * Deploy command can be overridden by creating a alepha.config.ts in the project root:
-       *
-       * ```ts
-       * import { defineConfig } from "alepha/cli";
-       *
-       * export default defineConfig({
-       *   commands: {
-       *     deploy: {
-       *       handler: async ({ root, mode, flags }) => {
-       *         // Custom deployment logic here
-       *       },
-       *     },
-       *   },
-       * });
-       * ```
-       */
+   * Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)
+   *
+   * Deploy command can be overridden by creating a alepha.config.ts in the project root:
+   *
+   * ```ts
+   * import { defineConfig } from "alepha/cli";
+   *
+   * export default defineConfig({
+   *   commands: {
+   *     deploy: {
+   *       handler: async ({ root, mode, flags }) => {
+   *         // Custom deployment logic here
+   *       },
+   *     },
+   *   },
+   * });
+   * ```
+   */
   readonly deploy: alepha_command0.CommandPrimitive<alepha0.TObject<{
     build: alepha0.TBoolean;
     migrate: alepha0.TBoolean;
@@ -408,6 +928,96 @@ declare class DeployCommand {
   }>>;
 }
 //#endregion
+//#region ../../src/cli/providers/ViteDevServerProvider.d.ts
+interface ViteDevServerOptions {
+  /**
+   * Root directory of the project.
+   */
+  root: string;
+  /**
+   * Path to the server entry file.
+   */
+  entry: AppEntry;
+  /**
+   * Port to run the dev server on.
+   */
+  port?: number;
+  /**
+   * Host to bind the dev server to.
+   */
+  host?: string | boolean;
+}
+/**
+ * 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)
+ */
+declare class ViteDevServerProvider {
+  protected readonly log: alepha_logger7.Logger;
+  protected readonly fs: FileSystemProvider;
+  protected readonly templateProvider: ViteUtils;
+  protected server: ViteDevServer;
+  protected options: ViteDevServerOptions;
+  protected alepha: Alepha | null;
+  protected hasError: boolean;
+  protected changedFiles: Set<string>;
+  init(options: ViteDevServerOptions): Promise<Alepha>;
+  start(): Promise<void>;
+  /**
+   * Create the Vite server in middleware mode.
+   */
+  protected createViteServer(): Promise<void>;
+  /**
+   * Vite plugin to handle HMR for Alepha.
+   */
+  protected createHmrPlugin(): Plugin;
+  /**
+   * Send browser reload signal via custom event.
+   * Browser listens for 'alepha:reload' and does window.location.reload()
+   */
+  protected sendBrowserReload(): void;
+  /**
+   * Setup environment variables for dev mode.
+   */
+  protected setupEnvironment(): Promise<void>;
+  /**
+   * Load or reload the Alepha instance.
+   */
+  protected loadAlepha(isInitialLoad?: boolean): Promise<Alepha>;
+  hasReact(): boolean;
+  /**
+   * Setup Alepha instance with Vite middleware and template.
+   */
+  protected setupAlepha(): Promise<void>;
+  /**
+   * Check if request is for an HTML page (not an asset).
+   */
+  protected isPageRequest(req: any): boolean;
+  /**
+   * Run Vite middleware and detect if it handled the request.
+   */
+  protected runViteMiddleware(req: any, res: any, ctx: {
+    metadata: any;
+  }): Promise<boolean>;
+  /**
+   * Invalidate modules and all their importers.
+   */
+  protected invalidateModulesWithImporters(): void;
+}
+//#endregion
 //#region ../../src/cli/commands/dev.d.ts
 declare class DevCommand {
   protected readonly log: alepha_logger7.Logger;
@@ -416,23 +1026,12 @@ declare class DevCommand {
   protected readonly pm: PackageManagerUtils;
   protected readonly scaffolder: ProjectScaffolder;
   protected readonly alepha: Alepha;
+  protected readonly viteDevServer: ViteDevServerProvider;
+  protected readonly boot: 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.
-       */
-  readonly dev: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
-  protected isBunProject(root: string): Promise<boolean>;
-  protected isFullstackProject(root: string): Promise<boolean>;
-}
-//#endregion
-//#region ../../src/cli/commands/format.d.ts
-declare class FormatCommand {
-  protected readonly utils: AlephaCliUtils;
-  protected readonly pm: PackageManagerUtils;
-  protected readonly scaffolder: ProjectScaffolder;
-  readonly format: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
+   * Will run the project in watch mode.
+   */
+  readonly dev: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
 }
 //#endregion
 //#region ../../src/cli/services/GitMessageParser.d.ts
@@ -453,16 +1052,16 @@ declare class FormatCommand {
 declare class GitMessageParser {
   protected readonly log: alepha_logger7.Logger;
   /**
-       * Parse a git commit line into a structured Commit object.
-       *
-       * **Format:** `type(scope): description` or `type(scope)!: description`
-       *
-       * **Supported types:** feat, fix, docs, refactor, perf, revert
-       *
-       * **Breaking changes:** Use `!` before `:` (e.g., `feat(api)!: remove endpoint`)
-       *
-       * @returns Commit object or null if not matching/ignored
-       */
+   * Parse a git commit line into a structured Commit object.
+   *
+   * **Format:** `type(scope): description` or `type(scope)!: description`
+   *
+   * **Supported types:** feat, fix, docs, refactor, perf, revert
+   *
+   * **Breaking changes:** Use `!` before `:` (e.g., `feat(api)!: remove endpoint`)
+   *
+   * @returns Commit object or null if not matching/ignored
+   */
   parseCommit(line: string, config: ChangelogOptions): Commit | null;
 }
 //#endregion
@@ -502,39 +1101,39 @@ declare class ChangelogCommand {
     ignore?: string[] | undefined;
   }>;
   /**
-       * Format a single commit line.
-       * Example: `- **cli**: add new command (\`abc1234\`)`
-       * Breaking changes are flagged: `- **cli**: add new command [BREAKING] (\`abc1234\`)`
-       */
+   * Format a single commit line.
+   * Example: `- **cli**: add new command (\`abc1234\`)`
+   * Breaking changes are flagged: `- **cli**: add new command [BREAKING] (\`abc1234\`)`
+   */
   protected formatCommit(commit: Commit): string;
   /**
-       * Format the changelog entry with sections.
-       */
+   * Format the changelog entry with sections.
+   */
   protected formatEntry(entry: ChangelogEntry): string;
   /**
-       * Parse git log output into a changelog entry.
-       */
+   * Parse git log output into a changelog entry.
+   */
   protected parseCommits(commitsOutput: string): ChangelogEntry;
   /**
-       * Check if entry has any public commits.
-       */
+   * Check if entry has any public commits.
+   */
   protected hasChanges(entry: ChangelogEntry): boolean;
   /**
-       * Get the latest version tag.
-       */
+   * Get the latest version tag.
+   */
   protected getLatestTag(git: (cmd: string) => Promise<string>): Promise<string | null>;
   readonly command: alepha_command0.CommandPrimitive<alepha0.TObject<{
     /**
-             * Show changes from this ref (tag, commit, branch).
-             * Defaults to the latest version tag.
-             * Example: --from=1.0.0
-             */
+     * Show changes from this ref (tag, commit, branch).
+     * Defaults to the latest version tag.
+     * Example: --from=1.0.0
+     */
     from: alepha0.TOptional<alepha0.TString>;
     /**
-             * Show changes up to this ref (tag, commit, branch).
-             * Defaults to HEAD.
-             * Example: --to=main
-             */
+     * Show changes up to this ref (tag, commit, branch).
+     * Defaults to HEAD.
+     * Example: --to=main
+     */
     to: alepha0.TOptional<alepha0.TString>;
   }>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
 }
@@ -556,18 +1155,17 @@ declare class InitCommand {
   protected readonly scaffolder: ProjectScaffolder;
   protected readonly fs: FileSystemProvider;
   /**
-       * Ensure the project has the necessary Alepha configuration files.
-       * Add the correct dependencies to package.json and install them.
-       */
+   * Ensure the project has the necessary Alepha configuration files.
+   * Add the correct dependencies to package.json and install them.
+   */
   readonly init: alepha_command0.CommandPrimitive<alepha0.TObject<{
     agent: alepha0.TOptional<alepha0.TBoolean>;
-    yarn: alepha0.TOptional<alepha0.TBoolean>;
-    pnpm: alepha0.TOptional<alepha0.TBoolean>;
-    npm: alepha0.TOptional<alepha0.TBoolean>;
-    bun: alepha0.TOptional<alepha0.TBoolean>;
-    web: alepha0.TOptional<alepha0.TBoolean>;
-    admin: alepha0.TOptional<alepha0.TBoolean>;
+    pm: alepha0.TOptional<alepha0.TUnsafe<"bun" | "yarn" | "npm" | "pnpm">>;
+    api: alepha0.TOptional<alepha0.TBoolean>;
+    react: alepha0.TOptional<alepha0.TBoolean>;
+    ui: alepha0.TOptional<alepha0.TBoolean>;
     test: alepha0.TOptional<alepha0.TBoolean>;
+    force: alepha0.TOptional<alepha0.TBoolean>;
   }>, alepha0.TOptional<alepha0.TString>, alepha0.TObject<alepha0.TProperties>>;
 }
 //#endregion
@@ -586,8 +1184,8 @@ declare class RootCommand {
   protected readonly alepha: Alepha;
   protected readonly color: ConsoleColorProvider;
   /**
-       * Called when no command is provided
-       */
+   * Called when no command is provided
+   */
   readonly root: alepha_command0.CommandPrimitive<alepha0.TObject<{
     version: alepha0.TOptional<alepha0.TBoolean>;
   }>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
@@ -610,9 +1208,10 @@ declare class TypecheckCommand {
   protected readonly utils: AlephaCliUtils;
   protected readonly pm: PackageManagerUtils;
   protected readonly log: alepha_logger7.Logger;
+  protected readonly scaffolder: ProjectScaffolder;
   /**
-       * Run TypeScript type checking across the codebase with no emit.
-       */
+   * Run TypeScript type checking across the codebase with no emit.
+   */
   readonly typecheck: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
 }
 //#endregion
@@ -621,21 +1220,29 @@ declare class VerifyCommand {
   protected readonly utils: AlephaCliUtils;
   protected readonly pm: PackageManagerUtils;
   /**
-       * Run a series of verification commands to ensure code quality and correctness.
-       *
-       * This command runs the following checks in order:
-       * - Clean the project
-       * - Format the code
-       * - Lint the code
-       * - Run tests (if Vitest is a dev dependency)
-       * - Check database migrations (if a migrations directory exists)
-       * - Type check the code
-       * - Build the project
-       * - Clean the project again
-       */
+   * Run a series of verification commands to ensure code quality and correctness.
+   *
+   * This command runs the following checks in order:
+   * - Clean the project
+   * - Format the code
+   * - Lint the code
+   * - Run tests (if Vitest is a dev dependency)
+   * - Check database migrations (if a migrations directory exists)
+   * - Type check the code
+   * - Build the project
+   * - Clean the project again
+   */
   readonly verify: alepha_command0.CommandPrimitive<alepha0.TObject<alepha0.TProperties>, alepha0.TSchema, alepha0.TObject<alepha0.TProperties>>;
 }
 //#endregion
+//#region ../../src/cli/atoms/appEntryOptions.d.ts
+declare const appEntryOptions: alepha0.Atom<alepha0.TObject<{
+  server: alepha0.TOptional<alepha0.TString>;
+  browser: alepha0.TOptional<alepha0.TString>;
+  style: alepha0.TOptional<alepha0.TString>;
+}>, "alepha.cli.appEntry.options">;
+type AppEntryOptions = Static<typeof appEntryOptions.schema>;
+//#endregion
 //#region ../../src/cli/atoms/buildOptions.d.ts
 /**
  * Build options atom for CLI build command.
@@ -645,12 +1252,12 @@ declare class VerifyCommand {
  */
 declare const buildOptions: alepha0.Atom<alepha0.TObject<{
   /**
-       * Generate build stats report.
-       */
+   * Generate build stats report.
+   */
   stats: alepha0.TOptional<alepha0.TBoolean>;
   /**
-       * Vercel deployment configuration.
-       */
+   * Vercel deployment configuration.
+   */
   vercel: alepha0.TOptional<alepha0.TObject<{
     projectName: alepha0.TOptional<alepha0.TString>;
     orgId: alepha0.TOptional<alepha0.TString>;
@@ -663,36 +1270,36 @@ declare const buildOptions: alepha0.Atom<alepha0.TObject<{
     }>>;
   }>>;
   /**
-       * Cloudflare Workers deployment configuration.
-       */
+   * Cloudflare Workers deployment configuration.
+   */
   cloudflare: alepha0.TOptional<alepha0.TObject<{
     config: alepha0.TOptional<alepha0.TRecord<string, alepha0.TAny>>;
   }>>;
   /**
-       * Docker deployment configuration.
-       */
+   * Docker deployment configuration.
+   */
   docker: alepha0.TOptional<alepha0.TObject<{
     /**
-             * Docker image name to use in the Dockerfile.
-             * @default "node:24-alpine"
-             */
+     * Docker image name to use in the Dockerfile.
+     * @default "node:24-alpine"
+     */
     image: alepha0.TOptional<alepha0.TString>;
     /**
-             * Command to run in the Docker container.
-             * @default "node"
-             */
+     * Command to run in the Docker container.
+     * @default "node"
+     */
     command: alepha0.TOptional<alepha0.TString>;
   }>>;
   /**
-       * Sitemap generation configuration.
-       */
+   * Sitemap generation configuration.
+   */
   sitemap: alepha0.TOptional<alepha0.TObject<{
     /**
-             * Base URL for sitemap entries.
-             */
+     * Base URL for sitemap entries.
+     */
     hostname: alepha0.TString;
   }>>;
-}>, "alepha.build.options">;
+}>, "alepha.cli.build.options">;
 /**
  * Type for build options.
  */
@@ -700,26 +1307,27 @@ type BuildOptions = Static<typeof buildOptions.schema>;
 //#endregion
 //#region ../../src/cli/defineConfig.d.ts
 interface AlephaCliConfig {
+  entry?: AppEntryOptions;
   /**
-       * Add custom commands to the Alepha CLI.
-       *
-       * You can override 'deploy', 'build', 'dev', 'start' commands this way.
-       * But you can also add your own commands and run them via `alepha <command>`.
-       */
+   * Add custom commands to the Alepha CLI.
+   *
+   * You can override 'deploy', 'build', 'dev', 'start' commands this way.
+   * But you can also add your own commands and run them via `alepha <command>`.
+   */
   commands?: Record<string, CommandPrimitive>;
   /**
-       * Register more services to the Alepha CLI (enhancements, commands, etc.).
-       */
+   * Register more services to the Alepha CLI (enhancements, commands, etc.).
+   */
   services?: Array<any>;
   /**
-       * Configure Alepha build command.
-       */
+   * Configure Alepha build command.
+   */
   build?: BuildOptions;
   /**
-       * Environment variables to set before running commands.
-       *
-       * Always use .env files by default, this is only for dynamic values.
-       */
+   * Environment variables to set before running commands.
+   *
+   * Always use .env files by default, this is only for dynamic values.
+   */
   env?: Record<string, unknown>;
 }
 type AlephaCliConfigFn = (alepha: Alepha) => AlephaCliConfig;
@@ -736,5 +1344,5 @@ declare const defineAlephaConfig: (runConfig: AlephaCliConfig | AlephaCliConfigF
 //#region ../../src/cli/version.d.ts
 declare const version: any;
 //#endregion
-export { AlephaCli, AlephaCliConfig, AlephaCliConfigFn, AlephaCliUtils, AlephaPackageBuilderCli, BuildCommand, ChangelogCommand, type ChangelogOptions, CleanCommand, Commit, DEFAULT_IGNORE, DbCommand, DeployCommand, DevCommand, FormatCommand, GitMessageParser, GitProvider, InitCommand, LintCommand, OpenApiCommand, RootCommand, TestCommand, TypecheckCommand, VerifyCommand, analyzeModules, changelogOptions, defineAlephaConfig, defineConfig, version };
+export { AlephaCli, AlephaCliConfig, AlephaCliConfigFn, AlephaCliUtils, AlephaPackageBuilderCli, AppEntry, AppEntryProvider, BuildCommand, ChangelogCommand, type ChangelogOptions, CleanCommand, Commit, DEFAULT_IGNORE, DbCommand, DeployCommand, DevCommand, GitMessageParser, GitProvider, InitCommand, LintCommand, OpenApiCommand, RootCommand, TestCommand, TypecheckCommand, VerifyCommand, analyzeModules, changelogOptions, defineAlephaConfig, defineConfig, version };
 //# sourceMappingURL=index.d.ts.map