@effected/cli 0.22.2 → 0.23.0

package/ui.d.ts

@@ -1,7 +1,8 @@
 import * as Cli from "@effected/cli";
-import { Console, Context, Effect, Option, PubSub, Scope, Stream } from "effect";
+import { Console, Context, Effect, Exit, Layer, Option, PubSub, Scope, Stream } from "effect";
 import { Param } from "effect/cli";
 import { ReactElement, ReactNode } from "react";
+import { Writable } from "node:stream";
 import { Key } from "ink";
 import { ColorLevel } from "@effected/env";
 /**
@@ -177,6 +178,120 @@ interface LiveHandle<S> {
    */
   readonly close: Effect.Effect<void>;
 }
+/**
+ * Options for `CliUi.liveDetached`: those of `CliUi.live`, with the events given as a `PubSub` or a stream, and the
+ * render given directly or as an effect that makes it.
+ *
+ * @typeParam R - the services a `render` effect reads, which the `env` layer provides
+ *
+ * @public
+ */
+interface DetachedLiveOptions<E, S, R = never> extends Omit<LiveOptions<E, S>, "events" | "render"> {
+  /**
+   * The events to fold. A `PubSub` is subscribed before `liveDetached` returns, in the view's own scope, so an event
+   * published right after the call is seen and `close` folds every message still queued. A stream is read as
+   * `CliUi.live` reads one.
+   */
+  readonly events: PubSub.PubSub<E> | Stream.Stream<E>;
+  /**
+   * Draw the state, as `CliUi.live`'s `render`; or an effect that makes that function, run once under `env` before
+   * the view is set up, so a render that needs an environment service (`CliLinks` to build links, `TerminalEnv` for
+   * the terminal's capabilities) reads it from the layer the view already builds rather than from a second build.
+   *
+   * @remarks
+   * A render effect that dies is the view's setup failing: `handle` rejects, `close` resolves, and `exit` carries
+   * the die, as for an `env` layer that dies. It can return a `CliUi.lazyView`.
+   */
+  readonly render: LiveOptions<E, S>["render"] | Effect.Effect<LiveOptions<E, S>["render"], never, R>;
+}
+/**
+ * A live view running outside Effect, from `CliUi.liveDetached`.
+ *
+ * @public
+ */
+interface DetachedLive<S> {
+  /**
+   * The view's handle once `CliUi.live` has set it up (it loads Ink asynchronously). Rejects if the view could not be
+   * set up; the rejection is handled, so a host that never awaits it sees no unhandled rejection.
+   */
+  readonly handle: Promise<LiveHandle<S>>;
+  /**
+   * The handle's `printAbove`: print one line above the frame and say whether it did. `false`, with nothing written,
+   * before the handle is set up, whenever no run's frame is mounted, and from the moment `close` is called, so the
+   * host writes the line itself.
+   */
+  readonly printAbove: (stream: "stdout" | "stderr", line: string) => boolean;
+  /**
+   * End the view and release it.
+   *
+   * @remarks
+   * In order: `printAbove` stops printing; the view's setup is awaited (one that died counts as settled); the
+   * handle's `close` folds every message still queued in the subscription and commits the last run; then the view's
+   * scope is closed, which unsubscribes and unmounts. Shut the `PubSub` down only after the returned promise
+   * resolves: a `PubSub.shutdown` before it drops the events the view has not taken yet.
+   *
+   * Idempotent: every call returns the same promise. It never rejects; how the view ended is `exit`.
+   */
+  readonly close: () => Promise<void>;
+  /**
+   * How the view ended: a success when its events ended or `close` ended them, the failure it died of (a `reduce`
+   * that threw, a stream that died, a setup that failed), or an interrupt when its scope closed under it.
+   */
+  readonly exit: Promise<Exit.Exit<void>>;
+}
+/**
+ * Options for `CliUi.routeStream`.
+ *
+ * @public
+ */
+interface RouteStreamOptions {
+  /** Which of the printer's streams the lines belong on. */
+  readonly stream: "stdout" | "stderr";
+  /**
+   * The most characters held back waiting for a line break; 8192 by default. Past it, the held text is offered as a
+   * line of its own, so a writer that never ends a line cannot grow the buffer without bound.
+   */
+  readonly maxHeld?: number | undefined;
+  /**
+   * What a line holding a carriage return is printed as: `keep` (the default) prints it as written, and `last` prints
+   * only the text after its last `\r`, which is what a terminal would have shown of a progress bar redrawn in place.
+   * A CRLF line ending is a line ending either way. A line written to the original stream is always written as it came.
+   */
+  readonly carriageReturn?: "keep" | "last" | undefined;
+  /**
+   * Called with every piece of text written, decoded, before it is routed: a tap for a recorder.
+   *
+   * @remarks
+   * Every write reaches it, a write of nothing but escape sequences (a cursor hide, a clear-screen) included, though
+   * such a write is never offered to the printer. A write holding only the first bytes of a character reaches it when
+   * the character completes, or as U+FFFD at `flush`.
+   */
+  readonly onText?: ((text: string) => void) | undefined;
+}
+/**
+ * A stream routed line by line through a printer, from `CliUi.routeStream`.
+ *
+ * @public
+ */
+interface RoutedStream {
+  /**
+   * The stream to hand to the writer in place of the original. It reports the original's `isTTY`, `columns`, `rows`,
+   * `getColorDepth`, `hasColors` and `getWindowSize`, where the original has them, so a library that sizes its output
+   * to the terminal still sees one.
+   */
+  readonly writable: Writable;
+  /**
+   * Turn routing on (the default) or off. Turned off, the text held waiting for a line break is written to the
+   * original, and every later write goes straight to it, decoded, until routing is turned back on.
+   */
+  readonly route: (on: boolean) => void;
+  /**
+   * Offer the text held waiting for a line break to the printer now, or write it to the original if it declines.
+   * It ends the decoding too: a character split across writes whose second half has not arrived is written as
+   * U+FFFD. Ending `writable` (`end()`) flushes the same way, so a last line with no line break is never lost.
+   */
+  readonly flush: () => void;
+}
 /**
  * What the kit's hooks read in a tree the kit did not mount: the theme, the glyph set, and optionally the size.
  *
@@ -200,6 +315,12 @@ interface UiContextValue {
     readonly columns: number;
     readonly rows: number;
   };
+  /**
+   * How a `DocView` under it shows an absolute path: `CliUi.context` sets it from the run's `displayPath`
+   * (`CliEnvOptions.displayPath`), so a frame shows a path as `Doc.print` and a live view's `final` do. Absent, a
+   * nested provider keeps the one above it, and with none the path is shown as given.
+   */
+  readonly displayPath?: ((absolute: string) => string) | undefined;
   /**
    * Whether the GitHub Actions runner reads the output (`CliUi.context` sets it from `CurrentRuntimeEnv`, when one is
    * provided): a `DocView` under it neutralizes any line its data would turn into a workflow command. `false` opts the
@@ -452,6 +573,82 @@ export declare class CliUi {
    * @param options - the events, the fold, the drawing, and what starts and ends a run
    */
   static readonly live: <E, S>(options: LiveOptions<E, S>) => Effect.Effect<LiveHandle<S>, never, Scope.Scope | Cli.CliTheme>;
+  /**
+   * A live view hosted by code that is not built on Effect: a test runner's reporter, a bundler plugin, a build hook.
+   *
+   * @remarks
+   * It runs `CliUi.live` in a fiber of its own, under `env` and in a scope of its own, and returns at once. A `PubSub`
+   * given as `events` is subscribed before it returns, so the first event published after the call is not lost.
+   * `env` is the environment the view reads, built by the host, which owns the platform: under Node,
+   * `CliEnv.layer().pipe(Layer.provide(NodeServices.layer))`; a test gives `CliEnv.layerTest` with a session's layer.
+   *
+   * End it with `close`, and only then shut the `PubSub` down: `close` folds the subscription's queued tail, commits
+   * the last run and releases the scope, and a shutdown before it drops that tail. `close` never rejects; `exit`
+   * says how the view ended. Forward output the host did not write through `printAbove`, or hand
+   * `CliUi.routeStream` the detached view's `printAbove` as its printer.
+   *
+   * A render that needs an environment service is given as an effect that makes the render function: it runs once
+   * under `env`, before the view is set up, so `CliLinks` or `TerminalEnv` come from the same build the view reads and
+   * the layer is not built a second time to resolve them. `env` must provide what that effect reads.
+   *
+   * Inside an Effect program, use `CliUi.live` in a scope instead.
+   *
+   * @example
+   * ```ts
+   * const view = CliUi.liveDetached(
+   * 	{
+   * 		...options,
+   * 		render: Effect.gen(function* () {
+   * 			const links = yield* CliLinks
+   * 			return (state: State, frame: number) => drawWith(links, state, frame)
+   * 		}),
+   * 	},
+   * 	CliEnv.layer().pipe(Layer.provide(NodeServices.layer)),
+   * )
+   * ```
+   *
+   * @param options - the live view's options, with the events as a `PubSub` or a stream and the render given directly
+   *   or as an effect that makes it
+   * @param env - the environment the view runs under, providing what a render effect reads
+   */
+  static readonly liveDetached: <E, S, R = never>(options: DetachedLiveOptions<E, S, R>, env: Layer.Layer<Cli.CliTheme | NoInfer<R>>) => DetachedLive<S>;
+  /**
+   * A stream to hand to a writer in place of a terminal stream, which routes what it writes line by line through
+   * `printer`, usually a live view's `printAbove`, and writes whatever the printer declines to `original`.
+   *
+   * @remarks
+   * For output the program does not write itself: a child process's stderr, or the streams of a test runner or a
+   * bundler running in-process. Each complete line is offered to `printer`; a `false` (no frame mounted) writes it,
+   * with its line break, to `original`. Text without a line break yet is held until one comes, until `flush`, or
+   * until it passes `maxHeld` characters, when it is offered as a line of its own. Bytes are decoded as UTF-8 across
+   * writes, so a character split between two writes arrives whole.
+   *
+   * Everything written to `original` is the decoded text, so a character split across two writes, by whichever path,
+   * arrives once and whole. A write that is nothing but escape sequences (a cursor hide, a clear-screen) goes
+   * straight to `original` when no partial line is held, since there is nothing to print above a frame. Ending
+   * `writable` flushes the held text, so a writer's last line with no line break is printed, not lost. A line's own cursor
+   * movements still tear the frame; `carriageReturn: "last"` keeps only what a progress bar redrawn with `\r` would
+   * have shown.
+   *
+   * The returned `writable` reports the original's `isTTY`, `columns`, `rows`, `getColorDepth`, `hasColors` and
+   * `getWindowSize` where the original has them. A printer that throws fails the write. Node only, as `./ui` is.
+   *
+   * @example
+   * ```ts
+   * const view = CliUi.liveDetached(options, env)
+   * const routed = CliUi.routeStream(process.stderr, view.printAbove, { stream: "stderr" })
+   * runner.errorStream = routed.writable
+   * // ...at the end
+   * routed.flush()
+   * await view.close()
+   * ```
+   *
+   * @param original - the stream the writer would have written to
+   * @param printer - where each line is offered first: `true` when it printed it, `false` with nothing written
+   * @param options - the printer's stream, the hold limit, carriage returns and a text tap
+   * @throws RangeError when `maxHeld` is not a non-negative integer
+   */
+  static readonly routeStream: (original: NodeJS.WritableStream, printer: (stream: "stdout" | "stderr", line: string) => boolean, options: RouteStreamOptions) => RoutedStream;
   /**
    * Run `screen` from a handler when the run is interactive; otherwise answer with `otherwise`, or fail with
    * `NotInteractive` when there is none.
@@ -908,7 +1105,7 @@ interface DocViewProps {
   /**
    * The render context. Omitted, it is built from the tree's theme (`useTheme`): its colour, its `paint` (token
    * overrides included) and its glyphs, the width `useTerminalSize().columns`, a human audience, links off, the
-   * identity `displayPath`, and `neutralizeWorkflowCommands` when the tree is under the GitHub Actions runner. Given,
+   * run's `displayPath` (the identity outside `CliRuntime.main`'s `env`), and `neutralizeWorkflowCommands` when the tree is under the GitHub Actions runner. Given,
    * it replaces that context entirely, neutralizing included (set `neutralizeWorkflowCommands` on it when the runner
    * reads the output), and the view needs no provider.
    */
@@ -1786,5 +1983,5 @@ export declare const Styled: (props: StyledProps) => ReactElement;
  * @public
  */
 export declare const useTerminalSize: () => TerminalSize;
-export type { Binding, CliUiFallbackOptions, CliUiPromptOptions, CliUiRunOptions, ConfirmAction, ConfirmInitOptions, ConfirmResult, ConfirmScreenOptions, ConfirmState, ConfirmToggle, ConfirmViewProps, DocViewProps, InkTextProps, KeyHelpProps, KeyHelpRow, KeyName, LiveHandle, LiveOptions, MultiSelectAction, MultiSelectInitOptions, MultiSelectItem, MultiSelectScreenOptions, MultiSelectSection, MultiSelectState, MultiSelectViewProps, Screen, ScreenControl, SelectAction, SelectChoice, SelectInitOptions, SelectScreenOptions, SelectState, SelectViewProps, StyledProps, Tab, TabsAction, TabsProps, TerminalSize, TextInputInitOptions, TextInputScreenOptions, TextInputState, TextInputViewProps, ToggleViewProps, UiContextValue, UiProviderProps, UiStreamsShape, UseKeysOptions, ViewportMove, ViewportRow, ViewportState, ViewportViewProps };
+export type { Binding, CliUiFallbackOptions, CliUiPromptOptions, CliUiRunOptions, ConfirmAction, ConfirmInitOptions, ConfirmResult, ConfirmScreenOptions, ConfirmState, ConfirmToggle, ConfirmViewProps, DetachedLive, DetachedLiveOptions, DocViewProps, InkTextProps, KeyHelpProps, KeyHelpRow, KeyName, LiveHandle, LiveOptions, MultiSelectAction, MultiSelectInitOptions, MultiSelectItem, MultiSelectScreenOptions, MultiSelectSection, MultiSelectState, MultiSelectViewProps, RouteStreamOptions, RoutedStream, Screen, ScreenControl, SelectAction, SelectChoice, SelectInitOptions, SelectScreenOptions, SelectState, SelectViewProps, StyledProps, Tab, TabsAction, TabsProps, TerminalSize, TextInputInitOptions, TextInputScreenOptions, TextInputState, TextInputViewProps, ToggleViewProps, UiContextValue, UiProviderProps, UiStreamsShape, UseKeysOptions, ViewportMove, ViewportRow, ViewportState, ViewportViewProps };
 //# sourceMappingURL=ui.d.ts.map