luca 2.0.0 → 3.0.0

package/commands/build-bootstrap.ts

@@ -0,0 +1,118 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+async function buildBootstrap(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fs = container.feature('fs')
+
+	const sourceDir = 'docs/bootstrap'
+	const outputPath = 'src/bootstrap/generated.ts'
+
+	if (!fs.exists(sourceDir)) {
+		console.log(`Source directory ${sourceDir} not found`)
+		return
+	}
+
+	// 1. Collect top-level markdown files (SKILL.md, CLAUDE.md, etc.)
+	const allFiles = await fs.readdir(sourceDir)
+	const mdFiles = allFiles.filter((f: string) => f.endsWith('.md'))
+	const entries: Record<string, string> = {}
+
+	for (const file of mdFiles) {
+		const content = await fs.readFileAsync(`${sourceDir}/${file}`)
+		const name = file.replace(/\.md$/, '')
+		entries[name] = content
+		console.log(`   ${name}: ${content.length} chars`)
+	}
+
+	// 2. Collect template files (docs/bootstrap/templates/*)
+	const templates: Record<string, string> = {}
+	const templatesDir = `${sourceDir}/templates`
+	if (fs.exists(templatesDir)) {
+		const templateFiles = await fs.readdir(templatesDir)
+		for (const file of templateFiles) {
+			const content = await fs.readFileAsync(`${templatesDir}/${file}`)
+			const name = file.replace(/\.[^.]+$/, '') // strip any extension
+			templates[name] = content
+			console.log(`   template/${name}: ${content.length} chars`)
+		}
+	}
+
+	// 3. Collect docs/examples/*.md
+	const examples: Record<string, string> = {}
+	const examplesDir = 'docs/examples'
+	if (fs.exists(examplesDir)) {
+		const exampleFiles = (await fs.readdir(examplesDir)).filter((f: string) => f.endsWith('.md'))
+		for (const file of exampleFiles) {
+			const content = await fs.readFileAsync(`${examplesDir}/${file}`)
+			examples[file] = content
+			console.log(`   example/${file}: ${content.length} chars`)
+		}
+	}
+
+	// 4. Collect docs/tutorials/*.md
+	const tutorials: Record<string, string> = {}
+	const tutorialsDir = 'docs/tutorials'
+	if (fs.exists(tutorialsDir)) {
+		const tutorialFiles = (await fs.readdir(tutorialsDir)).filter((f: string) => f.endsWith('.md'))
+		for (const file of tutorialFiles) {
+			const content = await fs.readFileAsync(`${tutorialsDir}/${file}`)
+			tutorials[file] = content
+			console.log(`   tutorial/${file}: ${content.length} chars`)
+		}
+	}
+
+	const escapeForTemplate = (s: string) => s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+	const fileEntries = Object.entries(entries).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const templateEntries = Object.entries(templates).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const exampleEntries = Object.entries(examples).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const tutorialEntries = Object.entries(tutorials).map(([name, content]) =>
+		`  ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const output = `// Auto-generated bootstrap content
+// Generated at: ${new Date().toISOString()}
+// Source: docs/bootstrap/*.md, docs/bootstrap/templates/*, docs/examples/*.md, docs/tutorials/*.md
+//
+// Do not edit manually. Run: luca build-bootstrap
+
+export const bootstrapFiles: Record<string, string> = {
+${fileEntries}
+}
+
+export const bootstrapTemplates: Record<string, string> = {
+${templateEntries}
+}
+
+export const bootstrapExamples: Record<string, string> = {
+${exampleEntries}
+}
+
+export const bootstrapTutorials: Record<string, string> = {
+${tutorialEntries}
+}
+`
+
+	fs.ensureFolder('src/bootstrap')
+	await fs.writeFileAsync(outputPath, output)
+	console.log(`\nGenerated ${outputPath}`)
+}
+
+export default {
+	description: 'Bundle docs/bootstrap/*.md into src/bootstrap/generated.ts for the compiled binary',
+	argsSchema,
+	handler: buildBootstrap,
+}

package/commands/build-python-bridge.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+async function buildPythonBridge(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fs = container.feature('fs')
+
+	const sourcePath = 'src/python/bridge.py'
+	const outputPath = 'src/python/generated.ts'
+
+	if (!fs.exists(sourcePath)) {
+		console.error(`   ❌ ${sourcePath} not found`)
+		process.exit(1)
+	}
+
+	const content = fs.readFile(sourcePath)
+	console.log(`   📄 bridge.py: ${content.length} chars`)
+
+	const escapeForTemplate = (s: string) =>
+		s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+	const output = `// Auto-generated Python bridge script
+// Generated at: ${new Date().toISOString()}
+// Source: src/python/bridge.py
+//
+// Do not edit manually. Run: luca build-python-bridge
+
+export const bridgeScript = \`${escapeForTemplate(content)}\`
+`
+
+	fs.ensureFolder('src/python')
+	await fs.writeFileAsync(outputPath, output)
+	console.log(`\n✨ Generated ${outputPath}`)
+}
+
+export default {
+	description: 'Bundle the Python bridge script into src/python/generated.ts',
+	argsSchema,
+	handler: buildPythonBridge,
+}

package/commands/build-scaffolds.ts

@@ -0,0 +1,176 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+
+export const argsSchema = CommandOptionsSchema.extend({})
+
+interface ScaffoldSection {
+	heading: string
+	code: string
+}
+
+interface ScaffoldData {
+	sections: ScaffoldSection[]
+	full: string
+	tutorial: string
+}
+
+/**
+ * Parse a markdown file to extract code blocks grouped by their nearest heading.
+ * Also extracts the "Complete Example" code block as the `full` template.
+ */
+function parseScaffoldMarkdown(content: string): ScaffoldData {
+	const sections: ScaffoldSection[] = []
+	let full = ''
+
+	let currentHeading = ''
+	const lines = content.split('\n')
+	let inCodeBlock = false
+	let codeBlockLang = ''
+	let codeBlockLines: string[] = []
+
+	for (const line of lines) {
+		// Track headings
+		const headingMatch = line.match(/^##\s+(.+)/)
+		if (headingMatch && !inCodeBlock) {
+			currentHeading = headingMatch[1].trim()
+			continue
+		}
+
+		// Track code fences
+		const fenceMatch = line.match(/^```(\w*)/)
+		if (fenceMatch && !inCodeBlock) {
+			inCodeBlock = true
+			codeBlockLang = fenceMatch[1] || ''
+			codeBlockLines = []
+			continue
+		}
+
+		if (line.startsWith('```') && inCodeBlock) {
+			inCodeBlock = false
+			const code = codeBlockLines.join('\n')
+
+			// Only collect ts/js code blocks
+			if (codeBlockLang === 'ts' || codeBlockLang === 'typescript' || codeBlockLang === 'js') {
+				sections.push({ heading: currentHeading, code })
+
+				if (currentHeading === 'Complete Example') {
+					full = code
+				}
+			}
+			continue
+		}
+
+		if (inCodeBlock) {
+			codeBlockLines.push(line)
+		}
+	}
+
+	return { sections, full, tutorial: content }
+}
+
+async function buildScaffolds(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+	const container = context.container as any
+	const fs = container.feature('fs')
+
+	const scaffoldDir = 'docs/scaffolds'
+	const readmePath = 'docs/mcp/readme.md'
+	const outputPath = 'src/scaffolds/generated.ts'
+
+	const types = ['feature', 'client', 'server', 'command', 'endpoint', 'selector']
+	const scaffolds: Record<string, ScaffoldData> = {}
+
+	for (const type of types) {
+		const filePath = `${scaffoldDir}/${type}.md`
+		if (!fs.exists(filePath)) {
+			console.log(`   ⏭  ${filePath} (not found, skipping)`)
+			continue
+		}
+
+		const content = fs.readFile(filePath)
+		scaffolds[type] = parseScaffoldMarkdown(content)
+		console.log(`   📄 ${type}: ${scaffolds[type].sections.length} sections, full template: ${scaffolds[type].full ? 'yes' : 'no'}`)
+	}
+
+	// Bundle the assistant example as a multi-file scaffold
+	const assistantDir = 'docs/examples/assistant'
+	const assistantFiles: Record<string, string> = {}
+	const assistantFileNames = ['CORE.md', 'tools.ts', 'hooks.ts']
+	for (const fileName of assistantFileNames) {
+		const filePath = `${assistantDir}/${fileName}`
+		if (fs.exists(filePath)) {
+			assistantFiles[fileName] = fs.readFile(filePath)
+		}
+	}
+	if (Object.keys(assistantFiles).length > 0) {
+		console.log(`   📄 assistant: ${Object.keys(assistantFiles).length} files (${Object.keys(assistantFiles).join(', ')})`)
+	}
+
+	// Read the MCP readme
+	let mcpReadme = ''
+	if (fs.exists(readmePath)) {
+		mcpReadme = fs.readFile(readmePath)
+		console.log(`   📄 MCP readme: ${mcpReadme.length} chars`)
+	} else {
+		console.log(`   ⚠️  ${readmePath} not found`)
+	}
+
+	// Generate the output file
+	const escapeForTemplate = (s: string) => s.replace(/\\/g, '\\\\').replace(/`/g, '\\`').replace(/\$\{/g, '\\${')
+
+	const scaffoldEntries = Object.entries(scaffolds).map(([type, data]) => {
+		const sectionsStr = data.sections.map(s =>
+			`      { heading: ${JSON.stringify(s.heading)}, code: \`${escapeForTemplate(s.code)}\` }`
+		).join(',\n')
+
+		return `  ${type}: {
+    sections: [
+${sectionsStr}
+    ],
+    full: \`${escapeForTemplate(data.full)}\`,
+    tutorial: \`${escapeForTemplate(data.tutorial)}\`,
+  }`
+	}).join(',\n')
+
+	const assistantFilesEntries = Object.entries(assistantFiles).map(([name, content]) =>
+		`    ${JSON.stringify(name)}: \`${escapeForTemplate(content)}\``
+	).join(',\n')
+
+	const output = `// Auto-generated scaffold and MCP readme content
+// Generated at: ${new Date().toISOString()}
+// Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
+//
+// Do not edit manually. Run: luca build-scaffolds
+
+export interface ScaffoldSection {
+  heading: string
+  code: string
+}
+
+export interface ScaffoldData {
+  sections: ScaffoldSection[]
+  full: string
+  tutorial: string
+}
+
+export const scaffolds: Record<string, ScaffoldData> = {
+${scaffoldEntries}
+}
+
+export const assistantFiles: Record<string, string> = {
+${assistantFilesEntries}
+}
+
+export const mcpReadme = \`${escapeForTemplate(mcpReadme)}\`
+`
+
+	fs.ensureFolder('src/scaffolds')
+	await fs.writeFileAsync(outputPath, output)
+	console.log(`\n✨ Generated ${outputPath}`)
+}
+
+export default {
+	description: 'Generate scaffold templates and MCP readme from docs/scaffolds/*.md',
+	argsSchema,
+	handler: buildScaffolds,
+}

package/commands/generate-api-docs.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+import { CommandOptionsSchema } from '@soederpop/luca/schemas'
+import { AGIContainer } from '../src/agi/container.server.js'
+import { __INTROSPECTION__ } from '../src/introspection/index.js'
+import { presentIntrospectionAsMarkdown } from '../src/helper.js'
+
+export const argsSchema = CommandOptionsSchema.extend({
+  clean: z.boolean().default(false).describe('Remove existing docs/apis folder before generating'),
+})
+
+/** Parse setBuildTimeData shortcut IDs from a generated introspection file */
+function parseGeneratedIds(content: string): { features: string[]; servers: string[]; clients: string[] } {
+  const features: string[] = []
+  const servers: string[] = []
+  const clients: string[] = []
+
+  for (const match of content.matchAll(/setBuildTimeData\('([^']+)'/g)) {
+    const id = match[1]
+    if (id.startsWith('features.')) features.push(id.replace('features.', ''))
+    else if (id.startsWith('servers.')) servers.push(id.replace('servers.', ''))
+    else if (id.startsWith('clients.')) clients.push(id.replace('clients.', ''))
+  }
+
+  return { features, servers, clients }
+}
+
+async function generateApiDocs(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const fs = context.container.feature('fs')
+  const baseDir = 'docs/apis'
+
+  if (options.clean) {
+    try { await fs.rmdir(baseDir) } catch {}
+  }
+
+  // Parse the generated introspection files to determine which helpers belong to which container
+  const nodeContent = fs.readFile('src/introspection/generated.node.ts')
+  const agiContent = fs.readFile('src/introspection/generated.agi.ts')
+  const webContent = fs.readFile('src/introspection/generated.web.ts')
+
+  const nodeIds = parseGeneratedIds(nodeContent)
+  const agiIds = parseGeneratedIds(agiContent)
+  const webIds = parseGeneratedIds(webContent)
+
+  // AGI-only features = features in agi that aren't in node
+  const nodeFeatureSet = new Set(nodeIds.features)
+  const agiOnlyFeatures = agiIds.features.filter(f => !nodeFeatureSet.has(f))
+
+  // Load web build-time data so __INTROSPECTION__ has web entries
+  await import('../src/introspection/generated.web.js')
+
+  // Use AGIContainer for rendering — it has all node+agi registries loaded
+  const agiContainer = new AGIContainer()
+
+  const groups: { dir: string; registryName: string; ids: string[] }[] = [
+    { dir: `${baseDir}/features/node`, registryName: 'features', ids: nodeIds.features },
+    { dir: `${baseDir}/features/agi`, registryName: 'features', ids: agiOnlyFeatures },
+    { dir: `${baseDir}/features/web`, registryName: 'features', ids: webIds.features },
+    { dir: `${baseDir}/servers`, registryName: 'servers', ids: agiIds.servers },
+    // Clients are registered at runtime, not in generated files — use live registry
+    { dir: `${baseDir}/clients`, registryName: 'clients', ids: agiContainer.clients.available },
+  ]
+
+  let totalFiles = 0
+
+  for (const group of groups) {
+    fs.ensureFolder(group.dir)
+    console.log(`\n📁 ${group.dir}`)
+
+    const registry = (agiContainer as any)[group.registryName]
+
+    for (const id of group.ids) {
+      try {
+        let markdown: string | undefined
+
+        if (registry.has(id)) {
+          markdown = registry.describe(id)
+        } else {
+          // Fallback: render from __INTROSPECTION__ map directly (e.g. web-only features)
+          const introspectionKey = `${group.registryName}.${id}`
+          const data = __INTROSPECTION__.get(introspectionKey)
+          if (data) {
+            markdown = presentIntrospectionAsMarkdown(data)
+          }
+        }
+
+        if (!markdown || !markdown.trim()) {
+          console.log(`   ⏭  ${id} (no introspection data)`)
+          continue
+        }
+
+        const fileName = toKebab(id) + '.md'
+        await fs.writeFileAsync(`${group.dir}/${fileName}`, markdown)
+        console.log(`   📄 ${fileName}`)
+        totalFiles++
+      } catch (err: any) {
+        console.log(`   ⚠️  ${id}: ${err.message}`)
+      }
+    }
+  }
+
+  console.log(`\n✨ Generated ${totalFiles} API docs in ${baseDir}/`)
+}
+
+/** Convert camelCase shortcut to kebab-case filename */
+function toKebab(str: string): string {
+  return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
+}
+
+export default {
+  description: 'Generate API reference docs from introspection data for all registries.',
+  argsSchema,
+  handler: generateApiDocs,
+}