@switchbot/openapi-cli 2.4.0 → 2.5.1

package/dist/commands/devices.js

@@ -1,10 +1,10 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, emitJsonError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
-import { resolveDeviceId } from '../utils/name-resolver.js';
+import { resolveDeviceId, ALL_STRATEGIES } from '../utils/name-resolver.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, buildHubLocationMap, DeviceNotFoundError, } from '../lib/devices.js';
 import { validateParameter } from '../devices/param-validator.js';
 import { registerBatchCommand } from './batch.js';
@@ -13,6 +13,7 @@ import { registerExplainCommand } from './explain.js';
 import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
+import { DryRunSignal } from '../api/client.js';
 export function registerDevicesCommand(program) {
     const COMMAND_TYPES = ['command', 'customize'];
     const devices = program
@@ -73,10 +74,12 @@ Examples:
   $ switchbot devices list --filter type="Air Conditioner"
   $ switchbot devices list --filter category=ir
   $ switchbot devices list --filter name=living,category=physical
+  $ switchbot devices list --filter 'name~living'              # explicit substring
+  $ switchbot devices list --filter 'type=/Air.*/'             # regex (case-insensitive)
 `)
         .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'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: type, name, category, room.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -84,36 +87,77 @@ Examples:
             const fmt = resolveFormat();
             const deviceMeta = loadDeviceMeta();
             const hubLocation = buildHubLocationMap(deviceList);
-            let listFilter = null;
+            const SUPPORTED_KEYS = ['type', 'name', 'category', 'room'];
+            let listClauses = null;
             if (options.filter) {
-                listFilter = {};
+                listClauses = [];
                 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.`);
+                    const trimmed = pair.trim();
+                    if (!trimmed)
+                        continue;
+                    const regexMatch = /^([^=~]+)=\/(.*)\/$/.exec(trimmed);
+                    const tildeIdx = trimmed.indexOf('~');
+                    const eqIdx = trimmed.indexOf('=');
+                    let key;
+                    let op;
+                    let raw;
+                    let regex;
+                    if (regexMatch) {
+                        key = regexMatch[1].trim();
+                        op = 'regex';
+                        raw = regexMatch[2];
+                        try {
+                            regex = new RegExp(raw, 'i');
+                        }
+                        catch (err) {
+                            throw new UsageError(`Invalid regex in --filter "${trimmed}": ${err.message}`);
+                        }
+                    }
+                    else if (tildeIdx !== -1 && (eqIdx === -1 || tildeIdx < eqIdx)) {
+                        key = trimmed.slice(0, tildeIdx).trim();
+                        op = 'sub';
+                        raw = trimmed.slice(tildeIdx + 1).trim().toLowerCase();
+                    }
+                    else if (eqIdx !== -1) {
+                        key = trimmed.slice(0, eqIdx).trim();
+                        op = 'eq';
+                        raw = trimmed.slice(eqIdx + 1).trim().toLowerCase();
+                    }
+                    else {
+                        throw new UsageError(`Invalid --filter pair "${trimmed}". Expected key=value, key~value, or key=/regex/.`);
+                    }
+                    if (!SUPPORTED_KEYS.includes(key)) {
+                        throw new UsageError(`Unknown --filter key "${key}". Supported: ${SUPPORTED_KEYS.join(', ')}.`);
                     }
-                    listFilter[k] = v.toLowerCase();
+                    listClauses.push({ key: key, op, raw, regex });
                 }
             }
             const matchesFilter = (entry) => {
-                if (!listFilter)
+                if (!listClauses || listClauses.length === 0)
                     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;
+                for (const c of listClauses) {
+                    const fieldVal = entry[c.key] ?? '';
+                    const lower = fieldVal.toLowerCase();
+                    let ok;
+                    if (c.op === 'regex') {
+                        ok = c.regex.test(fieldVal);
+                    }
+                    else if (c.op === 'sub') {
+                        ok = lower.includes(c.raw);
+                    }
+                    else if (c.key === 'category') {
+                        ok = lower === c.raw;
+                    }
+                    else {
+                        ok = lower.includes(c.raw);
+                    }
+                    if (!ok)
+                        return false;
+                }
                 return true;
             };
             if (fmt === 'json' && process.argv.includes('--json')) {
-                if (listFilter) {
+                if (listClauses) {
                     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);
@@ -171,19 +215,19 @@ Examples:
                 ]);
             }
             if (rows.length === 0 && fmt === 'table') {
-                console.log(listFilter ? 'No devices matched the filter.' : 'No devices found');
+                console.log(listClauses ? 'No devices matched the filter.' : 'No devices found');
                 return;
             }
             const defaultFields = options.wide ? undefined : narrowHeaders;
             // Accept API field names and short aliases alongside canonical column names
             const DEVICE_LIST_ALIASES = {
-                name: 'deviceName', deviceType: 'type', type: 'type',
+                id: 'deviceId', 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') {
-                const totalLabel = listFilter
+                const totalLabel = listClauses
                     ? `${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}`);
@@ -200,7 +244,7 @@ Examples:
         .description('Query the real-time status of a specific device')
         .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('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-strategy <s>', `Name match strategy: ${ALL_STRATEGIES.join('|')} (default: fuzzy)`, stringArg('--name-strategy'))
         .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
         .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
@@ -299,15 +343,16 @@ Examples:
         .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('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below).')
+        .argument('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below). Negative numbers like -1 are accepted as-is (use `--` before them only if Commander mis-parses in your shell).')
+        .allowUnknownOption()
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
-        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default for command: require-unique)', stringArg('--name-strategy'))
+        .option('--name-strategy <s>', `Name match strategy: ${ALL_STRATEGIES.join('|')} (default for command: require-unique)`, stringArg('--name-strategy'))
         .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
         .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .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)', stringArg('--idempotency-key'))
+        .option('--idempotency-key <key>', 'Client-supplied key to dedupe retries. process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key'))
         .addHelpText('after', `
 ────────────────────────────────────────────────────────────────────────
 For the full list of commands a specific device supports — and their
@@ -354,6 +399,10 @@ Examples:
   $ switchbot devices command <lockId> unlock --yes
 `)
         .action(async (deviceIdArg, cmdArg, parameter, options) => {
+        // Declared outside try so the DryRunSignal catch branch can reference them.
+        let _deviceId;
+        let _cmd;
+        let _parsedParam;
         try {
             // BUG-FIX: When --name is provided, Commander fills positionals left-to-right
             // starting at [deviceId]. Shift them back to their semantic slots.
@@ -387,6 +436,7 @@ Examples:
                 category: options.nameCategory,
                 room: options.nameRoom,
             });
+            _deviceId = deviceId;
             if (!getCachedDevice(deviceId)) {
                 console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
             }
@@ -398,7 +448,7 @@ Examples:
                     if (err.hint)
                         obj.hint = err.hint;
                     obj.context = { validationKind: err.kind };
-                    console.error(JSON.stringify({ error: obj }));
+                    emitJsonError(obj);
                 }
                 else {
                     console.error(`Error: ${err.message}`);
@@ -428,14 +478,12 @@ Examples:
                 const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
                 if (!paramCheck.ok) {
                     if (isJsonMode()) {
-                        console.error(JSON.stringify({
-                            error: {
-                                code: 2,
-                                kind: 'usage',
-                                message: paramCheck.error,
-                                context: { command: cmd, deviceType: cachedForParam.type, deviceId },
-                            },
-                        }));
+                        emitJsonError({
+                            code: 2,
+                            kind: 'usage',
+                            message: paramCheck.error,
+                            context: { command: cmd, deviceType: cachedForParam.type, deviceId },
+                        });
                     }
                     else {
                         console.error(`Error: ${paramCheck.error}`);
@@ -452,17 +500,15 @@ Examples:
                 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 } : {}) },
-                        },
-                    }));
+                    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.`);
@@ -486,6 +532,9 @@ Examples:
                     // keep as string
                 }
             }
+            // Capture for DryRunSignal catch branch (which runs after executeCommand throws).
+            _cmd = cmd;
+            _parsedParam = parsedParam;
             const body = await executeCommand(deviceId, cmd, parsedParam, options.type, undefined, { idempotencyKey: options.idempotencyKey });
             const isIr = getCachedDevice(deviceId)?.category === 'ir';
             const verification = isIr
@@ -523,6 +572,17 @@ Examples:
             // Error('__exit__')) so they aren't double-handled and the exit code is preserved.
             if (error instanceof Error && error.message === '__exit__')
                 throw error;
+            if (error instanceof DryRunSignal) {
+                const commandType = (options.type ?? 'command');
+                const wouldSend = { deviceId: _deviceId, command: _cmd, parameter: _parsedParam, commandType };
+                if (isJsonMode()) {
+                    printJson({ dryRun: true, wouldSend });
+                }
+                else {
+                    console.log(`[dry-run] Would POST devices/${_deviceId}/commands with ${JSON.stringify({ command: _cmd, parameter: _parsedParam, commandType })}`);
+                }
+                return;
+            }
             handleError(error);
         }
     });
@@ -610,7 +670,7 @@ Examples:
         .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', stringArg('--name'))
-        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-strategy <s>', `Name match strategy: ${ALL_STRATEGIES.join('|')} (default: fuzzy)`, stringArg('--name-strategy'))
         .option('--name-type <type>', 'Narrow --name by device type', stringArg('--name-type'))
         .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
         .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
@@ -716,8 +776,20 @@ Examples:
         }
         catch (error) {
             if (error instanceof DeviceNotFoundError) {
-                console.error(error.message);
-                console.error(`Try 'switchbot devices list' to see the full list.`);
+                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);
             }
             handleError(error);

package/dist/commands/events.js

@@ -1,7 +1,9 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
-import { intArg, stringArg } from '../utils/arg-parsers.js';
+import { intArg, stringArg, durationArg } from '../utils/arg-parsers.js';
+import { parseDurationToMs } from '../utils/flags.js';
+import { parseFilterExpr, matchClause, FilterSyntaxError } from '../utils/filter.js';
 import { SwitchBotMqttClient } from '../mqtt/client.js';
 import { fetchMqttCredential } from '../mqtt/credential.js';
 import { tryLoadConfig } from '../config.js';
@@ -28,45 +30,42 @@ function extractEventId(parsed) {
         return ctx.eventId;
     return null;
 }
-function matchFilter(body, filter) {
-    if (!filter)
+function matchFilter(body, clauses) {
+    if (!clauses || clauses.length === 0)
         return true;
     if (!body || typeof body !== 'object')
         return false;
     const b = body;
     const ctx = (b.context ?? b);
-    if (filter.deviceId && ctx.deviceMac !== filter.deviceId && ctx.deviceId !== filter.deviceId) {
-        return false;
-    }
-    if (filter.type && ctx.deviceType !== filter.type) {
-        return false;
+    for (const c of clauses) {
+        let candidate;
+        if (c.key === 'deviceId') {
+            const mac = ctx.deviceMac;
+            const id = ctx.deviceId;
+            candidate = String(typeof mac === 'string' && mac ? mac : typeof id === 'string' ? id : '');
+        }
+        else {
+            const t = ctx.deviceType;
+            candidate = typeof t === 'string' ? t : '';
+        }
+        if (!matchClause(candidate, c))
+            return false;
     }
     return true;
 }
+const EVENT_FILTER_KEYS = ['deviceId', 'type'];
 function parseFilter(flag) {
     if (!flag)
         return null;
-    const allowed = new Set(['deviceId', 'type']);
-    const out = {};
-    for (const pair of flag.split(',')) {
-        const eq = pair.indexOf('=');
-        if (eq === -1 || eq === 0) {
-            throw new UsageError(`Invalid --filter pair "${pair.trim()}". Expected "key=value". Supported keys: deviceId, type.`);
-        }
-        const k = pair.slice(0, eq).trim();
-        const v = pair.slice(eq + 1).trim();
-        if (!v) {
-            throw new UsageError(`Empty value for --filter key "${k}". Expected "key=value". Supported keys: deviceId, type.`);
-        }
-        if (!allowed.has(k)) {
-            throw new UsageError(`Unknown --filter key "${k}". Supported keys: deviceId, type.`);
+    try {
+        return parseFilterExpr(flag, EVENT_FILTER_KEYS);
+    }
+    catch (e) {
+        if (e instanceof FilterSyntaxError) {
+            throw new UsageError(e.message);
         }
-        if (k === 'deviceId')
-            out.deviceId = v;
-        else if (k === 'type')
-            out.type = v;
+        throw e;
     }
-    return out;
 }
 export function startReceiver(port, pathMatch, filter, onEvent) {
     const server = http.createServer((req, res) => {
@@ -133,8 +132,9 @@ export function registerEventsCommand(program) {
         .description('Run a local HTTP receiver and print incoming webhook events as JSONL')
         .option('--port <n>', `Local port to listen on (default ${DEFAULT_PORT})`, intArg('--port', { min: 1, max: 65535 }), String(DEFAULT_PORT))
         .option('--path <p>', `HTTP path to match (default "${DEFAULT_PATH}"; use "*" for all paths)`, stringArg('--path'), DEFAULT_PATH)
-        .option('--filter <expr>', 'Filter events, e.g. "deviceId=ABC123" or "type=Bot" (comma-separated)', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter events by deviceId / type. Grammar: "key=value" (substring), "key~value" (substring), "key=/regex/" (regex). Comma-separated clauses are AND-ed.', stringArg('--filter'))
         .option('--max <n>', 'Stop after N matching events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
+        .option('--for <dur>', 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg('--for'))
         .addHelpText('after', `
 SwitchBot posts events to a single webhook URL configured via:
   $ switchbot webhook setup https://<your-public-host>/<path>
@@ -147,14 +147,20 @@ Output (JSONL, one event per line):
   { "t": "<ISO>", "remote": "<ip:port>", "path": "/",
     "body": <parsed JSON or raw string>, "matched": true }
 
-Filter grammar: comma-separated "key=value" pairs. Supported keys:
-  deviceId=<id>    match by context.deviceMac / context.deviceId
-  type=<type>      match by context.deviceType (e.g. "Bot", "WoMeter")
+Filter grammar: comma-separated clauses (AND-ed). Each clause is one of
+  key=value     — case-insensitive substring
+  key~value     — explicit case-insensitive substring
+  key=/regex/   — case-insensitive regex
+
+Supported keys:
+  deviceId    match by context.deviceMac / context.deviceId
+  type        match by context.deviceType (e.g. "Bot", "WoMeter")
 
 Examples:
   $ switchbot events tail --port 3000
   $ switchbot events tail --port 3000 --filter deviceId=ABC123
-  $ switchbot events tail --filter 'type=WoMeter' --max 5 --json
+  $ switchbot events tail --filter 'type~Meter' --max 5 --json
+  $ switchbot events tail --filter 'type=/Bot|Meter/'
 `)
         .action(async (options) => {
         try {
@@ -166,9 +172,13 @@ Examples:
             if (maxMatched !== null && (!Number.isFinite(maxMatched) || maxMatched < 1)) {
                 throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
             }
+            const forMs = options.for ? parseDurationToMs(options.for) : null;
             const filter = parseFilter(options.filter);
             let matchedCount = 0;
             const ac = new AbortController();
+            const forTimer = forMs !== null && forMs > 0
+                ? setTimeout(() => ac.abort(), forMs)
+                : null;
             await new Promise((resolve, reject) => {
                 let server = null;
                 try {
@@ -197,6 +207,8 @@ Examples:
                 if (!isJsonMode())
                     console.error(startMsg);
                 const cleanup = () => {
+                    if (forTimer)
+                        clearTimeout(forTimer);
                     server?.close();
                     resolve();
                 };
@@ -214,6 +226,7 @@ Examples:
         .description('Subscribe to SwitchBot MQTT shadow events and stream them as JSONL')
         .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)', stringArg('--topic'))
         .option('--max <n>', 'Stop after N events (default: run until Ctrl-C)', intArg('--max', { min: 1 }))
+        .option('--for <dur>', 'Stop after elapsed time (e.g. "5m", "30s"). Combines with --max: first limit wins.', durationArg('--for'))
         .option('--sink <type>', 'Output sink: stdout (default), file, webhook, openclaw, telegram, homeassistant (repeatable)', (val, prev) => [...prev, val], [])
         .option('--sink-file <path>', 'File path for file sink', stringArg('--sink-file'))
         .option('--webhook-url <url>', 'Webhook URL for webhook sink', stringArg('--webhook-url'))
@@ -235,6 +248,7 @@ Output (JSONL, one event per line):
   { "t": "<ISO>", "eventId": "<uuid>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
 
 Control records (interleaved, no "payload" field — use type-prefix to filter):
+  { "type": "__session_start", "at": "<ISO>", "eventId": "<uuid>", "state": "connecting" }  before credential fetch (JSON mode only)
   { "type": "__connect",     "at": "<ISO>", "eventId": "<uuid>" }   first successful connect
   { "type": "__reconnect",   "at": "<ISO>", "eventId": "<uuid>" }   connect after a disconnect
   { "type": "__disconnect",  "at": "<ISO>", "eventId": "<uuid>" }   reconnecting or failed
@@ -272,6 +286,7 @@ Examples:
             if (maxEvents !== null && (!Number.isInteger(maxEvents) || maxEvents < 1)) {
                 throw new UsageError(`Invalid --max "${options.max}". Must be a positive integer.`);
             }
+            const forMs = options.for ? parseDurationToMs(options.for) : null;
             const loaded = tryLoadConfig();
             if (!loaded) {
                 throw new UsageError('No credentials found. Run \'switchbot config set-token\' or set SWITCHBOT_TOKEN and SWITCHBOT_SECRET.');
@@ -331,10 +346,24 @@ Examples:
             if (!isJsonMode()) {
                 console.error('Fetching MQTT credentials from SwitchBot service…');
             }
+            // Emit a __session_start envelope immediately (before any credential
+            // fetch) so JSON consumers can distinguish "connecting" from "never
+            // connected" even when mqtt-tail exits before the broker connects.
+            if (isJsonMode()) {
+                printJson({
+                    type: '__session_start',
+                    at: new Date().toISOString(),
+                    eventId: crypto.randomUUID(),
+                    state: 'connecting',
+                });
+            }
             const credential = await fetchMqttCredential(loaded.token, loaded.secret);
             const topic = options.topic ?? credential.topics.status;
             let eventCount = 0;
             const ac = new AbortController();
+            const forTimer = forMs !== null && forMs > 0
+                ? setTimeout(() => ac.abort(), forMs)
+                : null;
             const client = new SwitchBotMqttClient(credential, () => fetchMqttCredential(loaded.token, loaded.secret));
             const unsub = client.onMessage((msgTopic, payload) => {
                 let parsed;
@@ -385,6 +414,13 @@ Examples:
                 else {
                     console.log(JSON.stringify(ctl));
                 }
+                // Persist to __control.jsonl — best-effort, never blocks the stream.
+                try {
+                    deviceHistoryStore.recordControl(ctl);
+                }
+                catch {
+                    // swallow
+                }
             };
             const unsubState = client.onStateChange((state) => {
                 if (!isJsonMode()) {
@@ -413,6 +449,8 @@ Examples:
             }
             await new Promise((resolve) => {
                 const cleanup = () => {
+                    if (forTimer)
+                        clearTimeout(forTimer);
                     process.removeListener('SIGINT', cleanup);
                     process.removeListener('SIGTERM', cleanup);
                     unsub();

package/dist/commands/expand.js

@@ -1,5 +1,5 @@
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode, printJson, UsageError } from '../utils/output.js';
+import { handleError, isJsonMode, printJson, UsageError, emitJsonError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
@@ -93,10 +93,12 @@ Examples:
             if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, 'command')) {
                 const reason = getDestructiveReason(deviceType, command, 'command');
                 if (isJsonMode()) {
-                    console.error(JSON.stringify({ error: { code: 2, kind: 'guard',
-                            message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
-                            hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
-                        } }));
+                    emitJsonError({
+                        code: 2,
+                        kind: 'guard',
+                        message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
+                        hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
+                    });
                 }
                 else {
                     console.error(`Refusing to run destructive command "${command}" without --yes.`);