@switchbot/openapi-cli 2.1.0 → 2.2.1

package/dist/commands/devices.js

@@ -1,3 +1,4 @@
+import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
@@ -12,6 +13,7 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 export function registerDevicesCommand(program) {
+    const COMMAND_TYPES = ['command', 'customize'];
     const devices = program
         .command('devices')
         .description('Manage and control SwitchBot devices')
@@ -38,6 +40,7 @@ Run any subcommand with --help for its own flags and examples.
     // switchbot devices list
     devices
         .command('list')
+        .alias('ls')
         .description('List all physical devices and IR remote devices on the account')
         .addHelpText('after', `
 Default columns: deviceId, deviceName, type, category
@@ -66,20 +69,62 @@ Examples:
   $ switchbot devices list --format tsv --fields deviceId,deviceName,type,category
   $ switchbot devices list --json | jq '.deviceList[] | select(.familyName == "家里")'
   $ switchbot devices list --json | jq '[.deviceList[], .infraredRemoteList[]] | group_by(.familyName)'
+  $ switchbot devices list --filter type="Air Conditioner"
+  $ switchbot devices list --filter category=ir
+  $ switchbot devices list --filter name=living,category=physical
 `)
         .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: "type=X", "name=X", "category=physical|ir", "room=X" (comma-separated key=value pairs)', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
             const { deviceList, infraredRemoteList } = body;
             const fmt = resolveFormat();
             const deviceMeta = loadDeviceMeta();
+            const hubLocation = buildHubLocationMap(deviceList);
+            let listFilter = null;
+            if (options.filter) {
+                listFilter = {};
+                for (const pair of options.filter.split(',')) {
+                    const eq = pair.indexOf('=');
+                    if (eq === -1)
+                        throw new UsageError(`Invalid --filter pair "${pair.trim()}". Expected key=value.`);
+                    const k = pair.slice(0, eq).trim();
+                    const v = pair.slice(eq + 1).trim();
+                    if (!['type', 'name', 'category', 'room'].includes(k)) {
+                        throw new UsageError(`Unknown --filter key "${k}". Supported: type, name, category, room.`);
+                    }
+                    listFilter[k] = v.toLowerCase();
+                }
+            }
+            const matchesFilter = (entry) => {
+                if (!listFilter)
+                    return true;
+                if (listFilter.type && !entry.type.toLowerCase().includes(listFilter.type))
+                    return false;
+                if (listFilter.name && !entry.name.toLowerCase().includes(listFilter.name))
+                    return false;
+                if (listFilter.category && entry.category !== listFilter.category)
+                    return false;
+                if (listFilter.room && !entry.room.toLowerCase().includes(listFilter.room))
+                    return false;
+                return true;
+            };
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                if (listFilter) {
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '' }));
+                    const filteredIrList = infraredRemoteList.filter((d) => {
+                        const inherited = hubLocation.get(d.hubDeviceId);
+                        return matchesFilter({ type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '' });
+                    });
+                    printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
+                }
+                else {
+                    printJson({ ok: true, ...body });
+                }
                 return;
             }
-            const hubLocation = buildHubLocationMap(deviceList);
             const narrowHeaders = ['deviceId', 'deviceName', 'type', 'category'];
             const wideHeaders = ['deviceId', 'deviceName', 'type', 'category', 'controlType', 'family', 'roomID', 'room', 'hub', 'cloud', 'alias'];
             const userFields = resolveFields();
@@ -88,6 +133,8 @@ 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 || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -106,6 +153,8 @@ 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 || '' }))
+                    continue;
                 rows.push([
                     d.deviceId,
                     d.deviceName,
@@ -121,13 +170,22 @@ Examples:
                 ]);
             }
             if (rows.length === 0 && fmt === 'table') {
-                console.log('No devices found');
+                console.log(listFilter ? 'No devices matched the filter.' : 'No devices found');
                 return;
             }
             const defaultFields = options.wide ? undefined : narrowHeaders;
-            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields);
+            // Accept API field names and short aliases alongside canonical column names
+            const DEVICE_LIST_ALIASES = {
+                name: 'deviceName', deviceType: 'type', type: 'type',
+                roomName: 'room', familyName: 'family',
+                hubDeviceId: 'hub', enableCloudService: 'cloud',
+            };
+            renderRows(wideHeaders, rows, fmt, userFields ?? defaultFields, DEVICE_LIST_ALIASES);
             if (fmt === 'table') {
-                console.log(`\nTotal: ${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`);
+                const totalLabel = listFilter
+                    ? `${rows.length} match(es) (${deviceList.length} physical + ${infraredRemoteList.length} IR before filter)`
+                    : `${deviceList.length} physical device(s), ${infraredRemoteList.length} IR remote device(s)`;
+                console.log(`\nTotal: ${totalLabel}`);
                 console.log(`Tip: 'switchbot devices describe <deviceId>' shows a device's supported commands.`);
             }
         }
@@ -139,8 +197,9 @@ Examples:
     devices
         .command('status')
         .description('Query the real-time status of a specific device')
-        .argument('[deviceId]', 'Device ID from "devices list" (or use --name)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
+        .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)', stringArg('--ids'))
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
 
@@ -155,25 +214,70 @@ Examples:
   $ switchbot devices status ABC123DEF456 --json
   $ switchbot devices status ABC123DEF456 --format yaml
   $ switchbot devices status ABC123DEF456 --format tsv --fields power,battery
-  $ switchbot devices status ABC123DEF456 --json | jq '.battery'
+  $ switchbot devices status ABC123DEF456 --json | jq '.data.battery'
+  $ switchbot devices status --ids ABC123,DEF456,GHI789
+  $ switchbot devices status --ids ABC123,DEF456 --fields power,battery
 `)
         .action(async (deviceIdArg, options) => {
         try {
+            // Batch mode: --ids id1,id2,id3
+            if (options.ids) {
+                if (options.name)
+                    throw new UsageError('--ids and --name cannot be used together.');
+                const ids = options.ids.split(',').map((s) => s.trim()).filter(Boolean);
+                if (ids.length === 0)
+                    throw new UsageError('--ids requires at least one device ID.');
+                const results = await Promise.allSettled(ids.map((id) => fetchDeviceStatus(id)));
+                const fetchedAt = new Date().toISOString();
+                const batch = results.map((r, i) => r.status === 'fulfilled'
+                    ? { deviceId: ids[i], ok: true, _fetchedAt: fetchedAt, ...r.value }
+                    : { deviceId: ids[i], ok: false, error: r.reason?.message ?? String(r.reason) });
+                const batchFmt = resolveFormat();
+                if (isJsonMode() || batchFmt === 'json') {
+                    printJson(batch);
+                }
+                else if (batchFmt === 'jsonl') {
+                    for (const entry of batch) {
+                        console.log(JSON.stringify(entry));
+                    }
+                }
+                else {
+                    const fields = resolveFields();
+                    for (const entry of batch) {
+                        const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
+                        console.log(`\n─── ${String(deviceId)} ───`);
+                        if (!ok) {
+                            console.error(`  error: ${String(error)}`);
+                        }
+                        else {
+                            const displayStatus = fields
+                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
+                                : status;
+                            printKeyValue(displayStatus);
+                            console.error(`  fetched at ${String(ts)}`);
+                        }
+                    }
+                }
+                return;
+            }
             const deviceId = resolveDeviceId(deviceIdArg, options.name);
             const body = await fetchDeviceStatus(deviceId);
+            const fetchedAt = new Date().toISOString();
             const fmt = resolveFormat();
             if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(body);
+                printJson({ ...body, _fetchedAt: fetchedAt });
                 return;
             }
             if (fmt !== 'table') {
-                const allHeaders = Object.keys(body);
-                const allRows = [Object.values(body)];
+                const statusWithTs = { ...body, _fetchedAt: fetchedAt };
+                const allHeaders = Object.keys(statusWithTs);
+                const allRows = [Object.values(statusWithTs)];
                 const fields = resolveFields();
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
             printKeyValue(body);
+            console.error(`\nfetched at ${fetchedAt}`);
         }
         catch (error) {
             handleError(error);
@@ -184,12 +288,12 @@ Examples:
         .command('command')
         .description('Send a control command to a device')
         .argument('[deviceId]', 'Target device ID (or use --name)')
-        .argument('<cmd>', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
+        .argument('[cmd]', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
         .argument('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below).')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
-        .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', 'command')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
-        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)')
+        .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)', stringArg('--idempotency-key'))
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their
@@ -235,60 +339,89 @@ Examples:
   $ switchbot devices command ABC123 "MyButton" --type customize
   $ switchbot devices command <lockId> unlock --yes
 `)
-        .action(async (deviceIdArg, cmd, parameter, options) => {
-        const deviceId = resolveDeviceId(deviceIdArg, options.name);
-        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 };
-                console.error(JSON.stringify({ error: obj }));
+        .action(async (deviceIdArg, cmdArg, parameter, options) => {
+        try {
+            // BUG-FIX: When --name is provided, Commander misassigns the first positional
+            // to [deviceId] instead of [cmd]. Detect and shift positionals accordingly.
+            let cmd;
+            let effectiveDeviceIdArg;
+            if (options.name) {
+                if (deviceIdArg && cmdArg) {
+                    throw new UsageError('Provide either a deviceId argument or --name, not both.');
+                }
+                if (!deviceIdArg && !cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
+                cmd = (deviceIdArg ?? cmdArg);
+                effectiveDeviceIdArg = undefined;
             }
             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.)`);
+                if (!cmdArg) {
+                    throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
+                }
+                cmd = cmdArg;
+                effectiveDeviceIdArg = deviceIdArg;
+            }
+            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            if (!getCachedDevice(deviceId)) {
+                console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
+            }
+            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 };
+                    console.error(JSON.stringify({ error: 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.)`);
+                        }
                     }
                 }
+                process.exit(2);
             }
-            process.exit(2);
-        }
-        const cachedForGuard = getCachedDevice(deviceId);
-        if (!options.yes &&
-            !isDryRun() &&
-            isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
-            const typeLabel = cachedForGuard?.type ?? 'unknown';
-            const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
-            if (isJsonMode()) {
-                console.error(JSON.stringify({
-                    error: {
-                        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 } : {}) },
-                    },
-                }));
+            const cachedForGuard = getCachedDevice(deviceId);
+            if (!options.yes &&
+                !isDryRun() &&
+                isDestructiveCommand(cachedForGuard?.type, cmd, options.type)) {
+                const typeLabel = cachedForGuard?.type ?? 'unknown';
+                const reason = getDestructiveReason(cachedForGuard?.type, cmd, options.type);
+                if (isJsonMode()) {
+                    console.error(JSON.stringify({
+                        error: {
+                            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);
             }
-            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.`);
+            // Warn when --yes is given but the command is not destructive (no-op flag)
+            if (options.yes && !isDestructiveCommand(cachedForGuard?.type, cmd, options.type) && !isDryRun()) {
+                console.error(`Note: --yes has no effect; "${cmd}" is not a destructive command.`);
             }
-            process.exit(2);
-        }
-        try {
             // parameter may be a JSON object string (e.g. S10 startClean) or a plain string
             let parsedParam = parameter ?? 'default';
             if (parameter) {
@@ -311,14 +444,21 @@ Examples:
                 printJson(result);
                 return;
             }
-            console.log(`✓ Command sent: ${cmd}`);
-            if (isIr)
-                console.log('  Note: IR command sent — no device confirmation (fire-and-forget).');
-            if (body && typeof body === 'object' && Object.keys(body).length > 0) {
-                printKeyValue(body);
+            if (isIr) {
+                console.log(`→ IR signal sent: ${cmd} (no feedback — fire-and-forget)`);
+            }
+            else {
+                console.log(`✓ Command sent: ${cmd}`);
+                if (body && typeof body === 'object' && Object.keys(body).length > 0) {
+                    printKeyValue(body);
+                }
             }
         }
         catch (error) {
+            // Re-throw mock process.exit signals (Vitest intercepts process.exit as thrown
+            // Error('__exit__')) so they aren't double-handled and the exit code is preserved.
+            if (error instanceof Error && error.message === '__exit__')
+                throw error;
             handleError(error);
         }
     });
@@ -342,9 +482,10 @@ Examples:
                 printJson(catalog);
                 return;
             }
-            const headers = ['type', 'category', 'commands', 'aliases'];
+            const headers = ['type', 'role', 'category', 'commands', 'aliases'];
             const rows = catalog.map((e) => [
                 e.type,
+                e.role ?? '—',
                 e.category,
                 String(e.commands.length),
                 (e.aliases ?? []).join(', ') || '—',
@@ -404,7 +545,7 @@ Examples:
         .command('describe')
         .description('Describe a device by ID: metadata + supported commands + status fields (1 API call)')
         .argument('[deviceId]', 'Target device ID (or use --name)')
-        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId')
+        .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
         .option('--live', 'Also fetch live status values and merge them into capabilities (costs 1 extra API call)')
         .addHelpText('after', `
 Makes a GET /v1.1/devices call to look up the device's type, then prints its
@@ -535,6 +676,7 @@ function renderCatalogEntry(entry) {
     }
     else {
         console.log('\nCommands:');
+        const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
             const flags = [];
             if (c.commandType === 'customize')
@@ -542,9 +684,13 @@ function renderCatalogEntry(entry) {
             if (c.destructive)
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
-            return [label, c.parameter, c.description];
+            const base = [label, c.parameter, c.description];
+            return hasExamples ? [...base, (c.exampleParams ?? []).join(' | ') || ''] : base;
         });
-        printTable(['command', 'parameter', 'description'], rows);
+        const tableHeaders = hasExamples
+            ? ['command', 'parameter', 'description', 'example']
+            : ['command', 'parameter', 'description'];
+        printTable(tableHeaders, rows);
         const hasDestructive = entry.commands.some((c) => c.destructive);
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');