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

package/lib/command-stream.js

@@ -0,0 +1,199 @@
+// @ts-check
+import WebSocket from 'ws';
+import { randomUUID } from 'crypto';
+import { TIMEOUTS } from './constants.js';
+
+/**
+ * One-shot execution of a shell command on a device over the IOTMP
+ * WebSocket stream. The class exists to keep the four concerns of
+ * streaming exec — URL/auth, framing, safety timeout, cancellation —
+ * in visibly separate methods instead of braided together inside one
+ * big promise executor.
+ *
+ * Lifecycle:
+ *   new CommandStream({...}).run() → Promise<{exitCode, timedOut, cancelled}>
+ *
+ * `run()` opens the socket, resolves when the server sends the exit
+ * frame (or the socket closes, or the safety timer fires, or `cancel()`
+ * is called), and tears the WS down without waiting for the server's
+ * stop cascade.
+ */
+export class CommandStream {
+    /**
+     * @param {{
+     *   server: string,
+     *   token: string,
+     *   apiUser: string,
+     *   deviceId: string,
+     *   insecure: boolean,
+     *   cmd: string,
+     *   timeout?: number,
+     *   onStdout?: (s: string) => void,
+     *   onStderr?: (s: string) => void,
+     *   onCancel?: (cancel: () => void) => void,
+     *   stdin?: NodeJS.ReadableStream,
+     * }} opts
+     */
+    constructor(opts) {
+        this.opts = opts;
+        this.sessionId = randomUUID();
+        this.resource = `$cmd/${this.sessionId}`;
+
+        this.exitCode = null;
+        this.timedOut = false;
+        this.cancelled = false;
+
+        /** @type {WebSocket | null} */
+        this.ws = null;
+        this.resolved = false;
+        /** @type {NodeJS.Timeout | null} */
+        this.safetyTimer = null;
+        /** @type {((value: {exitCode: number | null, timedOut: boolean, cancelled: boolean}) => void) | null} */
+        this._resolve = null;
+        /** @type {((reason?: any) => void) | null} */
+        this._reject = null;
+    }
+
+    run() {
+        this.opts.onCancel?.(() => this.cancel());
+        return new Promise((resolve, reject) => {
+            this._resolve = resolve;
+            this._reject = reject;
+            this.ws = this._openSocket();
+            this._armSafety();
+            this._wireEvents(this.ws);
+        });
+    }
+
+    cancel() {
+        this.cancelled = true;
+        if (
+            this.ws &&
+            (this.ws.readyState === WebSocket.OPEN ||
+                this.ws.readyState === WebSocket.CONNECTING)
+        ) {
+            this.ws.close();
+        }
+    }
+
+    _buildUrl() {
+        const { server, apiUser, deviceId, cmd, timeout } = this.opts;
+        const params = new URLSearchParams({ cmd });
+        if (timeout && timeout > 0) params.set('timeout', String(timeout));
+        return `wss://${server}/v3/users/${apiUser}/devices/${deviceId}/resources/${this.resource}?${params}`;
+    }
+
+    _openSocket() {
+        return new WebSocket(this._buildUrl(), {
+            headers: { Authorization: `Bearer ${this.opts.token}` },
+            rejectUnauthorized: !this.opts.insecure,
+        });
+    }
+
+    /**
+     * Client-side safety timeout. The `timeout` URL param asks the
+     * server/agent to bound the command, but if the agent is hung the
+     * server's own timeout can take longer than expected (or not fire
+     * for some states) and the WS would otherwise stay open until
+     * ping/pong death. Grace period lives in constants.js.
+     */
+    _armSafety() {
+        const { timeout } = this.opts;
+        if (!timeout || timeout <= 0) return;
+        this.safetyTimer = setTimeout(() => {
+            if (this.resolved) return;
+            this.timedOut = true;
+            this._finish();
+        }, timeout * 1000 + TIMEOUTS.EXEC_SAFETY_GRACE_MS);
+    }
+
+    _disarmSafety() {
+        if (this.safetyTimer) {
+            clearTimeout(this.safetyTimer);
+            this.safetyTimer = null;
+        }
+    }
+
+    _wireEvents(ws) {
+        ws.on('open', () => this._forwardStdin(ws));
+        ws.on('error', (err) => {
+            if (this.cancelled || this.resolved) return;
+            this._disarmSafety();
+            this._reject?.(err);
+        });
+        ws.on('message', (raw) => this._handleMessage(raw));
+        ws.on('close', () => this._finish());
+    }
+
+    /**
+     * If the caller supplied a stdin stream, forward each chunk to the
+     * device as a stream frame. Payload is sent as a UTF-8 string
+     * under the standard {resource, payload} envelope that the
+     * server's stream handler expects.
+     */
+    _forwardStdin(ws) {
+        const { stdin } = this.opts;
+        if (!stdin || typeof stdin.on !== 'function') return;
+        stdin.on('data', (chunk) => {
+            if (ws.readyState !== WebSocket.OPEN) return;
+            const text = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+            ws.send(JSON.stringify({ resource: this.resource, payload: text }));
+        });
+    }
+
+    _handleMessage(raw) {
+        let evt;
+        try {
+            evt = JSON.parse(raw.toString('utf8'));
+        } catch {
+            return;
+        }
+        if (evt.signal && evt.signal !== 'data') return;
+        const p = evt.payload;
+        if (!p || typeof p !== 'object') return;
+        if (p.out !== undefined) {
+            this.opts.onStdout?.(decodeBytes(p.out));
+        } else if (p.err !== undefined) {
+            this.opts.onStderr?.(decodeBytes(p.err));
+        } else if (typeof p.exit === 'number') {
+            this.exitCode = p.exit;
+            if (p.timeout === true) this.timedOut = true;
+            // We have the full result — resolve immediately and tear
+            // down the WS without waiting for the server's stop
+            // cascade, which can add several seconds.
+            this._finish();
+        }
+    }
+
+    _finish() {
+        if (this.resolved) return;
+        this.resolved = true;
+        this._disarmSafety();
+        this._resolve?.({
+            exitCode: this.exitCode,
+            timedOut: this.timedOut,
+            cancelled: this.cancelled,
+        });
+        if (
+            this.ws &&
+            (this.ws.readyState === WebSocket.OPEN ||
+                this.ws.readyState === WebSocket.CONNECTING)
+        ) {
+            this.ws.terminate();
+        }
+    }
+}
+
+/**
+ * Decode a frame field that the server may deliver either as a plain
+ * string or as the `{bytes: [...]}` envelope used for binary-safe
+ * payloads. Non-strings fall back to empty so downstream handlers
+ * don't have to guard.
+ */
+function decodeBytes(field) {
+    if (typeof field === 'string') return field;
+    if (field && Array.isArray(field.bytes)) {
+        return Buffer.from(field.bytes).toString('utf8');
+    }
+    return '';
+}

package/lib/config.js

@@ -176,12 +176,14 @@ export function requireConfig() {
 
 /**
  * Write a fresh profile from the supplied data. The profile name is
- * derived from the supplied `server`, or from the active profile name
- * if no server is provided. Becomes the default if there isn't one yet.
+ * picked (in order): an explicit override set via setActiveProfile()
+ * (used by `profile add` to scope the write to a named profile), the
+ * supplied `server`, or the currently active profile name. Becomes the
+ * default if there isn't one yet.
  */
 export function writeConfig(config) {
     const store = readStore();
-    const name = (config && config.server) || getActiveProfile();
+    const name = activeProfileOverride || (config && config.server) || getActiveProfile();
     if (!name) {
         throw new Error('Cannot write config without a server / profile name');
     }

package/lib/console.js

@@ -1,7 +1,7 @@
 import WebSocket from 'ws';
-import chalk from 'chalk';
 import { requireConfig } from './config.js';
 import api from './api.js';
+import { warning, error as errorStyle } from './format.js';
 
 /**
  * Creates a WebSocket connection to a device terminal. Returns a
@@ -58,9 +58,17 @@ export async function connectToDeviceConsole(deviceId) {
             });
 
             process.stdin.on('data', (data) => {
-                // Ctrl+D (EOT) to exit gracefully
+                // Ctrl+D (EOT) to exit gracefully. The `ws.close()` below
+                // initiates a close handshake and waits for the server to
+                // acknowledge; when the server is slow to respond, the
+                // client would otherwise hang on keep-alive/TCP timeouts.
+                // Watchdog forces the socket down after a short grace so
+                // control returns to the shell promptly.
                 if (data.toString() === '\u0004') {
                     ws.close();
+                    setTimeout(() => {
+                        if (ws.readyState !== WebSocket.CLOSED) ws.terminate();
+                    }, 500);
                     return;
                 }
                 // Forward everything else (including Ctrl+C) to the device
@@ -74,7 +82,7 @@ export async function connectToDeviceConsole(deviceId) {
         });
 
         ws.on('close', () => {
-            console.log(chalk.yellow('\nConnection closed'));
+            console.log(warning('\nConnection closed'));
             restoreTerminal();
             // Small delay so any final output flushes before the caller exits.
             setTimeout(() => resolve(0), 100);
@@ -133,7 +141,7 @@ async function updateTerminalSize(config, deviceId, sessionId, cols, rows) {
             },
         });
     } catch (error) {
-        console.error(chalk.red(`Error updating terminal size: ${error.message}`));
+        console.error(errorStyle(`Error updating terminal size: ${error.message}`));
     }
 }
 

package/lib/constants.js

@@ -0,0 +1,76 @@
+// @ts-check
+
+/**
+ * Central home for the numeric knobs the CLI scatters otherwise.
+ * Keep every "magic number" that has meaning beyond its immediate call
+ * site here so we can tune them in one place (and grep for them when
+ * debugging a stuck transfer or a missed OAuth poll).
+ */
+
+/** Timeouts. All values in ms unless the constant name ends in `_SECONDS`. */
+export const TIMEOUTS = {
+    /** Default axios request timeout for control-plane HTTP calls. */
+    API_DEFAULT_MS: 10_000,
+
+    /** POSTs to device resources (cmd, update, etc.) — mid-weight calls. */
+    DEVICE_RESOURCE_CALL_MS: 30_000,
+
+    /** GETs that read a device resource value. */
+    DEVICE_RESOURCE_GET_MS: 15_000,
+
+    /** Playbook `update: apply` — agent updates can take minutes. */
+    DEVICE_UPDATE_APPLY_MS: 300_000,
+
+    /**
+     * Grace period added client-side on top of the server/agent's exec
+     * timeout so a hung agent doesn't keep the WebSocket open forever.
+     * Not proportional to the declared timeout — a 5-min command
+     * shouldn't wait 5 extra minutes just in case.
+     */
+    EXEC_SAFETY_GRACE_MS: 2_000,
+
+    /**
+     * Extra headroom on the HTTP call that wraps the legacy `api.exec`
+     * resource call, so the agent's own timeout has a chance to fire
+     * and return a proper exit code before axios aborts.
+     */
+    EXEC_EXTRA_GRACE_MS: 5_000,
+
+    /** Hard ceiling for the OAuth device-code flow — 10 minutes. */
+    OAUTH_DEVICE_CODE_MS: 10 * 60 * 1000,
+
+    /**
+     * Default command timeout (in *seconds*) for user-facing exec
+     * flows: CLI `device exec`, `product exec`, playbook `exec`, MCP
+     * `thinr_exec`. Callers override when they know better.
+     */
+    DEFAULT_EXEC_SECONDS: 30,
+
+    /** Chmod after a script install: tiny op, short seconds-level cap. */
+    SCRIPT_CHMOD_SECONDS: 10,
+};
+
+/** Byte units, so callers don't have to eyeball `1073741824`. */
+export const BYTES = {
+    KB: 1024,
+    MB: 1024 * 1024,
+    GB: 1024 * 1024 * 1024,
+
+    /**
+     * Chunk size used when wrapping in-memory buffers as Readable
+     * streams for file uploads, so `onUploadProgress` fires per chunk
+     * instead of once at 0% and once at 100%.
+     */
+    STREAM_CHUNK: 64 * 1024,
+};
+
+/** Random-port range used when creating TCP/HTTP proxies. */
+export const PROXY_PORTS = {
+    MIN: 50_000,
+    MAX: 51_000,
+};
+
+/** OAuth device-flow client identity registered for this CLI. */
+export const OAUTH = {
+    CLIENT_ID: '3b40164d28730e416cbd',
+};

package/lib/dashboard/event-stream.js

@@ -0,0 +1,239 @@
+// @ts-check
+import WebSocket from 'ws';
+import { readConfig } from '../config.js';
+import { refreshToken } from '../auth.js';
+import { debugCount, debugLog } from '../debug-log.js';
+
+// Single shared websocket to /v2/users/{user}/events. Both fleet
+// monitoring and product metrics live on the same endpoint with the
+// same auth, so opening two sockets per dashboard session is just
+// extra load on both ends.
+//
+// Use:
+//   const off = eventStream.on('bucket_write', (frame) => {...});
+//   eventStream.subscribe({ event: 'bucket_write', filters: { bucket } });
+//   eventStream.connect();      // ref-counted; first call opens
+//   ...
+//   off();                      // stop receiving frames
+//   eventStream.disconnect();   // ref-counted; last call closes
+//
+// `subscribe` is additive and idempotent — the server has no
+// unsubscribe verb in this protocol, so we can't take a filter back.
+// What we *can* do is dedupe locally so the same filter isn't sent
+// twice per session, and replay every active subscription whenever
+// the socket reconnects.
+
+const MAX_BACKOFF_MS = 30_000;
+
+class EventStream {
+    constructor() {
+        /** @type {WebSocket | null} */
+        this.ws = null;
+        this.refCount = 0;
+        /** @type {Map<string, Set<(frame: any) => void>>} */
+        this.handlers = new Map();
+        /** @type {Map<string, any>} */
+        this.subs = new Map();
+        this.reconnectAttempts = 0;
+        /** @type {NodeJS.Timeout | null} */
+        this.reconnectTimer = null;
+        this.disposed = true;
+        // Used by `onReconnect` to skip the very first open — that one is the
+        // initial connection, not a reconnect, and consumers already seed
+        // their state via the REST snapshot at mount time.
+        this.hasOpenedOnce = false;
+        /** @type {Set<() => void>} */
+        this.reconnectHandlers = new Set();
+    }
+
+    // Fired when the socket reopens after a previous disconnection. Use it
+    // to re-fetch any REST snapshot that backs an event-driven view, since
+    // events emitted while we were offline are gone for good.
+    onReconnect(handler) {
+        this.reconnectHandlers.add(handler);
+        return () => this.reconnectHandlers.delete(handler);
+    }
+
+    connect() {
+        this.refCount++;
+        this.disposed = false;
+        if (this.ws == null && this.reconnectTimer == null) this._open();
+    }
+
+    disconnect() {
+        this.refCount = Math.max(0, this.refCount - 1);
+        if (this.refCount === 0) {
+            this.disposed = true;
+            this._teardown();
+        }
+    }
+
+    on(eventName, handler) {
+        let set = this.handlers.get(eventName);
+        if (!set) {
+            set = new Set();
+            this.handlers.set(eventName, set);
+        }
+        set.add(handler);
+        return () => {
+            const cur = this.handlers.get(eventName);
+            if (cur) {
+                cur.delete(handler);
+                if (cur.size === 0) this.handlers.delete(eventName);
+            }
+        };
+    }
+
+    subscribe(message) {
+        const key = JSON.stringify(message);
+        if (this.subs.has(key)) return;
+        this.subs.set(key, message);
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            debugLog('ws:events', 'subscribe', message);
+            this.ws.send(key);
+        }
+    }
+
+    async _open() {
+        // If a previous handshake hit 401 we trigger a token refresh in the
+        // background; await it here so the next attempt uses the fresh
+        // token instead of racing the HTTP interceptor's refresh.
+        if (this._refreshing) {
+            try { await this._refreshing; } catch { /* fall through; readConfig may still have a usable token */ }
+        }
+        if (this.disposed) return;
+        const config = readConfig();
+        if (!config?.server || !config?.token || !config?.username) return;
+        const url = `wss://${config.server}/v2/users/${config.username}/events?authorization=${config.token}`;
+        debugLog('ws:events', 'connecting', {
+            endpoint: `wss://${config.server}/v2/users/${config.username}/events`,
+            pending_subs: this.subs.size,
+        });
+        const ws = new WebSocket(url);
+        this.ws = ws;
+
+        ws.on('open', () => {
+            if (this.disposed) {
+                ws.close();
+                return;
+            }
+            const isReconnect = this.hasOpenedOnce;
+            this.hasOpenedOnce = true;
+            this.reconnectAttempts = 0;
+            debugLog('ws:events', 'open', {
+                sub_replay: this.subs.size,
+                reconnect: isReconnect,
+            });
+            for (const [key, msg] of this.subs.entries()) {
+                debugLog('ws:events', 'subscribe', msg);
+                ws.send(key);
+            }
+            // Notify after replaying subs so reconnect handlers run with a
+            // fully resubscribed socket — they can rely on new events landing.
+            if (isReconnect) {
+                for (const h of this.reconnectHandlers) {
+                    try { h(); } catch (err) {
+                        debugLog('ws:events', 'reconnect-handler-error', {
+                            error: err?.message || String(err),
+                        });
+                    }
+                }
+            }
+        });
+
+        ws.on('message', (raw) => {
+            const bytes = raw?.length ?? 0;
+            debugCount('ws:events:bytes', bytes);
+            debugCount('ws:events:frames');
+            let frame;
+            try {
+                frame = JSON.parse(raw.toString('utf8'));
+            } catch {
+                return;
+            }
+            if (frame?.registered || frame?.success === false) {
+                debugLog('ws:events', 'ack', frame);
+                return;
+            }
+            const ev = frame?.event;
+            if (!ev) return;
+            debugCount(`ws:events:${ev}`);
+            const set = this.handlers.get(ev);
+            if (!set || set.size === 0) return;
+            for (const h of set) {
+                try {
+                    h(frame);
+                } catch (err) {
+                    debugLog('ws:events', 'handler-error', {
+                        event: ev,
+                        error: err?.message || String(err),
+                    });
+                }
+            }
+        });
+
+        ws.on('error', (err) => {
+            debugLog('ws:events', 'error', { error: err?.message || String(err) });
+        });
+
+        // Server rejects expired tokens at the WS handshake with HTTP 401.
+        // Without this, we'd reconnect with the same stale token until the
+        // exponential backoff outlasted the HTTP interceptor's refresh,
+        // which leaves the dashboard empty for up to a minute on the first
+        // open after a token expires. Trigger an explicit refresh; _open
+        // awaits the in-flight promise on the next reconnect attempt.
+        ws.on('unexpected-response', (req, res) => {
+            debugLog('ws:events', 'unexpected-response', {
+                status: res?.statusCode,
+                pending_refresh: !!this._refreshing,
+            });
+            if (res?.statusCode === 401 && !this._refreshing) {
+                this._refreshing = refreshToken()
+                    .then(() => {
+                        debugLog('ws:events', 'token-refreshed');
+                    })
+                    .catch((err) => {
+                        debugLog('ws:events', 'token-refresh-failed', {
+                            error: err?.message || String(err),
+                        });
+                    })
+                    .finally(() => {
+                        this._refreshing = null;
+                    });
+            }
+        });
+
+        ws.on('close', (code, reason) => {
+            this.ws = null;
+            debugLog('ws:events', 'close', { code, reason: reason?.toString?.() });
+            if (this.disposed) return;
+            const attempt = this.reconnectAttempts++;
+            const delay = Math.min(2 ** attempt * 1000, MAX_BACKOFF_MS);
+            debugLog('ws:events', 'reconnect-scheduled', { attempt, delay_ms: delay });
+            this.reconnectTimer = setTimeout(() => {
+                this.reconnectTimer = null;
+                if (!this.disposed) this._open();
+            }, delay);
+        });
+    }
+
+    _teardown() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            try {
+                this.ws.close();
+            } catch {
+                // ignore
+            }
+            this.ws = null;
+        }
+        this.subs.clear();
+        this.handlers.clear();
+        this.reconnectAttempts = 0;
+    }
+}
+
+export const eventStream = new EventStream();

package/lib/dashboard/metric-aggregate.js

@@ -0,0 +1,64 @@
+// @ts-check
+
+// Pure helpers for product-metric aggregation. Extracted from
+// `useProductMetrics` so the dashboard hook stays minimal and the
+// reducers can be unit-tested without dragging React or the websocket
+// singleton into the test runtime.
+
+/**
+ * Walk a dotted path into a payload. Returns `obj` itself when no path
+ * is supplied, and `undefined` when any intermediate hop is null.
+ *
+ * @param {*} obj
+ * @param {string | undefined} dotted
+ */
+export function getPath(obj, dotted) {
+    if (!dotted) return obj;
+    return dotted.split('.').reduce((acc, key) => (acc == null ? acc : acc[key]), obj);
+}
+
+/**
+ * Combine the latest values reported by every device of a product into
+ * a single panel value. Numeric reducers ignore non-numeric / null
+ * samples; categorical reducers operate on the raw values.
+ *
+ *   distribution → Record<string, number> (value coerced to string → device count)
+ *   count        → number of devices reporting any non-null value
+ *   none         → the raw values array, untouched
+ *   sum/avg/max/min → number, or null when no numeric samples are present
+ *
+ * @param {readonly unknown[]} values
+ * @param {string | undefined} mode
+ */
+export function aggregate(values, mode) {
+    if (mode === 'distribution') {
+        /** @type {Record<string, number>} */
+        const buckets = {};
+        for (const v of values) {
+            if (v == null) continue;
+            const key = String(v);
+            if (key === '') continue;
+            buckets[key] = (buckets[key] || 0) + 1;
+        }
+        return buckets;
+    }
+    if (mode === 'count') {
+        return values.filter((v) => v != null).length;
+    }
+    if (mode === 'none') {
+        return values;
+    }
+    const nums = values.filter((v) => Number.isFinite(Number(v))).map(Number);
+    if (nums.length === 0) return null;
+    switch (mode) {
+        case 'avg':
+            return nums.reduce((a, b) => a + b, 0) / nums.length;
+        case 'max':
+            return Math.max(...nums);
+        case 'min':
+            return Math.min(...nums);
+        case 'sum':
+        default:
+            return nums.reduce((a, b) => a + b, 0);
+    }
+}

package/lib/dashboard/metric-filter.js

@@ -0,0 +1,39 @@
+// @ts-check
+
+// Pure helper for the "click a bucket → filter devices" interaction.
+//
+// `valuesByDevice` mirrors the per-device latest sample map maintained
+// inside `useProductMetrics`: keyed by metricKey (`<product>:<name>`),
+// the value is a map of deviceId → latest value reported for that
+// metric. We compare reported values to the bucket key after coercing
+// both sides to string, matching the behaviour of the `distribution`
+// aggregator (which also bins by `String(v)`).
+
+/**
+ * @typedef {{ device: string, [k: string]: any }} DeviceLike
+ * @typedef {{ metricKey: string, bucket: string, [k: string]: any } | null | undefined} MetricFilter
+ */
+
+/**
+ * Filter a fleet view down to the devices whose latest sample for the
+ * filter's metric equals the chosen bucket. Devices missing a sample for
+ * that metric (offline or never-reported) drop out — they belong to the
+ * implicit "no data" bucket, which the panel doesn't surface.
+ *
+ * @template {DeviceLike} D
+ * @param {readonly D[]} devices
+ * @param {Record<string, Record<string, any>> | null | undefined} valuesByDevice
+ * @param {MetricFilter} metricFilter
+ * @returns {D[]}
+ */
+export function filterDevicesByMetric(devices, valuesByDevice, metricFilter) {
+    if (!metricFilter || metricFilter.bucket == null) return [...devices];
+    const map = valuesByDevice?.[metricFilter.metricKey];
+    if (!map) return [];
+    const target = String(metricFilter.bucket);
+    return devices.filter((d) => {
+        const v = map[d.device];
+        if (v == null) return false;
+        return String(v) === target;
+    });
+}