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

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,39 @@
 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 { 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 +41,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 +116,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 +140,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 +149,32 @@ 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 +182,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 +190,30 @@ 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).
          */
         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));
             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());
-            });
+            return new CommandStream({
+                server: config.server,
+                token: config.token,
+                apiUser,
+                deviceId,
+                insecure,
+                cmd,
+                timeout,
+                onStdout,
+                onStderr,
+                onCancel,
+                stdin,
+            }).run();
         },
     };
 }

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/fleet-upgrade.js

@@ -0,0 +1,106 @@
+import { createDeviceAPI } from './device-api.js';
+import { TIMEOUTS } from './constants.js';
+
+/**
+ * Roll a fleet-wide agent upgrade. Strategy:
+ *   1. If `canary` is set and there's more than one device, upgrade one
+ *      device in isolation first. A canary failure always aborts — the
+ *      point of the canary is to catch arch / channel / connectivity
+ *      mistakes before we touch the rest.
+ *   2. The remainder is upgraded in parallel batches of `batchSize`. If
+ *      `abortOnFailure` is set, any failure inside a batch stops the run
+ *      after that batch completes (we never leave requests dangling).
+ *   3. Results come back as { ok, failed, aborted } plus the per-device
+ *      records. Progress is reported through `onProgress` so the UI can
+ *      show `updating N/M…` live.
+ *
+ * We intentionally treat any HTTP rejection as a failure and any resolved
+ * call as success. The agent's `update` resource doesn't expose a stable
+ * machine-readable status across every "nothing to do" case, so finer
+ * classification would be fragile here — a resolved call means the agent
+ * accepted the request; whether it then swapped binaries is visible in
+ * the next sample's version field.
+ */
+export async function runFleetUpgrade({
+    deviceIds,
+    channel = 'latest',
+    user,
+    canary = true,
+    abortOnFailure = true,
+    batchSize = 5,
+    onProgress,
+    onDeviceResult,
+    signal,
+}) {
+    const queue = [...deviceIds];
+    const total = queue.length;
+    const results = [];
+    let done = 0;
+
+    const emitProgress = (phase) => {
+        onProgress?.({ done, total, phase });
+    };
+
+    async function upgradeOne(id) {
+        if (signal?.aborted) {
+            const r = { deviceId: id, ok: false, error: 'cancelled' };
+            results.push(r);
+            onDeviceResult?.(r);
+            return r;
+        }
+        let r;
+        try {
+            const api = createDeviceAPI(id, user ? { user } : {});
+            const result = await api.callResource(
+                'update',
+                { action: 'apply', channel },
+                { timeout: TIMEOUTS.DEVICE_UPDATE_APPLY_MS },
+            );
+            r = { deviceId: id, ok: true, result };
+        } catch (e) {
+            r = {
+                deviceId: id,
+                ok: false,
+                error: e?.message || String(e),
+            };
+        }
+        results.push(r);
+        done += 1;
+        onDeviceResult?.(r);
+        emitProgress('running');
+        return r;
+    }
+
+    emitProgress('running');
+
+    // Canary first — a single device, synchronously. Treat failure as
+    // terminal regardless of `abortOnFailure`: if the canary fails we have
+    // no signal that a wider rollout would succeed, and blindly firing at
+    // 95 more devices would only amplify whatever went wrong.
+    if (canary && queue.length > 1) {
+        const canaryId = queue.shift();
+        const r = await upgradeOne(canaryId);
+        if (!r.ok) {
+            return { results, aborted: true, reason: 'canary-failed' };
+        }
+    }
+
+    while (queue.length > 0) {
+        if (signal?.aborted) {
+            return { results, aborted: true, reason: 'cancelled' };
+        }
+        const batch = queue.splice(0, batchSize);
+        const batchResults = await Promise.all(batch.map(upgradeOne));
+        if (abortOnFailure && batchResults.some((r) => !r.ok)) {
+            return { results, aborted: true, reason: 'batch-failed' };
+        }
+    }
+
+    return { results, aborted: false };
+}
+
+export function summarize(results) {
+    const ok = results.filter((r) => r.ok).length;
+    const failed = results.length - ok;
+    return { ok, failed, total: results.length };
+}