@thinremote/thinr-cli 1.1.0 → 1.2.0

package/commands/device/property.js

@@ -5,12 +5,18 @@ import {
     getDeviceProperties,
     formatDeviceProperties,
 } from '../../lib/property.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, ensureConfigured } from './_shared.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    extractField,
+    runDeviceCommand,
+} from './_shared.js';
 
 export function registerPropertyCommand(device) {
     device
         .command('property <deviceId> [propertyId]')
+        .helpGroup('State & resources:')
         .description('List device properties, or read one by ID')
         .option('-j, --json', 'Output as JSON')
         .option('-f, --field <field>', 'Extract a sub-field (dot path, e.g. data.value)')
@@ -18,33 +24,29 @@ export function registerPropertyCommand(device) {
             applyJsonFlag(opts);
             ensureConfigured();
             if (!propertyId) {
-                const spinner = createSpinner(`Getting properties for ${deviceId}...`).start();
-                try {
-                    const result = await getDeviceProperties(deviceId);
-                    spinner.succeed(`Properties for ${deviceId} retrieved successfully`);
-                    if (isJsonMode()) printOk(result);
-                    else console.log(formatDeviceProperties(deviceId, result));
-                } catch (error) {
-                    spinner.fail('Property retrieval failed');
-                    const { message, code } = classifyError(error);
-                    printErr(message, { code });
-                }
+                await runDeviceCommand({
+                    start: `Getting properties for ${deviceId}...`,
+                    fn: () => getDeviceProperties(deviceId),
+                    success: `Properties for ${deviceId} retrieved successfully`,
+                    failure: 'Property retrieval failed',
+                    onSuccess: (result) => {
+                        if (isJsonMode()) printOk(result);
+                        else console.log(formatDeviceProperties(deviceId, result));
+                    },
+                });
                 return;
             }
-            const spinner = createSpinner(`Retrieving property for ${deviceId}...`).start();
-            try {
-                const property = await getDeviceProperty(deviceId, propertyId);
-                spinner.succeed(`Property ${propertyId} for ${deviceId} found`);
-                const value = opts.field
-                    ? opts.field.split('.').reduce((obj, key) => obj && obj[key], property)
-                    : property;
-                if (isJsonMode()) printOk(value);
-                else if (opts.field) console.log(value);
-                else console.log(formatDeviceProperty(deviceId, propertyId, property));
-            } catch (error) {
-                spinner.fail('Property retrieval failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Retrieving property for ${deviceId}...`,
+                fn: () => getDeviceProperty(deviceId, propertyId),
+                success: `Property ${propertyId} for ${deviceId} found`,
+                failure: 'Property retrieval failed',
+                onSuccess: (property) => {
+                    const value = extractField(property, opts.field);
+                    if (isJsonMode()) printOk(value);
+                    else if (opts.field) console.log(value);
+                    else console.log(formatDeviceProperty(deviceId, propertyId, property));
+                },
+            });
         });
 }

package/commands/device/proxy.js

@@ -5,6 +5,7 @@ import { ensureConfigured, runInteractive } from './_shared.js';
 export function registerProxyCommands(device) {
     device
         .command('tcp <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create a TCP proxy (no TLS). Default target: 22.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .action((deviceId, target, opts) =>
@@ -16,6 +17,7 @@ export function registerProxyCommands(device) {
 
     device
         .command('tls <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create a TLS proxy. Default target: 443.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .action((deviceId, target, opts) =>
@@ -27,6 +29,7 @@ export function registerProxyCommands(device) {
 
     device
         .command('http <deviceId> [target]')
+        .helpGroup('Remote access:')
         .description('Create an HTTP proxy. Default target: 80.')
         .option('-p, --port <port>', 'Local port to use (default: random)')
         .option('--no-open', 'Do not open the browser')

package/commands/device/resource.js

@@ -4,12 +4,19 @@ import {
     listDeviceResourcesWithSchemas,
     formatDeviceResourcesWithSchemas,
 } from '../../lib/resource.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, collectInput, ensureConfigured } from './_shared.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import {
+    applyJsonFlag,
+    collectInput,
+    ensureConfigured,
+    extractField,
+    runDeviceCommand,
+} from './_shared.js';
 
 export function registerResourceCommand(device) {
     device
         .command('resource <deviceId> [resource]')
+        .helpGroup('State & resources:')
         .description('List device resources, or call one by name')
         .option('-j, --json', 'Output as JSON')
         .option('-f, --field <field>', 'Extract a sub-field from the result (dot path)')
@@ -18,34 +25,28 @@ export function registerResourceCommand(device) {
             applyJsonFlag(opts);
             ensureConfigured();
             if (!resource) {
-                const spinner = createSpinner(`Getting resources for ${deviceId}...`).start();
-                try {
-                    const entries = await listDeviceResourcesWithSchemas(deviceId);
-                    spinner.succeed(`Successfully retrieved resources for ${deviceId}`);
-                    if (isJsonMode()) printOk(entries);
-                    else console.log(formatDeviceResourcesWithSchemas(deviceId, entries));
-                } catch (error) {
-                    spinner.fail('Resource retrieval failed');
-                    const { message, code } = classifyError(error);
-                    printErr(message, { code });
-                }
+                await runDeviceCommand({
+                    start: `Getting resources for ${deviceId}...`,
+                    fn: () => listDeviceResourcesWithSchemas(deviceId),
+                    success: `Successfully retrieved resources for ${deviceId}`,
+                    failure: 'Resource retrieval failed',
+                    onSuccess: (entries) => {
+                        if (isJsonMode()) printOk(entries);
+                        else console.log(formatDeviceResourcesWithSchemas(deviceId, entries));
+                    },
+                });
                 return;
             }
-            const spinner = createSpinner(
-                `Calling resource ${resource} for ${deviceId}...`,
-            ).start();
-            try {
-                const result = await callDeviceResource(deviceId, resource, opts.input);
-                spinner.succeed(`Resource ${resource} returned successfully for ${deviceId}`);
-                const value = opts.field
-                    ? opts.field.split('.').reduce((obj, key) => obj && obj[key], result)
-                    : result;
-                if (isJsonMode()) printOk(value);
-                else console.log(value);
-            } catch (error) {
-                spinner.fail('Resource call failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Calling resource ${resource} for ${deviceId}...`,
+                fn: () => callDeviceResource(deviceId, resource, opts.input),
+                success: `Resource ${resource} returned successfully for ${deviceId}`,
+                failure: 'Resource call failed',
+                onSuccess: (result) => {
+                    const value = extractField(result, opts.field);
+                    if (isJsonMode()) printOk(value);
+                    else console.log(value);
+                },
+            });
         });
 }

package/commands/device/status.js

@@ -1,26 +1,47 @@
 // @ts-check
 import { getDeviceStatus, formatDeviceStatus } from '../../lib/status.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, ensureConfigured } from './_shared.js';
+import { getMonitoringData } from '../../lib/monitoring.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import { applyJsonFlag, ensureConfigured, runDeviceCommand } from './_shared.js';
 
 export function registerStatusCommand(device) {
     device
         .command('status <deviceId>')
-        .description('Check device status and stats')
+        .helpGroup('Discovery:')
+        .description('Check device status, data transfer and the latest monitoring sample')
         .option('-j, --json', 'Output as JSON')
         .action(async (deviceId, opts) => {
             applyJsonFlag(opts);
             ensureConfigured();
-            const spinner = createSpinner(`Checking status of ${deviceId}...`).start();
-            try {
-                const status = await getDeviceStatus(deviceId);
-                spinner.succeed(`Device ${deviceId} found`);
-                if (isJsonMode()) printOk(status);
-                else console.log(formatDeviceStatus(deviceId, status));
-            } catch (error) {
-                spinner.fail('Status check failed');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+            await runDeviceCommand({
+                start: `Checking status of ${deviceId}...`,
+                // Fetch the server-side stats and the latest monitoring sample
+                // in parallel — the monitoring call is best-effort, we still
+                // render the stats section if the bucket query fails or the
+                // device never published.
+                fn: async () => {
+                    const [statusResult, monitoringResult] = await Promise.allSettled([
+                        getDeviceStatus(deviceId),
+                        getMonitoringData({ device: deviceId, items: 1, sort: 'desc' }),
+                    ]);
+                    if (statusResult.status === 'rejected') throw statusResult.reason;
+                    const monitoring =
+                        monitoringResult.status === 'fulfilled' &&
+                        Array.isArray(monitoringResult.value) &&
+                        monitoringResult.value.length > 0
+                            ? monitoringResult.value[0]
+                            : null;
+                    return { status: statusResult.value, monitoring };
+                },
+                // Skip the success banner: the detail block below speaks
+                // for the "found" state and the failure path prints its
+                // own clear error.
+                success: null,
+                failure: 'Status check failed',
+                onSuccess: ({ status, monitoring }) => {
+                    if (isJsonMode()) printOk({ ...status, monitoring });
+                    else console.log(formatDeviceStatus(deviceId, status, monitoring));
+                },
+            });
         });
 }

package/commands/device/transfer.js

@@ -0,0 +1,236 @@
+// @ts-check
+import { readFile as readLocalFile, writeFile as writeLocalFile, stat as statLocal } from 'fs/promises';
+import { createReadStream } from 'fs';
+import { Transform } from 'node:stream';
+import { basename } from 'path';
+import cliProgress from 'cli-progress';
+import { createDeviceAPI } from '../../lib/device-api.js';
+import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { success, hint, formatBytes, formatETA } from '../../lib/format.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+
+/**
+ * Build a single-line progress bar for a byte-counted transfer.
+ * Disabled when stdout isn't a TTY or when the caller asked for JSON
+ * output — in both cases the caller resorts to a simpler log line.
+ */
+function makeTransferBar(totalBytes) {
+    // cli-progress counts characters literally when sizing the line,
+    // so ANSI escape codes inside barChars / placeholders would make
+    // the whole thing truncate. Keep the bar and its columns plain;
+    // the theme lives on the surrounding "Uploading" / "Uploaded"
+    // lines instead.
+    const sizeW = 9;
+    const rateW = 12;
+    const etaW = 11;
+    const bar = new cliProgress.SingleBar({
+        // `{eta}` is reserved by cli-progress (plain seconds, no label);
+        // use a different placeholder name so our "ETA 12s" string
+        // actually shows up instead of being silently overridden.
+        format: `  {bar} {percentage}%  {transferred}/{total_human}  {rate}  {countdown}`,
+        barCompleteChar: '█',
+        barIncompleteChar: '░',
+        barsize: 24,
+        hideCursor: true,
+        clearOnComplete: false,
+        stopOnComplete: false,
+    });
+    const startedAt = Date.now();
+    bar.start(totalBytes, 0, {
+        transferred: formatBytes(0).padStart(sizeW),
+        total_human: formatBytes(totalBytes).padEnd(sizeW),
+        rate: '—'.padStart(rateW),
+        countdown: 'ETA —'.padEnd(etaW),
+    });
+    const onProgress = (ev) => {
+        const loaded = ev?.loaded ?? 0;
+        const elapsed = (Date.now() - startedAt) / 1000;
+        const rate = elapsed > 0 ? loaded / elapsed : 0;
+        const remaining = Math.max(0, totalBytes - loaded);
+        const etaSeconds = rate > 0 ? remaining / rate : Infinity;
+        bar.update(loaded, {
+            transferred: formatBytes(loaded).padStart(sizeW),
+            total_human: formatBytes(totalBytes).padEnd(sizeW),
+            rate:
+                elapsed > 0.2
+                    ? `${formatBytes(rate)}/s`.padStart(rateW)
+                    : '—'.padStart(rateW),
+            countdown:
+                elapsed > 0.5 && Number.isFinite(etaSeconds)
+                    ? `ETA ${formatETA(etaSeconds)}`.padEnd(etaW)
+                    : 'ETA —'.padEnd(etaW),
+        });
+    };
+    const finish = () => {
+        const elapsed = (Date.now() - startedAt) / 1000;
+        const averageRate = elapsed > 0 ? totalBytes / elapsed : 0;
+        bar.update(totalBytes, {
+            transferred: formatBytes(totalBytes).padStart(sizeW),
+            total_human: formatBytes(totalBytes).padEnd(sizeW),
+            rate:
+                elapsed > 0
+                    ? `${formatBytes(averageRate)}/s`.padStart(rateW)
+                    : '—'.padStart(rateW),
+            countdown: 'done'.padEnd(etaW),
+        });
+        bar.stop();
+        return { elapsed, averageRate };
+    };
+    return { onProgress, finish };
+}
+
+/**
+ * Split `push` and `pull` into two plain commands instead of the
+ * scp-style single `cp` with `<deviceId>:` prefixes. Intent is obvious
+ * from the verb and the argument order is always the same: device id,
+ * then source, then destination — no ambiguity about "which side is
+ * local".
+ */
+export function registerTransferCommands(device) {
+    device
+        .command('push <deviceId> <localPath> <remotePath>')
+        .helpGroup('Filesystem:')
+        .description('Upload a local file to the device (use trailing "/" on remote to keep the source basename)')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, localPath, remotePath, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            const finalRemote = remotePath.endsWith('/')
+                ? remotePath + basename(localPath)
+                : remotePath;
+
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const fileStat = await statLocal(localPath);
+                const totalBytes = fileStat.size;
+                const useBar = !isJsonMode() && !!process.stdout.isTTY;
+                if (!useBar) {
+                    // No progress bar needed — keep the simpler,
+                    // whole-buffer path that other callers also use.
+                    const content = await readLocalFile(localPath);
+                    await api.writeFile(finalRemote, content);
+                    if (isJsonMode()) {
+                        printOk({
+                            direction: 'push',
+                            device: deviceId,
+                            local: localPath,
+                            remote: finalRemote,
+                            bytes: content.byteLength,
+                        });
+                    } else {
+                        console.log(
+                            success(`Uploaded ${localPath} → ${deviceId}:${finalRemote}`) +
+                                ' ' +
+                                hint(`(${formatBytes(content.byteLength)})`),
+                        );
+                    }
+                    return;
+                }
+                console.log(
+                    hint(`Uploading ${localPath} → ${deviceId}:${finalRemote}`),
+                );
+                const { onProgress, finish } = makeTransferBar(totalBytes);
+                // A Transform between the file stream and axios counts
+                // bytes only when the downstream (axios → HTTP socket)
+                // accepts them. Backpressure means the count rises at
+                // the speed of the slowest link, so the bar tracks
+                // actual network progress instead of the speed of the
+                // local disk read. axios' own onUploadProgress would
+                // otherwise report the buffer fill, not the wire.
+                const stream = createReadStream(localPath, { highWaterMark: 64 * 1024 });
+                let loaded = 0;
+                const meter = new Transform({
+                    transform(chunk, _enc, cb) {
+                        loaded += chunk.length;
+                        onProgress({ loaded, total: totalBytes });
+                        cb(null, chunk);
+                    },
+                });
+                stream.pipe(meter);
+                await api.writeFile(finalRemote, meter, true, {
+                    contentLength: totalBytes,
+                });
+                const { elapsed, averageRate } = finish();
+                console.log(
+                    success(`Uploaded ${localPath} → ${deviceId}:${finalRemote}`) +
+                        ' ' +
+                        hint(
+                            `(${formatBytes(totalBytes)} in ${elapsed.toFixed(1)}s, ${formatBytes(averageRate)}/s avg)`,
+                        ),
+                );
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('pull <deviceId> <remotePath> <localPath>')
+        .helpGroup('Filesystem:')
+        .description('Download a remote file from the device to local disk')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, remotePath, localPath, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            const finalLocal = localPath.endsWith('/')
+                ? localPath + basename(remotePath)
+                : localPath;
+
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const useBar = !isJsonMode() && !!process.stdout.isTTY;
+                if (!useBar) {
+                    const buf = await api.readFile(remotePath);
+                    await writeLocalFile(finalLocal, buf);
+                    if (isJsonMode()) {
+                        printOk({
+                            direction: 'pull',
+                            device: deviceId,
+                            remote: remotePath,
+                            local: finalLocal,
+                            bytes: buf.byteLength,
+                        });
+                    } else {
+                        console.log(
+                            success(`Downloaded ${deviceId}:${remotePath} → ${finalLocal}`) +
+                                ' ' +
+                                hint(`(${formatBytes(buf.byteLength)})`),
+                        );
+                    }
+                    return;
+                }
+                // First HEAD-like round-trip isn't available; axios
+                // surfaces `total` on the first onDownloadProgress
+                // frame if the server sent Content-Length. Start the
+                // bar deferred until we know the total.
+                console.log(
+                    hint(`Downloading ${deviceId}:${remotePath} → ${finalLocal}`),
+                );
+                /** @type {ReturnType<typeof makeTransferBar> | null} */
+                let bar = null;
+                const buf = await api.readFile(remotePath, {
+                    onProgress: (ev) => {
+                        if (!bar && ev?.total) bar = makeTransferBar(ev.total);
+                        bar?.onProgress(ev);
+                    },
+                });
+                if (!bar) bar = makeTransferBar(buf.byteLength);
+                const { elapsed, averageRate } = bar.finish();
+                await writeLocalFile(finalLocal, buf);
+                console.log(
+                    success(`Downloaded ${deviceId}:${remotePath} → ${finalLocal}`) +
+                        ' ' +
+                        hint(
+                            `(${formatBytes(buf.byteLength)} in ${elapsed.toFixed(1)}s, ${formatBytes(averageRate)}/s avg)`,
+                        ),
+                );
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+}

package/commands/device/update.js

@@ -1,7 +1,8 @@
 // @ts-check
-import chalk from 'chalk';
 import { createDeviceAPI } from '../../lib/device-api.js';
 import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
+import { label as labelText, accent } from '../../lib/format.js';
+import { TIMEOUTS } from '../../lib/constants.js';
 import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
 
 const runUpdate = async (action, deviceId, opts, cmd) => {
@@ -9,33 +10,37 @@ const runUpdate = async (action, deviceId, opts, cmd) => {
     ensureConfigured();
     const user = getGlobalUser(cmd);
     const channel = opts.channel || 'latest';
-    const label = action === 'check' ? 'Checking for updates' : 'Applying update';
-    const spinner = createSpinner(`${label} on ${deviceId}...`).start();
+    const phase = action === 'check' ? 'Checking for updates' : 'Applying update';
+    const spinner = createSpinner(`${phase} on ${deviceId}...`).start();
     try {
         const api = createDeviceAPI(deviceId, { user });
-        const timeout = action === 'apply' ? 300000 : 30000;
+        const timeout =
+            action === 'apply' ? TIMEOUTS.DEVICE_UPDATE_APPLY_MS : TIMEOUTS.DEVICE_RESOURCE_CALL_MS;
         const result = await api.callResource('update', { action, channel }, { timeout });
-        spinner.succeed(`${label} finished`);
+        spinner.succeed(`${phase} finished`);
         if (isJsonMode()) {
             printOk(result);
         } else if (result && typeof result === 'object') {
-            if (result.current) console.log(`  current: ${chalk.bold(result.current)}`);
-            if (result.latest) console.log(`  latest:  ${chalk.bold(result.latest)}`);
+            if (result.current) console.log(`  current: ${labelText(result.current)}`);
+            if (result.latest) console.log(`  latest:  ${labelText(result.latest)}`);
             if (result.arch) console.log(`  arch:    ${result.arch}`);
-            if (result.status) console.log(`  status:  ${chalk.cyan(result.status)}`);
+            if (result.status) console.log(`  status:  ${accent(result.status)}`);
             if (result.message) console.log(`  message: ${result.message}`);
         } else {
             console.log(result);
         }
     } catch (error) {
-        spinner.fail(`${label} failed`);
+        spinner.fail(`${phase} failed`);
         const { message, code } = classifyError(error);
         printErr(message, { code });
     }
 };
 
 export function registerUpdateCommand(device) {
-    const update = device.command('update').description('Check for or apply agent updates');
+    const update = device
+        .command('update')
+        .helpGroup('Execution:')
+        .description('Check for or apply agent updates');
 
     update
         .command('check <deviceId>')

package/commands/fleet/index.js

@@ -0,0 +1,17 @@
+// @ts-check
+import { registerUpgradeCommand } from './upgrade.js';
+
+/**
+ * `thinr fleet <subcommand>` — operations that treat the whole device
+ * fleet as the unit of work, not a single device. Today we only expose
+ * `upgrade`; future fan-out commands (status summary, health probe,
+ * rollback, etc.) would live alongside it.
+ */
+export function fleetCommand(program) {
+    const fleet = program
+        .command('fleet')
+        .helpGroup('Operations:')
+        .description('Fleet-wide commands (run once, touch many devices)');
+
+    registerUpgradeCommand(fleet);
+}