1
import process from 'node:process';
2
+import type { Writable } from 'node:stream';
3
import * as p from '@clack/prompts';
4
import { Context, Effect, Exit, Layer } from 'effect';
5
13
readonly stderr: TtyLikeStream;
14
};
15
16
+/**
17
+ * Per-stream terminal capabilities.
18
+ *
19
+ * The three streams are independent contracts, so each derived capability
20
+ * depends only on the streams that actually serve it:
21
+ *
22
+ * - `canPrompt` — stdin must accept human input and stderr must display the
23
+ * Clack prompt. stdout is irrelevant: piping data must not change prompting
24
+ * or authentication behavior.
25
+ * - `canDecorate` — decoration (spinners, logs, notes) renders on stderr, so it
26
+ * only needs stderr.
27
+ * - machine output — `TerminalUI.output()` consults `stdoutIsTTY` alone.
28
+ *
29
+ * There is deliberately no aggregate "interactive" flag: it conflated these
30
+ * concerns and let output routing change program behavior.
31
+ */
32
export type TerminalCapabilities = {
33
readonly stdinIsTTY: boolean;
34
readonly stdoutIsTTY: boolean;
35
readonly stderrIsTTY: boolean;
19
- readonly isInteractive: boolean;
36
+ /** Whether Clack prompts can run (`stdinIsTTY && stderrIsTTY`). */
37
+ readonly canPrompt: boolean;
38
+ /** Whether stderr decoration can render (`stderrIsTTY`). */
39
readonly canDecorate: boolean;
40
};
41
49
stdinIsTTY,
50
stdoutIsTTY,
51
stderrIsTTY,
33
- isInteractive: stdinIsTTY && stdoutIsTTY && stderrIsTTY,
52
+ canPrompt: stdinIsTTY && stderrIsTTY,
53
canDecorate: stderrIsTTY,
54
};
55
};
79
* Write raw data to stdout for piping and scripting.
80
*
81
* This is the ONLY method that writes to stdout — everything else goes to stderr.
63
- * When stdout is a TTY (interactive terminal), this is a no-op — the human already
82
+ * When stdout is a TTY (a human is watching it), this is a no-op — the human already
83
* sees the data via decoration on stderr. When stdout is redirected (pipe, subshell,
65
- * file), the raw value is written for machine consumption.
84
+ * file), the raw value is written for machine consumption. Only stdout's own TTY
85
+ * state participates in this decision; redirecting stdin or stderr must never make
86
+ * data leak onto a visible stdout terminal.
87
*
88
* Use this for values that scripts should capture (API keys, version strings, etc.).
89
*/
136
137
/**
138
* Ask the user a yes/no confirmation question.
118
- * In non-interactive mode (piped), returns `defaultValue` (defaults to `true`).
139
+ * When prompting is unavailable, returns `defaultValue` (defaults to `true`).
140
*/
141
readonly confirm: (
142
message: string,
145
146
/**
147
* Present a single-select list to the user.
127
- * In non-interactive mode (piped), returns the first option's value.
148
+ * When prompting is unavailable, returns the first option's value.
149
*/
150
readonly select: <Value>(
151
message: string,
172
export const TerminalUI = Context.GenericTag<TerminalUI>('services/TerminalUI');
173
174
// ---------------------------------------------------------------------------
154
-// TerminalUILive — production layer using @clack/prompts
175
+// makeTerminalUI — build a TerminalUI from explicit streams
176
// ---------------------------------------------------------------------------
177
178
/**
158
- * Whether the CLI can prompt for human input. Human-only prompts are shown only
159
- * when stdin/stdout/stderr are all TTYs; agent and shell pipelines get
160
- * non-interactive behavior.
161
- */
162
-const liveCapabilities = getTerminalCapabilities({
163
- stdin: process.stdin,
164
- stdout: process.stdout,
165
- stderr: process.stderr,
166
-});
167
-
168
-const canPrompt = liveCapabilities.isInteractive;
169
-
170
-/**
171
- * Whether the CLI can render auxiliary UI. Logs, notes, and spinners only need
172
- * stderr, so they can still be shown when stdin is redirected from /dev/null or
173
- * stdout is reserved for machine-readable JSON/data.
179
+ * Intentionally a Node.js Writable rather than an Effect Sink: Clack accepts
180
+ * Writable streams and writes to them synchronously.
181
*/
175
-const canDecorate = liveCapabilities.canDecorate;
182
+type TerminalWritable = TtyLikeStream & Writable;
183
177
-/** Run a decoration side-effect only when stderr is a terminal. */
178
-function decorate(fn: () => void): void {
179
- if (canDecorate) fn();
180
-}
184
+type TerminalUIStreams = {
185
+ readonly stdin: TtyLikeStream;
186
+ readonly stdout: TerminalWritable;
187
+ readonly stderr: TerminalWritable;
188
+};
189
190
function createClackSpinnerHandle(
191
s: p.SpinnerResult,
210
};
211
}
212
205
-/** No-op spinner handle used when decoration is suppressed (piped mode). */
213
+/** No-op spinner handle used when decoration is suppressed (stderr redirected). */
214
const silentSpinnerHandle: SpinnerHandle = {
215
message: () => Effect.void,
216
stop: () => Effect.void,
217
error: () => Effect.void,
218
};
219
212
-const makeLive: TerminalUI = {
213
- capabilities: Effect.succeed(liveCapabilities),
220
+/**
221
+ * Build a TerminalUI backed by the given streams.
222
+ *
223
+ * Each stream governs exactly one concern:
224
+ * - stdin + stderr decide prompting (`canPrompt`);
225
+ * - stdout alone decides machine output (`output()` writes only when stdout
226
+ * is not a TTY, or when `force` is set);
227
+ * - stderr alone decides decoration (`canDecorate`).
228
+ */
229
+export const makeTerminalUI = (streams: TerminalUIStreams): TerminalUI => {
230
+ const capabilities = getTerminalCapabilities(streams);
231
+ const { canPrompt, canDecorate, stdoutIsTTY } = capabilities;
232
+ const stderr = streams.stderr;
233
+
234
+ const decorate = (render: () => void): Effect.Effect<void> => {
235
+ if (!canDecorate) {
236
+ return Effect.void;
237
+ }
238
+ return Effect.sync(render);
239
+ };
240
+
241
+ return {
242
+ capabilities: Effect.succeed(capabilities),
243
+
244
+ output: (data, options) =>
245
+ Effect.sync(() => {
246
+ if (options?.force || !stdoutIsTTY) {
247
+ streams.stdout.write(`${data}\n`);
248
+ }
249
+ }),
250
+
251
+ error: data => Effect.sync(() => stderr.write(`${data}\n`)),
252
+
253
+ intro: title => decorate(() => p.intro(title, { output: stderr })),
254
+ outro: message => decorate(() => p.outro(message, { output: stderr })),
255
+
256
+ log: {
257
+ info: message => decorate(() => p.log.info(message, { output: stderr })),
258
+ success: message => decorate(() => p.log.success(message, { output: stderr })),
259
+ warn: message => decorate(() => p.log.warn(message, { output: stderr })),
260
+ error: message => decorate(() => p.log.error(message, { output: stderr })),
261
+ step: message => decorate(() => p.log.step(message, { output: stderr })),
262
+ message: message => decorate(() => p.log.message(message, { output: stderr })),
263
+ },
264
+
265
+ note: (message, title) =>
266
+ decorate(() => p.note(message, title ?? '', { format: line => line, output: stderr })),
267
215
- output: (data, options) =>
216
- Effect.sync(() => {
217
- if (options?.force || !canPrompt) {
218
- process.stdout.write(`${data}\n`);
268
+ select: ((
269
+ message: string,
270
+ options: ReadonlyArray<{ value: unknown; label: string; hint?: string }>
271
+ ) => {
272
+ if (!canPrompt) {
273
+ return Effect.succeed(options[0].value);
274
}
220
- }),
221
-
222
- error: data => Effect.sync(() => process.stderr.write(`${data}\n`)),
223
-
224
- intro: title => Effect.sync(() => decorate(() => p.intro(title, { output: process.stderr }))),
225
- outro: message => Effect.sync(() => decorate(() => p.outro(message, { output: process.stderr }))),
226
-
227
- log: {
228
- info: message =>
229
- Effect.sync(() => decorate(() => p.log.info(message, { output: process.stderr }))),
230
- success: message =>
231
- Effect.sync(() => decorate(() => p.log.success(message, { output: process.stderr }))),
232
- warn: message =>
233
- Effect.sync(() => decorate(() => p.log.warn(message, { output: process.stderr }))),
234
- error: message =>
235
- Effect.sync(() => decorate(() => p.log.error(message, { output: process.stderr }))),
236
- step: message =>
237
- Effect.sync(() => decorate(() => p.log.step(message, { output: process.stderr }))),
238
- message: message =>
239
- Effect.sync(() => decorate(() => p.log.message(message, { output: process.stderr }))),
240
- },
241
-
242
- note: (message, title) =>
243
- Effect.sync(() =>
244
- decorate(() => p.note(message, title ?? '', { format: line => line, output: process.stderr }))
245
- ),
246
-
247
- select: ((
248
- message: string,
249
- options: ReadonlyArray<{ value: unknown; label: string; hint?: string }>
250
- ) =>
251
- canPrompt
252
- ? Effect.promise(async () => {
253
- const result = await p.select({
254
- message,
255
- options: [...options],
256
- output: process.stderr,
257
- });
258
- // p.select returns Value | symbol (symbol on cancel)
259
- if (typeof result === 'symbol') return options[0].value;
260
- return result;
261
- })
262
- : Effect.succeed(options[0].value)) as TerminalUI['select'],
263
-
264
- confirm: (message, options) =>
265
- canPrompt
266
- ? Effect.promise(async () => {
267
- const result = await p.confirm({
268
- message,
269
- initialValue: options?.defaultValue ?? true,
270
- output: process.stderr,
271
- });
272
- // p.confirm returns boolean | symbol (symbol on cancel)
273
- return typeof result === 'boolean' ? result : false;
274
- })
275
- : Effect.succeed(options?.defaultValue ?? true),
276
-
277
- withSpinner: (message, effect, options) =>
278
- canDecorate
279
- ? Effect.acquireUseRelease(
275
+
276
+ return Effect.promise(async () => {
277
+ const result = await p.select({
278
+ message,
279
+ options: [...options],
280
+ output: stderr,
281
+ });
282
+ // p.select returns Value | symbol (symbol on cancel)
283
+ if (typeof result === 'symbol') return options[0].value;
284
+ return result;
285
+ });
286
+ }) as TerminalUI['select'],
287
+
288
+ confirm: (message, options) => {
289
+ if (!canPrompt) {
290
+ return Effect.succeed(options?.defaultValue ?? true);
291
+ }
292
+
293
+ return Effect.promise(async () => {
294
+ const result = await p.confirm({
295
+ message,
296
+ initialValue: options?.defaultValue ?? true,
297
+ output: stderr,
298
+ });
299
+ if (p.isCancel(result)) return false;
300
+ return result;
301
+ });
302
+ },
303
+
304
+ withSpinner: (message, effect, options) => {
305
+ if (!canDecorate) {
306
+ return effect;
307
+ }
308
+
309
+ return Effect.acquireUseRelease(
310
+ Effect.sync(() => {
311
+ const s = p.spinner({ output: stderr });
312
+ s.start(message);
313
+ return s;
314
+ }),
315
+ () => effect,
316
+ (s, exit) =>
317
Effect.sync(() => {
281
- const s = p.spinner({ output: process.stderr });
282
- s.start(message);
283
- return s;
284
- }),
285
- () => effect,
286
- (s, exit) =>
287
- Effect.sync(() => {
288
- if (Exit.isSuccess(exit)) {
289
- const successMsg =
290
- typeof options?.successMessage === 'function'
291
- ? options.successMessage(exit.value)
292
- : (options?.successMessage ?? message);
293
- s.stop(successMsg);
294
- } else {
295
- s.error(options?.errorMessage ?? message);
318
+ if (Exit.isSuccess(exit)) {
319
+ let successMessage = message;
320
+ const configuredSuccessMessage = options?.successMessage;
321
+ if (typeof configuredSuccessMessage === 'function') {
322
+ successMessage = configuredSuccessMessage(exit.value);
323
+ } else if (configuredSuccessMessage !== undefined) {
324
+ successMessage = configuredSuccessMessage;
325
}
297
- })
298
- )
299
- : effect,
326
+ s.stop(successMessage);
327
+ } else {
328
+ s.error(options?.errorMessage ?? message);
329
+ }
330
+ })
331
+ );
332
+ },
333
+
334
+ useMakeSpinner: (message, use) => {
335
+ if (!canDecorate) {
336
+ return use(silentSpinnerHandle);
337
+ }
338
301
- useMakeSpinner: (message, use) =>
302
- canDecorate
303
- ? Effect.acquireUseRelease(
339
+ return Effect.acquireUseRelease(
340
+ Effect.sync(() => {
341
+ const s = p.spinner({ output: stderr });
342
+ s.start(message);
343
+ const { handle, isStopped } = createClackSpinnerHandle(s, message);
344
+ return { raw: s, handle, isStopped };
345
+ }),
346
+ ({ handle }) => use(handle),
347
+ ({ raw, isStopped }, exit) =>
348
Effect.sync(() => {
305
- const s = p.spinner({ output: process.stderr });
306
- s.start(message);
307
- const { handle, isStopped } = createClackSpinnerHandle(s, message);
308
- return { raw: s, handle, isStopped };
309
- }),
310
- ({ handle }) => use(handle),
311
- ({ raw, isStopped }, exit) =>
312
- Effect.sync(() => {
313
- // Only clean up if the spinner hasn't been stopped/errored by the callback
314
- if (Exit.isFailure(exit) && !isStopped()) {
315
- raw.error(message);
316
- }
317
- })
318
- )
319
- : use(silentSpinnerHandle),
349
+ // Only clean up if the spinner hasn't been stopped/errored by the callback
350
+ if (Exit.isFailure(exit) && !isStopped()) {
351
+ raw.error(message);
352
+ }
353
+ })
354
+ );
355
+ },
356
+ };
357
};
358
322
-export const TerminalUILive = Layer.succeed(TerminalUI, makeLive);
359
+// ---------------------------------------------------------------------------
360
+// TerminalUILive — production layer using @clack/prompts
361
+// ---------------------------------------------------------------------------
362
+
363
+export const TerminalUILive = Layer.succeed(
364
+ TerminalUI,
365
+ makeTerminalUI({
366
+ stdin: process.stdin,
367
+ stdout: process.stdout,
368
+ stderr: process.stderr,
369
+ })
370
+);