luca 2.0.0 → 3.0.0

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

@@ -0,0 +1,399 @@
+# ChildProcess (features.proc)
+
+The ChildProcess feature provides utilities for executing external processes and commands. This feature wraps Node.js child process functionality to provide convenient methods for executing shell commands, spawning processes, and capturing their output. It supports both synchronous and asynchronous execution with various options.
+
+## Usage
+
+```ts
+container.feature('proc')
+```
+
+## Methods
+
+### execAndCapture
+
+Executes a command string and captures its output asynchronously. This method takes a complete command string, splits it into command and arguments, and executes it using the spawnAndCapture method. It's a convenient wrapper for simple command execution.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `cmd` | `string` | ✓ | The complete command string to execute (e.g., "git status --porcelain") |
+| `options` | `any` |  | Options to pass to the underlying spawn process |
+
+**Returns:** `Promise<{
+    stderr: string;
+    stdout: string;
+    error: null | any;
+    exitCode: number;
+    pid: number | null;
+  }>`
+
+```ts
+// Execute a git command
+const result = await proc.execAndCapture('git status --porcelain')
+if (result.exitCode === 0) {
+ console.log('Git status:', result.stdout)
+} else {
+ console.error('Git error:', result.stderr)
+}
+
+// Execute with options
+const result = await proc.execAndCapture('npm list --depth=0', {
+ cwd: '/path/to/project'
+})
+```
+
+
+
+### spawnAndCapture
+
+Spawns a process and captures its output with real-time monitoring capabilities. This method provides comprehensive process execution with the ability to capture output, monitor real-time data streams, and handle process lifecycle events. It's ideal for long-running processes where you need to capture output as it happens.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | The command to execute (e.g., 'node', 'npm', 'git') |
+| `args` | `string[]` | ✓ | Array of arguments to pass to the command |
+| `options` | `SpawnOptions` |  | Options for process execution and monitoring |
+
+`SpawnOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `stdio` | `"ignore" | "inherit"` | Standard I/O mode for the child process |
+| `stdout` | `"ignore" | "inherit"` | Stdout mode for the child process |
+| `stderr` | `"ignore" | "inherit"` | Stderr mode for the child process |
+| `cwd` | `string` | Working directory for the child process |
+| `environment` | `Record<string, any>` | Environment variables to pass to the child process |
+| `onError` | `(data: string) => void` | Callback invoked when stderr data is received |
+| `onOutput` | `(data: string) => void` | Callback invoked when stdout data is received |
+| `onExit` | `(code: number) => void` | Callback invoked when the process exits |
+| `onStart` | `(childProcess: ChildProcess) => void` | Callback invoked when the process starts |
+
+**Returns:** `Promise<{
+    stderr: string;
+    stdout: string;
+    error: null | any;
+    exitCode: number;
+    pid: number | null;
+  }>`
+
+```ts
+// Basic usage
+const result = await proc.spawnAndCapture('node', ['--version'])
+console.log(`Node version: ${result.stdout}`)
+
+// With real-time output monitoring
+const result = await proc.spawnAndCapture('npm', ['install'], {
+ onOutput: (data) => console.log('📦 ', data.trim()),
+ onError: (data) => console.error('❌ ', data.trim()),
+ onExit: (code) => console.log(`Process exited with code ${code}`)
+})
+
+// Long-running process with custom working directory
+const buildResult = await proc.spawnAndCapture('npm', ['run', 'build'], {
+ cwd: '/path/to/project',
+ onOutput: (data) => {
+   if (data.includes('error')) {
+     console.error('Build error detected:', data)
+   }
+ }
+})
+```
+
+
+
+### spawn
+
+Spawn a raw child process and return the handle immediately. Useful when callers need streaming access to stdout/stderr and direct lifecycle control (for example, cancellation via kill()).
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | Parameter command |
+| `args` | `string[]` |  | Parameter args |
+| `options` | `RawSpawnOptions` |  | Parameter options |
+
+`RawSpawnOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `cwd` | `string` | Working directory for the child process |
+| `environment` | `Record<string, any>` | Environment variables to pass to the child process |
+| `stdin` | `string | Buffer` | Optional stdin payload written immediately after spawn |
+| `stdout` | `"pipe" | "inherit" | "ignore"` | Stdout mode for the child process |
+| `stderr` | `"pipe" | "inherit" | "ignore"` | Stderr mode for the child process |
+
+**Returns:** `import('child_process').ChildProcess`
+
+
+
+### 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.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | The command to execute |
+| `options` | `any` |  | Options for command execution (cwd, encoding, etc.) |
+
+**Returns:** `string`
+
+```ts
+const branch = proc.exec('git branch --show-current')
+const version = proc.exec('node --version')
+```
+
+
+
+### execSync
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `command` | `string` | ✓ | Parameter command |
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `string`
+
+
+
+### establishLock
+
+Establishes a PID-file lock to prevent duplicate process instances. Writes the current process PID to the given file path. If the file already exists and the PID inside it refers to a running process, the current process exits immediately. Stale PID files (where the process is no longer running) are automatically cleaned up. Cleanup handlers are registered on SIGTERM, SIGINT, and process exit to remove the PID file when the process shuts down.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pidPath` | `string` | ✓ | Path to the PID file, resolved relative to container.cwd |
+
+**Returns:** `{ release: () => void }`
+
+```ts
+// In a command handler — exits if already running
+const lock = proc.establishLock('tmp/luca-main.pid')
+
+// Later, if you need to release manually
+lock.release()
+```
+
+
+
+### kill
+
+Kills a process by its PID.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `pid` | `number` | ✓ | The process ID to kill |
+| `signal` | `NodeJS.Signals | number` |  | The signal to send (e.g. 'SIGTERM', 'SIGKILL', 9) |
+
+**Returns:** `boolean`
+
+```ts
+// Gracefully terminate a process
+proc.kill(12345)
+
+// Force kill a process
+proc.kill(12345, 'SIGKILL')
+```
+
+
+
+### findPidsByPort
+
+Finds PIDs of processes listening on a given port. Uses `lsof` on macOS/Linux to discover which processes have a socket bound to the specified port.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `port` | `number` | ✓ | The port number to search for |
+
+**Returns:** `number[]`
+
+```ts
+const pids = proc.findPidsByPort(3000)
+console.log(`Processes on port 3000: ${pids}`)
+
+// Kill everything on port 3000
+for (const pid of proc.findPidsByPort(3000)) {
+ proc.kill(pid)
+}
+```
+
+
+
+### isProcessRunning
+
+Checks whether any process matching a given name is currently running. Uses `pgrep -x` for an exact match against process names.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | The process name to look for (e.g. 'afplay', 'node', 'nginx') |
+
+**Returns:** `boolean`
+
+```ts
+if (proc.isProcessRunning('afplay')) {
+ console.log('Audio is currently playing')
+}
+```
+
+
+
+### onSignal
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `signal` | `NodeJS.Signals` | ✓ | Parameter signal |
+| `handler` | `() => void` | ✓ | Parameter handler |
+
+**Returns:** `() => void`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.proc**
+
+```ts
+const proc = container.feature('proc')
+
+// Execute a simple command synchronously
+const result = proc.exec('echo "Hello World"')
+console.log(result) // 'Hello World'
+
+// Execute and capture output asynchronously
+const { stdout, stderr } = await proc.spawnAndCapture('npm', ['--version'])
+console.log(`npm version: ${stdout}`)
+
+// Execute with callbacks for real-time output
+await proc.spawnAndCapture('npm', ['install'], {
+ onOutput: (data) => console.log('OUT:', data),
+ onError: (data) => console.log('ERR:', data)
+})
+```
+
+
+
+**execAndCapture**
+
+```ts
+// Execute a git command
+const result = await proc.execAndCapture('git status --porcelain')
+if (result.exitCode === 0) {
+ console.log('Git status:', result.stdout)
+} else {
+ console.error('Git error:', result.stderr)
+}
+
+// Execute with options
+const result = await proc.execAndCapture('npm list --depth=0', {
+ cwd: '/path/to/project'
+})
+```
+
+
+
+**spawnAndCapture**
+
+```ts
+// Basic usage
+const result = await proc.spawnAndCapture('node', ['--version'])
+console.log(`Node version: ${result.stdout}`)
+
+// With real-time output monitoring
+const result = await proc.spawnAndCapture('npm', ['install'], {
+ onOutput: (data) => console.log('📦 ', data.trim()),
+ onError: (data) => console.error('❌ ', data.trim()),
+ onExit: (code) => console.log(`Process exited with code ${code}`)
+})
+
+// Long-running process with custom working directory
+const buildResult = await proc.spawnAndCapture('npm', ['run', 'build'], {
+ cwd: '/path/to/project',
+ onOutput: (data) => {
+   if (data.includes('error')) {
+     console.error('Build error detected:', data)
+   }
+ }
+})
+```
+
+
+
+**exec**
+
+```ts
+const branch = proc.exec('git branch --show-current')
+const version = proc.exec('node --version')
+```
+
+
+
+**establishLock**
+
+```ts
+// In a command handler — exits if already running
+const lock = proc.establishLock('tmp/luca-main.pid')
+
+// Later, if you need to release manually
+lock.release()
+```
+
+
+
+**kill**
+
+```ts
+// Gracefully terminate a process
+proc.kill(12345)
+
+// Force kill a process
+proc.kill(12345, 'SIGKILL')
+```
+
+
+
+**findPidsByPort**
+
+```ts
+const pids = proc.findPidsByPort(3000)
+console.log(`Processes on port 3000: ${pids}`)
+
+// Kill everything on port 3000
+for (const pid of proc.findPidsByPort(3000)) {
+ proc.kill(pid)
+}
+```
+
+
+
+**isProcessRunning**
+
+```ts
+if (proc.isProcessRunning('afplay')) {
+ console.log('Audio is currently playing')
+}
+```
+

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

@@ -0,0 +1,305 @@
+# 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. Each handler maintains a memory-efficient output buffer: the first 20 lines (head) and last 50 lines (tail) of stdout/stderr are kept, everything in between is discarded.
+
+## 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
+
+### spawnProcess
+
+Tool handler: spawn a long-running background process.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ command: string; args?: string; tag?: string; cwd?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### runCommand
+
+Tool handler: run a command to completion and return its output.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ command: string; cwd?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### listProcesses
+
+Tool handler: list all tracked processes.
+
+**Returns:** `void`
+
+
+
+### getProcessOutput
+
+Tool handler: peek at a process's buffered output.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id?: string; tag?: string; stream?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### killProcess
+
+Tool handler: kill a process by ID or tag.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `args` | `{ id?: string; tag?: string; signal?: string }` | ✓ | Parameter args |
+
+**Returns:** `void`
+
+
+
+### 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
+
+Emitted when a new process is spawned
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | process ID |
+| `arg1` | `string` | process metadata |
+
+
+
+### exited
+
+Emitted when a process exits normally
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | process ID |
+| `arg1` | `number` | exit code |
+
+
+
+### crashed
+
+Emitted when a process exits with non-zero code
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | process ID |
+| `arg1` | `number` | exit code |
+| `arg2` | `string` | error info |
+
+
+
+### killed
+
+Emitted when a process is killed
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | process ID |
+
+
+
+### allStopped
+
+Emitted when all tracked processes have stopped
+
+
+
+## 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))
+
+// Peek at buffered output
+const { head, tail } = server.peek()
+
+// Kill one
+server.kill()
+
+// Kill all tracked processes
+pm.killAll()
+
+// List and lookup
+pm.list()              // SpawnHandler[]
+pm.getByTag('api')     // SpawnHandler | undefined
+```
+