/** @jsxRuntime automatic */ /** @jsxImportSource @alchemy.run/sigil */ import { AnsiText, Box, render, Static, useTitle } from "@alchemy.run/sigil"; import { useSyncExternalStore } from "@alchemy.run/sigil/react"; import * as Context from "effect/Context"; import * as Effect from "effect/Effect"; import type { ChildProcessSpawner } from "effect/process/ChildProcessSpawner"; import type * as Scope from "effect/Scope"; import * as Semaphore from "effect/Semaphore"; import type { ReactNode } from "react"; import { type BrowserLoginOptions, type Interaction, type NonInteractiveTerminal, openUrl, type SessionOptions, TerminalCancelled, taskFromProgress, } from "../../../Interaction.ts"; import type { ProgressHandle, ProgressOptions, Screen, TerminalCapabilities, TerminalOptions, LiveViewHandle, LiveViewOptions, View, } from "../types.ts"; import { CliEnvironment } from "../ui/Environment.tsx"; import { Spinner, Status } from "../ui/Feedback.tsx"; import { useTerminalInput } from "../ui/Interactive.tsx"; import { LiveStore, useLiveStore } from "../ui/Live.tsx"; import { CancelledPrompt } from "../ui/Transcript.tsx"; import { formatView, normalizeView } from "./Format.tsx"; import { confirmScreen, browserLoginScreen, multiSelectScreen, passwordScreen, selectScreen, textScreen, } from "./Prompts.tsx"; const InSession = Context.Reference("Alchemy::Interaction/InSession", { defaultValue: () => false, }); /** * One rendered block. Views are immutable once mounted — dynamic content * flows through caller-owned stores (`LiveStore` + `useLiveStore`) that the * view component subscribes to, never through the runtime. */ interface Item { readonly key: number; readonly view: View; readonly placement?: LiveViewOptions["placement"]; } interface StoreState { readonly staticItems: Item[]; readonly transcript: ReadonlyArray; readonly live: ReadonlyArray; readonly active?: Item; } /** * The single external store the React root syncs from. It only tracks WHICH * blocks are mounted and in what region (static scrollback, in-session * transcript, live region, active prompt) — block content never changes * after mount, so there is no update surface here. */ class TerminalStore { private state: StoreState = { staticItems: [], transcript: [], live: [] }; private readonly listeners = new Set<() => void>(); private nextKey = 0; readonly subscribe = (listener: () => void) => { this.listeners.add(listener); return () => this.listeners.delete(listener); }; readonly snapshot = () => this.state; private commit(state: StoreState) { this.state = state; for (const listener of this.listeners) listener(); } alloc() { return this.nextKey++; } append(view: View) { this.commit({ ...this.state, transcript: [...this.state.transcript, { key: this.alloc(), view }], }); } appendStatic(view: View) { this.commit({ ...this.state, staticItems: [...this.state.staticItems, { key: this.alloc(), view }], }); } addLive(key: number, view: View, placement: LiveViewOptions["placement"] = "afterTranscript") { this.commit({ ...this.state, live: [...this.state.live, { key, view, placement }] }); } removeLive(key: number) { this.commit({ ...this.state, live: this.state.live.filter((entry) => entry.key !== key) }); } /** * Move a live block into scrollback (its component renders one final time * from its store's final state). No-op when the row was already cleared. */ completeLive(key: number, destination: "staticItems" | "transcript") { const item = this.state.live.find((entry) => entry.key === key); if (item === undefined) return; this.commit({ ...this.state, [destination]: [...this.state[destination], { key: this.alloc(), view: item.view }], live: this.state.live.filter((entry) => entry.key !== key), }); } activate(view: View) { this.commit({ ...this.state, active: { key: this.alloc(), view } }); } deactivate() { if (this.state.active !== undefined) this.commit({ ...this.state, active: undefined }); } clear() { this.commit({ ...this.state, transcript: [], live: [] }); } clearStatic() { if (this.state.staticItems.length > 0) { this.commit({ ...this.state, staticItems: [] }); } } clearTranscript() { if (this.state.transcript.length > 0) { this.commit({ ...this.state, transcript: [] }); } } get idle() { return this.state.active === undefined && this.state.live.length === 0; } } /** * Always-on Ctrl+C handler wrapped around every screen by `run`. Screens no * longer need their own Ctrl+C wiring (a screen that forgot it used to make * the CLI unkillable, since Sigil runs with `exitOnCtrlC: false` in raw mode); * they only handle Escape, whose semantics differ per screen. */ type ScreenCancelGuardProps = { readonly onCancel: () => void; readonly children?: ReactNode }; function ScreenCancelGuard({ onCancel, children }: ScreenCancelGuardProps) { useTerminalInput( (input, key) => { if (key.ctrl && input === "c") onCancel(); }, { active: true }, ); return <>{children}; } type ItemViewProps = { readonly item: Item }; function ItemView({ item }: ItemViewProps) { return {item.view}; } type TerminalRootProps = { readonly store: TerminalStore }; function TerminalRoot({ store }: TerminalRootProps) { const state = useSyncExternalStore(store.subscribe, store.snapshot); useTerminalInput( (input, key) => { if (!key.ctrl || input !== "c") return; process.kill(process.pid, "SIGINT"); }, { active: state.active === undefined }, ); const beforeTranscript = state.live.filter((item) => item.placement === "beforeTranscript"); const afterTranscript = state.live.filter((item) => item.placement !== "beforeTranscript"); return ( {(item) => } {beforeTranscript.map((item) => ( ))} {state.transcript.map((item) => ( ))} {afterTranscript.map((item) => ( ))} {state.active === undefined ? null : ( 0 ? 1 : 0}> )} ); } /** Progress rows are ordinary live views over a runtime-owned store. */ interface ProgressState { readonly options: ProgressOptions; readonly final?: { readonly variant: "success" | "error"; readonly message?: string }; } type ProgressViewProps = { readonly store: LiveStore }; function ProgressView({ store }: ProgressViewProps) { const state = useLiveStore(store); useTitle(state.options.title); return state.final !== undefined ? ( {state.final.message ?? state.options.label} ) : state.options.spinning === false ? ( {state.options.label} ) : ( ); } export interface SigilRuntime { readonly service: Interaction["Service"]; readonly dispose: () => Promise; } export const makeRuntime = ( options: TerminalOptions, capabilities: TerminalCapabilities, ): SigilRuntime => { const stdin = options.stdin ?? process.stdin; const stdout = options.stdout ?? process.stdout; const stderr = options.stderr ?? process.stderr; const store = new TerminalStore(); const rendererGate = Semaphore.makeUnsafe(1); const promptGate = Semaphore.makeUnsafe(1); interface Mounted { readonly sigil: ReturnType; /** Whether the instance is currently on the alternate screen. */ alternate: boolean; /** Settles when the instance exits; render crashes are routed out, never rethrown. */ exit: Promise; /** * Flush any partial captured line into the Static transcript — called at * unmount so trailing output without a newline still lands. Lives on the * instance because it closes over this mount's capture buffers and must * die with it. */ readonly flushDirectStdio?: () => void; } // Lifecycle state. `mounted` and `unmounting` deliberately overlap: during // teardown the instance stays in `mounted` until re-validation passes, so // prints/live views racing the drain still see a live renderer (and can // abort the teardown). `sessionMounted` is an orthogonal axis — an // `session()` region pins the renderer regardless of store idleness — and // `disposed` is a terminal one-way latch. let mounted: Mounted | undefined; let unmounting: Promise | undefined; let sessionMounted = false; let disposed = false; /** * Fails the active interaction when a screen component throws during * render. Without this the prompt's callback would never resume and the * CLI would hang with a dead renderer. */ let failActive: ((error: unknown) => void) | undefined; /** * The single failure channel for renderer errors: route into the active * interaction when a prompt is waiting, otherwise surface on stderr. Every * async failure path (the exit promise, fire-and-forget mounts) funnels * here so no rejection ever escapes unhandled. */ const failRenderer = (error: unknown) => { if (failActive !== undefined) failActive(error); else stderr.write(`Sigil renderer error: ${String(error)}\n`); }; const mount = async (alternateScreen = false): Promise => { // Never overlap a new Sigil root with one that is still tearing down — // Sigil keys instances by stdout and two live roots corrupt the output. while (unmounting !== undefined) await unmounting; if (disposed || mounted !== undefined) return; const captureDirectStdio = options.captureConsole !== false; // Process output lives in the renderer's Static zone above every inline // view. Adding a static row commits it to scrollback and naturally moves // the live UI down, avoiding log-update's erase/restore path and its // render artifacts. `patchConsole: "stdio"` captures console, Node // warnings, and direct stream writes from tools such as Floci (the // renderer's own frames go through passthrough facades and bypass the // capture); `onCapturedOutput` takes ownership of each raw chunk so the // Static transcript renders it instead of the built-in splicing. The // renderer restores console and stream writes itself on unmount. const buffers = { stdout: "", stderr: "" }; // A captured write that ends mid-line parks its tail here waiting for // the rest of the line. A real terminal would display the partial // immediately — so when no continuation arrives promptly, flush the // tail as its own row instead of holding it until unmount. Without the // deadline, a writer whose final chunk lacks a trailing newline (e.g. // a pretty-printed cause written raw to stderr) has its last line // appear only when the process exits. One timer PER STREAM: a chatty // stdout must not keep resetting the deadline of a parked stderr tail. const partialFlushTimers: { [Stream in keyof typeof buffers]?: ReturnType; } = {}; const clearPartialFlush = (stream: keyof typeof buffers) => { const timer = partialFlushTimers[stream]; if (timer !== undefined) { clearTimeout(timer); partialFlushTimers[stream] = undefined; } }; const flushPartialLine = (stream: keyof typeof buffers) => { partialFlushTimers[stream] = undefined; if (buffers[stream] !== "") { store.appendStatic({buffers[stream]}); buffers[stream] = ""; } }; const appendLines = (stream: keyof typeof buffers, data: string) => { const parts = `${buffers[stream]}${data}`.split(/\r?\n/); buffers[stream] = parts.pop() ?? ""; for (const line of parts) { store.appendStatic({line || " "}); } clearPartialFlush(stream); if (buffers[stream] !== "") { const timer = setTimeout(() => flushPartialLine(stream), 50); timer.unref?.(); partialFlushTimers[stream] = timer; } }; const sigil = render( , { stdin, stdout, stderr, exitOnCtrlC: false, interactive: capabilities.input, alternateScreen: alternateScreen, colorProfile: capabilities.colors ? "truecolor" : "none", ...(captureDirectStdio ? { patchConsole: "stdio" as const, onCapturedOutput: (stream: "stdout" | "stderr", data: string) => { appendLines(stream, data); return true; }, } : { patchConsole: false as const }), }, ); const current: Mounted = { sigil, alternate: alternateScreen, exit: Promise.resolve(), flushDirectStdio: captureDirectStdio ? () => { // AnsiText, matching the line and deadline paths: a trailing // fragment must not render color-stripped just because teardown // won the race against the 50ms deadline. for (const stream of ["stdout", "stderr"] as const) { clearPartialFlush(stream); if (buffers[stream] !== "") { store.appendStatic({buffers[stream]}); buffers[stream] = ""; } } } : undefined, }; // Capture the exit promise at mount time: Sigil registers its process // `beforeExit` listener on the first `waitUntilExit()` call and `unmount` // only removes a listener that already exists, so waiting only after // unmount leaks one process listener per mount cycle. A rejection means a // component threw during render — Sigil has already unmounted itself, so // drop the dead instance and surface the error instead of hanging. current.exit = sigil.waitUntilExit().then( () => undefined, (error: unknown) => { // The crashed instance is dropped without the unmount path, so // disarm any pending partial-flush timer here too. current.flushDirectStdio?.(); if (mounted === current) mounted = undefined; failRenderer(error); }, ); mounted = current; }; const ensureMounted = () => Effect.promise(() => mount()); const waitForRender = () => mounted?.sigil.waitUntilRenderFlush().catch(() => undefined) ?? Promise.resolve(); /** * Tear down the renderer. Total (never rejects) and re-validated across its * awaits: output printed or live views opened while the final frame flushes * abort the teardown instead of being destroyed with it. `force` skips the * re-validation for dispose and presentation switches. */ const unmount = (force = false): Promise => { if (unmounting !== undefined) return unmounting; const current = mounted; if (current === undefined) return Promise.resolve(); unmounting = (async () => { try { current.flushDirectStdio?.(); // Drain: keep flushing until no new static output arrives between // flushes, so a `print` racing the teardown reaches the terminal. // Unbounded by design — the bound is the renderer's convergence: the // loop exits as soon as producers go quiet for one full flush. let staticCount; do { staticCount = store.snapshot().staticItems.length; await current.sigil.waitUntilRenderFlush(); } while (store.snapshot().staticItems.length !== staticCount); // Re-validate: a prompt or live view may have re-armed the renderer // while the frame flushed. Their output would be destroyed by the // teardown, so leave the instance mounted for them instead. if (!force && (sessionMounted || !store.idle)) return; // A captured chunk that arrived DURING the drain may have parked a // partial line and armed a flush timer. Flush and disarm now — // otherwise the timer fires after `clearStatic()` below and the // stale fragment replays at the top of the next mount. current.flushDirectStdio?.(); mounted = undefined; // unmount restores the patched console and stream writes. current.sigil.unmount(); await current.exit; current.sigil.cleanup(); // Static output has been handed off to the terminal. Do not replay // it when a later live session mounts a fresh Sigil root. store.clearStatic(); } catch { // Teardown must be total: a crashed instance still ends up unmounted // with console/stream patches restored — and with no armed partial // flush timer left to poke the store after clearStatic. if (mounted === current) mounted = undefined; try { current.flushDirectStdio?.(); current.sigil.unmount(); } catch { // Already unmounted (or unmount itself is what threw above). } } })().finally(() => { unmounting = undefined; }); return unmounting; }; const releaseIfIdle = () => Effect.suspend(() => sessionMounted || !store.idle ? Effect.void : Effect.promise(() => unmount()), ); const print = (view: View) => Effect.gen(function* () { const inSession = yield* InSession; view = normalizeView(view); if (inSession) { yield* Effect.sync(() => store.append(view)); } else if (mounted !== undefined) { yield* Effect.sync(() => store.appendStatic(view)); } else { const output = formatView(view, { ...capabilities, // Re-read the width at render time — the boot-time snapshot goes // stale the moment the user resizes the terminal. columns: stdout.columns ?? capabilities.columns, }); if (output !== "") yield* Effect.sync(() => stdout.write(`${output}\n`)); } }); const messageOptions = (message: string | { message: string; detail?: string }) => typeof message === "string" ? { message } : message; const log = (variant: "info" | "success" | "warning" | "error") => (message: string | { message: string; detail?: string }) => { const options = messageOptions(message); return print( {options.message} , ); }; const run = (screen: Screen) => Effect.gen(function* () { const inSession = yield* InSession; const interaction = promptGate.withPermits(1)( Effect.gen(function* () { let completedView: View | undefined; return yield* Effect.callback((resume) => { let settled = false; const finish = (result: Effect.Effect, resultView?: View) => { if (settled) return; settled = true; failActive = undefined; store.deactivate(); if (resultView !== undefined) { if (inSession) store.append(normalizeView(resultView)); else completedView = resultView; } resume(result); }; const cancel = () => finish( Effect.fail(new TerminalCancelled()), , ); // A screen that throws during render unmounts Sigil with the error; // without this hook the callback would never resume and the CLI // would hang forever on a dead renderer. failActive = (error) => finish(Effect.die(error)); store.activate( {screen.render({ submit: (value, summary) => finish(Effect.succeed(value), summary), cancel, })} , ); // Not awaited (Effect.callback's register is synchronous), but // never fire-and-forget: a mount failure — e.g. a synchronous // throw from Sigil's render() — routes through `failRenderer`, // which fails this very interaction via the `failActive` hook // installed above instead of escaping as an unhandled rejection. mount().catch(failRenderer); // Interruption cleanup: deactivate the screen and let the caller's // finalizers release the renderer. return Effect.sync(() => { if (!settled) { settled = true; failActive = undefined; store.deactivate(); } }); }).pipe( Effect.ensuring( Effect.suspend(() => inSession ? Effect.void : releaseIfIdle().pipe( Effect.andThen( completedView === undefined ? Effect.void : print(completedView), ), ), ), ), ); }), ); return yield* inSession ? interaction : rendererGate.withPermits(1)(interaction); }); // A session owns the renderer when invoked standalone. Nested, it reuses // the outer renderer and clears the prompts it showed when it settles, so // nested profile/OAuth flows suspend cleanly. Prompt serialization remains // centralized in `run`. const session = ( effect: Effect.Effect, sessionOptions: SessionOptions = {}, ): Effect.Effect => Effect.gen(function* () { if (yield* InSession) { return yield* effect.pipe(Effect.ensuring(Effect.sync(() => store.clearTranscript()))); } const alternate = sessionOptions.alternate === true && capabilities.alternateScreen; return yield* rendererGate.withPermits(1)( Effect.acquireUseRelease( Effect.promise(async () => { sessionMounted = true; store.clear(); // A renderer already mounted for an earlier progress row switches // presentation in place; Sigil keeps its Static output. if (mounted !== undefined && mounted.alternate !== alternate) { mounted.sigil.setAlternateScreen(alternate); mounted.alternate = alternate; } await mount(alternate); }), () => effect.pipe(Effect.provideService(InSession, true)), () => Effect.promise(async () => { sessionMounted = false; store.clear(); // Let the empty frame replace the session, then erase // that frame explicitly. Unmount can now restore terminal // modes without leaving the empty frame's newline behind. const current = mounted; if (current !== undefined) { await current.sigil.waitUntilRenderFlush(); // Back to the main screen first: the renderer may stay // mounted afterwards for live views that outlive the session. if (current.alternate) { current.sigil.setAlternateScreen(false); current.alternate = false; } current.sigil.clear(); } await unmount(); }), ), ); }); const makeLive = (initial: View, options: LiveViewOptions = {}): Effect.Effect => Effect.gen(function* () { const inSession = yield* InSession; const key = store.alloc(); let closed = false; yield* Effect.sync(() => store.addLive(key, normalizeView(initial), options.placement)); yield* ensureMounted(); return { close: Effect.suspend(() => { if (closed) return Effect.void; closed = true; // removeLive/completeLive no-op when the row was already cleared // by a session boundary. if (options.persistOnClose) store.completeLive(key, inSession ? "transcript" : "staticItems"); else store.removeLive(key); return Effect.promise(waitForRender).pipe(Effect.andThen(releaseIfIdle())); }), }; }); /** * Scope-bound: the enclosing scope closes the view as a backstop, so an * interrupted caller can never leave an orphaned row keeping the renderer * mounted (and the process alive) forever. */ const live = ( initial: View, options: LiveViewOptions = {}, ): Effect.Effect => Effect.acquireRelease(makeLive(initial, options), (handle) => handle.close); /** * A progress row is just a live view over a runtime-owned store — the * handle mutates the store, React re-renders. Settling swaps the store to * its final state and commits the block to scrollback. */ const makeProgress = (initial: ProgressOptions): Effect.Effect => Effect.gen(function* () { const inSession = yield* InSession; const progressStore = new LiveStore({ options: initial }); const key = store.alloc(); yield* Effect.sync(() => store.addLive(key, )); yield* ensureMounted(); let settled = false; const finishRow = (persist: boolean) => Effect.suspend(() => { if (settled) return Effect.void; settled = true; // completeLive/removeLive no-op when the row was already cleared // by a session boundary. if (persist) store.completeLive(key, inSession ? "transcript" : "staticItems"); else store.removeLive(key); return Effect.promise(waitForRender).pipe(Effect.andThen(releaseIfIdle())); }); const settle = (variant: "success" | "error", message?: string) => Effect.suspend(() => { if (settled) return Effect.void; progressStore.update((state) => ({ ...state, final: { variant, message } })); return finishRow(true); }); return { update: (next) => Effect.sync(() => { if (!settled) progressStore.set({ options: next }); }), succeed: (message) => settle("success", message), fail: (message) => settle("error", message), // An unsettled close abandons the row rather than committing it. close: finishRow(false), } satisfies ProgressHandle; }); const progress = (initial: ProgressOptions): Effect.Effect => Effect.acquireRelease(makeProgress(initial), (handle) => handle.close); /** * The login screen races `waitFor`: the poll or callback normally wins, * the screen only settles first when the user cancels or pastes a code. */ const browserLogin = ( login: BrowserLoginOptions, ) => Effect.gen(function* () { const services = yield* Effect.context(); // Invoked later by the screen's keyboard handler, outside this fiber. const reopen = () => Effect.runPromiseWith(services)(openUrl(login.url)); const openFailed = yield* Effect.isFailure(openUrl(login.url)); const manual = login.manualCode; const screen = run( browserLoginScreen({ message: `${login.provider} authorization`, waitingLabel: login.waitingLabel ?? "waiting for browser authorization (up to 5 minutes)…", url: login.url, code: login.code, openFailed, onOpen: reopen, allowManualInput: manual !== undefined, inputLabel: manual?.label ?? "Paste the authorization code or callback URL", placeholder: manual?.placeholder, validate: manual?.validate, }), ).pipe( Effect.flatMap((code): Effect.Effect => manual === undefined ? Effect.never : manual.exchange(code), ), ); return yield* Effect.raceFirst(login.waitFor, screen); }); const service: Interaction["Service"] = { terminal: capabilities, output: { print, info: log("info"), success: log("success"), warning: log("warning"), error: log("error"), }, prompt: { text: (inputOptions) => run(textScreen(inputOptions)), password: (inputOptions) => run(passwordScreen(inputOptions)), confirm: (confirmOptions) => run(confirmScreen(confirmOptions)), select: (selectOptions) => run(selectScreen(selectOptions)), multiSelect: (selectOptions) => run(multiSelectScreen(selectOptions)), screen: run, }, browserLogin, live, progress, task: taskFromProgress(progress), session, }; return { service, dispose: async () => { // After dispose the runtime must never mount again; force teardown even // if stray live rows were leaked. disposed = true; await unmount(true); }, }; };