@soederpop/luca 0.0.20 → 0.0.21

package/docs/bootstrap/SKILL.md

@@ -26,6 +26,13 @@ luca describe clients      # index of all available clients
 luca describe servers      # index of all available servers
 ```
 
+You can even learn about features in the browser container, or a specific platform (server, node are the same, browser,web are the same)
+
+```shell
+luca describe features --platform=web 
+luca describe features --platform=server
+```
+
 ### Learn about specific helpers
 
 ```shell
@@ -230,6 +237,15 @@ This is useful inside commands and scripts where you need introspection data pro
 
 ---
 
+## Server development troubleshooting
+
+- You can use `container.proc.findPidsByPort(3000)` which will return an array of numbers.
+- You can use `container.proc.kill(pid)` to kill that process
+- You can combine these two functions in `luca eval` if a server you're developing won't start because a previous instance is running (common inside e.g. claude code sessions )
+- `luca serve --force` will also replace the running process with the current one
+- `luca serve --any-port` will open on any port
+
+
 ## Reference
 
 See `references/api-docs/` for the full pre-generated API reference for every built-in feature, client, and server.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.20",
+  "version": "0.0.21",
   "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-21T01:13:43.856Z
+// Generated at: 2026-03-21T05:24:16.832Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -33,6 +33,13 @@ luca describe clients      # index of all available clients
 luca describe servers      # index of all available servers
 \`\`\`
 
+You can even learn about features in the browser container, or a specific platform (server, node are the same, browser,web are the same)
+
+\`\`\`shell
+luca describe features --platform=web 
+luca describe features --platform=server
+\`\`\`
+
 ### Learn about specific helpers
 
 \`\`\`shell
@@ -237,6 +244,15 @@ This is useful inside commands and scripts where you need introspection data pro
 
 ---
 
+## Server development troubleshooting
+
+- You can use \`container.proc.findPidsByPort(3000)\` which will return an array of numbers.
+- You can use \`container.proc.kill(pid)\` to kill that process
+- You can combine these two functions in \`luca eval\` if a server you're developing won't start because a previous instance is running (common inside e.g. claude code sessions )
+- \`luca serve --force\` will also replace the running process with the current one
+- \`luca serve --any-port\` will open on any port
+
+
 ## Reference
 
 See \`references/api-docs/\` for the full pre-generated API reference for every built-in feature, client, and server.

package/src/commands/chat.ts

@@ -187,8 +187,20 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 		output: process.stdout,
 	})
 
+	let rlClosed = false
+	rl.on('close', () => { rlClosed = true })
+
+	function ensureRl() {
+		if (rlClosed) {
+			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
+		}
+	}
+
 	function prompt(): Promise<string> {
 		return new Promise((resolve) => {
+			ensureRl()
 			rl.question(ui.colors.dim(`\n${name} > `), (answer: string) => resolve(answer.trim()))
 		})
 	}
@@ -247,6 +259,8 @@ export default async function chat(options: z.infer<typeof argsSchema>, context:
 			console.log()
 			console.log(ui.colors.dim(`  Back in chat with ${ui.colors.cyan(name)}.`))
 			rl = readline.createInterface({ input: process.stdin, output: process.stdout })
+			rlClosed = false
+			rl.on('close', () => { rlClosed = true })
 			continue
 		}
 

package/src/commands/prompt.ts

@@ -17,11 +17,11 @@ export const argsSchema = CommandOptionsSchema.extend({
 	'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'),
 	'include-output': z.boolean().default(false).describe('Include tool call outputs in the markdown (requires --out-file)'),
-	'dont-touch-file': z.boolean().default(false).describe('Do not update the prompt file frontmatter with run stats'),
-	'repeat-anyway': z.boolean().default(false).describe('Run even if repeatable is false and the prompt has already been run'),
+	'inputs-file': z.string().optional().describe('Path to a JSON or YAML file supplying input values'),
 	'parallel': z.boolean().default(false).describe('Run multiple prompt files in parallel with side-by-side terminal UI'),
 	'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'),
 })
 
 const CLI_TARGETS = new Set(['claude', 'codex'])
@@ -72,9 +72,10 @@ interface PreparedPrompt {
 	resolvedPath: string
 	promptContent: string
 	filename: string
+	agentOptions: Record<string, any>
 }
 
-async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: string, container: any, options: z.infer<typeof argsSchema>): Promise<RunStats> {
+async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: string, container: any, options: z.infer<typeof argsSchema>, agentOptions: Record<string, any> = {}): Promise<RunStats> {
 	const ui = container.feature('ui')
 	const featureName = target === 'claude' ? 'claudeCode' : 'openaiCodex'
 	const feature = container.feature(featureName)
@@ -118,7 +119,7 @@ async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: strin
 		})
 	}
 
-	const runOptions: Record<string, any> = { streaming: true }
+	const runOptions: Record<string, any> = { streaming: true, ...agentOptions }
 
 	if (options['in-folder']) {
 		runOptions.cwd = container.paths.resolve(options['in-folder'])
@@ -129,6 +130,9 @@ async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: strin
 		if (options.chrome) runOptions.chrome = true
 	}
 
+	// CLI flags override agentOptions from frontmatter
+	if (options.model) runOptions.model = options.model
+
 	const startTime = Date.now()
 	const sessionId = await feature.start(promptContent, runOptions)
 	const session = await feature.waitForSession(sessionId)
@@ -143,7 +147,7 @@ async function runClaudeOrCodex(target: 'claude' | 'codex', promptContent: strin
 	return { collectedEvents, durationMs: Date.now() - startTime, outputTokens }
 }
 
-async function runAssistant(name: string, promptContent: string, options: z.infer<typeof argsSchema>, container: any): Promise<RunStats> {
+async function runAssistant(name: string, promptContent: string, options: z.infer<typeof argsSchema>, container: any, agentOptions: Record<string, any> = {}): Promise<RunStats> {
 	const ui = container.feature('ui')
 	const manager = container.feature('assistantsManager')
 	await manager.discover()
@@ -156,7 +160,8 @@ async function runAssistant(name: string, promptContent: string, options: z.infe
 		process.exit(1)
 	}
 
-	const createOptions: Record<string, any> = {}
+	const createOptions: Record<string, any> = { ...agentOptions }
+	// CLI flags override agentOptions from frontmatter
 	if (options.model) createOptions.model = options.model
 
 	const assistant = manager.create(name, createOptions)
@@ -311,9 +316,11 @@ async function runParallel(
 			})
 		}
 
-		// Start all sessions
+		// Start all sessions — merge per-prompt agentOptions with shared runOptions
 		for (let i = 0; i < prepared.length; i++) {
-			const id = await feature.start(prepared[i].promptContent, runOptions)
+			const perPromptOptions = { ...prepared[i].agentOptions, ...runOptions }
+			if (options.model) perPromptOptions.model = options.model
+			const id = await feature.start(prepared[i].promptContent, perPromptOptions)
 			sessionMap.set(id, i)
 		}
 
@@ -348,12 +355,11 @@ async function runParallel(
 			process.exit(1)
 		}
 
-		const createOptions: Record<string, any> = {}
-		if (options.model) createOptions.model = options.model
-
 		const lineBuffers: string[] = prepared.map(() => '')
 
 		const assistants = prepared.map((p, i) => {
+			const createOptions: Record<string, any> = { ...p.agentOptions }
+			if (options.model) createOptions.model = options.model
 			const assistant = manager.create(target, createOptions)
 
 			assistant.on('chunk', (text: string) => {
@@ -526,24 +532,6 @@ async function runParallel(
 	// Wait for sessions to fully settle
 	await sessionPromise
 
-	// Post-completion: update frontmatter
-	if (!options['dont-touch-file']) {
-		for (let i = 0; i < promptStates.length; i++) {
-			const ps = promptStates[i]
-			if (ps.status === 'error') continue
-			const rawContent = fs.readFile(prepared[i].resolvedPath) as string
-			const updates: Record<string, any> = {
-				lastRanAt: Date.now(),
-				durationMs: ps.durationMs,
-			}
-			if (ps.outputTokens > 0) {
-				updates.outputTokens = ps.outputTokens
-			}
-			const updated = updateFrontmatter(rawContent, updates, container)
-			await Bun.write(prepared[i].resolvedPath, updated)
-		}
-	}
-
 	// Post-completion: out-files
 	if (options['out-file']) {
 		const base = options['out-file']
@@ -573,26 +561,123 @@ async function runParallel(
 	}
 }
 
-function updateFrontmatter(fileContent: string, updates: Record<string, any>, container: any): string {
+interface InputDef {
+	description?: string
+	required?: boolean
+	default?: any
+	type?: string
+	choices?: string[]
+}
+
+function parseInputDefs(meta: Record<string, any>): Record<string, InputDef> | null {
+	if (!meta?.inputs || typeof meta.inputs !== 'object') return null
+	const defs: Record<string, InputDef> = {}
+	for (const [key, val] of Object.entries(meta.inputs)) {
+		if (typeof val === 'object' && val !== null) {
+			defs[key] = val as InputDef
+		} else {
+			// Shorthand: `topic: "What to write about"` means description-only, required
+			defs[key] = { description: typeof val === 'string' ? val : String(val) }
+		}
+	}
+	return Object.keys(defs).length ? defs : null
+}
+
+async function resolveInputs(
+	inputDefs: Record<string, InputDef>,
+	options: z.infer<typeof argsSchema>,
+	container: any,
+): Promise<Record<string, any>> {
+	const { fs, paths } = container
 	const yaml = container.feature('yaml')
+	const ui = container.feature('ui')
+
+	// Layer 1: inputs-file (lowest priority of supplied values)
+	let fileInputs: Record<string, any> = {}
+	if (options['inputs-file']) {
+		const filePath = paths.resolve(options['inputs-file'])
+		const raw = fs.readFile(filePath) as string
+		if (filePath.endsWith('.json')) {
+			fileInputs = JSON.parse(raw)
+		} else {
+			fileInputs = yaml.parse(raw) || {}
+		}
+	}
+
+	// Layer 2: CLI flags (highest priority) — any unknown option that matches an input name
+	const cliInputs: Record<string, any> = {}
+	const argv = container.argv as Record<string, any>
+	for (const key of Object.keys(inputDefs)) {
+		if (argv[key] !== undefined) {
+			cliInputs[key] = argv[key]
+		}
+	}
 
-	if (fileContent.startsWith('---')) {
-		const endIndex = fileContent.indexOf('\n---', 3)
-		if (endIndex !== -1) {
-			const existingYaml = fileContent.slice(4, endIndex)
-			const meta = yaml.parse(existingYaml) || {}
-			Object.assign(meta, updates)
-			const newYaml = yaml.stringify(meta).trimEnd()
-			return `---\n${newYaml}\n---${fileContent.slice(endIndex + 4)}`
+	// Merge: CLI > file > defaults
+	const supplied: Record<string, any> = {}
+	for (const [key, def] of Object.entries(inputDefs)) {
+		if (cliInputs[key] !== undefined) {
+			supplied[key] = cliInputs[key]
+		} else if (fileInputs[key] !== undefined) {
+			supplied[key] = fileInputs[key]
+		} else if (def.default !== undefined) {
+			supplied[key] = def.default
 		}
 	}
 
-	// No existing frontmatter — prepend one
-	const newYaml = yaml.stringify(updates).trimEnd()
-	return `---\n${newYaml}\n---\n\n${fileContent}`
+	// Find missing required inputs
+	const missing: string[] = []
+	for (const [key, def] of Object.entries(inputDefs)) {
+		const isRequired = def.required !== false // default to required
+		if (isRequired && supplied[key] === undefined) {
+			missing.push(key)
+		}
+	}
+
+	if (missing.length === 0) return supplied
+
+	// In parallel mode, we can't run an interactive wizard
+	if ((options as any).parallel) {
+		console.error(`Missing required inputs for parallel mode (use --inputs-file or CLI flags): ${missing.join(', ')}`)
+		process.exit(1)
+	}
+
+	// Build wizard questions for missing inputs
+	const questions = missing.map((key) => {
+		const def = inputDefs[key]
+		const q: Record<string, any> = {
+			name: key,
+			message: def.description || key,
+		}
+
+		// Auto-infer type
+		if (def.choices?.length) {
+			q.type = 'list'
+			q.choices = def.choices
+		} else if (def.type) {
+			q.type = def.type
+		} else {
+			q.type = 'input'
+		}
+
+		if (def.default !== undefined) {
+			q.default = def.default
+		}
+
+		return q
+	})
+
+	const answers = await ui.wizard(questions, supplied)
+	return { ...supplied, ...answers }
+}
+
+function substituteInputs(content: string, inputs: Record<string, any>): string {
+	return content.replace(/\{\{(\w+)\}\}/g, (match, key) => {
+		return inputs[key] !== undefined ? String(inputs[key]) : match
+	})
 }
 
-async function executePromptFile(resolvedPath: string, container: any): Promise<string> {
+async function executePromptFile(resolvedPath: string, container: any, inputs?: Record<string, any>): Promise<string> {
 	if (!container.docs.isLoaded) await container.docs.load()
 	const doc = await container.docs.parseMarkdownAtPath(resolvedPath)
 	const vm = container.feature('vm')
@@ -608,6 +693,7 @@ async function executePromptFile(resolvedPath: string, container: any): Promise<
 
 	const shared = vm.createContext({
 		...container.context,
+		INPUTS: inputs || {},
 		console: captureConsole,
 		setTimeout, clearTimeout, setInterval, clearInterval,
 		fetch, URL, URLSearchParams,
@@ -669,24 +755,40 @@ async function preparePrompt(
 
 	let content = fs.readFile(resolvedPath) as string
 
-	// Check repeatable gate
-	if (!options['repeat-anyway'] && content.startsWith('---')) {
+	// Parse frontmatter for input definitions and agentOptions
+	let resolvedInputs: Record<string, any> = {}
+	let agentOptions: Record<string, any> = {}
+	let hasInputDefs = false
+	if (content.startsWith('---')) {
 		const fmEnd = content.indexOf('\n---', 3)
 		if (fmEnd !== -1) {
 			const yaml = container.feature('yaml')
 			const meta = yaml.parse(content.slice(4, fmEnd)) || {}
-			if (meta.repeatable === false && meta.lastRanAt) {
-				console.error(`${filePath}: already run (lastRanAt: ${new Date(meta.lastRanAt).toLocaleString()}) and repeatable is false. Skipping.`)
-				return null
+			const inputDefs = parseInputDefs(meta)
+			if (inputDefs) {
+				hasInputDefs = true
+				resolvedInputs = await resolveInputs(inputDefs, options, container)
+			}
+			if (meta.agentOptions && typeof meta.agentOptions === 'object') {
+				agentOptions = { ...meta.agentOptions }
 			}
 		}
 	}
 
+	if (options['inputs-file'] && !hasInputDefs) {
+		console.warn(`Warning: --inputs-file was provided but ${filePath} does not define any inputs in its frontmatter`)
+	}
+
 	let promptContent: string
 	if (options['preserve-frontmatter']) {
 		promptContent = content
 	} else {
-		promptContent = await executePromptFile(resolvedPath, container)
+		promptContent = await executePromptFile(resolvedPath, container, resolvedInputs)
+	}
+
+	// Substitute {{key}} placeholders with resolved input values
+	if (Object.keys(resolvedInputs).length) {
+		promptContent = substituteInputs(promptContent, resolvedInputs)
 	}
 
 	// Exclude sections by heading name
@@ -709,6 +811,7 @@ async function preparePrompt(
 		resolvedPath,
 		promptContent,
 		filename: paths.basename(resolvedPath),
+		agentOptions,
 	}
 }
 
@@ -751,6 +854,28 @@ export default async function prompt(options: z.infer<typeof argsSchema>, contex
 			process.exit(1)
 		}
 
+		if (options['dry-run']) {
+			const ui = container.feature('ui')
+			console.log(ui.colors.bold('\n── Dry Run (Parallel) ──\n'))
+			console.log(ui.colors.bold('Target:'), target)
+			console.log(ui.colors.bold('Prompts:'), prepared.length)
+			for (const p of prepared) {
+				console.log(ui.colors.bold(`\n── ${p.filename} ──`))
+				console.log(ui.colors.dim(`  Path: ${p.resolvedPath}`))
+				console.log(ui.colors.dim(`  Length: ${p.promptContent.length} chars`))
+				if (Object.keys(p.agentOptions).length) {
+					console.log(ui.colors.dim('  Agent options:'))
+					for (const [key, val] of Object.entries(p.agentOptions)) {
+						const display = typeof val === 'object' ? JSON.stringify(val) : val
+						console.log(ui.colors.dim(`    ${key}: ${display}`))
+					}
+				}
+				console.log('')
+				process.stdout.write(ui.markdown(p.promptContent))
+			}
+			return
+		}
+
 		if (prepared.length > 1) {
 			await runParallel(target, prepared, options, container)
 			return
@@ -767,28 +892,43 @@ export default async function prompt(options: z.infer<typeof argsSchema>, contex
 	}
 
 	const ui = container.feature('ui')
+
+	if (options['dry-run']) {
+		const runOptions: Record<string, any> = { ...p.agentOptions }
+		if (options.model) runOptions.model = options.model
+		if (options['in-folder']) runOptions.cwd = container.paths.resolve(options['in-folder'])
+		if (options['out-file']) runOptions.outFile = options['out-file']
+		if (options['include-output']) runOptions.includeOutput = true
+		if (options['exclude-sections']) runOptions.excludeSections = options['exclude-sections']
+		if (CLI_TARGETS.has(target)) {
+			runOptions.permissionMode = options['permission-mode']
+			if (options.chrome) runOptions.chrome = true
+		}
+
+		console.log(ui.colors.bold('\n── Dry Run ──\n'))
+		console.log(ui.colors.bold('Target:'), target)
+		console.log(ui.colors.bold('Prompt file:'), p.resolvedPath)
+		console.log(ui.colors.bold('Prompt length:'), `${p.promptContent.length} chars`)
+		if (Object.keys(runOptions).length) {
+			console.log(ui.colors.bold('Options:'))
+			for (const [key, val] of Object.entries(runOptions)) {
+				const display = typeof val === 'object' ? JSON.stringify(val) : val
+				console.log(`  ${key}: ${display}`)
+			}
+		}
+		console.log(ui.colors.bold('\n── Prompt Content ──\n'))
+		process.stdout.write(ui.markdown(p.promptContent))
+		return
+	}
+
 	process.stdout.write(ui.markdown(p.promptContent))
 
 	let stats: RunStats
 
 	if (CLI_TARGETS.has(target)) {
-		stats = await runClaudeOrCodex(target as 'claude' | 'codex', p.promptContent, container, options)
+		stats = await runClaudeOrCodex(target as 'claude' | 'codex', p.promptContent, container, options, p.agentOptions)
 	} else {
-		stats = await runAssistant(target, p.promptContent, options, container)
-	}
-
-	// Update prompt file frontmatter with run stats
-	if (!options['dont-touch-file']) {
-		const rawContent = fs.readFile(p.resolvedPath) as string
-		const updates: Record<string, any> = {
-			lastRanAt: Date.now(),
-			durationMs: stats.durationMs,
-		}
-		if (stats.outputTokens > 0) {
-			updates.outputTokens = stats.outputTokens
-		}
-		const updated = updateFrontmatter(rawContent, updates, container)
-		await Bun.write(p.resolvedPath, updated)
+		stats = await runAssistant(target, p.promptContent, options, container, p.agentOptions)
 	}
 
 	if (options['out-file'] && stats.collectedEvents.length) {