@soederpop/luca 0.0.2

package/docs/tutorials/05-state-and-events.md

@@ -0,0 +1,171 @@
+---
+title: State and Events
+tags: [state, events, observable, reactive, bus, emit, on, once, waitFor]
+---
+
+# State and Events
+
+Every container and helper in Luca has observable state and a typed event bus. These are the core primitives for building reactive applications.
+
+## Observable State
+
+State is a key-value store that notifies observers when values change.
+
+### Basic Usage
+
+```typescript
+// Every helper has state
+const feature = container.feature('myFeature')
+
+feature.state.set('loading', true)
+feature.state.get('loading')      // true
+feature.state.current              // Snapshot: { loading: true, ... }
+feature.state.version              // Number, increments on every change
+```
+
+### Observing Changes
+
+```typescript
+// Watch all state changes
+const dispose = feature.state.observe((changeType, key, value) => {
+  // changeType: 'add' | 'update' | 'delete'
+  console.log(`${key} was ${changeType}d:`, value)
+})
+
+// Later, stop observing
+dispose()
+```
+
+### Container State
+
+The container itself tracks important state:
+
+```typescript
+container.state.get('started')           // boolean
+container.state.get('enabledFeatures')   // string[]
+container.state.get('registries')        // string[]
+```
+
+### State in Custom Features
+
+Define your feature's state shape with a Zod schema:
+
+```typescript
+const TaskStateSchema = FeatureStateSchema.extend({
+  tasks: z.array(z.object({
+    id: z.string(),
+    title: z.string(),
+    done: z.boolean(),
+  })).default([]).describe('List of tasks'),
+  filter: z.enum(['all', 'active', 'done']).default('all').describe('Current filter'),
+})
+
+class TaskManager extends Feature<z.infer<typeof TaskStateSchema>> {
+  static override stateSchema = TaskStateSchema
+
+  addTask(title: string) {
+    const tasks = this.state.get('tasks') || []
+    const task = { id: crypto.randomUUID(), title, done: false }
+    this.state.set('tasks', [...tasks, task])
+    this.emit('taskAdded', task)
+  }
+
+  get activeTasks() {
+    return (this.state.get('tasks') || []).filter(t => !t.done)
+  }
+}
+```
+
+## Event Bus
+
+The event bus enables decoupled communication between components.
+
+### Emitting and Listening
+
+```typescript
+// Listen for an event
+feature.on('taskCompleted', (task) => {
+  console.log(`Task "${task.title}" is done!`)
+})
+
+// Emit an event
+feature.emit('taskCompleted', { id: '1', title: 'Write docs', done: true })
+```
+
+### One-Time Listeners
+
+```typescript
+feature.once('initialized', () => {
+  console.log('Feature is ready (this runs once)')
+})
+```
+
+### Waiting for Events (Promise-Based)
+
+```typescript
+// Block until an event fires
+await feature.waitFor('ready')
+console.log('Feature is now ready')
+
+// Useful for initialization sequences
+const server = container.server('express', { port: 3000 })
+await server.start()
+console.log('Server is accepting connections on port', server.state.get('port'))
+```
+
+### Container Events
+
+The container emits events for lifecycle moments:
+
+```typescript
+container.on('featureEnabled', (featureId, feature) => {
+  console.log(`Feature ${featureId} was enabled`)
+})
+```
+
+## Patterns
+
+### Coordinating Between Features
+
+```typescript
+const auth = container.feature('auth')
+const analytics = container.feature('analytics')
+
+// Analytics reacts to auth events
+auth.on('userLoggedIn', (user) => {
+  analytics.logEvent('login', { userId: user.id })
+})
+
+auth.on('userLoggedOut', (user) => {
+  analytics.logEvent('logout', { userId: user.id })
+})
+```
+
+### State-Driven UI Updates
+
+```typescript
+const cart = container.feature('cart')
+
+cart.state.observe((type, key, value) => {
+  if (key === 'items') {
+    renderCartBadge(value.length)
+  }
+  if (key === 'total') {
+    renderCartTotal(value)
+  }
+})
+```
+
+### Initialization Gates
+
+```typescript
+// Wait for multiple features to be ready
+await Promise.all([
+  container.feature('db').waitFor('connected'),
+  container.feature('cache').waitFor('ready'),
+  container.feature('auth').waitFor('initialized'),
+])
+
+console.log('All systems ready, starting server...')
+await container.server('express', { port: 3000 }).start()
+```

package/docs/tutorials/06-servers.md

@@ -0,0 +1,157 @@
+---
+title: Servers
+tags: [servers, express, websocket, start, stop, middleware, static]
+---
+
+# Servers
+
+Servers are helpers that listen for connections. Luca provides Express and WebSocket servers out of the box.
+
+## Express Server
+
+### Basic Setup
+
+```typescript
+const server = container.server('express', {
+  port: 3000,
+  cors: true,
+})
+
+await server.start()
+console.log('Listening on http://localhost:3000')
+```
+
+### With Endpoints
+
+The most common pattern is file-based endpoints:
+
+```typescript
+const server = container.server('express', { port: 3000, cors: true })
+
+// Auto-discover and mount endpoint files
+await server.useEndpoints('./endpoints')
+
+// Generate OpenAPI spec
+server.serveOpenAPISpec({
+  title: 'My API',
+  version: '1.0.0',
+  description: 'An awesome API built with Luca',
+})
+
+await server.start()
+```
+
+### Static Files
+
+```typescript
+const server = container.server('express', {
+  port: 3000,
+  static: './public',  // Serve files from public/ directory
+})
+```
+
+### Port Auto-Discovery
+
+If the requested port is taken, `configure()` can find an open one:
+
+```typescript
+const server = container.server('express', { port: 3000 })
+await server.configure()  // Finds port 3000 or next available
+await server.start()
+console.log(`Listening on port ${server.state.get('port')}`)
+```
+
+### Server State
+
+```typescript
+// After starting, check server state
+await server.start()
+server.state.get('listening')  // true
+server.state.get('port')       // 3000
+
+// Watch for state changes
+server.state.observe((type, key, value) => {
+  if (key === 'listening' && value) {
+    console.log('Server is now listening')
+  }
+})
+```
+
+### Accessing the Express App
+
+For custom middleware or routes beyond file-based endpoints:
+
+```typescript
+const server = container.server('express', { port: 3000 })
+
+// Access the underlying express app
+const app = server.app
+
+app.use((req, res, next) => {
+  console.log(`${req.method} ${req.url}`)
+  next()
+})
+
+app.get('/custom', (req, res) => {
+  res.json({ message: 'Custom route' })
+})
+
+await server.start()
+```
+
+## WebSocket Server
+
+```typescript
+const ws = container.server('websocket', { port: 8080 })
+
+ws.on('connection', (socket) => {
+  console.log('Client connected')
+
+  socket.on('message', (data) => {
+    console.log('Received:', data)
+    socket.send(JSON.stringify({ echo: data }))
+  })
+})
+
+await ws.start()
+```
+
+## Combining Servers
+
+Run HTTP and WebSocket together:
+
+```typescript
+const http = container.server('express', { port: 3000 })
+const ws = container.server('websocket', { port: 8080 })
+
+await http.useEndpoints('./endpoints')
+
+await Promise.all([
+  http.start(),
+  ws.start(),
+])
+
+console.log('HTTP on :3000, WebSocket on :8080')
+```
+
+## Discovering Servers
+
+```typescript
+container.servers.available    // ['express', 'websocket']
+container.servers.describe('express')
+```
+
+## The `luca serve` Command
+
+For most projects, you don't need to set up the server manually. The built-in `luca serve` command does it for you:
+
+```bash
+luca serve --port 3000
+```
+
+It automatically:
+- Finds your `endpoints/` directory
+- Mounts all endpoint files
+- Serves `public/` as static files
+- Generates the OpenAPI spec
+- Prints all routes

package/docs/tutorials/07-endpoints.md

@@ -0,0 +1,198 @@
+---
+title: Writing Endpoints
+tags: [endpoints, routes, api, express, openapi, rest, http, server]
+---
+
+# Writing Endpoints
+
+Endpoints are file-based HTTP routes. Each file in your `endpoints/` directory becomes an API route. Luca auto-discovers them when you run `luca serve`.
+
+## Basic Endpoint
+
+```typescript
+// endpoints/health.ts
+export const path = '/health'
+export const description = 'Health check endpoint'
+
+export async function get() {
+  return { status: 'ok', uptime: process.uptime() }
+}
+```
+
+That's it. `luca serve` will mount `GET /health` and include it in the auto-generated OpenAPI spec.
+
+## Request Validation with Zod
+
+Define schemas for your handlers. Parameters are validated automatically:
+
+```typescript
+// endpoints/users.ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+
+export const path = '/api/users'
+export const description = 'User management'
+export const tags = ['users']
+
+// GET /api/users?role=admin&limit=10
+export const getSchema = z.object({
+  role: z.string().optional().describe('Filter by role'),
+  limit: z.number().default(50).describe('Max results'),
+})
+
+export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
+  // params.role and params.limit are validated and typed
+  return { users: [], total: 0 }
+}
+
+// POST /api/users
+export const postSchema = z.object({
+  name: z.string().describe('Full name'),
+  email: z.string().email().describe('Email address'),
+  role: z.enum(['user', 'admin']).default('user').describe('User role'),
+})
+
+export async function post(params: z.infer<typeof postSchema>, ctx: EndpointContext) {
+  // params are validated
+  return { user: { id: '1', ...params }, message: 'User created' }
+}
+```
+
+## URL Parameters
+
+Use `:param` in the path or bracket-based file naming:
+
+```typescript
+// endpoints/users/[id].ts
+import { z } from 'zod'
+import type { EndpointContext } from '@soederpop/luca'
+
+export const path = '/api/users/:id'
+export const description = 'Get, update, or delete a specific user'
+export const tags = ['users']
+
+export async function get(_params: any, ctx: EndpointContext) {
+  const { id } = ctx.params  // From the URL
+  return { user: { id, name: 'Example' } }
+}
+
+export const putSchema = z.object({
+  name: z.string().optional(),
+  email: z.string().email().optional(),
+})
+
+export async function put(params: z.infer<typeof putSchema>, ctx: EndpointContext) {
+  const { id } = ctx.params
+  return { user: { id, ...params }, message: 'Updated' }
+}
+
+// Use a named const + re-export for delete (reserved word)
+const del = async (_params: any, ctx: EndpointContext) => {
+  const { id } = ctx.params
+  return { message: `User ${id} deleted` }
+}
+export { del as delete }
+```
+
+## The EndpointContext
+
+Every handler receives `(params, ctx)`. The context gives you access to:
+
+```typescript
+export async function post(params: any, ctx: EndpointContext) {
+  const {
+    container,   // The Luca container -- access any feature from here
+    request,     // Express request object
+    response,    // Express response object
+    query,       // Parsed query string
+    body,        // Parsed request body
+    params: urlParams,  // URL parameters (:id, etc.)
+  } = ctx
+
+  // Use container features
+  const data = container.fs.readJson('./data/config.json')
+
+  return { success: true }
+}
+```
+
+## Supported HTTP Methods
+
+Export any of these handler functions:
+
+- `get` -- GET requests
+- `post` -- POST requests
+- `put` -- PUT requests
+- `patch` -- PATCH requests
+- `delete` -- DELETE requests
+
+Each can have a corresponding schema export: `getSchema`, `postSchema`, `putSchema`, `patchSchema`, `deleteSchema`.
+
+## What Gets Exported
+
+| Export | Required | Description |
+|--------|----------|-------------|
+| `path` | Yes | The route path (e.g. `/api/users`, `/api/users/:id`) |
+| `description` | No | Human-readable description (used in OpenAPI spec) |
+| `tags` | No | Array of tags for OpenAPI grouping |
+| `get`, `post`, etc. | At least one | Handler functions |
+| `getSchema`, `postSchema`, etc. | No | Zod schemas for request validation |
+
+## Starting the Server
+
+```bash
+# Default: looks for endpoints/ or src/endpoints/, serves on port 3000
+luca serve
+
+# Custom port and directories
+luca serve --port 4000 --endpointsDir src/routes --staticDir public
+```
+
+The server automatically:
+- Discovers and mounts all endpoint files
+- Generates an OpenAPI spec at `/openapi.json`
+- Serves static files from `public/` if it exists
+- Enables CORS by default
+- Prints all mounted routes to the console
+
+## Programmatic Server Setup
+
+You can also set up the server in a script:
+
+```typescript
+import container from '@soederpop/luca'
+
+const server = container.server('express', { port: 3000, cors: true })
+
+await server.useEndpoints('./endpoints')
+
+server.serveOpenAPISpec({
+  title: 'My API',
+  version: '1.0.0',
+  description: 'My awesome API',
+})
+
+await server.start()
+console.log('Server running on http://localhost:3000')
+```
+
+## Streaming Responses
+
+For endpoints that need to stream (e.g. AI responses), you can write directly to the response:
+
+```typescript
+export const path = '/api/stream'
+
+export async function post(params: any, ctx: EndpointContext) {
+  const { response } = ctx
+
+  response.setHeader('Content-Type', 'text/event-stream')
+  response.setHeader('Cache-Control', 'no-cache')
+
+  for (const chunk of data) {
+    response.write(`data: ${JSON.stringify(chunk)}\n\n`)
+  }
+
+  response.end()
+}
+```

package/docs/tutorials/08-commands.md

@@ -0,0 +1,171 @@
+---
+title: Writing Commands
+tags: [commands, cli, luca-cli, scripts, args]
+---
+
+# Writing Commands
+
+Commands are CLI actions that the `luca` command discovers and runs. Projects can define their own commands in a `commands/` directory at the project root.
+
+## Basic Command
+
+```typescript
+// commands/seed.ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = 'Seed the database with sample data'
+
+export const argsSchema = z.object({
+  count: z.number().default(10).describe('Number of records to seed'),
+  table: z.string().optional().describe('Specific table to seed'),
+})
+
+export async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  console.log(`Seeding ${options.count} records...`)
+
+  for (let i = 0; i < options.count; i++) {
+    console.log(`  Created record ${i + 1}`)
+  }
+
+  console.log('Done.')
+}
+```
+
+Run it:
+
+```bash
+luca seed --count 20 --table users
+```
+
+## How Discovery Works
+
+When you run `luca <command>`, the CLI:
+
+1. Loads built-in commands (serve, run, etc.)
+2. Looks for a `commands/` directory in your project root
+3. Scans for `.ts` files and registers them as commands
+4. The filename becomes the command name: `commands/seed.ts` -> `luca seed`
+
+## Command File Structure
+
+| Export | Required | Description |
+|--------|----------|-------------|
+| `handler` | Yes | Async function that runs the command |
+| `argsSchema` | No | Zod schema defining accepted arguments |
+| `description` | No | Help text for the command |
+
+## Arguments and the Schema
+
+The `argsSchema` uses Zod to define what flags your command accepts. These are parsed from the command line automatically:
+
+```typescript
+export const argsSchema = z.object({
+  // String flag: --name "John"
+  name: z.string().describe('User name'),
+
+  // Number flag: --port 3000
+  port: z.number().default(3000).describe('Port number'),
+
+  // Boolean flag: --verbose
+  verbose: z.boolean().default(false).describe('Enable verbose logging'),
+
+  // Optional flag: --output file.json
+  output: z.string().optional().describe('Output file path'),
+
+  // Enum flag: --format json
+  format: z.enum(['json', 'csv', 'table']).default('table').describe('Output format'),
+})
+```
+
+## Using the Container in Commands
+
+Commands receive a context with the full container:
+
+```typescript
+export async function handler(options: any, context: ContainerContext) {
+  const { container } = context
+
+  // File system operations
+  const config = container.fs.readJson('./config.json')
+
+  // Git info (these are getters, not methods)
+  const branch = container.git.branch
+  const sha = container.git.sha
+
+  // Terminal UI
+  container.ui.colors.green('Success!')
+
+  // Run external processes (synchronous, returns string)
+  const result = container.proc.exec('ls -la')
+
+  // Use any feature
+  const cache = container.feature('diskCache', { path: './.cache' })
+}
+```
+
+## Examples
+
+### Database Migration Command
+
+```typescript
+// commands/migrate.ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = 'Run database migrations'
+
+export const argsSchema = z.object({
+  direction: z.enum(['up', 'down']).default('up').describe('Migration direction'),
+  steps: z.number().default(1).describe('Number of migrations to run'),
+})
+
+export async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  const { files } = container.fs.walk('./migrations', { include: ['*.sql'] })
+
+  console.log(`Running ${options.steps} migration(s) ${options.direction}...`)
+
+  for (const file of files.slice(0, options.steps)) {
+    console.log(`  Applying: ${file}`)
+    const sql = container.fs.readFile(file)
+    // ... execute sql
+  }
+
+  console.log('Migrations complete.')
+}
+```
+
+### Deploy Command
+
+```typescript
+// commands/deploy.ts
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = 'Deploy the application'
+
+export const argsSchema = z.object({
+  env: z.enum(['staging', 'production']).describe('Target environment'),
+  dryRun: z.boolean().default(false).describe('Preview without deploying'),
+})
+
+export async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+
+  if (options.dryRun) {
+    console.log(`[DRY RUN] Would deploy to ${options.env}`)
+    return
+  }
+
+  const sha = container.git.sha
+  console.log(`Deploying ${sha} to ${options.env}...`)
+
+  container.proc.exec('bun run build')
+  // ... deployment logic
+
+  console.log('Deployed successfully.')
+}
+```