luca 3.0.0 → 3.0.2

package/docs/tutorials/08-commands.md

@@ -1,252 +0,0 @@
----
-title: Writing Commands
-tags: [commands, cli, luca-cli, scripts, args]
----
-
-# Writing Commands
-
-Commands are CLI actions that the `luca` command discovers and runs. They are Helper subclasses under the hood — the framework grafts your module exports into a proper Command class at runtime, so you get the full Helper lifecycle (state, events, introspection) without ceremony.
-
-## 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 default async function seed(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, eval, describe, etc.)
-2. Loads `luca.cli.ts` if present (for project-level container customization)
-3. Discovers project commands via the `helpers` feature — scans `commands/` for `.ts` files
-4. Discovers user commands from `~/.luca/commands/`
-5. The filename becomes the command name: `commands/seed.ts` → `luca seed`
-
-Discovery routes through the `helpers` feature (`container.feature('helpers')`), which handles native import vs VM loading and deduplicates concurrent discovery calls. Commands loaded through the VM get `container` injected as a global.
-
-The `LUCA_COMMAND_DISCOVERY` env var controls discovery: `"disable"` skips all, `"no-local"` skips project, `"no-home"` skips user commands.
-
-## Command Module Patterns
-
-### Pattern 1: Default Export Function (recommended for project commands)
-
-The simplest pattern — export a default async function. The function becomes the command's `run` method.
-
-```typescript
-// commands/greet.ts
-import { z } from 'zod'
-import type { ContainerContext } from '@soederpop/luca'
-
-export const description = 'Greet someone'
-export const argsSchema = z.object({
-  name: z.string().default('world').describe('Who to greet'),
-})
-
-export default async function greet(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  console.log(`Hello, ${options.name}!`)
-}
-```
-
-### Pattern 2: Object Default Export with handler
-
-Useful when you want to co-locate all exports in one object:
-
-```typescript
-// commands/deploy.ts
-import { z } from 'zod'
-import type { ContainerContext } from '@soederpop/luca'
-
-export const argsSchema = z.object({
-  env: z.enum(['staging', 'production']).describe('Target environment'),
-  dryRun: z.boolean().default(false).describe('Preview without deploying'),
-})
-
-async function deploy(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  const { container } = context
-  if (options.dryRun) {
-    console.log(`[DRY RUN] Would deploy to ${options.env}`)
-    return
-  }
-  console.log(`Deploying ${container.git.sha} to ${options.env}...`)
-}
-
-export default {
-  description: 'Deploy the application',
-  argsSchema,
-  handler: deploy,
-}
-```
-
-### Pattern 3: registerHandler (used by built-in commands)
-
-Built-in commands use `commands.registerHandler()` for explicit registration. This is the pattern used in `src/commands/`:
-
-```typescript
-// src/commands/my-builtin.ts
-import { z } from 'zod'
-import { commands } from '../command'
-import { CommandOptionsSchema } from '../schemas/base'
-import type { ContainerContext } from '../container'
-
-declare module '../command.js' {
-  interface AvailableCommands {
-    'my-builtin': ReturnType<typeof commands.registerHandler>
-  }
-}
-
-export const argsSchema = CommandOptionsSchema.extend({
-  verbose: z.boolean().default(false).describe('Enable verbose output'),
-})
-
-export default async function myBuiltin(options: z.infer<typeof argsSchema>, context: ContainerContext) {
-  // implementation
-}
-
-commands.registerHandler('my-builtin', {
-  description: 'A built-in command',
-  argsSchema,
-  handler: myBuiltin,
-})
-```
-
-Project commands generally don't need `registerHandler` — discovery handles registration automatically.
-
-## Module Exports Reference
-
-| Export | Type | Description |
-|--------|------|-------------|
-| `default` | function or object | Async function becomes `run`, or object with `{ description, argsSchema, handler }` |
-| `description` | string | Help text shown in `luca --help` |
-| `argsSchema` | Zod schema | Defines accepted flags, parsed from CLI args automatically |
-| `positionals` | string[] | Names for positional arguments (mapped from `container.argv._`) |
-| `run` | function | Named export alternative to default function — grafted as the command's run method |
-| `handler` | function | Legacy alternative to `run` — receives parsed args via `parseArgs()` |
-
-When discovery loads your module, `graftModule()` synthesizes a Command subclass from these exports. The `run` or `handler` function becomes the command's implementation, schemas become static properties, and any other exported functions become methods on the command instance.
-
-## Arguments and Schemas
-
-The `argsSchema` uses Zod to define what flags your command accepts. These are parsed from the CLI 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'),
-})
-```
-
-### Positional Arguments
-
-Export a `positionals` array to map CLI positional args into named fields on `options`. Each entry names the corresponding positional — `positionals[0]` maps `_[1]` (the first arg after the command name), `positionals[1]` maps `_[2]`, etc.
-
-```typescript
-export const positionals = ['target', 'destination']
-
-export const argsSchema = z.object({
-  target: z.string().describe('Source path to operate on'),
-  destination: z.string().optional().describe('Where to write output'),
-})
-
-// luca my-command ./src ./out
-// => options.target === './src', options.destination === './out'
-```
-
-Positional mapping only applies when dispatched from the CLI. For programmatic dispatch (`cmd.dispatch({ target: './src' }, 'headless')`), args are already named.
-
-The raw positional array is still available as `options._` if you need it — `_[0]` is always the command name:
-
-```typescript
-// luca greet Alice Bob
-// options._ => ['greet', 'Alice', 'Bob']
-```
-
-## Using the Container
-
-Commands receive a context with the full container:
-
-```typescript
-export default 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' })
-}
-```
-
-## Command Dispatch
-
-When the CLI runs a command, it calls `cmd.dispatch()` which:
-
-1. Reads raw input from `container.argv` (or explicit args if called programmatically)
-2. Validates args against `argsSchema` if present
-3. Maps positional args if `positionals` is declared
-4. Intercepts `--help` to show auto-generated help text
-5. Calls `run(parsedOptions, context)` with the validated, typed options
-
-You can also dispatch commands programmatically:
-
-```typescript
-const cmd = container.command('seed')
-await cmd.dispatch({ count: 20, table: 'users' }, 'headless')
-```
-
-## Conventions
-
-- **File location**: `commands/<name>.ts` in the project root. Auto-discovered by the CLI.
-- **Naming**: kebab-case filenames. `commands/build-site.ts` → `luca build-site`.
-- **Use the container**: Never import `fs`, `path`, `child_process` directly. Use `container.feature('fs')`, `container.paths`, `container.feature('proc')`.
-- **Exit codes**: Return nothing for success. Throw for errors — the CLI catches and reports them.
-- **Help text**: Use `.describe()` on every schema field — it powers `luca <command> --help`.

package/docs/tutorials/09-clients.md

@@ -1,162 +0,0 @@
----
-title: Using Clients
-tags: [clients, rest, graphql, websocket, http, api, axios]
----
-
-# Using Clients
-
-Clients connect your application to external services. Luca provides built-in clients for REST APIs, GraphQL, and WebSocket connections.
-
-## REST Client
-
-The REST client wraps axios with Luca's helper patterns (state, events, introspection):
-
-```typescript
-const api = container.client('rest', {
-  baseURL: 'https://api.example.com',
-  headers: {
-    Authorization: 'Bearer my-token',
-  },
-})
-
-await api.connect()
-
-// Standard HTTP methods
-const users = await api.get('/users')
-const user = await api.get('/users/123')
-const created = await api.post('/users', { name: 'Alice', email: 'alice@example.com' })
-const updated = await api.put('/users/123', { name: 'Alice Updated' })
-await api.delete('/users/123')
-```
-
-### REST Client Events
-
-```typescript
-api.on('failure', (error) => {
-  console.error('Request failed:', error.message)
-})
-
-// State changes track connection status
-api.state.observe((type, key, value) => {
-  if (key === 'connected') {
-    console.log(`Client connected: ${value}`)
-  }
-})
-```
-
-## GraphQL Client
-
-For GraphQL APIs, use the REST client's `post()` method to send queries and mutations:
-
-```typescript
-const graph = container.client('rest', {
-  baseURL: 'https://api.example.com/graphql',
-  headers: { Authorization: 'Bearer my-token' },
-})
-
-await graph.connect()
-
-// Send a query
-const result = await graph.post('/', {
-  query: `
-    query GetUser($id: ID!) {
-      user(id: $id) {
-        name
-        email
-        posts { title }
-      }
-    }
-  `,
-  variables: { id: '123' },
-})
-
-// Send a mutation
-const mutationResult = await graph.post('/', {
-  query: `
-    mutation CreatePost($input: PostInput!) {
-      createPost(input: $input) {
-        id
-        title
-      }
-    }
-  `,
-  variables: { input: { title: 'Hello World', body: '...' } },
-})
-```
-
-## WebSocket Client
-
-The WebSocket client wraps a raw `WebSocket` connection:
-
-```typescript
-const ws = container.client('websocket', {
-  baseURL: 'wss://realtime.example.com',
-})
-
-await ws.connect()
-
-// Access the underlying WebSocket via ws.ws
-ws.ws.onmessage = (event) => {
-  console.log('Received:', event.data)
-}
-
-ws.ws.send(JSON.stringify({ type: 'subscribe', channel: 'updates' }))
-
-// Clean up
-ws.ws.close()
-```
-
-## Discovering Clients
-
-```typescript
-container.clients.available   // ['rest', 'graph', 'websocket']
-container.clients.describe('rest')
-```
-
-## Using Clients in Endpoints
-
-```typescript
-// endpoints/proxy.ts
-import { z } from 'zod'
-import type { EndpointContext } from '@soederpop/luca'
-
-export const path = '/api/external-data'
-
-export const getSchema = z.object({
-  query: z.string().describe('Search query'),
-})
-
-export async function get(params: z.infer<typeof getSchema>, ctx: EndpointContext) {
-  const api = ctx.container.client('rest', {
-    baseURL: 'https://external-api.com',
-  })
-
-  await api.connect()
-  const data = await api.get(`/search?q=${encodeURIComponent(params.query)}`)
-
-  return { results: data }
-}
-```
-
-## Using Clients in Features
-
-```typescript
-class WeatherService extends Feature<WeatherState, WeatherOptions> {
-  private api: any
-
-  async initialize() {
-    this.api = this.container.client('rest', {
-      baseURL: 'https://api.weather.com',
-      headers: { 'X-API-Key': this.options.apiKey },
-    })
-    await this.api.connect()
-  }
-
-  async getForecast(city: string) {
-    const data = await this.api.get(`/forecast/${encodeURIComponent(city)}`)
-    this.state.set('lastForecast', data)
-    this.emit('forecastFetched', data)
-    return data
-  }
-}
-```

package/docs/tutorials/10-creating-features.md

@@ -1,203 +0,0 @@
----
-title: Creating Custom Features
-tags: [features, custom, extend, zod, state, events, module-augmentation, helper]
----
-
-# Creating Custom Features
-
-You can create your own features to encapsulate domain logic, then register them so they're available through `container.feature('yourFeature')` with full type safety.
-
-## Anatomy of a Feature
-
-A feature has:
-- **State** -- observable, defined by a Zod schema
-- **Options** -- configuration passed at creation, defined by a Zod schema
-- **Events** -- typed event bus
-- **Methods** -- your domain logic
-- **Access to the container** -- via `this.container`
-
-## Basic Example
-
-```typescript
-import { z } from 'zod'
-import { Feature, features, FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
-
-// Define state schema by extending the base FeatureStateSchema
-export const CounterStateSchema = FeatureStateSchema.extend({
-  count: z.number().describe('Current count value'),
-  lastUpdated: z.string().optional().describe('ISO timestamp of last update'),
-})
-export type CounterState = z.infer<typeof CounterStateSchema>
-
-// Define options schema by extending the base FeatureOptionsSchema
-export const CounterOptionsSchema = FeatureOptionsSchema.extend({
-  initialCount: z.number().default(0).describe('Starting count value'),
-  step: z.number().default(1).describe('Increment step size'),
-})
-export type CounterOptions = z.infer<typeof CounterOptionsSchema>
-
-/**
- * A simple counter feature that demonstrates the feature pattern.
- * Tracks a count value with observable state and events.
- */
-export class Counter extends Feature<CounterState, CounterOptions> {
-  static override stateSchema = CounterStateSchema
-  static override optionsSchema = CounterOptionsSchema
-
-  /** Called when the feature is created */
-  async initialize() {
-    this.state.set('count', this.options.initialCount ?? 0)
-  }
-
-  /** Increment the counter by the configured step */
-  increment() {
-    const current = this.state.get('count') || 0
-    const next = current + (this.options.step ?? 1)
-    this.state.set('count', next)
-    this.state.set('lastUpdated', new Date().toISOString())
-    this.emit('incremented', next)
-    return next
-  }
-
-  /** Decrement the counter by the configured step */
-  decrement() {
-    const current = this.state.get('count') || 0
-    const next = current - (this.options.step ?? 1)
-    this.state.set('count', next)
-    this.state.set('lastUpdated', new Date().toISOString())
-    this.emit('decremented', next)
-    return next
-  }
-
-  /** Reset the counter to its initial value */
-  reset() {
-    this.state.set('count', this.options.initialCount ?? 0)
-    this.emit('reset')
-  }
-
-  /** Get the current count */
-  get value(): number {
-    return this.state.get('count') || 0
-  }
-}
-
-// Register the feature
-features.register('counter', Counter)
-
-// Module augmentation for type safety
-declare module '@soederpop/luca' {
-  interface AvailableFeatures {
-    counter: typeof Counter
-  }
-}
-```
-
-## Using Your Feature
-
-```typescript
-import './features/counter' // Side-effect import to register
-
-const counter = container.feature('counter', { initialCount: 10, step: 5 })
-
-counter.on('incremented', (value) => {
-  console.log(`Count is now ${value}`)
-})
-
-counter.increment()  // 15
-counter.increment()  // 20
-counter.value        // 20
-counter.reset()      // Back to 10
-
-// Observe state changes
-counter.state.observe((type, key, value) => {
-  console.log(`${key} ${type}d:`, value)
-})
-```
-
-## Enabling on the Container
-
-If your feature should be a container-level singleton with a shortcut:
-
-```typescript
-export class Counter extends Feature<CounterState, CounterOptions> {
-  // This creates the container.counter shortcut when enabled
-  static override shortcut = 'features.counter' as const
-  // ...
-}
-
-// Enable it
-container.feature('counter', { enable: true })
-
-// Now accessible as:
-container.counter.increment()
-```
-
-## Feature with Container Access
-
-Features can access other features and the full container:
-
-```typescript
-export class Analytics extends Feature<AnalyticsState, AnalyticsOptions> {
-  /** Log an event, writing to disk cache for persistence */
-  async logEvent(name: string, data: Record<string, any>) {
-    const cache = this.container.feature('diskCache', { path: './.analytics' })
-    const timestamp = new Date().toISOString()
-
-    await cache.set(`event:${timestamp}`, { name, data, timestamp })
-
-    this.state.set('totalEvents', (this.state.get('totalEvents') || 0) + 1)
-    this.emit('eventLogged', { name, data })
-  }
-
-  /** Get recent events from the cache */
-  async recentEvents(limit = 10) {
-    const fs = this.container.fs
-    // ... read from cache directory
-  }
-}
-```
-
-## Documenting Your Feature
-
-Document your classes, methods, and getters with JSDoc. This is important because Luca's introspection system extracts these docs and makes them available at runtime:
-
-```typescript
-/**
- * Manages user sessions with automatic expiration and renewal.
- * Sessions are persisted to disk and can survive process restarts.
- */
-export class SessionManager extends Feature<SessionState, SessionOptions> {
-  /**
-   * Create a new session for the given user.
-   * Returns a session token that can be used for authentication.
-   */
-  async createSession(userId: string): Promise<string> {
-    // ...
-  }
-
-  /** The number of currently active sessions */
-  get activeCount(): number {
-    return this.state.get('sessions')?.length || 0
-  }
-}
-```
-
-Then anyone (human or AI) can discover your feature:
-
-```typescript
-container.features.describe('sessionManager')
-// Returns the full markdown documentation extracted from your JSDoc
-
-// Quick discovery — list available methods and getters
-const session = container.feature('sessionManager')
-session.$methods  // => ['createSession', ...]
-session.$getters  // => ['activeCount', ...]
-```
-
-## Best Practices
-
-1. **Use Zod `.describe()` on schema fields** -- these descriptions appear in introspection and help documentation
-2. **Emit events for significant actions** -- enables reactive patterns and decoupled observers
-3. **Use state for observable values** -- don't hide important state in private variables if consumers need to watch it
-4. **Access the container, not imports** -- prefer `this.container.feature('fs')` over importing fs directly, so the feature works in any container
-5. **Document everything** -- JSDoc on the class, methods, and getters feeds the introspection system