@soederpop/luca 0.0.23 → 0.0.26

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)

package/assistants/architect/CORE.md

@@ -1,3 +0,0 @@
-# Luca Framework Assistant 
-
-Your job is to help people use the Luca framework

package/assistants/architect/hooks.ts

@@ -1,3 +0,0 @@
-export function started() {
-	console.log('Assistant started!')
-}

package/assistants/architect/tools.ts

@@ -1,10 +0,0 @@
-import { z } from 'zod'
-
-export const schemas = {
-	README: z.object({}).describe('CALL THIS README FUNCTION AS EARLY AS POSSIBLE')
-}
-
-export function README(options: z.infer<typeof schemas.README>) {
-	return 'YO YO'
-}
-

package/docs/apis/features/agi/skills-library.md

@@ -1,234 +0,0 @@
-# SkillsLibrary (features.skillsLibrary)
-
-Manages two contentbase collections of skills following the Claude Code SKILL.md format. Project-level skills live in .claude/skills/ and user-level skills live in ~/.luca/skills/. Skills can be discovered, searched, created, updated, and removed at runtime.
-
-## Usage
-
-```ts
-container.feature('skillsLibrary', {
-  // Path to project-level skills directory
-  projectSkillsPath,
-  // Path to user-level global skills directory
-  userSkillsPath,
-})
-```
-
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `projectSkillsPath` | `string` | Path to project-level skills directory |
-| `userSkillsPath` | `string` | Path to user-level global skills directory |
-
-## Methods
-
-### load
-
-Loads both project and user skill collections from disk. Gracefully handles missing directories.
-
-**Returns:** `Promise<SkillsLibrary>`
-
-
-
-### list
-
-Lists all skills from both collections. Project skills come first.
-
-**Returns:** `SkillEntry[]`
-
-
-
-### find
-
-Finds a skill by name. Project skills take precedence over user skills.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | The skill name to find (case-insensitive) |
-
-**Returns:** `SkillEntry | undefined`
-
-
-
-### search
-
-Searches skills by substring match against name and description.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `query` | `string` | ✓ | The search query |
-
-**Returns:** `SkillEntry[]`
-
-
-
-### getSkill
-
-Gets a skill by name. Alias for find().
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | The skill name |
-
-**Returns:** `SkillEntry | undefined`
-
-
-
-### create
-
-Creates a new SKILL.md file in the specified collection. Maintains the directory-per-skill structure (skill-name/SKILL.md).
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `skill` | `{
-			name: string
-			description: string
-			body: string
-			meta?: Record<string, unknown>
-		}` | ✓ | The skill to create |
-| `target` | `'project' | 'user'` |  | Which collection to write to (default: 'project') |
-
-**Returns:** `Promise<SkillEntry>`
-
-
-
-### update
-
-Updates an existing skill's content or metadata.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | The skill name to update |
-| `updates` | `{
-			description?: string
-			body?: string
-			meta?: Record<string, unknown>
-		}` | ✓ | Fields to update |
-
-**Returns:** `Promise<SkillEntry>`
-
-
-
-### remove
-
-Removes a skill by name, deleting its SKILL.md and cleaning up the directory.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `name` | `string` | ✓ | The skill name to remove |
-
-**Returns:** `Promise<boolean>`
-
-
-
-### toConversationTools
-
-Converts all skills into ConversationTool format for use with Conversation. Each skill becomes a tool that returns its instruction body when invoked.
-
-**Returns:** `Record<string, ConversationTool>`
-
-
-
-### toSystemPromptBlock
-
-Generates a markdown block listing all available skills with names and descriptions. Suitable for injecting into a system prompt.
-
-**Returns:** `string`
-
-
-
-## Getters
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `projectCollection` | `Collection` | Returns the project-level contentbase Collection, lazily initialized. |
-| `userCollection` | `Collection` | Returns the user-level contentbase Collection, lazily initialized. |
-| `isLoaded` | `boolean` | Whether the skills library has been loaded. |
-| `skillNames` | `string[]` | Array of all skill names across both collections. |
-
-## Events (Zod v4 schema)
-
-### loaded
-
-Fired after both project and user skill collections are loaded
-
-
-
-### skillCreated
-
-Fired after a new skill is written to disk
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | The created SkillEntry object |
-
-
-
-### skillUpdated
-
-Fired after an existing skill is updated
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `any` | The updated SkillEntry object |
-
-
-
-### skillRemoved
-
-Fired after a skill is deleted
-
-**Event Arguments:**
-
-| Name | Type | Description |
-|------|------|-------------|
-| `arg0` | `string` | The name of the removed skill |
-
-
-
-## State (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enabled` | `boolean` | Whether this feature is currently enabled |
-| `loaded` | `boolean` | Whether both collections have been loaded |
-| `projectSkillCount` | `number` | Number of skills in the project collection |
-| `userSkillCount` | `number` | Number of skills in the user-level collection |
-| `totalSkillCount` | `number` | Total number of skills across both collections |
-
-## Examples
-
-**features.skillsLibrary**
-
-```ts
-const skills = container.feature('skillsLibrary')
-await skills.load()
-
-// List and search
-const allSkills = skills.list()
-const matches = skills.search('code review')
-
-// Create a new skill
-await skills.create({
- name: 'summarize',
- description: 'Summarize a document',
- body: '## Instructions\nRead the document and produce a concise summary.'
-})
-```
-

package/docs/reports/assistant-bugs.md

@@ -1,38 +0,0 @@
-# Assistant systemPrompt Bug Fix Verification
-
-The bug: class field initializers (`private _systemPrompt: string = ''`) on Feature subclasses
-overwrite values set during `afterInitialize()` because ES2022 field initializers run AFTER `super()` returns.
-
-Fix: use `declare private _systemPrompt: string` which emits no JavaScript, so afterInitialize values persist.
-
-## Test
-
-```ts
-const assistant = container.feature('assistant', {
-  folder: '/Users/jon/@soederpop/commands/voice/assistant'
-})
-```
-
-systemPrompt should contain the CORE.md content (not be empty):
-
-```ts
-console.log("systemPrompt length:", assistant.systemPrompt.length)
-console.log("contains omar:", assistant.systemPrompt.toLowerCase().includes("omar"))
-console.log("first 80 chars:", assistant.systemPrompt.slice(0, 80))
-```
-
-Tools should have been loaded from tools.ts:
-
-```ts
-console.log("tools loaded:", Object.keys(assistant.tools))
-```
-
-Starting the assistant should pass the systemPrompt into the conversation:
-
-```ts
-await assistant.start()
-const systemMsg = assistant.conversation.messages[0]
-console.log("conversation has system message:", systemMsg.role === "system")
-console.log("system message has content:", systemMsg.content.length > 0)
-console.log("system message contains omar:", systemMsg.content.toLowerCase().includes("omar"))
-```

package/docs/reports/attach-pattern-usage.md

@@ -1,18 +0,0 @@
-# Attach Pattern
-
-Here is some problematic code:
-
-```ts skip
-const { container } = context
-const { VoiceRouter } = await import(resolve(import.meta.dir, 'voice/router.ts'))
-container.features.register('voiceRouter', VoiceRouter as any)
-const router = container.feature('voiceRouter' as any, { enable: true }) as InstanceType<typeof VoiceRouter>
-```
-
-I'd rather see
-
-```ts skip
-// we know since we're inside a command this has to be our path anyway, relative to the container's cwd is how we're discovered
-await import(container.paths.resolve('commands','voice','router.ts')).then(({ VoiceRouter }) => container.use(VoiceRouter))
-```
-