@soederpop/luca 0.0.5 → 0.0.7

package/src/commands/scaffold.ts

@@ -2,8 +2,8 @@ import { z } from 'zod'
 import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
-import { scaffolds } from '../scaffolds/generated.js'
-import { generateScaffold, toCamelCase } from '../scaffolds/template.js'
+import { scaffolds, assistantFiles } from '../scaffolds/generated.js'
+import { generateScaffold, toCamelCase, toKebabCase } from '../scaffolds/template.js'
 
 declare module '../command.js' {
 	interface AvailableCommands {
@@ -11,69 +11,215 @@ declare module '../command.js' {
 	}
 }
 
-const validTypes = Object.keys(scaffolds)
+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 (defaults to stdout)'),
+	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)) {
-		console.log(`Usage: luca scaffold <type> <name> [--description "..."] [--output path] [--tutorial]`)
-		console.log(`\nTypes: ${validTypes.join(', ')}`)
-		console.log(`\nExamples:`)
-		console.log(`  luca scaffold feature diskCache --description "File-backed key-value cache"`)
-		console.log(`  luca scaffold command deploy --output commands/deploy.ts`)
-		console.log(`  luca scaffold endpoint healthCheck`)
-		console.log(`  luca scaffold feature --tutorial`)
+		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 — show the full scaffold doc
+	// ── Tutorial mode ────────────────────────────────────────────
 	if (options.tutorial) {
 		const scaffold = scaffolds[type]
 		if (scaffold?.tutorial) {
-			const ui = container.feature('ui')
 			console.log(ui.markdown(scaffold.tutorial))
 		} else {
-			console.log(`No tutorial available for type: ${type}`)
+			ui.print.yellow(`No tutorial available for type: ${type}`)
 		}
 		return
 	}
 
+	// ── Missing name ─────────────────────────────────────────────
 	if (!name) {
-		console.log(`Usage: luca scaffold ${type} <name> [--description "..."] [--output path]`)
+		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) {
-		console.log(`No scaffold template available for type: ${type}`)
+		ui.print.yellow(`No scaffold template available for type: ${type}`)
 		return
 	}
 
-	// Write to file or stdout
-	if (options.output) {
-		const fs = container.feature('fs')
-		await fs.writeFileAsync(options.output, code)
-		console.log(`Wrote ${type} scaffold to ${options.output}`)
-	} else {
+	// --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, or endpoint',
+	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,94 @@
+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'),
+})
+
+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
+	const selectorArgs: Record<string, any> = { ...options }
+	delete selectorArgs._
+	delete selectorArgs.json
+	delete selectorArgs.noCache
+	delete selectorArgs.cache
+	delete selectorArgs.dispatchSource
+
+	// 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

@@ -115,7 +115,16 @@ export default async function serve(options: z.infer<typeof argsSchema>, context
 		}
 	}
 
-	await expressServer.start({ port })
+	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}`)

package/src/container.ts

@@ -629,6 +629,21 @@ function presentContainerIntrospectionAsMarkdown(data: ContainerIntrospection, s
     // Header
     sections.push(`${heading(1)} ${data.className}\n\n${data.description || ''}`)
 
+    // Container Properties section (node containers expose these top-level getters)
+    if (data.environment?.isNode || data.environment?.isBun) {
+      sections.push([
+        `${heading(2)} Container Properties`,
+        '',
+        '| Property | Description |',
+        '|----------|-------------|',
+        '| `container.cwd` | Current working directory |',
+        '| `container.paths` | Path utilities scoped to cwd: `resolve()`, `join()`, `relative()`, `dirname()`, `basename()`, `parse()` |',
+        '| `container.manifest` | Parsed `package.json` for the current directory (`name`, `version`, `dependencies`, etc.) |',
+        '| `container.argv` | Raw parsed CLI arguments (from minimist). Prefer `positionals` export for positional args in commands |',
+        '| `container.utils` | Common utilities: `uuid()`, `hashObject()`, `stringUtils`, `lodash` |',
+      ].join('\n'))
+    }
+
     // Registries section
     if (data.registries && data.registries.length > 0) {
       sections.push(`${heading(2)} Registries`)

package/src/endpoint.ts

@@ -56,6 +56,14 @@ export interface EndpointModule {
 
 const HTTP_METHODS = ['get', 'post', 'put', 'patch', 'delete'] as const
 
+/** All recognized exports on an endpoint module */
+const KNOWN_EXPORTS = new Set([
+  'path', 'description', 'tags', 'default', 'rateLimit',
+  ...HTTP_METHODS,
+  ...HTTP_METHODS.map(m => `${m}Schema`),
+  ...HTTP_METHODS.map(m => `${m}RateLimit`),
+])
+
 /**
  * Sliding-window rate limiter keyed by IP address.
  * Tracks timestamps of requests and prunes entries older than the window.
@@ -177,6 +185,10 @@ export class Endpoint<
       this._module = imported.default || imported
     }
 
+    // Note: DELETE handlers should be exported as `export { del as delete }`.
+    // We no longer remap `destroy` → `delete` because ESM namespace objects
+    // are frozen and the mutation throws on Bun.
+
     this.state.set('methods', this.methods)
     this.state.set('path', this.path)
     this.emit('loaded', this._module)
@@ -328,6 +340,13 @@ export class Endpoint<
   }
 }
 
+export function warnUnknownExports(mod: Record<string, any>, filePath: string): void {
+  const unknown = Object.keys(mod).filter(k => !k.startsWith('__') && !KNOWN_EXPORTS.has(k))
+  if (unknown.length > 0) {
+    console.warn(`[endpoint] ${filePath}: unknown exports: ${unknown.join(', ')}`)
+  }
+}
+
 export class EndpointsRegistry extends Registry<Endpoint<any>> {
   override scope = 'endpoints'
   override baseClass = Endpoint

package/src/graft.ts

@@ -0,0 +1,181 @@
+import { Helper } from './helper.js'
+import { z } from 'zod'
+
+export type GraftScope = 'features' | 'clients' | 'servers' | 'commands' | 'endpoints' | 'selectors'
+
+/**
+ * Export names that map to static class properties or receive special handling.
+ * Everything else that is a function goes onto the prototype as a method.
+ */
+const RESERVED_EXPORTS = new Set([
+	'description', 'envVars',
+	'stateSchema', 'optionsSchema', 'eventsSchema',
+	'args', 'argsSchema',
+	'positionals',
+	'getters',
+	'run', 'handler',
+	'cacheKey', 'cacheable',
+	'default',
+])
+
+/**
+ * Returns true when the candidate is a class (constructor function) whose
+ * prototype chain includes BaseClass. Handles cross-module-boundary cases
+ * by checking both reference equality and class name.
+ */
+export function isNativeHelperClass(candidate: unknown, BaseClass: typeof Helper | any): boolean {
+	if (typeof candidate !== 'function') return false
+	if (!BaseClass) return false
+	if (candidate === BaseClass) return true
+
+	let proto = Object.getPrototypeOf(candidate)
+	while (proto) {
+		if (proto === BaseClass) return true
+		if (BaseClass.name && proto.name === BaseClass.name) return true
+		proto = Object.getPrototypeOf(proto)
+	}
+	return false
+}
+
+/**
+ * Synthesize a Helper subclass from plain module exports.
+ *
+ * Given a set of exports from a module file and a Helper base class, produces a
+ * fully-formed subclass ready for registration in the appropriate registry.
+ *
+ * Static export mappings:
+ *   description   → static description
+ *   stateSchema   → static stateSchema
+ *   optionsSchema → static optionsSchema  (also aliased from `args`)
+ *   eventsSchema  → static eventsSchema
+ *   envVars       → static envVars
+ *   argsSchema    → static argsSchema (Command scope; also aliased from `args`)
+ *   positionals   → static positionals (Command scope; stored for CLI dispatch mapping)
+ *   getters       → Object.defineProperty(proto, key, { get })  per key
+ *   run           → override run() for Command scope (receives named args + context)
+ *   handler       → legacy: wired through parseArgs() for backward compat
+ *   [fn exports]  → prototype methods (all other function-valued named exports)
+ */
+export function graftModule<T extends typeof Helper>(
+	BaseClass: T,
+	moduleExports: Record<string, any>,
+	id: string,
+	scope: GraftScope,
+): T {
+	// Resolve schemas — prefer explicit exports, fall back to whatever the base class has
+	const optionsSchema = moduleExports.optionsSchema
+		?? moduleExports.args
+		?? (BaseClass as any).optionsSchema
+
+	const stateSchema = moduleExports.stateSchema
+		?? (BaseClass as any).stateSchema
+
+	const eventsSchema = moduleExports.eventsSchema
+		?? (BaseClass as any).eventsSchema
+
+	// Build the subclass
+	const GraftedClass = class extends (BaseClass as any) {} as unknown as T & { prototype: any }
+
+	// Static overrides
+	const statics: Record<string, any> = {
+		shortcut: `${scope}.${id}`,
+		description: moduleExports.description ?? '',
+	}
+
+	if (moduleExports.envVars) statics.envVars = moduleExports.envVars
+	if (optionsSchema) statics.optionsSchema = optionsSchema
+	if (stateSchema) statics.stateSchema = stateSchema
+	if (eventsSchema) statics.eventsSchema = eventsSchema
+
+	// Command-specific statics
+	if (scope === 'commands') {
+		const argsSchema = moduleExports.argsSchema ?? moduleExports.args ?? optionsSchema
+		statics.argsSchema = argsSchema
+		statics.commandDescription = moduleExports.description ?? ''
+		if (moduleExports.positionals) {
+			statics.positionals = moduleExports.positionals
+		}
+	}
+
+	// Selector-specific statics (must be set before Object.assign)
+	if (scope === 'selectors') {
+		statics.cacheable = moduleExports.cacheable !== false
+		statics.selectorDescription = moduleExports.description ?? ''
+		statics.argsSchema = moduleExports.argsSchema ?? moduleExports.args ?? optionsSchema
+	}
+
+	Object.assign(GraftedClass, statics)
+
+	// Wire run() for Command scope
+	if (scope === 'commands') {
+		if (typeof moduleExports.run === 'function') {
+			const runFn = moduleExports.run
+			;(GraftedClass as any).prototype.run = async function (args: any, context: any) {
+				return runFn(args, context)
+			}
+		} else if (typeof moduleExports.handler === 'function') {
+			const handlerFn = moduleExports.handler
+			;(GraftedClass as any).prototype.run = async function (args: any, context: any) {
+				return handlerFn(args, context)
+			}
+		}
+	}
+
+	// Wire run() and resolveCacheKey() for Selector scope
+	if (scope === 'selectors') {
+		if (typeof moduleExports.run === 'function') {
+			const runFn = moduleExports.run
+			;(GraftedClass as any).prototype.run = async function (args: any, context: any) {
+				return runFn(args, context)
+			}
+		}
+
+		if (typeof moduleExports.cacheKey === 'function') {
+			const cacheKeyFn = moduleExports.cacheKey
+			;(GraftedClass as any).prototype.resolveCacheKey = function (args: any, context: any) {
+				return cacheKeyFn(args, context)
+			}
+		}
+	}
+
+	// Install getters from the `getters` export
+	const getterMap: Record<string, () => any> = moduleExports.getters ?? {}
+	for (const [key, fn] of Object.entries(getterMap)) {
+		if (typeof fn === 'function') {
+			Object.defineProperty((GraftedClass as any).prototype, key, {
+				get: fn,
+				configurable: true,
+				enumerable: false,
+			})
+		}
+	}
+
+	// Graft all exported functions (that are not reserved) as prototype methods
+	for (const [key, value] of Object.entries(moduleExports)) {
+		if (RESERVED_EXPORTS.has(key)) continue
+		if (typeof value !== 'function') continue
+		;(GraftedClass as any).prototype[key] = value
+	}
+
+	// Name the class
+	const suffix = SCOPE_SUFFIXES[scope] || ''
+	const className = pascalCase(id) + suffix
+	Object.defineProperty(GraftedClass, 'name', { value: className, configurable: true })
+
+	return GraftedClass as T
+}
+
+const SCOPE_SUFFIXES: Record<string, string> = {
+	features: 'Feature',
+	clients: 'Client',
+	servers: 'Server',
+	commands: 'Command',
+	endpoints: 'Endpoint',
+	selectors: 'Selector',
+}
+
+function pascalCase(id: string): string {
+	return id
+		.replace(/[-_](.)/g, (_: string, c: string) => c.toUpperCase())
+		.replace(/^(.)/, (_: string, c: string) => c.toUpperCase())
+}