@soederpop/luca 0.0.23 → 0.0.25

package/src/cli/build-info.ts

@@ -0,0 +1,4 @@
+// Generated at compile time — do not edit manually
+export const BUILD_SHA = '33ebc12'
+export const BUILD_BRANCH = 'main'
+export const BUILD_DATE = '2026-03-22T06:53:18Z'

package/src/cli/cli.ts

@@ -1,11 +1,12 @@
 #!/usr/bin/env bun
 // @ts-ignore — bun resolves JSON imports at bundle time
 import pkg from '../../package.json'
+import { BUILD_SHA, BUILD_BRANCH, BUILD_DATE } from './build-info'
 
 // Fast-path flags that don't need the container
 const args = process.argv.slice(2)
 if (args.includes('--version') || args.includes('-v')) {
-	console.log(`luca v${pkg.version}`)
+	console.log(`luca v${pkg.version} (${BUILD_BRANCH}@${BUILD_SHA}) built ${BUILD_DATE}`)
 	console.log(`  npm: https://www.npmjs.com/package/@soederpop/luca`)
 	console.log(`  git: https://github.com/soederpop/luca`)
 	process.exit(0)

package/src/commands/bootstrap.ts

@@ -2,7 +2,7 @@ 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 { bootstrapFiles, bootstrapTemplates, bootstrapExamples, bootstrapTutorials } from '../bootstrap/generated.js'
 import { apiDocs } from './save-api-docs.js'
 import { generateScaffold } from '../scaffolds/template.js'
 
@@ -52,6 +52,21 @@ async function bootstrap(options: z.infer<typeof argsSchema>, context: Container
 	const apiDocsPath = container.paths.resolve(skillDir, 'references', 'api-docs')
 	await apiDocs({ _: [], outputPath: apiDocsPath }, context)
 
+	// ── 3b. examples and tutorials ─────────────────────────────────
+	const examplesDir = container.paths.resolve(skillDir, 'references', 'examples')
+	await fs.ensureFolder(examplesDir)
+	for (const [filename, content] of Object.entries(bootstrapExamples)) {
+		await fs.writeFileAsync(container.paths.resolve(examplesDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapExamples).length} example docs...`)
+
+	const tutorialsDir = container.paths.resolve(skillDir, 'references', 'tutorials')
+	await fs.ensureFolder(tutorialsDir)
+	for (const [filename, content] of Object.entries(bootstrapTutorials)) {
+		await fs.writeFileAsync(container.paths.resolve(tutorialsDir, filename), content)
+	}
+	ui.print.cyan(`  Writing ${Object.keys(bootstrapTutorials).length} tutorial docs...`)
+
 	// ── 4. docs/ folder ────────────────────────────────────────────
 	await fs.ensureFolder(mkPath('docs'))
 	await writeFile(fs, ui, mkPath('docs', 'models.ts'), bootstrapTemplates['docs-models'] || '', 'docs/models.ts')

package/src/commands/eval.ts

@@ -24,7 +24,12 @@ export default async function evalCommand(options: z.infer<typeof argsSchema>, c
 	
 	const args = container.argv._ as string[]
 	// args[0] is "eval", the rest is the code snippet
-	const code = args.slice(1).join(' ')
+	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]')

package/src/commands/sandbox-mcp.ts

@@ -42,11 +42,7 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 	const vmFeature = container.feature('vm')
 	const sandboxContext = vmFeature.createContext({
 		container,
-		console: {
-			log: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
-			error: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
-			warn: (...args: any[]) => args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' '),
-		},
+		console,
 		setTimeout,
 		setInterval,
 		clearTimeout,
@@ -154,8 +150,20 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 		}),
 		handler: async (args) => {
 			try {
-				const result = await vmFeature.run(args.code, sandboxContext)
+				const { result, console: calls } = await vmFeature.runCaptured(args.code, sandboxContext)
+
+				const content: Array<{ type: 'text', text: string }> = []
 
+				// Include captured console output if any
+				if (calls.length > 0) {
+					const consoleLines = calls.map(c => {
+						const prefix = c.method === 'log' ? '' : `[${c.method}] `
+						return prefix + c.args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a)).join(' ')
+					})
+					content.push({ type: 'text' as const, text: consoleLines.join('\n') })
+				}
+
+				// Include the result
 				let text: string
 				if (result === undefined) {
 					text = 'undefined'
@@ -173,7 +181,9 @@ export default async function mcpSandbox(options: z.infer<typeof argsSchema>, co
 					text = String(result)
 				}
 
-				return { content: [{ type: 'text' as const, text }] }
+				content.push({ type: 'text' as const, text })
+
+				return { content }
 			} catch (error: any) {
 				return {
 					content: [{ type: 'text' as const, text: `Error: ${error.message}\n\n${error.stack || ''}` }],

package/src/helper.ts

@@ -35,10 +35,12 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
   static stateSchema: z.ZodType = HelperStateSchema
   static optionsSchema: z.ZodType = HelperOptionsSchema
   static eventsSchema: z.ZodType = HelperEventsSchema
+  static tools: Record<string, { schema: z.ZodType, handler?: Function }> = {}
 
   protected readonly _context: ContainerContext
   protected readonly _events = new Bus<E>()
   protected readonly _options: K
+  protected readonly _instanceTools: Record<string, { schema: z.ZodType, handler?: Function }> = {}
 
   readonly state: State<T>
 
@@ -125,7 +127,7 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     this._context = context;
     this.state = new State<T>({ initialState: this.initialState });
     
-    this.hide('_context', '_state', '_options', '_events', 'uuid')
+    this.hide('_context', '_state', '_options', '_events', '_instanceTools', 'uuid')
     
     this.state.observe(() => {
       (this as any).emit('stateChange', this.state.current)
@@ -170,7 +172,7 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     return this
   }
   
-  /** 
+  /**
    * python / lodash style get method, which will get a value from the container using dot notation
    * and will return a default value if the value is not found.
   */
@@ -178,6 +180,58 @@ export abstract class Helper<T extends HelperState = HelperState, K extends Help
     return get(this, key, defaultValue)
   }
 
+  /**
+   * Register a tool on this instance at runtime. Instance tools take precedence
+   * over class-level static tools in toTools().
+   */
+  tool(name: string, options: { schema: z.ZodType, handler?: Function }): this {
+    this._instanceTools[name] = options
+    return this
+  }
+
+  /**
+   * Collect all tools from the inheritance chain and instance, returning
+   * { schemas, handlers } with matching keys. Walks the prototype chain
+   * so subclass tools override parent tools. Instance tools win over all.
+   *
+   * If a tool has no explicit handler but this instance has a method with
+   * the same name, a handler is auto-generated that delegates to that method.
+   */
+  toTools(): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
+    // Walk the prototype chain collecting static tools (parent-first, child overwrites)
+    const merged: Record<string, { schema: z.ZodType, handler?: Function }> = {}
+    const chain: Function[] = []
+
+    let current = this.constructor as any
+    while (current && current !== Object) {
+      if (Object.hasOwn(current, 'tools') && current.tools) {
+        chain.unshift(current)
+      }
+      current = Object.getPrototypeOf(current)
+    }
+
+    for (const ctor of chain) {
+      Object.assign(merged, (ctor as any).tools)
+    }
+
+    // Instance tools win over static
+    Object.assign(merged, this._instanceTools)
+
+    const schemas: Record<string, z.ZodType> = {}
+    const handlers: Record<string, Function> = {}
+
+    for (const [name, entry] of Object.entries(merged)) {
+      schemas[name] = entry.schema
+      if (entry.handler) {
+        handlers[name] = (args: any) => entry.handler!(args, this)
+      } else if (typeof (this as any)[name] === 'function') {
+        handlers[name] = (args: any) => (this as any)[name](args)
+      }
+    }
+
+    return { schemas, handlers }
+  }
+
   /** 
    * The options passed to the helper when it was created.
   */