@switchbot/openapi-cli 2.6.4 → 3.0.0

package/dist/rules/action.js

@@ -0,0 +1,205 @@
+/**
+ * Rule action executor — the only place that calls into `executeCommand`
+ * from the rules pipeline.
+ *
+ * Responsibilities:
+ *   1. Parse the `command` string into a `{ deviceId, verb, parameter }`
+ *      tuple, rejecting shapes the PoC doesn't understand.
+ *   2. Enforce the destructive-command blocklist as a second line of
+ *      defence (the validator should have caught it at load time — this
+ *      protects against hand-crafted engine inputs).
+ *   3. Resolve `action.device` (alias or deviceId) into the `<id>`
+ *      slot.
+ *   4. Branch on `dry_run`: dry-run writes audit with kind
+ *      `rule-fire-dry` and returns without touching the API.
+ *   5. Live run delegates to `executeCommand`, then re-writes audit
+ *      with the rule-scoped kind + fireId so `rules tail` / `replay`
+ *      can correlate multi-action fires.
+ */
+import { executeCommand } from '../lib/devices.js';
+import { writeAudit } from '../utils/audit.js';
+import { isDestructiveCommand } from './destructive.js';
+const DEVICES_COMMAND_RE = /^devices\s+command\s+(\S+)\s+(\S+)(?:\s+(.*))?$/;
+export function parseRuleCommand(cmd) {
+    const m = DEVICES_COMMAND_RE.exec(cmd.trim());
+    if (!m)
+        return null;
+    const deviceIdSlot = m[1];
+    const verb = m[2];
+    const rest = (m[3] ?? '').trim();
+    return {
+        deviceIdSlot,
+        verb,
+        parameterTokens: rest.length === 0 ? [] : rest.split(/\s+/),
+    };
+}
+/** Alias-first resolver — falls back to the raw value (assumed deviceId). */
+export function resolveActionDevice(explicit, slot, aliases) {
+    // Explicit device field on the action wins.
+    const candidate = explicit ?? (slot && slot !== '<id>' ? slot : null);
+    if (!candidate)
+        return null;
+    if (aliases[candidate])
+        return aliases[candidate];
+    return candidate;
+}
+/**
+ * Render a parameter for SwitchBot's command API. For the PoC we pass
+ * the raw token string for single-token args, join with `:` for
+ * multi-token args (matches the CLI's `devices command` convention),
+ * and `undefined` when no tokens were supplied (the SDK substitutes
+ * `'default'`).
+ */
+function renderParameter(tokens) {
+    if (tokens.length === 0)
+        return undefined;
+    if (tokens.length === 1)
+        return tokens[0];
+    return tokens.join(':');
+}
+export async function executeRuleAction(action, ctx) {
+    const parsed = parseRuleCommand(action.command);
+    if (!parsed) {
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId: 'unknown',
+            command: action.command,
+            parameter: null,
+            commandType: 'command',
+            dryRun: true,
+            result: 'error',
+            error: 'unparseable-command',
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                fireId: ctx.fireId,
+                reason: 'unparseable-command',
+            },
+        });
+        return { ok: false, error: 'unparseable-command', blocked: true };
+    }
+    if (isDestructiveCommand(action.command)) {
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId: resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases) ?? 'unknown',
+            command: action.command,
+            parameter: null,
+            commandType: 'command',
+            dryRun: true,
+            result: 'error',
+            error: `destructive-verb:${parsed.verb}`,
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                fireId: ctx.fireId,
+                reason: `destructive verb "${parsed.verb}" refused at runtime`,
+            },
+        });
+        return { ok: false, error: `destructive-verb:${parsed.verb}`, blocked: true, verb: parsed.verb };
+    }
+    const deviceId = resolveActionDevice(action.device, parsed.deviceIdSlot, ctx.aliases);
+    if (!deviceId || deviceId === '<id>') {
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId: 'unknown',
+            command: action.command,
+            parameter: null,
+            commandType: 'command',
+            dryRun: true,
+            result: 'error',
+            error: 'missing-device',
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                fireId: ctx.fireId,
+                reason: 'action omitted `device` and command used `<id>` placeholder',
+            },
+        });
+        return { ok: false, error: 'missing-device', verb: parsed.verb };
+    }
+    const dryRun = ctx.globalDryRun === true || ctx.rule.dry_run === true;
+    const parameter = renderParameter(parsed.parameterTokens);
+    if (dryRun) {
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire-dry',
+            deviceId,
+            command: parsed.verb,
+            parameter: parameter ?? 'default',
+            commandType: 'command',
+            dryRun: true,
+            result: 'ok',
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                matchedDevice: deviceId,
+                fireId: ctx.fireId,
+            },
+        });
+        return { ok: true, dryRun: true, deviceId, verb: parsed.verb };
+    }
+    if (ctx.skipApiCall) {
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId,
+            command: parsed.verb,
+            parameter: parameter ?? 'default',
+            commandType: 'command',
+            dryRun: false,
+            result: 'ok',
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                matchedDevice: deviceId,
+                fireId: ctx.fireId,
+                reason: 'api-skipped',
+            },
+        });
+        return { ok: true, deviceId, verb: parsed.verb };
+    }
+    try {
+        await executeCommand(deviceId, parsed.verb, parameter, 'command', ctx.httpClient);
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId,
+            command: parsed.verb,
+            parameter: parameter ?? 'default',
+            commandType: 'command',
+            dryRun: false,
+            result: 'ok',
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                matchedDevice: deviceId,
+                fireId: ctx.fireId,
+            },
+        });
+        return { ok: true, deviceId, verb: parsed.verb };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        writeAudit({
+            t: new Date().toISOString(),
+            kind: 'rule-fire',
+            deviceId,
+            command: parsed.verb,
+            parameter: parameter ?? 'default',
+            commandType: 'command',
+            dryRun: false,
+            result: 'error',
+            error: msg,
+            rule: {
+                name: ctx.rule.name,
+                triggerSource: ctx.rule.when.source,
+                matchedDevice: deviceId,
+                fireId: ctx.fireId,
+            },
+        });
+        return { ok: false, error: msg, deviceId, verb: parsed.verb };
+    }
+}

package/dist/rules/audit-query.js

@@ -0,0 +1,89 @@
+/**
+ * Shared filters + aggregations over the audit log for
+ * `switchbot rules tail` and `switchbot rules replay`.
+ *
+ * All functions are pure — no I/O, no clock reads — so they can be
+ * unit-tested with fixture arrays. The CLI entry points handle file
+ * reading, `--follow` tailing, and human vs JSON rendering.
+ */
+/** The subset of audit kinds the rules engine emits. */
+export const RULE_AUDIT_KINDS = [
+    'rule-fire',
+    'rule-fire-dry',
+    'rule-throttled',
+    'rule-webhook-rejected',
+];
+/** Keep entries that are rule-engine emitted and match the filter. */
+export function filterRuleAudits(entries, filter = {}) {
+    const kinds = new Set(filter.kinds ?? RULE_AUDIT_KINDS);
+    const out = [];
+    for (const e of entries) {
+        if (!kinds.has(e.kind))
+            continue;
+        if (filter.sinceMs !== undefined) {
+            const ms = Date.parse(e.t);
+            if (!Number.isFinite(ms) || ms < filter.sinceMs)
+                continue;
+        }
+        if (filter.ruleName !== undefined) {
+            if (e.rule?.name !== filter.ruleName)
+                continue;
+        }
+        out.push(e);
+    }
+    return out;
+}
+/** Aggregate a filtered stream into per-rule counters. */
+export function aggregateRuleAudits(entries) {
+    const byRule = new Map();
+    let webhookRejectedCount = 0;
+    for (const e of entries) {
+        if (e.kind === 'rule-webhook-rejected' && !e.rule) {
+            webhookRejectedCount++;
+            continue;
+        }
+        const name = e.rule?.name;
+        if (!name)
+            continue;
+        let s = byRule.get(name);
+        if (!s) {
+            s = {
+                rule: name,
+                fires: 0,
+                driesFires: 0,
+                throttled: 0,
+                errors: 0,
+                errorRate: 0,
+                firstAt: null,
+                lastAt: null,
+                triggerSource: null,
+            };
+            byRule.set(name, s);
+        }
+        if (e.kind === 'rule-fire')
+            s.fires++;
+        else if (e.kind === 'rule-fire-dry')
+            s.driesFires++;
+        else if (e.kind === 'rule-throttled')
+            s.throttled++;
+        if (e.result === 'error')
+            s.errors++;
+        if (!s.firstAt || e.t < s.firstAt)
+            s.firstAt = e.t;
+        if (!s.lastAt || e.t > s.lastAt)
+            s.lastAt = e.t;
+        const source = e.rule?.triggerSource;
+        if (source) {
+            if (s.triggerSource === null)
+                s.triggerSource = source;
+            else if (s.triggerSource !== source)
+                s.triggerSource = 'mixed';
+        }
+    }
+    for (const s of byRule.values()) {
+        const denom = s.fires + s.driesFires;
+        s.errorRate = denom === 0 ? 0 : s.errors / denom;
+    }
+    const summaries = [...byRule.values()].sort((a, b) => b.fires + b.driesFires - (a.fires + a.driesFires));
+    return { total: entries.length, summaries, webhookRejectedCount };
+}

package/dist/rules/cron-scheduler.js

@@ -0,0 +1,186 @@
+/**
+ * Cron trigger scheduler for the rules engine.
+ *
+ * Each cron rule gets its own scheduler entry. On every tick the
+ * scheduler synthesises an `EngineEvent` with `source: 'cron'` and hands
+ * it to the same dispatch path the MQTT pipeline uses, so conditions,
+ * throttle, and action execution behave identically regardless of
+ * trigger source.
+ *
+ * Tests can drive the scheduler deterministically via `fireNowForTest()`
+ * — the scheduler's internal timer still uses `setTimeout`, which means
+ * `vi.useFakeTimers()` plus `vi.advanceTimersByTime()` also work. Croner
+ * is used only for `nextRun(fromDate)` calculations; we own the
+ * timer/dispatch loop so the engine can drain events through a single
+ * serialised queue.
+ */
+import { Cron } from 'croner';
+/** Maps JS getDay() (0=Sun) to 3-letter abbreviation. */
+const JS_DAY_TO_ABBR = ['sun', 'mon', 'tue', 'wed', 'thu', 'fri', 'sat'];
+/** Expand a days[] entry to its canonical 3-letter abbr so comparisons are O(1). */
+function normaliseDay(d) {
+    return d.toLowerCase().slice(0, 3);
+}
+/** Return true if `t` falls on one of the listed days (or days is absent/empty). */
+export function matchesDayFilter(days, t) {
+    if (!days || days.length === 0)
+        return true;
+    const todayAbbr = JS_DAY_TO_ABBR[t.getDay()];
+    return days.some((d) => normaliseDay(d) === todayAbbr);
+}
+export class CronScheduler {
+    opts;
+    entries = new Map();
+    started = false;
+    stopped = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    getScheduledFor(ruleName) {
+        const s = this.entries.get(ruleName);
+        if (!s)
+            return null;
+        return { schedule: s.schedule, nextAt: s.nextAt };
+    }
+    hasRegistered(ruleName) {
+        return this.entries.has(ruleName);
+    }
+    /**
+     * Register a cron rule. Validates the pattern eagerly — an invalid
+     * schedule throws synchronously so engine start can surface the error.
+     */
+    register(rule) {
+        if (rule.when.source !== 'cron') {
+            throw new Error(`CronScheduler.register called for non-cron rule "${rule.name}"`);
+        }
+        if (this.entries.has(rule.name)) {
+            throw new Error(`CronScheduler: duplicate rule name "${rule.name}"`);
+        }
+        const schedule = rule.when.schedule;
+        let pattern;
+        try {
+            pattern = new Cron(schedule, { paused: true });
+        }
+        catch (err) {
+            throw new Error(`CronScheduler: invalid cron expression for rule "${rule.name}": ${schedule} (${err instanceof Error ? err.message : String(err)})`);
+        }
+        const entry = {
+            rule,
+            schedule,
+            pattern,
+            timer: null,
+            nextAt: null,
+        };
+        this.entries.set(rule.name, entry);
+        if (this.started && !this.stopped)
+            this.arm(entry);
+    }
+    unregister(ruleName) {
+        const e = this.entries.get(ruleName);
+        if (!e)
+            return;
+        if (e.timer)
+            clearTimeout(e.timer);
+        try {
+            e.pattern.stop();
+        }
+        catch {
+            // croner throws when already stopped — ignore.
+        }
+        this.entries.delete(ruleName);
+    }
+    start() {
+        if (this.stopped) {
+            throw new Error('CronScheduler: cannot start after stop().');
+        }
+        if (this.started)
+            return;
+        this.started = true;
+        for (const entry of this.entries.values())
+            this.arm(entry);
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.started = false;
+        for (const e of this.entries.values()) {
+            if (e.timer)
+                clearTimeout(e.timer);
+            e.timer = null;
+            try {
+                e.pattern.stop();
+            }
+            catch {
+                // ignore
+            }
+        }
+    }
+    /**
+     * Test helper — compute the pattern's next run after a reference
+     * timestamp without actually scheduling it. Handy for regression tests.
+     */
+    nextRunAfter(ruleName, after) {
+        const e = this.entries.get(ruleName);
+        if (!e)
+            return null;
+        return e.pattern.nextRun(after) ?? null;
+    }
+    /**
+     * Test helper — fire a rule immediately, bypassing the timer. Used by
+     * unit tests to skip vi.advanceTimersByTime logic when the focus is on
+     * dispatch behaviour, not scheduling accuracy.
+     */
+    async fireNowForTest(ruleName) {
+        const e = this.entries.get(ruleName);
+        if (!e)
+            throw new Error(`CronScheduler.fireNowForTest: no rule "${ruleName}"`);
+        await this.fire(e);
+    }
+    nowDate() {
+        return this.opts.now ? this.opts.now() : new Date();
+    }
+    arm(entry) {
+        if (this.stopped)
+            return;
+        const now = this.nowDate();
+        const next = entry.pattern.nextRun(now);
+        if (!next) {
+            entry.nextAt = null;
+            return;
+        }
+        entry.nextAt = next;
+        const delayMs = Math.max(0, next.getTime() - now.getTime());
+        entry.timer = setTimeout(() => {
+            entry.timer = null;
+            // Fire and then re-arm, regardless of outcome — we never want one
+            // misbehaving rule to kill its own future ticks.
+            this.fire(entry)
+                .catch(() => undefined)
+                .finally(() => {
+                if (!this.stopped && this.entries.has(entry.rule.name))
+                    this.arm(entry);
+            });
+        }, delayMs);
+        // Unref so a process with only cron rules still exits on SIGINT when
+        // the user expects (e.g. in integration tests).
+        if (typeof entry.timer.unref === 'function') {
+            entry.timer.unref();
+        }
+    }
+    async fire(entry) {
+        const when = this.nowDate();
+        // Apply the optional day-of-week filter before dispatching.
+        const trigger = entry.rule.when;
+        if (trigger.source === 'cron' && !matchesDayFilter(trigger.days, when)) {
+            return;
+        }
+        const event = {
+            source: 'cron',
+            event: entry.schedule,
+            t: when,
+            payload: { schedule: entry.schedule },
+        };
+        await this.opts.dispatch(entry.rule, event);
+    }
+}

package/dist/rules/destructive.js

@@ -0,0 +1,52 @@
+/**
+ * Destructive command parsing — single source of truth shared between the
+ * policy validator post-hook (rejects destructive commands inside
+ * `automation.rules[].then[].command`) and the runtime executor (second-
+ * line guard that refuses to shell out even if validation was bypassed).
+ */
+export const DESTRUCTIVE_COMMANDS = [
+    'lock',
+    'unlock',
+    'deleteWebhook',
+    'deleteScene',
+    'factoryReset',
+];
+/**
+ * Parse the verb out of a rule action command string. The expected form
+ * mirrors what the engine will eventually build: `devices command <id> <verb> [args...]`.
+ * We also accept scene shorthands (`scenes run <id>`, `webhooks delete <id>`).
+ *
+ * Returns null for anything we cannot confidently attribute to a known verb
+ * slot — the validator treats null as "probably fine, let the engine's own
+ * guard handle it if it's not."
+ */
+export function extractVerb(cmd) {
+    const trimmed = cmd.trim();
+    if (!trimmed)
+        return null;
+    const tokens = trimmed.split(/\s+/);
+    // `devices command <id> <verb> [args]`
+    if (tokens[0] === 'devices' && tokens[1] === 'command' && tokens.length >= 4) {
+        return tokens[3];
+    }
+    // `webhooks delete <id>` → verb is "deleteWebhook"
+    if (tokens[0] === 'webhooks' && tokens[1] === 'delete')
+        return 'deleteWebhook';
+    // `scenes delete <id>` → verb is "deleteScene"
+    if (tokens[0] === 'scenes' && tokens[1] === 'delete')
+        return 'deleteScene';
+    return null;
+}
+export function isDestructiveCommand(cmd) {
+    const verb = extractVerb(cmd);
+    if (!verb)
+        return false;
+    return DESTRUCTIVE_COMMANDS.includes(verb);
+}
+export function destructiveVerbOf(cmd) {
+    const verb = extractVerb(cmd);
+    if (verb && DESTRUCTIVE_COMMANDS.includes(verb)) {
+        return verb;
+    }
+    return null;
+}