@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/config.js

@@ -3,6 +3,12 @@ import path from 'node:path';
 import os from 'node:os';
 import { getConfigPath } from './utils/flags.js';
 import { getActiveProfile } from './lib/request-context.js';
+function sanitizeOptionalString(v) {
+    if (typeof v !== 'string')
+        return undefined;
+    const trimmed = v.trim();
+    return trimmed ? trimmed : undefined;
+}
 /**
  * Credential file resolution priority:
  *   1. --config <path> (absolute override — wins over everything)
@@ -85,15 +91,70 @@ export function tryLoadConfig() {
         return null;
     }
 }
-export function saveConfig(token, secret) {
+export function saveConfig(token, secret, extras) {
     const file = configFilePath();
     const dir = path.dirname(file);
     if (!fs.existsSync(dir)) {
         fs.mkdirSync(dir, { recursive: true });
     }
-    const cfg = { token, secret };
+    // Merge with existing file so label/limits/defaults aren't dropped when the
+    // user just rotates the token.
+    let existing = {};
+    if (fs.existsSync(file)) {
+        try {
+            existing = JSON.parse(fs.readFileSync(file, 'utf-8'));
+        }
+        catch {
+            existing = {};
+        }
+    }
+    const cfg = {
+        token,
+        secret,
+        ...(existing.label ? { label: existing.label } : {}),
+        ...(existing.description ? { description: existing.description } : {}),
+        ...(existing.limits ? { limits: existing.limits } : {}),
+        ...(existing.defaults ? { defaults: existing.defaults } : {}),
+    };
+    if (extras) {
+        const label = sanitizeOptionalString(extras.label);
+        const description = sanitizeOptionalString(extras.description);
+        if (label !== undefined)
+            cfg.label = label;
+        if (description !== undefined)
+            cfg.description = description;
+        if (extras.limits)
+            cfg.limits = { ...(cfg.limits ?? {}), ...extras.limits };
+        if (extras.defaults)
+            cfg.defaults = { ...(cfg.defaults ?? {}), ...extras.defaults };
+    }
     fs.writeFileSync(file, JSON.stringify(cfg, null, 2), { mode: 0o600 });
 }
+/**
+ * Read a profile's metadata (label / description / limits / defaults) without
+ * exposing the token/secret. Returns null when the file is missing or invalid.
+ */
+export function readProfileMeta(profile) {
+    const file = profile
+        ? profileFilePath(profile)
+        : path.join(os.homedir(), '.switchbot', 'config.json');
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const cfg = JSON.parse(raw);
+        return {
+            label: cfg.label,
+            description: cfg.description,
+            limits: cfg.limits,
+            defaults: cfg.defaults,
+            path: file,
+        };
+    }
+    catch {
+        return null;
+    }
+}
 export function showConfig() {
     const envToken = process.env.SWITCHBOT_TOKEN;
     const envSecret = process.env.SWITCHBOT_SECRET;
@@ -112,8 +173,16 @@ export function showConfig() {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         console.log(`Credential source: ${file}`);
+        if (cfg.label)
+            console.log(`label : ${cfg.label}`);
+        if (cfg.description)
+            console.log(`desc  : ${cfg.description}`);
         console.log(`token : ${maskCredential(cfg.token)}`);
         console.log(`secret: ${maskSecret(cfg.secret)}`);
+        if (cfg.limits?.dailyCap)
+            console.log(`limits: dailyCap=${cfg.limits.dailyCap}`);
+        if (cfg.defaults?.flags?.length)
+            console.log(`defaults: ${cfg.defaults.flags.join(' ')}`);
     }
     catch {
         console.error('Failed to read config file');

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

@@ -0,0 +1,181 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline';
+const DEFAULT_LIMIT = 1000;
+function historyDir() {
+    return path.join(os.homedir(), '.switchbot', 'device-history');
+}
+/**
+ * Parse a duration shortcut like "7d", "12h", "30m", "45s" into milliseconds.
+ * Returns null on malformed input (caller throws UsageError).
+ */
+export function parseDurationToMs(spec) {
+    const m = spec.trim().match(/^(\d+)(ms|s|m|h|d)$/i);
+    if (!m)
+        return null;
+    const n = Number(m[1]);
+    const unit = m[2].toLowerCase();
+    const factor = unit === 'ms' ? 1 : unit === 's' ? 1_000 : unit === 'm' ? 60_000 : unit === 'h' ? 3_600_000 : 86_400_000;
+    return n * factor;
+}
+/** Parse ISO-8601 (with Z or offset) or Date-parseable string → ms, else null. */
+export function parseInstantToMs(spec) {
+    const ms = Date.parse(spec);
+    return Number.isFinite(ms) ? ms : null;
+}
+export function resolveRange(opts) {
+    let fromMs = Number.NEGATIVE_INFINITY;
+    let toMs = Number.POSITIVE_INFINITY;
+    if (opts.since && (opts.from || opts.to)) {
+        throw new Error('--since is mutually exclusive with --from/--to.');
+    }
+    if (opts.since) {
+        const durMs = parseDurationToMs(opts.since);
+        if (durMs === null) {
+            throw new Error(`Invalid --since value "${opts.since}". Expected e.g. "30s", "15m", "1h", "7d".`);
+        }
+        fromMs = Date.now() - durMs;
+    }
+    else {
+        if (opts.from) {
+            const parsed = parseInstantToMs(opts.from);
+            if (parsed === null)
+                throw new Error(`Invalid --from value "${opts.from}". Expected ISO-8601 timestamp.`);
+            fromMs = parsed;
+        }
+        if (opts.to) {
+            const parsed = parseInstantToMs(opts.to);
+            if (parsed === null)
+                throw new Error(`Invalid --to value "${opts.to}". Expected ISO-8601 timestamp.`);
+            toMs = parsed;
+        }
+        if (fromMs > toMs)
+            throw new Error('--from must be <= --to.');
+    }
+    return { fromMs, toMs };
+}
+/** Return jsonl candidate files for a device, oldest-first. */
+export function jsonlFilesForDevice(deviceId, baseDir = historyDir()) {
+    const out = [];
+    if (!fs.existsSync(baseDir))
+        return out;
+    // Oldest-first so range walks can bail early once a line overshoots `toMs`.
+    for (let i = 3; i >= 1; i--) {
+        const p = path.join(baseDir, `${deviceId}.jsonl.${i}`);
+        if (fs.existsSync(p))
+            out.push(p);
+    }
+    const current = path.join(baseDir, `${deviceId}.jsonl`);
+    if (fs.existsSync(current))
+        out.push(current);
+    return out;
+}
+function projectFields(record, fields) {
+    if (fields.length === 0)
+        return record;
+    const projected = {};
+    const payload = (record.payload ?? {});
+    for (const f of fields) {
+        if (f in payload)
+            projected[f] = payload[f];
+    }
+    return { t: record.t, topic: record.topic, deviceType: record.deviceType, payload: projected };
+}
+/**
+ * Stream-read the JSONL rotation files for `deviceId` and return records
+ * within [fromMs, toMs]. Parse failures are silently dropped (best-effort).
+ *
+ * Files whose mtime < fromMs are skipped whole (coarse but sound: the newest
+ * record in the file is <= mtime, so nothing in it can match).
+ */
+export async function queryDeviceHistory(deviceId, opts = {}) {
+    const { fromMs, toMs } = resolveRange(opts);
+    const limit = Math.max(0, opts.limit ?? DEFAULT_LIMIT);
+    const fields = opts.fields ?? [];
+    const files = jsonlFilesForDevice(deviceId);
+    const out = [];
+    for (const file of files) {
+        try {
+            const stat = fs.statSync(file);
+            if (stat.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))
+                continue;
+            if (tMs < fromMs || tMs > toMs)
+                continue;
+            out.push(projectFields(rec, fields));
+            if (out.length >= limit) {
+                rl.close();
+                stream.destroy();
+                return out;
+            }
+        }
+    }
+    return out;
+}
+export function queryDeviceHistoryStats(deviceId) {
+    const dir = historyDir();
+    const files = jsonlFilesForDevice(deviceId);
+    let totalBytes = 0;
+    let oldest = null;
+    let newest = null;
+    let count = 0;
+    for (const file of files) {
+        try {
+            totalBytes += fs.statSync(file).size;
+        }
+        catch { /* */ }
+    }
+    // Walk the oldest file's head + current file's tail for oldest/newest + count.
+    // Counting is O(records) here, acceptable for "stats" which isn't a hot path.
+    for (const file of files) {
+        try {
+            const lines = fs.readFileSync(file, 'utf-8').split('\n');
+            for (const line of lines) {
+                if (!line)
+                    continue;
+                count += 1;
+                try {
+                    const rec = JSON.parse(line);
+                    const tMs = Date.parse(rec.t);
+                    if (Number.isFinite(tMs)) {
+                        if (oldest === null || tMs < oldest)
+                            oldest = tMs;
+                        if (newest === null || tMs > newest)
+                            newest = tMs;
+                    }
+                }
+                catch { /* */ }
+            }
+        }
+        catch { /* */ }
+    }
+    return {
+        deviceId,
+        fileCount: files.length,
+        totalBytes,
+        recordCount: count,
+        oldest: oldest !== null ? new Date(oldest).toISOString() : undefined,
+        newest: newest !== null ? new Date(newest).toISOString() : undefined,
+        jsonlFiles: files.map((f) => path.basename(f)),
+        historyDir: dir,
+    };
+}

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';
@@ -18,15 +19,21 @@ import { registerSchemaCommand } from './commands/schema.js';
 import { registerHistoryCommand } from './commands/history.js';
 import { registerPlanCommand } from './commands/plan.js';
 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.
 const TOP_LEVEL_COMMANDS = [
     'config', 'devices', 'scenes', 'webhook', 'completion', 'mcp',
     'quota', 'catalog', 'cache', 'events', 'doctor', 'schema',
-    'history', 'plan', 'capabilities',
+    'history', 'plan', 'capabilities', 'agent-bootstrap',
 ];
 const cacheModeArg = (value) => {
     if (value.startsWith('-')) {
@@ -43,9 +50,11 @@ 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', enumArg('--format', ['table', 'json', 'jsonl', 'tsv', 'yaml', 'id']))
+    .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 }))
+    .option('--table-style <style>', 'Table rendering style: unicode (default on TTY), ascii (default on pipes), simple, markdown', enumArg('--table-style', ['unicode', 'ascii', 'simple', 'markdown']))
     .option('-v, --verbose', 'Log HTTP request/response details to stderr')
     .option('--dry-run', 'Print mutating requests without sending them (GETs still execute)')
     .option('--timeout <ms>', 'HTTP request timeout in milliseconds (default: 30000)', intArg('--timeout', { min: 1 }))
@@ -76,6 +85,7 @@ registerSchemaCommand(program);
 registerHistoryCommand(program);
 registerPlanCommand(program);
 registerCapabilitiesCommand(program);
+registerAgentBootstrapCommand(program);
 program.addHelpText('after', `
 Credentials:
   Provide SwitchBot API v1.1 credentials via either:
@@ -130,6 +140,13 @@ function applyExitOverride(cmd) {
     cmd.commands.forEach(applyExitOverride);
 }
 applyExitOverride(program);
+// Enable "did you mean" suggestions across every subcommand, not just the root.
+// Without this, `switchbot devices lst` fails without suggesting `list`.
+function enableSuggestions(cmd) {
+    cmd.showSuggestionAfterError(true);
+    cmd.commands.forEach(enableSuggestions);
+}
+enableSuggestions(program);
 try {
     await program.parseAsync();
 }

package/dist/lib/devices.js

@@ -124,7 +124,14 @@ export async function executeCommand(deviceId, cmd, parameter, commandType, clie
             throw err;
         }
     };
-    return idempotencyCache.run(options?.idempotencyKey, execute);
+    const { result, replayed } = await idempotencyCache.run(options?.idempotencyKey, execute, { command: cmd, parameter });
+    if (!replayed)
+        return result;
+    // Cached hit — attach replayed marker without mutating the original.
+    if (result && typeof result === 'object') {
+        return { ...result, replayed: true };
+    }
+    return { value: result, replayed: true };
 }
 /**
  * Validate a command against the locally-cached device → catalog mapping.

package/dist/lib/idempotency.js

@@ -1,11 +1,46 @@
 /**
  * In-memory LRU cache for idempotent request deduplication.
  * Caches the outcome of a keyed operation for 60 seconds;
- * duplicate keys within the window return the cached result without re-executing.
+ * duplicate keys within the window return the cached result (with a
+ * `replayed: true` marker). Duplicate keys within the window for a DIFFERENT
+ * (command, parameter) shape raise {@link IdempotencyConflictError}.
+ *
+ * Keys are stored in-memory as a SHA-256 fingerprint of the user-provided
+ * key — the original string never touches the Map keys, so a later heap dump
+ * or inadvertent log capture does not leak the raw token.
+ *
  * Process-local only — not shared across replicas.
  */
+import crypto from 'node:crypto';
 const DEFAULT_TTL_MS = 60000; // 60 seconds
 const DEFAULT_MAX_ENTRIES = 1024;
+export class IdempotencyConflictError extends Error {
+    key;
+    existingShape;
+    newShape;
+    constructor(message, key, existingShape, newShape) {
+        super(message);
+        this.key = key;
+        this.existingShape = existingShape;
+        this.newShape = newShape;
+        this.name = 'IdempotencyConflictError';
+    }
+}
+function hashKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+}
+function shapeSignature(command, parameter) {
+    // Canonical-ish JSON — stable enough for object equality with no nested sort
+    // (callers can pass primitives or small objects).
+    let parm;
+    try {
+        parm = JSON.stringify(parameter ?? 'default');
+    }
+    catch {
+        parm = String(parameter);
+    }
+    return `${command}::${parm}`;
+}
 export class IdempotencyCache {
     cache = new Map();
     ttlMs;
@@ -17,56 +52,55 @@ export class IdempotencyCache {
     /**
      * Execute fn if the key is not cached, or return the cached result if it is.
      * On new execution, caches the result for ttlMs.
+     *
+     * When `shape` is provided, a cached hit is validated against the original
+     * (command, parameter) fingerprint; mismatched shape raises
+     * {@link IdempotencyConflictError}.
+     *
+     * Returns a tuple-esque object with `replayed: true` when the cached
+     * result is served. The `result` field is the original cached value.
      */
-    async run(key, fn) {
-        // No key = always execute (not cached)
+    async run(key, fn, shape) {
         if (!key) {
-            return fn();
+            const result = await fn();
+            return { result, replayed: false };
         }
+        const hashed = hashKey(key);
         const now = Date.now();
-        const cached = this.cache.get(key);
-        // Cached and not expired
+        const cached = this.cache.get(hashed);
+        const currentShape = shape ? shapeSignature(shape.command, shape.parameter) : '*';
         if (cached && cached.expiresAt > now) {
-            return cached.result;
+            if (shape && cached.shape !== '*' && cached.shape !== currentShape) {
+                throw new IdempotencyConflictError(`idempotency_conflict: key was first used for ${cached.shape.replace('::', ' ')}; refusing new shape ${currentShape.replace('::', ' ')}`, '<redacted>', cached.shape, currentShape);
+            }
+            return { result: cached.result, replayed: true };
         }
-        // Expired or uncached: execute
         const result = await fn();
-        // Prune if over capacity (LRU: remove oldest entries)
         if (this.cache.size >= this.maxEntries) {
-            const toRemove = Math.ceil(this.maxEntries * 0.1); // Remove 10%
+            const toRemove = Math.ceil(this.maxEntries * 0.1);
             let removed = 0;
             for (const [k, v] of this.cache.entries()) {
                 if (removed >= toRemove)
                     break;
-                // Remove expired entries first, then oldest
                 if (v.expiresAt <= now) {
                     this.cache.delete(k);
                     removed++;
                 }
             }
-            // If still over capacity, remove oldest insertion (Map is insertion-ordered)
             if (this.cache.size >= this.maxEntries) {
                 const firstKey = this.cache.keys().next().value;
                 if (firstKey)
                     this.cache.delete(firstKey);
             }
         }
-        // Cache the result
-        this.cache.set(key, { result, expiresAt: now + this.ttlMs });
-        return result;
+        this.cache.set(hashed, { result, expiresAt: now + this.ttlMs, shape: currentShape });
+        return { result, replayed: false };
     }
-    /**
-     * Clear all cached entries (mainly for testing).
-     */
     clear() {
         this.cache.clear();
     }
-    /**
-     * Return the number of cached entries.
-     */
     size() {
         return this.cache.size;
     }
 }
-// Global shared instance for the process
 export const idempotencyCache = new IdempotencyCache();