@switchbot/openapi-cli 2.2.1 → 2.4.0

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();

package/dist/mcp/device-history.js

@@ -2,31 +2,91 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 const MAX_HISTORY = 100;
+const JSONL_ROTATE_BYTES = 50 * 1024 * 1024; // 50 MB
+const JSONL_KEEP_ROTATIONS = 3; // .1 .2 .3
 function historyDir() {
     return path.join(os.homedir(), '.switchbot', 'device-history');
 }
 export class DeviceHistoryStore {
-    dir;
-    constructor() {
-        this.dir = historyDir();
+    // In-memory size counter so we don't stat() on every append.
+    jsonlSizes = new Map();
+    /** Reset the in-memory size counter. Tests use this between runs. */
+    resetSizes() {
+        this.jsonlSizes.clear();
+    }
+    get dir() {
+        return historyDir();
     }
     record(deviceId, topic, deviceType, payload, t) {
+        const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
         try {
             if (!fs.existsSync(this.dir))
                 fs.mkdirSync(this.dir, { recursive: true });
+            // 1. Ring-buffer JSON (back-compat with existing consumers).
             const file = path.join(this.dir, `${deviceId}.json`);
             const existing = fs.existsSync(file)
                 ? JSON.parse(fs.readFileSync(file, 'utf-8'))
                 : { latest: null, history: [] };
-            const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
             existing.latest = entry;
             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);
         }
         catch {
             // best-effort — history loss is non-fatal
         }
     }
+    appendJsonl(deviceId, entry) {
+        try {
+            const jsonlPath = path.join(this.dir, `${deviceId}.jsonl`);
+            const line = JSON.stringify(entry) + '\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);
+            if (size === undefined) {
+                try {
+                    size = fs.existsSync(jsonlPath) ? fs.statSync(jsonlPath).size : 0;
+                }
+                catch {
+                    size = 0;
+                }
+            }
+            if (size + lineBytes > JSONL_ROTATE_BYTES) {
+                this.rotateJsonl(deviceId);
+                size = 0;
+            }
+            fs.appendFileSync(jsonlPath, line, { mode: 0o600 });
+            this.jsonlSizes.set(deviceId, size + lineBytes);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    rotateJsonl(deviceId) {
+        const base = path.join(this.dir, `${deviceId}.jsonl`);
+        // .jsonl.3 is dropped; .2 → .3, .1 → .2, current → .1
+        try {
+            const oldest = `${base}.${JSONL_KEEP_ROTATIONS}`;
+            if (fs.existsSync(oldest))
+                fs.rmSync(oldest);
+        }
+        catch { /* swallow */ }
+        for (let i = JSONL_KEEP_ROTATIONS - 1; i >= 1; i--) {
+            const from = `${base}.${i}`;
+            const to = `${base}.${i + 1}`;
+            try {
+                if (fs.existsSync(from))
+                    fs.renameSync(from, to);
+            }
+            catch { /* swallow */ }
+        }
+        try {
+            if (fs.existsSync(base))
+                fs.renameSync(base, `${base}.1`);
+        }
+        catch { /* swallow */ }
+    }
     getLatest(deviceId) {
         try {
             const file = path.join(this.dir, `${deviceId}.json`);
@@ -54,13 +114,21 @@ export class DeviceHistoryStore {
         try {
             if (!fs.existsSync(this.dir))
                 return [];
-            return fs.readdirSync(this.dir)
-                .filter((f) => f.endsWith('.json'))
-                .map((f) => f.slice(0, -5));
+            const seen = new Set();
+            for (const f of fs.readdirSync(this.dir)) {
+                if (f.endsWith('.json'))
+                    seen.add(f.slice(0, -5));
+                else if (f.endsWith('.jsonl'))
+                    seen.add(f.slice(0, -6));
+            }
+            return Array.from(seen);
         }
         catch {
             return [];
         }
     }
+    getHistoryDir() {
+        return this.dir;
+    }
 }
 export const deviceHistoryStore = new DeviceHistoryStore();

package/dist/utils/arg-parsers.js

@@ -9,7 +9,10 @@ import { parseDurationToMs } from './flags.js';
  */
 export function intArg(flagName, opts) {
     return (value) => {
-        if (value.startsWith('-')) {
+        // Flag-like tokens (`--something`, `-x`) are rejected up-front.
+        // Pure negative integers (`-1`, `-42`) fall through to min/max so the
+        // error classifies as a range error rather than "requires a numeric value".
+        if (value.startsWith('-') && !/^-\d+$/.test(value)) {
             throw new InvalidArgumentError(`${flagName} requires a numeric value, got "${value}". ` +
                 `Did you forget a value? Use ${flagName}=<n> if the value really starts with "-".`);
         }

package/dist/utils/audit.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getAuditLog } from './flags.js';
+/** Bump when breaking changes to the audit line shape land. */
+export const AUDIT_VERSION = 1;
 function resolveAuditPath() {
     const flag = getAuditLog();
     if (flag === null)
@@ -16,7 +18,8 @@ export function writeAudit(entry) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        const stamped = { auditVersion: AUDIT_VERSION, ...entry };
+        fs.appendFileSync(file, JSON.stringify(stamped) + '\n');
     }
     catch {
         // Best-effort — never let audit failures break the actual command.
@@ -40,3 +43,65 @@ export function readAudit(file) {
     }
     return out;
 }
+export function verifyAudit(file) {
+    const report = {
+        file,
+        totalLines: 0,
+        parsedLines: 0,
+        skippedBlankLines: 0,
+        malformedLines: 0,
+        unversionedEntries: 0,
+        versionCounts: {},
+        problems: [],
+    };
+    if (!fs.existsSync(file)) {
+        report.problems.push({ line: 0, reason: 'audit log file does not exist' });
+        return report;
+    }
+    const raw = fs.readFileSync(file, 'utf-8');
+    const lines = raw.split(/\r?\n/);
+    let minT;
+    let maxT;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!trimmed) {
+            report.skippedBlankLines++;
+            continue;
+        }
+        report.totalLines++;
+        let entry = null;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            report.malformedLines++;
+            report.problems.push({
+                line: i + 1,
+                reason: 'JSON parse failed',
+                preview: trimmed.slice(0, 80),
+            });
+            continue;
+        }
+        report.parsedLines++;
+        const v = entry.auditVersion;
+        if (v === undefined) {
+            report.unversionedEntries++;
+            report.versionCounts['unversioned'] = (report.versionCounts['unversioned'] ?? 0) + 1;
+        }
+        else {
+            const key = String(v);
+            report.versionCounts[key] = (report.versionCounts[key] ?? 0) + 1;
+        }
+        if (entry.t) {
+            if (!minT || entry.t < minT)
+                minT = entry.t;
+            if (!maxT || entry.t > maxT)
+                maxT = entry.t;
+        }
+    }
+    if (minT)
+        report.earliest = minT;
+    if (maxT)
+        report.latest = maxT;
+    return report;
+}

package/dist/utils/flags.js

@@ -14,6 +14,14 @@ function getFlagValue(...flagNames) {
 export function isVerbose() {
     return process.argv.includes('--verbose') || process.argv.includes('-v');
 }
+/**
+ * Opt-in: disable header redaction in verbose traces. Adds a big warning on
+ * stderr. Use only when actively debugging an auth issue — never in logs or
+ * CI output.
+ */
+export function isTraceUnsafe() {
+    return process.argv.includes('--trace-unsafe');
+}
 export function isDryRun() {
     return process.argv.includes('--dry-run');
 }
@@ -111,6 +119,16 @@ export function getFields() {
         return undefined;
     return v.split(',').map((f) => f.trim()).filter(Boolean);
 }
+export function getTableStyle() {
+    const v = getFlagValue('--table-style');
+    if (v === 'unicode' || v === 'ascii' || v === 'simple' || v === 'markdown')
+        return v;
+    if (getFormat() === 'markdown')
+        return 'markdown';
+    // TTY → pretty unicode borders. Non-TTY (pipe/redirect) → ascii to avoid
+    // mojibake in consumer logs.
+    return process.stdout.isTTY ? 'unicode' : 'ascii';
+}
 export function getCacheMode() {
     if (process.argv.includes('--no-cache')) {
         return { listTtlMs: 0, statusTtlMs: 0 };

package/dist/utils/name-resolver.js

@@ -2,7 +2,14 @@ import { loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { levenshtein, normalizeDeviceName } from './string.js';
 import { UsageError, StructuredUsageError } from './output.js';
-function resolveDeviceByName(query) {
+const ALL_STRATEGIES = [
+    'exact', 'prefix', 'substring', 'fuzzy', 'first', 'require-unique',
+];
+export function isValidStrategy(s) {
+    return ALL_STRATEGIES.includes(s);
+}
+function resolveDeviceByName(query, opts = {}) {
+    const strategy = opts.strategy ?? 'fuzzy';
     const cache = loadCache();
     if (!cache || Object.keys(cache.devices).length === 0) {
         return { ok: false, ambiguous: false };
@@ -10,52 +17,71 @@ function resolveDeviceByName(query) {
     const meta = loadDeviceMeta();
     const q = normalizeDeviceName(query);
     const threshold = Math.min(3, Math.floor(q.length * 0.3));
+    const typeFilter = opts.type ? opts.type.toLowerCase() : null;
+    const roomFilter = opts.room ? opts.room.toLowerCase() : null;
     const candidates = [];
     for (const [deviceId, device] of Object.entries(cache.devices)) {
-        // alias exact match (highest priority)
-        const alias = meta.devices[deviceId]?.alias;
-        if (alias && normalizeDeviceName(alias) === q) {
-            return { ok: true, deviceId };
+        // narrow filters first
+        if (opts.category && device.category !== opts.category)
+            continue;
+        if (typeFilter && device.type.toLowerCase() !== typeFilter)
+            continue;
+        if (roomFilter) {
+            const rn = (device.roomName ?? '').toLowerCase();
+            if (rn !== roomFilter && !rn.includes(roomFilter))
+                continue;
         }
+        const alias = meta.devices[deviceId]?.alias;
         const rawName = normalizeDeviceName(device.name);
-        // exact match
-        if (rawName === q)
+        const normAlias = alias ? normalizeDeviceName(alias) : null;
+        // exact alias/name wins regardless of strategy
+        if ((normAlias && normAlias === q) || rawName === q) {
             return { ok: true, deviceId };
-        // alias substring/fuzzy (only query ⊂ alias, not the reverse)
-        if (alias) {
-            const normAlias = normalizeDeviceName(alias);
-            if (normAlias.includes(q)) {
+        }
+        if (strategy === 'exact')
+            continue;
+        if (strategy === 'prefix') {
+            if ((normAlias && normAlias.startsWith(q)) || rawName.startsWith(q)) {
                 candidates.push({ deviceId, name: device.name, score: 1 });
-                continue;
-            }
-            const dist = levenshtein(normAlias, q);
-            if (dist <= threshold) {
-                candidates.push({ deviceId, name: device.name, score: dist + 1 });
-                continue;
             }
+            continue;
         }
-        // name substring (only query ⊂ name, not the reverse — avoids long queries
-        // collapsing onto short device names)
-        if (rawName.includes(q)) {
+        // substring + fuzzy + require-unique + first all share substring match
+        if ((normAlias && normAlias.includes(q)) || rawName.includes(q)) {
             candidates.push({ deviceId, name: device.name, score: 1 });
             continue;
         }
-        // levenshtein
-        const dist = levenshtein(rawName, q);
-        if (dist <= threshold) {
-            candidates.push({ deviceId, name: device.name, score: dist + 1 });
+        if (strategy === 'substring')
+            continue;
+        // fuzzy / require-unique / first → also levenshtein
+        if (strategy === 'fuzzy' || strategy === 'require-unique' || strategy === 'first') {
+            const distName = levenshtein(rawName, q);
+            const distAlias = normAlias ? levenshtein(normAlias, q) : Number.POSITIVE_INFINITY;
+            const dist = Math.min(distName, distAlias);
+            if (dist <= threshold) {
+                candidates.push({ deviceId, name: device.name, score: dist + 1 });
+            }
         }
     }
     if (candidates.length === 0)
         return { ok: false, ambiguous: false };
     candidates.sort((a, b) => a.score - b.score);
+    if (strategy === 'first') {
+        return { ok: true, deviceId: candidates[0].deviceId };
+    }
+    if (strategy === 'require-unique') {
+        if (candidates.length === 1)
+            return { ok: true, deviceId: candidates[0].deviceId };
+        return { ok: false, ambiguous: true, candidates: candidates.slice(0, 4) };
+    }
+    // fuzzy / substring / prefix: collapse cluster of near-ties
     const best = candidates[0].score;
     const top = candidates.filter((c) => c.score <= best + 1);
     if (top.length === 1)
         return { ok: true, deviceId: top[0].deviceId };
     return { ok: false, ambiguous: true, candidates: top.slice(0, 4) };
 }
-export function resolveDeviceId(deviceId, nameQuery) {
+export function resolveDeviceId(deviceId, nameQuery, opts = {}) {
     if (deviceId && nameQuery) {
         throw new UsageError('Provide either a deviceId argument or --name, not both.');
     }
@@ -64,15 +90,37 @@ export function resolveDeviceId(deviceId, nameQuery) {
     if (!nameQuery) {
         throw new UsageError('A deviceId argument or --name flag is required.');
     }
+    if (opts.strategy && !isValidStrategy(opts.strategy)) {
+        throw new UsageError(`--name-strategy must be one of: ${ALL_STRATEGIES.join(', ')} (got "${opts.strategy}")`);
+    }
     const cache = loadCache();
     if (!cache) {
         throw new UsageError(`--name requires the device cache. Run 'switchbot devices list' first to populate it.`);
     }
-    const result = resolveDeviceByName(nameQuery);
+    const result = resolveDeviceByName(nameQuery, opts);
     if (result.ok)
         return result.deviceId;
     if (result.ambiguous) {
-        throw new StructuredUsageError(`"${nameQuery}" is ambiguous — be more specific or use the deviceId directly.`, { candidates: result.candidates.map((c) => ({ deviceId: c.deviceId, name: c.name })) });
+        const candidates = result.candidates.map((c) => ({ deviceId: c.deviceId, name: c.name }));
+        const narrow = [];
+        if (!opts.type)
+            narrow.push('--type');
+        if (!opts.category)
+            narrow.push('--category');
+        if (!opts.room)
+            narrow.push('--room');
+        const hint = narrow.length > 0
+            ? `Narrow with ${narrow.join(' / ')} or use the deviceId directly, or pass --name-strategy first to pick the best match.`
+            : `Use the deviceId directly, or pass --name-strategy first to pick the best match.`;
+        throw new StructuredUsageError(`"${nameQuery}" is ambiguous — ${candidates.length} devices match.`, {
+            error: 'ambiguous_name_match',
+            query: nameQuery,
+            candidates,
+            hint,
+        });
     }
-    throw new UsageError(`No device matches "${nameQuery}". Run 'switchbot devices list' to see device names.`);
+    const noMatchNarrow = opts.type || opts.category || opts.room
+        ? ' after applying --type/--category/--room filters'
+        : '';
+    throw new UsageError(`No device matches "${nameQuery}"${noMatchNarrow}. Run 'switchbot devices list' to see device names.`);
 }