@switchbot/openapi-cli 3.2.2 → 3.3.0

package/README.md

@@ -894,7 +894,7 @@ Queries the npm registry for the latest published version and compares it agains
 
 ```json
 {
-  "current": "3.2.2",
+  "current": "3.3.0",
   "latest": "4.0.0",
   "upToDate": false,
   "updateAvailable": true,

package/dist/index.js

@@ -28586,10 +28586,25 @@ Examples:
       if (isJsonMode()) {
         printJson(result);
       } else {
-        console.log(
-          `
-Summary: ${result.summary.ok} ok, ${result.summary.failed} failed, ${result.summary.skipped} skipped (${result.summary.durationMs}ms)`
-        );
+        if (dryRunned.length > 0) {
+          console.log(`
+Planned (dry-run): ${dryRunned.length} device(s)`);
+          for (const d of dryRunned) console.log(`  - ${d.deviceId}`);
+        }
+        if (preSkipped.length > 0) {
+          console.log(`
+Skipped (offline): ${preSkipped.length} device(s)`);
+          for (const d of preSkipped) console.log(`  - ${d.deviceId}`);
+        }
+        const parts = [
+          `${result.summary.ok} ok`,
+          `${result.summary.failed} failed`
+        ];
+        if (dryRunned.length > 0) parts.push(`${dryRunned.length} planned`);
+        if (preSkipped.length > 0) parts.push(`${preSkipped.length} skipped_offline`);
+        parts.push(`(${result.summary.durationMs}ms)`);
+        console.log(`
+Summary: ${parts.join(", ")}`);
       }
       if (failed.length > 0) process.exit(1);
     }
@@ -28751,7 +28766,7 @@ function sleep2(ms, signal) {
   });
 }
 function registerWatchCommand(devices) {
-  devices.command("watch").description("Poll device status on an interval and emit field-level changes (JSONL)").argument("[deviceId...]", "One or more deviceIds to watch (or use --name for one device)").option("--name <query>", "Resolve one device by fuzzy name (combined with any positional IDs)", stringArg("--name")).option(
+  devices.command("watch").description("Poll device status on an interval and emit field-level changes (human table by default; JSONL with --json for agents)").argument("[deviceId...]", "One or more deviceIds to watch (or use --name for one device)").option("--name <query>", "Resolve one device by fuzzy name (combined with any positional IDs)", stringArg("--name")).option(
     "--interval <dur>",
     `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1e3}s)`,
     durationArg("--interval"),
@@ -28759,16 +28774,22 @@ function registerWatchCommand(devices) {
   ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--for <dur>", 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg("--for")).option("--include-unchanged", "Emit a tick even when no field changed").addHelpText(
     "after",
     `
-Each poll emits one JSON line per deviceId with the shape:
+Default output is a human-readable table of field changes per tick; add --json
+to get one JSON-Lines record per deviceId per tick (the agent-friendly form).
+
+The very first poll emits a seed tick with "from": null for every field, so
+the initial state is observable. Subsequent ticks only include fields whose
+value changed (unless --include-unchanged is passed).
+
+Each --json line has the shape:
   { "t": "<ISO>", "tick": <n>, "deviceId": "ID", "type": "Bot",
     "changed": { "power": { "from": "off", "to": "on" } } }
 
-The very first poll has "from": null for every field (seed).
-
 Examples:
   $ switchbot devices watch ABC123 --interval 10s
   $ switchbot devices watch ABC123 --fields battery,power --interval 1m
   $ switchbot devices watch ABC123 DEF456 --interval 30s --max 10
+  # Agent-friendly: one JSONL record per tick, pipeable to jq
   $ switchbot devices watch ABC123 --json | jq 'select(.changed.power)'
   $ switchbot devices watch --name "Living Room AC" --interval 10s
 `
@@ -45370,16 +45391,30 @@ import { createRequire as createRequire3 } from "node:module";
 
 // src/policy/schema.ts
 init_cjs_shim();
+
+// src/embedded-assets.ts
+init_cjs_shim();
 import { readFileSync as readFileSync2 } from "node:fs";
 import { fileURLToPath } from "node:url";
+function readAsset(relPath) {
+  const resolved = fileURLToPath(new URL(relPath, import.meta.url));
+  return readFileSync2(resolved, "utf-8");
+}
+function readPolicySchemaJson(version2) {
+  return readAsset(`./policy/schema/v${version2}.json`);
+}
+function readPolicyExampleYaml() {
+  return readAsset(`./policy/examples/policy.example.yaml`);
+}
+
+// src/policy/schema.ts
 var SUPPORTED_POLICY_SCHEMA_VERSIONS = ["0.2"];
 var CURRENT_POLICY_SCHEMA_VERSION = "0.2";
 var schemaCache = /* @__PURE__ */ new Map();
 function loadPolicySchema(version2 = CURRENT_POLICY_SCHEMA_VERSION) {
   const cached2 = schemaCache.get(version2);
   if (cached2) return cached2;
-  const url2 = new URL(`./schema/v${version2}.json`, import.meta.url);
-  const raw = readFileSync2(fileURLToPath(url2), "utf-8");
+  const raw = readPolicySchemaJson(version2);
   const parsed = JSON.parse(raw);
   schemaCache.set(version2, parsed);
   return parsed;
@@ -46638,7 +46673,6 @@ function diffPolicyValues(leftDoc, rightDoc, leftSource, rightSource, maxChanges
 }
 
 // src/commands/mcp.ts
-import { fileURLToPath as fileURLToPath2 } from "node:url";
 import { dirname as pathDirname, join as pathJoin } from "node:path";
 import os13 from "node:os";
 import fs15 from "node:fs";
@@ -47581,8 +47615,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`
           context: { policyPath }
         });
       }
-      const templateUrl = new URL("../policy/examples/policy.example.yaml", import.meta.url);
-      const template = fs15.readFileSync(fileURLToPath2(templateUrl), "utf-8");
+      const template = readPolicyExampleYaml();
       fs15.mkdirSync(pathDirname(policyPath), { recursive: true });
       fs15.writeFileSync(policyPath, template, { encoding: "utf-8" });
       const structured = {
@@ -48714,40 +48747,61 @@ Total: ${entries.length} device type(s)  (source: ${source})`);
       handleError(error48);
     }
   });
-  catalog.command("search").description("Fuzzy search the effective catalog by type name, alias, role, or command name").argument("<keyword>", "Substring to match (case-insensitive) against type, alias, role, or command").action((keyword) => {
+  catalog.command("search").description("Fuzzy search the effective catalog by type name, alias, role, or command name").argument("<keyword>", "Substring to match (case-insensitive) against type, alias, role, or command").option("--strict", "Only return entries whose type name matches (skip alias/role/command fallbacks)").action((keyword, options) => {
     try {
       const q = keyword.toLowerCase();
       const entries = getEffectiveCatalog();
-      const hits = entries.filter((e) => {
-        if (e.type.toLowerCase().includes(q)) return true;
-        if ((e.role ?? "").toLowerCase().includes(q)) return true;
-        if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q))) return true;
-        if (e.commands.some((c) => c.command.toLowerCase().includes(q))) return true;
-        return false;
-      });
+      const strict = options.strict === true;
+      const hits = [];
+      for (const e of entries) {
+        const matched = [];
+        const typeHit = e.type.toLowerCase().includes(q);
+        const aliasExact = (e.aliases ?? []).some((a) => a.toLowerCase() === q);
+        const aliasSubstr = (e.aliases ?? []).some((a) => a.toLowerCase().includes(q) && a.toLowerCase() !== q);
+        const roleHit = (e.role ?? "").toLowerCase().includes(q);
+        const cmdMatches = e.commands.filter((c) => c.command.toLowerCase().includes(q)).map((c) => c.command);
+        if (typeHit) matched.push("type");
+        if (aliasExact) matched.push("alias");
+        else if (aliasSubstr) matched.push("alias-only");
+        if (roleHit) matched.push("role");
+        if (cmdMatches.length > 0) matched.push(`commands[${cmdMatches.join(",")}]`);
+        if (strict) {
+          if (!typeHit) continue;
+        } else if (matched.length === 0) {
+          continue;
+        }
+        let tier;
+        if (typeHit || aliasExact) tier = 0;
+        else if (roleHit || cmdMatches.length > 0) tier = 1;
+        else tier = 2;
+        hits.push({ entry: e, tier, matched });
+      }
+      hits.sort((a, b2) => a.tier - b2.tier);
       if (isJsonMode()) {
-        printJson({ query: keyword, matches: hits });
+        printJson({
+          query: keyword,
+          strict,
+          matches: hits.map((h) => ({ ...h.entry, _matchedOn: h.matched, _tier: h.tier }))
+        });
         return;
       }
       if (hits.length === 0) {
-        console.log(`No catalog entries match "${keyword}".`);
+        const suffix = strict ? " (strict mode \u2014 try without --strict)" : "";
+        console.log(`No catalog entries match "${keyword}"${suffix}.`);
         return;
       }
       const fmt = resolveFormat();
-      const headers = ["type", "category", "role", "matched"];
-      const rows = hits.map((e) => {
-        const matched = [];
-        if (e.type.toLowerCase().includes(q)) matched.push("type");
-        if ((e.aliases ?? []).some((a) => a.toLowerCase().includes(q))) matched.push("alias");
-        if ((e.role ?? "").toLowerCase().includes(q)) matched.push("role");
-        const cmdMatches = e.commands.filter((c) => c.command.toLowerCase().includes(q)).map((c) => c.command);
-        if (cmdMatches.length > 0) matched.push(`commands[${cmdMatches.join(",")}]`);
-        return [e.type, e.category, e.role ?? "\u2014", matched.join(", ") || "\u2014"];
-      });
+      const headers = ["type", "category", "role", "matched_on"];
+      const rows = hits.map((h) => [
+        h.entry.type,
+        h.entry.category,
+        h.entry.role ?? "\u2014",
+        h.matched.join(", ") || "\u2014"
+      ]);
       renderRows(headers, rows, fmt, resolveFields());
       if (fmt === "table") {
         console.log(`
-${hits.length} match${hits.length === 1 ? "" : "es"} for "${keyword}"`);
+${hits.length} match${hits.length === 1 ? "" : "es"} for "${keyword}"${strict ? " (strict)" : ""}`);
       }
     } catch (error48) {
       handleError(error48);
@@ -51331,7 +51385,6 @@ var import_yaml8 = __toESM(require_dist(), 1);
 init_output();
 import { readFileSync as readFileSync3, writeFileSync as writeFileSync2, existsSync, mkdirSync, copyFileSync, statSync } from "node:fs";
 import { dirname, resolve as resolvePath } from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
 
 // src/policy/format.ts
 init_cjs_shim();
@@ -51391,8 +51444,7 @@ function formatValidationResult(result, source, opts = {}) {
 // src/commands/policy.ts
 var LATEST_SUPPORTED_VERSION2 = SUPPORTED_POLICY_SCHEMA_VERSIONS[SUPPORTED_POLICY_SCHEMA_VERSIONS.length - 1];
 function readEmbeddedTemplate() {
-  const url2 = new URL("../policy/examples/policy.example.yaml", import.meta.url);
-  return readFileSync3(fileURLToPath3(url2), "utf-8");
+  return readPolicyExampleYaml();
 }
 var PolicyFileExistsError = class extends Error {
   constructor(policyPath) {
@@ -56221,11 +56273,29 @@ function resolveStatusSyncRuntime(options) {
   }
   const openclawToken = options.openclawToken ?? process.env.OPENCLAW_TOKEN;
   if (!openclawToken) {
-    throw new UsageError("--openclaw-token is required or set OPENCLAW_TOKEN in the environment.");
+    throw new UsageError(
+      [
+        "OpenClaw token missing. Provide one of:",
+        "  1. --openclaw-token <token>",
+        "  2. OPENCLAW_TOKEN=<token> in the environment",
+        "",
+        "The token is issued by your OpenClaw server admin (same token you use for `events mqtt-tail --sink openclaw`).",
+        "After setting it, re-run the command and verify with `switchbot status-sync status`."
+      ].join("\n")
+    );
   }
   const openclawModel = options.openclawModel ?? process.env.OPENCLAW_MODEL;
   if (!openclawModel) {
-    throw new UsageError("--openclaw-model is required or set OPENCLAW_MODEL in the environment.");
+    throw new UsageError(
+      [
+        "OpenClaw model missing. Provide one of:",
+        "  1. --openclaw-model <model>",
+        "  2. OPENCLAW_MODEL=<model> in the environment",
+        "",
+        "The model name maps this CLI to a registered agent/device on the OpenClaw side.",
+        "After setting it, re-run the command and verify with `switchbot status-sync status`."
+      ].join("\n")
+    );
   }
   return {
     openclawUrl: options.openclawUrl ?? process.env.OPENCLAW_URL ?? DEFAULT_OPENCLAW_URL,
@@ -56860,7 +56930,7 @@ init_output();
 import { spawn as spawn5 } from "node:child_process";
 import fs29 from "node:fs";
 import path25 from "node:path";
-import { fileURLToPath as fileURLToPath4 } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 init_arg_parsers();
 init_source();
 function readDaemonPid() {
@@ -57010,7 +57080,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       } catch {
       }
     }
-    const thisFile = fileURLToPath4(import.meta.url);
+    const thisFile = fileURLToPath2(import.meta.url);
     const cliEntry = path25.resolve(path25.dirname(thisFile), "..", "index.js");
     const args = ["rules", "run"];
     if (opts.policy) args.push(opts.policy);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "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",