@soederpop/luca 0.0.2

package/docs/tutorials/01-getting-started.md

@@ -0,0 +1,106 @@
+---
+title: Getting Started with Luca
+tags: [setup, quickstart, project, init]
+---
+
+# Getting Started with Luca
+
+## Prerequisites
+
+- [Bun](https://bun.sh) installed (Luca's runtime)
+- A new or existing bun project
+
+## Create a New Project
+
+```bash
+mkdir my-app && cd my-app
+bun init -y
+bun add @soederpop/luca 
+```
+
+## Project Structure
+
+A typical Luca project looks like this:
+
+```
+my-app/
+├── package.json
+├── endpoints/          # File-based HTTP routes (auto-discovered by `luca serve`)
+│   ├── health.ts
+│   └── users.ts
+├── commands/           # Project-local CLI commands (auto-discovered by `luca`)
+│   └── seed.ts
+├── assistants/         # AI assistants (file-based convention)
+│   └── my-helper/
+│       ├── CORE.md
+│       ├── tools.ts
+│       ├── hooks.ts
+│       └── docs/
+├── public/             # Static files served by `luca serve`
+│   └── index.html
+└── scripts/            # Standalone scripts that use the container
+    └── migrate.ts
+```
+
+## The Container
+
+Everything in Luca revolves around the **container**. It is a per-process singleton that acts as your dependency injector, event bus, and state machine.
+
+In scripts, you create one directly:
+
+```typescript
+import container from '@soederpop/luca/node'
+
+// Now you have access to all features
+const fs = container.fs           // File system operations
+const git = container.git         // Git utilities (branch, sha, lsFiles, etc.)
+const ui = container.ui           // Terminal UI (colors, prompts, figlet)
+const proc = container.feature('proc')  // Process execution
+```
+
+In endpoints and commands, the container is provided for you via context:
+
+```typescript
+// endpoints/health.ts
+export const path = '/health'
+
+export async function get(_params: any, ctx: EndpointContext) {
+  const { container } = ctx
+  return { status: 'ok', uptime: process.uptime() }
+}
+```
+
+## Running Your Project
+
+### Start the API server
+
+```bash
+luca serve
+# or with options:
+luca serve --port 4000 --endpointsDir src/endpoints
+```
+
+This auto-discovers your `endpoints/` directory, mounts all routes, and generates an OpenAPI spec at `/openapi.json`.
+
+### Run a CLI command
+
+```bash
+luca seed --count 10
+```
+
+This auto-discovers `commands/seed.ts` from your project and runs it.
+
+### Run a script
+
+```bash
+luca run scripts/migrate.ts
+```
+
+## What's Next
+
+- [The Container](./02-container.md) -- deep dive into the container
+- [Scripts and Markdown Notebooks](./03-scripts.md) -- run scripts and executable markdown
+- [Using Features](./04-features-overview.md) -- explore built-in features
+- [Servers](./06-servers.md) -- set up Express and WebSocket servers
+- [Writing Endpoints](./07-endpoints.md) -- build your API routes
+- [Writing Commands](./08-commands.md) -- add CLI commands to your project

package/docs/tutorials/02-container.md

@@ -0,0 +1,210 @@
+---
+title: The Container
+tags: [container, singleton, state, events, registries, dependency-injection]
+---
+
+# The Container
+
+The container is the heart of every Luca application. It is a per-process singleton that provides:
+
+- **Dependency injection** via factory methods and registries
+- **Observable state** that you can watch for changes
+- **Event bus** for decoupled communication
+- **Registries** for discovering available helpers
+
+## Getting the Container
+
+```typescript
+import container from '@soederpop/luca'
+```
+
+The import resolves automatically based on environment -- `@soederpop/luca` gives you a `NodeContainer` on the server and a `WebContainer` in browser builds. You can also be explicit:
+
+```typescript
+import container from '@soederpop/luca/node'  // Always NodeContainer
+import container from '@soederpop/luca/web'   // Always WebContainer
+```
+
+The NodeContainer comes pre-loaded with registries for features, clients, servers, commands, and endpoints. Core features like `fs`, `git`, `proc`, `os`, `networking`, `ui`, and `vm` are auto-enabled.
+
+## Registries
+
+Every helper type has a registry. Registries let you discover what's available and create instances:
+
+```typescript
+// What features are available?
+container.features.available
+// => ['fs', 'git', 'proc', 'vm', 'ui', 'networking', 'os', 'diskCache', 'contentDb', ...]
+
+// Get documentation for a feature
+container.features.describe('fs')
+
+// Get documentation for all features
+container.features.describeAll()
+
+// Check if something is registered
+container.features.has('diskCache')
+
+// Same pattern for all helper types:
+container.servers.available    // ['express', 'websocket']
+container.clients.available    // ['rest', 'graph', 'websocket']
+container.commands.available   // ['serve', 'run', ...]
+```
+
+## Factory Methods
+
+Create helper instances through the container's factory methods:
+
+```typescript
+// Features (cached by id + options hash)
+const fs = container.feature('fs')
+const cache = container.feature('diskCache', { path: './cache' })
+
+// Servers
+const server = container.server('express', { port: 3000, cors: true })
+
+// Clients
+const api = container.client('rest', { baseURL: 'https://api.example.com' })
+```
+
+Factory results are **cached**. Calling `container.feature('fs')` twice returns the same instance. Different options produce different instances.
+
+## Enabled Features (Shortcuts)
+
+Some features are "enabled" on the container, giving them shortcut access:
+
+```typescript
+// These are equivalent:
+container.feature('fs')
+container.fs
+
+// Auto-enabled features:
+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 finding, availability
+```
+
+To enable your own feature:
+
+```typescript
+const myFeature = container.feature('myFeature', { enable: true })
+// Now accessible as container.myFeature
+```
+
+## Observable State
+
+The container (and every helper) has observable state:
+
+```typescript
+// Set state
+container.state.set('ready', true)
+
+// Get state
+container.state.get('ready') // true
+
+// Get a snapshot of all state
+container.state.current
+
+// Observe all changes (changeType is 'add' | 'update' | 'delete')
+container.state.observe((changeType, key, value) => {
+  console.log(`${key} ${changeType}:`, value)
+})
+
+// State has a version counter
+container.state.version // increments on every change
+```
+
+## Event Bus
+
+The container has a built-in event bus for decoupled communication:
+
+```typescript
+// Listen for events
+container.on('featureEnabled', (featureName) => {
+  console.log(`${featureName} was enabled`)
+})
+
+// Emit events
+container.emit('myCustomEvent', { some: 'data' })
+
+// One-time listener
+container.once('ready', () => console.log('Container is ready'))
+
+// Wait for an event (promise-based)
+await container.waitFor('ready')
+```
+
+## Plugins and `.use()`
+
+Extend the container with the `.use()` method:
+
+```typescript
+// Enable a feature by name
+container.use('diskCache')
+
+// Attach a plugin
+container.use(MyPlugin)
+```
+
+A plugin is any class with a static `attach(container)` method:
+
+```typescript
+class MyPlugin {
+  static attach(container) {
+    // Add registries, factories, whatever you need
+    container.myThing = new MyThing(container)
+    return container
+  }
+}
+```
+
+## Utilities
+
+The container provides common utilities so you don't need extra dependencies:
+
+```typescript
+container.utils.uuid()                          // Generate a v4 UUID
+container.utils.hashObject({ foo: 'bar' })      // Deterministic hash
+container.utils.stringUtils.camelCase('my-var')  // 'myVar'
+container.utils.stringUtils.kebabCase('MyVar')   // 'my-var'
+container.utils.stringUtils.pluralize('feature') // 'features'
+
+// Lodash utilities
+const { uniq, groupBy, keyBy, debounce, throttle } = container.utils.lodash
+```
+
+## Path Utilities
+
+```typescript
+container.paths.resolve('relative/path')    // Resolve from cwd
+container.paths.join('a', 'b', 'c')         // Join path segments
+container.paths.relative('/absolute/path')  // Make relative to cwd
+```
+
+## Package Manifest
+
+Access the project's package.json:
+
+```typescript
+container.manifest.name        // "my-app"
+container.manifest.version     // "0.1.0"
+container.manifest.dependencies
+```
+
+## Introspection
+
+Discover everything about the container at runtime:
+
+```typescript
+// Structured introspection data
+const info = container.inspect()
+
+// Human-readable markdown
+const docs = container.inspectAsText()
+```
+
+This is what makes Luca especially powerful for AI agents -- they can discover the entire API surface at runtime without reading documentation.

package/docs/tutorials/03-scripts.md

@@ -0,0 +1,194 @@
+---
+title: Running Scripts and Markdown Notebooks
+tags: [scripts, luca-run, automation, bun, standalone, markdown, codeblocks, notebook]
+---
+
+# Running Scripts and Markdown Notebooks
+
+`luca run` executes TypeScript/JavaScript files and markdown files. This is often the fastest way to try out Luca features, automate tasks, or build runnable documentation.
+
+## Running a TypeScript Script
+
+```bash
+luca run scripts/hello.ts
+```
+
+```typescript
+// scripts/hello.ts
+import container from '@soederpop/luca'
+
+console.log('Available features:', container.features.available)
+console.log('Git branch:', container.git.branch)
+console.log('OS:', container.os.platform, container.os.arch)
+```
+
+The extension is optional -- `luca run scripts/hello` tries `.ts`, `.js`, and `.md` automatically.
+
+## Running Markdown Files
+
+This is one of Luca's most useful features. `luca run` can execute markdown files as runnable notebooks. It walks through the document, renders the prose to the terminal, and executes each `ts` or `js` fenced codeblock in sequence. All blocks share the same VM context, so variables defined in one block are available in the next.
+
+```bash
+luca run docs/tutorial.md
+```
+
+### How It Works
+
+Given a markdown file like this:
+
+````markdown
+# Setup Tutorial
+
+First, let's see what's available (container is provided automatically):
+
+```ts
+console.log(container.features.available)
+```
+
+Now let's use the file system feature:
+
+```ts
+const { files } = container.fs.walk('./src', { include: ['*.ts'] })
+console.log(`Found ${files.length} TypeScript files`)
+```
+
+This block won't run because it's Python:
+
+```python
+print("I'm skipped -- only ts and js blocks run")
+```
+````
+
+When you run `luca run docs/tutorial.md`, it:
+
+1. Renders "# Setup Tutorial" and the prose as formatted markdown in your terminal
+2. Displays the first codeblock, then executes it
+3. Renders the next paragraph
+4. Displays and executes the second codeblock (which can reference `container` from block 1)
+5. Skips the Python block entirely (only `ts` and `js` blocks execute)
+
+### Skipping Blocks
+
+Add `skip` in the code fence meta to prevent a block from running:
+
+````markdown
+```ts skip
+// This block is shown but NOT executed
+dangerousOperation()
+```
+````
+
+### Safe Mode
+
+Use `--safe` to require manual approval before each block runs:
+
+```bash
+luca run docs/tutorial.md --safe
+```
+
+The runner will prompt "Run this block? (y/n)" before executing each codeblock. Great for walkthroughs where you want to pause and observe.
+
+### Shared Context
+
+All codeblocks in a markdown file share a VM context. The context includes `console` and the full container context, so you can use container features without importing:
+
+````markdown
+```ts
+// Block 1: container is already available in the context
+const { files } = container.fs.walk('./src')
+```
+
+```ts
+// Block 2: `files` from block 1 is still in scope
+console.log(`Found ${files.length} files in src/`)
+```
+````
+
+### Use Cases for Markdown Scripts
+
+- **Runnable tutorials** -- documentation that actually executes
+- **Onboarding guides** -- new developers run the guide and see real output
+- **Demo scripts** -- explain and execute in the same document
+- **Literate DevOps** -- annotated operational runbooks
+
+## TypeScript Script Examples
+
+### File Processor
+
+```typescript
+// scripts/process-images.ts
+import container from '@soederpop/luca'
+
+const { fs, proc } = container
+
+const { files: images } = fs.walk('./uploads', { include: ['*.png', '*.jpg'] })
+console.log(`Processing ${images.length} images...`)
+
+for (const image of images) {
+  console.log(`  Optimizing: ${image}`)
+  proc.exec(`optipng ${image}`)
+}
+
+console.log('Done.')
+```
+
+### Data Migration
+
+```typescript
+// scripts/migrate-data.ts
+import container from '@soederpop/luca'
+
+const { fs } = container
+
+const api = container.client('rest', {
+  baseURL: 'https://api.example.com',
+})
+await api.connect()
+
+const oldData = fs.readJson('./data/legacy-users.json')
+console.log(`Migrating ${oldData.length} users...`)
+
+for (const user of oldData) {
+  await api.post('/users', {
+    name: user.full_name,
+    email: user.email_address,
+    role: 'user',
+  })
+  console.log(`  Migrated: ${user.full_name}`)
+}
+
+console.log('Migration complete.')
+```
+
+### Generate Report
+
+```typescript
+// scripts/weekly-report.ts
+import container from '@soederpop/luca'
+
+const { git, fs } = container
+
+const branch = git.branch       // getter, not a method
+const sha = git.sha             // getter, not a method
+const files = await git.lsFiles()
+const { files: srcFiles } = fs.walk('./src', { include: ['*.ts'] })
+
+const report = `# Weekly Report
+
+- Branch: ${branch}
+- Commit: ${sha}
+- Tracked files: ${files.length}
+- Source files: ${srcFiles.length}
+
+Generated: ${new Date().toISOString()}
+`
+
+await fs.writeFile('./reports/weekly.md', report)
+console.log('Report generated: reports/weekly.md')
+```
+
+## Tips
+
+- **Use the container** -- don't import `fs` from Node directly. `container.fs` gives you the same operations with the benefit of working within the container ecosystem.
+- **Markdown scripts are great for prototyping** -- write a markdown file, mix explanation with code, run it, iterate.
+- **Use `--safe` for unfamiliar scripts** -- review each block before it runs.

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

@@ -0,0 +1,196 @@
+---
+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()
+```