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

package/commands/_shared.js

@@ -0,0 +1,154 @@
+// @ts-check
+import { InvalidArgumentError } from 'commander';
+import { configExists } from '../lib/config.js';
+import {
+    setJsonMode,
+    isJsonMode,
+    printOk,
+    printErr,
+    createSpinner,
+    classifyError,
+} from '../lib/output.js';
+
+export function ensureConfigured() {
+    if (!configExists()) {
+        printErr('Not configured. Run thinr without parameters to set up.', {
+            code: 'not_configured',
+        });
+    }
+}
+
+export function applyJsonFlag(opts) {
+    if (opts.json) setJsonMode(true);
+}
+
+// Walks up to the root program so subcommands can read `--user` regardless
+// of nesting depth.
+export function getGlobalUser(cmd) {
+    let root = cmd;
+    while (root.parent) root = root.parent;
+    return root.opts().user || null;
+}
+
+export function parsePositiveInt(label) {
+    return (value) => {
+        const n = Number(value);
+        if (!Number.isInteger(n) || n <= 0) {
+            throw new InvalidArgumentError(`${label} must be a positive integer`);
+        }
+        return n;
+    };
+}
+
+// Collect repeatable `-i key=value` / `-v key=value` pairs into a single
+// object. Uses Commander's InvalidArgumentError so a bad value prints a
+// clean "error: option … argument is invalid" line instead of a stack trace.
+export function collectKeyValue(value, previous = {}) {
+    const idx = value.indexOf('=');
+    if (idx === -1) throw new InvalidArgumentError('must be key=value');
+    return { ...previous, [value.slice(0, idx)]: value.slice(idx + 1) };
+}
+
+// Historical aliases kept so existing subcommands don't need renaming at
+// the call sites. Same function, different names where it reads better.
+export const collectInput = collectKeyValue;
+export const collectVar = collectKeyValue;
+
+// Resolve a dot-path against a nested object. Returns `undefined` as soon
+// as any intermediate hop is missing — matching the previous inline
+// `reduce((o, k) => o && o[k], obj)` behaviour across the CLI.
+export function extractField(obj, path) {
+    if (!path) return obj;
+    return path.split('.').reduce((o, k) => (o == null ? o : o[k]), obj);
+}
+
+/**
+ * Live counter for fan-out spinners. Wraps an ora spinner and rewrites
+ * its text as work enters/leaves the pool and completes. Use it to avoid
+ * reimplementing the `done/in flight` bookkeeping in every fan-out
+ * command (product exec, product fs, product push, playbook run…).
+ *
+ *   const progress = new ProgressSpinner(spinner, devices.length,
+ *       ({ done, total, inFlight }) =>
+ *           `Running on ${total} devices — ${done}/${total} done · ${inFlight} in flight`);
+ *   progress.render();
+ *   // inside worker:
+ *   progress.startItem();
+ *   // …
+ *   progress.finishItem();
+ */
+export class ProgressSpinner {
+    constructor(spinner, total, formatText) {
+        this.spinner = spinner;
+        this.total = total;
+        this.formatText = formatText;
+        this.done = 0;
+        this.inFlight = 0;
+    }
+
+    render() {
+        this.spinner.text = this.formatText({
+            done: this.done,
+            total: this.total,
+            inFlight: this.inFlight,
+        });
+    }
+
+    startItem() {
+        this.inFlight++;
+        this.render();
+    }
+
+    finishItem() {
+        this.inFlight--;
+        this.done++;
+        this.render();
+    }
+
+    stop() {
+        this.spinner.stop();
+    }
+}
+
+/**
+ * One-shot command skeleton shared by read-only device subcommands
+ * (status, list, property, resource…). Handles the spinner start,
+ * try/catch, `classifyError`+`printErr` on failure, and the
+ * `isJsonMode() ? printOk : console.log` default for the success path.
+ *
+ * Shape:
+ *   await runDeviceCommand({
+ *       start: 'Fetching devices…',          // spinner label
+ *       fn: () => getDevices(filter),        // async unit of work
+ *       success: n => `Found ${n} device(s)`,// string | (result) => string | null
+ *       failure: 'Failed to list devices',   // string on failure
+ *       onSuccess: (result) => { … },        // optional full render override
+ *   });
+ *
+ * When `success` is `null` the spinner just stops (no checkmark), which
+ * matches the idiom used by commands whose output block already speaks
+ * for the "found" state. When `onSuccess` is omitted the result is
+ * printed verbatim (`printOk` in JSON mode, `console.log` otherwise).
+ */
+export async function runDeviceCommand({ start, fn, success, failure, onSuccess }) {
+    const spinner = createSpinner(start).start();
+    try {
+        const result = await fn();
+        if (success === null) {
+            spinner.stop();
+        } else {
+            spinner.succeed(typeof success === 'function' ? success(result) : success);
+        }
+        if (onSuccess) {
+            await onSuccess(result);
+        } else if (isJsonMode()) {
+            printOk(result);
+        } else {
+            console.log(result);
+        }
+    } catch (error) {
+        spinner.fail(typeof failure === 'function' ? failure(error) : failure);
+        const { message, code } = classifyError(error);
+        printErr(message, { code });
+    }
+}

package/commands/dashboard.js

@@ -0,0 +1,17 @@
+// @ts-check
+import { ensureConfigured } from './device/_shared.js';
+
+export async function runDashboard() {
+    ensureConfigured();
+    // React's package entry switches between react.development.js and
+    // react.production.js based on NODE_ENV at first load. The dev
+    // build has a known leak under frequent setState (facebook/react
+    // #34770) — heap grows from ~100MB to >1GB in minutes when WS
+    // events drive the UI. Force production unless the user has
+    // explicitly asked for the dev build (e.g. while debugging).
+    // Set BEFORE the dynamic import so the bundle resolves React with
+    // the correct env baked in.
+    if (!process.env.NODE_ENV) process.env.NODE_ENV = 'production';
+    const { run } = await import('../dist/dashboard.js');
+    await run();
+}

package/commands/device/_shared.js

@@ -1,48 +1,31 @@
 // @ts-check
-import chalk from 'chalk';
-import { InvalidArgumentError } from 'commander';
-import { configExists } from '../../lib/config.js';
-import { setJsonMode, classifyError, printErr } from '../../lib/output.js';
+import { classifyError } from '../../lib/output.js';
+import { error as errorStyle } from '../../lib/format.js';
 
-export function ensureConfigured() {
-    if (!configExists()) {
-        printErr('Not configured. Run thinr without parameters to set up.', {
-            code: 'not_configured',
-        });
-    }
-}
-
-export function applyJsonFlag(opts) {
-    if (opts.json) setJsonMode(true);
-}
-
-// Walks up to the root program so subcommands can read `--user` regardless
-// of nesting depth.
-export function getGlobalUser(cmd) {
-    let root = cmd;
-    while (root.parent) root = root.parent;
-    return root.opts().user || null;
-}
-
-// Collect repeatable `-i key=value` pairs into a single object. Uses
-// Commander's InvalidArgumentError so a bad value prints a clean
-// "error: option … argument is invalid" line instead of a stack trace.
-export function collectInput(value, previous = {}) {
-    const idx = value.indexOf('=');
-    if (idx === -1) throw new InvalidArgumentError('must be key=value');
-    return { ...previous, [value.slice(0, idx)]: value.slice(idx + 1) };
-}
+export {
+    ensureConfigured,
+    applyJsonFlag,
+    getGlobalUser,
+    parsePositiveInt,
+    collectKeyValue,
+    collectInput,
+    collectVar,
+    extractField,
+    ProgressSpinner,
+    runDeviceCommand,
+} from '../_shared.js';
 
 // Wrapper for the proxy / console handlers, which return a Promise that
 // resolves with an exit code or rejects with a tagged Error (instead of
-// calling process.exit themselves).
+// calling process.exit themselves). Kept local to `device/` because only
+// the interactive device subcommands use it.
 export const runInteractive = async (fn) => {
     try {
         const exitCode = await fn();
         process.exit(exitCode ?? 0);
     } catch (error) {
         const { message, code } = classifyError(error);
-        console.error(chalk.red(`Error [${code}]: ${message}`));
+        console.error(errorStyle(`Error [${code}]: ${message}`));
         process.exit(1);
     }
 };

package/commands/device/console.js

@@ -5,6 +5,7 @@ import { ensureConfigured, runInteractive } from './_shared.js';
 export function registerConsoleCommand(device) {
     device
         .command('console <deviceId>')
+        .helpGroup('Remote access:')
         .description('Open an interactive terminal on the device')
         .action((deviceId) =>
             runInteractive(() => {

package/commands/device/delete.js

@@ -0,0 +1,53 @@
+// @ts-check
+import { confirm } from '@inquirer/prompts';
+import { deleteDevice } from '../../lib/devices.js';
+import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { hint, info } from '../../lib/format.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+
+export function registerDeleteCommand(device) {
+    device
+        .command('delete <deviceId>')
+        .helpGroup('State & resources:')
+        .description('Delete a device record from the platform (irreversible)')
+        .option('-y, --yes', 'Skip the interactive confirmation prompt')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+
+            if (!opts.yes && !isJsonMode()) {
+                if (!process.stdin.isTTY) {
+                    printErr('Refusing to delete without --yes in a non-interactive shell', {
+                        code: 'needs_confirm',
+                    });
+                    return;
+                }
+                const ok = await confirm({
+                    message: `Delete device ${deviceId}? This cannot be undone.`,
+                    default: false,
+                });
+                if (!ok) {
+                    console.log(hint('Cancelled.'));
+                    return;
+                }
+            }
+
+            try {
+                const removed = await deleteDevice(deviceId, user);
+                if (isJsonMode()) {
+                    printOk({ device: deviceId, removed });
+                    return;
+                }
+                console.log(
+                    removed
+                        ? `Deleted ${info(deviceId)}`
+                        : `Device ${info(deviceId)} did not exist`,
+                );
+            } catch (error) {
+                const { message, code } = classifyError(error);
+                printErr(message, { code });
+            }
+        });
+}

package/commands/device/exec.js

@@ -1,12 +1,13 @@
 // @ts-check
-import chalk from 'chalk';
 import { createDeviceAPI } from '../../lib/device-api.js';
 import { isJsonMode, printOk, printErr, classifyError } from '../../lib/output.js';
+import { error as errorStyle, warning } from '../../lib/format.js';
 import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
 
 export function registerExecCommand(device) {
     device
         .command('exec <deviceId> <command...>')
+        .helpGroup('Execution:')
         .description('Execute a shell command on the device')
         .option('-j, --json', 'Buffer stdout/stderr and emit a single JSON envelope')
         .option('--legacy', 'Use the non-streaming one-shot API (older agents)')
@@ -52,10 +53,10 @@ export function registerExecCommand(device) {
                 });
                 process.off('SIGINT', onSigint);
                 if (timedOut) {
-                    console.error(chalk.red('\nError: command timed out on the device.'));
+                    console.error(errorStyle('\nError: command timed out on the device.'));
                 }
                 if (cancelled) {
-                    console.error(chalk.yellow('\n[interrupted]'));
+                    console.error(warning('\n[interrupted]'));
                     process.exit(130);
                 }
                 process.exit(exitCode ?? 1);
@@ -65,10 +66,10 @@ export function registerExecCommand(device) {
                 // Human path: prefix `[code]` matches the MCP error format
                 // and the rest of the CLI; the response dump only surfaces
                 // when the failure carries an HTTP body.
-                console.error(chalk.red(`Error [${code}]: ${message}`));
+                console.error(errorStyle(`Error [${code}]: ${message}`));
                 if (error.response) {
-                    console.error(chalk.red(`Status: ${error.response.status}`));
-                    console.error(chalk.red(`Body: ${JSON.stringify(error.response.data)}`));
+                    console.error(errorStyle(`Status: ${error.response.status}`));
+                    console.error(errorStyle(`Body: ${JSON.stringify(error.response.data)}`));
                 }
                 process.exit(1);
             }

package/commands/device/fs.js

@@ -0,0 +1,193 @@
+// @ts-check
+import { createDeviceAPI } from '../../lib/device-api.js';
+import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
+import { success, hint, muted, label } from '../../lib/format.js';
+import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+
+/**
+ * Plain filesystem operations on a single device, mirroring the
+ * MCP filesystem tools with CLI-native verbs. Two semantic families:
+ *   · read / write — inline content (strings, small files)
+ *   · push / pull  — file transfer with progress (in transfer.js)
+ * Plus ls, mkdir, rm, mv for directory housekeeping.
+ */
+export function registerFsCommands(device) {
+    device
+        .command('ls <deviceId> [path]')
+        .helpGroup('Filesystem:')
+        .description('List a directory on the device')
+        .option('-j, --json', 'Output as JSON')
+        .option('-a, --all', 'Include hidden entries (dotfiles)')
+        .action(async (deviceId, path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const target = path || '/';
+            const spinner = createSpinner(`Listing ${deviceId}:${target}...`).start();
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const entries = await api.listDir(target, !!opts.all);
+                spinner.succeed(`${deviceId}:${target} (${entries.length} entries)`);
+                if (isJsonMode()) {
+                    printOk(entries);
+                    return;
+                }
+                for (const e of entries) {
+                    const kind = e.type === 'directory' ? label('d') : muted('-');
+                    const mode = e.mode || 'rwxr-xr-x';
+                    const size = (e.size || 0).toString().padStart(10);
+                    console.log(`  ${kind}${mode}  ${hint(size)}  ${e.name}`);
+                }
+            } catch (err) {
+                spinner.fail('List failed');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('read <deviceId> <path>')
+        .alias('cat')
+        .helpGroup('Filesystem:')
+        .description('Print the contents of a remote file to stdout')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                const buf = await api.readFile(path);
+                const text = buf.toString('utf8');
+                if (isJsonMode()) {
+                    printOk({ device: deviceId, path, bytes: buf.byteLength, content: text });
+                    return;
+                }
+                process.stdout.write(text);
+                if (text && !text.endsWith('\n')) process.stdout.write('\n');
+            } catch (err) {
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('write <deviceId> <path> [content]')
+        .helpGroup('Filesystem:')
+        .description(
+            'Write inline content to a remote file (use `push` for large local files). Reads from stdin when <content> is omitted.',
+        )
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, path, content, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const spinner = createSpinner(`Writing ${deviceId}:${path}...`).start();
+            try {
+                let payload;
+                if (typeof content === 'string') {
+                    payload = Buffer.from(content, 'utf8');
+                } else if (!process.stdin.isTTY) {
+                    payload = await readAllStdin();
+                } else {
+                    spinner.stop();
+                    printErr(
+                        'No content given. Pass it as the third argument or pipe it on stdin.',
+                        { code: 'input_error' },
+                    );
+                    return;
+                }
+                const api = createDeviceAPI(deviceId, { user });
+                await api.writeFile(path, payload);
+                spinner.succeed(success(`Wrote ${payload.byteLength} bytes to ${deviceId}:${path}`));
+                if (isJsonMode()) {
+                    printOk({ device: deviceId, path, bytes: payload.byteLength });
+                }
+            } catch (err) {
+                spinner.fail('write failed');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('mkdir <deviceId> <path>')
+        .helpGroup('Filesystem:')
+        .description('Create a directory on the device')
+        .option('-j, --json', 'Output as JSON')
+        .action(async (deviceId, path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const spinner = createSpinner(`Creating ${deviceId}:${path}...`).start();
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                await api.mkdir(path);
+                spinner.succeed(success(`Created ${deviceId}:${path}`));
+                if (isJsonMode()) printOk({ device: deviceId, path });
+            } catch (err) {
+                spinner.fail('mkdir failed');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('rm <deviceId> <path>')
+        .helpGroup('Filesystem:')
+        .description(
+            'Delete a file or directory on the device (pass --recursive for directories with contents)',
+        )
+        .option('-j, --json', 'Output as JSON')
+        .option('-r, --recursive', 'Recursively delete non-empty directories (default: true)', true)
+        .option('--no-recursive', 'Fail on non-empty directories')
+        .action(async (deviceId, path, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const spinner = createSpinner(`Deleting ${deviceId}:${path}...`).start();
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                await api.delete(path, opts.recursive !== false);
+                spinner.succeed(success(`Deleted ${deviceId}:${path}`));
+                if (isJsonMode()) printOk({ device: deviceId, path });
+            } catch (err) {
+                spinner.fail('rm failed');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+
+    device
+        .command('mv <deviceId> <source> <destination>')
+        .helpGroup('Filesystem:')
+        .description('Move or rename a file or directory on the device')
+        .option('-j, --json', 'Output as JSON')
+        .option('-f, --force', 'Overwrite destination if it already exists')
+        .action(async (deviceId, source, destination, opts, cmd) => {
+            applyJsonFlag(opts);
+            ensureConfigured();
+            const user = getGlobalUser(cmd);
+            const spinner = createSpinner(
+                `Moving ${deviceId}:${source} → ${destination}...`,
+            ).start();
+            try {
+                const api = createDeviceAPI(deviceId, { user });
+                await api.move(source, destination, !!opts.force);
+                spinner.succeed(success(`Moved ${deviceId}:${source} → ${destination}`));
+                if (isJsonMode()) printOk({ device: deviceId, source, destination });
+            } catch (err) {
+                spinner.fail('mv failed');
+                const { message, code } = classifyError(err);
+                printErr(message, { code });
+            }
+        });
+}
+
+async function readAllStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    }
+    return Buffer.concat(chunks);
+}

package/commands/device/index.js

@@ -7,6 +7,10 @@ import { registerPropertyCommand } from './property.js';
 import { registerResourceCommand } from './resource.js';
 import { registerExecCommand } from './exec.js';
 import { registerUpdateCommand } from './update.js';
+import { registerTransferCommands } from './transfer.js';
+import { registerFsCommands } from './fs.js';
+import { registerLogsCommand } from './logs.js';
+import { registerDeleteCommand } from './delete.js';
 
 /**
  * `thinr device <subcommand> [<deviceId>] …` — all device-scoped actions
@@ -18,6 +22,7 @@ import { registerUpdateCommand } from './update.js';
 export function deviceCommand(program) {
     const device = program
         .command('device')
+        .helpGroup('Operations:')
         .description('Device commands (subcommand-first: thinr device <action> <deviceId>)');
 
     registerListCommand(device);
@@ -28,4 +33,8 @@ export function deviceCommand(program) {
     registerResourceCommand(device);
     registerExecCommand(device);
     registerUpdateCommand(device);
+    registerTransferCommands(device);
+    registerFsCommands(device);
+    registerLogsCommand(device);
+    registerDeleteCommand(device);
 }

package/commands/device/list.js

@@ -1,12 +1,18 @@
 // @ts-check
-import chalk from 'chalk';
 import { getDevices } from '../../lib/devices.js';
-import { isJsonMode, printOk, printErr, createSpinner, classifyError } from '../../lib/output.js';
-import { applyJsonFlag, ensureConfigured, getGlobalUser } from './_shared.js';
+import { isJsonMode, printOk } from '../../lib/output.js';
+import { success, hint, label } from '../../lib/format.js';
+import {
+    applyJsonFlag,
+    ensureConfigured,
+    getGlobalUser,
+    runDeviceCommand,
+} from './_shared.js';
 
 export function registerListCommand(device) {
     device
         .command('list [pattern]')
+        .helpGroup('Discovery:')
         .description(
             'List devices, optionally filtered by name/id pattern (case-insensitive regex)',
         )
@@ -16,28 +22,34 @@ export function registerListCommand(device) {
             ensureConfigured();
             const user = getGlobalUser(cmd);
             const filter = pattern ? { name: pattern } : {};
-            const label = pattern
-                ? `Searching devices matching "${pattern}"...`
-                : 'Fetching devices...';
-            const spinner = createSpinner(label).start();
-            try {
-                const devices = await getDevices(filter, user);
-                spinner.succeed(`Found ${devices.length} device(s)`);
-                if (isJsonMode()) {
-                    printOk(devices);
-                } else {
+            await runDeviceCommand({
+                start: pattern
+                    ? `Searching devices matching "${pattern}"...`
+                    : 'Fetching devices...',
+                fn: () => getDevices(filter, user),
+                success: (devices) => `Found ${devices.length} device(s)`,
+                failure: 'Failed to list devices',
+                onSuccess: (devices) => {
+                    if (isJsonMode()) {
+                        printOk(devices);
+                        return;
+                    }
+                    // Pad the device id column so trailing names line up
+                    // even when ids have very different widths — same
+                    // treatment as thinr product list.
+                    const idWidth = devices.reduce(
+                        (w, d) => Math.max(w, d.device.length),
+                        0,
+                    );
                     for (const d of devices) {
                         const online = d.connection?.active
-                            ? chalk.green('online ')
-                            : chalk.gray('offline');
-                        const name = d.name ? chalk.gray(` (${d.name})`) : '';
-                        console.log(`  ${online}  ${chalk.bold(d.device)}${name}`);
+                            ? success('online ')
+                            : hint('offline');
+                        const name = d.name ? hint(`(${d.name})`) : '';
+                        const id = label(d.device.padEnd(idWidth));
+                        console.log(`  ${online}  ${id}${name ? '  ' + name : ''}`);
                     }
-                }
-            } catch (error) {
-                spinner.fail('Failed to list devices');
-                const { message, code } = classifyError(error);
-                printErr(message, { code });
-            }
+                },
+            });
         });
 }