/**
* The capability to talk to the human driving this process.
*
* One contract, two renderers:
*
* - {@link layerSigil} — the interactive Sigil renderer: live rows,
* prompts as real screens, full-screen sessions.
* - {@link layerNonInteractive} — append-only plain output for CI, piped
* output, the Alchemist API and tests. Views print once, every prompt,
* screen and session fails with the typed {@link NonInteractiveTerminal}.
*
* {@link layer} picks between them from the terminal's capabilities, so
* callers never branch on the renderer themselves.
*
* Child processes (the RPC sidecar, spawned dev children) deliberately do
* NOT provide this service at all — interaction capability is structural,
* not configured. Code that might need a human declares it; a process that
* cannot reach one simply doesn't have the service in its graph.
*/
import * as Cause from "effect/Cause";
import * as Context from "effect/Context";
import * as Effect from "effect/Effect";
import * as Layer from "effect/Layer";
import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
import type * as Scope from "effect/Scope";
import type { ReactNode } from "react";
import { UserFacingError } from "./UserFacingError.ts";
declare const TerminalCancelled_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
readonly _tag: "TerminalCancelled";
} & Readonly;
/** The user dismissed the active terminal interaction. */
export declare class TerminalCancelled extends TerminalCancelled_base {
}
declare const NonInteractiveTerminal_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
readonly _tag: "NonInteractiveTerminal";
} & Readonly;
/** An interactive operation was requested without an interactive terminal. */
export declare class NonInteractiveTerminal extends NonInteractiveTerminal_base<{
readonly operation: string;
readonly message: string;
}> {
readonly [UserFacingError] = true;
}
declare const BrowserOpenFailed_base: new = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
readonly _tag: "BrowserOpenFailed";
} & Readonly;
/** The platform's browser launcher exited unsuccessfully. */
export declare class BrowserOpenFailed extends BrowserOpenFailed_base<{
readonly command: string;
readonly exitCode: number;
}> {
}
export type InteractionError = TerminalCancelled | NonInteractiveTerminal;
export interface MessageOptions {
readonly message: string;
readonly detail?: string;
}
export interface TextInputOptions {
readonly message: string;
/** Secondary guidance rendered beneath the field in muted text. */
readonly description?: string;
/** Place the editable field beside the message or beneath it. @default "inline" */
readonly layout?: "inline" | "stacked";
readonly placeholder?: string;
readonly initialValue?: string;
readonly defaultValue?: string;
readonly validate?: (value: string) => string | Error | undefined;
}
export interface PasswordInputOptions extends Omit {
}
export interface ConfirmOptions {
readonly message: string;
readonly initialValue?: boolean;
readonly confirmLabel?: string;
readonly cancelLabel?: string;
}
export interface Choice {
readonly value: Value;
readonly label: string;
/** Optional section heading shared by adjacent choices. */
readonly group?: string;
/** Indent the entire rendered row, including its selection indicator. */
readonly indent?: number;
/** Keep this row visible as the heading for following rows while scrolling. */
readonly sticky?: boolean;
/** Visually distinguish structural rows from ordinary choices. */
readonly tone?: "info";
readonly description?: string;
readonly disabled?: boolean | string;
}
export interface SelectOptions {
readonly message: string;
readonly options: ReadonlyArray>;
readonly initialValue?: Value;
readonly visibleCount?: number;
/** Allow typing to filter choices by label and description. */
readonly searchable?: boolean;
/** Place descriptions beside labels instead of on a second line. */
readonly descriptionPlacement?: "below" | "inline";
}
export interface MultiSelectOptions extends Omit, "initialValue"> {
readonly initialValues?: ReadonlyArray;
readonly required?: boolean;
}
export interface BrowserLoginOptions {
/** Display name, e.g. `"Railway"`; titles the login. */
readonly provider: string;
/** The page the user logs in on. Opened in their browser for them. */
readonly url: string;
/** Short code the user confirms on the login page (device flows). */
readonly code?: string;
/** @default "waiting for browser authorization (up to 5 minutes)…" */
readonly waitingLabel?: string;
/** Completes the login: a token poll, a CLI process, an OAuth callback. */
readonly waitFor: Effect.Effect;
/** Let the user paste a code instead, exchanged for the same result. */
readonly manualCode?: {
readonly label?: string;
readonly placeholder?: string;
readonly validate?: (value: string) => string | Error | undefined;
readonly exchange: (code: string) => Effect.Effect;
};
}
export interface ProgressOptions {
readonly label: string;
readonly detail?: string;
/** Terminal window title while this progress view is active. */
readonly title?: string;
/** Animate the leading status glyph. @default true */
readonly spinning?: boolean;
}
/** A composable layout. Views are inert; only a renderer draws them. */
export type View = ReactNode;
/** What the terminal behind this process can do. */
export interface TerminalCapabilities {
/** Whether this process has usable terminal input for prompts and sessions. */
readonly input: boolean;
readonly columns: number;
readonly rows: number;
readonly colors: boolean;
readonly unicode: boolean;
/** Whether full-screen sessions may use the terminal's alternate buffer. */
readonly alternateScreen: boolean;
}
export interface ScreenController {
readonly submit: (value: Value, summary?: View) => void;
readonly cancel: () => void;
}
/**
* An interactive scene. The scene owns its local component state while the
* renderer owns input streams, serialization, rendering and teardown. Every
* prompt is a screen; {@link Interaction} `prompt.screen` runs any other.
*/
export interface Screen {
readonly name: string;
readonly render: (controller: ScreenController) => View;
}
export declare const Screen: {
make: (name: string, render: (controller: ScreenController) => View) => Screen;
};
/**
* Handle for a progress row. Acquired within a `Scope`: the enclosing
* scope's close is a release backstop, so an interrupted fiber can never leave
* an orphaned row pinning the renderer. Settling early via `succeed`/`fail`/
* `close` is the normal path; every settle operation is idempotent.
*/
export interface ProgressHandle {
readonly update: (options: ProgressOptions) => Effect.Effect;
readonly succeed: (message?: string) => Effect.Effect;
readonly fail: (message?: string) => Effect.Effect;
readonly close: Effect.Effect;
}
/**
* A mounted live view. The view itself is immutable — dynamic content flows
* through a caller-owned store that its component subscribes to — so the
* handle only controls the block's lifetime. Scope-bound the same way as
* {@link ProgressHandle}; `close` settles early and is idempotent.
*/
export interface LiveViewHandle {
readonly close: Effect.Effect;
}
export interface LiveViewOptions {
/** Place a session shell/header before completed prompt output. */
readonly placement?: "beforeTranscript" | "afterTranscript";
/** Commit the final view to the static transcript when it closes. */
readonly persistOnClose?: boolean;
}
export interface SessionOptions {
/** Take over the terminal's alternate screen buffer when supported. */
readonly alternate?: boolean;
}
declare const Interaction_base: Context.ServiceClass Effect.Effect;
readonly info: (message: string | MessageOptions) => Effect.Effect;
readonly success: (message: string | MessageOptions) => Effect.Effect;
readonly warning: (message: string | MessageOptions) => Effect.Effect;
readonly error: (message: string | MessageOptions) => Effect.Effect;
};
readonly prompt: {
readonly text: (options: TextInputOptions) => Effect.Effect;
readonly password: (options: PasswordInputOptions) => Effect.Effect;
readonly confirm: (options: ConfirmOptions) => Effect.Effect;
readonly select: (options: SelectOptions) => Effect.Effect;
readonly multiSelect: (options: MultiSelectOptions) => Effect.Effect, InteractionError>;
/** Run an arbitrary interactive screen. */
readonly screen: (screen: Screen) => Effect.Effect;
};
/**
* Log the user in through their browser: open `url`, show it (and the
* device code), and wait for `waitFor`. Fails with `TerminalCancelled`
* when the user dismisses the login.
*/
readonly browserLogin: (options: BrowserLoginOptions) => Effect.Effect;
/**
* Mount a live layout while the scope is open. Without an interactive
* renderer the view prints once.
*/
readonly live: (view: View, options?: LiveViewOptions) => Effect.Effect;
/** Add a mutable progress row, settled through its handle. */
readonly progress: (options: ProgressOptions) => Effect.Effect;
/** Run work behind a progress row and collapse it to a final status line. */
readonly task: (options: ProgressOptions, effect: Effect.Effect) => Effect.Effect;
/**
* Keep one renderer alive while an Effect drives screens and prompts. A
* nested session reuses the outer renderer and clears the prompts it
* showed when it settles.
*/
readonly session: (effect: Effect.Effect, options?: SessionOptions) => Effect.Effect;
}>;
/**
* The capability to ask or tell the human driving this process. Provided
* by {@link layer}; never provided in child processes.
*/
export declare class Interaction extends Interaction_base {
}
export declare const print: (view: View) => Effect.Effect;
export declare const info: (message: string | MessageOptions) => Effect.Effect;
export declare const success: (message: string | MessageOptions) => Effect.Effect;
export declare const warning: (message: string | MessageOptions) => Effect.Effect;
export declare const error: (message: string | MessageOptions) => Effect.Effect;
export declare const text: (options: TextInputOptions) => Effect.Effect;
export declare const password: (options: PasswordInputOptions) => Effect.Effect;
export declare const confirm: (options: ConfirmOptions) => Effect.Effect;
export declare const select: (options: SelectOptions) => Effect.Effect;
export declare const multiSelect: (options: MultiSelectOptions) => Effect.Effect;
export declare const browserLogin: (options: BrowserLoginOptions) => Effect.Effect;
export declare const screen: (scene: Screen) => Effect.Effect;
/**
* `task` for any renderer: a scoped progress row settled by the effect's
* exit. Interruption (Ctrl+C) is not a failure — the row is dropped instead
* of painted as an error.
*/
export declare const taskFromProgress: (progress: Interaction["Service"]["progress"]) => Interaction["Service"]["task"];
/**
* Open a URL in the platform's default browser without invoking a shell.
*
* Fails with {@link BrowserOpenFailed} when the launcher exits non-zero (e.g.
* `xdg-open` with no handler installed). Some `xdg-open` configurations block
* until the browser itself exits — a launcher still running after a short
* grace period is treated as a successful launch rather than awaited.
*/
export declare const openUrl: (url: string) => Effect.Effect;
export interface TerminalOptions {
readonly stdin?: NodeJS.ReadStream;
readonly stdout?: NodeJS.WriteStream;
readonly stderr?: NodeJS.WriteStream;
/** Override automatic TTY input detection. Primarily useful for tests. */
readonly input?: boolean;
readonly colors?: boolean;
readonly unicode?: boolean;
/** Capture console output while the interactive renderer owns the tty. */
readonly captureConsole?: boolean;
}
export type NonInteractiveOptions = Pick & {
/**
* `--log-format json`: messages become log records (so the console's JSON
* sink prints them in the run log's envelope) and views print nothing, so
* the console carries JSON lines only.
*/
readonly json?: boolean;
};
export declare const makeNonInteractive: (options?: NonInteractiveOptions) => Interaction["Service"];
/**
* The append-only renderer: CI, redirected output, the programmatic engine
* API, tests, and any headless embedding. Messages print as plain status
* lines; every prompt fails immediately with the typed
* {@link NonInteractiveTerminal}.
*/
export declare const layerNonInteractive: (options?: NonInteractiveOptions) => Layer.Layer;
/**
* The interactive Sigil renderer, regardless of what the terminal reports.
* Prefer {@link layer}, which falls back to plain output without a TTY.
*/
export declare const layerSigil: (options?: TerminalOptions) => Layer.Layer;
/**
* The renderer this process's terminal supports: the interactive one when
* stdin and stdout are a TTY and nothing opted out (`--no-input`, CI, coding
* agents), plain output otherwise.
*/
export declare const layer: (options?: TerminalOptions) => Layer.Layer;
export {};
//# sourceMappingURL=Interaction.d.ts.map