alepha 0.16.1 → 0.16.2

package/AGENTS.md

@@ -0,0 +1,245 @@
+# Alepha Framework
+
+Convention-driven TypeScript framework for type-safe full-stack applications.
+
+## Philosophy
+
+- **Primitives**: `$`-prefixed functions (`$action`, `$entity`, `$page`)
+- **Class-Based**: Services are classes, primitives are class properties
+- **Zero-Config**: Code structure IS configuration
+- **End-to-End Types**: Database → API → React
+
+## Rules
+
+- Use `t` from Alepha for schemas (not Zod)
+- Use `protected` instead of `private` for class members
+- Import with file extensions: `import { User } from "./User.ts"`
+- Primitives are class properties (except `$entity`, `$atom`)
+- No decorators, no Express/Fastify patterns
+- No manual instantiation - use dependency injection
+
+## Project Structure
+
+```
+src/
+├── api/                # Backend
+│   ├── controllers/    # $action endpoints
+│   ├── services/       # Business logic
+│   ├── entities/       # $entity definitions
+│   └── index.ts        # $module
+├── web/                # Frontend (React)
+│   ├── components/     # React components
+│   ├── atoms/          # $atom state
+│   ├── AppRouter.ts    # $page routes
+│   └── index.ts        # $module
+├── main.server.ts      # Server entry
+├── main.browser.ts     # Browser entry
+└── main.css            # Styles
+```
+
+## Primitives Reference
+
+### Core (`alepha`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$inject` | Dependency injection |
+| `$env` | Environment variables |
+| `$hook` | Lifecycle hooks (on: "start", "stop") |
+| `$atom` | Global state (module-level) |
+| `$module` | Module definition |
+| `$context` | Request-scoped context |
+
+### Server (`alepha/server`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$action` | REST API endpoints (auto GET/POST) |
+| `$route` | Low-level HTTP routes |
+| `$client` | Type-safe HTTP client for cross-module |
+
+### Database (`alepha/orm`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$entity` | Database table definition |
+| `$repository` | Type-safe CRUD operations |
+| `$sequence` | Auto-increment sequences |
+
+### Infrastructure
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| `$logger` | `alepha/logger` | Structured logging |
+| `$queue` | `alepha/queue` | Background jobs |
+| `$scheduler` | `alepha/scheduler` | Cron tasks |
+| `$cache` | `alepha/cache` | Cached computations |
+| `$bucket` | `alepha/bucket` | File storage |
+| `$email` | `alepha/email` | Email sending |
+| `$sms` | `alepha/sms` | SMS sending |
+| `$lock` | `alepha/lock` | Distributed locks |
+| `$retry` | `alepha/retry` | Retry with backoff |
+
+### Security (`alepha/security`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$issuer` | JWT token generation/validation |
+| `$permission` | Permission definitions |
+| `$role` | Role-based access |
+| `$basicAuth` | HTTP Basic Auth |
+| `$serviceAccount` | Service-to-service auth |
+
+### React (`alepha/react/router`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$page` | Pages with SSR, loaders, code-splitting |
+| `$head` | Document head management |
+| `$dictionary` | i18n translations |
+
+### Other
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| `$command` | `alepha/command` | CLI commands |
+| `$channel` | `alepha/websocket` | WebSocket channels |
+| `$swagger` | `alepha/server` | OpenAPI docs |
+| `$proxy` | `alepha/server` | HTTP proxy |
+| `$tool` | `alepha/mcp` | MCP tool definition |
+| `$prompt` | `alepha/mcp` | MCP prompt definition |
+| `$resource` | `alepha/mcp` | MCP resource definition |
+
+## React Hooks
+
+```typescript
+import { useAlepha, useClient, useStore, useAction, useInject } from "alepha/react";
+import { useRouter, useActive, useQueryParams } from "alepha/react/router";
+import { useForm, useFormState } from "alepha/react/form";
+import { useAuth } from "alepha/react/auth";
+import { useHead } from "alepha/react/head";
+import { useI18n } from "alepha/react/i18n";
+```
+
+| Hook | Purpose |
+|------|---------|
+| `useClient<T>()` | Type-safe API calls |
+| `useStore(atom)` | Global state `[value, setValue]` |
+| `useAction({ handler })` | Async ops with loading/error |
+| `useRouter<T>()` | Type-safe navigation |
+| `useActive(path)` | Check if route is active |
+| `useForm({ schema, handler })` | Forms with validation |
+| `useAuth()` | Authentication state |
+| `useInject(Service)` | Access DI container |
+
+## Examples
+
+### API Endpoint
+```typescript
+import { t } from "alepha";
+import { $action } from "alepha/server";
+
+class UserController {
+  getUser = $action({
+    path: "/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),
+  });
+}
+```
+
+### Entity & Repository
+```typescript
+import { t } from "alepha";
+import { $entity, $repository, db } from "alepha/orm";
+
+export const userEntity = $entity({
+  name: "users",
+  schema: t.object({
+    id: db.primaryKey(),
+    email: t.email(),
+    createdAt: db.createdAt(),
+  }),
+});
+
+class UserService {
+  users = $repository(userEntity);
+}
+```
+
+### Page with Loader
+```tsx
+import { t } from "alepha";
+import { $page } from "alepha/react/router";
+import { $client } from "alepha/server/links";
+
+class AppRouter {
+  api = $client<UserController>();
+
+  userDetail = $page({
+    path: "/users/:id",
+    schema: { params: t.object({ id: t.uuid() }) },
+    loader: async ({ params }) => ({
+      user: await this.api.getUser({ params })
+    }),
+    component: ({ user }) => <div>{user.email}</div>,
+  });
+}
+```
+
+### Form
+```tsx
+import { t } from "alepha";
+import { useForm } from "alepha/react/form";
+
+function LoginForm() {
+  const form = useForm({
+    schema: t.object({
+      email: t.email(),
+      password: t.text(),
+    }),
+    handler: async (values) => {
+      await api.login(values);
+    },
+  });
+
+  return (
+    <form {...form.props}>
+      <input {...form.input.email.props} />
+      <input {...form.input.password.props} />
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+## Schema Types (`t`)
+
+```typescript
+import { t } from "alepha";
+
+t.string()              // Basic string
+t.text()                // String with maxLength, trim, lowercase options
+t.email()               // Email validation
+t.uuid()                // UUID validation
+t.number()              // Number
+t.integer()             // Integer
+t.boolean()             // Boolean
+t.date()                // Date
+t.array(t.string())     // Array
+t.object({ ... })       // Object
+t.optional(t.string())  // Optional
+t.nullable(t.string())  // Nullable
+t.enum(["a", "b"])      // Enum
+t.literal("value")      // Literal
+t.union([...])          // Union
+```
+
+## Common Mistakes
+
+1. Using decorators → Use primitives (`$action`, not `@Get()`)
+2. Using Zod → Use `t` from Alepha
+3. Using Express patterns → No `app.get()`, `router.use()`
+4. Using `$inject` across modules → Use `$client` instead
+5. Using async constructors → Use `$hook({ on: "start" })`
+6. Manual instantiation → Let DI container manage
+
+## Source Code
+
+Read implementation at `src/` directory. Check `.spec.ts` files for usage examples.

package/CLAUDE.md

@@ -0,0 +1,245 @@
+# Alepha Framework
+
+Convention-driven TypeScript framework for type-safe full-stack applications.
+
+## Philosophy
+
+- **Primitives**: `$`-prefixed functions (`$action`, `$entity`, `$page`)
+- **Class-Based**: Services are classes, primitives are class properties
+- **Zero-Config**: Code structure IS configuration
+- **End-to-End Types**: Database → API → React
+
+## Rules
+
+- Use `t` from Alepha for schemas (not Zod)
+- Use `protected` instead of `private` for class members
+- Import with file extensions: `import { User } from "./User.ts"`
+- Primitives are class properties (except `$entity`, `$atom`)
+- No decorators, no Express/Fastify patterns
+- No manual instantiation - use dependency injection
+
+## Project Structure
+
+```
+src/
+├── api/                # Backend
+│   ├── controllers/    # $action endpoints
+│   ├── services/       # Business logic
+│   ├── entities/       # $entity definitions
+│   └── index.ts        # $module
+├── web/                # Frontend (React)
+│   ├── components/     # React components
+│   ├── atoms/          # $atom state
+│   ├── AppRouter.ts    # $page routes
+│   └── index.ts        # $module
+├── main.server.ts      # Server entry
+├── main.browser.ts     # Browser entry
+└── main.css            # Styles
+```
+
+## Primitives Reference
+
+### Core (`alepha`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$inject` | Dependency injection |
+| `$env` | Environment variables |
+| `$hook` | Lifecycle hooks (on: "start", "stop") |
+| `$atom` | Global state (module-level) |
+| `$module` | Module definition |
+| `$context` | Request-scoped context |
+
+### Server (`alepha/server`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$action` | REST API endpoints (auto GET/POST) |
+| `$route` | Low-level HTTP routes |
+| `$client` | Type-safe HTTP client for cross-module |
+
+### Database (`alepha/orm`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$entity` | Database table definition |
+| `$repository` | Type-safe CRUD operations |
+| `$sequence` | Auto-increment sequences |
+
+### Infrastructure
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| `$logger` | `alepha/logger` | Structured logging |
+| `$queue` | `alepha/queue` | Background jobs |
+| `$scheduler` | `alepha/scheduler` | Cron tasks |
+| `$cache` | `alepha/cache` | Cached computations |
+| `$bucket` | `alepha/bucket` | File storage |
+| `$email` | `alepha/email` | Email sending |
+| `$sms` | `alepha/sms` | SMS sending |
+| `$lock` | `alepha/lock` | Distributed locks |
+| `$retry` | `alepha/retry` | Retry with backoff |
+
+### Security (`alepha/security`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$issuer` | JWT token generation/validation |
+| `$permission` | Permission definitions |
+| `$role` | Role-based access |
+| `$basicAuth` | HTTP Basic Auth |
+| `$serviceAccount` | Service-to-service auth |
+
+### React (`alepha/react/router`)
+| Primitive | Purpose |
+|-----------|---------|
+| `$page` | Pages with SSR, loaders, code-splitting |
+| `$head` | Document head management |
+| `$dictionary` | i18n translations |
+
+### Other
+| Primitive | Import | Purpose |
+|-----------|--------|---------|
+| `$command` | `alepha/command` | CLI commands |
+| `$channel` | `alepha/websocket` | WebSocket channels |
+| `$swagger` | `alepha/server` | OpenAPI docs |
+| `$proxy` | `alepha/server` | HTTP proxy |
+| `$tool` | `alepha/mcp` | MCP tool definition |
+| `$prompt` | `alepha/mcp` | MCP prompt definition |
+| `$resource` | `alepha/mcp` | MCP resource definition |
+
+## React Hooks
+
+```typescript
+import { useAlepha, useClient, useStore, useAction, useInject } from "alepha/react";
+import { useRouter, useActive, useQueryParams } from "alepha/react/router";
+import { useForm, useFormState } from "alepha/react/form";
+import { useAuth } from "alepha/react/auth";
+import { useHead } from "alepha/react/head";
+import { useI18n } from "alepha/react/i18n";
+```
+
+| Hook | Purpose |
+|------|---------|
+| `useClient<T>()` | Type-safe API calls |
+| `useStore(atom)` | Global state `[value, setValue]` |
+| `useAction({ handler })` | Async ops with loading/error |
+| `useRouter<T>()` | Type-safe navigation |
+| `useActive(path)` | Check if route is active |
+| `useForm({ schema, handler })` | Forms with validation |
+| `useAuth()` | Authentication state |
+| `useInject(Service)` | Access DI container |
+
+## Examples
+
+### API Endpoint
+```typescript
+import { t } from "alepha";
+import { $action } from "alepha/server";
+
+class UserController {
+  getUser = $action({
+    path: "/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),
+  });
+}
+```
+
+### Entity & Repository
+```typescript
+import { t } from "alepha";
+import { $entity, $repository, db } from "alepha/orm";
+
+export const userEntity = $entity({
+  name: "users",
+  schema: t.object({
+    id: db.primaryKey(),
+    email: t.email(),
+    createdAt: db.createdAt(),
+  }),
+});
+
+class UserService {
+  users = $repository(userEntity);
+}
+```
+
+### Page with Loader
+```tsx
+import { t } from "alepha";
+import { $page } from "alepha/react/router";
+import { $client } from "alepha/server/links";
+
+class AppRouter {
+  api = $client<UserController>();
+
+  userDetail = $page({
+    path: "/users/:id",
+    schema: { params: t.object({ id: t.uuid() }) },
+    loader: async ({ params }) => ({
+      user: await this.api.getUser({ params })
+    }),
+    component: ({ user }) => <div>{user.email}</div>,
+  });
+}
+```
+
+### Form
+```tsx
+import { t } from "alepha";
+import { useForm } from "alepha/react/form";
+
+function LoginForm() {
+  const form = useForm({
+    schema: t.object({
+      email: t.email(),
+      password: t.text(),
+    }),
+    handler: async (values) => {
+      await api.login(values);
+    },
+  });
+
+  return (
+    <form {...form.props}>
+      <input {...form.input.email.props} />
+      <input {...form.input.password.props} />
+      <button type="submit">Login</button>
+    </form>
+  );
+}
+```
+
+## Schema Types (`t`)
+
+```typescript
+import { t } from "alepha";
+
+t.string()              // Basic string
+t.text()                // String with maxLength, trim, lowercase options
+t.email()               // Email validation
+t.uuid()                // UUID validation
+t.number()              // Number
+t.integer()             // Integer
+t.boolean()             // Boolean
+t.date()                // Date
+t.array(t.string())     // Array
+t.object({ ... })       // Object
+t.optional(t.string())  // Optional
+t.nullable(t.string())  // Nullable
+t.enum(["a", "b"])      // Enum
+t.literal("value")      // Literal
+t.union([...])          // Union
+```
+
+## Common Mistakes
+
+1. Using decorators → Use primitives (`$action`, not `@Get()`)
+2. Using Zod → Use `t` from Alepha
+3. Using Express patterns → No `app.get()`, `router.use()`
+4. Using `$inject` across modules → Use `$client` instead
+5. Using async constructors → Use `$hook({ on: "start" })`
+6. Manual instantiation → Let DI container manage
+
+## Source Code
+
+Read implementation at `src/` directory. Check `.spec.ts` files for usage examples.

package/README.md

@@ -9,33 +9,36 @@
 />
 Alepha
 </h1>
-<p>TypeScript Framework Made Easy</p>
+<p>The AI-Native Application Engine</p>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/v/alepha.svg" alt="npm version"/></a>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/l/alepha.svg" alt="license"/></a>
 <a href="https://codecov.io/gh/feunard/alepha"><img src="https://codecov.io/gh/feunard/alepha/graph/badge.svg?token=ZDLWI514CP" alt="coverage"/></a>
 <a href="https://www.npmjs.com/package/alepha"><img src="https://img.shields.io/npm/dt/alepha.svg" alt="downloads"/></a>
 </div>
 
-## What is this?
+> [!WARNING]
+> This project is in active development and may not be suitable for production use. Please report any issues or bugs on [GitHub](https://github.com/feunard/alepha/issues).
 
-Enterprise-grade TypeScript framework for building full-stack applications with end-to-end type safety and minimal boilerplate.
+## What is Alepha?
 
-- **Multi-runtime** — Same code runs on Node, Bun, Workerd, Browser, and Expo
-- **One schema, everywhere** — Define once, get database, validation, TypeScript types, and React forms
+Full-stack TypeScript engine for agentic era. Define your schema once — get database, API, types, and forms.
+
+- **One schema, everywhere** — Database, API validation, TypeScript types, React forms — all from one definition
 - **Full autocomplete** — Client calls server with complete type safety, zero codegen
-- **Substitutable** — Swap any service with `.with()` for testing or customization
+- **Multi-runtime** — Same code runs on Node, Bun, and Cloudflare Workers
 - **Deploy anywhere** — Cloudflare, Vercel, Docker, bare metal
-- **AI friendly** — Built-in [llms.txt](https://alepha.dev/llms.txt) for LLM context
 
-Pick your layer. Each one builds on the previous.
+Built on predictable conventions and typed primitives — works great with AI coding assistants (BYOA).
+
+Each layer builds on the previous.
 
-| Layer | Description | Primitives |
-|-------|-------------|------------|
-| **L0** | Foundation: DI, lifecycle, config | `$inject`, `$client`, `$env`, `$module`, `$hook`, `$logger` |
-| **L1** | Backend: database, queues, storage | `$entity`, `$action`, `$queue`, `$bucket`, `$permission` |
-| **L2** | React frontend with SSR, routing, i18n | `$page`, `$head`, `$atom`, `$dictionary` |
-| **L3** | SaaS features: users, jobs, audits | `$realm`, `$job`, `$audit`, `$notification` |
-| **L4** | Admin panel & auth UI included | `$uiAdmin`, `$uiAuth` |
+| Layer | Description | Primitives                                              |
+|-------|-------------|---------------------------------------------------------|
+| **Foundation** | DI, lifecycle, config | `$inject`, `$env`, `$module`, `$hook`, `$logger`        |
+| **Backend** | Database, queues, storage, API | `$entity`, `$action`, `$queue`, `$bucket`, `$scheduler` |
+| **Frontend** | React with SSR, routing, i18n | `$page`, `$head`, `$atom`, `$dictionary`                |
+| **Platform** | Users, auth, jobs, audits | `$realm`, `$job`, `$audit`, `$notification`             |
+| **Admin** | Admin panel & auth UI | `$uiAdmin`, `$uiAuth`                                   |
 
 ## Example
 
@@ -92,26 +95,12 @@ Requirements: [Node.js](https://nodejs.org/) 22+ or [Bun](https://bun.sh/) 1.3+
 
 ```bash
 npx alepha init my-app --api         # L1: Backend only
-npx alepha init my-app --react       # L2: + React frontend
-npx alepha init my-app --admin       # L4: Full SaaS starter
-npx alepha init my-app --admin --ai  # L4: + AI assistant context
+                       --react       # L2: + React frontend
+                       --admin       # L3: + Admin UI
 
 cd my-app && npm run dev
 ```
 
-## CLI
-
-```bash
-alepha dev          # Dev server with HMR
-alepha lint         # Format & lint code
-alepha typecheck    # TypeScript check
-alepha test         # Run tests
-alepha build        # Production build
-alepha db generate  # Generate migrations
-alepha db migrate   # Apply migrations
-alepha db studio    # Visual database browser
-```
-
 ## Learn More
 
 - [Documentation](https://alepha.dev)