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

package/lib/mcp/tools-logs.js

@@ -0,0 +1,225 @@
+// @ts-check
+import {
+    addLogSource,
+    getProductLogs,
+    listPresets,
+    removeLogSource,
+    setDefaultLogSource,
+} from '../product/logs.js';
+import { inputError } from '../errors.js';
+
+function truncate(value, max = 80) {
+    if (typeof value !== 'string') return '';
+    return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+
+async function toolProductLogsList(args) {
+    if (!args.product) throw inputError('product is required');
+    const cfg = await getProductLogs(args.product, args.user);
+    const fallback = !!(/** @type {any} */ (cfg).__fallback);
+    const def = cfg.default || cfg.sources[0]?.name || null;
+    const lines = cfg.sources.map((s) => {
+        const tag = s.name === def ? '★' : ' ';
+        return `  ${tag} ${s.name}  →  ${truncate(s.command)}`;
+    });
+    const header = fallback
+        ? `Product "${args.product}" has no logs property — showing the synthetic fallback (${cfg.sources.length} source):`
+        : `${cfg.sources.length} log source(s) on "${args.product}" (default: ${def}):`;
+    return {
+        content: [{ type: 'text', text: [header, ...lines].join('\n') }],
+        isError: false,
+    };
+}
+
+async function toolProductLogsAdd(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    if (typeof args.command !== 'string' || args.command.trim() === '') {
+        throw inputError('command is required (non-empty string)');
+    }
+    const { config, action } = await addLogSource(
+        args.product,
+        {
+            name: args.name,
+            command: args.command,
+            makeDefault: !!args.default,
+            pattern: args.pattern,
+            preset: args.preset,
+        },
+        args.user,
+    );
+    const def = config.default || config.sources[0]?.name || null;
+    const lines = [
+        `${action === 'added' ? 'Added' : 'Updated'} source "${args.name}" on product "${args.product}"${
+            args.default ? ' (default)' : ''
+        }.`,
+        `Command: ${truncate(args.command, 120)}`,
+    ];
+    if (args.preset) lines.push(`Preset: ${args.preset}`);
+    if (args.pattern) lines.push(`Pattern: ${truncate(args.pattern, 120)}`);
+    lines.push(`Sources: ${config.sources.length}${def ? `, default: ${def}` : ''}`);
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        isError: false,
+    };
+}
+
+async function toolProductLogsPresets() {
+    const presets = listPresets();
+    const lines = [
+        `${presets.length} log line preset(s) shipped with the CLI:`,
+        ...presets.map((p) => `  · ${p.name} — ${p.description}`),
+    ];
+    return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        isError: false,
+    };
+}
+
+async function toolProductLogsRemove(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    const { removed, config } = await removeLogSource(args.product, args.name, args.user);
+    if (!removed) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Source "${args.name}" was not configured on product "${args.product}".`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    if (config === null) {
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Removed last source "${args.name}" from product "${args.product}". Logs property cleared — falls back to the system journal.`,
+                },
+            ],
+            isError: false,
+        };
+    }
+    const def = config.default || config.sources[0]?.name || null;
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Removed source "${args.name}" from product "${args.product}". ${config.sources.length} source(s) remain${def ? `, default: ${def}` : ''}.`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+async function toolProductLogsSetDefault(args) {
+    if (!args.product) throw inputError('product is required');
+    if (!args.name) throw inputError('name is required');
+    const config = await setDefaultLogSource(args.product, args.name, args.user);
+    return {
+        content: [
+            {
+                type: 'text',
+                text: `Default log source set to "${config.default}" on product "${args.product}".`,
+            },
+        ],
+        isError: false,
+    };
+}
+
+export const tools = [
+    {
+        name: 'thinr_product_logs_list',
+        description: `List the log sources configured on a product. Each source pairs a slug-ish \`name\` (visible to operators) with a \`command\` the agent will exec-stream when that source is selected. The default source — used when callers do not pick explicitly — is highlighted with a ★. When the product has no \`logs\` property yet, returns a synthetic fallback with a single \`system\` source running journalctl, matching the dashboard's pre-feature behaviour. Pair with thinr_product_logs_add to populate, thinr_product_logs_set_default to pick which one comes up first, or thinr_product_logs_remove to drop entries.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product'],
+        },
+        handler: toolProductLogsList,
+    },
+    {
+        name: 'thinr_product_logs_add',
+        description: `Upsert a log source on a product: adds a new entry if \`name\` is unused, replaces the command in place when it already exists. The command is an opaque shell string the agent will exec-stream as-is when the dashboard or CLI selects this source — there is no protocol indirection, no special log "kind". Use it to expose journalctl unit tails, container log streams (\`docker logs -f thinger\`), application log files (\`tail -F /var/log/app.log\`), or any other follow-style command relevant to the device fleet.
+
+Set \`default: true\` to mark this source as the active default; the previous default is preserved otherwise (or, on a fresh product, no default is recorded so consumers fall back to the first source). Names are slug-ish (letters, digits, underscore, dash; ≤ 32 chars). Up to 32 sources per product. The product does not need to exist on the agent — the configuration lives entirely server-side.
+
+Optionally attach a \`pattern\` (regex with named groups \`time\`, \`level\`, \`msg\`) or a \`preset\` (named pattern shipped with the CLI; see thinr_product_logs_presets) to enable structured rendering in the dashboard. When the pattern captures a \`level\` group, the operator can filter the panel by severity (info+/warn+/error+). \`pattern\` and \`preset\` are mutually exclusive; omit both to keep the source rendered raw.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: {
+                    type: 'string',
+                    description:
+                        'Stable identifier for the source (letters, digits, underscore, dash; ≤ 32 chars). Reusing the name updates the existing entry.',
+                },
+                command: {
+                    type: 'string',
+                    description:
+                        'Shell command the agent should exec-stream when this source is selected (e.g. "journalctl --no-pager --output=short -f", "docker logs -f thinger", "tail -F /var/log/nginx/access.log"). Stored verbatim.',
+                },
+                default: {
+                    type: 'boolean',
+                    description:
+                        'Mark this source as the active default (default: false). When false the previous default is preserved.',
+                },
+                pattern: {
+                    type: 'string',
+                    description:
+                        'Custom regex with named groups (time, level, msg) for structured rendering in the dashboard. Mutually exclusive with `preset`. Validated to compile at config time.',
+                },
+                preset: {
+                    type: 'string',
+                    description:
+                        'Named preset for structured rendering (e.g. "spdlog", "journalctl", "nginx-error"). Use thinr_product_logs_presets to list available names. Mutually exclusive with `pattern`.',
+                },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name', 'command'],
+        },
+        handler: toolProductLogsAdd,
+    },
+    {
+        name: 'thinr_product_logs_remove',
+        description: `Remove a log source by name from a product. When the removed entry was the default, the default is dropped (consumers will fall back to the first remaining source). When the last source is removed, the entire \`logs\` property is deleted so the product reverts to the synthetic fallback. Idempotent — calling it on a missing source reports success without erroring.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: { type: 'string', description: 'Source name previously registered.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductLogsRemove,
+    },
+    {
+        name: 'thinr_product_logs_presets',
+        description: `List the named log line patterns shipped with the CLI. Each preset bundles a regex with named groups (\`time\`, \`level\`, \`msg\`) tuned for a common log format (journalctl short, spdlog, nginx access/error). Use the preset name with thinr_product_logs_add via the \`preset\` argument to enable structured rendering and level-based filtering on a source without typing the regex by hand.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+        handler: toolProductLogsPresets,
+    },
+    {
+        name: 'thinr_product_logs_set_default',
+        description: `Set the active default log source on a product. The named source must already exist (use thinr_product_logs_add first). The default is what the dashboard surfaces first when an operator opens a device, and what \`thinr device logs <id>\` resolves to when no \`--source\` flag is passed. To clear the default, remove the matching source with thinr_product_logs_remove.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                product: { type: 'string', description: 'Product ID.' },
+                name: { type: 'string', description: 'Source name to mark as default.' },
+                user: { type: 'string', description: 'API user' },
+            },
+            required: ['product', 'name'],
+        },
+        handler: toolProductLogsSetDefault,
+    },
+];

package/lib/mcp/tools-playbook.js

@@ -0,0 +1,211 @@
+// @ts-check
+import { parsePlaybook } from '../playbook/loader.js';
+import { buildDryRunPlan, resolveTargets, runPlaybook } from '../playbook/runner.js';
+import { playbookSchema } from '../playbook/schema.js';
+import { inputError } from '../errors.js';
+
+async function toolPlaybookSchema() {
+    const schema = playbookSchema();
+    return {
+        content: [{ type: 'text', text: JSON.stringify(schema, null, 2) }],
+        isError: false,
+    };
+}
+
+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 },
+        };
+    }
+}
+
+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;
+    if (Array.isArray(args.target_devices) && args.target_devices.length) {
+        pb.target.devices = args.target_devices;
+    }
+    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;
+    if (args.vars && typeof args.vars === 'object') {
+        pb.vars = { ...pb.vars, ...args.vars };
+    }
+
+    if (args.dry_run) {
+        const plan = buildDryRunPlan(pb);
+        const out = {
+            dry_run: true,
+            name: pb.name,
+            target: pb.target,
+            vars: pb.vars,
+            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,
+        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 const tools = [
+    {
+        name: 'thinr_playbook_schema',
+        description: `Return the JSON schema a ThinR playbook document must follow: accepted top-level fields, the target block, the \`vars\` block (plain and extended forms with \`default\` / \`description\` / \`type\` / \`overridable\` / \`required\`), the variable substitution syntax, and the full catalogue of step actions with their parameters. Call this ONCE at the start of any authoring session — whether the user is asking for a one-shot local playbook (\`thinr_playbook_run\`) or a persistent product playbook (\`thinr_product_playbook_write\`) — so the generated YAML validates on the first try.`,
+        inputSchema: {
+            type: 'object',
+            properties: {},
+            required: [],
+        },
+        handler: toolPlaybookSchema,
+    },
+    {
+        name: 'thinr_playbook_validate',
+        description: `Parse and validate a playbook document without running it or uploading it. Returns a structured summary (name, description, target, step list) on success, or a consolidated error message listing every issue. Use this while drafting YAML from a natural-language request: write, call validate, fix the reported errors, repeat — then hand the final content to thinr_product_playbook_write (persistent) or thinr_playbook_run (one-shot). Never upload YAML that hasn't validated cleanly; thinr_product_playbook_write will re-validate and reject invalid documents, but running validate during iteration keeps the loop tight without touching product storage.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'Full YAML source of the playbook.',
+                },
+            },
+            required: ['content'],
+        },
+        handler: toolPlaybookValidate,
+    },
+    {
+        name: 'thinr_playbook_run',
+        description: `Run a playbook (YAML source passed inline) against the product / devices declared in its target block. Optional overrides let you retarget a saved playbook without editing it. Set \`dry_run: true\` to get the execution plan without touching any device.
+
+Response carries a consolidated report: devices visited, ok / failed counts, and per-device step outcomes (summary, duration, error message if any). \`isError\` is true whenever any device didn't complete every step cleanly, so clients can branch on a single flag.`,
+        inputSchema: {
+            type: 'object',
+            properties: {
+                content: {
+                    type: 'string',
+                    description: 'Full YAML source of the playbook.',
+                },
+                dry_run: {
+                    type: 'boolean',
+                    description:
+                        'Return the static plan without contacting devices (default: false).',
+                },
+                check: {
+                    type: 'boolean',
+                    description:
+                        'Contact devices read-only and report what each step would change, without writing. Each step verdict is one of "changed" / "unchanged" / "unknown". Actions that can\'t be predicted safely (exec, resource) always return "unknown".',
+                },
+                target_product: {
+                    type: 'string',
+                    description: 'Override the playbook\'s target.product.',
+                },
+                target_group: {
+                    type: 'string',
+                    description: 'Override the playbook\'s target.group.',
+                },
+                target_devices: {
+                    type: 'array',
+                    description: 'Override the playbook\'s target.devices with an explicit list.',
+                },
+                concurrency: {
+                    type: 'number',
+                    description: 'Override max parallel devices.',
+                },
+                fail_fast: {
+                    type: 'boolean',
+                    description:
+                        'Stop dequeueing new devices on the first failure (default: playbook\'s own value).',
+                },
+                continue_on_error: {
+                    type: 'boolean',
+                    description:
+                        'Keep running subsequent steps on a device even if one step fails (default: false — a failing step stops that device).',
+                },
+                vars: {
+                    type: 'object',
+                    description:
+                        'Merge into the playbook\'s `vars` block before substitution.',
+                },
+                user: {
+                    type: 'string',
+                    description: 'API user (admin impersonation).',
+                },
+            },
+            required: ['content'],
+        },
+        handler: toolPlaybookRun,
+    },
+];