@soederpop/luca 0.0.21 → 0.0.23

package/docs/prompts/check-for-undocumented-features.md

@@ -0,0 +1,27 @@
+---
+agentOptions:
+    permissionMode: bypassPermissions
+---
+
+# Check for undocumented features
+
+The luca introspection and luca cli's describe command is powered by the JSDoc comments in the code base, and the values passed to the describe methods in the zod schema.  This documentation is what is fed to AI Coding assistants to be able to understand how to use the individual features
+
+Please scan the following paths:
+
+```ts
+const fm = await container.feature('fileManager').start()
+const results = fm.match(['src/node/features/*.ts', 'src/agi/features/*.ts', 'src/web/features/*.ts'])
+console.log(results.join("\n"))
+```
+
+Please ensure every feature has accurate and valid JSDoc documentation for the class definitions, methods, and getters.
+
+Validate the output of `bun run src/cli/cli.ts describe whatever` for each item you're working on, that it displays properly, is easy to understand, accurate, in terms of how your comments display there.  You may need to run `bun run src/cli/cli.ts introspect` to generate the build time data.
+
+You can pass `--platform=web` to see web specific output.
+
+## Quality not just Quantity
+
+- The presence of documentation isn't sufficient.  Is it good documentation? Is it not overly verbose? Does it not explain stuff that doesn't matter? Is it accurate? If there are examples, do they work?
+- The main consumer of `luca describe` will be an LLM so token budget matters.  Every word has to be doing work.  It should still be nice to look at for human coders too.

package/luca.cli.ts

@@ -1,3 +1,16 @@
-export async function main(container) {
+export async function main(container: any) {
 	container.addContext('luca', container)
+
+	try {
+		container.onMissingCommand(handleMissingCommand)
+	} catch(error) {
+
+	}
+
+
+	async function handleMissingCommand({ words, phrase } : { words: string[], phrase: string }) {
+		const { ui } = container
+
+		ui.print.red('oh shit ' + phrase)
+	}
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.21",
+  "version": "0.0.23",
   "website": "https://luca.soederpop.com",
   "description": "lightweight universal conversational architecture AKA Le Ultimate Component Architecture AKA Last Universal Common Ancestor, part AI part Human",
   "author": "jon soeder aka the people's champ <jon@soederpop.com>",

package/src/bootstrap/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated bootstrap content
-// Generated at: 2026-03-21T05:24:16.832Z
+// Generated at: 2026-03-21T05:25:04.090Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
 //
 // Do not edit manually. Run: luca build-bootstrap

package/src/cli/cli.ts

@@ -19,7 +19,7 @@ import { join } from 'path'
 async function main() {
 	const profile = process.env.LUCA_PROFILE === '1'
 	const t = (label?: string) => {
-		if (!profile) return () => {}
+		if (!profile) return () => { }
 		const start = performance.now()
 		return (suffix?: string) => {
 			const ms = (performance.now() - start).toFixed(1)
@@ -59,8 +59,8 @@ async function main() {
 	const afterUser = new Set(container.commands.available as string[])
 	const userCommands = new Set([...afterUser].filter((n) => !builtinCommands.has(n) && !projectCommands.has(n)))
 
-	// Store command sources for help display
-	;(container as any)._commandSources = { builtinCommands, projectCommands, userCommands }
+		// Store command sources for help display
+		; (container as any)._commandSources = { builtinCommands, projectCommands, userCommands }
 
 	// Load generated introspection data if present
 	done = t('loadProjectIntrospection')
@@ -82,9 +82,33 @@ async function main() {
 		await cmd.dispatch()
 	} else if (commandName) {
 		// not a known command — treat as implicit `run`
-		container.argv._.splice(0, 0, 'run')
-		const cmd = container.command('run' as any)
-		await cmd.dispatch()
+		// 
+		if (resolveScript(commandName, container)) {
+			container.argv._.splice(0, 0, 'run')
+			const cmd = container.command('run' as any)
+			await cmd.dispatch()
+		} else {
+
+			// @ts-ignore TODO come up with a typesafe way to do this
+			if (container.state.get('missingCommandHandler')) {
+				// @ts-ignore TODO come up with a typesafe way to do this
+				const missingCommandHandler = container.state.get('missingCommandHandler') as any
+
+				if (typeof missingCommandHandler === 'function') {
+					await missingCommandHandler({
+						words: container.argv._,
+						phrase: container.argv._.join(' ')
+					}).catch((err: any) => {
+						console.error(`Missing command handler error: ${err.message}`, err)
+					})
+				}
+			} else {
+				container.argv._.splice(0, 0, 'help')
+				const cmd = container.command('help' as any)
+				await cmd.dispatch()
+			}
+		}
+
 	} else {
 		container.argv._.splice(0, 0, 'help')
 		const cmd = container.command('help' as any)
@@ -94,6 +118,21 @@ async function main() {
 	tTotal()
 }
 
+function resolveScript(ref: string, container: any) {
+	const candidates = [
+		ref,
+		`${ref}.ts`,
+		`${ref}.js`,
+		`${ref}.md`,
+	]
+
+	for (const candidate of candidates) {
+		const resolved = container.paths.resolve(candidate)
+		if (container.fs.exists(resolved)) return resolved
+	}
+
+	return null
+}
 
 async function loadCliModule() {
 	const modulePath = container.paths.resolve('luca.cli.ts')

package/src/commands/prompt.ts

@@ -12,7 +12,7 @@ declare module '../command.js' {
 
 export const argsSchema = CommandOptionsSchema.extend({
 	model: z.string().optional().describe('Override the LLM model (assistant mode only)'),
-'preserve-frontmatter': z.boolean().default(false).describe('Keep YAML frontmatter in the prompt instead of stripping it'),
+	'preserve-frontmatter': z.boolean().default(false).describe('Keep YAML frontmatter in the prompt instead of stripping it before sending to the agent.'),
 	'permission-mode': z.enum(['default', 'acceptEdits', 'bypassPermissions', 'plan']).default('acceptEdits').describe('Permission mode for CLI agents (default: acceptEdits)'),
 	'in-folder': z.string().optional().describe('Run the CLI agent in this directory (resolved via container.paths)'),
 	'out-file': z.string().optional().describe('Save session output as a markdown file'),
@@ -22,8 +22,16 @@ export const argsSchema = CommandOptionsSchema.extend({
 	'exclude-sections': z.string().optional().describe('Comma-separated list of section headings to exclude from the prompt'),
 	'chrome': z.boolean().default(false).describe('Launch Claude Code with a Chrome browser tool'),
 	'dry-run': z.boolean().default(false).describe('Display the resolved prompt and options without running the assistant'),
+	'local': z.boolean().default(false).describe('Use local models for assistant mode'),
 })
 
+function normalizeTarget(raw: string): string {
+	const lower = raw.toLowerCase().replace(/[-_]/g, '')
+	if (/claude/.test(lower)) return 'claude'
+	if (/codex/.test(lower) || /openai/.test(lower)) return 'codex'
+	return raw
+}
+
 const CLI_TARGETS = new Set(['claude', 'codex'])
 
 function formatSessionMarkdown(events: any[], includeOutput: boolean): string {
@@ -163,6 +171,7 @@ async function runAssistant(name: string, promptContent: string, options: z.infe
 	const createOptions: Record<string, any> = { ...agentOptions }
 	// CLI flags override agentOptions from frontmatter
 	if (options.model) createOptions.model = options.model
+	if (options.local) createOptions.local = true
 
 	const assistant = manager.create(name, createOptions)
 	let isFirstChunk = true
@@ -360,6 +369,7 @@ async function runParallel(
 		const assistants = prepared.map((p, i) => {
 			const createOptions: Record<string, any> = { ...p.agentOptions }
 			if (options.model) createOptions.model = options.model
+			if (options.local) createOptions.local = true
 			const assistant = manager.create(target, createOptions)
 
 			assistant.on('chunk', (text: string) => {
@@ -827,10 +837,16 @@ export default async function prompt(options: z.infer<typeof argsSchema>, contex
 		const candidate = paths.resolve(target)
 		if (fs.exists(candidate)) {
 			allPaths.push(target)
-			target = 'claude'
+			// this gives a way for you to say on a per project basis what you want the default coding assistant to be for the prompt command	
+			// TODO need to document this somewhere
+			const { codingAssistant } = (container.manifest.luca || {})
+			target = codingAssistant || 'claude'
 		}
 	}
 
+	// Normalize target aliases (e.g. claude-code → claude, openai-codex → codex)
+	if (target) target = normalizeTarget(target)
+
 	if (!target || allPaths.length === 0) {
 		console.error('Usage: luca prompt [claude|codex|assistant-name] <path/to/prompt.md> [more paths...]')
 		process.exit(1)