@soederpop/luca 0.0.8 → 0.0.10

package/AGENTS.md

@@ -26,6 +26,7 @@ On the frontend the browser container is perfect for highly reactive, stateful w
 		- `luca describe diskCache`
 		- `luca describe` describe the container itself
 		- `luca describe servers` describe which servers are available
+		- `luca describe ui.banner` describe a specific method or getter on a helper
 		- the arguments to describe are pretty forgiving and permissive
 
 **IMPORTANT NOTE** When trying to investigate features, clients, servers, etc, see if these tools can help you first instead of searching for files and reading them that way.  If youw ant to understand what they do, vs how theyre actually implemented

package/CLAUDE.md

@@ -26,6 +26,7 @@ On the frontend the browser container is perfect for highly reactive, stateful w
 		- `luca describe diskCache`
 		- `luca describe` describe the container itself
 		- `luca describe servers` describe which servers are available
+		- `luca describe ui.banner` describe a specific method or getter on a helper
 		- the arguments to describe are pretty forgiving and permissive
 
 **IMPORTANT NOTE** When trying to investigate features, clients, servers, etc, see if these tools can help you first instead of searching for files and reading them that way.  If youw ant to understand what they do, vs how theyre actually implemented

package/commands/release.ts

@@ -0,0 +1,178 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+const TARGETS = [
+	{ name: 'linux-x64', bunTarget: 'bun-linux-x64', suffix: 'linux-x64' },
+	{ name: 'linux-arm64', bunTarget: 'bun-linux-arm64', suffix: 'linux-arm64' },
+	{ name: 'darwin-x64', bunTarget: 'bun-darwin-x64', suffix: 'darwin-x64' },
+	{ name: 'darwin-arm64', bunTarget: 'bun-darwin-arm64', suffix: 'darwin-arm64' },
+	{ name: 'windows-x64', bunTarget: 'bun-windows-x64', suffix: 'windows-x64', ext: '.exe' },
+]
+
+export const argsSchema = CommandOptionsSchema.extend({
+	dryRun: z.boolean().optional().describe('Build binaries but skip tagging and uploading'),
+	skipBuild: z.boolean().optional().describe('Skip pre-build steps (introspection, scaffolds, bootstrap)'),
+	skipTests: z.boolean().optional().describe('Skip running tests before release'),
+	draft: z.boolean().optional().describe('Create the GitHub release as a draft'),
+	targets: z.string().optional().describe('Comma-separated list of targets to build (e.g. linux-x64,darwin-arm64). Defaults to all'),
+})
+
+async function release(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const proc = container.feature('proc')
+	const fs = container.feature('fs')
+	const ui = container.feature('ui')
+
+	const pkg = JSON.parse(await fs.readFileAsync('package.json'))
+	const version = pkg.version
+	const tag = `v${version}`
+	const distDir = 'dist/release'
+
+	ui.banner(`Luca Release ${tag}`)
+
+	// Filter targets if specified
+	let selectedTargets = TARGETS
+	if (options.targets) {
+		const requested = options.targets.split(',').map((t: string) => t.trim())
+		selectedTargets = TARGETS.filter(t => requested.includes(t.suffix) || requested.includes(t.name))
+		if (selectedTargets.length === 0) {
+			console.error(`No valid targets found. Available: ${TARGETS.map(t => t.suffix).join(', ')}`)
+			return
+		}
+	}
+
+	// 1. Run tests
+	if (!options.skipTests) {
+		console.log('\n→ Running tests...')
+		const testResult = await proc.exec('bun test test/*.test.ts', { silent: false })
+		if (testResult.exitCode !== 0) {
+			console.error('Tests failed. Fix them before releasing.')
+			return
+		}
+	}
+
+	// 2. Pre-build steps
+	if (!options.skipBuild) {
+		console.log('\n→ Running pre-build steps...')
+		const steps = [
+			['build:introspection', 'bun run build:introspection'],
+			['build:scaffolds', 'bun run build:scaffolds'],
+			['build:bootstrap', 'bun run build:bootstrap'],
+		]
+		for (const [label, cmd] of steps) {
+			console.log(`  ${label}...`)
+			const r = await proc.exec(cmd, { silent: true })
+			if (r.exitCode !== 0) {
+				console.error(`${label} failed:\n${r.stderr}`)
+				return
+			}
+		}
+	}
+
+	// 3. Cross-compile for all targets
+	fs.ensureFolder(distDir)
+
+	console.log(`\n→ Compiling for ${selectedTargets.length} targets...`)
+	for (const target of selectedTargets) {
+		const ext = target.ext || ''
+		const outfile = `${distDir}/luca-${target.suffix}${ext}`
+		const cmd = `bun build ./src/cli/cli.ts --compile --target=${target.bunTarget} --outfile ${outfile} --external node-llama-cpp`
+
+		console.log(`  ${target.name}...`)
+		const result = await proc.exec(cmd, { silent: true })
+		if (result.exitCode !== 0) {
+			console.error(`  Failed to compile for ${target.name}:\n${result.stderr}`)
+			return
+		}
+
+		const stat = fs.statSync(outfile)
+		const sizeMB = (stat.size / 1024 / 1024).toFixed(1)
+		console.log(`  ✓ ${outfile} (${sizeMB} MB)`)
+	}
+
+	if (options.dryRun) {
+		console.log(`\n→ Dry run complete. Binaries are in ${distDir}/`)
+		console.log('  Skipping git tag and GitHub release.')
+		return
+	}
+
+	// 4. Check if tag already exists
+	const tagCheck = await proc.exec(`git tag -l "${tag}"`, { silent: true })
+	if (tagCheck.stdout.trim() === tag) {
+		console.error(`\nTag ${tag} already exists. Bump the version in package.json first.`)
+		return
+	}
+
+	// 5. Check for clean working tree (allow untracked)
+	const statusCheck = await proc.exec('git status --porcelain', { silent: true })
+	const dirtyFiles = statusCheck.stdout.trim().split('\n').filter((l: string) => l && !l.startsWith('??'))
+	if (dirtyFiles.length > 0) {
+		console.error('\nWorking tree has uncommitted changes. Commit or stash them first.')
+		console.error(dirtyFiles.join('\n'))
+		return
+	}
+
+	// 6. Create git tag
+	console.log(`\n→ Creating tag ${tag}...`)
+	const tagResult = await proc.exec(`git tag -a "${tag}" -m "Release ${tag}"`, { silent: true })
+	if (tagResult.exitCode !== 0) {
+		console.error(`Failed to create tag:\n${tagResult.stderr}`)
+		return
+	}
+
+	// 7. Push tag
+	console.log(`→ Pushing tag ${tag}...`)
+	const pushResult = await proc.exec(`git push origin "${tag}"`, { silent: true })
+	if (pushResult.exitCode !== 0) {
+		console.error(`Failed to push tag:\n${pushResult.stderr}`)
+		return
+	}
+
+	// 8. Create GitHub release and upload binaries
+	const draftFlag = options.draft ? '--draft' : ''
+	const assets = selectedTargets
+		.map(t => `${distDir}/luca-${t.suffix}${t.ext || ''}`)
+		.join(' ')
+
+	const releaseTitle = `Luca ${tag}`
+	const releaseNotes = await generateReleaseNotes(proc, tag)
+
+	console.log(`\n→ Creating GitHub release ${tag}...`)
+	const ghCmd = `gh release create "${tag}" ${assets} --title "${releaseTitle}" --notes ${JSON.stringify(releaseNotes)} ${draftFlag}`
+	const ghResult = await proc.exec(ghCmd, { silent: false })
+
+	if (ghResult.exitCode !== 0) {
+		console.error(`Failed to create GitHub release:\n${ghResult.stderr}`)
+		console.log('The tag was pushed. You can manually create the release with:')
+		console.log(`  gh release create ${tag} ${assets}`)
+		return
+	}
+
+	console.log(`\n✓ Released ${tag} successfully!`)
+	console.log(`  https://github.com/soederpop/luca/releases/tag/${tag}`)
+}
+
+async function generateReleaseNotes(proc: any, tag: string): Promise<string> {
+	// Get commits since last tag
+	const lastTag = await proc.exec('git describe --tags --abbrev=0 HEAD^ 2>/dev/null || echo ""', { silent: true })
+	const since = lastTag.stdout.trim()
+
+	let logCmd: string
+	if (since) {
+		logCmd = `git log ${since}..HEAD --oneline --no-decorate`
+	} else {
+		logCmd = 'git log --oneline --no-decorate -20'
+	}
+
+	const log = await proc.exec(logCmd, { silent: true })
+	const commits = log.stdout.trim()
+
+	return `## What's Changed\n\n${commits ? commits.split('\n').map((c: string) => `- ${c}`).join('\n') : 'Initial release'}\n\n## Platforms\n\n- Linux x64\n- Linux ARM64\n- macOS x64 (Intel)\n- macOS ARM64 (Apple Silicon)\n- Windows x64`
+}
+
+export default {
+	description: 'Build cross-platform binaries and publish a GitHub release tagged by version',
+	argsSchema,
+	handler: release,
+}

package/docs/bootstrap/CLAUDE.md

@@ -15,6 +15,7 @@ The `luca` binary is available in the path. Key commands:
 - `luca` — list available commands (built-in + project commands)
 - `luca eval "expression"` — evaluate JS with the container in scope
 - `luca describe <name>` — full docs for any feature, client, or server (e.g. `luca describe fs`)
+- `luca describe <name>.<member>` — docs for a specific method or getter (e.g. `luca describe ui.banner`, `luca describe fs.readFile`)
 - `luca describe features` — index of all available features (also: `clients`, `servers`)
 - `luca serve` — start a local server using `endpoints/` folder
 - `luca run script.ts` — run a script with the container
@@ -28,7 +29,7 @@ The `luca` binary is available in the path. Key commands:
 
 ## Learning the Framework
 
-1. **Discover** — Run `luca describe features`, `luca describe clients`, `luca describe servers` to see what's available. Then `luca describe <name>` for full docs on any helper. This is your first move, always. (See `.claude/skills/luca-framework/SKILL.md` for the full mental model.)
+1. **Discover** — Run `luca describe features`, `luca describe clients`, `luca describe servers` to see what's available. Then `luca describe <name>` for full docs on any helper, or `luca describe <name>.<member>` to drill into a specific method or getter. This is your first move, always. (See `.claude/skills/luca-framework/SKILL.md` for the full mental model.)
 2. **Build** — Run `luca scaffold <type> --tutorial` before creating a new helper. It covers the full guide for that type.
 3. **Prototype** — Use `luca eval "expression"` to test container code before wiring up full handlers. Reach for eval when you're stuck — it gives you full runtime access.
 4. **Reference** — Browse `.claude/skills/luca-framework/references/api-docs/` for pre-generated API docs

package/docs/bootstrap/SKILL.md

@@ -36,6 +36,19 @@ luca describe express      # full docs for the express server
 luca describe git fs proc  # multiple helpers in one shot
 ```
 
+### Drill into a specific method or getter
+
+Use dot notation to get docs for a single method or getter on any helper:
+
+```shell
+luca describe ui.banner            # docs for the banner() method on ui
+luca describe fs.readFile          # docs for readFile() on fs
+luca describe ui.colors            # docs for the colors getter on ui
+luca describe git.branch           # docs for the branch getter on git
+```
+
+This shows the description, parameters, return type, and examples for just that member. If the member doesn't exist, it lists all available methods and getters on the helper.
+
 ### Get targeted documentation
 
 You can filter to only the sections you need:
@@ -63,7 +76,7 @@ luca describe --help       # full flag reference for describe
 luca help scaffold         # help for any command
 ```
 
-**Use `luca describe` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it.
+**Use `luca describe` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it. Use dot notation (`ui.banner`, `fs.readFile`) when you need docs on just one method or getter.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "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-19T04:48:18.099Z
+// Generated at: 2026-03-19T18:52:32.906Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -43,6 +43,19 @@ luca describe express      # full docs for the express server
 luca describe git fs proc  # multiple helpers in one shot
 \`\`\`
 
+### Drill into a specific method or getter
+
+Use dot notation to get docs for a single method or getter on any helper:
+
+\`\`\`shell
+luca describe ui.banner            # docs for the banner() method on ui
+luca describe fs.readFile          # docs for readFile() on fs
+luca describe ui.colors            # docs for the colors getter on ui
+luca describe git.branch           # docs for the branch getter on git
+\`\`\`
+
+This shows the description, parameters, return type, and examples for just that member. If the member doesn't exist, it lists all available methods and getters on the helper.
+
 ### Get targeted documentation
 
 You can filter to only the sections you need:
@@ -70,7 +83,7 @@ luca describe --help       # full flag reference for describe
 luca help scaffold         # help for any command
 \`\`\`
 
-**Use \`luca describe\` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it.
+**Use \`luca describe\` liberally.** It is the fastest, safest way to understand what the container provides. Every feature, client, and server is self-describing — if you know a name, describe will tell you everything about it. Use dot notation (\`ui.banner\`, \`fs.readFile\`) when you need docs on just one method or getter.
 
 ---
 
@@ -245,6 +258,7 @@ The \`luca\` binary is available in the path. Key commands:
 - \`luca\` — list available commands (built-in + project commands)
 - \`luca eval "expression"\` — evaluate JS with the container in scope
 - \`luca describe <name>\` — full docs for any feature, client, or server (e.g. \`luca describe fs\`)
+- \`luca describe <name>.<member>\` — docs for a specific method or getter (e.g. \`luca describe ui.banner\`, \`luca describe fs.readFile\`)
 - \`luca describe features\` — index of all available features (also: \`clients\`, \`servers\`)
 - \`luca serve\` — start a local server using \`endpoints/\` folder
 - \`luca run script.ts\` — run a script with the container
@@ -258,7 +272,7 @@ The \`luca\` binary is available in the path. Key commands:
 
 ## Learning the Framework
 
-1. **Discover** — Run \`luca describe features\`, \`luca describe clients\`, \`luca describe servers\` to see what's available. Then \`luca describe <name>\` for full docs on any helper. This is your first move, always. (See \`.claude/skills/luca-framework/SKILL.md\` for the full mental model.)
+1. **Discover** — Run \`luca describe features\`, \`luca describe clients\`, \`luca describe servers\` to see what's available. Then \`luca describe <name>\` for full docs on any helper, or \`luca describe <name>.<member>\` to drill into a specific method or getter. This is your first move, always. (See \`.claude/skills/luca-framework/SKILL.md\` for the full mental model.)
 2. **Build** — Run \`luca scaffold <type> --tutorial\` before creating a new helper. It covers the full guide for that type.
 3. **Prototype** — Use \`luca eval "expression"\` to test container code before wiring up full handlers. Reach for eval when you're stuck — it gives you full runtime access.
 4. **Reference** — Browse \`.claude/skills/luca-framework/references/api-docs/\` for pre-generated API docs

package/src/cli/cli.ts

@@ -1,4 +1,16 @@
 #!/usr/bin/env bun
+// @ts-ignore — bun resolves JSON imports at bundle time
+import pkg from '../../package.json'
+
+// 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(`  npm: https://www.npmjs.com/package/@soederpop/luca`)
+	console.log(`  git: https://github.com/soederpop/luca`)
+	process.exit(0)
+}
+
 import container from '@soederpop/luca/agi'
 import '@/commands/index.js'
 import { homedir } from 'os'
@@ -58,7 +70,14 @@ async function main() {
 	const commandName = container.argv._[0] as string
 
 	done = t('dispatch')
-	if (commandName && container.commands.has(commandName)) {
+	if (container.argv.help && !commandName) {
+		// --help with no command is the same as `luca` with no args
+		// Clear the help flag so the help command's handler runs (not the --help intercept)
+		delete container.argv.help
+		container.argv._.splice(0, 0, 'help')
+		const cmd = container.command('help' as any)
+		await cmd.dispatch()
+	} else if (commandName && container.commands.has(commandName)) {
 		const cmd = container.command(commandName as any)
 		await cmd.dispatch()
 	} else if (commandName) {

package/src/commands/run.ts

@@ -173,7 +173,10 @@ async function runMarkdown(scriptPath: string, options: z.infer<typeof argsSchem
 				continue
 			}
 
-			if (meta && typeof meta === 'string' && meta.toLowerCase().includes('skip')) continue
+			if (meta && typeof meta === 'string' && meta.toLowerCase().includes('skip')) {
+				console.log(container.ui.markdown(['```' + lang, value, '```'].join('\n')))
+				continue
+			}
 
 			console.log(container.ui.markdown(['```' + lang, value, '```'].join('\n')))