@switchbot/openapi-cli 2.7.2 → 3.0.0

package/dist/policy/schema.js

@@ -0,0 +1,18 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+export const SUPPORTED_POLICY_SCHEMA_VERSIONS = ['0.2'];
+export const CURRENT_POLICY_SCHEMA_VERSION = '0.2';
+const schemaCache = new Map();
+export function loadPolicySchema(version = CURRENT_POLICY_SCHEMA_VERSION) {
+    const cached = schemaCache.get(version);
+    if (cached)
+        return cached;
+    const url = new URL(`./schema/v${version}.json`, import.meta.url);
+    const raw = readFileSync(fileURLToPath(url), 'utf-8');
+    const parsed = JSON.parse(raw);
+    schemaCache.set(version, parsed);
+    return parsed;
+}
+export function isSupportedPolicySchemaVersion(v) {
+    return typeof v === 'string' && SUPPORTED_POLICY_SCHEMA_VERSIONS.includes(v);
+}

package/dist/policy/validate.js

@@ -0,0 +1,262 @@
+import { createRequire } from 'node:module';
+import { Ajv2020 } from 'ajv/dist/2020.js';
+import { isMap, isSeq, isScalar } from 'yaml';
+import { loadPolicyFile } from './load.js';
+import { loadPolicySchema, CURRENT_POLICY_SCHEMA_VERSION, SUPPORTED_POLICY_SCHEMA_VERSIONS, isSupportedPolicySchemaVersion, } from './schema.js';
+import { destructiveVerbOf, DESTRUCTIVE_COMMANDS } from '../rules/destructive.js';
+const require = createRequire(import.meta.url);
+const addFormats = require('ajv-formats');
+const validators = new Map();
+function getValidator(version) {
+    const cached = validators.get(version);
+    if (cached)
+        return cached;
+    const ajv = new Ajv2020({ allErrors: true, strict: false, allowUnionTypes: true });
+    addFormats(ajv);
+    const schema = loadPolicySchema(version);
+    const validate = ajv.compile(schema);
+    const compiled = { ajv, validate };
+    validators.set(version, compiled);
+    return compiled;
+}
+function instancePathToSegments(instancePath) {
+    if (!instancePath)
+        return [];
+    return instancePath
+        .slice(1)
+        .split('/')
+        .map((s) => s.replace(/~1/g, '/').replace(/~0/g, '~'));
+}
+function getNodeAt(doc, segments) {
+    let current = doc.contents;
+    for (const seg of segments) {
+        if (isMap(current)) {
+            const pair = current.items.find((p) => {
+                const k = p.key;
+                if (isScalar(k))
+                    return String(k.value) === seg;
+                return false;
+            });
+            if (!pair)
+                return null;
+            current = pair.value;
+        }
+        else if (isSeq(current)) {
+            const idx = Number(seg);
+            if (!Number.isInteger(idx))
+                return null;
+            current = current.items[idx];
+        }
+        else {
+            return null;
+        }
+    }
+    return current ?? null;
+}
+function getKeyNodeAt(doc, parentSegments, key) {
+    const parent = parentSegments.length === 0 ? doc.contents : getNodeAt(doc, parentSegments);
+    if (!parent || !isMap(parent))
+        return null;
+    const pair = parent.items.find((p) => isScalar(p.key) && String(p.key.value) === key);
+    return pair?.key ?? null;
+}
+function locateError(doc, lineCounter, err) {
+    const segments = instancePathToSegments(err.instancePath);
+    if (err.keyword === 'additionalProperties') {
+        const bad = err.params.additionalProperty;
+        if (bad) {
+            const keyNode = getKeyNodeAt(doc, segments, bad);
+            const range = keyNode?.range;
+            if (range) {
+                const pos = lineCounter.linePos(range[0]);
+                return { line: pos.line, col: pos.col };
+            }
+        }
+    }
+    if (err.keyword === 'required' || err.keyword === 'dependentRequired') {
+        const node = getNodeAt(doc, segments);
+        const range = node?.range;
+        if (range) {
+            const pos = lineCounter.linePos(range[0]);
+            return { line: pos.line, col: pos.col };
+        }
+        return { line: 1, col: 1 };
+    }
+    const node = getNodeAt(doc, segments);
+    const range = node?.range;
+    if (!range)
+        return {};
+    const pos = lineCounter.linePos(range[0]);
+    return { line: pos.line, col: pos.col };
+}
+function humanMessage(err) {
+    const path = err.instancePath || '(root)';
+    switch (err.keyword) {
+        case 'required':
+            return `missing required property "${err.params.missingProperty}"`;
+        case 'additionalProperties':
+            return `unknown property "${err.params.additionalProperty}"`;
+        case 'dependentRequired': {
+            const { property, missingProperty } = err.params;
+            const parent = path === '(root)' ? '' : `${path}: `;
+            return `${parent}when "${property}" is set, "${missingProperty}" is also required`;
+        }
+        case 'pattern':
+            return `${path} does not match pattern ${err.params.pattern}`;
+        case 'const':
+            return `${path} must be exactly ${JSON.stringify(err.params.allowedValue)}`;
+        case 'enum':
+            return `${path} must be one of ${JSON.stringify(err.params.allowedValues)}`;
+        case 'type':
+            return `${path} must be ${err.params.type}`;
+        case 'not':
+            return `${path} is not allowed here`;
+        default:
+            return `${path} ${err.message ?? 'is invalid'}`;
+    }
+}
+function hintFor(err) {
+    if (err.keyword === 'pattern' && err.instancePath.startsWith('/aliases/')) {
+        return 'paste the deviceId from `switchbot devices list --format=tsv`, e.g. 01-202407090924-26354212';
+    }
+    if (err.keyword === 'not' && err.instancePath.startsWith('/confirmations/never_confirm/')) {
+        return 'destructive actions (lock/unlock/delete*/factoryReset) cannot be pre-approved in policy.yaml';
+    }
+    if (err.keyword === 'const' && err.instancePath === '/version') {
+        const supported = SUPPORTED_POLICY_SCHEMA_VERSIONS.map((v) => `"${v}"`).join(' / ');
+        return `this CLI supports policy schema versions ${supported}; run \`switchbot policy migrate\` to upgrade an older file`;
+    }
+    if (err.keyword === 'required' && err.instancePath === '') {
+        const missing = err.params.missingProperty;
+        if (missing === 'version')
+            return `add \`version: "${CURRENT_POLICY_SCHEMA_VERSION}"\` at the top of the file`;
+    }
+    return undefined;
+}
+function readDeclaredVersion(data) {
+    if (data && typeof data === 'object' && 'version' in data) {
+        const v = data.version;
+        if (typeof v === 'string')
+            return v;
+    }
+    return undefined;
+}
+function unsupportedVersionResult(loaded, declared) {
+    const supported = SUPPORTED_POLICY_SCHEMA_VERSIONS.map((v) => `"${v}"`).join(' / ');
+    const isLegacy = declared === '0.1';
+    const hint = isLegacy
+        ? `v0.1 policy support was removed in v3.0. Run \`switchbot policy migrate\` with CLI ≤2.15 first, then upgrade.`
+        : `supported versions: ${supported}. upgrade the CLI or downgrade the file.`;
+    return {
+        policyPath: loaded.path,
+        schemaVersion: CURRENT_POLICY_SCHEMA_VERSION,
+        valid: false,
+        errors: [
+            {
+                path: '/version',
+                line: 1,
+                col: 1,
+                keyword: 'unsupported-version',
+                message: `policy schema version "${declared}" is not supported by this CLI`,
+                hint,
+                schemaPath: '#/properties/version',
+            },
+        ],
+    };
+}
+/**
+ * Walk `automation.rules[].then[]` and flag any command string whose verb
+ * appears in DESTRUCTIVE_COMMANDS. Uses the YAML doc (not the data tree) to
+ * get accurate line/col on the offending node.
+ *
+ * This is deliberately a post-ajv pass rather than a schema rule because
+ * JSON Schema cannot parse a command string and compare the verb slot to a
+ * blocklist. Keeping it in JS also lets `src/rules/destructive.ts` be the
+ * single source of truth shared with the runtime executor.
+ */
+function collectDestructiveRuleErrors(loaded) {
+    const data = loaded.data;
+    const rules = data?.automation?.rules;
+    if (!Array.isArray(rules))
+        return [];
+    const out = [];
+    for (let ri = 0; ri < rules.length; ri++) {
+        const rule = rules[ri];
+        const actions = Array.isArray(rule?.then) ? rule.then : [];
+        for (let ai = 0; ai < actions.length; ai++) {
+            const cmd = actions[ai]?.command;
+            if (typeof cmd !== 'string')
+                continue;
+            const verb = destructiveVerbOf(cmd);
+            if (!verb)
+                continue;
+            const instancePath = `/automation/rules/${ri}/then/${ai}/command`;
+            const segments = instancePath.slice(1).split('/');
+            const node = getNodeAt(loaded.doc, segments);
+            const range = node?.range;
+            let line;
+            let col;
+            if (range) {
+                const pos = loaded.lineCounter.linePos(range[0]);
+                line = pos.line;
+                col = pos.col;
+            }
+            const ruleName = typeof rule?.name === 'string' ? rule.name : `#${ri}`;
+            out.push({
+                path: instancePath,
+                line,
+                col,
+                keyword: 'rule-destructive-action',
+                message: `rule "${ruleName}" action #${ai} uses destructive command "${verb}"`,
+                hint: `destructive verbs (${DESTRUCTIVE_COMMANDS.join(', ')}) cannot be pre-approved in automation rules; run them via the interactive CLI so the confirmation gate fires`,
+                schemaPath: '#/properties/automation/properties/rules/items/properties/then/items/properties/command',
+            });
+        }
+    }
+    return out;
+}
+export function validateLoadedPolicy(loaded) {
+    const declared = readDeclaredVersion(loaded.data);
+    if (declared !== undefined && !isSupportedPolicySchemaVersion(declared)) {
+        return unsupportedVersionResult(loaded, declared);
+    }
+    const version = isSupportedPolicySchemaVersion(declared)
+        ? declared
+        : CURRENT_POLICY_SCHEMA_VERSION;
+    const { validate } = getValidator(version);
+    const ok = validate(loaded.data);
+    const errors = [];
+    if (!ok && validate.errors) {
+        for (const err of validate.errors) {
+            const { line, col } = locateError(loaded.doc, loaded.lineCounter, err);
+            errors.push({
+                path: err.instancePath || '',
+                line,
+                col,
+                keyword: err.keyword,
+                message: humanMessage(err),
+                hint: hintFor(err),
+                schemaPath: err.schemaPath,
+            });
+        }
+    }
+    // v0.2-only post-hook: destructive verbs like `unlock` / `factoryReset`
+    // cannot be pre-approved via rules, even if ajv considers the command
+    // string well-formed. Schema can't express this because `command` is a
+    // free-form string; we parse the verb in JS and append errors.
+    if (version === '0.2') {
+        const ruleErrors = collectDestructiveRuleErrors(loaded);
+        errors.push(...ruleErrors);
+    }
+    const valid = ok === true && errors.length === 0;
+    return {
+        policyPath: loaded.path,
+        schemaVersion: version,
+        valid,
+        errors,
+    };
+}
+export function validatePolicyFile(policyPath) {
+    const loaded = loadPolicyFile(policyPath);
+    return validateLoadedPolicy(loaded);
+}

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 };
+}