@soederpop/luca 0.0.25 → 0.0.26

package/src/introspection/generated.web.ts

@@ -1,7 +1,7 @@
 import { setBuildTimeData, setContainerBuildTimeData } from './index.js';
 
 // Auto-generated introspection registry data
-// Generated at: 2026-03-22T06:53:17.219Z
+// Generated at: 2026-03-22T20:57:23.113Z
 
 setBuildTimeData('features.containerLink', {
   "id": "features.containerLink",
@@ -982,6 +982,10 @@ setContainerBuildTimeData('Container', {
       "description": "Returns a map of enabled feature shortcut IDs to their instances.",
       "returns": "Partial<AvailableInstanceTypes<Features>>"
     },
+    "describer": {
+      "description": "Lazy-initialized ContainerDescriber for introspecting registries, helpers, and members.",
+      "returns": "ContainerDescriber"
+    },
     "context": {
       "description": "The Container's context is an object that contains the enabled features, the container itself, and any additional context that has been added to the container. All helper instances that are created by the container will have access to the shared context.",
       "returns": "ContainerContext<Features> & Partial<AvailableInstanceTypes<AvailableFeatures>>"
@@ -2029,6 +2033,10 @@ export const containerIntrospectionData = [
         "description": "Returns a map of enabled feature shortcut IDs to their instances.",
         "returns": "Partial<AvailableInstanceTypes<Features>>"
       },
+      "describer": {
+        "description": "Lazy-initialized ContainerDescriber for introspecting registries, helpers, and members.",
+        "returns": "ContainerDescriber"
+      },
       "context": {
         "description": "The Container's context is an object that contains the enabled features, the container itself, and any additional context that has been added to the container. All helper instances that are created by the container will have access to the shared context.",
         "returns": "ContainerContext<Features> & Partial<AvailableInstanceTypes<AvailableFeatures>>"

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

@@ -428,6 +428,23 @@ export class ContentDb extends Feature<ContentDbState, ContentDbOptions> {
   async generateModelSummary(options: any) {
 	  return this.collection.generateModelSummary(options)
   }
+  
+  get modelDefinitionTable() {
+    return Object.fromEntries(this.collection.modelDefinitions.map(d => {
+      
+      const prefixPattern = this.container.paths.relative(this.collection.resolve(d.prefix))
+
+      return [d.name, {
+        description: d.name === 'Base' ? 'Any markdown document not matched to a model' : d.description,
+        glob: `${prefixPattern}/**/*.md`,
+        routePatterns: Array(d.pattern).flatMap(p => p).filter(Boolean).map(p => `${prefixPattern}/${p}`)
+      }]
+    }))
+  }
+  
+  get fileTree() {
+    return this.collection.renderFileTree()
+  }
 
   // ── Search Integration ─────────────────────────────────────────────
 

package/src/node/features/fs.ts

@@ -88,6 +88,16 @@ export class FS extends Feature {
     return readFileSync(filePath, encoding ?? 'utf-8')
   }
 
+  /**
+   * Synchronously reads a file and returns its contents as a string.
+   * added this method because AI Assistants are understandly confused by this deviation from 2000's era node style
+   * @alias readFile
+   */
+  readFileSync(path: string, encoding?: BufferEncoding | null): string | Buffer {
+    return this.readFile(path,encoding)
+  }
+  
+
   /**
    * Asynchronously reads a file and returns its contents as a string.
    *
@@ -126,6 +136,14 @@ export class FS extends Feature {
   readJson(path: string) {
     return JSON.parse(this.readFile(path) as string)
   }
+  
+  /**
+    * Read and parse a JSON file synchronously
+    * @alias readJson
+   */
+  readJsonSync(path: string) {
+    return this.readJson(path)
+  }
 
   /**
    * Asynchronously reads and parses a JSON file.

package/src/scaffolds/generated.ts

@@ -1,5 +1,5 @@
 // Auto-generated scaffold and MCP readme content
-// Generated at: 2026-03-22T06:53:18.105Z
+// Generated at: 2026-03-22T20:57:24.026Z
 // Source: docs/scaffolds/*.md, docs/examples/assistant/, and docs/mcp/readme.md
 //
 // Do not edit manually. Run: luca build-scaffolds

package/src/server.ts

@@ -79,6 +79,44 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
         return super.container as NodeContainer
     }
 
+    /** Async functions passed to `.use()` before `start()` — drained in `start()`. */
+    _pendingPlugins: Promise<void>[] = []
+
+    /**
+     * Register a setup function against this server. The function receives the
+     * server instance and can configure it however it likes.
+     *
+     * - If the server hasn't started yet, async return values are queued and
+     *   awaited when `start()` is called.
+     * - If the server is already listening, the function is fire-and-forget.
+     * - Always returns `this` synchronously for chaining.
+     *
+     * @example
+     * ```typescript
+     * server
+     *   .use((s) => s.app.use(cors()))
+     *   .use(async (s) => { await loadRoutes(s) })
+     * await server.start()
+     * ```
+     */
+    use(fn: (server: this) => void | Promise<void>): this {
+      const result = fn(this)
+      if (result && typeof (result as any).then === 'function') {
+        if (!this.isListening) {
+          this._pendingPlugins.push(result as Promise<void>)
+        }
+      }
+      return this
+    }
+
+    /** Drain all pending `.use()` promises. Subclasses should call this at the top of `start()`. */
+    protected async _drainPendingPlugins() {
+      if (this._pendingPlugins.length) {
+        await Promise.all(this._pendingPlugins)
+        this._pendingPlugins = []
+      }
+    }
+
     get isListening() {
       return !!this.state.get('listening')
     }
@@ -117,6 +155,8 @@ export class Server<T extends ServerState = ServerState, K extends ServerOptions
         return this
       }
 
+      await this._drainPendingPlugins()
+
       if (options?.port) {
         this.state.set('port', options.port)
       }

package/src/servers/express.ts

@@ -104,6 +104,8 @@ export class ExpressServer<T extends ServerState = ServerState, K extends Expres
         return this
       }
 
+      await this._drainPendingPlugins()
+
       // Apply runtime port to state so this.port reflects the override
       if (options?.port) {
         this.state.set('port', options.port)

package/src/servers/mcp.ts

@@ -472,6 +472,7 @@ export class MCPServer extends Server<MCPServerState, MCPServerOptions> {
     stdioCompat?: StdioCompatMode
   }) {
     if (this.isListening) return this
+    await this._drainPendingPlugins()
     if (!this.isConfigured) await this.configure()
 
     const transport = options?.transport || this.options.transport || 'stdio'

package/src/servers/socket.ts

@@ -89,6 +89,8 @@ export class WebsocketServer<T extends ServerState = ServerState, K extends Sock
         return this
       }
 
+      await this._drainPendingPlugins()
+
       // Apply runtime port to state before configure/wss touches it
       if (options?.port) {
         this.state.set('port', options.port)