@thinremote/thinr-cli 1.3.4 → 1.4.0

package/lib/identity.js

@@ -0,0 +1,75 @@
+// @ts-check
+
+/**
+ * Identity of the `thinr` CLI on top of @thinger-io/cli-core: its names,
+ * where its profiles live, the OAuth client registered for it on the
+ * ThinRemote servers, and the shape every ThinRemote product starts with.
+ *
+ * Profiles stay apart from the `thinger` CLI's (~/.config/thinger-cli,
+ * THINGER_*), so neither MCP server operates on the other's servers.
+ *
+ * @type {import('@thinger-io/cli-core/identity').CliIdentity}
+ */
+export const thinrIdentity = {
+    name: 'thinr',
+    displayName: 'ThinRemote',
+    description: 'CLI for ThinRemote - Remote management for IoT devices',
+    configDir: 'thinr-cli',
+    envPrefix: 'THINR',
+    token: { id: 'ThinRemote', name: 'ThinRemote' },
+    oauth: { clientId: '3b40164d28730e416cbd' },
+    defaultServer: 'console.thinr.io',
+    mcp: { serverName: 'thinr', toolPrefix: 'thinr' },
+    // ThinRemote products: `type: thinremote`, a Linux icon, and a
+    // `monitoring` bucket fed every 60 s from the agent's `monitoring`
+    // resource.
+    productTemplate: {
+        description: 'ThinRemote product',
+        config: {
+            type: 'thinremote',
+            icons: [
+                {
+                    conditions: [],
+                    icon: {
+                        type: 'fa',
+                        source: 'fab fa-linux',
+                        color: '#000000',
+                        background: '#ffffff',
+                    },
+                },
+            ],
+        },
+        profile: {
+            buckets: {
+                monitoring: {
+                    name: 'Monitoring Data',
+                    description: 'ThinRemote device metrics',
+                    enabled: true,
+                    backend: 'mongodb',
+                    data: {
+                        source: 'resource',
+                        resource: 'monitoring',
+                        update: 'interval',
+                        interval: 60,
+                        magnitude: 'second',
+                        payload: '{{payload}}',
+                        payload_function: '',
+                        payload_type: 'source_payload',
+                    },
+                    retention: { period: 3, unit: 'months' },
+                    tags: [],
+                },
+            },
+        },
+    },
+};
+
+/** Server-level guidance sent to MCP clients on `initialize`. */
+export const mcpInstructions = `Tools to operate ThinRemote fleets: machines running thinr-agent on a Thinger.io server, with the permissions of the token stored in the CLI profile.
+
+- Read the guide first: thinr_doc_read id "thinremote" (the agent, products, which tool for each need, recipes); thinr_doc_read without id lists the rest (scripts, playbooks, metrics and logs) and the server's own docs.
+- Almost everything is a resource type behind thinr_resource_list / _get / _create / _update / _delete / _call, described by thinr_resource_describe: the server's (device, product, bucket, token, alarm…) and ThinRemote's: device_fs (a device's files and folders, parent = the device), device_script, product_script, product_metric, product_log_source and product_playbook (parent = the product; actions validate, run and rollout). Actions on devices: agent_update, agent_install (the command that installs the agent).
+- Shell commands: thinr_device_exec, on one device or on several (devices, product, group, all).
+- Monitoring: live with thinr_device_resource_call resource "monitoring"; history with thinr_bucket_data_read bucket "monitoring" (device for one), stored only for devices of products that have that bucket (ThinRemote products do).
+- List before acting to discover ids; never guess them. Fleet changes (thinr_device_exec on several devices, playbook rollouts) and deletes act immediately: confirm with the user first.
+- Every tool takes an optional \`profile\` (another configured server, see thinr_profile_list) and most take \`user\` (another account, admin only).`;

package/lib/local-files.js

@@ -0,0 +1,54 @@
+// @ts-check
+import { existsSync, lstatSync, realpathSync } from 'fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'path';
+import { inputError } from '@thinger-io/cli-core/errors';
+
+/**
+ * Files of the machine running the MCP server, as a model names them for a
+ * push or a pull: kept inside one folder, so a prompt injected through a
+ * device (a log line, a file) cannot have the model send ~/.ssh away or
+ * overwrite a shell profile. The folder is THINR_MCP_LOCAL_DIR, or the
+ * folder the server was started in.
+ */
+export function mcpLocalRoot() {
+    return resolve(process.env.THINR_MCP_LOCAL_DIR || process.cwd());
+}
+
+const inside = (root, path) => {
+    const rel = relative(root, path);
+    return rel === '' || (!rel.startsWith('..') && !isAbsolute(rel) && !rel.startsWith(`..${sep}`));
+};
+
+const outside = (path, root) =>
+    inputError(
+        `${path} is outside ${root}, the only folder of this machine the MCP server reads and writes (THINR_MCP_LOCAL_DIR changes it)`,
+    );
+
+/** A file to read (push): it must exist inside the root, links resolved. */
+export function localFileToRead(path, root = mcpLocalRoot()) {
+    const realRoot = realpathSync(root);
+    const wanted = resolve(realRoot, path);
+    if (!existsSync(wanted)) throw inputError(`No local file ${wanted}`);
+    const real = realpathSync(wanted);
+    if (!inside(realRoot, real)) throw outside(real, realRoot);
+    return real;
+}
+
+/**
+ * A file to write (pull): its folder inside the root, links resolved; an
+ * existing file only replaced when asked, and never through a link.
+ */
+export function localFileToWrite(path, root = mcpLocalRoot(), { overwrite = false } = {}) {
+    const realRoot = realpathSync(root);
+    const wanted = resolve(realRoot, path);
+    const dir = dirname(wanted);
+    if (!existsSync(dir)) throw inputError(`No local folder ${dir}`);
+    const target = resolve(realpathSync(dir), wanted.slice(dir.length + 1));
+    if (!inside(realRoot, target)) throw outside(target, realRoot);
+    if (existsSync(target)) {
+        if (lstatSync(target).isSymbolicLink())
+            throw inputError(`${target} is a link: not written`);
+        if (!overwrite) throw inputError(`${target} exists: pass overwrite to replace it`);
+    }
+    return target;
+}

package/lib/mcp/{tools-install.js → agent-install.js}

@@ -1,6 +1,6 @@
 // @ts-check
-import { requireConfig } from '../config.js';
-import { inputError } from '../errors.js';
+import { requireConfig } from '@thinger-io/cli-core/config';
+import { inputError } from '@thinger-io/cli-core/errors';
 
 const CHANNEL_SCRIPT = {
     latest: 'install.sh',
@@ -24,7 +24,14 @@ function decodeJwtClaims(token) {
     }
 }
 
-async function toolAgentInstallCommand(args) {
+/**
+ * The command that installs the agent on a new machine: the `agent_install`
+ * action of the `device` type (see resource-types.js).
+ *
+ * @param {{ device?: string, product?: string, channel?: string, sudo?: boolean,
+ *   overwrite?: boolean, no_start?: boolean, no_verify_ssl?: boolean, http?: boolean }} args
+ */
+export async function agentInstallCommand(args) {
     // requireConfig throws `not_configured` if there's no active profile
     // with a token — classifyError in server.js surfaces that cleanly.
     const config = requireConfig();
@@ -41,7 +48,7 @@ async function toolAgentInstallCommand(args) {
     const url = `${scheme}://get.thinremote.io/${script}`;
 
     const agentArgs = ['install', '--token', shQuote(config.token)];
-    if (args.device_id) agentArgs.push('--device', shQuote(args.device_id));
+    if (args.device) agentArgs.push('--device', shQuote(args.device));
     if (args.product) agentArgs.push('--product', shQuote(args.product));
     if (args.overwrite) agentArgs.push('--overwrite');
     if (args.no_start) agentArgs.push('--no-start');
@@ -92,61 +99,5 @@ async function toolAgentInstallCommand(args) {
         sections.push('', 'Warnings:', ...warnings.map((w) => `- ${w}`));
     }
 
-    return {
-        content: [{ type: 'text', text: sections.join('\n') }],
-        isError: false,
-    };
+    return sections.join('\n');
 }
-
-export const tools = [
-    {
-        name: 'thinr_agent_install_command',
-        description:
-            "Generate a one-liner shell command that installs thinr-agent on a remote host using the active profile's token for auto-provisioning. Meant to be run on the target machine (directly or piped through `ssh`). The token is embedded verbatim, so only share the output through trusted channels.",
-        inputSchema: {
-            type: 'object',
-            properties: {
-                device_id: {
-                    type: 'string',
-                    description:
-                        "Custom device identifier. Omit to let the agent default to the target host's hostname.",
-                },
-                product: {
-                    type: 'string',
-                    description:
-                        'Product to associate the device with. Omit to auto-detect or create the default product.',
-                },
-                overwrite: {
-                    type: 'boolean',
-                    description:
-                        'Auto-overwrite an existing device with the same id on the server.',
-                },
-                no_start: {
-                    type: 'boolean',
-                    description: 'Install the service but do not start it.',
-                },
-                no_verify_ssl: {
-                    type: 'boolean',
-                    description: 'Disable TLS certificate verification (for self-signed servers).',
-                },
-                channel: {
-                    type: 'string',
-                    enum: ['latest', 'main', 'develop'],
-                    description: 'Release channel. Defaults to `latest` (stable).',
-                },
-                sudo: {
-                    type: 'boolean',
-                    description:
-                        'Pipe into `sudo sh` instead of `sh`. Needed on Linux hosts when running as a non-root user, since installing the systemd service writes under /etc.',
-                },
-                http: {
-                    type: 'boolean',
-                    description:
-                        'Use http://get.thinremote.io instead of https (for devices without working HTTPS).',
-                },
-            },
-            required: [],
-        },
-        handler: toolAgentInstallCommand,
-    },
-];

package/lib/mcp/helpers.js

@@ -1,34 +1,14 @@
 // @ts-check
 import { createDeviceAPI } from '../device-api.js';
-import { getActiveProfile, getProfile, setActiveProfile } from '../config.js';
-import { setBaseURL } from '../api.js';
-import { inputError } from '../errors.js';
+import { inputError } from '@thinger-io/cli-core/errors';
+import { toolName } 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 thinr_devices to list available devices.');
+        throw inputError(
+            `device is required. Use ${toolName('resource_list')} (type "device") to list available devices.`,
+        );
     return { api: createDeviceAPI(device, { user: user || undefined }), device };
 }
-
-/** Run `fn` with the active profile temporarily switched to `profile`
- *  (when supplied) so callers can target any configured environment per
- *  tool call without persisting the change. */
-export async function withProfile(profile, fn) {
-    if (!profile) return fn();
-    const previous = getActiveProfile();
-    const target = getProfile(profile);
-    if (!target) {
-        throw inputError(`Unknown profile: ${profile}. Use thinr_profiles to list available ones.`);
-    }
-    setActiveProfile(profile);
-    if (target.server) setBaseURL(`https://${target.server}`);
-    try {
-        return await fn();
-    } finally {
-        setActiveProfile(previous);
-        const restore = previous ? getProfile(previous) : null;
-        if (restore?.server) setBaseURL(`https://${restore.server}`);
-    }
-}

package/lib/mcp/playbook-ops.js

@@ -0,0 +1,393 @@
+// @ts-check
+import {
+    findProductPlaybook,
+    listProductPlaybooks,
+    readProductPlaybook,
+    uploadFleetRunReport,
+} from '../product.js';
+import { requireConfig } from '@thinger-io/cli-core/config';
+import { filterActiveDevices, getDevices } from '@thinger-io/cli-core/devices';
+import { inputError } from '@thinger-io/cli-core/errors';
+import { parsePlaybook } from '../playbook/loader.js';
+import { buildDryRunPlan, resolveTargets, runPlaybook } from '../playbook/runner.js';
+import { DEFAULT_FAILURE_THRESHOLD, runFleetPlaybook } from '../playbook/fleet.js';
+import { playbookSchema } from '../playbook/schema.js';
+import { listVariables, resolveVarScope } from '../playbook/vars.js';
+import { mcpLocalRoot } from '../local-files.js';
+
+/**
+ * Validating, running and rolling out playbooks: the actions of the
+ * `product_playbook` resource type (see resource-types.js). Each takes the
+ * arguments of the tools they used to be and answers a whole tool result,
+ * flagged as an error when a device did not complete.
+ */
+
+export { DEFAULT_FAILURE_THRESHOLD, playbookSchema };
+
+export async function toolPlaybookValidate(args) {
+    if (typeof args.content !== 'string' || !args.content.trim()) {
+        throw inputError('content (YAML playbook source) is required');
+    }
+    try {
+        const pb = parsePlaybook(args.content);
+        const summary = {
+            valid: true,
+            name: pb.name,
+            description: pb.description,
+            target: pb.target,
+            steps: pb.steps.map((s) => ({ name: s.name, action: s.action })),
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+            isError: false,
+        };
+    } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            content: [{ type: 'text', text: msg }],
+            isError: true,
+            _meta: { code: 'input_error', message: msg },
+        };
+    }
+}
+
+export async function toolPlaybookRun(args) {
+    if (typeof args.content !== 'string' || !args.content.trim()) {
+        throw inputError('content (YAML playbook source) is required');
+    }
+    const pb = parsePlaybook(args.content);
+    if (args.target_product) pb.target.product = args.target_product;
+    if (args.target_group) pb.target.group = args.target_group;
+    // The whole product (or one of its groups), whatever devices the YAML lists.
+    if (args.target_all) pb.target.devices = null;
+    if (Array.isArray(args.target_devices) && args.target_devices.length) {
+        pb.target.devices = args.target_devices;
+        pb.target.group = null;
+    }
+    if (Number.isInteger(args.concurrency) && args.concurrency > 0) {
+        pb.target.concurrency = args.concurrency;
+    }
+    if (typeof args.fail_fast === 'boolean') pb.target.fail_fast = args.fail_fast;
+    // Overrides are checked against what the playbook declares (unknown,
+    // not overridable, wrong type, required and missing) before anything
+    // runs, as for saved playbooks.
+    const rawVars =
+        args.vars && typeof args.vars === 'object' && !Array.isArray(args.vars) ? args.vars : {};
+    let resolvedScope;
+    try {
+        resolvedScope = resolveVarScope(pb, rawVars);
+    } catch (err) {
+        throw inputError(err.message);
+    }
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb, { overrides: rawVars });
+        const out = {
+            dry_run: true,
+            name: pb.name,
+            target: pb.target,
+            vars: resolvedScope,
+            steps: plan,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(out, null, 2) }],
+            isError: false,
+        };
+    }
+
+    const devices = await resolveTargets(pb, { user: args.user });
+    if (devices.length === 0) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `No devices match the playbook target (product="${pb.target.product}"${pb.target.group ? `, group="${pb.target.group}"` : ''}).`,
+                },
+            ],
+            isError: false,
+        };
+    }
+
+    const checkMode = !!args.check;
+    const results = await runPlaybook(pb, devices, {
+        user: args.user,
+        overrides: rawVars,
+        localRoot: mcpLocalRoot(),
+        concurrency: pb.target.concurrency,
+        failFast: pb.target.fail_fast,
+        checkMode,
+        continueOnError: !!args.continue_on_error,
+    });
+
+    const okCount = results.filter((r) => r.ok).length;
+    let verdicts;
+    if (checkMode) {
+        verdicts = { changed: 0, unchanged: 0, unknown: 0 };
+        for (const r of results) {
+            for (const s of r.steps) {
+                if (s.verdict && s.verdict in verdicts) verdicts[s.verdict] += 1;
+            }
+        }
+    }
+    const summary = {
+        name: pb.name,
+        target: pb.target,
+        mode: checkMode ? 'check' : 'apply',
+        total: results.length,
+        ok: okCount,
+        failed: results.length - okCount,
+        ...(verdicts ? { verdicts } : {}),
+        results,
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(summary, null, 2) }],
+        isError: okCount < results.length,
+    };
+}
+
+export async function toolProductPlaybookRun(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    if (!args.device_id) throw inputError('device is required (single-device only)');
+
+    const entry = await findProductPlaybook(args.product, args.name, args.user);
+    if (!entry) {
+        const available = await listProductPlaybooks(args.product, args.user);
+        throw inputError(
+            `Playbook "${args.name}" is not registered on product "${args.product}". Available: ${available.map((e) => e.name).join(', ') || '(none)'}`,
+        );
+    }
+
+    const content = await readProductPlaybook(args.product, args.name, args.user);
+    const pb = parsePlaybook(content, { sourcePath: `${args.name}.yaml` });
+
+    const rawVars =
+        args.vars && typeof args.vars === 'object' && !Array.isArray(args.vars) ? args.vars : {};
+
+    let resolvedScope;
+    try {
+        resolvedScope = resolveVarScope(pb, rawVars);
+    } catch (err) {
+        throw inputError(err.message);
+    }
+
+    pb.target.devices = [args.device_id];
+    pb.target.product = args.product;
+    pb.target.group = null;
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb, { overrides: rawVars });
+        const payload = {
+            dry_run: true,
+            product: args.product,
+            name: args.name,
+            device: args.device_id,
+            variables: listVariables(pb),
+            vars: resolvedScope,
+            steps: plan,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    const all = await getDevices({ product: args.product }, args.user);
+    const device = all.find((d) => d.device === args.device_id) || {
+        device: args.device_id,
+        connection: { active: false },
+    };
+
+    const results = await runPlaybook(pb, [device], {
+        localRoot: mcpLocalRoot(),
+        user: args.user,
+        concurrency: 1,
+        failFast: true,
+        checkMode: !!args.check,
+        overrides: rawVars,
+    });
+    const result = results[0];
+    const payload = {
+        product: args.product,
+        name: args.name,
+        device: args.device_id,
+        mode: args.check ? 'check' : 'apply',
+        ok: !!result?.ok,
+        result,
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: !result?.ok,
+    };
+}
+
+export async function toolProductPlaybookRollout(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+
+    const batchSize =
+        Number.isFinite(args.batch_size) && args.batch_size > 0 ? Math.floor(args.batch_size) : 5;
+    const failureThreshold =
+        args.failure_threshold === undefined || args.failure_threshold === null
+            ? DEFAULT_FAILURE_THRESHOLD
+            : Number(args.failure_threshold);
+    if (!Number.isFinite(failureThreshold) || failureThreshold < 0 || failureThreshold > 100) {
+        throw inputError('failure_threshold must be a number between 0 and 100');
+    }
+
+    const entry = await findProductPlaybook(args.product, args.name, args.user);
+    if (!entry) {
+        const available = await listProductPlaybooks(args.product, args.user);
+        throw inputError(
+            `Playbook "${args.name}" is not registered on product "${args.product}". Available: ${available.map((e) => e.name).join(', ') || '(none)'}`,
+        );
+    }
+
+    const content = await readProductPlaybook(args.product, args.name, args.user);
+    const pb = parsePlaybook(content, { sourcePath: `${args.name}.yaml` });
+
+    const rawVars =
+        args.vars && typeof args.vars === 'object' && !Array.isArray(args.vars) ? args.vars : {};
+
+    let resolvedScope;
+    try {
+        resolvedScope = resolveVarScope(pb, rawVars);
+    } catch (err) {
+        throw inputError(err.message);
+    }
+
+    const filters = {};
+    if (args.filter && typeof args.filter === 'object' && !Array.isArray(args.filter)) {
+        for (const [k, v] of Object.entries(args.filter)) {
+            if (!/^[A-Za-z0-9_]+$/.test(k)) {
+                throw inputError(`Invalid filter key "${k}"`);
+            }
+            filters[k] = v;
+        }
+    }
+
+    const baseFilter = { product: args.product };
+    if (args.group) baseFilter.asset_group = args.group;
+    Object.assign(baseFilter, filters);
+    let devices = await getDevices(baseFilter, args.user);
+    if (!args.include_offline) devices = filterActiveDevices(devices);
+
+    pb.target.devices = null;
+    pb.target.product = args.product;
+    pb.target.group = args.group || null;
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb, { overrides: rawVars });
+        const payload = {
+            dry_run: true,
+            product: args.product,
+            name: args.name,
+            fleet: true,
+            device_count: devices.length,
+            devices: devices.map((d) => d.device),
+            batch_size: batchSize,
+            failure_threshold: failureThreshold,
+            variables: listVariables(pb),
+            vars: resolvedScope,
+            steps: plan,
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    if (devices.length === 0) {
+        const payload = {
+            product: args.product,
+            name: args.name,
+            fleet: true,
+            device_count: 0,
+            aborted: false,
+            summary: { attempted: 0, succeeded: 0, failed: 0, failureRate: 0 },
+            message: 'no matching devices',
+        };
+        return {
+            content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            isError: false,
+        };
+    }
+
+    const startedAt = new Date().toISOString();
+    const outcome = await runFleetPlaybook(pb, devices, {
+        localRoot: mcpLocalRoot(),
+        user: args.user,
+        batchSize,
+        failureThreshold,
+        overrides: rawVars,
+        checkMode: !!args.check,
+    });
+    const finishedAt = new Date().toISOString();
+
+    const summary = {
+        attempted: outcome.attempted,
+        succeeded: outcome.succeeded,
+        failed: outcome.failed,
+        failureRate: outcome.failureRate,
+        total: devices.length,
+    };
+
+    const report = {
+        product: args.product,
+        name: args.name,
+        user: args.user || requireConfig().username,
+        startedAt,
+        finishedAt,
+        durationMs: new Date(finishedAt).getTime() - new Date(startedAt).getTime(),
+        mode: args.check ? 'check' : 'apply',
+        playbook: {
+            name: pb.name || null,
+            description: pb.description || null,
+            steps: pb.steps.length,
+        },
+        rollout: {
+            batchSize,
+            failureThreshold,
+            filters: Object.keys(filters).length > 0 ? filters : null,
+            group: args.group || null,
+            includeOffline: !!args.include_offline,
+        },
+        vars: resolvedScope,
+        summary,
+        aborted: outcome.aborted,
+        reason: outcome.reason,
+        batches: outcome.batches,
+        devices: outcome.results.map((r) => ({
+            device: r?.device,
+            ok: !!r?.ok,
+            skipped: !!r?.skipped,
+            error: r?.error || null,
+        })),
+    };
+
+    const upload = await uploadFleetRunReport({ product: args.product, report, user: args.user });
+
+    const payload = {
+        product: args.product,
+        name: args.name,
+        fleet: true,
+        mode: args.check ? 'check' : 'apply',
+        startedAt,
+        finishedAt,
+        batch_size: batchSize,
+        failure_threshold: failureThreshold,
+        device_count: devices.length,
+        batches: outcome.batches,
+        summary,
+        aborted: outcome.aborted,
+        reason: outcome.reason,
+        results: outcome.results,
+        report_uploaded: upload.ok,
+        report_path: upload.ok ? upload.path : null,
+        report_error: upload.ok ? null : upload.reason,
+    };
+    return {
+        content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+        isError: outcome.aborted || summary.failed > 0,
+    };
+}