@soederpop/luca 0.1.2 → 0.2.1

package/src/node/features/content-db.ts

@@ -5,6 +5,7 @@ import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
 import { realpathSync } from 'node:fs'
 import type { GrepOptions } from './grep.js'
+import type { Helper } from '../../helper.js'
 
 export const ContentDbStateSchema = FeatureStateSchema.extend({
   loaded: z.boolean().default(false).describe('Whether the content collection has been loaded and parsed'),
@@ -46,70 +47,96 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   static { Feature.register(this, 'contentDb') }
 
   /** Tools that any assistant can use to progressively explore this collection. */
-  static tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+  static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     getCollectionOverview: {
       schema: z.object({}).describe(
-        'Get a high-level overview of the document collection: models, document counts, directory tree, and search index status. Call this first to understand what is available.'
+        'Get a high-level overview of the document collection: what models exist, how many documents each has, the directory tree, and search index status. Call this FIRST to understand the collection before exploring individual documents.'
       ),
     },
     listDocuments: {
       schema: z.object({
-        model: z.string().optional().describe('Filter to documents belonging to this model name'),
-        glob: z.string().optional().describe('Glob pattern to filter document path IDs (e.g. "guides/*", "apis/**")'),
+        model: z.string().optional().describe('Filter to documents of this model type (e.g. "Plan", "Task"). Get model names from getCollectionOverview.'),
+        glob: z.string().optional().describe('Glob pattern to filter by document path (e.g. "guides/*", "apis/**/*.md")'),
       }).describe(
-        'List available document IDs in the collection, optionally filtered by model or glob pattern.'
+        'List document IDs in the collection. Use this to browse what\'s available before reading. Filter by model or glob to narrow results.'
       ),
     },
     readDocument: {
       schema: z.object({
-        id: z.string().describe('The document path ID to read (e.g. "guides/intro")'),
-        include: z.array(z.string()).optional().describe('Only return these section headings'),
-        exclude: z.array(z.string()).optional().describe('Remove these section headings from the output'),
-        meta: z.boolean().optional().describe('Include YAML frontmatter in the output'),
+        id: z.string().describe('The document path ID (e.g. "guides/intro", "apis/auth"). Get valid IDs from listDocuments.'),
+        include: z.array(z.string()).optional().describe('Only return sections with these headings. Use to read specific parts of long documents without loading everything.'),
+        exclude: z.array(z.string()).optional().describe('Skip sections with these headings. Use to filter out irrelevant parts.'),
+        meta: z.boolean().optional().describe('Include the YAML frontmatter (title, status, tags, etc.) in the output. Useful for understanding document metadata.'),
       }).describe(
-        'Read a single document by its path ID. Use include/exclude to read only specific sections and avoid loading unnecessary content.'
+        'Read a document by its path ID. Use include/exclude to request only the sections you need — don\'t load an entire document when you only need one section.'
       ),
     },
     readMultipleDocuments: {
       schema: z.object({
-        ids: z.array(z.string()).describe('Array of document path IDs to read'),
-        include: z.array(z.string()).optional().describe('Only return these section headings from each document'),
-        exclude: z.array(z.string()).optional().describe('Remove these section headings from each document'),
-        meta: z.boolean().optional().describe('Include YAML frontmatter in the output'),
+        ids: z.array(z.string()).describe('Array of document path IDs to read. Get valid IDs from listDocuments.'),
+        include: z.array(z.string()).optional().describe('Only return sections with these headings from each document.'),
+        exclude: z.array(z.string()).optional().describe('Skip sections with these headings from each document.'),
+        meta: z.boolean().optional().describe('Include YAML frontmatter for each document.'),
       }).describe(
-        'Read multiple documents at once, concatenated with dividers. Use include/exclude to focus on relevant sections.'
+        'Read multiple documents in one call. More efficient than calling readDocument in a loop. Returns documents concatenated with dividers.'
       ),
     },
     queryDocuments: {
       schema: z.object({
-        model: z.string().describe('The model name to query (e.g. "Plan", "Task")'),
-        where: z.string().optional().describe('Filter conditions as JSON string, e.g. \'{ "meta.status": "approved" }\' or \'{ "meta.priority": { "$gt": 3 } }\''),
-        sort: z.string().optional().describe('Sort specification as JSON string, e.g. \'{ "meta.priority": "desc" }\''),
-        limit: z.number().optional().describe('Maximum number of results to return'),
-        offset: z.number().optional().describe('Number of results to skip'),
-        select: z.array(z.string()).optional().describe('Fields to include in output (e.g. ["id", "title", "meta.status"])'),
+        model: z.string().describe('The model name to query (e.g. "Plan", "Task", "Guide"). Must match a model defined in the collection — check getCollectionOverview.'),
+        where: z.string().optional().describe('MongoDB-style filter as a JSON string. Dot notation for nested fields. Examples: \'{"meta.status": "approved"}\', \'{"meta.priority": {"$gt": 3}}\', \'{"meta.tags": {"$in": ["urgent"]}}\''),
+        sort: z.string().optional().describe('Sort as a JSON string. Example: \'{"meta.priority": "desc"}\', \'{"meta.createdAt": "asc"}\''),
+        limit: z.number().optional().describe('Maximum number of results. Default: all matching documents.'),
+        offset: z.number().optional().describe('Skip this many results (for pagination).'),
+        select: z.array(z.string()).optional().describe('Only include these fields in output (e.g. ["id", "title", "meta.status"]). Reduces noise when you only need specific metadata.'),
       }).describe(
-        'Query documents by model with MongoDB-style filtering, sorting, and pagination. Returns serialized model instances.'
+        'Query documents by model with filtering, sorting, and pagination. Use this when you need to find documents matching specific criteria (status, priority, tags, dates) rather than browsing by name.'
       ),
     },
     searchContent: {
       schema: z.object({
-        pattern: z.string().describe('Regex pattern to search for across all documents'),
-        caseSensitive: z.boolean().optional().describe('Whether the search is case-sensitive (default: false)'),
+        pattern: z.string().describe('Regex pattern to search for across all document content. Examples: "TODO|FIXME", "authentication", "def.*handler"'),
+        caseSensitive: z.boolean().optional().describe('Case-sensitive search. Default: false (case insensitive).'),
       }).describe(
-        'Text/regex search (grep) across all documents in the collection. Returns matching lines with file context.'
+        'Text/regex search (grep) across all documents. Use for exact pattern matching, code references, or finding specific terms. Returns matching lines with file context. For natural language questions, use semanticSearch instead.'
       ),
     },
     semanticSearch: {
       schema: z.object({
-        query: z.string().describe('Natural language search query'),
-        limit: z.number().optional().describe('Maximum number of results (default: 10)'),
+        query: z.string().describe('A natural language question or topic description. Example: "how does the authentication flow work?" or "deployment configuration options"'),
+        limit: z.number().optional().describe('Maximum results to return. Default: 10.'),
       }).describe(
-        'Semantic search across documents using keyword + vector similarity. Falls back to text search if no search index exists.'
+        'Search documents using natural language — combines keyword matching with semantic similarity. Best for questions and topic exploration. Falls back to text search if no vector index exists. For exact pattern matching, use searchContent instead.'
       ),
     },
   }
 
+  /**
+   * When an assistant uses contentDb, inject system prompt guidance
+   * about progressive document exploration.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('contentDb', [
+        '## Document Collection',
+        '',
+        'You have access to a structured document collection (markdown files with frontmatter, organized by model/type).',
+        '',
+        '**Progressive exploration — go broad to narrow:**',
+        '1. `getCollectionOverview` — start here. Shows models, document counts, and directory structure.',
+        '2. `listDocuments` — browse document IDs, optionally filtered by model or glob.',
+        '3. `readDocument` — read a specific document. Use `include`/`exclude` to skip irrelevant sections.',
+        '4. `queryDocuments` — filter documents by metadata (status, priority, tags, etc.) with MongoDB-style queries.',
+        '',
+        '**Searching:**',
+        '- `semanticSearch` — best for natural language questions ("how does authentication work?")',
+        '- `searchContent` — best for exact patterns, code references, or regex across all documents',
+        '',
+        '**Efficiency:** Don\'t read entire documents when you only need one section. Use `include` to request specific headings. Use `readMultipleDocuments` to batch reads instead of calling `readDocument` in a loop.',
+      ].join('\n'))
+    }
+  }
+
   override get initialState(): ContentDbState {
     return {
       ...super.initialState,
@@ -460,7 +487,7 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
     // Dynamically import and attach SemanticSearch if not already registered
     const { SemanticSearch } = await import('./semantic-search.js')
     if (!this.container.features.available.includes('semanticSearch')) {
-      SemanticSearch.attach(this.container as any)
+      ;(SemanticSearch as any).attach(this.container as any)
     }
 
     // Store search index in ~/.luca/contentbase/{hash}/ keyed by the real (symlink-resolved) collection path
@@ -660,7 +687,7 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   get queries(): Record<string, ReturnType<typeof this.query>> {
     const queryChains: [string, ReturnType<typeof this.query>][] = []
     for (const modelName of this.modelNames) {
-      const queryChain = this.query(this.models[modelName])
+      const queryChain = this.query(this.models[modelName]!)
       const pluralized = this.container.utils.stringUtils.pluralize(modelName).toLowerCase()
       queryChains.push([modelName.toLowerCase(), queryChain])
       queryChains.push([pluralized, queryChain])

package/src/node/features/file-manager.ts

@@ -147,7 +147,7 @@ export class FileManager<
 
   /** Returns the list of directories currently being watched. */
   get watchedPaths(): string[] {
-    return this.state.get("watchedPaths") || [];
+    return (this.state.get("watchedPaths") as string[] | undefined) || [];
   }
 
   /** 
@@ -199,7 +199,7 @@ export class FileManager<
       const { git } = this.container;
       if (!git.isRepo) return null;
 
-      const gitDir = pathJoin(git.repoRoot, '.git');
+      const gitDir = pathJoin(git.repoRoot!, '.git');
       const head = readFileSync(pathJoin(gitDir, 'HEAD'), 'utf8').trim();
 
       // Detached HEAD — already a sha
@@ -217,7 +217,7 @@ export class FileManager<
         const ref = head.slice(5);
         const packed = readFileSync(packedRefsPath, 'utf8');
         const match = packed.match(new RegExp(`^([0-9a-f]{40}) ${ref}`, 'm'));
-        if (match) return match[1];
+        if (match) return match[1] ?? null;
       }
 
       return null;
@@ -334,8 +334,8 @@ export class FileManager<
       if (cwdRelative) {
         const prefix = cwdRelative + '/';
         for (let i = 0; i < fileIds.length; i++) {
-          if (fileIds[i].startsWith(prefix)) {
-            fileIds[i] = fileIds[i].slice(prefix.length);
+          if (fileIds[i]!.startsWith(prefix)) {
+            fileIds[i] = fileIds[i]!.slice(prefix.length);
           }
         }
       }
@@ -422,12 +422,12 @@ export class FileManager<
 
     // If already watching, just add the new paths
     if (this.isWatching && this.watcher) {
-      const currentPaths: string[] = this.state.get("watchedPaths") || [];
+      const currentPaths: string[] = (this.state.get("watchedPaths") as string[] | undefined) || [];
       const newPaths = pathsToWatch.filter(p => !currentPaths.includes(p));
 
       if (newPaths.length) {
         this.watcher.add(newPaths);
-        this.state.set("watchedPaths", [...currentPaths, ...newPaths]);
+        this.state.set("watchedPaths", [...currentPaths, ...newPaths] as any);
       }
 
       return;
@@ -481,7 +481,7 @@ export class FileManager<
 
     watcher.on("ready", () => {
       this.state.set("watching", true);
-      this.state.set("watchedPaths", pathsToWatch);
+      this.state.set("watchedPaths", pathsToWatch as any);
     });
 
     this.watcher = watcher;
@@ -495,7 +495,7 @@ export class FileManager<
     if (this.watcher) {
       this.watcher.close();
       this.state.set("watching", false);
-      this.state.set("watchedPaths", []);
+      this.state.set("watchedPaths", [] as any);
       this.watcher = null;
     }
   }
@@ -508,6 +508,7 @@ export class FileManager<
       const stats = statSync(absolutePath);
       this.files.set(path, {
         dirname: dir,
+        relativeDirname: this.container.paths.relative(dir),
         absolutePath,
         relativePath: path,
         name,

package/src/node/features/git.ts

@@ -155,7 +155,7 @@ export class Git extends Feature {
      */
     get branch(): string | null {
         if(!this.isRepo) { return null }
-        return this.container.feature('proc').exec(`${this.gitPath} branch`).split("\n").filter(line => line.startsWith('*')).map(line => line.replace('*', '').trim()).pop()
+        return this.container.feature('proc').exec(`${this.gitPath} branch`).split("\n").filter(line => line.startsWith('*')).map(line => line.replace('*', '').trim()).pop() ?? null
     }
     
     /**
@@ -230,7 +230,7 @@ export class Git extends Feature {
      */
     get repoRoot(): string | null {
         if (this.state.has('repoRoot')) {
-            return this.state.get('repoRoot')
+            return this.state.get('repoRoot') ?? null
         }
 
         const repoRoot = this.container.fs.findUp('.git')
@@ -507,12 +507,12 @@ export class Git extends Feature {
         if (str.startsWith('github.com/')) str = str.replace('github.com/', '')
         if (str.includes('#')) {
             const parts = str.split('#')
-            str = parts[0]
-            ref = parts[1]
+            str = parts[0] ?? str
+            ref = parts[1] ?? ref
         }
 
         const parts = str.split('/')
-        return { user: parts[0], repo: parts[1], ref, subdir: parts.slice(2).join('/') }
+        return { user: parts[0] ?? '', repo: parts[1] ?? '', ref, subdir: parts.slice(2).join('/') }
     }
 
     /**

package/src/node/features/helpers.ts

@@ -201,7 +201,7 @@ export class Helpers extends Feature<HelpersState, HelpersOptions> {
     }
 
     // Schemas
-    const schemasModule = { CommandOptionsSchema: commands.baseClass?.optionsSchema || z.object({}) }
+    const schemasModule: Record<string, any> = { CommandOptionsSchema: commands.baseClass?.optionsSchema || z.object({}) }
     try {
       // Pull all base schemas from the already-loaded schemas/base module
       const baseSchemas = require('../../schemas/base.js')

package/src/node/features/json-tree.ts

@@ -121,7 +121,7 @@ export class JsonTree<T extends JsonTreeState = JsonTreeState> extends Feature<T
     for (const file of jsonFiles.filter(Boolean)) {
       if (file?.relativePath) {
         const fileContent = fileSystem.readFile(file.relativePath);
-        const fileData = JSON.parse(fileContent);
+        const fileData = JSON.parse(String(fileContent));
         const path = file.relativePath
           .replace(/\.json$/, "")
           .replace(basePath + "/", "")

package/src/node/features/os.ts

@@ -207,12 +207,12 @@ export class OS extends Feature {
           displays.push({
             name: d._name ?? 'Unknown',
             resolution: {
-              width: resMatch ? parseInt(resMatch[1], 10) : 0,
-              height: resMatch ? parseInt(resMatch[2], 10) : 0,
+              width: resMatch ? parseInt(resMatch[1] ?? '0', 10) : 0,
+              height: resMatch ? parseInt(resMatch[2] ?? '0', 10) : 0,
             },
             retina: /retina/i.test(d._spdisplays_resolution ?? '') || /retina/i.test(d.spdisplays_display_type ?? ''),
             main: d.spdisplays_main === 'spdisplays_yes' || /yes/i.test(d.spdisplays_main ?? ''),
-            refreshRate: hzMatch ? parseFloat(hzMatch[1]) : undefined,
+            refreshRate: hzMatch ? parseFloat(hzMatch[1] ?? '0') : undefined,
             connectionType: d.spdisplays_connection_type ?? undefined,
           })
         }

package/src/node/features/package-finder.ts

@@ -296,7 +296,7 @@ export class PackageFinder<
    */
   get scopes(): string[] {
     return Array.from(
-      new Set(this.packageNames.filter(p => p.startsWith('@')).map(p => p.split('/')[0]))
+      new Set(this.packageNames.filter(p => p.startsWith('@')).map(p => p.split('/')[0]).filter((s): s is string => s !== undefined))
     )
   }
  

package/src/node/features/process-manager.ts

@@ -4,6 +4,7 @@ import { Feature } from '../feature.js'
 import { State } from '../../state.js'
 import { Bus, type EventMap } from '../../bus.js'
 import type { ChildProcess } from './proc.js'
+import type { Helper } from '../../helper.js'
 
 // ─── Output Buffer ─────────────────────────────────────────────────────────
 
@@ -436,46 +437,46 @@ export class ProcessManager extends Feature {
   static { Feature.register(this, 'processManager') }
 
   /** Tools that an assistant can use to spawn and manage processes. */
-  static tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
+  static override tools: Record<string, { schema: z.ZodType; handler?: Function }> = {
     spawnProcess: {
       schema: z.object({
-        command: z.string().describe('The command to execute (e.g. "node", "bun", "python")'),
-        args: z.string().optional().describe('Space-separated arguments to pass to the command'),
-        tag: z.string().optional().describe('A label for this process so you can find it later'),
-        cwd: z.string().optional().describe('Working directory for the process'),
+        command: z.string().describe('The executable to run (e.g. "node", "bun", "python"). NOT a shell command — use runCommand for shell syntax like pipes or &&.'),
+        args: z.string().optional().describe('Arguments as a single space-separated string. WARNING: spaces are used to split args, so paths with spaces will break. For complex argument quoting, prefer runCommand instead.'),
+        tag: z.string().optional().describe('A short, descriptive label for this process (e.g. "api-server", "file-watcher"). Always set a tag — it makes the process easy to find later with getProcessOutput and killProcess.'),
+        cwd: z.string().optional().describe('Working directory for the process. Defaults to the project root.'),
       }).describe(
-        'Spawn a long-running process (server, watcher, daemon) that runs in the background. Returns immediately with a process ID you can use to check status or kill it later.'
+        'Start a long-running background process (server, watcher, daemon). Returns immediately with a process ID — the process keeps running. Use this for anything that runs indefinitely. After spawning, call getProcessOutput to check if it started successfully. Always set a tag.'
       ),
     },
     runCommand: {
       schema: z.object({
-        command: z.string().describe('The command to execute (e.g. "npm install", "bun test")'),
-        cwd: z.string().optional().describe('Working directory for the command'),
+        command: z.string().describe('A full shell command string (executed via sh -c). Supports pipes, &&, redirects, env vars, globs — anything you can type in a terminal. Examples: "bun test", "npm install && npm run build", "cat logs/*.txt | grep ERROR"'),
+        cwd: z.string().optional().describe('Working directory for the command. Defaults to the project root.'),
       }).describe(
-        'Run a command and wait for it to complete. Returns the full stdout/stderr output and exit code. Use this for commands you expect to finish (builds, installs, tests).'
+        'Run a shell command and wait for it to complete. Returns stdout, stderr, and exit code. Use this for commands that finish on their own — builds, installs, tests, one-off scripts. For anything that runs forever (servers, watchers), use spawnProcess instead.'
       ),
     },
     listProcesses: {
       schema: z.object({}).describe(
-        'List all tracked processes with their status, PID, command, uptime, and a preview of recent output.'
+        'List all tracked background processes with their status, PID, command, uptime, and the last few lines of output. Call this to get an overview before deciding which process to inspect or kill.'
       ),
     },
     getProcessOutput: {
       schema: z.object({
-        id: z.string().optional().describe('The process ID to get output for'),
-        tag: z.string().optional().describe('The tag of the process to get output for'),
-        stream: z.string().optional().describe('Which stream to read: "stdout" (default) or "stderr"'),
+        id: z.string().optional().describe('The process ID (returned by spawnProcess). Provide either id or tag, not both.'),
+        tag: z.string().optional().describe('The tag you assigned when spawning the process. Provide either id or tag, not both.'),
+        stream: z.string().optional().describe('"stdout" (default) or "stderr". Check stderr when a process crashes or behaves unexpectedly.'),
       }).describe(
-        'Peek at a process\'s buffered output — shows the first 20 lines and last 50 lines of stdout or stderr.'
+        'Read a background process\'s buffered output — the first 20 lines (startup) and last 50 lines (recent activity). Call this after spawning to verify the process started correctly, and periodically to monitor its health.'
       ),
     },
     killProcess: {
       schema: z.object({
-        id: z.string().optional().describe('The process ID to kill'),
-        tag: z.string().optional().describe('The tag of the process to kill'),
-        signal: z.string().optional().describe('Signal to send: "SIGTERM" (default, graceful) or "SIGKILL" (force)'),
+        id: z.string().optional().describe('The process ID to kill. Provide either id or tag, not both.'),
+        tag: z.string().optional().describe('The tag of the process to kill. Provide either id or tag, not both.'),
+        signal: z.string().optional().describe('"SIGTERM" (default) for graceful shutdown, "SIGKILL" to force-kill a stuck process. Try SIGTERM first.'),
       }).describe(
-        'Kill a running process by ID or tag.'
+        'Stop a running background process. Use SIGTERM (default) for graceful shutdown. If a process doesn\'t respond, follow up with SIGKILL. Always clean up processes you spawned when they\'re no longer needed.'
       ),
     },
   }
@@ -593,6 +594,38 @@ export class ProcessManager extends Feature {
     return { id: handler.id, status: handler.status, signal, message: 'Process killed.' }
   }
 
+  /**
+   * When an assistant uses processManager, inject system prompt guidance
+   * about how to manage processes safely and effectively.
+   */
+  override setupToolsConsumer(consumer: Helper) {
+    if (typeof (consumer as any).addSystemPromptExtension === 'function') {
+      (consumer as any).addSystemPromptExtension('processManager', [
+        '## Process Management',
+        '',
+        '**Choosing the right tool:**',
+        '- `runCommand` — for anything that finishes on its own (builds, tests, installs, queries). Blocks until done.',
+        '- `spawnProcess` — for anything that runs indefinitely (servers, watchers, tails). Returns immediately.',
+        '- When in doubt: if you\'d press Ctrl-C to stop it, use `spawnProcess`. If you\'d wait for it, use `runCommand`.',
+        '',
+        '**After spawning a process:**',
+        '1. Always assign a descriptive `tag` so you can reference it later',
+        '2. Call `getProcessOutput` within a few seconds to verify it started correctly',
+        '3. Check `stderr` if the process crashes or output looks wrong',
+        '',
+        '**Monitoring:**',
+        '- Call `listProcesses` to see all running and finished processes at a glance',
+        '- Call `getProcessOutput` to read recent output — it keeps the first 20 and last 50 lines',
+        '- A process with status "crashed" exited with a non-zero code — check its stderr for the error',
+        '',
+        '**Cleanup:**',
+        '- Always `killProcess` background processes when they\'re no longer needed',
+        '- Use SIGTERM (default) first for graceful shutdown. Only use SIGKILL if SIGTERM doesn\'t work.',
+        '- If you spawned it, you\'re responsible for killing it',
+      ].join('\n'))
+    }
+  }
+
   // ─── Core API ───────────────────────────────────────────────────────────
 
   /**

package/src/node/features/python.ts

@@ -59,7 +59,7 @@ export const PythonEventsSchema = FeatureEventsSchema.extend({
   }).describe('Install result')]).describe('When dependency installation fails'),
   codeExecuted: z.tuple([z.object({
     code: z.string().describe('The Python code that was executed'),
-    variables: z.record(z.any()).describe('Variables passed to the execution'),
+    variables: z.record(z.string(), z.any()).describe('Variables passed to the execution'),
     result: z.object({
       stdout: z.string().describe('Standard output'),
       stderr: z.string().describe('Standard error'),
@@ -68,7 +68,7 @@ export const PythonEventsSchema = FeatureEventsSchema.extend({
   }).describe('Code execution details')]).describe('When Python code finishes executing'),
   fileExecuted: z.tuple([z.object({
     filePath: z.string().describe('Path to the executed Python file'),
-    variables: z.record(z.any()).describe('Variables passed as arguments'),
+    variables: z.record(z.string(), z.any()).describe('Variables passed as arguments'),
     result: z.object({
       stdout: z.string().describe('Standard output'),
       stderr: z.string().describe('Standard error'),
@@ -532,7 +532,7 @@ export class Python<
    */
   private _parsePythonCommand(extraArgs: string[]): { command: string, args: string[] } {
     const parts = this.pythonPath.split(/\s+/)
-    return { command: parts[0], args: [...parts.slice(1), ...extraArgs] }
+    return { command: parts[0] ?? 'python', args: [...parts.slice(1), ...extraArgs] }
   }
 
   /**

package/src/node/features/redis.ts

@@ -400,7 +400,7 @@ export class RedisFeature extends Feature<RedisState, RedisOptions> {
     )
 
     if (existing) {
-      if (existing.state !== 'running') {
+      if (existing.status !== 'running') {
         await docker.startContainer(name)
       }
       return existing.id

package/src/node/features/repl.ts

@@ -101,7 +101,7 @@ export class Repl<
 
     // Load existing history
     try {
-      const content = fs.readFile(this._historyPath, 'utf-8')
+      const content = this.container.fs.readFile(this._historyPath, 'utf-8') as string
       this._history = content.split('\n').filter(Boolean).reverse()
     } catch {}
 
@@ -204,7 +204,7 @@ export class Repl<
   private _saveHistory(line: string) {
     if (!this._historyPath || !line.trim()) return
     try {
-      fs.appendFileSync(this._historyPath, line + '\n')
+      this.container.fs.appendFile(this._historyPath, line + '\n')
     } catch {}
   }
 }

package/src/node/features/transpiler.ts

@@ -45,8 +45,8 @@ function esmToCjs(code: string): string {
     .replace(/^export\s+\{([^}]*)\}\s*;?$/gm, (_match, body: string) => {
       return body.split(',').map(s => {
         const parts = s.trim().split(/\s+as\s+/)
-        const local = parts[0].trim()
-        const exported = (parts[1] || parts[0]).trim()
+        const local = (parts[0] ?? '').trim()
+        const exported = (parts[1] ?? parts[0] ?? '').trim()
         return local ? `exports['${exported}'] = ${local};` : ''
       }).filter(Boolean).join(' ')
     })

package/src/node/features/ui.ts

@@ -2,7 +2,7 @@ import { z } from 'zod'
 import { FeatureStateSchema } from '../../schemas/base.js'
 import { Feature } from "../feature.js";
 import colors from "chalk";
-import type { Fonts } from "figlet";
+import type { FontName as Fonts } from "figlet";
 import { figlet, fontNames } from "./figlet-fonts.js";
 import inquirer from "inquirer";
 import { marked } from 'marked';

package/src/node/features/vm.ts

@@ -219,9 +219,9 @@ export class VM<
 
     // Find the last non-empty line
     let lastIdx = lines.length - 1
-    while (lastIdx > 0 && !lines[lastIdx].trim()) lastIdx--
+    while (lastIdx > 0 && !(lines[lastIdx] ?? '').trim()) lastIdx--
 
-    let lastLine = lines[lastIdx]!
+    let lastLine = lines[lastIdx] ?? ''
 
     // For single-line code with semicolons (e.g. CLI eval), split the last line
     // into statements and only try to return the final statement.
@@ -390,7 +390,7 @@ export class VM<
     if (!fs.exists(filePath)) return {}
 
     const raw = fs.readFile(filePath)
-    const { code } = this.container.feature('transpiler').transformSync(raw, { format: 'cjs' })
+    const { code } = this.container.feature('transpiler').transformSync(String(raw), { format: 'cjs' })
 
     const sharedExports = {}
     const { context } = this.performSync(code, {

package/src/node/features/yaml-tree.ts

@@ -113,7 +113,7 @@ export class YamlTree<T extends YamlTreeState = YamlTreeState> extends Feature<T
     for (const file of yamlFiles.filter(Boolean)) {
       if(file?.relativePath) {
         const fileContent = fileSystem.readFile(file.relativePath);
-        const fileData = yamlFeature.parse(fileContent);
+        const fileData = yamlFeature.parse(String(fileContent));
         const path = file.relativePath.replace(/\.ya?ml$/, "").replace(basePath + "/", "").split("/").filter(v => v?.length).map(p => camelCase(p));
         set(tree, path, fileData)
       }

package/src/node.ts

@@ -65,6 +65,7 @@ export type { AvailableFeatures, FeatureOptions, FeatureState } from './feature'
 export type { NodeContainer, NodeFeatures } from './node/container'
 export type { AvailableServers, StartOptions, ServersInterface } from './server'
 export type { HelperState, HelperOptions } from './helper'
+export type { Entity } from './entity'
 export type { EventMap } from './bus'
 export type { SetStateValue, StateChangeType } from './state'
 

package/src/python/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated Python bridge script
-// Generated at: 2026-03-30T06:52:57.841Z
+// Generated at: 2026-04-05T06:58:08.827Z
 // Source: src/python/bridge.py
 //
 // Do not edit manually. Run: luca build-python-bridge

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-30T06:52:56.013Z
+// Generated at: 2026-04-05T06:58:07.148Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds