@switchbot/openapi-cli 2.2.1 → 2.4.0

package/dist/commands/devices.js

@@ -6,6 +6,7 @@ import { getCachedDevice } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, buildHubLocationMap, DeviceNotFoundError, } from '../lib/devices.js';
+import { validateParameter } from '../devices/param-validator.js';
 import { registerBatchCommand } from './batch.js';
 import { registerWatchCommand } from './watch.js';
 import { registerExplainCommand } from './explain.js';
@@ -199,6 +200,10 @@ Examples:
         .description('Query the real-time status of a specific device')
         .argument('[deviceId]', 'Device ID from "devices list" (or use --name or --ids)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--ids <list>', 'Comma-separated device IDs for batch status (incompatible with --name)', stringArg('--ids'))
         .addHelpText('after', `
 Status fields vary by device type. To discover them without a live call:
@@ -260,7 +265,12 @@ Examples:
                 }
                 return;
             }
-            const deviceId = resolveDeviceId(deviceIdArg, options.name);
+            const deviceId = resolveDeviceId(deviceIdArg, options.name, {
+                strategy: options.nameStrategy ?? 'fuzzy',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             const body = await fetchDeviceStatus(deviceId);
             const fetchedAt = new Date().toISOString();
             const fmt = resolveFormat();
@@ -291,6 +301,10 @@ Examples:
         .argument('[cmd]', 'Command name, e.g. turnOn, turnOff, setColor, setBrightness, setAll, startClean')
         .argument('[parameter]', 'Command parameter. Omit for commands like turnOn/turnOff (defaults to "default"). Format depends on the command (see below).')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default for command: require-unique)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type (e.g. "Bot", "Color Bulb")', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--type <commandType>', 'Command type: "command" for built-in commands (default), "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--yes', 'Confirm a destructive command (Smart Lock unlock, Garage open, …). --dry-run is always allowed without --yes.')
         .option('--idempotency-key <key>', 'Idempotency key for deduplication (60s window; same key replays cached result)', stringArg('--idempotency-key'))
@@ -341,19 +355,22 @@ Examples:
 `)
         .action(async (deviceIdArg, cmdArg, parameter, options) => {
         try {
-            // BUG-FIX: When --name is provided, Commander misassigns the first positional
-            // to [deviceId] instead of [cmd]. Detect and shift positionals accordingly.
+            // BUG-FIX: When --name is provided, Commander fills positionals left-to-right
+            // starting at [deviceId]. Shift them back to their semantic slots.
             let cmd;
             let effectiveDeviceIdArg;
             if (options.name) {
-                if (deviceIdArg && cmdArg) {
-                    throw new UsageError('Provide either a deviceId argument or --name, not both.');
-                }
-                if (!deviceIdArg && !cmdArg) {
+                // `--name "x" <cmd> [parameter]` → Commander binds deviceIdArg=<cmd>, cmdArg=[parameter].
+                if (!deviceIdArg) {
                     throw new UsageError('Command name is required (e.g. turnOn, turnOff, setAll).');
                 }
-                // --name "x" turnOn  →  deviceIdArg="turnOn", cmdArg=undefined → shift
-                cmd = (deviceIdArg ?? cmdArg);
+                cmd = deviceIdArg;
+                if (cmdArg !== undefined) {
+                    if (parameter !== undefined) {
+                        throw new UsageError('Too many positional arguments after --name. Expected: --name <query> <cmd> [parameter].');
+                    }
+                    parameter = cmdArg;
+                }
                 effectiveDeviceIdArg = undefined;
             }
             else {
@@ -363,7 +380,13 @@ Examples:
                 cmd = cmdArg;
                 effectiveDeviceIdArg = deviceIdArg;
             }
-            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name);
+            const deviceId = resolveDeviceId(effectiveDeviceIdArg, options.name, {
+                // Mutating command → default require-unique (never silently pick between ambiguous matches).
+                strategy: options.nameStrategy ?? 'require-unique',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             if (!getCachedDevice(deviceId)) {
                 console.error(`Note: device ${deviceId} is not in the local cache — run 'switchbot devices list' first to enable command validation.`);
             }
@@ -391,6 +414,37 @@ Examples:
                 }
                 process.exit(2);
             }
+            // Case-only mismatch: emit a warning and continue with the canonical name.
+            if (validation.caseNormalizedFrom && validation.normalized) {
+                console.error(`Note: '${validation.caseNormalizedFrom}' normalized to '${validation.normalized}' (case mismatch). Use exact casing to silence this warning.`);
+                cmd = validation.normalized;
+            }
+            else if (validation.normalized) {
+                cmd = validation.normalized;
+            }
+            // Raw-parameter validation (runs for known (deviceType, command) pairs only).
+            const cachedForParam = getCachedDevice(deviceId);
+            if (cachedForParam && options.type === 'command') {
+                const paramCheck = validateParameter(cachedForParam.type, cmd, parameter);
+                if (!paramCheck.ok) {
+                    if (isJsonMode()) {
+                        console.error(JSON.stringify({
+                            error: {
+                                code: 2,
+                                kind: 'usage',
+                                message: paramCheck.error,
+                                context: { command: cmd, deviceType: cachedForParam.type, deviceId },
+                            },
+                        }));
+                    }
+                    else {
+                        console.error(`Error: ${paramCheck.error}`);
+                    }
+                    process.exit(2);
+                }
+                if (paramCheck.normalized !== undefined)
+                    parameter = paramCheck.normalized;
+            }
             const cachedForGuard = getCachedDevice(deviceId);
             if (!options.yes &&
                 !isDryRun() &&
@@ -434,10 +488,19 @@ Examples:
             }
             const body = await executeCommand(deviceId, cmd, parsedParam, options.type, undefined, { idempotencyKey: options.idempotencyKey });
             const isIr = getCachedDevice(deviceId)?.category === 'ir';
+            const verification = isIr
+                ? {
+                    verifiable: false,
+                    reason: 'IR transmission is unidirectional; no receipt acknowledgment is possible.',
+                    suggestedFollowup: 'Confirm visible change manually or via a paired state sensor.',
+                }
+                : null;
             if (isJsonMode()) {
                 const result = { ok: true, command: cmd, deviceId };
-                if (isIr)
+                if (isIr) {
                     result.subKind = 'ir-no-feedback';
+                    result.verification = verification;
+                }
                 if (body && typeof body === 'object' && Object.keys(body).length > 0) {
                     Object.assign(result, body);
                 }
@@ -446,6 +509,7 @@ Examples:
             }
             if (isIr) {
                 console.log(`→ IR signal sent: ${cmd} (no feedback — fire-and-forget)`);
+                console.error('⚠ IR (unverifiable) — no receipt acknowledgment. Confirm state manually.');
             }
             else {
                 console.log(`✓ Command sent: ${cmd}`);
@@ -546,6 +610,10 @@ Examples:
         .description('Describe a device by ID: metadata + supported commands + status fields (1 API call)')
         .argument('[deviceId]', 'Target device ID (or use --name)')
         .option('--name <query>', 'Resolve device by fuzzy name instead of deviceId', stringArg('--name'))
+        .option('--name-strategy <s>', 'Name match strategy: exact|prefix|substring|fuzzy|first|require-unique (default: fuzzy)', stringArg('--name-strategy'))
+        .option('--name-type <type>', 'Narrow --name by device type', stringArg('--name-type'))
+        .option('--name-category <cat>', 'Narrow --name by category: physical|ir', enumArg('--name-category', ['physical', 'ir']))
+        .option('--name-room <room>', 'Narrow --name by room name (substring match)', stringArg('--name-room'))
         .option('--live', 'Also fetch live status values and merge them into capabilities (costs 1 extra API call)')
         .addHelpText('after', `
 Makes a GET /v1.1/devices call to look up the device's type, then prints its
@@ -577,7 +645,12 @@ Examples:
 `)
         .action(async (deviceIdArg, options) => {
         try {
-            const deviceId = resolveDeviceId(deviceIdArg, options.name);
+            const deviceId = resolveDeviceId(deviceIdArg, options.name, {
+                strategy: options.nameStrategy ?? 'fuzzy',
+                type: options.nameType,
+                category: options.nameCategory,
+                room: options.nameRoom,
+            });
             const result = await describeDevice(deviceId, options);
             const { device, isPhysical, typeName, controlType, catalog, capabilities, source, suggestedActions: picks } = result;
             if (isJsonMode()) {

package/dist/commands/doctor.js

@@ -3,8 +3,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { printJson, isJsonMode } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
-import { configFilePath, listProfiles } from '../config.js';
+import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
 import { describeCache } from '../devices/cache.js';
+export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
     if (envOk)
@@ -39,21 +40,97 @@ function checkProfiles() {
         return { name: 'profiles', status: 'ok', detail: 'no profile dir (default profile only)' };
     }
     const profiles = listProfiles();
+    if (profiles.length === 0) {
+        return { name: 'profiles', status: 'ok', detail: 'profile dir empty' };
+    }
+    const labelled = profiles.map((p) => {
+        const meta = readProfileMeta(p);
+        if (meta?.label)
+            return `${p} (${meta.label})`;
+        return p;
+    });
     return {
         name: 'profiles',
         status: 'ok',
-        detail: profiles.length ? `found ${profiles.length}: ${profiles.join(', ')}` : 'profile dir empty',
+        detail: `found ${profiles.length}: ${labelled.join(', ')}`,
     };
 }
-function checkClockSkew() {
-    const now = Date.now();
-    const drift = now - Math.floor(now / 1000) * 1000;
-    // HMAC signing uses ms timestamps — we can't detect remote skew without a
-    // round-trip, but we can flag if the local clock has NTP issues via the
-    // classic "jumps back" pattern. Best-effort: just report local time.
-    const iso = new Date().toISOString();
-    return { name: 'clock', status: 'ok', detail: `local time ${iso} (drift check needs API round-trip)` };
-    void drift;
+async function checkClockSkew() {
+    // Real probe: HEAD the SwitchBot API endpoint and compare the server's Date
+    // header against local time. No auth required for the Date header — the API
+    // returns 401 but still stamps the response. Gracefully degrades to
+    // probeSource:'none' if offline / no network reachable.
+    //
+    // Under vitest, only run the probe if fetch has been stubbed (detected via
+    // vi.fn marker) — otherwise skip network I/O to keep unrelated tests fast.
+    const underVitest = Boolean(process.env.VITEST);
+    const fetchFn = globalThis.fetch;
+    const fetchIsMocked = Boolean(fetchFn && typeof fetchFn === 'function' && 'mock' in fetchFn);
+    if (underVitest && !fetchIsMocked) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: { probeSource: 'none', skewMs: null, message: 'skipped: test environment' },
+        };
+    }
+    const localBefore = Date.now();
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), 2500);
+    try {
+        const res = await fetch('https://api.switch-bot.com/v1.1/devices', {
+            method: 'HEAD',
+            signal: ctrl.signal,
+        });
+        const localAfter = Date.now();
+        const dateHeader = res.headers.get('date');
+        if (!dateHeader) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: 'server returned no Date header' },
+            };
+        }
+        const serverMs = Date.parse(dateHeader);
+        if (!Number.isFinite(serverMs)) {
+            return {
+                name: 'clock',
+                status: 'warn',
+                detail: { probeSource: 'api', skewMs: null, message: `unparseable Date header: ${dateHeader}` },
+            };
+        }
+        // Split the round-trip in half to estimate the local instant that matches
+        // the server's Date header. HTTP Date resolution is 1s, so treat anything
+        // under 2000ms as ok, 2000–60000ms as warn, beyond that as fail (HMAC
+        // auth rejects requests with skew > 5 minutes anyway).
+        const midpoint = (localBefore + localAfter) / 2;
+        const skewMs = Math.round(midpoint - serverMs);
+        const absSkew = Math.abs(skewMs);
+        const status = absSkew < 2000 ? 'ok' : absSkew < 60_000 ? 'warn' : 'fail';
+        return {
+            name: 'clock',
+            status,
+            detail: {
+                probeSource: 'api',
+                skewMs,
+                localIso: new Date(midpoint).toISOString(),
+                serverIso: new Date(serverMs).toISOString(),
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'clock',
+            status: 'warn',
+            detail: {
+                probeSource: 'none',
+                skewMs: null,
+                message: `probe failed: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
+    }
+    finally {
+        clearTimeout(timer);
+    }
 }
 function checkCatalog() {
     const catalog = getEffectiveCatalog();
@@ -153,7 +230,7 @@ Examples:
             checkCatalog(),
             checkCache(),
             checkQuotaFile(),
-            checkClockSkew(),
+            await checkClockSkew(),
             checkMqtt(),
         ];
         const summary = {
@@ -162,13 +239,27 @@ Examples:
             fail: checks.filter((c) => c.status === 'fail').length,
         };
         const overallFail = summary.fail > 0;
+        const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
         if (isJsonMode()) {
-            printJson({ overall: overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok', summary, checks });
+            // Stable contract (locked as doctor.schemaVersion=1):
+            //   { ok: boolean, overall: 'ok'|'warn'|'fail', generatedAt, schemaVersion,
+            //     summary: { ok, warn, fail }, checks: [{ name, status, detail }] }
+            // `ok` is an alias of (overall === 'ok') — agents prefer the boolean,
+            // humans prefer the string; both are provided.
+            printJson({
+                ok: overall === 'ok',
+                overall,
+                generatedAt: new Date().toISOString(),
+                schemaVersion: DOCTOR_SCHEMA_VERSION,
+                summary,
+                checks,
+            });
         }
         else {
             for (const c of checks) {
                 const icon = c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗';
-                console.log(`${icon} ${c.name.padEnd(12)} ${c.detail}`);
+                const detailStr = typeof c.detail === 'string' ? c.detail : JSON.stringify(c.detail);
+                console.log(`${icon} ${c.name.padEnd(12)} ${detailStr}`);
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);

package/dist/commands/events.js

@@ -1,4 +1,5 @@
 import http from 'node:http';
+import crypto from 'node:crypto';
 import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
 import { SwitchBotMqttClient } from '../mqtt/client.js';
@@ -16,6 +17,17 @@ import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
+function extractEventId(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    if (typeof p.eventId === 'string' && p.eventId.length > 0)
+        return p.eventId;
+    const ctx = p.context;
+    if (ctx && typeof ctx.eventId === 'string' && ctx.eventId.length > 0)
+        return ctx.eventId;
+    return null;
+}
 function matchFilter(body, filter) {
     if (!filter)
         return true;
@@ -220,7 +232,19 @@ Connects to the SwitchBot MQTT service using your existing credentials
 No additional MQTT configuration required.
 
 Output (JSONL, one event per line):
-  { "t": "<ISO>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+  { "t": "<ISO>", "eventId": "<uuid>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+
+Control records (interleaved, no "payload" field — use type-prefix to filter):
+  { "type": "__connect",     "at": "<ISO>", "eventId": "<uuid>" }   first successful connect
+  { "type": "__reconnect",   "at": "<ISO>", "eventId": "<uuid>" }   connect after a disconnect
+  { "type": "__disconnect",  "at": "<ISO>", "eventId": "<uuid>" }   reconnecting or failed
+
+Reconnect policy: the MQTT client retries with exponential backoff
+(1s → 30s capped, forever) while the credential is still valid; if the
+credential is rejected or 5 consecutive reconnects fail, state goes to
+'failed' and the command exits non-zero so supervisors can restart it.
+QoS is 0 (at-most-once); agents requiring at-least-once delivery should
+fan-out via --sink file and deduplicate by eventId on the consumer side.
 
 Sink types (--sink, repeatable):
   stdout             Print JSONL to stdout (default when no --sink given)
@@ -321,9 +345,14 @@ Examples:
                     parsed = payload.toString('utf-8');
                 }
                 const t = new Date().toISOString();
+                // Every event carries an eventId so downstream sinks / replay tools
+                // can dedupe. If the broker supplied one (some providers do via a
+                // header), prefer that; otherwise synth a UUID locally.
+                const existingId = extractEventId(parsed);
+                const eventId = existingId ?? crypto.randomUUID();
                 if (dispatcher) {
                     const { deviceId, deviceType, text } = parseSinkEvent(parsed);
-                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text };
+                    const sinkEvent = { t, topic: msgTopic, deviceId, deviceType, payload: parsed, text, eventId };
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
                     dispatcher.dispatch(sinkEvent).catch(() => { });
                 }
@@ -331,7 +360,7 @@ Examples:
                     // Default behavior: record history + print to stdout
                     const { deviceId, deviceType } = parseSinkEvent(parsed);
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
-                    const record = { t, topic: msgTopic, payload: parsed };
+                    const record = { t, eventId, topic: msgTopic, payload: parsed };
                     if (isJsonMode()) {
                         printJson(record);
                     }
@@ -345,12 +374,32 @@ Examples:
                 }
             });
             let mqttFailed = false;
+            let hasConnectedBefore = false;
+            const emitControl = (kind) => {
+                const ctl = { type: kind, at: new Date().toISOString(), eventId: crypto.randomUUID() };
+                // Control events always go to stdout as JSONL so consumers that
+                // filter real events by presence of `payload` can skip them.
+                if (isJsonMode()) {
+                    printJson(ctl);
+                }
+                else {
+                    console.log(JSON.stringify(ctl));
+                }
+            };
             const unsubState = client.onStateChange((state) => {
                 if (!isJsonMode()) {
                     console.error(`[${new Date().toLocaleTimeString()}] MQTT state: ${state}`);
                 }
-                if (state === 'failed') {
+                if (state === 'connected') {
+                    emitControl(hasConnectedBefore ? '__reconnect' : '__connect');
+                    hasConnectedBefore = true;
+                }
+                else if (state === 'reconnecting') {
+                    emitControl('__disconnect');
+                }
+                else if (state === 'failed') {
                     mqttFailed = true;
+                    emitControl('__disconnect');
                     if (!isJsonMode()) {
                         console.error('MQTT connection failed permanently (credential expired or reconnect exhausted) — exiting.');
                     }

package/dist/commands/expand.js

@@ -5,83 +5,7 @@ import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../l
 import { isDryRun } from '../utils/flags.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
 import { DryRunSignal } from '../api/client.js';
-// ---- Mapping tables --------------------------------------------------------
-const AC_MODE_MAP = { auto: 1, cool: 2, dry: 3, fan: 4, heat: 5 };
-const AC_FAN_MAP = { auto: 1, low: 2, mid: 3, high: 4 };
-const CURTAIN_MODE_MAP = { default: 'ff', performance: '0', silent: '1' };
-const RELAY_MODE_MAP = { toggle: 0, edge: 1, detached: 2, momentary: 3 };
-const BLIND_DIRECTION = new Set(['up', 'down']);
-// ---- Translators -----------------------------------------------------------
-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}`;
-}
-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}`;
-}
-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}`;
-}
-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}`;
-}
+import { buildAcSetAll, buildCurtainSetPosition, buildBlindTiltSetPosition, buildRelaySetMode, } from '../devices/param-validator.js';
 // ---- Registration ----------------------------------------------------------
 export function registerExpandCommand(devices) {
     devices