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

package/CHANGELOG.md

@@ -1,9 +1,53 @@
 # Changelog
 
-## [1.2.0] - 2026-04-16
+## [1.3.0] - 2026-09-13
 
 ### Added
 
+- `thinr login` — re-authenticate the current profile in place, without
+  deleting and recreating it. Renews an expired session in one step and
+  defaults the server prompt to the profile's existing server.
+
+### Changed
+
+- Session-expiry errors now point to the working command: "Session
+  expired. Run `thinr login` to sign in again." (previously suggested
+  `thinr`, which opens the dashboard instead of re-authenticating).
+- More robust token refresh for WebSocket sessions: the interactive
+  console and streaming `exec` now refresh an expired access token
+  before the handshake and retry once on a 401, matching the
+  refresh-on-401 behaviour of HTTP calls.
+
+## [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
@@ -23,9 +67,27 @@
 
 ### 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

package/README.md

@@ -12,8 +12,8 @@ Two operating modes:
 
 - **CLI** — interactive or scripted device management from a shell.
 - **MCP server** — a stdio [Model Context Protocol][mcp] server that
-  exposes the same operations as typed tools for AI clients like
-  Claude Code.
+  exposes the same operations as 80+ typed tools for AI clients like
+  Claude Code, Claude Desktop and Cursor.
 
 Both modes share the same auth, profiles, and device API layer, so
 you configure the tool once and use it in whichever mode fits the
@@ -30,13 +30,16 @@ 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)
+    - [Integrating with Claude Desktop, Cursor and other MCP hosts](#integrating-with-claude-desktop-cursor-and-other-mcp-hosts)
 - [Profiles and multi-account use](#profiles-and-multi-account-use)
 - [Development](#development)
 - [License](#license)
@@ -337,6 +340,69 @@ 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
@@ -363,46 +429,116 @@ Other profiles are left untouched.
 
 ## Part 2 — MCP server
 
-`thinr` ships an [MCP][mcp] server that exposes the CLI's device
-operations as a set of typed tools. AI clients (Claude Code, Claude
-Desktop, and any other MCP-compatible host) can then list devices,
-run shell commands, read/write files, call resources, and manage
-products through the same API the CLI uses — with stable schemas and
-a consistent error contract.
+`thinr` ships an [MCP][mcp] server that exposes the CLI's device and
+fleet operations as a set of 80+ typed tools. AI clients (Claude Code,
+Claude Desktop, Cursor, and any other MCP-compatible host) can list
+devices, run shell commands, read/write files, call resources, manage
+products, author and roll out playbooks, triage alarms and rotate
+access tokens through the same API the CLI uses — with stable schemas
+and a consistent error contract.
 
 ### Starting the server
 
 ```bash
-thinr mcp [-d, --device <deviceId>]
+thinr mcp
 ```
 
-The server speaks [MCP over stdio][mcp-stdio]. `-d/--device` sets a
-default device that tools can omit in each call; `--user` can be
-passed through (via the global flag) to impersonate another account.
+The server speaks [MCP over stdio][mcp-stdio]. Every tool call carries
+its own `device`, `user` and `profile` arguments, so a single running
+server handles any device of any configured environment without a
+restart.
 
 [mcp-stdio]: https://modelcontextprotocol.io/specification/server/transport#stdio
 
 ### 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` (when
+relevant), `user` and `profile` arguments, so a single session can
+target any device, account or environment without restart.
+
+| Area                         | Tools                                                                                                                                                                                                                |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Discovery                    | `thinr_devices` (with optional `query` for regex filtering), `thinr_device_info`, `thinr_profiles`                                                                                                                   |
+| Provisioning and lifecycle   | `thinr_agent_install_command`, `thinr_device_set_product`, `thinr_device_delete`                                                                                                                                     |
+| 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 (device)          | `thinr_property_get`, `thinr_property_set`                                                                                                                                                                           |
+| Scripts (device)             | `thinr_script_list`, `thinr_script_write`, `thinr_script_delete`                                                                                                                                                     |
+| Monitoring and agent updates | `thinr_monitoring`, `thinr_bucket_read`, `thinr_update`                                                                                                                                                              |
+| Alarms                       | `thinr_alarm_instances`, `thinr_alarm_instance_stats`, `thinr_alarm_instance_get`, `thinr_alarm_instance_update`, `thinr_alarm_instance_delete`, `thinr_alarm_rules`, `thinr_alarm_rule_read/write/delete`           |
+| Access tokens                | User: `thinr_token_list`, `thinr_token_get`, `thinr_token_create`, `thinr_token_update`, `thinr_token_delete`. Device: `thinr_device_token_list`, `thinr_device_token_create`, `thinr_device_token_delete`           |
+| Products                     | `thinr_products`, `thinr_product_create`, `thinr_product_update`, `thinr_product_delete`, `thinr_product_exec`, `thinr_product_write`                                                                                |
+| Product scripts              | `thinr_product_script_list`, `thinr_product_script_read`, `thinr_product_script_write`, `thinr_product_script_delete`                                                                                                |
+| Product properties           | `thinr_product_property_get`, `thinr_product_property_set`, `thinr_product_property_delete`                                                                                                                          |
+| Product profile schema       | `thinr_product_profile_api_{list,get,set,delete}`, `thinr_product_profile_bucket_{list,get,set,delete}`, `thinr_product_profile_property_{list,get,set,delete}`                                                      |
+| Product log sources          | `thinr_product_logs_list`, `thinr_product_logs_add`, `thinr_product_logs_remove`, `thinr_product_logs_presets`, `thinr_product_logs_set_default`                                                                     |
+| Product metrics              | `thinr_product_metric_list`, `thinr_product_metric_set`, `thinr_product_metric_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
@@ -431,8 +567,27 @@ That's it — a single MCP server entry handles every device of the
 active profile. Tool calls pass `device` (and optionally `user` /
 `profile`) per call.
 
-Other MCP hosts follow the same pattern — they just need the command
-`thinr mcp` (optionally with `-d <deviceId>`) over stdio.
+### Integrating with Claude Desktop, Cursor and other MCP hosts
+
+Other MCP hosts use a JSON config file (`claude_desktop_config.json`,
+`.cursor/mcp.json`, etc.). The entry shape is the same on every host:
+
+```json
+{
+    "mcpServers": {
+        "thinr": {
+            "command": "thinr",
+            "args": ["mcp"]
+        }
+    }
+}
+```
+
+The `thinr` binary must be on `PATH` for the host to spawn it —
+`npm install -g @thinremote/thinr-cli` puts it there. If the host
+runs under a shell that doesn't load your global npm bin
+(common on macOS GUI apps), point `command` at the absolute path
+(`which thinr`) instead.
 
 ---
 
@@ -485,7 +640,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,10 +4,9 @@ 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 { configExists, readConfig, setActiveProfile } from '../lib/config.js';
+import { accent, info } from '../lib/format.js';
+import { configExists, getActiveProfile, readConfig, setActiveProfile } from '../lib/config.js';
 import { detectJsonModeFromArgv } from '../lib/output.js';
 
 // Single source of truth for the version: package.json. Avoids the drift
@@ -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,35 @@ 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('login')
+    .helpGroup('Profile:')
+    .description('Re-authenticate the current profile (renew an expired session)')
+    .action(async () => {
+        try {
+            // Pin the target to the active/default profile by name so the
+            // refreshed credentials overwrite it in place, even when the
+            // profile name differs from the server hostname.
+            const name = getActiveProfile();
+            if (name) setActiveProfile(name);
+            await authenticate();
+            console.log(info('Signed in.'));
+        } catch (error) {
+            console.error(`Error: ${error.message}`);
+            process.exit(1);
+        }
+    });
+
 program
     .command('mcp')
+    .helpGroup('Integration:')
     .description('Start the MCP server (stdio) for AI tool integration')
     .action(async () => {
         try {
@@ -91,27 +112,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);