@switchbot/openapi-cli 2.5.0 → 2.5.1

package/dist/commands/mcp.js

@@ -3,7 +3,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { z } from 'zod';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode } from '../utils/output.js';
+import { handleError, isJsonMode, buildErrorPayload, emitJsonError } from '../utils/output.js';
 import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
@@ -26,11 +26,36 @@ function mcpError(kind, code, message, options) {
         obj.retryable = true;
     if (options?.context)
         obj.context = options.context;
+    if (options?.subKind !== undefined)
+        obj.subKind = options.subKind;
+    if (options?.errorClass !== undefined)
+        obj.errorClass = options.errorClass;
+    if (options?.transient !== undefined)
+        obj.transient = options.transient;
+    if (options?.retryAfterMs !== undefined)
+        obj.retryAfterMs = options.retryAfterMs;
     return {
         isError: true,
         content: [{ type: 'text', text: JSON.stringify({ error: obj }, null, 2) }],
+        structuredContent: { error: obj },
     };
 }
+/**
+ * Convert any thrown error into a structured MCP tool-error response,
+ * preserving all ErrorPayload fields (subKind, transient, hint, etc.).
+ */
+function apiErrorToMcpError(err) {
+    const payload = buildErrorPayload(err);
+    return mcpError(payload.kind, payload.code, payload.message, {
+        hint: payload.hint,
+        retryable: payload.retryable,
+        context: payload.context,
+        subKind: payload.subKind,
+        errorClass: payload.errorClass,
+        transient: payload.transient,
+        retryAfterMs: payload.retryAfterMs,
+    });
+}
 export function createSwitchBotMcpServer(options) {
     const eventManager = options?.eventManager;
     const server = new McpServer({
@@ -248,8 +273,19 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         },
     }, async ({ deviceId, command, parameter, commandType, confirm, idempotencyKey, dryRun }) => {
         const effectiveType = commandType ?? 'command';
-        // dryRun early-return — no API call, no validation against live device list
+        // dryRun early-return — no API call. We still preflight the deviceId
+        // against the local cache so fabricated IDs don't silently pass
+        // validation (bug #SYS-3). Dry-run is meant to catch bad inputs; a
+        // dry-run that accepts anything is worse than no dry-run at all.
         if (dryRun) {
+            const cached = getCachedDevice(deviceId);
+            if (!cached) {
+                return mcpError('usage', 2, `Device "${deviceId}" not found in local cache.`, {
+                    subKind: 'device-not-found',
+                    hint: "Run 'list_devices' first to warm the cache, then retry with dryRun:true.",
+                    context: { deviceId },
+                });
+            }
             const wouldSend = {
                 deviceId,
                 command,
@@ -319,7 +355,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     },
                 });
             }
-            throw err;
+            return apiErrorToMcpError(err);
         }
         const isIr = getCachedDevice(deviceId)?.category === 'ir';
         const structured = { ok: true, command, deviceId, result };
@@ -364,7 +400,12 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                 structuredContent: structured,
             };
         }
-        await executeScene(sceneId);
+        try {
+            await executeScene(sceneId);
+        }
+        catch (err) {
+            return apiErrorToMcpError(err);
+        }
         const structured = { ok: true, sceneId };
         return {
             content: [{ type: 'text', text: JSON.stringify(structured, null, 2) }],
@@ -393,7 +434,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         description: 'Search the built-in device catalog by type name or alias. Returns matching entries with their commands, roles, destructive flags, and status fields. No API call.',
         _meta: { agentSafetyTier: 'read' },
         inputSchema: z.object({
-            query: z.string().describe('Search query (matches type and aliases, case-insensitive). Use empty string to list all.'),
+            query: z.string().describe('Search query (matches type and aliases, case-insensitive). Must be non-empty; use list_catalog_types to enumerate instead.'),
             limit: z.number().int().min(1).max(100).optional().default(20).describe('Max entries returned (default 20)'),
         }).strict(),
         outputSchema: {
@@ -416,6 +457,11 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             total: z.number().int().describe('Number of entries returned'),
         },
     }, async ({ query, limit }) => {
+        if (query.trim() === '') {
+            return mcpError('usage', 2, 'search_catalog requires a non-empty query.', {
+                hint: "Pass a search term like 'Bot' or 'Hub', or call list_catalog_types to enumerate all types without a query.",
+            });
+        }
         const hits = searchCatalog(query, limit);
         const structured = { results: hits, total: hits.length };
         return {
@@ -466,7 +512,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     context: { deviceId },
                 });
             }
-            throw err;
+            return apiErrorToMcpError(err);
         }
     });
     // ---- aggregate_device_history --------------------------------------------
@@ -670,7 +716,7 @@ Inspect locally:
                 if (!Number.isFinite(port) || port < 1 || port > 65535) {
                     const msg = `Invalid --port "${options.port}". Must be 1-65535.`;
                     if (isJsonMode()) {
-                        console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                        emitJsonError({ code: 2, kind: 'usage', message: msg });
                     }
                     else {
                         console.error(msg);
@@ -686,7 +732,7 @@ Inspect locally:
                 if (!isLocalhost && !authToken) {
                     const msg = 'Refusing to listen on 0.0.0.0 without --auth-token. Pass --auth-token <token> or bind to localhost (default).';
                     if (isJsonMode()) {
-                        console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                        emitJsonError({ code: 2, kind: 'usage', message: msg });
                     }
                     else {
                         console.error(msg);

package/dist/commands/plan.js

@@ -191,8 +191,13 @@ Workflow:
     });
     plan
         .command('validate')
-        .description('Validate a plan file (or stdin) against the schema')
+        .description('Validate a plan file (or stdin) against the schema (structural only; does not verify device or scene existence)')
         .argument('[file]', 'Path to plan.json, or "-" / omit to read stdin')
+        .addHelpText('after', `
+To check semantic validity (e.g., that deviceIds and sceneIds actually exist),
+use 'plan run --dry-run' which exercises name resolution and device lookup
+against the live API without executing any mutations.
+`)
         .action(async (file) => {
         let raw;
         try {

package/dist/commands/scenes.js

@@ -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 });

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/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/filter.js

@@ -4,42 +4,109 @@ export class FilterSyntaxError extends Error {
         this.name = 'FilterSyntaxError';
     }
 }
-const VALID_KEYS = ['type', 'family', 'room', 'category'];
 /**
- * Parse a filter expression like "type=Bot,family=Home" into discrete clauses.
+ * Parse a comma-separated filter expression into discrete clauses.
  *
- * Grammar:
- *   expr    := clause ("," clause)*
- *   clause  := KEY OP VALUE
- *   KEY     := type | family | room | category
- *   OP      := "=" | "~="
- *   VALUE   := any non-empty string (no comma — split at the clause boundary)
+ * Grammar (per clause, recognition order):
+ *   1. key=/pattern/   → regex (case-insensitive); invalid regex throws.
+ *   2. key~value       → substring (case-insensitive).
+ *   3. key=value       → 'eq' op (substring; caller decides whether to treat
+ *                        as exact for specific keys via matchClause's
+ *                        `exactKeys` option).
  *
- * Whitespace around keys / values is trimmed. Empty expressions return [].
+ * `allowedKeys` is command-specific: `devices list` uses
+ * {type,name,category,room}; `devices batch` uses {type,family,room,category};
+ * `events tail` uses {deviceId,type}.
  */
-export function parseFilter(expr) {
+export function parseFilterExpr(expr, allowedKeys) {
     if (!expr)
         return [];
     const parts = expr.split(',').map((p) => p.trim()).filter((p) => p.length > 0);
     const clauses = [];
     for (const part of parts) {
-        const m = /^([a-zA-Z_]+)\s*(~=|=)\s*(.+)$/.exec(part);
-        if (!m) {
-            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>" or "<key>~=<pattern>"`);
+        const regexMatch = /^([^=~]+)=\/(.*)\/$/.exec(part);
+        const tildeIdx = part.indexOf('~');
+        const eqIdx = part.indexOf('=');
+        let key;
+        let op;
+        let raw;
+        let regex;
+        if (regexMatch) {
+            key = regexMatch[1].trim();
+            op = 'regex';
+            raw = regexMatch[2];
+            try {
+                regex = new RegExp(raw, 'i');
+            }
+            catch (err) {
+                throw new FilterSyntaxError(`Invalid regex in --filter "${part}": ${err.message}`);
+            }
+        }
+        else if (tildeIdx !== -1 && (eqIdx === -1 || tildeIdx < eqIdx)) {
+            key = part.slice(0, tildeIdx).trim();
+            op = 'sub';
+            raw = part.slice(tildeIdx + 1).trim();
+            if (raw.startsWith('=')) {
+                throw new FilterSyntaxError(`Invalid filter clause "${part}" — "~=" is no longer supported. Use "${key}~${raw.slice(1)}" instead.`);
+            }
+        }
+        else if (eqIdx !== -1) {
+            key = part.slice(0, eqIdx).trim();
+            op = 'eq';
+            raw = part.slice(eqIdx + 1).trim();
         }
-        const key = m[1];
-        const op = m[2];
-        const value = m[3].trim();
-        if (!VALID_KEYS.includes(key)) {
-            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${VALID_KEYS.join(', ')}`);
+        else {
+            throw new FilterSyntaxError(`Invalid filter clause "${part}" — expected "<key>=<value>", "<key>~<value>", or "<key>=/<regex>/"`);
         }
-        if (!value) {
+        if (!key) {
+            throw new FilterSyntaxError(`Empty key in filter clause "${part}"`);
+        }
+        if (!raw) {
             throw new FilterSyntaxError(`Empty value for filter clause "${part}"`);
         }
-        clauses.push({ key, op, value });
+        if (!allowedKeys.includes(key)) {
+            throw new FilterSyntaxError(`Unknown filter key "${key}" — supported: ${allowedKeys.join(', ')}`);
+        }
+        clauses.push({ key, op, raw, regex });
     }
     return clauses;
 }
+/**
+ * Match a single candidate string against a clause.
+ *
+ * - `regex` → RegExp.test against the candidate (case-insensitive by construction).
+ * - `sub`   → case-insensitive substring.
+ * - `eq`    → case-insensitive substring, except for keys listed in
+ *             `exactKeys`, which get case-insensitive exact comparison.
+ *             Default `exactKeys` is `['category']` to preserve the existing
+ *             list/batch behavior for that key.
+ */
+export function matchClause(candidate, clause, options) {
+    if (candidate === undefined)
+        return false;
+    if (clause.op === 'regex') {
+        return clause.regex.test(candidate);
+    }
+    const cLower = candidate.toLowerCase();
+    const vLower = clause.raw.toLowerCase();
+    if (clause.op === 'sub') {
+        return cLower.includes(vLower);
+    }
+    const exactKeys = options?.exactKeys ?? ['category'];
+    if (exactKeys.includes(clause.key)) {
+        return cLower === vLower;
+    }
+    return cLower.includes(vLower);
+}
+const BATCH_KEYS = ['type', 'family', 'room', 'category'];
+/**
+ * Back-compat narrow signature: parses with the batch key set. Callers that
+ * need a different key set (list, events tail) should call parseFilterExpr
+ * directly.
+ */
+export function parseFilter(expr) {
+    return parseFilterExpr(expr, BATCH_KEYS);
+}
 /** Normalize a physical / IR device entry to the shape the filter matcher expects. */
 function toFilterable(d, isPhysical, hubLocation) {
     if (isPhysical) {
@@ -62,27 +129,23 @@ function toFilterable(d, isPhysical, hubLocation) {
         category: 'ir',
     };
 }
-function matches(d, clause) {
-    const candidate = clause.key === 'type'
-        ? d.type
-        : clause.key === 'family'
-            ? d.family
-            : clause.key === 'room'
-                ? d.room
-                : d.category;
-    if (candidate === undefined)
-        return false;
-    if (clause.op === '=')
-        return candidate.toLowerCase() === clause.value.toLowerCase();
-    // '~=' — case-insensitive substring match on the candidate.
-    return candidate.toLowerCase().includes(clause.value.toLowerCase());
+function candidateFor(d, key) {
+    switch (key) {
+        case 'type':
+            return d.type;
+        case 'family':
+            return d.family;
+        case 'room':
+            return d.room;
+        case 'category':
+            return d.category;
+        default:
+            return undefined;
+    }
 }
 /**
  * Apply the parsed clauses to a mixed list of physical devices + IR remotes.
- * Returns the deviceIds of the entries that satisfy every clause.
- *
- * `hubLocation` (optional) allows family/room filters to match IR remotes by
- * the Hub-inherited location.
+ * Returns the filterable entries that satisfy every clause.
  */
 export function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation) {
     const candidates = [
@@ -91,5 +154,5 @@ export function applyFilter(clauses, deviceList, infraredRemoteList, hubLocation
     ];
     if (clauses.length === 0)
         return candidates;
-    return candidates.filter((c) => clauses.every((clause) => matches(c, clause)));
+    return candidates.filter((c) => clauses.every((clause) => matchClause(candidateFor(c, clause.key), clause)));
 }

package/dist/utils/flags.js

@@ -92,7 +92,7 @@ export function isQuotaDisabled() {
 }
 const DEFAULT_LIST_TTL_MS = 60 * 60 * 1000;
 function parseDurationToMs(v) {
-    const m = /^(\d+)(ms|s|m|h)?$/.exec(v.trim().toLowerCase());
+    const m = /^(\d+)(ms|s|m|h|d|w)?$/.exec(v.trim().toLowerCase());
     if (!m)
         return null;
     const n = Number(m[1]);
@@ -104,6 +104,8 @@ function parseDurationToMs(v) {
         case 's': return n * 1000;
         case 'm': return n * 60 * 1000;
         case 'h': return n * 60 * 60 * 1000;
+        case 'd': return n * 24 * 60 * 60 * 1000;
+        case 'w': return n * 7 * 24 * 60 * 60 * 1000;
         default: return null;
     }
 }

package/dist/utils/format.js

@@ -1,4 +1,4 @@
-import { printTable, printJson, isJsonMode, UsageError } from './output.js';
+import { printTable, printJson, isJsonMode, UsageError, emitJsonError } from './output.js';
 import { getFormat, getFields } from './flags.js';
 import { dump as yamlDump } from 'js-yaml';
 export function parseFormat(flag) {
@@ -16,7 +16,7 @@ export function parseFormat(flag) {
         default: {
             const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id, markdown.`;
             if (isJsonMode()) {
-                console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
+                emitJsonError({ code: 2, kind: 'usage', message: msg });
             }
             else {
                 console.error(msg);

package/dist/utils/name-resolver.js

@@ -2,7 +2,7 @@ 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';
-const ALL_STRATEGIES = [
+export const ALL_STRATEGIES = [
     'exact', 'prefix', 'substring', 'fuzzy', 'first', 'require-unique',
 ];
 export function isValidStrategy(s) {