@thinremote/thinr-cli 1.2.0-alpha.1 → 1.3.0

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('·');
+    }
+}

package/commands/playbook/validate.js

@@ -0,0 +1,38 @@
+// @ts-check
+import { loadPlaybookFile } from '../../lib/playbook/loader.js';
+import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { success, label, hint } from '../../lib/format.js';
+import { applyJsonFlag } from './_shared.js';
+
+export function registerValidateCommand(playbook) {
+    playbook
+        .command('validate <file>')
+        .helpGroup('Playbook:')
+        .description('Parse and validate a playbook without running it')
+        .option('-j, --json', 'Output as JSON')
+        .action((file, opts) => {
+            applyJsonFlag(opts);
+            try {
+                const pb = loadPlaybookFile(file);
+                if (isJsonMode()) {
+                    printOk({
+                        valid: true,
+                        name: pb.name,
+                        target: pb.target,
+                        steps: pb.steps.map((s) => ({
+                            name: s.name,
+                            action: s.action,
+                        })),
+                    });
+                    return;
+                }
+                console.log(success('✔ Playbook is valid'));
+                if (pb.name) console.log(label(pb.name));
+                if (pb.description) console.log(hint(pb.description));
+                console.log(hint(`${pb.steps.length} step(s)`));
+            } catch (error) {
+                const { message, code } = classifyError(error);
+                printErr(message, { code: code === 'error' ? 'input_error' : code });
+            }
+        });
+}

package/commands/product/_shared.js

@@ -0,0 +1,8 @@
+// @ts-check
+import { getDevices } from '../../lib/devices.js';
+
+export async function fetchProductDevices(productId, group, user) {
+    const filter = { product: productId };
+    if (group) filter.asset_group = group;
+    return getDevices(filter, user);
+}

package/commands/product/exec.js

@@ -0,0 +1,243 @@
+// @ts-check
+import Table from 'cli-table3';
+import { createDeviceAPI } from '../../lib/device-api.js';
+import { TIMEOUTS } from '../../lib/constants.js';
+import { runProductFanOut } from '../../lib/product-orchestrator.js';
+import {
+    label,
+    muted,
+    hint,
+    success,
+    error as errorStyle,
+    warning,
+} from '../../lib/format.js';
+import {
+    isJsonMode,
+    printOk,
+    printErr,
+    createSpinner,
+    classifyError,
+} from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    getGlobalUser,
+    parsePositiveInt,
+    ProgressSpinner,
+} from '../_shared.js';
+
+export function registerProductExecCommand(product) {
+    product
+        .command('exec <productId> <command...>')
+        .helpGroup('Fan-out:')
+        .description(
+            'Execute a shell command in parallel on every active device of the product',
+        )
+        .option('-j, --json', 'Output as JSON')
+        .option('-g, --group <group>', 'Filter devices by asset group')
+        .option(
+            '-c, --concurrency <n>',
+            'Max parallel executions (default: 10)',
+            parsePositiveInt('concurrency'),
+            10,
+        )
+        .option(
+            '--timeout <seconds>',
+            `Per-device timeout in seconds (default: ${TIMEOUTS.DEFAULT_EXEC_SECONDS})`,
+            parsePositiveInt('timeout'),
+            TIMEOUTS.DEFAULT_EXEC_SECONDS,
+        )
+        .option('--fail-fast', 'Stop dequeueing new devices as soon as one fails')
+        .option('-a, --all', 'Include offline devices (by default, only active)')
+        .action(async (productId, commandParts, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const commandStr = commandParts.join(' ');
+
+            const fetchSpinner = createSpinner(
+                `Retrieving devices for product ${productId}...`,
+            ).start();
+            /** @type {ProgressSpinner | null} */
+            let progress = null;
+
+            let result;
+            try {
+                result = await runProductFanOut({
+                    product: productId,
+                    group: opts.group,
+                    includeOffline: !!opts.all,
+                    user,
+                    concurrency: opts.concurrency,
+                    failFast: !!opts.failFast,
+                    worker: async (device) => {
+                        const api = createDeviceAPI(device.device, { user });
+                        const perStart = Date.now();
+                        let stdout = '';
+                        let stderr = '';
+                        try {
+                            const { exitCode, timedOut } = await api.execStream(commandStr, {
+                                timeout: opts.timeout,
+                                onStdout: (s) => {
+                                    stdout += s;
+                                },
+                                onStderr: (s) => {
+                                    stderr += s;
+                                },
+                            });
+                            return {
+                                device: device.device,
+                                ok: !timedOut && exitCode === 0,
+                                exitCode: exitCode ?? null,
+                                timedOut: !!timedOut,
+                                durationMs: Date.now() - perStart,
+                                stdout,
+                                stderr,
+                            };
+                        } catch (err) {
+                            const msg = err instanceof Error ? err.message : String(err);
+                            return {
+                                device: device.device,
+                                ok: false,
+                                exitCode: null,
+                                timedOut: false,
+                                durationMs: Date.now() - perStart,
+                                stdout,
+                                stderr,
+                                error: msg,
+                            };
+                        }
+                    },
+                    skipped: (device, firstFailure) => ({
+                        device: device.device,
+                        ok: false,
+                        exitCode: null,
+                        timedOut: false,
+                        durationMs: 0,
+                        stdout: '',
+                        stderr: '',
+                        error: `skipped (fail-fast after ${firstFailure})`,
+                    }),
+                    isFailure: (entry) => !entry.ok,
+                    onDevicesResolved: (devices) => {
+                        fetchSpinner.succeed(
+                            `Found ${devices.length} device(s) in product ${productId}`,
+                        );
+                        if (devices.length > 0 && !isJsonMode()) {
+                            progress = new ProgressSpinner(
+                                createSpinner('').start(),
+                                devices.length,
+                                ({ done, total, inFlight }) =>
+                                    `Running \`${commandStr}\` on ${total} device(s) — ` +
+                                    `${done}/${total} done · ${inFlight} in flight` +
+                                    (opts.failFast ? ' · fail-fast' : ''),
+                            );
+                            progress.render();
+                        }
+                    },
+                    onItemStart: () => progress?.startItem(),
+                    onItemFinish: () => progress?.finishItem(),
+                });
+            } catch (error) {
+                fetchSpinner.fail(`Failed to retrieve devices for product ${productId}`);
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+                return;
+            }
+            progress?.stop();
+
+            const { devices, entries, durationMs } = result;
+
+            if (devices.length === 0) {
+                if (isJsonMode()) {
+                    printOk({
+                        product: productId,
+                        command: commandStr,
+                        summary: { total: 0, ok: 0, failed: 0, durationMs: 0 },
+                        results: [],
+                    });
+                } else {
+                    console.log(warning('No devices to run on.'));
+                }
+                return;
+            }
+
+            const okCount = entries.filter((e) => e.ok).length;
+            const timedOutCount = entries.filter((e) => e.timedOut).length;
+            const errorCount = entries.filter((e) => e.error).length;
+            const failCount = entries.length - okCount - timedOutCount - errorCount;
+
+            if (isJsonMode()) {
+                printOk({
+                    product: productId,
+                    command: commandStr,
+                    summary: {
+                        total: entries.length,
+                        ok: okCount,
+                        failed: failCount + timedOutCount + errorCount,
+                        timedOut: timedOutCount,
+                        errored: errorCount,
+                        durationMs,
+                    },
+                    results: entries,
+                });
+                return;
+            }
+
+            const statusBadge = (e) => {
+                if (e.error) return errorStyle('error');
+                if (e.timedOut) return warning('timeout');
+                if (e.ok) return success('ok');
+                return errorStyle('fail');
+            };
+            const detail = (e) => {
+                if (e.error) return e.error;
+                if (e.timedOut) return `after ${opts.timeout}s`;
+                return `exit=${e.exitCode ?? 'null'}`;
+            };
+            const table = new Table({
+                head: ['Device', 'Status', 'Detail', 'Duration'].map((h) => label(h)),
+                style: { head: [], border: ['gray'] },
+                colAligns: ['left', 'left', 'left', 'right'],
+            });
+            for (const e of entries) {
+                table.push([
+                    e.device,
+                    statusBadge(e),
+                    detail(e),
+                    `${e.durationMs}ms`,
+                ]);
+            }
+            console.log(table.toString());
+
+            // Output section: only devices that produced stdout/stderr.
+            // Single-line outputs render inline; multi-line ones indent
+            // on their own block so grepping and copying still work.
+            const withOutput = entries.filter(
+                (e) => (e.stdout && e.stdout.trim()) || (e.stderr && e.stderr.trim()),
+            );
+            if (withOutput.length) {
+                console.log(label('\nOutput:'));
+                for (const e of withOutput) {
+                    const body = [e.stdout, e.stderr]
+                        .map((s) => (s ? s.replace(/\s+$/, '') : ''))
+                        .filter(Boolean)
+                        .join('\n');
+                    const lines = body.split('\n');
+                    if (lines.length === 1) {
+                        console.log(`  ${muted(e.device + ':')}  ${lines[0]}`);
+                    } else {
+                        console.log(`  ${muted(e.device + ':')}`);
+                        for (const line of lines) console.log(`    ${line}`);
+                    }
+                }
+            }
+
+            console.log(
+                '\n' +
+                    hint(
+                        `${entries.length} total — ${okCount} ok, ${failCount} fail, ${timedOutCount} timeout, ${errorCount} error · ${durationMs}ms`,
+                    ),
+            );
+        });
+}