@switchbot/openapi-cli 2.6.3 → 2.7.2

package/dist/commands/devices.js

@@ -1,7 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, exitWithError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
+import { findCatalogEntry, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice, loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId, ALL_STRATEGIES } from '../utils/name-resolver.js';
@@ -15,6 +15,14 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
+import { resolveField, resolveFieldList, listSupportedFieldInputs } from '../schema/field-aliases.js';
+const EXPAND_HINTS = {
+    'Air Conditioner': { command: 'setAll', flags: '--temp 26 --mode cool --fan low --power on' },
+    'Curtain': { command: 'setPosition', flags: '--position 50 --mode silent' },
+    'Curtain 3': { command: 'setPosition', flags: '--position 50' },
+    'Blind Tilt': { command: 'setPosition', flags: '--direction up --angle 50' },
+    'Relay Switch 2PM': { command: 'setMode', flags: '--channel 1 --mode edge' },
+};
 export function registerDevicesCommand(program) {
     const COMMAND_TYPES = ['command', 'customize'];
     const devices = program
@@ -80,7 +88,7 @@ Examples:
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
-        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: type, name, category, room.', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category, familyName/family, hubDeviceId/hub, roomID/roomid, enableCloudService/cloud, alias.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -90,11 +98,34 @@ Examples:
             const hubLocation = buildHubLocationMap(deviceList);
             // Parse --filter into a list of clauses. Shared grammar across
             // `devices list`, `devices batch`, and `events tail` / `mqtt-tail`.
-            const LIST_KEYS = ['type', 'name', 'category', 'room'];
+            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType',
+                'family', 'hub', 'roomID', 'cloud', 'alias'];
+            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType',
+                'roomName', 'category', 'familyName', 'hubDeviceId', 'roomID',
+                'enableCloudService', 'alias'];
+            const LIST_FILTER_TO_RUNTIME = {
+                deviceId: 'deviceId',
+                deviceName: 'name',
+                deviceType: 'type',
+                controlType: 'controlType',
+                roomName: 'room',
+                category: 'category',
+                familyName: 'family',
+                hubDeviceId: 'hub',
+                roomID: 'roomID',
+                enableCloudService: 'cloud',
+                alias: 'alias',
+            };
             let listClauses = null;
             if (options.filter) {
                 try {
-                    listClauses = parseFilterExpr(options.filter, LIST_KEYS);
+                    listClauses = parseFilterExpr(options.filter, LIST_KEYS, {
+                        resolveKey: (input) => {
+                            const canonical = resolveField(input, LIST_FILTER_CANONICAL);
+                            return LIST_FILTER_TO_RUNTIME[canonical];
+                        },
+                        supportedKeys: listSupportedFieldInputs(LIST_FILTER_CANONICAL),
+                    });
                 }
                 catch (err) {
                     if (err instanceof FilterSyntaxError)
@@ -114,10 +145,10 @@ Examples:
             };
             if (fmt === 'json' && process.argv.includes('--json')) {
                 if (listClauses) {
-                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }));
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }));
                     const filteredIrList = infraredRemoteList.filter((d) => {
                         const inherited = hubLocation.get(d.hubDeviceId);
-                        return matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' });
+                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' });
                     });
                     printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
                 }
@@ -134,7 +165,7 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
-                if (!matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -154,7 +185,7 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
-                if (!matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -177,9 +208,19 @@ Examples:
             const defaultFields = options.wide ? undefined : narrowHeaders;
             // Accept API field names and short aliases alongside canonical column names
             const DEVICE_LIST_ALIASES = {
-                id: 'deviceId', name: 'deviceName', deviceType: 'type', type: 'type',
-                roomName: 'room', familyName: 'family',
-                hubDeviceId: 'hub', enableCloudService: 'cloud',
+                id: 'deviceId',
+                name: 'deviceName',
+                deviceType: 'type',
+                type: 'type',
+                roomName: 'room',
+                familyName: 'family',
+                hubDeviceId: 'hub',
+                enableCloudService: 'cloud',
+                controlType: 'controlType',
+                deviceName: 'deviceName',
+                deviceId: 'deviceId',
+                category: 'category',
+                alias: 'alias',
             };
             renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields, DEVICE_LIST_ALIASES);
             if (fmt === 'table') {
@@ -247,7 +288,7 @@ Examples:
                     }
                 }
                 else {
-                    const fields = resolveFields();
+                    const rawFields = resolveFields();
                     for (const entry of batch) {
                         const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
                         console.log(`\n─── ${String(deviceId)} ───`);
@@ -255,9 +296,13 @@ Examples:
                             console.error(`  error: ${String(error)}`);
                         }
                         else {
+                            const statusMap = status;
+                            const fields = rawFields
+                                ? resolveFieldList(rawFields, Object.keys(statusMap))
+                                : undefined;
                             const displayStatus = fields
-                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
-                                : status;
+                                ? Object.fromEntries(fields.map((f) => [f, statusMap[f] ?? null]))
+                                : statusMap;
                             printKeyValue(displayStatus);
                             console.error(`  fetched at ${String(ts)}`);
                         }
@@ -282,7 +327,10 @@ Examples:
                 const statusWithTs = { ...body, _fetchedAt: fetchedAt };
                 const allHeaders = Object.keys(statusWithTs);
                 const allRows = [Object.values(statusWithTs)];
-                const fields = resolveFields();
+                const rawFields = resolveFields();
+                const fields = rawFields
+                    ? resolveFieldList(rawFields, allHeaders)
+                    : undefined;
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
@@ -420,26 +468,22 @@ Examples:
             const validation = validateCommand(deviceId, cmd, parameter, options.type);
             if (!validation.ok) {
                 const err = validation.error;
-                if (isJsonMode()) {
-                    const obj = { code: 2, kind: 'usage', message: err.message };
-                    if (err.hint)
-                        obj.hint = err.hint;
-                    obj.context = { validationKind: err.kind };
-                    emitJsonError(obj);
-                }
-                else {
-                    console.error(`Error: ${err.message}`);
-                    if (err.hint)
-                        console.error(err.hint);
-                    if (err.kind === 'unknown-command') {
-                        const cached = getCachedDevice(deviceId);
-                        if (cached) {
-                            console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
-                            console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
-                        }
+                let hint = err.hint;
+                if (err.kind === 'unknown-command') {
+                    const cached = getCachedDevice(deviceId);
+                    if (cached) {
+                        const extra = `Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.\n` +
+                            `(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`;
+                        hint = hint ? `${hint}\n${extra}` : extra;
                     }
                 }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: err.message,
+                    hint,
+                    context: { validationKind: err.kind },
+                });
             }
             // Case-only mismatch: emit a warning and continue with the canonical name.
             if (validation.caseNormalizedFrom && validation.normalized) {
@@ -454,18 +498,10 @@ Examples:
             if (cachedForParam && options.type === 'command' && !options.skipParamValidation) {
                 const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
                 if (!paramCheck.ok) {
-                    if (isJsonMode()) {
-                        emitJsonError({
-                            code: 2,
-                            kind: 'usage',
-                            message: paramCheck.error,
-                            context: { command: cmd, deviceType: cachedForParam.type, deviceId, humanHint: paramCheck.error },
-                        });
-                    }
-                    else {
-                        console.error(`Error: ${paramCheck.error}`);
-                    }
-                    process.exit(2);
+                    exitWithError({
+                        message: `Error: ${paramCheck.error}`,
+                        context: { command: cmd, deviceType: cachedForParam.type, deviceId, humanHint: paramCheck.error },
+                    });
                 }
                 if (paramCheck.normalized !== undefined)
                     parameter = paramCheck.normalized;
@@ -476,24 +512,14 @@ Examples:
                 isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
                 const typeLabel = cachedForGuard?.type ?? 'unknown';
                 const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${cmd}" on ${typeLabel} is destructive and requires --yes.`,
-                        hint: reason
-                            ? `Re-run with --yes to confirm. Reason: ${reason}`
-                            : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                        context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
-                    });
-                }
-                else {
-                    console.error(`Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`);
-                    if (reason)
-                        console.error(`Reason: ${reason}`);
-                    console.error(`Re-run with --yes to confirm, or --dry-run to preview without sending.`);
-                }
-                process.exit(2);
+                exitWithError({
+                    kind: 'guard',
+                    message: `Refusing to run destructive command "${cmd}" on ${typeLabel} without --yes.`,
+                    hint: reason
+                        ? `Re-run with --yes to confirm. Reason: ${reason}`
+                        : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
+                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}) },
+                });
             }
             // Warn when --yes is given but the command is not destructive (no-op flag)
             if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
@@ -630,7 +656,7 @@ Examples:
             const joinedMatch = findCatalogEntry(joined);
             if (joinedMatch && !Array.isArray(joinedMatch)) {
                 if (isJsonMode()) {
-                    printJson(joinedMatch);
+                    printJson(normalizeCatalogForJson(joinedMatch));
                 }
                 else {
                     renderCatalogEntry(joinedMatch);
@@ -649,7 +675,7 @@ Examples:
                 }
                 if (individualMatches.length === typeParts.length) {
                     if (isJsonMode()) {
-                        printJson(individualMatches);
+                        printJson(individualMatches.map(normalizeCatalogForJson));
                     }
                     else {
                         individualMatches.forEach((entry, i) => {
@@ -702,7 +728,8 @@ JSON output shape (--json):
       liveStatus: <status payload when --live was passed>
     },
     source: "catalog" | "live" | "catalog+live" | "none",
-    suggestedActions: [{command, parameter?, description}]
+    suggestedActions: [{command, parameter?, description}],
+    expandHint?: {command, flags, example}  // present when the type supports 'devices expand'
   }
 
 Examples:
@@ -722,6 +749,7 @@ Examples:
             const result = await describeDevice(deviceId, options);
             const { device, isPhysical, typeName, controlType, catalog, capabilities, source, suggestedActions: picks } = result;
             if (isJsonMode()) {
+                const expandHint = catalog ? EXPAND_HINTS[catalog.type] : undefined;
                 printJson({
                     device,
                     controlType,
@@ -729,6 +757,7 @@ Examples:
                     capabilities,
                     source,
                     suggestedActions: picks,
+                    ...(expandHint ? { expandHint: { command: expandHint.command, flags: expandHint.flags, example: `switchbot devices expand ${deviceId} ${expandHint.command} ${expandHint.flags}` } } : {}),
                 });
                 return;
             }
@@ -785,20 +814,12 @@ Examples:
         catch (error) {
             if (error instanceof DeviceNotFoundError) {
                 const message = `${error.message} Try 'switchbot devices list' to see the full list.`;
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 1,
-                        kind: 'runtime',
-                        message,
-                        errorClass: 'runtime',
-                        transient: false,
-                    });
-                }
-                else {
-                    console.error(error.message);
-                    console.error(`Try 'switchbot devices list' to see the full list.`);
-                }
-                process.exit(1);
+                exitWithError({
+                    code: 1,
+                    kind: 'runtime',
+                    message,
+                    extra: { errorClass: 'runtime', transient: false },
+                });
             }
             handleError(error);
         }
@@ -814,6 +835,21 @@ Examples:
     // switchbot devices meta set/get/list/clear
     registerDevicesMetaCommand(devices);
 }
+function normalizeCatalogForJson(entry) {
+    return {
+        ...entry,
+        commands: entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
+            const reason = getCommandSafetyReason(c);
+            return {
+                ...c,
+                safetyTier: tier,
+                destructive: tier === 'destructive',
+                ...(reason ? { safetyReason: reason } : {}),
+            };
+        }),
+    };
+}
 function renderCatalogEntry(entry) {
     console.log(`Type:     ${entry.type}`);
     console.log(`Category: ${entry.category === 'ir' ? 'IR remote' : 'Physical device'}`);
@@ -831,10 +867,11 @@ function renderCatalogEntry(entry) {
         console.log('\nCommands:');
         const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
             const flags = [];
             if (c.commandType === 'customize')
                 flags.push('customize');
-            if (c.destructive)
+            if (tier === 'destructive')
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
             const base = [label, c.parameter, c.description];
@@ -844,7 +881,7 @@ function renderCatalogEntry(entry) {
             ? ['command', 'parameter', 'description', 'example']
             : ['command', 'parameter', 'description'];
         printTable(tableHeaders, rows);
-        const hasDestructive = entry.commands.some((c) => c.destructive);
+        const hasDestructive = entry.commands.some((c) => deriveSafetyTier(c, entry) === 'destructive');
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');
         }
@@ -853,4 +890,8 @@ function renderCatalogEntry(entry) {
         console.log('\nStatus fields (from "devices status"):');
         console.log('  ' + entry.statusFields.join(', '));
     }
+    const expandHint = EXPAND_HINTS[entry.type];
+    if (expandHint) {
+        console.log(`\nTip: Use 'devices expand <id> ${expandHint.command} ${expandHint.flags}' for semantic flags instead of raw parameters.`);
+    }
 }