luca 1.1.2 → 3.0.0

package/src/commands/scaffold.ts

@@ -0,0 +1,225 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import { scaffolds, assistantFiles } from '../scaffolds/generated.js'
+import { generateScaffold, toCamelCase, toKebabCase } from '../scaffolds/template.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		scaffold: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+const validTypes = [...Object.keys(scaffolds), 'assistant']
+
+export const argsSchema = CommandOptionsSchema.extend({
+	description: z.string().optional().describe('Brief description of the helper'),
+	output: z.string().optional().describe('Output file path (overrides default location)'),
+	print: z.boolean().default(false).describe('Print the generated code to stdout instead of writing a file'),
+	tutorial: z.boolean().default(false).describe('Show the full tutorial instead of generating code'),
+})
+
+const TYPE_INFO: Record<string, { what: string; where: string; run: string }> = {
+	feature: {
+		what: 'A container-managed capability (caching, encryption, custom I/O)',
+		where: 'features/<name>.ts',
+		run: 'container.feature(\'<name>\') in any command, endpoint, or script',
+	},
+	client: {
+		what: 'A connection to an external service (REST API, WebSocket, GraphQL)',
+		where: 'clients/<name>.ts',
+		run: 'container.client(\'<name>\') in any command, endpoint, or script',
+	},
+	server: {
+		what: 'A listener accepting incoming connections (HTTP, WebSocket, custom protocol)',
+		where: 'servers/<name>.ts',
+		run: 'container.server(\'<name>\') then .start()',
+	},
+	command: {
+		what: 'A CLI task that extends `luca` (build scripts, generators, automation)',
+		where: 'commands/<name>.ts',
+		run: 'luca <name>',
+	},
+	endpoint: {
+		what: 'A REST API route auto-discovered by `luca serve`',
+		where: 'endpoints/<name>.ts',
+		run: 'luca serve → GET/POST /api/<name>',
+	},
+	selector: {
+		what: 'A cached data query — returns structured results from the container',
+		where: 'selectors/<name>.ts',
+		run: 'luca select <name> or container.select(\'<name>\')',
+	},
+	assistant: {
+		what: 'An AI assistant with a system prompt, tools, and lifecycle hooks',
+		where: 'assistants/<name>/',
+		run: 'luca chat <name>',
+	},
+}
+
+export default async function scaffoldCommand(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const args = container.argv._ as string[]
+	const ui = container.feature('ui')
+
+	// args: ["scaffold", type?, name?]
+	const type = args[1]
+	const name = args[2]
+
+	// ── No type or invalid type: show full help ──────────────────
+	if (!type || !validTypes.includes(type)) {
+		ui.print.cyan('\n  luca scaffold — generate boilerplate for luca helpers\n')
+		ui.print('  Usage:  luca scaffold <type> <name> [options]\n')
+		ui.print('  Options:')
+		ui.print('    --description "..."   Brief description (shows in help text and docs)')
+		ui.print('    --output <path>       Override the default output file path')
+		ui.print('    --print               Print to stdout instead of writing a file')
+		ui.print('    --tutorial            Show the full guide for a type instead of generating code\n')
+
+		ui.print('  Types:\n')
+		for (const [t, info] of Object.entries(TYPE_INFO)) {
+			ui.print.green(`    ${t}`)
+			ui.print(`      ${info.what}`)
+			ui.print.dim(`      File: ${info.where}  →  Run: ${info.run}`)
+			ui.print('')
+		}
+
+		ui.print('  Examples:\n')
+		ui.print('    # Generate a command (writes to commands/deploy.ts)')
+		ui.print('    luca scaffold command deploy --description "Deploy to production"\n')
+		ui.print('    # Generate a feature (writes to features/disk-cache.ts)')
+		ui.print('    luca scaffold feature disk-cache --description "File-backed key-value cache"\n')
+		ui.print('    # Print to stdout instead of writing')
+		ui.print('    luca scaffold endpoint users --print\n')
+		ui.print('    # Read the full tutorial for a type')
+		ui.print('    luca scaffold feature --tutorial')
+		ui.print('    luca scaffold endpoint --tutorial\n')
+
+		ui.print('  Workflow:\n')
+		ui.print('    1. luca scaffold <type> <name>    Generate the file')
+		ui.print('    2. Edit the generated file — add your logic')
+		ui.print('    3. luca about                     Verify it was discovered')
+		ui.print('    4. luca describe <name>           See the generated docs\n')
+
+		if (type && !validTypes.includes(type)) {
+			ui.print.yellow(`  "${type}" is not a valid type. Available: ${validTypes.join(', ')}\n`)
+		}
+		return
+	}
+
+	// ── Tutorial mode ────────────────────────────────────────────
+	if (options.tutorial) {
+		const scaffold = scaffolds[type]
+		if (scaffold?.tutorial) {
+			console.log(ui.markdown(scaffold.tutorial))
+		} else {
+			ui.print.yellow(`No tutorial available for type: ${type}`)
+		}
+		return
+	}
+
+	// ── Missing name ─────────────────────────────────────────────
+	if (!name) {
+		const info = TYPE_INFO[type]
+		ui.print.cyan(`\n  luca scaffold ${type} <name> [options]\n`)
+		ui.print(`  ${info?.what || ''}\n`)
+		ui.print('  Examples:')
+		if (type === 'feature') {
+			ui.print(`    luca scaffold feature diskCache --description "File-backed cache"`)
+			ui.print(`    luca scaffold feature diskCache --output features/diskCache.ts`)
+		} else if (type === 'client') {
+			ui.print(`    luca scaffold client github --description "GitHub API client"`)
+			ui.print(`    luca scaffold client github --output clients/github.ts`)
+		} else if (type === 'server') {
+			ui.print(`    luca scaffold server grpc --description "gRPC server"`)
+			ui.print(`    luca scaffold server grpc --output servers/grpc.ts`)
+		} else if (type === 'command') {
+			ui.print(`    luca scaffold command deploy --description "Deploy to production"`)
+			ui.print(`    luca scaffold command deploy --output commands/deploy.ts`)
+		} else if (type === 'endpoint') {
+			ui.print(`    luca scaffold endpoint users --description "User management API"`)
+			ui.print(`    luca scaffold endpoint users --output endpoints/users.ts`)
+		} else if (type === 'selector') {
+			ui.print(`    luca scaffold selector package-info --description "Returns parsed package.json data"`)
+			ui.print(`    luca scaffold selector package-info --output selectors/package-info.ts`)
+		} else if (type === 'assistant') {
+			ui.print(`    luca scaffold assistant chief-of-staff`)
+			ui.print(`    luca scaffold assistant chief-of-staff --output assistants/chief-of-staff`)
+		}
+		ui.print(`\n    luca scaffold ${type} --tutorial    Full guide with patterns and conventions\n`)
+		return
+	}
+
+	// ── Assistant: multi-file scaffold ───────────────────────────
+	if (type === 'assistant') {
+		if (!assistantFiles || Object.keys(assistantFiles).length === 0) {
+			ui.print.yellow('No assistant scaffold files bundled. Rebuild with: luca build-scaffolds')
+			return
+		}
+
+		const outputDir = options.output || `assistants/${toCamelCase(name)}`
+		const fs = container.feature('fs')
+		const resolvedDir = container.paths.resolve(outputDir)
+
+		await fs.ensureFolder(resolvedDir)
+
+		for (const [fileName, content] of Object.entries(assistantFiles)) {
+			const filePath = container.paths.resolve(resolvedDir, fileName)
+			await fs.writeFileAsync(filePath, content)
+		}
+
+		ui.print.green(`\n  ✓ Scaffolded assistant "${name}" in ${outputDir}/`)
+		ui.print.dim(`    CORE.md   — system prompt (edit this to define your assistant's personality)`)
+		ui.print.dim(`    tools.ts  — tool functions the assistant can call`)
+		ui.print.dim(`    hooks.ts  — lifecycle event handlers`)
+		ui.print(`\n  Start chatting:  luca chat ${name}\n`)
+		return
+	}
+
+	const code = generateScaffold(type, name, options.description)
+
+	if (!code) {
+		ui.print.yellow(`No scaffold template available for type: ${type}`)
+		return
+	}
+
+	// --print: just output to stdout
+	if (options.print) {
+		console.log(code)
+		return
+	}
+
+	// Default: write to file
+	const kebabName = toKebabCase(name)
+	const defaultPaths: Record<string, string> = {
+		feature: `features/${kebabName}.ts`,
+		client: `clients/${kebabName}.ts`,
+		server: `servers/${kebabName}.ts`,
+		command: `commands/${kebabName}.ts`,
+		endpoint: `endpoints/${kebabName}.ts`,
+		selector: `selectors/${kebabName}.ts`,
+	}
+	const outputPath = options.output || defaultPaths[type] || `${type}s/${kebabName}.ts`
+	const fs = container.feature('fs')
+	const resolvedPath = container.paths.resolve(outputPath)
+
+	// Check if file already exists
+	if (await fs.existsAsync(resolvedPath)) {
+		ui.print.yellow(`  ✗ File already exists: ${outputPath}`)
+		ui.print.dim(`  Use --output <path> to write to a different location, or --print to view the code\n`)
+		return
+	}
+
+	const dir = container.paths.resolve(outputPath, '..')
+	await fs.ensureFolder(dir)
+	await fs.writeFileAsync(resolvedPath, code)
+	ui.print.green(`  ✓ Wrote ${type} scaffold to ${outputPath}`)
+	ui.print.dim(`  Next: edit the file, then run \`luca about\` to verify discovery\n`)
+}
+
+commands.registerHandler('scaffold', {
+	description: 'Generate boilerplate for a new luca feature, client, server, command, endpoint, or assistant',
+	argsSchema,
+	handler: scaffoldCommand,
+})

package/src/commands/select.ts

@@ -0,0 +1,99 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { selectors } from '../selector.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		select: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	json: z.boolean().default(false).describe('Output result as raw JSON (data only, no metadata)'),
+	noCache: z.boolean().default(false).describe('Skip cache lookup and force a fresh run'),
+}).passthrough()
+
+export default async function selectCommand(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const ui = container.feature('ui')
+	const args = container.argv._ as string[]
+	const name = args[1]
+
+	// Discover project selectors
+	await container.helpers.discoverAll()
+
+	if (!name) {
+		const available = selectors.available
+		if (available.length === 0) {
+			ui.print('No selectors available.')
+			ui.print.dim('Create one: luca scaffold selector <name>')
+		} else {
+			ui.print.cyan('\n  luca select <name> [--json] [--no-cache]\n')
+			ui.print('  Available selectors:\n')
+			for (const s of available) {
+				ui.print.green(`    ${s}`)
+			}
+			ui.print('')
+		}
+		return
+	}
+
+	const instance = container.select(name)
+
+	// Pass remaining args (after command name and selector name) as input.
+	// Pull from container.argv directly — the select command's own argsSchema
+	// would otherwise strip selector-specific keys during Zod parse.
+	const rawArgv = { ...(container as any).argv }
+	const selectorArgs: Record<string, any> = { ...rawArgv }
+	delete selectorArgs._
+	delete selectorArgs.json
+	delete selectorArgs.noCache
+	delete selectorArgs.cache
+	delete selectorArgs.dispatchSource
+	delete selectorArgs.help
+	delete selectorArgs.name
+
+	// minimist turns --no-cache into { cache: false }
+	const skipCache = options.noCache || (container.argv.cache === false)
+
+	if (skipCache) {
+		// Bypass cache by calling run() directly with proper lifecycle
+		const Cls = instance.constructor as any
+		const parsed = Cls.argsSchema.parse(selectorArgs)
+		instance.state.set('running', true)
+		instance.emit('started')
+		let data: any
+		try {
+			data = await instance.run(parsed, instance.context)
+			instance.state.set('running', false)
+			instance.state.set('lastRanAt', Date.now())
+			instance.emit('completed', data)
+		} catch (err: any) {
+			instance.state.set('running', false)
+			instance.emit('failed', err)
+			throw err
+		}
+		if (options.json) {
+			console.log(JSON.stringify(data, null, 2))
+		} else {
+			console.log(JSON.stringify({ data, cached: false }, null, 2))
+		}
+		return
+	}
+
+	const result = await instance.select(selectorArgs)
+
+	if (options.json) {
+		console.log(JSON.stringify(result.data, null, 2))
+	} else {
+		console.log(JSON.stringify(result, null, 2))
+	}
+}
+
+commands.registerHandler('select', {
+	description: 'Run a selector and display its cached or fresh data',
+	argsSchema,
+	handler: selectCommand,
+})

package/src/commands/serve.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod'
+import { commands } from '../command.js'
+import { CommandOptionsSchema } from '../schemas/base.js'
+import type { ContainerContext } from '../container.js'
+import type { ExpressServer } from '../servers/express.js'
+
+declare module '../command.js' {
+	interface AvailableCommands {
+		serve: ReturnType<typeof commands.registerHandler>
+	}
+}
+
+export const argsSchema = CommandOptionsSchema.extend({
+	port: z.number().default(3000).describe('Port to listen on'),
+	endpointsDir: z.string().optional().describe('Directory to load endpoints from'),
+	staticDir: z.string().optional().describe('Directory to serve static files from'),
+	setup: z.string().optional().describe('Path to a TS module whose default export receives the server instance'),
+	cors: z.boolean().default(true).describe('Enable CORS'),
+	force: z.boolean().default(false).describe('Kill any process currently using the target port'),
+	anyPort: z.boolean().default(false).describe('Find an available port starting above 3000'),
+	open: z.boolean().default(true).describe('Open the server URL in Google Chrome'),
+	watch: z.boolean().default(false).describe('Watch endpoint files and hot-reload handlers on change'),
+})
+
+export default async function serve(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const { fs, paths, manifest, networking, proc } = container
+
+	let port = options.port
+	const staticDir = options.staticDir ? paths.resolve(options.staticDir) : paths.resolve('public')
+
+	if (options.anyPort) {
+		port = await networking.findOpenPort(3001)
+	}
+
+	const isPortAvailable = await networking.isPortOpen(port)
+	if (!isPortAvailable) {
+		if (!options.force) {
+			console.error(`Port ${port} is already in use.`)
+			console.error(`Use --force to kill the process on this port, or --any-port to find another port.`)
+			process.exit(1)
+		}
+
+		const pids = proc.findPidsByPort(port)
+		if (!pids.length) {
+			console.error(`Port ${port} is in use, but no PID could be discovered for termination.`)
+			process.exit(1)
+		}
+
+		for (const pid of pids) {
+			proc.kill(pid)
+		}
+
+		let portFreed = false
+		for (let i = 0; i < 10; i++) {
+			if (await networking.isPortOpen(port)) {
+				portFreed = true
+				break
+			}
+			await new Promise((resolve) => setTimeout(resolve, 100))
+		}
+
+		if (!portFreed) {
+			console.error(`Failed to free port ${port} after terminating process(es): ${pids.join(', ')}`)
+			process.exit(1)
+		}
+	}
+
+	// Discover the endpoints directory from the project root.
+	// Checks explicit flag, then common conventions, then skips if absent.
+	const endpointsDir = resolveEndpointsDir(options, fs, paths)
+
+	// Resolve static directory: explicit flag > public/ > cwd (if index.html exists)
+	let resolvedStaticDir: string | undefined
+	if (fs.exists(staticDir)) {
+		resolvedStaticDir = staticDir
+	} else if (fs.exists(paths.resolve('index.html'))) {
+		resolvedStaticDir = paths.resolve('.')
+	}
+
+	// If there's nothing to serve at all, bail out.
+	if (!endpointsDir && !resolvedStaticDir) {
+		console.error(`Can't figure out what to serve in this folder.`)
+		console.error(`Expected one of: endpoints/, src/endpoints/, public/, or an index.html in the current directory.`)
+		process.exit(1)
+	}
+
+	const expressServer = container.server('express', {
+		port,
+		cors: options.cors,
+		static: resolvedStaticDir,
+		historyFallback: resolvedStaticDir && !options.staticDir,
+	}) as ExpressServer
+
+	if (endpointsDir) {
+		await expressServer.useEndpoints(endpointsDir)
+
+		expressServer.serveOpenAPISpec({
+			title: manifest.name || 'API',
+			version: manifest.version || '0.0.0',
+			description: manifest.description || '',
+		})
+	}
+
+	if (options.setup) {
+		const setupPath = paths.resolve(options.setup)
+		if (!fs.exists(setupPath)) {
+			console.error(`Setup module not found: ${setupPath}`)
+			process.exit(1)
+		}
+		const vmFeature = container.feature('vm')
+		const mod = vmFeature.loadModule(setupPath, { server: expressServer })
+		const setupFn = mod.default || mod
+		if (typeof setupFn === 'function') {
+			await setupFn(expressServer)
+		}
+	}
+
+	try {
+		await expressServer.start({ port })
+	} catch (error: any) {
+		if (error?.code === 'EADDRINUSE') {
+			console.error(`Port ${port} is already in use.`)
+			console.error(`Use --force to kill the process on this port, or --any-port to find another port.`)
+			process.exit(1)
+		}
+		throw error
+	}
+
+	const name = manifest.name || 'Server'
+	console.log(`\n${name} listening on http://localhost:${port}`)
+
+	if (endpointsDir) {
+		console.log(`OpenAPI spec at http://localhost:${port}/openapi.json`)
+	}
+
+	if (options.open) {
+		try {
+			const opener = container.feature('opener')
+			await opener.open(`http://localhost:${port}`)
+		} catch (error) {
+			console.warn(`Could not open browser automatically: ${(error as Error).message}`)
+		}
+	}
+
+	if (resolvedStaticDir) {
+		console.log(`\nStatic files from ${resolvedStaticDir}`)
+	}
+
+	if (endpointsDir) {
+		if (expressServer._mountedEndpoints.length) {
+			console.log(`\nEndpoints:`)
+			for (const ep of expressServer._mountedEndpoints) {
+				console.log(`  ${ep.methods.map((m: string) => m.toUpperCase()).join(', ').padEnd(20)} ${ep.path}`)
+			}
+		} else {
+			console.log(`\nNo endpoints found in ${endpointsDir}`)
+		}
+	}
+
+	if (options.watch && endpointsDir) {
+		const fm = container.feature('fileManager')
+		await fm.watch({ paths: [endpointsDir] })
+
+		fm.on('file:change', async ({ type, path: filePath }: { type: string; path: string }) => {
+			if (!filePath.endsWith('.ts')) return
+
+			if (type === 'change') {
+				try {
+					const ep = await expressServer.reloadEndpoint(filePath)
+					if (ep) {
+						console.log(`[watch] Reloaded ${ep.methods.map((m: string) => m.toUpperCase()).join(',')} ${ep.path}`)
+					}
+				} catch (err: any) {
+					console.error(`[watch] Failed to reload ${filePath}: ${err.message}`)
+				}
+			} else if (type === 'add') {
+				console.log(`[watch] New file detected: ${filePath} (restart to mount)`)
+			} else if (type === 'delete') {
+				console.log(`[watch] File deleted: ${filePath} (restart to unmount)`)
+			}
+		})
+
+		console.log(`\n[watch] Watching ${endpointsDir} for changes`)
+	}
+
+	console.log()
+}
+
+function resolveEndpointsDir(options: any, fs: any, paths: any): string | null {
+	if (options.endpointsDir) {
+		const dir = paths.resolve(options.endpointsDir)
+		return fs.exists(dir) ? dir : null
+	}
+
+	for (const candidate of ['endpoints', 'src/endpoints']) {
+		const dir = paths.resolve(candidate)
+		if (fs.exists(dir)) return dir
+	}
+
+	return null
+}
+
+commands.registerHandler('serve', {
+	description: 'Start the API server with file-based endpoints',
+	argsSchema,
+	handler: serve,
+})