@soederpop/luca 0.0.2

package/src/commands/eval.ts

@@ -0,0 +1,116 @@
+import { z } from 'zod'
+import { inspect } from 'util'
+import { commands } from '../command.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
+	const code = args.slice(1).join(' ')
+
+	if (!code.trim()) {
+		console.error('Usage: luca eval "<code>" [--json]')
+		return
+	}
+
+	const vm = container.feature('vm')
+
+	// HACK
+	Array(container.argv.enable).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)
+	}
+}
+
+const BUILTIN_TYPES = new Set(['Object', 'Array', 'Map', 'Set', 'Date', 'RegExp', 'Promise', 'Error', 'Number', 'String', 'Boolean'])
+
+export function displayResult(value: any) {
+	if (typeof value !== 'object' || value === null) {
+		console.log(value)
+		return
+	}
+
+	const hasCustomInspect = typeof value[Symbol.for('nodejs.util.inspect.custom')] === 'function'
+	const ctorName = value.constructor?.name
+	const isClassInstance = ctorName && !BUILTIN_TYPES.has(ctorName)
+
+	// Objects with custom inspect or builtins: use standard inspect
+	if (hasCustomInspect || !isClassInstance) {
+		console.log(inspect(value, { colors: true, depth: 4 }))
+		return
+	}
+
+	// Class instances: show clean data (no _ props, no functions)
+	const data: Record<string, any> = {}
+	for (const [k, v] of Object.entries(value)) {
+		if (k.startsWith('_') || typeof v === 'function') continue
+		data[k] = v
+	}
+	const body = inspect(data, { colors: true, depth: 3 })
+	console.log(`${ctorName} ${body}`)
+
+	// Collect methods and getters from own + prototype chain
+	const methods: string[] = []
+	const getters: string[] = []
+
+	for (const [k, v] of Object.entries(value)) {
+		if (k.startsWith('_')) continue
+		if (typeof v === 'function') methods.push(k)
+	}
+
+	let proto = Object.getPrototypeOf(value)
+	while (proto && proto !== Object.prototype) {
+		for (const k of Object.getOwnPropertyNames(proto)) {
+			if (k === 'constructor' || k.startsWith('_')) continue
+			const desc = Object.getOwnPropertyDescriptor(proto, k)
+			if (!desc) continue
+			if (desc.get && !getters.includes(k)) getters.push(k)
+			else if (typeof desc.value === 'function' && !methods.includes(k)) methods.push(k)
+		}
+		proto = Object.getPrototypeOf(proto)
+	}
+
+	if (getters.length || methods.length) {
+		const parts: string[] = []
+		if (getters.length) parts.push(`  \x1b[36mgetters:\x1b[0m ${getters.sort().join(', ')}`)
+		if (methods.length) parts.push(`  \x1b[36mmethods:\x1b[0m ${methods.sort().map(m => m + '()').join(', ')}`)
+		console.log(parts.join('\n'))
+	}
+}
+
+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,214 @@
+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'])
+
+/**
+ * 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()
+		console.log(c.white('  Commands:'))
+		console.log()
+
+		// Dynamic padding based on longest command name
+		const commandNames = (container.commands.available as string[]).filter((n: string) => n !== 'help')
+		const maxNameLen = Math.max(...commandNames.map((n: string) => n.length)) + 2
+
+		for (const name of commandNames) {
+			const Cmd = container.commands.lookup(name) as any
+			const desc = Cmd.commandDescription || ''
+			console.log(`    ${c.cyan(name.padEnd(maxNameLen))} ${c.dim(desc)}`)
+		}
+
+		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,14 @@
+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'

package/src/commands/mcp.ts

@@ -0,0 +1,64 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { MCPServer } from '../servers/mcp.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		mcp: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	transport: z.enum(['stdio', 'http']).default('stdio').describe('Transport type (stdio or http)'),
+	port: z.number().default(3001).describe('Port for HTTP transport'),
+	name: z.string().optional().describe('Server name reported to MCP clients'),
+	version: z.string().optional().describe('Server version reported to MCP clients'),
+	mcpCompat: z.enum(['standard', 'codex']).optional()
+		.describe('HTTP compatibility profile. Defaults to standard. Can also be set via MCP_HTTP_COMPAT.'),
+	stdioCompat: z.enum(['standard', 'codex', 'auto']).optional()
+		.describe('Stdio framing compatibility profile. Defaults to standard. Can also be set via MCP_STDIO_COMPAT.'),
+})
+
+export default async function mcp(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const envCompat = process.env.MCP_HTTP_COMPAT?.toLowerCase()
+	const resolvedCompat = options.mcpCompat || (envCompat === 'codex' ? 'codex' : 'standard')
+	const envStdioCompat = process.env.MCP_STDIO_COMPAT?.toLowerCase()
+	const resolvedStdioCompat = options.stdioCompat
+		|| (envStdioCompat === 'codex' || envStdioCompat === 'auto' ? envStdioCompat : 'standard')
+
+	const mcpServer = container.server('mcp', {
+		transport: options.transport,
+		port: options.port,
+		serverName: options.name || container.manifest?.name || 'luca-mcp',
+		serverVersion: options.version || container.manifest?.version || '1.0.0',
+		mcpCompat: options.mcpCompat,
+		stdioCompat: options.stdioCompat,
+	}) as MCPServer
+
+	await mcpServer.start({
+		transport: options.transport,
+		port: options.port,
+		mcpCompat: options.mcpCompat,
+		stdioCompat: options.stdioCompat,
+	})
+
+	if (options.transport === 'http') {
+		const name = options.name || container.manifest?.name || 'MCP Server'
+		console.log(`\n${name} listening on http://localhost:${options.port}/mcp`)
+		console.log(`Transport: HTTP (Streamable)`)
+		console.log(`Compatibility: ${resolvedCompat}`)
+	} else {
+		// stdio mode — don't print to stdout as it's used for the protocol
+		console.error(`MCP server started (stdio transport)`)
+		console.error(`Stdio Compatibility: ${resolvedStdioCompat}`)
+	}
+}
+
+commands.registerHandler('mcp', {
+	description: 'Start an MCP (Model Context Protocol) server',
+	argsSchema,
+	handler: mcp,
+})