@switchbot/openapi-cli 3.1.0 → 3.1.1

package/README.md

@@ -73,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)
@@ -80,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)
 
@@ -94,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** — 1856 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
@@ -743,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
@@ -862,7 +889,7 @@ 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.
+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
@@ -1096,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 (1856 tests)
+npm test                    # Run the Vitest suite (1882 tests)
 npm run test:watch          # Watch mode
 npm run test:coverage       # Coverage report (v8, HTML + text)
 ```
@@ -1152,7 +1179,7 @@ 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`
+│   ├── 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
@@ -1178,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 (1856 tests, mocked axios, no network)
+tests/                    # Vitest suite (1882 tests, mocked axios, no network)
 ```
 
 ### Release flow
@@ -1192,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/commands/daemon.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { isJsonMode, printJson, exitWithError } from '../utils/output.js';
-import { readPidFile, writePidFile, isPidAlive, getDefaultPidFilePaths, writeReloadSentinel, sighupSupported } from '../rules/pid-file.js';
+import { readPidFile, writePidFile, clearPidFile, isPidAlive, getDefaultPidFilePaths, writeReloadSentinel, sighupSupported } from '../rules/pid-file.js';
 import { stringArg } from '../utils/arg-parsers.js';
 import chalk from 'chalk';
 import { DAEMON_LOG_FILE, DAEMON_PID_FILE, DAEMON_STATE_FILE, HEALTHZ_PID_FILE, readDaemonState, writeDaemonState, } from '../lib/daemon-state.js';
@@ -65,6 +65,39 @@ function persistState(partial) {
     writeDaemonState(next);
     return next;
 }
+function readLastLines(filePath, n = 20) {
+    try {
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        return lines.slice(Math.max(0, lines.length - n)).join('\n').trim();
+    }
+    catch {
+        return '';
+    }
+}
+async function probeLiveness(opts) {
+    await new Promise((resolve) => setTimeout(resolve, opts.delayMs));
+    const dead = opts.child.exitCode !== null || opts.child.killed;
+    if (!dead)
+        return true;
+    if (opts.fatal) {
+        if (opts.pidFile)
+            clearPidFile(opts.pidFile);
+        const exitCode = opts.child.exitCode ?? 'unknown';
+        const logSnippet = opts.logFile ? readLastLines(opts.logFile) : '';
+        const trailingLog = logSnippet ? `\n\nLast log lines:\n${logSnippet}` : '';
+        const logRef = opts.logFile ?? 'daemon log';
+        persistState({
+            status: 'failed', pid: null, failedAt: new Date().toISOString(),
+            failureReason: `Daemon exited immediately (code ${exitCode}). Check ${logRef}.`,
+        });
+        exitWithError({
+            code: 1, kind: 'runtime',
+            message: `Daemon process exited immediately (code ${exitCode}). Check ${logRef} for details.${trailingLog}`,
+        });
+    }
+    return false;
+}
 function renderHumanStatus(status) {
     if (status.status === 'running' && status.pid !== null) {
         console.log(`${chalk.green('●')} Daemon is running (pid ${status.pid}).`);
@@ -118,7 +151,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
         .option('--policy <path>', 'Policy file path (default: auto-detected)', stringArg('--policy'))
         .option('--force', 'Restart even if the daemon appears to be running.')
         .option('--healthz-port <n>', 'Also start a health HTTP server on this port (default: disabled).')
-        .action((opts) => {
+        .action(async (opts) => {
         const current = getDaemonStatus();
         if (current.status === 'running' && !opts.force) {
             if (isJsonMode()) {
@@ -139,7 +172,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
             }
         }
         const thisFile = fileURLToPath(import.meta.url);
-        const cliEntry = path.resolve(path.dirname(thisFile), 'index.js');
+        const cliEntry = path.resolve(path.dirname(thisFile), '..', 'index.js');
         const args = ['rules', 'run'];
         if (opts.policy)
             args.push(opts.policy);
@@ -163,6 +196,11 @@ The daemon reads the same policy file as \`switchbot rules run\`.
         });
         child.unref();
         fs.closeSync(logFd);
+        // Liveness probe: wait 300 ms then verify the child is still alive.
+        await probeLiveness({
+            child, delayMs: 300, fatal: true,
+            pidFile: DAEMON_PID_FILE, logFile: DAEMON_LOG_FILE,
+        });
         const newPid = child.pid;
         if (!newPid) {
             persistState({
@@ -187,8 +225,13 @@ The daemon reads the same policy file as \`switchbot rules run\`.
             healthChild.unref();
             fs.closeSync(healthLogFd);
             if (healthChild.pid) {
-                healthzPid = healthChild.pid;
-                writePidFile(HEALTHZ_PID_FILE, healthzPid);
+                // Brief liveness probe for the health server process.
+                const healthAlive = await probeLiveness({ child: healthChild, delayMs: 200, fatal: false });
+                if (healthAlive) {
+                    healthzPid = healthChild.pid;
+                    writePidFile(HEALTHZ_PID_FILE, healthzPid);
+                }
+                // Non-fatal if health server dies — daemon itself is still running.
             }
         }
         persistState({

package/dist/commands/upgrade-check.js

@@ -6,6 +6,8 @@ const require = createRequire(import.meta.url);
 const { name: pkgName, version: currentVersion } = require('../../package.json');
 function fetchLatestVersion(packageName, timeoutMs = 8000) {
     const encoded = packageName.replace('/', '%2F');
+    // /latest is shorthand for dist-tags.latest — always the current stable
+    // release tag, never a prerelease unless accidentally published as such.
     const url = `https://registry.npmjs.org/${encoded}/latest`;
     return new Promise((resolve, reject) => {
         const req = https.get(url, { timeout: timeoutMs }, (res) => {
@@ -28,6 +30,9 @@ function fetchLatestVersion(packageName, timeoutMs = 8000) {
         req.on('error', reject);
     });
 }
+// Intentionally avoids the `semver` npm package (YAGNI): comparing two
+// well-formed registry version strings needs only these 10 lines, and adding
+// a runtime dep solely for version comparison would bloat install footprint.
 function semverGt(a, b) {
     const numParts = (v) => v.replace(/-.*$/, '').split('.').map((n) => Number.parseInt(n, 10));
     const [aMaj, aMin, aPat] = numParts(a);
@@ -64,6 +69,20 @@ export function registerUpgradeCheckCommand(program) {
         const upToDate = !semverGt(latestVersion, currentVersion);
         const currentMajor = Number.parseInt(currentVersion.split('.')[0], 10);
         const latestMajor = Number.parseInt(latestVersion.split('.')[0], 10);
+        if (latestVersion.includes('-')) {
+            const msg = `Latest registry version (${latestVersion}) is a prerelease — skipping update check.`;
+            if (isJsonMode()) {
+                printJson({
+                    current: currentVersion, latest: latestVersion, upToDate: true,
+                    updateAvailable: false, breakingChange: false, installCommand: null,
+                    note: msg,
+                });
+            }
+            else {
+                console.log(`${chalk.green('✓')} You are running the latest stable version (${currentVersion}). Registry latest (${latestVersion}) is a prerelease — skipping.`);
+            }
+            return;
+        }
         const result = {
             current: currentVersion,
             latest: latestVersion,

package/dist/rules/action.js

@@ -203,3 +203,14 @@ export async function executeRuleAction(action, ctx) {
         return { ok: false, error: msg, deviceId, verb: parsed.verb };
     }
 }
+/**
+ * Extract the raw deviceId from an action object without alias resolution.
+ * Prefers `action.device` over the deviceId embedded in the command string.
+ * Use resolveActionDevice() when alias resolution is needed.
+ */
+export function extractDeviceIdFromAction(action) {
+    if (action.device)
+        return action.device;
+    const m = /\bdevices\s+command\s+(\S+)/.exec(action.command ?? '');
+    return m ? m[1] : null;
+}

package/dist/rules/conflict-analyzer.js

@@ -25,6 +25,7 @@
 import { isTimeBetween, isAllCondition, isAnyCondition, isNotCondition } from './types.js';
 import { parseMaxPerMs } from './throttle.js';
 import { isDestructiveCommand } from './destructive.js';
+import { extractDeviceIdFromAction } from './action.js';
 /** Known opposing command pairs (order-independent). */
 const OPPOSING_PAIRS = [
     ['turnOn', 'turnOff'],
@@ -37,6 +38,19 @@ const OPPOSING_PAIRS = [
     ['volumeUp', 'volumeDown'],
     ['fanSpeedUp', 'fanSpeedDown'],
 ];
+/**
+ * MQTT events that fire on every device state push and can rapidly exhaust
+ * the daily API quota when a rule has no throttle.
+ *
+ * Conditional events like `motion.detected` are intentionally excluded —
+ * they fire discretely, not at continuous high frequency. Extend this set
+ * when new catch-all or near-continuous event types are added to the classifier.
+ */
+export const HIGH_FREQ_EVENTS = ['device.shadow', '*'];
+/** Returns true when an MQTT event is known to fire at high frequency. */
+export function isHighFreqEvent(event) {
+    return HIGH_FREQ_EVENTS.includes(event);
+}
 function commandsAreOpposing(a, b) {
     for (const [x, y] of OPPOSING_PAIRS) {
         if ((a === x && b === y) || (a === y && b === x))
@@ -44,9 +58,6 @@ function commandsAreOpposing(a, b) {
     }
     return false;
 }
-function extractDeviceFromAction(action) {
-    return action.device ?? null;
-}
 function extractCommandVerb(command) {
     // command strings are like "devices command <id> turnOn" — extract last token
     const parts = command.trim().split(/\s+/);
@@ -108,8 +119,8 @@ export function analyzeConflicts(rules, quietHours) {
                 continue;
             for (const actionA of a.then) {
                 for (const actionB of b.then) {
-                    const deviceA = extractDeviceFromAction(actionA);
-                    const deviceB = extractDeviceFromAction(actionB);
+                    const deviceA = extractDeviceIdFromAction(actionA);
+                    const deviceB = extractDeviceIdFromAction(actionB);
                     // Skip if devices can't be compared.
                     if (!deviceA || !deviceB || deviceA !== deviceB)
                         continue;
@@ -136,7 +147,7 @@ export function analyzeConflicts(rules, quietHours) {
         if (rule.when.source !== 'mqtt')
             continue;
         const event = rule.when.event;
-        const isHighFreq = event === 'device.shadow' || event === '*';
+        const isHighFreq = isHighFreqEvent(event);
         if (!isHighFreq)
             continue;
         const cooldown = effectiveCooldownMs(rule);

package/dist/rules/suggest.js

@@ -80,7 +80,7 @@ export function suggestRule(opts) {
     const then = actionDevices.length > 0
         ? actionDevices.map((d) => ({
             command: `devices command <id> ${command}`,
-            device: d.name ?? d.id,
+            device: d.id,
         }))
         : [{ command: `devices command <id> ${command}` }];
     const rule = {

package/dist/utils/audit.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { getAuditLog } from './flags.js';
+export const DEFAULT_AUDIT_PATH = path.join(os.homedir(), '.switchbot', 'audit.log');
 /**
  * Bump when breaking changes to the audit line shape land.
  *
@@ -20,7 +22,9 @@ function resolveAuditPath() {
     return path.resolve(flag);
 }
 export function writeAudit(entry) {
-    const file = resolveAuditPath();
+    let file = resolveAuditPath();
+    if (!file && entry.planId)
+        file = DEFAULT_AUDIT_PATH;
     if (!file)
         return;
     const dir = path.dirname(file);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.1.0",
+  "version": "3.1.1",
   "description": "SwitchBot smart home CLI — control devices, run scenes, stream real-time events, and integrate AI agents via MCP. Full API v1.1 coverage.",
   "keywords": [
     "switchbot",