Fix real-device follow-ups and harden JSON contracts (#38)

* Fix cache-backed device visibility and small command UX regressions

* Tighten audit semantics and suggestion safeguards

* Make policy validation and migration contract truthful

* Polish catalog, status/watch, and operator tooling

* Tighten policy validation and status-sync preflight

* Finish residual diagnostics and contract coverage

* Fix MCP missing-device fallback and lock JSON shapes

* Add catalog fidelity fixtures and contract helpers

* Harden JSON contracts and release smoke coverage

* Expand contract coverage and clean release smoke

* Expand low-frequency contracts and catalog fixtures

* Align policy rule fixtures with current validation

* Correct release-notes registry and pin self-review contracts

Self-review of the 3.3.1 follow-up rollup surfaced a false breaking-change
record and several contracts that were only held in place by careful
reading. This commit corrects the record and pins each contract with a
test that fails loudly if it drifts.

- src/version-notes.ts: remove the 3.3.0 envelope entry from
  RELEASE_METADATA. The {schemaVersion,data} envelope actually shipped
  in commit 33d3825 (v2.0.0) and has been in every 3.x release; flagging
  3.3.0 as the breaking boundary would fire upgrade-check warnings on
  every 3.2.x → 3.3.x upgrade for no reason.
- tests/commands/upgrade-check.test.ts + tests/commands/doctor.test.ts:
  update the asserted contract to match — empty registry returns null;
  doctor release-notes check reports 'ok' for a version with no notice.
- tests/policy/validate.test.ts: add parametric coverage for pathological
  rule device refs (undefined, empty string, literal `<id>`) against
  validateLoadedPolicyAgainstInventory. The live validator's silent
  `continue` on null-resolved refs is only safe because the offline base
  pass catches the same shapes; the new test couples the two so weakening
  either side is caught immediately.
- tests/utils/audit.test.ts: spy ENOSPC and EACCES fs failures into
  writeAudit and assert it does not throw. Several callers (dry-run
  path in src/lib/devices.ts in particular) rely on this being
  best-effort; the contract is now a test, not a comment.
- src/policy/validate.ts: add clarifying comments on the permissive
  offline device-ID regex (real gate is alias-live-device-not-found)
  and on the findCatalogEntry ambiguous-array branch (rare, silence
  beats false positives against drifting upstream types).
- package.json: rename `test:release-smoke` → `test:release-smoke:manual`
  so future maintainers do not assume it runs in prepublishOnly or CI.
- package.json + package-lock.json + README.md: bump package version to
  match the branch-intended rollup and refresh the upgrade-check
  example.

* Fix status-sync --probe preflight and parent-command option inheritance

Three follow-up fixes surfaced by deeper review of the 3.3.1 rollup. Each
was producing a user-visible regression despite passing tests, because the
existing tests pinned the wrong contract.

- src/status-sync/manager.ts: the --probe preflight was hitting the
  OpenClaw base URL with GET and treating any response (including 401 /
  404 / 5xx from upstream proxies) as success, so misconfigurations
  surfaced only after the detached daemon had already been spawned and
  was silently dropping writes. Probe now POSTs to the same endpoint
  the sink uses at runtime (`/v1/chat/completions`), with a body the
  server actually parses, and separates network-error handling from
  HTTP-error handling. Status-specific hints (401/403 → token, 404 →
  URL path, 400/422 → model, 5xx → server) point at the misconfigured
  input so the operator does not have to guess.

- src/commands/schema.ts + src/commands/health.ts: the bare fallback
  forms (`switchbot schema --type Bot`, `switchbot health --prometheus`)
  were previously declared with options on the root command, on the
  subcommand, or on both — none of which worked, because commander v12
  routes parsing of a parent/child dual-declared option to the PARENT
  command, leaving the subcommand action with empty opts. Options are
  now declared only on the root; subcommand actions pull them via
  `cmd.optsWithGlobals()`. The bare and explicit forms now behave
  identically, and `health serve --audit-log` still works because
  optsWithGlobals merges parent options into serve's own port/host.

- tests/status-sync/manager.test.ts: default fetch mock flipped from
  401-returning to 200-returning so existing success-path tests no
  longer accidentally exercised the failure hint. Three new tests pin
  the probe contract: POST to /v1/chat/completions with the model in the
  body, 401 surfaces a token hint, 404 surfaces a URL-path hint, and
  trailing slashes on the base URL are trimmed before appending the
  probe path.

* Validate trigger and condition device refs

---------

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

Author: chenliuyun

README.md

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

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "@switchbot/openapi-cli",
-  "version": "3.3.0",
+  "version": "3.3.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",
@@ -48,6 +48,7 @@
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
+    "test:release-smoke:manual": "npm test -- tests/commands/policy.test.ts tests/commands/devices.test.ts tests/commands/explain.test.ts tests/commands/doctor.test.ts tests/commands/mcp.test.ts tests/commands/health-check.test.ts tests/commands/quota.test.ts tests/commands/status-sync.test.ts tests/status-sync/smoke.test.ts tests/commands/watch.test.ts tests/commands/events.test.ts tests/devices/catalog-fidelity.test.ts tests/commands/schema.test.ts tests/commands/auth.test.ts tests/commands/config.test.ts tests/commands/scenes.test.ts tests/commands/batch.test.ts tests/commands/history.test.ts tests/commands/expand.test.ts tests/commands/webhook.test.ts tests/commands/daemon.test.ts tests/commands/upgrade-check.test.ts tests/commands/install.test.ts tests/commands/uninstall.test.ts tests/commands/rules.test.ts tests/commands/plan.test.ts",
     "verify:pre-commit": "npm run build && npm test -- tests/version.test.ts",
     "verify:pre-push": "npm run build && npm test -- tests/version.test.ts && npm run smoke:pack-install",
     "prepublishOnly": "npm test && npm run build && npm run smoke:pack-install"

package.json

@@ -364,7 +364,6 @@ Examples:
               : undefined,
           }));
           const planDoc = {
-            schemaVersion: '1.1',
             dryRun: true,
             plan: {
               command: cmd,
@@ -503,7 +502,6 @@ Examples:
             skipped: dryRunned.length + preSkipped.length,
             durationMs: Date.now() - startedAt,
             unverifiableCount: succeeded.filter((s) => getCachedDevice(s.deviceId)?.category === 'ir').length,
-            schemaVersion: '1.1',
             maxConcurrent: concurrency,
             staggerMs,
             ...(dryRun ? { dryRun: true } : {}),

src/commands/batch.ts

@@ -44,6 +44,30 @@ 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 };
+  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 &&
+    !Object.prototype.hasOwnProperty.call(body, 'onlineStatus') &&
+    body.battery === 0 &&
+    body.temperature === 0 &&
+    body.humidity === 0;
+
+  if (staleZeroReading) {
+    annotated.hint = 'readings look stale; check batteries or hub connectivity';
+  }
+
+  return annotated;
+}
+
 export function registerDevicesCommand(program: Command): void {
   const COMMAND_TYPES = ['command', 'customize'] as const;
   const devices = program
@@ -303,7 +327,7 @@ Examples:
           const fetchedAt = new Date().toISOString();
           const batch = results.map((r, i) =>
             r.status === 'fulfilled'
-              ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt, ...(r.value as object) }
+              ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt, ...annotateStatusPayload(ids[i], r.value as Record<string, unknown>) }
               : { deviceId: ids[i], ok: false, error: (r.reason as Error)?.message ?? String(r.reason) },
           );
           const batchFmt = resolveFormat();
@@ -342,7 +366,7 @@ Examples:
           category: options.nameCategory,
           room: options.nameRoom,
         });
-        const body = await fetchDeviceStatus(deviceId);
+        const body = annotateStatusPayload(deviceId, await fetchDeviceStatus(deviceId));
         const fetchedAt = new Date().toISOString();
         const fmt = resolveFormat();
 
@@ -678,7 +702,7 @@ Examples:
           if (isJsonMode()) {
             printJson({ dryRun: true, wouldSend });
           } else {
-            console.log(`[dry-run] Would POST devices/${_deviceId}/commands with ${JSON.stringify({ command: _cmd, parameter: _parsedParam, commandType })}`);
+            console.log(`◦ dry-run intercepted for ${_cmd} on ${_deviceId}; see stderr preview for the HTTP request.`);
           }
           return;
         }
@@ -856,6 +880,8 @@ Examples:
             capabilities,
             source,
             suggestedActions: picks,
+            ...(result.catalogNote ? { catalogNote: result.catalogNote } : {}),
+            ...(result.warnings && result.warnings.length > 0 ? { warnings: result.warnings } : {}),
             ...(expandHint ? { expandHint: { command: expandHint.command, flags: expandHint.flags, example: `switchbot devices expand ${deviceId} ${expandHint.command} ${expandHint.flags}` } } : {}),
           });
           return;
@@ -893,8 +919,17 @@ Examples:
           capabilities && 'liveStatus' in capabilities ? capabilities.liveStatus : undefined;
 
         console.log('');
+        if (result.warnings && result.warnings.length > 0) {
+          for (const warning of result.warnings) {
+            console.log(`Warning: ${warning}`);
+          }
+          console.log('');
+        }
         if (!catalog) {
           console.log(`(Type "${typeName}" is not in the built-in catalog — no command reference available.)`);
+          if (result.catalogNote) {
+            console.log(result.catalogNote);
+          }
           if (isPhysical) {
             console.log(`Try 'switchbot devices status ${deviceId}' to see what this device reports.`);
           } else {
@@ -995,6 +1030,7 @@ function renderCatalogEntry(entry: DeviceCatalogEntry): void {
   if (entry.statusFields && entry.statusFields.length > 0) {
     console.log('\nStatus fields (from "devices status"):');
     console.log('  ' + entry.statusFields.join(', '));
+    console.log('  Note: statusFields are advisory; actual fields can vary by firmware and device variant.');
   }
 
   const expandHint = EXPAND_HINTS[entry.type];

src/commands/devices.ts

@@ -6,11 +6,13 @@ import { execSync } from 'node:child_process';
 import { printJson, isJsonMode, exitWithError } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
-import { describeCache, resetListCache } from '../devices/cache.js';
+import { describeCache, resetListCache, loadCache } from '../devices/cache.js';
 import { DAILY_QUOTA, todayUsage } from '../utils/quota.js';
 import { AGENT_BOOTSTRAP_SCHEMA_VERSION } from './agent-bootstrap.js';
 import { CATALOG_SCHEMA_VERSION } from '../devices/catalog.js';
 import { createSwitchBotMcpServer, listRegisteredTools } from './mcp.js';
+import { getReleaseMetadata } from '../version-notes.js';
+import { VERSION as currentVersion } from '../version.js';
 import {
   resolvePolicyPath,
   loadPolicyFile,
@@ -355,10 +357,56 @@ interface AuditRecord {
   kind?: string;
   deviceId?: string;
   command?: string;
-  result?: 'ok' | 'error';
+  result?: 'ok' | 'error' | 'dry-run';
   error?: string;
 }
 
+function checkInventoryConsistency(): Check {
+  const cache = loadCache();
+  if (!cache) {
+    return {
+      name: 'inventory',
+      status: 'ok',
+      detail: "no local inventory cache — run 'switchbot devices list' to enable hub-reference checks",
+    };
+  }
+
+  const dangling = Object.entries(cache.devices)
+    .filter(([, device]) => device.category === 'physical')
+    .filter(([deviceId, device]) => {
+      const hubDeviceId = device.hubDeviceId;
+      return Boolean(
+        hubDeviceId &&
+        hubDeviceId !== '000000000000' &&
+        hubDeviceId !== deviceId &&
+        !cache.devices[hubDeviceId],
+      );
+    })
+    .map(([deviceId, device]) => ({
+      deviceId,
+      deviceName: device.name,
+      hubDeviceId: device.hubDeviceId!,
+      deviceType: device.type,
+    }));
+
+  if (dangling.length === 0) {
+    return {
+      name: 'inventory',
+      status: 'ok',
+      detail: `inventory graph consistent across ${Object.keys(cache.devices).length} cached devices`,
+    };
+  }
+
+  return {
+    name: 'inventory',
+    status: 'warn',
+    detail: {
+      message: `${dangling.length} device(s) reference a hubDeviceId that is not present in the current inventory`,
+      dangling: dangling.slice(0, 10),
+    },
+  };
+}
+
 function checkAudit(): Check {
   // P9: surface recent command failures so agents / ops can spot problems
   // before they page. When --audit-log was never enabled, the file won't
@@ -853,6 +901,27 @@ function checkMcp(): Check {
   }
 }
 
+function checkReleaseNotes(): Check {
+  const meta = getReleaseMetadata(currentVersion);
+  if (!meta || !meta.breaking) {
+    return {
+      name: 'release-notes',
+      status: 'ok',
+      detail: { version: currentVersion, message: 'no known breaking-change notice for the current release' },
+    };
+  }
+  return {
+    name: 'release-notes',
+    status: 'warn',
+    detail: {
+      version: currentVersion,
+      breaking: true,
+      message: meta.summary,
+      hint: 'If you have scripts pinned to 3.2.x JSON output, update them before rolling this release wider.',
+    },
+  };
+}
+
 interface CheckDef {
   name: string;
   description: string;
@@ -871,6 +940,7 @@ const CHECK_REGISTRY: CheckDef[] = [
   { name: 'profiles', description: 'profile definitions valid', run: () => checkProfiles() },
   { name: 'catalog', description: 'catalog loads', run: () => checkCatalog() },
   { name: 'catalog-schema', description: 'catalog vs agent-bootstrap version aligned', run: () => checkCatalogSchema() },
+  { name: 'inventory', description: 'cached inventory graph consistency (hubDeviceId references)', run: () => checkInventoryConsistency() },
   { name: 'cache', description: 'device cache state', run: () => checkCache() },
   { name: 'quota', description: 'API quota headroom', run: () => checkQuotaFile() },
   { name: 'clock', description: 'system clock skew', run: () => checkClockSkew() },
@@ -880,6 +950,7 @@ const CHECK_REGISTRY: CheckDef[] = [
     run: ({ probe }) => (probe ? checkMqttProbe() : checkMqtt()),
   },
   { name: 'mcp', description: 'MCP server instantiable + tool count', run: () => checkMcp() },
+  { name: 'release-notes', description: 'current release breaking-change notice', run: () => checkReleaseNotes() },
   { name: 'policy', description: 'policy.yaml present + schema-valid (if configured)', run: () => checkPolicy() },
   { name: 'audit', description: 'recent command errors (last 24h)', run: () => checkAudit() },
   { name: 'daemon', description: 'daemon state file + runtime status', run: () => checkDaemon() },

src/commands/doctor.ts

@@ -74,6 +74,14 @@ interface EventRecord {
   matched: boolean;
 }
 
+function emitJsonStreamRecord<T extends { schemaVersion: string }>(record: T): void {
+  const { schemaVersion, ...rest } = record as T & Record<string, unknown>;
+  printJson({
+    payloadVersion: schemaVersion,
+    ...rest,
+  });
+}
+
 function matchFilterDetail(
   body: unknown,
   clauses: FilterClause[] | null,
@@ -262,7 +270,7 @@ Examples:
               if (!ev.matched) return;
               matchedCount++;
               if (isJsonMode()) {
-                printJson(ev);
+                emitJsonStreamRecord(ev);
               } else {
                 const when = new Date(ev.t).toLocaleTimeString();
                 console.log(`[${when}] ${ev.remote} ${ev.path} ${JSON.stringify(ev.body)}`);
@@ -457,7 +465,7 @@ Examples:
         // connected" even when mqtt-tail exits before the broker connects.
         if (isJsonMode()) {
           const sessionStartAt = new Date().toISOString();
-          printJson({
+          emitJsonStreamRecord({
             schemaVersion: EVENTS_SCHEMA_VERSION,
             source: 'mqtt',
             kind: 'control',
@@ -518,7 +526,7 @@ Examples:
               payload: parsed,
             };
             if (isJsonMode()) {
-              printJson(record);
+              emitJsonStreamRecord(record);
             } else {
               console.log(JSON.stringify(record));
             }
@@ -554,7 +562,7 @@ Examples:
           // Control events always go to stdout as JSONL so consumers that
           // filter real events by presence of `payload` can skip them.
           if (isJsonMode()) {
-            printJson(ctl);
+            emitJsonStreamRecord(ctl);
           } else {
             console.log(JSON.stringify(ctl));
           }

src/commands/events.ts

@@ -1,10 +1,10 @@
 import { Command } from 'commander';
-import { intArg, stringArg } from '../utils/arg-parsers.js';
+import { intArg, stringArg, enumArg } from '../utils/arg-parsers.js';
 import { handleError, isJsonMode, printJson, UsageError, exitWithError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
-import { resolveDeviceId } from '../utils/name-resolver.js';
+import { resolveDeviceId, ALL_STRATEGIES, type NameResolveStrategy } from '../utils/name-resolver.js';
 import { DryRunSignal } from '../api/client.js';
 import {
   buildAcSetAll,
@@ -22,6 +22,10 @@ export function registerExpandCommand(devices: Command): void {
     .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'] as const))
+    .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'))
@@ -65,6 +69,10 @@ Examples:
       commandArg: string | undefined,
       options: {
         name?: string;
+        nameStrategy?: string;
+        nameType?: string;
+        nameCategory?: 'physical' | 'ir';
+        nameRoom?: string;
         temp?: string; mode?: string; fan?: string; power?: string;
         position?: string; direction?: string; angle?: string;
         channel?: string; yes?: boolean;
@@ -82,7 +90,12 @@ Examples:
           effectiveDeviceIdArg = undefined;
         }
 
-        deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+        deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name, {
+          strategy: (options.nameStrategy as NameResolveStrategy | undefined) ?? 'require-unique',
+          type: options.nameType,
+          category: options.nameCategory,
+          room: options.nameRoom,
+        });
         if (!effectiveCommand) throw new UsageError('A command argument is required (setAll, setPosition, setMode).');
 
         command = effectiveCommand;