@switchbot/openapi-cli 2.6.4 → 2.7.2

package/dist/commands/devices.js

@@ -1,7 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, emitJsonError, exitWithError } from '../utils/output.js';
+import { printTable, printKeyValue, printJson, isJsonMode, handleError, UsageError, StructuredUsageError, exitWithError } from '../utils/output.js';
 import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { findCatalogEntry, getEffectiveCatalog } from '../devices/catalog.js';
+import { findCatalogEntry, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice, loadCache } from '../devices/cache.js';
 import { loadDeviceMeta } from '../devices/device-meta.js';
 import { resolveDeviceId, ALL_STRATEGIES } from '../utils/name-resolver.js';
@@ -15,7 +15,7 @@ import { registerExpandCommand } from './expand.js';
 import { registerDevicesMetaCommand } from './device-meta.js';
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
-import { resolveField, listSupportedFieldInputs } from '../schema/field-aliases.js';
+import { resolveField, resolveFieldList, listSupportedFieldInputs } from '../schema/field-aliases.js';
 const EXPAND_HINTS = {
     'Air Conditioner': { command: 'setAll', flags: '--temp 26 --mode cool --fan low --power on' },
     'Curtain': { command: 'setPosition', flags: '--position 50 --mode silent' },
@@ -88,7 +88,7 @@ Examples:
 `)
         .option('--wide', 'Show all columns (controlType, family, roomID, room, hub, cloud)')
         .option('--show-hidden', 'Include devices hidden via "devices meta set --hide"')
-        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category.', stringArg('--filter'))
+        .option('--filter <expr>', 'Filter devices: comma-separated clauses. Each clause is "key=value" (substring; exact for category), "key!=value" (negated substring), "key~value" (explicit substring), or "key=/regex/" (case-insensitive regex). Supported keys: deviceId/id, deviceName/name, deviceType/type, controlType, roomName/room, category, familyName/family, hubDeviceId/hub, roomID/roomid, enableCloudService/cloud, alias.', stringArg('--filter'))
         .action(async (options) => {
         try {
             const body = await fetchDeviceList();
@@ -98,8 +98,11 @@ Examples:
             const hubLocation = buildHubLocationMap(deviceList);
             // Parse --filter into a list of clauses. Shared grammar across
             // `devices list`, `devices batch`, and `events tail` / `mqtt-tail`.
-            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType'];
-            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType', 'roomName', 'category'];
+            const LIST_KEYS = ['deviceId', 'type', 'name', 'category', 'room', 'controlType',
+                'family', 'hub', 'roomID', 'cloud', 'alias'];
+            const LIST_FILTER_CANONICAL = ['deviceId', 'deviceName', 'deviceType', 'controlType',
+                'roomName', 'category', 'familyName', 'hubDeviceId', 'roomID',
+                'enableCloudService', 'alias'];
             const LIST_FILTER_TO_RUNTIME = {
                 deviceId: 'deviceId',
                 deviceName: 'name',
@@ -107,6 +110,11 @@ Examples:
                 controlType: 'controlType',
                 roomName: 'room',
                 category: 'category',
+                familyName: 'family',
+                hubDeviceId: 'hub',
+                roomID: 'roomID',
+                enableCloudService: 'cloud',
+                alias: 'alias',
             };
             let listClauses = null;
             if (options.filter) {
@@ -137,10 +145,10 @@ Examples:
             };
             if (fmt === 'json' && process.argv.includes('--json')) {
                 if (listClauses) {
-                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }));
+                    const filteredDeviceList = deviceList.filter((d) => matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }));
                     const filteredIrList = infraredRemoteList.filter((d) => {
                         const inherited = hubLocation.get(d.hubDeviceId);
-                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' });
+                        return matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' });
                     });
                     printJson({ ok: true, deviceList: filteredDeviceList, infraredRemoteList: filteredIrList });
                 }
@@ -157,7 +165,7 @@ Examples:
             for (const d of deviceList) {
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
-                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.deviceType || '', name: d.deviceName, category: 'physical', room: d.roomName || '', controlType: d.controlType || '', family: d.familyName || '', hub: d.hubDeviceId || '', roomID: d.roomID || '', cloud: String(d.enableCloudService), alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -177,7 +185,7 @@ Examples:
                 if (!options.showHidden && deviceMeta.devices[d.deviceId]?.hidden)
                     continue;
                 const inherited = hubLocation.get(d.hubDeviceId);
-                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '' }))
+                if (!matchesFilter({ deviceId: d.deviceId, type: d.remoteType, name: d.deviceName, category: 'ir', room: inherited?.room || '', controlType: d.controlType || '', family: inherited?.family || '', hub: d.hubDeviceId || '', roomID: inherited?.roomID || '', cloud: '', alias: deviceMeta.devices[d.deviceId]?.alias || '' }))
                     continue;
                 rows.push([
                     d.deviceId,
@@ -280,7 +288,7 @@ Examples:
                     }
                 }
                 else {
-                    const fields = resolveFields();
+                    const rawFields = resolveFields();
                     for (const entry of batch) {
                         const { deviceId, ok, error, _fetchedAt: ts, ...status } = entry;
                         console.log(`\n─── ${String(deviceId)} ───`);
@@ -288,9 +296,13 @@ Examples:
                             console.error(`  error: ${String(error)}`);
                         }
                         else {
+                            const statusMap = status;
+                            const fields = rawFields
+                                ? resolveFieldList(rawFields, Object.keys(statusMap))
+                                : undefined;
                             const displayStatus = fields
-                                ? Object.fromEntries(fields.map((f) => [f, status[f] ?? null]))
-                                : status;
+                                ? Object.fromEntries(fields.map((f) => [f, statusMap[f] ?? null]))
+                                : statusMap;
                             printKeyValue(displayStatus);
                             console.error(`  fetched at ${String(ts)}`);
                         }
@@ -315,7 +327,10 @@ Examples:
                 const statusWithTs = { ...body, _fetchedAt: fetchedAt };
                 const allHeaders = Object.keys(statusWithTs);
                 const allRows = [Object.values(statusWithTs)];
-                const fields = resolveFields();
+                const rawFields = resolveFields();
+                const fields = rawFields
+                    ? resolveFieldList(rawFields, allHeaders)
+                    : undefined;
                 renderRows(allHeaders, allRows, fmt, fields);
                 return;
             }
@@ -453,26 +468,22 @@ Examples:
             const validation = validateCommand(deviceId, cmd, parameter, options.type);
             if (!validation.ok) {
                 const err = validation.error;
-                if (isJsonMode()) {
-                    const obj = { code: 2, kind: 'usage', message: err.message };
-                    if (err.hint)
-                        obj.hint = err.hint;
-                    obj.context = { validationKind: err.kind };
-                    emitJsonError(obj);
-                }
-                else {
-                    console.error(`Error: ${err.message}`);
-                    if (err.hint)
-                        console.error(err.hint);
-                    if (err.kind === 'unknown-command') {
-                        const cached = getCachedDevice(deviceId);
-                        if (cached) {
-                            console.error(`Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.`);
-                            console.error(`(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`);
-                        }
+                let hint = err.hint;
+                if (err.kind === 'unknown-command') {
+                    const cached = getCachedDevice(deviceId);
+                    if (cached) {
+                        const extra = `Run 'switchbot devices commands ${JSON.stringify(cached.type)}' for parameter formats and descriptions.\n` +
+                            `(If the catalog is out of date, run 'switchbot devices list' to refresh the local cache, or pass --type customize for custom IR buttons.)`;
+                        hint = hint ? `${hint}\n${extra}` : extra;
                     }
                 }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: err.message,
+                    hint,
+                    context: { validationKind: err.kind },
+                });
             }
             // Case-only mismatch: emit a warning and continue with the canonical name.
             if (validation.caseNormalizedFrom && validation.normalized) {
@@ -507,7 +518,7 @@ Examples:
                     hint: reason
                         ? `Re-run with --yes to confirm. Reason: ${reason}`
                         : 'Re-run with --yes to confirm, or --dry-run to preview without sending.',
-                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { destructiveReason: reason } : {}) },
+                    context: { command: cmd, deviceType: typeLabel, deviceId, ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}) },
                 });
             }
             // Warn when --yes is given but the command is not destructive (no-op flag)
@@ -645,7 +656,7 @@ Examples:
             const joinedMatch = findCatalogEntry(joined);
             if (joinedMatch && !Array.isArray(joinedMatch)) {
                 if (isJsonMode()) {
-                    printJson(joinedMatch);
+                    printJson(normalizeCatalogForJson(joinedMatch));
                 }
                 else {
                     renderCatalogEntry(joinedMatch);
@@ -664,7 +675,7 @@ Examples:
                 }
                 if (individualMatches.length === typeParts.length) {
                     if (isJsonMode()) {
-                        printJson(individualMatches);
+                        printJson(individualMatches.map(normalizeCatalogForJson));
                     }
                     else {
                         individualMatches.forEach((entry, i) => {
@@ -824,6 +835,21 @@ Examples:
     // switchbot devices meta set/get/list/clear
     registerDevicesMetaCommand(devices);
 }
+function normalizeCatalogForJson(entry) {
+    return {
+        ...entry,
+        commands: entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
+            const reason = getCommandSafetyReason(c);
+            return {
+                ...c,
+                safetyTier: tier,
+                destructive: tier === 'destructive',
+                ...(reason ? { safetyReason: reason } : {}),
+            };
+        }),
+    };
+}
 function renderCatalogEntry(entry) {
     console.log(`Type:     ${entry.type}`);
     console.log(`Category: ${entry.category === 'ir' ? 'IR remote' : 'Physical device'}`);
@@ -841,10 +867,11 @@ function renderCatalogEntry(entry) {
         console.log('\nCommands:');
         const hasExamples = entry.commands.some((c) => c.exampleParams && c.exampleParams.length > 0);
         const rows = entry.commands.map((c) => {
+            const tier = deriveSafetyTier(c, entry);
             const flags = [];
             if (c.commandType === 'customize')
                 flags.push('customize');
-            if (c.destructive)
+            if (tier === 'destructive')
                 flags.push('!destructive');
             const label = flags.length > 0 ? `${c.command}  [${flags.join(', ')}]` : c.command;
             const base = [label, c.parameter, c.description];
@@ -854,7 +881,7 @@ function renderCatalogEntry(entry) {
             ? ['command', 'parameter', 'description', 'example']
             : ['command', 'parameter', 'description'];
         printTable(tableHeaders, rows);
-        const hasDestructive = entry.commands.some((c) => c.destructive);
+        const hasDestructive = entry.commands.some((c) => deriveSafetyTier(c, entry) === 'destructive');
         if (hasDestructive) {
             console.log('\n[!destructive] commands have hard-to-reverse real-world effects — confirm before issuing.');
         }

package/dist/commands/doctor.js

@@ -1,10 +1,14 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { printJson, isJsonMode } from '../utils/output.js';
+import { printJson, isJsonMode, exitWithError } from '../utils/output.js';
 import { getEffectiveCatalog } from '../devices/catalog.js';
 import { configFilePath, listProfiles, readProfileMeta } from '../config.js';
-import { describeCache } from '../devices/cache.js';
+import { describeCache, resetListCache } from '../devices/cache.js';
+import { DAILY_QUOTA, todayUsage } from '../utils/quota.js';
+import { AGENT_BOOTSTRAP_SCHEMA_VERSION } from './agent-bootstrap.js';
+import { CATALOG_SCHEMA_VERSION } from '../devices/catalog.js';
+import { createSwitchBotMcpServer, listRegisteredTools } from './mcp.js';
 export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
@@ -160,15 +164,148 @@ function checkCache() {
 function checkQuotaFile() {
     const p = path.join(os.homedir(), '.switchbot', 'quota.json');
     if (!fs.existsSync(p)) {
-        return { name: 'quota', status: 'ok', detail: 'no quota file yet (will be created on first call)' };
+        return {
+            name: 'quota',
+            status: 'ok',
+            detail: {
+                path: p,
+                percentUsed: 0,
+                remaining: DAILY_QUOTA,
+                message: 'no quota file yet (will be created on first call)',
+            },
+        };
     }
     try {
         const raw = fs.readFileSync(p, 'utf-8');
         JSON.parse(raw);
-        return { name: 'quota', status: 'ok', detail: p };
     }
     catch {
-        return { name: 'quota', status: 'warn', detail: `${p} unreadable/malformed — run 'switchbot quota reset'` };
+        return {
+            name: 'quota',
+            status: 'warn',
+            detail: { path: p, message: `unreadable/malformed — run 'switchbot quota reset'` },
+        };
+    }
+    // P9: surface headroom so agents can decide when to slow down or pause.
+    // Quota resets at local midnight (the quota counter buckets by local
+    // date), so project the next reset to the next 00:00:00 local.
+    const usage = todayUsage();
+    const percentUsed = Math.round((usage.total / DAILY_QUOTA) * 100);
+    const now = new Date();
+    const reset = new Date(now);
+    reset.setHours(24, 0, 0, 0); // next local midnight
+    const status = percentUsed > 80 ? 'warn' : 'ok';
+    const recommendation = percentUsed > 90
+        ? 'over 90% used — consider --no-quota for read-only triage or rescheduling work after the reset'
+        : percentUsed > 80
+            ? 'over 80% used — avoid bulk operations until the daily reset'
+            : 'headroom available';
+    return {
+        name: 'quota',
+        status,
+        detail: {
+            path: p,
+            percentUsed,
+            remaining: usage.remaining,
+            total: usage.total,
+            dailyCap: DAILY_QUOTA,
+            projectedResetTime: reset.toISOString(),
+            recommendation,
+        },
+    };
+}
+function checkCatalogSchema() {
+    // P9: sentinel against silent drift between the catalog shape and the
+    // agent-bootstrap payload. Both constants are exported from their
+    // respective modules; if a future refactor changes one without the
+    // other, this check fails so consumers (agents) learn before the
+    // mismatch corrupts their mental model.
+    const match = CATALOG_SCHEMA_VERSION === AGENT_BOOTSTRAP_SCHEMA_VERSION;
+    return {
+        name: 'catalog-schema',
+        status: match ? 'ok' : 'fail',
+        detail: {
+            catalogSchemaVersion: CATALOG_SCHEMA_VERSION,
+            bootstrapExpectsVersion: AGENT_BOOTSTRAP_SCHEMA_VERSION,
+            match,
+            message: match
+                ? 'catalog and agent-bootstrap schemaVersion aligned'
+                : 'catalog and agent-bootstrap schemaVersion have drifted — bump in lockstep',
+        },
+    };
+}
+function checkAudit() {
+    // P9: surface recent command failures so agents / ops can spot problems
+    // before they page. When --audit-log was never enabled, the file won't
+    // exist — report that cleanly rather than as an error.
+    const p = path.join(os.homedir(), '.switchbot', 'audit.log');
+    if (!fs.existsSync(p)) {
+        return {
+            name: 'audit',
+            status: 'ok',
+            detail: {
+                path: p,
+                enabled: false,
+                message: 'audit log not present (enable with --audit-log)',
+            },
+        };
+    }
+    try {
+        const raw = fs.readFileSync(p, 'utf-8');
+        const since = Date.now() - 24 * 60 * 60 * 1000;
+        const recent = [];
+        let total = 0;
+        for (const line of raw.split('\n')) {
+            const trimmed = line.trim();
+            if (!trimmed)
+                continue;
+            let rec;
+            try {
+                rec = JSON.parse(trimmed);
+            }
+            catch {
+                continue;
+            }
+            if (rec.result !== 'error')
+                continue;
+            total += 1;
+            const ts = rec.t ? Date.parse(rec.t) : NaN;
+            if (Number.isFinite(ts) && ts >= since) {
+                recent.push({
+                    t: rec.t,
+                    command: rec.command ?? '?',
+                    deviceId: rec.deviceId,
+                    error: rec.error ?? 'unknown',
+                });
+            }
+        }
+        // Cap the report to the 10 most recent so the doctor payload stays
+        // bounded even on a log with thousands of errors.
+        recent.sort((a, b) => (a.t < b.t ? 1 : -1));
+        const clipped = recent.slice(0, 10);
+        const status = recent.length > 0 ? 'warn' : 'ok';
+        return {
+            name: 'audit',
+            status,
+            detail: {
+                path: p,
+                enabled: true,
+                totalErrors: total,
+                errorsLast24h: recent.length,
+                recent: clipped,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'audit',
+            status: 'warn',
+            detail: {
+                path: p,
+                enabled: true,
+                message: `could not read audit log: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
     }
 }
 function checkNodeVersion() {
@@ -210,10 +347,160 @@ function checkMqtt() {
         detail: "unavailable — configure credentials first (see credentials check above)",
     };
 }
+async function checkMqttProbe() {
+    // P10: live-probe the MQTT broker. Only runs when --probe is passed.
+    // Does not subscribe — just connects + disconnects to verify the
+    // credential + TLS handshake works end-to-end. Hard 5s timeout so
+    // a misbehaving broker never wedges the doctor command.
+    const { fetchMqttCredential } = await import('../mqtt/credential.js');
+    const { SwitchBotMqttClient } = await import('../mqtt/client.js');
+    const token = process.env.SWITCHBOT_TOKEN;
+    const secret = process.env.SWITCHBOT_SECRET;
+    let creds = null;
+    if (token && secret) {
+        creds = { token, secret };
+    }
+    else {
+        const file = configFilePath();
+        if (fs.existsSync(file)) {
+            try {
+                const cfg = JSON.parse(fs.readFileSync(file, 'utf-8'));
+                if (cfg.token && cfg.secret) {
+                    creds = { token: cfg.token, secret: cfg.secret };
+                }
+            }
+            catch { /* fall through */ }
+        }
+    }
+    if (!creds) {
+        return {
+            name: 'mqtt',
+            status: 'warn',
+            detail: { probe: 'skipped', reason: 'no credentials configured' },
+        };
+    }
+    const deadline = new Promise((_, reject) => setTimeout(() => reject(new Error('probe timeout after 5000ms')), 5000));
+    try {
+        const cred = await Promise.race([fetchMqttCredential(creds.token, creds.secret), deadline]);
+        const client = new SwitchBotMqttClient(cred);
+        await Promise.race([client.connect(), deadline]);
+        await client.disconnect();
+        return {
+            name: 'mqtt',
+            status: 'ok',
+            detail: { probe: 'connected', brokerUrl: cred.brokerUrl, region: cred.region },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'mqtt',
+            status: 'warn',
+            detail: { probe: 'failed', reason: err instanceof Error ? err.message : String(err) },
+        };
+    }
+}
+function checkMcp() {
+    // P10: dry-run instantiation of the MCP server to catch tool-registration
+    // regressions. No network I/O, no token needed. If createSwitchBotMcpServer
+    // throws (e.g. duplicate tool name, schema build error) the check fails.
+    try {
+        const server = createSwitchBotMcpServer();
+        const tools = listRegisteredTools(server);
+        return {
+            name: 'mcp',
+            status: 'ok',
+            detail: {
+                serverInstantiated: true,
+                toolCount: tools.length,
+                tools,
+                transportsAvailable: ['stdio', 'http'],
+                message: `${tools.length} tools registered; no network probe`,
+            },
+        };
+    }
+    catch (err) {
+        return {
+            name: 'mcp',
+            status: 'fail',
+            detail: {
+                serverInstantiated: false,
+                error: err instanceof Error ? err.message : String(err),
+            },
+        };
+    }
+}
+const CHECK_REGISTRY = [
+    { name: 'node', description: 'Node.js version compatibility', run: () => checkNodeVersion() },
+    { name: 'credentials', description: 'credentials file present and parseable', run: () => checkCredentials() },
+    { name: 'profiles', description: 'profile definitions valid', run: () => checkProfiles() },
+    { name: 'catalog', description: 'catalog loads', run: () => checkCatalog() },
+    { name: 'catalog-schema', description: 'catalog vs agent-bootstrap version aligned', run: () => checkCatalogSchema() },
+    { name: 'cache', description: 'device cache state', run: () => checkCache() },
+    { name: 'quota', description: 'API quota headroom', run: () => checkQuotaFile() },
+    { name: 'clock', description: 'system clock skew', run: () => checkClockSkew() },
+    {
+        name: 'mqtt',
+        description: 'MQTT credentials (+ --probe for live broker handshake)',
+        run: ({ probe }) => (probe ? checkMqttProbe() : checkMqtt()),
+    },
+    { name: 'mcp', description: 'MCP server instantiable + tool count', run: () => checkMcp() },
+    { name: 'audit', description: 'recent command errors (last 24h)', run: () => checkAudit() },
+];
+function applyFixes(checks, writeOk) {
+    const results = [];
+    for (const c of checks) {
+        if (c.name === 'cache' && c.status !== 'ok') {
+            if (writeOk) {
+                try {
+                    resetListCache();
+                    results.push({ check: 'cache', action: 'cache-cleared', applied: true });
+                }
+                catch (err) {
+                    results.push({
+                        check: 'cache',
+                        action: 'cache-clear',
+                        applied: false,
+                        message: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            }
+            else {
+                results.push({
+                    check: 'cache',
+                    action: 'cache-clear',
+                    applied: false,
+                    message: 'pass --yes to apply',
+                });
+            }
+        }
+        else if (c.name === 'catalog-schema' && c.status !== 'ok') {
+            results.push({
+                check: 'catalog-schema',
+                action: 'manual',
+                applied: false,
+                message: "drift detected — run 'switchbot capabilities --reload' to refresh overlay",
+            });
+        }
+        else if (c.name === 'credentials' && c.status === 'fail') {
+            results.push({
+                check: 'credentials',
+                action: 'manual',
+                applied: false,
+                message: "run 'switchbot config set-token' to configure credentials",
+            });
+        }
+    }
+    return results;
+}
 export function registerDoctorCommand(program) {
     program
         .command('doctor')
-        .description('Self-check: credentials, catalog, cache, quota, profiles, Node version')
+        .description('Self-check the SwitchBot CLI setup: credentials, catalog, cache, quota, MQTT, MCP')
+        .option('--section <names>', 'Comma-separated list of checks to run (see --list for names)')
+        .option('--list', 'Print the registered check names and exit 0 without running any check')
+        .option('--fix', 'Apply safe, reversible remediations for failing checks (e.g. clear stale cache)')
+        .option('--yes', 'Required together with --fix to confirm write actions')
+        .option('--probe', 'Perform live-probe variant of checks that support it (mqtt)')
         .addHelpText('after', `
 Runs a battery of local sanity checks and exits with code 0 only when every
 check is 'ok'. 'warn' → exit 0 (informational); 'fail' → exit 1.
@@ -221,18 +508,52 @@ check is 'ok'. 'warn' → exit 0 (informational); 'fail' → exit 1.
 Examples:
   $ switchbot doctor
   $ switchbot --json doctor | jq '.checks[] | select(.status != "ok")'
+  $ switchbot doctor --list
+  $ switchbot doctor --section credentials,mcp --json
+  $ switchbot doctor --probe --json
+  $ switchbot doctor --fix --yes --json
 `)
-        .action(async () => {
-        const checks = [
-            checkNodeVersion(),
-            await checkCredentials(),
-            checkProfiles(),
-            checkCatalog(),
-            checkCache(),
-            checkQuotaFile(),
-            await checkClockSkew(),
-            checkMqtt(),
-        ];
+        .action(async (opts) => {
+        // --list: print the registry and exit 0.
+        if (opts.list) {
+            if (isJsonMode()) {
+                printJson({
+                    checks: CHECK_REGISTRY.map((c) => ({ name: c.name, description: c.description })),
+                });
+            }
+            else {
+                console.log('Available checks:');
+                for (const c of CHECK_REGISTRY) {
+                    console.log(`  ${c.name.padEnd(16)} ${c.description}`);
+                }
+            }
+            return;
+        }
+        // --section: run only the named subset, dedup and validate.
+        let selected = CHECK_REGISTRY;
+        if (opts.section) {
+            const raw = opts.section.split(',').map((s) => s.trim()).filter(Boolean);
+            const names = Array.from(new Set(raw));
+            const known = new Set(CHECK_REGISTRY.map((c) => c.name));
+            const unknown = names.filter((n) => !known.has(n));
+            if (unknown.length > 0) {
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: `Unknown check name(s): ${unknown.join(', ')}. Valid: ${CHECK_REGISTRY.map((c) => c.name).join(', ')}`,
+                });
+                return;
+            }
+            const order = new Map(CHECK_REGISTRY.map((c, i) => [c.name, i]));
+            selected = names
+                .map((n) => CHECK_REGISTRY.find((c) => c.name === n))
+                .sort((a, b) => (order.get(a.name) - order.get(b.name)));
+        }
+        const runOpts = { probe: Boolean(opts.probe) };
+        const checks = [];
+        for (const def of selected) {
+            checks.push(await def.run(runOpts));
+        }
         const summary = {
             ok: checks.filter((c) => c.status === 'ok').length,
             warn: checks.filter((c) => c.status === 'warn').length,
@@ -240,20 +561,27 @@ Examples:
         };
         const overallFail = summary.fail > 0;
         const overall = overallFail ? 'fail' : summary.warn > 0 ? 'warn' : 'ok';
+        let fixes;
+        if (opts.fix) {
+            fixes = applyFixes(checks, Boolean(opts.yes));
+        }
         if (isJsonMode()) {
             // 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({
+            const payload = {
                 ok: overall === 'ok',
                 overall,
                 generatedAt: new Date().toISOString(),
                 schemaVersion: DOCTOR_SCHEMA_VERSION,
                 summary,
                 checks,
-            });
+            };
+            if (fixes !== undefined)
+                payload.fixes = fixes;
+            printJson(payload);
         }
         else {
             for (const c of checks) {
@@ -263,6 +591,14 @@ Examples:
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);
+            if (fixes && fixes.length > 0) {
+                console.log('');
+                console.log('Fixes:');
+                for (const f of fixes) {
+                    const marker = f.applied ? '✓' : '-';
+                    console.log(`  ${marker} ${f.check}: ${f.action}${f.message ? ' — ' + f.message : ''}`);
+                }
+            }
         }
         if (overallFail)
             process.exit(1);