@soederpop/luca 0.0.3 → 0.0.4

package/docs/CLI.md

@@ -34,7 +34,7 @@ Run a script or markdown file (.ts, .js, .md).
 luca run <file> [options]
 ```
 
-Resolves the file by trying the path as-is, then appending `.ts`, `.js`, `.md` in order. Markdown files are executed block-by-block with the container in scope. TypeScript and JavaScript files are run as standalone scripts via `proc.runScript`.
+Resolves the file by trying the path as-is, then appending `.ts`, `.js`, `.md` in order. Markdown files are executed block-by-block with the container in scope. TypeScript and JavaScript files are run as standalone scripts via `proc.execAndCapture`.
 
 | Flag | Type | Default | Description |
 |------|------|---------|-------------|

package/docs/apis/features/node/content-db.md

@@ -72,6 +72,14 @@ console.log(contentDb.isLoaded) // true
 
 
 
+### reload
+
+Force-reload the collection from disk, picking up new/changed/deleted documents.
+
+**Returns:** `Promise<ContentDb>`
+
+
+
 ### read
 
 Read a single document by its path ID, optionally filtering to specific sections. The document title (H1) is always included in the output. When using `include`, the leading content (paragraphs between the H1 and first H2) is also included by default, controlled by the `leadingContent` option. When `include` is provided, only those sections are returned (via extractSections in flat mode). When `exclude` is provided, those sections are removed from the full document. If both are set, `include` takes precedence.
@@ -232,6 +240,14 @@ Rebuild the entire search index from scratch.
 | `searchIndexStatus` | `any` | Get the current search index status. |
 | `queries` | `Record<string, ReturnType<typeof this.query>>` | Returns an object with query builders keyed by model name (singular and plural, lowercased). Provides a convenient shorthand for querying without looking up model definitions manually. |
 
+## Events (Zod v4 schema)
+
+### reloaded
+
+Event emitted by ContentDb
+
+
+
 ## State (Zod v4 schema)
 
 | Property | Type | Description |

package/docs/apis/features/node/fs.md

@@ -206,6 +206,18 @@ fs.ensureFolder('logs/debug')
 
 
 
+### mkdirp
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `folder` | `string` | ✓ | Parameter folder |
+
+**Returns:** `void`
+
+
+
 ### ensureFile
 
 Synchronously ensures a file exists with the specified content, creating directories as needed.
@@ -295,6 +307,18 @@ if (fs.exists('config.json')) {
 
 
 
+### existsSync
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `path` | `string` | ✓ | Parameter path |
+
+**Returns:** `boolean`
+
+
+
 ### rm
 
 Asynchronously removes a file.

package/docs/apis/features/node/ipc-socket.md

@@ -169,7 +169,6 @@ Event emitted by IpcSocket
 | Property | Type | Description |
 |----------|------|-------------|
 | `enabled` | `boolean` | Whether this feature is currently enabled |
-| `mode` | `string` | The current mode of the IPC socket - either server or client |
 
 ## Examples
 

package/docs/apis/features/node/package-finder.md

@@ -5,18 +5,9 @@ PackageFinder Feature - Comprehensive package discovery and analysis tool This f
 ## Usage
 
 ```ts
-container.feature('packageFinder', {
-  // Optional configuration parameter
-  option,
-})
+container.feature('packageFinder')
 ```
 
-## Options (Zod v4 schema)
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `option` | `string` | Optional configuration parameter |
-
 ## Methods
 
 ### afterInitialize
@@ -237,7 +228,6 @@ const unscoped = finder.exclude(pkg => pkg.name.startsWith('@'));
 | Property | Type | Description |
 |----------|------|-------------|
 | `enabled` | `boolean` | Whether this feature is currently enabled |
-| `started` | `boolean` | Whether the package finder has been started and initial scan completed |
 
 ## Examples
 

package/docs/apis/features/node/proc.md

@@ -130,36 +130,6 @@ Spawn a raw child process and return the handle immediately. Useful when callers
 
 
 
-### runScript
-
-Runs a script file with Bun, inheriting stdout for full TTY passthrough (animations, colors, cursor movement) while capturing stderr in a rolling buffer.
-
-**Parameters:**
-
-| Name | Type | Required | Description |
-|------|------|----------|-------------|
-| `scriptPath` | `string` | ✓ | Absolute path to the script file |
-| `options` | `{ cwd?: string; maxLines?: number; env?: Record<string, string> }` |  | Options |
-
-`{ cwd?: string; maxLines?: number; env?: Record<string, string> }` properties:
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `cwd` | `any` | Working directory |
-| `maxLines` | `any` | Max stderr lines to keep |
-| `env` | `any` | Extra environment variables |
-
-**Returns:** `Promise<{ exitCode: number; stderr: string[] }>`
-
-```ts
-const { exitCode, stderr } = await proc.runScript('/path/to/script.ts')
-if (exitCode !== 0) {
- console.log('Error:', stderr.join('\n'))
-}
-```
-
-
-
 ### exec
 
 Execute a command synchronously and return its output. Runs a shell command and waits for it to complete before returning. Useful for simple commands where you need the result immediately.
@@ -354,17 +324,6 @@ const buildResult = await proc.spawnAndCapture('npm', ['run', 'build'], {
 
 
 
-**runScript**
-
-```ts
-const { exitCode, stderr } = await proc.runScript('/path/to/script.ts')
-if (exitCode !== 0) {
- console.log('Error:', stderr.join('\n'))
-}
-```
-
-
-
 **exec**
 
 ```ts

package/docs/apis/features/node/ui.md

@@ -417,8 +417,6 @@ const menuItem = ui.padRight('Coffee', 20, '.') + '$3.50';
 | Property | Type | Description |
 |----------|------|-------------|
 | `enabled` | `boolean` | Whether this feature is currently enabled |
-| `fonts` | `array` | Array of available fonts for ASCII art generation |
-| `colorPalette` | `array` | Color palette of hex colors for automatic color assignment |
 
 ## Examples
 

package/package.json

@@ -1,9 +1,9 @@
 {
   "name": "@soederpop/luca",
-  "version": "0.0.3",
-  "private": false,
-  "description": "lightweight universal conversational architecture",
-  "author": "jon soeder <jon@soederpop.com>",
+  "version": "0.0.4",
+  "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>",
   "type": "module",
   "repository": "https://github.com/soederpop/luca",
   "license": "MIT",
@@ -12,7 +12,11 @@
   },
   "keywords": [
     "conversational",
-    "architecture"
+    "architecture",
+    "universal",
+    "ai",
+    "agentic",
+    "coding assistant"
   ],
   "main": "./src/node.ts",
   "types": "./src/node.ts",
@@ -31,7 +35,8 @@
     "./client": "./src/client.ts",
     "./clients/*": "./src/clients/*",
     "./feature": "./src/feature.ts",
-    "./react": "./src/react/index.ts"
+    "./react": "./src/react/index.ts",
+    "./introspection": "./src/introspection/index.ts"
   },
   "bin": {
     "luca": "./src/cli/cli.ts"
@@ -42,7 +47,7 @@
     "lint": "eslint src/ --ext .js,.jsx,.ts,.tsx",
     "clean": "rm -rf dist build package",
     "build:web": "bun run scripts/build-web.ts",
-    "build:introspection": "bun run src/cli/cli.ts update-introspection",
+    "build:introspection": "bun run src/cli/cli.ts introspect",
     "compile": "bun build ./src/cli/cli.ts --compile --outfile dist/luca --external node-llama-cpp",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "build:scaffolds": "bun run src/cli/cli.ts build-scaffolds",
@@ -98,7 +103,6 @@
     "compromise": "^14.14.5",
     "contentbase": "",
     "cors": "^2.8.5",
-    "cross-fetch": "^4.1.0",
     "detect-port": "^1.5.1",
     "dotenv": "^17.2.4",
     "endent": "^2.1.0",

package/src/agi/container.server.ts

@@ -1,5 +1,5 @@
-import type { ContainerState } from '@soederpop/luca/container'
-import { type NodeFeatures, NodeContainer } from '@soederpop/luca/node/container'
+import type { ContainerState } from '../container'
+import { type NodeFeatures, NodeContainer } from '../node/container'
 import '@/introspection/generated.agi.js'
 import { OpenAIClient } from '../clients/openai'
 import { ElevenLabsClient } from '../clients/elevenlabs'
@@ -38,6 +38,16 @@ export type {
 	NodeFeatures,
 }
 
+export interface AGIFeatures extends NodeFeatures {
+	conversation: typeof Conversation
+	claudeCode: typeof ClaudeCode
+	openaiCodex: typeof OpenAICodex
+	skillsLibrary: typeof SkillsLibrary
+	conversationHistory: typeof ConversationHistory
+	assistant: typeof Assistant
+	assistantsManager: typeof AssistantsManager
+}
+
 export interface ConversationFactoryOptions {
 	tools?: {
 		handlers: Record<string, ConversationTool['handler']>
@@ -56,7 +66,10 @@ export interface ConversationFactoryOptions {
  * AGI-specific container that extends NodeContainer with AI capabilities including
  * OpenAI conversations, code generation, and self-modifying agent features.
  */
-export class AGIContainer extends NodeContainer {
+export class AGIContainer<
+	Features extends AGIFeatures = AGIFeatures,
+	K extends ContainerState = ContainerState
+> extends NodeContainer<Features, K> {
 	openai!: OpenAIClient
 	claudeCode?: ClaudeCode
 	openaiCodex?: OpenAICodex

package/src/agi/features/assistant.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 import type { Conversation, ConversationTool, ContentPart, AskOptions, Message } from './conversation'
 import type { AGIContainer } from '../container.server.js'
 import type { ContentDb } from '@soederpop/luca/node'
@@ -94,10 +93,7 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	static override eventsSchema = AssistantEventsSchema
 	static override shortcut = 'features.assistant' as const
 
-	static attach(container: Container<AvailableFeatures, any>) {
-		features.register('assistant', Assistant)
-		return container
-	}
+	static { Feature.register(this, 'assistant') }
 
 	/** @returns Default state with the assistant not started, zero conversations, and the resolved folder path. */
 	override get initialState(): AssistantState {
@@ -764,4 +760,4 @@ export class Assistant extends Feature<AssistantState, AssistantOptions> {
 	}
 }
 
-export default features.register('assistant', Assistant)
+export default Assistant

package/src/agi/features/assistants-manager.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 import type { AGIContainer } from '../container.server.js'
 import type { Assistant } from './assistant.js'
 
@@ -78,10 +77,7 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	static override eventsSchema = AssistantsManagerEventsSchema
 	static override shortcut = 'features.assistantsManager' as const
 
-	static attach(container: Container<AvailableFeatures, any>) {
-		features.register('assistantsManager', AssistantsManager)
-		return container
-	}
+	static { Feature.register(this, 'assistantsManager') }
 
 	/** @returns Default state with discovery not yet run and zero counts. */
 	override get initialState(): AssistantsManagerState {
@@ -257,4 +253,4 @@ export class AssistantsManager extends Feature<AssistantsManagerState, Assistant
 	}
 }
 
-export default features.register('assistantsManager', AssistantsManager)
+export default AssistantsManager

package/src/agi/features/claude-code.ts

@@ -1,9 +1,8 @@
 // @ts-nocheck
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -281,10 +280,7 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
   static override shortcut = 'features.claudeCode' as const
   static override envVars = ['TMPDIR']
 
-  static attach(container: Container<AvailableFeatures, any>) {
-    container.features.register('claudeCode', ClaudeCode)
-    return container
-  }
+  static { Feature.register(this, 'claudeCode') }
 
   override get initialState(): ClaudeCodeState {
     return {
@@ -1108,4 +1104,4 @@ export class ClaudeCode extends Feature<ClaudeCodeState, ClaudeCodeOptions> {
   }
 }
 
-export default features.register('claudeCode', ClaudeCode)
+export default ClaudeCode

package/src/agi/features/conversation-history.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 import { NodeContainer, type DiskCache, type NodeFeatures } from '@soederpop/luca/node/container'
 import type { Message } from './conversation'
 
@@ -79,10 +78,7 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 	static override optionsSchema = ConversationHistoryOptionsSchema
 	static override shortcut = 'features.conversationHistory' as const
 
-	static attach(container: Container<AvailableFeatures, any>) {
-		features.register('conversationHistory', ConversationHistory)
-		return container
-	}
+	static { Feature.register(this, 'conversationHistory') }
 
 	/** @returns Default state with zero conversations and no last-saved timestamp. */
 	override get initialState(): ConversationHistoryState {
@@ -494,4 +490,4 @@ export class ConversationHistory extends Feature<ConversationHistoryState, Conve
 	}
 }
 
-export default features.register('conversationHistory', ConversationHistory)
+export default ConversationHistory

package/src/agi/features/conversation.ts

@@ -1,8 +1,7 @@
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container';
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 import type { OpenAIClient } from '../../clients/openai';
 import type OpenAI from 'openai';
 import type { ConversationHistory } from './conversation-history';
@@ -125,6 +124,8 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	static override optionsSchema = ConversationOptionsSchema
 	static override shortcut = 'features.conversation' as const
 
+	static { Feature.register(this, 'conversation') }
+
 	private _callMaxTokens: number | undefined = undefined
 
 	/** Resolved max tokens: per-call override > options-level > undefined (no limit). */
@@ -136,11 +137,6 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 		return this.options.tools || {}
 	}
 
-	static attach(container: Container<AvailableFeatures, any>) {
-		features.register('conversation', Conversation)
-		return container
-	}
-
 	/** @returns Default state seeded from options: id, thread, model, initial history, and zero token usage. */
 	override get initialState(): ConversationState {
 		return {
@@ -796,4 +792,4 @@ export class Conversation extends Feature<ConversationState, ConversationOptions
 	}
 }
 
-export default features.register('conversation', Conversation)
+export default Conversation

package/src/agi/features/openai-codex.ts

@@ -1,9 +1,8 @@
 // @ts-nocheck
 import { z } from 'zod'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
 import { type AvailableFeatures } from '@soederpop/luca/feature'
-import { features, Feature } from '@soederpop/luca/feature'
+import { Feature } from '@soederpop/luca/feature'
 
 declare module '@soederpop/luca/feature' {
   interface AvailableFeatures {
@@ -149,10 +148,7 @@ export class OpenAICodex extends Feature<OpenAICodexState, OpenAICodexOptions> {
   static override optionsSchema = OpenAICodexOptionsSchema
   static override shortcut = 'features.openaiCodex' as const
 
-  static attach(container: Container<AvailableFeatures, any>) {
-    container.features.register('openaiCodex', OpenAICodex)
-    return container
-  }
+  static { Feature.register(this, 'openaiCodex') }
 
   override get initialState(): OpenAICodexState {
     return {
@@ -628,4 +624,4 @@ export class OpenAICodex extends Feature<OpenAICodexState, OpenAICodexOptions> {
   }
 }
 
-export default features.register('openaiCodex', OpenAICodex)
+export default OpenAICodex

package/src/agi/features/openapi.ts

@@ -1,4 +1,4 @@
-import { Feature, features } from '../../feature.js'
+import { Feature } from '../../feature.js'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
 import { z } from 'zod'
 import { camelCase } from 'lodash-es'
@@ -103,6 +103,8 @@ export class OpenAPI extends Feature<OpenAPIState, OpenAPIOptions> {
   static override stateSchema = OpenAPIStateSchema
   static override optionsSchema = OpenAPIOptionsSchema
 
+  static { Feature.register(this, 'openapi') }
+
   /** Raw parsed spec document */
   private _spec: any = null
 
@@ -435,4 +437,4 @@ function schemaToJsonSchema(schema: any): any {
   return result
 }
 
-export default features.register('openapi', OpenAPI)
+export default OpenAPI

package/src/agi/features/skills-library.ts

@@ -5,8 +5,7 @@ import fs from 'fs/promises'
 import yaml from 'js-yaml'
 import { kebabCase } from 'lodash-es'
 import { FeatureStateSchema, FeatureOptionsSchema } from '../../schemas/base.js'
-import type { Container } from '@soederpop/luca/container'
-import { type AvailableFeatures, features, Feature } from '@soederpop/luca/feature'
+import { type AvailableFeatures, Feature } from '@soederpop/luca/feature'
 import { Collection, defineModel } from 'contentbase'
 import type { ConversationTool } from './conversation'
 
@@ -94,14 +93,11 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 	static override optionsSchema = SkillsLibraryOptionsSchema
 	static override shortcut = 'features.skillsLibrary' as const
 
+	static { Feature.register(this, 'skillsLibrary') }
+
 	private _projectCollection?: Collection
 	private _userCollection?: Collection
 
-	static attach(container: Container<AvailableFeatures, any>) {
-		features.register('skillsLibrary', SkillsLibrary)
-		return container
-	}
-
 	/** @returns Default state with loaded=false and zero skill counts across both collections. */
 	override get initialState(): SkillsLibraryState {
 		return {
@@ -422,4 +418,4 @@ export class SkillsLibrary extends Feature<SkillsLibraryState, SkillsLibraryOpti
 	}
 }
 
-export default features.register('skillsLibrary', SkillsLibrary)
+export default SkillsLibrary

package/src/cli/cli.ts

@@ -11,6 +11,8 @@ async function main() {
 	await discoverProjectCommands()
 	// Discover user-level commands (~/.luca/commands/)
 	await discoverUserCommands()
+	// Load generated introspection data if present
+	await loadProjectIntrospection()
 
 	const commandName = container.argv._[0] as string
 
@@ -58,6 +60,26 @@ async function discoverProjectCommands() {
 	}
 }
 
+async function loadProjectIntrospection() {
+	const candidates = [
+		'features/introspection.generated.ts',
+		'src/introspection.generated.ts',
+		'introspection.generated.ts',
+	]
+
+	for (const candidate of candidates) {
+		const filePath = container.paths.resolve(candidate)
+		if (container.fs.exists(filePath)) {
+			try {
+				await import(filePath)
+			} catch {
+				// Generated file may be stale or malformed — skip silently
+			}
+			return
+		}
+	}
+}
+
 async function discoverUserCommands() {
 	const { fs } = container
 	const dir = join(homedir(), '.luca', 'commands')