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

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Changelog
 
+## [1.2.0] - 2026-04-16
+
+### Added
+
+- `thinr product exec <productId> <command...>` — run a shell command
+  in parallel on every active device of a product, with bounded
+  concurrency (`-c, --concurrency`, default 10), per-device timeout
+  (`--timeout`, default 30 s), `--fail-fast`, asset-group filter
+  (`-g, --group`) and an `-a, --all` switch to include offline
+  devices. Live progress shows a single spinner with done/total
+  counters; the final render uses a `cli-table3` table per device
+  plus a compact `Output:` section and a one-line totals bar.
+- `thinr_product_exec` MCP tool — the same fan-out as the CLI
+  subcommand, returning a consolidated text report so an AI agent
+  can roll out a change across a whole fleet in a single call
+  instead of looping `thinr_exec` per device.
+- `lib/concurrency.js#runPool` — tiny helper used by both entry
+  points; keeps at most N workers in flight and returns a parallel
+  results array. `runPool` plus an internal try/catch in each worker
+  keeps fleet-wide errors localised per device.
+
+### Changed
+
+- `cli-table3` added as a direct dependency to render the
+  product-exec summary.
+
 ## [1.1.0] - 2026-04-16
 
 Major release: MCP server for AI clients, subcommand-first CLI, JSON
@@ -128,6 +154,7 @@ consistent error taxonomy across both interfaces.
 - Property listing and retrieval
 - Device resource listing and execution
 
+[1.2.0]: https://github.com/Thin-Remote/thinr-cli/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.2...1.1.0
 [1.0.2]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.1...1.0.2
 [1.0.1]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.0...1.0.1

package/README.md

@@ -299,6 +299,44 @@ Options:
 Offline devices are skipped for `resource` — the server would reject
 the call anyway.
 
+#### `exec`
+
+Run a shell command in parallel across every active device of the
+product and report a per-device status table plus each device's
+output:
+
+```bash
+thinr product exec <productId> <command...> [options]
+```
+
+Options:
+
+- `-j, --json`: Output as JSON. Emits a single envelope with a
+  `summary` block and a `results[]` array carrying stdout, stderr,
+  exit code, `timedOut` flag and per-device duration.
+- `-c, --concurrency <n>`: Max parallel executions (default: 10)
+- `--timeout <seconds>`: Per-device timeout (default: 30)
+- `--fail-fast`: Stop dequeueing new devices as soon as one fails
+- `-g, --group <group>`: Filter devices by asset group
+- `-a, --all`: Include offline devices (default: only active)
+
+Examples:
+
+```bash
+# hostname on every active device
+thinr product exec my-product hostname
+
+# apt upgrade across the fleet with 5 parallel slots and a long timeout
+thinr product exec my-product "apt-get -y upgrade" -c 5 --timeout 600
+
+# target only a subset of the product
+thinr product exec my-product "systemctl restart agent" -g staging
+```
+
+Also exposed as an MCP tool (`thinr_product_exec`) with the same
+parameters, so agents can drive a fleet operation with a single call
+instead of looping `thinr_exec` per device.
+
 ### `thinr profile`
 
 Manage the profile store (see [Profiles and multi-account

package/commands/product.js

@@ -1,9 +1,12 @@
 import chalk from 'chalk';
+import Table from 'cli-table3';
 import { InvalidArgumentError } from 'commander';
 import { configExists } from '../lib/config.js';
 import { formatDeviceProperty, getDeviceProperty } from '../lib/property.js';
 import { callDeviceResource } from '../lib/resource.js';
 import { filterActiveDevices, getDevices } from '../lib/devices.js';
+import { createDeviceAPI } from '../lib/device-api.js';
+import { runPool } from '../lib/concurrency.js';
 import {
     setJsonMode,
     isJsonMode,
@@ -37,6 +40,16 @@ function collectInput(value, previous = {}) {
     return { ...previous, [value.slice(0, idx)]: value.slice(idx + 1) };
 }
 
+function parsePositiveInt(label) {
+    return (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`${label} must be a positive integer`);
+        }
+        return n;
+    };
+}
+
 async function fetchProductDevices(productId, group, user) {
     const filter = { productId };
     if (group) filter.asset_group = group;
@@ -164,4 +177,231 @@ export function productCommand(program) {
             }
             if (isJsonMode()) printOk({ product: productId, resource, results });
         });
+
+    product
+        .command('exec <productId> <command...>')
+        .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: 30)',
+            parsePositiveInt('timeout'),
+            30,
+        )
+        .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 spinner = createSpinner(`Retrieving devices for product ${productId}...`).start();
+            let devices;
+            try {
+                devices = await fetchProductDevices(productId, opts.group, user);
+                spinner.succeed(`Found ${devices.length} device(s) in product ${productId}`);
+            } catch (error) {
+                spinner.fail(`Failed to retrieve devices for product ${productId}`);
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+                return;
+            }
+            if (!opts.all) devices = filterActiveDevices(devices);
+
+            if (devices.length === 0) {
+                if (isJsonMode()) {
+                    printOk({
+                        product: productId,
+                        command: commandStr,
+                        summary: { total: 0, ok: 0, failed: 0, durationMs: 0 },
+                        results: [],
+                    });
+                } else {
+                    console.log(chalk.yellow('No devices to run on.'));
+                }
+                return;
+            }
+
+            // Live progress (human mode only): a single spinner that
+            // updates with done/in-flight counters as workers finish.
+            // Spinner is silenced in JSON mode by createSpinner itself.
+            const runSpinner = createSpinner('').start();
+            let doneCount = 0;
+            let inFlight = 0;
+            const updateSpinnerText = () => {
+                runSpinner.text =
+                    `Running \`${commandStr}\` on ${devices.length} device(s) — ` +
+                    `${doneCount}/${devices.length} done · ${inFlight} in flight` +
+                    (opts.failFast ? ' · fail-fast' : '');
+            };
+            updateSpinnerText();
+
+            const startTs = Date.now();
+            const poolResults = await runPool(
+                devices,
+                opts.concurrency,
+                async (device) => {
+                    inFlight++;
+                    updateSpinnerText();
+                    const api = createDeviceAPI(device.device, { user });
+                    const perDeviceStart = Date.now();
+                    let stdout = '';
+                    let stderr = '';
+                    const { exitCode, timedOut } = await api.execStream(commandStr, {
+                        timeout: opts.timeout,
+                        onStdout: (s) => {
+                            stdout += s;
+                        },
+                        onStderr: (s) => {
+                            stderr += s;
+                        },
+                    });
+                    const durationMs = Date.now() - perDeviceStart;
+                    const entry = {
+                        device: device.device,
+                        ok: !timedOut && exitCode === 0,
+                        exitCode: exitCode ?? null,
+                        timedOut: !!timedOut,
+                        durationMs,
+                        stdout,
+                        stderr,
+                    };
+                    inFlight--;
+                    doneCount++;
+                    updateSpinnerText();
+                    return entry;
+                },
+                { failFast: !!opts.failFast },
+            ).catch((err) => {
+                // fail-fast re-throws the first error; the partial results
+                // are still in `results` as it was populated before the throw.
+                // We fall through below and normalize with what we have.
+                return err;
+            });
+
+            // poolResults is either the array (success path) or the rethrown
+            // error from fail-fast. When it's an error, the pool still filled
+            // `results[i]` for what finished; but we lost that handle. Easy
+            // workaround: when fail-fast throws, re-run with failFast=false on
+            // nothing — or simpler, just catch inside runPool and not throw.
+            // For now, if it's an Error instance, surface it as a top-level
+            // failure and abort.
+            // Stop the live spinner now that the pool has settled, regardless
+            // of outcome. The final summary below replaces it.
+            runSpinner.stop();
+
+            if (poolResults instanceof Error) {
+                const { message, code } = classifyError(poolResults);
+                if (isJsonMode()) {
+                    printErr(message, { code });
+                } else {
+                    console.error(chalk.red(`fail-fast: ${message}`));
+                }
+                return;
+            }
+
+            const entries = poolResults.map((r, i) => {
+                if (r?.ok) return r.value;
+                const { message, code } = classifyError(r?.error);
+                return {
+                    device: devices[i].device,
+                    ok: false,
+                    exitCode: null,
+                    timedOut: false,
+                    durationMs: 0,
+                    stdout: '',
+                    stderr: '',
+                    error: { message, code },
+                };
+            });
+
+            const totalDurationMs = Date.now() - startTs;
+            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: totalDurationMs,
+                    },
+                    results: entries,
+                });
+                return;
+            }
+
+            const statusBadge = (e) => {
+                if (e.error) return chalk.red('error');
+                if (e.timedOut) return chalk.yellow('timeout');
+                if (e.ok) return chalk.green('ok');
+                return chalk.red('fail');
+            };
+            const detail = (e) => {
+                if (e.error) return e.error.message;
+                if (e.timedOut) return `after ${opts.timeout}s`;
+                return `exit=${e.exitCode ?? 'null'}`;
+            };
+            const table = new Table({
+                head: ['Device', 'Status', 'Detail', 'Duration'].map((h) => chalk.bold(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(chalk.bold('\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(`  ${chalk.dim(e.device + ':')}  ${lines[0]}`);
+                    } else {
+                        console.log(`  ${chalk.dim(e.device + ':')}`);
+                        for (const line of lines) console.log(`    ${line}`);
+                    }
+                }
+            }
+
+            console.log(
+                '\n' +
+                    chalk.gray(
+                        `${entries.length} total — ${okCount} ok, ${failCount} fail, ${timedOutCount} timeout, ${errorCount} error · ${totalDurationMs}ms`,
+                    ),
+            );
+        });
 }

package/lib/concurrency.js

@@ -0,0 +1,52 @@
+// @ts-check
+
+/**
+ * Run `worker(item, index)` over `items` with at most `limit` invocations
+ * in flight at any time. Returns an array parallel to `items` describing
+ * the outcome of each task as `{ ok: true, value }` or `{ ok: false, error }`.
+ *
+ * By default, a rejection from one worker does not stop the others — the
+ * caller inspects the results array. Set `failFast: true` to stop dequeueing
+ * new work as soon as any worker rejects; in-flight tasks still finish and
+ * their results are included. The first rejection is rethrown after the
+ * in-flight tasks settle.
+ *
+ * @template T, R
+ * @param {T[]} items
+ * @param {number} limit
+ * @param {(item: T, index: number) => Promise<R>} worker
+ * @param {{ failFast?: boolean }} [opts]
+ * @returns {Promise<Array<{ ok: true, value: R } | { ok: false, error: unknown }>>}
+ */
+export async function runPool(items, limit, worker, { failFast = false } = {}) {
+    const results = new Array(items.length);
+    let nextIndex = 0;
+    let aborted = false;
+    /** @type {unknown} */
+    let abortError = null;
+
+    const effectiveLimit = Math.max(1, Math.min(limit, items.length));
+
+    async function runner() {
+        while (!aborted) {
+            const i = nextIndex++;
+            if (i >= items.length) return;
+            try {
+                results[i] = { ok: true, value: await worker(items[i], i) };
+            } catch (error) {
+                results[i] = { ok: false, error };
+                if (failFast && !aborted) {
+                    aborted = true;
+                    abortError = error;
+                }
+            }
+        }
+    }
+
+    const runners = [];
+    for (let i = 0; i < effectiveLimit; i++) runners.push(runner());
+    await Promise.all(runners);
+
+    if (aborted && abortError) throw abortError;
+    return results;
+}

package/lib/mcp/tools-products.js

@@ -8,6 +8,9 @@ import {
     readProductScript,
     getProductApi,
 } from '../product.js';
+import { getDevices, filterActiveDevices } from '../devices.js';
+import { createDeviceAPI } from '../device-api.js';
+import { runPool } from '../concurrency.js';
 import { inputError } from '../errors.js';
 
 async function toolProducts(args) {
@@ -110,6 +113,170 @@ async function toolProductScriptDelete(args) {
     };
 }
 
+/**
+ * @typedef {{
+ *   device: string,
+ *   ok: boolean,
+ *   exitCode: number | null,
+ *   timedOut: boolean,
+ *   durationMs: number,
+ *   stdout: string,
+ *   stderr: string,
+ *   error?: string,
+ * }} ExecEntry
+ */
+
+async function toolProductExec(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.command) throw inputError('command is required');
+    const concurrency =
+        Number.isFinite(args.concurrency) && args.concurrency > 0
+            ? Math.floor(args.concurrency)
+            : 10;
+    const timeout =
+        Number.isFinite(args.timeout) && args.timeout > 0 ? Math.floor(args.timeout) : 30;
+    const failFast = !!args.fail_fast;
+    const includeOffline = !!args.all;
+
+    const filter = { productId: args.product };
+    if (args.group) filter.asset_group = args.group;
+    let devices = await getDevices(filter, args.user);
+    if (!includeOffline) devices = filterActiveDevices(devices);
+
+    if (devices.length === 0) {
+        const suffix = args.group ? `, group="${args.group}"` : '';
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No devices to run on (product="${args.product}"${suffix}).`,
+                },
+            ],
+            isError: false,
+        };
+    }
+
+    const startTs = Date.now();
+    let aborted = false;
+    /** @type {string | null} */
+    let firstFailureDevice = null;
+
+    // Worker never throws: it returns a populated `ExecEntry` in every
+    // branch (success, non-zero exit, timeout, connection error, or
+    // "skipped" once fail-fast has triggered). That keeps the post-pool
+    // mapping trivial and sidesteps the `{ ok: true } | { ok: false }`
+    // union narrowing limitation with JSDoc types.
+    const poolResults = await runPool(devices, concurrency, async (device) => {
+        if (failFast && aborted) {
+            /** @type {ExecEntry} */
+            const skipped = {
+                device: device.device,
+                ok: false,
+                exitCode: null,
+                timedOut: false,
+                durationMs: 0,
+                stdout: '',
+                stderr: '',
+                error: `skipped (fail-fast after ${firstFailureDevice})`,
+            };
+            return skipped;
+        }
+        const perStart = Date.now();
+        let stdout = '';
+        let stderr = '';
+        /** @type {ExecEntry} */
+        let entry;
+        try {
+            const api = createDeviceAPI(device.device, { user: args.user || undefined });
+            const { exitCode, timedOut } = await api.execStream(args.command, {
+                timeout,
+                onStdout: (s) => {
+                    stdout += s;
+                },
+                onStderr: (s) => {
+                    stderr += s;
+                },
+            });
+            entry = {
+                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);
+            entry = {
+                device: device.device,
+                ok: false,
+                exitCode: null,
+                timedOut: false,
+                durationMs: Date.now() - perStart,
+                stdout,
+                stderr,
+                error: msg,
+            };
+        }
+        if (failFast && !entry.ok && !aborted) {
+            aborted = true;
+            firstFailureDevice = entry.device;
+        }
+        return entry;
+    });
+
+    /** @type {ExecEntry[]} */
+    const entries = poolResults.map((r, i) => {
+        if (r && r.ok) return r.value;
+        // Defensive fallback — the worker above never throws, so this
+        // branch shouldn't trigger in practice.
+        return {
+            device: devices[i].device,
+            ok: false,
+            exitCode: null,
+            timedOut: false,
+            durationMs: 0,
+            stdout: '',
+            stderr: '',
+            error: 'unknown error',
+        };
+    });
+
+    const totalMs = Date.now() - startTs;
+    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;
+
+    const lines = [];
+    lines.push(
+        `Ran \`${args.command}\` on ${entries.length} device(s) of product "${args.product}" ` +
+            `(concurrency=${concurrency}, timeout=${timeout}s).\n`,
+    );
+    for (const e of entries) {
+        const status = e.error
+            ? `ERROR (${e.error})`
+            : e.timedOut
+              ? `TIMEOUT after ${timeout}s`
+              : e.ok
+                ? `OK exit=0`
+                : `FAIL exit=${e.exitCode}`;
+        lines.push(`--- ${e.device} [${status}] ${e.durationMs}ms ---`);
+        if (e.stdout) lines.push(e.stdout.trimEnd());
+        if (e.stderr) lines.push(`stderr: ${e.stderr.trimEnd()}`);
+    }
+    lines.push(
+        `\nSummary: ${okCount} ok, ${failCount} failed, ${timedOutCount} timed out, ${errorCount} errored — ${totalMs}ms total`,
+    );
+
+    const anyFailure = failCount + timedOutCount + errorCount > 0;
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        isError: anyFailure,
+    };
+}
+
 export const tools = [
     {
         name: 'thinr_products',
@@ -211,6 +378,51 @@ The file extension (.sh, .py, .js, …) is preserved in the storage for editor h
         },
         handler: toolProductScriptWrite,
     },
+    {
+        name: 'thinr_product_exec',
+        description: `Execute a shell command in parallel on every active device of a product, and return stdout, stderr, exit code and duration per device plus a consolidated summary.
+
+Prefer this over iterating \`thinr_exec\` device-by-device when you need to roll out or inspect something across a fleet. Offline devices are skipped by default; pass \`all: true\` to attempt them anyway (they will typically fail fast with a connection error). \`concurrency\` bounds how many devices run at once (default 10), \`timeout\` is per-device in seconds (default 30), and \`fail_fast\` stops dequeueing new devices as soon as one returns a non-zero exit / times out — in-flight work still completes.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: {
+                    type: 'string',
+                    description: 'Product ID (discover with thinr_products).',
+                },
+                command: {
+                    type: 'string',
+                    description: 'Shell command to run on each device.',
+                },
+                group: {
+                    type: 'string',
+                    description:
+                        'Optional asset group filter — restricts execution to devices in this group.',
+                },
+                concurrency: {
+                    type: 'number',
+                    description: 'Max parallel executions (default: 10).',
+                },
+                timeout: {
+                    type: 'number',
+                    description: 'Per-device timeout in seconds (default: 30).',
+                },
+                fail_fast: {
+                    type: 'boolean',
+                    description:
+                        'Stop dequeueing new devices as soon as one fails (default: false).',
+                },
+                all: {
+                    type: 'boolean',
+                    description:
+                        'Include offline devices (default: false — only active devices are targeted).',
+                },
+                user: { type: 'string', description: 'API user (admin impersonation).' },
+            },
+            required: ['product', 'command'],
+        },
+        handler: toolProductExec,
+    },
     {
         name: 'thinr_product_script_delete',
         description: `Remove a product script: deletes the file under scripts/ in the product storage and the associated API resource.`,

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinremote/thinr-cli",
-    "version": "1.1.0",
+    "version": "1.2.0-alpha.1",
     "description": "CLI for ThinRemote — remote management for IoT devices, with an MCP server for AI clients",
     "main": "bin/thinr.js",
     "bin": {
@@ -46,6 +46,7 @@
         "@modelcontextprotocol/sdk": "^1.29.0",
         "axios": "^1.10.0",
         "chalk": "^5.4.1",
+        "cli-table3": "^0.6.5",
         "commander": "^14.0.0",
         "conf": "^15.1.0",
         "figlet": "^1.8.1",