@soederpop/luca 0.0.2

package/commands/build-scaffolds.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+interface ScaffoldSection {
+	heading: string
+	code: string
+}
+
+interface ScaffoldData {
+	sections: ScaffoldSection[]
+	full: string
+	tutorial: string
+}
+
+/**
+ * Parse a markdown file to extract code blocks grouped by their nearest heading.
+ * Also extracts the "Complete Example" code block as the `full` template.
+ */
+function parseScaffoldMarkdown(content: string): ScaffoldData {
+	const sections: ScaffoldSection[] = []
+	let full = ''
+
+	let currentHeading = ''
+	const lines = content.split('\n')
+	let inCodeBlock = false
+	let codeBlockLang = ''
+	let codeBlockLines: string[] = []
+
+	for (const line of lines) {
+		// Track headings
+		const headingMatch = line.match(/^##\s+(.+)/)
+		if (headingMatch && !inCodeBlock) {
+			currentHeading = headingMatch[1].trim()
+			continue
+		}
+
+		// Track code fences
+		const fenceMatch = line.match(/^```(\w*)/)
+		if (fenceMatch && !inCodeBlock) {
+			inCodeBlock = true
+			codeBlockLang = fenceMatch[1] || ''
+			codeBlockLines = []
+			continue
+		}
+
+		if (line.startsWith('```') && inCodeBlock) {
+			inCodeBlock = false
+			const code = codeBlockLines.join('\n')
+
+			// Only collect ts/js code blocks
+			if (codeBlockLang === 'ts' || codeBlockLang === 'typescript' || codeBlockLang === 'js') {
+				sections.push({ heading: currentHeading, code })
+
+				if (currentHeading === 'Complete Example') {
+					full = code
+				}
+			}
+			continue
+		}
+
+		if (inCodeBlock) {
+			codeBlockLines.push(line)
+		}
+	}
+
+	return { sections, full, tutorial: content }
+}
+
+async function buildScaffolds(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fs = container.feature('fs')
+
+	const scaffoldDir = 'docs/scaffolds'
+	const readmePath = 'docs/mcp/readme.md'
+	const outputPath = 'src/scaffolds/generated.ts'
+
+	const types = ['feature', 'client', 'server', 'command', 'endpoint']
+	const scaffolds: Record<string, ScaffoldData> = {}
+
+	for (const type of types) {
+		const filePath = `${scaffoldDir}/${type}.md`
+		if (!fs.exists(filePath)) {
+			console.log(`   ⏭  ${filePath} (not found, skipping)`)
+			continue
+		}
+
+		const content = fs.readFile(filePath)
+		scaffolds[type] = parseScaffoldMarkdown(content)
+		console.log(`   📄 ${type}: ${scaffolds[type].sections.length} sections, full template: ${scaffolds[type].full ? 'yes' : 'no'}`)
+	}
+
+	// Read the MCP readme
+	let mcpReadme = ''
+	if (fs.exists(readmePath)) {
+		mcpReadme = fs.readFile(readmePath)
+		console.log(`   📄 MCP readme: ${mcpReadme.length} chars`)
+	} else {
+		console.log(`   ⚠️  ${readmePath} not found`)
+	}
+
+	// Generate the output file
+	const escapeForTemplate = (s: string) => s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+	const scaffoldEntries = Object.entries(scaffolds).map(([type, data]) => {
+		const sectionsStr = data.sections.map(s =>
+			`      { heading: ${JSON.stringify(s.heading)}, code: \`${escapeForTemplate(s.code)}\` }`
+		).join(',\n')
+
+		return `  ${type}: {
+    sections: [
+${sectionsStr}
+    ],
+    full: \`${escapeForTemplate(data.full)}\`,
+    tutorial: \`${escapeForTemplate(data.tutorial)}\`,
+  }`
+	}).join(',\n')
+
+	const output = `// Auto-generated scaffold and MCP readme content
+// Generated at: ${new Date().toISOString()}
+// Source: docs/scaffolds/*.md and docs/mcp/readme.md
+//
+// Do not edit manually. Run: luca build-scaffolds
+
+export interface ScaffoldSection {
+  heading: string
+  code: string
+}
+
+export interface ScaffoldData {
+  sections: ScaffoldSection[]
+  full: string
+  tutorial: string
+}
+
+export const scaffolds: Record<string, ScaffoldData> = {
+${scaffoldEntries}
+}
+
+export const mcpReadme = \`${escapeForTemplate(mcpReadme)}\`
+`
+
+	fs.ensureFolder('src/scaffolds')
+	await fs.writeFileAsync(outputPath, output)
+	console.log(`\n✨ Generated ${outputPath}`)
+}
+
+export default {
+	description: 'Generate scaffold templates and MCP readme from docs/scaffolds/*.md',
+	argsSchema,
+	handler: buildScaffolds,
+}

package/commands/generate-api-docs.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+import { AGIContainer } from '../src/agi/container.server.js'
+import { __INTROSPECTION__ } from '../src/introspection/index.js'
+import { presentIntrospectionAsMarkdown } from '../src/helper.js'
+
+export const argsSchema = CommandOptionsSchema.extend({
+  clean: z.boolean().default(false).describe('Remove existing docs/apis folder before generating'),
+})
+
+/** Parse setBuildTimeData shortcut IDs from a generated introspection file */
+function parseGeneratedIds(content: string): { features: string[]; servers: string[]; clients: string[] } {
+  const features: string[] = []
+  const servers: string[] = []
+  const clients: string[] = []
+
+  for (const match of content.matchAll(/setBuildTimeData\('([^']+)'/g)) {
+    const id = match[1]
+    if (id.startsWith('features.')) features.push(id.replace('features.', ''))
+    else if (id.startsWith('servers.')) servers.push(id.replace('servers.', ''))
+    else if (id.startsWith('clients.')) clients.push(id.replace('clients.', ''))
+  }
+
+  return { features, servers, clients }
+}
+
+async function generateApiDocs(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const fs = context.container.feature('fs')
+  const baseDir = 'docs/apis'
+
+  if (options.clean) {
+    try { await fs.rmdir(baseDir) } catch {}
+  }
+
+  // Parse the generated introspection files to determine which helpers belong to which container
+  const nodeContent = fs.readFile('src/introspection/generated.node.ts')
+  const agiContent = fs.readFile('src/introspection/generated.agi.ts')
+  const webContent = fs.readFile('src/introspection/generated.web.ts')
+
+  const nodeIds = parseGeneratedIds(nodeContent)
+  const agiIds = parseGeneratedIds(agiContent)
+  const webIds = parseGeneratedIds(webContent)
+
+  // AGI-only features = features in agi that aren't in node
+  const nodeFeatureSet = new Set(nodeIds.features)
+  const agiOnlyFeatures = agiIds.features.filter(f => !nodeFeatureSet.has(f))
+
+  // Load web build-time data so __INTROSPECTION__ has web entries
+  await import('../src/introspection/generated.web.js')
+
+  // Use AGIContainer for rendering — it has all node+agi registries loaded
+  const agiContainer = new AGIContainer()
+
+  const groups: { dir: string; registryName: string; ids: string[] }[] = [
+    { dir: `${baseDir}/features/node`, registryName: 'features', ids: nodeIds.features },
+    { dir: `${baseDir}/features/agi`, registryName: 'features', ids: agiOnlyFeatures },
+    { dir: `${baseDir}/features/web`, registryName: 'features', ids: webIds.features },
+    { dir: `${baseDir}/servers`, registryName: 'servers', ids: agiIds.servers },
+    // Clients are registered at runtime, not in generated files — use live registry
+    { dir: `${baseDir}/clients`, registryName: 'clients', ids: agiContainer.clients.available },
+  ]
+
+  let totalFiles = 0
+
+  for (const group of groups) {
+    fs.ensureFolder(group.dir)
+    console.log(`\n📁 ${group.dir}`)
+
+    const registry = (agiContainer as any)[group.registryName]
+
+    for (const id of group.ids) {
+      try {
+        let markdown: string | undefined
+
+        if (registry.has(id)) {
+          markdown = registry.describe(id)
+        } else {
+          // Fallback: render from __INTROSPECTION__ map directly (e.g. web-only features)
+          const introspectionKey = `${group.registryName}.${id}`
+          const data = __INTROSPECTION__.get(introspectionKey)
+          if (data) {
+            markdown = presentIntrospectionAsMarkdown(data)
+          }
+        }
+
+        if (!markdown || !markdown.trim()) {
+          console.log(`   ⏭  ${id} (no introspection data)`)
+          continue
+        }
+
+        const fileName = toKebab(id) + '.md'
+        await fs.writeFileAsync(`${group.dir}/${fileName}`, markdown)
+        console.log(`   📄 ${fileName}`)
+        totalFiles++
+      } catch (err: any) {
+        console.log(`   ⚠️  ${id}: ${err.message}`)
+      }
+    }
+  }
+
+  console.log(`\n✨ Generated ${totalFiles} API docs in ${baseDir}/`)
+}
+
+/** Convert camelCase shortcut to kebab-case filename */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+export default {
+  description: 'Generate API reference docs from introspection data for all registries.',
+  argsSchema,
+  handler: generateApiDocs,
+}

package/commands/update-introspection.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+import '../src/introspection/scan.js'
+import { NodeContainer } from '../src/node/container.js'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+const targets = [
+  {
+    name: 'node',
+    src: ['src/node/features', 'src/servers', 'src/container.ts', 'src/node/container.ts'],
+    outputPath: 'src/introspection/generated.node.ts',
+  },
+  {
+    name: 'web',
+    src: ['src/web/features', 'src/container.ts', 'src/web/container.ts'],
+    outputPath: 'src/introspection/generated.web.ts',
+  },
+  {
+    name: 'agi',
+    src: ['src/node/features', 'src/servers', 'src/agi/features', 'src/container.ts', 'src/node/container.ts', 'src/agi/container.server.ts'],
+    outputPath: 'src/introspection/generated.agi.ts',
+  },
+]
+
+/**
+ * Generates per-container introspection metadata files.
+ *
+ * Each container type gets its own generated file containing only the
+ * metadata relevant to that environment:
+ *
+ * - generated.node.ts: node features + servers
+ * - generated.web.ts: web features
+ * - generated.agi.ts: node features + servers + agi features
+ */
+async function updateIntrospection(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const container = new NodeContainer()
+
+  for (const target of targets) {
+    console.log(`\n📦 Generating ${target.name} introspection data...`)
+    console.log(`   📁 Sources: ${target.src.join(', ')}`)
+    console.log(`   📄 Output: ${target.outputPath}`)
+
+    const scanner = container.feature('introspectionScanner', {
+      src: target.src,
+      outputPath: target.outputPath,
+    })
+
+    scanner.on('scanCompleted', (data) => {
+      console.log(`   ✅ Found ${data.results} helpers in ${data.files} files (${data.duration}ms)`)
+    })
+
+    await scanner.scan()
+    await scanner.generateRegistryScript()
+
+    console.log(`   📝 Wrote ${target.outputPath}`)
+  }
+
+  console.log('\n✨ All introspection data generated.')
+}
+
+export default {
+  description: 'Generate per-container introspection metadata files from source.',
+  argsSchema,
+  handler: updateIntrospection,
+}

package/docs/CLI.md

@@ -0,0 +1,335 @@
+# Luca CLI
+
+The `luca` command-line interface provides commands for running scripts, starting servers, inspecting the container, and interacting with AI assistants.
+
+## Usage
+
+```
+luca <command|file> [options]
+```
+
+When given a file path instead of a command name, luca delegates to `run` automatically.
+
+---
+
+## Commands
+
+### help
+
+Show help for luca commands.
+
+```
+luca help [command]
+```
+
+With no arguments, displays the full command list. Pass a command name to see its detailed usage.
+
+---
+
+### run
+
+Run a script or markdown file (.ts, .js, .md).
+
+```
+luca run <file> [options]
+```
+
+Resolves the file by trying the path as-is, then appending `.ts`, `.js`, `.md` in order. Markdown files are executed block-by-block with the container in scope. TypeScript and JavaScript files are run as standalone scripts via `proc.runScript`.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--safe` | boolean | `false` | Require approval before each code block (markdown mode) |
+| `--console` | boolean | `false` | Start an interactive REPL after executing a markdown file, with all accumulated context |
+
+---
+
+### serve
+
+Start the API server with file-based endpoints.
+
+```
+luca serve [options]
+```
+
+Discovers endpoints from `endpoints/` or `src/endpoints/`, serves static files from `public/` or the current directory (if `index.html` exists), and starts an Express server.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--port` | number | `3000` | Port to listen on |
+| `--endpoints-dir` | string | auto | Directory to load endpoints from |
+| `--static-dir` | string | auto | Directory to serve static files from |
+| `--setup` | string | | Path to a TS module whose default export receives the server instance |
+| `--cors` | boolean | `true` | Enable CORS |
+| `--force` | boolean | `false` | Kill any process currently using the target port |
+| `--any-port` | boolean | `false` | Find an available port starting above 3000 |
+| `--open` | boolean | `true` | Open the server URL in Google Chrome |
+
+#### Setup scripts
+
+The `--setup` flag lets you customize the Express server before it starts. The module is loaded through the VM, so `container` and all features are in the global scope. The default export receives the server helper instance.
+
+```ts
+// setup.ts
+export default function (server) {
+  const app = server.app
+
+  app.use('/webhook', (req, res) => {
+    res.json({ ok: true })
+  })
+
+  app.get('/health', (req, res) => {
+    res.json({ status: 'healthy' })
+  })
+}
+```
+
+```
+luca serve --setup setup.ts
+```
+
+---
+
+### eval
+
+Evaluate a JavaScript/TypeScript expression with the container in scope.
+
+```
+luca eval "<code>" [options]
+```
+
+All enabled features are available as top-level variables in the evaluation context.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--json` | boolean | `false` | Serialize output as JSON |
+
+**Examples:**
+
+```
+luca eval "container.features.available"
+luca eval "fs.readdir('src')" --json
+luca eval "networking.isPortOpen(3000)"
+```
+
+---
+
+### console
+
+Start an interactive REPL with all container features in scope.
+
+```
+luca console
+```
+
+All registered features are instantiated and available as top-level variables. If a `luca.console.ts` file exists in the project root, its exports are merged into the REPL scope.
+
+---
+
+### describe
+
+Describe the container, registries, or individual helpers.
+
+```
+luca describe [target...] [options]
+```
+
+Targets can be:
+- Nothing — shows command usage
+- `container` — full container introspection
+- A registry name: `features`, `clients`, `servers`, `commands`, `endpoints`
+- A helper name: `fs`, `express`, `rest`, etc. (fuzzy-matched across registries)
+- A qualified name: `features.fs`, `servers.express`
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--json` | boolean | `false` | Output introspection data as JSON instead of markdown |
+| `--pretty` | boolean | `false` | Render markdown with terminal styling |
+| `--no-title` | boolean | `false` | Omit the title header from output |
+| `--description` | boolean | `false` | Show the description section |
+| `--usage` | boolean | `false` | Show the usage section |
+| `--methods` | boolean | `false` | Show the methods section |
+| `--getters` | boolean | `false` | Show the getters section |
+| `--events` | boolean | `false` | Show the events section |
+| `--state` | boolean | `false` | Show the state section |
+| `--options` | boolean | `false` | Show the options section |
+| `--env-vars` | boolean | `false` | Show the envVars section |
+| `--examples` | boolean | `false` | Show the examples section |
+
+Section flags can be combined. When none are specified, all sections are shown.
+
+**Examples:**
+
+```
+luca describe fs
+luca describe servers
+luca describe features.vm --methods --pretty
+luca describe rest websocket --json
+```
+
+---
+
+### chat
+
+Start an interactive chat session with a local assistant.
+
+```
+luca chat [name] [options]
+```
+
+Discovers assistants from the configured folder (default `assistants/`). If multiple assistants are found and no name is given, prompts for selection.
+
+Conversations are persisted by default using `daily` mode — the same conversation is automatically resumed throughout the day. On exit, a resume instruction is printed so you can return to any session later.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--model` | string | | Override the LLM model for the assistant |
+| `--folder` | string | `assistants` | Directory containing assistant definitions |
+| `--history-mode` | `lifecycle` \| `daily` \| `persistent` \| `session` | `daily` | Conversation persistence mode |
+| `--resume` | string | | Thread ID to resume a specific conversation |
+| `--list` | boolean | `false` | List recent conversations and exit |
+| `--off-record` | boolean | `false` | Alias for `--history-mode lifecycle` (ephemeral, no persistence) |
+
+#### History modes
+
+- **lifecycle** — Ephemeral. No persistence, fresh conversation every time (the pre-existing behavior).
+- **daily** — Auto-resumes today's conversation. New conversation each day. Auto-compacts when nearing context limits. This is the default for `luca chat`.
+- **persistent** — Single long-running thread per assistant+project. Auto-compacts.
+- **session** — Unique thread per invocation, but resumable via `--resume`.
+
+#### Resuming conversations
+
+On exit, non-ephemeral sessions print a resume command:
+
+```
+Session saved. To resume this conversation:
+  luca chat my-assistant --resume my-assistant:a1b2c3d4:2026-03-02
+```
+
+Use `--list` to browse recent conversations:
+
+```
+luca chat my-assistant --list
+```
+
+---
+
+### prompt
+
+Send a prompt file to an assistant, Claude Code, or OpenAI Codex and stream the response.
+
+```
+luca prompt <target> <path/to/prompt.md> [options]
+```
+
+The target can be:
+- `claude` — runs the prompt through the Claude Code CLI
+- `codex` — runs the prompt through the OpenAI Codex CLI
+- Any other name — looks up a local assistant via `assistantsManager`
+
+The prompt file is read as plain text and sent in full. Output streams to stdout as it arrives.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--model` | string | | Override the LLM model (assistant mode only) |
+| `--folder` | string | `assistants` | Directory containing assistant definitions |
+
+**Examples:**
+
+```
+luca prompt claude prompts/refactor.md
+luca prompt codex prompts/add-tests.md
+luca prompt my-assistant prompts/summarize.md --model gpt-4o
+```
+
+---
+
+### mcp
+
+Start an MCP (Model Context Protocol) server.
+
+```
+luca mcp [options]
+```
+
+Starts an MCP server that exposes the project's endpoints and tools to MCP-compatible clients.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--transport` | `stdio` \| `http` | `stdio` | Transport type |
+| `--port` | number | `3001` | Port for HTTP transport |
+| `--name` | string | auto | Server name reported to MCP clients |
+| `--version` | string | auto | Server version reported to MCP clients |
+
+---
+
+### sandbox-mcp
+
+Start an MCP server with a Luca container sandbox for AI agents to explore and test code.
+
+```
+luca sandbox-mcp [options]
+```
+
+Provides tools (`eval`, `inspect_container`, `list_registry`, `describe_helper`, `inspect_helper_instance`), prompts (`discover`, `introspect`), and resources (`luca://container/info`, `luca://features`) for AI agents to interact with the container.
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--transport` | `stdio` \| `http` | `stdio` | Transport type |
+| `--port` | number | `3002` | Port for HTTP transport |
+
+#### Codex CLI stdio timeout workaround
+
+If OpenAI Codex CLI reports `MCP client ... timed out after 10 seconds` for `luca_sandbox` or `contentbase`, and the same command starts fine manually, use a Node stdio bridge to launch Bun.
+
+Create a small bridge script:
+
+```sh
+mkdir -p ~/.codex/bin
+cat > ~/.codex/bin/mcp-stdio-bridge.js <<'EOF'
+#!/usr/bin/env node
+const { spawn } = require('node:child_process')
+
+const [cmd, ...args] = process.argv.slice(2)
+if (!cmd) process.exit(2)
+
+const child = spawn(cmd, args, { stdio: ['pipe', 'pipe', 'pipe'] })
+process.stdin.on('data', (chunk) => child.stdin.write(chunk))
+process.stdin.on('end', () => child.stdin.end())
+process.stdin.on('error', () => child.stdin.end())
+child.stdout.on('data', (chunk) => process.stdout.write(chunk))
+child.stderr.on('data', (chunk) => process.stderr.write(chunk))
+child.on('exit', (code, signal) => {
+  if (signal) process.kill(process.pid, signal)
+  process.exit(code ?? 0)
+})
+EOF
+chmod +x ~/.codex/bin/mcp-stdio-bridge.js
+```
+
+Then wire Codex MCP servers through the bridge:
+
+```toml
+[mcp_servers.luca_sandbox]
+command = "node"
+args = ["/Users/<you>/.codex/bin/mcp-stdio-bridge.js", "/Users/<you>/.bun/bin/bun", "/absolute/path/to/luca/src/cli/cli.ts", "sandbox-mcp", "--transport", "stdio"]
+cwd = "/absolute/path/to/project"
+enabled = true
+startup_timeout_sec = 30
+
+[mcp_servers.contentbase]
+command = "node"
+args = ["/Users/<you>/.codex/bin/mcp-stdio-bridge.js", "/Users/<you>/.bun/bin/bun", "/absolute/path/to/contentbase/src/cli/index.ts", "mcp", "--transport", "stdio"]
+cwd = "/absolute/path/to/project"
+enabled = true
+startup_timeout_sec = 30
+```
+
+Notes:
+- Prefer absolute paths in `args`.
+- Avoid `bun run ...` here; pass the script path directly to Bun.
+
+---
+
+## Project Commands
+
+Any `commands/` folder in a project (or `~/.luca/commands/` globally) extends the CLI. For example, a file `commands/deploy.ts` becomes `luca deploy`. These modules are loaded through the VM and have full container access.