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

package/lib/playbook/loader.js

@@ -0,0 +1,247 @@
+// @ts-check
+import { readFileSync } from 'fs';
+import YAML from 'yaml';
+import { ACTION_BY_NAME } from './schema.js';
+import { VAR_TYPES, checkVarType, inferVarType } from './vars.js';
+
+const IDENT_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const VAR_META_KEYS = ['default', 'description', 'type', 'overridable', 'required'];
+const VAR_META_KEY_SET = new Set(VAR_META_KEYS);
+
+/**
+ * Parse and validate a playbook document. Returns the normalised shape
+ * ready to feed into the runner, or throws a descriptive Error listing
+ * every issue found (one per line).
+ *
+ * @param {string} source  YAML source text.
+ * @param {{ sourcePath?: string }} [opts]
+ */
+export function parsePlaybook(source, { sourcePath } = {}) {
+    let raw;
+    try {
+        raw = YAML.parse(source);
+    } catch (err) {
+        throw new Error(
+            `Invalid YAML${sourcePath ? ` in ${sourcePath}` : ''}: ${err.message}`,
+            { cause: err },
+        );
+    }
+
+    const errors = [];
+
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        throw new Error('Playbook root must be a YAML mapping with `target` and `steps`.');
+    }
+
+    const target = validateTarget(raw.target, errors);
+    const { vars, variables } = validateVars(raw.vars, errors);
+    const steps = validateSteps(raw.steps, errors);
+
+    if (errors.length) {
+        throw new Error(`Invalid playbook:\n  - ${errors.join('\n  - ')}`);
+    }
+
+    return {
+        name: typeof raw.name === 'string' ? raw.name : null,
+        description: typeof raw.description === 'string' ? raw.description : null,
+        target,
+        vars,
+        variables,
+        steps,
+    };
+}
+
+/** Read + parse a playbook from disk. */
+export function loadPlaybookFile(path) {
+    const source = readFileSync(path, 'utf8');
+    return parsePlaybook(source, { sourcePath: path });
+}
+
+function validateTarget(t, errors) {
+    if (!t || typeof t !== 'object' || Array.isArray(t)) {
+        errors.push('`target` is required and must be a mapping.');
+        return { product: null, group: null, devices: null, concurrency: 10, fail_fast: false };
+    }
+    const hasProduct = typeof t.product === 'string' && t.product;
+    const hasDevices = Array.isArray(t.devices) && t.devices.length > 0;
+    if (!hasProduct && !hasDevices) {
+        errors.push('`target.product` or `target.devices` must be provided.');
+    }
+    if (t.devices !== undefined && !Array.isArray(t.devices)) {
+        errors.push('`target.devices` must be a list of device IDs.');
+    }
+    if (t.group !== undefined && typeof t.group !== 'string') {
+        errors.push('`target.group` must be a string.');
+    }
+    if (t.concurrency !== undefined && (!Number.isInteger(t.concurrency) || t.concurrency <= 0)) {
+        errors.push('`target.concurrency` must be a positive integer.');
+    }
+    if (t.fail_fast !== undefined && typeof t.fail_fast !== 'boolean') {
+        errors.push('`target.fail_fast` must be a boolean.');
+    }
+    return {
+        product: hasProduct ? t.product : null,
+        group: typeof t.group === 'string' ? t.group : null,
+        devices: hasDevices ? [...t.devices] : null,
+        concurrency: Number.isInteger(t.concurrency) && t.concurrency > 0 ? t.concurrency : 10,
+        fail_fast: !!t.fail_fast,
+    };
+}
+
+function validateVars(v, errors) {
+    if (v === undefined || v === null) return { vars: {}, variables: [] };
+    if (typeof v !== 'object' || Array.isArray(v)) {
+        errors.push('`vars` must be a mapping of name → value.');
+        return { vars: {}, variables: [] };
+    }
+    const vars = {};
+    const variables = [];
+    for (const [name, raw] of Object.entries(v)) {
+        if (!IDENT_RE.test(name)) {
+            errors.push(`\`vars.${name}\` is not a valid identifier (letters, digits, underscore; no leading digit).`);
+            continue;
+        }
+        const def = normaliseVarDef(name, raw, errors);
+        if (!def) continue;
+        variables.push(def);
+        if (def.hasDefault) vars[name] = def.default;
+    }
+    return { vars, variables };
+}
+
+function isExtendedVarValue(raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return false;
+    for (const key of VAR_META_KEYS) {
+        if (key in raw) return true;
+    }
+    return false;
+}
+
+function normaliseVarDef(name, raw, errors) {
+    if (!isExtendedVarValue(raw)) {
+        return {
+            name,
+            description: null,
+            type: inferVarType(raw),
+            default: raw,
+            hasDefault: true,
+            overridable: true,
+            required: false,
+        };
+    }
+
+    for (const key of Object.keys(raw)) {
+        if (!VAR_META_KEY_SET.has(key)) {
+            errors.push(`\`vars.${name}\`: unknown metadata key "${key}" (expected: ${VAR_META_KEYS.join(', ')}).`);
+            return null;
+        }
+    }
+
+    let type = raw.type;
+    if (type !== undefined) {
+        if (typeof type !== 'string' || !VAR_TYPES.includes(type)) {
+            errors.push(`\`vars.${name}.type\` must be one of: ${VAR_TYPES.join(', ')}.`);
+            return null;
+        }
+    } else {
+        type = 'default' in raw ? inferVarType(raw.default) : 'string';
+    }
+
+    if (raw.description !== undefined && typeof raw.description !== 'string') {
+        errors.push(`\`vars.${name}.description\` must be a string.`);
+        return null;
+    }
+    if (raw.overridable !== undefined && typeof raw.overridable !== 'boolean') {
+        errors.push(`\`vars.${name}.overridable\` must be a boolean.`);
+        return null;
+    }
+    if (raw.required !== undefined && typeof raw.required !== 'boolean') {
+        errors.push(`\`vars.${name}.required\` must be a boolean.`);
+        return null;
+    }
+
+    const hasDefault = 'default' in raw;
+    if (hasDefault && !checkVarType(raw.default, type)) {
+        errors.push(`\`vars.${name}.default\` does not match declared type ${type}.`);
+        return null;
+    }
+
+    return {
+        name,
+        description: typeof raw.description === 'string' ? raw.description : null,
+        type,
+        default: hasDefault ? raw.default : undefined,
+        hasDefault,
+        overridable: raw.overridable !== false,
+        required: raw.required === true,
+    };
+}
+
+function validateSteps(s, errors) {
+    if (!Array.isArray(s) || s.length === 0) {
+        errors.push('`steps` must be a non-empty list.');
+        return [];
+    }
+    const out = [];
+    s.forEach((raw, i) => {
+        const where = `step[${i}]${raw?.name ? ` "${raw.name}"` : ''}`;
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            errors.push(`${where}: must be a mapping.`);
+            return;
+        }
+        const { action, pause_after, when, register, label, ...rest } = raw;
+        if (typeof action !== 'string' || !action) {
+            errors.push(`${where}: \`action\` is required.`);
+            return;
+        }
+        const spec = ACTION_BY_NAME[action];
+        if (!spec) {
+            errors.push(`${where}: unknown action "${action}".`);
+            return;
+        }
+        // `name` is usually the step's human label, but actions like
+        // `script_install` / `script_delete` declare a `name` of their
+        // own. Resolve the clash transparently: if the action owns
+        // `name`, route it to params; otherwise treat it as the label.
+        // A top-level `label:` field is always honoured as an explicit
+        // override for the clashing case.
+        const actionOwnsName = spec.params.some((p) => p.name === 'name');
+        let stepLabel = null;
+        let params;
+        if (actionOwnsName) {
+            params = rest;
+        } else {
+            const { name: stepName, ...others } = rest;
+            params = others;
+            if (typeof stepName === 'string' && stepName) stepLabel = stepName;
+        }
+        if (typeof label === 'string' && label) stepLabel = label;
+
+        for (const p of spec.params) {
+            if (p.required && params[p.name] === undefined) {
+                errors.push(`${where}: \`${p.name}\` is required for action "${action}".`);
+            }
+        }
+        if (pause_after !== undefined && (!Number.isFinite(pause_after) || pause_after < 0)) {
+            errors.push(`${where}: \`pause_after\` must be a non-negative number of seconds.`);
+            return;
+        }
+        if (when !== undefined && typeof when !== 'string') {
+            errors.push(`${where}: \`when\` must be a string expression.`);
+            return;
+        }
+        if (register !== undefined && (typeof register !== 'string' || !/^[A-Za-z_][A-Za-z0-9_]*$/.test(register))) {
+            errors.push(`${where}: \`register\` must be a valid identifier (letters, digits, underscore; no leading digit).`);
+            return;
+        }
+        out.push({
+            name: stepLabel || spec.summary(params),
+            action,
+            params,
+            pause_after: Number.isFinite(pause_after) ? pause_after : 0,
+            when: typeof when === 'string' ? when : null,
+            register: typeof register === 'string' ? register : null,
+        });
+    });
+    return out;
+}

package/lib/playbook/runner.js

@@ -0,0 +1,300 @@
+// @ts-check
+import { filterActiveDevices, getDevices } from '../devices.js';
+import { runPool } from '../concurrency.js';
+import { HANDLERS, CHECKERS, createActionContext } from './actions.js';
+
+/** Actions whose effect isn't derivable from observable state, so
+ * pre-checking before apply is either pointless or harmful (sleep
+ * would always skip; exec/resource have unpredictable side effects
+ * we must always trigger; pull writes to local disk — pre-check
+ * would hash the remote just to overwrite the local file anyway). */
+const NON_IDEMPOTENT = new Set(['sleep', 'exec', 'resource', 'pull']);
+import { ACTION_BY_NAME } from './schema.js';
+import { interpolate, resolveVarScope } from './vars.js';
+import { evaluateCondition } from './expression.js';
+
+function buildScope(pb, opts, extras) {
+    if (opts && Object.hasOwn(opts, 'overrides')) {
+        return resolveVarScope(pb, opts.overrides || {}, extras);
+    }
+    return { ...(pb.vars || {}), ...extras };
+}
+
+/**
+ * Resolve the playbook's `target` block to a concrete device list.
+ * Honours optional CLI overrides (product / group / devices) that the
+ * caller may pass to tweak a saved playbook without editing it.
+ *
+ * @param {any} pb
+ * @param {{ user?: string | null, overrides?: { product?: string, group?: string, devices?: string[] } }} [opts]
+ */
+export async function resolveTargets(pb, opts = {}) {
+    const { user, overrides = {} } = opts;
+    const target = { ...pb.target, ...overrides };
+    if (Array.isArray(target.devices) && target.devices.length > 0) {
+        // Explicit list — we still fetch the fleet so we can attach
+        // connection state, but fall back gracefully when a requested
+        // id isn't in the user's fleet (unlikely).
+        const all = await getDevices({}, user);
+        const byId = Object.fromEntries(all.map((d) => [d.device, d]));
+        return target.devices.map((id) => byId[id] || { device: id, connection: { active: false } });
+    }
+    if (!target.product) {
+        throw new Error('playbook target has no product/devices after overrides');
+    }
+    const filter = { product: target.product };
+    if (target.group) filter.asset_group = target.group;
+    const all = await getDevices(filter, user);
+    return filterActiveDevices(all);
+}
+
+/**
+ * Static "what would happen" summary — does no remote calls. Returns
+ * rows of `{ step, summary }` the caller can render as a plan.
+ *
+ * Pass `opts.overrides` to resolve variables with the new scope model
+ * (declared defaults + validated overrides, throws on unknown / non-
+ * overridable / wrong-type / missing-required vars). Omit it to fall
+ * back to the legacy behaviour that just spreads `pb.vars` into scope.
+ *
+ * @param {any} pb
+ * @param {{ overrides?: Record<string, unknown> }} [opts]
+ */
+export function buildDryRunPlan(pb, opts) {
+    /** @type {Record<string, unknown>} */
+    const scope = buildScope(pb, opts, { device: '<device>' });
+    return pb.steps.map((s, i) => {
+        const spec = ACTION_BY_NAME[s.action];
+        const resolvedParams = interpolate(s.params, scope);
+        return {
+            index: i,
+            name: s.name,
+            action: s.action,
+            summary: spec ? spec.summary(resolvedParams) : s.action,
+            pause_after: s.pause_after,
+        };
+    });
+}
+
+/**
+ * Run the playbook over `devices` with `concurrency` parallel workers.
+ * Each worker runs every step in order against its device and records
+ * the outcome per step. Handlers never throw past the runner — failures
+ * are captured into the results table.
+ *
+ * Set `checkMode: true` to route every step through CHECKERS instead
+ * of HANDLERS. Actions without a checker are reported as `unknown`
+ * and skipped without side effects.
+ *
+ * Pass `opts.overrides` to resolve variables with the new scope model
+ * (declared defaults + validated overrides). Omit it to fall back to
+ * the legacy behaviour that just spreads `pb.vars` into scope.
+ *
+ * @param {Object} pb                 Parsed playbook.
+ * @param {Object[]} devices          Device records from resolveTargets().
+ * @param {{
+ *   user?: string | null,
+ *   concurrency?: number,
+ *   failFast?: boolean,
+ *   continueOnError?: boolean,
+ *   baseDir?: string,
+ *   checkMode?: boolean,
+ *   overrides?: Record<string, unknown>,
+ *   onStepStart?: (args: { deviceId: string, stepIndex: number, step: any }) => void,
+ *   onStepEnd?:   (args: { deviceId: string, stepIndex: number, step: any, ok: boolean, summary: string, error?: string, durationMs: number, verdict?: 'applied' | 'changed' | 'unchanged' | 'unknown', stdout?: string, stderr?: string, exitCode?: number }) => void,
+ * }} [opts]
+ */
+export async function runPlaybook(pb, devices, opts = {}) {
+    const checkMode = !!opts.checkMode;
+    const concurrency = opts.concurrency ?? pb.target.concurrency ?? 10;
+    const failFast = opts.failFast ?? pb.target.fail_fast ?? false;
+    const continueOnError = opts.continueOnError ?? pb.target.continue_on_error ?? false;
+    const user = opts.user ?? null;
+    const baseDir = opts.baseDir;
+
+    /** @type {boolean} */
+    let aborted = false;
+
+    const results = await runPool(devices, concurrency, async (device) => {
+        const deviceId = device.device;
+        const ctx = createActionContext({ deviceId, user, baseDir });
+        /** @type {Record<string, unknown>} */
+        const scope = buildScope(pb, opts, { device: deviceId });
+        const steps = [];
+        let deviceOk = true;
+
+        for (let i = 0; i < pb.steps.length; i++) {
+            if (aborted) {
+                steps.push({ index: i, name: pb.steps[i].name, ok: false, skipped: true, summary: 'skipped (fail-fast)', durationMs: 0 });
+                continue;
+            }
+            const step = pb.steps[i];
+
+            // `when` gate. Evaluated against the live scope (playbook
+            // vars + `device` + every `register`-ed step result so far).
+            // A parse/eval error fails the step — less confusing than
+            // silently skipping and continuing.
+            if (step.when) {
+                let gate;
+                try {
+                    gate = evaluateCondition(step.when, scope);
+                } catch (err) {
+                    const durationMs = 0;
+                    const msg = err instanceof Error ? err.message : String(err);
+                    steps.push({
+                        index: i,
+                        name: step.name,
+                        ok: false,
+                        summary: `when-expression error: ${msg}`,
+                        error: msg,
+                        durationMs,
+                    });
+                    opts.onStepEnd?.({ deviceId, stepIndex: i, step, ok: false, summary: msg, error: msg, durationMs });
+                    deviceOk = false;
+                    if (failFast) aborted = true;
+                    break;
+                }
+                if (!gate) {
+                    steps.push({
+                        index: i,
+                        name: step.name,
+                        ok: true,
+                        skipped: true,
+                        summary: `skipped (when: ${step.when})`,
+                        durationMs: 0,
+                    });
+                    opts.onStepEnd?.({ deviceId, stepIndex: i, step, ok: true, summary: 'skipped', durationMs: 0 });
+                    continue;
+                }
+            }
+
+            const handler = HANDLERS[step.action];
+            const checker = CHECKERS[step.action];
+            const resolvedParams = interpolate(step.params, scope);
+            opts.onStepStart?.({ deviceId, stepIndex: i, step });
+
+            const t0 = Date.now();
+            try {
+                let summary;
+                let verdict;
+                let stdout;
+                let stderr;
+                let exitCode;
+                if (checkMode) {
+                    if (checker) {
+                        const result = await checker(ctx, resolvedParams);
+                        verdict = result.status;
+                        summary = result.summary;
+                    } else {
+                        verdict = 'unknown';
+                        summary = `check not supported for ${step.action}`;
+                    }
+                } else {
+                    let preCheck = null;
+                    if (checker && !NON_IDEMPOTENT.has(step.action)) {
+                        try {
+                            preCheck = await checker(ctx, resolvedParams);
+                        } catch {
+                            preCheck = null;
+                        }
+                    }
+                    if (preCheck && preCheck.status === 'unchanged') {
+                        verdict = 'unchanged';
+                        summary = preCheck.summary;
+                    } else {
+                        const out = await handler(ctx, resolvedParams);
+                        if (typeof out === 'string') {
+                            summary = out;
+                        } else {
+                            summary = out.summary;
+                            stdout = out.stdout;
+                            stderr = out.stderr;
+                            exitCode = out.exitCode;
+                        }
+                        verdict = 'changed';
+                    }
+                }
+                const durationMs = Date.now() - t0;
+                const entry = { index: i, name: step.name, ok: true, summary, durationMs, verdict };
+                if (stdout !== undefined) entry.stdout = stdout;
+                if (stderr !== undefined) entry.stderr = stderr;
+                if (exitCode !== undefined) entry.exitCode = exitCode;
+                steps.push(entry);
+                if (step.register) {
+                    scope[step.register] = {
+                        ok: true,
+                        result: summary,
+                        duration_ms: durationMs,
+                    };
+                }
+                opts.onStepEnd?.({
+                    deviceId,
+                    stepIndex: i,
+                    step,
+                    ok: true,
+                    summary,
+                    durationMs,
+                    verdict,
+                    stdout,
+                    stderr,
+                    exitCode,
+                });
+            } catch (err) {
+                const durationMs = Date.now() - t0;
+                const msg = err instanceof Error ? err.message : String(err);
+                const stdout = err && typeof err === 'object' ? err.stdout : undefined;
+                const stderr = err && typeof err === 'object' ? err.stderr : undefined;
+                const exitCode = err && typeof err === 'object' ? err.exitCode : undefined;
+                const entry = { index: i, name: step.name, ok: false, summary: msg, error: msg, durationMs };
+                if (stdout !== undefined) entry.stdout = stdout;
+                if (stderr !== undefined) entry.stderr = stderr;
+                if (exitCode !== undefined) entry.exitCode = exitCode;
+                steps.push(entry);
+                if (step.register) {
+                    scope[step.register] = {
+                        ok: false,
+                        error: msg,
+                        duration_ms: durationMs,
+                    };
+                }
+                opts.onStepEnd?.({
+                    deviceId,
+                    stepIndex: i,
+                    step,
+                    ok: false,
+                    summary: msg,
+                    error: msg,
+                    durationMs,
+                    stdout,
+                    stderr,
+                    exitCode,
+                });
+                deviceOk = false;
+                if (failFast) aborted = true;
+                if (continueOnError) continue;
+                break;
+            }
+
+            if (step.pause_after > 0) {
+                await new Promise((r) => setTimeout(r, step.pause_after * 1000));
+            }
+        }
+
+        return { device: deviceId, ok: deviceOk, steps };
+    });
+
+    return results.map((r, i) => {
+        if (r && r.ok) return r.value;
+        let msg = 'unknown error';
+        if (r && r.ok === false) {
+            const err = r.error;
+            msg = err instanceof Error ? err.message : String(err);
+        }
+        return {
+            device: devices[i].device,
+            ok: false,
+            steps: [],
+            error: msg,
+        };
+    });
+}