@soederpop/luca 0.0.23 → 0.0.26

package/src/cli/build-info.ts

@@ -0,0 +1,4 @@
+// Generated at compile time — do not edit manually
+export const BUILD_SHA = '4f7677c'
+export const BUILD_BRANCH = 'main'
+export const BUILD_DATE = '2026-03-22T20:57:24Z'

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/command.ts

@@ -266,6 +266,81 @@ export class CommandsRegistry extends Registry<Command<any>> {
 	override scope = 'commands'
 	override baseClass = Command as any
 
+	/**
+	 * Convert all registered commands into a `{ schemas, handlers }` object
+	 * compatible with `assistant.use()`.
+	 *
+	 * Each command becomes a tool whose parameters come from the command's
+	 * `argsSchema` (with internal CLI fields stripped) and whose handler
+	 * dispatches the command headlessly, returning `{ exitCode, stdout, stderr }`.
+	 *
+	 * @param container - The container used to instantiate and dispatch commands
+	 * @param options - Optional filter/transform options
+	 * @param options.include - Only include these command names (default: all)
+	 * @param options.exclude - Exclude these command names (default: none)
+	 * @param options.prefix - Prefix tool names (e.g. 'luca_' → 'luca_eval')
+	 */
+	toTools(
+		container: Container<any> & CommandsInterface,
+		options?: { include?: string[], exclude?: string[], prefix?: string },
+	): { schemas: Record<string, z.ZodType>, handlers: Record<string, Function> } {
+		const schemas: Record<string, z.ZodType> = {}
+		const handlers: Record<string, Function> = {}
+		const prefix = options?.prefix ?? ''
+		const includeSet = options?.include ? new Set(options.include) : null
+		const excludeSet = new Set(options?.exclude ?? [])
+
+		// Internal fields inherited from HelperOptionsSchema / CommandOptionsSchema
+		const internalFields = ['_', 'dispatchSource', 'name', '_cacheKey']
+
+		for (const name of this.available) {
+			if (excludeSet.has(name)) continue
+			if (includeSet && !includeSet.has(name)) continue
+
+			const Cmd = this.lookup(name) as typeof Command
+			const rawSchema = Cmd.argsSchema
+			const description = Cmd.commandDescription || Cmd.description || name
+
+			// Build a clean schema by stripping internal CLI fields from the argsSchema.
+			// If the schema is a ZodObject we can use .omit(), otherwise create a
+			// virtual passthrough schema so the tool still flows through.
+			let toolSchema: z.ZodType
+			try {
+				const shape = typeof (rawSchema as any)?._def?.shape === 'function'
+					? (rawSchema as any)._def.shape()
+					: (rawSchema as any)?._def?.shape
+
+				if (shape) {
+					// Build a new object schema omitting internal fields
+					const cleanShape: Record<string, z.ZodType> = {}
+					for (const [key, val] of Object.entries(shape)) {
+						if (internalFields.includes(key)) continue
+						cleanShape[key] = val as z.ZodType
+					}
+
+					toolSchema = Object.keys(cleanShape).length > 0
+						? z.object(cleanShape).describe(description)
+						: z.object({}).describe(description)
+				} else {
+					// Not a ZodObject — wrap as passthrough
+					toolSchema = z.object({}).describe(description)
+				}
+			} catch {
+				toolSchema = z.object({}).describe(description)
+			}
+
+			const toolName = `${prefix}${name}`
+			schemas[toolName] = toolSchema
+			handlers[toolName] = async (args: Record<string, any>) => {
+				const cmd = container.command(name as any)
+				const result = await cmd.dispatch(args ?? {}, 'headless')
+				return result ?? { exitCode: 0, stdout: '', stderr: '' }
+			}
+		}
+
+		return { schemas, handlers }
+	}
+
 	/**
 	 * Internal: register a command from a handler function.
 	 * Used by built-in commands. External commands should use the module export pattern.

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')