luca 2.0.0 → 3.0.2

package/src/commands/bootstrap.ts

@@ -0,0 +1,244 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { NodeContainer } from '../node/container.js'
+import { bootstrapFiles, bootstrapTemplates, bootstrapExamples, bootstrapTutorials } from '../bootstrap/generated.js'
+import { generateScaffold } from '../scaffolds/template.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		bootstrap: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	output: z.string().default('.').describe('Output folder path (defaults to cwd)'),
+	'update-skill': z.boolean().default(false).describe('Only update .claude/skills/luca-framework in the current project'),
+})
+
+async function bootstrap(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as unknown as NodeContainer
+	const args = container.argv._ as string[]
+	const fs = container.feature('fs')
+	const ui = container.feature('ui')
+	const proc = container.feature('proc')
+
+	// ── --update-skill: refresh skill files in the current project ──
+	if (options['update-skill']) {
+		return await updateSkill(container, fs, ui)
+	}
+
+	// Require an explicit target — don't silently bootstrap into cwd
+	let target = args[1] || (options.output !== '.' ? options.output : '')
+
+	if (!target) {
+		const answer = await ui.askQuestion('Project name (folder to create):')
+		target = answer?.question?.trim()
+		if (!target) {
+			ui.print.red('\n  No project name given, aborting.\n')
+			return
+		}
+	}
+
+	const outputDir = container.paths.resolve(target)
+	await fs.ensureFolder(outputDir)
+	const mkPath = (...segments: string[]) => container.paths.resolve(outputDir, ...segments)
+
+	ui.print.cyan('\n  luca bootstrap\n')
+
+	// ── Check for AI coding tools ──────────────────────────────────
+	await checkToolAvailability(ui, proc)
+
+	// ── 1. .env (only if missing) ──────────────────────────────────
+	const envPath = mkPath('.env')
+	if (!fs.exists(envPath)) {
+		await writeFile(fs, ui, envPath, '', '.env')
+	} else {
+		ui.print.dim('  .env already exists, skipping')
+	}
+
+	// ── 2. CLAUDE.md ───────────────────────────────────────────────
+	await writeFile(fs, ui, mkPath('CLAUDE.md'), bootstrapFiles['CLAUDE'] || '', 'CLAUDE.md')
+
+	// ── 3. .claude/skills/luca-framework/ ──────────────────────────
+	const skillDir = mkPath('.claude', 'skills', 'luca-framework')
+	await fs.ensureFolder(skillDir)
+	await writeFile(fs, ui, container.paths.resolve(skillDir, 'SKILL.md'), bootstrapFiles['SKILL'] || '', '.claude/skills/luca-framework/SKILL.md')
+
+	// ── 3b. examples and tutorials ─────────────────────────────────
+	const examplesDir = container.paths.resolve(skillDir, 'references', 'examples')
+	await fs.ensureFolder(examplesDir)
+	for (const [filename, content] of Object.entries(bootstrapExamples)) {
+		await fs.writeFileAsync(container.paths.resolve(examplesDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapExamples).length} example docs...`)
+
+	const tutorialsDir = container.paths.resolve(skillDir, 'references', 'tutorials')
+	await fs.ensureFolder(tutorialsDir)
+	for (const [filename, content] of Object.entries(bootstrapTutorials)) {
+		await fs.writeFileAsync(container.paths.resolve(tutorialsDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapTutorials).length} tutorial docs...`)
+
+	// ── 4. docs/ folder ────────────────────────────────────────────
+	await fs.ensureFolder(mkPath('docs'))
+	await writeFile(fs, ui, mkPath('docs', 'models.ts'), bootstrapTemplates['docs-models'] || '', 'docs/models.ts')
+	await writeFile(fs, ui, mkPath('docs', 'README.md'), bootstrapTemplates['docs-readme'] || '', 'docs/README.md')
+
+	// ── 5. commands/about.ts ────────────────────────────────────────
+	await fs.ensureFolder(mkPath('commands'))
+	await writeFile(fs, ui, mkPath('commands', 'about.ts'), bootstrapTemplates['about-command'] || '', 'commands/about.ts')
+
+	// ── 6. features/example.ts (scaffold-based) ────────────────────
+	await fs.ensureFolder(mkPath('features'))
+	const featureCode = generateScaffold('feature', 'example', 'An example feature demonstrating the luca feature pattern')
+		|| bootstrapTemplates['example-feature'] || ''
+	await writeFile(fs, ui, mkPath('features', 'example.ts'), featureCode, 'features/example.ts')
+
+	// ── 7. endpoints/health.ts ─────────────────────────────────────
+	await fs.ensureFolder(mkPath('endpoints'))
+	await writeFile(fs, ui, mkPath('endpoints', 'health.ts'), bootstrapTemplates['health-endpoint'] || '', 'endpoints/health.ts')
+
+	// ── 8. luca.cli.ts ─────────────────────────────────────────────
+	await writeFile(fs, ui, mkPath('luca.cli.ts'), bootstrapTemplates['luca-cli'] || '', 'luca.cli.ts')
+
+	// ── 9. RUNME.md ────────────────────────────────────────────────
+	await writeFile(fs, ui, mkPath('RUNME.md'), bootstrapTemplates['runme'] || '', 'RUNME.md')
+
+	// ── 10. .claude/settings.json (permissions for AI coding tools) ──
+	const settingsPath = mkPath('.claude', 'settings.json')
+	const claudeSettings = {
+		permissions: {
+			allow: [
+				'Bash(luca *)',
+				'Bash(bun run *)',
+				'Bash(bun test *)',
+			],
+		},
+	}
+
+	if (!fs.exists(settingsPath)) {
+		await fs.ensureFolder(mkPath('.claude'))
+		await writeFile(fs, ui, settingsPath, JSON.stringify(claudeSettings, null, 2) + '\n', '.claude/settings.json')
+	} else {
+		// Merge luca permissions into existing settings
+		try {
+			const existing = JSON.parse(fs.readFile(settingsPath) as string)
+			const perms = existing.permissions || {}
+			const allow = new Set(perms.allow || [])
+			for (const rule of claudeSettings.permissions.allow) {
+				allow.add(rule)
+			}
+			existing.permissions = { ...perms, allow: [...allow] }
+			await writeFile(fs, ui, settingsPath, JSON.stringify(existing, null, 2) + '\n', '.claude/settings.json (merged)')
+		} catch {
+			ui.print.yellow('  ⚠ Could not parse existing .claude/settings.json, skipping merge')
+		}
+	}
+
+	// ── Summary ────────────────────────────────────────────────────
+	ui.print('')
+	ui.print.green('  ✓ Bootstrap complete!\n')
+	ui.print('  Your project is ready. Here\'s what to try:\n')
+	ui.print('    luca                  — see available commands')
+	ui.print('    luca about            — project info + discovered helpers')
+	ui.print('    luca serve            — start the API server (try /api/health)')
+	ui.print('    luca describe fs      — learn about any built-in feature')
+	ui.print('    luca RUNME            — run the interactive markdown demo')
+	ui.print('')
+	ui.print('  Need to build something? Use scaffold:\n')
+	ui.print('    luca scaffold command deploy    — add a CLI command')
+	ui.print('    luca scaffold feature cache     — add a container feature')
+	ui.print('    luca scaffold endpoint users    — add a REST route')
+	ui.print('    luca scaffold client github     — add an API client')
+	ui.print('    luca scaffold server mqtt       — add a server')
+	ui.print('')
+	ui.print.dim('    Run luca scaffold <type> --tutorial for a full guide on any type')
+	ui.print('')
+}
+
+// ── Helpers ──────────────────────────────────────────────────────────
+
+async function updateSkill(container: any, fs: any, ui: any) {
+	const skillDir = container.paths.resolve('.claude', 'skills', 'luca-framework')
+
+	// Wipe existing skill directory so stale files don't linger
+	if (fs.exists(skillDir)) {
+		await fs.rmdir(skillDir)
+	}
+
+	await fs.ensureFolder(skillDir)
+	await writeFile(fs, ui, container.paths.resolve(skillDir, 'SKILL.md'), bootstrapFiles['SKILL'] || '', '.claude/skills/luca-framework/SKILL.md')
+
+	const examplesDir = container.paths.resolve(skillDir, 'references', 'examples')
+	await fs.ensureFolder(examplesDir)
+	for (const [filename, content] of Object.entries(bootstrapExamples)) {
+		await fs.writeFileAsync(container.paths.resolve(examplesDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapExamples).length} example docs...`)
+
+	const tutorialsDir = container.paths.resolve(skillDir, 'references', 'tutorials')
+	await fs.ensureFolder(tutorialsDir)
+	for (const [filename, content] of Object.entries(bootstrapTutorials)) {
+		await fs.writeFileAsync(container.paths.resolve(tutorialsDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapTutorials).length} tutorial docs...`)
+
+	ui.print('')
+	ui.print.green('  ✓ Skill updated!')
+	ui.print('')
+}
+
+async function writeFile(fs: any, ui: any, path: string, content: string, label: string) {
+	ui.print.cyan(`  Writing ${label}...`)
+	await fs.writeFileAsync(path, content)
+}
+
+async function checkToolAvailability(ui: any, proc: any) {
+	const tools: { name: string; found: boolean; envKey?: string; envFound?: boolean }[] = []
+
+	for (const name of ['claude', 'codex']) {
+		let found = false
+		try {
+			const result = await proc.exec(`which ${name}`, { silent: true })
+			found = result.exitCode === 0 && result.stdout.trim().length > 0
+		} catch {
+			found = false
+		}
+		tools.push({ name, found })
+	}
+
+	const openaiKey = !!process.env.OPENAI_API_KEY
+	const hasAnyCodingTool = tools.some(t => t.found)
+
+	if (!hasAnyCodingTool) {
+		ui.print.yellow('  ┌─────────────────────────────────────────────────────────────┐')
+		ui.print.yellow('  │  No AI coding assistant detected (claude, codex)            │')
+		ui.print.yellow('  │                                                             │')
+		ui.print.yellow('  │  Luca works best with an AI coding assistant.               │')
+		ui.print.yellow('  │                                                             │')
+		ui.print.yellow('  │  Claude Code:  https://docs.anthropic.com/en/docs/claude-code│')
+		ui.print.yellow('  │  Codex CLI:    https://github.com/openai/codex              │')
+		ui.print.yellow('  └─────────────────────────────────────────────────────────────┘')
+		ui.print('')
+	} else {
+		for (const t of tools) {
+			if (t.found) ui.print.green(`  ✓ ${t.name} detected`)
+		}
+	}
+
+	if (!openaiKey) {
+		ui.print.dim('  ℹ OPENAI_API_KEY not set (only needed for codex/OpenAI features)')
+	} else {
+		ui.print.green('  ✓ OPENAI_API_KEY set')
+	}
+
+	ui.print('')
+}
+
+commands.registerHandler('bootstrap', {
+	description: 'Scaffold a new luca project with commands, features, endpoints, docs, and AI assistant configuration',
+	argsSchema,
+	handler: bootstrap,
+})

package/src/commands/chat.ts

@@ -0,0 +1,309 @@
+import { z } from 'zod'
+import * as readline from 'readline'
+import { commands } from '../command'
+import { CommandOptionsSchema } from '../schemas/base'
+import type { ContainerContext } from '../container'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		chat: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	model: z.string().optional().describe('Override the LLM model for the assistant'),
+	local: z.boolean().default(false).describe('Whether to use a local API server'),
+	resume: z.string().optional().describe('Thread ID or conversation ID to resume'),
+	list: z.boolean().optional().describe('List recent conversations and exit'),
+	historyMode: z.enum(['lifecycle', 'daily', 'persistent', 'session']).optional().describe('Override history persistence mode'),
+	offRecord: z.boolean().optional().describe('Alias for --history-mode lifecycle (ephemeral, no persistence)'),
+	clear: z.boolean().optional().describe('Clear the conversation history for the resolved history mode and exit'),
+	prependPrompt: z.string().optional().describe('Text or path to a markdown file to prepend to the system prompt'),
+	appendPrompt: z.string().optional().describe('Text or path to a markdown file to append to the system prompt'),
+	use: z.union([z.string(), z.array(z.string())]).optional().describe('Feature(s) to inject into the assistant via .use(). Supports options: --use "contentDb:rootPath=/tmp;lazy=true"'),
+	forbidTool: z.union([z.string(), z.array(z.string())]).optional().describe('Tool name patterns to exclude (supports * glob). Can be specified multiple times.'),
+	allowTool: z.union([z.string(), z.array(z.string())]).optional().describe('Tool name patterns to allow (strict allowlist, supports * glob). Can be specified multiple times.'),
+})
+
+export default async function chat(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const ui = container.feature('ui')
+
+	const manager = container.feature('assistantsManager')
+	await manager.discover()
+
+	const entries = manager.list()
+
+	if (entries.length === 0) {
+		console.error(ui.colors.red('No assistants found.'))
+		console.error(ui.colors.dim(`  Create a directory with a CORE.md file anywhere in the project.`))
+		process.exit(1)
+	}
+
+	const requestedName = container.argv._[1] as string | undefined
+	let name: string
+
+	if (requestedName) {
+		const entry = manager.get(requestedName)
+		if (!entry) {
+			const available = entries.map((e: any) => e.name).join(', ')
+			console.error(ui.colors.red(`Assistant "${requestedName}" not found.`))
+			console.error(ui.colors.dim(`  Available: ${available}`))
+			process.exit(1)
+		}
+		name = requestedName
+	} else if (entries.length === 1) {
+		name = entries[0].name
+	} else {
+		const answers = await ui.wizard([
+			{
+				type: 'list',
+				name: 'assistant',
+				message: 'Choose an assistant',
+				choices: entries.map((e: any) => ({ name: e.name, value: e.name })),
+			},
+		])
+		name = answers.assistant
+	}
+
+	// Resolve history mode: --off-record overrides everything to lifecycle
+	// CLI defaults to 'daily' for interactive persistence
+	const historyMode = options.offRecord
+		? 'lifecycle'
+		: (options.historyMode || 'daily')
+
+	const createOptions: Record<string, any> = { historyMode, injectTimestamps: true }
+	if (options.model) createOptions.model = options.model
+	if (options.local) createOptions.local = options.local
+	if (options.forbidTool) createOptions.forbidTools = Array.isArray(options.forbidTool) ? options.forbidTool : [options.forbidTool]
+	if (options.allowTool) createOptions.allowTools = Array.isArray(options.allowTool) ? options.allowTool : [options.allowTool]
+
+	// Resolve --prepend-prompt / --append-prompt: if it's an existing file, read it; if it ends in .md but doesn't exist, error
+	const fs = container.feature('fs')
+	for (const flag of ['prependPrompt', 'appendPrompt'] as const) {
+		const raw = options[flag]
+		if (!raw) continue
+		const resolved = container.paths.resolve(raw)
+		if (fs.exists(resolved)) {
+			createOptions[flag] = fs.readFile(resolved)
+		} else if (raw.endsWith('.md')) {
+			console.error(ui.colors.red(`File not found: ${resolved}`))
+			process.exit(1)
+		} else {
+			createOptions[flag] = raw
+		}
+	}
+
+	const assistant = manager.create(name, createOptions)
+
+	// --clear: wipe history for the current mode and exit
+	if (options.clear) {
+		const deleted = await assistant.clearHistory()
+		if (deleted > 0) {
+			console.log(ui.colors.green(`  Cleared ${deleted} conversation(s) for ${ui.colors.cyan(name)} (${historyMode} mode).`))
+		} else {
+			console.log(ui.colors.dim(`  No history to clear for ${ui.colors.cyan(name)} (${historyMode} mode).`))
+		}
+		return
+	}
+
+	// --list: show recent conversations and exit
+	if (options.list) {
+		const history = await assistant.listHistory({ limit: 20 })
+		if (history.length === 0) {
+			console.log(ui.colors.dim('  No saved conversations.'))
+		} else {
+			console.log()
+			console.log(ui.colors.dim('  Recent conversations:'))
+			console.log()
+			for (const meta of history) {
+				const date = new Date(meta.updatedAt).toLocaleString()
+				const msgs = ui.colors.dim(`(${meta.messageCount} messages)`)
+				console.log(`  ${ui.colors.cyan(meta.thread)} ${msgs}`)
+				console.log(`    ${ui.colors.dim(date)} - ${meta.title}`)
+			}
+			console.log()
+			console.log(ui.colors.dim(`  Resume with: luca chat ${name} --resume <thread-id>`))
+		}
+		return
+	}
+
+	// --resume: set thread override before start
+	if (options.resume) {
+		assistant.resumeThread(options.resume)
+	}
+
+	const ink = container.feature('ink', { enable: true })
+	await ink.loadModules()
+	const React = ink.React
+	const { Text } = ink.components
+
+	// Use the raw ink render (sync) since modules are already loaded
+	const inkModule = await import('ink')
+
+	let responseBuffer = ''
+	let inkInstance: any = null
+
+	function mdElement(content: string) {
+		const rendered = content ? String(ui.markdown(content)).trimEnd() : ''
+		return React.createElement(Text, null, rendered)
+	}
+
+	assistant.on('chunk', (text: string) => {
+		responseBuffer += text
+		if (!inkInstance) {
+			process.stdout.write('\n')
+			inkInstance = inkModule.render(mdElement(responseBuffer), { patchConsole: false })
+		} else {
+			inkInstance.rerender(mdElement(responseBuffer))
+		}
+	})
+
+	assistant.on('toolCall', (toolName: string, args: any) => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+		responseBuffer = ''
+		const argsStr = JSON.stringify(args).slice(0, 120)
+		process.stdout.write(ui.colors.dim(`\n  ⟳ ${toolName}`) + ui.colors.dim(`(${argsStr})\n`))
+	})
+
+	assistant.on('toolResult', (toolName: string, result: any) => {
+		const preview = typeof result === 'string' ? result.slice(0, 100) : JSON.stringify(result).slice(0, 100)
+		process.stdout.write(ui.colors.green(`  ✓ ${toolName}`) + ui.colors.dim(` → ${preview}${preview.length >= 100 ? '…' : ''}\n`))
+	})
+
+	assistant.on('toolError', (toolName: string, error: any) => {
+		const msg = error?.message || String(error)
+		process.stdout.write(ui.colors.red(`  ✗ ${toolName}: ${msg}\n`))
+	})
+
+	assistant.on('response', () => {
+		if (inkInstance) { inkInstance.unmount(); inkInstance = null }
+		responseBuffer = ''
+		process.stdout.write('\n')
+	})
+
+	// --use: inject features into the assistant
+	if (options.use) {
+		const items = Array.isArray(options.use) ? options.use : [options.use]
+		for (const item of items) {
+			const [namepart, optStr] = item.split(':')
+			if (!namepart) continue
+			const featureOpts: Record<string, any> = { enable: true }
+			if (optStr) {
+				for (const pair of optStr.split(';')) {
+					const [k, v] = pair.split('=')
+					if (k) featureOpts[k.trim()] = v?.trim() === 'true' ? true : v?.trim() === 'false' ? false : v?.trim()
+				}
+			}
+			const feature = container.feature(namepart.trim(), featureOpts)
+			assistant.use(feature)
+		}
+	}
+
+	// Start the assistant (loads history if applicable)
+	await assistant.start()
+
+	const messageCount = assistant.messages?.length || 0
+	const isResuming = historyMode !== 'lifecycle' && messageCount > 1
+
+	let rl = readline.createInterface({
+		input: process.stdin,
+		output: process.stdout,
+	})
+
+	let rlClosed = false
+	rl.on('close', () => { rlClosed = true })
+
+	function ensureRl() {
+		if (rlClosed) {
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
+		}
+	}
+
+	function prompt(): Promise<string> {
+		return new Promise((resolve) => {
+			ensureRl()
+			rl.question(ui.colors.dim(`\n${name} > `), (answer: string) => resolve(answer.trim()))
+		})
+	}
+
+	console.log()
+	if (isResuming) {
+		console.log(ui.colors.dim(`  Resuming conversation with ${ui.colors.cyan(name)} (${messageCount} messages). Type .exit to quit.`))
+	} else {
+		console.log(ui.colors.dim(`  Chatting with ${ui.colors.cyan(name)}. Type .exit to quit.`))
+	}
+	if (historyMode !== 'lifecycle') {
+		console.log(ui.colors.dim(`  Mode: ${historyMode}`))
+	}
+	console.log()
+
+	while (true) {
+		const question = await prompt()
+
+		if (!question) continue
+		if (question === '.exit') break
+
+		if (question === '/console') {
+			// Pause chat readline so the REPL can own stdin
+			rl.close()
+
+			// Build feature context like `luca console` does
+			const featureContext: Record<string, any> = {}
+			for (const fname of container.features.available) {
+				try { featureContext[fname] = container.feature(fname) } catch {}
+			}
+
+			const replPrompt = ui.colors.magenta('console') + ui.colors.dim(' > ')
+			const repl = container.feature('repl', { prompt: replPrompt })
+
+			console.log()
+			console.log(ui.colors.dim('  Dropping into console. The assistant is available as `assistant`.'))
+			console.log(ui.colors.dim('  Type .exit to return to chat.'))
+			console.log()
+
+			await repl.start({
+				context: {
+					...featureContext,
+					assistant,
+					console,
+					setTimeout, setInterval, clearTimeout, clearInterval,
+					fetch,
+				},
+			})
+
+			// Wait for the REPL to close
+			await new Promise<void>((resolve) => {
+				repl._rl!.on('close', resolve)
+			})
+
+			// Resume chat readline
+			console.log()
+			console.log(ui.colors.dim(`  Back in chat with ${ui.colors.cyan(name)}.`))
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
+			continue
+		}
+
+		await assistant.ask(question)
+	}
+
+	rl.close()
+
+	// Show resume instruction for non-lifecycle modes
+	if (historyMode !== 'lifecycle' && assistant.currentThreadId) {
+		console.log()
+		console.log(ui.colors.dim(`  Session saved. To resume this conversation:`))
+		console.log(ui.colors.dim(`    luca chat ${name} --resume ${assistant.currentThreadId}`))
+		console.log()
+	}
+}
+
+commands.registerHandler('chat', {
+	description: 'Start an interactive chat session with a local assistant',
+	argsSchema,
+	handler: chat,
+})