@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/commands/doctor.js

@@ -3,8 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { printJson, isJsonMode } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
-import { configFilePath, listProfiles } from '../config.js';
+import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
 import { describeCache } from '../devices/cache.js';
+export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
     if (envOk)
@@ -39,21 +40,97 @@ function checkProfiles() {
         return { name: 'profiles', status: 'ok', detail: 'no profile dir (default profile only)' };
     }
     const profiles = listProfiles();
+    if (profiles.length === 0) {
+        return { name: 'profiles', status: 'ok', detail: 'profile dir empty' };
+    }
+    const labelled = profiles.map((p) => {
+        const meta = readProfileMeta(p);
+        if (meta?.label)
+            return `${p} (${meta.label})`;
+        return p;
+    });
     return {
         name: 'profiles',
         status: 'ok',
-        detail: profiles.length ? `found ${profiles.length}: ${profiles.join(', ')}` : 'profile dir empty',
+        detail: `found ${profiles.length}: ${labelled.join(', ')}`,
     };
 }
-function checkClockSkew() {
-    const now = Date.now();
-    const drift = now - Math.floor(now / 1000) * 1000;
-    // HMAC signing uses ms timestamps — we can't detect remote skew without a
-    // round-trip, but we can flag if the local clock has NTP issues via the
-    // classic "jumps back" pattern. Best-effort: just report local time.
-    const iso = new Date().toISOString();
-    return { name: 'clock', status: 'ok', detail: `local time ${iso} (drift check needs API round-trip)` };
-    void drift;
+async function checkClockSkew() {
+    // Real probe: HEAD the SwitchBot API endpoint and compare the server's Date
+    // header against local time. No auth required for the Date header — the API
+    // returns 401 but still stamps the response. Gracefully degrades to
+    // probeSource:'none' if offline / no network reachable.
+    //
+    // Under vitest, only run the probe if fetch has been stubbed (detected via
+    // vi.fn marker) — otherwise skip network I/O to keep unrelated tests fast.
+    const underVitest = Boolean(process.env.VITEST);
+    const fetchFn = globalThis.fetch;
+    const fetchIsMocked = Boolean(fetchFn && typeof fetchFn === 'function' && 'mock' in fetchFn);
+    if (underVitest && !fetchIsMocked) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: { probeSource: 'none', skewMs: null, message: 'skipped: test environment' },
+        };
+    }
+    const localBefore = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const res = await fetch('https://api.switch-bot.com/v1.1/devices', {
+            method: 'HEAD',
+            signal: ctrl.signal,
+        });
+        const localAfter = Date.now();
+        const dateHeader = res.headers.get('date');
+        if (!dateHeader) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: 'server returned no Date header' },
+            };
+        }
+        const serverMs = Date.parse(dateHeader);
+        if (!Number.isFinite(serverMs)) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: `unparseable Date header: ${dateHeader}` },
+            };
+        }
+        // Split the round-trip in half to estimate the local instant that matches
+        // the server's Date header. HTTP Date resolution is 1s, so treat anything
+        // under 2000ms as ok, 2000–60000ms as warn, beyond that as fail (HMAC
+        // auth rejects requests with skew > 5 minutes anyway).
+        const midpoint = (localBefore + localAfter) / 2;
+        const skewMs = Math.round(midpoint - serverMs);
+        const absSkew = Math.abs(skewMs);
+        const status = absSkew < 2000 ? 'ok' : absSkew < 60_000 ? 'warn' : 'fail';
+        return {
+            name: 'clock',
+            status,
+            detail: {
+                probeSource: 'api',
+                skewMs,
+                localIso: new Date(midpoint).toISOString(),
+                serverIso: new Date(serverMs).toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: {
+                probeSource: 'none',
+                skewMs: null,
+                message: `probe failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 function checkCatalog() {
     const catalog = getEffectiveCatalog();
@@ -153,7 +230,7 @@ Examples:
             checkCatalog(),
             checkCache(),
             checkQuotaFile(),
-            checkClockSkew(),
+            await checkClockSkew(),
             checkMqtt(),
         ];
         const summary = {
@@ -162,13 +239,27 @@ Examples:
             fail: checks.filter((c) => c.status === 'fail').length,
         };
         const overallFail = summary.fail > 0;
+        const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
         if (isJsonMode()) {
-            printJson({ overall: overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok', summary, checks });
+            // Stable contract (locked as doctor.schemaVersion=1):
+            //   { ok: boolean, overall: 'ok'|'warn'|'fail', generatedAt, schemaVersion,
+            //     summary: { ok, warn, fail }, checks: [{ name, status, detail }] }
+            // `ok` is an alias of (overall === 'ok') — agents prefer the boolean,
+            // humans prefer the string; both are provided.
+            printJson({
+                ok: overall === 'ok',
+                overall,
+                generatedAt: new Date().toISOString(),
+                schemaVersion: DOCTOR_SCHEMA_VERSION,
+                summary,
+                checks,
+            });
         }
         else {
             for (const c of checks) {
                 const icon = c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗';
-                console.log(`${icon} ${c.name.padEnd(12)} ${c.detail}`);
+                const detailStr = typeof c.detail === 'string' ? c.detail : JSON.stringify(c.detail);
+                console.log(`${icon} ${c.name.padEnd(12)} ${detailStr}`);
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);

package/dist/commands/events.js

@@ -1,4 +1,5 @@
 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 { SwitchBotMqttClient } from '../mqtt/client.js';
@@ -16,6 +17,17 @@ import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
+function extractEventId(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    if (typeof p.eventId === 'string' && p.eventId.length > 0)
+        return p.eventId;
+    const ctx = p.context;
+    if (ctx && typeof ctx.eventId === 'string' && ctx.eventId.length > 0)
+        return ctx.eventId;
+    return null;
+}
 function matchFilter(body, filter) {
     if (!filter)
         return true;
@@ -220,7 +232,19 @@ Connects to the SwitchBot MQTT service using your existing credentials
 No additional MQTT configuration required.
 
 Output (JSONL, one event per line):
-  { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+  { "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": "__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
+
+Reconnect policy: the MQTT client retries with exponential backoff
+(1s → 30s capped, forever) while the credential is still valid; if the
+credential is rejected or 5 consecutive reconnects fail, state goes to
+'failed' and the command exits non-zero so supervisors can restart it.
+QoS is 0 (at-most-once); agents requiring at-least-once delivery should
+fan-out via --sink file and deduplicate by eventId on the consumer side.
 
 Sink types (--sink, repeatable):
   stdout             Print JSONL to stdout (default when no --sink given)
@@ -321,9 +345,14 @@ Examples:
                     parsed = payload.toString('utf-8');
                 }
                 const t = new Date().toISOString();
+                // Every event carries an eventId so downstream sinks / replay tools
+                // can dedupe. If the broker supplied one (some providers do via a
+                // header), prefer that; otherwise synth a UUID locally.
+                const existingId = extractEventId(parsed);
+                const eventId = existingId ?? crypto.randomUUID();
                 if (dispatcher) {
                     const { deviceId, deviceType, text } = parseSinkEvent(parsed);
-                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text };
+                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text, eventId };
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
                     dispatcher.dispatch(sinkEvent).catch(() => { });
                 }
@@ -331,7 +360,7 @@ Examples:
                     // Default behavior: record history + print to stdout
                     const { deviceId, deviceType } = parseSinkEvent(parsed);
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
-                    const record = { t, topic: msgTopic, payload: parsed };
+                    const record = { t, eventId, topic: msgTopic, payload: parsed };
                     if (isJsonMode()) {
                         printJson(record);
                     }
@@ -345,12 +374,39 @@ Examples:
                 }
             });
             let mqttFailed = false;
+            let hasConnectedBefore = false;
+            const emitControl = (kind) => {
+                const ctl = { type: kind, at: new Date().toISOString(), eventId: crypto.randomUUID() };
+                // Control events always go to stdout as JSONL so consumers that
+                // filter real events by presence of `payload` can skip them.
+                if (isJsonMode()) {
+                    printJson(ctl);
+                }
+                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()) {
                     console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
                 }
-                if (state === 'failed') {
+                if (state === 'connected') {
+                    emitControl(hasConnectedBefore ? '__reconnect' : '__connect');
+                    hasConnectedBefore = true;
+                }
+                else if (state === 'reconnecting') {
+                    emitControl('__disconnect');
+                }
+                else if (state === 'failed') {
                     mqttFailed = true;
+                    emitControl('__disconnect');
                     if (!isJsonMode()) {
                         console.error('MQTT connection failed permanently (credential expired or reconnect exhausted) — exiting.');
                     }

package/dist/commands/history.js

@@ -1,9 +1,11 @@
 import path from 'node:path';
 import os from 'node:os';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
-import { readAudit } from '../utils/audit.js';
+import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { readAudit, verifyAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
+import { queryDeviceHistory, queryDeviceHistoryStats, } from '../devices/history-query.js';
+import { aggregateDeviceHistory, ALL_AGG_FNS, } from '../devices/history-agg.js';
 const DEFAULT_AUDIT = path.join(os.homedir(), '.switchbot', 'audit.log');
 export function registerHistoryCommand(program) {
     const history = program
@@ -101,4 +103,227 @@ Examples:
             handleError(err);
         }
     });
+    history
+        .command('range')
+        .description('Query time-ranged device history from JSONL storage (populated by events mqtt-tail / MCP)')
+        .argument('<deviceId>', 'Device ID to query')
+        .option('--since <duration>', 'Relative window ending now, e.g. "30s", "15m", "1h", "7d" (mutually exclusive with --from/--to)', stringArg('--since'))
+        .option('--from <iso>', 'Range start (ISO-8601)', stringArg('--from'))
+        .option('--to <iso>', 'Range end (ISO-8601)', stringArg('--to'))
+        .option('--field <name>', 'Project a payload field (repeat to keep multiple)', (v, acc = []) => acc.concat(v), [])
+        .option('--limit <n>', 'Maximum records to return (default 1000)', intArg('--limit', { min: 1 }))
+        .addHelpText('after', `
+History is the append-only JSONL mirror of the per-device ring buffer: every
+'events mqtt-tail' event and every MCP tool status-refresh is written to
+~/.switchbot/device-history/<deviceId>.jsonl (rotates at 50MB × 3 files).
+
+Examples:
+  $ switchbot history range <id> --since 7d --json
+  $ switchbot history range <id> --since 1h --field temperature --field humidity
+  $ switchbot history range <id> --from 2026-04-18T00:00:00Z --to 2026-04-19T00:00:00Z
+`)
+        .action(async (deviceId, options) => {
+        // Usage-level validation: keep synchronous and pre-query so handleError
+        // maps these to exit 2 (via UsageError) rather than runtime exit 1.
+        if (options.since && (options.from || options.to)) {
+            handleError(new UsageError('--since is mutually exclusive with --from/--to.'));
+        }
+        try {
+            const records = await queryDeviceHistory(deviceId, {
+                since: options.since,
+                from: options.from,
+                to: options.to,
+                fields: options.field ?? [],
+                limit: options.limit !== undefined ? Number(options.limit) : undefined,
+            });
+            if (isJsonMode()) {
+                printJson({ deviceId, count: records.length, records });
+                return;
+            }
+            if (records.length === 0) {
+                console.log(`(no history records for ${deviceId} in requested range)`);
+                return;
+            }
+            for (const r of records) {
+                const payloadStr = JSON.stringify(r.payload);
+                console.log(`${r.t}  ${r.topic}  ${payloadStr}`);
+            }
+        }
+        catch (err) {
+            // Convert history-query's plain Error range messages into UsageError so
+            // they exit 2 instead of 1.
+            if (err instanceof Error && /^(Invalid --|--from|--since)/i.test(err.message)) {
+                handleError(new UsageError(err.message));
+            }
+            handleError(err);
+        }
+    });
+    history
+        .command('stats')
+        .description('Show on-disk size + record counts for a device history')
+        .argument('<deviceId>', 'Device ID to inspect')
+        .action((deviceId) => {
+        try {
+            const stats = queryDeviceHistoryStats(deviceId);
+            if (isJsonMode()) {
+                printJson(stats);
+                return;
+            }
+            console.log(`Device:        ${stats.deviceId}`);
+            console.log(`History dir:   ${stats.historyDir}`);
+            console.log(`JSONL files:   ${stats.fileCount} (${stats.jsonlFiles.join(', ') || '—'})`);
+            console.log(`Total size:    ${stats.totalBytes.toLocaleString()} bytes`);
+            console.log(`Record count:  ${stats.recordCount}`);
+            console.log(`Oldest:        ${stats.oldest ?? '—'}`);
+            console.log(`Newest:        ${stats.newest ?? '—'}`);
+        }
+        catch (err) {
+            handleError(err);
+        }
+    });
+    history
+        .command('verify')
+        .description('Check the audit log for malformed lines and schema-version drift')
+        .option('--file <path>', `Path to the audit log (default ${DEFAULT_AUDIT})`, stringArg('--file'))
+        .addHelpText('after', `
+See docs/audit-log.md for the audit log format. Exit code:
+  0  every line parses and carries the current auditVersion, or file is missing (warn)
+  1  one or more lines are malformed or schema drift detected
+  2  (usage) — not emitted by this subcommand
+
+Examples:
+  $ switchbot history verify
+  $ switchbot history verify --file ./custom.log --json
+`)
+        .action((options) => {
+        const file = options.file ?? DEFAULT_AUDIT;
+        const report = verifyAudit(file);
+        // Determine status and exit code
+        let status = 'ok';
+        let exitCode = 0;
+        if (report.fileMissing) {
+            status = 'warn';
+        }
+        else if (report.malformedLines > 0 || report.unversionedEntries > 0) {
+            status = 'fail';
+            exitCode = 1;
+        }
+        if (isJsonMode()) {
+            const output = {
+                status,
+                fileMissing: report.fileMissing === true,
+                parsed: report.parsedLines,
+                malformed: report.malformedLines,
+                unversioned: report.unversionedEntries,
+                message: report.fileMissing
+                    ? 'Audit log file not found (fresh install)'
+                    : report.malformedLines > 0 || report.unversionedEntries > 0
+                        ? 'Audit log has malformed or unversioned entries'
+                        : 'Audit log is valid',
+            };
+            printJson(output);
+        }
+        else {
+            if (report.fileMissing) {
+                console.log(`Audit log:       ${report.file} (missing — fresh install)`);
+                console.log(`Status:          ✓ warn (expected for new accounts)`);
+            }
+            else {
+                console.log(`Audit log:       ${report.file}`);
+                console.log(`Parsed lines:    ${report.parsedLines} / ${report.totalLines}`);
+                console.log(`Malformed:       ${report.malformedLines}`);
+                console.log(`Unversioned:     ${report.unversionedEntries}`);
+                const versions = Object.entries(report.versionCounts)
+                    .map(([v, n]) => `${v}:${n}`)
+                    .join(', ');
+                console.log(`Version counts:  ${versions || '—'}`);
+                if (report.earliest)
+                    console.log(`Earliest:        ${report.earliest}`);
+                if (report.latest)
+                    console.log(`Latest:          ${report.latest}`);
+                if (report.problems.length > 0) {
+                    console.log('\nProblems:');
+                    for (const p of report.problems) {
+                        console.log(`  line ${p.line}: ${p.reason}${p.preview ? ` — "${p.preview}"` : ''}`);
+                    }
+                }
+            }
+        }
+        process.exit(exitCode);
+    });
+    history
+        .command('aggregate')
+        .description('Aggregate time-ranged device history metrics into buckets')
+        .argument('<deviceId>', 'Device ID to aggregate')
+        .option('--since <duration>', 'Relative window ending now, e.g. "1h", "7d" (mutually exclusive with --from/--to)', stringArg('--since'))
+        .option('--from <iso>', 'Range start (ISO-8601)', stringArg('--from'))
+        .option('--to <iso>', 'Range end (ISO-8601)', stringArg('--to'))
+        .option('--metric <name>', 'Payload field to aggregate (repeat for multiple)', (v, acc = []) => acc.concat(v), [])
+        .option('--agg <csv>', 'Comma-separated aggregation functions (count,min,max,avg,sum,p50,p95)', stringArg('--agg'))
+        .option('--bucket <duration>', 'Bucket width, e.g. "15m", "1h", "1d"', stringArg('--bucket'))
+        .option('--max-bucket-samples <n>', 'Max samples per bucket for quantiles (1–100000)', intArg('--max-bucket-samples', { min: 1, max: 100_000 }))
+        .action(async (deviceId, options) => {
+        const metrics = options.metric ?? [];
+        if (metrics.length === 0) {
+            handleError(new UsageError('at least one --metric is required.'));
+        }
+        if (options.since && (options.from || options.to)) {
+            handleError(new UsageError('--since is mutually exclusive with --from/--to.'));
+        }
+        let aggs;
+        if (options.agg !== undefined) {
+            const parts = options.agg.split(',').map((s) => s.trim()).filter(Boolean);
+            const unknown = parts.filter((p) => !ALL_AGG_FNS.includes(p));
+            if (unknown.length > 0) {
+                handleError(new UsageError(`Unknown aggregation function(s): ${unknown.join(', ')}. Legal values: ${ALL_AGG_FNS.join(', ')}.`));
+            }
+            aggs = parts;
+        }
+        const aggOpts = {
+            metrics,
+            aggs,
+            since: options.since,
+            from: options.from,
+            to: options.to,
+            bucket: options.bucket,
+            maxBucketSamples: options.maxBucketSamples !== undefined ? Number(options.maxBucketSamples) : undefined,
+        };
+        try {
+            const res = await aggregateDeviceHistory(deviceId, aggOpts);
+            if (isJsonMode()) {
+                printJson(res);
+                return;
+            }
+            if (res.buckets.length === 0) {
+                console.log(`(no history records for ${deviceId} in requested range)`);
+                return;
+            }
+            const aggCols = res.aggs;
+            const cols = ['t', ...res.metrics.flatMap((m) => aggCols.map((a) => `${m}.${a}`))];
+            console.log(cols.join('\t'));
+            for (const bkt of res.buckets) {
+                const row = cols.map((col) => {
+                    if (col === 't')
+                        return bkt.t;
+                    const [metric, agg] = col.split('.');
+                    const val = bkt.metrics[metric]?.[agg];
+                    return val !== undefined ? String(val) : '\u2014';
+                });
+                console.log(row.join('\t'));
+            }
+            if (res.partial) {
+                for (const note of res.notes) {
+                    console.error('note: ' + note);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error) {
+                if (/bucket/i.test(err.message) || /--since/i.test(err.message) || /--from/i.test(err.message) || /--to/i.test(err.message)) {
+                    handleError(new UsageError(err.message));
+                }
+            }
+            handleError(err);
+        }
+    });
 }