/**
* 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 Data from "effect/Data";
import * as Effect from "effect/Effect";
import * as Exit from "effect/Exit";
import * as Layer from "effect/Layer";
import * as Option from "effect/Option";
import { ChildProcess } from "effect/process";
import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner";
import type * as Scope from "effect/Scope";
import type { ReactNode } from "react";
import { UserFacingError } from "./UserFacingError.ts";
import { ANSI_DIM, ANSI_RESET, ansiFg, colorsEnabled, unicodeEnabled } from "./Util/Terminal.ts";
import { glyphsFor, statusColor, type StatusVariant } from "./Util/Theme.ts";
/** The user dismissed the active terminal interaction. */
export class TerminalCancelled extends Data.TaggedError("TerminalCancelled") {}
/** An interactive operation was requested without an interactive terminal. */
export class NonInteractiveTerminal extends Data.TaggedError("NonInteractiveTerminal")<{
readonly operation: string;
readonly message: string;
}> {
readonly [UserFacingError] = true;
}
/** The platform's browser launcher exited unsuccessfully. */
export class BrowserOpenFailed extends Data.TaggedError("BrowserOpenFailed")<{
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<
TextInputOptions,
"initialValue" | "defaultValue"
> {}
export interface ConfirmOptions {
readonly message: string;
readonly initialValue?: boolean;
readonly confirmLabel?: string;
readonly cancelLabel?: string;
}
export interface Choice<Value> {
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<Value> {
readonly message: string;
readonly options: ReadonlyArray<Choice<Value>>;
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<Value> extends Omit<SelectOptions<Value>, "initialValue"> {
readonly initialValues?: ReadonlyArray<Value>;
readonly required?: boolean;
}
export interface BrowserLoginOptions<A, E, R, E2 = never, R2 = never> {
/** 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<A, E, R>;
/** 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<A, E2, R2>;
};
}
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<Value> {
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<Value> {
readonly name: string;
readonly render: (controller: ScreenController<Value>) => View;
}
export const Screen = {
make: <Value>(
name: string,
render: (controller: ScreenController<Value>) => View,
): Screen<Value> => ({ name, render }),
};
/**
* 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<void>;
readonly succeed: (message?: string) => Effect.Effect<void>;
readonly fail: (message?: string) => Effect.Effect<void>;
readonly close: Effect.Effect<void>;
}
/**
* 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<void>;
}
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;
}
/**
* The capability to ask or tell the human driving this process. Provided
* by {@link layer}; never provided in child processes.
*/
export class Interaction extends Context.Service<
Interaction,
{
readonly terminal: TerminalCapabilities;
readonly output: {
/** Append a completed layout to terminal scrollback/output. */
readonly print: (view: View) => Effect.Effect<void>;
readonly info: (message: string | MessageOptions) => Effect.Effect<void>;
readonly success: (message: string | MessageOptions) => Effect.Effect<void>;
readonly warning: (message: string | MessageOptions) => Effect.Effect<void>;
readonly error: (message: string | MessageOptions) => Effect.Effect<void>;
};
readonly prompt: {
readonly text: (options: TextInputOptions) => Effect.Effect<string, InteractionError>;
readonly password: (options: PasswordInputOptions) => Effect.Effect<string, InteractionError>;
readonly confirm: (options: ConfirmOptions) => Effect.Effect<boolean, InteractionError>;
readonly select: <Value>(
options: SelectOptions<Value>,
) => Effect.Effect<Value, InteractionError>;
readonly multiSelect: <Value>(
options: MultiSelectOptions<Value>,
) => Effect.Effect<ReadonlyArray<Value>, InteractionError>;
/** Run an arbitrary interactive screen. */
readonly screen: <Value>(screen: Screen<Value>) => Effect.Effect<Value, InteractionError>;
};
/**
* 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: <A, E, R, E2 = never, R2 = never>(
options: BrowserLoginOptions<A, E, R, E2, R2>,
) => Effect.Effect<A, E | E2 | InteractionError, R | R2 | ChildProcessSpawner>;
/**
* 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<LiveViewHandle, never, Scope.Scope>;
/** Add a mutable progress row, settled through its handle. */
readonly progress: (
options: ProgressOptions,
) => Effect.Effect<ProgressHandle, never, Scope.Scope>;
/** Run work behind a progress row and collapse it to a final status line. */
readonly task: <A, E, R>(
options: ProgressOptions,
effect: Effect.Effect<A, E, R>,
) => Effect.Effect<A, E, R>;
/**
* 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: <A, E, R>(
effect: Effect.Effect<A, E, R>,
options?: SessionOptions,
) => Effect.Effect<A, E | NonInteractiveTerminal, R>;
}
>()("Alchemy::Interaction") {}
// Top-level forms of the service's messages and prompts. Each acquires
// `Interaction` when it runs, not when it's built, so a provider can hold
// one in a value without capturing whichever service was ambient then.
export const print = (view: View) => Effect.flatMap(Interaction, (i) => i.output.print(view));
export const info = (message: string | MessageOptions) =>
Effect.flatMap(Interaction, (i) => i.output.info(message));
export const success = (message: string | MessageOptions) =>
Effect.flatMap(Interaction, (i) => i.output.success(message));
export const warning = (message: string | MessageOptions) =>
Effect.flatMap(Interaction, (i) => i.output.warning(message));
export const error = (message: string | MessageOptions) =>
Effect.flatMap(Interaction, (i) => i.output.error(message));
export const text = (options: TextInputOptions) =>
Effect.flatMap(Interaction, (i) => i.prompt.text(options));
export const password = (options: PasswordInputOptions) =>
Effect.flatMap(Interaction, (i) => i.prompt.password(options));
export const confirm = (options: ConfirmOptions) =>
Effect.flatMap(Interaction, (i) => i.prompt.confirm(options));
export const select = <Value>(options: SelectOptions<Value>) =>
Effect.flatMap(Interaction, (i) => i.prompt.select(options));
export const multiSelect = <Value>(options: MultiSelectOptions<Value>) =>
Effect.flatMap(Interaction, (i) => i.prompt.multiSelect(options));
export const browserLogin = <A, E, R, E2 = never, R2 = never>(
options: BrowserLoginOptions<A, E, R, E2, R2>,
) => Effect.flatMap(Interaction, (i) => i.browserLogin(options));
export const screen = <Value>(scene: Screen<Value>) =>
Effect.flatMap(Interaction, (i) => i.prompt.screen(scene));
/**
* `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 const taskFromProgress =
(progress: Interaction["Service"]["progress"]): Interaction["Service"]["task"] =>
(options, effect) =>
Effect.scoped(
Effect.gen(function* () {
const handle = yield* progress(options);
return yield* effect.pipe(
Effect.onExit((exit) =>
Exit.isSuccess(exit)
? handle.succeed()
: Cause.hasInterruptsOnly(exit.cause)
? handle.close
: handle.fail(),
),
);
}),
);
/**
* 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 const openUrl = (url: string) =>
Effect.gen(function* () {
const [command, args] =
process.platform === "win32"
? (["rundll32.exe", ["url.dll,FileProtocolHandler", url]] as const)
: process.platform === "darwin"
? (["open", [url]] as const)
: (["xdg-open", [url]] as const);
const handle = yield* ChildProcess.make(command, [...args], {
shell: false,
});
const exitCode = yield* handle.exitCode.pipe(Effect.timeoutOption("3 seconds"));
if (Option.isSome(exitCode) && exitCode.value !== 0) {
return yield* new BrowserOpenFailed({ command, exitCode: exitCode.value });
}
}).pipe(Effect.scoped);
// Bun can hand concurrent dynamic imports of one module a half-evaluated
// namespace (a TDZ ReferenceError on its exports), so every lazy renderer
// module is imported through one shared promise.
const importOnce = <M>(load: () => Promise<M>) => {
let module: Promise<M> | undefined;
return () => (module ??= load());
};
const loadFormat = importOnce(() => import("./Cli/components/view/Format.tsx"));
const loadSigilRuntime = importOnce(() => import("./Cli/components/view/Runtime.tsx"));
const loadCapabilities = importOnce(() => import("./Cli/components/capabilities.ts"));
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<TerminalOptions, "stdout" | "colors" | "unicode">;
const nonInteractiveFailure = (operation: string) =>
new NonInteractiveTerminal({
operation,
message: `Cannot run ${operation} without an interactive terminal. Provide the equivalent command flags instead.`,
});
export const makeNonInteractive = (options: NonInteractiveOptions = {}): Interaction["Service"] => {
const stdout = options.stdout ?? process.stdout;
const colors = options.colors ?? colorsEnabled(stdout);
const unicode = options.unicode ?? unicodeEnabled();
const glyphs = glyphsFor(unicode);
const terminal: TerminalCapabilities = {
input: false,
columns: stdout.columns ?? 80,
rows: stdout.rows ?? 24,
colors,
unicode,
alternateScreen: false,
};
const colorize = (hex: string, value: string) =>
colors ? `${ansiFg(hex)}${value}${ANSI_RESET}` : value;
const muted = (value: string) => (colors ? `${ANSI_DIM}${value}${ANSI_RESET}` : value);
// Plain-string equivalent of the CLI's `Status` component: colored glyph,
// the message (painted for errors), and a muted `· detail` suffix.
const statusText = (variant: StatusVariant, message: string, detail?: string) => {
const glyph = colorize(statusColor(variant), glyphs[variant]);
const body = variant === "error" ? colorize(statusColor(variant), message) : message;
return `${glyph} ${body}${detail === undefined ? "" : ` ${muted(`· ${detail}`)}`}`;
};
const log = (variant: StatusVariant) => (message: string | MessageOptions) =>
Effect.sync(() => {
const { message: text, detail } = typeof message === "string" ? { message } : message;
stdout.write(`${statusText(variant, text, detail)}\n`);
});
// Views are React layouts: load the static formatter only when one is
// actually printed, so headless processes never pull in the renderer.
const print = (view: View) =>
Effect.promise(loadFormat).pipe(
Effect.map(({ formatView }) =>
formatView(view, { ...terminal, columns: stdout.columns ?? terminal.columns }),
),
Effect.flatMap((text) =>
text === "" ? Effect.void : Effect.sync(() => void stdout.write(`${text}\n`)),
),
);
const unavailable = (operation: string) => Effect.fail(nonInteractiveFailure(operation));
const progress: Interaction["Service"]["progress"] = (initial) =>
Effect.acquireRelease(
log("info")({ message: initial.label, detail: initial.detail }).pipe(
Effect.map((): ProgressHandle => {
let current = initial;
let settled = false;
const settle = (variant: "success" | "error", message?: string) =>
Effect.suspend(() => {
if (settled) return Effect.void;
settled = true;
return log(variant)(message ?? current.label);
});
return {
update: (next) =>
Effect.sync(() => {
if (!settled) current = next;
}),
succeed: (message) => settle("success", message),
fail: (message) => settle("error", message),
close: Effect.sync(() => {
settled = true;
}),
};
}),
),
(handle) => handle.close,
);
return {
terminal,
output: {
print,
info: log("info"),
success: log("success"),
warning: log("warning"),
error: log("error"),
},
prompt: {
text: () => unavailable("text input"),
password: () => unavailable("password input"),
confirm: () => unavailable("confirmation"),
select: () => unavailable("selection"),
multiSelect: () => unavailable("multiple selection"),
screen: (screen) => unavailable(screen.name),
},
// Without a screen there's nothing to paste a code into: print the URL
// and wait, so device and poll logins still work headless.
browserLogin: (login) =>
Effect.gen(function* () {
const openFailed = yield* Effect.isFailure(openUrl(login.url));
yield* log("info")({
message: `${login.provider} authorization: ${openFailed ? "open" : "opened"} ${login.url}`,
detail: login.code === undefined ? undefined : `code ${login.code}`,
});
return yield* login.waitFor;
}),
live: (view) => print(view).pipe(Effect.as({ close: Effect.void })),
progress,
task: taskFromProgress(progress),
session: () => unavailable("application"),
};
};
/**
* 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 const layerNonInteractive = (options: NonInteractiveOptions = {}) =>
Layer.effect(
Interaction,
Effect.sync(() => makeNonInteractive(options)),
);
/**
* The interactive Sigil renderer, regardless of what the terminal reports.
* Prefer {@link layer}, which falls back to plain output without a TTY.
*/
export const layerSigil = (options: TerminalOptions = {}) =>
Layer.effect(
Interaction,
Effect.gen(function* () {
const { resolveCapabilities } = yield* Effect.promise(loadCapabilities);
const { makeRuntime } = yield* Effect.promise(loadSigilRuntime);
const { service } = yield* Effect.acquireRelease(
Effect.sync(() => makeRuntime(options, { ...resolveCapabilities(options), input: true })),
({ dispose }) => Effect.promise(dispose),
);
return service;
}),
);
/**
* 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 const layer = (options: TerminalOptions = {}) =>
Layer.unwrap(
Effect.gen(function* () {
const { resolveCapabilities } = yield* Effect.promise(loadCapabilities);
const capabilities = resolveCapabilities(options);
return capabilities.input
? layerSigil(options)
: layerNonInteractive({
stdout: options.stdout,
colors: capabilities.colors,
unicode: capabilities.unicode,
});
}),
);