3.5.0: device intelligence, UX polish & correctness (#44)

* feat: AI device controlType fallback with typeSource signal

* feat: inject deviceId/deviceType into all status responses

* feat: warn on AI devices using controlType fallback

* feat: add scenes run and history list aliases

* feat: expand setColor to ~148 CSS Level 4 named colors

* feat: add --once shorthand for --max 1 on watch

* feat: add --plan flag for inline JSON on plan run

* feat: layered health audit with expected/unexpected error breakdown

* feat: add [n/total] progress counter to batch human output

* fix: show "Unknown Device" for devices with no type from API

AI MindClip and AI PinNote report neither deviceType nor controlType.
Previously rendered as empty/dash; now shows "Unknown Device" with a
stderr warning in describe mode.

* fix: v3.5.0 correctness fixes from real-device validation

- Status identity injection: ensure deviceId/deviceType override raw API fields
- Cache stores typeSource to distinguish deviceType vs controlType origin
- Cache-to-DeviceList synthesis respects typeSource (prevents controlType leaking as deviceType)
- --plan invalid JSON now throws UsageError (exit 2) instead of runtime error
- Tests updated for typeSource, controlType fallback warning, and stricter assertions

---------

Co-authored-by: chenliuyun <chenliuyun@onero.com>

Author: chenliuyun

src/commands/batch.ts

@@ -386,9 +386,13 @@ 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 {
@@ -403,7 +407,7 @@ Examples:
             const replayed =
               typeof result === 'object' && result !== null && (result as { replayed?: boolean }).replayed === true;
             if (!isJsonMode()) {
-              console.log(`✓ ${id}: ${cmd}${replayed ? ' (replayed)' : ''}`);
+              console.log(`[${stepIdx}/${totalDevices}] ✓ ${id}: ${cmd}${replayed ? ' (replayed)' : ''}`);
             }
             return {
               ok: true as const,
@@ -428,7 +432,7 @@ Examples:
             }
             const errorPayload = buildErrorPayload(err);
             if (!isJsonMode()) {
-              console.error(`✗ ${id}: ${errorPayload.message}`);
+              console.error(`[${stepIdx}/${totalDevices}] ✗ ${id}: ${errorPayload.message}`);
             }
             return {
               ok: false as const,

src/commands/devices.ts

@@ -44,15 +44,21 @@ const EXPAND_HINTS: Record<string, { command: string; flags: string }> = {
   'Relay Switch 2PM': { command: 'setMode',      flags: '--channel 1 --mode edge' },
 };
 
-function annotateStatusPayload(deviceId: string, body: Record<string, unknown>): Record<string, unknown> {
-  const annotated = { ...body };
+function annotateStatusPayload(
+  deviceId: string,
+  body: Record<string, unknown>,
+): Record<string, unknown> {
+  const cached = getCachedDevice(deviceId);
+  const deviceType = cached?.type ?? '';
+  const annotated: Record<string, unknown> = { 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 cached = getCachedDevice(deviceId);
   const looksLikeMeter = cached?.type?.toLowerCase().includes('meter') ?? false;
   const staleZeroReading =
     looksLikeMeter &&
@@ -221,7 +227,7 @@ Examples:
           rows.push([
             d.deviceId,
             d.deviceName,
-            d.deviceType || '—',
+            d.deviceType || d.controlType || 'Unknown Device',
             'physical',
             d.controlType || '—',
             d.familyName || '—',
@@ -887,12 +893,20 @@ Examples:
           return;
         }
 
+        if (result.typeSource === 'controlType') {
+          const deviceName = (device as Device).deviceName ?? deviceId;
+          console.error(`warning: ${deviceName} (${deviceId}): deviceType not reported by API, using controlType "${result.controlType}". Capabilities may be limited.`);
+        } else if (typeName === 'Unknown Device') {
+          const deviceName = (device as Device).deviceName ?? deviceId;
+          console.error(`warning: ${deviceName} (${deviceId}): neither deviceType nor controlType reported by API. Capabilities may be limited.`);
+        }
+
         if (isPhysical) {
           const physical = device as Device;
           printKeyValue({
             deviceId: physical.deviceId,
             deviceName: physical.deviceName,
-            deviceType: physical.deviceType || '—',
+            deviceType: physical.deviceType || physical.controlType || 'Unknown Device',
             controlType: physical.controlType || '—',
             family: physical.familyName || '—',
             roomID: physical.roomID || '—',

src/commands/history.ts

@@ -36,6 +36,7 @@ Examples:
 
   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 }))

src/commands/plan.ts

@@ -493,18 +493,31 @@ against the live API without executing any mutations.
     .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 (
         file: string | undefined,
-        options: { yes?: boolean; requireApproval?: boolean; continueOnError?: boolean },
+        options: { yes?: boolean; requireApproval?: boolean; continueOnError?: boolean; plan?: string },
       ) => {
         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 !== undefined && file !== undefined) {
+          console.error('error: --plan and a file argument are mutually exclusive.');
+          process.exit(2);
+        }
         let raw: unknown;
         try {
-          raw = await readPlanSource(file);
+          if (options.plan !== undefined) {
+            try {
+              raw = JSON.parse(options.plan);
+            } catch (err) {
+              throw new UsageError(`--plan is not valid JSON: ${(err as Error).message}`);
+            }
+          } else {
+            raw = await readPlanSource(file);
+          }
         } catch (err) {
           handleError(err);
         }

src/commands/scenes.ts

@@ -51,6 +51,7 @@ Examples:
   // switchbot scenes execute <sceneId>
   scenes
     .command('execute')
+    .alias('run')
     .description('Execute a manual scene by its ID')
     .argument('<sceneId>', 'Scene ID from "scenes list"')
     .addHelpText('after', `

src/commands/watch.ts

@@ -91,6 +91,7 @@ export function registerWatchCommand(devices: Command): void {
       '30s',
     )
     .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')
@@ -128,12 +129,20 @@ Examples:
           name?: string;
           interval: string;
           max?: string;
+          once?: boolean;
           for?: string;
           includeUnchanged?: boolean;
           initial: 'snapshot' | 'emit' | 'skip';
         },
       ) => {
         try {
+          if (options.once && options.max !== undefined) {
+            throw new UsageError('--once and --max are mutually exclusive.');
+          }
+          if (options.once) {
+            options.max = '1';
+          }
+
           const allIds = [...deviceIds];
           if (options.name) {
             const resolved = resolveDeviceId(undefined, options.name);

src/devices/cache.ts

@@ -31,6 +31,7 @@ const DEFAULT_STATUS_GC_TTL_MS = 24 * 60 * 60 * 1000; // 24 h
 
 export interface CachedDevice {
   type: string;
+  typeSource?: 'deviceType' | 'controlType' | 'remoteType';
   name: string;
   category: 'physical' | 'ir';
   hubDeviceId?: string;
@@ -151,9 +152,8 @@ export function updateCacheFromDeviceList(body: DeviceListBodyShape): void {
   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,
@@ -168,6 +168,7 @@ export function updateCacheFromDeviceList(body: DeviceListBodyShape): void {
     if (!d.deviceId) continue;
     devices[d.deviceId] = {
       type: d.remoteType,
+      typeSource: 'remoteType',
       name: d.deviceName,
       category: 'ir',
       hubDeviceId: d.hubDeviceId,

src/devices/css-colors.ts

@@ -0,0 +1,150 @@
+export const CSS_COLORS: Record<string, [number, number, number]> = {
+  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

@@ -1,4 +1,5 @@
 import { UsageError } from '../utils/output.js';
+import { CSS_COLORS } from './css-colors.js';
 
 export const AC_MODE_MAP: Record<string, number> = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
 export const AC_FAN_MAP: Record<string, number> = { auto: 1, low: 2, mid: 3, high: 4 };
@@ -212,33 +213,23 @@ function hintBrightnessRetry(): string {
   return `Ask the user whether they meant a percentage (1-100). Example: "50".`;
 }
 
-// B-12: setColor accepts R:G:B, R,G,B, #RRGGBB, #RGB, or a small CSS named color
-// palette. All forms are normalized to `R:G:B` (the only wire shape SwitchBot
+// B-12: setColor accepts R:G:B, R,G,B, #RRGGBB, #RGB, or a CSS Level 4 named
+// color. All forms are normalized to `R:G:B` (the only wire shape SwitchBot
 // accepts) so the caller can POST the result unchanged.
-const NAMED_COLORS: Record<string, [number, number, number]> = {
-  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],
+const CUSTOM_COLORS: Record<string, [number, number, number]> = {
   warm: [255, 180, 100],
 };
 
+const NAMED_COLORS: Record<string, [number, number, number]> = {
+  ...CSS_COLORS,
+  ...CUSTOM_COLORS,
+};
+
 function validateSetColor(raw: string | undefined): ValidateResult {
   if (raw === undefined || 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();