@yadurajfleetos/cli 0.1.8 → 0.2.0

package/dist/prompt.js

@@ -0,0 +1,205 @@
+/**
+ * Interactive prompts.
+ *
+ * One implementation each, because four hand-rolled versions of "are you sure"
+ * drifted into four different answers to the questions that actually matter: what
+ * happens when stdin is not a terminal, whether silence counts as consent, and
+ * whether a typed password can end up in the scrollback.
+ *
+ * Prompts write to stderr, like the rest of the progress UI, so a command that
+ * both asks a question and emits `--json` stays pipeable into jq.
+ */
+import { createInterface } from 'node:readline/promises';
+import { c, cursor, glyphs, truncate, unicode } from './render.js';
+import { CliError, EXIT } from './api.js';
+import { activeLadder } from './ladder.js';
+import { glyph, width } from './ui.js';
+const err = process.stderr;
+/** Asking a question needs somewhere to read the answer from and somewhere to show it. */
+export const canPrompt = () => Boolean(process.stdin.isTTY && err.isTTY);
+/**
+ * A ladder owns the cursor while it is live, so it has to stand down for the
+ * duration of a prompt rather than redraw over the question being asked.
+ */
+async function withTerminal(run) {
+    const live = activeLadder();
+    live?.suspend();
+    try {
+        return await run();
+    }
+    finally {
+        live?.resume();
+    }
+}
+/**
+ * A yes/no question.
+ *
+ * The two policies are deliberately separate knobs, because for the destructive
+ * commands they genuinely differ: `fleet deploy` and `fleet down` want Enter to
+ * mean *no* at a keyboard — an accidental return should not roll out a build —
+ * while a scripted CI step that pipes no stdin should still proceed without
+ * needing `--yes`. `ifNoTerminal` defaults to `default` when a caller has no such
+ * split, and `fleet rm` sets neither: it refuses both ways.
+ */
+export async function confirm(question, opts = {}) {
+    const fallback = opts.default ?? false;
+    if (!canPrompt())
+        return opts.ifNoTerminal ?? fallback;
+    return withTerminal(async () => {
+        const rl = createInterface({ input: process.stdin, output: err });
+        try {
+            const answer = (await rl.question(`  ${question} ${c.dim(fallback ? '[Y/n]' : '[y/N]')} `))
+                .trim()
+                .toLowerCase();
+            if (!answer)
+                return fallback;
+            return answer === 'y' || answer === 'yes';
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+/** A free-text answer. Empty input is rejected rather than silently accepted. */
+export async function ask(label, opts = {}) {
+    if (!canPrompt())
+        throw new CliError(`${label.trim()} is required, and there is no terminal to ask on.`, EXIT.usage);
+    return withTerminal(async () => {
+        if (opts.hint)
+            err.write(`${c.dim(`  ${opts.hint}`)}\n`);
+        const rl = createInterface({ input: process.stdin, output: err });
+        try {
+            const value = (await rl.question(`  ${c.dim(label.padEnd(18))}`)).trim();
+            if (!value)
+                throw new CliError(`${label.trim()} is required.`, EXIT.usage);
+            return value;
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+/**
+ * The same, with the echo suppressed. A password or token must not survive in the
+ * terminal scrollback or in a screen recording, which rules out letting readline
+ * echo it and clearing the line afterwards.
+ */
+export async function askSecret(label, opts = {}) {
+    if (!canPrompt())
+        throw new CliError(`${label.trim()} is required, and there is no terminal to ask on.`, EXIT.usage);
+    return withTerminal(async () => {
+        if (opts.hint)
+            err.write(`${c.dim(`  ${opts.hint}`)}\n`);
+        const rl = createInterface({ input: process.stdin, output: err });
+        try {
+            err.write(`  ${c.dim(label.padEnd(18))}`);
+            // The prompt is written directly, then readline's own echo is disabled, so
+            // nothing typed after this point reaches the terminal at all.
+            const internal = rl;
+            internal._writeToOutput = () => { };
+            const value = (await rl.question('')).trim();
+            err.write('\n');
+            if (!value)
+                throw new CliError(`${label.trim()} is required.`, EXIT.usage);
+            return value;
+        }
+        finally {
+            rl.close();
+        }
+    });
+}
+const KEY = {
+    up: ['\x1b[A', '\x1bOA', 'k'],
+    down: ['\x1b[B', '\x1bOB', 'j'],
+    enter: ['\r', '\n'],
+    cancel: ['\x03', 'q', '\x1b'],
+};
+/**
+ * An arrow-key picker. Callers must check `canPrompt()` first and raise their own
+ * error otherwise: the message a script sees when it forgets `--fleet` is part of
+ * that command's contract, and this function does not know what it should say.
+ */
+export async function select(title, choices) {
+    if (!choices.length)
+        throw new CliError('Nothing to choose from.', EXIT.usage);
+    if (!canPrompt())
+        throw new CliError('No interactive terminal to choose on.', EXIT.usage);
+    return withTerminal(() => new Promise((resolve) => {
+        let index = 0;
+        let painted = 0;
+        const pad = Math.max(...choices.map((choice) => choice.label.length));
+        const keys = unicode ? '↑↓ move · enter select · q cancel' : 'up/down move, enter select, q cancel';
+        const draw = () => {
+            const lines = [
+                `  ${c.bold(title)}`,
+                ...choices.map((choice, i) => {
+                    const pointer = i === index ? c.signal(glyphs.pointer) : ' ';
+                    const label = i === index ? c.signal(choice.label.padEnd(pad)) : choice.label.padEnd(pad);
+                    return `  ${pointer} ${label}${choice.hint ? `  ${c.dim(choice.hint)}` : ''}`;
+                }),
+                c.dim(`    ${keys}`),
+            ].map((line) => truncate(line, width()));
+            err.write((painted ? cursor.up(painted) + '\r' + cursor.clearBelow() : '') +
+                lines.join('\n') +
+                '\n');
+            painted = lines.length;
+        };
+        const stdin = process.stdin;
+        const wasRaw = Boolean(stdin.isRaw);
+        const teardown = () => {
+            stdin.off('data', onData);
+            stdin.setRawMode?.(wasRaw);
+            stdin.pause();
+            // `ESC[0A` is read as up-one by most terminals, so an unpainted list
+            // must not try to move at all.
+            if (painted)
+                err.write(cursor.up(painted) + '\r' + cursor.clearBelow());
+            err.write(cursor.show());
+            painted = 0;
+        };
+        function onData(chunk) {
+            // A chunk carries a whole escape sequence, or several keys at once.
+            const key = chunk.toString();
+            if (KEY.cancel.includes(key)) {
+                teardown();
+                err.write(`${glyph.pending} ${c.dim('cancelled')}\n`);
+                // In raw mode ^C arrives as a byte, not a signal, so the exit code
+                // has to be produced here or the shell sees a clean exit.
+                process.exit(key === '\x03' ? 130 : EXIT.ok);
+            }
+            if (KEY.enter.includes(key)) {
+                const chosen = choices[index];
+                teardown();
+                err.write(`${glyph.ok} ${c.bold(title)}  ${chosen.label}\n`);
+                resolve(chosen.value);
+                return;
+            }
+            if (KEY.up.includes(key))
+                index = (index - 1 + choices.length) % choices.length;
+            else if (KEY.down.includes(key))
+                index = (index + 1) % choices.length;
+            else if (/^[1-9]$/.test(key) && Number(key) <= choices.length)
+                index = Number(key) - 1;
+            else
+                return;
+            draw();
+        }
+        err.write(cursor.hide());
+        draw();
+        stdin.setEncoding('utf8');
+        stdin.setRawMode?.(true);
+        stdin.on('data', onData);
+        stdin.resume();
+    }));
+}
+/**
+ * Offer a picker when a name did not match, and otherwise raise the error the
+ * command would have raised anyway. Used by the three lookups that previously
+ * only listed the valid names and left the operator to retype one.
+ */
+export async function selectOrThrow(title, choices, error) {
+    if (!canPrompt() || !choices.length)
+        throw error;
+    err.write(`${glyph.warn} ${error.message.split('\n')[0]}\n`);
+    return select(title, choices);
+}

package/dist/render.js

@@ -10,6 +10,59 @@ export const colourDepth = !useColour
     : /truecolor|24bit/i.test(process.env.COLORTERM ?? '')
         ? 2
         : 1;
+/**
+ * Whether the terminal can be trusted with braille, box-drawing and block
+ * glyphs. This is a separate question from colour: a terminal that renders
+ * `⠋` as a replacement box makes the CLI look broken, whereas plain ASCII only
+ * looks plain. So the guess errs toward ASCII and takes overrides in both
+ * directions — `FLEET_ASCII=1` forces the fallback, `FLEET_UNICODE=1` forces the
+ * glyphs on for the many Linux shells that simply never set a locale.
+ */
+export const unicode = process.env.FLEET_ASCII
+    ? false
+    : process.env.FLEET_UNICODE
+        ? true
+        : process.env.TERM === 'dumb'
+            ? false
+            : /utf-?8/i.test(`${process.env.LC_ALL ?? ''} ${process.env.LC_CTYPE ?? ''} ${process.env.LANG ?? ''}`) ||
+                Boolean(process.env.WT_SESSION) ||
+                Boolean(process.env.TERM_PROGRAM);
+/**
+ * One vocabulary, chosen once, so no caller ever branches on `unicode`. Every
+ * entry is a single terminal cell wide in both sets — the progress UI redraws in
+ * place and a two-cell glyph would shift everything after it.
+ */
+export const glyphs = unicode
+    ? {
+        frames: ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'],
+        ok: '✔',
+        fail: '✖',
+        warn: '▲',
+        info: '›',
+        pending: '·',
+        stepActive: '◆',
+        stepTodo: '○',
+        pointer: '❯',
+        barFill: '█',
+        barEmpty: '░',
+        branch: '└',
+        rule: '─',
+    }
+    : {
+        frames: ['-', '\\', '|', '/'],
+        ok: 'v',
+        fail: 'x',
+        warn: '!',
+        info: '>',
+        pending: '.',
+        stepActive: '>',
+        stepTodo: '.',
+        pointer: '>',
+        barFill: '#',
+        barEmpty: '.',
+        branch: '\\',
+        rule: '-',
+    };
 const ESC = '\x1b[';
 const wrap = (code) => (s) => (useColour ? `${ESC}${code}m${s}${ESC}0m` : s);
 /** Truecolour when the terminal has it, otherwise the supplied fallback. */
@@ -32,6 +85,10 @@ export const cursor = {
     hide: () => `${ESC}?25l`,
     show: () => `${ESC}?25h`,
     up: (n) => `${ESC}${n}A`,
+    // Moving down with a control sequence rather than a newline matters at the
+    // bottom of the screen: `\n` there scrolls the region out from under the
+    // cursor arithmetic, `ESC[nB` cannot.
+    down: (n) => `${ESC}${n}B`,
     clearLine: () => `\r${ESC}2K`,
     clearBelow: () => `${ESC}0J`,
 };

package/dist/ui.js

@@ -6,29 +6,86 @@
  * fallback, so output captured by CI or a log file reads as a transcript rather
  * than as a smear of cursor escapes.
  */
-import { c, cursor, truncate, visibleLength } from './render.js';
+import { c, cursor, glyphs, truncate, visibleLength } from './render.js';
 import { MARK_HEIGHT, markFrame, PEER_COUNT } from './mark.js';
 const err = process.stderr;
 /** `columns` reads 0 on some pseudo-terminals, so `??` is not enough. */
-const width = () => Math.max(1, (err.columns || process.stdout.columns || 80) - 1);
-/** Animate only where it can be erased again. */
-export const animated = () => Boolean(err.isTTY) && !process.env.CI && !process.env.FLEET_NO_ANIMATION;
-const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+export const width = () => Math.max(1, (err.columns || process.stdout.columns || 80) - 1);
+/**
+ * `--quiet` drops progress entirely: no frames, no settled lines. Errors still
+ * print, because a command that failed silently is worse than a noisy one.
+ */
+let quiet = false;
+export const setQuiet = (value) => {
+    quiet = value;
+};
+export const isQuiet = () => quiet;
+/**
+ * Animate only where it can be erased again. `FLEET_ANIMATION` overrides the
+ * detection in both directions for recordings and for terminals the heuristics
+ * read wrongly; `FLEET_NO_ANIMATION` keeps working as it always has.
+ */
+export const animated = () => {
+    if (quiet)
+        return false;
+    if (process.env.FLEET_ANIMATION === '0')
+        return false;
+    if (process.env.FLEET_ANIMATION === '1')
+        return true;
+    return Boolean(err.isTTY) && !process.env.CI && !process.env.FLEET_NO_ANIMATION;
+};
+const FRAMES = glyphs.frames;
 const TICK = 80;
+/**
+ * Redrawing in place is slower to watch over a long link than locally, and a
+ * tall region costs proportionally more per frame. Neither is worth 12 frames a
+ * second.
+ */
+export const tickFor = (height) => process.env.SSH_CONNECTION || process.env.SSH_TTY || height > 10 ? 200 : TICK;
 export const glyph = {
-    ok: c.signal('✔'),
-    fail: c.red('✖'),
-    warn: c.yellow('▲'),
-    info: c.cyan('›'),
-    pending: c.dim('·'),
+    ok: c.signal(glyphs.ok),
+    fail: c.red(glyphs.fail),
+    warn: c.yellow(glyphs.warn),
+    info: c.cyan(glyphs.info),
+    pending: c.dim(glyphs.pending),
 };
-/** Elapsed time, shown only once it is long enough to be worth knowing. */
-const elapsed = (startedAt) => {
-    const seconds = (Date.now() - startedAt) / 1000;
+/** A duration, shown only once it is long enough to be worth knowing. */
+export const duration = (ms) => {
+    const seconds = ms / 1000;
     return seconds < 2 ? '' : c.dim(` ${seconds.toFixed(seconds < 10 ? 1 : 0)}s`);
 };
+/** Time since a start point. Ticks up while a step is in flight. */
+export const elapsed = (startedAt) => duration(Date.now() - startedAt);
+/**
+ * Exactly one thing may own an in-place redraw region at a time. Two writers
+ * moving the cursor relative to their own idea of where it is do not produce
+ * half-correct output, they produce shredded output — so the second writer stays
+ * quiet rather than fighting for the rows.
+ */
+let regionOwner = null;
+export const claimRegion = (owner) => {
+    if (regionOwner)
+        return false;
+    regionOwner = owner;
+    return true;
+};
+export const releaseRegion = (owner) => {
+    if (regionOwner === owner)
+        regionOwner = null;
+};
+export const regionActive = () => regionOwner !== null;
+/**
+ * Run while a ^C is being handled, before the process leaves. This is how the
+ * live region gets erased and how a command says what it left running — killing
+ * the CLI does not kill a build that is already underway on the control plane,
+ * and pretending otherwise is the misleading part.
+ */
+let onInterrupt = null;
+export const setInterruptHandler = (fn) => {
+    onInterrupt = fn;
+};
 let restoreCursorHooked = false;
-function hookCursorRestore() {
+export function hookCursorRestore() {
     if (restoreCursorHooked)
         return;
     restoreCursorHooked = true;
@@ -37,11 +94,33 @@ function hookCursorRestore() {
     process.on('exit', restore);
     for (const signal of ['SIGINT', 'SIGTERM']) {
         process.on(signal, () => {
+            try {
+                onInterrupt?.();
+            }
+            catch {
+                // A failing teardown must not stop the cursor being restored.
+            }
             restore();
             process.exit(signal === 'SIGINT' ? 130 : 143);
         });
     }
 }
+/** A spinner that reports nothing: `--quiet`, or a region already owned. */
+const silentSpinner = (label) => {
+    let text = label;
+    return {
+        update: (next) => {
+            text = next;
+        },
+        hints: () => { },
+        note: () => { },
+        succeed: () => { },
+        fail: () => { },
+        stop: () => {
+            void text;
+        },
+    };
+};
 export function spinner(label) {
     const startedAt = Date.now();
     let text = label;
@@ -49,6 +128,9 @@ export function spinner(label) {
     let frame = 0;
     let timer;
     let done = false;
+    // A ladder already owns the cursor; a second writer would shred both.
+    if (quiet || regionActive())
+        return silentSpinner(label);
     if (!animated()) {
         err.write(`${label}…\n`);
         return {
@@ -65,18 +147,21 @@ export function spinner(label) {
             stop: () => { },
         };
     }
+    const owner = {};
+    claimRegion(owner);
     hookCursorRestore();
     err.write(cursor.hide());
-    const clear = () => err.write(cursor.clearLine());
     const draw = () => {
         // A hint every third of a spinner cycle: long enough to read, short enough
         // that the line is visibly alive during a multi-minute build.
         const hint = hintLines.length
             ? hintLines[Math.floor((Date.now() - startedAt) / 3200) % hintLines.length]
             : undefined;
-        clear();
-        err.write(truncate(`${c.signal(FRAMES[frame % FRAMES.length])} ${text}${elapsed(startedAt)}` +
-            (hint ? c.dim(`  ${hint}`) : ''), width()));
+        // One write per frame. Clearing and drawing separately doubles the syscalls
+        // and can be seen as a flicker on a slow link.
+        err.write(cursor.clearLine() +
+            truncate(`${c.signal(FRAMES[frame % FRAMES.length])} ${text}${elapsed(startedAt)}` +
+                (hint ? c.dim(`  ${hint}`) : ''), width()));
         frame++;
     };
     draw();
@@ -87,8 +172,8 @@ export function spinner(label) {
             return;
         done = true;
         clearInterval(timer);
-        clear();
-        err.write(`${mark} ${final ?? text}${elapsed(startedAt)}\n${cursor.show()}`);
+        releaseRegion(owner);
+        err.write(cursor.clearLine() + `${mark} ${final ?? text}${elapsed(startedAt)}\n` + cursor.show());
     };
     return {
         update: (next) => {
@@ -99,8 +184,7 @@ export function spinner(label) {
             hintLines = lines;
         },
         note: (line) => {
-            clear();
-            err.write(`${line}\n`);
+            err.write(cursor.clearLine() + `${line}\n`);
             draw();
         },
         succeed: (final) => settle(glyph.ok, final),
@@ -110,8 +194,8 @@ export function spinner(label) {
                 return;
             done = true;
             clearInterval(timer);
-            clear();
-            err.write(cursor.show());
+            releaseRegion(owner);
+            err.write(cursor.clearLine() + cursor.show());
         },
     };
 }
@@ -198,13 +282,14 @@ export async function splash(label, run, opts = {}) {
 export function rule(label) {
     const width = Math.min(process.stdout.columns ?? 80, 72);
     if (!label)
-        return c.dim('─'.repeat(width));
-    const line = '─'.repeat(Math.max(0, width - visibleLength(label) - 3));
-    return `${c.dim('──')} ${c.bold(label)} ${c.dim(line)}`;
+        return c.dim(glyphs.rule.repeat(width));
+    const line = glyphs.rule.repeat(Math.max(0, width - visibleLength(label) - 3));
+    return `${c.dim(glyphs.rule.repeat(2))} ${c.bold(label)} ${c.dim(line)}`;
 }
 /** A horizontal meter. Used for headroom, where the shape matters more than the number. */
 export function bar(fraction, width = 12) {
-    const filled = Math.round(Math.max(0, Math.min(1, fraction)) * width);
-    const colour = fraction > 0.85 ? c.red : fraction > 0.65 ? c.yellow : c.signal;
-    return colour('█'.repeat(filled)) + c.dim('░'.repeat(width - filled));
+    const clamped = Math.max(0, Math.min(1, fraction));
+    const filled = Math.round(clamped * width);
+    const colour = clamped > 0.85 ? c.red : clamped > 0.65 ? c.yellow : c.signal;
+    return colour(glyphs.barFill.repeat(filled)) + c.dim(glyphs.barEmpty.repeat(width - filled));
 }

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@yadurajfleetos/cli",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Fleet OS command-line interface for deploying and orchestrating services on user-owned hardware",
   "type": "module",
   "license": "MIT",
   "bin": {
-    "fleet": "./dist/index.js"
+    "fleet": "dist/index.js"
   },
   "files": [
     "dist",