@switchbot/openapi-cli 2.6.4 → 2.7.2

package/dist/commands/events.js

@@ -1,6 +1,6 @@
 import http from 'node:http';
 import crypto from 'node:crypto';
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitStreamHeader } from '../utils/output.js';
 import { intArg, stringArg, durationArg } from '../utils/arg-parsers.js';
 import { parseDurationToMs } from '../utils/flags.js';
 import { parseFilterExpr, matchClause, FilterSyntaxError } from '../utils/filter.js';
@@ -19,6 +19,16 @@ import { deviceHistoryStore } from '../mcp/device-history.js';
 const DEFAULT_PORT = 3000;
 const DEFAULT_PATH = '/';
 const MAX_BODY_BYTES = 1_000_000;
+/**
+ * P6: unified-envelope schema version shared by webhook and MQTT event output.
+ *
+ * The same key set now appears on both `events tail` (webhook) and
+ * `events mqtt-tail` (MQTT) output lines so downstream JSONL consumers can
+ * use a single parser regardless of source. Old fields are kept for one
+ * minor window so existing consumers keep working — see README and
+ * CHANGELOG for the deprecation schedule.
+ */
+export const EVENTS_SCHEMA_VERSION = '1';
 function extractEventId(parsed) {
     if (!parsed || typeof parsed !== 'object')
         return null;
@@ -30,13 +40,27 @@ function extractEventId(parsed) {
         return ctx.eventId;
     return null;
 }
-function matchFilter(body, clauses) {
+function extractDeviceId(parsed) {
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const p = parsed;
+    const ctx = p.context ?? p;
+    const mac = ctx.deviceMac;
+    if (typeof mac === 'string' && mac.length > 0)
+        return mac;
+    const id = ctx.deviceId;
+    if (typeof id === 'string' && id.length > 0)
+        return id;
+    return null;
+}
+function matchFilterDetail(body, clauses) {
     if (!clauses || clauses.length === 0)
-        return true;
+        return { matched: true, matchedKeys: [] };
     if (!body || typeof body !== 'object')
-        return false;
+        return { matched: false, matchedKeys: [] };
     const b = body;
     const ctx = (b.context ?? b);
+    const hitKeys = [];
     for (const c of clauses) {
         let candidate;
         if (c.key === 'deviceId') {
@@ -49,9 +73,10 @@ function matchFilter(body, clauses) {
             candidate = typeof t === 'string' ? t : '';
         }
         if (!matchClause(candidate, c))
-            return false;
+            return { matched: false, matchedKeys: [] };
+        hitKeys.push(c.key);
     }
-    return true;
+    return { matched: true, matchedKeys: hitKeys };
 }
 const EVENT_FILTER_KEYS = ['deviceId', 'type'];
 function parseFilter(flag) {
@@ -108,11 +133,22 @@ export function startReceiver(port, pathMatch, filter, onEvent) {
             catch {
                 // keep raw
             }
-            const matched = matchFilter(body, filter);
+            const { matched, matchedKeys } = matchFilterDetail(body, filter);
+            const t = new Date().toISOString();
+            const urlPath = req.url ?? '/';
             onEvent({
-                t: new Date().toISOString(),
+                schemaVersion: EVENTS_SCHEMA_VERSION,
+                source: 'webhook',
+                kind: 'event',
+                t,
+                eventId: extractEventId(body),
+                deviceId: extractDeviceId(body),
+                topic: urlPath,
+                payload: body,
+                matchedKeys,
+                // Legacy mirror:
                 remote: `${req.socket.remoteAddress ?? ''}:${req.socket.remotePort ?? ''}`,
-                path: req.url ?? '/',
+                path: urlPath,
                 body,
                 matched,
             });
@@ -143,9 +179,14 @@ SwitchBot posts events to a single webhook URL configured via:
 the port to the internet yourself (ngrok/cloudflared/reverse proxy) and
 point the SwitchBot webhook at that public URL.
 
-Output (JSONL, one event per line):
-  { "t": "<ISO>", "remote": "<ip:port>", "path": "/",
-    "body": <parsed JSON or raw string>, "matched": true }
+Output (JSONL, one event per line; P6 unified envelope v2.7+):
+  { "schemaVersion": "1", "source": "webhook", "kind": "event",
+    "t": "<ISO>", "eventId": <string|null>, "deviceId": <string|null>,
+    "topic": "/",               // = path
+    "payload": <parsed JSON or raw string>,
+    "matchedKeys": ["deviceId"], // which filter clauses matched
+    // Legacy fields kept for one minor window (removed in v3.0):
+    "remote": "<ip:port>", "path": "/", "body": <payload>, "matched": true }
 
 Filter grammar: comma-separated clauses (AND-ed). Each clause is one of
   key=value     — case-insensitive substring
@@ -179,6 +220,10 @@ Examples:
             const forTimer = forMs !== null && forMs > 0
                 ? setTimeout(() => ac.abort(), forMs)
                 : null;
+            // P7: streaming JSON contract — first line under --json is the
+            // stream header (webhook events arrive via push cadence).
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'event', cadence: 'push' });
             await new Promise((resolve, reject) => {
                 let server = null;
                 try {
@@ -244,14 +289,20 @@ Connects to the SwitchBot MQTT service using your existing credentials
 (SWITCHBOT_TOKEN + SWITCHBOT_SECRET or ~/.switchbot/config.json).
 No additional MQTT configuration required.
 
-Output (JSONL, one event per line):
-  { "t": "<ISO>", "eventId": "<uuid>", "topic": "<mqtt-topic>", "payload": <parsed JSON or raw string> }
+Output (JSONL, one event per line; P6 unified envelope v2.7+):
+  { "schemaVersion": "1", "source": "mqtt", "kind": "event",
+    "t": "<ISO>", "eventId": "<uuid>", "deviceId": <string|null>,
+    "topic": "<mqtt-topic>",
+    "payload": <parsed JSON or raw string> }
 
-Control records (interleaved, no "payload" field — use type-prefix to filter):
-  { "type": "__session_start", "at": "<ISO>", "eventId": "<uuid>", "state": "connecting" }  before credential fetch (JSON mode only)
-  { "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
+Control records (interleaved, kind: "control" — filter by the "kind" field):
+  { "schemaVersion": "1", "source": "mqtt", "kind": "control",
+    "controlKind": "session_start"|"connect"|"reconnect"|"disconnect"|"heartbeat",
+    "t": "<ISO>", "eventId": "<uuid>",
+    "state": "connecting"         // present on session_start only
+    // Legacy fields kept for one minor window (removed in v3.0):
+    "type": "__session_start"|"__connect"|"__reconnect"|"__disconnect",
+    "at":   "<ISO>"  }
 
 Reconnect policy: the MQTT client retries with exponential backoff
 (1s → 30s capped, forever) while the credential is still valid; if the
@@ -346,15 +397,27 @@ Examples:
             if (!isJsonMode()) {
                 console.error('Fetching MQTT credentials from SwitchBot service…');
             }
+            // P7: streaming JSON contract — first line under --json is the stream
+            // header (mqtt events arrive via push cadence). Must emit BEFORE
+            // __session_start so header is always the very first line.
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'event', cadence: 'push' });
             // Emit a __session_start envelope immediately (before any credential
             // fetch) so JSON consumers can distinguish "connecting" from "never
             // connected" even when mqtt-tail exits before the broker connects.
             if (isJsonMode()) {
+                const sessionStartAt = new Date().toISOString();
                 printJson({
-                    type: '__session_start',
-                    at: new Date().toISOString(),
+                    schemaVersion: EVENTS_SCHEMA_VERSION,
+                    source: 'mqtt',
+                    kind: 'control',
+                    controlKind: 'session_start',
+                    t: sessionStartAt,
                     eventId: crypto.randomUUID(),
                     state: 'connecting',
+                    // Legacy (deprecated as of v2.7; removed in v3.0):
+                    type: '__session_start',
+                    at: sessionStartAt,
                 });
             }
             const credential = await fetchMqttCredential(loaded.token, loaded.secret);
@@ -389,7 +452,16 @@ Examples:
                     // Default behavior: record history + print to stdout
                     const { deviceId, deviceType } = parseSinkEvent(parsed);
                     deviceHistoryStore.record(deviceId, msgTopic, deviceType, parsed, t);
-                    const record = { t, eventId, topic: msgTopic, payload: parsed };
+                    const record = {
+                        schemaVersion: EVENTS_SCHEMA_VERSION,
+                        source: 'mqtt',
+                        kind: 'event',
+                        t,
+                        eventId,
+                        deviceId: deviceId ?? null,
+                        topic: msgTopic,
+                        payload: parsed,
+                    };
                     if (isJsonMode()) {
                         printJson(record);
                     }
@@ -405,7 +477,24 @@ Examples:
             let mqttFailed = false;
             let hasConnectedBefore = false;
             const emitControl = (kind) => {
-                const ctl = { type: kind, at: new Date().toISOString(), eventId: crypto.randomUUID() };
+                const at = new Date().toISOString();
+                const controlKindMap = {
+                    __connect: 'connect',
+                    __reconnect: 'reconnect',
+                    __disconnect: 'disconnect',
+                    __heartbeat: 'heartbeat',
+                };
+                const ctl = {
+                    schemaVersion: EVENTS_SCHEMA_VERSION,
+                    source: 'mqtt',
+                    kind: 'control',
+                    controlKind: controlKindMap[kind],
+                    t: at,
+                    eventId: crypto.randomUUID(),
+                    // Legacy (deprecated as of v2.7; removed in v3.0):
+                    type: kind,
+                    at,
+                };
                 // Control events always go to stdout as JSONL so consumers that
                 // filter real events by presence of `payload` can skip them.
                 if (isJsonMode()) {

package/dist/commands/expand.js

@@ -1,5 +1,5 @@
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { handleError, isJsonMode, printJson, UsageError, emitJsonError } from '../utils/output.js';
+import { handleError, isJsonMode, printJson, UsageError, exitWithError } from '../utils/output.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { executeCommand, isDestructiveCommand, getDestructiveReason } from '../lib/devices.js';
 import { isDryRun } from '../utils/flags.js';
@@ -92,20 +92,12 @@ Examples:
             }
             if (!options.yes && !isDryRun() && isDestructiveCommand(deviceType, command, 'command')) {
                 const reason = getDestructiveReason(deviceType, command, 'command');
-                if (isJsonMode()) {
-                    emitJsonError({
-                        code: 2,
-                        kind: 'guard',
-                        message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
-                        hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
-                    });
-                }
-                else {
-                    console.error(`Refusing to run destructive command "${command}" without --yes.`);
-                    if (reason)
-                        console.error(`Reason: ${reason}`);
-                }
-                process.exit(2);
+                exitWithError({
+                    code: 2,
+                    kind: 'guard',
+                    message: `"${command}" on ${deviceType || 'device'} is destructive and requires --yes.`,
+                    hint: reason ? `Re-run with --yes. Reason: ${reason}` : 'Re-run with --yes to confirm.',
+                });
             }
             const body = await executeCommand(deviceId, command, parameter, 'command');
             const isIr = cached?.category === 'ir';

package/dist/commands/explain.js

@@ -43,12 +43,16 @@ Examples:
             }
             const caps = desc.capabilities;
             const commands = caps && 'commands' in caps
-                ? caps.commands.map((c) => ({
-                    command: c.command,
-                    parameter: c.parameter,
-                    idempotent: c.idempotent,
-                    destructive: c.destructive,
-                }))
+                ? caps.commands.map((c) => {
+                    const tier = c.safetyTier;
+                    return {
+                        command: c.command,
+                        parameter: c.parameter,
+                        idempotent: c.idempotent,
+                        ...(tier ? { safetyTier: tier } : {}),
+                        destructive: c.destructive,
+                    };
+                })
                 : [];
             const statusFields = caps && 'statusFields' in caps ? caps.statusFields : [];
             const liveStatus = caps && 'liveStatus' in caps ? caps.liveStatus : undefined;

package/dist/commands/history.js

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import os from 'node:os';
 import { intArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson, isJsonMode, handleError, UsageError, emitJsonError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, exitWithError } from '../utils/output.js';
 import { readAudit, verifyAudit } from '../utils/audit.js';
 import { executeCommand } from '../lib/devices.js';
 import { queryDeviceHistory, queryDeviceHistoryStats, } from '../devices/history-query.js';
@@ -10,7 +10,7 @@ const DEFAULT_AUDIT = path.join(os.homedir(), '.switchbot', 'audit.log');
 export function registerHistoryCommand(program) {
     const history = program
         .command('history')
-        .description('View and replay commands recorded via --audit-log')
+        .description('View and replay SwitchBot commands recorded via --audit-log')
         .addHelpText('after', `
 Every 'devices command' run with --audit-log is appended as JSONL to the
 audit file (default ~/.switchbot/audit.log). 'history show' prints the file,
@@ -70,25 +70,19 @@ Examples:
         const entries = readAudit(file);
         const idx = Number(indexArg);
         if (!Number.isInteger(idx) || idx < 1 || idx > entries.length) {
-            const msg = `Invalid index ${indexArg}. Log has ${entries.length} entries.`;
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `Invalid index ${indexArg}. Log has ${entries.length} entries.`,
+            });
         }
         const entry = entries[idx - 1];
         if (entry.kind !== 'command') {
-            const msg = `Entry ${idx} is not a command (kind=${entry.kind}).`;
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `Entry ${idx} is not a command (kind=${entry.kind}).`,
+            });
         }
         try {
             const result = await executeCommand(entry.deviceId, entry.command, entry.parameter, entry.commandType);

package/dist/commands/identity.js

@@ -0,0 +1,59 @@
+/**
+ * Single source of truth for SwitchBot product identity.
+ *
+ * Consumed by:
+ *   - `program.description()` / `--help`   (via PRODUCT_TAGLINE in src/index.ts)
+ *   - `--help --json` root                  (via src/utils/help-json.ts)
+ *   - `switchbot capabilities` / `--json`   (identity block)
+ *   - `switchbot agent-bootstrap --json`    (identity block)
+ *
+ * Keeping this in one file prevents drift between those four surfaces.
+ *
+ * IMPORTANT: the SwitchBot CLI only talks to the SwitchBot Cloud API over
+ * HTTPS. It does NOT drive BLE radios directly — BLE-only devices are
+ * reached by going through a SwitchBot Hub, which the Cloud API already
+ * handles transparently. Please do not reintroduce the word "BLE" into the
+ * tagline / README: it is misleading for AI agents reading `--help`.
+ */
+export const IDENTITY = {
+    product: 'SwitchBot',
+    domain: 'IoT smart home device control',
+    vendor: 'Wonderlabs, Inc.',
+    apiVersion: 'v1.1',
+    apiDocs: 'https://github.com/OpenWonderLabs/SwitchBotAPI',
+    // Product category keywords. AI agents scan these to judge scope
+    // ("does SwitchBot control door locks? air conditioners?") without
+    // parsing the full device catalog.
+    productCategories: [
+        'lights (bulbs / strips / color)',
+        'locks / keypads',
+        'curtains / blinds / shades',
+        'sensors (motion / contact / climate / water-leak)',
+        'plugs / strips',
+        'bots / mechanical pushers',
+        'robot vacuums',
+        'IR appliances via Hub (TV / AC / fan / projector)',
+    ],
+    deviceCategories: {
+        physical: 'Wi-Fi-connected and Hub-mediated devices — controlled via Cloud API (CLI does not drive BLE directly)',
+        ir: 'IR remote devices learned by a SwitchBot Hub (TV, AC, fan, etc.)',
+    },
+    constraints: {
+        quotaPerDay: 10000,
+        hubRequiredForBle: true,
+        transport: 'Cloud API v1.1 (HTTPS)',
+        authMethod: 'HMAC-SHA256 token+secret',
+    },
+    agentGuide: 'docs/agent-guide.md',
+};
+/**
+ * One-line product description used for `program.description()` (the first
+ * line an AI agent sees when running `switchbot --help`).
+ *
+ * Structure: "SwitchBot smart home CLI — <product categories> via <transport>;
+ *             <verbs: scenes, events, MCP>." Keep categories in sync with
+ * IDENTITY.productCategories above.
+ */
+export const PRODUCT_TAGLINE = 'SwitchBot smart home CLI — control lights, locks, curtains, sensors, plugs, ' +
+    'and IR appliances (TV/AC/fan) via Cloud API v1.1; run scenes, stream real-time ' +
+    'events, and integrate AI agents via MCP.';

package/dist/commands/mcp.js

@@ -7,7 +7,7 @@ import { handleError, buildErrorPayload, exitWithError } from '../utils/output.j
 import { VERSION } from '../version.js';
 import { fetchDeviceList, fetchDeviceStatus, executeCommand, describeDevice, validateCommand, isDestructiveCommand, getDestructiveReason, searchCatalog, DeviceNotFoundError, toMcpDescribeShape, toMcpDeviceListShape, toMcpIrDeviceShape, } from '../lib/devices.js';
 import { fetchScenes, executeScene } from '../lib/scenes.js';
-import { findCatalogEntry } from '../devices/catalog.js';
+import { findCatalogEntry, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { validateParameter } from '../devices/param-validator.js';
 import { EventSubscriptionManager } from '../mcp/events-subscription.js';
@@ -362,7 +362,7 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     command: effectiveCommand,
                     deviceType: typeName,
                     description: spec?.description ?? null,
-                    ...(reason ? { destructiveReason: reason } : {}),
+                    ...(reason ? { safetyReason: reason, destructiveReason: reason } : {}),
                 },
             });
         }
@@ -516,6 +516,8 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
                     description: z.string(),
                     commandType: z.enum(['command', 'customize']).optional(),
                     idempotent: z.boolean().optional(),
+                    safetyTier: z.enum(['read', 'mutation', 'ir-fire-forget', 'destructive', 'maintenance']).optional(),
+                    safetyReason: z.string().optional(),
                     destructive: z.boolean().optional(),
                 }).passthrough()),
                 aliases: z.array(z.string()).optional(),
@@ -532,9 +534,22 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             });
         }
         const hits = searchCatalog(query, limit);
-        const structured = { results: hits, total: hits.length };
+        const normalised = hits.map((e) => ({
+            ...e,
+            commands: e.commands.map((c) => {
+                const tier = deriveSafetyTier(c, e);
+                const reason = getCommandSafetyReason(c);
+                return {
+                    ...c,
+                    safetyTier: tier,
+                    destructive: tier === 'destructive',
+                    ...(reason ? { safetyReason: reason } : {}),
+                };
+            }),
+        }));
+        const structured = { results: normalised, total: normalised.length };
         return {
-            content: [{ type: 'text', text: JSON.stringify(hits, null, 2) }],
+            content: [{ type: 'text', text: JSON.stringify(normalised, null, 2) }],
             structuredContent: structured,
         };
     });
@@ -591,16 +606,64 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
         _meta: { agentSafetyTier: 'read' },
         inputSchema: z
             .object({
-            deviceId: z.string().min(1),
-            since: z.string().optional(),
-            from: z.string().optional(),
-            to: z.string().optional(),
-            metrics: z.array(z.string().min(1)).min(1),
-            aggs: z.array(z.enum(ALL_AGG_FNS)).optional(),
-            bucket: z.string().optional(),
-            maxBucketSamples: z.number().int().positive().max(MAX_SAMPLE_CAP).optional(),
+            deviceId: z.string().min(1).describe('Device ID to aggregate over (must exist in ~/.switchbot/device-history/).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Relative window ending now, e.g. "30s", "15m", "1h", "7d". Mutually exclusive with from/to.'),
+            from: z.string().optional().describe('Range start (ISO-8601). Requires `to`.'),
+            to: z.string().optional().describe('Range end (ISO-8601). Requires `from`.'),
+            metrics: z
+                .array(z.string().min(1))
+                .min(1)
+                .describe('One or more numeric payload field names to aggregate (e.g. ["temperature","humidity"]).'),
+            aggs: z
+                .array(z.enum(ALL_AGG_FNS))
+                .optional()
+                .describe('Aggregation functions to apply per metric (default: ["count","avg"]).'),
+            bucket: z
+                .string()
+                .optional()
+                .describe('Bucket width like "5m", "1h", "1d". Omit for a single bucket spanning the full range.'),
+            maxBucketSamples: z
+                .number()
+                .int()
+                .positive()
+                .max(MAX_SAMPLE_CAP)
+                .optional()
+                .describe(`Sample cap per bucket to bound memory (default ${10_000}, max ${MAX_SAMPLE_CAP}). partial=true in the result when any bucket was capped.`),
         })
             .strict(),
+        outputSchema: {
+            deviceId: z.string(),
+            bucket: z.string().optional().describe('Bucket width echoed back when specified; omitted for single-bucket results.'),
+            from: z.string().describe('Effective range start (ISO-8601).'),
+            to: z.string().describe('Effective range end (ISO-8601).'),
+            metrics: z.array(z.string()).describe('Metrics that were requested.'),
+            aggs: z
+                .array(z.enum(ALL_AGG_FNS))
+                .describe('Aggregation functions that were applied.'),
+            buckets: z
+                .array(z.object({
+                t: z.string().describe('Bucket start timestamp (ISO-8601).'),
+                metrics: z
+                    .record(z.string(), z
+                    .object({
+                    count: z.number().optional(),
+                    min: z.number().optional(),
+                    max: z.number().optional(),
+                    avg: z.number().optional(),
+                    sum: z.number().optional(),
+                    p50: z.number().optional(),
+                    p95: z.number().optional(),
+                })
+                    .describe('Per-aggregate function result for this metric in this bucket.'))
+                    .describe('Per-metric result keyed by metric name.'),
+            }))
+                .describe('Time-ordered buckets; empty when no records match.'),
+            partial: z.boolean().describe('True if any bucket was sample-capped; retry with a higher maxBucketSamples or a narrower range for exact values.'),
+            notes: z.array(z.string()).describe('Human-readable notes about the aggregation (e.g. "metric X is non-numeric").'),
+        },
     }, async (args) => {
         const opts = {
             since: args.since,
@@ -612,9 +675,21 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
             maxBucketSamples: args.maxBucketSamples,
         };
         const res = await aggregateDeviceHistory(args.deviceId, opts);
+        const structured = {
+            deviceId: res.deviceId,
+            from: res.from,
+            to: res.to,
+            metrics: res.metrics,
+            aggs: res.aggs,
+            buckets: res.buckets,
+            partial: res.partial,
+            notes: res.notes,
+        };
+        if (res.bucket !== undefined)
+            structured.bucket = res.bucket;
         return {
             content: [{ type: 'text', text: JSON.stringify(res, null, 2) }],
-            structuredContent: res,
+            structuredContent: structured,
         };
     });
     // ---- account_overview ---------------------------------------------------
@@ -729,6 +804,18 @@ API docs: https://github.com/OpenWonderLabs/SwitchBotAPI`,
     }
     return server;
 }
+/**
+ * P10: list the tool names registered on an McpServer instance. Used by
+ * `doctor`'s dry-run check. The MCP SDK keeps `_registeredTools` private,
+ * so we reach through a narrow cast — safe because this only runs in
+ * diagnostic code and the shape is stable across SDK versions.
+ */
+export function listRegisteredTools(server) {
+    const internal = server;
+    if (!internal._registeredTools)
+        return [];
+    return Object.keys(internal._registeredTools).sort();
+}
 export function registerMcpCommand(program) {
     const mcp = program
         .command('mcp')

package/dist/commands/plan.js

@@ -160,7 +160,7 @@ function readStdin() {
 export function registerPlanCommand(program) {
     const plan = program
         .command('plan')
-        .description('Agent-authored batch plans: schema, validate, run')
+        .description('Author, validate, and run SwitchBot batch plans (JSON schema for AI agents)')
         .addHelpText('after', `
 A "plan" is a JSON document describing a sequence of commands/scenes/waits.
 The schema is fixed — agents emit plans, the CLI executes them. No LLM inside.

package/dist/commands/schema.js

@@ -1,6 +1,7 @@
 import { enumArg, stringArg } from '../utils/arg-parsers.js';
 import { printJson } from '../utils/output.js';
-import { getEffectiveCatalog } from '../devices/catalog.js';
+import { getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
+import { RESOURCE_CATALOG } from '../devices/resources.js';
 import { loadCache } from '../devices/cache.js';
 function toSchemaEntry(e) {
     return {
@@ -10,18 +11,22 @@ function toSchemaEntry(e) {
         aliases: e.aliases ?? [],
         role: e.role ?? null,
         readOnly: e.readOnly ?? false,
-        commands: e.commands.map(toSchemaCommand),
+        commands: e.commands.map((c) => toSchemaCommand(c, e)),
         statusFields: e.statusFields ?? [],
     };
 }
-function toSchemaCommand(c) {
+function toSchemaCommand(c, entry) {
+    const tier = deriveSafetyTier(c, entry);
+    const reason = getCommandSafetyReason(c);
     return {
         command: c.command,
         parameter: c.parameter,
         description: c.description,
         commandType: (c.commandType ?? 'command'),
         idempotent: Boolean(c.idempotent),
-        destructive: Boolean(c.destructive),
+        safetyTier: tier,
+        destructive: tier === 'destructive',
+        ...(reason ? { safetyReason: reason } : {}),
         ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
     };
 }
@@ -31,13 +36,17 @@ function toCompactEntry(e) {
         category: e.category,
         role: e.role ?? null,
         readOnly: e.readOnly ?? false,
-        commands: e.commands.map((c) => ({
-            command: c.command,
-            parameter: c.parameter,
-            commandType: (c.commandType ?? 'command'),
-            idempotent: Boolean(c.idempotent),
-            destructive: Boolean(c.destructive),
-        })),
+        commands: e.commands.map((c) => {
+            const tier = deriveSafetyTier(c, e);
+            return {
+                command: c.command,
+                parameter: c.parameter,
+                commandType: (c.commandType ?? 'command'),
+                idempotent: Boolean(c.idempotent),
+                safetyTier: tier,
+                destructive: tier === 'destructive',
+            };
+        }),
         statusFields: e.statusFields ?? [],
     };
 }
@@ -54,7 +63,7 @@ export function registerSchemaCommand(program) {
     const CATEGORIES = ['physical', 'ir'];
     const schema = program
         .command('schema')
-        .description('Export the device catalog as structured JSON (for agent prompts / tooling)');
+        .description('Export the SwitchBot device catalog as structured JSON (for AI agent prompts / tooling)');
     schema
         .command('export')
         .description('Print the catalog as structured JSON (one object per type)')
@@ -137,6 +146,7 @@ Examples:
         };
         if (!options.compact) {
             payload.generatedAt = new Date().toISOString();
+            payload.resources = RESOURCE_CATALOG;
             payload.cliAddedFields = [
                 {
                     field: '_fetchedAt',