@switchbot/openapi-cli 3.3.2 → 3.4.0

package/README.md

@@ -93,7 +93,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - 🎨 **Dual output modes** — colorized tables by default; `--json` passthrough for `jq` and scripting
 - 🔐 **Secure credentials** — HMAC-SHA256 signed requests; config file written with `0600`; env-var override for CI
 - 🔍 **Dry-run mode** — preview every mutating request before it hits the API
-- 🧪 **Fully tested** — 1959 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 2204 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -273,11 +273,58 @@ Five annotated starter files covering common setups live in
 With a policy.yaml (v0.2) you can declare automations that the CLI
 executes for you. Supported triggers: **MQTT** (device events),
 **cron** (schedule-driven), and **webhook** (local HTTP POST).
-Supported conditions: `time_between` (quiet hours) and `device_state`
-(live API check with per-tick dedup). Every fire is recorded in
-`~/.switchbot/audit.log`. `rules run` is long-running; use
+Supported conditions: `time_between` (quiet hours), `device_state`
+(live API check with per-tick dedup), and `llm` (AI decision — see
+below). Every fire is recorded in `~/.switchbot/audit.log`. `rules run` is long-running; use
 `daemon start` / `daemon reload` for the managed background mode.
 
+**Actions** — each rule's `then` array accepts two action types:
+
+- `type: command` (default, no `type` field required) — sends a device command, e.g. `devices command <id> turnOn`
+- `type: notify` — delivers a payload to an external channel after the rule fires:
+  - `channel: webhook` — HTTP POST to a URL (only `http://` and `https://` schemes are accepted; `rules lint` rejects others)
+  - `channel: file` — appends a JSONL line to a local file. `to` must be an absolute path; relative or `~`-prefixed paths are rejected by `rules lint` (code `notify-relative-path`) and at runtime
+  - `channel: openclaw` — HTTP POST to an OpenClaw endpoint (same protocol restriction)
+  - Optional `template` field supports `{{ rule.name }}`, `{{ event.* }}`, `{{ device.id }}` placeholders. Nested fields use dot paths, e.g. `{{ event.context.deviceMac }}`; arrays index numerically, e.g. `{{ event.list.0 }}`
+
+```yaml
+then:
+  - command: devices command AC_001 turnOn
+  - type: notify
+    channel: webhook
+    to: https://your.host/hook
+    template: '{"rule":"{{ rule.name }}","fired":"{{ rule.fired_at }}"}'
+```
+
+**LLM condition** — add an AI judgement step before actions fire. The engine calls the
+configured LLM provider, passes the prompt plus recent event context, and gates execution
+on the model's yes/no answer:
+
+```yaml
+conditions:
+  - llm:
+      prompt: "Is the temperature above normal comfort range?"
+      provider: auto          # auto | openai | anthropic
+      cache_ttl: 5m           # skip redundant calls for identical context
+      budget:
+        max_calls_per_hour: 20
+      on_error: pass          # fail | pass | skip
+```
+
+Set `OPENAI_API_KEY` or `ANTHROPIC_API_KEY` (provider `auto` tries Anthropic first).
+`rules lint` flags misconfigured LLM conditions (no provider key, cache TTL too high for
+the trigger frequency, budget zero). Evaluation decisions are recorded in the trace log.
+
+**Decision trace** — enable `automation.audit.evaluate_trace` in `policy.yaml` to record
+every evaluation decision (why a rule fired or was blocked):
+
+```yaml
+automation:
+  audit:
+    evaluate_trace: sampled   # full | sampled | off (default: sampled)
+    evaluate_retention_days: 7
+```
+
 ```bash
 # 1. Author rules under `automation.rules`. See examples/policies/automation.yaml
 #    for a walkthrough covering the three trigger sources.
@@ -308,8 +355,39 @@ switchbot rules last-fired -n 20           # 20 most recent fire entries
 switchbot rules conflicts                  # opposing actions, high-frequency MQTT,
                                            # destructive commands, quiet-hours gaps
 switchbot rules doctor --json              # lint + conflicts combined; exit 0 when clean
+
+# 8. Scaffold a new rule from natural language (heuristic or LLM-backed).
+switchbot rules suggest --intent "turn off AC at 11pm"
+switchbot rules suggest --intent "if door opens and temp below 20 turn on heater" \
+  --llm auto                               # routes complex intents to LLM automatically
+switchbot rules suggest --intent "..." --llm openai  # explicit backend
+# Set OPENAI_API_KEY or ANTHROPIC_API_KEY; auto mode falls back to heuristic on failure
+
+# 9. Explain why a specific evaluation fired or was blocked (requires evaluate_trace).
+switchbot rules trace-explain --rule "motion on" --last
+switchbot rules trace-explain --rule "motion on" --since 1h --json
+switchbot rules trace-explain <fireId>     # single evaluation by ID
+
+# 10. Simulate a rule against historical events without running the engine.
+switchbot rules simulate "motion on"       # replay last 24h from audit log
+switchbot rules simulate "motion on" --since 7d --json
+switchbot rules simulate policy.yaml --rule "night AC" --against events.jsonl
 ```
 
+`rules suggest` enforces several guardrails on LLM output so a model can't quietly arm
+something unsafe:
+
+- **`dry_run` is forced to `true`** on every LLM-generated rule. Review the output and
+  flip it yourself before running the engine without `--dry-run`.
+- **Explicit overrides always win.** If you pass `--trigger`, the LLM's answer must match;
+  a mismatch fails fast. Within the same trigger, mismatched `--event` / `--schedule` /
+  `--days` / `--webhook-path` are rewritten to your value with a warning.
+- **`--llm` is enum-validated at the CLI** (`auto | openai | anthropic`) — junk values
+  exit non-zero instead of falling through.
+- **Notify URLs must be `http://` or `https://`.** `rules lint` and the runtime both
+  reject `file://`, `ftp://`, etc., so a generated webhook can't smuggle in a non-HTTP
+  scheme.
+
 When `quiet_hours` is configured in `policy.yaml`, `rules conflicts` additionally flags event-driven (MQTT / webhook) rules that lack a `time_between` condition — they would fire uninhibited during the quiet window. The hint in each finding includes a ready-to-paste `time_between` condition to add.
 
 Webhook trigger token management:
@@ -842,8 +920,16 @@ Exposes MCP tools (`list_devices`, `describe_device`, `get_device_status`,
 `send_command`, `list_scenes`, `run_scene`, `search_catalog`,
 `account_overview`, `plan_suggest`, `plan_run`, `audit_query`,
 `audit_stats`, `policy_diff`, `policy_validate`, `policy_new`,
-`policy_migrate`) plus a `switchbot://events` resource for real-time
-shadow updates.
+`policy_migrate`, `rules_suggest`, `rule_notifications`,
+`rules_explain`, `rules_simulate`) plus a
+`switchbot://events` resource for real-time shadow updates.
+`rules_suggest` accepts an optional `llm` parameter (`openai | anthropic | auto`)
+to generate YAML for complex intents via an LLM backend.
+`rule_notifications` returns `rule-notify` audit entries, filterable by rule
+name, time range, channel, and result.
+`rules_explain` returns the decision trace for a specific evaluation (why a rule
+fired or was blocked); `rules_simulate` replays historical events against a rule
+and reports would-fire / blocked / throttled outcomes.
 See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full tool reference and safety rules (destructive-command guard).
 
 ### `doctor` — self-check
@@ -853,7 +939,7 @@ switchbot doctor
 switchbot doctor --json
 ```
 
-Runs local checks (Node version, credentials, profiles, catalog, cache, quota, clock, MQTT, policy, MCP) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). Use this to diagnose connectivity or config issues before running automation.
+Runs local checks (Node version, credentials, profiles, catalog, cache, quota, clock, MQTT, policy, MCP, notify-connectivity) and exits 1 if any check fails. `warn` results exit 0. The MQTT check reports `ok` when REST credentials are configured (auto-provisioned on first use). The `notify-connectivity` check probes webhook URLs declared in `type: notify` actions. Use this to diagnose connectivity or config issues before running automation.
 
 `--json` output includes `maturityScore` (0–100) and `maturityLabel` (`production-ready` / `mostly-ready` / `needs-work` / `not-ready`) to give an at-a-glance readiness rating:
 
@@ -1123,7 +1209,7 @@ npm install
 
 npm run dev -- <args>       # Run from TypeScript sources via tsx
 npm run build               # Compile to dist/
-npm test                    # Run the Vitest suite (1959 tests)
+npm test                    # Run the Vitest suite (2204 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -1165,8 +1251,16 @@ src/
 │   ├── audit-query.ts    # Audit log filtering + aggregation
 │   ├── conflict-analyzer.ts # Static conflict detection (opposing actions,
 │   │                     #   high-freq MQTT, destructive cmds, quiet-hours gaps)
-│   ├── suggest.ts        # Heuristic-based rule YAML generation
-│   └── types.ts          # Shared rule/trigger/condition/action types
+│   ├── suggest.ts        # Heuristic + LLM-backed rule YAML generation
+│   ├── notify.ts         # notify action executor (webhook / file / openclaw)
+│   └── types.ts          # Shared rule/trigger/condition/action types (CommandAction | NotifyAction)
+├── llm/
+│   ├── index.ts          # createLLMProvider factory + LLM_AUTO_THRESHOLD
+│   ├── complexity.ts     # Intent complexity scorer (0–10) for auto-routing
+│   ├── rule-prompt.ts    # System prompt builder (embeds v0.2 schema snippet)
+│   └── providers/
+│       ├── openai.ts     # OpenAI-compatible provider (uses Node.js https)
+│       └── anthropic.ts  # Anthropic provider
 ├── status-sync/
 │   └── manager.ts        # Spawn/stop logic, state file, OpenClaw bridge
 ├── lib/
@@ -1181,7 +1275,8 @@ src/
 │   ├── install.ts        # `switchbot install` / `uninstall`
 │   ├── policy.ts         # `policy validate/new/migrate/diff/add-rule/backup/restore`
 │   ├── rules.ts          # `rules suggest/lint/list/explain/run/reload/tail/replay/
-│   │                     #   conflicts/doctor/summary/last-fired/webhook-*`
+│   │                     #   conflicts/doctor/summary/last-fired/webhook-*/
+│   │                     #   trace-explain/simulate`
 │   ├── scenes.ts
 │   ├── health.ts         # `health check/serve` — report + HTTP endpoints
 │   ├── upgrade-check.ts  # `upgrade-check` — npm registry version check
@@ -1205,7 +1300,7 @@ src/
     ├── format.ts         # renderRows / filterFields / output-format dispatch
     ├── audit.ts          # JSONL audit log writer
     └── quota.ts          # Local daily-quota counter
-tests/                    # Vitest suite (1959 tests, mocked axios, no network)
+tests/                    # Vitest suite (2204 tests, mocked axios, no network)
 ```
 
 ### Release flow