@thinremote/thinr-cli 1.5.0 → 1.6.1

package/lib/mcp/resource-types.js

@@ -8,25 +8,22 @@ import {
 } from '@thinger-io/cli-core/resource';
 import { getDevices } from '@thinger-io/cli-core/devices';
 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';
 import {
     deleteProductPlaybook,
     findProductPlaybook,
     installProductScript,
-    listDashboardMetrics,
     listProductPlaybooks,
     listProductScripts,
     readProductPlaybook,
     readProductScript,
-    removeDashboardMetric,
     removeProductScript,
-    upsertDashboardMetric,
     uploadProductPlaybook,
 } from '../product.js';
-import { addLogSource, getProductLogs, listPresets, removeLogSource } from '../product/logs.js';
 import { localFileToRead, localFileToWrite } from '../local-files.js';
 import { getAPI } from './helpers.js';
 import { agentInstallCommand } from './agent-install.js';
+import { execAction } from './device-exec.js';
 import {
     DEFAULT_FAILURE_THRESHOLD,
     playbookSchema,
@@ -39,9 +36,10 @@ import {
 /**
  * ThinRemote's own resources, served by the generic `resource_*` tools of
  * cli-core next to the server's: a device's file system and scripts, and
- * a product's scripts, dashboard metrics, log sources and playbooks. Plus
- * two actions on the server's `device` type: updating the agent and the
- * command that installs it.
+ * a product's scripts and playbooks. Plus three actions on the server's
+ * `device` type: a shell command, updating the agent and the command that
+ * installs it. (The product's dashboard metrics and log sources are its
+ * product properties `dashboard_metrics` and `logs`: resource-hooks.js.)
  *
  * Create fails when the record is already there and update when it is
  * not, as on the server; a file of `device_fs` is written either way.
@@ -51,9 +49,9 @@ import {
 /** @typedef {import('@thinger-io/cli-core/mcp/tools-resource').LocalAction} LocalAction */
 
 /**
- * One write at a time per product and kind: metrics, log sources and the
- * playbook index are each one product property, read, changed and written
- * back, and a client often sends several creates at once.
+ * One write at a time per product and kind: the scripts and the playbook
+ * index are each read, changed and written back, and a client often sends
+ * several creates at once.
  * @type {Map<string, Promise<unknown>>}
  */
 const queues = new Map();
@@ -93,7 +91,7 @@ const deviceFs = {
     schema: {
         type: 'object',
         properties: {
-            path: { type: 'string', description: 'Absolute path on the device (the id).' },
+            path: { type: 'string', description: 'Absolute path on the device (ids.path).' },
             content: { type: 'string', description: 'Text to write (create, update).' },
             type: {
                 type: 'string',
@@ -102,7 +100,31 @@ const deviceFs = {
             },
         },
     },
-    notes: 'Paths are absolute on the device and act as the agent\'s OS user (root for a system install; check before writing to /etc). resource_list takes filter {path: "<folder>", include_hidden?: true} (default "/", which means the agent\'s working directory, normally the root). resource_get reads a text file; binary files are copied with the pull action. resource_create writes a file (body {content}) or creates a folder (body {type: "directory"}); resource_update writes a file whether it exists or not; resource_delete deletes a file or a folder with all it holds, never "/" or a folder right under it (use device_exec for that). push and pull read and write files of the machine running this MCP server only inside its local folder (THINR_MCP_LOCAL_DIR, or where the server started), and pull replaces a file only with body.overwrite.',
+    notes: 'ids.path is absolute on the device; the tools act as the agent\'s OS user (root for a system install; check before writing to /etc). resource_list takes filter {path: "<folder>", include_hidden?: true} (default "/", which means the agent\'s working directory, normally the root). resource_get reads a text file; binary files are copied with the pull action. resource_create writes a file (body {content}) or creates a folder (body {type: "directory"}); resource_update writes a file whether it exists or not; resource_delete deletes a file or a folder with all it holds, never "/" or a folder right under it (use {op:device.exec} for that). push and pull read and write files of the machine running this MCP server only inside its local folder (THINR_MCP_LOCAL_DIR, or where the server started), and pull replaces a file only with body.overwrite.',
+    filter: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+            path: { type: 'string', description: 'Folder to list (default "/").' },
+            include_hidden: { type: 'boolean', description: 'Also dot files.' },
+        },
+    },
+    examples: [
+        {
+            tool: 'resource_list',
+            arguments: { type: 'device_fs', ids: { device: 'gw_1' }, filter: { path: '/etc' } },
+            does: 'List /etc on the device gw_1.',
+        },
+        {
+            tool: 'resource_create',
+            arguments: {
+                type: 'device_fs',
+                ids: { device: 'gw_1', path: '/tmp/app.conf' },
+                body: { content: 'port=8080\n' },
+            },
+            does: 'Write a text file on the device.',
+        },
+    ],
     async list(ctx) {
         const { api } = getAPI(ctx.parent, ctx.user);
         const asked = ctx.filter?.path || '/';
@@ -125,7 +147,7 @@ const deviceFs = {
         const { api } = getAPI(ctx.parent, ctx.user);
         const buf = await api.readFile(ctx.id);
         if (isBinary(buf)) {
-            return `Binary file of ${buf.byteLength} bytes: copy it to this machine with ${toolName('resource_call')} action "pull".`;
+            return `Binary file of ${buf.byteLength} bytes: copy it to this machine with ${opRef('device_fs', 'pull')}.`;
         }
         return buf.toString('utf8');
     },
@@ -152,7 +174,7 @@ const deviceFs = {
         const path = posix.normalize(String(ctx.id));
         if (!path.startsWith('/') || path.split('/').filter(Boolean).length < 2) {
             throw inputError(
-                `Not deleting ${ctx.id}: only absolute paths at least two levels deep (/var/tmp/x). For more, ${toolName('device_exec')}.`,
+                `Not deleting ${ctx.id}: only absolute paths at least two levels deep (/var/tmp/x). For more, ${opRef('device', 'exec')}.`,
             );
         }
         const { api } = getAPI(ctx.parent, ctx.user);
@@ -161,7 +183,7 @@ const deviceFs = {
     actions: {
         move: {
             description:
-                'Move or rename the path `id` to body.destination; body.overwrite replaces what is there. Write to a temporary file and move it into place for a change that is never seen half done.',
+                'Move or rename the path ids.path to body.destination; body.overwrite replaces what is there. Write to a temporary file and move it into place for a change that is never seen half done.',
             body: {
                 type: 'object',
                 properties: { destination: { type: 'string' }, overwrite: { type: 'boolean' } },
@@ -201,7 +223,7 @@ const deviceFs = {
         },
         pull: {
             description:
-                'Copy the file `id` of the device to the machine running this MCP server (body.destination, inside its local folder: see notes; ending in "/" keeps the name). An existing file is replaced only with body.overwrite.',
+                'Copy the file ids.path of the device to the machine running this MCP server (body.destination, inside its local folder: see notes; ending in "/" keeps the name). An existing file is replaced only with body.overwrite.',
             body: {
                 type: 'object',
                 properties: { destination: { type: 'string' }, overwrite: { type: 'boolean' } },
@@ -284,7 +306,7 @@ async function installDeviceScript(body, ctx, { replace }) {
     );
     const found = (reloaded?.scripts || []).find((s) => s.name === resource);
     return [
-        `Script at ${path}; resource "${resource}": call it with ${toolName('device_resource_call')}.`,
+        `Script at ${path}; resource "${resource}": call it with ${opRef('device_resource', 'call')} ids {"device": "${ctx.parent}", "resource": "${resource}"}.`,
         found?.describe
             ? `Schema: ${JSON.stringify(found.describe)}`
             : 'Schema: none (the script does not answer --describe): any input, raw output.',
@@ -296,13 +318,14 @@ const deviceScript = {
     description:
         'Scripts installed on a device with the agent: each becomes a resource of the device (battery.sh → "battery").',
     parent: 'device',
-    id: 'name',
+    id: 'script',
+    bodyId: 'name',
     schema: {
         type: 'object',
         properties: {
             name: {
                 type: 'string',
-                description: 'File name (the id); without extension it names the resource.',
+                description: 'File name (ids.script); without extension it names the resource.',
             },
             content: { type: 'string', description: 'Script source, shebang included.' },
             force: {
@@ -312,7 +335,7 @@ const deviceScript = {
             },
         },
     },
-    notes: 'The id is the file name with its extension ("uptime.sh"), in create, update and delete alike; the resource it becomes is named without it ("uptime"). Scripts run on whatever OS the device has: check it (resource_get of the device, agent.system_info) before relying on /proc or GNU tools. A script runs with the agent\'s privileges (root for a system install): installing one grants permanent remote execution of that code. Contract (--describe, JSON on stdin and stdout): {tool:doc_read} id "thinremote-scripts". For every device of a product use type "product_script" instead.',
+    notes: 'ids.script is the file name with its extension ("uptime.sh"), in create, update and delete alike; the resource it becomes is named without it ("uptime"). Scripts run on whatever OS the device has: check it (resource_get of the device, agent.system_info) before relying on /proc or GNU tools. A script runs with the agent\'s privileges (root for a system install): installing one grants permanent remote execution of that code. Contract (--describe, JSON on stdin and stdout): {op:doc.get} ids {"doc": "thinremote-scripts"}. For every device of a product use type "product_script" instead.',
     async list(ctx) {
         const { scripts } = await scriptsInfo(ctx.parent, ctx.user);
         return scripts.map((s) => ({
@@ -368,7 +391,7 @@ async function writeProductScript(body, ctx, { replace }) {
     });
     return [
         ...steps.map((s) => `- ${s}`),
-        `Call it on any device of the product: ${toolName('device_resource_call')} resource "${stem}".`,
+        `Call it on any device of the product: ${opRef('device_resource', 'call')} ids {"device": <device>, "resource": "${stem}"}.`,
     ].join('\n');
 }
 
@@ -377,11 +400,12 @@ const productScript = {
     description:
         'Scripts of a product: kept once in its storage, they run on any of its devices as a product API resource named after the file (backup.sh → "backup").',
     parent: 'product',
-    id: 'name',
+    id: 'script',
+    bodyId: 'name',
     schema: {
         type: 'object',
         properties: {
-            name: { type: 'string', description: 'File name (the id), e.g. "backup.sh".' },
+            name: { type: 'string', description: 'File name (ids.script), e.g. "backup.sh".' },
             content: { type: 'string', description: 'Script source.' },
             input: {
                 type: 'object',
@@ -395,7 +419,7 @@ const productScript = {
             },
         },
     },
-    notes: 'Writing one sets up all it needs (storage, wrapper, product code, API resource); the product must exist. Records listed with registered: false are files without their API resource. Contract and examples: {tool:doc_read} id "thinremote-scripts".',
+    notes: 'Writing one sets up all it needs (storage, wrapper, product code, API resource); the product must exist. Records listed with registered: false are files without their API resource. Contract and examples: {op:doc.get} ids {"doc": "thinremote-scripts"}.',
     list: (ctx) => listProductScripts(ctx.parent, ctx.user),
     async get(ctx) {
         return { name: ctx.id, content: await readProductScript(ctx.parent, ctx.id, ctx.user) };
@@ -412,190 +436,6 @@ const productScript = {
     },
 };
 
-// ─── product_metric ─────────────────────────────────────────────────
-
-const METRIC_FIELDS = [
-    'label',
-    'resource',
-    'field',
-    'aggregation',
-    'visualization',
-    'interval',
-    'unit',
-];
-
-async function writeMetric(body, ctx, { replace }) {
-    const list = await listDashboardMetrics(ctx.parent, ctx.user);
-    const current = list.find((m) => m.name === ctx.id);
-    if (current && !replace) throw exists('metric', ctx.id, `product ${ctx.parent}`);
-    if (!current && replace) throw missing('metric', ctx.id, `product ${ctx.parent}`);
-    const metric = { ...(current || {}), name: ctx.id };
-    for (const k of METRIC_FIELDS) if (body[k] !== undefined) metric[k] = body[k];
-    const { count } = await upsertDashboardMetric(ctx.parent, metric, ctx.user);
-    return `The product has ${count} metric(s).`;
-}
-
-/** @type {LocalType} */
-const productMetric = {
-    description:
-        "Metrics of thinr's terminal dashboard for a product (not a console dashboard): a value asked to every device and combined across the fleet.",
-    parent: 'product',
-    id: 'name',
-    schema: {
-        type: 'object',
-        properties: {
-            name: { type: 'string', description: 'Metric id.' },
-            label: { type: 'string', description: 'Shown in the panel.' },
-            resource: {
-                type: 'string',
-                description:
-                    'Product API resource asked to each device (usually a product script). Required.',
-            },
-            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 ("%").' },
-        },
-        required: ['resource'],
-    },
-    notes: 'Kept in the product property "dashboard_metrics": change them here, not through the property. Recipe: {tool:doc_read} id "thinremote-metrics-logs".',
-    list: (ctx) => listDashboardMetrics(ctx.parent, ctx.user),
-    async get(ctx) {
-        const metric = (await listDashboardMetrics(ctx.parent, ctx.user)).find(
-            (m) => m.name === ctx.id,
-        );
-        if (!metric) throw missing('metric', ctx.id, `product ${ctx.parent}`);
-        return metric;
-    },
-    create: (body, ctx) =>
-        oneAtATime(ctx, 'metric', () => writeMetric(body, ctx, { replace: false })),
-    update: (body, ctx) =>
-        oneAtATime(ctx, 'metric', () => writeMetric(body, ctx, { replace: true })),
-    async delete(ctx) {
-        const { action } = await oneAtATime(ctx, 'metric', () =>
-            removeDashboardMetric(ctx.parent, ctx.id, ctx.user),
-        );
-        if (action !== 'removed') throw missing('metric', ctx.id, `product ${ctx.parent}`);
-    },
-};
-
-// ─── product_log_source ─────────────────────────────────────────────
-
-async function logSources(product, user) {
-    const cfg = await getProductLogs(product, user);
-    const fallback = !!(/** @type {any} */ (cfg).__fallback);
-    const def = cfg.default || cfg.sources[0]?.name || null;
-    return {
-        fallback,
-        sources: cfg.sources.map((s) => ({
-            ...s,
-            default: s.name === def,
-            ...(fallback ? { fallback: true } : {}),
-        })),
-    };
-}
-
-async function writeLogSource(body, ctx, { replace }) {
-    const { sources, fallback } = await logSources(ctx.parent, ctx.user);
-    const current = fallback ? undefined : sources.find((s) => s.name === ctx.id);
-    if (current && !replace) throw exists('log source', ctx.id, `product ${ctx.parent}`);
-    if (!current && replace) throw missing('log source', ctx.id, `product ${ctx.parent}`);
-    const command = body.command ?? current?.command;
-    if (typeof command !== 'string' || !command.trim()) {
-        throw inputError('body.command is required');
-    }
-    const { config } = await addLogSource(
-        ctx.parent,
-        {
-            name: ctx.id,
-            command,
-            makeDefault: !!body.default,
-            // Giving one of them (even null) replaces both: they exclude each other.
-            ...('pattern' in body || 'preset' in body
-                ? { pattern: body.pattern ?? undefined, preset: body.preset ?? undefined }
-                : { pattern: current?.pattern, preset: current?.preset }),
-        },
-        ctx.user,
-    );
-    const def = config.default || config.sources[0]?.name;
-    return `The product has ${config.sources.length} log source(s); default: ${def}.`;
-}
-
-/** @type {LocalType} */
-const productLogSource = {
-    description:
-        "Log sources of a product: named shell commands the agent streams when someone opens a device's logs in thinr.",
-    parent: 'product',
-    id: 'name',
-    schema: {
-        type: 'object',
-        properties: {
-            name: {
-                type: 'string',
-                description: 'Source id (letters, digits, _ and -; up to 32).',
-            },
-            command: {
-                type: 'string',
-                description:
-                    'What the agent runs and streams: "journalctl -f", "docker logs -f app", "tail -F <file>".',
-            },
-            default: {
-                type: 'boolean',
-                description: 'Shown first (and by `thinr device logs` without --source).',
-            },
-            preset: {
-                type: 'string',
-                description: 'Named line format for structured rendering (see presets below).',
-            },
-            pattern: {
-                type: 'string',
-                description: 'Or a regex with named groups time, level and msg (not with preset).',
-            },
-        },
-        required: ['command'],
-    },
-    notes: 'Without any source a product shows one `system` journal source, listed with fallback: true; removing the last one brings it back. Details: {tool:doc_read} id "thinremote-metrics-logs".',
-    describe: () => ({
-        presets: Object.fromEntries(listPresets().map((p) => [p.name, p.description])),
-    }),
-    list: async (ctx) => (await logSources(ctx.parent, ctx.user)).sources,
-    async get(ctx) {
-        const source = (await logSources(ctx.parent, ctx.user)).sources.find(
-            (s) => s.name === ctx.id,
-        );
-        if (!source) throw missing('log source', ctx.id, `product ${ctx.parent}`);
-        return source;
-    },
-    create: (body, ctx) =>
-        oneAtATime(ctx, 'logs', () => writeLogSource(body, ctx, { replace: false })),
-    update: (body, ctx) =>
-        oneAtATime(ctx, 'logs', () => writeLogSource(body, ctx, { replace: true })),
-    async delete(ctx) {
-        const { removed, config } = await oneAtATime(ctx, 'logs', () =>
-            removeLogSource(ctx.parent, ctx.id, ctx.user),
-        );
-        if (!removed) throw missing('log source', ctx.id, `product ${ctx.parent}`);
-        if (config === null)
-            return 'It was the last one: the product falls back to the system journal.';
-    },
-};
-
 // ─── product_playbook ───────────────────────────────────────────────
 
 /** What resource_describe shows next to the format: fields at the top level. */
@@ -642,11 +482,15 @@ const productPlaybook = {
     description:
         'Playbooks of a product: YAML steps the agent runs on each device (write a file, run a command, install a script…), validated, tried and rolled out in batches.',
     parent: 'product',
-    id: 'name',
+    id: 'playbook',
+    bodyId: 'name',
     schema: {
         type: 'object',
         properties: {
-            name: { type: 'string', description: 'Playbook id (letters, digits, _ and -).' },
+            name: {
+                type: 'string',
+                description: 'Playbook id (ids.playbook; letters, digits, _ and -).',
+            },
             content: {
                 type: 'string',
                 description: 'The YAML, following `playbook_format` below.',
@@ -654,7 +498,19 @@ const productPlaybook = {
             description: { type: 'string', description: "Defaults to the YAML's own description." },
         },
     },
-    notes: 'Flow: write the YAML following playbook_format, check it with the validate action, save it with resource_create (validated again: nothing is saved if invalid), try it with the run action on one device (dry_run, then check, then for real), then roll it out with the rollout action. The run and validate actions also take an unsaved playbook: no id, the YAML in body.content. Rollouts change real machines: confirm with the user and start with small batches. Guide: {tool:doc_read} id "thinremote-playbooks".',
+    notes: 'Flow: write the YAML following playbook_format, check it with the validate action, save it with resource_create (validated again: nothing is saved if invalid), try it with the run action on one device (dry_run, then check, then for real), then roll it out with the rollout action. The run and validate actions also take an unsaved playbook: no ids.playbook, the YAML in body.content. Rollouts and runs on several devices change real machines: they answer their plan first, run with confirm: true once the user agrees; start with small batches. Guide: {op:doc.get} ids {"doc": "thinremote-playbooks"}.',
+    examples: [
+        {
+            tool: 'resource_call',
+            arguments: {
+                type: 'product_playbook',
+                action: 'run',
+                ids: { product: 'gateways', playbook: 'app-config' },
+                body: { device: 'gw_1', check: true },
+            },
+            does: 'Contact one device read-only and say what each step of the saved playbook would change.',
+        },
+    ],
     describe: () => {
         // The schema calls the top-level fields "document": said plainly,
         // with an example, so nobody nests them under a `document:` key.
@@ -683,7 +539,7 @@ const productPlaybook = {
     actions: {
         validate: {
             description:
-                'Check a playbook without running or saving it: a summary, or every issue found. The saved one (`id`) or the YAML in body.content.',
+                'Check a playbook without running or saving it: a summary, or every issue found. The saved one (ids.playbook) or the YAML in body.content.',
             on: 'either',
             body: { type: 'object', properties: { content: { type: 'string' } } },
             async run(body, ctx) {
@@ -693,8 +549,9 @@ const productPlaybook = {
         },
         run: {
             description:
-                'Run a playbook now, on the target given: body.device (one device: the pre-flight before a rollout), body.devices (of this product), body.group, or body.all: true for every device of the product at once (no batches or failure threshold: for a fleet, prefer rollout). The playbook is the saved one (`id`) or the YAML in body.content. body.dry_run gives the plan without contacting devices; body.check contacts them read-only and says what each step would change. body.vars overrides its variables (checked against what it declares).',
+                'Run a playbook now, on the target given: body.device (one device: the pre-flight before a rollout), body.devices (of this product), body.group, or body.all: true for every device of the product at once (no batches or failure threshold: for a fleet, prefer rollout; on several devices it answers its targets until confirmed). The playbook is the saved one (ids.playbook) or the YAML in body.content. body.dry_run gives the plan without contacting devices; body.check contacts them read-only and says what each step would change. body.vars overrides its variables (checked against what it declares).',
             on: 'either',
+            confirm: true,
             body: {
                 type: 'object',
                 properties: {
@@ -729,6 +586,14 @@ const productPlaybook = {
                         throw inputError(`Not devices of ${ctx.parent}: ${foreign.join(', ')}`);
                     }
                 }
+                if (!b.device && !b.dry_run && !b.check && !ctx.confirmed && ctx.plan) {
+                    const which = listed
+                        ? `the devices ${b.devices.join(', ')}`
+                        : await groupDevices(ctx, b.group);
+                    return ctx.plan(
+                        `It would run the playbook ${ctx.id ? `"${ctx.id}"` : 'given in body.content'} now on ${which}, all at once.`,
+                    );
+                }
                 if (ctx.id && b.device && !b.content) {
                     return toolProductPlaybookRun({
                         product: ctx.parent,
@@ -757,7 +622,8 @@ const productPlaybook = {
             },
         },
         rollout: {
-            description: `Roll the saved playbook \`id\` out across the product's devices in batches of body.batch_size (default 5), stopping when the failure rate reaches body.failure_threshold (percent, default ${DEFAULT_FAILURE_THRESHOLD}). Narrow it with body.group or body.filter; offline devices are skipped unless body.include_offline. body.dry_run lists plan and devices; body.check says what would change. Writes a report to playbooks/runs/ in the product storage. Changes real machines: confirm with the user and try it with run on one device first.`,
+            description: `Roll the saved playbook ids.playbook out across the product's devices in batches of body.batch_size (default 5), stopping when the failure rate reaches body.failure_threshold (percent, default ${DEFAULT_FAILURE_THRESHOLD}). Narrow it with body.group or body.filter; offline devices are skipped unless body.include_offline. body.dry_run lists plan and devices; body.check says what would change. Writes a report to playbooks/runs/ in the product storage. Changes real machines: it answers its plan (devices, batches) until confirmed; try it with run on one device first.`,
+            confirm: true,
             body: {
                 type: 'object',
                 properties: {
@@ -771,24 +637,46 @@ const productPlaybook = {
                     check: { type: 'boolean' },
                 },
             },
-            run(body, ctx) {
+            async run(body, ctx) {
                 const b = body && typeof body === 'object' ? body : {};
-                return toolProductPlaybookRollout({
-                    ...b,
-                    product: ctx.parent,
-                    name: ctx.id,
-                    user: ctx.user,
-                });
+                const args = { ...b, product: ctx.parent, name: ctx.id, user: ctx.user };
+                if (!b.dry_run && !b.check && !ctx.confirmed && ctx.plan) {
+                    return ctx.plan(
+                        rolloutPlan(await toolProductPlaybookRollout({ ...args, dry_run: true })),
+                    );
+                }
+                return toolProductPlaybookRollout(args);
             },
         },
     },
 };
 
-/** The YAML an action works on: body.content, or the saved playbook `id`. */
+/** The devices of a product (or of one of its groups) a run reaches, in words. */
+async function groupDevices(ctx, group) {
+    const filter = { product: ctx.parent, ...(group ? { asset_group: group } : {}) };
+    const ids = (await getDevices(filter, ctx.user)).map((d) => d.device);
+    const where = group ? `group "${group}" of product "${ctx.parent}"` : `product "${ctx.parent}"`;
+    return `every device of ${where} (${ids.length}${ids.length ? `: ${ids.join(', ')}` : ''})`;
+}
+
+/** What a rollout would do, from its dry run. */
+function rolloutPlan(dry) {
+    const text = dry?.content?.[0]?.text ?? '';
+    try {
+        const p = JSON.parse(text);
+        return `It would roll out the playbook "${p.name}" on ${p.device_count} device(s) of product "${p.product}" in batches of ${p.batch_size}, stopping at ${p.failure_threshold}% failures: ${(p.devices || []).join(', ')}. Steps: ${(p.steps || []).length}.`;
+    } catch {
+        return `It would roll out the playbook:\n${text}`;
+    }
+}
+
+/** The YAML an action works on: body.content, or the saved playbook ids.playbook. */
 async function playbookSource(body, ctx) {
     if (typeof body?.content === 'string' && body.content.trim()) return body.content;
     if (!ctx.id)
-        throw inputError('give the playbook: `id` (saved on the product) or body.content (YAML)');
+        throw inputError(
+            'give the playbook: ids.playbook (saved on the product) or body.content (YAML)',
+        );
     const entry = await findProductPlaybook(ctx.parent, ctx.id, ctx.user);
     if (!entry) {
         const names = (await listProductPlaybooks(ctx.parent, ctx.user)).map((e) => e.name);
@@ -806,17 +694,16 @@ export const resourceTypes = {
     device_fs: deviceFs,
     device_script: deviceScript,
     product_script: productScript,
-    product_metric: productMetric,
-    product_log_source: productLogSource,
     product_playbook: productPlaybook,
 };
 
 /** @type {Record<string, Record<string, LocalAction>>} */
 export const resourceActions = {
     device: {
+        exec: execAction,
         agent_update: {
             description:
-                'Check for a new version of the ThinRemote agent of device `id` (body {action: "check"}) or install it (body {action: "apply", channel?: "latest" | "main" | "develop"}).',
+                'Check for a new version of the ThinRemote agent of the device ids.device (body {action: "check"}) or install it (body {action: "apply", channel?: "latest" | "main" | "develop"}).',
             body: {
                 type: 'object',
                 properties: {

package/lib/playbook/actions.js

@@ -160,7 +160,7 @@ export const HANDLERS = {
         if (op !== 'check' && op !== 'apply') throw new Error('`op` must be "check" or "apply"');
         const payload = { action: op, channel: params.channel || 'latest' };
         // Agent updates can take a while. Give `apply` the same 5-min
-        // window the CLI's `thinr device update apply` uses.
+        // window the CLI's `thinr agent update` uses.
         const timeout =
             op === 'apply' ? TIMEOUTS.DEVICE_UPDATE_APPLY_MS : TIMEOUTS.DEVICE_RESOURCE_CALL_MS;
         const result = await ctx.api.callResource('update', payload, { timeout });

package/lib/playbook/schema.js

@@ -216,7 +216,7 @@ export const ACTION_BY_NAME = Object.fromEntries(ACTIONS.map((a) => [a.name, a])
 
 /**
  * JSON-shaped summary of the accepted playbook format. Consumed by the
- * MCP `thinr_playbook_schema` tool so an AI agent can author playbooks
+ * MCP's resource_describe of type `product_playbook` so an agent can author playbooks
  * that validate on the first try.
  */
 export function playbookSchema() {

package/lib/product/log-presets.js

@@ -115,7 +115,7 @@ export const LEVEL_SEVERITY = /** @type {Record<string, number>} */ ({
 
 /**
  * Return all presets as a sorted list. Used by `thinr product logs presets`
- * and by `thinr_resource_describe` type `product_log_source` (MCP).
+ * and by `thinr_resource_describe` type `product_property` (MCP).
  *
  * @returns {LogPreset[]}
  */

package/lib/product.js

@@ -374,6 +374,32 @@ function validateMetric(m) {
     }
 }
 
+/**
+ * The whole value of the `dashboard_metrics` property, as written through
+ * the resource tools: an array of metrics with unique names.
+ *
+ * @param {unknown} value
+ * @returns {any[]}
+ */
+export function validateDashboardMetrics(value) {
+    if (!Array.isArray(value)) {
+        throw inputError('dashboard_metrics must be an array of metrics');
+    }
+    const seen = new Set();
+    value.forEach((m, i) => {
+        try {
+            validateMetric(m);
+        } catch (e) {
+            throw inputError(`dashboard_metrics[${i}]: ${e.message}`);
+        }
+        if (seen.has(m.name)) {
+            throw inputError(`dashboard_metrics[${i}].name "${m.name}" is duplicated`);
+        }
+        seen.add(m.name);
+    });
+    return value;
+}
+
 async function loadMetricList(productId, user) {
     try {
         const value = await getProductProperty(productId, DASHBOARD_METRICS_PROPERTY, user);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@thinremote/thinr-cli",
-    "version": "1.5.0",
+    "version": "1.6.1",
     "description": "CLI for ThinRemote — remote management for IoT devices, with an MCP server for AI clients",
     "main": "bin/thinr.js",
     "bin": {
@@ -50,7 +50,7 @@
         "@inkjs/ui": "^2.0.0",
         "@inquirer/prompts": "^8.4.1",
         "@modelcontextprotocol/sdk": "^1.29.0",
-        "@thinger-io/cli-core": "^0.4.0",
+        "@thinger-io/cli-core": "^0.5.1",
         "axios": "^1.10.0",
         "chalk": "^5.4.1",
         "cli-progress": "^3.12.0",

package/commands/fleet/index.js

@@ -1,17 +0,0 @@
-// @ts-check
-import { registerUpgradeCommand } from './upgrade.js';
-
-/**
- * `thinr fleet <subcommand>` — operations that treat the whole device
- * fleet as the unit of work, not a single device. Today we only expose
- * `upgrade`; future fan-out commands (status summary, health probe,
- * rollback, etc.) would live alongside it.
- */
-export function fleetCommand(program) {
-    const fleet = program
-        .command('fleet')
-        .helpGroup('Operations:')
-        .description('Fleet-wide commands (run once, touch many devices)');
-
-    registerUpgradeCommand(fleet);
-}