/** * 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