alepha 0.14.4 → 0.15.0

package/src/cli/assets/claudeMd.ts

@@ -0,0 +1,303 @@
+export interface ClaudeMdOptions {
+  react?: boolean;
+  ui?: boolean;
+  projectName?: string;
+}
+
+export const claudeMd = (options: ClaudeMdOptions = {}) => {
+  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)
+├── index.html            # (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)
+
+## 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();
+};

package/src/cli/assets/mainBrowserTs.ts

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

package/src/cli/assets/mainServerTs.ts

@@ -0,0 +1,24 @@
+export interface MainServerTsOptions {
+  react?: boolean;
+}
+
+export const mainServerTs = (options: MainServerTsOptions = {}) => {
+  const { react = false } = options;
+
+  const webImport = react
+    ? `import { WebModule } from "./web/index.ts";\n`
+    : "";
+
+  const webWith = react ? `alepha.with(WebModule);\n` : "";
+
+  return `
+import { Alepha, run } from "alepha";
+import { ApiModule } from "./api/index.ts";
+${webImport}
+const alepha = Alepha.create();
+
+alepha.with(ApiModule);
+${webWith}
+run(alepha);
+`.trim();
+};

package/src/cli/assets/webAppRouterTs.ts

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

package/src/cli/assets/webHelloComponentTsx.ts

@@ -0,0 +1,16 @@
+export const webHelloComponentTsx = () => `
+interface Props {
+  message: string;
+}
+
+const Hello = (props: Props) => {
+  return (
+    <div>
+      <h1>{props.message}</h1>
+      <p>Edit this component in src/web/components/Hello.tsx</p>
+    </div>
+  );
+};
+
+export default Hello;
+`.trim();

package/src/cli/assets/webIndexTs.ts

@@ -0,0 +1,16 @@
+export interface WebIndexTsOptions {
+  appName?: string;
+}
+
+export const webIndexTs = (options: WebIndexTsOptions = {}) => {
+  const { appName = "app" } = options;
+  return `
+import { $module } from "alepha";
+import { AppRouter } from "./AppRouter.ts";
+
+export const WebModule = $module({
+  name: "${appName}.web",
+  services: [AppRouter],
+});
+`.trim();
+};

package/src/cli/commands/build.ts

@@ -1,7 +1,6 @@
-import { access, readFile, unlink, writeFile } from "node:fs/promises";
-import { join } from "node:path";
 import { $inject, $use, t } from "alepha";
 import { $command } from "alepha/command";
+import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import {
   boot,
@@ -16,10 +15,15 @@ import {
 } from "alepha/vite";
 import { buildOptions } from "../atoms/buildOptions.ts";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
+import { ProjectScaffolder } from "../services/ProjectScaffolder.ts";
 
 export class BuildCommand {
   protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
   protected readonly utils = $inject(AlephaCliUtils);
+  protected readonly pm = $inject(PackageManagerUtils);
+  protected readonly scaffolder = $inject(ProjectScaffolder);
   protected readonly options = $use(buildOptions);
 
   public readonly build = $command({
@@ -55,18 +59,23 @@ export class BuildCommand {
           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 }) => {
       // Tell viteAlephaBuild plugin to skip - CLI handles all tasks
       process.env.ALEPHA_BUILD_MODE = "cli";
       process.env.NODE_ENV = "production";
 
-      if (await this.utils.hasExpo(root)) {
+      if (await this.pm.hasExpo(root)) {
         // will come soon
         return;
       }
 
-      await this.utils.ensureConfig(root, {
+      await this.scaffolder.ensureConfig(root, {
         tsconfigJson: true,
       });
 
@@ -76,21 +85,17 @@ export class BuildCommand {
       const distDir = "dist";
       const clientDir = "public";
 
-      await this.utils.ensureDependency(root, "vite", { run });
+      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 hasClient = false;
-      try {
-        await access(join(root, "index.html"));
-        hasClient = true;
-      } catch {
-        // No index.html
-      }
+      const hasClient = await this.fs.exists(this.fs.join(root, "index.html"));
 
       // Build client (precompress always enabled)
       if (hasClient) {
@@ -110,12 +115,26 @@ export class BuildCommand {
       await run({
         name: "vite build server",
         handler: async () => {
-          let clientBuilt = false;
-          try {
-            await readFile(`${distDir}/${clientDir}/index.html`, "utf-8");
-            clientBuilt = true;
-          } catch {
-            // No client build
+          const clientIndexPath = `${distDir}/${clientDir}/index.html`;
+          const clientBuilt = await this.fs.exists(clientIndexPath);
+
+          const conditions: string[] = [];
+
+          // bun:
+          // - alepha
+          // - react-dom
+
+          if (flags.bun) {
+            conditions.push("bun");
+          }
+
+          // workerd:
+          // - react-dom
+          // - postgres
+
+          // TODO: investigate if we have more conditions like 'edge' to add here
+          if (options.cloudflare) {
+            conditions.push("workerd");
           }
 
           await buildServer({
@@ -124,11 +143,12 @@ export class BuildCommand {
             distDir,
             clientDir: clientBuilt ? clientDir : undefined,
             stats,
+            conditions,
           });
 
           // Server will handle index.html if both client & server are built
           if (clientBuilt) {
-            await unlink(`${distDir}/${clientDir}/index.html`);
+            await this.fs.rm(clientIndexPath);
           }
         },
       });
@@ -148,7 +168,7 @@ export class BuildCommand {
           await run({
             name: "add sitemap",
             handler: async () => {
-              await writeFile(
+              await this.fs.writeFile(
                 `${distDir}/${clientDir}/sitemap.xml`,
                 await generateSitemap({
                   entry: `${distDir}/index.js`,

package/src/cli/commands/db.ts

@@ -1,7 +1,6 @@
-import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
+import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import type {
   DatabaseProvider,
@@ -27,6 +26,7 @@ const drizzleCommandFlags = t.object({
 
 export class DbCommand {
   protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
   protected readonly utils = $inject(AlephaCliUtils);
 
   /**
@@ -66,26 +66,23 @@ export class DbCommand {
 
         accepted.add(providerName);
 
-        const migrationDir = join(rootDir, "migrations", providerName);
+        const migrationDir = this.fs.join(rootDir, "migrations", providerName);
 
-        const journalFile = await readFile(
-          `${migrationDir}/meta/_journal.json`,
-          "utf-8",
-        ).catch(() => null);
+        const journalBuffer = await this.fs
+          .readFile(`${migrationDir}/meta/_journal.json`)
+          .catch(() => null);
 
-        if (!journalFile) {
+        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();
@@ -295,6 +292,10 @@ export class DbCommand {
       const providerName = provider.name;
       const dialect = provider.dialect;
 
+      if (providerName === "") {
+        continue;
+      }
+
       if (accepted.has(providerName)) {
         continue;
       }
@@ -316,6 +317,7 @@ export class DbCommand {
         provider,
         providerName,
         providerUrl: provider.url,
+        providerDriver: provider.driver,
         dialect,
         entry,
         rootDir,
@@ -341,6 +343,7 @@ export class DbCommand {
     provider: DatabaseProvider;
     providerName: string;
     providerUrl: string;
+    providerDriver: string;
     dialect: string;
     entry: string;
     rootDir: string;
@@ -371,16 +374,16 @@ export class DbCommand {
       config.schemaFilter = options.provider.schema;
     }
 
-    if (options.providerName === "d1") {
+    if (options.providerDriver === "d1") {
       config.driver = "d1-http";
     }
 
-    if (options.providerName === "pglite") {
+    if (options.providerDriver === "pglite") {
       config.driver = "pglite";
     }
 
     if (options.dialect === "sqlite") {
-      if (options.providerName === "d1") {
+      if (options.providerDriver === "d1") {
         const token = process.env.CLOUDFLARE_API_TOKEN;
         if (!token) {
           throw new AlephaError(
@@ -421,7 +424,7 @@ export class DbCommand {
       } 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,

package/src/cli/commands/deploy.ts

@@ -1,12 +1,15 @@
-import { join } from "node:path";
 import { $inject, AlephaError, t } from "alepha";
 import { $command } from "alepha/command";
+import { FileSystemProvider } from "alepha/file";
 import { $logger } from "alepha/logger";
 import { AlephaCliUtils } from "../services/AlephaCliUtils.ts";
+import { PackageManagerUtils } from "../services/PackageManagerUtils.ts";
 
 export class DeployCommand {
   protected readonly log = $logger();
+  protected readonly fs = $inject(FileSystemProvider);
   protected readonly utils = $inject(AlephaCliUtils);
+  protected readonly pm = $inject(PackageManagerUtils);
 
   /**
    * Deploy the project to a hosting platform (e.g., Vercel, Cloudflare, Surge)
@@ -79,7 +82,10 @@ export class DeployCommand {
           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}`);
@@ -93,7 +99,10 @@ export class DeployCommand {
           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}`);
@@ -103,8 +112,11 @@ export class DeployCommand {
 
       // Surge deployment
       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;