alepha 0.14.4 → 0.15.1

package/src/cli/assets/claudeMd.ts

@@ -0,0 +1,308 @@
+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)
+│   └── main.css          # CSS entry (React only)
+├── package.json
+└── tsconfig.json
+\`\`\`
+`
+    : `
+\`\`\`
+${projectName}/
+├── src/
+│   ├── api/              # Backend
+│   │   ├── controllers/  # API controllers with $action
+│   │   ├── services/     # Business logic
+│   │   ├── entities/     # Database entities with $entity
+│   │   ├── providers/    # External service wrappers
+│   │   └── index.ts      # API module definition with $module
+│   └── main.server.ts    # Server entry (always use main.server.ts)
+├── package.json
+└── tsconfig.json
+\`\`\`
+`;
+
+  return `# CLAUDE.md
+
+This file provides guidance to Claude Code when working with this Alepha project.
+
+## Overview
+
+This is an **Alepha** project - a convention-driven TypeScript framework for type-safe full-stack applications.
+
+**Key Concepts:**
+- **Primitives**: Features defined with \`$\`-prefixed functions (\`$action\`, \`$entity\`, \`$page\`)
+- **Class-Based**: Services are classes, primitives are class properties
+- **Zero-Config**: Code structure IS the configuration
+- **End-to-End Types**: Types flow from database → API → ${react ? "React" : "client"}
+
+## Rules
+
+- Use TypeScript strict mode
+- Use Biome for formatting (\`alepha lint\`)
+- Use Vitest for testing
+- One file = one class
+- Primitives are class properties (except \`$entity\`, \`$atom\`)
+- No decorators, no Express/Fastify patterns
+- No manual instantiation - use dependency injection
+- Use \`protected\` instead of \`private\` for class members
+- Import with file extensions: \`import { User } from "./User.ts"\`
+- Use \`t\` from Alepha for schemas (not Zod)
+- Prefer \`t.text()\` over \`t.string()\` for user input (has default max length, auto-trim, supports lowercase option)
+
+## Project Structure
+${projectStructure}
+## Core Primitives
+
+### API with \`$action\`
+\`\`\`typescript
+import { t } from "alepha";
+import { $action } from "alepha/server";
+
+class UserController {
+  getUser = $action({
+    path: "/users/:id",  // → GET /api/users/:id
+    schema: {
+      params: t.object({ id: t.uuid() }),
+      response: t.object({ id: t.uuid(), email: t.email() }),
+    },
+    handler: async ({ params }) => this.userRepo.findById(params.id),
+  });
+
+  createUser = $action({
+    // POST inferred from body schema
+    schema: {
+      body: t.object({ email: t.email() }),
+      response: userEntity.schema,
+    },
+    handler: async ({ body }) => this.userRepo.create(body),
+  });
+}
+\`\`\`
+
+### Database with \`$entity\` and \`$repository\`
+\`\`\`typescript
+import { $entity, $repository, db } from "alepha/orm";
+
+// Entity defined at module level (for drizzle-kit compatibility)
+export const userEntity = $entity({
+  name: "users",
+  schema: t.object({
+    id: db.primaryKey(),
+    email: t.email(),
+    createdAt: db.createdAt(),
+    updatedAt: db.updatedAt(),
+  }),
+  indexes: [{ column: "email", unique: true }],
+});
+
+class UserService {
+  repo = $repository(userEntity);
+
+  async findById(id: string) {
+    return this.repo.findById(id);
+  }
+}
+\`\`\`
+
+### Dependency Injection
+\`\`\`typescript
+import { $inject } from "alepha";
+
+class OrderService {
+  userService = $inject(UserService);  // Within same module
+
+  async createOrder(userId: string) {
+    const user = await this.userService.findById(userId);
+    // ...
+  }
+}
+
+// Cross-module: use $client instead of $inject
+class AppRouter {
+  api = $client<OrderController>();  // Type-safe HTTP client
+}
+\`\`\`
+
+### Modules with \`$module\`
+\`\`\`typescript
+// src/api/index.ts - Groups all API services
+import { $module } from "alepha";
+
+export const ApiModule = $module({
+  name: "app.api",
+  services: [
+    UserController,
+    OrderController,
+    UserService,
+  ],
+});
+
+// src/web/index.ts - Groups all web services (React only)
+export const WebModule = $module({
+  name: "app.web",
+  services: [AppRouter, Toaster],
+  register(alepha) {
+    // Optional: configure additional services
+    alepha.with(SomeLibrary);
+  },
+});
+\`\`\`
+
+### Environment Variables
+\`\`\`typescript
+import { $env, t } from "alepha";
+
+class AppConfig {
+  env = $env(t.object({
+    DATABASE_URL: t.string(),
+    API_KEY: t.optional(t.string()),
+  }));
+}
+\`\`\`
+${reactSection}
+## Quick Reference
+
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| \`$inject\` | \`alepha\` | Dependency injection |
+| \`$env\` | \`alepha\` | Environment variables |
+| \`$hook\` | \`alepha\` | Lifecycle hooks |
+| \`$logger\` | \`alepha/logger\` | Structured logging |
+| \`$action\` | \`alepha/server\` | REST API endpoints |
+| \`$route\` | \`alepha/server\` | Low-level HTTP routes |
+| \`$entity\` | \`alepha/orm\` | Database tables |
+| \`$repository\` | \`alepha/orm\` | Type-safe data access |
+| \`$queue\` | \`alepha/queue\` | Background jobs |
+| \`$scheduler\` | \`alepha/scheduler\` | Cron tasks |
+| \`$cache\` | \`alepha/cache\` | Cached computations |
+| \`$bucket\` | \`alepha/bucket\` | File storage |
+| \`$issuer\` | \`alepha/security\` | JWT tokens |
+| \`$command\` | \`alepha/command\` | CLI commands |${
+    react
+      ? `
+| \`$page\` | \`@alepha/react/router\` | React pages with SSR |
+| \`$atom\` | \`alepha\` | Global state |`
+      : ""
+  }
+
+## Testing
+
+\`\`\`typescript
+import { describe, it, expect } from "vitest";
+import { Alepha } from "alepha";
+
+describe("UserService", () => {
+  it("should create user", async () => {
+    const alepha = Alepha.create().with(UserService);
+    const service = alepha.inject(UserService);
+
+    const user = await service.create({ email: "test@example.com" });
+    expect(user.email).toBe("test@example.com");
+  });
+
+  it("should mock dependencies", async () => {
+    const alepha = Alepha.create()
+      .with(OrderService)
+      .with({ provide: PaymentGateway, use: MockPaymentGateway });
+
+    const service = alepha.inject(OrderService);
+    // PaymentGateway is now mocked
+  });
+});
+\`\`\`
+
+## Common Mistakes
+
+1. **DON'T use decorators** - Use primitives (\`$action\`, not \`@Get()\`)
+2. **DON'T use Zod** - Use TypeBox via \`t\` from Alepha
+3. **DON'T use Express patterns** - No \`app.get()\`, \`router.use()\`
+4. **DON'T inject across modules** - Use \`$client\` for cross-module calls
+5. **DON'T use async constructors** - Use \`$hook({ on: "start" })\`
+6. **DON'T instantiate manually** - Let DI container manage instances
+
+## After Code Changes
+
+Always run:
+\`\`\`bash
+alepha lint      # Format and lint
+alepha typecheck # Type checking
+alepha test      # Run tests (if applicable)
+alepha build     # Build the project
+\`\`\`
+
+## Documentation
+
+- Full docs: https://alepha.dev/llms.txt
+- Detailed docs: https://alepha.dev/llms-full.txt
+`.trim();
+};

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,10 +1,11 @@
-export const mainBrowserTs = () => `
+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/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/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/tsconfigJson.ts

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

package/src/cli/assets/webAppRouterTs.ts

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

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/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").