@thinremote/thinr-cli 1.2.0-alpha.1 → 1.3.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;
+    });
+}

package/lib/debug-log.js

@@ -0,0 +1,93 @@
+// @ts-check
+import { createWriteStream, mkdirSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+
+// Opt-in JSONL logger for diagnosing dashboard backend load. Activates only
+// when `THINR_DEBUG` is set to a truthy string. Writes to
+// `~/.thinr/dashboard-debug.log` so it never collides with the Ink alt-screen.
+//
+// API:
+//   debugLog(category, msg, data?) — one line per event
+//   debugCount(key, n = 1)         — bump a counter; flushed every 5s in a
+//                                    `summary` line and then reset, so the
+//                                    log shows event rates without one row
+//                                    per high-frequency frame.
+//   isDebugEnabled()
+//
+// Each line is JSON:
+//   { t: <iso>, c: <category>, m: <msg>, d?: <data> }
+//   { t: <iso>, c: 'summary', d: { '<key>': <count>, ... } }
+
+const SUMMARY_MS = 5_000;
+
+let stream = null;
+let enabled = null;
+let counters = new Map();
+let summaryTimer = null;
+
+function init() {
+    if (enabled !== null) return;
+    enabled = !!process.env.THINR_DEBUG;
+    if (!enabled) return;
+    const dir = join(homedir(), '.thinr');
+    try {
+        mkdirSync(dir, { recursive: true });
+    } catch {
+        // best-effort; if creation fails the createWriteStream below will
+        // also fail and we silently disable.
+    }
+    const path = join(dir, 'dashboard-debug.log');
+    try {
+        stream = createWriteStream(path, { flags: 'w' });
+    } catch {
+        enabled = false;
+        return;
+    }
+    write({
+        t: new Date().toISOString(),
+        c: 'init',
+        m: 'log open',
+        d: { pid: process.pid, mode: process.env.THINR_DEBUG },
+    });
+    summaryTimer = setInterval(flushSummary, SUMMARY_MS);
+    summaryTimer.unref?.();
+}
+
+function write(obj) {
+    if (!stream) return;
+    try {
+        stream.write(JSON.stringify(obj) + '\n');
+    } catch {
+        // ignore — better to drop a line than crash the dashboard.
+    }
+}
+
+function flushSummary() {
+    if (!enabled || counters.size === 0) return;
+    const d = Object.fromEntries(counters);
+    counters = new Map();
+    write({ t: new Date().toISOString(), c: 'summary', d });
+}
+
+export function debugLog(category, msg, data) {
+    init();
+    if (!enabled) return;
+    write({
+        t: new Date().toISOString(),
+        c: category,
+        m: msg,
+        ...(data !== undefined ? { d: data } : {}),
+    });
+}
+
+export function debugCount(key, n = 1) {
+    init();
+    if (!enabled) return;
+    counters.set(key, (counters.get(key) || 0) + n);
+}
+
+export function isDebugEnabled() {
+    init();
+    return !!enabled;
+}

package/lib/device-api.js

@@ -1,42 +1,40 @@
 import api from './api.js';
 import { requireConfig } from './config.js';
-import WebSocket from 'ws';
-import { randomUUID } from 'crypto';
+import { BYTES, TIMEOUTS } from './constants.js';
+import { CommandStream } from './command-stream.js';
+import { ensureFreshToken, refreshToken } from './auth.js';
+import { Readable } from 'node:stream';
+
+// Directory endpoints on the agent expect a trailing slash so it can
+// distinguish "list this directory" from "read a file with this name".
+const withTrailingSlash = (p) => (p.endsWith('/') ? p : p + '/');
+
+// The $fs/hash resource is mounted under the resource path, which is
+// already an absolute URL path; the caller's relative `foo/bar` would
+// otherwise produce `…/resources/$fs/hashfoo/bar`. Prepend the slash.
+const withLeadingSlash = (p) => (p.startsWith('/') ? p : `/${p}`);
 
-/**
- * Create a device API client for filesystem and command operations
- * @param {string} deviceId - The device ID
- * @param {Object} [options] - Options
- * @param {string} [options.user] - Override API user (admin impersonation)
- * @returns {Object} API client with fs and exec methods
- */
 export function createDeviceAPI(deviceId, options = {}) {
     const config = requireConfig();
     const apiUser = options.user || config.username;
     const resourcePath = `/v3/users/${apiUser}/devices/${deviceId}/resources`;
     const filesPath = `/v3/users/${apiUser}/devices/${deviceId}/files`;
 
-    /**
-     * Call a device resource (for cmd, etc.)
-     */
     async function callResource(resource, payload = null, opts = {}) {
         const url = `${resourcePath}/${resource}`;
         const response = await api.post(url, payload, {
             responseType: opts.responseType || 'json',
             params: opts.params || {},
             headers: opts.headers || {},
-            timeout: opts.timeout || 30000,
+            timeout: opts.timeout || TIMEOUTS.DEVICE_RESOURCE_CALL_MS,
         });
         return response;
     }
 
     return {
-        /**
-         * List directory contents
-         * GET /v3/users/{user}/devices/{device}/files/{path}/
-         */
+        // GET /v3/users/{user}/devices/{device}/files/{path}/
         async listDir(dirPath, includeHidden = false) {
-            const normalized = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+            const normalized = withTrailingSlash(dirPath);
             const params = {};
             if (includeHidden) params.hidden = true;
             const response = await api.get(`${filesPath}${normalized}`, { params });
@@ -44,34 +42,73 @@ export function createDeviceAPI(deviceId, options = {}) {
         },
 
         /**
-         * Read file contents
+         * Read file contents. Pass `opts.onProgress` to observe the
+         * download byte-by-byte (axios ProgressEvent: `{ loaded, total,
+         * progress, rate, ... }`). File transfers run with no HTTP
+         * timeout by default because a large pull can easily outlast
+         * the default 10s axios timeout.
+         *
          * GET /v3/users/{user}/devices/{device}/files/{path}
          */
-        async readFile(filePath) {
+        async readFile(filePath, opts = {}) {
             const response = await api.get(`${filesPath}${filePath}`, {
                 responseType: 'arraybuffer',
+                timeout: opts.timeout ?? 0,
+                onDownloadProgress: opts.onProgress,
             });
             return Buffer.from(response.data);
         },
 
         /**
-         * Write file contents
+         * Write file contents. Pass `opts.onProgress` to observe the
+         * upload byte-by-byte (axios ProgressEvent: `{ loaded, total,
+         * progress, rate, ... }`). Buffers are wrapped in a chunked
+         * Readable so the progress callback fires per chunk — axios
+         * otherwise flushes the whole body in one socket write and
+         * progress ends up binary (0% → 100%). Timeout defaults to
+         * unbounded; a 10s default kills any transfer bigger than
+         * a handful of megabytes.
+         *
          * PUT /v3/users/{user}/devices/{device}/files/{path}
          */
-        async writeFile(filePath, content, overwrite = true) {
+        async writeFile(filePath, content, overwrite = true, opts = {}) {
             const params = {};
             if (!overwrite) params.overwrite = false;
-            const response = await api.put(`${filesPath}${filePath}`, content, {
-                headers: { 'Content-Type': 'application/octet-stream' },
+            const isBuffer = Buffer.isBuffer(content);
+            // Streams: the caller gets granular `onUploadProgress` events
+            // per socket write. Buffers: axios flushes the whole body in
+            // a single write, so the callback only fires at 0% and 100%
+            // — callers that care about progress should pass a stream.
+            const body = isBuffer
+                ? Readable.from(content, { highWaterMark: BYTES.STREAM_CHUNK })
+                : content;
+            const headers = { 'Content-Type': 'application/octet-stream' };
+            if (isBuffer) {
+                headers['Content-Length'] = String(content.byteLength);
+            } else if (opts.contentLength != null) {
+                headers['Content-Length'] = String(opts.contentLength);
+            }
+            const response = await api.put(`${filesPath}${filePath}`, body, {
+                headers,
                 params,
+                timeout: opts.timeout ?? 0,
+                maxBodyLength: Infinity,
+                maxContentLength: Infinity,
+                // `follow-redirects` (axios' default HTTP client)
+                // buffers the request body in memory to be able to
+                // replay it on a 3xx. That defeats the upstream
+                // backpressure that the CLI's progress meter relies
+                // on — bytes get "sent" to RAM instantly, then the
+                // real socket drain happens out-of-band. The
+                // /v3/…/files/ endpoint doesn't redirect, so opting
+                // out is free and restores true streaming.
+                maxRedirects: 0,
+                onUploadProgress: opts.onProgress,
             });
             return response.data;
         },
 
-        /**
-         * Get file/directory info
-         * GET /v3/users/{user}/devices/{device}/files/{path}?info=true
-         */
+        // GET /v3/users/{user}/devices/{device}/files/{path}?info=true
         async info(filePath) {
             const response = await api.get(`${filesPath}${filePath}`, {
                 params: { info: true },
@@ -80,9 +117,23 @@ export function createDeviceAPI(deviceId, options = {}) {
         },
 
         /**
-         * Delete file or directory
-         * DELETE /v3/users/{user}/devices/{device}/files/{path}
+         * Hash the remote file with the given algorithm.
+         * GET /v3/users/{user}/devices/{device}/resources/$fs/hash/{path}
+         *
+         * Returns `{ path, algorithm, hash, size, mtime }`. Throws axios
+         * errors (404 for missing file, 400 for non-regular path, 403
+         * when the path is outside the agent's allowed base).
          */
+        async hashFile(filePath, algorithm = 'sha256') {
+            const normalized = withLeadingSlash(filePath);
+            const response = await api.get(`${resourcePath}/$fs/hash${normalized}`, {
+                params: algorithm && algorithm !== 'sha256' ? { algorithm } : {},
+                timeout: TIMEOUTS.DEVICE_RESOURCE_CALL_MS,
+            });
+            return response.data;
+        },
+
+        // DELETE /v3/users/{user}/devices/{device}/files/{path}
         async delete(filePath, recursive = true) {
             const params = {};
             if (recursive) params.recursive = true;
@@ -90,10 +141,7 @@ export function createDeviceAPI(deviceId, options = {}) {
             return response.data;
         },
 
-        /**
-         * Move/rename file or directory
-         * PATCH /v3/users/{user}/devices/{device}/files/{sourcePath}
-         */
+        // PATCH /v3/users/{user}/devices/{device}/files/{sourcePath}
         async move(source, destination, overwrite = false) {
             const response = await api.patch(`${filesPath}${source}`, {
                 path: destination,
@@ -102,43 +150,36 @@ export function createDeviceAPI(deviceId, options = {}) {
             return response.data;
         },
 
-        /**
-         * Create directory
-         * PUT /v3/users/{user}/devices/{device}/files/{path}/
-         */
+        // PUT /v3/users/{user}/devices/{device}/files/{path}/
         async mkdir(dirPath) {
-            const normalized = dirPath.endsWith('/') ? dirPath : dirPath + '/';
+            const normalized = withTrailingSlash(dirPath);
             const response = await api.put(`${filesPath}${normalized}`, null, {
                 headers: { 'Content-Length': '0' },
             });
             return response.data;
         },
 
-        /**
-         * Read a device resource property (GET)
-         * GET /v3/users/{user}/devices/{device}/resources/{resource}
-         */
+        // GET /v3/users/{user}/devices/{device}/resources/{resource}
         async getResource(resource) {
             const url = `${resourcePath}/${resource}`;
-            const response = await api.get(url, { timeout: 15000 });
+            const response = await api.get(url, { timeout: TIMEOUTS.DEVICE_RESOURCE_GET_MS });
             return response.data;
         },
 
-        /**
-         * Call a device resource action (POST)
-         * POST /v3/users/{user}/devices/{device}/resources/{resource}
-         */
-        async callResource(resource, payload = null, { timeout = 30000 } = {}) {
+        // POST /v3/users/{user}/devices/{device}/resources/{resource}
+        async callResource(
+            resource,
+            payload = null,
+            { timeout = TIMEOUTS.DEVICE_RESOURCE_CALL_MS } = {},
+        ) {
             const url = `${resourcePath}/${resource}`;
             const response = await api.post(url, payload, { timeout });
             return response.data;
         },
 
-        /**
-         * Execute a command on the device
-         * POST /v3/users/{user}/devices/{device}/resources/cmd
-         */
-        async exec(cmd, timeout = 30) {
+        // Legacy one-shot exec via POST /resources/cmd. Prefer execStream
+        // for anything interactive or longer than a few seconds.
+        async exec(cmd, timeout = TIMEOUTS.DEFAULT_EXEC_SECONDS) {
             const response = await callResource(
                 'cmd',
                 {
@@ -146,7 +187,7 @@ export function createDeviceAPI(deviceId, options = {}) {
                     timeout,
                     mode: 'api',
                 },
-                { timeout: (timeout + 5) * 1000 },
+                { timeout: timeout * 1000 + TIMEOUTS.EXEC_EXTRA_GRACE_MS },
             );
             return response.data;
         },
@@ -154,104 +195,46 @@ export function createDeviceAPI(deviceId, options = {}) {
         /**
          * Execute a command on the device using the WebSocket stream. Incoming
          * frames are dispatched to onStdout/onStderr as they arrive. Resolves
-         * with { exitCode, timedOut } when the remote command completes or the
-         * connection closes. Returns a `cancel()` function via the optional
-         * onCancel hook so callers (e.g. SIGINT handlers) can tear it down.
+         * with { exitCode, timedOut, cancelled } when the remote command
+         * completes, the connection closes, the safety timer fires, or the
+         * caller invokes the `cancel()` function exposed via onCancel.
          *
          * Preferred path for the CLI: the server detects WS close and stops
-         * the device-side stream automatically.
+         * the device-side stream automatically. Framing, timeout and
+         * cancellation live in `CommandStream` (lib/command-stream.js).
+         *
+         * Auth: the WS handshake has no refresh-on-401 interceptor like
+         * HTTP calls do, so the token is refreshed up front when its JWT
+         * is already expired, and a handshake 401 gets one explicit
+         * refresh-and-retry.
          */
-        execStream(cmd, { timeout = 0, onStdout, onStderr, onCancel, stdin } = {}) {
-            const sessionId = randomUUID();
-            const resource = `$cmd/${sessionId}`;
-            const params = new URLSearchParams({ cmd });
-            if (timeout > 0) params.set('timeout', String(timeout));
+        async execStream(cmd, { timeout = 0, onStdout, onStderr, onCancel, stdin } = {}) {
             const isLocal = config.server === 'localhost' || config.server === '127.0.0.1';
             const insecure = isLocal || process.env.THINR_INSECURE === '1';
-            const wsUrl = `wss://${config.server}/v3/users/${apiUser}/devices/${deviceId}/resources/${resource}?${params}`;
-            const ws = new WebSocket(wsUrl, {
-                headers: { Authorization: `Bearer ${config.token}` },
-                rejectUnauthorized: !insecure,
-            });
-
-            let exitCode = null;
-            let timedOut = false;
-            let cancelled = false;
-
-            const cancel = () => {
-                cancelled = true;
-                if (ws.readyState === WebSocket.OPEN || ws.readyState === WebSocket.CONNECTING) {
-                    ws.close();
-                }
-            };
-            onCancel?.(cancel);
-
-            const decodeBytes = (field) => {
-                if (typeof field === 'string') return field;
-                if (field && Array.isArray(field.bytes)) {
-                    return Buffer.from(field.bytes).toString('utf8');
-                }
-                return '';
-            };
-
-            return new Promise((resolve, reject) => {
-                let resolved = false;
-                const done = () => {
-                    if (resolved) return;
-                    resolved = true;
-                    resolve({ exitCode, timedOut, cancelled });
-                    // Tear down the socket without blocking on the server's
-                    // close handshake.
-                    if (
-                        ws.readyState === WebSocket.OPEN ||
-                        ws.readyState === WebSocket.CONNECTING
-                    ) {
-                        ws.terminate();
-                    }
-                };
-
-                ws.on('open', () => {
-                    // 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.
-                    if (stdin && typeof stdin.on === 'function') {
-                        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, payload: text }));
-                        });
-                    }
-                });
-                ws.on('error', (err) => {
-                    if (cancelled) return;
-                    reject(err);
-                });
-                ws.on('message', (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) onStdout?.(decodeBytes(p.out));
-                    else if (p.err !== undefined) onStderr?.(decodeBytes(p.err));
-                    else if (typeof p.exit === 'number') {
-                        exitCode = p.exit;
-                        if (p.timeout === true) 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.
-                        done();
-                    }
-                });
-                ws.on('close', () => done());
-            });
+            const run = (token) =>
+                new CommandStream({
+                    server: config.server,
+                    token,
+                    apiUser,
+                    deviceId,
+                    insecure,
+                    cmd,
+                    timeout,
+                    onStdout,
+                    onStderr,
+                    onCancel,
+                    stdin,
+                }).run();
+            try {
+                return await run((await ensureFreshToken()) || config.token);
+            } catch (error) {
+                // A token that decodes as still-valid can be rejected
+                // anyway (revoked, clock skew): mirror the api.js
+                // interceptor and retry the handshake once after an
+                // explicit refresh.
+                if (error?.statusCode !== 401) throw error;
+                return run(await refreshToken());
+            }
         },
     };
 }

package/lib/devices.js

@@ -2,11 +2,6 @@ import { requireConfig } from './config.js';
 import api from './api.js';
 import { apiError } from './errors.js';
 
-/**
- * Get devices belonging to a product
- * @param {Object} filter - Filters to query devices
- * @return {Promise<Array>} List of devices
- */
 export async function getDevices(filter, user = null) {
     const config = requireConfig();
     const apiUser = user || config.username;
@@ -32,22 +27,15 @@ export async function getDevices(filter, user = null) {
 
         return devices;
     } catch (error) {
-        const product = filter && filter.productId;
+        const product = filter && filter.product;
         const notFound = product ? `Product not found: ${product}` : 'Devices not found';
         throw apiError(error, { notFound });
     }
 }
 
-/**
- * Fetch a single device record (metadata only — assigned product,
- * description, asset group, connection state, …). Use this when you
- * need the side-channel info that doesn't come from the device's own
- * agent (system_info, monitoring, …) but from the server's record.
- *
- * @param {string} deviceId
- * @param {string} [user]  Admin impersonation; defaults to the active profile.
- * @returns {Promise<Object>} Raw API record.
- */
+// Server-side metadata (assigned product, description, asset group,
+// connection state…). For device-side data — system_info, monitoring —
+// hit the agent resources directly instead.
 export async function getDevice(deviceId, user = null) {
     const config = requireConfig();
     const apiUser = user || config.username;
@@ -59,11 +47,20 @@ export async function getDevice(deviceId, user = null) {
     }
 }
 
-/**
- * Filter active devices from a list of devices
- * @param {Array} devices - List of devices to filter
- * @return {Array} List of active devices
- */
+// Idempotent: returns true if the device record was removed, false if it
+// was already absent. Other failures (auth, network) propagate as apiError.
+export async function deleteDevice(deviceId, user = null) {
+    const config = requireConfig();
+    const apiUser = user || config.username;
+    try {
+        await api.delete(`/v1/users/${apiUser}/devices/${deviceId}`);
+        return true;
+    } catch (error) {
+        if (error.response?.status === 404) return false;
+        throw apiError(error);
+    }
+}
+
 export function filterActiveDevices(devices) {
     return devices.filter((device) => device.connection && device.connection.active === true);
 }

package/lib/errors.js

@@ -7,6 +7,18 @@
  * that names the missing entity (e.g. "Device not found: abc").
  */
 export function apiError(error, messages = {}) {
+    // Errors normalized upstream (the tagged 'unauthorized' from a failed
+    // token refresh, inputError, ...) carry a stable string code and no
+    // axios envelope: pass them through so the code survives.
+    if (
+        error &&
+        typeof error.code === 'string' &&
+        !error.isAxiosError &&
+        !error.response &&
+        !error.request
+    ) {
+        return error;
+    }
     if (error && error.response) {
         const status = error.response.status;
         if (status === 404) {