luca 3.0.0 → 3.1.0

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

@@ -1,174 +0,0 @@
----
-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

@@ -1,222 +0,0 @@
----
-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.