@soederpop/luca 0.0.7 → 0.0.9

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/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/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/docs/bootstrap/templates/runme.md

@@ -0,0 +1,54 @@
+# 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.7",
+  "version": "0.0.9",
   "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-19T00:28:07.695Z
+// Generated at: 2026-03-19T04:48:18.099Z
 // Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
 //
 // Do not edit manually. Run: luca build-bootstrap
@@ -536,5 +536,60 @@ export async function get(_params: any, ctx: any) {
     uptime: process.uptime(),
   }
 }
+`,
+  "runme": `# 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/src/commands/bootstrap.ts

@@ -74,7 +74,10 @@ async function bootstrap(options: z.infer<typeof argsSchema>, context: Container
 	// ── 8. luca.cli.ts ─────────────────────────────────────────────
 	await writeFile(fs, ui, mkPath('luca.cli.ts'), bootstrapTemplates['luca-cli'] || '', 'luca.cli.ts')
 
-	// ── 9. .claude/settings.json (permissions for AI coding tools) ──
+	// ── 9. RUNME.md ────────────────────────────────────────────────
+	await writeFile(fs, ui, mkPath('RUNME.md'), bootstrapTemplates['runme'] || '', 'RUNME.md')
+
+	// ── 10. .claude/settings.json (permissions for AI coding tools) ──
 	const settingsPath = mkPath('.claude', 'settings.json')
 	const claudeSettings = {
 		permissions: {
@@ -113,6 +116,7 @@ async function bootstrap(options: z.infer<typeof argsSchema>, context: Container
 	ui.print('    luca about            — project info + discovered helpers')
 	ui.print('    luca serve            — start the API server (try /api/health)')
 	ui.print('    luca describe fs      — learn about any built-in feature')
+	ui.print('    luca RUNME            — run the interactive markdown demo')
 	ui.print('')
 	ui.print('  Need to build something? Use scaffold:\n')
 	ui.print('    luca scaffold command deploy    — add a CLI command')

package/src/commands/describe.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { commands } from '../command.js'
 import { CommandOptionsSchema } from '../schemas/base.js'
 import type { ContainerContext } from '../container.js'
-import type { IntrospectionSection } from '../introspection/index.js'
+import type { IntrospectionSection, MethodIntrospection, GetterIntrospection } from '../introspection/index.js'
 
 declare module '../command.js' {
 	interface AvailableCommands {
@@ -67,6 +67,7 @@ type ResolvedTarget =
 	| { kind: 'container' }
 	| { kind: 'registry'; name: RegistryName }
 	| { kind: 'helper'; registry: RegistryName; id: string }
+	| { kind: 'member'; registry: RegistryName; id: string; member: string; memberType: 'method' | 'getter' }
 
 class DescribeError extends Error {
 	constructor(message: string) {
@@ -117,9 +118,44 @@ function fuzzyFind(registry: any, input: string): string | undefined {
 	return (registry.available as string[]).find((id: string) => normalize(id) === norm)
 }
 
+/**
+ * Try to resolve "helperName.memberName" by searching all registries for the helper,
+ * then checking if memberName is a method or getter on it.
+ * Returns a 'member' target or null if no match.
+ */
+function resolveHelperMember(helperName: string, memberName: string, container: any): ResolvedTarget | null {
+	for (const registryName of REGISTRY_NAMES) {
+		const reg = container[registryName]
+		if (!reg) continue
+		const found = fuzzyFind(reg, helperName)
+		if (!found) continue
+
+		const Ctor = reg.lookup(found)
+		const introspection = Ctor.introspect?.()
+		if (!introspection) continue
+
+		if (introspection.methods?.[memberName]) {
+			return { kind: 'member', registry: registryName, id: found, member: memberName, memberType: 'method' }
+		}
+		if (introspection.getters?.[memberName]) {
+			return { kind: 'member', registry: registryName, id: found, member: memberName, memberType: 'getter' }
+		}
+
+		// If we found the helper but not the member, give a helpful error
+		const allMembers = [
+			...Object.keys(introspection.methods || {}).map((m: string) => m + '()'),
+			...Object.keys(introspection.getters || {}),
+		].sort()
+		throw new DescribeError(
+			`"${memberName}" is not a known method or getter on ${found}.\n\nAvailable members:\n  ${allMembers.join(', ')}`
+		)
+	}
+	return null
+}
+
 /**
  * Parse a single target string into a resolved target.
- * Accepts: "container", "features", "features.fs", "fs", etc.
+ * Accepts: "container", "features", "features.fs", "fs", "ui.banner", etc.
  */
 function resolveTarget(target: string, container: any): ResolvedTarget {
 	const lower = target.toLowerCase()
@@ -153,6 +189,12 @@ function resolveTarget(target: string, container: any): ResolvedTarget {
 			}
 			return { kind: 'helper', registry, id: resolved }
 		}
+
+		// Not a registry prefix — try "helper.member" (e.g. "ui.banner", "fs.readFile")
+		const helperName = prefix!
+		const memberName = rest.join('.')
+		const memberResult = resolveHelperMember(helperName, memberName, container)
+		if (memberResult) return memberResult
 	}
 
 	// Unqualified name: search all registries (fuzzy)
@@ -546,6 +588,76 @@ function buildHelperSummary(Ctor: any): string {
 	return lines.join('\n')
 }
 
+function getMemberData(container: any, registryName: RegistryName, id: string, member: string, memberType: 'method' | 'getter', headingDepth = 1): { json: any; text: string } {
+	const registry = container[registryName]
+	const Ctor = registry.lookup(id)
+	const introspection = Ctor.introspect?.()
+	const h = '#'.repeat(headingDepth)
+	const hSub = '#'.repeat(headingDepth + 1)
+
+	if (memberType === 'method') {
+		const method = introspection?.methods?.[member] as MethodIntrospection | undefined
+		if (!method) return { json: {}, text: `No introspection data for ${id}.${member}()` }
+
+		const parts: string[] = []
+		parts.push(`${h} ${id}.${member}()`)
+		parts.push(`> method on **${introspection.className || id}**`)
+
+		if (method.description) parts.push(method.description)
+
+		// Parameters
+		const paramEntries = Object.entries(method.parameters || {})
+		if (paramEntries.length > 0) {
+			const paramLines = [`${hSub} Parameters`, '']
+			for (const [name, info] of paramEntries) {
+				const req = (method.required || []).includes(name) ? ' *(required)*' : ''
+				paramLines.push(`- **${name}** \`${info.type}\`${req}${info.description ? ' — ' + info.description : ''}`)
+				// Nested properties (e.g. options objects)
+				if (info.properties) {
+					for (const [propName, propInfo] of Object.entries(info.properties)) {
+						paramLines.push(`  - **${propName}** \`${propInfo.type}\`${propInfo.description ? ' — ' + propInfo.description : ''}`)
+					}
+				}
+			}
+			parts.push(paramLines.join('\n'))
+		}
+
+		// Returns
+		if (method.returns && method.returns !== 'void') {
+			parts.push(`${hSub} Returns\n\n\`${method.returns}\``)
+		}
+
+		// Examples
+		if (method.examples?.length) {
+			parts.push(`${hSub} Examples`)
+			for (const ex of method.examples) {
+				parts.push(`\`\`\`${ex.language || 'typescript'}\n${ex.code}\n\`\`\``)
+			}
+		}
+
+		return { json: { [member]: method, _helper: id, _type: 'method' }, text: parts.join('\n\n') }
+	}
+
+	// Getter
+	const getter = introspection?.getters?.[member] as GetterIntrospection | undefined
+	if (!getter) return { json: {}, text: `No introspection data for ${id}.${member}` }
+
+	const parts: string[] = []
+	parts.push(`${h} ${id}.${member}`)
+	parts.push(`> getter on **${introspection.className || id}** — returns \`${getter.returns || 'unknown'}\``)
+
+	if (getter.description) parts.push(getter.description)
+
+	if (getter.examples?.length) {
+		parts.push(`${hSub} Examples`)
+		for (const ex of getter.examples) {
+			parts.push(`\`\`\`${ex.language || 'typescript'}\n${ex.code}\n\`\`\``)
+		}
+	}
+
+	return { json: { [member]: getter, _helper: id, _type: 'getter' }, text: parts.join('\n\n') }
+}
+
 function getHelperData(container: any, registryName: RegistryName, id: string, sections: (IntrospectionSection | 'description')[], noTitle = false, headingDepth = 1): { json: any; text: string } {
 	const registry = container[registryName]
 	const Ctor = registry.lookup(id)
@@ -628,6 +740,8 @@ export default async function describe(options: z.infer<typeof argsSchema>, cont
 				return getRegistryData(container, item.name, sections, noTitle, headingDepth)
 			case 'helper':
 				return getHelperData(container, item.registry, item.id, sections, noTitle, headingDepth)
+			case 'member':
+				return getMemberData(container, item.registry, item.id, item.member, item.memberType, headingDepth)
 		}
 	}
 

package/src/commands/run.ts

@@ -16,6 +16,38 @@ export const argsSchema = CommandOptionsSchema.extend({
 	dontInjectContext: z.boolean().default(false).describe('Skip auto-injecting container context into scripts (run with plain bun instead)'),
 })
 
+/**
+ * Convert esbuild ESM output imports/exports to CJS require/module.exports
+ * so the code can run in a vm context that provides `require`.
+ */
+function esmToCjs(code: string): string {
+	return code
+		// import { a, b } from 'x' → const { a, b } = require('x')
+		.replace(/^import\s+\{([^}]+)\}\s+from\s+(['"][^'"]+['"])\s*;?$/gm,
+			'const {$1} = require($2);')
+		// import x from 'y' → const x = require('y').default ?? require('y')
+		.replace(/^import\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?$/gm,
+			'const $1 = require($2).default ?? require($2);')
+		// import * as x from 'y' → const x = require('y')
+		.replace(/^import\s+\*\s+as\s+(\w+)\s+from\s+(['"][^'"]+['"])\s*;?$/gm,
+			'const $1 = require($2);')
+		// import 'y' → require('y')
+		.replace(/^import\s+(['"][^'"]+['"])\s*;?$/gm,
+			'require($1);')
+		// export default → module.exports.default =
+		.replace(/^export\s+default\s+/gm, 'module.exports.default = ')
+		// export { ... } → strip (vars already in scope)
+		.replace(/^export\s+\{[^}]*\}\s*;?$/gm, '')
+		// export const/let/var → const/let/var
+		.replace(/^export\s+(const|let|var)\s+/gm, '$1 ')
+}
+
+function hasTLA(code: string): boolean {
+	// Quick check: contains await outside of async function bodies
+	// This is a heuristic — wrapTopLevelAwait does the real work
+	return /\bawait\b/.test(code) && !/^\s*\(?\s*async\b/.test(code)
+}
+
 function resolveScript(ref: string, context: ContainerContext): string | null {
 	const container = context.container as any
 	const candidates = [
@@ -141,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')))
 
@@ -196,7 +231,17 @@ async function runScript(scriptPath: string, context: ContainerContext, options:
 	const vm = container.feature('vm')
 	const esbuild = container.feature('esbuild')
 	const raw = container.fs.readFile(scriptPath)
-	const { code } = esbuild.transformSync(raw, { format: 'cjs' })
+
+	let code: string
+	if (hasTLA(raw)) {
+		// TLA is incompatible with CJS format, so transform as ESM (preserves await)
+		// then convert import/export statements to require/module.exports for the vm
+		const { code: esm } = esbuild.transformSync(raw, { format: 'esm' })
+		code = esmToCjs(esm)
+	} else {
+		const { code: cjs } = esbuild.transformSync(raw, { format: 'cjs' })
+		code = cjs
+	}
 
 	const ctx = {
 		require: vm.createRequireFor(scriptPath),

package/src/node/features/esbuild.ts

@@ -31,7 +31,7 @@ export class ESBuild extends Feature {
     return esbuild.transformSync(code, {
       loader: 'ts',
       format: 'esm',
-      target: 'es2020',
+      target: 'esnext',
       sourcemap: false,
       minify: false,
       ...options
@@ -48,7 +48,7 @@ export class ESBuild extends Feature {
     return esbuild.transform(code, {
       loader: 'ts',
       format: 'esm',
-      target: 'es2020',
+      target: 'esnext',
       sourcemap: false,
       minify: false,
       ...options
@@ -69,7 +69,7 @@ export class ESBuild extends Feature {
       bundle: true,
       platform: 'node',
       format: 'esm',
-      target: 'es2020',
+      target: 'esnext',
       write: false,
       ...options
     })

package/test/vm-context.test.ts

@@ -0,0 +1,146 @@
+import { describe, it, expect } from 'bun:test'
+import { NodeContainer } from '../src/node/container'
+
+/**
+ * These tests verify the VM context preservation behavior that `luca run`
+ * depends on for markdown execution. When running sequential code blocks
+ * in a shared context, variables defined in earlier blocks must be accessible
+ * in later blocks — as long as the blocks don't use top-level await (which
+ * wraps code in an async IIFE and isolates the scope).
+ */
+describe('VM context preservation across sequential runs', () => {
+	it('preserves const declarations across runs without await', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const x = 42', shared)
+		const result = await vm.run('x', shared)
+
+		expect(result).toBe(42)
+	})
+
+	it('preserves let declarations across runs without await', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('let count = 0', shared)
+		await vm.run('count += 10', shared)
+		const result = await vm.run('count', shared)
+
+		expect(result).toBe(10)
+	})
+
+	it('preserves function declarations across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('function double(n) { return n * 2 }', shared)
+		const result = await vm.run('double(21)', shared)
+
+		expect(result).toBe(42)
+	})
+
+	it('preserves arrow functions assigned to const', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const greet = (name) => `hello ${name}`', shared)
+		const result = await vm.run('greet("world")', shared)
+
+		expect(result).toBe('hello world')
+	})
+
+	it('preserves objects and allows mutation across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const data = { items: [] }', shared)
+		await vm.run('data.items.push("a", "b")', shared)
+		await vm.run('data.items.push("c")', shared)
+		const result = await vm.run('data.items', shared)
+
+		expect(result).toEqual(['a', 'b', 'c'])
+	})
+
+	it('preserves class declarations across runs', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('class Counter { constructor() { this.n = 0 } inc() { this.n++ } }', shared)
+		await vm.run('const counter = new Counter(); counter.inc(); counter.inc()', shared)
+		const result = await vm.run('counter.n', shared)
+
+		expect(result).toBe(2)
+	})
+
+	it('later blocks can compose values from earlier blocks', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		await vm.run('const firstName = "Jane"', shared)
+		await vm.run('const lastName = "Doe"', shared)
+		await vm.run('const fullName = `${firstName} ${lastName}`', shared)
+		const result = await vm.run('fullName', shared)
+
+		expect(result).toBe('Jane Doe')
+	})
+
+	it('top-level await blocks lose const/let scope (known limitation)', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({})
+
+		// This block has await, so it gets wrapped in (async () => { ... })()
+		// The const is scoped to that IIFE and doesn't leak to the shared context
+		await vm.run('const val = await Promise.resolve(99)', shared)
+		const result = await vm.run('typeof val', shared)
+
+		expect(result).toBe('undefined')
+	})
+
+	it('top-level await blocks can share state via pre-existing context properties', async () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+		const shared = vm.createContext({ result: null })
+
+		// Assigning to an existing context property works even inside the IIFE
+		await vm.run('result = await Promise.resolve("async value")', shared)
+		const value = await vm.run('result', shared)
+
+		expect(value).toBe('async value')
+	})
+})
+
+describe('VM wrapTopLevelAwait', () => {
+	it('does not wrap code without await', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const code = 'const x = 42'
+		expect(vm.wrapTopLevelAwait(code)).toBe(code)
+	})
+
+	it('wraps code containing await in an async IIFE', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const wrapped = vm.wrapTopLevelAwait('const x = await fetch("http://example.com")')
+		expect(wrapped).toContain('async')
+		expect(wrapped).toContain('await fetch')
+	})
+
+	it('does not wrap code already in an async function', () => {
+		const c = new NodeContainer()
+		const vm = c.feature('vm')
+
+		const code = 'async function go() { await fetch("http://example.com") }'
+		expect(vm.wrapTopLevelAwait(code)).toBe(code)
+	})
+})

package/tmp/.cache/luca-disk-cache/content-v2/sha512/1b/b5/c75b28794f00f94c4d609a98978e9420e9b7146d204a7fbf5b0b30477292581705d207c0100dabaac27eef540aaaece3374af75104a93219d4ec8bfb44e7

@@ -1 +0,0 @@
-["d587b833-0933-4782-8c20-ad1c28d12c7a"]

package/tmp/.cache/luca-disk-cache/content-v2/sha512/da/df/1d90ce4e042abeb035a197832c6d6893420a747a056be773eb00e4f745a037d505c8db13dde7d36b36b6b893addbb7df0f5fe9f0c13e665f20056447318b

@@ -1 +0,0 @@
-{"id":"d587b833-0933-4782-8c20-ad1c28d12c7a","title":"Untitled","model":"gpt-5.2","tags":[],"thread":"assistant:zapldb:2026-03-15","createdAt":"2026-03-15T03:08:58.783Z","updatedAt":"2026-03-15T03:08:58.783Z","messageCount":5,"metadata":{}}

package/tmp/.cache/luca-disk-cache/content-v2/sha512/ed/04/e1d0c2a58c2db29b3921ca2affb3ea4febe831c53b38ebc21019fb799823aba6ed5b4611873d2cd25d422d49955b852a9c326da0d678899bc1c2c2960901

@@ -1 +0,0 @@
-{"id":"d587b833-0933-4782-8c20-ad1c28d12c7a","title":"Untitled","model":"gpt-5.2","messages":[{"role":"system","content":"# Luca Assistant Example\n\nYou are currently an example / template \"Assistant\" provided by the Luca framework.  ( You'll probably have no idea what that is, don't worry, it doesn't matter ).\n\nYou are what gets scaffolded when a user writes the `luca scaffold assistant` command.\n\nIn luca, an Assistant is backed by a folder which has a few components:\n\n- CORE.md -- this is a markdown file that will get injected into the system prompt of a chat completion call\n- tools.ts -- this file is expected to export functions, and a schemas object whose keys are the names of the functions that get exported, and whose values are zod v4 schemas that describe the parameters\n- hooks.ts -- this file is expexted to export functions, whose names match the events emitted by the luca assistant helper\n\nCurrently, the user is chatting with you from the `luca chat` CLI.  \n\nYou should tell them what each of these files is and how to edit them.\n\nIt is also important for them to know that the luca `container` is globally available for them in the context of the `tools.ts` and `hooks.ts` files."},{"role":"user","content":"What should we do?"},{"role":"assistant","content":null,"tool_calls":[{"id":"call_bwGYIZLkPRtuqUMVRAg8ykPy","type":"function","function":{"name":"README","arguments":"{}"}}]},{"role":"tool","tool_call_id":"call_bwGYIZLkPRtuqUMVRAg8ykPy","content":"YO YO"},{"role":"assistant","content":"You’ll typically do three things: customize the assistant’s behavior (CORE.md), add capabilities (tools.ts), and wire up lifecycle events (hooks.ts).\n\n## 1) Edit `CORE.md` (behavior + policy)\n**What it is:** A markdown file whose contents get injected into the **system prompt** at runtime. This is where you define the assistant’s identity, boundaries, style, domain knowledge, do/don’t rules, and any project-specific instructions.\n\n**What to put in it:**\n- Role + purpose (“You are an assistant that helps with X…”)\n- Tone/format preferences (concise, code-first, etc.)\n- Hard constraints (what it must never do, how it handles secrets, etc.)\n- Domain context (your product, APIs, repos, conventions)\n\n**When to edit:** Any time you want the assistant to “think/behave differently” without changing code.\n\n---\n\n## 2) Edit `tools.ts` (add callable functions)\n**What it is:** A TypeScript module that exports:\n- **functions** the model can call as tools (e.g., `searchDocs`, `runQuery`, `readFile`, `createTicket`)\n- a **`schemas` object** mapping tool/function names → **zod v4 schemas** describing parameters\n\n**Why it matters:** Tools are how your assistant safely does real work (fetch data, manipulate files, call APIs) instead of guessing.\n\n**Key points:**\n- Keep tools small and composable.\n- Validate all inputs with zod schemas.\n- Return structured data the model can use.\n\n**Important:** The luca **`container`** is globally available inside `tools.ts`. Use it to access shared services/config (whatever your luca setup provides) without manually importing/constructing everything.\n\n---\n\n## 3) Edit `hooks.ts` (react to events)\n**What it is:** A TypeScript module exporting functions whose names match luca assistant helper **events** (lifecycle hooks). These run automatically when those events fire (e.g., session start, before/after tool call, etc.—depending on what luca emits in your setup).\n\n**Use cases:**\n- Logging / tracing\n- Metrics\n- Tool-call auditing\n- Injecting/refreshing context\n- Guardrails (block certain actions, redact secrets)\n\n**Important:** The luca **`container`** is also globally available in `hooks.ts`.\n\n---\n\n## What to do next (practical plan)\n1) **Open `CORE.md`** and write 10–30 lines that clearly define the assistant’s job and constraints.\n2) **Add 1–2 tools** in `tools.ts` that reflect what you actually want the assistant to be able to do (start minimal).\n3) **Add a basic hook** in `hooks.ts` for logging (so you can see what’s happening and iterate safely).\n4) Run `luca chat` again and test; tighten instructions/schemas based on failures.\n\nIf you tell me what your assistant is supposed to help with (e.g., “triage support tickets”, “write PRs”, “query an internal API”), I can suggest exactly what to put into `CORE.md` and the first tools/hooks to implement."}],"tags":[],"thread":"assistant:zapldb:2026-03-15","createdAt":"2026-03-15T03:08:58.783Z","updatedAt":"2026-03-15T03:08:58.783Z","messageCount":5,"metadata":{}}

package/tmp/.cache/luca-disk-cache/index-v5/00/13/572aa4c9a94f99eda999695d050cdd0ca7fe2d23a50af03234d4c8ce0791

@@ -1,2 +0,0 @@
-
-0633d48140563c44b78c1c0b9ff1c1fc5d79b689	{"key":"conversation-history:__index__","integrity":"sha512-G7XHWyh5TwD5TE1gmpiXjpQg6bcUbSBKf79bCzBHcpJYFwXSB8AQDauqwn7vVAqq7OM3SvdRBKkyGdTsi/tE5w==","time":1773544138800,"size":40}

package/tmp/.cache/luca-disk-cache/index-v5/75/a9/cb61dc0f0589e8ec10a9aca27b834bc73884c479941042d22a2b22324cd3

@@ -1,2 +0,0 @@
-
-db975a1cc1e358a00d66dab7a468db4ee63eb62d	{"key":"conversation-history:meta:d587b833-0933-4782-8c20-ad1c28d12c7a","integrity":"sha512-2t8dkM5OBCq+sDWhl4MsbWiTQgp0egVr53PrAOT3RaA31QXI2xPd59NrNra4k63bt98PX+nwwT5mXyAFZEcxiw==","time":1773544138799,"size":240}

package/tmp/.cache/luca-disk-cache/index-v5/9f/0f/8b1f915ee64cfff7667dd96acd7a5ac0a96aa91a346e19cefd45909a9c9c

@@ -1,2 +0,0 @@
-
-74e795aeefad56844bf7be3dc434e7e99a145283	{"key":"conversation-history:d587b833-0933-4782-8c20-ad1c28d12c7a","integrity":"sha512-7QTh0MKljC2ymzkhyir/s+pP6+gxxTs468IQGft5mCOrpu1bRhGHPSzSXUItSZVbhSqcMm2g1niJm8HCwpYJAQ==","time":1773544138797,"size":4603}