@switchbot/openapi-cli 2.2.1 → 2.4.0

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;
+}
+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/devices/param-validator.js

@@ -0,0 +1,263 @@
+import { UsageError } from '../utils/output.js';
+export const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
+export const AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
+export const CURTAIN_MODE_MAP = { default: 'ff', performance: '0', silent: '1' };
+export const RELAY_MODE_MAP = { toggle: 0, edge: 1, detached: 2, momentary: 3 };
+const BLIND_DIRECTION = new Set(['up', 'down']);
+// ---- Semantic-flag builders (used by `devices expand`) --------------------
+export function buildAcSetAll(opts) {
+    if (!opts.temp)
+        throw new UsageError('--temp is required for setAll (e.g. --temp 26)');
+    if (!opts.mode)
+        throw new UsageError('--mode is required for setAll (auto|cool|dry|fan|heat)');
+    if (!opts.fan)
+        throw new UsageError('--fan is required for setAll (auto|low|mid|high)');
+    if (!opts.power)
+        throw new UsageError('--power is required for setAll (on|off)');
+    const temp = parseInt(opts.temp, 10);
+    if (!Number.isFinite(temp) || temp < 16 || temp > 30) {
+        throw new UsageError(`--temp must be an integer between 16 and 30 (got "${opts.temp}")`);
+    }
+    const modeInt = AC_MODE_MAP[opts.mode.toLowerCase()];
+    if (modeInt === undefined) {
+        throw new UsageError(`--mode must be one of: auto, cool, dry, fan, heat (got "${opts.mode}")`);
+    }
+    const fanInt = AC_FAN_MAP[opts.fan.toLowerCase()];
+    if (fanInt === undefined) {
+        throw new UsageError(`--fan must be one of: auto, low, mid, high (got "${opts.fan}")`);
+    }
+    const power = opts.power.toLowerCase();
+    if (power !== 'on' && power !== 'off') {
+        throw new UsageError(`--power must be "on" or "off" (got "${opts.power}")`);
+    }
+    return `${temp},${modeInt},${fanInt},${power}`;
+}
+export function buildCurtainSetPosition(opts) {
+    if (!opts.position)
+        throw new UsageError('--position is required (0-100)');
+    const pos = parseInt(opts.position, 10);
+    if (!Number.isFinite(pos) || pos < 0 || pos > 100) {
+        throw new UsageError(`--position must be an integer between 0 and 100 (got "${opts.position}")`);
+    }
+    const modeStr = opts.mode ? CURTAIN_MODE_MAP[opts.mode.toLowerCase()] : 'ff';
+    if (modeStr === undefined) {
+        throw new UsageError(`--mode must be one of: default, performance, silent (got "${opts.mode}")`);
+    }
+    return `0,${modeStr},${pos}`;
+}
+export function buildBlindTiltSetPosition(opts) {
+    if (!opts.direction)
+        throw new UsageError('--direction is required (up|down)');
+    if (!opts.angle)
+        throw new UsageError('--angle is required (0-100)');
+    const dir = opts.direction.toLowerCase();
+    if (!BLIND_DIRECTION.has(dir)) {
+        throw new UsageError(`--direction must be "up" or "down" (got "${opts.direction}")`);
+    }
+    const angle = parseInt(opts.angle, 10);
+    if (!Number.isFinite(angle) || angle < 0 || angle > 100) {
+        throw new UsageError(`--angle must be an integer between 0 and 100 (got "${opts.angle}")`);
+    }
+    return `${dir};${angle}`;
+}
+export function buildRelaySetMode(opts) {
+    if (!opts.channel)
+        throw new UsageError('--channel is required (1 or 2)');
+    if (!opts.mode)
+        throw new UsageError('--mode is required (toggle|edge|detached|momentary)');
+    const ch = parseInt(opts.channel, 10);
+    if (ch !== 1 && ch !== 2) {
+        throw new UsageError(`--channel must be 1 or 2 (got "${opts.channel}")`);
+    }
+    const modeInt = RELAY_MODE_MAP[opts.mode.toLowerCase()];
+    if (modeInt === undefined) {
+        throw new UsageError(`--mode must be one of: toggle, edge, detached, momentary (got "${opts.mode}")`);
+    }
+    return `${ch};${modeInt}`;
+}
+/**
+ * Validate a raw wire-format parameter string for (deviceType, command)
+ * combos where the shape is well-defined. Unknown combos pass through so
+ * `devices command` remains a usable escape hatch for types/commands the
+ * CLI hasn't modelled yet.
+ *
+ * On passthrough, `normalized` is left undefined so the caller keeps the
+ * original parameter value (preserving the `undefined → "default"` default
+ * for no-arg commands).
+ */
+export function validateParameter(deviceType, command, raw) {
+    if (!deviceType)
+        return { ok: true };
+    if (deviceType === 'Air Conditioner' && command === 'setAll') {
+        return validateAcSetAll(raw);
+    }
+    if (deviceType.startsWith('Curtain') && command === 'setPosition') {
+        return validateCurtainSetPosition(raw);
+    }
+    if (deviceType.startsWith('Blind Tilt') && command === 'setPosition') {
+        return validateBlindTiltSetPosition(raw);
+    }
+    if (deviceType.startsWith('Relay Switch') && command === 'setMode') {
+        return validateRelaySetMode(raw);
+    }
+    return { ok: true };
+}
+function validateAcSetAll(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setAll requires a parameter "<temp>,<mode>,<fan>,<on|off>". Example: "26,2,2,on".`,
+        };
+    }
+    if (raw.startsWith('{') || raw.startsWith('[')) {
+        return {
+            ok: false,
+            error: `setAll parameter must be a CSV string like "26,2,2,on", not JSON (got ${JSON.stringify(raw)}).`,
+        };
+    }
+    const parts = raw.split(',');
+    if (parts.length !== 4) {
+        return {
+            ok: false,
+            error: `setAll expects 4 comma-separated fields "<temp>,<mode>,<fan>,<on|off>", got ${parts.length} (${JSON.stringify(raw)}). Example: "26,2,2,on".`,
+        };
+    }
+    const [tempStr, modeStr, fanStr, powerStr] = parts.map((s) => s.trim());
+    const temp = Number(tempStr);
+    if (!Number.isInteger(temp) || temp < 16 || temp > 30) {
+        return {
+            ok: false,
+            error: `setAll field 1 (temp) must be an integer 16-30, got "${tempStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const mode = Number(modeStr);
+    if (!Number.isInteger(mode) || mode < 1 || mode > 5) {
+        return {
+            ok: false,
+            error: `setAll field 2 (mode) must be 1-5 (1=auto 2=cool 3=dry 4=fan 5=heat), got "${modeStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const fan = Number(fanStr);
+    if (!Number.isInteger(fan) || fan < 1 || fan > 4) {
+        return {
+            ok: false,
+            error: `setAll field 3 (fan) must be 1-4 (1=auto 2=low 3=mid 4=high), got "${fanStr}". Example: "26,2,2,on".`,
+        };
+    }
+    const power = powerStr.toLowerCase();
+    if (power !== 'on' && power !== 'off') {
+        return {
+            ok: false,
+            error: `setAll field 4 (power) must be "on" or "off", got "${powerStr}". Example: "26,2,2,on".`,
+        };
+    }
+    return { ok: true, normalized: `${temp},${mode},${fan},${power}` };
+}
+function validateCurtainSetPosition(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `setPosition requires a parameter. Expected: "<0-100>" or "<index>,<ff|0|1>,<0-100>". Example: "50" or "0,ff,50".`,
+        };
+    }
+    if (!raw.includes(',')) {
+        const pos = Number(raw);
+        if (!Number.isInteger(pos) || pos < 0 || pos > 100) {
+            return {
+                ok: false,
+                error: `setPosition must be an integer 0-100, got "${raw}". Example: "50".`,
+            };
+        }
+        return { ok: true, normalized: String(pos) };
+    }
+    const parts = raw.split(',').map((s) => s.trim());
+    if (parts.length !== 3) {
+        return {
+            ok: false,
+            error: `setPosition tuple form expects 3 comma-separated fields "<index>,<ff|0|1>,<0-100>", got ${parts.length} (${JSON.stringify(raw)}).`,
+        };
+    }
+    const [idxStr, modeStr, posStr] = parts;
+    const idx = Number(idxStr);
+    if (!Number.isInteger(idx) || idx < 0) {
+        return {
+            ok: false,
+            error: `setPosition field 1 (index) must be a non-negative integer, got "${idxStr}".`,
+        };
+    }
+    const modeLower = modeStr.toLowerCase();
+    if (!['ff', '0', '1'].includes(modeLower)) {
+        return {
+            ok: false,
+            error: `setPosition field 2 (mode) must be "ff", "0", or "1", got "${modeStr}". (ff=default, 0=performance, 1=silent)`,
+        };
+    }
+    const pos = Number(posStr);
+    if (!Number.isInteger(pos) || pos < 0 || pos > 100) {
+        return {
+            ok: false,
+            error: `setPosition field 3 (position) must be an integer 0-100, got "${posStr}".`,
+        };
+    }
+    return { ok: true, normalized: `${idx},${modeLower},${pos}` };
+}
+function validateBlindTiltSetPosition(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition requires a parameter. Expected: "<up|down>;<0-100>". Example: "up;50".`,
+        };
+    }
+    const parts = raw.split(';');
+    if (parts.length !== 2) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition expects "<up|down>;<angle>", got ${JSON.stringify(raw)}. Example: "up;50".`,
+        };
+    }
+    const dir = parts[0].toLowerCase();
+    if (!BLIND_DIRECTION.has(dir)) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition direction must be "up" or "down", got "${parts[0]}".`,
+        };
+    }
+    const angle = Number(parts[1]);
+    if (!Number.isInteger(angle) || angle < 0 || angle > 100) {
+        return {
+            ok: false,
+            error: `Blind Tilt setPosition angle must be an integer 0-100, got "${parts[1]}".`,
+        };
+    }
+    return { ok: true, normalized: `${dir};${angle}` };
+}
+function validateRelaySetMode(raw) {
+    if (raw === undefined || raw === '' || raw === 'default') {
+        return {
+            ok: false,
+            error: `Relay Switch setMode requires a parameter. Expected: "<1|2>;<0|1|2|3>". Example: "1;1" (channel 1, edge mode).`,
+        };
+    }
+    const parts = raw.split(';');
+    if (parts.length !== 2) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode expects "<channel>;<mode>", got ${JSON.stringify(raw)}. Example: "1;1".`,
+        };
+    }
+    const ch = Number(parts[0]);
+    if (ch !== 1 && ch !== 2) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode channel must be 1 or 2, got "${parts[0]}".`,
+        };
+    }
+    const mode = Number(parts[1]);
+    if (!Number.isInteger(mode) || mode < 0 || mode > 3) {
+        return {
+            ok: false,
+            error: `Relay Switch setMode mode must be 0-3 (0=toggle 1=edge 2=detached 3=momentary), got "${parts[1]}".`,
+        };
+    }
+    return { ok: true, normalized: `${ch};${mode}` };
+}

package/dist/index.js

@@ -18,6 +18,7 @@ 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');
 const program = new Command();
@@ -26,7 +27,7 @@ const program = new Command();
 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('-')) {
@@ -44,8 +45,9 @@ program
     .description('Command-line tool for SwitchBot API v1.1')
     .version(pkgVersion)
     .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 +78,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 +133,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,13 +124,22 @@ 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.
  * Returns `{ ok: true }` when validation passes or is skipped (unknown device,
- * custom IR button, etc.); returns `{ ok: false, error }` when the caller
- * should refuse the call.
+ * custom IR button, etc.). On a case-only mismatch the canonical command name
+ * is returned via `normalized` along with a `caseNormalizedFrom` field so the
+ * caller can emit a warning and continue with the canonical name.
+ * Returns `{ ok: false, error }` only when the caller should refuse the call.
  */
 export function validateCommand(deviceId, cmd, parameter, commandType) {
     if (commandType === 'customize')
@@ -144,24 +153,34 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
     const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
     if (builtinCommands.length === 0)
         return { ok: true };
-    const spec = builtinCommands.find((c) => c.command === cmd);
+    let spec = builtinCommands.find((c) => c.command === cmd);
+    let caseNormalizedFrom;
+    let normalizedCmd = cmd;
     if (!spec) {
         const unique = [...new Set(builtinCommands.map((c) => c.command))];
         const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
-        const hint = caseMatch
-            ? `Did you mean "${caseMatch}"? Supported commands: ${unique.join(', ')}`
-            : `Supported commands: ${unique.join(', ')}`;
-        return {
-            ok: false,
-            error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
-        };
+        if (caseMatch) {
+            // Case-only mismatch: normalize and continue.
+            caseNormalizedFrom = cmd;
+            normalizedCmd = caseMatch;
+            spec = builtinCommands.find((c) => c.command === caseMatch);
+        }
+        else {
+            const hint = `Supported commands: ${unique.join(', ')}`;
+            return {
+                ok: false,
+                error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
+            };
+        }
     }
+    if (!spec)
+        return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
     const noParamExpected = spec.parameter === '—';
     const userProvidedParam = parameter !== undefined && parameter !== 'default';
     if (noParamExpected && userProvidedParam) {
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${cmd}`),
+            error: new CommandValidationError(`"${normalizedCmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${normalizedCmd}`),
         };
     }
     // Warn when a parameter is required but the user omitted it
@@ -170,12 +189,12 @@ export function validateCommand(deviceId, cmd, parameter, commandType) {
         const example = spec.exampleParams?.[0];
         return {
             ok: false,
-            error: new CommandValidationError(`"${cmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
-                ? `Example: switchbot devices command <deviceId> ${cmd} "${example}"`
+            error: new CommandValidationError(`"${normalizedCmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
+                ? `Example: switchbot devices command <deviceId> ${normalizedCmd} "${example}"`
                 : `See: switchbot devices commands ${cached.type}`),
         };
     }
-    return { ok: true };
+    return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
 }
 /**
  * Inspect catalog annotations to decide whether a command is destructive,