@switchbot/openapi-cli 3.0.0 → 3.1.1

package/README.md

@@ -64,6 +64,8 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
   - [`plan`](#plan--declarative-batch-operations)
   - [`mcp`](#mcp--model-context-protocol-server)
   - [`doctor`](#doctor--self-check)
+  - [`health`](#health--runtime-health-report)
+  - [`upgrade-check`](#upgrade-check--version-check)
   - [`quota`](#quota--api-request-counter)
   - [`history`](#history--audit-log)
   - [`catalog`](#catalog--device-type-catalog)
@@ -71,6 +73,7 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
   - [`capabilities`](#capabilities--cli-manifest)
   - [`cache`](#cache--inspect-and-clear-local-cache)
   - [`policy`](#policy--validate-scaffold-and-migrate-policyyaml)
+  - [`daemon`](#daemon--background-rules-engine-process)
   - [`completion`](#completion--shell-tab-completion)
 - [Output modes](#output-modes)
   - [Cache](#cache)
@@ -78,8 +81,6 @@ Under the hood every surface shares the same catalog, cache, and HMAC client —
 - [Environment variables](#environment-variables)
 - [Scripting examples](#scripting-examples)
 - [Development](#development)
-- [Contributing](#contributing)
-- [Roadmap](#roadmap)
 - [License](#license)
 - [References](#references)
 
@@ -92,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** — 1765 Vitest tests, mocked axios, zero network in CI
+- 🧪 **Fully tested** — 1882 Vitest tests, mocked axios, zero network in CI
 - ⚡ **Shell completion** — Bash / Zsh / Fish / PowerShell
 
 ## Requirements
@@ -275,7 +276,7 @@ executes for you. Supported triggers: **MQTT** (device events),
 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
-`rules reload` to hot-reload policy without dropping listeners.
+`daemon start` / `daemon reload` for the managed background mode.
 
 ```bash
 # 1. Author rules under `automation.rules`. See examples/policies/automation.yaml
@@ -285,16 +286,37 @@ Supported conditions: `time_between` (quiet hours) and `device_state`
 switchbot rules lint                       # exit 0 valid, 1 error
 switchbot rules list --json | jq .         # structured summary
 
-# 3. Run the engine. --dry-run overrides every rule into audit-only mode;
+# 3. Inspect a single rule in full detail (trigger, conditions, actions,
+#    cooldown, hysteresis, maxFiringsPerHour, suppressIfAlreadyDesired, last fired).
+switchbot rules explain "motion on"
+switchbot rules explain "motion on" --json
+
+# 4. Run the engine. --dry-run overrides every rule into audit-only mode;
 #    --max-firings bounds a demo session.
 switchbot rules run --dry-run --max-firings 5
 
-# 4. Edit policy.yaml in another shell, then hot-reload without restart.
-switchbot rules reload                     # SIGHUP on Unix, sentinel file on Windows
+# 5. Edit policy.yaml in another shell, then hot-reload without restart.
+switchbot daemon reload                    # managed daemon reload
 
-# 5. Review recorded fires.
+# 6. Review recorded fires.
 switchbot rules tail --follow              # stream rule-* audit lines
 switchbot rules replay --since 1h --json   # per-rule fires/dries/throttled/errors
+switchbot rules summary                    # aggregate fires/errors per rule (24h window)
+switchbot rules last-fired -n 20           # 20 most recent fire entries
+
+# 7. Conflict and health analysis.
+switchbot rules conflicts                  # opposing actions, high-frequency MQTT,
+                                           # destructive commands, quiet-hours gaps
+switchbot rules doctor --json              # lint + conflicts combined; exit 0 when clean
+```
+
+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:
+
+```bash
+switchbot rules webhook-rotate-token       # rotate the bearer token for webhook triggers
+switchbot rules webhook-show-token         # print current token (creates one if absent)
 ```
 
 See [`docs/design/phase4-rules.md`](./docs/design/phase4-rules.md) for
@@ -356,6 +378,12 @@ switchbot devices command ABC123 turnOn --dry-run
 switchbot config set-token <token> <secret>   # Save to ~/.switchbot/config.json
 switchbot config show                          # Print current source + masked secret
 switchbot config list-profiles                 # List saved profiles
+
+# Print (or write) the recommended AI-agent profile template
+switchbot config agent-profile                 # print to stdout
+switchbot config agent-profile --write         # write to ~/.switchbot/profiles/agent.json (mode 0600)
+switchbot config agent-profile --write --force # overwrite if it already exists
+switchbot config agent-profile --json          # structured JSON envelope
 ```
 
 ### `devices` — list, status, control
@@ -551,6 +579,10 @@ skipped devices appear under `summary.skipped` with `skippedReason:'offline'`.
 ```bash
 switchbot scenes list                 # Columns: sceneId, sceneName
 switchbot scenes execute <sceneId>
+
+# One-shot summary: risk profile, execution hint, estimated commands
+switchbot scenes explain <sceneId>
+switchbot scenes explain <sceneId> --json
 ```
 
 ### `webhook` — receive device events over HTTP
@@ -710,6 +742,34 @@ switchbot events mqtt-tail --sink homeassistant --ha-url http://homeassistant.lo
 
 Device state is also persisted to `~/.switchbot/device-history/<deviceId>.json` (latest + 100-entry ring buffer) regardless of sink configuration. This enables the `get_device_history` MCP tool to answer state queries without an API call.
 
+### `daemon` — background rules-engine process
+
+Runs `switchbot rules run` as a detached background process. Tracks runtime
+metadata in `~/.switchbot/daemon.state.json` and can co-launch a health HTTP
+server.
+
+```bash
+# Start the daemon (no-op if already running)
+switchbot daemon start
+switchbot daemon start --policy ./my-policy.yaml
+switchbot daemon start --healthz-port 3100     # also launch health serve on port 3100
+switchbot daemon start --force                 # restart even if already running
+
+# Inspect daemon state (pid, log path, health server, last reload)
+switchbot daemon status
+switchbot daemon status --json
+
+# Hot-reload policy without restarting (sends SIGHUP on Unix, writes sentinel on Windows)
+switchbot daemon reload
+
+# Stop the daemon and any co-launched health server
+switchbot daemon stop
+```
+
+Start prints the PID, log path, and state file location. If the process exits
+within 300 ms of launch, start fails immediately and includes the last 20 lines
+of the log in the error message for fast diagnosis.
+
 ### `completion` — shell tab-completion
 
 ```bash
@@ -743,15 +803,18 @@ switchbot plan validate plan.json
 # Preview — mutations skipped, GETs still execute
 switchbot --dry-run plan run plan.json
 
-# Run — pass --yes to allow destructive steps
-switchbot plan run plan.json --yes
+# Save / review / approve / execute for destructive plans
+switchbot plan save plan.json
+switchbot plan review <planId>
+switchbot plan approve <planId>
+switchbot plan execute <planId>
 switchbot plan run plan.json --continue-on-error
 
 # Run with per-step TTY confirmation for destructive steps (human-in-the-loop)
 switchbot plan run plan.json --require-approval
 ```
 
-A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. `--require-approval` prompts for each destructive step individually, letting you approve or reject without re-running the whole plan. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
+A plan file is a JSON document with `version`, `description`, and a `steps` array of `command`, `scene`, or `wait` steps. Steps execute sequentially; a failed step stops the run unless `--continue-on-error` is set. `plan run` is the preview/direct path, but destructive steps are blocked by default and should go through `plan save` → `plan review` → `plan approve` → `plan execute`. See [`docs/agent-guide.md`](./docs/agent-guide.md) for the full schema and agent integration patterns.
 
 ### `devices watch` — poll status
 
@@ -792,6 +855,56 @@ 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.
 
+`--json` output includes `maturityScore` (0–100) and `maturityLabel` (`production-ready` / `mostly-ready` / `needs-work` / `not-ready`) to give an at-a-glance readiness rating:
+
+```bash
+switchbot doctor --json | jq '{score: .data.maturityScore, label: .data.maturityLabel}'
+```
+
+Pass `--fix --yes` to auto-apply safe fixes (e.g. clear stale cache entries) without a prompt.
+
+### `health` — runtime health report
+
+```bash
+# One-shot report: quota, audit error rate, circuit-breaker state
+switchbot health check
+switchbot health check --prometheus      # Prometheus text format
+switchbot health check --json
+
+# Start a long-running HTTP server with /healthz and /metrics
+switchbot health serve                   # default port 3100, bind 127.0.0.1
+switchbot health serve --port 8080
+switchbot health serve --json            # print {"status":"listening",...} on start
+```
+
+`/healthz` returns a JSON health report (HTTP 200 when `ok`/`degraded`, 503 when circuit is open).
+`/metrics` returns Prometheus text metrics (`switchbot_quota_used_total`, `switchbot_circuit_open`, …).
+Port conflicts are reported immediately with a clear hint to choose a different port via `--port`.
+
+### `upgrade-check` — version check
+
+```bash
+switchbot upgrade-check                      # human output; exits 1 when update available
+switchbot upgrade-check --json               # structured JSON output
+switchbot upgrade-check --timeout 5000       # custom registry timeout (ms)
+```
+
+Queries the npm registry for the latest published version and compares it against the running version. When the registry's `dist-tags.latest` is itself a prerelease (e.g. `4.0.0-rc.1`), the check is skipped and the current version is treated as up-to-date — accidental prerelease tags don't trigger spurious upgrade prompts.
+`--json` output:
+
+```json
+{
+  "current": "3.2.1",
+  "latest": "4.0.0",
+  "upToDate": false,
+  "updateAvailable": true,
+  "breakingChange": true,
+  "installCommand": "npm install -g @switchbot/openapi-cli@4.0.0"
+}
+```
+
+`breakingChange` is `true` when the latest major version is higher than the current — useful for agents or CI that need to distinguish breaking upgrades from patch releases.
+
 ### `quota` — API request counter
 
 ```bash
@@ -876,6 +989,11 @@ switchbot policy validate --no-snippet             # plain error list, no source
 
 # Report the schema version the file declares
 switchbot policy migrate
+
+# Snapshot and restore the active policy
+switchbot policy backup                            # write timestamped backup alongside policy file
+switchbot policy backup --out ./backups/           # custom destination directory
+switchbot policy restore <backup-file>             # overwrite active policy from backup (auto-backups first)
 ```
 
 Path resolution order: positional `[path]` > `SWITCHBOT_POLICY_PATH` env var > default policy path.
@@ -1005,7 +1123,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 (1765 tests)
+npm test                    # Run the Vitest suite (1882 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -1045,6 +1163,8 @@ src/
 │   ├── webhook-listener.ts # HTTP listener (bearer token, localhost-only)
 │   ├── pid-file.ts       # Hot-reload via SIGHUP or sentinel file
 │   ├── 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
 ├── status-sync/
@@ -1059,9 +1179,12 @@ src/
 │   ├── explain.ts        # `devices explain` — one-shot device summary
 │   ├── device-meta.ts    # `devices meta` — local aliases / hide flags
 │   ├── install.ts        # `switchbot install` / `uninstall`
-│   ├── policy.ts         # `policy validate/new/migrate/diff/add-rule`
-│   ├── rules.ts          # `rules suggest/lint/list/run/reload/tail/replay`
+│   ├── 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-*`
 │   ├── scenes.ts
+│   ├── health.ts         # `health check/serve` — report + HTTP endpoints
+│   ├── upgrade-check.ts  # `upgrade-check` — npm registry version check
 │   ├── status-sync.ts    # `status-sync run/start/stop/status`
 │   ├── webhook.ts
 │   ├── watch.ts          # `devices watch <deviceId>`
@@ -1082,7 +1205,7 @@ src/
     ├── format.ts         # renderRows / filterFields / output-format dispatch
     ├── audit.ts          # JSONL audit log writer
     └── quota.ts          # Local daily-quota counter
-tests/                    # Vitest suite (1765 tests, mocked axios, no network)
+tests/                    # Vitest suite (1882 tests, mocked axios, no network)
 ```
 
 ### Release flow
@@ -1096,41 +1219,6 @@ git push --follow-tags
 
 Then on GitHub → **Releases → Draft a new release → select tag → Publish**. The `publish.yml` workflow runs tests, verifies the tag matches `package.json`, and publishes `@switchbot/openapi-cli` to npm with [provenance](https://docs.npmjs.com/generating-provenance-statements).
 
-## Contributing
-
-Bug reports, feature requests, and PRs are welcome.
-
-1. Fork the repo and create a topic branch.
-2. Keep changes small and focused; add or update Vitest cases for any behavior change.
-3. Run `npm test` and `npm run build` locally — both must pass.
-4. Open a pull request against `main`. CI runs on Node 18/20/22; all three must stay green.
-
-## Roadmap
-
-Phase 1 through Phase 4 are shipped. The authoritative phase/track table
-(including skill-side `autonomyLevel` L1/L2/L3 mapping) lives in
-[`docs/design/roadmap.md`](./docs/design/roadmap.md).
-
-Shipped tracks summary:
-
-- **Track β**: one-command install/uninstall surface (`switchbot install` / `switchbot uninstall`).
-- **Track γ**: rules v0.2 runtime increment (`days` + `all`/`any`/`not`).
-- **Track δ (L2)**: plan authoring + guarded execution (`plan suggest`, `plan run --require-approval`) and MCP review/execute tools (`plan_suggest`, `plan_run`, `audit_query`, `audit_stats`, `policy_diff`).
-- **Track ζ (L3)**: autonomous rule authoring (`rules suggest`, `policy add-rule`) with MCP parity (`rules_suggest`, `policy_add_rule`).
-- **Track ε**: cross-OS keychain CI matrix (macOS + Linux libsecret + Windows Credential Manager).
-
-Backlog tracks still open:
-
-1. **Daemon mode** — long-running local process with Unix/named-pipe
-  transport so repeated MCP or plan invocations avoid fresh-process
-  startup cost.
-2. **`npx @switchbot/mcp-server`** — split the MCP server into a tiny
-  package so non-CLI users can run it directly with `npx`.
-3. **`switchbot self-test`** — scripted end-to-end go/no-go checks for
-  token/secret validity plus representative device control.
-4. **Record / replay** — capture request/response fixtures and replay
-  offline for deterministic integration tests and CI.
-
 ## License
 
 [MIT](./LICENSE) © chenliuyun

package/dist/api/client.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { buildAuthHeaders } from '../auth.js';
 import { loadConfig } from '../config.js';
 import { isVerbose, isDryRun, getTimeout, getRetryOn429, getRetryOn5xx, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
-import { nextRetryDelayMs, sleep } from '../utils/retry.js';
+import { nextRetryDelayMs, sleep, CircuitBreaker, CircuitOpenError } from '../utils/retry.js';
 import { recordRequest, checkDailyCap } from '../utils/quota.js';
 import { readProfileMeta } from '../config.js';
 import { getActiveProfile } from '../lib/request-context.js';
@@ -40,6 +40,17 @@ export class DryRunSignal extends Error {
         this.name = 'DryRunSignal';
     }
 }
+/**
+ * Module-level circuit breaker for the SwitchBot API. Shared across all
+ * client instances in the process. Opens after 5 consecutive 5xx / network
+ * errors; resets to half-open after 60 s.
+ * Exported for health-check inspection.
+ */
+export const apiCircuitBreaker = new CircuitBreaker('switchbot-api', {
+    failureThreshold: 5,
+    resetTimeoutMs: 60_000,
+});
+export { CircuitOpenError };
 export function createClient() {
     const { token, secret } = loadConfig();
     const verbose = isVerbose();
@@ -57,6 +68,8 @@ export function createClient() {
     });
     // Inject auth headers; optionally log the request; short-circuit on --dry-run.
     client.interceptors.request.use((config) => {
+        // Circuit breaker check — fail fast when the API is consistently down.
+        apiCircuitBreaker.checkAndAllow();
         // Pre-flight cap check: refuse the call before it touches the network.
         if (dailyCap) {
             const check = checkDailyCap(dailyCap);
@@ -110,6 +123,8 @@ export function createClient() {
                 `API error code: ${data.statusCode}`;
             throw new ApiError(msg, data.statusCode);
         }
+        // Successful HTTP response — record for circuit breaker.
+        apiCircuitBreaker.recordSuccess();
         return response;
     }, (error) => {
         if (error instanceof DryRunSignal)
@@ -131,6 +146,8 @@ export function createClient() {
                         return sleep(delay).then(() => client.request(config));
                     }
                 }
+                // Network-level failure — record for circuit breaker.
+                apiCircuitBreaker.recordFailure();
                 throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: isIdempotentRead });
             }
             const status = error.response?.status;
@@ -165,6 +182,11 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
+            // Record 5xx and network errors for circuit breaker. 4xx errors are
+            // expected business responses — don't count toward circuit threshold.
+            if (status === undefined || status >= 500) {
+                apiCircuitBreaker.recordFailure();
+            }
             // P8: quota already recorded in the request interceptor before
             // dispatch — no extra bookkeeping needed here on the error path.
             // Timeouts, DNS failures, 5xx, and exhausted retries all counted

package/dist/commands/batch.js

@@ -6,6 +6,7 @@ import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js'
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
 import { getCachedTypeMap, getCachedDevice, loadStatusCache } from '../devices/cache.js';
+import { allowsDirectDestructiveExecution, destructiveExecutionHint } from '../lib/destructive-mode.js';
 const DEFAULT_CONCURRENCY = 5;
 const COMMAND_TYPES = ['command', 'customize'];
 /**
@@ -98,7 +99,7 @@ export function registerBatchCommand(devices) {
         .option('--stagger <ms>', 'Fixed delay between task starts in ms (default 0 = random 20-60ms jitter)', intArg('--stagger', { min: 0 }), '0')
         .option('--plan', '[DEPRECATED, use --emit-plan] With --dry-run: emit a plan JSON document instead of executing anything')
         .option('--emit-plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
-        .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
+        .option('--yes', 'Allow destructive commands only from an explicit dev profile')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
         .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key-prefix'))
@@ -134,7 +135,8 @@ Planning:
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
-  Keypad createKey/deleteKey) are blocked by default. Pass --yes to override.
+  Keypad createKey/deleteKey) are blocked by default. Use the reviewed plan
+  flow instead of direct execution.
   --dry-run intercepts every POST and reports the intended calls without
   hitting the API.
 
@@ -142,7 +144,7 @@ Examples:
   $ switchbot devices batch turnOff --filter 'type~=Light,family=home'
   $ switchbot devices batch turnOn --ids ID1,ID2,ID3
   $ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
-  $ switchbot devices batch unlock --filter 'type=Smart Lock' --yes
+  $ switchbot devices batch unlock --filter 'type=Smart Lock' --dry-run --emit-plan
 `)
         .action(async (cmd, parameter, options, commandObj) => {
         // Trailing "-" sentinel selects stdin mode.
@@ -234,10 +236,24 @@ Examples:
                 code: 2,
                 kind: 'guard',
                 message: `Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes: ${deviceIds.join(', ')}`,
-                hint: 'Re-issue the call with --yes to proceed.',
+                hint: 'Re-issue the call with --yes only from an explicit dev profile, or use the reviewed plan flow.',
                 context: { command: cmd, deviceIds },
             });
         }
+        if (blockedForDestructive.length > 0 && options.yes && !allowsDirectDestructiveExecution()) {
+            exitWithError({
+                code: 2,
+                kind: 'guard',
+                message: `Direct destructive execution is disabled for batch command "${cmd}".`,
+                hint: destructiveExecutionHint(),
+                context: {
+                    command: cmd,
+                    blockedCount: blockedForDestructive.length,
+                    deviceIds: blockedForDestructive.map((item) => item.deviceId),
+                    requiredWorkflow: 'plan-approval',
+                },
+            });
+        }
         // parameter may be a JSON object string; mirror the single-command action.
         let parsedParam = parameter ?? 'default';
         if (parameter) {