@soederpop/luca 0.0.6 → 0.0.8

package/CLAUDE.md

@@ -56,7 +56,8 @@ When creating a new feature (e.g. `gws`), all four of these steps must be comple
 
 1. **Feature file** — `src/node/features/gws.ts`
    - Export the class: `export class Gws extends Feature { ... }`
-   - Register at bottom: `export default features.register('gws', Gws)`
+   - Register inside the class: `static { Feature.register(this, 'gws') }`
+   - Default export is just the class: `export default Gws`
 
 2. **Side-effect import** — `src/node/container.ts` (import block ~line 20-63)
    - Add `import "./features/gws";` (this triggers registration)
@@ -79,6 +80,14 @@ If the feature has a test, it goes in `test/gws.test.ts`.
 - For more descriptive things like class descriptions, method descriptions, we rely on jsdoc blocks.  These are parsed and used to generate modules we commit to source.  We shouldn't let these drift, so for this reason we have a pre-commit hook which ensures they're up to date
 - We rely on module augmentation a lot to make sure `container.feature()` can provide type signatures for everything that gets added to it by extension modules down the road.  ( kind of like we did with AGIContainer extending NodeContainer )
 
+## Generated Files — Build Artifacts
+
+**Files matching `generated.ts` or `.generated*.ts` are BUILD ARTIFACTS, not source of truth.** They are produced by the introspection system (which parses JSDoc blocks, Zod schemas, etc.) and bundled into the binary at compile time. **Never edit these files directly** — your changes will be overwritten on the next build.
+
+The source of truth for scaffolds and templates is the markdown files and the actual source code with their JSDoc annotations. If scaffold output is wrong, fix the markdown source or the JSDoc blocks on the real classes, then rebuild.
+
+This means **JSDoc blocks on helpers (features, clients, servers) must be valid and complete** — they are picked up by the introspection system, used to generate API docs, scaffold tutorials, and the `luca describe` output. Treat JSDoc as documentation infrastructure, not comments.
+
 ## Testing
 
 - Test runner is **bun** (not vitest). Do not import from or add vitest.

package/RUNME.md

@@ -0,0 +1,56 @@
+# Runnable Markdown
+
+The `luca` CLI allows you to run markdown blocks as long as they're tagged with `ts` in the language.
+
+```ts
+const banner = ui.banner('LUCA', { 
+    font: 'Puffy', 
+    colors: ['red','white','blue'] 
+})
+
+ui.print(banner)
+```
+
+What is kind of cool is ( so long as there's no top-level-await in the block ) the context will preserve:
+
+```ts
+if(typeof banner === 'undefined') { 
+    ui.print.red('uh oh, something broke.')
+}
+```
+
+You can skip blocks too with the skip tag in the language of the fenced block
+
+```ts skip
+console.log('Not gonna say anything')
+```
+
+Did you hear something? No. 
+
+Something even cooler is the ability to render React blocks.  This makes luca kind of like a poor man's MDX.  I just define some Blocks in the markdown by creating an h2 `## Blocks` section with a fenced codeblock that uses `tsx`. The `ink.components` and `ink.React` globals are injected into the scope.
+
+## Blocks
+
+```tsx
+const { Box, Text } = ink.components
+const React = ink.React
+
+function Greeting({ name, role }) {
+  return (
+    <Box borderStyle="round" padding={1}>
+      <Text color="green" bold>Hello {name}!</Text>
+      <Text dimColor> ({role})</Text>
+    </Box>
+  )
+}
+```
+
+## Rendering React Blocks
+
+Then I can use the Blocks in code. 
+
+```ts
+await render('Greeting', { name: 'Jon', role: 'Humble Servant' })
+```
+
+

package/bun.lock

@@ -18,7 +18,7 @@
         "chokidar": "^3.5.3",
         "cli-markdown": "^3.5.0",
         "compromise": "^14.14.5",
-        "contentbase": "",
+        "contentbase": "^0.0.5",
         "cors": "^2.8.5",
         "detect-port": "^1.5.1",
         "dotenv": "^17.2.4",

package/commands/build-bootstrap.ts

@@ -0,0 +1,78 @@
+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`)
+		}
+	}
+
+	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 output = `// Auto-generated bootstrap content
+// Generated at: ${new Date().toISOString()}
+// Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
+//
+// Do not edit manually. Run: luca build-bootstrap
+
+export const bootstrapFiles: Record<string, string> = {
+${fileEntries}
+}
+
+export const bootstrapTemplates: Record<string, string> = {
+${templateEntries}
+}
+`
+
+	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-scaffolds.ts

@@ -77,7 +77,7 @@ async function buildScaffolds(options: z.infer<typeof argsSchema>, context: Cont
 	const readmePath = 'docs/mcp/readme.md'
 	const outputPath = 'src/scaffolds/generated.ts'
 
-	const types = ['feature', 'client', 'server', 'command', 'endpoint']
+	const types = ['feature', 'client', 'server', 'command', 'endpoint', 'selector']
 	const scaffolds: Record<string, ScaffoldData> = {}
 
 	for (const type of types) {
@@ -92,6 +92,20 @@ async function buildScaffolds(options: z.infer<typeof argsSchema>, context: Cont
 		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)) {
@@ -118,9 +132,13 @@ ${sectionsStr}
   }`
 	}).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 and docs/mcp/readme.md
+// Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds
 
@@ -139,6 +157,10 @@ export const scaffolds: Record<string, ScaffoldData> = {
 ${scaffoldEntries}
 }
 
+export const assistantFiles: Record<string, string> = {
+${assistantFilesEntries}
+}
+
 export const mcpReadme = \`${escapeForTemplate(mcpReadme)}\`
 `