luca 2.0.0 → 3.0.0

package/docs/tutorials/14-type-system.md

@@ -0,0 +1,174 @@
+---
+title: Type System and Module Augmentation
+tags: [types, typescript, zod, module-augmentation, schemas, type-safety]
+---
+
+# Type System and Module Augmentation
+
+Luca's type system ensures that as you add features, clients, servers, and commands, the container's factory methods stay fully typed. This is powered by Zod schemas and TypeScript module augmentation.
+
+## The Pattern
+
+When you register a new helper, you augment the corresponding interface so TypeScript knows about it:
+
+```typescript
+import { Feature, features, FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
+import { z } from 'zod'
+
+// 1. Define your feature
+export class MyCache extends Feature<MyCacheState, MyCacheOptions> {
+  // ...
+}
+
+// 2. Register it
+features.register('myCache', MyCache)
+
+// 3. Augment the interface
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    myCache: typeof MyCache
+  }
+}
+
+// 4. Now fully typed everywhere:
+const cache = container.feature('myCache', { ttl: 3600 })
+//    ^-- TypeScript knows this is MyCache
+//                                  ^-- autocomplete for MyCache options
+```
+
+## Zod Schemas = Types + Runtime Validation
+
+Every schema you define gives you both compile-time types and runtime validation:
+
+```typescript
+// Define once with Zod
+export const UserOptionsSchema = FeatureOptionsSchema.extend({
+  apiKey: z.string().describe('API key for authentication'),
+  timeout: z.number().default(5000).describe('Request timeout in ms'),
+  retries: z.number().default(3).describe('Max retry attempts'),
+})
+
+// Extract the type
+export type UserOptions = z.infer<typeof UserOptionsSchema>
+
+// Use for static typing
+export class UserService extends Feature<UserState, UserOptions> {
+  static override optionsSchema = UserOptionsSchema
+
+  connect() {
+    // this.options is typed: { apiKey: string, timeout: number, retries: number }
+    const { apiKey, timeout } = this.options
+  }
+}
+```
+
+The schema also powers:
+- **Runtime validation** when options are passed to the factory
+- **Introspection** -- `.describe()` text appears in `helper.introspect()`
+- **Documentation** -- field descriptions appear in `container.features.describe('userService')`
+
+## State Typing
+
+```typescript
+const TaskStateSchema = FeatureStateSchema.extend({
+  tasks: z.array(z.object({
+    id: z.string(),
+    title: z.string(),
+    done: z.boolean(),
+  })).default([]),
+  filter: z.enum(['all', 'active', 'done']).default('all'),
+})
+
+type TaskState = z.infer<typeof TaskStateSchema>
+
+class TaskManager extends Feature<TaskState> {
+  static override stateSchema = TaskStateSchema
+
+  addTask(title: string) {
+    const tasks = this.state.get('tasks')
+    //    ^-- typed as Array<{ id: string, title: string, done: boolean }>
+
+    this.state.set('tasks', [...(tasks || []), { id: '1', title, done: false }])
+    //                       ^-- TypeScript validates the shape
+  }
+}
+```
+
+## Module Augmentation for All Helper Types
+
+The pattern is the same for features, clients, servers, and commands:
+
+```typescript
+// Features
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    myFeature: typeof MyFeature
+  }
+}
+
+// Clients
+declare module '@soederpop/luca' {
+  interface AvailableClients {
+    myClient: typeof MyClient
+  }
+}
+
+// Servers
+declare module '@soederpop/luca' {
+  interface AvailableServers {
+    myServer: typeof MyServer
+  }
+}
+
+// Commands
+declare module '@soederpop/luca' {
+  interface AvailableCommands {
+    myCommand: typeof MyCommand
+  }
+}
+```
+
+## Using .describe() Effectively
+
+```typescript
+const ConfigSchema = z.object({
+  host: z.string().describe('Database hostname or IP address'),
+  port: z.number().default(5432).describe('Database port'),
+  database: z.string().describe('Database name to connect to'),
+  ssl: z.boolean().default(false).describe('Whether to use SSL/TLS for the connection'),
+  pool: z.object({
+    min: z.number().default(2).describe('Minimum connections to keep open'),
+    max: z.number().default(10).describe('Maximum connections allowed'),
+  }).describe('Connection pool configuration'),
+})
+```
+
+These descriptions are not just for humans reading the code -- they show up in:
+- `container.features.describe('db')` output
+- `container.features.introspect('db')` data
+- OpenAPI specs when used in endpoint schemas
+- AI agent tool descriptions
+
+## The Full Typed Flow
+
+```typescript
+// 1. You define a feature with schemas
+export class Analytics extends Feature<AnalyticsState, AnalyticsOptions> { ... }
+
+// 2. You register + augment
+features.register('analytics', Analytics)
+declare module '@soederpop/luca' {
+  interface AvailableFeatures { analytics: typeof Analytics }
+}
+
+// 3. Now every interaction is typed:
+const a = container.feature('analytics', { trackingId: 'UA-123' })
+//    ^-- Analytics instance     ^-- autocomplete: 'analytics'
+//                                         ^-- type error if wrong options
+
+a.state.get('pageViews')  // typed by AnalyticsState
+a.on('pageView', ...)     // typed by event definitions
+a.track('click', { ... }) // typed by Analytics methods
+```
+
+This is the core principle: **never break the type system.** Every step of `container.feature('name', options)` should give you autocomplete, type checking, and documentation.

package/docs/tutorials/15-project-patterns.md

@@ -0,0 +1,222 @@
+---
+title: Project Patterns and Recipes
+tags: [patterns, recipes, examples, architecture, full-stack, best-practices]
+---
+
+# Project Patterns and Recipes
+
+Common patterns for building applications with Luca.
+
+## Pattern: REST API with File-Based Routing
+
+The most common Luca project -- a JSON API with automatic OpenAPI docs.
+
+```
+my-api/
+├── package.json
+├── endpoints/
+│   ├── health.ts
+│   ├── users.ts
+│   └── users/[id].ts
+├── commands/
+│   └── seed.ts
+└── public/
+    └── index.html
+```
+
+```json
+// package.json
+{
+  "name": "my-api",
+  "scripts": {
+    "dev": "luca serve",
+    "seed": "luca seed"
+  },
+  "dependencies": {
+    "@soederpop/luca": "latest",
+    "zod": "^3.24.0"
+  }
+}
+```
+
+Start with `bun run dev`. OpenAPI spec auto-generated at `/openapi.json`.
+
+## Pattern: CLI Tool
+
+A project that's primarily a set of CLI commands.
+
+```
+my-tool/
+├── package.json
+├── commands/
+│   ├── init.ts
+│   ├── build.ts
+│   ├── deploy.ts
+│   └── status.ts
+└── lib/
+    └── helpers.ts
+```
+
+```bash
+luca init --template react
+luca build --minify
+luca deploy --env production
+luca status
+```
+
+## Pattern: AI-Powered App
+
+An API with an AI assistant behind it.
+
+```
+ai-app/
+├── package.json
+├── endpoints/
+│   ├── health.ts
+│   ├── ask.ts           # Proxies to the assistant
+│   └── conversations.ts # List/manage conversations
+├── assistants/
+│   └── helper/
+│       ├── CORE.md
+│       ├── tools.ts
+│       ├── hooks.ts
+│       └── docs/
+│           ├── product-info.md
+│           ├── faq.md
+│           └── policies.md
+└── public/
+    └── index.html       # Chat UI
+```
+
+The endpoint creates the assistant and forwards questions:
+
+```typescript
+// endpoints/ask.ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+
+export const path = '/api/ask'
+export const postSchema = z.object({
+  question: z.string(),
+  conversationId: z.string().optional(),
+})
+
+export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+  const assistant = ctx.container.feature('assistant', {
+    folder: 'assistants/helper',
+    model: 'gpt-4o',
+  })
+
+  const answer = await assistant.ask(params.question)
+  return { answer }
+}
+```
+
+## Pattern: Content-Driven Site
+
+Using contentbase to power a documentation site or blog.
+
+```
+docs-site/
+├── package.json
+├── content/
+│   ├── guides/
+│   │   ├── getting-started.md
+│   │   ├── configuration.md
+│   │   └── deployment.md
+│   └── reference/
+│       ├── api.md
+│       └── cli.md
+├── endpoints/
+│   ├── docs.ts          # Query and serve content
+│   └── search.ts        # Full-text search over content
+└── public/
+    └── index.html
+```
+
+```typescript
+// endpoints/docs.ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+
+export const path = '/api/docs'
+export const getSchema = z.object({
+  section: z.string().optional(),
+})
+
+export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+  const db = ctx.container.feature('contentDb', { rootPath: './content' })
+  await db.load()
+  // ... query and return content
+}
+```
+
+## Pattern: Automation Script Suite
+
+A collection of scripts for DevOps or data tasks.
+
+```
+automation/
+├── package.json
+├── scripts/
+│   ├── backup-db.ts
+│   ├── sync-data.ts
+│   ├── generate-report.ts
+│   └── cleanup-old-files.ts
+└── config.json
+```
+
+```bash
+luca run scripts/backup-db.ts
+luca run scripts/sync-data.ts --since 2024-01-01
+luca run scripts/generate-report.ts --format pdf
+```
+
+## Pattern: Feature Composition
+
+Build complex features by composing simpler ones:
+
+```typescript
+class NotificationService extends Feature<NotifState, NotifOptions> {
+  private cache: any
+  private api: any
+
+  async initialize() {
+    // Compose other features
+    this.cache = this.container.feature('diskCache', { path: './.notif-cache' })
+    this.api = this.container.client('rest', {
+      baseURL: this.options.webhookUrl,
+    })
+    await this.api.connect()
+  }
+
+  async send(channel: string, message: string) {
+    // Check rate limiting via cache
+    const key = `ratelimit:${channel}`
+    if (await this.cache.has(key)) {
+      this.emit('rateLimited', { channel })
+      return
+    }
+
+    // Send via API client
+    await this.api.post('/send', { channel, message })
+    await this.cache.set(key, true, { ttl: 60 })
+
+    this.emit('sent', { channel, message })
+  }
+}
+```
+
+## Best Practices
+
+1. **Use file-based conventions** -- endpoints in `endpoints/`, commands in `commands/`, assistants in `assistants/`. This is the Luca way.
+
+2. **Let the container own your dependencies** -- instead of importing libraries directly, use features and clients. This gives you introspection, state management, and events for free.
+
+3. **Keep endpoints thin** -- endpoints should validate input and delegate to features. Business logic belongs in features, not route handlers.
+
+4. **Compose features** -- build complex behavior by combining simpler features. Each feature should do one thing well.
+
+5. **Use Zod everywhere** -- for endpoint schemas, feature options, state definitions. It gives you types, validation, and documentation in one place.
+
+6. **Document with JSDoc** -- Luca's introspection system extracts it. Your documentation IS your code.