@switchbot/openapi-cli 2.4.0 → 2.5.1

package/dist/commands/scenes.js

@@ -1,4 +1,4 @@
-import { printJson, isJsonMode, handleError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, StructuredUsageError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
 export function registerScenesCommand(program) {
@@ -47,6 +47,15 @@ Example:
 `)
         .action(async (sceneId) => {
         try {
+            const sceneList = await fetchScenes();
+            const found = sceneList.find((s) => s.sceneId === sceneId);
+            if (!found) {
+                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
+                    error: 'scene_not_found',
+                    sceneId,
+                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
+                });
+            }
             await executeScene(sceneId);
             if (isJsonMode()) {
                 printJson({ ok: true, sceneId });
@@ -59,4 +68,46 @@ Example:
             handleError(error);
         }
     });
+    // switchbot scenes describe <sceneId>
+    scenes
+        .command('describe')
+        .description('Show metadata for a scene by its ID (SwitchBot API v1.1 does not expose step detail)')
+        .argument('<sceneId>', 'Scene ID from "scenes list"')
+        .addHelpText('after', `
+Note: SwitchBot API v1.1 does not return scene step detail. Only the scene name is available.
+
+Example:
+  $ switchbot scenes describe T12345678
+`)
+        .action(async (sceneId) => {
+        try {
+            const sceneList = await fetchScenes();
+            const found = sceneList.find((s) => s.sceneId === sceneId);
+            if (!found) {
+                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
+                    error: 'scene_not_found',
+                    sceneId,
+                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
+                });
+            }
+            const result = {
+                sceneId: found.sceneId,
+                sceneName: found.sceneName,
+                stepCount: null,
+                note: 'SwitchBot API v1.1 does not expose scene steps — displayed name only',
+            };
+            if (isJsonMode()) {
+                printJson(result);
+            }
+            else {
+                console.log(`sceneId:   ${result.sceneId}`);
+                console.log(`sceneName: ${result.sceneName}`);
+                console.log(`stepCount: (not available)`);
+                console.log(`note:      ${result.note}`);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
 }

package/dist/commands/schema.js

@@ -156,6 +156,12 @@ Examples:
                     type: 'object',
                     description: 'CLI-synthesized receipt-acknowledgment metadata. For IR devices, verifiable:false signals that no device-side confirmation is possible.',
                 },
+                {
+                    field: 'hints',
+                    appliesTo: ['agent-bootstrap'],
+                    type: 'string[]',
+                    description: 'CLI-synthesized advisory messages for the calling agent. Always emitted; empty array ([]) means no hints to report — never null and not a disabled-field signal.',
+                },
             ];
         }
         printJson(payload);

package/dist/commands/watch.js

@@ -61,6 +61,7 @@ export function registerWatchCommand(devices) {
         .option('--name <query>', 'Resolve one device by fuzzy name (combined with any positional IDs)', stringArg('--name'))
         .option('--interval <dur>', `Polling interval: "30s", "1m", "500ms", ... (default 30s, min ${MIN_INTERVAL_MS / 1000}s)`, durationArg('--interval'), '30s')
         .option('--max <n>', 'Stop after N ticks (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('--include-unchanged', 'Emit a tick even when no field changed')
         .addHelpText('after', `
 Each poll emits one JSON line per deviceId with the shape:
@@ -99,11 +100,15 @@ Examples:
                 }
                 maxTicks = Math.floor(n);
             }
+            const forMs = options.for ? parseDurationToMs(options.for) : null;
             const fields = getFields() ?? null;
             const ac = new AbortController();
             const onSig = () => ac.abort();
             process.on('SIGINT', onSig);
             process.on('SIGTERM', onSig);
+            const forTimer = forMs !== null && forMs > 0
+                ? setTimeout(() => ac.abort(), forMs)
+                : null;
             try {
                 const prev = new Map();
                 const client = createClient();
@@ -163,6 +168,8 @@ Examples:
                 handleError(err);
             }
             finally {
+                if (forTimer)
+                    clearTimeout(forTimer);
                 process.off('SIGINT', onSig);
                 process.off('SIGTERM', onSig);
             }

package/dist/devices/cache.js

@@ -1,47 +1,78 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
+import { createHash } from 'node:crypto';
 import { getConfigPath } from '../utils/flags.js';
+import { getActiveProfile } from '../lib/request-context.js';
+/**
+ * Returns the directory where cache files should be stored.
+ *
+ * - If a profile is active, scopes into a per-profile sub-directory so that
+ *   rotating credentials or switching profiles never serves stale inventory
+ *   from a prior session (Bug #37).
+ * - If no profile is active (unnamed / default), returns `baseDir` unchanged
+ *   so the existing legacy path (~/.switchbot/devices.json) is preserved.
+ *
+ * Only called when `getConfigPath()` returns undefined — the --config-path
+ * override takes full precedence and bypasses this helper entirely.
+ */
+function scopedCacheDir(baseDir) {
+    const profile = getActiveProfile();
+    if (profile === undefined)
+        return baseDir;
+    const hash = createHash('sha256').update(profile).digest('hex').slice(0, 8);
+    const dir = path.join(baseDir, 'cache', hash);
+    if (!fs.existsSync(dir))
+        fs.mkdirSync(dir, { recursive: true });
+    return dir;
+}
 /** GC cutoff for status entries: evict anything older than this. */
 const DEFAULT_STATUS_GC_TTL_MS = 24 * 60 * 60 * 1000; // 24 h
 function cacheFilePath() {
     const override = getConfigPath();
     const dir = override
         ? path.dirname(path.resolve(override))
-        : path.join(os.homedir(), '.switchbot');
+        : scopedCacheDir(path.join(os.homedir(), '.switchbot'));
     return path.join(dir, 'devices.json');
 }
-// In-memory hot-cache: undefined = not yet loaded, null = loaded but empty.
-let _listCache = undefined;
-let _statusCache = undefined;
+// In-memory hot-cache keyed by active profile (or '__default__' for no profile).
+// Using Maps instead of module-level singletons ensures that mcp serve, which
+// rotates profiles per request via withRequestContext, never leaks inventory
+// across profiles within the same process (Bug #37).
+const _listCacheByProfile = new Map();
+const _statusCacheByProfile = new Map();
+function cacheKey() {
+    return getActiveProfile() ?? '__default__';
+}
 /** Force the next loadCache() call to re-read from disk. Used in tests. */
 export function resetListCache() {
-    _listCache = undefined;
+    _listCacheByProfile.clear();
 }
 /** Force the next loadStatusCache() call to re-read from disk. Used in tests. */
 export function resetStatusCache() {
-    _statusCache = undefined;
+    _statusCacheByProfile.clear();
 }
 export function loadCache() {
-    if (_listCache !== undefined)
-        return _listCache;
+    const key = cacheKey();
+    if (_listCacheByProfile.has(key))
+        return _listCacheByProfile.get(key);
     const file = cacheFilePath();
     if (!fs.existsSync(file)) {
-        _listCache = null;
+        _listCacheByProfile.set(key, null);
         return null;
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cache = JSON.parse(raw);
         if (!cache || typeof cache.devices !== 'object' || cache.devices === null) {
-            _listCache = null;
+            _listCacheByProfile.set(key, null);
             return null;
         }
-        _listCache = cache;
+        _listCacheByProfile.set(key, cache);
         return cache;
     }
     catch {
-        _listCache = null;
+        _listCacheByProfile.set(key, null);
         return null;
     }
 }
@@ -109,7 +140,7 @@ export function updateCacheFromDeviceList(body) {
         if (!fs.existsSync(dir))
             fs.mkdirSync(dir, { recursive: true });
         fs.writeFileSync(file, JSON.stringify(cache, null, 2), { mode: 0o600 });
-        _listCache = cache;
+        _listCacheByProfile.set(cacheKey(), cache);
     }
     catch {
         // Cache write failures must not break the command that triggered them.
@@ -119,7 +150,7 @@ export function clearCache() {
     const file = cacheFilePath();
     if (fs.existsSync(file))
         fs.unlinkSync(file);
-    _listCache = null;
+    _listCacheByProfile.set(cacheKey(), null);
 }
 // ---- Device list freshness -------------------------------------------------
 /** Age of the on-disk list cache in ms, or null if there is no cache. */
@@ -143,34 +174,38 @@ function statusCacheFilePath() {
     const override = getConfigPath();
     const dir = override
         ? path.dirname(path.resolve(override))
-        : path.join(os.homedir(), '.switchbot');
+        : scopedCacheDir(path.join(os.homedir(), '.switchbot'));
     return path.join(dir, 'status.json');
 }
 export function loadStatusCache() {
-    if (_statusCache !== undefined)
-        return _statusCache;
+    const key = cacheKey();
+    if (_statusCacheByProfile.has(key))
+        return _statusCacheByProfile.get(key);
     const file = statusCacheFilePath();
     if (!fs.existsSync(file)) {
-        _statusCache = { entries: {} };
-        return _statusCache;
+        const empty = { entries: {} };
+        _statusCacheByProfile.set(key, empty);
+        return empty;
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const parsed = JSON.parse(raw);
         if (!parsed || typeof parsed.entries !== 'object' || parsed.entries === null) {
-            _statusCache = { entries: {} };
-            return _statusCache;
+            const empty = { entries: {} };
+            _statusCacheByProfile.set(key, empty);
+            return empty;
         }
-        _statusCache = parsed;
+        _statusCacheByProfile.set(key, parsed);
         return parsed;
     }
     catch {
-        _statusCache = { entries: {} };
-        return _statusCache;
+        const empty = { entries: {} };
+        _statusCacheByProfile.set(key, empty);
+        return empty;
     }
 }
 function saveStatusCache(cache) {
-    _statusCache = cache;
+    _statusCacheByProfile.set(cacheKey(), cache);
     try {
         const file = statusCacheFilePath();
         const dir = path.dirname(file);
@@ -220,7 +255,7 @@ export function clearStatusCache() {
     const file = statusCacheFilePath();
     if (fs.existsSync(file))
         fs.unlinkSync(file);
-    _statusCache = { entries: {} };
+    _statusCacheByProfile.set(cacheKey(), { entries: {} });
 }
 export function describeCache(now = Date.now()) {
     const listFile = cacheFilePath();

package/dist/devices/history-agg.js

@@ -0,0 +1,138 @@
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { jsonlFilesForDevice, parseDurationToMs, resolveRange } from './history-query.js';
+export const ALL_AGG_FNS = ['count', 'min', 'max', 'avg', 'sum', 'p50', 'p95'];
+export const DEFAULT_AGGS = ['count', 'avg'];
+export const DEFAULT_SAMPLE_CAP = 10_000;
+export const MAX_SAMPLE_CAP = 100_000;
+export async function aggregateDeviceHistory(deviceId, opts) {
+    const { fromMs, toMs } = resolveRange(opts);
+    const aggs = (opts.aggs && opts.aggs.length > 0) ? opts.aggs : [...DEFAULT_AGGS];
+    const needQuantile = aggs.includes('p50') || aggs.includes('p95');
+    let bucketMs = null;
+    if (opts.bucket !== undefined) {
+        bucketMs = parseDurationToMs(opts.bucket);
+        if (bucketMs === null) {
+            throw new Error(`Invalid --bucket "${opts.bucket}". Expected e.g. "15m", "1h", "1d".`);
+        }
+    }
+    const sampleCap = Math.max(1, Math.min(opts.maxBucketSamples ?? DEFAULT_SAMPLE_CAP, MAX_SAMPLE_CAP));
+    let partial = false;
+    const notes = [];
+    // bucketKey (epoch ms; 0 when no --bucket) → metric name → Acc
+    const buckets = new Map();
+    for (const file of jsonlFilesForDevice(deviceId)) {
+        try {
+            const st = fs.statSync(file);
+            if (st.mtimeMs < fromMs)
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const stream = fs.createReadStream(file, { encoding: 'utf-8' });
+        const rl = readline.createInterface({ input: stream, crlfDelay: Infinity });
+        for await (const line of rl) {
+            if (!line)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(line);
+            }
+            catch {
+                continue;
+            }
+            const tMs = Date.parse(rec.t);
+            if (!Number.isFinite(tMs) || tMs < fromMs || tMs > toMs)
+                continue;
+            const key = bucketMs !== null ? Math.floor(tMs / bucketMs) * bucketMs : 0;
+            let bkt = buckets.get(key);
+            if (!bkt) {
+                bkt = new Map();
+                buckets.set(key, bkt);
+            }
+            for (const metric of opts.metrics) {
+                const v = rec.payload?.[metric];
+                if (typeof v !== 'number' || !Number.isFinite(v))
+                    continue;
+                let acc = bkt.get(metric);
+                if (!acc) {
+                    acc = {
+                        min: v,
+                        max: v,
+                        sum: 0,
+                        count: 0,
+                        samples: needQuantile ? [] : null,
+                        sampleCapHit: false,
+                    };
+                    bkt.set(metric, acc);
+                }
+                acc.min = Math.min(acc.min, v);
+                acc.max = Math.max(acc.max, v);
+                acc.sum += v;
+                acc.count += 1;
+                if (acc.samples) {
+                    if (acc.samples.length < sampleCap) {
+                        acc.samples.push(v);
+                    }
+                    else if (!acc.sampleCapHit) {
+                        acc.sampleCapHit = true;
+                        partial = true;
+                        notes.push(`bucket ${new Date(key).toISOString()} metric ${metric}: sample cap ${sampleCap} reached, quantiles approximate`);
+                    }
+                }
+            }
+        }
+    }
+    return finalize(deviceId, opts, aggs, buckets, partial, notes, fromMs, toMs);
+}
+function finalize(deviceId, opts, aggs, buckets, partial, notes, fromMs, toMs) {
+    const fromIso = Number.isFinite(fromMs) ? new Date(fromMs).toISOString() : new Date(0).toISOString();
+    const toIso = Number.isFinite(toMs) ? new Date(toMs).toISOString() : new Date(Date.now()).toISOString();
+    const keys = [...buckets.keys()].sort((a, b) => a - b);
+    const outBuckets = [];
+    for (const key of keys) {
+        const perMetric = buckets.get(key);
+        const metricsOut = {};
+        for (const [metric, acc] of perMetric.entries()) {
+            if (acc.count === 0)
+                continue;
+            const r = {};
+            if (aggs.includes('count'))
+                r.count = acc.count;
+            if (aggs.includes('min'))
+                r.min = acc.min;
+            if (aggs.includes('max'))
+                r.max = acc.max;
+            if (aggs.includes('avg'))
+                r.avg = acc.sum / acc.count;
+            if (aggs.includes('sum'))
+                r.sum = acc.sum;
+            if ((aggs.includes('p50') || aggs.includes('p95')) && acc.samples) {
+                const sorted = [...acc.samples].sort((a, b) => a - b);
+                if (aggs.includes('p50'))
+                    r.p50 = sorted[Math.floor(0.5 * (sorted.length - 1))];
+                if (aggs.includes('p95'))
+                    r.p95 = sorted[Math.floor(0.95 * (sorted.length - 1))];
+            }
+            metricsOut[metric] = r;
+        }
+        if (Object.keys(metricsOut).length === 0)
+            continue;
+        outBuckets.push({
+            t: new Date(key).toISOString(),
+            metrics: metricsOut,
+        });
+    }
+    return {
+        deviceId,
+        bucket: opts.bucket,
+        from: fromIso,
+        to: toIso,
+        metrics: [...opts.metrics],
+        aggs: [...aggs],
+        buckets: outBuckets,
+        partial,
+        notes,
+    };
+}

package/dist/devices/history-query.js

@@ -24,7 +24,7 @@ export function parseInstantToMs(spec) {
     const ms = Date.parse(spec);
     return Number.isFinite(ms) ? ms : null;
 }
-function resolveRange(opts) {
+export function resolveRange(opts) {
     let fromMs = Number.NEGATIVE_INFINITY;
     let toMs = Number.POSITIVE_INFINITY;
     if (opts.since && (opts.from || opts.to)) {

package/dist/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Command, CommanderError, InvalidArgumentError } from 'commander';
 import { createRequire } from 'node:module';
+import chalk from 'chalk';
 import { intArg, stringArg, enumArg } from './utils/arg-parsers.js';
 import { parseDurationToMs } from './utils/flags.js';
 import { registerConfigCommand } from './commands/config.js';
@@ -21,6 +22,11 @@ import { registerCapabilitiesCommand } from './commands/capabilities.js';
 import { registerAgentBootstrapCommand } from './commands/agent-bootstrap.js';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../package.json');
+// Early initialization: check for --no-color flag or NO_COLOR env var and disable chalk.
+// This must happen before any commands run so all chalk output is affected.
+if (process.argv.includes('--no-color') || Boolean(process.env.NO_COLOR)) {
+    chalk.level = 0;
+}
 const program = new Command();
 // Top-level subcommand names. Used by stringArg to produce clearer errors when
 // a value is omitted and the next argv token turns out to be a subcommand name.
@@ -44,6 +50,7 @@ program
     .name('switchbot')
     .description('Command-line tool for SwitchBot API v1.1')
     .version(pkgVersion)
+    .option('--no-color', 'Disable ANSI colors in output')
     .option('--json', 'Output raw JSON response (disables tables; useful for pipes/scripts)')
     .option('--format <type>', 'Output format: table (default), json, jsonl, tsv, yaml, id, markdown', enumArg('--format', ['table', 'json', 'jsonl', 'tsv', 'yaml', 'id', 'markdown']))
     .option('--fields <csv>', 'Comma-separated list of columns to include (e.g. --fields=id,name,type)', stringArg('--fields', { disallow: TOP_LEVEL_COMMANDS }))

package/dist/mcp/device-history.js

@@ -31,19 +31,30 @@ export class DeviceHistoryStore {
             existing.history = [entry, ...existing.history].slice(0, MAX_HISTORY);
             fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
             // 2. Append-only JSONL for range queries.
-            this.appendJsonl(deviceId, entry);
+            this.writeJsonl(deviceId, entry);
         }
         catch {
             // best-effort — history loss is non-fatal
         }
     }
-    appendJsonl(deviceId, entry) {
+    /** Append a mqtt control event (no deviceId) to the dedicated __control.jsonl file. */
+    recordControl(event) {
         try {
-            const jsonlPath = path.join(this.dir, `${deviceId}.jsonl`);
-            const line = JSON.stringify(entry) + '\n';
+            if (!fs.existsSync(this.dir))
+                fs.mkdirSync(this.dir, { recursive: true });
+            this.writeJsonl('__control', event);
+        }
+        catch {
+            // best-effort — never block the event stream
+        }
+    }
+    writeJsonl(fileKey, record) {
+        try {
+            const jsonlPath = path.join(this.dir, `${fileKey}.jsonl`);
+            const line = JSON.stringify(record) + '\n';
             const lineBytes = Buffer.byteLength(line, 'utf-8');
             // Seed size counter from disk on first touch (avoids drift across restarts).
-            let size = this.jsonlSizes.get(deviceId);
+            let size = this.jsonlSizes.get(fileKey);
             if (size === undefined) {
                 try {
                     size = fs.existsSync(jsonlPath) ? fs.statSync(jsonlPath).size : 0;
@@ -53,18 +64,18 @@ export class DeviceHistoryStore {
                 }
             }
             if (size + lineBytes > JSONL_ROTATE_BYTES) {
-                this.rotateJsonl(deviceId);
+                this.rotateJsonl(fileKey);
                 size = 0;
             }
             fs.appendFileSync(jsonlPath, line, { mode: 0o600 });
-            this.jsonlSizes.set(deviceId, size + lineBytes);
+            this.jsonlSizes.set(fileKey, size + lineBytes);
         }
         catch {
             // best-effort
         }
     }
-    rotateJsonl(deviceId) {
-        const base = path.join(this.dir, `${deviceId}.jsonl`);
+    rotateJsonl(fileKey) {
+        const base = path.join(this.dir, `${fileKey}.jsonl`);
         // .jsonl.3 is dropped; .2 → .3, .1 → .2, current → .1
         try {
             const oldest = `${base}.${JSONL_KEEP_ROTATIONS}`;

package/dist/utils/arg-parsers.js

@@ -37,7 +37,8 @@ export function durationArg(flagName) {
         }
         const ms = parseDurationToMs(value);
         if (ms === null) {
-            throw new InvalidArgumentError(`${flagName} must look like "30s", "1m", "500ms", "1h" (got "${value}")`);
+            throw new InvalidArgumentError(`${flagName} must look like "30s", "1m", "500ms", "1h", "7d", "2w" ` +
+                `(supported units: ms, s, m, h, d, w — got "${value}")`);
         }
         return value;
     };

package/dist/utils/audit.js

@@ -55,7 +55,7 @@ export function verifyAudit(file) {
         problems: [],
     };
     if (!fs.existsSync(file)) {
-        report.problems.push({ line: 0, reason: 'audit log file does not exist' });
+        report.fileMissing = true;
         return report;
     }
     const raw = fs.readFileSync(file, 'utf-8');