@soederpop/luca 0.0.6 → 0.0.8

package/docs/tutorials/00-bootstrap.md

@@ -0,0 +1,148 @@
+---
+title: "Bootstrap: Learning the Container at Runtime"
+tags:
+  - bootstrap
+  - introspection
+  - repl
+  - agent
+  - discovery
+  - quickstart
+---
+# Bootstrap: Learning the Container at Runtime
+
+You don't need to memorize the Luca API. The container tells you everything it can do — at runtime. This tutorial teaches you the discovery pattern so you can explore any feature, client, server, or command without reading docs.
+
+## Start with `luca eval`
+
+The `eval` command runs JavaScript with the container in scope. All features are available as top-level variables.
+
+```bash
+# What features are available?
+luca eval "container.features.available"
+# => ['fs', 'git', 'proc', 'vm', 'networking', 'os', 'grep', ...]
+
+# What clients?
+luca eval "container.clients.available"
+
+# What servers?
+luca eval "container.servers.available"
+
+# What commands?
+luca eval "container.commands.available"
+```
+
+## Describe Anything
+
+The `luca describe` command generates API docs for any helper. It reads JSDoc, Zod schemas, and method signatures to produce markdown documentation.
+
+```bash
+# Describe the container itself
+luca describe
+
+# Describe a feature
+luca describe fs
+
+# Describe multiple at once
+luca describe git fs proc
+
+# Show only specific sections
+luca describe fs --methods --examples
+
+# Describe all features
+luca describe features
+```
+
+In code, the same works via registries:
+
+```js
+container.features.describe('fs')       // markdown docs for fs
+container.features.describeAll()        // condensed overview of all features
+container.clients.describe('rest')      // docs for the rest client
+```
+
+## The Discovery Pattern
+
+Every registry follows the same shape. Once you know the pattern, you can explore anything:
+
+```js
+// List what's available
+container.features.available
+container.clients.available
+container.servers.available
+container.commands.available
+
+// Get docs for a specific helper
+container.features.describe('fs')
+container.clients.describe('rest')
+container.servers.describe('express')
+
+// Check if something exists
+container.features.has('fs')           // => true
+
+// Get a helper instance
+const fs = container.feature('fs')
+const rest = container.client('rest')
+```
+
+## Instance Introspection
+
+Once you have a helper instance, it can describe itself:
+
+```js
+const fs = container.feature('fs')
+
+// Structured introspection (object with methods, getters, events, state, options)
+fs.introspect()
+
+// Human-readable markdown
+fs.introspectAsText()
+```
+
+The container itself is introspectable:
+
+```js
+container.inspect()          // structured object with all registries, state, events
+container.inspectAsText()    // full markdown overview
+```
+
+## The REPL
+
+For interactive exploration, use `luca console`. It gives you a persistent REPL with the container and all features in scope:
+
+```bash
+luca console
+```
+
+Inside the REPL, you can tab-complete, call methods, and explore interactively. Variables survive across lines.
+
+## Feature Shortcuts
+
+In eval and REPL contexts, core features are available as top-level variables — no need to call `container.feature()`:
+
+```bash
+luca eval "fs.readFile('package.json')"
+luca eval "git.branch"
+luca eval "proc.exec('ls')"
+luca eval "grep.search('.', 'TODO')"
+```
+
+## Quick Reference
+
+| Want to know...                | Ask                                    |
+|--------------------------------|----------------------------------------|
+| What registries exist?         | `container.registries`                 |
+| What features are available?   | `container.features.available`         |
+| Full docs for a feature?       | `container.features.describe('fs')`    |
+| All features at a glance?      | `container.features.describeAll()`     |
+| Structured introspection?      | `feature.introspect()`                 |
+| What state does it have?       | `feature.state.current`               |
+| What events does it emit?      | `feature.introspect().events`          |
+| Full container overview?       | `container.inspectAsText()`            |
+| CLI docs for a helper?         | `luca describe <name>`                 |
+
+## What's Next
+
+- [The Container](./02-container.md) — deep dive into state, events, and lifecycle
+- [Scripts](./03-scripts.md) — run scripts and executable markdown notebooks
+- [Features Overview](./04-features-overview.md) — explore built-in features
+- [Writing Commands](./08-commands.md) — add CLI commands to your project

package/docs/tutorials/07-endpoints.md

@@ -86,12 +86,11 @@ export async function put(params: z.infer<typeof putSchema>, ctx: EndpointContex
   return { user: { id, ...params }, message: 'Updated' }
 }
 
-// Use a named const + re-export for delete (reserved word)
-const del = async (_params: any, ctx: EndpointContext) => {
+// 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` }
 }
-export { del as delete }
 ```
 
 ## The EndpointContext
@@ -124,9 +123,10 @@ Export any of these handler functions:
 - `post` -- POST requests
 - `put` -- PUT requests
 - `patch` -- PATCH requests
-- `delete` -- DELETE 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`, `deleteSchema`.
+Each can have a corresponding schema export: `getSchema`, `postSchema`, `putSchema`, `patchSchema`, `destroySchema` / `deleteSchema`.
 
 ## What Gets Exported
 
@@ -135,8 +135,8 @@ Each can have a corresponding schema export: `getSchema`, `postSchema`, `putSche
 | `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 |
+| `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
 

package/docs/tutorials/08-commands.md

@@ -5,7 +5,7 @@ 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.
+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
 
@@ -21,7 +21,7 @@ export const argsSchema = z.object({
   table: z.string().optional().describe('Specific table to seed'),
 })
 
-export async function handler(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+export default async function seed(options: z.infer<typeof argsSchema>, context: ContainerContext) {
   const { container } = context
 
   console.log(`Seeding ${options.count} records...`)
@@ -44,22 +44,117 @@ luca seed --count 20 --table users
 
 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`
+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`
 
-## Command File Structure
+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.
 
-| 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 |
+The `LUCA_COMMAND_DISCOVERY` env var controls discovery: `"disable"` skips all, `"no-local"` skips project, `"no-home"` skips user commands.
 
-## Arguments and the Schema
+## Command Module Patterns
 
-The `argsSchema` uses Zod to define what flags your command accepts. These are parsed from the command line automatically:
+### 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({
@@ -80,12 +175,37 @@ export const argsSchema = z.object({
 })
 ```
 
-## Using the Container in Commands
+### 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 async function handler(options: any, context: ContainerContext) {
+export default async function handler(options: any, context: ContainerContext) {
   const { container } = context
 
   // File system operations
@@ -106,66 +226,27 @@ export async function handler(options: any, context: ContainerContext) {
 }
 ```
 
-## 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'] })
+## Command Dispatch
 
-  console.log(`Running ${options.steps} migration(s) ${options.direction}...`)
+When the CLI runs a command, it calls `cmd.dispatch()` which:
 
-  for (const file of files.slice(0, options.steps)) {
-    console.log(`  Applying: ${file}`)
-    const sql = container.fs.readFile(file)
-    // ... execute sql
-  }
+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
 
-  console.log('Migrations complete.')
-}
-```
-
-### Deploy Command
+You can also dispatch commands programmatically:
 
 ```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}...`)
+const cmd = container.command('seed')
+await cmd.dispatch({ count: 20, table: 'users' }, 'headless')
+```
 
-  container.proc.exec('bun run build')
-  // ... deployment logic
+## Conventions
 
-  console.log('Deployed successfully.')
-}
-```
+- **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/luca.cli.ts

@@ -0,0 +1,3 @@
+export async function main(container) {
+	container.addContext('luca', container)
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.6",
+  "version": "0.0.8",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",
@@ -48,12 +48,13 @@
     "clean": "rm -rf dist build package",
     "build:web": "bun run scripts/build-web.ts",
     "build:introspection": "bun run src/cli/cli.ts introspect",
-    "compile": "bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
+    "compile": "bun run build:introspection && bun run build:scaffolds && bun run build:bootstrap && bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:scaffolds": "bun run src/cli/cli.ts build-scaffolds",
+    "build:bootstrap": "bun run src/cli/cli.ts build-bootstrap",
     "test": "bun test test/*.test.ts",
-    "update-all-docs": "bun run test && bun run build:introspection && bun run src/cli/cli.ts generate-api-docs && bun run build:scaffolds",
-    "precommit": "bun run update-all-docs && git add docs/apis/ src/introspection/generated.*.ts src/scaffolds/generated.ts && bun compile",
+    "update-all-docs": "bun run test && bun run build:introspection && bun run src/cli/cli.ts generate-api-docs && bun run build:scaffolds && bun run build:bootstrap",
+    "precommit": "bun run update-all-docs && git add docs/apis/ src/introspection/generated.*.ts src/scaffolds/generated.ts src/bootstrap/generated.ts && bun compile",
     "test:integration": "bun test ./test-integration/"
   },
   "devDependencies": {
@@ -101,7 +102,7 @@
     "chokidar": "^3.5.3",
     "cli-markdown": "^3.5.0",
     "compromise": "^14.14.5",
-    "contentbase": "^0.0.5",
+    "contentbase": "^0.1.1",
     "cors": "^2.8.5",
     "detect-port": "^1.5.1",
     "dotenv": "^17.2.4",