fullnative 0.1.0

package/dist/core/process/Command.js

@@ -0,0 +1,143 @@
+import { spawn } from "node:child_process";
+import { LiveProcess } from "./LiveProcess.js";
+/**
+ * Builder inmutable para construir un comando antes de ejecutarlo.
+ * Permite configurar opciones de forma fluida y luego ejecutar.
+ */
+export class Command {
+    _command;
+    _args;
+    _options;
+    /**
+     * Crea un nuevo `Command`.
+     *
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando (por defecto, vacío).
+     * @param options - Opciones de ejecución (por defecto, vacío).
+     */
+    constructor(command, args = [], options = {}) {
+        this._command = command;
+        this._args = args;
+        this._options = options;
+    }
+    /** Comando a ejecutar. */
+    get command() {
+        return this._command;
+    }
+    /** Argumentos del comando. */
+    get args() {
+        return this._args;
+    }
+    /**
+     * Crea una nueva instancia de `Command` con argumentos adicionales
+     * añadidos a los existentes.
+     *
+     * @param args - Argumentos a añadir.
+     * @returns Un nuevo `Command` inmutable con los argumentos combinados.
+     */
+    withArgs(...args) {
+        return new Command(this._command, [...this._args, ...args], this._options);
+    }
+    /**
+     * Crea una nueva instancia de `Command` cambiando el directorio de trabajo.
+     *
+     * @param cwd - Ruta del directorio de trabajo.
+     * @returns Un nuevo `Command` inmutable con el `cwd` actualizado.
+     */
+    in(cwd) {
+        return new Command(this._command, this._args, { ...this._options, cwd });
+    }
+    /**
+     * Crea una nueva instancia de `Command` con variables de entorno adicionales,
+     * fusionadas con las existentes (o con `process.env` si no se habían definido).
+     *
+     * @param env - Variables de entorno a añadir o sobrescribir.
+     * @returns Un nuevo `Command` inmutable con el entorno actualizado.
+     */
+    withEnv(env) {
+        const baseEnv = this._options.env ?? process.env;
+        return new Command(this._command, this._args, {
+            ...this._options,
+            env: { ...baseEnv, ...env },
+        });
+    }
+    /**
+     * Crea una nueva instancia de `Command` con un timeout en milisegundos.
+     * Al expirar, el proceso se matará con `SIGTERM`.
+     *
+     * @param ms - Tiempo máximo de ejecución en milisegundos.
+     * @returns Un nuevo `Command` inmutable con el timeout configurado.
+     */
+    withTimeout(ms) {
+        return new Command(this._command, this._args, { ...this._options, timeout: ms });
+    }
+    /**
+     * Crea una nueva instancia de `Command` que envía datos por stdin al iniciar.
+     *
+     * @param data - Datos a enviar por stdin (texto o buffer).
+     * @returns Un nuevo `Command` inmutable con la entrada configurada.
+     */
+    withInput(data) {
+        return new Command(this._command, this._args, { ...this._options, input: data });
+    }
+    /**
+     * Crea una nueva instancia de `Command` que lanza un `ProcessError` si el
+     * proceso termina con código de salida distinto de 0. Esto hace que
+     * `run()` rechace la promesa en lugar de devolver un `Result` fallido.
+     *
+     * @returns Un nuevo `Command` inmutable con `rejectOnNonZero` activado.
+     */
+    throwOnError() {
+        return new Command(this._command, this._args, {
+            ...this._options,
+            rejectOnNonZero: true,
+        });
+    }
+    /**
+     * Inicia el comando y devuelve un `LiveProcess` para interactuar en vivo
+     * con stdin/stdout/stderr.
+     *
+     * @returns Un `LiveProcess` que envuelve el proceso hijo recién iniciado.
+     */
+    spawn() {
+        const { timeout, input, rejectOnNonZero, ...spawnOpts } = this._options;
+        const child = spawn(this._command, [...this._args], spawnOpts);
+        const handle = new LiveProcess(this._command, this._args, child);
+        if (input !== undefined && child.stdin) {
+            child.stdin.write(input);
+            child.stdin.end();
+        }
+        if (timeout) {
+            setTimeout(() => {
+                if (handle.running)
+                    handle.kill("SIGTERM");
+            }, timeout).unref();
+        }
+        return handle;
+    }
+    /**
+     * Ejecuta el comando, espera a que termine y devuelve el resultado.
+     * Si se configuró `throwOnError`, rechaza con `ProcessError` si el código
+     * de salida no es 0.
+     *
+     * @returns El `Result` de la ejecución.
+     * @throws {ProcessError} Si `rejectOnNonZero` está activo y el código de salida no es 0.
+     */
+    async run() {
+        const handle = this.spawn();
+        const result = await handle.wait();
+        if (this._options.rejectOnNonZero)
+            result.throwIfFailed();
+        return result;
+    }
+    /**
+     * Ejecuta el comando y devuelve solo stdout, con espacios en blanco
+     * eliminados de los extremos (trim).
+     *
+     * @returns El stdout del comando ya trimado.
+     */
+    async output() {
+        return (await this.run()).stdout.trim();
+    }
+}
+//# sourceMappingURL=Command.js.map

package/dist/core/process/Command.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Command.js","sourceRoot":"","sources":["../../../src/core/process/Command.ts"],"names":[],"mappings":"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"}

package/dist/core/process/LiveProcess.d.ts

@@ -0,0 +1,134 @@
+import { type ChildProcess } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import { Result } from "./Result.js";
+/**
+ * Representa un proceso en ejecución (o ya finalizado).
+ * Permite interactuar con su stdin/stdout/stderr en vivo.
+ */
+export declare class LiveProcess {
+    /** Proceso hijo nativo de `child_process`. */
+    readonly child: ChildProcess;
+    /** Comando ejecutado. */
+    readonly command: string;
+    /** Argumentos pasados al comando. */
+    readonly args: readonly string[];
+    /** Fecha de inicio de la ejecución. */
+    readonly startedAt: Date;
+    private readonly _stdoutChunks;
+    private readonly _stderrChunks;
+    private _exitCode;
+    private _signal;
+    private _ended;
+    private _killed;
+    /**
+     * Promesa que se resuelve con un `Result` cuando el proceso termina,
+     * o se rechaza con un `ProcessError` si el proceso no pudo iniciarse.
+     */
+    readonly onExitPromise: Promise<Result>;
+    /**
+     * Crea un `LiveProcess` a partir de un `ChildProcess` ya iniciado.
+     *
+     * No se debe usar directamente; usar `Command.spawn()` o `Process.spawn()`.
+     *
+     * @param command - Comando ejecutado.
+     * @param args - Argumentos pasados al comando.
+     * @param child - Proceso hijo nativo de `child_process`.
+     */
+    constructor(command: string, args: readonly string[], child: ChildProcess);
+    /** Identificador del proceso asignado por el sistema operativo, o `undefined` si no se inició. */
+    get pid(): number | undefined;
+    /** `true` mientras el proceso sigue en ejecución. */
+    get running(): boolean;
+    /** `true` si el proceso ya terminó (naturalmente o por señal). */
+    get ended(): boolean;
+    /** Código de salida del proceso, o `null` si aún no termina o fue terminado por señal. */
+    get exitCode(): number | null;
+    /** Señal que terminó el proceso, o `null` si no fue por señal. */
+    get signal(): NodeJS.Signals | null;
+    /**
+     * `true` si el proceso fue matado explícitamente vía `kill()` o `forceKill()`.
+     *
+     * Se distingue de una terminación natural: este valor solo se vuelve
+     * `true` cuando el usuario llamó manualmente a un método de terminación.
+     */
+    get stopped(): boolean;
+    /** Milisegundos transcurridos desde el inicio del proceso hasta ahora (en vivo). */
+    get elapsed(): number;
+    /** Stream legible de stdout del proceso, o `null` si no está disponible. */
+    get stdout(): Readable | null;
+    /** Stream legible de stderr del proceso, o `null` si no está disponible. */
+    get stderr(): Readable | null;
+    /** Stream escribible de stdin del proceso, o `null` si no está disponible. */
+    get stdin(): Writable | null;
+    /**
+     * Stream legible que combina los chunks de stdout y stderr ya capturados
+     * en orden: primero todos los de stdout, luego los de stderr.
+     */
+    get combinedOutput(): Readable;
+    /**
+     * Escribe datos en stdin del proceso.
+     *
+     * @param data - Texto o buffer a escribir.
+     * @returns `true` si la escritura fue exitosa, `false` si no hay stdin disponible.
+     */
+    write(data: string | Buffer): boolean;
+    /**
+     * Envía una línea a stdin del proceso, añadiendo un salto de línea al final.
+     *
+     * @param line - Línea de texto a enviar.
+     * @returns `true` si la escritura fue exitosa, `false` si no hay stdin disponible.
+     */
+    sendLine(line: string): boolean;
+    /** Cierra stdin del proceso señalizando fin de entrada (EOF). */
+    endInput(): void;
+    /**
+     * Espera a que el proceso termine y devuelve el resultado.
+     *
+     * @returns El `Result` de la ejecución cuando el proceso termina.
+     * @throws {ProcessError} Si el proceso no pudo iniciarse (fallo de spawn).
+     */
+    wait(): Promise<Result>;
+    /**
+     * Envía una señal al proceso para terminarlo.
+     *
+     * @param signal - Señal a enviar (por defecto `SIGTERM`).
+     * @returns `true` si la señal se envió correctamente.
+     */
+    kill(signal?: NodeJS.Signals): boolean;
+    /**
+     * Fuerza la terminación inmediata del proceso enviando `SIGKILL`.
+     *
+     * @returns `true` si la señal se envió correctamente.
+     */
+    forceKill(): boolean;
+    /**
+     * Registra un callback que se ejecuta cuando el proceso termina.
+     *
+     * @param callback - Función que recibe el `Result` al finalizar.
+     * @returns `this` para encadenamiento.
+     */
+    onExit(callback: (result: Result) => void): this;
+    /**
+     * Registra un callback que se ejecuta por cada chunk de datos de stdout.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stdout.
+     * @returns `this` para encadenamiento.
+     */
+    onStdout(callback: (chunk: Buffer) => void): this;
+    /**
+     * Registra un callback que se ejecuta por cada chunk de datos de stderr.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stderr.
+     * @returns `this` para encadenamiento.
+     */
+    onStderr(callback: (chunk: Buffer) => void): this;
+    /**
+     * Registra un callback unificado que se ejecuta por cada chunk de stdout
+     * **o** stderr, sin distinguir el origen.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stdout o stderr.
+     * @returns `this` para encadenamiento.
+     */
+    onOutput(callback: (chunk: Buffer) => void): this;
+}
+//# sourceMappingURL=LiveProcess.d.ts.map

package/dist/core/process/LiveProcess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveProcess.d.ts","sourceRoot":"","sources":["../../../src/core/process/LiveProcess.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,oBAAoB,CAAC;AACvD,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAGrC;;;GAGG;AACH,qBAAa,WAAW;IACtB,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAC;IAC7B,yBAAyB;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,qCAAqC;IACrC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAgB;IAC9C,OAAO,CAAC,SAAS,CAAuB;IACxC,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IAExC;;;;;;;;OAQG;gBACS,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,KAAK,EAAE,YAAY;IAwCzE,kGAAkG;IAClG,IAAI,GAAG,IAAI,MAAM,GAAG,SAAS,CAE5B;IAED,qDAAqD;IACrD,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,kEAAkE;IAClE,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,0FAA0F;IAC1F,IAAI,QAAQ,IAAI,MAAM,GAAG,IAAI,CAE5B;IAED,kEAAkE;IAClE,IAAI,MAAM,IAAI,MAAM,CAAC,OAAO,GAAG,IAAI,CAElC;IAED;;;;;OAKG;IACH,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,oFAAoF;IACpF,IAAI,OAAO,IAAI,MAAM,CAEpB;IAED,4EAA4E;IAC5E,IAAI,MAAM,IAAI,QAAQ,GAAG,IAAI,CAE5B;IAED,4EAA4E;IAC5E,IAAI,MAAM,IAAI,QAAQ,GAAG,IAAI,CAE5B;IAED,8EAA8E;IAC9E,IAAI,KAAK,IAAI,QAAQ,GAAG,IAAI,CAE3B;IAED;;;OAGG;IACH,IAAI,cAAc,IAAI,QAAQ,CAO7B;IAED;;;;;OAKG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO;IAKrC;;;;;OAKG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI/B,iEAAiE;IACjE,QAAQ,IAAI,IAAI;IAIhB;;;;;OAKG;IACG,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC;IAI7B;;;;;OAKG;IACH,IAAI,CAAC,MAAM,GAAE,MAAM,CAAC,OAAmB,GAAG,OAAO;IAKjD;;;;OAIG;IACH,SAAS,IAAI,OAAO;IAKpB;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAKhD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAKjD;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;IAKjD;;;;;;OAMG;IACH,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,GAAG,IAAI;CAKlD"}

package/dist/core/process/LiveProcess.js

@@ -0,0 +1,214 @@
+import { Readable } from "node:stream";
+import { Result } from "./Result.js";
+import { ProcessError } from "./ProcessError.js";
+/**
+ * Representa un proceso en ejecución (o ya finalizado).
+ * Permite interactuar con su stdin/stdout/stderr en vivo.
+ */
+export class LiveProcess {
+    /** Proceso hijo nativo de `child_process`. */
+    child;
+    /** Comando ejecutado. */
+    command;
+    /** Argumentos pasados al comando. */
+    args;
+    /** Fecha de inicio de la ejecución. */
+    startedAt;
+    _stdoutChunks = [];
+    _stderrChunks = [];
+    _exitCode = null;
+    _signal = null;
+    _ended = false;
+    _killed = false;
+    /**
+     * Promesa que se resuelve con un `Result` cuando el proceso termina,
+     * o se rechaza con un `ProcessError` si el proceso no pudo iniciarse.
+     */
+    onExitPromise;
+    /**
+     * Crea un `LiveProcess` a partir de un `ChildProcess` ya iniciado.
+     *
+     * No se debe usar directamente; usar `Command.spawn()` o `Process.spawn()`.
+     *
+     * @param command - Comando ejecutado.
+     * @param args - Argumentos pasados al comando.
+     * @param child - Proceso hijo nativo de `child_process`.
+     */
+    constructor(command, args, child) {
+        this.command = command;
+        this.args = args;
+        this.child = child;
+        this.startedAt = new Date();
+        if (child.stdout) {
+            child.stdout.on("data", (chunk) => this._stdoutChunks.push(chunk));
+        }
+        if (child.stderr) {
+            child.stderr.on("data", (chunk) => this._stderrChunks.push(chunk));
+        }
+        this.onExitPromise = new Promise((resolve, reject) => {
+            child.on("error", (err) => {
+                this._ended = true;
+                reject(new ProcessError(this.command, this.args, "spawn", { cause: err }));
+            });
+            child.on("exit", (code, signal) => {
+                this._exitCode = code;
+                this._signal = signal;
+                this._ended = true;
+                const durationMs = Date.now() - this.startedAt.getTime();
+                resolve(new Result(this.command, this.args, Buffer.concat(this._stdoutChunks).toString("utf8"), Buffer.concat(this._stderrChunks).toString("utf8"), code, signal, durationMs));
+            });
+        });
+    }
+    /** Identificador del proceso asignado por el sistema operativo, o `undefined` si no se inició. */
+    get pid() {
+        return this.child.pid;
+    }
+    /** `true` mientras el proceso sigue en ejecución. */
+    get running() {
+        return !this._ended;
+    }
+    /** `true` si el proceso ya terminó (naturalmente o por señal). */
+    get ended() {
+        return this._ended;
+    }
+    /** Código de salida del proceso, o `null` si aún no termina o fue terminado por señal. */
+    get exitCode() {
+        return this._exitCode;
+    }
+    /** Señal que terminó el proceso, o `null` si no fue por señal. */
+    get signal() {
+        return this._signal;
+    }
+    /**
+     * `true` si el proceso fue matado explícitamente vía `kill()` o `forceKill()`.
+     *
+     * Se distingue de una terminación natural: este valor solo se vuelve
+     * `true` cuando el usuario llamó manualmente a un método de terminación.
+     */
+    get stopped() {
+        return this._killed;
+    }
+    /** Milisegundos transcurridos desde el inicio del proceso hasta ahora (en vivo). */
+    get elapsed() {
+        return Date.now() - this.startedAt.getTime();
+    }
+    /** Stream legible de stdout del proceso, o `null` si no está disponible. */
+    get stdout() {
+        return this.child.stdout;
+    }
+    /** Stream legible de stderr del proceso, o `null` si no está disponible. */
+    get stderr() {
+        return this.child.stderr;
+    }
+    /** Stream escribible de stdin del proceso, o `null` si no está disponible. */
+    get stdin() {
+        return this.child.stdin;
+    }
+    /**
+     * Stream legible que combina los chunks de stdout y stderr ya capturados
+     * en orden: primero todos los de stdout, luego los de stderr.
+     */
+    get combinedOutput() {
+        return Readable.from((async function* (self) {
+            for (const chunk of self._stdoutChunks)
+                yield chunk;
+            for (const chunk of self._stderrChunks)
+                yield chunk;
+        })(this));
+    }
+    /**
+     * Escribe datos en stdin del proceso.
+     *
+     * @param data - Texto o buffer a escribir.
+     * @returns `true` si la escritura fue exitosa, `false` si no hay stdin disponible.
+     */
+    write(data) {
+        if (!this.child.stdin)
+            return false;
+        return this.child.stdin.write(data);
+    }
+    /**
+     * Envía una línea a stdin del proceso, añadiendo un salto de línea al final.
+     *
+     * @param line - Línea de texto a enviar.
+     * @returns `true` si la escritura fue exitosa, `false` si no hay stdin disponible.
+     */
+    sendLine(line) {
+        return this.write(line + "\n");
+    }
+    /** Cierra stdin del proceso señalizando fin de entrada (EOF). */
+    endInput() {
+        this.child.stdin?.end();
+    }
+    /**
+     * Espera a que el proceso termine y devuelve el resultado.
+     *
+     * @returns El `Result` de la ejecución cuando el proceso termina.
+     * @throws {ProcessError} Si el proceso no pudo iniciarse (fallo de spawn).
+     */
+    async wait() {
+        return this.onExitPromise;
+    }
+    /**
+     * Envía una señal al proceso para terminarlo.
+     *
+     * @param signal - Señal a enviar (por defecto `SIGTERM`).
+     * @returns `true` si la señal se envió correctamente.
+     */
+    kill(signal = "SIGTERM") {
+        this._killed = true;
+        return this.child.kill(signal);
+    }
+    /**
+     * Fuerza la terminación inmediata del proceso enviando `SIGKILL`.
+     *
+     * @returns `true` si la señal se envió correctamente.
+     */
+    forceKill() {
+        this._killed = true;
+        return this.child.kill("SIGKILL");
+    }
+    /**
+     * Registra un callback que se ejecuta cuando el proceso termina.
+     *
+     * @param callback - Función que recibe el `Result` al finalizar.
+     * @returns `this` para encadenamiento.
+     */
+    onExit(callback) {
+        this.onExitPromise.then(callback);
+        return this;
+    }
+    /**
+     * Registra un callback que se ejecuta por cada chunk de datos de stdout.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stdout.
+     * @returns `this` para encadenamiento.
+     */
+    onStdout(callback) {
+        this.child.stdout?.on("data", callback);
+        return this;
+    }
+    /**
+     * Registra un callback que se ejecuta por cada chunk de datos de stderr.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stderr.
+     * @returns `this` para encadenamiento.
+     */
+    onStderr(callback) {
+        this.child.stderr?.on("data", callback);
+        return this;
+    }
+    /**
+     * Registra un callback unificado que se ejecuta por cada chunk de stdout
+     * **o** stderr, sin distinguir el origen.
+     *
+     * @param callback - Función que recibe cada `Buffer` de stdout o stderr.
+     * @returns `this` para encadenamiento.
+     */
+    onOutput(callback) {
+        this.child.stdout?.on("data", callback);
+        this.child.stderr?.on("data", callback);
+        return this;
+    }
+}
+//# sourceMappingURL=LiveProcess.js.map

package/dist/core/process/LiveProcess.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"LiveProcess.js","sourceRoot":"","sources":["../../../src/core/process/LiveProcess.ts"],"names":[],"mappings":"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"}

package/dist/core/process/Process.d.ts

@@ -0,0 +1,108 @@
+import { Command } from "./Command.js";
+import { LiveProcess } from "./LiveProcess.js";
+import { Result } from "./Result.js";
+import type { ProcessOptions } from "./types.js";
+/**
+ * Facade para ejecutar y manejar procesos nativos con una API cómoda.
+ *
+ * @example
+ * const proc = new Process();
+ *
+ * // Ejecución simple
+ * const result = await proc.run("echo", "hola");
+ * console.log(result.stdout); // "hola\n"
+ *
+ * // Builder fluido
+ * const out = await proc.cmd("git")
+ *   .withArgs("log", "--oneline")
+ *   .in("/my/repo")
+ *   .output();
+ *
+ * // Proceso interactivo
+ * const p = proc.spawn("node", "-i");
+ * p.sendLine("1 + 1");
+ * p.endInput();
+ * await p.wait();
+ */
+export declare class Process {
+    /**
+     * Crea un builder de comando (`Command`) sin ejecutarlo.
+     *
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando.
+     * @returns Un nuevo `Command` listo para configurar y ejecutar.
+     */
+    cmd(command: string, ...args: string[]): Command;
+    /**
+     * Ejecuta un comando, espera a que termine y devuelve el resultado.
+     *
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando.
+     * @returns El `Result` de la ejecución.
+     */
+    run(command: string, ...args: string[]): Promise<Result>;
+    /**
+     * Ejecuta un comando y devuelve solo stdout, con espacios en blanco
+     * eliminados de los extremos (trim).
+     *
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando.
+     * @returns El stdout del comando ya trimado.
+     */
+    output(command: string, ...args: string[]): Promise<string>;
+    /**
+     * Ejecuta un script de shell interpretado por el shell del sistema
+     * (`/bin/sh` en Unix, `cmd.exe` en Windows) y espera a que termine.
+     *
+     * @param script - Script de shell a ejecutar.
+     * @param options - Opciones de ejecución del proceso.
+     * @returns El `Result` de la ejecución.
+     */
+    shell(script: string, options?: Omit<ProcessOptions, never>): Promise<Result>;
+    /**
+     * Inicia un proceso y devuelve un `LiveProcess` para interactuar en vivo.
+     *
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando.
+     * @returns Un `LiveProcess` que envuelve el proceso hijo recién iniciado.
+     */
+    spawn(command: string, ...args: string[]): LiveProcess;
+    /**
+     * Inicia un proceso con opciones de ejecución y devuelve un `LiveProcess`.
+     * La firma es *options-first*: las opciones se pasan antes que el comando.
+     *
+     * @param options - Opciones de ejecución del proceso.
+     * @param command - Comando a ejecutar.
+     * @param args - Argumentos del comando.
+     * @returns Un `LiveProcess` que envuelve el proceso hijo recién iniciado.
+     */
+    spawnWith(options: ProcessOptions, command: string, ...args: string[]): LiveProcess;
+    /**
+     * Ejecuta un script de shell interpretado por el shell del sistema
+     * (`/bin/sh` en Unix, `cmd.exe` en Windows) y devuelve un `LiveProcess`
+     * interactivo para comunicarse en vivo con el proceso.
+     *
+     * @param script - Script de shell a ejecutar.
+     * @param options - Opciones de ejecución del proceso.
+     * @returns Un `LiveProcess` que envuelve el proceso hijo recién iniciado.
+     */
+    spawnScript(script: string, options?: ProcessOptions): LiveProcess;
+    /**
+     * Comprueba si un comando existe en el PATH del sistema.
+     * Usa `where` en Windows y `which` en Unix.
+     *
+     * @param command - Nombre del comando a buscar.
+     * @returns `true` si el comando existe y es ejecutable, `false` en caso contrario.
+     */
+    exists(command: string): Promise<boolean>;
+    /**
+     * Devuelve la ruta completa del comando encontrado en el PATH, o `null`
+     * si no existe. Usa `where` en Windows y `which` en Unix; si hay múltiples
+     * resultados, devuelve el primero.
+     *
+     * @param command - Nombre del comando a buscar.
+     * @returns La ruta completa del comando, o `null` si no se encuentra.
+     */
+    which(command: string): Promise<string | null>;
+}
+//# sourceMappingURL=Process.d.ts.map

package/dist/core/process/Process.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Process.d.ts","sourceRoot":"","sources":["../../../src/core/process/Process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,qBAAa,OAAO;IAClB;;;;;;OAMG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO;IAIhD;;;;;;OAMG;IACG,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAI9D;;;;;;;OAOG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC;IAIjE;;;;;;;OAOG;IACG,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,IAAI,CAAC,cAAc,EAAE,KAAK,CAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAOvF;;;;;;OAMG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW;IAItD;;;;;;;;OAQG;IACH,SAAS,CAAC,OAAO,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW;IAInF;;;;;;;;OAQG;IACH,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,WAAW;IAOtE;;;;;;OAMG;IACG,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAO/C;;;;;;;OAOG;IACG,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;CAQrD"}