@switchbot/openapi-cli 2.6.3 → 2.7.2

package/dist/index.js

@@ -4,6 +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, 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';
@@ -28,6 +31,11 @@ if (process.argv.includes('--no-color') || Boolean(process.env.NO_COLOR)) {
     chalk.level = 0;
 }
 const program = new Command();
+if (isJsonMode()) {
+    // In --json mode, commander writes plain-text usage errors by default.
+    // Silence that channel and emit a single structured error in the catch block.
+    program.configureOutput({ writeErr: () => { } });
+}
 // Top-level subcommand names. Used by stringArg to produce clearer errors when
 // a value is omitted and the next argv token turns out to be a subcommand name.
 const TOP_LEVEL_COMMANDS = [
@@ -48,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)')
@@ -130,10 +138,7 @@ Docs: https://github.com/OpenWonderLabs/SwitchBotAPI
 // per-command: subcommand errors won't bubble to the root override, so walk
 // every registered command and apply the same handler.
 const usageExitHandler = (err) => {
-    if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
-        process.exit(0);
-    }
-    process.exit(2);
+    throw err;
 };
 function applyExitOverride(cmd) {
     cmd.exitOverride(usageExitHandler);
@@ -147,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();
 }
@@ -155,9 +164,19 @@ 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()) {
+            emitJsonError({ code: 2, kind: 'usage', message: err.message });
+        }
         process.exit(2);
     }
     throw err;

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';
@@ -151,8 +151,12 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     if (!match || Array.isArray(match))
         return { ok: true };
     const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
-    if (builtinCommands.length === 0)
-        return { ok: true };
+    if (match.readOnly || builtinCommands.length === 0) {
+        return {
+            ok: false,
+            error: new CommandValidationError(`${cached.name} (${cached.type}) is a read-only sensor — it has no control commands.`, 'read-only-device', `Use 'switchbot devices status ${deviceId}' to read this device instead.`),
+        };
+    }
     let spec = builtinCommands.find((c) => c.command === cmd);
     let caseNormalizedFrom;
     let normalizedCmd = cmd;
@@ -212,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;
@@ -224,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) +
@@ -260,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 } : {}),
         }

package/dist/schema/field-aliases.js

@@ -0,0 +1,131 @@
+import { UsageError } from '../utils/output.js';
+/**
+ * User-facing aliases for canonical field names.
+ *
+ * Keys are canonical names (matching API response keys and CLI/schema output);
+ * values are lowercase alternatives a user may type for `--fields` or `--filter`.
+ *
+ * Conflict rules (do not add an alias that violates these — tests will fail):
+ * - `temp` is exclusive to `temperature` (NOT `colorTemperature`, `targetTemperature`).
+ * - `motion` is exclusive to `moveDetected`; `moving` uses `active` instead.
+ * - `mode` is exclusive to top-level `mode` (preset); device-specific modes go through `deviceMode`.
+ * - Reserved / too-generic words never appear as aliases: `auto`, `status`, `state`,
+ *   `switch`, `type`, `on`, `off`.
+ * - Device-type words are never aliases: `lock`, `fan`.
+ */
+export const FIELD_ALIASES = {
+    // Identification (shared with list/filter)
+    deviceId: ['id'],
+    deviceName: ['name'],
+    deviceType: ['type'],
+    controlType: ['control'],
+    roomName: ['room'],
+    roomID: ['roomid'],
+    familyName: ['family'],
+    hubDeviceId: ['hub'],
+    enableCloudService: ['cloud'],
+    alias: ['alias'],
+    // Phase 1 — common status fields
+    battery: ['batt', 'bat'],
+    temperature: ['temp', 'ambient'],
+    colorTemperature: ['kelvin', 'colortemp'],
+    humidity: ['humid', 'rh'],
+    brightness: ['bright', 'bri'],
+    fanSpeed: ['speed'],
+    position: ['pos'],
+    moveDetected: ['motion'],
+    openState: ['open'],
+    doorState: ['door'],
+    CO2: ['co2'],
+    power: ['enabled'],
+    mode: ['preset'],
+    // Phase 2 — niche device fields
+    childLock: ['safe', 'childlock'],
+    targetTemperature: ['setpoint', 'target'],
+    electricCurrent: ['current', 'amps'],
+    voltage: ['volts'],
+    usedElectricity: ['energy', 'kwh'],
+    electricityOfDay: ['daily', 'today'],
+    weight: ['load'],
+    version: ['firmware', 'fw'],
+    lightLevel: ['light', 'lux'],
+    oscillation: ['swing', 'osc'],
+    verticalOscillation: ['vswing'],
+    nightStatus: ['night'],
+    chargingStatus: ['charging', 'charge'],
+    switch1Status: ['ch1', 'channel1'],
+    switch2Status: ['ch2', 'channel2'],
+    taskType: ['task'],
+    moving: ['active'],
+    onlineStatus: ['online_status'],
+    workingStatus: ['working'],
+    // Phase 3 — catalog statusFields coverage
+    group: ['cluster'],
+    calibrate: ['calibration', 'calib'],
+    direction: ['tilt'],
+    deviceMode: ['devmode'],
+    nebulizationEfficiency: ['mist', 'spray'],
+    sound: ['audio'],
+    lackWater: ['tank', 'water-low'],
+    filterElement: ['filter'],
+    color: ['rgb', 'hex'],
+    useTime: ['runtime', 'uptime'],
+    switchStatus: ['relay'],
+    lockState: ['locked'],
+    slidePosition: ['slide'],
+    // Phase 4 — ultra-niche sensor + webhook fields (~98% coverage target)
+    waterLeakDetect: ['leak', 'water'],
+    pressure: ['press', 'pa'],
+    moveCount: ['movecnt'],
+    errorCode: ['err'],
+    buttonName: ['btn', 'button'],
+    pressedAt: ['pressed'],
+    deviceMac: ['mac'],
+    detectionState: ['detected', 'detect'],
+};
+/**
+ * Resolve a user-typed field name to its canonical form against an allowed list.
+ *
+ * Matching is case-insensitive and trims surrounding whitespace. Direct matches
+ * win over alias matches. Throws UsageError if the input is empty or does not
+ * match any canonical / alias in the allowed list.
+ */
+export function resolveField(input, allowedCanonical) {
+    const normalized = input.trim().toLowerCase();
+    if (!normalized) {
+        throw new UsageError('Field name cannot be empty.');
+    }
+    for (const canonical of allowedCanonical) {
+        if (canonical.toLowerCase() === normalized)
+            return canonical;
+    }
+    for (const canonical of allowedCanonical) {
+        const aliases = FIELD_ALIASES[canonical] ?? [];
+        if (aliases.some((a) => a.toLowerCase() === normalized))
+            return canonical;
+    }
+    throw new UsageError(`Unknown field "${input}". Supported: ${listSupportedFieldInputs(allowedCanonical).join(', ')}`);
+}
+/**
+ * Resolve every field in a list. Preserves order and the original UsageError
+ * from resolveField() on the first unknown input.
+ */
+export function resolveFieldList(inputs, allowedCanonical) {
+    return inputs.map((f) => resolveField(f, allowedCanonical));
+}
+export function listSupportedFieldInputs(allowedCanonical) {
+    const out = new Set();
+    for (const canonical of allowedCanonical) {
+        out.add(canonical);
+        for (const alias of FIELD_ALIASES[canonical] ?? [])
+            out.add(alias);
+    }
+    return [...out];
+}
+/**
+ * All canonical keys known to the alias registry. Use when no dynamic
+ * canonical list is available (e.g. `watch` before the first poll response).
+ */
+export function listAllCanonical() {
+    return Object.keys(FIELD_ALIASES);
+}

package/dist/utils/filter.js

@@ -20,7 +20,7 @@ export class FilterSyntaxError extends Error {
  * {type,name,category,room}; `devices batch` uses {type,family,room,category};
  * `events tail` uses {deviceId,type}.
  */
-export function parseFilterExpr(expr, allowedKeys) {
+export function parseFilterExpr(expr, allowedKeys, options) {
     if (!expr)
         return [];
     const parts = expr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
@@ -72,10 +72,23 @@ export function parseFilterExpr(expr, allowedKeys) {
         if (!raw) {
             throw new FilterSyntaxError(`Empty value for filter clause "${part}"`);
         }
-        if (!allowedKeys.includes(key)) {
-            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${allowedKeys.join(', ')}`);
+        let resolvedKey = key;
+        if (options?.resolveKey) {
+            try {
+                resolvedKey = options.resolveKey(key);
+            }
+            catch (err) {
+                if (err instanceof Error) {
+                    throw new FilterSyntaxError(err.message);
+                }
+                throw err;
+            }
+        }
+        if (!allowedKeys.includes(resolvedKey)) {
+            const printableKeys = options?.supportedKeys ?? allowedKeys;
+            throw new FilterSyntaxError(`Unknown filter key "${key}" – supported: ${printableKeys.join(', ')}`);
         }
-        clauses.push({ key, op, raw, regex });
+        clauses.push({ key: resolvedKey, op, raw, regex });
     }
     return clauses;
 }

package/dist/utils/help-json.js

@@ -0,0 +1,54 @@
+import { IDENTITY } from '../commands/identity.js';
+export function commandToJson(cmd, opts = {}) {
+    const args = cmd.registeredArguments.map((a) => ({
+        name: a.name(),
+        required: a.required,
+        variadic: a.variadic,
+        description: a.description ?? '',
+    }));
+    const options = cmd.options
+        .filter((o) => o.long !== '--help' && o.long !== '--version')
+        .map((o) => {
+        const entry = { flags: o.flags, description: o.description ?? '' };
+        if (o.defaultValue !== undefined)
+            entry.defaultValue = o.defaultValue;
+        if (o.argChoices && o.argChoices.length > 0)
+            entry.choices = o.argChoices;
+        return entry;
+    });
+    const subcommands = cmd.commands
+        .filter((c) => !c.name().startsWith('_'))
+        .map((c) => ({ name: c.name(), description: c.description() }));
+    const out = {
+        name: cmd.name(),
+        description: cmd.description(),
+        arguments: args,
+        options,
+        subcommands,
+    };
+    if (opts.includeIdentity) {
+        out.product = IDENTITY.product;
+        out.domain = IDENTITY.domain;
+        out.vendor = IDENTITY.vendor;
+        out.apiVersion = IDENTITY.apiVersion;
+        out.apiDocs = IDENTITY.apiDocs;
+        out.productCategories = IDENTITY.productCategories;
+    }
+    return out;
+}
+/** Walk argv tokens (skipping flags) to find the deepest matching subcommand. */
+export function resolveTargetCommand(root, argv) {
+    let cmd = root;
+    for (const token of argv) {
+        if (token.startsWith('-'))
+            continue;
+        const sub = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
+        if (sub) {
+            cmd = sub;
+        }
+        else {
+            break;
+        }
+    }
+    return cmd;
+}

package/dist/utils/output.js

@@ -28,6 +28,43 @@ export function emitJsonError(errorPayload) {
         console.error(chalk.red(msg));
     }
 }
+/**
+ * P7: emit the stream-header first line for any NDJSON/streaming command
+ * running under `--json`. Downstream JSON consumers can key on
+ * `{ stream: true }` to distinguish the header from subsequent event
+ * lines, and on `eventKind` / `cadence` to pick a parser strategy.
+ *
+ * Non-streaming commands (single-object / array output) do NOT emit this
+ * header — only watch / events tail / events mqtt-tail.
+ */
+export function emitStreamHeader(opts) {
+    console.log(JSON.stringify({
+        schemaVersion: '1',
+        stream: true,
+        eventKind: opts.eventKind,
+        cadence: opts.cadence,
+    }));
+}
+export function exitWithError(messageOrOpts) {
+    const opts = typeof messageOrOpts === 'string' ? { message: messageOrOpts } : messageOrOpts;
+    const { message, kind = 'usage', code = 2, hint, context, extra } = opts;
+    if (isJsonMode()) {
+        const payload = { code, kind, message };
+        if (hint)
+            payload.hint = hint;
+        if (context)
+            payload.context = context;
+        if (extra)
+            Object.assign(payload, extra);
+        emitJsonError(payload);
+    }
+    else {
+        console.error(message);
+        if (hint)
+            console.error(hint);
+    }
+    process.exit(code);
+}
 function escapeMarkdownCell(s) {
     // Pipes break markdown table layout; backslash-escape them. Collapse
     // newlines into <br> so each row stays on one line.

package/package.json

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