@effected/cli 0.10.0 → 0.12.0

package/testing.d.ts

@@ -1,4 +1,4 @@
-import { Effect, FileSystem, Path, PlatformError, Scope } from "effect";
+import { Effect, FileSystem, Layer, Path, PlatformError, Scope, Terminal } from "effect";
 import { ChildProcessSpawner } from "effect/process";
 //#region src/CliTest.d.ts
 /**
@@ -57,6 +57,22 @@ interface RunResult {
 /**
  * Spawn a built CLI bin hermetically and read its exit code and streams as data.
  *
+ * @example
+ * ```ts
+ * import * as NodeServices from "@effect/platform-node/NodeServices"
+ * import { assert, it } from "@effect/vitest"
+ * import { CliTest } from "@effected/cli/testing"
+ * import { Effect } from "effect"
+ *
+ * it.effect("prints its version", () =>
+ *   Effect.gen(function* () {
+ *     const sandbox = yield* CliTest.sandbox({ path: process.env.PATH ?? "" })
+ *     const result = yield* CliTest.run("dist/bin.js", ["--version"], { sandbox, execPath: process.execPath })
+ *     assert.strictEqual(result.exitCode, 0)
+ *   }).pipe(Effect.scoped, Effect.provide(NodeServices.layer)),
+ * )
+ * ```
+ *
  * @public
  */
 export declare class CliTest {
@@ -90,5 +106,75 @@ export declare class CliTest {
   static readonly run: (bin: string, args: ReadonlyArray<string>, options: RunOptions) => Effect.Effect<RunResult, PlatformError.PlatformError, ChildProcessSpawner.ChildProcessSpawner>;
 }
 //#endregion
-export type { RunOptions, RunResult, Sandbox };
+//#region src/TestTerminal.d.ts
+/**
+ * One key press for {@link TestTerminal}.
+ *
+ * @public
+ */
+interface KeyInput {
+  /** The key name the prompts switch on: `down`, `up`, `enter`, `space`, `escape`, or a character. */
+  readonly name: string;
+  /** Whether Ctrl is held. */
+  readonly ctrl?: boolean | undefined;
+  /** Whether Meta is held. */
+  readonly meta?: boolean | undefined;
+  /** Whether Shift is held. */
+  readonly shift?: boolean | undefined;
+}
+/**
+ * What {@link TestTerminal.make} builds: the `Terminal` layer and the means to drive and inspect it.
+ *
+ * @public
+ */
+interface TestTerminalHandle {
+  /** Provides `Terminal` backed by this double. */
+  readonly layer: Layer.Layer<Terminal.Terminal>;
+  /** Queue key presses, as if the user had typed them. */
+  readonly input: (keys: ReadonlyArray<KeyInput>) => Effect.Effect<void>;
+  /** Queue `text` one character at a time. */
+  readonly type: (text: string) => Effect.Effect<void>;
+  /** End the input, as Ctrl-C or end-of-file does: a prompt waiting for a key is quit. */
+  readonly end: Effect.Effect<void>;
+  /** Everything written to the terminal so far, prompt frames and escape codes included. */
+  readonly output: Effect.Effect<string>;
+  /** How many queued key presses nobody has taken yet. */
+  readonly pending: Effect.Effect<number>;
+  /**
+   * What the program did with the input: `keys` taken from it, `lines` read with `readLine`, and
+   * `subscriptions` to `readInput`. All `0` proves a code path never touched the terminal's input. Counting the
+   * subscription matters: on a real terminal merely subscribing attaches a reader to stdin, even when no key is
+   * ever taken.
+   */
+  readonly reads: Effect.Effect<{
+    readonly keys: number;
+    readonly lines: number;
+    readonly subscriptions: number;
+  }>;
+}
+/**
+ * A scripted `Terminal` for testing prompts and anything that reads the terminal.
+ *
+ * @remarks
+ * Queue keys with `input` or `type`, run the program under `layer`, then read `output`. To assert that a code path
+ * did NOT touch the terminal, queue some keys first and check `reads` is all zero (no subscription, no key, no
+ * line) and `pending` is unchanged afterwards. Only
+ * available from `@effected/cli/testing`.
+ *
+ * @public
+ */
+export declare class TestTerminal {
+  private constructor();
+  /**
+   * Build a test terminal.
+   *
+   * @param options - the reported size; 80 by 24 by default
+   */
+  static readonly make: (options?: {
+    readonly columns?: number | undefined;
+    readonly rows?: number | undefined;
+  }) => Effect.Effect<TestTerminalHandle>;
+}
+//#endregion
+export type { KeyInput, RunOptions, RunResult, Sandbox, TestTerminalHandle };
 //# sourceMappingURL=testing.d.ts.map

package/testing.js

@@ -1,3 +1,4 @@
 import { CliTest } from "./CliTest.js";
+import { TestTerminal } from "./TestTerminal.js";
 
-export { CliTest };
+export { CliTest, TestTerminal };

package/ui/CliUi.js

@@ -0,0 +1,432 @@
+import { Cancelled } from "../Cancelled.js";
+import { CliInteractive } from "../CliInteractive.js";
+import { underGithubActions } from "../internal/autoFormat.js";
+import { CliTheme } from "../CliTheme.js";
+import { NotInteractive } from "../NotInteractive.js";
+import { answerWithoutPerson } from "../internal/fallbackAnswer.js";
+import { inkModules, loadInk, withInkColour } from "./internal/ink.js";
+import { errorBoundary } from "./internal/ErrorBoundary.js";
+import { UiStreams } from "./UiStreams.js";
+import { lazyView } from "./internal/lazyView.js";
+import { mountPermit } from "./internal/mountPermit.js";
+import { UiRenderOptions } from "./internal/renderOptions.js";
+import { useScreenGuard } from "./internal/ScreenContext.js";
+import { uiProviders } from "./internal/UiProviders.js";
+import { live } from "./CliUiLive.js";
+import { KeyTable, useKeys } from "./KeyTable.js";
+import { Cause, Deferred, Effect, Exit, Option, Semaphore } from "effect";
+import { Audience } from "@effected/env";
+import { Prompt } from "effect/cli";
+
+//#region src/ui/CliUi.ts
+/**
+* stdout's theme as the audience sees it: colourless for an agent (as `Render.context` makes it), so a screen's
+* `useTheme`, `Styled` and the widgets' colour-none markers never carry an escape for one. `Audience` is read only when
+* provided, so it stays out of the requirements.
+*/
+const audienceTheme = Effect.gen(function* () {
+	const audience = yield* Effect.serviceOption(Audience);
+	return CliTheme.forAudience((yield* CliTheme).forStream("stdout"), Option.isSome(audience) ? audience.value.kind : void 0);
+});
+/** The root keys: Esc cancels with `"escape"`, Ctrl-C with `"interrupt"`. `q` belongs to widgets, never here. */
+const RootKeys = (props) => {
+	useKeys(KeyTable.root, props.cancel);
+	const guard = useScreenGuard();
+	inkModules().ink.usePaste(guard(() => void 0));
+	return props.children;
+};
+const SCREEN_EXITED = "@effected/cli/ui: the screen exited without resolving or cancelling";
+const mount = (screen, theme, clear, crash, neutralize) => Effect.gen(function* () {
+	const overrides = yield* UiRenderOptions;
+	yield* Effect.acquireRelease(Effect.sync(() => overrides.onMount?.("screen")), (_, exit) => Effect.sync(() => {
+		const died = Exit.isFailure(exit) ? exit.cause.reasons.find(Cause.isDieReason) : void 0;
+		const interrupted = Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause);
+		overrides.onUnmount?.(died !== void 0 ? { defect: died.defect } : interrupted ? void 0 : crash.current);
+	}));
+	const { ink, react } = yield* loadInk;
+	const streams = yield* UiStreams;
+	yield* withInkColour(theme.color);
+	const result = yield* Deferred.make();
+	const control = {
+		resolve: (value) => {
+			Deferred.doneUnsafe(result, Exit.succeed(value));
+		},
+		cancel: (reason) => {
+			Deferred.doneUnsafe(result, Exit.fail(new Cancelled({ reason })));
+		}
+	};
+	const element = yield* Effect.promise(async () => screen(control));
+	const die = (error) => {
+		if (crash.current === void 0) crash.current = { defect: error };
+		Deferred.doneUnsafe(result, Exit.die(error));
+	};
+	const tree = react.createElement(errorBoundary(), {
+		onError: die,
+		children: uiProviders({
+			cancel: control.cancel,
+			die,
+			theme,
+			glyphs: theme.glyphs,
+			...neutralize ? { neutralizeWorkflowCommands: true } : {}
+		}, react.createElement(RootKeys, {
+			cancel: control.cancel,
+			children: element
+		}))
+	});
+	const instance = yield* Effect.acquireRelease(Effect.sync(() => ink.render(tree, {
+		stdin: streams.stdin,
+		stdout: streams.stdout,
+		stderr: streams.stderr,
+		interactive: true,
+		exitOnCtrlC: false,
+		patchConsole: false,
+		...overrides.debug === true ? { debug: true } : {},
+		...overrides.onRender === void 0 ? {} : { onRender: overrides.onRender },
+		...overrides.maxFps === void 0 ? {} : { maxFps: overrides.maxFps }
+	})), (instance) => Effect.promise(async () => {
+		if (clear) instance.clear();
+		const exited = instance.waitUntilExit();
+		instance.unmount();
+		await exited.catch(() => void 0);
+	}));
+	const exited = Effect.tryPromise({
+		try: () => instance.waitUntilExit(),
+		catch: (cause) => cause
+	}).pipe(Effect.orDie, Effect.flatMap(() => Effect.flatMap(Deferred.isDone(result), (done) => done ? Deferred.await(result) : Effect.die(/* @__PURE__ */ new Error(SCREEN_EXITED)))));
+	return yield* Effect.raceFirst(Deferred.await(result), exited);
+});
+/**
+* Interactive screens drawn with Ink, mounted as scoped resources.
+*
+* @example
+* ```ts
+* import { CliUi, Confirm } from "@effected/cli/ui"
+* import { Effect } from "effect"
+*
+* // Answers `otherwise` when there is no person to ask, and fails with `Cancelled` when they back out.
+* const ask = CliUi.prompt(Confirm.screen({ message: "Overwrite the config?" }), {
+* 	otherwise: { confirmed: false, toggles: {} },
+* })
+* ```
+*
+* @public
+*/
+var CliUi = class CliUi {
+	constructor() {}
+	/**
+	* Mount `screen` and wait for it to resolve or cancel.
+	*
+	* @remarks
+	* When `CliInteractive` is false it fails with `NotInteractive` and mounts nothing; Ink and React are not even
+	* loaded. Otherwise it loads them, holds Ink's colour level at stdout's, and mounts the screen on
+	* `UiStreams` with Ink's own Ctrl-C exit off: Ctrl-C cancels with `"interrupt"` and Esc with `"escape"`.
+	*
+	* Mounting is one scoped resource. However the screen ends (resolved, cancelled, crashed, or the fiber
+	* interrupted), it is unmounted, raw mode and bracketed paste are off, the cursor is shown, and the colour level is
+	* restored. A
+	* component that throws is a defect, never a hang or a typed failure, and nothing of Ink's crash screen reaches
+	* stdout. So is a `useKeys` handler that throws; a handler a consumer registers with Ink's own `useInput` or
+	* `usePaste` is outside the kit, and what it throws escapes as Ink leaves it. A crash wins over an end in the same
+	* tick: a handler that cancels or resolves and then throws, or a component that throws before the screen has
+	* unmounted, is a defect, never the `Cancelled` or the value; a defect raised while the screen unmounts stays beside
+	* that crash in the cause rather than replacing it. An interrupt stays an interrupt, even when the tree reports a
+	* crash as it unmounts.
+	*
+	* A screen draws on stdout (`UiStreams`), and mounts only when `CliInteractive` is true: a human audience, a
+	* terminal on both stdin and stdout, and a `TERM` that is not `dumb`. `CliInteractive` reads `false` until a layer
+	* sets it (`CliRuntime.main`'s `env` does), so a program that never provides one always gets `NotInteractive`.
+	*
+	* Screens run one at a time, process-wide: Ink owns raw mode on the one terminal, so a second `run` waits until the
+	* first is released; so does a `run` while a {@link CliUi.live} view has a run drawn. A screen that itself awaits
+	* another `CliUi.run` therefore deadlocks, and nothing guards against it.
+	*
+	* Do not log while a screen is mounted. Ink redraws its frame by counting the lines it last wrote, and it is
+	* mounted with `patchConsole` off, so a line written to the terminal from elsewhere (an `Effect.log`, `CliLog`, a
+	* background fiber) lands inside the frame and tears it. Log before the screen mounts or after it resolves.
+	*
+	* With `clear` the last frame is erased as the screen unmounts, so a wizard of several screens leaves only what the
+	* program prints; without it the last frame stays, with the highlight where the answer was.
+	*
+	* @param screen - builds the element to mount from its {@link ScreenControl}
+	* @param options - whether to erase the last frame
+	*/
+	static run = (screen, options) => Effect.gen(function* () {
+		if (!(yield* CliInteractive)) return yield* Effect.fail(new NotInteractive());
+		const theme = yield* audienceTheme;
+		const neutralize = yield* underGithubActions;
+		const crash = { current: void 0 };
+		const exit = yield* Effect.exit(Semaphore.withPermit(mountPermit, Effect.scoped(mount(screen, theme, options?.clear === true, crash, neutralize))));
+		const crashed = crash.current;
+		const interrupted = Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause);
+		if (crashed === void 0 || interrupted) return yield* exit;
+		const dies = Exit.isFailure(exit) ? exit.cause.reasons.filter(Cause.isDieReason) : [];
+		if (dies.some((reason) => reason.defect === crashed.defect)) return yield* exit;
+		return yield* Effect.failCause(Cause.fromReasons([Cause.makeDieReason(crashed.defect), ...dies]));
+	});
+	/**
+	* The kit's context for an Ink tree the kit did not mount: stdout's theme and glyph set.
+	*
+	* @remarks
+	* Hand it to {@link UiProvider}. It loads Ink and React, as a screen's mount does, so the provider and the kit's
+	* hooks can render; a missing peer is a defect naming both. It is the only way to get a `UiContextValue`.
+	*
+	* Ink loads asynchronously, so this is an `Effect` that must run before the first render. A renderer that is itself
+	* synchronous (a test helper, a report-time `renderToString`) runs it once, with a top-level `await` at module
+	* scope, and then renders synchronously from the value as often as it likes:
+	*
+	* ```ts
+	* const value = await Effect.runPromise(CliUi.context.pipe(Effect.provide(themeLayer)))
+	*
+	* // later, synchronously:
+	* const text = renderToString(createElement(UiProvider, { value: { ...value, size: { columns, rows } } }, tree), {
+	*   columns,
+	* })
+	* ```
+	*/
+	static context = Effect.gen(function* () {
+		const theme = yield* audienceTheme;
+		const neutralize = yield* underGithubActions;
+		yield* loadInk;
+		return {
+			"~@effected/cli/ui/UiContextValue": true,
+			theme,
+			glyphs: theme.glyphs,
+			...neutralize ? { neutralizeWorkflowCommands: true } : {}
+		};
+	});
+	/**
+	* A live view over a stream: fold `events` into state, and draw it with Ink while a run is going, for the caller's
+	* scope.
+	*
+	* @remarks
+	* `events` is a `PubSub` subscription or a stream, folded in a fiber of the caller's scope. A subscription, made
+	* before the first publish, is the surest: nothing published after it is missed. `live` makes a stream's first pull
+	* before it returns, so one that subscribes on its first pull without forking (`Stream.fromPubSub`) is subscribed by
+	* then; one that forks its upstream (`Stream.merge`, `buffer`, a concurrent `flatMap`) subscribes later, and loses
+	* what is published before.
+	*
+	* `live` returns its handle at once, before Ink has loaded: it loads Ink when a run first mounts (or, when not
+	* interactive, when an owned run without a `final` prints its final frame), and it waits on nothing asynchronous before returning, so
+	* a host outside Effect can take the handle with `Effect.runSync`. The handle works from the start: a `close`
+	* before any run has mounted folds what is queued and ends the view as the events ending would, waiting for a mount
+	* already under way, and one with no run to end loads nothing.
+	*
+	* End the view with `handle.close`: it stops taking events, folds what is still queued (a subscription's queued
+	* messages included), commits or prints the run as the events ending would, and waits for `done`. Then close the
+	* scope. A publisher may instead end a subscription with `PubSub.end(pubsub, last)`, which keeps everything: the view
+	* folds what is buffered and `last` once, then ends. A `PubSub.shutdown` drops what the view has not taken yet, and
+	* closing the scope by itself stops the fold at once: both lose a run's tail. Closing the scope unmounts whatever is drawn: the terminal is restored (the
+	* cursor shown, Ink's colour level put back) and nothing more is written. `done` completes when the events end.
+	*
+	* A run begins at an `isStart` event (or wherever `begins` says, given the state before and after the event) and ends
+	* at an `isTerminal` event; an event while no run is going that begins none is folded and not drawn, so what a program
+	* reports after a run ends never mounts a second copy of it. A run mounts the view; its end unmounts it, which leaves
+	* its last frame on the terminal, and the next run mounts afresh below it. A start while a run is drawn redraws in
+	* place: the frame is never cleared, so nothing above it is erased. The state is never reset by the kit: a reducer that wants a fresh run
+	* resets it on the start.
+	*
+	* The frame is at most the terminal's rows less one, re-read on every render and on a resize, so a tall frame never
+	* makes Ink wipe the scrollback; its width is Ink's own. The clamp
+	* lags one paint when the terminal gets shorter: Ink re-lays out and repaints the tree it already has on a resize,
+	* before React re-renders with the new row count, so a frame already at the old height can be drawn once taller
+	* than the terminal, which Ink answers by clearing the screen and its scrollback. Only a shrink in height while
+	* the frame is at its full height does it; a frame that keeps a few rows spare never meets it.
+	*
+	* While a run is drawn the view also redraws on a tick of `tickMillis` (80 by default), a schedule in the run's
+	* scope: interrupted with the run or the scope, it never outlives them. Its timer is not unref'd, so while a run is
+	* drawn it keeps the process alive: the run's terminal event, or the scope's close, is what lets the process exit.
+	* The frame index never steps back. Events that arrive at
+	* once, in one chunk or in several the view had not yet caught up with, are folded together and drawn once. The view
+	* takes events from `events` as fast as the stream yields them, so a stream that applies backpressure buffers in the
+	* view while it draws.
+	*
+	* A run whose drawing fails (a `render` that throws, or a mount that fails) degrades rather than ending the view:
+	* it is unmounted, leaving its last good frame on the terminal, then one warning is logged (`Effect.logWarning`),
+	* and the fold goes on. At its terminal event, a run with no frame left on the terminal (it never painted, or its
+	* last good frame threw too) writes its final frame once, as a string. The next run mounts afresh, and so does a
+	* start that comes while a degraded run is going: it ends that run as its terminal event would. A `reduce` that
+	* throws, or an `events` stream that dies, unmounts the run, then `done` dies with the error.
+	*
+	* When the run is not interactive, nothing is mounted and Ink is loaded only when a string is due. In the `owned`
+	* mode (the default) each run's final frame is written once to stdout, as a string laid out at stdout's width (80
+	* when it reports none) with no height to fit, at its terminal event or when the stream ends. It is escape-free at
+	* colour `none`, and for an agent audience (`Audience`, when provided) whatever the terminal could do. With a
+	* `final` document, that document is printed instead, once per run, rendered as `Doc.print` renders it, and Ink,
+	* React and a `CliUi.lazyView` module are never loaded: an agent, CI or piped run of a command with a live view pays
+	* for none of them. In the `hosted` mode nothing is written.
+	*
+	* Keep React off the runs that never draw (`--help`, a usage error) with `render: CliUi.lazyView(() => import(...))`.
+	*
+	* No input is mounted: the view reads no keys and never enters raw mode, so Ctrl-C stays the platform's SIGINT,
+	* which interrupts the program and so closes the scope. Each run holds the process-wide mount permit from its
+	* mount to its end, so a `CliUi.run` during a run waits for the run to end, and one between runs mounts at once.
+	*
+	* While a run is drawn, write logs through `logConsole`, provided around the work the view reports on: its lines
+	* land above the frame. A line written to the terminal any other way tears the frame.
+	*
+	* The view draws on stdout (`UiStreams`), at stdout's colour level and glyphs, and mounts only when the run is
+	* interactive (`CliInteractive`).
+	*
+	* @param options - the events, the fold, the drawing, and what starts and ends a run
+	*/
+	static live = live;
+	/**
+	* Run `screen` from a handler when the run is interactive; otherwise answer with `otherwise`, or fail with
+	* `NotInteractive` when there is none.
+	*
+	* @remarks
+	* `CliUi.run` with a default: not interactive, it returns `otherwise` and Ink and React are never loaded.
+	* Interactive, it mounts the screen, and a cancel is the typed `Cancelled` a handler can catch, which
+	* `CliRuntime.main` otherwise renders as one line with exit `130`. A missing Ink in an interactive run is a defect
+	* naming the peers, never a silent `otherwise`. Screens in sequence make a wizard: discover the defaults first,
+	* pass each as an `otherwise`, and a non-interactive run returns exactly them.
+	*
+	* Without `otherwise`, `NotInteractive` stays in the error type even after the caller checked `CliInteractive`, since
+	* the type cannot know. Catch the tag and fail with `CliError.UserError` to exit as a usage error (`64` under
+	* `CliRuntime.main`).
+	*
+	* As with `CliUi.run`, do not log while the screen is mounted: a line written to the terminal from elsewhere tears
+	* the frame.
+	*
+	* @param screen - the screen to show
+	* @param options - the non-interactive default, and whether to erase the last frame
+	*/
+	static prompt = (screen, options) => CliUi.run(screen, options?.clear === true ? { clear: true } : void 0).pipe(Effect.catchTag("NotInteractive", (error) => {
+		const otherwise = options?.otherwise;
+		return otherwise === void 0 ? Effect.fail(error) : Effect.succeed(otherwise);
+	}));
+	/**
+	* A fallback for `Flag.withFallbackPrompt` or `Argument.withFallbackPrompt` that shows a screen when the run is
+	* interactive: `CliPrompt.fallback` for screens.
+	*
+	* @remarks
+	* Interactive, the screen mounts and its answer is the parameter's value. Not interactive, `otherwise` is used when
+	* given and Ink and React are never loaded; without it the parameter fails as missing, exactly as with no fallback,
+	* so core renders its own message and `CliRuntime.main` exits `64`. Name the parameter with `flag` (the name
+	* without dashes) or `argument` so that error can be built.
+	*
+	* The options are {@link @effected/cli!CliPromptFallbackOptions}, the same as `CliPrompt.fallback`'s, and `clear`
+	* as for {@link CliUi.run}.
+	*
+	* 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`.
+	*
+	* 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`,
+	* raised as a defect because core's parse step turns every typed failure into a usage error, so only
+	* `CliRuntime.main` (or `CliRuntime.reportFailures`) renders it, as one line with exit `130`. A missing Ink in an
+	* interactive run is a defect naming the peers, never a silent `otherwise`.
+	*
+	* After the screen has unmounted, core still runs the answered `Prompt.succeed` it is handed against the
+	* terminal, exactly as it does for `CliPrompt.fallback`: `Prompt.run` opens the terminal's input in a scope (on
+	* Node a readline over stdin, in raw mode) before looking at the prompt. That is harmless. The prompt is already
+	* answered, so nothing is read and no key is waited for; the scope closes at once, restoring the mode and closing
+	* the reader; and Ink has already let go of stdin, so the two never hold it together. Not interactive, the screen
+	* never mounts, and `CliPrompt.gateTerminal`, which `CliEnv.layer` installs, keeps that subscription off the real
+	* terminal altogether.
+	*
+	* @param screen - the screen to show
+	* @param options - the parameter it stands in for, the non-interactive default, and whether to erase the last frame
+	*/
+	static fallback = (screen, options) => {
+		let explained = false;
+		return Effect.gen(function* () {
+			const theme = yield* Effect.serviceOption(CliTheme);
+			if (Option.isNone(theme)) {
+				if (!explained && (yield* CliInteractive)) {
+					explained = true;
+					const name = "flag" in options ? `--${options.flag}` : `<${options.argument}>`;
+					yield* Effect.logDebug(`@effected/cli/ui: CliUi.fallback for ${name} answered without its screen: CliInteractive is on, but no CliTheme is provided around parsing (CliRuntime.main's env provides one)`);
+				}
+				return yield* answerWithoutPerson(options);
+			}
+			return yield* CliUi.run(screen, options.clear === true ? { clear: true } : void 0).pipe(Effect.provideService(CliTheme, theme.value), Effect.map((answer) => Prompt.succeed(answer)), Effect.catchTag("Cancelled", (cancelled) => Effect.die(cancelled)), Effect.catchTag("NotInteractive", () => answerWithoutPerson(options)));
+		});
+	};
+	/**
+	* A screen whose module is loaded only when it mounts, so importing the command that uses it loads neither the
+	* screen's own code nor React.
+	*
+	* @param load - imports the module whose default export is the screen
+	*/
+	static lazy = (load) => async (control) => (await load()).default(control);
+	/**
+	* A live view's `render` whose module is loaded only when a run first draws it, so importing the command that uses
+	* the view loads neither the view's own code nor React: `CliUi.lazy` for `CliUi.live`.
+	*
+	* @remarks
+	* `load` resolves to the view, `(state, frame) => ReactElement`, exactly what `render` takes, so the frame index a
+	* spinner needs reaches it: either a module whose default export is the view (`() => import("./view.js")`), or the
+	* view itself (`() => import("./views.js").then((module) => module.syncView)`, for a named export).
+	*
+	* It is optional: `render` still takes the view directly, and needs no dynamic import. A view passed directly
+	* loads with the module that imports it, so it costs React on every run that loads that module; `lazyView` is
+	* how a command keeps React off the runs that never draw. `CliUi.live` loads the module before a run mounts with Ink, or before it
+	* prints a run's final frame as a string; a run that is not interactive and has a `final` document never loads it,
+	* nor Ink, nor React. An import that fails degrades the run, as a render that throws does: one warning, and the next
+	* run tries the import again. A load that resolves to no view (neither a function nor a module whose `default` is
+	* one) is a programming error, and deterministic, so it is kept for the view's life: every run degrades without
+	* loading again, and the view warns once, saying what it received and what is expected, rather than once per run. A
+	* view function that happens to carry a `default` property is the view.
+	*
+	* The returned function is for `CliUi.live`'s `render` alone: called before its module has loaded, it throws.
+	*
+	* Keep the `LiveOptions` (the state, the events and the `lazyView` call) in a module the view does not import. The
+	* view module usually imports the state's types or its fold from somewhere; if that somewhere is the module that
+	* holds the `import("./view.js")`, the dynamic import closes a cycle, which Biome's `noImportCycles` reports even
+	* though it is lazy. A layout that stays acyclic: the model (state, events, fold) in one module, the view importing
+	* the model, and the options (with `lazyView`) in a third that imports the model and loads the view.
+	*
+	* ```ts
+	* // commands/sync.ts: no JSX, no React
+	* const view = yield* CliUi.live({
+	*   events,
+	*   initial,
+	*   reduce,
+	*   render: CliUi.lazyView(() => import("./sync-view.js")),
+	*   final: (state) => [Doc.paragraph(`${state.done} synced`)],
+	*   isStart,
+	*   isTerminal,
+	* })
+	* ```
+	*
+	* @param load - resolves to the view, or to a module whose default export is the view
+	*/
+	static lazyView = lazyView;
+	/**
+	* A screen whose answer is `f` of `screen`'s: it mounts `screen` and resolves with `f(value)` when `screen` resolves
+	* with `value`.
+	*
+	* @remarks
+	* Only the resolve is mapped. A cancel passes through unchanged, as the same `Cancelled`, and so does everything
+	* else about the screen: what it draws, its keys, a lazy load. `f` runs when the screen resolves; what it throws is
+	* thrown from the screen's resolve, so it is a defect of the run, as any other throw in a key handler is.
+	*
+	* The mapped screen is a `Screen` like any other, so it goes wherever a screen goes: `CliUi.run`, `CliUi.prompt`,
+	* `CliUi.fallback`, or around a `CliUi.lazy` one. The commonest use is a `Confirm` behind a boolean flag, where the
+	* fallback needs a `Screen<boolean>` and `Confirm` answers a whole `ConfirmResult`:
+	*
+	* ```ts
+	* const yes = Flag.Boolean("yes").pipe(
+	*   Flag.withFallbackPrompt(
+	*     CliUi.fallback(
+	*       CliUi.map(Confirm.screen({ message: "Publish?" }), (result) => result.confirmed),
+	*       { flag: "yes", otherwise: false },
+	*     ),
+	*   ),
+	* )
+	* ```
+	*
+	* @param screen - the screen to show
+	* @param f - turns its answer into the mapped screen's
+	*/
+	static map = (screen, f) => (control) => screen({
+		resolve: (value) => control.resolve(f(value)),
+		cancel: control.cancel
+	});
+};
+
+//#endregion
+export { CliUi };