luca 3.0.0 → 3.1.0

package/docs/tutorials/04-features-overview.md

@@ -1,196 +0,0 @@
----
-title: Features Overview
-tags: [features, built-in, fs, git, proc, vm, ui, networking, os, diskCache]
----
-
-# Features Overview
-
-Features are the core building blocks in Luca. A feature is a thing that emits events, has observable state, and provides an interface for doing something meaningful. The container comes with many built-in features.
-
-## Using Features
-
-```typescript
-// Auto-enabled features have shortcuts
-container.fs          // File system
-container.git         // Git operations
-container.proc        // Process execution
-container.vm          // JavaScript VM
-container.ui          // Terminal UI
-container.os          // OS info
-container.networking  // Port utilities
-
-// On-demand features are created through the factory
-const cache = container.feature('diskCache', { path: './.cache' })
-const db = container.feature('contentDb', { rootPath: './docs' })
-```
-
-## Built-In Feature Reference
-
-### fs -- File System
-
-Read, write, and navigate the file system:
-
-```typescript
-const fs = container.fs
-
-// Read files (synchronous)
-const content = fs.readFile('./README.md')
-const json = fs.readJson('./package.json')
-
-// Write files (async -- creates parent dirs automatically)
-await fs.writeFile('./output.txt', 'Hello')
-
-// Check existence
-fs.exists('./path/to/file')
-
-// Walk directories -- returns { files: string[], directories: string[] }
-const { files } = fs.walk('./src', { include: ['*.ts'] })
-
-// Find files upward (synchronous)
-const configPath = fs.findUp('tsconfig.json')
-```
-
-### git -- Git Operations
-
-Work with git repositories:
-
-```typescript
-const git = container.git
-
-const branch = git.branch                  // Current branch name (getter)
-const sha = git.sha                        // Current commit SHA (getter)
-const isRepo = git.isRepo                  // Whether cwd is a git repo (getter)
-const root = git.repoRoot                  // Absolute path to repo root (getter)
-const files = await git.lsFiles()          // List tracked files
-const recent = await git.getLatestChanges(5) // Recent commits
-```
-
-### proc -- Process Execution
-
-Run external processes:
-
-```typescript
-const proc = container.proc
-
-// Execute a command synchronously and get output as a string
-const result = proc.exec('ls -la')
-
-// Execute with options
-const output = proc.exec('npm test', {
-  cwd: '/path/to/project',
-  env: { NODE_ENV: 'test' },
-})
-```
-
-### vm -- JavaScript VM
-
-Execute JavaScript in an isolated context:
-
-```typescript
-const vm = container.vm
-
-const result = await vm.run('1 + 2 + 3')  // 6
-
-const greeting = await vm.run('`Hello ${name}!`', { name: 'World' })
-// 'Hello World!'
-
-// The VM has access to the container context by default
-const files = await vm.run('container.fs.walk("./src")')
-```
-
-### ui -- Terminal UI
-
-Colors, prompts, and formatted output:
-
-```typescript
-const ui = container.ui
-
-// Colors
-ui.colors.green('Success!')
-ui.colors.red('Error!')
-ui.colors.yellow('Warning!')
-
-// ASCII art
-console.log(ui.asciiArt('My App', 'Standard'))
-
-// Colorful ASCII banner with gradient
-console.log(ui.banner('My App', { font: 'Star Wars', colors: ['red', 'white', 'blue'] }))
-
-// Render markdown in the terminal
-ui.markdown('# Hello\n\nThis is **bold**')
-```
-
-### networking -- Port Utilities
-
-```typescript
-const net = container.networking
-
-// Find an available port (starting from a preferred port)
-const port = await net.findOpenPort(3000)
-```
-
-### os -- System Info
-
-```typescript
-const os = container.os
-
-os.platform   // 'darwin', 'linux', 'win32'
-os.arch       // 'x64', 'arm64'
-os.cpuCount   // Number of CPU cores
-os.tmpdir     // Temp directory path
-```
-
-### diskCache -- Disk-Based Cache
-
-```typescript
-const cache = container.feature('diskCache', { path: './.cache' })
-
-await cache.set('key', { data: 'value' })
-const data = await cache.get('key')
-await cache.has('key')    // true
-await cache.rm('key')     // remove a cached item
-```
-
-### contentDb -- Markdown as a Database
-
-Turn markdown folders into queryable collections. See the dedicated [ContentBase tutorial](./11-contentbase.md).
-
-### fileManager -- Batch File Operations
-
-```typescript
-const fm = container.feature('fileManager')
-// Batch read, write, copy, move operations
-```
-
-### grep -- Search File Contents
-
-```typescript
-const grep = container.grep
-const results = await grep.search({ pattern: 'TODO', include: '*.ts' })
-// Returns array of { file, line, column, match } objects
-```
-
-### docker -- Docker Operations
-
-```typescript
-const docker = container.feature('docker')
-// Build, run, manage containers
-```
-
-## Discovering Features
-
-Don't memorize this list. You can always discover what's available at runtime:
-
-```typescript
-// List all registered features
-container.features.available
-
-// Get documentation for any feature
-container.features.describe('diskCache')
-
-// Get docs for everything
-container.features.describeAll()
-
-// Structured introspection data for a feature's full API
-container.feature('fs').introspect()
-```

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

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

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

@@ -1,198 +0,0 @@
----
-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 `destroy` for DELETE — it's a reserved word in JS
-export async function destroy(_params: any, ctx: EndpointContext) {
-  const { id } = ctx.params
-  return { message: `User ${id} deleted` }
-}
-```
-
-## 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
-- `destroy` -- DELETE requests (preferred — avoids the `delete` reserved word)
-- `delete` -- DELETE requests (also works via `export { del as delete }`)
-
-Each can have a corresponding schema export: `getSchema`, `postSchema`, `putSchema`, `patchSchema`, `destroySchema` / `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`, `put`, `patch`, `destroy` | At least one | Handler functions (`destroy` maps to DELETE) |
-| `getSchema`, `postSchema`, `destroySchema`, 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()
-}
-```