@soederpop/luca 0.0.31 → 0.0.34

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

@@ -1,6 +1,6 @@
 # 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.
+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. Supports two modes: - **Stateless** (default): `execute()` and `executeFile()` spawn a fresh process per call - **Persistent session**: `startSession()` spawns a long-lived bridge process that maintains state across `run()` calls, enabling real codebase interaction with imports and session variables
 
 ## Usage
 
@@ -136,6 +136,154 @@ Gets information about the current Python environment.
 
 
 
+### startSession
+
+Starts a persistent Python session by spawning the bridge process. The bridge sets up sys.path for the project directory, then enters a JSON-line REPL loop. State (variables, imports) persists across run() calls until stopSession() or resetSession() is called.
+
+**Returns:** `Promise<void>`
+
+```ts
+const python = container.feature('python', { dir: '/path/to/project' })
+await python.enable()
+await python.startSession()
+await python.run('x = 42')
+const result = await python.run('print(x)')
+console.log(result.stdout) // '42\n'
+await python.stopSession()
+```
+
+
+
+### stopSession
+
+Stops the persistent Python session and cleans up the bridge process.
+
+**Returns:** `Promise<void>`
+
+```ts
+await python.stopSession()
+```
+
+
+
+### run
+
+Executes Python code in the persistent session. Variables and imports survive across calls. This is the session equivalent of execute().
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | Python code to execute |
+| `variables` | `Record<string, any>` |  | Variables to inject into the namespace before execution |
+
+**Returns:** `Promise<RunResult>`
+
+```ts
+await python.startSession()
+
+// State persists across calls
+await python.run('x = 42')
+const result = await python.run('print(x * 2)')
+console.log(result.stdout) // '84\n'
+
+// Inject variables from JS
+const result2 = await python.run('print(f"Hello {name}!")', { name: 'World' })
+console.log(result2.stdout) // 'Hello World!\n'
+```
+
+
+
+### eval
+
+Evaluates a Python expression in the persistent session and returns its value.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `expression` | `string` | ✓ | Python expression to evaluate |
+
+**Returns:** `Promise<any>`
+
+```ts
+await python.run('x = 42')
+const result = await python.eval('x * 2')
+console.log(result) // 84
+```
+
+
+
+### importModule
+
+Imports a Python module into the persistent session namespace.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `moduleName` | `string` | ✓ | Dotted module path (e.g. 'myapp.models') |
+| `alias` | `string` |  | Optional alias for the import (defaults to the last segment) |
+
+**Returns:** `Promise<void>`
+
+```ts
+await python.importModule('json')
+await python.importModule('myapp.models', 'models')
+const result = await python.eval('models.User')
+```
+
+
+
+### call
+
+Calls a function by dotted path in the persistent session namespace.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `funcPath` | `string` | ✓ | Dotted path to the function (e.g. 'json.dumps' or 'my_func') |
+| `args` | `any[]` |  | Positional arguments |
+| `kwargs` | `Record<string, any>` |  | Keyword arguments |
+
+**Returns:** `Promise<any>`
+
+```ts
+await python.importModule('json')
+const result = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })
+```
+
+
+
+### getLocals
+
+Returns all non-dunder variables from the persistent session namespace.
+
+**Returns:** `Promise<Record<string, any>>`
+
+```ts
+await python.run('x = 42\ny = "hello"')
+const locals = await python.getLocals()
+console.log(locals) // { x: 42, y: 'hello' }
+```
+
+
+
+### resetSession
+
+Clears all variables and imports from the persistent session namespace. The session remains active — you can continue calling run() after reset.
+
+**Returns:** `Promise<void>`
+
+```ts
+await python.run('x = 42')
+await python.resetSession()
+// x is now undefined
+```
+
+
+
 ## Getters
 
 | Property | Type | Description |
@@ -194,6 +342,24 @@ Event emitted by Python
 
 
 
+### sessionError
+
+Event emitted by Python
+
+
+
+### sessionStarted
+
+Event emitted by Python
+
+
+
+### sessionStopped
+
+Event emitted by Python
+
+
+
 ## State (Zod v4 schema)
 
 | Property | Type | Description |
@@ -204,25 +370,27 @@ Event emitted by Python
 | `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 |
+| `sessionActive` | `boolean` | Whether a persistent Python session is currently active |
+| `sessionId` | `any` | Unique ID of the current persistent session |
 
 ## Examples
 
 **features.python**
 
 ```ts
-const python = container.feature('python', { 
+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
+// Stateless execution
 const result = await python.execute('print("Hello from Python!")')
 
-// Execute with custom variables
-const result2 = await python.execute('print(f"Hello {name}!")', { name: 'World' })
+// Persistent session
+await python.startSession()
+await python.run('import myapp.models')
+await python.run('users = myapp.models.User.objects.all()')
+const result = await python.run('print(len(users))')
+await python.stopSession()
 ```
 
 
@@ -276,3 +444,91 @@ const result = await python.executeFile('/path/to/script.py')
 console.log(result.stdout)
 ```
 
+
+
+**startSession**
+
+```ts
+const python = container.feature('python', { dir: '/path/to/project' })
+await python.enable()
+await python.startSession()
+await python.run('x = 42')
+const result = await python.run('print(x)')
+console.log(result.stdout) // '42\n'
+await python.stopSession()
+```
+
+
+
+**stopSession**
+
+```ts
+await python.stopSession()
+```
+
+
+
+**run**
+
+```ts
+await python.startSession()
+
+// State persists across calls
+await python.run('x = 42')
+const result = await python.run('print(x * 2)')
+console.log(result.stdout) // '84\n'
+
+// Inject variables from JS
+const result2 = await python.run('print(f"Hello {name}!")', { name: 'World' })
+console.log(result2.stdout) // 'Hello World!\n'
+```
+
+
+
+**eval**
+
+```ts
+await python.run('x = 42')
+const result = await python.eval('x * 2')
+console.log(result) // 84
+```
+
+
+
+**importModule**
+
+```ts
+await python.importModule('json')
+await python.importModule('myapp.models', 'models')
+const result = await python.eval('models.User')
+```
+
+
+
+**call**
+
+```ts
+await python.importModule('json')
+const result = await python.call('json.dumps', [{ a: 1 }], { indent: 2 })
+```
+
+
+
+**getLocals**
+
+```ts
+await python.run('x = 42\ny = "hello"')
+const locals = await python.getLocals()
+console.log(locals) // { x: 42, y: 'hello' }
+```
+
+
+
+**resetSession**
+
+```ts
+await python.run('x = 42')
+await python.resetSession()
+// x is now undefined
+```
+

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

@@ -0,0 +1,380 @@
+# RedisFeature (features.redis)
+
+Redis feature for shared state and pub/sub communication between container instances. Wraps ioredis with a focused API for the primitives that matter most: key/value state, pub/sub messaging, and cross-instance coordination. Uses a dedicated subscriber connection for pub/sub (ioredis requirement), created lazily on first subscribe call.
+
+## Usage
+
+```ts
+container.feature('redis', {
+  // Redis connection URL, e.g. redis://localhost:6379. Defaults to redis://localhost:6379
+  url,
+  // Key prefix applied to all get/set/del operations for namespace isolation
+  prefix,
+  // If true, connection is deferred until first command
+  lazyConnect,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `url` | `string` | Redis connection URL, e.g. redis://localhost:6379. Defaults to redis://localhost:6379 |
+| `prefix` | `string` | Key prefix applied to all get/set/del operations for namespace isolation |
+| `lazyConnect` | `boolean` | If true, connection is deferred until first command |
+
+## Methods
+
+### set
+
+Set a key to a string value with optional TTL.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+| `value` | `string` | ✓ | The string value to store |
+| `ttl` | `number` |  | Optional time-to-live in seconds |
+
+**Returns:** `Promise<void>`
+
+
+
+### get
+
+Get a key's value. Returns null if the key doesn't exist.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+
+**Returns:** `Promise<string | null>`
+
+
+
+### del
+
+Delete one or more keys.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `keys` | `string[]` | ✓ | One or more key names to delete |
+
+**Returns:** `Promise<number>`
+
+
+
+### exists
+
+Check if a key exists.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+
+**Returns:** `Promise<boolean>`
+
+
+
+### expire
+
+Set a key's TTL in seconds.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+| `seconds` | `number` | ✓ | TTL in seconds |
+
+**Returns:** `Promise<boolean>`
+
+
+
+### keys
+
+Find keys matching a glob pattern (respects prefix).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pattern` | `string` |  | Glob pattern, e.g. "worker:*" |
+
+**Returns:** `Promise<string[]>`
+
+
+
+### setJSON
+
+Store a value as JSON.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+| `value` | `unknown` | ✓ | Any JSON-serializable value |
+| `ttl` | `number` |  | Optional TTL in seconds |
+
+**Returns:** `Promise<void>`
+
+
+
+### getJSON
+
+Retrieve and parse a JSON value.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The key name |
+
+**Returns:** `Promise<T | null>`
+
+
+
+### hset
+
+Set fields on a hash.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The hash key |
+| `fields` | `Record<string, string>` | ✓ | Object of field/value pairs |
+
+**Returns:** `Promise<void>`
+
+
+
+### hgetall
+
+Get all fields from a hash.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The hash key |
+
+**Returns:** `Promise<Record<string, string>>`
+
+
+
+### hget
+
+Get a single field from a hash.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `key` | `string` | ✓ | The hash key |
+| `field` | `string` | ✓ | The field name |
+
+**Returns:** `Promise<string | null>`
+
+
+
+### subscribe
+
+Subscribe to one or more channels. Optionally pass a handler that fires only for these channels. The feature also emits a `message` event for all messages.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `channels` | `string | string[]` | ✓ | Channel name(s) to subscribe to |
+| `handler` | `MessageHandler` |  | Optional per-channel message handler |
+
+**Returns:** `Promise<void>`
+
+```ts
+await redis.subscribe('tasks', (channel, msg) => {
+ console.log(`Got ${msg} on ${channel}`)
+})
+```
+
+
+
+### unsubscribe
+
+Unsubscribe from one or more channels.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `channels` | `string[]` | ✓ | Channel name(s) to unsubscribe from |
+
+**Returns:** `Promise<void>`
+
+
+
+### publish
+
+Publish a message to a channel.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `channel` | `string` | ✓ | The channel to publish to |
+| `message` | `string` | ✓ | The message string (use JSON.stringify for objects) |
+
+**Returns:** `Promise<number>`
+
+
+
+### ensureLocalDocker
+
+Spin up a local Redis instance via Docker. Checks if a container with the given name already exists and starts it if stopped, or creates a new one from redis:alpine. Requires the docker feature to be available on the container.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `{ name?: string; port?: number; image?: string }` |  | Container name and host port |
+
+**Returns:** `Promise<string>`
+
+```ts
+const redis = container.feature('redis', { url: 'redis://localhost:6379', lazyConnect: true })
+await redis.ensureLocalDocker()
+```
+
+
+
+### close
+
+Close all redis connections (main client + subscriber).
+
+**Returns:** `Promise<this>`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `client` | `Redis` | The underlying ioredis client for advanced operations. |
+| `subscriber` | `Redis | null` | The dedicated subscriber connection, if pub/sub is active. |
+
+## Events (Zod v4 schema)
+
+### message
+
+When a message is received on a subscribed channel
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The channel name |
+| `arg1` | `string` | The message payload |
+
+
+
+### error
+
+When a redis operation fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The error message |
+
+
+
+### subscribed
+
+When successfully subscribed to a channel
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The channel name |
+
+
+
+### unsubscribed
+
+When unsubscribed from a channel
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The channel name |
+
+
+
+### closed
+
+When the redis connection is closed
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `connected` | `boolean` | Whether the redis connection is currently open |
+| `url` | `string` | Connection URL used for this redis feature instance |
+| `subscriberConnected` | `boolean` | Whether the dedicated subscriber connection is open |
+| `subscribedChannels` | `array` | List of channels currently subscribed to |
+| `lastError` | `string` | Most recent redis error message, if any |
+
+## Examples
+
+**features.redis**
+
+```ts
+const redis = container.feature('redis', { url: 'redis://localhost:6379' })
+
+// Shared state
+await redis.set('worker:status', 'active')
+const status = await redis.get('worker:status')
+
+// Pub/sub between instances
+redis.on('message', (channel, msg) => console.log(`${channel}: ${msg}`))
+await redis.subscribe('tasks')
+await redis.publish('tasks', JSON.stringify({ type: 'ping' }))
+
+// JSON helpers
+await redis.setJSON('config', { workers: 4, debug: true })
+const config = await redis.getJSON<{ workers: number }>('config')
+```
+
+
+
+**subscribe**
+
+```ts
+await redis.subscribe('tasks', (channel, msg) => {
+ console.log(`Got ${msg} on ${channel}`)
+})
+```
+
+
+
+**ensureLocalDocker**
+
+```ts
+const redis = container.feature('redis', { url: 'redis://localhost:6379', lazyConnect: true })
+await redis.ensureLocalDocker()
+```
+