@switchbot/openapi-cli 3.2.0 → 3.2.1

package/dist/install/steps.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Install-orchestrator step runner (Phase 3A · F5).
+ *
+ * Each step has a deterministic `execute` and a matching `undo`. The
+ * runner executes steps in order; on any failure it walks the
+ * already-completed steps in reverse and invokes their `undo`. If an
+ * `undo` itself fails, the error is captured and surfaced — the
+ * runner does NOT abort the rollback. The caller gets a full report
+ * and can decide how to surface partial cleanup failures.
+ *
+ * The module is intentionally agnostic of what steps do; consumers
+ * (future `openclaw plugins install`) plug in concrete steps like
+ * "npm i -g the CLI" or "write the credential to the keychain".
+ */
+export interface InstallStep<Ctx = unknown> {
+    name: string;
+    description?: string;
+    execute: (ctx: Ctx) => Promise<void> | void;
+    undo: (ctx: Ctx) => Promise<void> | void;
+}
+export type StepOutcome = {
+    step: string;
+    status: 'succeeded';
+} | {
+    step: string;
+    status: 'failed';
+    error: string;
+} | {
+    step: string;
+    status: 'rolled-back';
+} | {
+    step: string;
+    status: 'rollback-failed';
+    error: string;
+} | {
+    step: string;
+    status: 'skipped';
+};
+export interface InstallReport {
+    ok: boolean;
+    /** Outcome entries in execution order (execution first, then rollback). */
+    outcomes: StepOutcome[];
+    /** Name of the step that caused the rollback, if any. */
+    failedAt?: string;
+}
+export interface RunInstallOptions<Ctx> {
+    /** Context object passed to every step. Defaults to `{}`. */
+    context?: Ctx;
+    /**
+     * When set, the runner stops immediately after executing this step
+     * (even on success). Useful for tests that want to exercise partial
+     * state without needing every step to succeed.
+     */
+    stopAfter?: string;
+}
+/**
+ * Run the given steps in order. On the first failure, the runner
+ * walks already-executed steps in reverse and invokes each step's
+ * undo. Returns a report describing every step's fate.
+ */
+export declare function runInstall<Ctx = Record<string, unknown>>(steps: InstallStep<Ctx>[], options?: RunInstallOptions<Ctx>): Promise<InstallReport>;

package/dist/install/steps.js

@@ -0,0 +1,68 @@
+/**
+ * Install-orchestrator step runner (Phase 3A · F5).
+ *
+ * Each step has a deterministic `execute` and a matching `undo`. The
+ * runner executes steps in order; on any failure it walks the
+ * already-completed steps in reverse and invokes their `undo`. If an
+ * `undo` itself fails, the error is captured and surfaced — the
+ * runner does NOT abort the rollback. The caller gets a full report
+ * and can decide how to surface partial cleanup failures.
+ *
+ * The module is intentionally agnostic of what steps do; consumers
+ * (future `openclaw plugins install`) plug in concrete steps like
+ * "npm i -g the CLI" or "write the credential to the keychain".
+ */
+/**
+ * Run the given steps in order. On the first failure, the runner
+ * walks already-executed steps in reverse and invokes each step's
+ * undo. Returns a report describing every step's fate.
+ */
+export async function runInstall(steps, options = {}) {
+    const ctx = (options.context ?? {});
+    const outcomes = [];
+    const executed = [];
+    let failedAt;
+    for (const step of steps) {
+        try {
+            await step.execute(ctx);
+            outcomes.push({ step: step.name, status: 'succeeded' });
+            executed.push(step);
+        }
+        catch (err) {
+            outcomes.push({
+                step: step.name,
+                status: 'failed',
+                error: err instanceof Error ? err.message : String(err),
+            });
+            failedAt = step.name;
+            break;
+        }
+        if (options.stopAfter === step.name)
+            break;
+    }
+    if (failedAt !== undefined) {
+        // Roll back completed steps in reverse. Undo failures are captured
+        // but do not abort further rollback attempts — the goal is to
+        // leave as little residue as possible.
+        for (let i = executed.length - 1; i >= 0; i--) {
+            const step = executed[i];
+            try {
+                await step.undo(ctx);
+                outcomes.push({ step: step.name, status: 'rolled-back' });
+            }
+            catch (err) {
+                outcomes.push({
+                    step: step.name,
+                    status: 'rollback-failed',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+    return {
+        ok: failedAt === undefined,
+        outcomes,
+        ...(failedAt !== undefined ? { failedAt } : {}),
+    };
+}
+//# sourceMappingURL=steps.js.map

package/dist/install/steps.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"steps.js","sourceRoot":"","sources":["../../src/install/steps.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAmCH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,UAAU,CAC9B,KAAyB,EACzB,UAAkC,EAAE;IAEpC,MAAM,GAAG,GAAG,CAAC,OAAO,CAAC,OAAO,IAAK,EAAU,CAAQ,CAAC;IACpD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IACnC,MAAM,QAAQ,GAAuB,EAAE,CAAC;IAExC,IAAI,QAA4B,CAAC;IAEjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,IAAI,CAAC;YACH,MAAM,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;YACxB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;YACxD,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,QAAQ,CAAC,IAAI,CAAC;gBACZ,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,MAAM,EAAE,QAAQ;gBAChB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;YACH,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC;YACrB,MAAM;QACR,CAAC;QACD,IAAI,OAAO,CAAC,SAAS,KAAK,IAAI,CAAC,IAAI;YAAE,MAAM;IAC7C,CAAC;IAED,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,mEAAmE;QACnE,8DAA8D;QAC9D,uCAAuC;QACvC,KAAK,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC9C,MAAM,IAAI,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;YACzB,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;gBACrB,QAAQ,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,aAAa,EAAE,CAAC,CAAC;YAC5D,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC;oBACZ,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,MAAM,EAAE,iBAAiB;oBACzB,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;iBACxD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,QAAQ,KAAK,SAAS;QAC1B,QAAQ;QACR,GAAG,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KAChD,CAAC;AACJ,CAAC"}

package/dist/lib/command-keywords.d.ts

@@ -0,0 +1,5 @@
+export declare const COMMAND_KEYWORDS: Array<{
+    pattern: RegExp;
+    command: string;
+}>;
+export declare function inferCommandFromIntent(intent: string): string | undefined;

package/dist/lib/command-keywords.js

@@ -0,0 +1,18 @@
+export const COMMAND_KEYWORDS = [
+    { pattern: /\boff\b|\bturn.?off\b|\bstop\b/i, command: 'turnOff' },
+    { pattern: /\bon\b|\bturn.?on\b|\bstart\b/i, command: 'turnOn' },
+    { pattern: /\bpress\b|\bclick\b|\btap\b/i, command: 'press' },
+    { pattern: /\block\b/i, command: 'lock' },
+    { pattern: /\bunlock\b/i, command: 'unlock' },
+    { pattern: /\bopen\b|\braise\b|\bup\b/i, command: 'open' },
+    { pattern: /\bclose\b|\blower\b|\bdown\b/i, command: 'close' },
+    { pattern: /\bpause\b/i, command: 'pause' },
+];
+export function inferCommandFromIntent(intent) {
+    for (const k of COMMAND_KEYWORDS) {
+        if (k.pattern.test(intent))
+            return k.command;
+    }
+    return undefined;
+}
+//# sourceMappingURL=command-keywords.js.map

package/dist/lib/command-keywords.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"command-keywords.js","sourceRoot":"","sources":["../../src/lib/command-keywords.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,gBAAgB,GAAgD;IAC3E,EAAE,OAAO,EAAE,iCAAiC,EAAE,OAAO,EAAE,SAAS,EAAE;IAClE,EAAE,OAAO,EAAE,gCAAgC,EAAE,OAAO,EAAE,QAAQ,EAAE;IAChE,EAAE,OAAO,EAAE,8BAA8B,EAAE,OAAO,EAAE,OAAO,EAAE;IAC7D,EAAE,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,EAAE;IACzC,EAAE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,QAAQ,EAAE;IAC7C,EAAE,OAAO,EAAE,4BAA4B,EAAE,OAAO,EAAE,MAAM,EAAE;IAC1D,EAAE,OAAO,EAAE,+BAA+B,EAAE,OAAO,EAAE,OAAO,EAAE;IAC9D,EAAE,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE;CAC5C,CAAC;AAEF,MAAM,UAAU,sBAAsB,CAAC,MAAc;IACnD,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACjC,IAAI,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,CAAC,CAAC,OAAO,CAAC;IAC/C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}

package/dist/lib/daemon-state.d.ts

@@ -0,0 +1,24 @@
+export declare const DAEMON_PID_FILE: string;
+export declare const DAEMON_LOG_FILE: string;
+export declare const DAEMON_STATE_FILE: string;
+export declare const HEALTHZ_PID_FILE: string;
+export interface DaemonState {
+    status: 'starting' | 'running' | 'stopped' | 'failed';
+    pid: number | null;
+    startedAt?: string;
+    stoppedAt?: string;
+    failedAt?: string;
+    failureReason?: string;
+    logFile: string;
+    pidFile: string;
+    stateFile: string;
+    healthzPid?: number | null;
+    healthzPort?: number | null;
+    healthzPidFile?: string;
+    lastReloadAt?: string;
+    lastReloadStatus?: 'ok' | 'failed';
+    lastReloadMessage?: string;
+}
+export declare function writeDaemonState(state: DaemonState): void;
+export declare function readDaemonState(): DaemonState | null;
+export declare function removeDaemonState(): void;

package/dist/lib/daemon-state.js

@@ -0,0 +1,47 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function getStateDir() {
+    return path.join(os.homedir(), '.switchbot');
+}
+function getDaemonPidFile() {
+    return path.join(getStateDir(), 'daemon.pid');
+}
+function getDaemonLogFile() {
+    return path.join(getStateDir(), 'daemon.log');
+}
+function getDaemonStateFile() {
+    return path.join(getStateDir(), 'daemon.state.json');
+}
+function getHealthzPidFile() {
+    return path.join(getStateDir(), 'healthz.pid');
+}
+export const DAEMON_PID_FILE = getDaemonPidFile();
+export const DAEMON_LOG_FILE = getDaemonLogFile();
+export const DAEMON_STATE_FILE = getDaemonStateFile();
+export const HEALTHZ_PID_FILE = getHealthzPidFile();
+function ensureStateDir() {
+    fs.mkdirSync(getStateDir(), { recursive: true, mode: 0o700 });
+}
+export function writeDaemonState(state) {
+    ensureStateDir();
+    fs.writeFileSync(getDaemonStateFile(), JSON.stringify(state, null, 2), { mode: 0o600 });
+}
+export function readDaemonState() {
+    try {
+        const raw = fs.readFileSync(getDaemonStateFile(), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function removeDaemonState() {
+    try {
+        fs.unlinkSync(getDaemonStateFile());
+    }
+    catch {
+        // best effort
+    }
+}
+//# sourceMappingURL=daemon-state.js.map

package/dist/lib/daemon-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"daemon-state.js","sourceRoot":"","sources":["../../src/lib/daemon-state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,SAAS,WAAW;IAClB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,YAAY,CAAC,CAAC;AAC/C,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,gBAAgB;IACvB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;AAChD,CAAC;AAED,SAAS,kBAAkB;IACzB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,mBAAmB,CAAC,CAAC;AACvD,CAAC;AAED,SAAS,iBAAiB;IACxB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,EAAE,CAAC;AAClD,MAAM,CAAC,MAAM,eAAe,GAAG,gBAAgB,EAAE,CAAC;AAClD,MAAM,CAAC,MAAM,iBAAiB,GAAG,kBAAkB,EAAE,CAAC;AACtD,MAAM,CAAC,MAAM,gBAAgB,GAAG,iBAAiB,EAAE,CAAC;AAoBpD,SAAS,cAAc;IACrB,EAAE,CAAC,SAAS,CAAC,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,KAAkB;IACjD,cAAc,EAAE,CAAC;IACjB,EAAE,CAAC,aAAa,CAAC,kBAAkB,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;AAC1F,CAAC;AAED,MAAM,UAAU,eAAe;IAC7B,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,kBAAkB,EAAE,EAAE,OAAO,CAAC,CAAC;QAC3D,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAgB,CAAC;IACxC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,EAAE,CAAC,UAAU,CAAC,kBAAkB,EAAE,CAAC,CAAC;IACtC,CAAC;IAAC,MAAM,CAAC;QACP,cAAc;IAChB,CAAC;AACH,CAAC"}

package/dist/lib/destructive-mode.d.ts

@@ -0,0 +1,2 @@
+export declare function allowsDirectDestructiveExecution(profile?: string | undefined): boolean;
+export declare function destructiveExecutionHint(): string;

package/dist/lib/destructive-mode.js

@@ -0,0 +1,13 @@
+import { getActiveProfile } from './request-context.js';
+const DIRECT_DESTRUCTIVE_PROFILES = new Set(['dev', 'development']);
+export function allowsDirectDestructiveExecution(profile = getActiveProfile()) {
+    if (process.env.SWITCHBOT_ALLOW_DIRECT_DESTRUCTIVE === '1')
+        return true;
+    if (!profile)
+        return false;
+    return DIRECT_DESTRUCTIVE_PROFILES.has(profile.toLowerCase());
+}
+export function destructiveExecutionHint() {
+    return "Use 'switchbot plan save <file>' -> 'switchbot plan review <planId>' -> 'switchbot plan approve <planId>' -> 'switchbot plan execute <planId>' instead.";
+}
+//# sourceMappingURL=destructive-mode.js.map

package/dist/lib/destructive-mode.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"destructive-mode.js","sourceRoot":"","sources":["../../src/lib/destructive-mode.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAExD,MAAM,2BAA2B,GAAG,IAAI,GAAG,CAAC,CAAC,KAAK,EAAE,aAAa,CAAC,CAAC,CAAC;AAEpE,MAAM,UAAU,gCAAgC,CAAC,OAAO,GAAG,gBAAgB,EAAE;IAC3E,IAAI,OAAO,CAAC,GAAG,CAAC,kCAAkC,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACxE,IAAI,CAAC,OAAO;QAAE,OAAO,KAAK,CAAC;IAC3B,OAAO,2BAA2B,CAAC,GAAG,CAAC,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;AAChE,CAAC;AAED,MAAM,UAAU,wBAAwB;IACtC,OAAO,yJAAyJ,CAAC;AACnK,CAAC"}

package/dist/lib/devices.d.ts

@@ -0,0 +1,151 @@
+import type { AxiosInstance } from 'axios';
+import { suggestedActions, type DeviceCatalogEntry, type CommandSpec } from '../devices/catalog.js';
+export interface Device {
+    deviceId: string;
+    deviceName: string;
+    deviceType?: string;
+    enableCloudService: boolean;
+    hubDeviceId: string;
+    roomID?: string;
+    roomName?: string | null;
+    familyName?: string;
+    controlType?: string;
+}
+export interface InfraredDevice {
+    deviceId: string;
+    deviceName: string;
+    remoteType: string;
+    hubDeviceId: string;
+    controlType?: string;
+}
+export interface DeviceListBody {
+    deviceList: Device[];
+    infraredRemoteList: InfraredDevice[];
+}
+export interface DescribeCapabilities {
+    role: string | null;
+    readOnly: boolean;
+    commands: CommandSpec[];
+    statusFields: string[];
+    liveStatus?: Record<string, unknown>;
+}
+export interface DescribeResult {
+    device: Device | InfraredDevice;
+    isPhysical: boolean;
+    typeName: string;
+    controlType: string | null;
+    catalog: DeviceCatalogEntry | null;
+    capabilities: DescribeCapabilities | {
+        liveStatus: Record<string, unknown>;
+    } | null;
+    source: 'catalog' | 'live' | 'catalog+live' | 'none';
+    suggestedActions: ReturnType<typeof suggestedActions>;
+    /** For IR remotes: the family/room inherited from their bound Hub. Undefined for physical devices. */
+    inheritedLocation?: {
+        family?: string;
+        room?: string;
+        roomID?: string;
+    };
+}
+export declare class DeviceNotFoundError extends Error {
+    readonly deviceId: string;
+    constructor(deviceId: string);
+}
+export declare class CommandValidationError extends Error {
+    readonly kind: 'read-only-device' | 'unknown-command' | 'unexpected-parameter' | 'missing-parameter';
+    readonly hint?: string | undefined;
+    constructor(message: string, kind: 'read-only-device' | 'unknown-command' | 'unexpected-parameter' | 'missing-parameter', hint?: string | undefined);
+}
+/** Fetch the full device + IR remote inventory and refresh the local cache. */
+export declare function fetchDeviceList(client?: AxiosInstance): Promise<DeviceListBody>;
+/** Fetch live status for a single physical device. IR remotes have no status channel. */
+export declare function fetchDeviceStatus(deviceId: string, client?: AxiosInstance): Promise<Record<string, unknown>>;
+/**
+ * Execute a command on a device. `parameter` is the fully-parsed value already
+ * (JSON-object when applicable), not a raw CLI string — callers should parse
+ * upstream if needed.
+ */
+export declare function executeCommand(deviceId: string, cmd: string, parameter: unknown, commandType: 'command' | 'customize', client?: AxiosInstance, options?: {
+    idempotencyKey?: string;
+    planId?: string;
+}): Promise<unknown>;
+/**
+ * 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.). 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 declare function validateCommand(deviceId: string, cmd: string, parameter: string | undefined, commandType: string): {
+    ok: true;
+    normalized?: string;
+    caseNormalizedFrom?: string;
+} | {
+    ok: false;
+    error: CommandValidationError;
+};
+/**
+ * Inspect catalog annotations to decide whether a command is destructive,
+ * i.e. has hard-to-reverse real-world effects and should require an explicit
+ * confirmation from an agent / operator before execution. Customize commands
+ * are considered non-destructive here — they're user-defined IR buttons
+ * whose behavior the catalog can't know about.
+ */
+export declare function isDestructiveCommand(deviceType: string | undefined, cmd: string, commandType: string): boolean;
+/** Return the safetyReason for a command, or null if not destructive / not found. */
+export declare function getDestructiveReason(deviceType: string | undefined, cmd: string, commandType: string): string | null;
+/**
+ * Describe a device by id: metadata + catalog entry (if known) +
+ * optional live status. Throws `DeviceNotFoundError` when the id is unknown.
+ */
+export declare function describeDevice(deviceId: string, options?: {
+    live?: boolean;
+}, client?: AxiosInstance): Promise<DescribeResult>;
+/** Build a map from hubDeviceId → room/family/roomID for IR-remote inheritance. */
+export declare function buildHubLocationMap(deviceList: Device[]): Map<string, {
+    family?: string;
+    room?: string;
+    roomID?: string;
+}>;
+/**
+ * Search the local catalog by type name / alias. Returns up to `limit`
+ * entries whose type or alias contains the query (case-insensitive).
+ * Intended for MCP's `search_catalog` tool — not for dispatching commands.
+ */
+export declare function searchCatalog(query: string, limit?: number): DeviceCatalogEntry[];
+/** Shape expected by the MCP describe_device outputSchema. */
+export interface McpDescribeShape {
+    device: {
+        deviceId: string;
+        deviceName: string;
+        deviceType?: string;
+        enableCloudService?: boolean;
+        hubDeviceId?: string;
+        roomID?: string;
+        roomName?: string | null;
+        familyName?: string;
+        controlType?: string;
+        remoteType?: string;
+    };
+    isPhysical: boolean;
+    typeName: string;
+    controlType: string | null;
+    source: 'catalog' | 'live' | 'catalog+live' | 'none';
+    capabilities: unknown;
+    suggestedActions: Array<{
+        command: string;
+        parameter?: string;
+        description: string;
+    }>;
+    inheritedLocation?: {
+        family?: string;
+        room?: string;
+    };
+}
+/** Convert a DescribeResult to the shape validated by the MCP outputSchema. */
+export declare function toMcpDescribeShape(r: DescribeResult): McpDescribeShape;
+/** Shapes the device list body for the MCP list_devices outputSchema. */
+export declare function toMcpDeviceListShape(d: Device): Record<string, unknown>;
+/** Shapes an infrared remote for the MCP list_devices outputSchema. */
+export declare function toMcpIrDeviceShape(d: InfraredDevice): Record<string, unknown>;