@thinremote/thinr-cli 1.1.0 → 1.2.0

package/commands/fleet/upgrade.js

@@ -0,0 +1,275 @@
+// @ts-check
+import { confirm } from '@inquirer/prompts';
+import { getDevices } from '../../lib/devices.js';
+import { getMonitoringData } from '../../lib/monitoring.js';
+import { fetchLatestAgentVersion } from '../../lib/agent-releases.js';
+import { runFleetUpgrade, summarize } from '../../lib/fleet-upgrade.js';
+import { classifyAgainst, normalizeAgentVersion } from '../../lib/agent-versions.js';
+import {
+    isJsonMode,
+    printOk,
+    printErr,
+    createSpinner,
+    classifyError,
+} from '../../lib/output.js';
+import {
+    success,
+    error as errorStyle,
+    warning,
+    hint,
+    label,
+    muted,
+    accent,
+} from '../../lib/format.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    getGlobalUser,
+    parsePositiveInt,
+} from '../_shared.js';
+
+export function registerUpgradeCommand(fleet) {
+    fleet
+        .command('upgrade')
+        .helpGroup('Fleet:')
+        .description('Apply an agent update across every outdated device in the fleet')
+        .option('-j, --json', 'Output as JSON')
+        .option('--channel <name>', 'Release channel to target', 'latest')
+        .option('-p, --product <id>', 'Restrict to devices belonging to this product')
+        .option('-g, --group <id>', 'Restrict to devices in this asset group')
+        .option(
+            '--batch-size <n>',
+            'Devices updated in parallel once the canary passes',
+            parsePositiveInt('batch-size'),
+            5,
+        )
+        .option('--no-canary', 'Skip the canary phase (upgrade everything in batches from the start)')
+        .option('--continue-on-error', 'Keep rolling after a batch failure instead of aborting')
+        .option('--dry-run', 'List what would be upgraded without sending any update request')
+        .option('-y, --yes', 'Skip the confirmation prompt (required in non-interactive shells)')
+        .action(async (opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            // ── 1. Target version ──────────────────────────────────────
+            const latestSpinner = createSpinner(
+                `Resolving ${opts.channel} release…`,
+            ).start();
+            let target;
+            try {
+                target = await fetchLatestAgentVersion({ channel: opts.channel });
+                latestSpinner.succeed(`Channel ${accent(opts.channel)} → ${success(target)}`);
+            } catch (err) {
+                latestSpinner.fail(`Failed to resolve channel ${opts.channel}`);
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+                return;
+            }
+
+            // ── 2. Fleet inventory ─────────────────────────────────────
+            const listSpinner = createSpinner('Listing fleet…').start();
+            let devices;
+            try {
+                const filter = {};
+                if (opts.product) filter.product = opts.product;
+                if (opts.group) filter.asset_group = opts.group;
+                devices = await getDevices(filter, user);
+                listSpinner.succeed(`Fleet size: ${label(devices.length)} device(s)`);
+            } catch (err) {
+                listSpinner.fail('Failed to list devices');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+                return;
+            }
+            if (devices.length === 0) {
+                if (isJsonMode()) {
+                    printOk({ target, outdated: [], results: [] });
+                } else {
+                    console.log(hint('No devices match the filter.'));
+                }
+                return;
+            }
+
+            // ── 3. Current versions ────────────────────────────────────
+            // Fleet-wide monitoring snapshot trimmed to `agent.version`.
+            // The backend may return several rows per device (history
+            // tail); with `sort=desc` the first row we see per device is
+            // the most recent one, so we ignore later repeats. We also
+            // scope to the filtered fleet so monitoring data from devices
+            // outside the product/group filter doesn't leak into the count.
+            const versionsSpinner = createSpinner('Reading agent versions…').start();
+            const fleetIds = new Set(devices.map((d) => d.device));
+            const deviceVersions = {};
+            for (const d of devices) deviceVersions[d.device] = null;
+            try {
+                const rows = await getMonitoringData({
+                    user,
+                    items: Math.max(500, devices.length),
+                    sort: 'desc',
+                    fields: 'agent.version',
+                });
+                if (Array.isArray(rows)) {
+                    for (const row of rows) {
+                        const id = row?.device;
+                        const v = row?.agent?.version;
+                        if (!id || !v || !fleetIds.has(id)) continue;
+                        if (deviceVersions[id]) continue;
+                        deviceVersions[id] = v;
+                    }
+                }
+                const known = Object.values(deviceVersions).filter(Boolean).length;
+                versionsSpinner.succeed(`Read versions for ${label(known)} of ${devices.length} device(s)`);
+            } catch (err) {
+                versionsSpinner.fail('Failed to read monitoring data');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+                return;
+            }
+
+            const { outdated, current, unknown } = classifyAgainst(target, deviceVersions);
+
+            // ── 4. Render summary ──────────────────────────────────────
+            const versionCounts = countVersions(deviceVersions);
+            if (!isJsonMode()) {
+                console.log();
+                console.log(label('Agent versions in fleet:'));
+                for (const [v, c] of versionCounts) {
+                    const tag = v === target ? success('●') : warning('●');
+                    console.log(`  ${tag} ${v.padEnd(12)} ${muted(String(c))}`);
+                }
+                if (unknown.length) {
+                    console.log(`  ${muted('?')} ${'unknown'.padEnd(12)} ${muted(String(unknown.length))}`);
+                }
+                console.log();
+                console.log(
+                    `Target: ${success(target)}  ·  ` +
+                        `outdated: ${label(outdated.length)}  ·  ` +
+                        `current: ${muted(current.length)}` +
+                        (unknown.length ? `  ·  unknown: ${muted(unknown.length)}` : ''),
+                );
+                console.log();
+            }
+
+            if (outdated.length === 0) {
+                if (isJsonMode()) {
+                    printOk({
+                        target,
+                        summary: { outdated: 0, current: current.length, unknown: unknown.length },
+                        results: [],
+                    });
+                } else {
+                    console.log(success('All devices are already on the target version.'));
+                }
+                return;
+            }
+
+            // ── 5. Dry-run ─────────────────────────────────────────────
+            if (opts.dryRun) {
+                if (isJsonMode()) {
+                    printOk({
+                        target,
+                        dryRun: true,
+                        outdated,
+                        current,
+                        unknown,
+                    });
+                    return;
+                }
+                console.log(label(`Would upgrade ${outdated.length} device(s):`));
+                for (const id of outdated) {
+                    console.log(`  - ${id} ${muted(`(${normalizeAgentVersion(deviceVersions[id]) || '?'})`)}`);
+                }
+                return;
+            }
+
+            // ── 6. Confirmation ────────────────────────────────────────
+            if (!opts.yes && !isJsonMode()) {
+                if (!process.stdin.isTTY) {
+                    printErr(
+                        'Refusing to upgrade without --yes in a non-interactive shell',
+                        { code: 'needs_confirm' },
+                    );
+                    return;
+                }
+                const plan = opts.canary ? 'canary first, then batches' : 'all in batches';
+                const failure = opts.continueOnError ? 'continue on failure' : 'abort on failure';
+                const ok = await confirm({
+                    message: `Upgrade ${outdated.length} device(s) to ${target}? (${plan} · ${failure})`,
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(hint('Cancelled.'));
+                    return;
+                }
+            }
+
+            // ── 7. Rollout ─────────────────────────────────────────────
+            const runSpinner = createSpinner('').start();
+            const setRunText = (done, total) => {
+                runSpinner.text = `Upgrading · ${done}/${total} device(s) processed`;
+            };
+            setRunText(0, outdated.length);
+
+            const perDevice = [];
+            const { results, aborted, reason } = await runFleetUpgrade({
+                deviceIds: outdated,
+                channel: opts.channel,
+                user,
+                canary: opts.canary,
+                abortOnFailure: !opts.continueOnError,
+                batchSize: opts.batchSize,
+                onProgress: ({ done, total }) => setRunText(done, total),
+                onDeviceResult: (r) => {
+                    perDevice.push(r);
+                },
+            });
+            runSpinner.stop();
+
+            // ── 8. Results ─────────────────────────────────────────────
+            const sum = summarize(results);
+            if (isJsonMode()) {
+                printOk({
+                    target,
+                    channel: opts.channel,
+                    aborted,
+                    reason: aborted ? reason : undefined,
+                    summary: sum,
+                    results,
+                });
+                return;
+            }
+
+            for (const r of results) {
+                if (r.ok) {
+                    console.log(`  ${success('✓')} ${r.deviceId}`);
+                } else {
+                    console.log(`  ${errorStyle('✗')} ${r.deviceId}  ${muted(r.error)}`);
+                }
+            }
+
+            console.log();
+            const verdict = aborted
+                ? `${warning('aborted')} (${reason}) · ${sum.ok} ok · ${sum.failed} failed`
+                : `${success('done')} · ${sum.ok} ok · ${sum.failed} failed`;
+            console.log(label(`Rollout ${verdict}`));
+
+            if (aborted || sum.failed > 0) {
+                // Scripts can use the exit code to gate follow-up work — a
+                // partial rollout is a "soft failure" worth surfacing.
+                process.exitCode = 1;
+            }
+        });
+}
+
+function countVersions(deviceVersions) {
+    const counts = new Map();
+    for (const raw of Object.values(deviceVersions)) {
+        const v = normalizeAgentVersion(raw);
+        if (!v) continue;
+        counts.set(v, (counts.get(v) || 0) + 1);
+    }
+    // Newest first by semver — reuse the comparator via dynamic import
+    // would be overkill here; the caller only needs a stable human order.
+    return [...counts.entries()].sort((a, b) => b[0].localeCompare(a[0], undefined, { numeric: true }));
+}

package/commands/logout.js

@@ -1,6 +1,6 @@
-import chalk from 'chalk';
 import ora from 'ora';
 import { deleteConfig, configExists } from '../lib/config.js';
+import { warning, error, hint } from '../lib/format.js';
 
 /**
  * Register the logout command
@@ -9,11 +9,12 @@ import { deleteConfig, configExists } from '../lib/config.js';
 export function logoutCommand(program) {
     program
         .command('logout')
+        .helpGroup('Configuration:')
         .description('Remove stored credentials and configuration')
         .action(async () => {
             // Check if configured
             if (!configExists()) {
-                console.log(chalk.yellow('No configuration found. Already logged out.'));
+                console.log(warning('No configuration found. Already logged out.'));
                 return;
             }
 
@@ -22,27 +23,25 @@ export function logoutCommand(program) {
             try {
                 // Delete local configuration
                 spinner.text = 'Removing local configuration...';
-                const success = deleteConfig();
+                const ok = deleteConfig();
 
-                if (success) {
+                if (ok) {
                     spinner.succeed('Logged out successfully. Configuration removed.');
                 } else {
                     spinner.fail('Failed to remove configuration.');
                     console.error(
-                        chalk.red(
+                        error(
                             'Error: Unable to delete configuration file. You may need to remove it manually.',
                         ),
                     );
                     console.error(
-                        chalk.gray('Configuration is stored in ~/.config/thinr-cli/config.json'),
+                        hint('Configuration is stored in ~/.config/thinr-cli/config.json'),
                     );
                 }
-            } catch (error) {
+            } catch (err) {
                 spinner.fail('Failed to remove configuration.');
-                console.error(chalk.red(`Error: ${error.message}`));
-                console.error(
-                    chalk.gray('Configuration is stored in ~/.config/thinr-cli/config.json'),
-                );
+                console.error(error(`Error: ${err.message}`));
+                console.error(hint('Configuration is stored in ~/.config/thinr-cli/config.json'));
             }
         });
 }

package/commands/playbook/_shared.js

@@ -0,0 +1,12 @@
+// @ts-check
+export {
+    ensureConfigured,
+    applyJsonFlag,
+    getGlobalUser,
+    parsePositiveInt,
+    collectKeyValue,
+    collectVar,
+    collectInput,
+    extractField,
+    ProgressSpinner,
+} from '../_shared.js';

package/commands/playbook/index.js

@@ -0,0 +1,18 @@
+// @ts-check
+import { registerRunCommand } from './run.js';
+import { registerValidateCommand } from './validate.js';
+
+/**
+ * `thinr playbook <subcommand>` — declarative, repeatable sequences of
+ * agent actions over a fleet. See `lib/playbook/schema.js` for the
+ * accepted format.
+ */
+export function playbookCommand(program) {
+    const playbook = program
+        .command('playbook')
+        .helpGroup('Operations:')
+        .description('Run declarative YAML playbooks against the fleet');
+
+    registerRunCommand(playbook);
+    registerValidateCommand(playbook);
+}

package/commands/playbook/run.js

@@ -0,0 +1,302 @@
+// @ts-check
+import { dirname, resolve } from 'path';
+import { loadPlaybookFile } from '../../lib/playbook/loader.js';
+import { buildDryRunPlan, resolveTargets, runPlaybook } from '../../lib/playbook/runner.js';
+import {
+    isJsonMode,
+    printOk,
+    printErr,
+    createSpinner,
+    classifyError,
+} from '../../lib/output.js';
+import { success, error as errorStyle, warning, hint, label, muted } from '../../lib/format.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    getGlobalUser,
+    parsePositiveInt,
+    collectVar,
+} from './_shared.js';
+
+export function registerRunCommand(playbook) {
+    playbook
+        .command('run <file>')
+        .helpGroup('Playbook:')
+        .description('Run a playbook against the product / devices declared in its target block')
+        .option('-j, --json', 'Output as JSON')
+        .option('--dry-run', 'Print the static plan without contacting devices')
+        .option('--check', 'Contact devices read-only and report what would change (no writes)')
+        .option('--target <product>', 'Override the target product declared in the file')
+        .option('--group <group>', 'Override the asset group filter')
+        .option(
+            '-c, --concurrency <n>',
+            'Override max parallel devices',
+            parsePositiveInt('concurrency'),
+        )
+        .option('--fail-fast', 'Stop dequeueing new devices on the first failure')
+        .option('--continue-on-error', 'Keep running subsequent steps on a device even if one fails')
+        .option('-v, --var <key=value>', 'Override a playbook variable (repeatable)', collectVar, {})
+        .action(async (file, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            let pb;
+            try {
+                pb = loadPlaybookFile(file);
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code: code === 'error' ? 'input_error' : code });
+                return;
+            }
+
+            // CLI overrides merge into the parsed document before we
+            // resolve targets, so overrides affect device selection too.
+            if (opts.target) pb.target.product = opts.target;
+            if (opts.group) pb.target.group = opts.group;
+            if (opts.concurrency) pb.target.concurrency = opts.concurrency;
+            if (opts.failFast) pb.target.fail_fast = true;
+            if (opts.var && Object.keys(opts.var).length) {
+                pb.vars = { ...pb.vars, ...opts.var };
+            }
+
+            // ── Dry-run path ──────────────────────────────────────────
+            if (opts.dryRun) {
+                const plan = buildDryRunPlan(pb);
+                if (isJsonMode()) {
+                    printOk({
+                        name: pb.name,
+                        target: pb.target,
+                        vars: pb.vars,
+                        steps: plan,
+                    });
+                    return;
+                }
+                if (pb.name) console.log(label(pb.name));
+                console.log(
+                    hint(
+                        `target: ${pb.target.product || '(explicit)'}` +
+                            (pb.target.group ? ` · group=${pb.target.group}` : '') +
+                            ` · concurrency=${pb.target.concurrency}` +
+                            (pb.target.fail_fast ? ' · fail-fast' : ''),
+                    ),
+                );
+                console.log(label(`\nPlan (${plan.length} step${plan.length === 1 ? '' : 's'}):`));
+                for (const s of plan) {
+                    const pause = s.pause_after ? muted(`  then pause ${s.pause_after}s`) : '';
+                    console.log(
+                        `  ${hint(String(s.index + 1).padStart(2) + '.')} ` +
+                            `${label(s.name)}  ${muted(`(${s.action})`)}${pause}`,
+                    );
+                }
+                return;
+            }
+
+            // ── Resolve targets ──────────────────────────────────────
+            const resolveSpinner = createSpinner('Resolving targets...').start();
+            let devices;
+            try {
+                devices = await resolveTargets(pb, { user });
+                resolveSpinner.succeed(`Running on ${devices.length} device(s)`);
+            } catch (err) {
+                resolveSpinner.fail('Failed to resolve targets');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+                return;
+            }
+
+            if (devices.length === 0) {
+                if (isJsonMode()) {
+                    printOk({ name: pb.name, devices: [], results: [] });
+                } else {
+                    console.log(warning('No devices to run on.'));
+                }
+                return;
+            }
+
+            // ── Execute ──────────────────────────────────────────────
+            const runSpinner = createSpinner('').start();
+            let done = 0;
+            const verb = opts.check ? 'Checking' : 'Executing';
+            const updateSpinner = () => {
+                runSpinner.text = `${verb} · ${done}/${devices.length} device(s) finished`;
+            };
+            updateSpinner();
+
+            const results = await runPlaybook(pb, devices, {
+                user,
+                concurrency: pb.target.concurrency,
+                failFast: pb.target.fail_fast,
+                baseDir: dirname(resolve(file)),
+                checkMode: !!opts.check,
+                continueOnError: !!opts.continueOnError,
+                onStepEnd: () => {
+                    // bump the spinner whenever any device finishes its
+                    // last step. Cheaper than a per-step counter when
+                    // devices are running in parallel.
+                },
+            });
+            // Count devices whose outcome is known (all settled).
+            done = results.length;
+            runSpinner.stop();
+
+            // ── Render ───────────────────────────────────────────────
+            const verdictTotals = aggregateVerdicts(results);
+
+            if (isJsonMode()) {
+                const okCount = results.filter((r) => r.ok).length;
+                printOk({
+                    name: pb.name,
+                    target: pb.target,
+                    mode: opts.check ? 'check' : 'apply',
+                    summary: {
+                        total: results.length,
+                        ok: okCount,
+                        failed: results.length - okCount,
+                        ...(opts.check ? { verdicts: verdictTotals } : {}),
+                    },
+                    results,
+                });
+                return;
+            }
+
+            const devicesWithFailures = [];
+            const deviceColWidth = Math.max(
+                ...results.map((r) => r.device.length),
+                12,
+            );
+            for (const r of results) {
+                const fails = r.steps.filter((s) => !s.ok && !s.skipped);
+                const statusTag = r.ok ? success('success') : errorStyle('failed ');
+                let durationMs = 0;
+                for (const s of r.steps) durationMs += s.durationMs || 0;
+                const duration = muted(`${durationMs}ms`.padStart(6));
+                const counts = opts.check
+                    ? perDeviceCheckCounts(r)
+                    : perDeviceApplyCounts(r);
+                let extra = '';
+                if (fails.length === 1) {
+                    extra = `  ${fails[0].name} · ${muted(fails[0].summary)}`;
+                } else if (fails.length > 1) {
+                    devicesWithFailures.push({ device: r.device, fails });
+                }
+                console.log(
+                    `  ${statusTag}  ${r.device.padEnd(deviceColWidth)}  ${duration}  ${counts}${extra}`,
+                );
+            }
+            const okCount = results.filter((r) => r.ok).length;
+            console.log(
+                hint(
+                    `${results.length} total · ${okCount} ok · ${results.length - okCount} failed`,
+                ),
+            );
+            // Always surface per-step failure detail when any device had
+            // multiple failures (continue-on-error path) or we want to
+            // group by step for a quick "which steps broke, on which
+            // devices" view.
+            if (devicesWithFailures.length) {
+                const failedStepIndices = new Set();
+                for (const r of results) {
+                    for (const s of r.steps) {
+                        if (!s.ok && !s.skipped) failedStepIndices.add(s.index);
+                    }
+                }
+                const sortedIndices = [...failedStepIndices].sort((a, b) => a - b);
+                console.log(label('\nFailed steps:'));
+                for (const idx of sortedIndices) {
+                    const header = `${String(idx + 1).padStart(2)}. ${pb.steps[idx].name}`;
+                    console.log(`  ${label(header)}`);
+                    for (const r of results) {
+                        const s = r.steps.find((x) => x.index === idx);
+                        if (!s || s.ok || s.skipped) continue;
+                        console.log(
+                            `    ${errorStyle('!')} ${r.device.padEnd(20)} ${muted(s.summary)}`,
+                        );
+                    }
+                }
+            }
+            if (opts.check) {
+                console.log(label('\nCheck details:'));
+                const stepCount = pb.steps.length;
+                for (let idx = 0; idx < stepCount; idx++) {
+                    const header = `${String(idx + 1).padStart(2)}. ${pb.steps[idx].name}`;
+                    console.log(`  ${label(header)}`);
+                    for (const r of results) {
+                        const s = r.steps.find((x) => x.index === idx);
+                        if (!s) continue;
+                        const tag = verdictTag(s);
+                        console.log(
+                            `    ${tag} ${r.device.padEnd(20)} ${muted(s.summary)}`,
+                        );
+                    }
+                }
+                console.log(
+                    hint(
+                        `\nSummary: +${verdictTotals.changed}  ` +
+                            `=${verdictTotals.unchanged}  ` +
+                            `?${verdictTotals.unknown}`,
+                    ),
+                );
+            }
+        });
+}
+
+function perDeviceCheckCounts(r) {
+    const counts = { changed: 0, unchanged: 0, unknown: 0, failed: 0, skipped: 0 };
+    for (const s of r.steps) {
+        if (!s.ok) counts.failed += 1;
+        else if (s.skipped) counts.skipped += 1;
+        else if (s.verdict && s.verdict in counts) counts[s.verdict] += 1;
+    }
+    const parts = [
+        `${warning('+' + counts.changed)}`,
+        `${muted('=' + counts.unchanged)}`,
+        `${hint('?' + counts.unknown)}`,
+    ];
+    if (counts.failed) parts.push(errorStyle(`!${counts.failed}`));
+    if (counts.skipped) parts.push(muted(`·${counts.skipped}`));
+    return parts.join('  ');
+}
+
+function perDeviceApplyCounts(r) {
+    let changed = 0;
+    let unchanged = 0;
+    let failed = 0;
+    let skipped = 0;
+    for (const s of r.steps) {
+        if (!s.ok) failed += 1;
+        else if (s.skipped) skipped += 1;
+        else if (s.verdict === 'unchanged') unchanged += 1;
+        else changed += 1;
+    }
+    const parts = [warning(`+${changed}`), muted(`=${unchanged}`)];
+    if (failed) parts.push(errorStyle(`!${failed}`));
+    if (skipped) parts.push(muted(`·${skipped}`));
+    return parts.join('  ');
+}
+
+function aggregateVerdicts(results) {
+    const totals = { changed: 0, unchanged: 0, unknown: 0 };
+    for (const r of results) {
+        for (const s of r.steps) {
+            if (!s.verdict) continue;
+            if (s.verdict in totals) totals[s.verdict] += 1;
+        }
+    }
+    return totals;
+}
+
+function verdictTag(step) {
+    if (!step.ok) return errorStyle('!');
+    if (step.skipped) return muted('·');
+    switch (step.verdict) {
+        case 'changed':
+            return warning('+');
+        case 'unchanged':
+            return muted('=');
+        case 'unknown':
+            return hint('?');
+        default:
+            return muted('·');
+    }
+}