@yadurajfleetos/cli 0.1.8 → 0.2.0

package/dist/ladder.js

@@ -0,0 +1,290 @@
+/**
+ * A progress ladder: several named steps sharing one redraw region, each
+ * settling in place as it completes.
+ *
+ * This exists because a stack of independent spinners cannot answer the only
+ * question an operator has during a four-minute deploy — where am I. Completed
+ * steps stay on screen, the active step carries the clock, and the steps still to
+ * come are listed from the start, so the shape of the whole operation is legible
+ * before it has finished.
+ *
+ * The two rules from ui.ts still hold. Everything here goes to stderr, so `--json`
+ * on stdout stays pipeable into jq. And every animated form has a plain-line
+ * transcript equivalent, so a CI log reads as a sequence of events rather than as
+ * a smear of cursor escapes.
+ */
+import { c, cursor, glyphs, truncate } from './render.js';
+import { MARK_HEIGHT, markFrame, PEER_COUNT } from './mark.js';
+import { animated, claimRegion, duration, elapsed, glyph, hookCursorRestore, isQuiet, releaseRegion, setInterruptHandler, tickFor, width, } from './ui.js';
+const err = process.stderr;
+/**
+ * The live ladder, if there is one. Prompts need to find it in order to step
+ * aside for it; threading it through every call site instead would mean every
+ * command that can prompt has to know whether it is inside a ladder.
+ */
+let current = null;
+export const activeLadder = () => current;
+const screenRows = () => err.rows || process.stdout.rows || 24;
+export function ladder(steps, opts = {}) {
+    const rows = steps.map((step) => ({ ...step, state: 'todo' }));
+    const at = (key) => rows.find((row) => row.key === key);
+    // The mark is the first thing to go when the terminal is short: the steps carry
+    // the information, the mesh only carries the brand.
+    const withMark = Boolean(opts.mark) && screenRows() >= MARK_HEIGHT + rows.length + 5;
+    // One spare row for the detail line that appears under the active step.
+    const height = (withMark ? MARK_HEIGHT + 1 : 0) + rows.length + 1;
+    const indent = withMark ? '  ' : '';
+    const owner = {};
+    // claimRegion mutates, so it stays last: a ladder that is too tall to redraw
+    // must not take ownership on its way to the transcript fallback.
+    const live = animated() && !isQuiet() && screenRows() >= height + 2 && claimRegion(owner);
+    const tick = tickFor(height);
+    let ticks = 0;
+    let phase = 0;
+    let painted = [];
+    let timer;
+    let closed = false;
+    let lastTranscriptDetail = 0;
+    const took = (row) => row.state === 'active' ? elapsed(row.startedAt ?? Date.now()) : duration(row.took ?? 0);
+    const render = (row, spin) => {
+        const marker = row.state === 'active'
+            ? c.signal(spin)
+            : row.state === 'done'
+                ? glyph.ok
+                : row.state === 'fail'
+                    ? glyph.fail
+                    : glyph.pending;
+        const dimmed = row.state === 'todo' || row.state === 'skip';
+        const label = dimmed ? c.dim(row.label) : row.label;
+        const summary = row.summary ? `  ${c.dim(row.summary)}` : '';
+        return `${marker} ${label}${summary}${took(row)}`;
+    };
+    const frame = () => {
+        const spin = glyphs.frames[ticks % glyphs.frames.length];
+        const body = rows.flatMap((row) => {
+            const out = [`${indent}${render(row, spin)}`];
+            if (row.state === 'active' && row.detail)
+                out.push(`${indent}  ${c.dim(`${glyphs.branch} ${row.detail}`)}`);
+            return out;
+        });
+        const head = withMark
+            ? [
+                ...markFrame(phase).map((line, i) => `  ${line}${i === 2 && opts.title ? `    ${c.bold(opts.title)}` : ''}`),
+                '',
+            ]
+            : [];
+        return [...head, ...body].map((line) => truncate(line, width()));
+    };
+    /**
+     * Rewrite only the rows that moved, batched into a single write. A full repaint
+     * of a nine-row region twelve times a second is visible as flicker over SSH,
+     * and most frames change one row.
+     */
+    const paint = (lines) => {
+        if (!lines.length)
+            return;
+        if (painted.length !== lines.length) {
+            // The row count changed, so a partial rewrite would orphan rows below.
+            err.write((painted.length ? cursor.up(painted.length) + '\r' + cursor.clearBelow() : '') +
+                lines.join('\n') +
+                '\n');
+            painted = lines;
+            return;
+        }
+        let first = -1;
+        let last = -1;
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i] !== painted[i]) {
+                if (first < 0)
+                    first = i;
+                last = i;
+            }
+        }
+        // Nothing moved: leave the terminal completely alone.
+        if (first < 0)
+            return;
+        let out = cursor.up(lines.length - first);
+        for (let i = first; i <= last; i++) {
+            if (lines[i] !== painted[i])
+                out += cursor.clearLine() + lines[i];
+            out += '\n';
+        }
+        // Back to where the region ends, without a newline that could scroll it.
+        const below = lines.length - 1 - last;
+        if (below > 0)
+            out += cursor.down(below);
+        err.write(out);
+        painted = lines;
+    };
+    const erase = () => {
+        if (!painted.length)
+            return;
+        err.write(cursor.up(painted.length) + '\r' + cursor.clearBelow());
+        painted = [];
+    };
+    const advance = () => {
+        ticks += 1;
+        // Scale the pulse by the tick so it travels at the same speed on a slow link.
+        phase = (phase + 0.25 * (tick / 80)) % PEER_COUNT;
+        paint(frame());
+    };
+    const start = () => {
+        timer = setInterval(advance, tick);
+        timer.unref?.();
+    };
+    /** One transcript line per transition — the same rule the spinner follows. */
+    const transcript = (line) => {
+        if (!isQuiet())
+            err.write(`${line}\n`);
+    };
+    const api = {
+        begin(key, label) {
+            const row = at(key);
+            if (!row)
+                return;
+            if (label)
+                row.label = label;
+            row.state = 'active';
+            row.startedAt = Date.now();
+            row.detail = undefined;
+            if (live)
+                paint(frame());
+            else
+                transcript(`${c.dim(glyphs.stepActive)} ${row.label}…`);
+        },
+        detail(key, text) {
+            const row = at(key);
+            if (!row || row.state !== 'active' || row.detail === text)
+                return;
+            row.detail = text;
+            if (live) {
+                paint(frame());
+                return;
+            }
+            // Without a redraw region every sub-step would be its own line, and a build
+            // emits hundreds. Keep a captured log alive without flooding it.
+            if (Date.now() - lastTranscriptDetail < 10_000)
+                return;
+            lastTranscriptDetail = Date.now();
+            transcript(`  ${c.dim(`${glyphs.branch} ${text}`)}`);
+        },
+        done(key, summary) {
+            const row = at(key);
+            if (!row)
+                return;
+            row.took = Date.now() - (row.startedAt ?? Date.now());
+            row.state = 'done';
+            row.summary = summary;
+            row.detail = undefined;
+            if (live)
+                paint(frame());
+            else
+                transcript(`${glyph.ok} ${row.label}${summary ? ` — ${summary}` : ''}${took(row)}`);
+        },
+        skip(key, why) {
+            const row = at(key);
+            if (!row)
+                return;
+            row.state = 'skip';
+            row.summary = why ?? 'skipped';
+            row.detail = undefined;
+            if (live)
+                paint(frame());
+            else
+                transcript(`${glyph.pending} ${c.dim(`${row.label} — ${row.summary}`)}`);
+        },
+        fail(key, why) {
+            const row = at(key);
+            if (!row)
+                return;
+            row.took = Date.now() - (row.startedAt ?? Date.now());
+            row.state = 'fail';
+            row.summary = why;
+            row.detail = undefined;
+            if (live)
+                paint(frame());
+            else
+                transcript(`${glyph.fail} ${row.label}${why ? ` — ${why}` : ''}${took(row)}`);
+        },
+        failActive(why) {
+            for (const row of rows)
+                if (row.state === 'active')
+                    api.fail(row.key, why);
+        },
+        note(line) {
+            if (!live) {
+                transcript(line);
+                return;
+            }
+            erase();
+            err.write(`${line}\n`);
+            paint(frame());
+        },
+        suspend() {
+            if (!live)
+                return;
+            clearInterval(timer);
+            erase();
+            err.write(cursor.show());
+            releaseRegion(owner);
+        },
+        resume() {
+            if (!live || closed || !claimRegion(owner))
+                return;
+            err.write(cursor.hide());
+            paint(frame());
+            start();
+        },
+        close() {
+            if (closed)
+                return;
+            closed = true;
+            clearInterval(timer);
+            setInterruptHandler(null);
+            releaseRegion(owner);
+            if (current === api)
+                current = null;
+            if (!live)
+                return;
+            erase();
+            // Reprint the settled steps as static lines so scrollback keeps the summary.
+            // The mesh does not survive: a frozen loading animation in scrollback says
+            // nothing that a settled step list does not say better.
+            const settled = rows
+                .filter((row) => row.state !== 'todo')
+                .map((row) => truncate(render(row, glyphs.stepActive), width()));
+            err.write((settled.length ? `${settled.join('\n')}\n` : '') + cursor.show());
+        },
+    };
+    if (live) {
+        current = api;
+        hookCursorRestore();
+        setInterruptHandler(() => {
+            erase();
+            if (opts.onCancel)
+                err.write(`${glyph.warn} ${opts.onCancel}\n`);
+        });
+        err.write(cursor.hide());
+        paint(frame());
+        start();
+    }
+    return api;
+}
+/**
+ * Run work under a ladder, closing it on either outcome. Whichever step was in
+ * flight when the work threw is marked failed, so the transcript shows where it
+ * stopped rather than only that it stopped.
+ */
+export async function withLadder(steps, run, opts = {}) {
+    const l = ladder(steps, opts);
+    try {
+        return await run(l);
+    }
+    catch (error) {
+        l.failActive(error instanceof Error ? error.message : undefined);
+        throw error;
+    }
+    finally {
+        l.close();
+    }
+}

package/dist/mark.js

@@ -6,14 +6,28 @@
  * The mark is a fixed character grid rather than a string per state, because
  * the loading animation lights individual spokes and needs to address cells.
  */
-import { c, colourDepth, rgb } from './render.js';
-const GRID = [
-    '  ○     ○     ○  ',
-    '   ╲    │    ╱   ',
-    '○───────◉───────○',
-    '   ╱    │    ╲   ',
-    '  ○     ○     ○  ',
-];
+import { c, colourDepth, rgb, unicode } from './render.js';
+/**
+ * Both grids are deliberately the same 17×5 shape. Every cell coordinate below,
+ * and the cursor arithmetic in the progress UI above, is written against those
+ * dimensions — an ASCII fallback of a different size would silently break the
+ * redraw rather than merely look plainer.
+ */
+const GRID = unicode
+    ? [
+        '  ○     ○     ○  ',
+        '   ╲    │    ╱   ',
+        '○───────◉───────○',
+        '   ╱    │    ╲   ',
+        '  ○     ○     ○  ',
+    ]
+    : [
+        '  o     o     o  ',
+        '   \\    |    /   ',
+        'o-------@-------o',
+        '   /    |    \\   ',
+        '  o     o     o  ',
+    ];
 export const MARK_WIDTH = 17;
 export const MARK_HEIGHT = GRID.length;
 /** Where the hub sits. Always lit — a fleet with no control plane is not a fleet. */
@@ -82,6 +96,8 @@ export function markFrame(phase) {
 /** The resting mark: hub live, peers quiet. */
 export const mark = () => markFrame(-1);
 const WORDMARK = ['█▀▀ █   █▀▀ █▀▀ ▀█▀', '█▀  █   █▀  █▀   █ ', '▀   ▀▀▀ ▀▀▀ ▀▀▀  ▀ '];
+/** The hub, read back out of the grid so the two glyph sets cannot drift. */
+const hubGlyph = GRID[HUB[0]][HUB[1]];
 /**
  * Mark and wordmark side by side, with the tagline tucked under the wordmark so
  * the block stays rectangular. Falls back to a single line when the terminal is
@@ -91,11 +107,15 @@ export function banner(subtitle) {
     // `columns` is 0, not undefined, on some pseudo-terminals — `??` would miss it.
     const columns = process.stdout.columns || 80;
     if (columns < 46)
-        return `${c.signal('◉')} ${c.bold('fleet')}${subtitle ? c.dim(`  ${subtitle}`) : ''}`;
+        return `${c.signal(hubGlyph)} ${c.bold('fleet')}${subtitle ? c.dim(`  ${subtitle}`) : ''}`;
     // The wordmark sits against the middle three rows of the mark; the tagline
     // takes the last. Every mark row is exactly MARK_WIDTH visible columns, so a
     // fixed gutter aligns them without measuring around the colour codes.
-    const right = ['', ...WORDMARK.map(c.bold), subtitle ? c.dim(subtitle) : ''];
+    // Without block glyphs the drawn wordmark is unreadable, so ASCII terminals
+    // get the name set once against the hub row instead of a row of mojibake.
+    const right = unicode
+        ? ['', ...WORDMARK.map(c.bold), subtitle ? c.dim(subtitle) : '']
+        : ['', '', c.bold('F L E E T'), subtitle ? c.dim(subtitle) : '', ''];
     return mark()
         .map((line, i) => `  ${line}${right[i] ? `    ${right[i]}` : ''}`.trimEnd())
         .join('\n');

package/dist/plan.js

@@ -0,0 +1,69 @@
+/**
+ * What to deploy, and in what order.
+ *
+ * `fleet up` used to deploy exactly one service, which meant a stack was four
+ * invocations typed in the right order — and getting the order wrong looked
+ * like a broken application rather than a sequencing mistake, because an API
+ * whose database is not up yet fails its health check like any other outage.
+ */
+import { parse as parseYaml } from 'yaml';
+/**
+ * Read the manifest the way the control plane will.
+ *
+ * Deliberately forgiving: the server validates, and this only needs enough
+ * structure to decide what to send and when. A manifest that is wrong will be
+ * rejected by apply with a proper message before any of this matters.
+ */
+export function planFromManifest(source) {
+    const doc = parseYaml(source);
+    const services = doc?.services;
+    if (!services || typeof services !== 'object')
+        return [];
+    return Object.entries(services).map(([name, raw]) => {
+        const body = (raw ?? {});
+        return {
+            name,
+            build: typeof body.build === 'string' ? body.build : undefined,
+            affinity: Array.isArray(body.affinity) ? body.affinity.filter((a) => typeof a === 'string') : [],
+        };
+    });
+}
+/**
+ * Order services so a dependency is deployed before whatever depends on it.
+ *
+ * `affinity` is the signal. It means "co-locate", not "depends on", but in
+ * practice the two coincide: a service is pinned next to the database it talks
+ * to, and it cannot become healthy until that database answers. Using it for
+ * ordering is a heuristic, and the cost of it being wrong is one slow retry
+ * rather than a failure — the agent's restart policy brings up a container that
+ * started too early anyway.
+ *
+ * Ties keep manifest order, so the file stays the explanation for what happens.
+ * A cycle is not an error here: the services involved are emitted in manifest
+ * order rather than dropped, because refusing to deploy is a worse answer than
+ * deploying in an imperfect order.
+ */
+export function deployOrder(services) {
+    const byName = new Map(services.map((s) => [s.name, s]));
+    const ordered = [];
+    const state = new Map();
+    const visit = (name) => {
+        if (state.get(name) === 'done')
+            return;
+        // Already on the stack: a cycle. Stop rather than recurse forever; the
+        // caller still gets every service, just not in a perfect order.
+        if (state.get(name) === 'visiting')
+            return;
+        const service = byName.get(name);
+        if (!service)
+            return; // affinity on something not in this manifest
+        state.set(name, 'visiting');
+        for (const dependency of service.affinity)
+            visit(dependency);
+        state.set(name, 'done');
+        ordered.push(name);
+    };
+    for (const service of services)
+        visit(service.name);
+    return ordered;
+}

package/dist/progress.js

@@ -0,0 +1,188 @@
+/**
+ * Following a deploy.
+ *
+ * `POST /services/:id/deploy` is a single request that can take minutes: it builds
+ * for every architecture in the fleet, pushes to the registry, allocates a port
+ * and hands the container to an agent. The control plane now walks the deployment
+ * row through those phases and publishes the build's own sub-step alongside it
+ * (control-plane/src/api/deploy-progress.ts), so the CLI can poll for them while
+ * it waits on the request it already has in flight, and show where the work has
+ * actually got to instead of guessing.
+ *
+ * Progress is decoration, never the result: a poll that fails is swallowed and the
+ * deploy carries on. Only `awaitRunning`, where a poll *is* the mechanism, treats
+ * a persistently unreachable control plane as an error.
+ */
+import { request, CliError, EXIT } from './api.js';
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** A failure reason can be a build log tail; a one-line error gets one line of it. */
+export const firstLine = (text) => text.split('\n')[0].trim().slice(0, 200);
+export async function fetchProgress(serviceId) {
+    const { body } = await request('GET', `/services/${serviceId}/progress`);
+    return body.progress;
+}
+/**
+ * The build's sub-step as one line. `linux/arm64` is shortened because the arch is
+ * the informative half and the redraw region is narrow.
+ */
+export function progressLine(p) {
+    if (!p.detail)
+        return undefined;
+    const counter = p.step && p.ofSteps ? `${p.step}/${p.ofSteps} ` : '';
+    const platform = p.platform ? `${p.platform.replace(/^linux\//, '')} ` : '';
+    return `${counter}${platform}${p.detail}`;
+}
+/**
+ * Poll `/progress` in the background while something else is being awaited.
+ *
+ * The shape is the device-flow race in auth.ts: the answer comes from one promise
+ * while a second keeps the display honest until it lands. `stop()` interrupts the
+ * sleep rather than waiting it out, so the last frame is not held back by a poll
+ * interval that is no longer needed.
+ */
+export function follow(serviceId, sink, opts = {}) {
+    const interval = opts.intervalMs ?? 800;
+    let stopped = false;
+    let misses = 0;
+    let wake = null;
+    const rest = (ms) => new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        wake = () => {
+            clearTimeout(timer);
+            resolve();
+        };
+    });
+    const loop = (async () => {
+        while (!stopped) {
+            await rest(interval);
+            if (stopped)
+                return;
+            try {
+                const progress = await fetchProgress(serviceId);
+                misses = 0;
+                if (progress)
+                    sink(progress);
+            }
+            catch {
+                // A control plane that predates the endpoint answers 404 every time, so
+                // give up rather than spend the whole build asking again.
+                if (++misses >= 3) {
+                    opts.onUnavailable?.();
+                    return;
+                }
+            }
+        }
+    })();
+    return {
+        stop: async () => {
+            stopped = true;
+            wake?.();
+            await loop.catch(() => { });
+        },
+    };
+}
+/** Ladder steps for a deploy, in the order the control plane reports them. */
+export const DEPLOY_STEPS = [
+    { key: 'place', label: 'choosing a node' },
+    { key: 'build', label: 'building the image' },
+    { key: 'push', label: 'pushing to the fleet registry' },
+    { key: 'schedule', label: 'scheduling onto the node' },
+    { key: 'health', label: 'waiting for the container' },
+];
+/** Which ladder step each server-reported phase corresponds to. */
+const STEP_OF = {
+    queued: 0,
+    building: 1,
+    pushing: 2,
+    scheduling: 3,
+    deploying: 4,
+    running: 5,
+};
+/**
+ * Drive a ladder from the server's phases.
+ *
+ * Forward only: a poll can arrive out of order, and re-beginning a step would
+ * restart its clock. Steps the deploy never entered are marked skipped rather than
+ * done — a service deployed from a prebuilt image goes straight from `queued` to
+ * `scheduling`, and settling build and push as complete would claim work that
+ * never happened.
+ */
+export function phaseWalker(l, steps = DEPLOY_STEPS) {
+    let at = 0;
+    l.begin(steps[0].key);
+    const advance = (target, summary) => {
+        if (target <= at)
+            return;
+        for (let i = at; i < target; i++) {
+            if (i === at)
+                l.done(steps[i].key, summary);
+            else
+                l.skip(steps[i].key, 'not needed');
+        }
+        at = target;
+        if (target < steps.length)
+            l.begin(steps[target].key);
+    };
+    return {
+        advance,
+        finish: (summary) => advance(steps.length, summary),
+        get at() {
+            return at;
+        },
+        apply(p) {
+            if (p.status === 'failed') {
+                l.failActive(p.failureReason ? firstLine(p.failureReason) : undefined);
+                return;
+            }
+            const target = STEP_OF[p.status];
+            if (target !== undefined) {
+                // Which node was chosen is the one summary worth carrying over from a
+                // poll, and it belongs on the step that decided it.
+                advance(target, at === 0 ? (p.nodeName ?? undefined) : undefined);
+            }
+            const line = progressLine(p);
+            if (line && at < steps.length)
+                l.detail(steps[at].key, line);
+        },
+    };
+}
+/**
+ * Follow a service to `running`.
+ *
+ * The deploy request returns once the image exists and a node has been chosen; the
+ * container actually starting is the agent's job and happens afterwards, so the
+ * CLI follows it to a conclusion rather than reporting "scheduled" and leaving the
+ * operator to guess. One indexed row per poll, not the whole service list.
+ */
+export async function awaitRunning(service, opts = {}) {
+    const deadline = Date.now() + (opts.timeoutMs ?? 180_000);
+    let misses = 0;
+    while (Date.now() < deadline) {
+        let progress = null;
+        try {
+            progress = await fetchProgress(service.id);
+            misses = 0;
+        }
+        catch (err) {
+            // Here a poll is the mechanism, not decoration. Reporting a timeout when
+            // the control plane simply stopped answering would blame the wrong thing.
+            if (++misses >= 5)
+                throw err;
+        }
+        if (progress?.status === 'running')
+            return;
+        if (progress?.status === 'failed') {
+            const why = progress.failureReason ? `: ${firstLine(progress.failureReason)}` : '';
+            throw new CliError(`"${service.name}" did not start${why}. \`fleet deployments ${service.name}\` has the detail.`, EXIT.healthCheckFailed);
+        }
+        if (progress?.status === 'pinned_unavailable') {
+            throw new CliError(`"${service.name}" is pinned to a node that is not available. ` +
+                `\`fleet where ${service.name}\` explains why.`, EXIT.noEligibleNode);
+        }
+        if (progress)
+            opts.onProgress?.(progress);
+        await sleep(2000);
+    }
+    throw new CliError(`"${service.name}" was scheduled but has not reported running. ` +
+        `\`fleet deployments ${service.name}\` has the detail.`, EXIT.healthCheckFailed);
+}