@thinremote/thinr-cli 1.1.0 → 1.2.0

package/lib/playbook/schema.js

@@ -0,0 +1,209 @@
+// @ts-check
+
+/**
+ * Catalogue of playbook actions the runner knows how to execute.
+ *
+ * Each entry declares the parameters it accepts (name, type, required
+ * flag, human description). The runner uses this for validation, the
+ * MCP surface uses it to advertise what playbooks can do, and the CLI
+ * uses it for dry-run labels and error messages.
+ *
+ * Action handlers live in ./actions.js; names must match.
+ *
+ * @typedef {{ name: string, type: 'string' | 'number' | 'boolean' | 'object', required?: boolean, description: string }} ParamSpec
+ * @typedef {{ name: string, description: string, params: ParamSpec[], summary: (params: Record<string, unknown>) => string }} ActionSpec
+ */
+
+/** @type {ActionSpec[]} */
+export const ACTIONS = [
+    {
+        name: 'exec',
+        description: 'Run a shell command on the device and fail the step on non-zero exit.',
+        params: [
+            { name: 'command', type: 'string', required: true, description: 'Shell command to run.' },
+            { name: 'timeout', type: 'number', description: 'Per-device timeout in seconds (default: 30).' },
+        ],
+        summary: (p) => `exec: ${p.command}`,
+    },
+    {
+        name: 'sleep',
+        description: 'Pause execution for the given number of seconds before the next step.',
+        params: [
+            { name: 'seconds', type: 'number', required: true, description: 'Seconds to sleep.' },
+        ],
+        summary: (p) => `sleep ${p.seconds}s`,
+    },
+    {
+        name: 'write',
+        description: 'Write inline content to a file on the device. Use `push` to upload a local file instead.',
+        params: [
+            { name: 'path', type: 'string', required: true, description: 'Absolute path on the device.' },
+            { name: 'content', type: 'string', required: true, description: 'Inline content to write.' },
+        ],
+        summary: (p) => `write ${p.path}`,
+    },
+    {
+        name: 'push',
+        description: 'Upload a local file to the device.',
+        params: [
+            { name: 'source', type: 'string', required: true, description: 'Local file path (relative paths resolve against the playbook directory).' },
+            { name: 'destination', type: 'string', required: true, description: 'Absolute path on the device.' },
+        ],
+        summary: (p) => `push ${p.source} → ${p.destination}`,
+    },
+    {
+        name: 'pull',
+        description: 'Download a remote file from the device to the local disk.',
+        params: [
+            { name: 'source', type: 'string', required: true, description: 'Absolute path on the device.' },
+            { name: 'destination', type: 'string', required: true, description: 'Local file path (relative paths resolve against the playbook directory).' },
+        ],
+        summary: (p) => `pull ${p.source} → ${p.destination}`,
+    },
+    {
+        name: 'rm',
+        description: 'Remove a file or directory on the device.',
+        params: [
+            { name: 'path', type: 'string', required: true, description: 'Absolute path on the device.' },
+            { name: 'recursive', type: 'boolean', description: 'Recurse into directories (default: true).' },
+        ],
+        summary: (p) => `rm ${p.path}`,
+    },
+    {
+        name: 'mkdir',
+        description: 'Create a directory on the device.',
+        params: [
+            { name: 'path', type: 'string', required: true, description: 'Absolute directory path on the device.' },
+        ],
+        summary: (p) => `mkdir ${p.path}`,
+    },
+    {
+        name: 'mv',
+        description: 'Move or rename a path on the device. Handy for atomic deploys (write to tmp, mv into place).',
+        params: [
+            { name: 'source', type: 'string', required: true, description: 'Path to move from.' },
+            { name: 'destination', type: 'string', required: true, description: 'Target path.' },
+            { name: 'overwrite', type: 'boolean', description: 'Overwrite destination if it exists (default: false).' },
+        ],
+        summary: (p) => `mv ${p.source} → ${p.destination}`,
+    },
+    {
+        name: 'property_set',
+        description: 'Create or overwrite a device property.',
+        params: [
+            { name: 'property', type: 'string', required: true, description: 'Property name.' },
+            { name: 'value', type: 'object', required: true, description: 'Any JSON-serialisable value.' },
+        ],
+        summary: (p) => `property_set ${p.property}`,
+    },
+    {
+        name: 'resource',
+        description: 'Invoke a device resource. Inputs are forwarded as the resource payload.',
+        params: [
+            { name: 'resource', type: 'string', required: true, description: 'Resource name.' },
+            { name: 'inputs', type: 'object', description: 'Resource inputs (omit for read-only resources).' },
+        ],
+        summary: (p) => `resource ${p.resource}`,
+    },
+    {
+        name: 'update',
+        description: 'Check for or apply an agent update.',
+        params: [
+            { name: 'op', type: 'string', required: true, description: '"check" or "apply".' },
+            { name: 'channel', type: 'string', description: 'Update channel (default: "latest").' },
+        ],
+        summary: (p) => `update ${p.op}`,
+    },
+    {
+        name: 'script_install',
+        description: 'Install or replace a custom script on the device. Triggers a scripts reload.',
+        params: [
+            { name: 'name', type: 'string', required: true, description: 'Script filename (e.g. "battery.sh").' },
+            { name: 'content', type: 'string', description: 'Inline script source.' },
+            { name: 'content_file', type: 'string', description: 'Local file with the script source.' },
+        ],
+        summary: (p) => `script_install ${p.name}`,
+    },
+    {
+        name: 'script_delete',
+        description: 'Remove a custom script from the device.',
+        params: [
+            { name: 'name', type: 'string', required: true, description: 'Script filename.' },
+        ],
+        summary: (p) => `script_delete ${p.name}`,
+    },
+];
+
+/** Map from action name to spec, computed once for O(1) lookup. */
+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
+ * that validate on the first try.
+ */
+export function playbookSchema() {
+    return {
+        version: 1,
+        description:
+            'ThinR playbook — declarative sequence of agent-backed actions executed in parallel across a fleet.',
+        document: {
+            name: 'Optional human-readable name.',
+            description: 'Optional longer description.',
+            target: {
+                product: 'Product ID (use instead of `devices`).',
+                group: 'Optional asset group filter.',
+                devices: 'Optional explicit list of device IDs.',
+                concurrency: 'Max parallel devices (default: 10).',
+                fail_fast: 'Abort the whole run on the first step failure (default: false).',
+            },
+            vars: 'Mapping of variable name → value (plain form) or name → metadata object (extended form — see `vars_extended`). Referenced in step params with `{{ var }}`.',
+            steps: 'Ordered list of steps, executed sequentially on each device.',
+        },
+        vars_extended: {
+            description:
+                'Extended form for a single `vars` entry. Use it when a variable needs a description, an explicit type for override validation, or must be marked non-overridable or required.',
+            fields: {
+                default: 'Default value. Optional when `required: true`. Must match the declared `type`.',
+                description: 'Optional human-readable text shown in the dashboard form.',
+                type: 'Expected value type for overrides: "string", "number", "boolean", or "object".',
+                overridable:
+                    'Whether CLI / MCP / dashboard callers may override the value at run time. Defaults to `true`. Set `false` for internal variables.',
+                required:
+                    'Whether a value is mandatory at run time. Defaults to `false`. If `true` and no default is set, an override must be provided.',
+            },
+            example: {
+                port: { default: 8080, description: 'Service listening port.', type: 'number' },
+                internal_token: { default: 'fixed', overridable: false },
+                release: { type: 'string', required: true, description: 'Release tag to deploy.' },
+            },
+        },
+        step: {
+            name: 'Human-readable label shown in the summary.',
+            action: 'Action name — one of the actions below.',
+            pause_after: 'Optional seconds to wait after this step completes.',
+            when: 'Optional boolean expression. When present and falsy the step is skipped. See `when_expression` below for supported syntax.',
+            register: 'Optional identifier. When set, the step outcome is exposed under that name to later `when` expressions and string interpolation as `{ ok, result | error, duration_ms }`.',
+            '...': 'Additional fields are the action parameters (see `actions` below).',
+        },
+        when_expression: {
+            syntax:
+                'Minimal boolean mini-language: `==`, `!=`, `>`, `<`, `>=`, `<=`, `and`, `or`, `not`, parentheses; literals for strings (single or double quoted), numbers, `true`, `false`, `null`; dotted identifier paths resolve against the current scope.',
+            examples: [
+                'env == "prod"',
+                'check.ok and agent.version != "1.6.0"',
+                'not dry_run',
+            ],
+        },
+        actions: ACTIONS.map((a) => ({
+            name: a.name,
+            description: a.description,
+            params: a.params,
+        })),
+        variable_interpolation: {
+            syntax: '{{ name }}',
+            scope: 'Anything from the top-level `vars` block, plus the implicit `device` (current device ID).',
+            applies_to: 'String parameter values. Non-string values are passed through verbatim.',
+        },
+    };
+}

package/lib/playbook/vars.js

@@ -0,0 +1,209 @@
+// @ts-check
+
+/**
+ * Very small `{{ name }}` substitution over string values only. We
+ * intentionally don't recreate Jinja2 — conditionals and filters belong
+ * in a future iteration with a proper templating library. For now the
+ * only syntax supported is a bare variable reference, optionally wrapped
+ * in whitespace.
+ *
+ * `scope` is a flat map of variable names to values. Anything referenced
+ * but missing from the scope raises a hard error so typos don't silently
+ * produce empty strings.
+ *
+ * @param {any} value
+ * @param {any} scope
+ * @returns {any}
+ */
+export function interpolate(value, scope) {
+    if (typeof value === 'string') return interpolateString(value, scope);
+    if (Array.isArray(value)) return value.map((v) => interpolate(v, scope));
+    if (value && typeof value === 'object') {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) out[k] = interpolate(v, scope);
+        return out;
+    }
+    return value;
+}
+
+const TEMPLATE_RE = /\{\{\s*([A-Za-z_][A-Za-z0-9_]*)\s*\}\}/g;
+
+function interpolateString(s, scope) {
+    return s.replace(TEMPLATE_RE, (_match, name) => {
+        if (!(name in scope)) {
+            throw new Error(`Undefined playbook variable: ${name}`);
+        }
+        const v = scope[name];
+        return v == null ? '' : String(v);
+    });
+}
+
+/** Allowed variable types in the extended `vars` form. */
+export const VAR_TYPES = ['string', 'number', 'boolean', 'object'];
+
+/**
+ * Check that `value` matches the declared playbook var `type`. Object
+ * means non-null object or array (any JSON-serialisable composite).
+ *
+ * @param {unknown} value
+ * @param {string} type
+ */
+export function checkVarType(value, type) {
+    switch (type) {
+        case 'string':
+            return typeof value === 'string';
+        case 'number':
+            return typeof value === 'number' && Number.isFinite(value);
+        case 'boolean':
+            return typeof value === 'boolean';
+        case 'object':
+            return value !== null && typeof value === 'object';
+        default:
+            return false;
+    }
+}
+
+/**
+ * Infer a declared type from a plain-form default value. Mirrors the
+ * rules in {@link checkVarType}.
+ *
+ * @param {unknown} value
+ * @returns {'string' | 'number' | 'boolean' | 'object'}
+ */
+export function inferVarType(value) {
+    if (typeof value === 'string') return 'string';
+    if (typeof value === 'boolean') return 'boolean';
+    if (typeof value === 'number' && Number.isFinite(value)) return 'number';
+    return 'object';
+}
+
+function describeValueType(value) {
+    if (value === null) return 'null';
+    if (Array.isArray(value)) return 'array';
+    return typeof value;
+}
+
+/**
+ * Public view of a playbook's declared variables. Consumed by CLI, MCP
+ * and the dashboard to render forms and validate overrides. `default`
+ * is omitted entirely when the variable was declared without one.
+ *
+ * @param {{ variables?: Array<{
+ *   name: string,
+ *   description: string | null,
+ *   type: string,
+ *   default?: unknown,
+ *   hasDefault: boolean,
+ *   overridable: boolean,
+ *   required: boolean,
+ * }> }} pb
+ */
+export function listVariables(pb) {
+    const defs = pb?.variables || [];
+    return defs.map((d) => {
+        const out = {
+            name: d.name,
+            description: d.description,
+            type: d.type,
+            overridable: d.overridable,
+            required: d.required,
+        };
+        if (d.hasDefault) out.default = d.default;
+        return out;
+    });
+}
+
+/**
+ * Coerce a CLI-provided raw string `--var key=value` into the declared
+ * type of the matching variable. Unknown variables are passed through
+ * unchanged so {@link resolveVarScope} can produce the canonical error.
+ *
+ * Accepted string shapes per type:
+ *  - string  → as-is
+ *  - number  → anything parsed by `Number` to a finite value
+ *  - boolean → the literal strings `"true"` / `"false"`
+ *  - object  → a valid JSON document (object or array)
+ *
+ * @param {any} pb
+ * @param {string} name
+ * @param {string} raw  Raw CLI value (right-hand side of `key=value`).
+ * @returns {unknown}
+ */
+export function coerceCliVarValue(pb, name, raw) {
+    const def = (pb?.variables || []).find((d) => d.name === name);
+    if (!def) return raw;
+    switch (def.type) {
+        case 'number': {
+            const n = Number(raw);
+            if (!Number.isFinite(n)) {
+                throw new Error(`Variable "${name}" expects a number, got "${raw}".`);
+            }
+            return n;
+        }
+        case 'boolean':
+            if (raw === 'true') return true;
+            if (raw === 'false') return false;
+            throw new Error(`Variable "${name}" expects true or false, got "${raw}".`);
+        case 'object':
+            try {
+                return JSON.parse(raw);
+            } catch (err) {
+                throw new Error(
+                    `Variable "${name}" expects a JSON object/array, got "${raw}": ${err.message}`,
+                    { cause: err },
+                );
+            }
+        case 'string':
+        default:
+            return raw;
+    }
+}
+
+/**
+ * Build the final interpolation scope for a playbook run. Seeds with
+ * declared defaults, applies validated overrides, enforces `required`
+ * and `overridable`, then layers runtime-only `extras` (e.g. the
+ * implicit `device`) on top. Throws a descriptive Error on any failure.
+ *
+ * @param {any} pb
+ * @param {Record<string, unknown>} [overrides]  External values (CLI / MCP / dashboard).
+ * @param {Record<string, unknown>} [extras]     Runtime-only scope additions.
+ */
+export function resolveVarScope(pb, overrides = {}, extras = {}) {
+    const defs = pb?.variables || [];
+    const byName = new Map(defs.map((d) => [d.name, d]));
+
+    /** @type {Record<string, unknown>} */
+    const scope = {};
+    for (const d of defs) {
+        if (d.hasDefault) scope[d.name] = d.default;
+    }
+
+    for (const [name, value] of Object.entries(overrides || {})) {
+        const def = byName.get(name);
+        if (!def) {
+            throw new Error(`Unknown playbook variable: ${name}`);
+        }
+        if (!def.overridable) {
+            throw new Error(`Playbook variable "${name}" is not overridable.`);
+        }
+        if (!checkVarType(value, def.type)) {
+            throw new Error(
+                `Playbook variable "${name}" expects type ${def.type}, got ${describeValueType(value)}.`,
+            );
+        }
+        scope[name] = value;
+    }
+
+    for (const d of defs) {
+        if (d.required && !(d.name in scope)) {
+            throw new Error(`Required playbook variable "${d.name}" has no value.`);
+        }
+    }
+
+    for (const [name, value] of Object.entries(extras || {})) {
+        scope[name] = value;
+    }
+
+    return scope;
+}

package/lib/product/log-presets.js

@@ -0,0 +1,196 @@
+// @ts-check
+/**
+ * Catalog of named log line patterns. Each preset is a regex string with
+ * named groups out of `time`, `level`, `msg`. The dashboard compiles the
+ * resolved regex once per source and uses it to split each line into the
+ * three coloured chunks; the CLI and MCP just pass the preset name
+ * through and let the renderer resolve it.
+ *
+ * Patterns are intentionally tolerant — they should match the common
+ * shape of each format and silently fall through to "render raw" on
+ * lines that don't fit (e.g. multi-line stack traces, banner lines).
+ *
+ * Adding a preset: keep it small (3-5 fields max), avoid greedy or
+ * nested quantifiers (catastrophic backtracking), prefer character
+ * classes over `.` where possible.
+ */
+
+/**
+ * @typedef {{
+ *   name: string,
+ *   pattern: string,
+ *   description: string,
+ * }} LogPreset
+ */
+
+/** @type {Record<string, LogPreset>} */
+const PRESETS = {
+    journalctl: {
+        name: 'journalctl',
+        // `journalctl --output=short`: "Mon DD HH:MM:SS host unit[pid]: message".
+        // No level field in this output mode — unit stays as part of `msg`
+        // so it remains visible in the panel.
+        pattern: '^(?<time>\\w{3}\\s+\\d+\\s+\\d{2}:\\d{2}:\\d{2})\\s+\\S+\\s+(?<msg>.*)$',
+        description: 'systemd journal "short" output (no level captured)',
+    },
+    spdlog: {
+        name: 'spdlog',
+        // Thinger.io / agent flavour: "YYYY-MM-DD HH:MM:SS.mmm (...) [worker thread N] file.cpp:NN  LEVEL| msg".
+        // `LEVEL` is uppercase. The two-space gap before the level and
+        // the trailing pipe are diagnostic enough to avoid matching
+        // unrelated lines that happen to start with a timestamp.
+        pattern:
+            '^(?<time>\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d{3})\\s+\\([^)]*\\)\\s+\\[[^\\]]*\\]\\s+\\S+\\s+(?<level>[A-Z]+)\\|\\s*(?<msg>.*)$',
+        description: 'spdlog as emitted by the thinger server / agent (LEVEL| msg)',
+    },
+    'spdlog-bracket': {
+        name: 'spdlog-bracket',
+        // Default spdlog pattern: "[YYYY-MM-DD HH:MM:SS.mmm] [logger] [level] msg".
+        // The middle bracketed groups are optional so a bare
+        // "[time] [level] msg" line still matches.
+        pattern:
+            '^\\[(?<time>\\d{4}-\\d{2}-\\d{2} \\d{2}:\\d{2}:\\d{2}\\.\\d+)\\](?:\\s+\\[[^\\]]+\\])*\\s+\\[(?<level>\\w+)\\]\\s+(?<msg>.*)$',
+        description: 'spdlog default bracketed pattern: [time] [logger] [level] msg',
+    },
+    'nginx-error': {
+        name: 'nginx-error',
+        // Format: "YYYY/MM/DD HH:MM:SS [level] pid#tid: *cid message".
+        pattern:
+            '^(?<time>\\d{4}/\\d{2}/\\d{2} \\d{2}:\\d{2}:\\d{2})\\s+\\[(?<level>\\w+)\\]\\s+(?<msg>.*)$',
+        description: 'nginx error log: "YYYY/MM/DD HH:MM:SS [level] pid#tid: msg"',
+    },
+    'nginx-access': {
+        name: 'nginx-access',
+        // Common Log Format with a few extras. No level field, but the
+        // request line + status code carries enough signal that the
+        // panel can still split time and msg cleanly.
+        pattern:
+            '^(?<msg>\\S+\\s+\\S+\\s+\\S+\\s+\\[(?<time>[^\\]]+)\\]\\s+.*)$',
+        description: 'nginx access log (CLF): no level captured, time inside brackets',
+    },
+};
+
+/**
+ * Levels captured by patterns are normalized to lowercase before any
+ * comparison. This list is the canonical set the renderer recognises;
+ * unknown levels still render with the `info` palette but are kept
+ * verbatim in the level slot for debugging.
+ */
+export const LOG_LEVELS = /** @type {const} */ ([
+    'trace',
+    'debug',
+    'info',
+    'notice',
+    'warn',
+    'warning',
+    'error',
+    'critical',
+    'crit',
+    'fatal',
+]);
+
+/**
+ * Lookup table for level → severity. Higher number means more severe.
+ * Used by the panel filter to test "is this line at or above the
+ * configured threshold?".
+ */
+export const LEVEL_SEVERITY = /** @type {Record<string, number>} */ ({
+    trace: 0,
+    trc: 0,
+    debug: 0,
+    dbg: 0,
+    info: 1,
+    inf: 1,
+    notice: 2,
+    warn: 3,
+    warning: 3,
+    wrn: 3,
+    error: 4,
+    err: 4,
+    critical: 5,
+    crit: 5,
+    fatal: 5,
+    fat: 5,
+});
+
+/**
+ * Return all presets as a sorted list. Used by `thinr product logs presets`
+ * and by the MCP `thinr_product_logs_presets` tool.
+ *
+ * @returns {LogPreset[]}
+ */
+export function listPresets() {
+    return Object.values(PRESETS)
+        .map((p) => ({ ...p }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+}
+
+/**
+ * Look up a single preset by name. Returns `null` when the name is not
+ * registered so callers can decide whether that's an error or just a
+ * "use the literal pattern" path.
+ *
+ * @param {string} name
+ * @returns {LogPreset | null}
+ */
+export function getPreset(name) {
+    if (typeof name !== 'string') return null;
+    const p = PRESETS[name];
+    return p ? { ...p } : null;
+}
+
+/**
+ * Set of valid preset names — kept for cheap membership checks in the
+ * validator. Returning a fresh array each call would defeat the
+ * "validate without allocating" property the schema relies on.
+ */
+export const PRESET_NAMES = Object.freeze(Object.keys(PRESETS).sort());
+
+/**
+ * Parse a single log line against a (compiled or string) pattern.
+ * Returns `{ time, level, msg, level_norm }` when the line matches and
+ * the pattern uses any of the known named groups, or `null` when the
+ * line doesn't match. `level_norm` is the lowercase form of the
+ * captured level — convenient for color and severity lookups.
+ *
+ * Passing a `null` regex is supported and returns `null` so callers
+ * can use the helper unconditionally.
+ *
+ * @param {string} line
+ * @param {RegExp | null} regex
+ * @returns {{ time?: string, level?: string, msg?: string, level_norm?: string } | null}
+ */
+export function parseLogLine(line, regex) {
+    if (!regex) return null;
+    const m = regex.exec(line);
+    if (!m || !m.groups) return null;
+    const { time, level, msg } = m.groups;
+    const out = {};
+    if (typeof time === 'string') out.time = time;
+    if (typeof level === 'string') {
+        out.level = level;
+        out.level_norm = level.toLowerCase();
+    }
+    if (typeof msg === 'string') out.msg = msg;
+    return out;
+}
+
+/**
+ * Resolve a level threshold ("all" | "info" | "warn" | "error") against
+ * a parsed level. Lines without a captured level pass through (we do
+ * not silently hide what we cannot classify). Unknown levels are
+ * treated as `info` so debug noise doesn't leak through a `warn+`
+ * filter.
+ *
+ * @param {string | null | undefined} levelNorm
+ * @param {'all' | 'info' | 'warn' | 'error'} threshold
+ * @returns {boolean}
+ */
+export function levelPassesThreshold(levelNorm, threshold) {
+    if (threshold === 'all') return true;
+    if (!levelNorm) return true;
+    const sev = LEVEL_SEVERITY[levelNorm];
+    const min = LEVEL_SEVERITY[threshold];
+    if (sev == null) return min <= LEVEL_SEVERITY.info;
+    return sev >= min;
+}