@thinremote/thinr-cli 1.1.0 → 1.2.0

package/CHANGELOG.md

@@ -1,5 +1,75 @@
 # Changelog
 
+## [1.2.0] - 2026-06-10
+
+### Added
+
+- `thinr` with no arguments now launches the interactive dashboard
+  directly when stdout is a TTY (and a configuration exists), so the
+  fleet view is one keystroke away. Non-TTY contexts (pipes, scripts)
+  fall back to `--help`. First-time users still get the auth flow,
+  then drop straight into the dashboard.
+- TUI dashboard: alarms panel on the overview tab, with rule- and
+  instance-level views, severity colouring and live updates over the
+  same event stream the rest of the dashboard already uses.
+- `thinr device delete <deviceId>` — remove a device record from the
+  platform. Interactive `confirm` by default, `--yes` to skip in
+  scripts, idempotent on a missing device. Useful after re-provisioning
+  an agent under a new hostname leaves the old `ip-…` record offline.
+- MCP: `thinr_device_delete` — same operation for AI clients.
+- MCP: `thinr_push` and `thinr_pull` — upload a local file to a
+  device and download a remote file to local disk, respectively.
+  Rounds out filesystem parity with the CLI so an agent can move
+  binary or large payloads that don't fit inline in `thinr_write`.
+- MCP: alarms tools (`thinr_alarm_instances`,
+  `thinr_alarm_instance_get`, `thinr_alarm_instance_stats`,
+  `thinr_alarm_instance_update`, `thinr_alarm_instance_delete`,
+  `thinr_alarm_rules`, `thinr_alarm_rule_read`, `thinr_alarm_rule_write`,
+  `thinr_alarm_rule_delete`) — list, inspect and manage alarm
+  instances and rules from AI clients, with state/severity parsing
+  shared with the dashboard.
+- MCP: product profile config tools (buckets, properties, API
+  resources) and access-token tools (user-level and device-level).
+- `thinr product exec <productId> <command...>` — run a shell command
+  in parallel on every active device of a product, with bounded
+  concurrency (`-c, --concurrency`, default 10), per-device timeout
+  (`--timeout`, default 30 s), `--fail-fast`, asset-group filter
+  (`-g, --group`) and an `-a, --all` switch to include offline
+  devices. Live progress shows a single spinner with done/total
+  counters; the final render uses a `cli-table3` table per device
+  plus a compact `Output:` section and a one-line totals bar.
+- `thinr_product_exec` MCP tool — the same fan-out as the CLI
+  subcommand, returning a consolidated text report so an AI agent
+  can roll out a change across a whole fleet in a single call
+  instead of looping `thinr_exec` per device.
+- `lib/concurrency.js#runPool` — tiny helper used by both entry
+  points; keeps at most N workers in flight and returns a parallel
+  results array. `runPool` plus an internal try/catch in each worker
+  keeps fleet-wide errors localised per device.
+
+### Changed
+
+- Unified filesystem verbs across CLI, MCP and playbooks so the same
+  eight nouns mean the same thing everywhere: `read` / `write`
+  (inline content) · `push` / `pull` (local ↔ remote file transfer)
+  · `ls` · `mkdir` · `rm` · `mv`.
+- CLI: `thinr device cat` is now `thinr device read` (`cat` kept as
+  a hidden alias). New `thinr device write <deviceId> <path>
+  [content]` accepts the payload as an argument or on stdin.
+- MCP: `thinr_delete` renamed to `thinr_rm`, `thinr_move` renamed to
+  `thinr_mv`. No backwards-compatibility aliases.
+- Playbook actions: `delete` → `rm`, `move` → `mv`. The `write`
+  action now only accepts inline `content`; use the new `push`
+  action to upload a local file (`source`, `destination`). New
+  `pull` action downloads a remote file to the local disk.
+- `cli-table3` added as a direct dependency to render the
+  product-exec summary.
+
+### Removed
+
+- `thinr dashboard` subcommand. The dashboard is now the default for
+  bare `thinr`; the explicit subcommand had not shipped to anyone yet.
+
 ## [1.1.0] - 2026-04-16
 
 Major release: MCP server for AI clients, subcommand-first CLI, JSON
@@ -128,6 +198,7 @@ consistent error taxonomy across both interfaces.
 - Property listing and retrieval
 - Device resource listing and execution
 
+[1.2.0]: https://github.com/Thin-Remote/thinr-cli/compare/1.1.0...1.2.0
 [1.1.0]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.2...1.1.0
 [1.0.2]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.1...1.0.2
 [1.0.1]: https://github.com/Thin-Remote/thinr-cli/compare/1.0.0...1.0.1

package/README.md

@@ -30,11 +30,13 @@ task at hand.
     - [JSON output](#json-output)
     - [`thinr device <action> [<deviceId>]`](#thinr-device-action-deviceid)
     - [`thinr product <action> <productId>`](#thinr-product-action-productid)
+    - [`thinr playbook <action>`](#thinr-playbook-action)
     - [`thinr profile`](#thinr-profile)
     - [`thinr logout`](#thinr-logout)
 - [Part 2 — MCP server](#part-2--mcp-server)
     - [Starting the server](#starting-the-server)
     - [Tool catalog](#tool-catalog)
+    - [Authoring playbooks from natural language](#authoring-playbooks-from-natural-language)
     - [Per-call controls](#per-call-controls)
     - [Integrating with Claude Code](#integrating-with-claude-code)
 - [Profiles and multi-account use](#profiles-and-multi-account-use)
@@ -299,6 +301,107 @@ Options:
 Offline devices are skipped for `resource` — the server would reject
 the call anyway.
 
+#### `exec`
+
+Run a shell command in parallel across every active device of the
+product and report a per-device status table plus each device's
+output:
+
+```bash
+thinr product exec <productId> <command...> [options]
+```
+
+Options:
+
+- `-j, --json`: Output as JSON. Emits a single envelope with a
+  `summary` block and a `results[]` array carrying stdout, stderr,
+  exit code, `timedOut` flag and per-device duration.
+- `-c, --concurrency <n>`: Max parallel executions (default: 10)
+- `--timeout <seconds>`: Per-device timeout (default: 30)
+- `--fail-fast`: Stop dequeueing new devices as soon as one fails
+- `-g, --group <group>`: Filter devices by asset group
+- `-a, --all`: Include offline devices (default: only active)
+
+Examples:
+
+```bash
+# hostname on every active device
+thinr product exec my-product hostname
+
+# apt upgrade across the fleet with 5 parallel slots and a long timeout
+thinr product exec my-product "apt-get -y upgrade" -c 5 --timeout 600
+
+# target only a subset of the product
+thinr product exec my-product "systemctl restart agent" -g staging
+```
+
+Also exposed as an MCP tool (`thinr_product_exec`) with the same
+parameters, so agents can drive a fleet operation with a single call
+instead of looping `thinr_exec` per device.
+
+#### `playbook`
+
+Manage playbooks stored on a product and run them against one device
+or the whole fleet:
+
+```bash
+thinr product playbook list     <productId> [--json]
+thinr product playbook upload   <productId> <name> [file] [--description <text>] [--skip-validation] [--json]
+thinr product playbook download <productId> <name> [-o <file>] [--json]
+thinr product playbook delete   <productId> <name> [--json]
+thinr product playbook run      <productId> <name> (--device <id> | --fleet) [options]
+```
+
+`upload` reads the YAML from a file, or from stdin when the path is
+omitted or `-`. The document is validated against the playbook schema
+before being written to the product storage; an invalid document is
+rejected with a descriptive error and nothing is uploaded. Pass
+`--skip-validation` only to work around a schema-runtime gap (do not
+use it to bypass real errors).
+
+`run` targets either a single device (`--device <id>`) or the whole
+fleet (`--fleet`, progressive batch rollout):
+
+- `-v, --var <key=value>` — override an overridable playbook variable
+  (repeatable; values are coerced to the declared type).
+- `--vars-file <path>` — load variable overrides from a YAML/JSON file.
+- `--dry-run` — print the resolved plan without contacting any device.
+- `--check` — contact devices read-only and report what each step would
+  change.
+- `--yes` / `-y` — skip the interactive confirmation prompt.
+
+Fleet-only options:
+
+- `--batch-size <n>` — devices attempted in parallel per batch
+  (default: 5).
+- `--failure-threshold <p>` — abort rollout when cumulative failure
+  rate reaches P% (default: 25).
+- `-g, --group <id>` — restrict to an asset group.
+- `--filter <key=value>` — extra server-side filter (repeatable).
+- `--include-offline` — attempt offline devices too (default: active
+  only).
+
+Each fleet rollout writes a persistent JSON report to
+`playbooks/runs/<timestamp>-<name>-<user>.json` in the product's file
+storage, capturing resolved variables, per-device outcomes, and any
+abort reason.
+
+### `thinr playbook <action>`
+
+Run or validate a local playbook YAML file (not stored on a product).
+Useful for one-shot or ad-hoc runs:
+
+```bash
+thinr playbook validate <file>
+thinr playbook run      <file> [--dry-run] [--check] [options]
+```
+
+`validate` parses the YAML and reports any schema errors. `run`
+resolves the target block declared inside the playbook and executes
+it; the same variable-override flags as `thinr product playbook run`
+apply. For playbooks that should be reusable across users, upload
+them to their product with `thinr product playbook upload` instead.
+
 ### `thinr profile`
 
 Manage the profile store (see [Profiles and multi-account
@@ -346,25 +449,86 @@ passed through (via the global flag) to impersonate another account.
 
 ### Tool catalog
 
-Roughly 28 tools, grouped by capability. Every tool accepts optional
-`device`, `user`, and `profile` arguments, so a single session can
-target any device/account/environment without restart.
-
-| Area                  | Tools                                                                                                                 |
-| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| Discovery             | `thinr_devices` (with optional `query` for regex filtering), `thinr_device_info`, `thinr_profiles`                    |
-| Shell                 | `thinr_exec` (buffered), with streaming stdout/stderr                                                                 |
-| Filesystem            | `thinr_read`, `thinr_write`, `thinr_ls`, `thinr_mkdir`, `thinr_delete`, `thinr_move`                                  |
-| Resources             | `thinr_resource_list` (with `in`/`out` schemas), `thinr_resource_call`                                                |
-| Properties            | `thinr_property_get`, `thinr_property_set`                                                                            |
-| Scripts (device)      | `thinr_script_list`, `thinr_script_write`, `thinr_script_delete`                                                      |
-| Monitoring and update | `thinr_monitoring`, `thinr_update`                                                                                    |
-| Products              | `thinr_products`, `thinr_product_delete`, `thinr_device_set_product`                                                  |
-| Product scripts       | `thinr_product_script_list`, `thinr_product_script_read`, `thinr_product_script_write`, `thinr_product_script_delete` |
+Grouped by capability. Every tool accepts optional `device`, `user`,
+and `profile` arguments, so a single session can target any
+device/account/environment without restart.
+
+| Area                  | Tools                                                                                                                                                                                        |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Discovery             | `thinr_devices` (with optional `query` for regex filtering), `thinr_device_info`, `thinr_profiles`                                                                                           |
+| Shell                 | `thinr_exec` (buffered), with streaming stdout/stderr                                                                                                                                        |
+| Filesystem            | `thinr_read`, `thinr_write`, `thinr_push`, `thinr_pull`, `thinr_ls`, `thinr_mkdir`, `thinr_rm`, `thinr_mv`                                                                                   |
+| Resources             | `thinr_resource_list` (with `in`/`out` schemas), `thinr_resource_call`                                                                                                                       |
+| Properties            | `thinr_property_get`, `thinr_property_set`                                                                                                                                                   |
+| Scripts (device)      | `thinr_script_list`, `thinr_script_write`, `thinr_script_delete`                                                                                                                             |
+| Monitoring and update | `thinr_monitoring`, `thinr_bucket_read`, `thinr_update`                                                                                                                                      |
+| Products              | `thinr_products`, `thinr_product_delete`, `thinr_device_set_product`, `thinr_product_exec`, `thinr_product_write`                                                                            |
+| Product scripts       | `thinr_product_script_list`, `thinr_product_script_read`, `thinr_product_script_write`, `thinr_product_script_delete`                                                                        |
+| Playbooks (authoring) | `thinr_playbook_schema`, `thinr_playbook_validate`, `thinr_playbook_run` (ad-hoc)                                                                                                            |
+| Product playbooks     | `thinr_product_playbook_list`, `thinr_product_playbook_read`, `thinr_product_playbook_write`, `thinr_product_playbook_run` (single device), `thinr_product_playbook_rollout` (fleet), `thinr_product_playbook_delete` |
 
 Full input/output schemas are published via standard MCP
 `list_tools`; the client will show them when you connect.
 
+### Authoring playbooks from natural language
+
+Playbooks are declarative YAML documents — steps like `exec`, `write`,
+`install_package`, `service`, plus a `target` block and a `vars`
+block — that the runner applies to a device or a fleet. With the MCP
+server connected, an AI assistant can turn a natural-language request
+into a validated playbook and store it on the relevant product
+without the user ever writing YAML by hand.
+
+The intended authoring loop is:
+
+1. **Fetch the schema.** Call `thinr_playbook_schema` once at the
+   start of the session to get the authoritative list of top-level
+   fields, target block, step actions with their parameters, and the
+   two accepted forms of the `vars` block (plain and extended).
+2. **Draft the YAML.** Translate the user's request into a playbook
+   draft. Use the extended `vars` form
+   (`default` / `description` / `type` / `overridable` / `required`)
+   whenever the user hints at knobs the caller may need to tune at
+   run time.
+3. **Validate and iterate.** Call `thinr_playbook_validate` with the
+   draft. On failure, read the consolidated error message, fix the
+   YAML, and call validate again. Never skip this step.
+4. **Upload.** Once validation is clean, call
+   `thinr_product_playbook_write` with the product id, a short name
+   (letters / digits / underscore / dash), and the validated YAML.
+   The tool re-validates server-side; never pass `skip_validation` to
+   mask a real error.
+5. **Pre-flight on one device.** Call
+   `thinr_product_playbook_run` with a single `device` (plus
+   `dry_run: true` or `check: true` for a read-only preview) to
+   confirm the steps behave as expected.
+6. **Roll out.** Finally, `thinr_product_playbook_rollout` rolls the
+   playbook across the fleet in batches with a failure-rate kill
+   switch, and writes a persistent report to `playbooks/runs/` in the
+   product file storage.
+
+Example prompt the user can give the assistant:
+
+> "On product `edge-gateways`, create a playbook called
+> `nginx-upgrade` that updates the nginx package, renders
+> `/etc/nginx/nginx.conf` from a template, and restarts nginx only
+> if the config check passes. Make `worker_connections` an
+> overridable integer variable, default 1024. Then try it on
+> `edge-gw-17` in check mode."
+
+A well-behaved assistant translates this into:
+
+- `thinr_playbook_schema` → read the authoring contract.
+- Draft YAML → `thinr_playbook_validate` until clean.
+- `thinr_product_playbook_write` with `product="edge-gateways"`,
+  `name="nginx-upgrade"`, and the validated content.
+- `thinr_product_playbook_run` with `device="edge-gw-17"` and
+  `check: true` to preview what would change.
+
+After that a second message like "looks good, roll it out to staging"
+maps to `thinr_product_playbook_rollout` with the matching
+`group` / `filter` and a conservative `batch_size`.
+
 ### Per-call controls
 
 The server starts with no per-session pin: every tool call must say
@@ -447,7 +611,57 @@ npm link            # makes `thinr` available on $PATH
 node bin/thinr.js   # or run directly without linking
 ```
 
-There are no automated tests yet — contributions welcome.
+Unit tests live under `tests/` and run offline:
+
+```bash
+npm test
+```
+
+### Integration tests
+
+The product-playbook end-to-end script at
+[`tests/integration/playbook-e2e.js`](tests/integration/playbook-e2e.js)
+drives a real ThinRemote cloud through the full playbook lifecycle
+(create product → upload flat/extended/internal playbooks → list →
+download → replace → reject invalid inputs → optionally run in
+`check` mode against a device → delete). Cleanup of the temporary
+product and its file storage is unconditional (`try / finally`),
+even if the run fails halfway.
+
+Prerequisites:
+
+- An authenticated CLI profile (`thinr` once, or `THINR_PROFILE=<name>`
+  pointing at an existing entry in `~/.config/thinr-cli/config.json`).
+- The account must be allowed to create products and file storages.
+
+Invocations:
+
+```bash
+# Offline checks only — parses fixtures, exercises resolveVarScope,
+# asserts the dry-run plan. No network access. Safe in CI without
+# credentials.
+node tests/integration/playbook-e2e.js --offline
+
+# Full flow against the active profile. Creates a throw-away product
+# named "playbook-e2e-<timestamp>-<rand>" and deletes it on exit.
+node tests/integration/playbook-e2e.js
+
+# Add a test device to exercise `check`-mode execution with and
+# without variable overrides. The device must belong to the active
+# user; it does NOT need to be bound to the temporary product.
+THINR_E2E_DEVICE=<device-id> node tests/integration/playbook-e2e.js
+```
+
+The script only touches resources it creates itself (identified by
+the `playbook-e2e-` product-id prefix). If a run is interrupted
+before the `finally` cleanup executes — e.g. the process is killed
+— list leftovers with `thinr product list --json` and drop each one
+through the MCP `thinr_product_delete` tool (from an AI client) or
+via a Node one-liner reusing `deleteProductWithStorage` from
+`lib/product.js`.
+
+No credentials or tokens are ever written to the repository; the
+script reads them from the standard CLI profile store.
 
 ## License
 

package/bin/thinr.js

@@ -4,9 +4,8 @@ import { readFileSync } from 'fs';
 import { fileURLToPath } from 'url';
 import { dirname, resolve } from 'path';
 import { Command } from 'commander';
-import chalk from 'chalk';
 import figlet from 'figlet';
-import ora from 'ora';
+import { accent, info } from '../lib/format.js';
 import { configExists, readConfig, setActiveProfile } from '../lib/config.js';
 import { detectJsonModeFromArgv } from '../lib/output.js';
 
@@ -34,22 +33,23 @@ for (let i = 2; i < process.argv.length; i++) {
 detectJsonModeFromArgv();
 import { authenticate } from '../lib/auth.js';
 import { deviceCommand } from '../commands/device/index.js';
+import { fleetCommand } from '../commands/fleet/index.js';
 import { logoutCommand } from '../commands/logout.js';
-import { productCommand } from '../commands/product.js';
+import { playbookCommand } from '../commands/playbook/index.js';
+import { productCommand } from '../commands/product/index.js';
 import { profileCommand } from '../commands/profile.js';
+import { runDashboard } from '../commands/dashboard.js';
 import { setBaseURL } from '../lib/api.js';
 import { startMCPServer } from '../lib/mcp/server.js';
 
-// Function to display the banner
 function displayBanner() {
-    console.log(chalk.cyan(figlet.textSync('thinr-cli', { horizontalLayout: 'full' })));
-    console.log(chalk.blue('Thin Remote CLI - Remote management for IoT devices'));
+    console.log(accent(figlet.textSync('thinr-cli', { horizontalLayout: 'full' })));
+    console.log(info('Thin Remote CLI - Remote management for IoT devices'));
     console.log();
 }
 
 const program = new Command();
 
-// Set up CLI information
 program
     .name('thinr')
     .description('CLI for ThinRemote - Remote management for IoT devices')
@@ -57,14 +57,16 @@ program
     .option('-u, --user <username>', 'API user override (admin impersonation)')
     .option('--profile <name>', 'Configuration profile to use (defaults to the saved default)');
 
-// Register commands
 deviceCommand(program);
+fleetCommand(program);
 productCommand(program);
+playbookCommand(program);
 profileCommand(program);
 logoutCommand(program);
 
 program
     .command('mcp')
+    .helpGroup('Integration:')
     .description('Start the MCP server (stdio) for AI tool integration')
     .action(async () => {
         try {
@@ -91,27 +93,24 @@ if (configExists()) {
     }
 }
 
-// Handle no command (just "thinr")
+// Handle no command (just "thinr"): launch the dashboard when running
+// interactively. Non-TTY contexts (pipes, scripts, `thinr | cat`) fall
+// back to `--help` so they get something useful instead of an Ink crash.
 if (process.argv.length <= 2) {
-    const spinner = ora('Checking configuration...').start();
-
-    try {
+    if (!process.stdout.isTTY) {
+        program.help();
+    } else {
         if (!configExists()) {
-            // Display banner only if configuration doesn't exist
             displayBanner();
-            spinner.succeed('No configuration found. Starting setup...');
-            await authenticate();
-            program.help();
-        } else {
-            spinner.succeed('Configuration found');
-            // Show help if already configured, but don't display banner twice
-            program.help();
+            try {
+                await authenticate();
+            } catch (error) {
+                console.error(`Configuration error: ${error.message}`);
+                process.exit(1);
+            }
         }
-    } catch (error) {
-        spinner.fail(`Configuration error: ${error.message}`);
-        process.exit(1);
+        await runDashboard();
     }
-    spinner.succeed('Configuration found');
 } else {
     // Parse arguments - don't show banner for regular commands
     program.parse(process.argv);

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();
+}