@soederpop/luca 0.0.6 → 0.0.8

package/src/command.ts

@@ -1,9 +1,12 @@
 import { Helper } from './helper.js'
 import type { Container, ContainerContext } from './container.js'
 import { Registry } from './registry.js'
-import { CommandStateSchema, CommandOptionsSchema, CommandEventsSchema } from './schemas/base.js'
+import { CommandStateSchema, CommandOptionsSchema, CommandEventsSchema, type DispatchSource, type CommandRunResult } from './schemas/base.js'
 import { z } from 'zod'
 import { join } from 'path'
+import { graftModule, isNativeHelperClass } from './graft.js'
+
+export type { DispatchSource, CommandRunResult }
 
 export type CommandState = z.infer<typeof CommandStateSchema>
 export type CommandOptions = z.infer<typeof CommandOptionsSchema>
@@ -22,6 +25,24 @@ export interface CommandsInterface {
 
 export type CommandHandler<T = any> = (options: T, context: ContainerContext) => Promise<void>
 
+/**
+ * Type helper for module-augmentation of AvailableCommands when using the
+ * SimpleCommand (module-based) pattern instead of a full class.
+ *
+ * @example
+ * ```typescript
+ * declare module '@soederpop/luca' {
+ *   interface AvailableCommands {
+ *     serve: SimpleCommand<typeof argsSchema>
+ *   }
+ * }
+ * ```
+ */
+export type SimpleCommand<Schema extends z.ZodType = z.ZodType> = typeof Command & {
+	argsSchema: Schema
+	positionals: string[]
+}
+
 export class Command<
 	T extends CommandState = CommandState,
 	K extends CommandOptions = CommandOptions
@@ -34,35 +55,73 @@ export class Command<
 
 	static commandDescription: string = ''
 	static argsSchema: z.ZodType = CommandOptionsSchema
+	static positionals: string[] = []
+
+	/** Self-register a Command subclass from a static initialization block. */
+	static register: (SubClass: typeof Command, id?: string) => typeof Command
 
 	override get initialState(): T {
 		return ({ running: false } as unknown) as T
 	}
 
+	/**
+	 * Parse raw CLI argv against this command's argsSchema.
+	 * Kept for backward compatibility with built-in commands.
+	 */
 	parseArgs(): any {
 		const schema = (this.constructor as typeof Command).argsSchema
 		return schema.parse(this.container.options)
 	}
 
-	async execute(): Promise<void> {
-		// override in subclass
+	/**
+	 * The user-defined command payload. Override this in class-based commands,
+	 * or export a `run` function in module-based commands.
+	 *
+	 * Receives clean, named args (positionals already mapped) and the container context.
+	 */
+	async run(_args: any, _context: ContainerContext): Promise<void> {
+		// override in subclass or grafted from module export
 	}
 
-	async run(): Promise<void> {
-		// Intercept --help before the command executes
-		if (this.container.argv.help) {
+	/**
+	 * Internal dispatch normalizer. Maps positionals for CLI, passes through named
+	 * args for headless, validates via argsSchema, captures output when headless.
+	 *
+	 * @param rawInput - Named args object. When omitted, reads from container.argv.
+	 * @param source - Override the dispatch source. Defaults to constructor option.
+	 */
+	async execute(rawInput?: Record<string, any>, source?: DispatchSource): Promise<CommandRunResult | void> {
+		const dispatchSource = source ?? (this._options as any).dispatchSource ?? 'cli'
+		const Cls = this.constructor as typeof Command
+
+		// Help intercept (CLI only) — must happen before schema validation
+		// so `luca somecommand --help` works even without required args
+		if (dispatchSource === 'cli' && (this.container as any).argv?.help) {
 			const { formatCommandHelp } = await import('./commands/help.js')
 			const ui = (this.container as any).feature('ui')
-			const name = (this.constructor as typeof Command).shortcut?.replace('commands.', '') || 'unknown'
+			const name = Cls.shortcut?.replace('commands.', '') || 'unknown'
 			console.log(formatCommandHelp(name, this.constructor, ui.colors))
 			return
 		}
 
+		// Build named args from raw input
+		const raw = rawInput ?? { ...(this.container as any).argv }
+		const named = this._normalizeInput(raw, dispatchSource)
+
+		// Validate against argsSchema
+		const parsed = Cls.argsSchema.parse(named)
+
+		// For headless dispatch, capture stdout/stderr
+		if (dispatchSource !== 'cli') {
+			return this._runCaptured(parsed)
+		}
+
+		// CLI path — lifecycle events + run
 		this.state.set('running', true)
 		this.emit('started')
 
 		try {
-			await this.execute()
+			await this.run(parsed, this.context)
 			this.state.set('running', false)
 			this.state.set('exitCode', 0)
 			this.emit('completed', 0)
@@ -74,6 +133,109 @@ export class Command<
 		}
 	}
 
+	/**
+	 * The public entry point for dispatching a command.
+	 * Called by the CLI and other dispatch surfaces.
+	 */
+	async dispatch(rawInput?: Record<string, any>, source?: DispatchSource): Promise<CommandRunResult | void> {
+		return this.execute(rawInput, source)
+	}
+
+	/**
+	 * Map CLI positional args to named fields based on the command's positionals declaration.
+	 * For non-CLI dispatch, args are already named — pass through.
+	 */
+	private _normalizeInput(raw: Record<string, any>, source: DispatchSource): Record<string, any> {
+		if (source !== 'cli') return raw
+
+		const Cls = this.constructor as typeof Command
+		const positionals = Cls.positionals
+		if (!positionals.length) return raw
+
+		const result = { ...raw }
+
+		// Map raw._[1], raw._[2], etc. (skipping _[0] which is command name) to named fields
+		const posArgs: string[] = (raw._ || []).slice(1)
+		for (let i = 0; i < positionals.length; i++) {
+			const name = positionals[i]!
+			if (result[name] !== undefined) continue
+			if (posArgs[i] === undefined) continue
+
+			// Last positional collects all remaining args if the schema expects an array
+			if (i === positionals.length - 1 && posArgs.length > positionals.length) {
+				const isArray = this._schemaExpectsArray(Cls.argsSchema, name)
+				if (isArray) {
+					result[name] = posArgs.slice(i)
+					continue
+				}
+			}
+
+			result[name] = posArgs[i]
+		}
+
+		return result
+	}
+
+	/**
+	 * Check whether a Zod schema expects an array type for a given field.
+	 * Unwraps ZodObject → ZodOptional/ZodDefault/ZodNullable → ZodArray.
+	 */
+	private _schemaExpectsArray(schema: z.ZodType, field: string): boolean {
+		try {
+			const shape = typeof (schema as any)?._def?.shape === 'function'
+				? (schema as any)._def.shape()
+				: (schema as any)?._def?.shape
+			if (!shape || !shape[field]) return false
+			let inner = shape[field]
+			// Unwrap wrappers (optional, default, nullable)
+			while (inner) {
+				if (inner instanceof z.ZodArray) return true
+				if (inner._def?.innerType) { inner = inner._def.innerType; continue }
+				if (inner._def?.schema) { inner = inner._def.schema; continue }
+				break
+			}
+			return false
+		} catch {
+			return false
+		}
+	}
+
+	/**
+	 * Run the command with stdout/stderr capture for headless dispatch.
+	 * Returns a CommandRunResult with captured output.
+	 *
+	 * NOTE: Uses global console mutation — not safe for concurrent headless dispatches.
+	 * A future iteration should pass a logger through context instead.
+	 */
+	private async _runCaptured(args: any): Promise<CommandRunResult> {
+		const captured = { stdout: '', stderr: '' }
+		const origLog = console.log.bind(console)
+		const origErr = console.error.bind(console)
+
+		console.log = (...a: any[]) => { captured.stdout += a.join(' ') + '\n' }
+		console.error = (...a: any[]) => { captured.stderr += a.join(' ') + '\n' }
+
+		let exitCode = 0
+		try {
+			this.state.set('running', true)
+			this.emit('started')
+			await this.run(args, this.context)
+			this.state.set('exitCode', 0)
+			this.emit('completed', 0)
+		} catch (err: any) {
+			exitCode = 1
+			this.state.set('exitCode', 1)
+			this.emit('failed', err)
+			captured.stderr += (err?.message || String(err)) + '\n'
+		} finally {
+			console.log = origLog
+			console.error = origErr
+			this.state.set('running', false)
+		}
+
+		return { exitCode, stdout: captured.stdout, stderr: captured.stderr }
+	}
+
 	static attach(container: Container<any> & CommandsInterface) {
 		container.commands = commands
 
@@ -104,6 +266,10 @@ export class CommandsRegistry extends Registry<Command<any>> {
 	override scope = 'commands'
 	override baseClass = Command as any
 
+	/**
+	 * Internal: register a command from a handler function.
+	 * Used by built-in commands. External commands should use the module export pattern.
+	 */
 	registerHandler<T = any>(
 		name: string,
 		opts: {
@@ -112,27 +278,27 @@ export class CommandsRegistry extends Registry<Command<any>> {
 			handler: CommandHandler<T>
 		},
 	) {
-		const handler = opts.handler
-		const argsSchema = opts.argsSchema || CommandOptionsSchema
-		const desc = opts.description || ''
-
-		const CommandClass = class extends Command {
-			static override shortcut = `commands.${name}` as const
-			static override description = desc
-			static override commandDescription = desc
-			static override optionsSchema = argsSchema as any
-			static override argsSchema = argsSchema
-
-			override async execute() {
-				await handler(this.parseArgs(), this.context)
-			}
-		}
-
-		Object.defineProperty(CommandClass, 'name', { value: `${name}Command` })
+		const CommandClass = graftModule(
+			Command as any,
+			{
+				description: opts.description,
+				argsSchema: opts.argsSchema,
+				handler: opts.handler,
+			},
+			name,
+			'commands',
+		) as any
 
-		return this.register(name, CommandClass as any)
+		return this.register(name, CommandClass)
 	}
 
+	/**
+	 * Discover and register commands from a directory.
+	 * Detection order:
+	 *   1. Default export is a class extending Command → register directly
+	 *   2. Module exports a `run` function → graft as SimpleCommand
+	 *   3. Module exports a `handler` function → legacy graft
+	 */
 	async discover(options: { directory: string }) {
 		const { Glob } = globalThis.Bun || (await import('bun'))
 		const glob = new Glob('*.ts')
@@ -140,19 +306,53 @@ export class CommandsRegistry extends Registry<Command<any>> {
 		for await (const file of glob.scan({ cwd: options.directory })) {
 			if (file === 'index.ts') continue
 
+			const name = file.replace(/\.ts$/, '')
+			if (this.has(name)) continue
+
 			const mod = await import(join(options.directory, file))
+
+			// 1. Class-based: default export extends Command
+			if (isNativeHelperClass(mod.default, Command)) {
+				const ExportedClass = mod.default
+				if (!ExportedClass.shortcut || ExportedClass.shortcut === 'commands.base') {
+					ExportedClass.shortcut = `commands.${name}`
+				}
+				if (!ExportedClass.commandDescription && ExportedClass.description) {
+					ExportedClass.commandDescription = ExportedClass.description
+				}
+				this.register(name, ExportedClass)
+				continue
+			}
+
 			const commandModule = mod.default || mod
 
-			// Support export-based command files (like endpoints).
-			// If the module exports a handler function, register it
-			// using the filename as the command name.
-			if (typeof commandModule.handler === 'function' && !this.has(file.replace(/\.ts$/, ''))) {
-				const name = file.replace(/\.ts$/, '')
-				this.registerHandler(name, {
-					description: commandModule.description || '',
+			// 2. Module-based with `run` export (new SimpleCommand pattern)
+			if (typeof commandModule.run === 'function') {
+				const Grafted = graftModule(Command as any, commandModule, name, 'commands')
+				this.register(name, Grafted as any)
+				continue
+			}
+
+			// 3. Legacy: `handler` export
+			if (typeof commandModule.handler === 'function') {
+				const Grafted = graftModule(Command as any, {
+					description: commandModule.description,
 					argsSchema: commandModule.argsSchema,
 					handler: commandModule.handler,
-				})
+				}, name, 'commands')
+				this.register(name, Grafted as any)
+				continue
+			}
+
+			// 4. Plain default-exported function: export default async function name(options, context)
+			if (typeof mod.default === 'function' && !isNativeHelperClass(mod.default, Command)) {
+				const Grafted = graftModule(Command as any, {
+					description: mod.description || '',
+					argsSchema: mod.argsSchema,
+					positionals: mod.positionals,
+					handler: mod.default,
+				}, name, 'commands')
+				this.register(name, Grafted as any)
 			}
 		}
 	}
@@ -161,4 +361,51 @@ export class CommandsRegistry extends Registry<Command<any>> {
 export const commands = new CommandsRegistry()
 export const helperCache = new Map()
 
+/**
+ * Self-register a Command subclass from a static initialization block.
+ * Mirrors Feature.register / Client.register / Server.register pattern.
+ *
+ * @example
+ * ```typescript
+ * export class DeployCommand extends Command {
+ *   static override description = 'Deploy to production'
+ *   static override argsSchema = deployArgsSchema
+ *   static override positionals = ['environment']
+ *   static { Command.register(this, 'deploy') }
+ *
+ *   override async run(args, context) { ... }
+ * }
+ * ```
+ */
+Command.register = function registerCommand(
+	SubClass: typeof Command,
+	id?: string,
+) {
+	const registryId = id ?? (SubClass.name
+		? SubClass.name[0]!.toLowerCase() + SubClass.name.slice(1).replace(/Command$/, '')
+		: `command_${Date.now()}`)
+
+	if (!Object.getOwnPropertyDescriptor(SubClass, 'shortcut')?.value ||
+		(SubClass as any).shortcut === 'commands.base') {
+		;(SubClass as any).shortcut = `commands.${registryId}`
+	}
+
+	if (!(SubClass as any).commandDescription && (SubClass as any).description) {
+		;(SubClass as any).commandDescription = (SubClass as any).description
+	}
+
+	commands.register(registryId, SubClass as any)
+
+	if (!Object.getOwnPropertyDescriptor(SubClass, 'attach')) {
+		;(SubClass as any).attach = (container: any) => {
+			commands.register(registryId, SubClass as any)
+			return container
+		}
+	}
+
+	return SubClass
+}
+
+export { graftModule, isNativeHelperClass } from './graft.js'
+
 export default Command

package/src/commands/bootstrap.ts

@@ -0,0 +1,185 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import { bootstrapFiles, bootstrapTemplates } from '../bootstrap/generated.js'
+import { apiDocs } from './save-api-docs.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)'),
+})
+
+async function bootstrap(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const { container } = context
+	const args = container.argv._ as string[]
+	const outputDir = container.paths.resolve(args[1] || options.output)
+	const fs = container.feature('fs')
+	const ui = container.feature('ui')
+	const proc = container.feature('proc')
+
+	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')
+
+	ui.print.cyan('  Generating API docs...')
+	const apiDocsPath = container.paths.resolve(skillDir, 'references', 'api-docs')
+	await apiDocs({ _: [], outputPath: apiDocsPath }, context)
+
+	// ── 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 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

@@ -12,7 +12,7 @@ declare module '../command.js' {
 
 export const argsSchema = CommandOptionsSchema.extend({
 	model: z.string().optional().describe('Override the LLM model for the assistant'),
-	folder: z.string().default('assistants').describe('Directory containing assistant definitions'),
+	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'),
@@ -23,14 +23,14 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 	const container = context.container as any
 	const ui = container.feature('ui')
 
-	const manager = container.feature('assistantsManager', { folder: options.folder })
-	manager.discover()
+	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 an assistant directory in "${options.folder}/" with a CORE.md file.`))
+		console.error(ui.colors.dim(`  Create a directory with a CORE.md file anywhere in the project.`))
 		process.exit(1)
 	}
 
@@ -68,6 +68,7 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 
 	const createOptions: Record<string, any> = { historyMode }
 	if (options.model) createOptions.model = options.model
+	if (options.local) createOptions.local = options.local
 
 	const assistant = manager.create(name, createOptions)