@thinremote/thinr-cli 1.5.0 → 1.6.1

package/lib/mcp/{tools-exec.js → device-exec.js}

@@ -85,21 +85,25 @@ async function targetsOf(args) {
     return { devices: active, offline };
 }
 
-async function toolExec(args) {
+/**
+ * @param {Record<string, any>} args  The body, with `device` (ids.device) and `user`.
+ * @param {import('@thinger-io/cli-core/mcp/tools-resource').LocalContext} [ctx]
+ */
+async function toolExec(args, ctx) {
     if (typeof args.command !== 'string' || !args.command.trim()) {
-        throw inputError('command is required');
+        throw inputError('body.command is required');
     }
     const listed = Array.isArray(args.devices) && args.devices.length > 0;
     const fleet = listed || args.product || args.group;
     const kinds = [args.device, listed, args.product || args.group, args.all].filter(Boolean);
     if (kinds.length > 1) {
         throw inputError(
-            'give one kind of target: `device`, `devices`, `product` (and `group`) or `group`, or `all`',
+            'give one kind of target: ids.device, or in the body `devices`, `product` (and `group`) or `group`, or `all`',
         );
     }
     if (!args.device && !fleet && !args.all) {
         throw inputError(
-            'give the target: `device` for one device; `devices`, `product` or `group` for several; `all: true` for every device of the ThinRemote products',
+            'give the target: ids.device for one device; body `devices`, `product` or `group` for several; body `all: true` for every device of the ThinRemote products',
         );
     }
     // Default guards against hung commands locking the session; callers
@@ -131,6 +135,13 @@ async function toolExec(args) {
             isError: offline.length > 0,
         };
     }
+    // On several devices it asks first: the plan names every target.
+    if (!args.device && ctx?.plan && !ctx.confirmed) {
+        const ids = devices.map((d) => d.device);
+        return ctx.plan(
+            `It would run \`${args.command}\` on ${ids.length} device(s): ${ids.join(', ')}.${skipped}`,
+        );
+    }
 
     const concurrency = positive(args.concurrency, 10);
     const { entries, durationMs } = await runProductFanOut({
@@ -217,57 +228,75 @@ async function toolExec(args) {
     };
 }
 
-export const tools = [
-    {
-        name: 'device_exec',
-        description:
-            'Run a shell command on devices with the ThinRemote agent: on one (`device`: its output and exit code), or on several in parallel (`devices`, a `product` and optionally its `group`, or `all: true` for every device of the ThinRemote products: output, exit code and duration per device plus a summary). Offline devices are skipped unless `include_offline`. `dry_run` says which devices it would reach without running anything. On several devices it acts at once: confirm with the user first; for repeatable, checked changes use a playbook (type "product_playbook").',
-        inputSchema: {
-            type: 'object',
-            properties: {
-                command: { type: 'string', description: 'Shell command to run.' },
-                device: {
-                    type: 'string',
-                    description: 'One device (from {tool:resource_list} type "device").',
-                },
-                devices: {
-                    type: 'array',
-                    items: { type: 'string' },
-                    description: 'Several devices by id.',
-                },
-                product: { type: 'string', description: 'Every device of this product.' },
-                group: {
-                    type: 'string',
-                    description: 'Asset group: alone, or narrowing `product`.',
-                },
-                all: {
-                    type: 'boolean',
-                    description: 'Every device of the ThinRemote products of the account.',
-                },
-                include_offline: {
-                    type: 'boolean',
-                    description: 'Also try devices that are not connected (default false).',
-                },
-                timeout: {
-                    type: 'number',
-                    description: 'Seconds per device before giving up (default 30).',
-                },
-                concurrency: {
-                    type: 'number',
-                    description: 'Devices at a time, on several (default 10).',
-                },
-                fail_fast: {
-                    type: 'boolean',
-                    description: 'On several: start no more devices after one fails.',
-                },
-                dry_run: {
-                    type: 'boolean',
-                    description: 'Only list the devices it would run on.',
-                },
-                user: { type: 'string', description: 'Account to act on (admin only).' },
+/**
+ * The shell command, as an action of the server's `device` type: on the
+ * device of ids.device, or on several (body devices, product, group, all).
+ * On several it answers its targets until confirmed.
+ *
+ * @type {import('@thinger-io/cli-core/mcp/tools-resource').LocalAction}
+ */
+export const execAction = {
+    description:
+        'Run a shell command on devices with the ThinRemote agent: on one (ids.device: its output and exit code), or on several in parallel (no ids; body `devices`, a `product` and optionally its `group`, or `all: true` for every device of the ThinRemote products: output, exit code and duration per device plus a summary). Offline devices are skipped unless `include_offline`. `dry_run` says which devices it would reach without running anything. For repeatable, checked changes use a playbook (type "product_playbook").',
+    on: 'either',
+    bodyRequired: true,
+    confirm: true,
+    body: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['command'],
+        properties: {
+            command: { type: 'string', description: 'Shell command to run.' },
+            devices: {
+                type: 'array',
+                items: { type: 'string' },
+                description: 'Several devices by id.',
+            },
+            product: { type: 'string', description: 'Every device of this product.' },
+            group: { type: 'string', description: 'Asset group: alone, or narrowing `product`.' },
+            all: {
+                type: 'boolean',
+                description: 'Every device of the ThinRemote products of the account.',
+            },
+            include_offline: {
+                type: 'boolean',
+                description: 'Also try devices that are not connected (default false).',
+            },
+            timeout: {
+                type: 'number',
+                description: 'Seconds per device before giving up (default 30).',
             },
-            required: ['command'],
+            concurrency: {
+                type: 'number',
+                description: 'Devices at a time, on several (default 10).',
+            },
+            fail_fast: {
+                type: 'boolean',
+                description: 'On several: start no more devices after one fails.',
+            },
+            dry_run: { type: 'boolean', description: 'Only list the devices it would run on.' },
         },
-        handler: toolExec,
     },
-];
+    examples: [
+        {
+            tool: 'resource_call',
+            arguments: {
+                type: 'device',
+                action: 'exec',
+                ids: { device: 'gw_1' },
+                body: { command: 'uptime' },
+            },
+            does: 'Run uptime on one device.',
+        },
+        {
+            tool: 'resource_call',
+            arguments: {
+                type: 'device',
+                action: 'exec',
+                body: { command: 'df -h /', product: 'gateways', dry_run: true },
+            },
+            does: 'The connected devices of the product gateways it would run on.',
+        },
+    ],
+    run: (body, ctx) => toolExec({ ...body, device: ctx.id, user: ctx.user }, ctx),
+};

package/lib/mcp/helpers.js

@@ -1,14 +1,14 @@
 // @ts-check
 import { createDeviceAPI } from '../device-api.js';
 import { inputError } from '@thinger-io/cli-core/errors';
-import { toolName } from '@thinger-io/cli-core/mcp/naming';
+import { opRef } from '@thinger-io/cli-core/mcp/naming';
 
 /** Build a device-scoped API client. Tools must always pass `device`
  *  explicitly — the server has no per-session default. */
 export function getAPI(device, user) {
     if (!device)
         throw inputError(
-            `device is required. Use ${toolName('resource_list')} (type "device") to list available devices.`,
+            `device is required. Use ${opRef('device', 'list')} to list available devices.`,
         );
     return { api: createDeviceAPI(device, { user: user || undefined }), device };
 }

package/lib/mcp/resource-hooks.js

@@ -1,17 +1,84 @@
 // @ts-check
 import { deleteStorage } from '@thinger-io/cli-core/storage';
-import { toolName } from '@thinger-io/cli-core/mcp/naming';
+import { inputError } from '@thinger-io/cli-core/errors';
+import { opRef } from '@thinger-io/cli-core/mcp/naming';
+import { DASHBOARD_METRICS_PROPERTY, validateDashboardMetrics } from '../product.js';
+import {
+    FALLBACK_LOGS_COMMAND,
+    FALLBACK_LOGS_SOURCE_NAME,
+    LOGS_PROPERTY,
+    listPresets,
+    validateLogsConfig,
+} from '../product/logs.js';
 import { getAPI } from './helpers.js';
 
 /** Where the rest of what an agent offers is, keyed by what it is. */
 const agentMap = (device) => ({
-    monitoring: `live: ${toolName('device_resource_call')} resource "monitoring"; history: ${toolName('bucket_data_read')} bucket "monitoring" device "${device}" (fields cpu.usage, memory.usage, disk.root.usage, network.rx_rate, load.1m…), kept only when the device's product has a monitoring bucket (ThinRemote products do): empty otherwise`,
-    files: `${toolName('resource_list')} / _get / _create / _update / _delete type "device_fs" parent "${device}"`,
-    scripts: `type "device_script" parent "${device}"`,
-    commands: `${toolName('device_exec')} device "${device}"`,
-    agent_update: `${toolName('resource_call')} type "device" action "agent_update" id "${device}"`,
+    monitoring: `live: ${opRef('device_resource', 'call')} ids {"device": "${device}", "resource": "monitoring"}; history: ${opRef('bucket_data', 'list')} ids {"bucket": "monitoring"} filter {"device": "${device}"} (fields cpu.usage, memory.usage, disk.root.usage, network.rx_rate, load.1m…), kept only when the device's product has a monitoring bucket (ThinRemote products do): empty otherwise`,
+    files: `type "device_fs" ids {"device": "${device}", "path": <absolute path>}`,
+    scripts: `type "device_script" ids {"device": "${device}", "script": <file name>}`,
+    commands: `${opRef('device', 'exec')} ids {"device": "${device}"} body {"command": …}`,
+    agent_update: `${opRef('device', 'agent_update')} ids {"device": "${device}"}`,
 });
 
+/** One metric of thinr's terminal dashboard, an element of `dashboard_metrics`. */
+const METRIC_SCHEMA = {
+    type: 'object',
+    required: ['name', 'resource'],
+    properties: {
+        name: { type: 'string', description: 'Metric id (letters, digits, _ and -), unique.' },
+        label: { type: 'string', description: 'Shown in the panel.' },
+        resource: {
+            type: 'string',
+            description: 'Product API resource asked to each device (usually a product script).',
+        },
+        field: {
+            type: 'string',
+            description: 'Dot path to the value in the answer; omit for scalars.',
+        },
+        aggregation: {
+            type: 'string',
+            enum: ['sum', 'avg', 'max', 'min', 'count', 'top', 'none', 'distribution'],
+            description:
+                'How the devices\' values combine; "distribution" counts devices per value (versions, kernels).',
+        },
+        visualization: {
+            type: 'string',
+            enum: ['kpi', 'bar', 'sparkline', 'list'],
+            description: 'kpi (default), sparkline (trend), list (pairs with distribution).',
+        },
+        interval: {
+            type: 'number',
+            description: 'Seconds between refreshes; omit to only relay what devices push.',
+        },
+        unit: { type: 'string', description: 'Suffix shown with the value ("%").' },
+    },
+};
+
+/** The product properties thinr reads, checked whole before they are written. */
+const CHECKED = {
+    [LOGS_PROPERTY]: validateLogsConfig,
+    [DASHBOARD_METRICS_PROPERTY]: validateDashboardMetrics,
+};
+
+/**
+ * The value of `logs` or `dashboard_metrics`, checked (and normalized) before
+ * it reaches the server: thinr reads them, and a bad one breaks its
+ * terminal dashboard for the whole product.
+ */
+function checkedProperty(body, ctx) {
+    if (!body || typeof body !== 'object' || Array.isArray(body)) return body;
+    const name = ctx.id ?? body.property;
+    const check = Object.hasOwn(CHECKED, name) ? CHECKED[name] : undefined;
+    if (!check || body.value === undefined) return body;
+    if (ctx.merge) {
+        throw inputError(
+            `${name} is written whole: update it without merge (read it, change it, send the whole value)`,
+        );
+    }
+    return { ...body, value: check(body.value) };
+}
+
 /**
  * What ThinRemote adds to the generic `resource_*` tools of cli-core, which
  * run these after their own hooks:
@@ -24,6 +91,10 @@ const agentMap = (device) => ({
  *   model that starts from the device finds it.
  * - Deleting a product also deletes its file storage, which holds the
  *   product's scripts and only ThinRemote products have.
+ * - The product properties thinr's terminal dashboard reads (`logs`, its
+ *   log sources; `dashboard_metrics`, its fleet metrics) are checked before
+ *   they are written, and resource_describe of product_property shows their
+ *   shape.
  *
  * @type {Record<string, import('@thinger-io/cli-core/mcp/resource-hooks').ResourceHooks>}
  */
@@ -50,4 +121,31 @@ export const resourceHooks = {
             }
         },
     },
+    product_property: {
+        beforeCreate: checkedProperty,
+        beforeUpdate: checkedProperty,
+        describe: () => ({
+            [LOGS_PROPERTY]: {
+                about: "Log sources of thinr's terminal dashboard: named shell commands the agent streams when someone opens a device's logs. Written whole; checked before it is saved.",
+                shape: {
+                    sources: [
+                        {
+                            name: 'letters, digits, _ and - (up to 32), unique',
+                            command: '"journalctl -f", "docker logs -f app", "tail -F <file>"',
+                            preset: 'optional: a named line format (presets below)',
+                            pattern:
+                                'optional, not with preset: a regex with named groups time, level and msg',
+                        },
+                    ],
+                    default: 'optional: the name of the source shown first',
+                },
+                fallback: `Without the property a product shows one "${FALLBACK_LOGS_SOURCE_NAME}" source: ${FALLBACK_LOGS_COMMAND}.`,
+                presets: Object.fromEntries(listPresets().map((p) => [p.name, p.description])),
+            },
+            [DASHBOARD_METRICS_PROPERTY]: {
+                about: "Fleet metrics of thinr's terminal dashboard (not a console dashboard): an array of metrics, each a value asked to every device and combined across the fleet. Written whole; checked before it is saved.",
+                element: METRIC_SCHEMA,
+            },
+        }),
+    },
 };