@yadurajfleetos/cli 0.1.0

package/dist/render.js

@@ -0,0 +1,159 @@
+/** Terminal rendering. Colour is dropped when output is piped or NO_COLOR is set. */
+const useColour = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR;
+/**
+ * 0 none, 1 the sixteen ANSI colours, 2 twenty-four bit. The brand palette only
+ * survives intact at level 2; below that every shade collapses onto the nearest
+ * basic colour, which is why nothing here encodes meaning in shade alone.
+ */
+export const colourDepth = !useColour
+    ? 0
+    : /truecolor|24bit/i.test(process.env.COLORTERM ?? '')
+        ? 2
+        : 1;
+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. */
+export const rgb = (r, g, b, fallback = (s) => s) => (s) => colourDepth === 2 ? `${ESC}38;2;${r};${g};${b}m${s}${ESC}0m` : fallback(s);
+export const c = {
+    dim: wrap('2'),
+    bold: wrap('1'),
+    green: wrap('32'),
+    yellow: wrap('33'),
+    red: wrap('31'),
+    cyan: wrap('36'),
+    /** The one accent from the marketing site, reserved for live things. */
+    signal: rgb(0x3f, 0xe0, 0x8b, wrap('32')),
+    grey: rgb(0x6b, 0x72, 0x80, wrap('2')),
+};
+export const cursor = {
+    // Cursor controls are terminal capabilities, not colour capabilities. The
+    // progress UI writes to stderr, so stdout may be piped to jq while stderr is
+    // still an interactive terminal that needs its cursor restored.
+    hide: () => `${ESC}?25l`,
+    show: () => `${ESC}?25h`,
+    up: (n) => `${ESC}${n}A`,
+    clearLine: () => `\r${ESC}2K`,
+    clearBelow: () => `${ESC}0J`,
+};
+export const statusColour = (status) => {
+    switch (status) {
+        case 'online':
+        case 'running':
+            return c.green(status);
+        case 'offline':
+        case 'failed':
+            return c.red(status);
+        case 'cordoned':
+        case 'draining':
+        case 'deploying':
+        case 'pinned_unavailable':
+            return c.yellow(status);
+        default:
+            return c.dim(status);
+    }
+};
+/**
+ * Column widths are measured on the visible text, not the escaped string —
+ * otherwise colour codes count toward the width and every column drifts.
+ */
+// SGR is what Fleet emits today, but accept all CSI sequences so a value that
+// arrives already decorated by a caller cannot make width accounting drift.
+// OSC covers terminal hyperlinks, which are zero-width too.
+const ANSI = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))/g;
+const isZeroWidth = (code) => (code >= 0x0300 && code <= 0x036f) ||
+    (code >= 0x1ab0 && code <= 0x1aff) ||
+    (code >= 0x1dc0 && code <= 0x1dff) ||
+    (code >= 0x20d0 && code <= 0x20ff) ||
+    (code >= 0xfe00 && code <= 0xfe0f) ||
+    (code >= 0xfe20 && code <= 0xfe2f) ||
+    code === 0x200d;
+/** A pragmatic terminal-cell width for the CLI's labels and progress lines. */
+const cellWidth = (grapheme) => {
+    const points = [...grapheme].map((char) => char.codePointAt(0));
+    if (!points.length || points.every(isZeroWidth))
+        return 0;
+    // Emoji presentation and common wide East Asian ranges occupy two cells in
+    // mainstream terminals. A grapheme stays one unit here, so ZWJ emoji do not
+    // accidentally count once per constituent code point.
+    if (points.some((code) => code >= 0x1f000 ||
+        (code >= 0x1100 && code <= 0x115f) ||
+        (code >= 0x2e80 && code <= 0xa4cf) ||
+        (code >= 0xac00 && code <= 0xd7a3) ||
+        (code >= 0xf900 && code <= 0xfaff) ||
+        (code >= 0xff01 && code <= 0xff60) ||
+        (code >= 0xffe0 && code <= 0xffe6)))
+        return 2;
+    return 1;
+};
+const graphemes = (text) => {
+    // Segmenter prevents a truncation point from splitting an emoji, accent, or
+    // other user-visible character. The fallback remains correct enough on old
+    // Node versions: it only loses the nicer grapheme boundary.
+    const Segmenter = Intl.Segmenter;
+    return Segmenter
+        ? [...new Segmenter().segment(text)].map((part) => part.segment)
+        : [...text];
+};
+const visibleLength = (s) => graphemes(s.replace(ANSI, '')).reduce((width, grapheme) => width + cellWidth(grapheme), 0);
+export function table(headers, rows) {
+    // Printing a header over nothing looks like a bug; callers handle the
+    // empty case with a sentence instead.
+    if (!rows.length)
+        return '';
+    const widths = headers.map((h, i) => Math.max(visibleLength(h), ...rows.map((r) => visibleLength(r[i] ?? ''))));
+    const pad = (s, width) => s + ' '.repeat(Math.max(0, width - visibleLength(s)));
+    const head = headers.map((h, i) => c.dim(pad(h.toUpperCase(), widths[i]))).join('  ');
+    const body = rows.map((r) => r.map((cell, i) => pad(cell ?? '', widths[i])).join('  '));
+    return [head, ...body].join('\n');
+}
+export function keyValues(pairs) {
+    const width = Math.max(...pairs.map(([k]) => k.length));
+    return pairs.map(([k, v]) => `${c.dim(k.padEnd(width))}  ${v}`).join('\n');
+}
+/** Handles both directions: a heartbeat in the past, a token expiring ahead. */
+export function relativeTime(iso) {
+    if (!iso)
+        return 'never';
+    const seconds = Math.round((Date.now() - new Date(iso).getTime()) / 1000);
+    const magnitude = Math.abs(seconds);
+    const suffix = seconds >= 0 ? 'ago' : 'from now';
+    if (magnitude < 60)
+        return `${magnitude}s ${suffix}`;
+    if (magnitude < 3600)
+        return `${Math.round(magnitude / 60)}m ${suffix}`;
+    if (magnitude < 86400)
+        return `${Math.round(magnitude / 3600)}h ${suffix}`;
+    return `${Math.round(magnitude / 86400)}d ${suffix}`;
+}
+export const mb = (value) => value >= 1024 ? `${(value / 1024).toFixed(1)}GB` : `${value}MB`;
+/**
+ * Cut to a visible width, stepping over colour codes rather than counting them.
+ * Anything that redraws in place depends on this: a line that wraps occupies two
+ * terminal rows, and the cursor arithmetic above it silently goes wrong.
+ */
+export function truncate(text, width) {
+    const limit = Math.max(1, width);
+    if (visibleLength(text) <= limit)
+        return text;
+    let out = '';
+    let visible = 0;
+    let hasSgr = false;
+    for (let i = 0; i < text.length; i++) {
+        const escape = text.slice(i).match(/^\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))/);
+        if (escape) {
+            out += escape[0];
+            hasSgr ||= /^\x1b\[[0-9;]*m$/.test(escape[0]);
+            i += escape[0].length - 1;
+            continue;
+        }
+        const [grapheme] = graphemes(text.slice(i));
+        const cells = cellWidth(grapheme);
+        if (visible + cells > limit - 1)
+            break;
+        out += grapheme;
+        i += grapheme.length - 1;
+        visible += cells;
+    }
+    return `${out}…${hasSgr ? `${ESC}0m` : ''}`;
+}
+export { visibleLength };

package/dist/ui.js

@@ -0,0 +1,210 @@
+/**
+ * Progress reporting.
+ *
+ * Two rules shape everything here. Animation goes to stderr, so `--json` on
+ * stdout stays pipeable into jq. And every animated form has a plain-line
+ * 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 { 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 = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const TICK = 80;
+export const glyph = {
+    ok: c.signal('✔'),
+    fail: c.red('✖'),
+    warn: c.yellow('▲'),
+    info: c.cyan('›'),
+    pending: c.dim('·'),
+};
+/** Elapsed time, shown only once it is long enough to be worth knowing. */
+const elapsed = (startedAt) => {
+    const seconds = (Date.now() - startedAt) / 1000;
+    return seconds < 2 ? '' : c.dim(` ${seconds.toFixed(seconds < 10 ? 1 : 0)}s`);
+};
+let restoreCursorHooked = false;
+function hookCursorRestore() {
+    if (restoreCursorHooked)
+        return;
+    restoreCursorHooked = true;
+    // A spinner interrupted by ^C must not leave the cursor hidden in the shell.
+    const restore = () => err.write(cursor.show());
+    process.on('exit', restore);
+    for (const signal of ['SIGINT', 'SIGTERM']) {
+        process.on(signal, () => {
+            restore();
+            process.exit(signal === 'SIGINT' ? 130 : 143);
+        });
+    }
+}
+export function spinner(label) {
+    const startedAt = Date.now();
+    let text = label;
+    let hintLines = [];
+    let frame = 0;
+    let timer;
+    let done = false;
+    if (!animated()) {
+        err.write(`${label}…\n`);
+        return {
+            update(next) {
+                text = next;
+                err.write(`${next}…\n`);
+            },
+            hints(lines) {
+                hintLines = lines;
+            },
+            note: (line) => err.write(`${line}\n`),
+            succeed: (final) => err.write(`${final ?? text} — done\n`),
+            fail: (final) => err.write(`${final ?? text} — failed\n`),
+            stop: () => { },
+        };
+    }
+    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()));
+        frame++;
+    };
+    draw();
+    timer = setInterval(draw, TICK);
+    timer.unref?.();
+    const settle = (mark, final) => {
+        if (done)
+            return;
+        done = true;
+        clearInterval(timer);
+        clear();
+        err.write(`${mark} ${final ?? text}${elapsed(startedAt)}\n${cursor.show()}`);
+    };
+    return {
+        update: (next) => {
+            text = next;
+            draw();
+        },
+        hints: (lines) => {
+            hintLines = lines;
+        },
+        note: (line) => {
+            clear();
+            err.write(`${line}\n`);
+            draw();
+        },
+        succeed: (final) => settle(glyph.ok, final),
+        fail: (final) => settle(glyph.fail, final),
+        stop: () => {
+            if (done)
+                return;
+            done = true;
+            clearInterval(timer);
+            clear();
+            err.write(cursor.show());
+        },
+    };
+}
+/** Run work under a spinner, settling it correctly on either outcome. */
+export async function task(label, run, opts = {}) {
+    const s = spinner(label);
+    if (opts.hints)
+        s.hints(opts.hints);
+    try {
+        const value = await run(s);
+        s.succeed(opts.done?.(value));
+        return value;
+    }
+    catch (error) {
+        s.fail();
+        throw error;
+    }
+}
+/**
+ * The full-mark loading screen: the mesh pulses above a status line for the
+ * duration of the work. Reserved for the operations that genuinely take minutes
+ * — using it for a fast request would just add latency to look busy.
+ */
+export async function splash(label, run, opts = {}) {
+    const rows = process.stdout.rows ?? 24;
+    // Not enough room to redraw in place means the frames would scroll and stack.
+    if (!animated() || rows < MARK_HEIGHT + 4) {
+        return task(label, (s) => run(s), opts);
+    }
+    const startedAt = Date.now();
+    let text = label;
+    let hintLines = opts.hints ?? [];
+    let phase = 0;
+    let painted = 0;
+    hookCursorRestore();
+    err.write(cursor.hide());
+    const draw = () => {
+        if (painted)
+            err.write(cursor.up(painted) + '\r' + cursor.clearBelow());
+        const hint = hintLines.length
+            ? hintLines[Math.floor((Date.now() - startedAt) / 3200) % hintLines.length]
+            : '';
+        const lines = [
+            ...markFrame(phase).map((line) => `  ${line}`),
+            '',
+            `  ${c.signal(FRAMES[Math.floor(phase * 2) % FRAMES.length])} ${text}${elapsed(startedAt)}`,
+            hint ? `    ${c.dim(hint)}` : '',
+        ];
+        err.write(lines.map((line) => truncate(line, width())).join('\n') + '\n');
+        painted = lines.length;
+        // One peer every four ticks: slow enough to follow the pulse around.
+        phase = (phase + 0.25) % PEER_COUNT;
+    };
+    draw();
+    const timer = setInterval(draw, TICK);
+    timer.unref?.();
+    const teardown = () => {
+        clearInterval(timer);
+        if (painted)
+            err.write(cursor.up(painted) + '\r' + cursor.clearBelow());
+        painted = 0;
+        err.write(cursor.show());
+    };
+    try {
+        const value = await run({
+            update: (next) => {
+                text = next;
+            },
+            hints: (lines) => {
+                hintLines = lines;
+            },
+        });
+        teardown();
+        err.write(`${glyph.ok} ${opts.done?.(value) ?? text}${elapsed(startedAt)}\n`);
+        return value;
+    }
+    catch (error) {
+        teardown();
+        err.write(`${glyph.fail} ${text}${elapsed(startedAt)}\n`);
+        throw error;
+    }
+}
+/** A titled rule, for separating sections of a long report. */
+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)}`;
+}
+/** 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));
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@yadurajfleetos/cli",
+  "version": "0.1.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"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "dev": "tsx src/index.ts",
+    "build": "tsc -p tsconfig.json",
+    "prepublishOnly": "npm run build && npm test",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test --import tsx tests/*.test.ts"
+  },
+  "dependencies": {
+    "yaml": "^2.9.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.2.0",
+    "tsx": "^4.23.12",
+    "typescript": "^7.0.2"
+  },
+  "keywords": [
+    "fleet",
+    "orchestration",
+    "deployment",
+    "homelab",
+    "docker",
+    "self-hosted"
+  ]
+}