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

package/dist/schema/ImportMap.d.ts

@@ -0,0 +1,30 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Schema definition for import map files: imports and scope mappings.
+ * @license Apache-2.0
+ */
+import Schema from '@netfeez/schema';
+export declare const ImportMap: Schema<{
+    readonly type: "object";
+    readonly additional: true;
+    readonly default: {};
+    readonly keys: {
+        readonly imports: {
+            readonly type: "object";
+            readonly additional: true;
+            readonly default: {};
+            readonly description: "Mapping of bare specifiers to their resolved URLs or paths.";
+        };
+        readonly scopes: {
+            readonly type: "object";
+            readonly additional: true;
+            readonly default: {};
+            readonly description: "Scope-based mappings of bare specifiers to their resolved URLs or paths.";
+        };
+    };
+    readonly description: "Structure of an import map file.";
+}>;
+export declare namespace ImportMap {
+    type Root = typeof ImportMap.infer;
+}
+export default ImportMap;

package/dist/schema/ImportMap.js

@@ -0,0 +1,28 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Schema definition for import map files: imports and scope mappings.
+ * @license Apache-2.0
+ */
+import Schema from '@netfeez/schema';
+export const ImportMap = new Schema({
+    type: 'object',
+    additional: true,
+    default: {},
+    keys: {
+        imports: {
+            type: 'object',
+            additional: true,
+            default: {},
+            description: 'Mapping of bare specifiers to their resolved URLs or paths.'
+        },
+        scopes: {
+            type: 'object',
+            additional: true,
+            default: {},
+            description: 'Scope-based mappings of bare specifiers to their resolved URLs or paths.'
+        }
+    },
+    description: 'Structure of an import map file.'
+});
+export default ImportMap;
+//# sourceMappingURL=ImportMap.js.map

package/dist/schema/ImportMap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ImportMap.js","sourceRoot":"","sources":["../../src/schema/ImportMap.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,MAAM,MAAM,iBAAiB,CAAC;AAErC,MAAM,CAAC,MAAM,SAAS,GAAG,IAAI,MAAM,CAAC;IAChC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;IAChB,OAAO,EAAE,EAAE;IACX,IAAI,EAAE;QACF,OAAO,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,IAAI;YAChB,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,6DAA6D;SAC7E;QACD,MAAM,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,IAAI;YAChB,OAAO,EAAE,EAAE;YACX,WAAW,EAAE,0EAA0E;SAC1F;KACJ;IACD,WAAW,EAAE,kCAAkC;CAClD,CAAC,CAAC;AAMH,eAAe,SAAS,CAAC"}

package/{build → dist}/schema/TSConfig.d.ts

@@ -1,51 +1,65 @@
-import { Schema } from '@netfeez/common';
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Schema definitions for tsconfig files: compiler options and path mappings.
+ * @license Apache-2.0
+ */
+import Schema from '@netfeez/schema';
 export declare const CompilerOptions: Schema<{
     readonly type: "object";
-    readonly allowAdditionalProperties: true;
-    readonly properties: {
+    readonly additional: true;
+    readonly keys: {
         readonly rootDir: {
             readonly type: "string";
+            readonly description: "Root directory of the TypeScript source files.";
         };
         readonly outDir: {
             readonly type: "string";
+            readonly description: "Output directory for the compiled files.";
         };
         readonly paths: {
             readonly type: "object";
-            readonly allowAdditionalProperties: {
+            readonly additional: {
                 readonly type: "array";
                 readonly items: {
                     readonly type: "string";
                 };
             };
+            readonly description: "Path mapping aliases used by TypeScript to resolve modules.";
         };
     };
+    readonly description: "TypeScript compiler options.";
 }>;
 export declare const TSConfig: Schema<{
     readonly type: "object";
-    readonly allowAdditionalProperties: true;
-    readonly properties: {
+    readonly additional: true;
+    readonly keys: {
         readonly compilerOptions: {
             readonly type: "object";
-            readonly allowAdditionalProperties: true;
-            readonly properties: {
+            readonly additional: true;
+            readonly keys: {
                 readonly rootDir: {
                     readonly type: "string";
+                    readonly description: "Root directory of the TypeScript source files.";
                 };
                 readonly outDir: {
                     readonly type: "string";
+                    readonly description: "Output directory for the compiled files.";
                 };
                 readonly paths: {
                     readonly type: "object";
-                    readonly allowAdditionalProperties: {
+                    readonly additional: {
                         readonly type: "array";
                         readonly items: {
                             readonly type: "string";
                         };
                     };
+                    readonly description: "Path mapping aliases used by TypeScript to resolve modules.";
                 };
             };
+            readonly description: "The compiler options object of the tsconfig file.";
         };
     };
+    readonly description: "Structure of a tsconfig.json file.";
 }>;
 export declare namespace TSConfig {
     namespace Root {

package/dist/schema/TSConfig.js

@@ -0,0 +1,39 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Schema definitions for tsconfig files: compiler options and path mappings.
+ * @license Apache-2.0
+ */
+import Schema from '@netfeez/schema';
+export const CompilerOptions = new Schema({
+    type: 'object',
+    additional: true,
+    keys: {
+        rootDir: {
+            type: 'string',
+            description: 'Root directory of the TypeScript source files.'
+        },
+        outDir: {
+            type: 'string',
+            description: 'Output directory for the compiled files.'
+        },
+        paths: {
+            type: 'object',
+            additional: { type: 'array', items: { type: 'string' } },
+            description: 'Path mapping aliases used by TypeScript to resolve modules.'
+        }
+    },
+    description: 'TypeScript compiler options.'
+});
+export const TSConfig = new Schema({
+    type: 'object',
+    additional: true,
+    keys: {
+        compilerOptions: {
+            ...CompilerOptions.definition,
+            description: 'The compiler options object of the tsconfig file.'
+        }
+    },
+    description: 'Structure of a tsconfig.json file.'
+});
+export default TSConfig;
+//# sourceMappingURL=TSConfig.js.map

package/dist/schema/TSConfig.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"TSConfig.js","sourceRoot":"","sources":["../../src/schema/TSConfig.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,MAAM,MAAM,iBAAiB,CAAC;AAErC,MAAM,CAAC,MAAM,eAAe,GAAG,IAAI,MAAM,CAAC;IACtC,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;IAChB,IAAI,EAAE;QACF,OAAO,EAAE;YACL,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,gDAAgD;SAChE;QACD,MAAM,EAAE;YACJ,IAAI,EAAE,QAAQ;YACd,WAAW,EAAE,0CAA0C;SAC1D;QACD,KAAK,EAAE;YACH,IAAI,EAAE,QAAQ;YACd,UAAU,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE;YACxD,WAAW,EAAE,6DAA6D;SAC7E;KACJ;IACD,WAAW,EAAE,8BAA8B;CAC9C,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,QAAQ,GAAG,IAAI,MAAM,CAAC;IAC/B,IAAI,EAAE,QAAQ;IACd,UAAU,EAAE,IAAI;IAChB,IAAI,EAAE;QACF,eAAe,EAAE;YACb,GAAG,eAAe,CAAC,UAAU;YAC7B,WAAW,EAAE,mDAAmD;SACnE;KACJ;IACD,WAAW,EAAE,oCAAoC;CACpD,CAAC,CAAC;AASH,eAAe,QAAQ,CAAC"}

package/{build → dist}/schema/schema.d.ts

@@ -1,10 +1,15 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Aggregates every schema definition under the shared schema namespace.
+ * @license Apache-2.0
+ */
 import _TSConfig from './TSConfig.js';
 import _ImportMap from './ImportMap.js';
 import _Config from './Config/Config.js';
 import _Resolver, { Target as _Target } from './Config/Resolver.js';
 import _Transform, { GlobalTransform as _GlobalTransform } from './Config/Transform.js';
 import _Extractor from './Config/Extractor.js';
-import _Builder from './Config/Builder.js';
+import _Builder, { BuilderEntry as _BuilderEntry, RunEntry as _RunEntry, ExtractEntry as _ExtractEntry, TransformEntry as _TransformEntry } from './Config/Builder.js';
 import _Dependency from './Config/Dependency.js';
 export { TSConfig } from './TSConfig.js';
 export { ImportMap } from './ImportMap.js';
@@ -12,7 +17,7 @@ export { Config } from './Config/Config.js';
 export { Resolver, Target } from './Config/Resolver.js';
 export { Transform, GlobalTransform } from './Config/Transform.js';
 export { Extractor } from './Config/Extractor.js';
-export { Builder } from './Config/Builder.js';
+export { Builder, BuilderEntry, RunEntry, ExtractEntry, TransformEntry } from './Config/Builder.js';
 export { Dependency } from './Config/Dependency.js';
 export declare namespace schema {
     export import TSConfig = _TSConfig;
@@ -24,6 +29,10 @@ export declare namespace schema {
     export import GlobalTransform = _GlobalTransform;
     export import Extractor = _Extractor;
     export import Builder = _Builder;
+    export import BuilderEntry = _BuilderEntry;
+    export import RunEntry = _RunEntry;
+    export import ExtractEntry = _ExtractEntry;
+    export import TransformEntry = _TransformEntry;
     export import Dependency = _Dependency;
 }
 export default schema;

package/{build → dist}/schema/schema.js

@@ -1,10 +1,15 @@
+/**
+ * @author NetFeez <netfeez.dev@gmail.com>.
+ * @description Aggregates every schema definition under the shared schema namespace.
+ * @license Apache-2.0
+ */
 import _TSConfig from './TSConfig.js';
 import _ImportMap from './ImportMap.js';
 import _Config from './Config/Config.js';
 import _Resolver, { Target as _Target } from './Config/Resolver.js';
 import _Transform, { GlobalTransform as _GlobalTransform } from './Config/Transform.js';
 import _Extractor from './Config/Extractor.js';
-import _Builder from './Config/Builder.js';
+import _Builder, { BuilderEntry as _BuilderEntry, RunEntry as _RunEntry, ExtractEntry as _ExtractEntry, TransformEntry as _TransformEntry } from './Config/Builder.js';
 import _Dependency from './Config/Dependency.js';
 export { TSConfig } from './TSConfig.js';
 export { ImportMap } from './ImportMap.js';
@@ -12,7 +17,7 @@ export { Config } from './Config/Config.js';
 export { Resolver, Target } from './Config/Resolver.js';
 export { Transform, GlobalTransform } from './Config/Transform.js';
 export { Extractor } from './Config/Extractor.js';
-export { Builder } from './Config/Builder.js';
+export { Builder, BuilderEntry, RunEntry, ExtractEntry, TransformEntry } from './Config/Builder.js';
 export { Dependency } from './Config/Dependency.js';
 export var schema;
 (function (schema) {
@@ -25,6 +30,10 @@ export var schema;
     schema.GlobalTransform = _GlobalTransform;
     schema.Extractor = _Extractor;
     schema.Builder = _Builder;
+    schema.BuilderEntry = _BuilderEntry;
+    schema.RunEntry = _RunEntry;
+    schema.ExtractEntry = _ExtractEntry;
+    schema.TransformEntry = _TransformEntry;
     schema.Dependency = _Dependency;
 })(schema || (schema = {}));
 export default schema;

package/dist/schema/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../src/schema/schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,SAAS,MAAM,eAAe,CAAC;AACtC,OAAO,UAAU,MAAM,gBAAgB,CAAC;AACxC,OAAO,OAAO,MAAM,oBAAoB,CAAC;AACzC,OAAO,SAAS,EAAE,EAAE,MAAM,IAAI,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpE,OAAO,UAAU,EAAE,EAAE,eAAe,IAAI,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACxF,OAAO,UAAU,MAAM,uBAAuB,CAAC;AAC/C,OAAO,QAAQ,EAAE,EACb,YAAY,IAAI,aAAa,EAC7B,QAAQ,IAAI,SAAS,EACrB,YAAY,IAAI,aAAa,EAC7B,cAAc,IAAI,eAAe,EACpC,MAAM,qBAAqB,CAAC;AAC7B,OAAO,WAAW,MAAM,wBAAwB,CAAC;AAEjD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AACxD,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACnE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAAE,OAAO,EAAE,YAAY,EAAE,QAAQ,EAAE,YAAY,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AACpG,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,MAAM,KAAW,MAAM,CAetB;AAfD,WAAiB,MAAM;IACL,OAAA,QAAQ,GAAG,SAAU,CAAA;IACrB,OAAA,SAAS,GAAG,UAAW,CAAA;IACvB,OAAA,MAAM,GAAG,OAAQ,CAAA;IACjB,OAAA,QAAQ,GAAG,SAAU,CAAA;IACrB,OAAA,MAAM,GAAG,OAAQ,CAAA;IACjB,OAAA,SAAS,GAAG,UAAW,CAAA;IACvB,OAAA,eAAe,GAAG,gBAAiB,CAAA;IACnC,OAAA,SAAS,GAAG,UAAW,CAAA;IACvB,OAAA,OAAO,GAAG,QAAS,CAAA;IACnB,OAAA,YAAY,GAAG,aAAc,CAAA;IAC7B,OAAA,QAAQ,GAAG,SAAU,CAAA;IACrB,OAAA,YAAY,GAAG,aAAc,CAAA;IAC7B,OAAA,cAAc,GAAG,eAAgB,CAAA;IACjC,OAAA,UAAU,GAAG,WAAY,CAAA;AAC3C,CAAC,EAfgB,MAAM,KAAN,MAAM,QAetB;AAED,eAAe,MAAM,CAAC"}

package/dist/task/Command.d.ts

@@ -0,0 +1,287 @@
+/**
+ * @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 { ChildProcessWithoutNullStreams } from "node:child_process";
+import { Events } from "@netfeez/common";
+export declare class Command extends Events<Command.EventMap> {
+    /**
+     * 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.
+     */
+    private static vToken;
+    /**
+     * 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.
+     */
+    private static vShells;
+    protected readonly mode: Command.Mode;
+    protected readonly shell: Command.Shell | null;
+    protected readonly script: string;
+    protected readonly program: Command.Program;
+    /** The sentinel the shell writes once the instruction finished, carrying its exit status. */
+    protected readonly marker: string;
+    protected child: Command.Process | null;
+    protected settled: boolean;
+    protected startedAt: number;
+    protected output: string;
+    protected errors: string;
+    protected outputCursor: number;
+    protected errorsCursor: number;
+    private vOrdinal;
+    private constructor();
+    /**
+     * 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: Command.Shell | null, script: string, ordinal?: number): Command;
+    /**
+     * 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: Command.Program, ordinal?: number): Command;
+    /**
+     * 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: string): Command.Shell;
+    /**
+     * 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: Command.Shell): Promise<void>;
+    /**
+     * 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.
+     **/
+    protected static reader(shell: Command.Shell): Command.ShellState;
+    /**
+     * Takes down a process and every process it started.
+     * @param child - The process to take down.
+     * @returns void
+     **/
+    static terminate(child: Command.Process): void;
+    /**
+     * 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: Command.Program): string;
+    /** The human readable form of this instruction, used to describe it when it fails. **/
+    get label(): string;
+    /** The position of this instruction inside its task, starting at 1, carried by every line it emits. **/
+    get ordinal(): number;
+    /**
+     * 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(): void;
+    /**
+     * 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?: Command.Reason): void;
+    /**
+     * Runs the script in the shell, followed by the sentinel that carries its exit status.
+     * @returns void
+     **/
+    protected execInShell(): void;
+    /**
+     * Runs the program in a process of its own, started in its own working directory.
+     * @returns void
+     **/
+    protected execAsProgram(): void;
+    /**
+     * 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
+     **/
+    protected readonly onStdout: (data: Buffer) => void;
+    /**
+     * 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.
+     **/
+    protected sentinel(output: string): {
+        index: number;
+        code: number | null;
+    } | null;
+    /**
+     * Consumes a stderr chunk, emitting the lines it closes.
+     * @param data - The raw chunk written to stderr.
+     * @returns void
+     **/
+    protected readonly onStderr: (data: Buffer) => void;
+    /**
+     * 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
+     **/
+    protected readonly onStdinError: () => void;
+    /**
+     * 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
+     **/
+    protected stream(final?: boolean): void;
+    /**
+     * 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.
+     **/
+    protected emitLines(buffer: string, cursor: number, event: 'log' | 'err', final: boolean): number;
+    /**
+     * 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
+     **/
+    protected settle(outcome: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        reason: Command.Reason | null;
+    }): void;
+    /**
+     * 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.
+     **/
+    protected static sentinel(marker: string): string;
+    /**
+     * 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.
+     **/
+    protected static warmup(marker: string): string;
+    /**
+     * 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.
+     **/
+    protected static token(): string;
+}
+export declare namespace Command {
+    type Emitter = Events.Emitter<EventMap>;
+    type Process = ChildProcessWithoutNullStreams;
+    type Shell = ChildProcessWithoutNullStreams;
+    type Mode = 'shell' | 'program';
+    type Reason = 'stopped' | 'timeout' | 'shell' | 'spawn' | 'protocol';
+    /** The options a command is created with, either a shell and a script or a program. */
+    interface Options {
+        shell?: Command.Shell;
+        script?: string;
+        program?: Command.Program;
+        /** The position of the instruction inside its task, starting at 1, carried by every line it emits. */
+        ordinal?: number;
+    }
+    /**
+     * The reader of a shell that outlives the instruction reading it: the command in flight, the probe
+     * waiting for the shell to report itself ready, or neither while the shell is between instructions.
+     */
+    interface ShellState {
+        /** The command reading the shell right now, or `null` when no instruction is running. */
+        reader: Command | null;
+        /** Told about every chunk that arrives while no instruction is reading the shell. */
+        probe: ((text: string) => void) | null;
+        /** Whether the shell already reported itself ready. */
+        ready: boolean;
+    }
+    /**
+     * A program to run as a process of its own, where neither the executable, its arguments nor its
+     * working directory go through a shell.
+     */
+    interface Program {
+        executable: string;
+        args?: string[];
+        cwd?: string;
+    }
+    /** How an instruction ended, in the only form a task needs to turn it into a verdict. */
+    interface Verdict {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        reason: Reason | null;
+        output: string;
+        error: string;
+        time: number;
+    }
+    /**
+     * The events of a command: a line of stdout, a line of stderr, both carrying the ordinal of the
+     * instruction they belong to, and the single verdict that settles it.
+     */
+    type EventMap = {
+        log: [message: string, ordinal: number];
+        err: [message: string, ordinal: number];
+        end: [verdict: Verdict];
+    };
+}
+export default Command;