@soederpop/luca 0.0.2

package/docs/apis/features/node/process-manager.md

@@ -0,0 +1,210 @@
+# ProcessManager (features.processManager)
+
+Manages long-running child processes with tracking, events, and automatic cleanup. Unlike the `proc` feature whose spawn methods block until the child exits, ProcessManager returns a SpawnHandler immediately — a handle object with its own state, events, and lifecycle methods. The feature tracks all spawned processes, maintains observable state, and can automatically kill them on parent exit.
+
+## Usage
+
+```ts
+container.feature('processManager', {
+  // Register process.on exit/SIGINT/SIGTERM handlers to kill all tracked processes
+  autoCleanup,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `autoCleanup` | `boolean` | Register process.on exit/SIGINT/SIGTERM handlers to kill all tracked processes |
+
+## Methods
+
+### spawn
+
+Spawn a long-running process and return a handle immediately. The returned SpawnHandler provides events for stdout/stderr streaming, exit/crash notifications, and methods to kill or await the process.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | The command to execute (e.g. 'node', 'bun', 'python') |
+| `args` | `string[]` |  | Arguments to pass to the command |
+| `options` | `SpawnOptions` |  | Spawn configuration |
+
+`SpawnOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tag` | `string` | User-defined tag for later lookups via getByTag() |
+| `cwd` | `string` | Working directory for the spawned process (defaults to container cwd) |
+| `env` | `Record<string, string>` | Additional environment variables merged with process.env |
+| `stdin` | `'pipe' | 'inherit' | 'ignore' | null` | stdin mode: 'pipe' to write to the process, 'inherit', or 'ignore' (default: 'ignore') |
+| `stdout` | `'pipe' | 'inherit' | 'ignore' | null` | stdout mode: 'pipe' to capture output, 'inherit', or 'ignore' (default: 'pipe') |
+| `stderr` | `'pipe' | 'inherit' | 'ignore' | null` | stderr mode: 'pipe' to capture errors, 'inherit', or 'ignore' (default: 'pipe') |
+
+**Returns:** `SpawnHandler`
+
+
+
+### get
+
+Get a SpawnHandler by its unique ID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✓ | The process ID returned by spawn |
+
+**Returns:** `SpawnHandler | undefined`
+
+
+
+### getByTag
+
+Find a SpawnHandler by its user-defined tag.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `tag` | `string` | ✓ | The tag passed to spawn() |
+
+**Returns:** `SpawnHandler | undefined`
+
+
+
+### list
+
+List all tracked SpawnHandlers (running and finished).
+
+**Returns:** `SpawnHandler[]`
+
+
+
+### killAll
+
+Kill all running processes.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `signal` | `NodeJS.Signals | number` |  | Signal to send (default: SIGTERM) |
+
+**Returns:** `void`
+
+
+
+### stop
+
+Stop the process manager: kill all running processes and remove cleanup handlers.
+
+**Returns:** `Promise<void>`
+
+
+
+### remove
+
+Remove a finished handler from tracking.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `id` | `string` | ✓ | The process ID to remove |
+
+**Returns:** `boolean`
+
+
+
+### enable
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `Promise<this>`
+
+
+
+### _onHandlerDone
+
+Called by SpawnHandler when a process finishes. Updates feature-level state.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `handler` | `SpawnHandler` | ✓ | Parameter handler |
+| `status` | `'exited' | 'crashed' | 'killed'` | ✓ | Parameter status |
+| `exitCode` | `number` |  | Parameter exitCode |
+
+**Returns:** `void`
+
+
+
+## Events (Zod v4 schema)
+
+### spawned
+
+Event emitted by ProcessManager
+
+
+
+### exited
+
+Event emitted by ProcessManager
+
+
+
+### crashed
+
+Event emitted by ProcessManager
+
+
+
+### killed
+
+Event emitted by ProcessManager
+
+
+
+### allStopped
+
+Event emitted by ProcessManager
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `processes` | `object` | Map of process ID to metadata |
+| `totalSpawned` | `number` | Total number of processes spawned since feature creation |
+
+## Examples
+
+**features.processManager**
+
+```ts
+const pm = container.feature('processManager', { enable: true })
+
+const server = pm.spawn('node', ['server.js'], { tag: 'api', cwd: '/app' })
+server.on('stdout', (data) => console.log('[api]', data))
+server.on('crash', (code) => console.error('API crashed:', code))
+
+// Kill one
+server.kill()
+
+// Kill all tracked processes
+pm.killAll()
+
+// List and lookup
+pm.list()              // SpawnHandler[]
+pm.getByTag('api')     // SpawnHandler | undefined
+```
+

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

@@ -0,0 +1,278 @@
+# Python (features.python)
+
+The Python VM feature provides Python virtual machine capabilities for executing Python code. This feature automatically detects Python environments (uv, conda, venv, system) and provides methods to install dependencies and execute Python scripts. It can manage project-specific Python environments and maintain context between executions.
+
+## Usage
+
+```ts
+container.feature('python', {
+  // Directory containing the Python project
+  dir,
+  // Custom install command to override auto-detection
+  installCommand,
+  // Path to Python script that will populate locals/context
+  contextScript,
+  // Specific Python executable path to use
+  pythonPath,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `dir` | `string` | Directory containing the Python project |
+| `installCommand` | `string` | Custom install command to override auto-detection |
+| `contextScript` | `string` | Path to Python script that will populate locals/context |
+| `pythonPath` | `string` | Specific Python executable path to use |
+
+## Methods
+
+### enable
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `Promise<this>`
+
+
+
+### detectEnvironment
+
+Detects the Python environment type and sets the appropriate Python path. This method checks for various Python environment managers in order of preference: uv, conda, venv, then falls back to system Python. It sets the pythonPath and environmentType in the state.
+
+**Returns:** `Promise<void>`
+
+```ts
+await python.detectEnvironment()
+console.log(python.state.get('environmentType')) // 'uv' | 'conda' | 'venv' | 'system'
+console.log(python.state.get('pythonPath')) // '/path/to/python/executable'
+```
+
+
+
+### installDependencies
+
+Installs dependencies for the Python project. This method automatically detects the appropriate package manager and install command based on the environment type. If a custom installCommand is provided in options, it will use that instead.
+
+**Returns:** `Promise<{ stdout: string; stderr: string; exitCode: number }>`
+
+```ts
+// Auto-detect and install
+const result = await python.installDependencies()
+
+// With custom install command
+const python = container.feature('python', { 
+ installCommand: 'pip install -r requirements.txt' 
+})
+const result = await python.installDependencies()
+```
+
+
+
+### execute
+
+Executes Python code and returns the result. This method creates a temporary Python script with the provided code and variables, executes it using the detected Python environment, and captures the output.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | The Python code to execute |
+| `variables` | `Record<string, any>` |  | Variables to make available to the Python code |
+| `options` | `{ captureLocals?: boolean }` |  | Execution options |
+
+`{ captureLocals?: boolean }` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `captureLocals` | `any` | Whether to capture and return local variables after execution |
+
+**Returns:** `Promise<{ stdout: string; stderr: string; exitCode: number; locals?: any }>`
+
+```ts
+// Simple execution
+const result = await python.execute('print("Hello World")')
+console.log(result.stdout) // 'Hello World'
+
+// With variables
+const result = await python.execute('print(f"Hello {name}!")', { name: 'Alice' })
+
+// Capture locals
+const result = await python.execute('x = 42\ny = x * 2', {}, { captureLocals: true })
+console.log(result.locals) // { x: 42, y: 84 }
+```
+
+
+
+### executeFile
+
+Executes a Python file and returns the result.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filePath` | `string` | ✓ | Path to the Python file to execute |
+| `variables` | `Record<string, any>` |  | Variables to make available via command line arguments |
+
+**Returns:** `Promise<{ stdout: string; stderr: string; exitCode: number }>`
+
+```ts
+const result = await python.executeFile('/path/to/script.py')
+console.log(result.stdout)
+```
+
+
+
+### getEnvironmentInfo
+
+Gets information about the current Python environment.
+
+**Returns:** `Promise<{ version: string; path: string; packages: string[] }>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `projectDir` | `any` | Returns the root directory of the Python project. |
+| `pythonPath` | `any` | Returns the path to the Python executable for this environment. |
+| `environmentType` | `any` | Returns the detected environment type: 'uv', 'conda', 'venv', or 'system'. |
+
+## Events (Zod v4 schema)
+
+### ready
+
+Event emitted by Python
+
+
+
+### environmentDetected
+
+Event emitted by Python
+
+
+
+### installingDependencies
+
+Event emitted by Python
+
+
+
+### dependenciesInstalled
+
+Event emitted by Python
+
+
+
+### dependencyInstallFailed
+
+Event emitted by Python
+
+
+
+### localsParseError
+
+Event emitted by Python
+
+
+
+### codeExecuted
+
+Event emitted by Python
+
+
+
+### fileExecuted
+
+Event emitted by Python
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `pythonPath` | `any` | Path to the detected Python executable |
+| `projectDir` | `any` | Root directory of the Python project |
+| `environmentType` | `any` | Detected Python environment type (uv, conda, venv, or system) |
+| `isReady` | `boolean` | Whether the Python environment is ready for execution |
+| `lastExecutedScript` | `any` | Path to the last executed Python script |
+
+## Examples
+
+**features.python**
+
+```ts
+const python = container.feature('python', { 
+ dir: "/path/to/python/project",
+ contextScript: "/path/to/setup-context.py"
+})
+
+// Auto-install dependencies
+await python.installDependencies()
+
+// Execute Python code
+const result = await python.execute('print("Hello from Python!")')
+
+// Execute with custom variables
+const result2 = await python.execute('print(f"Hello {name}!")', { name: 'World' })
+```
+
+
+
+**detectEnvironment**
+
+```ts
+await python.detectEnvironment()
+console.log(python.state.get('environmentType')) // 'uv' | 'conda' | 'venv' | 'system'
+console.log(python.state.get('pythonPath')) // '/path/to/python/executable'
+```
+
+
+
+**installDependencies**
+
+```ts
+// Auto-detect and install
+const result = await python.installDependencies()
+
+// With custom install command
+const python = container.feature('python', { 
+ installCommand: 'pip install -r requirements.txt' 
+})
+const result = await python.installDependencies()
+```
+
+
+
+**execute**
+
+```ts
+// Simple execution
+const result = await python.execute('print("Hello World")')
+console.log(result.stdout) // 'Hello World'
+
+// With variables
+const result = await python.execute('print(f"Hello {name}!")', { name: 'Alice' })
+
+// Capture locals
+const result = await python.execute('x = 42\ny = x * 2', {}, { captureLocals: true })
+console.log(result.locals) // { x: 42, y: 84 }
+```
+
+
+
+**executeFile**
+
+```ts
+const result = await python.executeFile('/path/to/script.py')
+console.log(result.stdout)
+```
+

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

@@ -0,0 +1,88 @@
+# Repl (features.repl)
+
+REPL feature — provides an interactive read-eval-print loop with tab completion and history. Launches a REPL session that evaluates JavaScript/TypeScript expressions in a sandboxed VM context populated with the container and its helpers. Supports tab completion for dot-notation property access, command history persistence, and async/await.
+
+## Usage
+
+```ts
+container.feature('repl', {
+  // The prompt string to display in the REPL (default: "> ")
+  prompt,
+  // Path to the REPL history file for command persistence
+  historyPath,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `prompt` | `string` | The prompt string to display in the REPL (default: "> ") |
+| `historyPath` | `string` | Path to the REPL history file for command persistence |
+
+## Methods
+
+### start
+
+Start the REPL session. Creates a VM context populated with the container and its helpers, sets up readline with tab completion and history, then enters the interactive loop. Type `.exit` or `exit` to quit. Supports top-level await.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ historyPath?: string, context?: any }` |  | Configuration for the REPL session |
+
+`{ historyPath?: string, context?: any }` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `historyPath` | `any` | Custom path for the history file (defaults to node_modules/.cache/.repl_history) |
+| `context` | `any` | Additional variables to inject into the VM context |
+
+**Returns:** `void`
+
+```ts
+const repl = container.feature('repl', { enable: true })
+await repl.start({
+ context: { db: myDatabase },
+ historyPath: '.repl-history'
+})
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `isStarted` | `any` | Whether the REPL session is currently running. |
+| `vmContext` | `any` | The VM context object used for evaluating expressions in the REPL. |
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `started` | `boolean` | Whether the REPL server has been started |
+
+## Examples
+
+**features.repl**
+
+```ts
+const repl = container.feature('repl', { enable: true })
+await repl.start({ context: { myVar: 42 } })
+```
+
+
+
+**start**
+
+```ts
+const repl = container.feature('repl', { enable: true })
+await repl.start({
+ context: { db: myDatabase },
+ historyPath: '.repl-history'
+})
+```
+