@soederpop/luca 0.0.5 → 0.0.7

package/src/bootstrap/generated.ts

@@ -0,0 +1,540 @@
+// Auto-generated bootstrap content
+// Generated at: 2026-03-19T00:28:07.695Z
+// Source: docs/bootstrap/*.md, docs/bootstrap/templates/*
+//
+// Do not edit manually. Run: luca build-bootstrap
+
+export const bootstrapFiles: Record<string, string> = {
+  "SKILL": `---
+name: Using the luca framework
+description: Learn the luca container — discover what's available with luca describe, build new helpers with luca scaffold, and prototype with luca eval
+---
+# Luca: Learning the Container
+
+The Luca framework \`@soederpop/luca\` ships a \`luca\` binary — a bun-based CLI for a dependency injection container. This project is based on it if this skill is present. The container auto-discovers modules in \`commands/\`, \`clients/\`, \`servers/\`, \`features/\`, and \`endpoints/\` folders.
+
+There are three things to learn, in this order:
+
+1. **Discover** what the container can do — \`luca describe\`
+2. **Build** new helpers when your project needs them — \`luca scaffold\`
+3. **Prototype** and debug with live code — \`luca eval\`
+
+---
+
+## Phase 1: Discover with \`luca describe\`
+
+This is your primary tool. Before reading source files, searching for APIs, or writing any code — ask describe. It outputs full documentation for any part of the container: methods, options, events, state, examples.
+
+### See what's available
+
+\`\`\`shell
+luca describe features     # index of all available features
+luca describe clients      # index of all available clients
+luca describe servers      # index of all available servers
+\`\`\`
+
+### Learn about specific helpers
+
+\`\`\`shell
+luca describe fs           # full docs for the fs feature
+luca describe git          # full docs for git
+luca describe rest         # full docs for the rest client
+luca describe express      # full docs for the express server
+luca describe git fs proc  # multiple helpers in one shot
+\`\`\`
+
+### Get targeted documentation
+
+You can filter to only the sections you need:
+
+\`\`\`shell
+luca describe fs --methods          # just the methods
+luca describe git --events          # just the events it emits
+luca describe express --options     # just the constructor options
+luca describe fs git --examples     # just examples for both
+luca describe fs --usage --methods  # combine sections
+\`\`\`
+
+### Describe the container itself
+
+\`\`\`shell
+luca describe              # overview of the container
+luca describe self         # same thing
+\`\`\`
+
+### Get help on any command
+
+\`\`\`shell
+luca                       # list all available commands
+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.
+
+---
+
+## Phase 2: Build with \`luca scaffold\`
+
+When your project needs a new helper, scaffold it. The \`scaffold\` command generates correct boilerplate — you fill in the logic.
+
+### Learn how to build each type
+
+Before creating anything, read the tutorial for that helper type:
+
+\`\`\`shell
+luca scaffold feature --tutorial    # how features work, full guide
+luca scaffold command --tutorial    # how commands work
+luca scaffold endpoint --tutorial   # how endpoints work
+luca scaffold client --tutorial     # how clients work
+luca scaffold server --tutorial     # how servers work
+\`\`\`
+
+These tutorials are the authoritative reference for each helper type. They cover imports, schemas, class structure, registration, conventions, and complete examples.
+
+### Generate a helper
+
+\`\`\`shell
+luca scaffold <type> <name> --description "What it does"
+\`\`\`
+
+The workflow after scaffolding:
+
+\`\`\`shell
+luca scaffold command sync-data --description "Pull data from staging"
+# edit commands/sync-data.ts — add your logic
+luca describe sync-data            # verify it shows up and reads correctly
+\`\`\`
+
+Every scaffolded helper is auto-discovered by the container at runtime.
+
+### When to use each type
+
+| You need to...                                     | Scaffold a...  | Example                                                        |
+|----------------------------------------------------|----------------|----------------------------------------------------------------|
+| Add a reusable local capability (caching, crypto)  | **feature**    | \`luca scaffold feature disk-cache --description "File-backed key-value cache"\` |
+| Add a CLI task (build, deploy, generate)           | **command**    | \`luca scaffold command deploy --description "Deploy to production"\` |
+| Talk to an external API or service                 | **client**     | \`luca scaffold client github --description "GitHub API wrapper"\` |
+| Accept incoming connections (HTTP, WS)             | **server**     | \`luca scaffold server mqtt --description "MQTT broker"\` |
+| Add a REST route to \`luca serve\`                   | **endpoint**   | \`luca scaffold endpoint users --description "User management API"\` |
+
+### Scaffold options
+
+\`\`\`shell
+luca scaffold command deploy --description "..."    # writes to commands/deploy.ts
+luca scaffold endpoint users --print                # print to stdout instead of writing
+luca scaffold feature cache --output lib/cache.ts   # override output path
+\`\`\`
+
+---
+
+## Phase 3: Prototype with \`luca eval\`
+
+Once you know what's available (describe) and how to build things (scaffold), use \`luca eval\` to test ideas, verify behavior, and debug.
+
+\`\`\`shell
+luca eval "container.features.available"
+luca eval "container.feature('proc').exec('ls')"
+luca eval "container.feature('fs').readFile('package.json')"
+\`\`\`
+
+The eval command boots a full container with all helpers discovered and registered. Core features are available as top-level shortcuts:
+
+\`\`\`shell
+luca eval "fs.readFile('package.json')"
+luca eval "git.branch"
+luca eval "proc.exec('ls')"
+\`\`\`
+
+**Reach for eval when you're stuck.** It gives you full control of the container at runtime — you can test method calls, inspect state, verify event behavior, and debug issues that are hard to reason about from docs alone.
+
+**Use eval as a testing tool.** Before wiring up a full command handler or feature, test your logic in eval first. Want to verify how \`fs.moveAsync\` behaves, or whether a watcher event fires the way you expect? Run it in eval. This is the fastest way to validate container code without the overhead of building the full command around it.
+
+\`\`\`shell
+# Test file operations before building a command around them
+luca eval "await fs.moveAsync('inbox/test.json', 'inbox/valid/test.json')"
+
+# First: luca describe fileManager --events  (to learn what events exist)
+# Then test the behavior:
+luca eval "const fm = container.feature('fileManager'); fm.on('file:change', (e) => console.log(e)); await fm.watch({ paths: ['inbox'] })"
+\`\`\`
+
+### The REPL
+
+For interactive exploration, \`luca console\` opens a persistent REPL with the container in scope. Useful when you need to try multiple things in sequence.
+
+---
+
+## Key Concepts
+
+### The Container
+
+The container is a singleton that holds everything your application needs. It organizes components into **registries**: features, clients, servers, commands, and endpoints. Use the factory functions to get instances:
+
+\`\`\`js
+const fs = container.feature('fs')
+const rest = container.client('rest')
+const server = container.server('express')
+\`\`\`
+
+### State
+
+Every helper and the container itself have observable state:
+
+\`\`\`js
+const feature = container.feature('fs')
+
+feature.state.current              // snapshot of all state
+feature.state.get('someKey')       // single value
+feature.state.set('key', 'value')  // update
+
+// Watch for changes
+feature.state.observe((changeType, key, value) => {
+  // changeType: 'add' | 'update' | 'delete'
+})
+\`\`\`
+
+The container has state too: \`container.state.current\`, \`container.state.observe()\`.
+
+### Events
+
+Every helper and the container are event emitters — \`on\`, \`once\`, \`emit\`, \`waitFor\` all work as expected. Use \`luca describe <name> --events\` to see what a helper emits.
+
+### Utilities
+
+The container provides common utilities at \`container.utils\` — no external imports needed:
+
+- \`container.utils.uuid()\` — v4 UUID
+- \`container.utils.hashObject(obj)\` — deterministic hash
+- \`container.utils.stringUtils\` — camelCase, kebabCase, pluralize, etc.
+- \`container.utils.lodash\` — groupBy, keyBy, pick, omit, debounce, etc.
+- \`container.paths.resolve()\` / \`container.paths.join()\` — path operations
+
+### Programmatic introspection
+
+Everything \`luca describe\` outputs is also available at runtime in code:
+
+\`\`\`js
+container.features.describe('fs')   // markdown docs (same as the CLI)
+feature.introspect()                // structured object: { methods, events, state, options }
+container.inspectAsText()           // full container overview as markdown
+\`\`\`
+
+This is useful inside commands and scripts where you need introspection data programmatically.
+
+---
+
+## Reference
+
+See \`references/api-docs/\` for the full pre-generated API reference for every built-in feature, client, and server.
+`,
+  "CLAUDE": `# Luca Project
+
+This project uses the [Luca framework](https://github.com/soederpop/luca) — Lightweight Universal Conversational Architecture.
+
+For a deep dive into the framework internals, see the [Luca GitHub repository](https://github.com/soederpop/luca).
+
+## Runtime
+
+The runtime is **bun**. Use \`bun run\` for scripts, \`bun test\` for tests.
+
+## The \`luca\` CLI
+
+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 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
+- \`luca scaffold <type> <name>\` — generate boilerplate for a new helper (run \`luca scaffold\` for full help)
+
+## Container Rules
+
+- **NEVER import from \`fs\`, \`path\`, or other Node builtins.** Use \`container.feature('fs')\` for file operations, \`container.paths\` for path operations.
+- The container should provide everything you need. If something is missing, raise the concern rather than pulling in external dependencies.
+- Use \`container.utils\` for common utilities (uuid, lodash helpers, string utils).
+
+## 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.)
+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
+
+## Project Structure
+
+- \`commands/\` — custom CLI commands, run via \`luca <commandName>\` (auto-discovered)
+- \`endpoints/\` — file-based HTTP routes, served via \`luca serve\` (auto-discovered)
+- \`features/\` — custom container features, discovered via \`container.helpers.discoverAll()\` (auto-discovered)
+- \`docs/\` — content documents managed by the \`contentDb\` feature (\`container.docs\`). See [contentbase](https://github.com/soederpop/contentbase) for the document model system.
+- \`luca.cli.ts\` — optional project-level CLI customization (runs before any command)
+
+## Command Arguments
+
+Command handlers receive \`(options, context)\`. The \`options\` object contains:
+- **Named flags** from \`argsSchema\`: \`--verbose\` → \`options.verbose\`
+- **Positional args** mapped via \`positionals\` export: \`luca cmd ./src\` → \`options.target\`
+- **Raw positionals** in \`options._\`: array where \`_[0]\` is the command name, \`_[1+]\` are positional args
+
+To accept positional arguments, export a \`positionals\` array that maps them to named fields in \`argsSchema\`:
+
+\`\`\`ts
+export const positionals = ['target']  // luca myCmd ./src => options.target === './src'
+export const argsSchema = z.object({
+  target: z.string().optional().describe('The target to operate on'),
+  verbose: z.boolean().default(false).describe('Enable verbose output'),
+})
+\`\`\`
+
+## What's Available
+
+The container provides more than you might expect. Before importing anything external, check here:
+
+- **YAML** — \`container.feature('yaml')\` wraps \`js-yaml\`. Use \`.parse(str)\` and \`.stringify(obj)\`.
+- **SQLite** — \`container.feature('sqlite')\` for databases. Parameterized queries, tagged templates.
+- **REST client** — \`container.client('rest', { baseURL })\`. Methods (\`get\`, \`post\`, etc.) return **parsed JSON directly**, not \`{ data, status, headers }\`. On HTTP errors, the error is returned (not thrown).
+- **Content DB** — \`container.docs\` (alias for \`container.feature('contentDb')\`) manages markdown documents with frontmatter. Query with \`docs.query(docs.models.MyModel).fetchAll()\`.
+- **Grep** — \`container.feature('grep')\` has \`search()\` and \`codeAnnotations()\` for finding TODOs/FIXMEs/etc.
+- **chalk** — available as \`container.feature('ui').colors\`, not via \`import('chalk')\`.
+- **figlet** — available as \`container.feature('ui').asciiArt(text)\`.
+- **uuid** — \`container.utils.uuid()\`
+- **lodash** — \`container.utils.lodash\` (groupBy, keyBy, pick, omit, debounce, etc.)
+- **string utils** — \`container.utils.stringUtils\` (camelCase, kebabCase, pluralize, etc.)
+
+## Known Gotchas
+
+- **For DELETE endpoint handlers, use \`export { del as delete }\`** — \`delete\` is a JS reserved word. Define your function with any name, then re-export it as \`delete\`.
+- **Bun globals (\`Bun.spawn\`, \`Bun.serve\`) are unavailable** in command/endpoint handlers. Use Node's \`child_process\` for spawning processes, or use \`container.feature('proc').exec()\`.
+- **\`ui.print.*\` writes to stdout** — if your command supports \`--json\`, gate UI output behind \`if (!options.json)\`.
+- **VM contexts start empty** — when using \`container.feature('vm')\`, inject globals explicitly (\`console\`, \`Date\`, \`Promise\`, \`crypto\`, \`TextEncoder\`, \`setTimeout\`).
+- **Long-running commands** (servers, watchers) need \`await new Promise(() => {})\` at the end with a \`process.on('SIGINT', ...)\` handler for cleanup.
+- **Shared state between endpoints**: use \`ctx.request.app.locals\` to share data across endpoint files.
+- **Database init**: use \`luca.cli.ts\` \`main()\` hook for table creation and seeding — it runs before any command or server starts.
+
+## Extending the Container
+
+Use \`luca scaffold\` to generate new helpers:
+
+\`\`\`sh
+luca scaffold command myTask --description "Automate something"
+luca scaffold feature myCache --description "Custom caching layer"
+luca scaffold endpoint users --description "User management API"
+\`\`\`
+
+Run \`luca scaffold\` with no arguments for full usage and examples.
+
+## Git Strategy
+
+Roll on main. Commit with good messages that explain why, not just what.
+`
+}
+
+export const bootstrapTemplates: Record<string, string> = {
+  "docs-models": `import { defineModel, z } from 'contentbase'
+
+/**
+ * Define your content models here. Each model maps to a folder prefix
+ * inside the docs/ directory. Documents in those folders follow the
+ * model's metadata schema.
+ *
+ * Access documents at runtime:
+ *   const docs = container.docs          // contentDb feature
+ *   if (!docs.isLoaded) await docs.load()
+ *   const notes = await docs.query(docs.models.Note).fetchAll()
+ *
+ * See https://github.com/soederpop/contentbase for full documentation.
+ */
+
+export const Note = defineModel('Note', {
+  prefix: 'notes',
+  meta: z.object({
+    tags: z.array(z.string()).default([]),
+    status: z.enum(['draft', 'published']).default('draft'),
+  }),
+})
+`,
+  "luca-cli": `/**
+ * luca.cli.ts — Project-level CLI customization
+ *
+ * This file is automatically loaded by the \`luca\` CLI before any command runs.
+ * Use it to:
+ *
+ * - Discover project-level helpers (features, commands, endpoints)
+ * - Register custom context variables accessible in \`luca eval\`
+ * - Set up project-specific container configuration
+ *
+ * Exports:
+ *   main(container)    — called at CLI startup, before command execution
+ *   onStart(container) — called when the container's 'started' event fires
+ *
+ * Example:
+ *   export async function main(container: any) {
+ *     await container.helpers.discoverAll()
+ *     container.addContext('myFeature', container.feature('myFeature'))
+ *   }
+ */
+
+export async function main(container: any) {
+  // Discover project-level helpers (commands/, features/, endpoints/)
+  await container.helpers.discoverAll()
+}
+`,
+  "docs-readme": `# Docs
+
+This folder contains structured content documents managed by the [contentbase](https://github.com/soederpop/contentbase) system.
+
+## How it works
+
+Documents are markdown files with YAML frontmatter. Each document belongs to a **model** defined in \`docs/models.ts\`. Models specify:
+- A **prefix** (subfolder name, e.g. \`notes/\`)
+- A **metadata schema** (validated frontmatter fields)
+
+## Accessing documents at runtime
+
+The \`contentDb\` feature (aliased to \`container.docs\`) loads and queries documents:
+
+\`\`\`typescript
+const docs = container.docs
+if (!docs.isLoaded) await docs.load()
+
+// Query all notes
+const notes = await docs.query(docs.models.Note).fetchAll()
+
+// Get a specific document
+const doc = docs.collection('notes').document('my-note')
+\`\`\`
+
+## Creating a new document
+
+Add a markdown file in the appropriate subfolder:
+
+\`\`\`markdown
+---
+title: My First Note
+tags: [example]
+status: draft
+---
+
+Content goes here.
+\`\`\`
+
+## Learn more
+
+- [Contentbase GitHub](https://github.com/soederpop/contentbase) — full documentation and API reference
+- \`luca describe contentDb\` — runtime docs for the contentDb feature
+`,
+  "example-feature": `import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema } from '@soederpop/luca'
+import { Feature } from '@soederpop/luca'
+import type { ContainerContext } from '@soederpop/luca'
+
+declare module '@soederpop/luca' {
+  interface AvailableFeatures {
+    example: typeof Example
+  }
+}
+
+const ExampleStateSchema = FeatureStateSchema.extend({
+  greetCount: z.number().default(0).describe('Number of times greet() has been called'),
+})
+type ExampleState = z.infer<typeof ExampleStateSchema>
+
+const ExampleOptionsSchema = FeatureOptionsSchema.extend({})
+type ExampleOptions = z.infer<typeof ExampleOptionsSchema>
+
+/**
+ * An example feature demonstrating the luca feature pattern.
+ *
+ * Discovered automatically by \`container.helpers.discoverAll()\`
+ * and available as \`container.feature('example')\`.
+ *
+ * To learn more: \`luca scaffold feature --tutorial\`
+ *
+ * @example
+ * \`\`\`typescript
+ * const example = container.feature('example')
+ * example.greet('Luca') // => "Hello, Luca! (greeting #1)"
+ * \`\`\`
+ */
+export class Example extends Feature<ExampleState, ExampleOptions> {
+  static override shortcut = 'features.example' as const
+  static override stateSchema = ExampleStateSchema
+  static override optionsSchema = ExampleOptionsSchema
+  static override description = 'An example feature demonstrating the luca feature pattern'
+  static { Feature.register(this, 'example') }
+
+  /**
+   * A simple method to show the feature works.
+   * @param name - Name to greet
+   * @returns Greeting string
+   */
+  greet(name = 'World') {
+    const count = (this.state.get('greetCount') || 0) + 1
+    this.state.set('greetCount', count)
+    return \`Hello, \${name}! (greeting #\${count})\`
+  }
+}
+
+export default Example
+`,
+  "about-command": `/**
+ * about — Display project information and discovered helpers.
+ * Run with: luca about
+ *
+ * Positional words after the command name are available as options._
+ * For example: \`luca about commands\` → options._[1] === 'commands'
+ */
+import { z } from 'zod'
+import type { ContainerContext } from '@soederpop/luca'
+
+export const description = 'Display project information and discovered helpers'
+
+export const argsSchema = z.object({})
+
+export default async function about(options: z.infer<typeof argsSchema>, context: ContainerContext) {
+  const { container } = context
+  const ui = container.feature('ui')
+
+  // Discover all project-level helpers (commands, features, endpoints, etc.)
+  const discovered = await container.helpers.discoverAll()
+
+  const projectName = container.paths.resolve('.').split('/').pop() || 'project'
+
+  ui.print.cyan(\`\\n  \${projectName}\\n\`)
+  ui.print('  Powered by luca — Lightweight Universal Conversational Architecture\\n')
+
+  const types = ['features', 'clients', 'servers', 'commands', 'endpoints']
+
+  for (const type of types) {
+    const names = discovered[type] || []
+    if (names.length > 0) {
+      ui.print.green(\`  \${type} (\${names.length})\`)
+      for (const name of names) {
+        ui.print(\`    • \${name}\`)
+      }
+    }
+  }
+
+  const totalBuiltIn = types.reduce((sum: number, t: string) => sum + (container[t]?.available?.length || 0), 0)
+  ui.print.dim(\`\\n  \${totalBuiltIn} built-in helpers available. Run \\\`luca describe\\\` for details.\\n\`)
+}
+`,
+  "health-endpoint": `/**
+ * Health check endpoint.
+ * Accessible at GET /api/health when you run \`luca serve\`.
+ */
+export const path = '/api/health'
+export const description = 'Health check endpoint'
+export const tags = ['health']
+
+export async function get(_params: any, ctx: any) {
+  return {
+    status: 'ok',
+    timestamp: Date.now(),
+    uptime: process.uptime(),
+  }
+}
+`
+}

package/src/cli/cli.ts

@@ -5,30 +5,74 @@ import { homedir } from 'os'
 import { join } from 'path'
 
 async function main() {
+	const profile = process.env.LUCA_PROFILE === '1'
+	const t = (label?: string) => {
+		if (!profile) return () => {}
+		const start = performance.now()
+		return (suffix?: string) => {
+			const ms = (performance.now() - start).toFixed(1)
+			console.error(`[profile] ${label}${suffix ? ` ${suffix}` : ''}: ${ms}ms`)
+		}
+	}
+
+	const tTotal = t('total boot')
+
+	// LUCA_COMMAND_DISCOVERY: "disable" skips all, "no-local" skips project, "no-home" skips user
+	const discovery = process.env.LUCA_COMMAND_DISCOVERY || ''
+
+	// Snapshot built-in commands BEFORE loadCliModule — luca.cli.ts may call
+	// helpers.discoverAll() which registers project commands early
+	const builtinCommands = new Set(container.commands.available as string[])
+
 	// Load project-level CLI module (luca.cli.ts) for container customization
+	let done = t('loadCliModule')
 	await loadCliModule()
+	done()
+
 	// Discover project-local commands (commands/ or src/commands/)
-	await discoverProjectCommands()
+	done = t('discoverProjectCommands')
+	if (discovery !== 'disable' && discovery !== 'no-local') {
+		await discoverProjectCommands()
+	}
+	done()
+	const afterProject = new Set(container.commands.available as string[])
+	const projectCommands = new Set([...afterProject].filter((n) => !builtinCommands.has(n)))
+
 	// Discover user-level commands (~/.luca/commands/)
-	await discoverUserCommands()
+	done = t('discoverUserCommands')
+	if (discovery !== 'disable' && discovery !== 'no-home') {
+		await discoverUserCommands()
+	}
+	done()
+	const afterUser = new Set(container.commands.available as string[])
+	const userCommands = new Set([...afterUser].filter((n) => !builtinCommands.has(n) && !projectCommands.has(n)))
+
+	// Store command sources for help display
+	;(container as any)._commandSources = { builtinCommands, projectCommands, userCommands }
+
 	// Load generated introspection data if present
+	done = t('loadProjectIntrospection')
 	await loadProjectIntrospection()
+	done()
 
 	const commandName = container.argv._[0] as string
 
+	done = t('dispatch')
 	if (commandName && container.commands.has(commandName)) {
 		const cmd = container.command(commandName as any)
-		await cmd.run()
+		await cmd.dispatch()
 	} else if (commandName) {
 		// not a known command — treat as implicit `run`
 		container.argv._.splice(0, 0, 'run')
 		const cmd = container.command('run' as any)
-		await cmd.run()
+		await cmd.dispatch()
 	} else {
 		container.argv._.splice(0, 0, 'help')
 		const cmd = container.command('help' as any)
-		await cmd.run()
+		await cmd.dispatch()
 	}
+	done()
+	tTotal()
 }
 
 
@@ -36,28 +80,26 @@ async function loadCliModule() {
 	const modulePath = container.paths.resolve('luca.cli.ts')
 	if (!container.fs.exists(modulePath)) return
 
-	const mod = await import(modulePath)
-	const exports = mod.default || mod
+	// Use the helpers feature to load the module — it handles the native import
+	// vs VM decision using the same useNativeImport check as discovery
+	const helpers = container.feature('helpers') as any
+	const exports = await helpers.loadModuleExports(modulePath)
 
-	if (typeof exports.main === 'function') {
+	if (typeof exports?.main === 'function') {
 		await exports.main(container)
 	}
 
-	if (typeof exports.onStart === 'function') {
+	if (typeof exports?.onStart === 'function') {
 		container.once('started', () => exports.onStart(container))
 	}
 }
 
 async function discoverProjectCommands() {
-	const { fs, paths } = container
-
-	for (const candidate of ['commands', 'src/commands']) {
-		const dir = paths.resolve(candidate)
-		if (fs.exists(dir)) {
-			await container.commands.discover({ directory: dir })
-			return
-		}
-	}
+	// Always route through the helpers feature — it handles native import vs VM
+	// internally, and deduplicates concurrent/repeated discovery via promise caching.
+	// If luca.cli.ts already called helpers.discoverAll(), this resolves instantly.
+	const helpers = container.feature('helpers') as any
+	await helpers.discover('commands')
 }
 
 async function loadProjectIntrospection() {
@@ -81,11 +123,12 @@ async function loadProjectIntrospection() {
 }
 
 async function discoverUserCommands() {
-	const { fs } = container
 	const dir = join(homedir(), '.luca', 'commands')
 
-	if (fs.exists(dir)) {
-		await container.commands.discover({ directory: dir })
+	if (container.fs.exists(dir)) {
+		// Route through helpers for consistent dedup and VM/native handling
+		const helpers = container.feature('helpers') as any
+		await helpers.discover('commands', { directory: dir })
 	}
 }