Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
fix(cli): harden spinner message clamping
Keep live spinner updates within both Clack's construction-time width and the current terminal width, so resizing wider cannot reintroduce wrapped frames while narrower terminals remain clamped. Segment messages by grapheme cluster before measuring display width so keycap and joined emoji cannot be under-counted or split.
jkomyno committed
Aug 31, 2026 at 13:00 UTC
41019972e1eee0c589418b111df03519a6b7513f
2 files changed
+108
-47
ts/packages/cli/src/services/terminal-ui.ts
+40
-27
@@ -201,53 +201,58 @@ type TerminalUIStreams = {
201
// columns. Below that the frame prefix alone overflows the row and no message
202
// length can keep it on one line, so the budget degrades to just the ellipsis.
203
const SPINNER_RENDER_OVERHEAD = 7; // frame + two spaces (3) + animated dots (3) + last-column safety (1)
204
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
205
205
-export const clampSpinnerMessage = (output: Writable, message: string): string => {
206
+export const clampSpinnerMessage = (columns: number, message: string): string => {
207
const singleLine = message.replace(/\s*\r?\n\s*/g, ' ');
208
if (singleLine.includes('\u001b')) {
209
return singleLine; // truncating could split an ANSI escape sequence
210
}
211
211
- const budget = Math.max(getColumns(output) - SPINNER_RENDER_OVERHEAD, 1);
212
+ const budget = Math.max(columns - SPINNER_RENDER_OVERHEAD, 1);
213
if (stringWidth(singleLine) <= budget) {
214
return singleLine;
215
}
216
216
- // Measure in display columns, not UTF-16 code units: clack wraps the rendered
217
- // frame by width, so a CJK character it counts as two columns would slip past
218
- // a `.length` budget and wrap anyway. Accumulating whole code points also keeps
219
- // the cut off a surrogate pair. One column is reserved for the ellipsis.
217
+ // Measure whole grapheme clusters in display columns. Measuring individual
218
+ // code points under-counts sequences such as keycap emoji, while slicing by
219
+ // UTF-16 length can split surrogate pairs or joined emoji. One column is
220
+ // reserved for the ellipsis.
221
let clamped = '';
222
let width = 0;
222
- for (const char of singleLine) {
223
- const charWidth = stringWidth(char);
224
- if (width + charWidth > budget - 1) {
223
+ for (const { segment } of graphemeSegmenter.segment(singleLine)) {
224
+ const segmentWidth = stringWidth(segment);
225
+ if (width + segmentWidth > budget - 1) {
226
break;
227
}
227
- clamped += char;
228
- width += charWidth;
228
+ clamped += segment;
229
+ width += segmentWidth;
230
}
231
return `${clamped}…`;
232
};
233
234
+type StartedClackSpinner = {
235
+ readonly raw: p.SpinnerResult;
236
+ readonly updateMessage: (message: string) => void;
237
+};
238
+
239
function createClackSpinnerHandle(
234
- s: p.SpinnerResult,
235
- defaultMessage: string,
236
- output: Writable
240
+ spinner: StartedClackSpinner,
241
+ defaultMessage: string
242
): { handle: SpinnerHandle; isStopped: () => boolean } {
243
let stopped = false;
244
return {
245
handle: {
241
- message: (msg: string) => Effect.sync(() => s.message(clampSpinnerMessage(output, msg))),
246
+ message: (msg: string) => Effect.sync(() => spinner.updateMessage(msg)),
247
stop: (msg?: string) =>
248
Effect.sync(() => {
249
stopped = true;
245
- s.stop(msg ?? defaultMessage);
250
+ spinner.raw.stop(msg ?? defaultMessage);
251
}),
252
error: (msg?: string) =>
253
Effect.sync(() => {
254
stopped = true;
250
- s.error(msg ?? defaultMessage);
255
+ spinner.raw.error(msg ?? defaultMessage);
256
}),
257
},
258
isStopped: () => stopped,
@@ -283,10 +288,18 @@ export const makeTerminalUI = (streams: TerminalUIStreams): TerminalUI => {
288
};
289
290
/** Start a clack spinner on stderr, clamped to a single terminal row. */
286
- const startSpinner = (message: string): p.SpinnerResult => {
287
- const s = p.spinner({ output: stderr });
288
- s.start(clampSpinnerMessage(stderr, message));
289
- return s;
291
+ const startSpinner = (message: string): StartedClackSpinner => {
292
+ // Clack captures this width during construction and continues wrapping
293
+ // against it. Updates may respect a later narrower terminal, but must never
294
+ // grow beyond Clack's fixed width.
295
+ const initialColumns = getColumns(stderr);
296
+ const raw = p.spinner({ output: stderr });
297
+ raw.start(clampSpinnerMessage(initialColumns, message));
298
+ return {
299
+ raw,
300
+ updateMessage: msg =>
301
+ raw.message(clampSpinnerMessage(Math.min(initialColumns, getColumns(stderr)), msg)),
302
+ };
303
};
304
305
return {
@@ -360,7 +373,7 @@ export const makeTerminalUI = (streams: TerminalUIStreams): TerminalUI => {
373
return Effect.acquireUseRelease(
374
Effect.sync(() => startSpinner(message)),
375
() => effect,
363
- (s, exit) =>
376
+ (spinner, exit) =>
377
Effect.sync(() => {
378
if (Exit.isSuccess(exit)) {
379
let successMessage = message;
@@ -370,9 +383,9 @@ export const makeTerminalUI = (streams: TerminalUIStreams): TerminalUI => {
383
} else if (configuredSuccessMessage !== undefined) {
384
successMessage = configuredSuccessMessage;
385
}
373
- s.stop(successMessage);
386
+ spinner.raw.stop(successMessage);
387
} else {
375
- s.error(options?.errorMessage ?? message);
388
+ spinner.raw.error(options?.errorMessage ?? message);
389
}
390
})
391
);
@@ -385,9 +398,9 @@ export const makeTerminalUI = (streams: TerminalUIStreams): TerminalUI => {
398
399
return Effect.acquireUseRelease(
400
Effect.sync(() => {
388
- const s = startSpinner(message);
389
- const { handle, isStopped } = createClackSpinnerHandle(s, message, stderr);
390
- return { raw: s, handle, isStopped };
401
+ const spinner = startSpinner(message);
402
+ const { handle, isStopped } = createClackSpinnerHandle(spinner, message);
403
+ return { raw: spinner.raw, handle, isStopped };
404
}),
405
({ handle }) => use(handle),
406
({ raw, isStopped }, exit) =>
ts/packages/cli/test/src/services/terminal-ui.test.ts
+68
-20
@@ -173,35 +173,23 @@ describe('TerminalUI', () => {
173
});
174
175
describe('clampSpinnerMessage keeps live spinner messages on one terminal row', () => {
176
- const streamWithColumns = (columns?: number) =>
177
- columns === undefined ? makeSink(true) : Object.assign(makeSink(true), { columns });
178
-
176
it('leaves a message that fits untouched', () => {
180
- expect(clampSpinnerMessage(streamWithColumns(80), 'Checking for updates')).toBe(
181
- 'Checking for updates'
182
- );
177
+ expect(clampSpinnerMessage(80, 'Checking for updates')).toBe('Checking for updates');
178
});
179
180
it('truncates a message longer than the row budget with an ellipsis', () => {
186
- const clamped = clampSpinnerMessage(streamWithColumns(40), 'x'.repeat(100));
181
+ const clamped = clampSpinnerMessage(40, 'x'.repeat(100));
182
expect(clamped).toBe(`${'x'.repeat(32)}…`);
183
expect(clamped).toHaveLength(40 - 7);
184
});
185
186
it('collapses embedded newlines into spaces', () => {
192
- expect(clampSpinnerMessage(streamWithColumns(80), 'line one\nline two')).toBe(
193
- 'line one line two'
194
- );
187
+ expect(clampSpinnerMessage(80, 'line one\nline two')).toBe('line one line two');
188
});
189
190
it('never slices a message containing ANSI escape sequences', () => {
191
const colored = `\u001b[32m${'x'.repeat(100)}\u001b[0m`;
199
- expect(clampSpinnerMessage(streamWithColumns(40), colored)).toBe(colored);
200
- });
201
-
202
- it('falls back to 80 columns when the stream reports no width', () => {
203
- const clamped = clampSpinnerMessage(streamWithColumns(undefined), 'x'.repeat(100));
204
- expect(clamped).toHaveLength(80 - 7);
192
+ expect(clampSpinnerMessage(40, colored)).toBe(colored);
193
});
194
195
it('measures display columns, not UTF-16 code units', () => {
@@ -212,13 +200,23 @@ describe('TerminalUI', () => {
200
expect(message).toHaveLength(20);
201
expect(stringWidth(message)).toBe(40);
202
215
- const clamped = clampSpinnerMessage(streamWithColumns(40), message);
203
+ const clamped = clampSpinnerMessage(40, message);
204
expect(clamped.endsWith('…')).toBe(true);
205
expect(stringWidth(clamped)).toBeLessThanOrEqual(40 - 7);
206
});
207
208
+ it('measures and truncates whole grapheme clusters', () => {
209
+ const keycap = '1\uFE0F\u20E3';
210
+ expect(stringWidth(keycap)).toBe(2);
211
+ expect([...keycap].reduce((width, char) => width + stringWidth(char), 0)).toBe(1);
212
+
213
+ const clamped = clampSpinnerMessage(20, keycap.repeat(20));
214
+ expect(clamped).toMatch(/^(?:1\uFE0F\u20E3)*…$/u);
215
+ expect(stringWidth(clamped)).toBeLessThanOrEqual(20 - 7);
216
+ });
217
+
218
it('never cuts a surrogate pair in half', () => {
221
- const clamped = clampSpinnerMessage(streamWithColumns(20), '\u{1f600}'.repeat(40));
219
+ const clamped = clampSpinnerMessage(20, '\u{1f600}'.repeat(40));
220
expect(clamped).not.toMatch(/[\uD800-\uDBFF](?![\uDC00-\uDFFF])/);
221
expect(stringWidth(clamped)).toBeLessThanOrEqual(20 - 7);
222
});
@@ -226,12 +224,12 @@ describe('TerminalUI', () => {
224
it('degrades to the ellipsis on terminals narrower than the frame overhead', () => {
225
// Below SPINNER_RENDER_OVERHEAD + 1 columns no message length fits, so the
226
// budget bottoms out at one column rather than jumping back up to eight.
229
- expect(clampSpinnerMessage(streamWithColumns(4), 'x'.repeat(100))).toBe('…');
227
+ expect(clampSpinnerMessage(4, 'x'.repeat(100))).toBe('…');
228
});
229
230
it('keeps the rendered frame within the row at the exact budget boundary', () => {
231
const columns = 20;
234
- const clamped = clampSpinnerMessage(streamWithColumns(columns), 'x'.repeat(100));
232
+ const clamped = clampSpinnerMessage(columns, 'x'.repeat(100));
233
// frame (1) + two spaces (2) + message + three animated dots (3).
234
expect(1 + 2 + stringWidth(clamped) + 3).toBeLessThanOrEqual(columns);
235
});
@@ -311,6 +309,56 @@ describe('TerminalUI', () => {
309
)
310
);
311
312
+ it.live('does not grow updates beyond the width Clack captured at construction', () =>
313
+ withFakeTimers(
314
+ Effect.gen(function* () {
315
+ const { ui, stderr } = narrowUi(20);
316
+
317
+ yield* ui.useMakeSpinner('Checking for updates...', spinner =>
318
+ Effect.gen(function* () {
319
+ stderr.columns = 80;
320
+ yield* spinner.message(LONG_UPGRADE_MESSAGE);
321
+ yield* Effect.sync(() => vi.advanceTimersByTime(TICKS_PAST_THREE_DOTS));
322
+ yield* spinner.stop('Upgrade completed!');
323
+ })
324
+ );
325
+
326
+ const frames = clampedFrames(stderr);
327
+ expect(frames.length).toBeGreaterThan(0);
328
+ expect(frames[0]).toContain('New version');
329
+ for (const frame of frames) {
330
+ expect(frame).not.toContain('\n');
331
+ expect(stringWidth(frame)).toBeLessThanOrEqual(20);
332
+ }
333
+ })
334
+ )
335
+ );
336
+
337
+ it.live('respects a terminal that narrows after spinner construction', () =>
338
+ withFakeTimers(
339
+ Effect.gen(function* () {
340
+ const { ui, stderr } = narrowUi(80);
341
+
342
+ yield* ui.useMakeSpinner('Checking for updates...', spinner =>
343
+ Effect.gen(function* () {
344
+ stderr.columns = 20;
345
+ yield* spinner.message(LONG_UPGRADE_MESSAGE);
346
+ yield* Effect.sync(() => vi.advanceTimersByTime(TICKS_PAST_THREE_DOTS));
347
+ yield* spinner.stop('Upgrade completed!');
348
+ })
349
+ );
350
+
351
+ const frames = clampedFrames(stderr);
352
+ expect(frames.length).toBeGreaterThan(0);
353
+ expect(frames[0]).toContain('New version');
354
+ for (const frame of frames) {
355
+ expect(frame).not.toContain('\n');
356
+ expect(stringWidth(frame)).toBeLessThanOrEqual(20);
357
+ }
358
+ })
359
+ )
360
+ );
361
+
362
it.live('clamps the withSpinner start message too', () =>
363
withFakeTimers(
364
Effect.gen(function* () {