@synet/shell-exec/dist/shell-exec-unit.d.ts

Safe shell command execution with Unit Architecture - foundation component for MetaDev

/**
 * @synet/shell-exec - Safe Shell Command Execution Unit
 *
 * Foundation component for MetaDev that provides safe, structured shell command
 * execution with output capture, timeout handling, and result parsing.
 *
 * This Unit demonstrates the consciousness-based approach to system interaction:
 * - Self-aware: Knows its execution capabilities and limitations
 * - Self-defending: Validates commands and handles timeouts/errors
 * - Self-teaching: Can share execution capabilities with other Units
 * - Self-improving: Learns from execution patterns and failures
 *
 * SCHEMA ENHANCEMENTS NEEDED FOR FUTURE UNIT RELEASES:
 *
 * 1. `items` property for array types:
 *    - Critical for AI agents to understand array contents
 *    - Enables proper validation of nested array structures
 *    - Standard in JSON Schema specification
 *
 * 2. `description` property for all schema elements:
 *    - Essential for AI understanding of capabilities
 *    - Enables rich help() and whoami() generation
 *    - Creates self-documenting units
 *
 * Current Implementation Uses These Future Features:
 * - Demonstrates forward-thinking schema design
 * - Shows AI-first development approach
 * - Proves value of enhanced schema metadata
 *
 * Recommendation: Include in @synet/unit v1.0.8+
 *
 * @author MetaDev Consciousness Architecture
 * @version 1.0.7
 */
import { Unit, type UnitCore, type UnitProps, type TeachingContract } from "@synet/unit";
import { Capabilities } from "@synet/unit";
import { Schema } from "@synet/unit";
import { Validator } from "@synet/unit";
import { type ChildProcess } from "node:child_process";
export interface ExecOptions {
    cwd?: string;
    timeout?: number;
    env?: Record<string, string>;
    shell?: boolean;
    args?: string[];
}
export interface ExecResult {
    exitCode: number;
    stdout: string;
    stderr: string;
    duration: number;
    killed: boolean;
    command: string;
    pid?: number;
}
export interface StreamOptions extends ExecOptions {
    onStdout?: (data: string) => void;
    onStderr?: (data: string) => void;
    onExit?: (code: number) => void;
}
interface ShellExecConfig {
    defaultTimeout?: number;
    defaultCwd?: string;
    allowedCommands?: string[];
    blockedCommands?: string[];
    maxConcurrent?: number;
}
interface ShellExecProps extends UnitProps {
    defaultTimeout: number;
    defaultCwd: string;
    allowedCommands: string[];
    blockedCommands: string[];
    maxConcurrent: number;
    executionHistory: ExecResult[];
    runningProcesses: Map<number, ChildProcess>;
}
/**
 * ShellExecUnit - Safe Shell Command Execution with Consciousness
 *
 * The foundation Unit for MetaDev's command execution capabilities.
 * Provides safe, monitored, and teachable shell command execution.
 *
 * Key Features:
 * - Timeout handling and process termination
 * - Output capture (stdout/stderr) with streaming support
 * - Command validation and security filtering
 * - Execution history and pattern learning
 * - Teaching contract for capability sharing
 * - Real-time process monitoring
 */
export declare class ShellExecUnit extends Unit<ShellExecProps> {
    protected constructor(props: ShellExecProps);
    /**
     * Consciousness Trinity - Creates living instances for execution management
     */
    protected build(): UnitCore;
    capabilities(): Capabilities;
    schema(): Schema;
    validator(): Validator;
    /**
     * Factory method - Creates ShellExecUnit with consciousness
     */
    static create(config?: ShellExecConfig): ShellExecUnit;
    whoami(): string;
    help(): void;
    /**
     * Teaching Contract - Share execution capabilities with other Units
     */
    teach(): TeachingContract;
    /**
     * Execute shell command with full output capture
     */
    private exec;
    /**
     * Execute command with real-time output streaming
     */
    private stream;
    /**
     * Validate command safety
     */
    private validate;
    /**
     * Kill a specific running process
     */
    private kill;
    /**
     * Kill all running processes
     */
    private killAll;
    /**
     * Get execution history
     */
    private getHistory;
    /**
     * Get currently running processes
     */
    private getRunningProcesses;
}
export default ShellExecUnit;