@soederpop/luca 0.0.9 → 0.0.11

package/commands/release.ts

@@ -0,0 +1,186 @@
+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 fileSystem = container.feature('fs')
+	const ui = container.feature('ui')
+
+	const pkg = JSON.parse(await fileSystem.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.execAndCapture('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.execAndCapture(cmd, { silent: true })
+			if (r.exitCode !== 0) {
+				console.error(`${label} failed:\n${r.stderr}`)
+				return
+			}
+		}
+	}
+
+	// 3. Cross-compile for all targets
+	fileSystem.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.execAndCapture(cmd, { silent: true })
+		if (result.exitCode !== 0) {
+			console.error(`  Failed to compile for ${target.name}:\n${result.stderr}`)
+			return
+		}
+
+		const sizeBytes = proc.exec(`stat -f%z ${container.paths.resolve(outfile)}`)
+		const sizeMB = (parseInt(sizeBytes, 10) / 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.execAndCapture(`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.execAndCapture('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.execAndCapture(`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.execAndCapture(`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 assetPaths = selectedTargets
+		.map(t => container.paths.resolve(`${distDir}/luca-${t.suffix}${t.ext || ''}`))
+
+	const releaseTitle = `Luca ${tag}`
+	const releaseNotes = await generateReleaseNotes(proc, tag)
+
+	// Write notes to a temp file so gh doesn't need shell quoting
+	const notesFile = container.paths.resolve(distDir, 'release-notes.md')
+	await fileSystem.writeFileAsync(notesFile, releaseNotes)
+
+	console.log(`\n→ Creating GitHub release ${tag}...`)
+	const ghArgs = [
+		'release', 'create', tag,
+		...assetPaths,
+		'--title', releaseTitle,
+		'--notes-file', notesFile,
+		...(options.draft ? ['--draft'] : []),
+	]
+	const ghResult = await proc.spawnAndCapture('gh', ghArgs)
+
+	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} ${assetPaths.join(' ')}`)
+		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.execAndCapture('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.execAndCapture(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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.9",
+  "version": "0.0.11",
   "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>",
@@ -102,7 +102,7 @@
     "chokidar": "^3.5.3",
     "cli-markdown": "^3.5.0",
     "compromise": "^14.14.5",
-    "contentbase": "^0.1.1",
+    "contentbase": "^0.1.4",
     "cors": "^2.8.5",
     "detect-port": "^1.5.1",
     "dotenv": "^17.2.4",

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-20T00:15:40.841Z
 // 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) {