@effected/cli 0.23.0 → 0.24.0

package/testing.d.ts

@@ -1,5 +1,5 @@
-import { Effect, FileSystem, Layer, Path, PlatformError, Scope, Terminal } from "effect";
-import { ChildProcessSpawner } from "effect/process";
+import { Duration, Effect, FileSystem, Layer, Path, PlatformError, Scope, Stream, Terminal } from "effect";
+import { ChildProcess, ChildProcessSpawner } from "effect/process";
 /**
  * A hermetic temp directory minted by {@link CliTest.sandbox}, removed when its
  * scope closes.
@@ -39,6 +39,12 @@ interface RunOptions {
    * the child gets an already-ended empty input, never an open pipe.
    */
   readonly stdin?: string | undefined;
+  /**
+   * How long a child has to exit after `SIGTERM` (or the signal `kill` sends), when its scope closes or
+   * {@link SpawnedBin.kill} is called, before it is sent `SIGKILL`; `2 seconds` by default. A finite duration: a
+   * child that ignores the signal would otherwise keep the scope from closing forever, and leave the process behind.
+   */
+  readonly forceKillAfter?: Duration.Input | undefined;
 }
 /**
  * What a spawned bin did, as data: a non-zero exit is a result, not a failure.
@@ -46,13 +52,46 @@ interface RunOptions {
  * @public
  */
 interface RunResult {
-  /** The child's exit code. */
-  readonly exitCode: number;
+  /** The child's exit code, or `null` when a signal ended it. */
+  readonly exitCode: number | null;
+  /** The signal that ended the child, or `null` when it exited with a code. */
+  readonly signal: ChildProcess.Signal | null;
   /** Everything the child wrote to stdout, decoded as UTF-8. */
   readonly stdout: string;
   /** Everything the child wrote to stderr, decoded as UTF-8. */
   readonly stderr: string;
 }
+/**
+ * A bin {@link CliTest.spawn} started and has not waited for: its output as it arrives, a way to signal it, and its
+ * exit.
+ *
+ * @public
+ */
+interface SpawnedBin {
+  /**
+   * The child's stdout as lines, each without its line break (`\r\n` included), from the first byte it wrote,
+   * ending when the child closes stdout; a last line with no line break comes when it does. Every subscription replays
+   * from the start, so a test may read it more than once, and output a test never reads is still drained, so the
+   * child never blocks on a full pipe.
+   */
+  readonly stdout: Stream.Stream<string>;
+  /** The child's stderr as lines, as `stdout` gives stdout. */
+  readonly stderr: Stream.Stream<string>;
+  /**
+   * Send `signal` (`SIGTERM` by default) and wait for the child to exit. A child still running after
+   * {@link RunOptions.forceKillAfter} is sent `SIGKILL`, so this always ends. A child that has already exited, on its
+   * own or at the same moment, is not an error: this returns normally, and `exitCode` and `result` keep reporting how
+   * it ended. A kill that fails on a child still running fails with that `PlatformError`.
+   */
+  readonly kill: (signal?: ChildProcess.Signal) => Effect.Effect<void, PlatformError.PlatformError>;
+  /**
+   * The child's exit code once it exits, or `null` when a signal ended it (the default `kill` included): `result`
+   * names the signal. Re-reading it after the exit answers at once.
+   */
+  readonly exitCode: Effect.Effect<number | null, PlatformError.PlatformError>;
+  /** Wait for the exit and the end of both streams, and read everything, as {@link CliTest.run} returns it. */
+  readonly result: Effect.Effect<RunResult, PlatformError.PlatformError>;
+}
 /**
  * Spawn a built CLI bin hermetically and read its exit code and streams as data.
  *
@@ -103,6 +142,30 @@ export declare class CliTest {
    * ends it.
    */
   static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * Start `execPath bin ...args` and return at once with a handle on it: its output as lines while it runs, a signal,
+   * and its exit, for a long-running command (a `--follow`, a watch mode, a server) that {@link CliTest.run} would wait
+   * on forever.
+   *
+   * @remarks
+   * The child lives in the caller's scope: when the scope closes first, the child is sent `SIGTERM`, then `SIGKILL`
+   * after `forceKillAfter` (`2 seconds` by default), so a test that ends early leaves nothing running and never waits
+   * on a child that ignores the signal. A child a signal ended reports `exitCode: null` and the signal in `result`. Both streams are drained from the start whether or not the test reads them, so a
+   * chatty child never blocks on a full pipe, and each stream replays from its first line to every reader. The
+   * options are {@link CliTest.run}'s, `stdin` included: the child gets that text, then an ended input.
+   *
+   * ```ts
+   * const child = yield* CliTest.spawn("dist/bin.js", ["logs", "--follow"], { sandbox, execPath: process.execPath })
+   * yield* Stream.runHead(child.stdout) // the first line: it is following
+   * yield* child.kill("SIGINT")
+   * assert.strictEqual(yield* child.exitCode, 0)
+   * ```
+   *
+   * @param bin - the built bin to run
+   * @param args - its arguments
+   * @param options - the sandbox, the node binary, and the working directory, environment and stdin
+   */
+  static readonly spawn: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<SpawnedBin, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner | Scope.Scope>;
 }
 /**
  * One key press for {@link TestTerminal}.
@@ -172,5 +235,5 @@ export declare class TestTerminal {
     readonly rows?: number | undefined;
   }) => Effect.Effect<TestTerminalHandle>;
 }
-export type { KeyInput, RunOptions, RunResult, Sandbox, TestTerminalHandle };
+export type { KeyInput, RunOptions, RunResult, Sandbox, SpawnedBin, TestTerminalHandle };
 //# sourceMappingURL=testing.d.ts.map

package/ui/CliUi.js

@@ -384,7 +384,10 @@ var CliUi = class CliUi {
 	* It runs during parsing, whose environment is core's alone, so it reads `CliTheme` if one is there: with
 	* `CliRuntime.main`'s `env` (`CliEnv.layer`), or provided around the program. With no theme it treats the run as
 	* not interactive, and when `CliInteractive` is on it says so once, at debug level. Interactivity is
-	* `CliInteractive`, which an audience flag can set before parsing under `CliAudience`.
+	* `CliInteractive`, which an audience flag can set before parsing under `CliAudience`. Core calls a fallback only
+	* when its `TerminalCapabilities.canPrompt` is `true`; `CliInteractive.layer` and `layerTest` hold it there so that
+	* `otherwise` survives a piped run, and a `canPrompt: false` provided inside the program bypasses this fallback,
+	* as it does `CliPrompt.fallback`.
 	*
 	* As with `CliPrompt.fallback`, the screen runs here rather than being handed to core, whose fallback runner
 	* turns a quit into the missing-parameter error, which would exit `64`. A cancel (Esc, Ctrl-C) is `Cancelled`,

package/ui.d.ts

@@ -687,7 +687,10 @@ export declare class CliUi {
    * It runs during parsing, whose environment is core's alone, so it reads `CliTheme` if one is there: with
    * `CliRuntime.main`'s `env` (`CliEnv.layer`), or provided around the program. With no theme it treats the run as
    * not interactive, and when `CliInteractive` is on it says so once, at debug level. Interactivity is
-   * `CliInteractive`, which an audience flag can set before parsing under `CliAudience`.
+   * `CliInteractive`, which an audience flag can set before parsing under `CliAudience`. Core calls a fallback only
+   * when its `TerminalCapabilities.canPrompt` is `true`; `CliInteractive.layer` and `layerTest` hold it there so that
+   * `otherwise` survives a piped run, and a `canPrompt: false` provided inside the program bypasses this fallback,
+   * as it does `CliPrompt.fallback`.
    *
    * As with `CliPrompt.fallback`, the screen runs here rather than being handed to core, whose fallback runner
    * turns a quit into the missing-parameter error, which would exit `64`. A cancel (Esc, Ctrl-C) is `Cancelled`,

package/internal/causeMessage.js

@@ -1,57 +0,0 @@
-import { Predicate } from "effect";
-
-// src/internal/causeMessage.ts
-/** How many nodes of a cause chain the walk reads before stopping, so a cyclic chain cannot spin. */
-const CAUSE_DEPTH = 8;
-/**
-* The message a single node carries: a thrown string, or a non-empty string `message` property. A getter or
-* proxy trap that throws is a node with no message.
-*/
-const messageAt = (node) => {
-	try {
-		const text = Predicate.isString(node) ? node : Predicate.hasProperty(node, "message") && Predicate.isString(node.message) ? node.message : void 0;
-		return text === void 0 || text.trim() === "" ? void 0 : text;
-	} catch {
-		return;
-	}
-};
-/** The next link of the chain: a node's `cause`, or `undefined` when it has none or reading it throws. */
-const causeAt = (node) => {
-	try {
-		return Predicate.hasProperty(node, "cause") ? node.cause : void 0;
-	} catch {
-		return;
-	}
-};
-/**
-* Every distinct non-empty message a preserved cause chain carries, nearest
-* first and joined with `: `, or `undefined` when nothing along it has one.
-*
-* A `Schema.Defect()` field holds whatever was thrown, so the read is guarded
-* rather than assumed: `Predicate.hasProperty` + `Predicate.isString` accepts
-* an `Error`, a cross-realm `Error` that fails `instanceof`, a plain
-* `{ message }` object and a thrown string alike. An empty or whitespace-only
-* message counts as none. The walk follows `cause` links because a wrapper's
-* text is often the generic summary and the driver's text underneath is the
-* actionable detail, yet a wrapper that composes its own context must not
-* lose it either; so nothing is dropped, and a deeper text the nearer one
-* already contains is not repeated. The walk is bounded, so a cycle terminates.
-*
-* It never throws: every property read is guarded, so a `message` getter that throws leaves that link
-* without text, and a `cause` getter that throws ends the walk with what was found so far.
-*/
-const causeMessage = (cause) => {
-	let message;
-	let node = cause;
-	for (let depth = 0; depth < CAUSE_DEPTH && node !== void 0 && node !== null; depth++) {
-		const text = messageAt(node);
-		if (text !== void 0) {
-			if (message === void 0 || text.includes(message)) message = text;
-			else if (!message.includes(text)) message = `${message}: ${text}`;
-		}
-		node = causeAt(node);
-	}
-	return message;
-};
-
-export { causeMessage };