@switchbot/openapi-cli 2.6.4 → 2.7.2

package/dist/commands/watch.js

@@ -1,10 +1,11 @@
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitStreamHeader } from '../utils/output.js';
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
 import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
+import { resolveFieldList, listAllCanonical } from '../schema/field-aliases.js';
 const DEFAULT_INTERVAL_MS = 30_000;
 const MIN_INTERVAL_MS = 1_000;
 function diff(prev, next, fields) {
@@ -101,7 +102,15 @@ Examples:
                 maxTicks = Math.floor(n);
             }
             const forMs = options.for ? parseDurationToMs(options.for) : null;
-            const fields = getFields() ?? null;
+            const rawFields = getFields() ?? null;
+            // Resolve aliases upfront against the static canonical registry.
+            // Validating here lets UsageError exit the command before any
+            // polling starts, and keeps mid-loop error handling free of
+            // "misuse" concerns. Unknown fields that are not registered as
+            // aliases but happen to match an API key pass through unchanged.
+            const fields = rawFields
+                ? resolveFieldList(rawFields, listAllCanonical())
+                : null;
             const ac = new AbortController();
             const onSig = () => ac.abort();
             process.on('SIGINT', onSig);
@@ -109,6 +118,10 @@ Examples:
             const forTimer = forMs !== null && forMs > 0
                 ? setTimeout(() => ac.abort(), forMs)
                 : null;
+            // P7: streaming JSON contract — first line under --json is the
+            // stream header so consumers can route by eventKind/cadence.
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'tick', cadence: 'poll' });
             try {
                 const prev = new Map();
                 const client = createClient();

package/dist/devices/catalog.js

@@ -7,14 +7,99 @@
  *   - CommandSpec.idempotent: repeat-safe — calling it N times ends in the
  *     same state as calling it once (turnOn, setBrightness 50). Agents can
  *     retry these freely. Counter-examples: toggle, press, volumeAdd.
- *   - CommandSpec.destructive: causes a real-world effect that is hard or
- *     unsafe to reverse (unlock, garage open, deleteKey). UIs and agents
- *     should require explicit confirmation before issuing these.
+ *   - CommandSpec.safetyTier: explicit action safety classification. See
+ *     SafetyTier for the 5-tier enum. Built-in entries set this on the
+ *     destructive tier; other tiers are derived (see deriveSafetyTier).
+ *   - CommandSpec.destructive (deprecated, v3.0 removal): legacy boolean
+ *     that maps to safetyTier === 'destructive'. Still accepted in
+ *     ~/.switchbot/catalog.json overlays and derived into safetyTier.
  *   - DeviceCatalogEntry.role: functional grouping for filter/search
  *     ("all lighting", "all security"). Does not affect API behavior.
  *   - DeviceCatalogEntry.readOnly: the device has no control commands; it
  *     can only be queried via 'devices status'.
  */
+/**
+ * Catalog shape version. Bump when any of the exported interfaces
+ * (CommandSpec / DeviceCatalogEntry / SafetyTier) gain/lose/rename a
+ * load-bearing field. The agent-bootstrap payload's schemaVersion must
+ * stay pinned to this value; `doctor` fails the `catalog-schema` check
+ * when they drift.
+ */
+export const CATALOG_SCHEMA_VERSION = '1.0';
+/**
+ * Human-readable descriptions for common status fields. Populated from
+ * the SwitchBot API v1.1 docs. Used by deriveStatusQueries() so every
+ * query has a meaningful description even when the entry itself only
+ * declares the field name.
+ */
+const STATUS_FIELD_DESCRIPTIONS = {
+    power: 'Power state (on/off)',
+    battery: 'Battery percentage (0-100)',
+    version: 'Firmware version string',
+    temperature: 'Ambient temperature (°C)',
+    humidity: 'Ambient humidity (% RH)',
+    CO2: 'CO2 concentration (ppm)',
+    brightness: 'Current brightness (0-100)',
+    color: 'Current RGB color (r:g:b)',
+    colorTemperature: 'Color temperature in Kelvin',
+    mode: 'Operating mode',
+    deviceMode: 'Hardware mode (Bot-specific)',
+    lockState: 'Lock state (locked/unlocked)',
+    doorState: 'Door contact state (open/closed)',
+    calibrate: 'Calibration status',
+    moving: 'Motion in progress (boolean)',
+    slidePosition: 'Slide position (0-100)',
+    group: 'Multi-device group membership',
+    direction: 'Tilt direction',
+    voltage: 'Line voltage',
+    electricCurrent: 'Instantaneous current draw',
+    electricityOfDay: 'kWh consumed today',
+    usedElectricity: 'Cumulative kWh',
+    useTime: 'Total runtime (seconds)',
+    weight: 'Load / weight reading',
+    switchStatus: 'Relay state (integer encoded)',
+    switch1Status: 'Channel 1 relay state',
+    switch2Status: 'Channel 2 relay state',
+    workingStatus: 'Device working status (vacuum/purifier)',
+    onlineStatus: 'Online / offline (string)',
+    online: 'Online / offline (boolean or int)',
+    taskType: 'Current task identifier',
+    nightStatus: 'Night-mode status',
+    oscillation: 'Horizontal oscillation on/off',
+    verticalOscillation: 'Vertical oscillation on/off',
+    chargingStatus: 'Charging (boolean)',
+    fanSpeed: 'Current fan speed level',
+    nebulizationEfficiency: 'Humidifier mist level',
+    childLock: 'Child-lock engaged',
+    sound: 'Beep / audio feedback enabled',
+    lackWater: 'Water tank low (boolean)',
+    filterElement: 'Filter life remaining',
+    auto: 'Auto mode enabled',
+    targetTemperature: 'Thermostat target temperature',
+    moveDetected: 'Motion detected (boolean)',
+    openState: 'Contact sensor open/closed',
+    status: 'Device-specific status word',
+    lightLevel: 'Ambient light level',
+};
+/**
+ * P11: derive the read-only query list for an entry. If the entry has
+ * explicit `statusQueries`, return them as-is; otherwise synthesize one
+ * ReadOnlyQuerySpec per `statusFields` entry, all keyed to the `status`
+ * endpoint. IR-category entries have no status channel so return [].
+ */
+export function deriveStatusQueries(entry) {
+    if (entry.statusQueries && entry.statusQueries.length > 0)
+        return entry.statusQueries;
+    if (entry.category === 'ir')
+        return [];
+    const fields = entry.statusFields ?? [];
+    return fields.map((f) => ({
+        field: f,
+        description: STATUS_FIELD_DESCRIPTIONS[f] ?? `${f} (see API docs)`,
+        endpoint: 'status',
+        safetyTier: 'read',
+    }));
+}
 // ---- Command fragments (reused across entries) -------------------------
 const onOff = [
     { command: 'turnOn', parameter: '—', description: 'Power on', idempotent: true },
@@ -64,7 +149,7 @@ export const DEVICE_CATALOG = [
         aliases: ['Smart Lock Pro'],
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
             { command: 'deadbolt', parameter: '—', description: 'Pro only: engage deadbolt', idempotent: true },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
@@ -76,7 +161,7 @@ export const DEVICE_CATALOG = [
         role: 'security',
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
     },
@@ -87,7 +172,7 @@ export const DEVICE_CATALOG = [
         role: 'security',
         commands: [
             { command: 'lock', parameter: '—', description: 'Lock the door', idempotent: true },
-            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, destructive: true, destructiveReason: 'Physically unlocks the door — anyone nearby can open it.' },
+            { command: 'unlock', parameter: '—', description: 'Unlock the door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Physically unlocks the door — anyone nearby can open it.' },
             { command: 'deadbolt', parameter: '—', description: 'Engage deadbolt', idempotent: true },
         ],
         statusFields: ['battery', 'version', 'lockState', 'doorState', 'calibrate'],
@@ -306,8 +391,8 @@ export const DEVICE_CATALOG = [
         description: 'Cloud-connected garage door controller; turnOn opens and turnOff closes the door.',
         role: 'security',
         commands: [
-            { command: 'turnOn', parameter: '—', description: 'Open the garage door', idempotent: true, destructive: true, destructiveReason: 'Opens the garage door — anyone nearby can enter the space.' },
-            { command: 'turnOff', parameter: '—', description: 'Close the garage door', idempotent: true, destructive: true, destructiveReason: 'Closes the garage door — verify no person or obstacle is in the way.' },
+            { command: 'turnOn', parameter: '—', description: 'Open the garage door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Opens the garage door — anyone nearby can enter the space.' },
+            { command: 'turnOff', parameter: '—', description: 'Close the garage door', idempotent: true, safetyTier: 'destructive', safetyReason: 'Closes the garage door — verify no person or obstacle is in the way.' },
         ],
         statusFields: ['switchStatus', 'version', 'online'],
     },
@@ -329,8 +414,8 @@ export const DEVICE_CATALOG = [
         role: 'security',
         aliases: ['Keypad Touch'],
         commands: [
-            { command: 'createKey', parameter: '\'{"name":"...","type":"permanent|timeLimit|disposable|urgent","password":"6-12 digits","startTime":<s>,"endTime":<s>}\'', description: 'Create a passcode (async; result via webhook)', idempotent: false, destructive: true, destructiveReason: 'Provisions a new access credential — anyone with this passcode can unlock the door.' },
-            { command: 'deleteKey', parameter: '\'{"id":<passcode_id>}\'', description: 'Delete a passcode (async; result via webhook)', idempotent: true, destructive: true, destructiveReason: 'Permanently removes a passcode — the holder immediately loses door access.' },
+            { command: 'createKey', parameter: '\'{"name":"...","type":"permanent|timeLimit|disposable|urgent","password":"6-12 digits","startTime":<s>,"endTime":<s>}\'', description: 'Create a passcode (async; result via webhook)', idempotent: false, safetyTier: 'destructive', safetyReason: 'Provisions a new access credential — anyone with this passcode can unlock the door.' },
+            { command: 'deleteKey', parameter: '\'{"id":<passcode_id>}\'', description: 'Delete a passcode (async; result via webhook)', idempotent: true, safetyTier: 'destructive', safetyReason: 'Permanently removes a passcode — the holder immediately loses door access.' },
         ],
         statusFields: ['version'],
     },
@@ -538,13 +623,41 @@ export function findCatalogEntry(query) {
         return matches[0];
     return matches;
 }
+/**
+ * Derive the safety tier for a catalog command, honouring an explicit
+ * `safetyTier` when present and falling back to heuristic inference.
+ *
+ * The inference order is:
+ *   1. Explicit `spec.safetyTier`.
+ *   2. Legacy `spec.destructive: true` → `'destructive'` (overlay compat).
+ *   3. IR context (customize command OR entry.category === 'ir')
+ *      → `'ir-fire-forget'`.
+ *   4. Default → `'mutation'`.
+ */
+export function deriveSafetyTier(spec, entry) {
+    if (spec.safetyTier)
+        return spec.safetyTier;
+    if (spec.destructive)
+        return 'destructive';
+    if (spec.commandType === 'customize')
+        return 'ir-fire-forget';
+    if (entry?.category === 'ir')
+        return 'ir-fire-forget';
+    return 'mutation';
+}
+/** Read the safety reason for a command, with fallback to the legacy field. */
+export function getCommandSafetyReason(spec) {
+    return spec.safetyReason ?? spec.destructiveReason ?? null;
+}
 /**
  * Pick up to 3 non-destructive, idempotent commands an agent can safely invoke
  * to explore or exercise a device. Used by `devices describe --json` to hint
  * at concrete next steps.
  */
 export function suggestedActions(entry) {
-    const safe = entry.commands.filter((c) => c.idempotent === true && !c.destructive && c.commandType !== 'customize');
+    const safe = entry.commands.filter((c) => c.idempotent === true &&
+        deriveSafetyTier(c, entry) !== 'destructive' &&
+        c.commandType !== 'customize');
     const picks = [];
     const seen = new Set();
     for (const c of safe) {

package/dist/devices/resources.js

@@ -0,0 +1,270 @@
+/**
+ * Declarative metadata for non-device resources exposed by the SwitchBot API:
+ * scenes, webhooks, and keypad credentials ("keys").
+ *
+ * Consumed by `capabilities --json` and `schema export` so AI agents can
+ * discover these surfaces the same way they discover device commands.
+ *
+ * Scope:
+ * - Descriptive metadata only (no runtime execution — CLI/MCP handlers stay
+ *   source-of-truth for behavior).
+ * - Webhook event list is derived from the device catalog and is advisory —
+ *   not every SwitchBot device actually pushes every listed event; refer to
+ *   the SwitchBot webhook docs for authoritative shapes.
+ */
+const COMMON_WEBHOOK_FIELDS = [
+    { name: 'deviceType', type: 'string', description: 'SwitchBot device type string', example: 'WoMeter' },
+    { name: 'deviceMac', type: 'string', description: 'Bluetooth MAC address (uppercase, colon-separated)', example: 'AA:BB:CC:11:22:33' },
+    { name: 'timeOfSample', type: 'timestamp', description: 'Millisecond Unix timestamp when the sample was taken', example: 1700000000000 },
+];
+export const RESOURCE_CATALOG = {
+    scenes: {
+        description: 'Manual scenes (IFTTT-style rules) authored in the SwitchBot app. Execution is fire-and-forget from the cloud — side-effects happen on the user\'s devices.',
+        operations: [
+            {
+                verb: 'list',
+                method: 'GET',
+                endpoint: '/v1.1/scenes',
+                params: [],
+                safetyTier: 'read',
+            },
+            {
+                verb: 'execute',
+                method: 'POST',
+                endpoint: '/v1.1/scenes/{sceneId}/execute',
+                params: [{ name: 'sceneId', required: true, type: 'string' }],
+                safetyTier: 'mutation',
+            },
+            {
+                verb: 'describe',
+                method: 'GET',
+                endpoint: '/v1.1/scenes/{sceneId}',
+                params: [{ name: 'sceneId', required: true, type: 'string' }],
+                safetyTier: 'read',
+            },
+        ],
+    },
+    webhooks: {
+        endpoints: [
+            {
+                verb: 'setup',
+                method: 'POST',
+                path: '/v1.1/webhook/setupWebhook',
+                safetyTier: 'mutation',
+                requiredParams: ['url'],
+            },
+            {
+                verb: 'query',
+                method: 'POST',
+                path: '/v1.1/webhook/queryWebhook',
+                safetyTier: 'read',
+                requiredParams: ['action'],
+            },
+            {
+                verb: 'update',
+                method: 'POST',
+                path: '/v1.1/webhook/updateWebhook',
+                safetyTier: 'mutation',
+                requiredParams: ['url', 'enable'],
+            },
+            {
+                verb: 'delete',
+                method: 'POST',
+                path: '/v1.1/webhook/deleteWebhook',
+                safetyTier: 'destructive',
+                requiredParams: ['url'],
+            },
+        ],
+        events: [
+            {
+                eventType: 'WoMeter',
+                devicePattern: 'Meter / Meter Plus / Indoor-Outdoor Meter',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius', example: 22.5 },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)', example: 45 },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)', example: 88 },
+                ],
+            },
+            {
+                eventType: 'WoCO2Sensor',
+                devicePattern: 'CO2 Monitor',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'CO2', type: 'number', description: 'CO2 concentration in ppm', example: 520 },
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
+                ],
+            },
+            {
+                eventType: 'WoPresence',
+                devicePattern: 'Motion Sensor / Video Doorbell motion',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'detectionState', type: 'string', description: 'Detection result word', example: 'DETECTED' },
+                ],
+            },
+            {
+                eventType: 'WoContact',
+                devicePattern: 'Contact Sensor',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'openState', type: 'string', description: 'Door/window state', example: 'open' },
+                    { name: 'moveDetected', type: 'boolean', description: 'Motion detected during this sample' },
+                ],
+            },
+            {
+                eventType: 'WoLock',
+                devicePattern: 'Smart Lock / Smart Lock Lite / Smart Lock Pro',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'lockState', type: 'string', description: 'Lock state: locked, unlocked, jammed', example: 'locked' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoPlug',
+                devicePattern: 'Plug Mini / Plug / Relay Switch',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)', example: 'on' },
+                    { name: 'voltage', type: 'number', description: 'Instantaneous voltage (V)' },
+                    { name: 'electricCurrent', type: 'number', description: 'Instantaneous current (A)' },
+                ],
+            },
+            {
+                eventType: 'WoBot',
+                devicePattern: 'Bot',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoCurtain',
+                devicePattern: 'Curtain / Blind Tilt / Roller Shade',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'slidePosition', type: 'number', description: 'Current slide position (0–100)' },
+                    { name: 'calibrate', type: 'boolean', description: 'True if device is calibrated' },
+                ],
+            },
+            {
+                eventType: 'WoDoorbell',
+                devicePattern: 'Video Doorbell button press',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'buttonName', type: 'string', description: 'Identifier of the pressed button' },
+                    { name: 'pressedAt', type: 'timestamp', description: 'Press timestamp in milliseconds' },
+                ],
+            },
+            {
+                eventType: 'WoKeypad',
+                devicePattern: 'Keypad scan / createKey result / deleteKey result',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'eventType', type: 'string', description: 'Sub-event (createKey / deleteKey / invalidCode)' },
+                    { name: 'commandId', type: 'string', description: 'Correlation id returned by the original command' },
+                    { name: 'result', type: 'string', description: 'Outcome (success / failed / timeout)' },
+                ],
+            },
+            {
+                eventType: 'WoColorBulb',
+                devicePattern: 'Color Bulb',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
+                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
+                    { name: 'colorTemperature', type: 'number', description: 'Color temperature in Kelvin' },
+                ],
+            },
+            {
+                eventType: 'WoStrip',
+                devicePattern: 'Strip Light',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
+                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
+                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
+                ],
+            },
+            {
+                eventType: 'WoSweeper',
+                devicePattern: 'Robot Vacuum',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'workingStatus', type: 'string', description: 'Cleaning state' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                    { name: 'taskType', type: 'string', description: 'Current task (standby / clean / charge)' },
+                ],
+            },
+            {
+                eventType: 'WoWaterLeakDetect',
+                devicePattern: 'Water Leak Detector',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'waterLeakDetect', type: 'number', description: 'Leak flag (0 = dry, 1 = leak detected)' },
+                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
+                ],
+            },
+            {
+                eventType: 'WoHub',
+                devicePattern: 'Hub 2 / Hub 3 (ambient sensors)',
+                fields: [
+                    ...COMMON_WEBHOOK_FIELDS,
+                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
+                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
+                    { name: 'lightLevel', type: 'number', description: 'Illuminance level' },
+                ],
+            },
+        ],
+        constraints: {
+            maxUrlLength: 2048,
+            maxWebhooksPerAccount: 1,
+        },
+    },
+    keys: [
+        {
+            keyType: 'permanent',
+            description: 'Passcode that never expires — valid until manually deleted.',
+            requiredParams: ['name', 'password'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'timeLimit',
+            description: 'Passcode valid only between startTime and endTime (Unix seconds).',
+            requiredParams: ['name', 'password', 'startTime', 'endTime'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'disposable',
+            description: 'Passcode that can be used once and then auto-expires.',
+            requiredParams: ['name', 'password'],
+            optionalParams: ['startTime', 'endTime'],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+        {
+            keyType: 'urgent',
+            description: 'Emergency passcode (typically tied to panic / audit workflow).',
+            requiredParams: ['name', 'password'],
+            optionalParams: [],
+            supportedDevices: ['Keypad', 'Keypad Touch'],
+            safetyTier: 'destructive',
+        },
+    ],
+};
+/** Convenience: return the list of known webhook event types. */
+export function listWebhookEventTypes() {
+    return RESOURCE_CATALOG.webhooks.events.map((e) => e.eventType);
+}
+/** Convenience: return the list of supported keypad key types. */
+export function listKeyTypes() {
+    return RESOURCE_CATALOG.keys.map((k) => k.keyType);
+}

package/dist/index.js

@@ -4,7 +4,9 @@ import { createRequire } from 'node:module';
 import chalk from 'chalk';
 import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
 import { parseDurationToMs } from './utils/flags.js';
-import { emitJsonError, isJsonMode } from './utils/output.js';
+import { emitJsonError, isJsonMode, printJson } from './utils/output.js';
+import { commandToJson, resolveTargetCommand } from './utils/help-json.js';
+import { PRODUCT_TAGLINE } from './commands/identity.js';
 import { registerConfigCommand } from './commands/config.js';
 import { registerDevicesCommand } from './commands/devices.js';
 import { registerScenesCommand } from './commands/scenes.js';
@@ -54,7 +56,7 @@ const cacheModeArg = (value) => {
 };
 program
     .name('switchbot')
-    .description('Command-line tool for SwitchBot API v1.1')
+    .description(PRODUCT_TAGLINE)
     .version(pkgVersion)
     .option('--no-color', 'Disable ANSI colors in output')
     .option('--json', 'Output raw JSON response (disables tables; useful for pipes/scripts)')
@@ -150,6 +152,10 @@ function enableSuggestions(cmd) {
     cmd.commands.forEach(enableSuggestions);
 }
 enableSuggestions(program);
+// In JSON mode suppress the plain-text help output so we can emit structured JSON instead.
+if (isJsonMode()) {
+    program.configureOutput({ writeOut: () => { } });
+}
 try {
     await program.parseAsync();
 }
@@ -158,7 +164,14 @@ catch (err) {
     // argParser on a subcommand option) don't always hit the root exitOverride.
     // Mirror the root mapping so all usage errors surface as exit 2.
     if (err instanceof CommanderError) {
-        if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+        if (err.code === 'commander.helpDisplayed') {
+            if (isJsonMode()) {
+                const target = resolveTargetCommand(program, process.argv.slice(2));
+                printJson(commandToJson(target, { includeIdentity: target === program }));
+            }
+            process.exit(0);
+        }
+        if (err.code === 'commander.version') {
             process.exit(0);
         }
         if (isJsonMode()) {

package/dist/lib/devices.js

@@ -1,6 +1,6 @@
 import { createClient } from '../api/client.js';
 import { idempotencyCache } from './idempotency.js';
-import { findCatalogEntry, suggestedActions, getEffectiveCatalog, } from '../devices/catalog.js';
+import { findCatalogEntry, suggestedActions, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice, updateCacheFromDeviceList, loadCache, isListCacheFresh, getCachedStatus, setCachedStatus, } from '../devices/cache.js';
 import { getCacheMode } from '../utils/flags.js';
 import { writeAudit } from '../utils/audit.js';
@@ -216,9 +216,11 @@ export function isDestructiveCommand(deviceType, cmd, commandType) {
     if (!match || Array.isArray(match))
         return false;
     const spec = match.commands.find((c) => c.command === cmd);
-    return Boolean(spec?.destructive);
+    if (!spec)
+        return false;
+    return deriveSafetyTier(spec, match) === 'destructive';
 }
-/** Return the destructiveReason for a command, or null if not destructive / not found. */
+/** Return the safetyReason for a command, or null if not destructive / not found. */
 export function getDestructiveReason(deviceType, cmd, commandType) {
     if (commandType === 'customize')
         return null;
@@ -228,7 +230,7 @@ export function getDestructiveReason(deviceType, cmd, commandType) {
     if (!match || Array.isArray(match))
         return null;
     const spec = match.commands.find((c) => c.command === cmd);
-    return spec?.destructiveReason ?? null;
+    return spec ? getCommandSafetyReason(spec) : null;
 }
 /**
  * Describe a device by id: metadata + catalog entry (if known) +
@@ -264,7 +266,16 @@ export async function describeDevice(deviceId, options = {}, client) {
         ? {
             role: catalogEntry.role ?? null,
             readOnly: catalogEntry.readOnly ?? false,
-            commands: catalogEntry.commands,
+            commands: catalogEntry.commands.map((c) => {
+                const tier = deriveSafetyTier(c, catalogEntry);
+                const reason = getCommandSafetyReason(c);
+                return {
+                    ...c,
+                    safetyTier: tier,
+                    destructive: tier === 'destructive',
+                    ...(reason ? { safetyReason: reason } : {}),
+                };
+            }),
             statusFields: catalogEntry.statusFields ?? [],
             ...(liveStatus !== undefined ? { liveStatus } : {}),
         }