@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/policy/schema/v0.2.json

@@ -0,0 +1,331 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.openclaw.ai/switchbot/v0.2/policy.json",
+  "title": "OpenClaw SwitchBot policy v0.2",
+  "description": "Tightens the `automation.rules[]` shape that v0.1 left as a loose `array of object`. Validator reads this when the policy file's top-level `version` field is \"0.2\". See docs/design/phase4-rules-schema.md for the field-level rationale.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["version"],
+  "properties": {
+    "version": {
+      "type": "string",
+      "const": "0.2",
+      "description": "Policy schema version. Will migrate 0.1 -> 0.2 in place via `switchbot policy migrate`."
+    },
+
+    "aliases": {
+      "type": ["object", "null"],
+      "description": "Unchanged from v0.1.",
+      "additionalProperties": {
+        "type": "string",
+        "pattern": "^[A-Z0-9]{2,}-[A-Z0-9-]+$"
+      }
+    },
+
+    "confirmations": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Unchanged from v0.1.",
+      "properties": {
+        "always_confirm": {
+          "type": ["array", "null"],
+          "uniqueItems": true,
+          "items": { "type": "string", "minLength": 1 }
+        },
+        "never_confirm": {
+          "type": ["array", "null"],
+          "uniqueItems": true,
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "not": {
+              "enum": ["lock", "unlock", "deleteWebhook", "deleteScene", "factoryReset"]
+            }
+          }
+        }
+      }
+    },
+
+    "quiet_hours": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Unchanged from v0.1.",
+      "properties": {
+        "start": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" },
+        "end":   { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" }
+      },
+      "dependentRequired": { "start": ["end"], "end": ["start"] }
+    },
+
+    "audit": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "properties": {
+        "log_path":  { "type": "string", "minLength": 1 },
+        "retention": { "type": "string", "pattern": "^(never|\\d+[dwm])$" }
+      }
+    },
+
+    "automation": {
+      "type": ["object", "null"],
+      "description": "In v0.2, `rules[]` gets a real shape. `enabled: false` still fully disables the engine regardless of rules defined.",
+      "additionalProperties": false,
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "default": false
+        },
+        "rules": {
+          "type": ["array", "null"],
+          "items": { "$ref": "#/$defs/rule" }
+        }
+      }
+    },
+
+    "cli": {
+      "type": ["object", "null"],
+      "additionalProperties": false,
+      "description": "Unchanged from v0.1.",
+      "properties": {
+        "profile":   { "type": "string", "minLength": 1, "default": "default" },
+        "cache_ttl": { "type": "string", "pattern": "^\\d+[smh]$" }
+      }
+    }
+  },
+
+  "$defs": {
+    "rule": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name", "when", "then"],
+      "properties": {
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Human label used in audit log and dry-run output. Unique per policy file."
+        },
+        "enabled": {
+          "type": "boolean",
+          "default": true,
+          "description": "Lets you disable a single rule without deleting it."
+        },
+        "when": { "$ref": "#/$defs/trigger" },
+        "conditions": {
+          "type": ["array", "null"],
+          "description": "Optional AND-joined gates evaluated after the trigger matches. All must pass for the rule to fire.",
+          "items": { "$ref": "#/$defs/condition" }
+        },
+        "then": {
+          "type": "array",
+          "minItems": 1,
+          "description": "One or more actions executed in order. If any action fails, the remainder still runs (policy log records each result).",
+          "items": { "$ref": "#/$defs/action" }
+        },
+        "throttle": {
+          "type": ["object", "null"],
+          "additionalProperties": false,
+          "description": "Optional rate limit. Applied per-rule, keyed by the trigger's deviceId when present.",
+          "properties": {
+            "max_per": {
+              "type": "string",
+              "pattern": "^\\d+[smh]$",
+              "description": "Minimum spacing between fires, e.g. \"10m\". Later triggers inside the window are suppressed and audited."
+            },
+            "dedupe_window": {
+              "type": "string",
+              "pattern": "^\\d+[smh]$",
+              "description": "Deduplicate identical events arriving within this window after the last fire. Complements max_per: use when rapid sensor bursts should collapse into one action."
+            }
+          },
+          "required": ["max_per"]
+        },
+        "cooldown": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Shorthand cooldown — minimum pause after a rule fires before it can fire again. Equivalent to throttle.max_per but at rule level. Takes precedence over throttle.max_per when both are set."
+        },
+        "requires_stable_for": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Hysteresis guard — the triggering device state must remain stable (unchanged) for this duration before the rule fires. Prevents action storms from transient sensor flicker. Validated at lint; enforcement is best-effort in the engine."
+        },
+        "hysteresis": {
+          "type": "string",
+          "pattern": "^\\d+[smh]$",
+          "description": "Alias for requires_stable_for with clearer semantics. Takes precedence when both are set. The triggering state must be continuously observed for this duration before the rule fires."
+        },
+        "maxFiringsPerHour": {
+          "type": "integer",
+          "minimum": 1,
+          "description": "Maximum number of times this rule may fire in any rolling 60-minute window. Applied after cooldown/throttle checks. Useful as an absolute safety cap for high-frequency MQTT triggers."
+        },
+        "suppressIfAlreadyDesired": {
+          "type": "boolean",
+          "description": "When true, skip the rule's actions if the target device's last-known cached state already matches the expected outcome of the command (e.g. skip turnOn if powerState is already 'on'). Best-effort: requires a warm device cache."
+        },
+        "dry_run": {
+          "type": "boolean",
+          "default": true,
+          "description": "When true, actions write to the audit log (kind=dry-run) but do NOT hit the SwitchBot API."
+        }
+      }
+    },
+
+    "trigger": {
+      "type": "object",
+      "oneOf": [
+        { "$ref": "#/$defs/triggerMqtt" },
+        { "$ref": "#/$defs/triggerCron" },
+        { "$ref": "#/$defs/triggerWebhook" }
+      ]
+    },
+
+    "triggerMqtt": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "event"],
+      "properties": {
+        "source": { "const": "mqtt" },
+        "event": {
+          "type": "string",
+          "description": "Event type from `switchbot events mqtt-tail --json`, e.g. `motion.detected`, `contact.opened`, `button.pressed`, `device.shadow`."
+        },
+        "device": {
+          "type": "string",
+          "description": "Optional filter by deviceId or alias. Matches the trigger's `deviceId` payload field."
+        }
+      }
+    },
+
+    "triggerCron": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "schedule"],
+      "properties": {
+        "source": { "const": "cron" },
+        "schedule": {
+          "type": "string",
+          "description": "Standard 5-field cron (minute hour dom month dow). Interpreted in local system timezone."
+        },
+        "days": {
+          "type": "array",
+          "description": "Optional weekday filter applied after the cron expression fires. Values are full-name or 3-letter day abbreviations (case-insensitive): mon/monday … sun/sunday. When omitted, all days pass.",
+          "uniqueItems": true,
+          "minItems": 1,
+          "items": {
+            "type": "string",
+            "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun",
+                     "monday", "tuesday", "wednesday", "thursday", "friday", "saturday", "sunday"]
+          }
+        }
+      }
+    },
+
+    "triggerWebhook": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "path"],
+      "properties": {
+        "source": { "const": "webhook" },
+        "path": {
+          "type": "string",
+          "pattern": "^/[a-z0-9/_-]+$",
+          "description": "Local HTTP path the rule engine listens on. Auth + transport are configured elsewhere (Phase 3)."
+        }
+      }
+    },
+
+    "condition": {
+      "description": "Predicate evaluated after the trigger matches. Leaf shapes: time_between, device_state. Composites: all (AND), any (OR), not (negation). `additionalProperties: false` lives on each `oneOf` branch so keys are validated per-shape.",
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["time_between"],
+          "properties": {
+            "time_between": {
+              "type": "array",
+              "items": { "type": "string", "pattern": "^([01]\\d|2[0-3]):[0-5]\\d$" },
+              "minItems": 2,
+              "maxItems": 2,
+              "description": "Two HH:MM strings: [start, end]. End-before-start means overnight window."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["device", "field", "op", "value"],
+          "properties": {
+            "device": { "type": "string", "description": "deviceId or alias" },
+            "field":  { "type": "string", "description": "status field name, e.g. `online`, `power`, `brightness`" },
+            "op":     { "enum": ["==", "!=", "<", ">", "<=", ">="] },
+            "value":  { "description": "Literal to compare against. Booleans, strings, numbers." }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["all"],
+          "properties": {
+            "all": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/condition" },
+              "description": "All sub-conditions must be true (logical AND)."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["any"],
+          "properties": {
+            "any": {
+              "type": "array",
+              "minItems": 1,
+              "items": { "$ref": "#/$defs/condition" },
+              "description": "At least one sub-condition must be true (logical OR)."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["not"],
+          "properties": {
+            "not": {
+              "$ref": "#/$defs/condition",
+              "description": "Negates the sub-condition."
+            }
+          }
+        }
+      ]
+    },
+
+    "action": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["command"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "A CLI invocation fragment, e.g. `devices command <id> turnOn`. The engine prepends `switchbot` and appends `--audit-log`."
+        },
+        "device": {
+          "type": "string",
+          "description": "deviceId or alias resolved before building the command. Substituted into the `<id>` slot."
+        },
+        "args": {
+          "type": ["object", "null"],
+          "description": "Extra key/value pairs rendered as `--key value` flags."
+        },
+        "on_error": {
+          "enum": ["continue", "stop"],
+          "default": "continue",
+          "description": "If this action fails, should the rule keep executing its remaining `then[]` entries?"
+        }
+      }
+    }
+  }
+}

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