@soederpop/luca 0.0.2

package/docs/tutorials/09-clients.md

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

@@ -0,0 +1,198 @@
+---
+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
+```
+
+## 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

package/docs/tutorials/11-contentbase.md

@@ -0,0 +1,191 @@
+---
+title: Contentbase - Markdown as a Database
+tags: [contentbase, contentdb, markdown, database, models, query, collections]
+---
+
+# Contentbase - Markdown as a Database
+
+Contentbase lets you treat folders of markdown files as queryable database collections. Define models with Zod schemas, extract structured data from frontmatter and content, and query it with a fluent API.
+
+## Setup
+
+```typescript
+import container from '@soederpop/luca'
+
+const db = container.feature('contentDb', { rootPath: './content' })
+const { defineModel, section, hasMany, belongsTo } = db.library
+```
+
+## Directory Structure
+
+```
+content/
+├── posts/
+│   ├── hello-world.md
+│   ├── getting-started.md
+│   └── advanced-tips.md
+├── authors/
+│   ├── alice.md
+│   └── bob.md
+└── tags/
+    ├── javascript.md
+    └── typescript.md
+```
+
+## Defining Models
+
+Models map to subdirectories and define the shape of your content:
+
+```typescript
+import { z } from 'zod'
+
+const Post = defineModel('Post', {
+  // Maps to content/posts/
+  prefix: 'posts',
+
+  // Frontmatter schema
+  meta: z.object({
+    title: z.string(),
+    date: z.string(),
+    status: z.enum(['draft', 'published', 'archived']),
+    author: z.string().optional(),
+    tags: z.array(z.string()).default([]),
+  }),
+
+  // Extract structured data from the markdown body
+  sections: {
+    summary: section('Summary', {
+      extract: (query) => query.select('paragraph')?.toString() || '',
+      schema: z.string(),
+    }),
+    codeExamples: section('Code Examples', {
+      extract: (query) => query.selectAll('code').map((n: any) => n.toString()),
+      schema: z.array(z.string()),
+    }),
+  },
+
+  // Relationships
+  relationships: {
+    author: belongsTo(() => Author, { key: 'meta.author' }),
+    tags: hasMany(() => Tag, { heading: 'Tags' }),
+  },
+})
+
+const Author = defineModel('Author', {
+  prefix: 'authors',
+  meta: z.object({
+    name: z.string(),
+    email: z.string().email(),
+    role: z.enum(['writer', 'editor', 'admin']),
+  }),
+  relationships: {
+    posts: hasMany(() => Post, { foreignKey: 'meta.author' }),
+  },
+})
+```
+
+## Registering and Loading
+
+```typescript
+db.register(Post)
+db.register(Author)
+await db.load()  // Parses all markdown files and builds the queryable index
+```
+
+## Querying
+
+Contentbase provides a fluent query API:
+
+```typescript
+// Fetch all posts
+const allPosts = await db.query(Post).fetchAll()
+
+// Filter by frontmatter fields
+const published = await db.query(Post)
+  .where('meta.status', 'published')
+  .fetchAll()
+
+// Multiple filters
+const recentPosts = await db.query(Post)
+  .where('meta.status', 'published')
+  .where('meta.tags', 'includes', 'javascript')
+  .fetchAll()
+
+// Get a single document by slug (filename without .md)
+const post = await db.query(Post).find('hello-world')
+```
+
+## Markdown File Format
+
+Each markdown file has YAML frontmatter and a body:
+
+```markdown
+---
+title: Hello World
+date: 2024-01-15
+status: published
+author: alice
+tags: [javascript, tutorial]
+---
+
+# Hello World
+
+This is the post content.
+
+## Summary
+
+A brief introduction to our blog.
+
+## Code Examples
+
+\`\`\`javascript
+console.log('Hello!')
+\`\`\`
+```
+
+## Use Cases
+
+- **Documentation sites** -- query and render docs with frontmatter metadata
+- **Blog engines** -- posts with authors, tags, categories
+- **Knowledge bases** -- structured content with relationships
+- **Project management** -- epics, stories, tasks as markdown with status tracking
+- **Configuration** -- human-readable config files that are also queryable
+
+## Full Example: Blog Engine
+
+```typescript
+import container from '@soederpop/luca'
+import { z } from 'zod'
+
+const db = container.feature('contentDb', { rootPath: './blog' })
+const { defineModel, section, hasMany } = db.library
+
+const Post = defineModel('Post', {
+  prefix: 'posts',
+  meta: z.object({
+    title: z.string(),
+    date: z.string(),
+    status: z.enum(['draft', 'published']),
+    tags: z.array(z.string()).default([]),
+  }),
+  sections: {
+    excerpt: section('Excerpt', {
+      extract: (q) => q.select('paragraph')?.toString() || '',
+      schema: z.string(),
+    }),
+  },
+})
+
+db.register(Post)
+await db.load()
+
+// Get published posts for the homepage
+const posts = await db.query(Post)
+  .where('meta.status', 'published')
+  .fetchAll()
+
+for (const post of posts) {
+  console.log(`${post.meta.title} (${post.meta.date})`)
+  console.log(`  ${post.sections.excerpt}`)
+}
+```