@dexto/tools-process 1.5.0

package/dist/process-service.d.cts

@@ -0,0 +1,96 @@
+import { ProcessConfig, ExecuteOptions, ProcessResult, ProcessHandle, ProcessOutput, ProcessInfo } from './types.cjs';
+import { IDextoLogger } from '@dexto/core';
+
+/**
+ * Process Service
+ *
+ * Secure command execution and process management for Dexto internal tools
+ */
+
+/**
+ * ProcessService - Handles command execution and process management
+ *
+ * This service receives fully-validated configuration from the Process Tools Provider.
+ * All defaults have been applied by the provider's schema, so the service trusts the config
+ * and uses it as-is without any fallback logic.
+ *
+ * TODO: Add tests for this class
+ */
+declare class ProcessService {
+    private config;
+    private commandValidator;
+    private initialized;
+    private initPromise;
+    private backgroundProcesses;
+    private logger;
+    /**
+     * Create a new ProcessService with validated configuration.
+     *
+     * @param config - Fully-validated configuration from provider schema.
+     *                 All required fields have values, defaults already applied.
+     * @param logger - Logger instance for this service
+     */
+    constructor(config: ProcessConfig, logger: IDextoLogger);
+    /**
+     * Initialize the service.
+     * Safe to call multiple times - subsequent calls return the same promise.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Internal initialization logic.
+     */
+    private doInitialize;
+    /**
+     * Ensure the service is initialized before use.
+     * Tools should call this at the start of their execute methods.
+     * Safe to call multiple times - will await the same initialization promise.
+     */
+    ensureInitialized(): Promise<void>;
+    /**
+     * Execute a command
+     */
+    executeCommand(command: string, options?: ExecuteOptions): Promise<ProcessResult | ProcessHandle>;
+    private static readonly SIGKILL_TIMEOUT_MS;
+    /**
+     * Kill a process tree (process group on Unix, taskkill on Windows)
+     */
+    private killProcessTree;
+    /**
+     * Execute command in foreground with timeout and abort support
+     */
+    private executeForeground;
+    /**
+     * Execute command in background
+     */
+    private executeInBackground;
+    /**
+     * Get output from a background process
+     */
+    getProcessOutput(processId: string): Promise<ProcessOutput>;
+    /**
+     * Kill a background process
+     */
+    killProcess(processId: string): Promise<void>;
+    /**
+     * List all background processes
+     */
+    listProcesses(): Promise<ProcessInfo[]>;
+    /**
+     * Get buffer size in bytes
+     */
+    private getBufferSize;
+    /**
+     * Get service configuration
+     */
+    getConfig(): Readonly<ProcessConfig>;
+    /**
+     * Resolve and confine cwd to the configured working directory
+     */
+    private resolveSafeCwd;
+    /**
+     * Cleanup completed processes
+     */
+    cleanup(): Promise<void>;
+}
+
+export { ProcessService };

package/dist/process-service.d.ts

@@ -0,0 +1,96 @@
+import { ProcessConfig, ExecuteOptions, ProcessResult, ProcessHandle, ProcessOutput, ProcessInfo } from './types.js';
+import { IDextoLogger } from '@dexto/core';
+
+/**
+ * Process Service
+ *
+ * Secure command execution and process management for Dexto internal tools
+ */
+
+/**
+ * ProcessService - Handles command execution and process management
+ *
+ * This service receives fully-validated configuration from the Process Tools Provider.
+ * All defaults have been applied by the provider's schema, so the service trusts the config
+ * and uses it as-is without any fallback logic.
+ *
+ * TODO: Add tests for this class
+ */
+declare class ProcessService {
+    private config;
+    private commandValidator;
+    private initialized;
+    private initPromise;
+    private backgroundProcesses;
+    private logger;
+    /**
+     * Create a new ProcessService with validated configuration.
+     *
+     * @param config - Fully-validated configuration from provider schema.
+     *                 All required fields have values, defaults already applied.
+     * @param logger - Logger instance for this service
+     */
+    constructor(config: ProcessConfig, logger: IDextoLogger);
+    /**
+     * Initialize the service.
+     * Safe to call multiple times - subsequent calls return the same promise.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Internal initialization logic.
+     */
+    private doInitialize;
+    /**
+     * Ensure the service is initialized before use.
+     * Tools should call this at the start of their execute methods.
+     * Safe to call multiple times - will await the same initialization promise.
+     */
+    ensureInitialized(): Promise<void>;
+    /**
+     * Execute a command
+     */
+    executeCommand(command: string, options?: ExecuteOptions): Promise<ProcessResult | ProcessHandle>;
+    private static readonly SIGKILL_TIMEOUT_MS;
+    /**
+     * Kill a process tree (process group on Unix, taskkill on Windows)
+     */
+    private killProcessTree;
+    /**
+     * Execute command in foreground with timeout and abort support
+     */
+    private executeForeground;
+    /**
+     * Execute command in background
+     */
+    private executeInBackground;
+    /**
+     * Get output from a background process
+     */
+    getProcessOutput(processId: string): Promise<ProcessOutput>;
+    /**
+     * Kill a background process
+     */
+    killProcess(processId: string): Promise<void>;
+    /**
+     * List all background processes
+     */
+    listProcesses(): Promise<ProcessInfo[]>;
+    /**
+     * Get buffer size in bytes
+     */
+    private getBufferSize;
+    /**
+     * Get service configuration
+     */
+    getConfig(): Readonly<ProcessConfig>;
+    /**
+     * Resolve and confine cwd to the configured working directory
+     */
+    private resolveSafeCwd;
+    /**
+     * Cleanup completed processes
+     */
+    cleanup(): Promise<void>;
+}
+
+export { ProcessService };

package/dist/process-service.js

@@ -0,0 +1,510 @@
+import { spawn } from "node:child_process";
+import * as crypto from "node:crypto";
+import * as path from "node:path";
+import { CommandValidator } from "./command-validator.js";
+import { ProcessError } from "./errors.js";
+import { DextoLogComponent } from "@dexto/core";
+const DEFAULT_TIMEOUT = 12e4;
+class ProcessService {
+  config;
+  commandValidator;
+  initialized = false;
+  initPromise = null;
+  backgroundProcesses = /* @__PURE__ */ new Map();
+  logger;
+  /**
+   * Create a new ProcessService with validated configuration.
+   *
+   * @param config - Fully-validated configuration from provider schema.
+   *                 All required fields have values, defaults already applied.
+   * @param logger - Logger instance for this service
+   */
+  constructor(config, logger) {
+    this.config = config;
+    this.logger = logger.createChild(DextoLogComponent.PROCESS);
+    this.commandValidator = new CommandValidator(this.config, this.logger);
+  }
+  /**
+   * Initialize the service.
+   * Safe to call multiple times - subsequent calls return the same promise.
+   */
+  initialize() {
+    if (this.initPromise) {
+      return this.initPromise;
+    }
+    this.initPromise = this.doInitialize();
+    return this.initPromise;
+  }
+  /**
+   * Internal initialization logic.
+   */
+  async doInitialize() {
+    if (this.initialized) {
+      this.logger.debug("ProcessService already initialized");
+      return;
+    }
+    this.backgroundProcesses.clear();
+    this.initialized = true;
+    this.logger.info("ProcessService initialized successfully");
+  }
+  /**
+   * Ensure the service is initialized before use.
+   * Tools should call this at the start of their execute methods.
+   * Safe to call multiple times - will await the same initialization promise.
+   */
+  async ensureInitialized() {
+    if (this.initialized) {
+      return;
+    }
+    await this.initialize();
+  }
+  /**
+   * Execute a command
+   */
+  async executeCommand(command, options = {}) {
+    await this.ensureInitialized();
+    const validation = this.commandValidator.validateCommand(command);
+    if (!validation.isValid || !validation.normalizedCommand) {
+      throw ProcessError.invalidCommand(command, validation.error || "Unknown error");
+    }
+    const normalizedCommand = validation.normalizedCommand;
+    const rawTimeout = options.timeout !== void 0 && Number.isFinite(options.timeout) ? options.timeout : DEFAULT_TIMEOUT;
+    const timeout = Math.max(1, Math.min(rawTimeout, this.config.maxTimeout));
+    const cwd = this.resolveSafeCwd(options.cwd);
+    const env = {};
+    for (const [key, value] of Object.entries({
+      ...process.env,
+      ...this.config.environment,
+      ...options.env
+    })) {
+      if (value !== void 0) {
+        env[key] = value;
+      }
+    }
+    if (options.runInBackground) {
+      return await this.executeInBackground(normalizedCommand, options);
+    }
+    return await this.executeForeground(normalizedCommand, {
+      cwd,
+      timeout,
+      env,
+      ...options.description !== void 0 && { description: options.description },
+      ...options.abortSignal !== void 0 && { abortSignal: options.abortSignal }
+    });
+  }
+  static SIGKILL_TIMEOUT_MS = 200;
+  /**
+   * Kill a process tree (process group on Unix, taskkill on Windows)
+   */
+  async killProcessTree(pid, child) {
+    if (process.platform === "win32") {
+      await new Promise((resolve) => {
+        const killer = spawn("taskkill", ["/pid", String(pid), "/f", "/t"], {
+          stdio: "ignore"
+        });
+        killer.once("exit", () => resolve());
+        killer.once("error", () => resolve());
+      });
+    } else {
+      try {
+        process.kill(-pid, "SIGTERM");
+        await new Promise((res) => setTimeout(res, ProcessService.SIGKILL_TIMEOUT_MS));
+        if (child.exitCode === null) {
+          process.kill(-pid, "SIGKILL");
+        }
+      } catch {
+        child.kill("SIGTERM");
+        await new Promise((res) => setTimeout(res, ProcessService.SIGKILL_TIMEOUT_MS));
+        if (child.exitCode === null) {
+          child.kill("SIGKILL");
+        }
+      }
+    }
+  }
+  /**
+   * Execute command in foreground with timeout and abort support
+   */
+  executeForeground(command, options) {
+    return new Promise((resolve, reject) => {
+      const startTime = Date.now();
+      let stdout = "";
+      let stderr = "";
+      let stdoutBytes = 0;
+      let stderrBytes = 0;
+      let outputTruncated = false;
+      let killed = false;
+      let aborted = false;
+      let closed = false;
+      const maxBuffer = this.config.maxOutputBuffer;
+      if (options.abortSignal?.aborted) {
+        this.logger.debug(`Command cancelled before execution: ${command}`);
+        resolve({
+          stdout: "",
+          stderr: "(Command was cancelled)",
+          exitCode: 130,
+          // Standard exit code for SIGINT
+          duration: 0
+        });
+        return;
+      }
+      this.logger.debug(`Executing command: ${command}`);
+      const child = spawn(command, {
+        cwd: options.cwd,
+        env: options.env,
+        shell: true,
+        detached: process.platform !== "win32"
+        // Create process group on Unix
+      });
+      const timeoutHandle = setTimeout(() => {
+        killed = true;
+        if (child.pid) {
+          void this.killProcessTree(child.pid, child);
+        } else {
+          child.kill("SIGTERM");
+        }
+      }, options.timeout);
+      const abortHandler = () => {
+        if (closed) return;
+        aborted = true;
+        this.logger.debug(`Command cancelled by user: ${command}`);
+        clearTimeout(timeoutHandle);
+        if (child.pid) {
+          void this.killProcessTree(child.pid, child);
+        } else {
+          child.kill("SIGTERM");
+        }
+      };
+      options.abortSignal?.addEventListener("abort", abortHandler, { once: true });
+      child.stdout?.on("data", (data) => {
+        if (outputTruncated) return;
+        const chunk = data.toString();
+        const chunkBytes = Buffer.byteLength(chunk, "utf8");
+        if (stdoutBytes + stderrBytes + chunkBytes <= maxBuffer) {
+          stdout += chunk;
+          stdoutBytes += chunkBytes;
+        } else {
+          const remaining = maxBuffer - stdoutBytes - stderrBytes;
+          if (remaining > 0) {
+            stdout += chunk.slice(0, remaining);
+            stdoutBytes += remaining;
+          }
+          stdout += "\n...[truncated]";
+          outputTruncated = true;
+          this.logger.warn(`Output buffer full for command: ${command}`);
+        }
+      });
+      child.stderr?.on("data", (data) => {
+        if (outputTruncated) return;
+        const chunk = data.toString();
+        const chunkBytes = Buffer.byteLength(chunk, "utf8");
+        if (stdoutBytes + stderrBytes + chunkBytes <= maxBuffer) {
+          stderr += chunk;
+          stderrBytes += chunkBytes;
+        } else {
+          const remaining = maxBuffer - stdoutBytes - stderrBytes;
+          if (remaining > 0) {
+            stderr += chunk.slice(0, remaining);
+            stderrBytes += remaining;
+          }
+          stderr += "\n...[truncated]";
+          outputTruncated = true;
+          this.logger.warn(`Output buffer full for command: ${command}`);
+        }
+      });
+      child.on("close", (code, signal) => {
+        closed = true;
+        clearTimeout(timeoutHandle);
+        options.abortSignal?.removeEventListener("abort", abortHandler);
+        const duration = Date.now() - startTime;
+        if (aborted) {
+          stdout += "\n\n(Command was cancelled)";
+          this.logger.debug(`Command cancelled after ${duration}ms: ${command}`);
+          resolve({
+            stdout,
+            stderr,
+            exitCode: 130,
+            // Standard exit code for SIGINT
+            duration
+          });
+          return;
+        }
+        if (killed) {
+          reject(ProcessError.timeout(command, options.timeout));
+          return;
+        }
+        let exitCode = typeof code === "number" ? code : 1;
+        if (code === null) {
+          stderr += `
+Process terminated by signal ${signal ?? "UNKNOWN"}`;
+        }
+        this.logger.debug(
+          `Command completed with exit code ${exitCode} in ${duration}ms: ${command}`
+        );
+        resolve({
+          stdout,
+          stderr,
+          exitCode,
+          duration
+        });
+      });
+      child.on("error", (error) => {
+        clearTimeout(timeoutHandle);
+        options.abortSignal?.removeEventListener("abort", abortHandler);
+        if (error.code === "ENOENT") {
+          reject(ProcessError.commandNotFound(command));
+        } else if (error.code === "EACCES") {
+          reject(ProcessError.permissionDenied(command));
+        } else {
+          reject(ProcessError.executionFailed(command, error.message));
+        }
+      });
+    });
+  }
+  /**
+   * Execute command in background
+   */
+  async executeInBackground(command, options) {
+    const runningCount = Array.from(this.backgroundProcesses.values()).filter(
+      (p) => p.status === "running"
+    ).length;
+    if (runningCount >= this.config.maxConcurrentProcesses) {
+      throw ProcessError.tooManyProcesses(runningCount, this.config.maxConcurrentProcesses);
+    }
+    const processId = crypto.randomBytes(4).toString("hex");
+    const cwd = this.resolveSafeCwd(options.cwd);
+    const env = {};
+    for (const [key, value] of Object.entries({
+      ...process.env,
+      ...this.config.environment,
+      ...options.env
+    })) {
+      if (value !== void 0) {
+        env[key] = value;
+      }
+    }
+    this.logger.debug(`Starting background process ${processId}: ${command}`);
+    const child = spawn(command, {
+      cwd,
+      env,
+      shell: true,
+      detached: false
+    });
+    const outputBuffer = {
+      stdout: [],
+      stderr: [],
+      complete: false,
+      lastRead: Date.now(),
+      bytesUsed: 0,
+      truncated: false
+    };
+    const bgProcess = {
+      processId,
+      command,
+      child,
+      startedAt: /* @__PURE__ */ new Date(),
+      status: "running",
+      outputBuffer,
+      description: options.description
+    };
+    this.backgroundProcesses.set(processId, bgProcess);
+    const bgTimeout = Math.max(
+      1,
+      Math.min(options.timeout || DEFAULT_TIMEOUT, this.config.maxTimeout)
+    );
+    let killEscalationTimer = null;
+    const killTimer = setTimeout(() => {
+      if (bgProcess.status === "running") {
+        this.logger.warn(
+          `Background process ${processId} timed out after ${bgTimeout}ms, sending SIGTERM`
+        );
+        child.kill("SIGTERM");
+        killEscalationTimer = setTimeout(() => {
+          if (bgProcess.status === "running") {
+            this.logger.warn(
+              `Background process ${processId} did not respond to SIGTERM, sending SIGKILL`
+            );
+            child.kill("SIGKILL");
+          }
+        }, 5e3);
+      }
+    }, bgTimeout);
+    child.stdout?.on("data", (data) => {
+      const chunk = data.toString();
+      const chunkBytes = Buffer.byteLength(chunk, "utf8");
+      if (outputBuffer.bytesUsed + chunkBytes <= this.config.maxOutputBuffer) {
+        outputBuffer.stdout.push(chunk);
+        outputBuffer.bytesUsed += chunkBytes;
+      } else {
+        if (!outputBuffer.truncated) {
+          outputBuffer.truncated = true;
+          this.logger.warn(`Output buffer full for process ${processId}`);
+        }
+      }
+    });
+    child.stderr?.on("data", (data) => {
+      const chunk = data.toString();
+      const chunkBytes = Buffer.byteLength(chunk, "utf8");
+      if (outputBuffer.bytesUsed + chunkBytes <= this.config.maxOutputBuffer) {
+        outputBuffer.stderr.push(chunk);
+        outputBuffer.bytesUsed += chunkBytes;
+      } else {
+        if (!outputBuffer.truncated) {
+          outputBuffer.truncated = true;
+          this.logger.warn(`Error buffer full for process ${processId}`);
+        }
+      }
+    });
+    child.on("close", (code) => {
+      clearTimeout(killTimer);
+      if (killEscalationTimer) clearTimeout(killEscalationTimer);
+      bgProcess.status = code === 0 ? "completed" : "failed";
+      bgProcess.exitCode = code ?? void 0;
+      bgProcess.completedAt = /* @__PURE__ */ new Date();
+      bgProcess.outputBuffer.complete = true;
+      this.logger.debug(`Background process ${processId} completed with exit code ${code}`);
+    });
+    child.on("error", (error) => {
+      clearTimeout(killTimer);
+      if (killEscalationTimer) clearTimeout(killEscalationTimer);
+      bgProcess.status = "failed";
+      bgProcess.completedAt = /* @__PURE__ */ new Date();
+      bgProcess.outputBuffer.complete = true;
+      const chunk = `Error: ${error.message}`;
+      const chunkBytes = Buffer.byteLength(chunk, "utf8");
+      if (bgProcess.outputBuffer.bytesUsed + chunkBytes <= this.config.maxOutputBuffer) {
+        bgProcess.outputBuffer.stderr.push(chunk);
+        bgProcess.outputBuffer.bytesUsed += chunkBytes;
+      } else {
+        if (!bgProcess.outputBuffer.truncated) {
+          bgProcess.outputBuffer.truncated = true;
+          this.logger.warn(`Error buffer full for process ${processId}`);
+        }
+      }
+      this.logger.error(`Background process ${processId} failed: ${error.message}`);
+    });
+    return {
+      processId,
+      command,
+      pid: child.pid,
+      startedAt: bgProcess.startedAt,
+      description: options.description
+    };
+  }
+  /**
+   * Get output from a background process
+   */
+  async getProcessOutput(processId) {
+    await this.ensureInitialized();
+    const bgProcess = this.backgroundProcesses.get(processId);
+    if (!bgProcess) {
+      throw ProcessError.processNotFound(processId);
+    }
+    const stdout = bgProcess.outputBuffer.stdout.join("");
+    const stderr = bgProcess.outputBuffer.stderr.join("");
+    bgProcess.outputBuffer.stdout = [];
+    bgProcess.outputBuffer.stderr = [];
+    bgProcess.outputBuffer.lastRead = Date.now();
+    bgProcess.outputBuffer.bytesUsed = 0;
+    return {
+      stdout,
+      stderr,
+      status: bgProcess.status,
+      exitCode: bgProcess.exitCode,
+      duration: bgProcess.completedAt ? bgProcess.completedAt.getTime() - bgProcess.startedAt.getTime() : void 0
+    };
+  }
+  /**
+   * Kill a background process
+   */
+  async killProcess(processId) {
+    await this.ensureInitialized();
+    const bgProcess = this.backgroundProcesses.get(processId);
+    if (!bgProcess) {
+      throw ProcessError.processNotFound(processId);
+    }
+    if (bgProcess.status !== "running") {
+      this.logger.debug(`Process ${processId} is not running (status: ${bgProcess.status})`);
+      return;
+    }
+    try {
+      bgProcess.child.kill("SIGTERM");
+      setTimeout(() => {
+        if (bgProcess.child.exitCode === null) {
+          bgProcess.child.kill("SIGKILL");
+        }
+      }, 5e3);
+      this.logger.debug(`Process ${processId} sent SIGTERM`);
+    } catch (error) {
+      throw ProcessError.killFailed(
+        processId,
+        error instanceof Error ? error.message : String(error)
+      );
+    }
+  }
+  /**
+   * List all background processes
+   */
+  async listProcesses() {
+    await this.ensureInitialized();
+    return Array.from(this.backgroundProcesses.values()).map((bgProcess) => ({
+      processId: bgProcess.processId,
+      command: bgProcess.command,
+      pid: bgProcess.child.pid,
+      status: bgProcess.status,
+      startedAt: bgProcess.startedAt,
+      completedAt: bgProcess.completedAt,
+      exitCode: bgProcess.exitCode,
+      description: bgProcess.description
+    }));
+  }
+  /**
+   * Get buffer size in bytes
+   */
+  getBufferSize(buffer) {
+    const stdoutSize = buffer.stdout.reduce((sum, line) => sum + line.length, 0);
+    const stderrSize = buffer.stderr.reduce((sum, line) => sum + line.length, 0);
+    return stdoutSize + stderrSize;
+  }
+  /**
+   * Get service configuration
+   */
+  getConfig() {
+    return { ...this.config };
+  }
+  /**
+   * Resolve and confine cwd to the configured working directory
+   */
+  resolveSafeCwd(cwd) {
+    const baseDir = this.config.workingDirectory || process.cwd();
+    if (!cwd) return baseDir;
+    const candidate = path.isAbsolute(cwd) ? path.resolve(cwd) : path.resolve(baseDir, cwd);
+    const rel = path.relative(baseDir, candidate);
+    const outside = rel.startsWith("..") || path.isAbsolute(rel);
+    if (outside) {
+      throw ProcessError.invalidWorkingDirectory(
+        cwd,
+        `Working directory must be within ${baseDir}`
+      );
+    }
+    return candidate;
+  }
+  /**
+   * Cleanup completed processes
+   */
+  async cleanup() {
+    const now = Date.now();
+    const CLEANUP_AGE = 36e5;
+    for (const [processId, bgProcess] of this.backgroundProcesses.entries()) {
+      if (bgProcess.status !== "running" && bgProcess.completedAt) {
+        const age = now - bgProcess.completedAt.getTime();
+        if (age > CLEANUP_AGE) {
+          this.backgroundProcesses.delete(processId);
+          this.logger.debug(`Cleaned up old process ${processId}`);
+        }
+      }
+    }
+  }
+}
+export {
+  ProcessService
+};