@thinremote/thinr-cli 1.1.0 → 1.2.0

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`,
+                    ),
+            );
+        });
+}

package/commands/product/fs.js

@@ -0,0 +1,218 @@
+// @ts-check
+import Table from 'cli-table3';
+import { createDeviceAPI } from '../../lib/device-api.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';
+
+/**
+ * Factory for product-level fan-out filesystem subcommands.
+ * Captures the repetitive boilerplate (fetch product devices,
+ * optionally filter offline, fan out through the shared orchestrator,
+ * render the same cli-table3 summary) so each verb only has to
+ * describe its per-device operation.
+ */
+function registerProductFsCommand(product, { name, description, args, build, perDeviceLabel }) {
+    const cmd = product
+        .command(`${name} ${args}`)
+        .helpGroup('Filesystem:')
+        .description(description)
+        .option('-j, --json', 'Output as JSON')
+        .option('-g, --group <group>', 'Filter devices by asset group')
+        .option(
+            '-c, --concurrency <n>',
+            'Max parallel operations (default: 10)',
+            parsePositiveInt('concurrency'),
+            10,
+        )
+        .option('--fail-fast', 'Stop dequeueing new devices on the first failure')
+        .option('-a, --all', 'Include offline devices (by default, only active)');
+
+    cmd.action(async (...commandArgs) => {
+        const opts = commandArgs[commandArgs.length - 2];
+        const commanderCmd = commandArgs[commandArgs.length - 1];
+        const positionalArgs = commandArgs.slice(0, -2);
+        const [productId, ...rest] = positionalArgs;
+
+        applyJsonFlag(opts);
+        ensureConfigured();
+        const user = getGlobalUser(commanderCmd);
+
+        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();
+                    try {
+                        await build(api, rest, opts);
+                        return {
+                            device: device.device,
+                            ok: true,
+                            durationMs: Date.now() - perStart,
+                        };
+                    } catch (err) {
+                        return {
+                            device: device.device,
+                            ok: false,
+                            error: err instanceof Error ? err.message : String(err),
+                            durationMs: Date.now() - perStart,
+                        };
+                    }
+                },
+                skipped: (device, firstFailure) => ({
+                    device: device.device,
+                    ok: false,
+                    error: `skipped (fail-fast after ${firstFailure})`,
+                    durationMs: 0,
+                }),
+                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 }) =>
+                                `${perDeviceLabel(rest)} 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,
+                    summary: { total: 0, ok: 0, failed: 0 },
+                    results: [],
+                });
+            } else {
+                console.log(warning('No devices to target.'));
+            }
+            return;
+        }
+
+        const okCount = entries.filter((e) => e.ok).length;
+        const failCount = entries.length - okCount;
+
+        if (isJsonMode()) {
+            printOk({
+                product: productId,
+                summary: {
+                    total: entries.length,
+                    ok: okCount,
+                    failed: failCount,
+                    durationMs,
+                },
+                results: entries,
+            });
+            return;
+        }
+
+        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,
+                e.ok ? success('ok') : errorStyle('fail'),
+                e.ok ? muted('—') : e.error || '',
+                `${e.durationMs}ms`,
+            ]);
+        }
+        console.log(table.toString());
+        console.log(
+            hint(`${entries.length} total · ${okCount} ok · ${failCount} failed · ${durationMs}ms`),
+        );
+    });
+
+    return cmd;
+}
+
+export function registerProductFsCommands(product) {
+    registerProductFsCommand(product, {
+        name: 'mkdir',
+        description: 'Create a directory on every active device of the product',
+        args: '<productId> <path>',
+        perDeviceLabel: ([path]) => `mkdir ${path}`,
+        build: async (api, [path]) => {
+            await api.mkdir(path);
+        },
+    });
+
+    registerProductFsCommand(product, {
+        name: 'rm',
+        description:
+            'Delete a file or directory on every active device of the product (DESTRUCTIVE — double-check the path).',
+        args: '<productId> <path>',
+        perDeviceLabel: ([path]) => `rm ${path}`,
+        build: async (api, [path], opts) => {
+            await api.delete(path, opts.recursive !== false);
+        },
+    }).option(
+        '-r, --recursive',
+        'Recursively delete non-empty directories (default: true)',
+        true,
+    ).option('--no-recursive', 'Fail on non-empty directories');
+
+    registerProductFsCommand(product, {
+        name: 'mv',
+        description: 'Move or rename a path on every active device of the product',
+        args: '<productId> <source> <destination>',
+        perDeviceLabel: ([src, dst]) => `mv ${src} → ${dst}`,
+        build: async (api, [src, dst], opts) => {
+            await api.move(src, dst, !!opts.force);
+        },
+    }).option('-f, --force', 'Overwrite destination if it already exists');
+}

package/commands/product/index.js

@@ -0,0 +1,35 @@
+// @ts-check
+import { registerProductListCommand } from './list.js';
+import { registerProductPropertyCommand } from './property.js';
+import { registerProductPropertyAdminCommands } from './props.js';
+import { registerProductMetricCommands } from './metric.js';
+import { registerProductResourceCommand } from './resource.js';
+import { registerProductExecCommand } from './exec.js';
+import { registerProductStatusCommand } from './status.js';
+import { registerProductFsCommands } from './fs.js';
+import { registerProductPushCommand } from './push.js';
+import { registerProductPlaybookCommand } from './playbook.js';
+import { registerProductLogsCommand } from './logs.js';
+
+/**
+ * `thinr product <subcommand> <productId> …` — fan-out commands across
+ * every device that belongs to a product.
+ */
+export function productCommand(program) {
+    const product = program
+        .command('product')
+        .helpGroup('Operations:')
+        .description('Product commands (subcommand-first: thinr product <action> <productId>)');
+
+    registerProductListCommand(product);
+    registerProductStatusCommand(product);
+    registerProductPropertyCommand(product);
+    registerProductPropertyAdminCommands(product);
+    registerProductMetricCommands(product);
+    registerProductResourceCommand(product);
+    registerProductExecCommand(product);
+    registerProductFsCommands(product);
+    registerProductPushCommand(product);
+    registerProductPlaybookCommand(product);
+    registerProductLogsCommand(product);
+}

package/commands/product/list.js

@@ -0,0 +1,86 @@
+// @ts-check
+import { getProducts, getProductApi } from '../../lib/product.js';
+import { runPool } from '../../lib/concurrency.js';
+import { label, hint, success } from '../../lib/format.js';
+import {
+    isJsonMode,
+    printOk,
+    printErr,
+    createSpinner,
+    classifyError,
+} from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    getGlobalUser,
+    parsePositiveInt,
+} from '../_shared.js';
+
+export function registerProductListCommand(product) {
+    product
+        .command('list')
+        .helpGroup('Discovery:')
+        .description('List every product configured on the server')
+        .option('-j, --json', 'Output as JSON')
+        .option(
+            '-c, --concurrency <n>',
+            'Max parallel api-resource lookups (default: 10)',
+            parsePositiveInt('concurrency'),
+            10,
+        )
+        .action(async (opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            const spinner = createSpinner('Fetching products...').start();
+            let products;
+            try {
+                products = await getProducts(user);
+            } catch (error) {
+                spinner.fail('Failed to fetch products');
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+                return;
+            }
+
+            // Script counts come from each product's api resources map.
+            // Parallelise so a large catalogue doesn't crawl serially.
+            const scriptResults = await runPool(products, opts.concurrency, async (p) => {
+                try {
+                    const apis = await getProductApi(p.product, user);
+                    return Object.keys(apis || {}).length;
+                } catch {
+                    return null;
+                }
+            });
+            const rows = products.map((p, i) => ({
+                product: p.product,
+                name: p.name && p.name !== p.product ? p.name : null,
+                enabled: !!p.enabled,
+                scripts: scriptResults[i]?.ok ? scriptResults[i].value : null,
+            }));
+
+            spinner.succeed(`Found ${rows.length} product(s)`);
+
+            if (isJsonMode()) {
+                printOk({ products: rows });
+                return;
+            }
+
+            if (rows.length === 0) return;
+
+            // Pad the product id column so the trailing name/scripts
+            // bits align even when ids have very different widths.
+            const idWidth = rows.reduce((w, r) => Math.max(w, r.product.length), 0);
+            for (const r of rows) {
+                const flag = r.enabled ? success('enabled ') : hint('disabled');
+                const id = label(r.product.padEnd(idWidth));
+                const name = r.name ? hint(`(${r.name})`) : '';
+                const scripts =
+                    r.scripts != null && r.scripts > 0 ? hint(`${r.scripts} script(s)`) : '';
+                const extras = [name, scripts].filter(Boolean).join('  ');
+                console.log(`  ${flag}  ${id}${extras ? '  ' + extras : ''}`);
+            }
+        });
+}