@switchbot/openapi-cli 3.4.0 → 3.5.0

package/dist/index.js

@@ -7221,7 +7221,7 @@ function emitJsonError(errorPayload) {
 function emitStreamHeader(opts) {
   console.log(
     JSON.stringify({
-      schemaVersion: SCHEMA_VERSION,
+      schemaVersion: opts.schemaVersion ?? SCHEMA_VERSION,
       stream: true,
       eventKind: opts.eventKind,
       cadence: opts.cadence
@@ -7531,7 +7531,7 @@ var init_output = __esm({
     init_source();
     init_client();
     init_flags();
-    SCHEMA_VERSION = "1.1";
+    SCHEMA_VERSION = "1.2";
     ASCII_BORDER_CHARS = {
       top: "-",
       "top-mid": "+",
@@ -8380,9 +8380,8 @@ function updateCacheFromDeviceList(body) {
   for (const d of body.deviceList) {
     if (!d.deviceId) continue;
     devices[d.deviceId] = {
-      // Some real devices omit deviceType entirely (for example AI accessories).
-      // Keep them in cache with an empty type string rather than dropping the row.
-      type: d.deviceType ?? "",
+      type: d.deviceType || d.controlType || "Unknown Device",
+      typeSource: d.deviceType ? "deviceType" : d.controlType ? "controlType" : "deviceType",
       name: d.deviceName,
       category: "physical",
       hubDeviceId: d.hubDeviceId,
@@ -8397,6 +8396,7 @@ function updateCacheFromDeviceList(body) {
     if (!d.deviceId) continue;
     devices[d.deviceId] = {
       type: d.remoteType,
+      typeSource: "remoteType",
       name: d.deviceName,
       category: "ir",
       hubDeviceId: d.hubDeviceId,
@@ -8793,10 +8793,11 @@ async function fetchDeviceList(client, options = {}) {
       const infraredRemoteList = [];
       for (const [deviceId, entry] of Object.entries(cached2.devices)) {
         if (entry.category === "physical") {
+          const cachedDeviceType = entry.typeSource === "deviceType" ? entry.type : entry.typeSource === void 0 && entry.type !== entry.controlType ? entry.type : void 0;
           deviceList.push({
             deviceId,
             deviceName: entry.name,
-            ...entry.type ? { deviceType: entry.type } : {},
+            ...cachedDeviceType && cachedDeviceType !== "Unknown Device" ? { deviceType: cachedDeviceType } : {},
             enableCloudService: entry.enableCloudService ?? true,
             hubDeviceId: entry.hubDeviceId ?? "",
             roomID: entry.roomID,
@@ -8867,10 +8868,12 @@ async function executeCommand(deviceId, cmd, parameter, commandType, client, opt
       if (err instanceof Error && err.name === "DryRunSignal") {
         writeAudit({ ...baseAudit, result: "dry-run" });
       } else {
+        const statusCode = err instanceof ApiError ? err.code : void 0;
         writeAudit({
           ...baseAudit,
           result: "error",
-          error: err instanceof Error ? err.message : String(err)
+          error: err instanceof Error ? err.message : String(err),
+          ...statusCode !== void 0 ? { statusCode } : {}
         });
       }
       throw err;
@@ -8991,7 +8994,23 @@ async function describeDevice(deviceId, options = {}, client) {
     ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
   }
   if (!physical && !ir) throw new DeviceNotFoundError(deviceId);
-  const typeName = physical ? physical.deviceType ?? "" : ir.remoteType;
+  let typeName;
+  let typeSource;
+  if (physical) {
+    if (physical.deviceType) {
+      typeName = physical.deviceType;
+      typeSource = "deviceType";
+    } else if (physical.controlType) {
+      typeName = physical.controlType;
+      typeSource = "controlType";
+    } else {
+      typeName = "Unknown Device";
+      typeSource = "deviceType";
+    }
+  } else {
+    typeName = ir.remoteType;
+    typeSource = "remoteType";
+  }
   const match = typeName ? findCatalogEntry(typeName) : null;
   const catalogEntry = !match || Array.isArray(match) ? null : match;
   let liveStatus;
@@ -9027,6 +9046,7 @@ async function describeDevice(deviceId, options = {}, client) {
     device: selectedDevice,
     isPhysical: Boolean(physical),
     typeName,
+    typeSource,
     controlType: physical?.controlType ?? ir?.controlType ?? null,
     catalog: catalogEntry,
     capabilities,
@@ -28296,8 +28316,21 @@ function commandToJson(cmd, opts = {}) {
 }
 function resolveTargetCommand(root, argv) {
   let cmd = root;
+  const rootOptions = root.options;
+  let consumeNext = false;
   for (const token of argv) {
-    if (token.startsWith("-")) continue;
+    if (consumeNext) {
+      consumeNext = false;
+      continue;
+    }
+    if (token.startsWith("-")) {
+      if (!token.includes("=")) {
+        const localOpts = cmd.options;
+        const opt = localOpts.find((o) => o.short === token || o.long === token) || rootOptions.find((o) => o.short === token || o.long === token);
+        if (opt && (opt.required || opt.optional)) consumeNext = true;
+      }
+      continue;
+    }
     const sub = cmd.commands.find(
       (c) => c.name() === token || c.aliases().includes(token)
     );
@@ -31697,6 +31730,161 @@ function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation) {
 // src/devices/param-validator.ts
 init_cjs_shim();
 init_output();
+
+// src/devices/css-colors.ts
+init_cjs_shim();
+var CSS_COLORS = {
+  aliceblue: [240, 248, 255],
+  antiquewhite: [250, 235, 215],
+  aqua: [0, 255, 255],
+  aquamarine: [127, 255, 212],
+  azure: [240, 255, 255],
+  beige: [245, 245, 220],
+  bisque: [255, 228, 196],
+  black: [0, 0, 0],
+  blanchedalmond: [255, 235, 205],
+  blue: [0, 0, 255],
+  blueviolet: [138, 43, 226],
+  brown: [165, 42, 42],
+  burlywood: [222, 184, 135],
+  cadetblue: [95, 158, 160],
+  chartreuse: [127, 255, 0],
+  chocolate: [210, 105, 30],
+  coral: [255, 127, 80],
+  cornflowerblue: [100, 149, 237],
+  cornsilk: [255, 248, 220],
+  crimson: [220, 20, 60],
+  cyan: [0, 255, 255],
+  darkblue: [0, 0, 139],
+  darkcyan: [0, 139, 139],
+  darkgoldenrod: [184, 134, 11],
+  darkgray: [169, 169, 169],
+  darkgreen: [0, 100, 0],
+  darkgrey: [169, 169, 169],
+  darkkhaki: [189, 183, 107],
+  darkmagenta: [139, 0, 139],
+  darkolivegreen: [85, 107, 47],
+  darkorange: [255, 140, 0],
+  darkorchid: [153, 50, 204],
+  darkred: [139, 0, 0],
+  darksalmon: [233, 150, 122],
+  darkseagreen: [143, 188, 143],
+  darkslateblue: [72, 61, 139],
+  darkslategray: [47, 79, 79],
+  darkslategrey: [47, 79, 79],
+  darkturquoise: [0, 206, 209],
+  darkviolet: [148, 0, 211],
+  deeppink: [255, 20, 147],
+  deepskyblue: [0, 191, 255],
+  dimgray: [105, 105, 105],
+  dimgrey: [105, 105, 105],
+  dodgerblue: [30, 144, 255],
+  firebrick: [178, 34, 34],
+  floralwhite: [255, 250, 240],
+  forestgreen: [34, 139, 34],
+  fuchsia: [255, 0, 255],
+  gainsboro: [220, 220, 220],
+  ghostwhite: [248, 248, 255],
+  gold: [255, 215, 0],
+  goldenrod: [218, 165, 32],
+  gray: [128, 128, 128],
+  green: [0, 128, 0],
+  greenyellow: [173, 255, 47],
+  grey: [128, 128, 128],
+  honeydew: [240, 255, 240],
+  hotpink: [255, 105, 180],
+  indianred: [205, 92, 92],
+  indigo: [75, 0, 130],
+  ivory: [255, 255, 240],
+  khaki: [240, 230, 140],
+  lavender: [230, 230, 250],
+  lavenderblush: [255, 240, 245],
+  lawngreen: [124, 252, 0],
+  lemonchiffon: [255, 250, 205],
+  lightblue: [173, 216, 230],
+  lightcoral: [240, 128, 128],
+  lightcyan: [224, 255, 255],
+  lightgoldenrodyellow: [250, 250, 210],
+  lightgray: [211, 211, 211],
+  lightgreen: [144, 238, 144],
+  lightgrey: [211, 211, 211],
+  lightpink: [255, 182, 193],
+  lightsalmon: [255, 160, 122],
+  lightseagreen: [32, 178, 170],
+  lightskyblue: [135, 206, 250],
+  lightslategray: [119, 136, 153],
+  lightslategrey: [119, 136, 153],
+  lightsteelblue: [176, 196, 222],
+  lightyellow: [255, 255, 224],
+  lime: [0, 255, 0],
+  limegreen: [50, 205, 50],
+  linen: [250, 240, 230],
+  magenta: [255, 0, 255],
+  maroon: [128, 0, 0],
+  mediumaquamarine: [102, 205, 170],
+  mediumblue: [0, 0, 205],
+  mediumorchid: [186, 85, 211],
+  mediumpurple: [147, 111, 219],
+  mediumseagreen: [60, 179, 113],
+  mediumslateblue: [123, 104, 238],
+  mediumspringgreen: [0, 250, 154],
+  mediumturquoise: [72, 209, 204],
+  mediumvioletred: [199, 21, 133],
+  midnightblue: [25, 25, 112],
+  mintcream: [245, 255, 250],
+  mistyrose: [255, 228, 225],
+  moccasin: [255, 228, 181],
+  navajowhite: [255, 222, 173],
+  navy: [0, 0, 128],
+  oldlace: [253, 245, 230],
+  olive: [128, 128, 0],
+  olivedrab: [107, 142, 35],
+  orange: [255, 165, 0],
+  orangered: [255, 69, 0],
+  orchid: [218, 112, 214],
+  palegoldenrod: [238, 232, 170],
+  palegreen: [152, 251, 152],
+  paleturquoise: [175, 238, 238],
+  palevioletred: [219, 112, 147],
+  papayawhip: [255, 239, 213],
+  peachpuff: [255, 218, 185],
+  peru: [205, 133, 63],
+  pink: [255, 192, 203],
+  plum: [221, 160, 221],
+  powderblue: [176, 224, 230],
+  purple: [128, 0, 128],
+  rebeccapurple: [102, 51, 153],
+  red: [255, 0, 0],
+  rosybrown: [188, 143, 143],
+  royalblue: [65, 105, 225],
+  saddlebrown: [139, 69, 19],
+  salmon: [250, 128, 114],
+  sandybrown: [244, 164, 96],
+  seagreen: [46, 139, 87],
+  seashell: [255, 245, 238],
+  sienna: [160, 82, 45],
+  silver: [192, 192, 192],
+  skyblue: [135, 206, 235],
+  slateblue: [106, 90, 205],
+  slategray: [112, 128, 144],
+  slategrey: [112, 128, 144],
+  snow: [255, 250, 250],
+  springgreen: [0, 255, 127],
+  steelblue: [70, 130, 180],
+  tan: [210, 180, 140],
+  teal: [0, 128, 128],
+  thistle: [216, 191, 216],
+  tomato: [255, 99, 71],
+  turquoise: [64, 224, 208],
+  violet: [238, 130, 238],
+  wheat: [245, 222, 179],
+  white: [255, 255, 255],
+  whitesmoke: [245, 245, 245],
+  yellow: [255, 255, 0],
+  yellowgreen: [154, 205, 50]
+};
+
+// src/devices/param-validator.ts
 var AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
 var AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
 var CURTAIN_MODE_MAP = { default: "ff", performance: "0", silent: "1" };
@@ -31763,6 +31951,26 @@ function buildRelaySetMode(opts) {
   }
   return `${ch};${modeInt}`;
 }
+function buildBrightnessSet(opts) {
+  if (!opts.brightness) throw new UsageError("--brightness is required (1-100)");
+  const b2 = parseInt(opts.brightness, 10);
+  if (!Number.isFinite(b2) || b2 < 1 || b2 > 100) {
+    throw new UsageError(`--brightness must be an integer between 1 and 100 (got "${opts.brightness}")`);
+  }
+  return String(b2);
+}
+function buildColorSet(opts) {
+  if (!opts.color) throw new UsageError('--color is required (e.g. "255:0:0", "#FF0000", "red")');
+  const result = validateSetColor(opts.color);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.color;
+}
+function buildColorTemperatureSet(opts) {
+  if (!opts.colorTemp) throw new UsageError("--color-temp is required (2700-6500)");
+  const result = validateSetColorTemperature(opts.colorTemp);
+  if (!result.ok) throw new UsageError(result.error);
+  return result.normalized ?? opts.colorTemp;
+}
 function validateParameter(deviceType, command, raw) {
   if (!deviceType) return { ok: true };
   if (deviceType === "Air Conditioner" && command === "setAll") {
@@ -31783,7 +31991,7 @@ function validateParameter(deviceType, command, raw) {
   if (command === "setColor" && isColorDevice(deviceType)) {
     return validateSetColor(raw);
   }
-  if (command === "setColorTemperature" && isColorDevice(deviceType)) {
+  if (command === "setColorTemperature" && isBrightnessDevice(deviceType)) {
     return validateSetColorTemperature(raw);
   }
   return { ok: true };
@@ -31792,7 +32000,12 @@ function isBrightnessDevice(deviceType) {
   return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Dimmer" || deviceType === "Fill Light";
 }
 function isColorDevice(deviceType) {
-  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Ceiling Light" || deviceType === "Ceiling Light Pro" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+  return deviceType === "Color Bulb" || deviceType === "Strip Light" || deviceType === "Strip Light 3" || deviceType === "Floor Lamp" || deviceType === "Light Strip" || deviceType === "Fill Light";
+}
+function isLightingCommandSupported(deviceType, command) {
+  if (command === "setBrightness" || command === "setColorTemperature") return isBrightnessDevice(deviceType);
+  if (command === "setColor") return isColorDevice(deviceType);
+  return false;
 }
 function validateSetBrightness(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
@@ -31820,29 +32033,18 @@ function validateSetBrightness(raw) {
 function hintBrightnessRetry() {
   return `Ask the user whether they meant a percentage (1-100). Example: "50".`;
 }
-var NAMED_COLORS = {
-  red: [255, 0, 0],
-  green: [0, 128, 0],
-  lime: [0, 255, 0],
-  blue: [0, 0, 255],
-  yellow: [255, 255, 0],
-  cyan: [0, 255, 255],
-  magenta: [255, 0, 255],
-  white: [255, 255, 255],
-  black: [0, 0, 0],
-  orange: [255, 165, 0],
-  purple: [128, 0, 128],
-  pink: [255, 192, 203],
-  brown: [165, 42, 42],
-  grey: [128, 128, 128],
-  gray: [128, 128, 128],
+var CUSTOM_COLORS = {
   warm: [255, 180, 100]
 };
+var NAMED_COLORS = {
+  ...CSS_COLORS,
+  ...CUSTOM_COLORS
+};
 function validateSetColor(raw) {
   if (raw === void 0 || raw === "" || raw === "default") {
     return {
       ok: false,
-      error: `setColor requires a color. Expected one of: "R:G:B" (e.g. "255:0:0"), "#RRGGBB" (e.g. "#FF0000"), "#RGB", "R,G,B", or a named color (${Object.keys(NAMED_COLORS).slice(0, 8).join(", ")}, ...).`
+      error: `setColor requires a color. Use a CSS color name (e.g. coral, teal, salmon), hex (#RRGGBB / #RGB), or R:G:B format.`
     };
   }
   const trimmed = raw.trim();
@@ -32357,8 +32559,11 @@ Examples:
         }
         return;
       }
+      const totalDevices = resolved.ids.length;
+      const deviceIndices = new Map(resolved.ids.map((id, i) => [id, i + 1]));
       const startedAt = Date.now();
       const outcomes = await runPool(resolved.ids, concurrency, staggerMs, async (id) => {
+        const stepIdx = deviceIndices.get(id);
         const stepStart = Date.now();
         const startedIso = new Date(stepStart).toISOString();
         try {
@@ -32370,7 +32575,7 @@ Examples:
           const durationMs = Date.now() - stepStart;
           const replayed = typeof result2 === "object" && result2 !== null && result2.replayed === true;
           if (!isJsonMode()) {
-            console.log(`\u2713 ${id}: ${cmd}${replayed ? " (replayed)" : ""}`);
+            console.log(`[${stepIdx}/${totalDevices}] \u2713 ${id}: ${cmd}${replayed ? " (replayed)" : ""}`);
           }
           return {
             ok: true,
@@ -32393,7 +32598,7 @@ Examples:
           }
           const errorPayload = buildErrorPayload(err);
           if (!isJsonMode()) {
-            console.error(`\u2717 ${id}: ${errorPayload.message}`);
+            console.error(`[${stepIdx}/${totalDevices}] \u2717 ${id}: ${errorPayload.message}`);
           }
           return {
             ok: false,
@@ -32643,7 +32848,7 @@ function registerWatchCommand(devices) {
     `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1e3}s)`,
     durationArg("--interval"),
     "30s"
-  ).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").option("--initial <mode>", "How to handle the first poll: snapshot | emit | skip (default: snapshot)", enumArg("--initial", INITIAL_MODES), "snapshot").addHelpText(
+  ).option("--max <n>", "Stop after N ticks (default: run until Ctrl-C)", intArg("--max", { min: 1 })).option("--once", "Stop after one tick (shorthand for --max 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").option("--initial <mode>", "How to handle the first poll: snapshot | emit | skip (default: snapshot)", enumArg("--initial", INITIAL_MODES), "snapshot").addHelpText(
     "after",
     `
 Default output is a human-readable table of field changes per tick; add --json
@@ -32672,6 +32877,12 @@ Examples:
   ).action(
     async (deviceIds, options) => {
       try {
+        if (options.once && options.max !== void 0) {
+          throw new UsageError("--once and --max are mutually exclusive.");
+        }
+        if (options.once) {
+          options.max = "1";
+        }
         const allIds = [...deviceIds];
         if (options.name) {
           const resolved = resolveDeviceId(void 0, options.name);
@@ -32923,10 +33134,11 @@ init_arg_parsers();
 init_output();
 init_cache();
 init_devices();
+init_catalog();
 init_flags();
 init_client();
 function registerExpandCommand(devices) {
-  devices.command("expand").description("Send a command with semantic flags instead of raw positional parameters").argument("[deviceId]", 'Target device ID from "devices list" (or use --name)').argument("[command]", "Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2)").option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--temp <celsius>", "AC setAll: temperature in Celsius (16-30)", intArg("--temp", { min: 16, max: 30 })).option("--mode <mode>", "AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary", stringArg("--mode")).option("--fan <speed>", "AC setAll: fan speed auto|low|mid|high", stringArg("--fan")).option("--power <state>", "AC setAll: on|off", stringArg("--power")).option("--position <percent>", "Curtain setPosition: 0-100 (0=open, 100=closed)", intArg("--position", { min: 0, max: 100 })).option("--direction <dir>", "Blind Tilt setPosition: up|down", stringArg("--direction")).option("--angle <percent>", "Blind Tilt setPosition: 0-100 (0=closed, 100=open)", intArg("--angle", { min: 0, max: 100 })).option("--channel <n>", "Relay Switch 2 setMode: channel 1 or 2", intArg("--channel", { min: 1, max: 2 })).option("--yes", "Confirm destructive commands").addHelpText("after", `
+  devices.command("expand").description("Send a command with semantic flags instead of raw positional parameters").argument("[deviceId]", 'Target device ID from "devices list" (or use --name)').argument("[command]", "Command name: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch 2), setBrightness/setColor/setColorTemperature (lighting)").option("--name <query>", "Resolve device by fuzzy name instead of deviceId", stringArg("--name")).option("--name-strategy <s>", `Name match strategy: ${ALL_STRATEGIES.join("|")} (default: require-unique)`, stringArg("--name-strategy")).option("--name-type <type>", 'Narrow --name by device type (e.g. "Curtain", "Air Conditioner")', stringArg("--name-type")).option("--name-category <cat>", "Narrow --name by category: physical|ir", enumArg("--name-category", ["physical", "ir"])).option("--name-room <room>", "Narrow --name by room name (substring match)", stringArg("--name-room")).option("--temp <celsius>", "AC setAll: temperature in Celsius (16-30)", intArg("--temp", { min: 16, max: 30 })).option("--mode <mode>", "AC: auto|cool|dry|fan|heat  Curtain: default|performance|silent  Relay: toggle|edge|detached|momentary", stringArg("--mode")).option("--fan <speed>", "AC setAll: fan speed auto|low|mid|high", stringArg("--fan")).option("--power <state>", "AC setAll: on|off", stringArg("--power")).option("--position <percent>", "Curtain setPosition: 0-100 (0=open, 100=closed)", intArg("--position", { min: 0, max: 100 })).option("--direction <dir>", "Blind Tilt setPosition: up|down", stringArg("--direction")).option("--angle <percent>", "Blind Tilt setPosition: 0-100 (0=closed, 100=open)", intArg("--angle", { min: 0, max: 100 })).option("--channel <n>", "Relay Switch 2 setMode: channel 1 or 2", intArg("--channel", { min: 1, max: 2 })).option("--brightness <percent>", "setBrightness: 1-100 percent", intArg("--brightness", { min: 1, max: 100 })).option("--color <value>", "setColor: R:G:B, #RRGGBB, or named color (red, blue, etc.)", stringArg("--color")).option("--color-temp <kelvin>", "setColorTemperature: 2700-6500 Kelvin", intArg("--color-temp", { min: 2700, max: 6500 })).option("--yes", "Confirm destructive commands").addHelpText("after", `
 Translates semantic flags into the wire parameter format, then sends the command.
 
 Supported expansions:
@@ -32947,12 +33159,25 @@ Supported expansions:
     --channel 1 --mode edge  \u2192  "1;1"
     --mode values: toggle (0) | edge (1) | detached (2) | momentary (3)
 
+  Color Bulb / Strip Light / Ceiling Light \u2014 setBrightness
+    --brightness 80  \u2192  "80"
+
+  Color Bulb / Strip Light / Floor Lamp \u2014 setColor
+    --color "255:0:0"  \u2192  "255:0:0"
+    --color "#FF0000"  \u2192  "255:0:0"
+    --color red        \u2192  "255:0:0"
+
+  Color Bulb / Strip Light / Ceiling Light \u2014 setColorTemperature
+    --color-temp 4000  \u2192  "4000"
+
 Examples:
-  $ switchbot devices expand <acId>      setAll       --temp 26 --mode cool --fan low --power on
-  $ switchbot devices expand <curtainId> setPosition  --position 50 --mode silent
-  $ switchbot devices expand <blindId>   setPosition  --direction up --angle 50
-  $ switchbot devices expand <relayId>   setMode      --channel 1 --mode edge
-  $ switchbot devices expand <acId>      setAll       --temp 22 --mode heat --fan auto --power on --dry-run
+  $ switchbot devices expand <acId>      setAll               --temp 26 --mode cool --fan low --power on
+  $ switchbot devices expand <curtainId> setPosition          --position 50 --mode silent
+  $ switchbot devices expand <blindId>   setPosition          --direction up --angle 50
+  $ switchbot devices expand <relayId>   setMode              --channel 1 --mode edge
+  $ switchbot devices expand <stripId>   setBrightness        --brightness 80
+  $ switchbot devices expand <bulbId>    setColor             --color "#FF0000"
+  $ switchbot devices expand <bulbId>    setColorTemperature  --color-temp 4000
   $ switchbot devices expand --name "Living Room AC" setAll --temp 26 --mode cool --fan low --power on
 `).action(async (deviceIdArg, commandArg, options) => {
     let deviceId = "";
@@ -32970,12 +33195,22 @@ Examples:
         category: options.nameCategory,
         room: options.nameRoom
       });
-      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode).");
+      if (!effectiveCommand) throw new UsageError("A command argument is required (setAll, setPosition, setMode, setBrightness, setColor, setColorTemperature).");
       command = effectiveCommand;
       const cached2 = getCachedDevice(deviceId);
       const deviceType = cached2?.type ?? "";
       let parameter;
       if (command === "setAll") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this is an Air Conditioner.`
+          );
+        }
+        if (deviceType !== "Air Conditioner") {
+          throw new UsageError(
+            `"setAll" is only supported on Air Conditioner devices, but "${cached2.type}" was found.`
+          );
+        }
         parameter = buildAcSetAll(options);
       } else if (command === "setPosition") {
         if (!cached2) {
@@ -32983,13 +33218,56 @@ Examples:
             `Device ${deviceId} is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' knows whether this is a Curtain or a Blind Tilt.`
           );
         }
+        const positionTypes = ["Curtain", "Curtain 3", "Roller Shade", "Blind Tilt"];
+        if (!positionTypes.some((t) => deviceType.startsWith(t))) {
+          throw new UsageError(
+            `"setPosition" is only supported on Curtain, Roller Shade, and Blind Tilt devices, but "${cached2.type}" was found.`
+          );
+        }
         const isBlind = deviceType.startsWith("Blind Tilt");
-        parameter = isBlind ? buildBlindTiltSetPosition(options) : buildCurtainSetPosition(options);
+        const isRollerShade = deviceType.startsWith("Roller Shade");
+        if (isBlind) {
+          parameter = buildBlindTiltSetPosition(options);
+        } else if (isRollerShade) {
+          if (!options.position) throw new UsageError("--position is required (0-100)");
+          parameter = options.position;
+        } else {
+          parameter = buildCurtainSetPosition(options);
+        }
       } else if (command === "setMode" && deviceType.startsWith("Relay Switch")) {
         parameter = buildRelaySetMode(options);
+      } else if (command === "setBrightness" || command === "setColor" || command === "setColorTemperature") {
+        if (!cached2) {
+          throw new UsageError(
+            `Device "${deviceId}" is not in the local cache \u2014 run 'switchbot devices list' first so 'expand' can verify this device supports ${command}.`
+          );
+        }
+        const catalogResult = findCatalogEntry(cached2.type);
+        const catalogEntry = Array.isArray(catalogResult) ? catalogResult[0] : catalogResult;
+        const supportedHint = command === "setColor" ? "Color Bulb, Strip Light, Floor Lamp, and similar RGB lighting devices" : "Color Bulb, Strip Light, Ceiling Light, Floor Lamp, and similar lighting devices";
+        if (catalogEntry !== null) {
+          if (!catalogEntry.commands.some((c) => c.command === command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        } else {
+          if (!isLightingCommandSupported(cached2.type, command)) {
+            throw new UsageError(
+              `Device type "${cached2.type}" does not support ${command}. Supported on: ${supportedHint}.`
+            );
+          }
+        }
+        if (command === "setBrightness") {
+          parameter = buildBrightnessSet(options);
+        } else if (command === "setColor") {
+          parameter = buildColorSet(options);
+        } else {
+          parameter = buildColorTemperatureSet(options);
+        }
       } else {
         throw new UsageError(
-          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Use 'switchbot devices command' to send raw parameters instead.`
+          `'expand' does not support "${command}" for device type "${deviceType || "unknown"}". Supported: setAll (AC), setPosition (Curtain/Blind Tilt), setMode (Relay Switch), setBrightness/setColor/setColorTemperature (lighting). Use 'switchbot devices command' to send raw parameters instead.`
         );
       }
       if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, "command")) {
@@ -33153,13 +33431,16 @@ var EXPAND_HINTS = {
   "Relay Switch 2PM": { command: "setMode", flags: "--channel 1 --mode edge" }
 };
 function annotateStatusPayload(deviceId, body) {
-  const annotated = { ...body };
+  const cached2 = getCachedDevice(deviceId);
+  const deviceType = cached2?.type ?? "";
+  const annotated = { deviceId, deviceType, ...body };
+  annotated.deviceId = deviceId;
+  annotated.deviceType = deviceType;
   if (Object.keys(body).length === 0) {
     annotated.supported = false;
     annotated.note = "this device does not expose cloud status";
     return annotated;
   }
-  const cached2 = getCachedDevice(deviceId);
   const looksLikeMeter = cached2?.type?.toLowerCase().includes("meter") ?? false;
   const staleZeroReading = looksLikeMeter && !Object.prototype.hasOwnProperty.call(body, "onlineStatus") && body.battery === 0 && body.temperature === 0 && body.humidity === 0;
   if (staleZeroReading) {
@@ -33316,7 +33597,7 @@ Examples:
         rows.push([
           d.deviceId,
           d.deviceName,
-          d.deviceType || "\u2014",
+          d.deviceType || d.controlType || "Unknown Device",
           "physical",
           d.controlType || "\u2014",
           d.familyName || "\u2014",
@@ -33402,7 +33683,7 @@ Examples:
         const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
         const fetchedAt2 = (/* @__PURE__ */ new Date()).toISOString();
         const batch = results.map(
-          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
+          (r, i) => r.status === "fulfilled" ? { deviceId: ids[i], ok: true, fetchedAt: fetchedAt2, ...annotateStatusPayload(ids[i], r.value) } : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) }
         );
         const batchFmt = resolveFormat();
         if (isJsonMode() || batchFmt === "json") {
@@ -33414,7 +33695,7 @@ Examples:
         } else {
           const rawFields = resolveFields();
           for (const entry of batch) {
-            const { deviceId: deviceId2, ok, error: error48, _fetchedAt: ts, ...status } = entry;
+            const { deviceId: deviceId2, ok, error: error48, fetchedAt: ts, ...status } = entry;
             console.log(`
 \u2500\u2500\u2500 ${String(deviceId2)} \u2500\u2500\u2500`);
             if (!ok) {
@@ -33440,11 +33721,11 @@ Examples:
       const fetchedAt = (/* @__PURE__ */ new Date()).toISOString();
       const fmt = resolveFormat();
       if (fmt === "json" && process.argv.includes("--json")) {
-        printJson({ ...body, _fetchedAt: fetchedAt });
+        printJson({ ...body, fetchedAt });
         return;
       }
       if (fmt !== "table") {
-        const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+        const statusWithTs = { ...body, fetchedAt };
         const allHeaders = Object.keys(statusWithTs);
         const allRows = [Object.values(statusWithTs)];
         const rawFields = resolveFields();
@@ -33773,7 +34054,7 @@ Examples:
       const joinedMatch = findCatalogEntry(joined);
       if (joinedMatch && !Array.isArray(joinedMatch)) {
         if (isJsonMode()) {
-          printJson(normalizeCatalogForJson(joinedMatch));
+          printJson([normalizeCatalogForJson(joinedMatch)]);
         } else {
           renderCatalogEntry(joinedMatch);
         }
@@ -33865,12 +34146,19 @@ Examples:
         });
         return;
       }
+      if (result.typeSource === "controlType") {
+        const deviceName2 = device.deviceName ?? deviceId;
+        console.error(`warning: ${deviceName2} (${deviceId}): deviceType not reported by API, using controlType "${result.controlType}". Capabilities may be limited.`);
+      } else if (typeName === "Unknown Device") {
+        const deviceName2 = device.deviceName ?? deviceId;
+        console.error(`warning: ${deviceName2} (${deviceId}): neither deviceType nor controlType reported by API. Capabilities may be limited.`);
+      }
       if (isPhysical) {
         const physical = device;
         printKeyValue({
           deviceId: physical.deviceId,
           deviceName: physical.deviceName,
-          deviceType: physical.deviceType || "\u2014",
+          deviceType: physical.deviceType || physical.controlType || "Unknown Device",
           controlType: physical.controlType || "\u2014",
           family: physical.familyName || "\u2014",
           roomID: physical.roomID || "\u2014",
@@ -34049,7 +34337,7 @@ Examples:
       handleError(error48);
     }
   });
-  scenes.command("execute").description("Execute a manual scene by its ID").argument("<sceneId>", 'Scene ID from "scenes list"').addHelpText("after", `
+  scenes.command("execute").alias("run").description("Execute a manual scene by its ID").argument("<sceneId>", 'Scene ID from "scenes list"').addHelpText("after", `
 Example:
   $ switchbot scenes execute T12345678
 `).action(async (sceneId) => {
@@ -48672,9 +48960,9 @@ var logLevel = process.env.LOG_LEVEL || "warn";
 var logFormat = process.env.LOG_FORMAT || "json";
 var pinoConfig = {
   level: logLevel,
-  transport: logFormat === "pretty" ? { target: "pino-pretty" } : void 0
+  transport: logFormat === "pretty" ? { target: "pino-pretty", options: { destination: 2 } } : void 0
 };
-var log = pino(pinoConfig);
+var log = logFormat === "pretty" ? pino(pinoConfig) : pino(pinoConfig, pino.destination(2));
 
 // src/mcp/device-history.ts
 init_cjs_shim();
@@ -49782,15 +50070,27 @@ against the live API without executing any mutations.
       handleError(err);
     }
   });
-  plan.command("run").description("Validate + preview/execute a plan. Respects --dry-run; destructive steps require the reviewed plan flow by default").argument("[file]", 'Path to plan.json, or "-" / omit to read stdin').option("--yes", "Authorize destructive commands (e.g. Smart Lock unlock, Garage open)").option("--require-approval", "Prompt for confirmation before each destructive step (TTY only; mutually exclusive with --json)").option("--continue-on-error", "Keep running after a failed step (default: stop at first error)").action(
+  plan.command("run").description("Validate + preview/execute a plan. Respects --dry-run; destructive steps require the reviewed plan flow by default").argument("[file]", 'Path to plan.json, or "-" / omit to read stdin').option("--yes", "Authorize destructive commands (e.g. Smart Lock unlock, Garage open)").option("--require-approval", "Prompt for confirmation before each destructive step (TTY only; mutually exclusive with --json)").option("--continue-on-error", "Keep running after a failed step (default: stop at first error)").option("--plan <json>", "Inline plan JSON (alternative to file argument or stdin)").action(
     async (file2, options) => {
       if (options.requireApproval && isJsonMode()) {
         console.error("error: --require-approval cannot be used with --json (no TTY available for prompts)");
         process.exit(1);
       }
+      if (options.plan !== void 0 && file2 !== void 0) {
+        console.error("error: --plan and a file argument are mutually exclusive.");
+        process.exit(2);
+      }
       let raw;
       try {
-        raw = await readPlanSource(file2);
+        if (options.plan !== void 0) {
+          try {
+            raw = JSON.parse(options.plan);
+          } catch (err) {
+            throw new UsageError(`--plan is not valid JSON: ${err.message}`);
+          }
+        } else {
+          raw = await readPlanSource(file2);
+        }
       } catch (err) {
         handleError(err);
       }
@@ -52513,12 +52813,27 @@ function listRegisteredTools(server) {
   if (!internal._registeredTools) return [];
   return Object.keys(internal._registeredTools).sort();
 }
+function listRegisteredToolsWithMeta(server) {
+  const internal = server;
+  if (!internal._registeredTools) return [];
+  return Object.entries(internal._registeredTools).sort(([a], [b2]) => a.localeCompare(b2)).map(([name, reg]) => {
+    const entry = { name };
+    if (reg.description) entry.description = reg.description;
+    if (reg.inputSchema) {
+      try {
+        entry.inputSchema = external_exports.toJSONSchema(reg.inputSchema);
+      } catch {
+      }
+    }
+    return entry;
+  });
+}
 function listRegisteredResources() {
   return ["switchbot://events"];
 }
 function printMcpToolDirectory() {
   const server = createSwitchBotMcpServer();
-  const tools = listRegisteredTools(server).map((name) => ({ name }));
+  const tools = listRegisteredToolsWithMeta(server);
   const resources = listRegisteredResources().map((uri) => ({ uri }));
   if (isJsonMode()) {
     printJson({ tools, resources });
@@ -52526,7 +52841,8 @@ function printMcpToolDirectory() {
   }
   console.log("Tools:");
   for (const tool of tools) {
-    console.log(`  ${tool.name}`);
+    const desc = tool.description ? ` \u2014 ${tool.description.slice(0, 80)}` : "";
+    console.log(`  ${tool.name}${desc}`);
   }
   console.log("");
   console.log("Resources:");
@@ -52538,7 +52854,7 @@ Total: ${tools.length} tool(s), ${resources.length} resource(s)`);
 }
 function registerMcpCommand(program3) {
   const mcp = program3.command("mcp").description("Run as a Model Context Protocol server so AI agents can call SwitchBot tools").addHelpText("after", `
-  The MCP server exposes twenty-one tools:
+  The MCP server exposes twenty-four tools:
   - list_devices            fetch all physical + IR devices
   - get_device_status       live status for a physical device
   - send_command            control a device (destructive commands need confirm:true)
@@ -52561,6 +52877,8 @@ function registerMcpCommand(program3) {
   - audit_stats             aggregate audit counts by kind/result/device/rule
   - rule_notifications      query rule notify action delivery history
   - rules_suggest           draft an automation rule YAML from intent (heuristic, no LLM)
+  - rules_explain           show why a rule evaluation fired or was blocked
+  - rules_simulate          simulate a rule against historical events
   - policy_add_rule         append a rule into automation.rules[] in policy.yaml
 
 Resource (read-only):
@@ -53003,7 +53321,7 @@ Examples:
           throw new UsageError(`"${match.type}" exists in the effective catalog but not in source "${source}".`);
         }
         if (isJsonMode()) {
-          printJson(picked);
+          printJson([picked]);
           return;
         }
         renderEntry(picked);
@@ -53745,7 +54063,7 @@ Examples:
       let matchedCount = 0;
       const ac = new AbortController();
       const forTimer = forMs !== null && forMs > 0 ? setTimeout(() => ac.abort(), forMs) : null;
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       await new Promise((resolve2, reject) => {
         let server = null;
         try {
@@ -53897,7 +54215,7 @@ Examples:
       if (!isJsonMode()) {
         console.error("Fetching MQTT credentials from SwitchBot service\u2026");
       }
-      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push" });
+      if (isJsonMode()) emitStreamHeader({ eventKind: "event", cadence: "push", schemaVersion: EVENTS_SCHEMA_VERSION });
       if (isJsonMode()) {
         const sessionStartAt = (/* @__PURE__ */ new Date()).toISOString();
         emitJsonStreamRecord({
@@ -55467,7 +55785,7 @@ function runSchemaExport(options) {
       payload.resources = RESOURCE_CATALOG;
       payload.cliAddedFields = [
         {
-          field: "_fetchedAt",
+          field: "fetchedAt",
           appliesTo: ["devices status", "devices describe"],
           type: "string (ISO-8601)",
           description: "CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API."
@@ -55530,7 +55848,7 @@ Common top-level fields:
   schemaVersion             CLI schema version (stable for agent contracts)
   data.version              Catalog schema version
   data.types                Array of SchemaEntry (or CompactSchemaEntry with --compact)
-  data._fetchedAt           CLI-added; present on live-query responses ('devices status'),
+  data.fetchedAt            CLI-added; present on live-query responses ('devices status'),
                             not on this offline export.
 
 Examples:
@@ -55566,7 +55884,7 @@ Examples:
   $ switchbot history show --limit 10
   $ switchbot history replay 3
 `);
-  history.command("show").description("Print recent audit entries").option("--file <path>", `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg("--file")).option("--limit <n>", "Show only the last N entries", intArg("--limit", { min: 1 })).action((options) => {
+  history.command("show").alias("list").description("Print recent audit entries").option("--file <path>", `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg("--file")).option("--limit <n>", "Show only the last N entries", intArg("--limit", { min: 1 })).action((options) => {
     const file2 = options.file ?? DEFAULT_AUDIT;
     const entries = readAudit(file2);
     const limited = options.limit !== void 0 ? entries.slice(-Math.max(1, Number(options.limit) || 1)) : entries;
@@ -56841,13 +57159,12 @@ function registerRun(rules) {
     const loaded = loadAutomation(pathArg);
     if (!loaded) return;
     if (loaded.automation?.enabled !== true) {
-      const msg = "automation.enabled is not true \u2014 nothing to run.";
-      if (isJsonMode()) {
-        printJson({ kind: "control", controlKind: "disabled", message: msg });
-      } else {
-        console.error(msg);
-      }
-      process.exit(0);
+      exitWithError({
+        code: 1,
+        kind: "runtime",
+        message: "automation.enabled is not true \u2014 set it to true in your policy file to start the daemon.",
+        hint: "Set automation.enabled: true in your policy file, then re-run."
+      });
     }
     const lint = lintRules(loaded.automation);
     if (!lint.valid) {
@@ -59216,6 +59533,7 @@ import os25 from "node:os";
 import path27 from "node:path";
 var DEFAULT_AUDIT_PATH3 = path27.join(os25.homedir(), ".switchbot", "audit.log");
 var AUDIT_ERROR_WINDOW_MS = 24 * 60 * 60 * 1e3;
+var EXPECTED_ERROR_CODES = /* @__PURE__ */ new Set([161, 171, 190]);
 function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
   const now = /* @__PURE__ */ new Date();
   const procHealth = {
@@ -59236,20 +59554,46 @@ function getHealthReport(auditPath = DEFAULT_AUDIT_PATH3) {
   };
   let auditHealth;
   if (!fs31.existsSync(auditPath)) {
-    auditHealth = { present: false, recentErrors: 0, recentTotal: 0, errorRatePercent: 0, status: "ok" };
+    auditHealth = {
+      present: false,
+      recentErrors: 0,
+      recentTotal: 0,
+      errorRatePercent: 0,
+      expectedErrors: 0,
+      unexpectedErrors: 0,
+      unexpectedRatePercent: 0,
+      breakdown: {},
+      status: "ok"
+    };
   } else {
     const entries = readAudit(auditPath);
     const windowStart = now.getTime() - AUDIT_ERROR_WINDOW_MS;
     const recent = entries.filter((e) => new Date(e.t).getTime() >= windowStart);
-    const errors = recent.filter((e) => e.result === "error").length;
+    const errorEntries = recent.filter((e) => e.result === "error");
     const total = recent.length;
+    const errors = errorEntries.length;
     const errorRate = total > 0 ? Math.round(errors / total * 100) : 0;
+    const breakdown = {};
+    let expectedErrors = 0;
+    for (const e of errorEntries) {
+      const code = e.statusCode !== void 0 ? String(e.statusCode) : "unknown";
+      breakdown[code] = (breakdown[code] ?? 0) + 1;
+      if (e.statusCode !== void 0 && EXPECTED_ERROR_CODES.has(e.statusCode)) {
+        expectedErrors++;
+      }
+    }
+    const unexpectedErrors = errors - expectedErrors;
+    const unexpectedRatePercent = total > 0 ? Math.round(unexpectedErrors / total * 100 * 10) / 10 : 0;
     auditHealth = {
       present: true,
       recentErrors: errors,
       recentTotal: total,
       errorRatePercent: errorRate,
-      status: errorRate >= 30 ? "warn" : "ok"
+      expectedErrors,
+      unexpectedErrors,
+      unexpectedRatePercent,
+      breakdown,
+      status: unexpectedRatePercent >= 30 ? "warn" : "ok"
     };
   }
   const cbStats = apiCircuitBreaker.getStats();
@@ -59658,7 +60002,7 @@ The daemon reads the same policy file as \`switchbot rules run\`.
       }
     }
     const thisFile = fileURLToPath3(import.meta.url);
-    const cliEntry = path28.resolve(path28.dirname(thisFile), "..", "index.js");
+    const cliEntry = path28.basename(thisFile) === "index.js" ? thisFile : path28.resolve(path28.dirname(thisFile), "..", "index.js");
     const args = ["rules", "run"];
     if (opts.policy) args.push(opts.policy);
     fs32.mkdirSync(path28.dirname(DAEMON_PID_FILE), { recursive: true, mode: 448 });
@@ -60015,17 +60359,32 @@ try {
 } catch (err) {
   if (err instanceof CommanderError) {
     if (err.code === "commander.helpDisplayed") {
+      const helpRequested = process.argv.includes("--help") || process.argv.includes("-h") || process.argv.includes("help");
+      if (helpRequested) {
+        if (isJsonMode()) {
+          const target = resolveTargetCommand(program2, process.argv.slice(2));
+          printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        }
+        process.exit(0);
+      }
       if (isJsonMode()) {
         const target = resolveTargetCommand(program2, process.argv.slice(2));
-        printJson(commandToJson(target, { includeIdentity: target === program2 }));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        const usefulMessage = subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+        emitJsonError({ code: 2, kind: "usage", message: usefulMessage });
       }
-      process.exit(0);
+      process.exit(2);
     }
     if (err.code === "commander.version") {
       process.exit(0);
     }
     if (isJsonMode()) {
-      emitJsonError({ code: 2, kind: "usage", message: err.message });
+      const errorMessage = err.code === "commander.help" ? (() => {
+        const target = resolveTargetCommand(program2, process.argv.slice(2));
+        const subNames = target.commands.map((c) => c.name()).join(", ");
+        return subNames ? `${target.name()}: a subcommand is required. Available: ${subNames}` : err.message;
+      })() : err.message;
+      emitJsonError({ code: 2, kind: "usage", message: errorMessage });
     }
     process.exit(2);
   }