depflow 3.0.0-dev.10 → 3.0.0-dev.12

package/dist/task/Command.js

@@ -0,0 +1,404 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Runs one instruction, as a script in a shared shell or as its own process, streaming its
+ * output and settling exactly one verdict for it.
+ * @license Apache-2.0
+ */
+import { spawn } from "node:child_process";
+import { Events } from "@netfeez/common";
+export class Command extends Events {
+    /**
+     * Monotonic source of the markers written into the shell, so two commands executed in the same
+     * millisecond can never share one, and a marker can never be replayed by a later command.
+     */
+    static vToken = 0;
+    /**
+     * The shells already read by a command, so the reader of a shell shared by the instructions of a
+     * task is attached once instead of once per instruction.
+     */
+    static vShells = new WeakMap();
+    mode;
+    shell;
+    script;
+    program;
+    /** The sentinel the shell writes once the instruction finished, carrying its exit status. */
+    marker;
+    child = null;
+    settled = false;
+    startedAt = 0;
+    output = '';
+    errors = '';
+    outputCursor = 0;
+    errorsCursor = 0;
+    vOrdinal;
+    constructor(mode, options) {
+        super();
+        this.mode = mode;
+        this.shell = options.shell ?? null;
+        this.script = options.script ?? '';
+        this.program = options.program ?? { executable: '', args: [] };
+        this.marker = Command.token();
+        this.vOrdinal = options.ordinal ?? 1;
+    }
+    /**
+     * Creates a command that runs a script in an already running shell.
+     * @param shell - The shell the script is written to, or `null` when the shell of the task is gone.
+     * @param script - The shell script to run.
+     * @returns The command, not yet started.
+     *
+     * @remarks The shell is not owned by the command: it outlives it, so the death of a command is
+     * never the death of the shell, and a shell that dies is reported by the task that owns it. A
+     * command with no shell fails as soon as it runs, instead of waiting for output that can never
+     * come.
+     *
+     * @remarks The ordinal travels with every line the command emits, so the task never has to invent
+     * which of its instructions a line belongs to.
+     *
+     * @param ordinal - The position of the instruction inside its task, starting at 1.
+     */
+    static inShell(shell, script, ordinal = 1) {
+        return new Command('shell', { shell: shell ?? undefined, script, ordinal });
+    }
+    /**
+     * Creates a command that runs a program in a process of its own, where nothing in the arguments
+     * nor in the working directory can be reinterpreted by a shell.
+     * @param program - The program to run.
+     * @param ordinal - The position of the instruction inside its task, starting at 1.
+     * @returns The command, not yet started.
+     */
+    static asProgram(program, ordinal = 1) {
+        return new Command('program', { program, ordinal });
+    }
+    /**
+     * Creates a shell for running scripts, started in the given working directory.
+     * @param cwd - The working directory the shell is started in, so a script never needs to `cd` into
+     * the folder the task belongs to reach it.
+     * @returns The shell process.
+     *
+     * @remarks The shell leads its own process group where the platform allows it, so the task owning
+     * it can take down the whole tree of processes a script left behind. It holds the event loop while
+     * the task runs, and the task releases it when it is done, so a task in flight is never cut short.
+     *
+     * @remarks The arguments of the shell are its own, never a string to be interpreted: `cmd.exe` is
+     * started quiet (`/Q`) and without the autorun registry entries (`/D`), so it neither greets itself
+     * nor echoes the orders it is given. The greeting a shell still writes is dropped by
+     * {@link Command.prepare}.
+     */
+    static createShell(cwd) {
+        const isWin = process.platform === 'win32';
+        return spawn(isWin ? 'cmd.exe' : 'bash', isWin ? ['/Q', '/D'] : [], {
+            shell: false,
+            cwd,
+            detached: !isWin,
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+    }
+    /**
+     * Silences a shell and waits until it answers, so nothing the shell says about itself is ever read as
+     * the output of an instruction.
+     * @param shell - The shell to prepare, the one {@link Command.createShell} started.
+     * @returns A promise resolving once the shell reported itself ready, or once it is gone.
+     *
+     * @remarks A shell reading its orders from a pipe narrates them: `cmd.exe` writes its banner and its
+     * prompt to stdout before and after every order, and both belong to the shell, not to the
+     * instruction that follows. The prompt is reduced to a blank line, and everything the shell wrote
+     * before the first instruction took it over is dropped by {@link Command.reader}, so the first
+     * instruction starts from a shell that only speaks when spoken to. A shell that is already gone
+     * resolves too: the instruction is the one that reports it, not this handshake.
+     *
+     * The handshake ends on the readiness marker or on the death of the shell, never on the orders
+     * having been written: a write that succeeded says nothing about what the shell already said.
+     */
+    static prepare(shell) {
+        const state = Command.reader(shell);
+        if (state.ready)
+            return Promise.resolve();
+        const marker = Command.token();
+        return new Promise((resolve) => {
+            const onGone = () => {
+                if (state.ready)
+                    return;
+                shell.off('exit', onGone);
+                shell.off('error', onGone);
+                shell.stdin.off('error', onGone);
+                state.probe = null;
+                state.ready = true;
+                resolve();
+            };
+            const onWritten = (error) => { if (error)
+                onGone(); };
+            state.probe = (text) => { if (text.includes(`${marker}=1`))
+                onGone(); };
+            shell.once('exit', onGone);
+            shell.once('error', onGone);
+            shell.stdin.on('error', onGone);
+            shell.stdin.write(`${Command.warmup(marker)}\n`, onWritten);
+        });
+    }
+    /**
+     * The single reader of a shell, attached the first time anything reads it and kept for its whole life.
+     * @param shell - The shell to read.
+     * @returns The state of the reader, holding whoever is reading the shell right now.
+     *
+     * @remarks A shell is read through one pair of listeners for its whole life, and what it produced goes
+     * to the command reading it, or to nobody while the shell is only talking to itself. The handover is
+     * therefore a single assignment, which nothing can slip into: a reader attached to the shell by one
+     * instruction and detached by the next leaves a window in which the trailing prompt of the shell is
+     * read as the output of the instruction that follows it.
+     **/
+    static reader(shell) {
+        const existing = Command.vShells.get(shell);
+        if (existing)
+            return existing;
+        const state = { reader: null, probe: null, ready: false };
+        shell.stdout.on('data', (data) => {
+            if (state.reader)
+                state.reader.onStdout(data);
+            else
+                state.probe?.(data.toString());
+        });
+        shell.stderr.on('data', (data) => { state.reader?.onStderr(data); });
+        Command.vShells.set(shell, state);
+        return state;
+    }
+    /**
+     * Takes down a process and every process it started.
+     * @param child - The process to take down.
+     * @returns void
+     **/
+    static terminate(child) {
+        try {
+            if (process.platform === 'win32' || !child.pid)
+                child.kill('SIGKILL');
+            else
+                process.kill(-child.pid, 'SIGKILL');
+        }
+        catch { }
+    }
+    /**
+     * The human readable form of a program, used to describe it when it fails.
+     * @param program - The program to format.
+     * @returns The program followed by its arguments.
+     **/
+    static format(program) {
+        return [program.executable, ...(program.args ?? [])].join(' ');
+    }
+    /** The human readable form of this instruction, used to describe it when it fails. **/
+    get label() {
+        return this.mode === 'shell' ? this.script : Command.format(this.program);
+    }
+    /** The position of this instruction inside its task, starting at 1, carried by every line it emits. **/
+    get ordinal() {
+        return this.vOrdinal;
+    }
+    /**
+     * Starts the command, emitting a `log` event per stdout line, an `err` event per stderr line and
+     * a single `end` event carrying the verdict.
+     * @returns void
+     *
+     * @remarks The verdict is settled exactly once: on the status line the shell writes, on the exit
+     * of the process, on a spawn failure, or when the command is killed.
+     */
+    exec() {
+        if (this.settled)
+            return;
+        this.startedAt = Date.now();
+        if (this.mode === 'shell')
+            this.execInShell();
+        else
+            this.execAsProgram();
+    }
+    /**
+     * Takes the command down, carrying why into its verdict.
+     * @param reason - Why the command is being killed, carried into its verdict.
+     * @returns void
+     *
+     * @remarks A program is taken down along with every process it started. A script cannot be: it
+     * shares the shell with the rest of the task, so the task that owns the shell is the one that takes
+     * the shell down when the run ends.
+     */
+    kill(reason = 'stopped') {
+        if (this.child)
+            Command.terminate(this.child);
+        this.settle({ code: null, signal: null, reason });
+    }
+    /**
+     * Runs the script in the shell, followed by the sentinel that carries its exit status.
+     * @returns void
+     **/
+    execInShell() {
+        if (!this.shell)
+            return void this.settle({ code: null, signal: null, reason: 'shell' });
+        if (this.shell.exitCode !== null || this.shell.signalCode !== null)
+            return void this.settle({ code: null, signal: null, reason: 'shell' });
+        Command.reader(this.shell).reader = this;
+        this.shell.stdin.on('error', this.onStdinError);
+        try {
+            this.shell.stdin.write(`${this.script}\n${Command.sentinel(this.marker)}\n`);
+        }
+        catch {
+            this.settle({ code: null, signal: null, reason: 'shell' });
+        }
+    }
+    /**
+     * Runs the program in a process of its own, started in its own working directory.
+     * @returns void
+     **/
+    execAsProgram() {
+        this.child = spawn(this.program.executable, this.program.args ?? [], {
+            shell: false,
+            cwd: this.program.cwd,
+            detached: process.platform !== 'win32',
+            stdio: ['pipe', 'pipe', 'pipe']
+        });
+        this.child.stdout.on('data', this.onStdout);
+        this.child.stderr.on('data', this.onStderr);
+        this.child.once('error', () => this.settle({ code: null, signal: null, reason: 'spawn' }));
+        this.child.once('close', (code, signal) => this.settle({ code, signal, reason: null }));
+    }
+    /**
+     * Consumes a stdout chunk, emitting the lines it closes, and stops at the sentinel when the
+     * command is a script.
+     * @param data - The raw chunk written to stdout.
+     * @returns void
+     **/
+    onStdout = (data) => {
+        const chunk = data.toString();
+        this.output += chunk;
+        if (this.mode === 'shell' && !this.settled) {
+            const status = this.sentinel(this.output);
+            if (status !== null) {
+                this.output = this.output.slice(0, status.index);
+                this.stream(true);
+                this.settle(status.code === null ? { code: null, signal: null, reason: 'protocol' } : { code: status.code, signal: null, reason: null });
+                return;
+            }
+        }
+        this.stream();
+    };
+    /**
+     * The status line the shell wrote, as the index it starts at and the exit status it carries.
+     * @param output - The output collected so far.
+     * @returns The status, `null` when the line is not there yet, or a null code when it carries none.
+     *
+     * @remarks Only a whole line that is the sentinel counts, and the sentinel carries a random
+     * suffix, so nothing an instruction prints can stand for the shell reporting its status.
+     **/
+    sentinel(output) {
+        const match = output.match(new RegExp(`(?:^|\n)(${this.marker})=([^\\n]*)\\n`));
+        if (!match || match.index === undefined)
+            return null;
+        const code = Number(match[2]);
+        return {
+            index: match.index + (match[0].startsWith('\n') ? 1 : 0),
+            code: Number.isInteger(code) ? code : null
+        };
+    }
+    /**
+     * Consumes a stderr chunk, emitting the lines it closes.
+     * @param data - The raw chunk written to stderr.
+     * @returns void
+     **/
+    onStderr = (data) => {
+        this.errors += data.toString();
+        this.stream();
+    };
+    /**
+     * Absorbs the failure of writing into a shell that is already gone, which is how a sentinel that
+     * will never arrive announces itself.
+     * @returns void
+     **/
+    onStdinError = () => {
+        this.settle({ code: null, signal: null, reason: 'shell' });
+    };
+    /**
+     * Emits the lines both streams have closed since the last call.
+     * @param final - Whether the remaining partial line is emitted too, as nothing else will come.
+     * @returns void
+     **/
+    stream(final = false) {
+        this.outputCursor = this.emitLines(this.output, this.outputCursor, 'log', final);
+        this.errorsCursor = this.emitLines(this.errors, this.errorsCursor, 'err', final);
+    }
+    /**
+     * Emits the complete lines a buffer holds from a given cursor, each carrying the ordinal of the
+     * instruction it belongs to.
+     * @param buffer - The accumulated output of the stream.
+     * @param cursor - Where the previous call stopped.
+     * @param event - The event each line is emitted with.
+     * @param final - Whether the trailing partial line is emitted as well.
+     * @returns The position the cursor reached.
+     **/
+    emitLines(buffer, cursor, event, final) {
+        const end = final ? buffer.length : buffer.lastIndexOf('\n') + 1;
+        if (end <= cursor)
+            return cursor;
+        for (const line of buffer.slice(cursor, end).split('\n')) {
+            const text = line.trim();
+            if (text)
+                this.emit(event, text, this.vOrdinal);
+        }
+        return end;
+    }
+    /**
+     * Settles the verdict of the command, exactly once, detaching every listener it attached.
+     * @param outcome - The status, signal and reason the command ended with.
+     * @returns void
+     **/
+    settle(outcome) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        if (this.shell) {
+            if (Command.reader(this.shell).reader === this)
+                Command.reader(this.shell).reader = null;
+            this.shell.stdin.off('error', this.onStdinError);
+        }
+        this.child?.stdout?.off('data', this.onStdout);
+        this.child?.stderr?.off('data', this.onStderr);
+        this.stream(true);
+        this.emit('end', {
+            code: outcome.code,
+            signal: outcome.signal,
+            reason: outcome.reason,
+            output: this.output.trim(),
+            error: this.errors.trim(),
+            time: Date.now() - this.startedAt
+        });
+    }
+    /**
+     * The line the shell writes once the previous instruction finished, in its own dialect.
+     * @param marker - The sentinel of the command.
+     * @returns The line carrying the exit status of the instruction.
+     **/
+    static sentinel(marker) {
+        return process.platform === 'win32'
+            ? `echo ${marker}=%errorlevel%`
+            : `printf '${marker}=%d\\n' "$?"`;
+    }
+    /**
+     * The orders that turn a fresh shell into one that only reports what an instruction produced.
+     * @param marker - The readiness marker of this shell.
+     * @returns The lines, in the dialect of the shell.
+     *
+     * @remarks `cmd.exe` greets itself with a banner and a prompt, and echoes every order it is given;
+     * `/Q` already silences the echo, and reducing the prompt to a newline leaves nothing else the
+     * reader of an instruction has to tell apart from its output. `bash` reading from a pipe is quiet on
+     * its own, so it only has to say it is ready.
+     **/
+    static warmup(marker) {
+        return process.platform === 'win32' ? `prompt $_\necho ${marker}=1` : `echo ${marker}=1`;
+    }
+    /**
+     * A marker no other order of this process can carry, taken from a monotonic counter.
+     * @returns The marker of the next order written into a shell.
+     *
+     * @remarks The random suffix keeps a marker from being replayed by an instruction that happens to
+     * print it, and the counter keeps two orders written in the same millisecond from sharing one.
+     **/
+    static token() {
+        return `DEP_FLOW_${++Command.vToken}_${Math.random().toString(36).slice(2, 10)}`;
+    }
+}
+export default Command;
+//# sourceMappingURL=Command.js.map

package/dist/task/Command.js.map

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

package/dist/task/Group.d.ts

@@ -0,0 +1,15 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Colored group template factory for the grouper of @netfeez/vterm.
+ * @license Apache-2.0
+ */
+import type { Grouper } from '@netfeez/vterm';
+export declare namespace Group {
+    /**
+     * Builds a colored group template for the grouper of @netfeez/vterm.
+     * @param color - A hex color (`#RRGGBB`) or a vterm color index (1-7).
+     * @returns The group template with open, item, line and stop symbols.
+     */
+    function create(color: `#${string}` | number): Grouper.GroupTemplate;
+}
+export default Group;

package/dist/task/Group.js

@@ -0,0 +1,29 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Colored group template factory for the grouper of @netfeez/vterm.
+ * @license Apache-2.0
+ */
+export var Group;
+(function (Group) {
+    /**
+     * Builds a colored group template for the grouper of @netfeez/vterm.
+     * @param color - A hex color (`#RRGGBB`) or a vterm color index (1-7).
+     * @returns The group template with open, item, line and stop symbols.
+     */
+    function create(color) {
+        let code = '';
+        if (typeof color === 'number') {
+            code = color >= 1 && color <= 7 ? `C${color}` : 'R';
+        }
+        else if (typeof color === 'string' && /^#([0-9A-Fa-f]{6})$/.test(color)) {
+            code = `C(${color})`;
+        }
+        else {
+            code = 'R';
+        }
+        return { open: `&N&${code}╭─`, item: `&N&${code}│ `, line: `&N&${code}├─`, stop: `&N&${code}╰─` };
+    }
+    Group.create = create;
+})(Group || (Group = {}));
+export default Group;
+//# sourceMappingURL=Group.js.map

package/dist/task/Group.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Group.js","sourceRoot":"","sources":["../../src/task/Group.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAIH,MAAM,KAAW,KAAK,CAerB;AAfD,WAAiB,KAAK;IAClB;;;;OAIG;IACH,SAAgB,MAAM,CAAC,KAA4B;QAC/C,IAAI,IAAI,GAAG,EAAE,CAAC;QACd,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;YAC5B,IAAI,GAAG,KAAK,IAAI,CAAC,IAAI,KAAK,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;QACxD,CAAC;aAAM,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,qBAAqB,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACxE,IAAI,GAAG,KAAK,KAAK,GAAG,CAAC;QACzB,CAAC;aAAM,CAAC;YAAC,IAAI,GAAG,GAAG,CAAC;QAAC,CAAC;QACtB,OAAO,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,IAAI,EAAE,MAAM,IAAI,IAAI,EAAE,CAAC;IACtG,CAAC;IARe,MAAA,MAAM,SAQrB,CAAA;AACL,CAAC,EAfgB,KAAK,KAAL,KAAK,QAerB;AAED,eAAe,KAAK,CAAC"}