luca 2.0.0 → 3.0.2

package/src/commands/describe.ts

@@ -0,0 +1,243 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { HelperIntrospection, IntrospectionSection } from '../introspection/index.js'
+import { __INTROSPECTION__, __BROWSER_INTROSPECTION__ } from '../introspection/index.js'
+import { features } from '../feature.js'
+import { ContainerDescriber } from '../container-describer.js'
+import type { BrowserFeatureData } from '../container-describer.js'
+import { presentIntrospectionAsTypeScript } from '../helper.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		describe: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	json: z.boolean().default(false).describe('Output introspection data as JSON instead of markdown'),
+	typescript: z.boolean().default(false).describe('Output introspection data as TypeScript interface declarations'),
+	ts: z.boolean().default(false).describe('Alias for --typescript'),
+	pretty: z.boolean().default(false).describe('Render markdown with terminal styling via ui.markdown'),
+	title: z.boolean().default(true).describe('Include the title header in the output (use --no-title to omit)'),
+	// Clean section flags (can be combined: --description --usage)
+	description: z.boolean().default(false).describe('Show the description section'),
+	usage: z.boolean().default(false).describe('Show the usage section'),
+	methods: z.boolean().default(false).describe('Show the methods section'),
+	getters: z.boolean().default(false).describe('Show the getters section'),
+	events: z.boolean().default(false).describe('Show the events section'),
+	state: z.boolean().default(false).describe('Show the state section'),
+	options: z.boolean().default(false).describe('Show the options section'),
+	'env-vars': z.boolean().default(false).describe('Show the envVars section'),
+	envvars: z.boolean().default(false).describe('Show the envVars section'),
+	examples: z.boolean().default(false).describe('Show the examples section'),
+	// Legacy --only-* flags
+	'only-methods': z.boolean().default(false).describe('Show only the methods section'),
+	'only-getters': z.boolean().default(false).describe('Show only the getters section'),
+	'only-events': z.boolean().default(false).describe('Show only the events section'),
+	'only-state': z.boolean().default(false).describe('Show only the state section'),
+	'only-options': z.boolean().default(false).describe('Show only the options section'),
+	'only-env-vars': z.boolean().default(false).describe('Show only the envVars section'),
+	'only-envvars': z.boolean().default(false).describe('Show only the envVars section'),
+	'only-examples': z.boolean().default(false).describe('Show only the examples section'),
+	platform: z.enum(['browser', 'web', 'server', 'node', 'all']).default('all').describe('Which platform features to show: browser/web, server/node, or all'),
+})
+
+// --- Browser feature loading (build-time concern, lives here not in ContainerDescriber) ---
+
+const WEB_FEATURE_IDS = ['speech', 'voice', 'assetLoader', 'network', 'vault', 'vm', 'esbuild', 'helpers', 'containerLink']
+
+let _browserData: BrowserFeatureData | null = null
+
+/**
+ * Load web/browser feature introspection data into a separate map.
+ * This is a build-time hack: we import web feature classes into the node process,
+ * snapshot their introspection, then restore the node registry.
+ * The ContainerDescriber itself knows nothing about this.
+ */
+async function loadBrowserFeatures(): Promise<BrowserFeatureData> {
+	if (_browserData) return _browserData
+
+	const nodeFeatureIds = new Set(features.available)
+	const nodeIntrospection = new Map<string, HelperIntrospection>()
+	const nodeConstructors = new Map<string, any>()
+
+	for (const id of nodeFeatureIds) {
+		const data = __INTROSPECTION__.get(`features.${id}`)
+		if (data) nodeIntrospection.set(`features.${id}`, structuredClone(data))
+		try { nodeConstructors.set(id, features.lookup(id)) } catch {}
+	}
+
+	await import('../introspection/generated.web.js')
+
+	await Promise.all([
+		import('../web/features/speech.js'),
+		import('../web/features/voice-recognition.js'),
+		import('../web/features/asset-loader.js'),
+		import('../web/features/network.js'),
+		import('../web/features/vault.js'),
+		import('../web/features/vm.js'),
+		import('../web/features/esbuild.js'),
+		import('../web/features/helpers.js'),
+		import('../web/features/container-link.js'),
+	])
+
+	const browserIntrospection = new Map<string, HelperIntrospection>()
+	const browserConstructors = new Map<string, any>()
+	const collidingIds = new Set<string>()
+
+	for (const id of WEB_FEATURE_IDS) {
+		const key = `features.${id}`
+		const data = __INTROSPECTION__.get(key)
+		if (data) browserIntrospection.set(key, structuredClone(data))
+		try { browserConstructors.set(id, features.lookup(id)) } catch {}
+		if (nodeFeatureIds.has(id)) collidingIds.add(id)
+	}
+
+	for (const [id, ctor] of nodeConstructors) {
+		features.register(id, ctor)
+	}
+
+	for (const [key, data] of nodeIntrospection) {
+		__INTROSPECTION__.set(key, data)
+	}
+
+	for (const id of WEB_FEATURE_IDS) {
+		const key = `features.${id}`
+		if (!nodeIntrospection.has(key)) __INTROSPECTION__.delete(key)
+		if (!nodeFeatureIds.has(id)) features.unregister(id)
+	}
+
+	for (const [key, data] of browserIntrospection) {
+		__BROWSER_INTROSPECTION__.set(key, data)
+	}
+
+	_browserData = {
+		introspection: browserIntrospection,
+		constructors: browserConstructors,
+		available: WEB_FEATURE_IDS.filter(id => browserIntrospection.has(`features.${id}`)),
+		collidingIds,
+	}
+
+	return _browserData
+}
+
+function shouldIncludeBrowser(platform: string): boolean {
+	return platform === 'browser' || platform === 'web' || platform === 'all'
+}
+
+// --- Command handler ---
+
+export default async function describe(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const describer = new ContainerDescriber(container)
+
+	const args = container.argv._ as string[]
+	const targets = args.slice(1)
+
+	// No targets: show help screen
+	if (targets.length === 0) {
+		const { formatCommandHelp } = await import('./help.js')
+		const ui = container.feature('ui') as any
+		const Cmd = container.commands.lookup('describe')
+		console.log(formatCommandHelp('describe', Cmd, ui.colors))
+		return
+	}
+
+	// Build-time hack: load browser features into the describer if needed
+	if (shouldIncludeBrowser(options.platform)) {
+		const browserData = await loadBrowserFeatures()
+		describer.setBrowserData(browserData)
+	}
+
+	const sections = ContainerDescriber.getSectionsFromFlags(options)
+
+	const result = await describer.describe(targets, {
+		sections,
+		noTitle: !options.title,
+		platform: options.platform as any,
+	})
+
+	const wantsTypeScript = options.typescript || options.ts
+
+	if (wantsTypeScript) {
+		const output = renderResultAsTypeScript(result, targets, describer, sections)
+		if (options.pretty) {
+			const ui = container.feature('ui')
+			console.log(ui.markdown('```ts\n' + output + '\n```'))
+		} else {
+			console.log(output)
+		}
+	} else if (options.json) {
+		console.log(JSON.stringify(result.json, null, 2))
+	} else if (options.pretty) {
+		const ui = container.feature('ui')
+		console.log(ui.markdown(result.text))
+	} else {
+		console.log(result.text)
+	}
+}
+
+/**
+ * Renders the describe result as TypeScript interface declarations.
+ * Handles single helpers, arrays of helpers (registry describes), and the container.
+ */
+function renderResultAsTypeScript(result: { json: any; text: string }, targets: string[], describer: ContainerDescriber, sections: (IntrospectionSection | 'description')[]): string {
+	const json = result.json
+	const section = sections.length === 1 && sections[0] !== 'description' ? sections[0] as IntrospectionSection : undefined
+
+	// Single helper introspection object (has shortcut = full data, or id = filtered data)
+	if (json && (json.shortcut || json.id)) {
+		// If sections were applied, the JSON is partial — get full data and pass section to renderer
+		const fullData = json.shortcut ? json : __INTROSPECTION__.get(json.id) || json
+		return presentIntrospectionAsTypeScript(fullData, section)
+	}
+
+	// Container introspection (has className, registries, factories)
+	if (json && json.className && json.registries) {
+		const container = (describer as any).container
+		return container.introspectAsType()
+	}
+
+	// Array of results (e.g. from registry describe or multiple targets)
+	if (Array.isArray(json)) {
+		const interfaces = json
+			.filter((item: any) => item && (item.shortcut || item.id))
+			.map((item: any) => {
+				const fullData = item.shortcut ? item : __INTROSPECTION__.get(item.id) || item
+				return presentIntrospectionAsTypeScript(fullData, section)
+			})
+		return interfaces.join('\n\n')
+	}
+
+	// Object keyed by helper id (registry describe format — has _shared and per-helper summaries)
+	if (json && typeof json === 'object' && !json._helper && json._shared) {
+		const ids = Object.keys(json).filter(k => k !== '_shared')
+		const interfaces = ids
+			.map((id: string) => {
+				// Try qualified key first (e.g. "clients.rest"), then scan the introspection map
+				for (const prefix of ['features', 'clients', 'servers', 'commands', 'endpoints']) {
+					const data = __INTROSPECTION__.get(`${prefix}.${id}`)
+					if (data) return presentIntrospectionAsTypeScript(data, section)
+				}
+				return null
+			})
+			.filter(Boolean)
+		if (interfaces.length > 0) return interfaces.join('\n\n')
+	}
+
+	// Member-level result (has _helper and _type) — render the full helper interface
+	if (json && json._helper) {
+		const fullData = __INTROSPECTION__.get(json._helper) || __INTROSPECTION__.get(`features.${json._helper}`)
+		if (fullData) return presentIntrospectionAsTypeScript(fullData)
+	}
+
+	return result.text
+}
+
+commands.registerHandler('describe', {
+	description: 'Describe the container, registries, or individual helpers',
+	argsSchema,
+	handler: describe,
+})

package/src/commands/eval.ts

@@ -0,0 +1,67 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { displayResult } from '../node/features/display-result.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		eval: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	json: z.boolean().default(false).describe('Serialize output as JSON'),
+	enable: z.string().optional().describe('Enable a feature before evaluating (e.g. --enable diskCache)'),
+})
+
+export default async function evalCommand(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+
+	container.addContext('feature', (...args: any) => container.feature(...args))
+
+	await container.helpers.discoverAll()
+	
+	const args = container.argv._ as string[]
+	// args[0] is "eval", the rest is the code snippet
+	let code = args.slice(1).join(' ')
+
+	// Read from stdin if no inline code was provided
+	if (!code.trim()) {
+		code = await Bun.stdin.text()
+	}
+
+	if (!code.trim()) {
+		console.error('Usage: luca eval "<code>" [--json]')
+		return
+	}
+
+	const vm = container.feature('vm')
+
+	// HACK
+	Array(container.argv.enable).filter(Boolean).map((id) => {
+		container.feature(id, { ...container.argv, enable: true }).enable()
+	})
+
+	// Build context with container and all enabled feature instances
+	const ctx: Record<string, any> = { container }
+	for (const [name, instance] of Object.entries(container.enabledFeatures ?? {})) {
+		ctx[name] = instance
+	}
+
+	const result = await vm.run(code, ctx)
+
+	if (options.json) {
+		console.log(JSON.stringify(result, null, 2))
+	} else {
+		displayResult(result)
+	}
+}
+
+export { displayResult } from '../node/features/display-result.js'
+
+commands.registerHandler('eval', {
+	description: 'Evaluate a JavaScript/TypeScript expression with the container in scope',
+	argsSchema,
+	handler: evalCommand,
+})

package/src/commands/help.ts

@@ -0,0 +1,240 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		help: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+/** Hidden option prefixes — legacy aliases that shouldn't clutter help output. */
+const HIDDEN_PREFIXES = ['only-']
+const HIDDEN_KEYS = new Set(['_', 'name', '_cacheKey', 'dispatchSource'])
+
+/**
+ * Extract CLI option info from a Zod schema.
+ * Walks through Zod v4 wrapper types (default, optional) to find descriptions, types, and defaults.
+ */
+function extractOptions(schema: any): Array<{ flag: string; description: string; type: string; defaultValue?: any }> {
+	if (!schema?.shape) return []
+
+	const options: Array<{ flag: string; description: string; type: string; defaultValue?: any }> = []
+
+	for (const [key, field] of Object.entries(schema.shape)) {
+		if (HIDDEN_KEYS.has(key)) continue
+		if (HIDDEN_PREFIXES.some((p) => key.startsWith(p))) continue
+
+		const f = field as any
+		// In Zod v4, description lives on the schema object itself
+		const description = f.description || ''
+		let type = 'string'
+		let defaultValue: any = undefined
+
+		// Walk through wrapper types to find leaf type and default
+		let current = f
+		while (current) {
+			const defType = current._def?.type || current.type
+			if (defType === 'default') {
+				defaultValue = current._def?.defaultValue
+				if (typeof defaultValue === 'function') defaultValue = defaultValue()
+			}
+			if (defType === 'boolean') { type = 'boolean'; break }
+			if (defType === 'string') { type = 'string'; break }
+			if (defType === 'number') { type = 'number'; break }
+			if (defType === 'enum') { type = current.options?.join(' | ') || 'enum'; break }
+			// Unwrap
+			current = current._def?.innerType
+		}
+
+		options.push({ flag: key, description, type, defaultValue })
+	}
+
+	return options
+}
+
+/**
+ * Format CLI-oriented help text for a single command.
+ * Exported so other commands (like describe) can reuse it.
+ */
+export function formatCommandHelp(name: string, Cmd: any, colors: any): string {
+	const desc = Cmd.commandDescription || ''
+	const schema = Cmd.argsSchema
+	const lines: string[] = []
+
+	lines.push('')
+	lines.push(`  ${colors.cyan.bold(`luca ${name}`)}  ${desc ? `${colors.dim('—')} ${desc}` : ''}`)
+	lines.push('')
+
+	const options = extractOptions(schema)
+
+	if (options.length === 0) {
+		lines.push(`  ${colors.white('Usage:')} ${colors.cyan(`luca ${name}`)}`)
+	} else {
+		const booleans = options.filter((o) => o.type === 'boolean')
+		const valued = options.filter((o) => o.type !== 'boolean')
+
+		lines.push(`  ${colors.white('Usage:')} ${colors.cyan(`luca ${name}`)} ${colors.dim('[options]')}`)
+		lines.push('')
+
+		if (valued.length > 0) {
+			lines.push(`  ${colors.white('Options:')}`)
+			lines.push('')
+			const maxLen = Math.max(...valued.map((o) => `--${o.flag} <${o.type}>`.length))
+			for (const opt of valued) {
+				const flag = `--${opt.flag} <${opt.type}>`
+				let line = `    ${colors.green(flag.padEnd(maxLen + 2))} ${opt.description}`
+				if (opt.defaultValue !== undefined && opt.defaultValue !== false) {
+					line += ` ${colors.dim(`(default: ${opt.defaultValue})`)}`
+				}
+				lines.push(line)
+			}
+			lines.push('')
+		}
+
+		if (booleans.length > 0) {
+			lines.push(`  ${colors.white('Flags:')}`)
+			lines.push('')
+			const maxLen = Math.max(...booleans.map((o) => `--${o.flag}`.length))
+			for (const opt of booleans) {
+				const flag = `--${opt.flag}`
+				let line = `    ${colors.green(flag.padEnd(maxLen + 2))} ${opt.description}`
+				if (opt.defaultValue === true) {
+					line += ` ${colors.dim('(default: true)')}`
+				}
+				lines.push(line)
+			}
+			lines.push('')
+		}
+	}
+
+	return lines.join('\n')
+}
+
+/** Strip ANSI escape codes for visible width calculation. */
+function stripAnsi(s: string): string {
+	return s.replace(/\x1B\[[0-9;]*m/g, '')
+}
+
+/** Merge two multi-line blocks side by side with a gap. */
+function sideBySide(left: string[], right: string[], gap = 3): string[] {
+	const maxLeftWidth = Math.max(...left.map((l) => stripAnsi(l).length))
+	const maxLines = Math.max(left.length, right.length)
+	const result: string[] = []
+
+	for (let i = 0; i < maxLines; i++) {
+		const l = left[i] || ''
+		const r = right[i] || ''
+		const visLen = stripAnsi(l).length
+		const pad = Math.max(0, maxLeftWidth - visLen) + gap
+		result.push(l + ' '.repeat(pad) + r)
+	}
+
+	return result
+}
+
+const LEGO_ROBOT = [
+	' ┌─○○─┐ ',
+	' │ ●● │ ',
+	' ├○──○┤ ',
+	' └─╨╨─┘ ',
+]
+
+const BANNER_COLORS: string[] = ['cyan', 'blue', 'magenta']
+
+export default async function help(_options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const ui = container.feature('ui') as any
+	const c = ui.colors
+
+	const args = container.argv._ as string[]
+	const target = args[1] as string
+
+	if (!target) {
+		// Robot (left) + banner (right), same height — direct 1:1 alignment
+		const banner = ui.banner('luca', { font: 'Small Slant', colors: BANNER_COLORS })
+		const bannerLines = banner.split('\n').filter((l: string) => l.trim())
+		const coloredRobot = ui.applyGradient(LEGO_ROBOT.join('\n'), BANNER_COLORS)
+		const robotLines = coloredRobot.split('\n') as string[]
+		const robotWidth = Math.max(...LEGO_ROBOT.map((l: string) => l.length))
+
+		const headerLines: string[] = []
+		const maxLines = Math.max(robotLines.length, bannerLines.length)
+		for (let i = 0; i < maxLines; i++) {
+			const rLine = robotLines[i] || ''
+			const rPad = robotWidth - stripAnsi(rLine).length
+			const bLine = bannerLines[i] || ''
+			headerLines.push(rLine + ' '.repeat(rPad + 2) + bLine)
+		}
+
+		console.log('\n')
+		console.log(headerLines.join('\n'))
+		console.log(c.dim('  Lightweight Universal Conversational Architecture'))
+		console.log()
+		console.log(c.white('  Usage: ') + c.cyan('luca') + c.dim(' <command|file> [options]'))
+		console.log()
+		const allNames = (container.commands.available as string[]).filter((n: string) => n !== 'help')
+		const maxNameLen = Math.max(...allNames.map((n: string) => n.length)) + 2
+
+		const sources = (container as any)._commandSources as
+			| { builtinCommands: Set<string>; projectCommands: Set<string>; userCommands: Set<string> }
+			| undefined
+
+		const printCommands = (names: string[]) => {
+			for (const name of names) {
+				const Cmd = container.commands.lookup(name) as any
+				const desc = Cmd.commandDescription || ''
+				console.log(`    ${c.cyan(name.padEnd(maxNameLen))} ${c.dim(desc)}`)
+			}
+		}
+
+		// Built-in commands
+		const builtinNames = sources
+			? allNames.filter((n) => sources.builtinCommands.has(n))
+			: allNames
+		console.log(c.white('  Commands:'))
+		console.log()
+		printCommands(builtinNames)
+
+		// Project-local commands
+		if (sources && sources.projectCommands.size > 0) {
+			console.log()
+			console.log(c.white('  Project Commands') + c.dim(' (./commands/*)'))
+			console.log()
+			printCommands(allNames.filter((n) => sources.projectCommands.has(n)))
+		}
+
+		// User-level commands
+		if (sources && sources.userCommands.size > 0) {
+			console.log()
+			console.log(c.white('  User Commands') + c.dim(' (~/.luca/commands/*)'))
+			console.log()
+			printCommands(allNames.filter((n) => sources.userCommands.has(n)))
+		}
+
+		console.log()
+		console.log(c.dim('  Run ') + c.cyan('luca <file>') + c.dim(' to execute a script or markdown (.ts, .js, .md)'))
+		console.log(c.dim('  Run ') + c.cyan('luca help <command>') + c.dim(' for detailed usage of a command'))
+		console.log()
+		return
+	}
+
+	if (!container.commands.has(target)) {
+		console.error(`  Unknown command: ${c.red(target)}`)
+		console.error()
+		console.error(`  Run ${c.cyan('luca help')} to see available commands.`)
+		return
+	}
+
+	const Cmd = container.commands.lookup(target) as any
+	console.log(formatCommandHelp(target, Cmd, c))
+}
+
+commands.registerHandler('help', {
+	description: 'Show help for luca commands',
+	argsSchema,
+	handler: help,
+})

package/src/commands/index.ts

@@ -0,0 +1,19 @@
+export { Command, commands, CommandsRegistry, type AvailableCommands, type CommandsInterface, type CommandHandler, type CommandState, type CommandOptions } from '../command.js'
+
+// Side-effect imports register each command
+import './run.js'
+import './console.js'
+import './serve.js'
+import './chat.js'
+import './prompt.js'
+import './mcp.js'
+import './sandbox-mcp.js'
+import './describe.js'
+import './eval.js'
+import './help.js'
+import './scaffold.js'
+import './introspect.js'
+import './save-api-docs.js'
+import './bootstrap.js'
+import './select.js'
+import './code.js'