@switchbot/openapi-cli 3.2.0 → 3.2.1

package/dist/rules/cron-scheduler.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 type { EngineEvent, Rule, DayOfWeek } from './types.js';
+/** Return true if `t` falls on one of the listed days (or days is absent/empty). */
+export declare function matchesDayFilter(days: DayOfWeek[] | undefined, t: Date): boolean;
+export interface CronDispatch {
+    (rule: Rule, event: EngineEvent): Promise<void>;
+}
+export interface CronSchedulerOptions {
+    /** Dispatch callback — the engine's queue wrapper that runs the rule. */
+    dispatch: CronDispatch;
+    /** Clock injection for tests; defaults to Date.now. */
+    now?: () => Date;
+}
+export declare class CronScheduler {
+    private readonly opts;
+    private readonly entries;
+    private started;
+    private stopped;
+    constructor(opts: CronSchedulerOptions);
+    getScheduledFor(ruleName: string): {
+        schedule: string;
+        nextAt: Date | null;
+    } | null;
+    hasRegistered(ruleName: string): boolean;
+    /**
+     * Register a cron rule. Validates the pattern eagerly — an invalid
+     * schedule throws synchronously so engine start can surface the error.
+     */
+    register(rule: Rule): void;
+    unregister(ruleName: string): void;
+    start(): void;
+    stop(): void;
+    /**
+     * Test helper — compute the pattern's next run after a reference
+     * timestamp without actually scheduling it. Handy for regression tests.
+     */
+    nextRunAfter(ruleName: string, after: Date): Date | 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.
+     */
+    fireNowForTest(ruleName: string): Promise<void>;
+    private nowDate;
+    private arm;
+    private fire;
+}

package/dist/rules/cron-scheduler.js

@@ -0,0 +1,187 @@
+/**
+ * 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);
+    }
+}
+//# sourceMappingURL=cron-scheduler.js.map

package/dist/rules/cron-scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cron-scheduler.js","sourceRoot":"","sources":["../../src/rules/cron-scheduler.ts"],"names":[],"mappings":"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"}

package/dist/rules/destructive.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 declare const DESTRUCTIVE_COMMANDS: readonly ["lock", "unlock", "deleteWebhook", "deleteScene", "factoryReset"];
+export type DestructiveCommand = (typeof DESTRUCTIVE_COMMANDS)[number];
+/**
+ * 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 declare function extractVerb(cmd: string): string | null;
+export declare function isDestructiveCommand(cmd: string): boolean;
+export declare function destructiveVerbOf(cmd: string): DestructiveCommand | null;

package/dist/rules/destructive.js

@@ -0,0 +1,53 @@
+/**
+ * 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;
+}
+//# sourceMappingURL=destructive.js.map

package/dist/rules/destructive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destructive.js","sourceRoot":"","sources":["../../src/rules/destructive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,MAAM;IACN,QAAQ;IACR,eAAe;IACf,aAAa;IACb,cAAc;CACN,CAAC;AAIX;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,GAAW;IACrC,MAAM,OAAO,GAAG,GAAG,CAAC,IAAI,EAAE,CAAC;IAC3B,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAEpC,uCAAuC;IACvC,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,MAAM,IAAI,CAAC,EAAE,CAAC;QAC7E,OAAO,MAAM,CAAC,CAAC,CAAC,CAAC;IACnB,CAAC;IACD,mDAAmD;IACnD,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,UAAU,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ;QAAE,OAAO,eAAe,CAAC;IAC/E,+CAA+C;IAC/C,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ,IAAI,MAAM,CAAC,CAAC,CAAC,KAAK,QAAQ;QAAE,OAAO,aAAa,CAAC;IAC3E,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAQ,oBAA0C,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AACpE,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAAW;IAC3C,MAAM,IAAI,GAAG,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,IAAI,IAAI,IAAK,oBAA0C,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACvE,OAAO,IAA0B,CAAC;IACpC,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/rules/engine.d.ts

@@ -0,0 +1,193 @@
+/**
+ * Rules engine runtime — orchestrates trigger subscription, matcher
+ * pipeline, throttle gate, and action executor.
+ *
+ * v0.2 PoC scope:
+ *   - Loads an `automation` block from a policy file.
+ *   - Subscribes to a single MQTT client; routes every shadow message
+ *     through `matchesMqttTrigger` → `evaluateConditions` → throttle →
+ *     `executeRuleAction`.
+ *   - Cron + webhook triggers are **recognised but not wired** — they
+ *     surface in the static lint as `unsupported` so users know the
+ *     feature is pending (E1/E2 fill it in without a schema change).
+ *   - Exposes `start()`, `stop()`, `getStats()` for the rules run
+ *     subcommand.
+ *
+ * Not responsible for: loading the policy file, validating it, talking
+ * to the SwitchBot REST API (that's `executeCommand`), or writing
+ * audit lines (that's each module's local responsibility).
+ */
+import type { AxiosInstance } from 'axios';
+import type { SwitchBotMqttClient } from '../mqtt/client.js';
+import type { MqttCredential } from '../mqtt/credential.js';
+import { type DeviceStatusFetcher } from './matcher.js';
+import { type AutomationBlock, type EngineEvent, type Rule } from './types.js';
+export interface LintIssue {
+    rule: string;
+    severity: 'error' | 'warning';
+    code: string;
+    message: string;
+}
+export interface LintResult {
+    rules: Array<{
+        name: string;
+        enabled: boolean;
+        status: 'ok' | 'error' | 'unsupported' | 'disabled';
+        issues: LintIssue[];
+    }>;
+    valid: boolean;
+    unsupportedCount: number;
+}
+export declare function lintRules(automation: AutomationBlock | null | undefined): LintResult;
+export interface RulesEngineOptions {
+    automation: AutomationBlock | null | undefined;
+    aliases: Record<string, string>;
+    /** Pre-connected MQTT client — owned by the caller. */
+    mqttClient: SwitchBotMqttClient;
+    /** Credential exposed so we know the default shadow topic to subscribe to. */
+    mqttCredential: MqttCredential;
+    /** Optional HTTP client for executeCommand — omit in tests. */
+    httpClient?: AxiosInstance;
+    /** When true, treat every rule as dry_run regardless of policy. */
+    globalDryRun?: boolean;
+    /** Max firings before the engine self-stops — test / demo only. */
+    maxFirings?: number;
+    /** Suppress live API calls. Used by tests that don't want to mock axios. */
+    skipApiCall?: boolean;
+    /** Side channel for unit tests — drop every processed event here. */
+    onFire?: (entry: EngineFireEntry) => void;
+    /**
+     * Webhook bearer token. Required when any rule uses a webhook
+     * trigger; the listener will refuse to start otherwise.
+     */
+    webhookToken?: string;
+    /** Webhook listener port (default 18790). Set 0 to auto-allocate. */
+    webhookPort?: number;
+    /** Webhook listener host (default 127.0.0.1). */
+    webhookHost?: string;
+    /**
+     * Override how device_state conditions fetch live status. Primarily a
+     * test seam — production callers should leave it unset so the engine
+     * goes through the normal `fetchDeviceStatus` path with the shared
+     * axios client.
+     */
+    statusFetcher?: DeviceStatusFetcher;
+}
+export interface EngineFireEntry {
+    ruleName: string;
+    fireId: string;
+    /** Final disposition of the fire. */
+    status: 'fired' | 'dry' | 'throttled' | 'conditions-failed' | 'unsupported' | 'blocked';
+    deviceId?: string;
+    reason?: string;
+}
+export interface EngineStats {
+    started: boolean;
+    rulesLoaded: number;
+    rulesActive: number;
+    eventsProcessed: number;
+    fires: number;
+    dryFires: number;
+    throttled: number;
+    conditionsFailed: number;
+}
+export declare class RulesEngine {
+    private readonly opts;
+    private rules;
+    private aliases;
+    private readonly throttle;
+    /** hysteresis / requires_stable_for: tracks when each (rule::device) trigger was first seen. */
+    private hysteresisFirstSeen;
+    private unsubscribeMessage;
+    private unsubscribeState;
+    private cronScheduler;
+    private webhookListener;
+    private started;
+    private stopped;
+    /**
+     * Sequential dispatch queue. Two MQTT messages arriving in the same
+     * tick would otherwise race inside the throttle check — each sees an
+     * empty lastFireAt map because neither has recorded yet. Serialising
+     * keeps the semantics of `max_per` honest.
+     */
+    private pendingChain;
+    private stats;
+    constructor(opts: RulesEngineOptions);
+    getStats(): EngineStats;
+    getRules(): readonly Rule[];
+    /**
+     * Subscribes to MQTT and begins the pipeline. Throws if the policy
+     * block is missing `enabled: true` or if lint finds errors (e.g.
+     * destructive command in a rule action).
+     */
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Hot-reload the running engine with a fresh automation block and
+     * alias map — typically triggered by SIGHUP or by the `rules reload`
+     * subcommand writing the reload sentinel file.
+     *
+     * Semantics:
+     *   - Rejects (and keeps the old ruleset) when the new automation is
+     *     disabled or fails lint. The engine never silently degrades.
+     *   - Diffs cron registrations by `rule.name` + `schedule`: unchanged
+     *     entries keep their armed timer, changed/removed entries are
+     *     unregistered, new entries are registered and armed.
+     *   - Hands the fresh webhook rule list to the live listener (keeps
+     *     the bound port / open connections). If the reload removes every
+     *     webhook rule the listener is torn down; if it adds the first
+     *     webhook rule we refuse — spinning up a new listener mid-run
+     *     would silently change the security surface.
+     *   - `ThrottleGate` state is retained for surviving rule names and
+     *     dropped for removed ones. A rule that was throttled before the
+     *     reload stays throttled after it (same name = same window), but
+     *     a renamed rule resets.
+     */
+    reload(nextAutomation: AutomationBlock | null | undefined, nextAliases?: Record<string, string>): Promise<{
+        changed: boolean;
+        errors: string[];
+        warnings: string[];
+    }>;
+    /**
+     * Expose the MQTT pipeline for direct invocation from tests — feeds a
+     * synthetic payload through the same matcher/throttle/action chain.
+     */
+    ingestMqttForTest(payload: unknown): Promise<void>;
+    /**
+     * Dispatch a pre-built EngineEvent through all matching MQTT rules.
+     * Used by tests that need full control over the event timestamp (e.g.
+     * hysteresis tests that advance time manually).
+     */
+    ingestEventForTest(event: EngineEvent): Promise<void>;
+    /**
+     * Fire a cron rule directly without needing the scheduler/timers.
+     * Used by tests that want to exercise the dispatch pipeline without
+     * depending on fake timers or croner's internals.
+     */
+    ingestCronForTest(rule: Rule, when?: Date): Promise<void>;
+    /**
+     * Fire a webhook rule directly without standing up the HTTP listener.
+     */
+    ingestWebhookForTest(rule: Rule, body?: string, when?: Date): Promise<void>;
+    /** Returns the bound webhook port when the listener is active. */
+    getWebhookPort(): number | null;
+    /** Read-only peek at cron schedule state — for `rules list` extras. */
+    getCronSchedule(ruleName: string): {
+        schedule: string;
+        nextAt: Date | null;
+    } | null;
+    /** Test helper — resolves after all queued dispatches complete. */
+    drainForTest(): Promise<void>;
+    /**
+     * Append a task to the dispatch queue; callers get back a promise that
+     * resolves when their task finishes (errors are swallowed — we never
+     * want the queue itself to die because one rule threw). Returning a
+     * promise lets awaited callsites (ingestMqttForTest) observe completion.
+     */
+    private enqueue;
+    private onMqttMessage;
+    private onCronFire;
+    private onWebhookFire;
+    private firesTotal;
+    private dispatchRule;
+}