@switchbot/openapi-cli 3.1.1 → 3.2.0

package/dist/rules/action.js

@@ -1,216 +0,0 @@
-/**
- * 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 };
-    }
-}
-/**
- * Extract the raw deviceId from an action object without alias resolution.
- * Prefers `action.device` over the deviceId embedded in the command string.
- * Use resolveActionDevice() when alias resolution is needed.
- */
-export function extractDeviceIdFromAction(action) {
-    if (action.device)
-        return action.device;
-    const m = /\bdevices\s+command\s+(\S+)/.exec(action.command ?? '');
-    return m ? m[1] : null;
-}

package/dist/rules/audit-query.js

@@ -1,89 +0,0 @@
-/**
- * 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/conflict-analyzer.js

@@ -1,214 +0,0 @@
-/**
- * Static conflict analysis for automation rules.
- *
- * Detects patterns that are technically valid but likely to cause
- * operational problems:
- *
- *   1. Opposing-action pairs — same device, opposite commands (e.g.
- *      turnOn / turnOff), triggered by the same source within a short
- *      window and with no throttle on either rule.
- *
- *   2. High-frequency MQTT rules without throttle — rules that listen
- *      on `device.shadow` (catch-all) with no throttle can fire on
- *      every shadow push (up to once per second) and exhaust the daily
- *      API quota quickly.
- *
- *   3. Potentially-destructive action without quiet-hours protection —
- *      a rule that targets a destructive verb is technically blocked by
- *      the engine, but we can still flag it early so users don't get a
- *      surprise at runtime.
- *
- * Results are designed to be consumed by `rules doctor --json` and
- * by CI pipelines. Each finding carries a `severity` so callers can
- * decide how to gate on them.
- */
-import { isTimeBetween, isAllCondition, isAnyCondition, isNotCondition } from './types.js';
-import { parseMaxPerMs } from './throttle.js';
-import { isDestructiveCommand } from './destructive.js';
-import { extractDeviceIdFromAction } from './action.js';
-/** Known opposing command pairs (order-independent). */
-const OPPOSING_PAIRS = [
-    ['turnOn', 'turnOff'],
-    ['lock', 'unlock'],
-    ['open', 'close'],
-    ['openDoor', 'closeDoor'],
-    ['openCurtain', 'closeCurtain'],
-    ['turnOn', 'standby'],
-    ['brightnessUp', 'brightnessDown'],
-    ['volumeUp', 'volumeDown'],
-    ['fanSpeedUp', 'fanSpeedDown'],
-];
-/**
- * MQTT events that fire on every device state push and can rapidly exhaust
- * the daily API quota when a rule has no throttle.
- *
- * Conditional events like `motion.detected` are intentionally excluded —
- * they fire discretely, not at continuous high frequency. Extend this set
- * when new catch-all or near-continuous event types are added to the classifier.
- */
-export const HIGH_FREQ_EVENTS = ['device.shadow', '*'];
-/** Returns true when an MQTT event is known to fire at high frequency. */
-export function isHighFreqEvent(event) {
-    return HIGH_FREQ_EVENTS.includes(event);
-}
-function commandsAreOpposing(a, b) {
-    for (const [x, y] of OPPOSING_PAIRS) {
-        if ((a === x && b === y) || (a === y && b === x))
-            return true;
-    }
-    return false;
-}
-function extractCommandVerb(command) {
-    // command strings are like "devices command <id> turnOn" — extract last token
-    const parts = command.trim().split(/\s+/);
-    return parts[parts.length - 1] ?? command;
-}
-function effectiveCooldownMs(rule) {
-    if (rule.cooldown) {
-        try {
-            return parseMaxPerMs(rule.cooldown);
-        }
-        catch {
-            return null;
-        }
-    }
-    if (rule.throttle?.max_per) {
-        try {
-            return parseMaxPerMs(rule.throttle.max_per);
-        }
-        catch {
-            return null;
-        }
-    }
-    return null;
-}
-function hasTimeBetweenGuard(conditions) {
-    if (!conditions)
-        return false;
-    for (const c of conditions) {
-        if (isTimeBetween(c))
-            return true;
-        if (isAllCondition(c) && hasTimeBetweenGuard(c.all))
-            return true;
-        if (isAnyCondition(c) && hasTimeBetweenGuard(c.any))
-            return true;
-        if (isNotCondition(c) && hasTimeBetweenGuard([c.not]))
-            return true;
-    }
-    return false;
-}
-export function analyzeConflicts(rules, quietHours) {
-    const findings = [];
-    const active = rules.filter((r) => r.enabled !== false);
-    // 1. Opposing-action pairs on the same device
-    for (let i = 0; i < active.length; i++) {
-        for (let j = i + 1; j < active.length; j++) {
-            const a = active[i];
-            const b = active[j];
-            // Only flag when they share the same trigger source (otherwise they
-            // can't race each other in normal operation).
-            if (a.when.source !== b.when.source)
-                continue;
-            const cooldownA = effectiveCooldownMs(a);
-            const cooldownB = effectiveCooldownMs(b);
-            // If both rules have meaningful cooldowns (≥ 5 minutes), the risk is
-            // low — skip.
-            const bothThrottled = cooldownA !== null && cooldownA >= 5 * 60_000 &&
-                cooldownB !== null && cooldownB >= 5 * 60_000;
-            if (bothThrottled)
-                continue;
-            for (const actionA of a.then) {
-                for (const actionB of b.then) {
-                    const deviceA = extractDeviceIdFromAction(actionA);
-                    const deviceB = extractDeviceIdFromAction(actionB);
-                    // Skip if devices can't be compared.
-                    if (!deviceA || !deviceB || deviceA !== deviceB)
-                        continue;
-                    const verbA = extractCommandVerb(actionA.command);
-                    const verbB = extractCommandVerb(actionB.command);
-                    if (commandsAreOpposing(verbA, verbB)) {
-                        const noThrottle = cooldownA === null || cooldownB === null;
-                        findings.push({
-                            severity: noThrottle ? 'warning' : 'info',
-                            code: 'opposing-actions',
-                            message: `Rules "${a.name}" and "${b.name}" issue opposing commands (${verbA} / ${verbB}) on device "${deviceA}" via the same trigger source.`,
-                            rules: [a.name, b.name],
-                            hint: noThrottle
-                                ? 'Add a "cooldown" or "throttle.max_per" to both rules to prevent rapid state oscillation.'
-                                : undefined,
-                        });
-                    }
-                }
-            }
-        }
-    }
-    // 2. High-frequency MQTT catch-all rules without throttle
-    for (const rule of active) {
-        if (rule.when.source !== 'mqtt')
-            continue;
-        const event = rule.when.event;
-        const isHighFreq = isHighFreqEvent(event);
-        if (!isHighFreq)
-            continue;
-        const cooldown = effectiveCooldownMs(rule);
-        if (cooldown === null) {
-            findings.push({
-                severity: 'warning',
-                code: 'high-frequency-no-throttle',
-                message: `Rule "${rule.name}" listens on "${event}" (high-frequency catch-all) with no throttle/cooldown. This can rapidly exhaust the daily API quota.`,
-                rules: [rule.name],
-                hint: 'Add "cooldown: 1m" or "throttle: { max_per: 1m }" to rate-limit this rule.',
-            });
-        }
-        else if (cooldown < 30_000) {
-            findings.push({
-                severity: 'info',
-                code: 'high-frequency-low-throttle',
-                message: `Rule "${rule.name}" listens on "${event}" with a throttle under 30 s. Consider increasing to at least 1 m to protect API quota.`,
-                rules: [rule.name],
-            });
-        }
-    }
-    // 3. Destructive actions in rules (engine blocks these at runtime, but
-    //    surface early with clear guidance).
-    for (const rule of active) {
-        for (let i = 0; i < rule.then.length; i++) {
-            const verb = extractCommandVerb(rule.then[i].command);
-            if (isDestructiveCommand(verb)) {
-                findings.push({
-                    severity: 'error',
-                    code: 'destructive-action-in-rule',
-                    message: `Rule "${rule.name}" then[${i}] contains destructive command "${verb}". The engine blocks this at runtime.`,
-                    rules: [rule.name],
-                    hint: 'Remove the destructive command or replace it with a non-destructive alternative.',
-                });
-            }
-        }
-    }
-    // 4. Event-driven rules with no time_between guard when quiet_hours is defined.
-    //    Cron rules fire on an explicit schedule so their overlap with quiet hours
-    //    requires schedule analysis — flag those separately when needed.
-    if (quietHours?.start && quietHours?.end) {
-        for (const rule of active) {
-            if (rule.when.source === 'cron')
-                continue;
-            if (!hasTimeBetweenGuard(rule.conditions)) {
-                findings.push({
-                    severity: 'warning',
-                    code: 'no-quiet-hours-guard',
-                    message: `Rule "${rule.name}" (${rule.when.source} trigger) has no time_between condition and may fire during quiet hours (${quietHours.start}–${quietHours.end}).`,
-                    rules: [rule.name],
-                    hint: `Add a conditions entry "{ time_between: ['${quietHours.end}', '${quietHours.start}'] }" to block this rule during quiet hours.`,
-                });
-            }
-        }
-    }
-    const counts = { error: 0, warning: 0, info: 0 };
-    for (const f of findings)
-        counts[f.severity]++;
-    return {
-        findings,
-        counts,
-        clean: counts.error === 0,
-    };
-}