@switchbot/openapi-cli 2.6.4 → 3.0.0

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) {
@@ -89,10 +114,10 @@ export function startReceiver(port, pathMatch, filter, onEvent) {
             if (size > MAX_BODY_BYTES) {
                 bailed = true;
                 res.statusCode = 413;
-                res.setHeader('connection', 'close');
                 res.end('payload too large');
-                // Drop remaining upload without destroying the socket mid-flush.
-                req.on('data', () => { });
+                // Drain remaining upload so the client can read the 413 response before
+                // the connection closes naturally (avoids ECONNRESET racing the response).
+                req.resume();
                 return;
             }
             chunks.push(c);
@@ -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,15 @@ 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 } : {}),
+                    };
+                })
                 : [];
             const statusFields = caps && 'statusFields' in caps ? caps.statusFields : [];
             const liveStatus = caps && 'liveStatus' in caps ? caps.liveStatus : undefined;
@@ -110,7 +113,7 @@ function printHuman(r) {
     if (r.commands.length) {
         console.log('commands:');
         for (const c of r.commands) {
-            const flags = [c.idempotent && 'idempotent', c.destructive && 'destructive']
+            const flags = [c.idempotent && 'idempotent', c.safetyTier === 'destructive' && 'destructive']
                 .filter(Boolean)
                 .join(', ');
             const suffix = flags ? `  [${flags}]` : '';

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/install.js

@@ -0,0 +1,246 @@
+/**
+ * `switchbot install` — one-command bootstrap (Phase 3B in-repo).
+ *
+ * Collapses the 7-step Quickstart (credentials → policy → skill link →
+ * doctor verify) into a single orchestrated command with automatic
+ * rollback on any step failure. The step library
+ * (`src/install/default-steps.ts`) does the heavy lifting; this file
+ * composes the steps based on user flags, drives the step runner, and
+ * formats the outcome.
+ *
+ * Design notes:
+ * - `switchbot install` assumes the CLI is already on PATH (the user
+ *   ran `npm i -g @switchbot/openapi-cli` to get here). We do not
+ *   re-install the CLI from inside itself.
+ * - Doctor verification is NOT a step — if it failed, an automatic
+ *   rollback would destroy good state. Instead we print a "next: run
+ *   `switchbot doctor`" hint after success.
+ */
+import { InvalidArgumentError } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolvePolicyPath } from '../policy/load.js';
+import { runInstall } from '../install/steps.js';
+import { runPreflight } from '../install/preflight.js';
+import { stepPromptCredentials, stepWriteKeychain, stepScaffoldPolicy, stepSymlinkSkill, stepDoctorVerify, } from '../install/default-steps.js';
+import { isJsonMode, printJson } from '../utils/output.js';
+import { getActiveProfile } from '../lib/request-context.js';
+import chalk from 'chalk';
+const AGENT_VALUES = ['claude-code', 'cursor', 'copilot', 'none'];
+function parseAgent(value) {
+    if (!value)
+        return 'claude-code';
+    if (!AGENT_VALUES.includes(value)) {
+        throw new InvalidArgumentError(`--agent must be one of ${AGENT_VALUES.join(', ')} (got "${value}")`);
+    }
+    return value;
+}
+function parseSkipList(value) {
+    if (!value)
+        return new Set();
+    return new Set(value
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean));
+}
+function printRecipe(ctx) {
+    if (!ctx.skillRecipePrinted)
+        return;
+    const lines = [];
+    lines.push('');
+    lines.push(chalk.bold(`Skill-install recipe for agent=${ctx.agent}:`));
+    switch (ctx.agent) {
+        case 'claude-code':
+            lines.push('  # re-run with --skill-path pointing at your local clone of openclaw-switchbot-skill', '  switchbot install --agent claude-code --skill-path /path/to/openclaw-switchbot-skill');
+            break;
+        case 'cursor':
+            lines.push('  # Cursor expects a rules file, not a skill directory. See:', '  #   openclaw-switchbot-skill/docs/agents/cursor.md');
+            break;
+        case 'copilot':
+            lines.push('  # Copilot merges instructions into .github/copilot-instructions.md. See:', '  #   openclaw-switchbot-skill/docs/agents/copilot.md');
+            break;
+        case 'none':
+            lines.push('  (none — skill step skipped)');
+            break;
+    }
+    console.error(lines.join('\n'));
+}
+function printDryRun(steps, ctx) {
+    if (isJsonMode()) {
+        printJson({
+            dryRun: true,
+            profile: ctx.profile,
+            agent: ctx.agent,
+            skillPath: ctx.skillPath ?? null,
+            policyPath: ctx.policyPath,
+            steps: steps.map((s) => ({ name: s.name, description: s.description })),
+        });
+        return;
+    }
+    console.log(chalk.bold('switchbot install — dry run'));
+    console.log(`  profile: ${ctx.profile}`);
+    console.log(`  agent:   ${ctx.agent}`);
+    console.log(`  skill:   ${ctx.skillPath ?? '(none — recipe will be printed)'}`);
+    console.log(`  policy:  ${ctx.policyPath}`);
+    console.log('');
+    console.log(chalk.bold('Steps that would run (in order):'));
+    for (const s of steps) {
+        console.log(`  • ${s.name}${s.description ? `  — ${s.description}` : ''}`);
+    }
+    console.log('');
+    console.log(chalk.dim('No changes made. Re-run without --dry-run to apply.'));
+}
+export function registerInstallCommand(program) {
+    program
+        .command('install')
+        .description('One-command bootstrap: credentials + policy + skill link (rolls back on failure)')
+        .option('--agent <name>', `target agent: ${AGENT_VALUES.join(' | ')} (default: claude-code)`)
+        .option('--skill-path <dir>', 'local clone of openclaw-switchbot-skill (enables auto-link)')
+        .option('--token-file <path>', 'two-line credential file (token, secret); read once and deleted on success')
+        .option('--skip <names>', 'comma-separated list of step names to skip (e.g. "scaffold-policy,symlink-skill")')
+        .option('--force', 'replace an existing skill symlink pointing at a different path; allow link even without SKILL.md')
+        .option('--verify', 'after a successful install, run `switchbot doctor --json` as a warn-only post-check')
+        .addHelpText('after', `
+The global --dry-run flag previews the step list without making changes.
+Global --json emits the install report as JSON to stdout.
+
+Exit codes:
+  0  success
+  2  preflight check failed (nothing changed)
+  3  step failed; rollback completed
+  4  step failed; rollback had residue (see output)
+
+Examples:
+  # Interactive install, Claude Code skill not linked (recipe printed):
+  switchbot install
+
+  # Full install with skill link:
+  switchbot install --skill-path ../openclaw-switchbot-skill
+
+  # Non-interactive (CI) install:
+  printf '%s\\n%s\\n' "$TOKEN" "$SECRET" > /tmp/sb-creds
+  switchbot install --token-file /tmp/sb-creds --skill-path ./skill
+`)
+        .action(async (opts, command) => {
+        const agent = parseAgent(opts.agent);
+        const profile = getActiveProfile() ?? 'default';
+        const skip = parseSkipList(opts.skip);
+        const skillPath = opts.skillPath ? path.resolve(opts.skillPath) : undefined;
+        const tokenFile = opts.tokenFile ? path.resolve(opts.tokenFile) : undefined;
+        const force = Boolean(opts.force);
+        const verify = Boolean(opts.verify);
+        const globalOpts = command.parent?.opts() ?? {};
+        const dryRun = Boolean(globalOpts.dryRun);
+        // Pre-flight: read-only checks, never mutate anything.
+        const pf = await runPreflight({
+            agent,
+            expectSkillLink: agent === 'claude-code' && Boolean(skillPath),
+        });
+        if (!pf.ok) {
+            if (isJsonMode()) {
+                printJson({ ok: false, stage: 'preflight', preflight: pf });
+            }
+            else {
+                console.error(chalk.red('✗ preflight failed — nothing changed'));
+                for (const c of pf.checks) {
+                    const mark = c.status === 'fail' ? chalk.red('✗') : c.status === 'warn' ? chalk.yellow('!') : chalk.green('✓');
+                    console.error(`  ${mark} ${c.name}: ${c.message}`);
+                    if (c.hint)
+                        console.error(`      hint: ${c.hint}`);
+                }
+            }
+            process.exit(2);
+        }
+        const ctx = {
+            profile,
+            agent,
+            skillPath,
+            tokenFile,
+            policyPath: resolvePolicyPath(),
+            nonInteractive: !process.stdin.isTTY && !tokenFile,
+        };
+        const allSteps = [
+            stepPromptCredentials(),
+            stepWriteKeychain(),
+            stepScaffoldPolicy(),
+            stepSymlinkSkill({ force }),
+        ];
+        const steps = allSteps.filter((s) => !skip.has(s.name));
+        if (dryRun) {
+            printDryRun(steps, ctx);
+            return;
+        }
+        const report = await runInstall(steps, { context: ctx });
+        // Delete the token file now that credentials are committed.
+        if (report.ok && tokenFile) {
+            try {
+                fs.unlinkSync(tokenFile);
+            }
+            catch {
+                // non-fatal: credentials are already in the keychain
+            }
+        }
+        // A7: opt-in post-install verification. Doctor is NEVER part of the
+        // rollback chain — a failing doctor after a good install would
+        // destroy working state. So we run it AFTER runInstall resolves, as
+        // a warn-only check. The outcome is reported but never flips the
+        // command's exit code.
+        if (report.ok && verify) {
+            const cliPath = process.argv[1] ?? '';
+            const step = stepDoctorVerify({ cliPath });
+            await step.execute(ctx);
+        }
+        if (isJsonMode()) {
+            printJson({
+                ok: report.ok,
+                profile: ctx.profile,
+                agent: ctx.agent,
+                report,
+                preflight: pf,
+                policyPath: ctx.policyPath,
+                policyScaffolded: ctx.policyScaffoldResult && !ctx.policyScaffoldResult.skipped,
+                skillLinkPath: ctx.skillLinkPath,
+                skillLinkCreated: Boolean(ctx.skillLinkCreated),
+                verify: verify ? { ok: ctx.doctorOk ?? null, report: ctx.doctorReport ?? null } : undefined,
+            });
+        }
+        else if (report.ok) {
+            console.log(chalk.green('✓ install complete'));
+            if (ctx.skillLinkCreated)
+                console.log(`  linked skill: ${ctx.skillLinkPath}`);
+            if (ctx.policyScaffoldResult?.skipped === false)
+                console.log(`  wrote policy: ${ctx.policyScaffoldResult.policyPath}`);
+            printRecipe(ctx);
+            if (verify) {
+                if (ctx.doctorOk) {
+                    console.log(chalk.green('✓ doctor --json: all green'));
+                }
+                else {
+                    console.log(chalk.yellow('! doctor --json reported issues — install is committed; run `switchbot doctor` to inspect'));
+                }
+            }
+            console.log('');
+            console.log(chalk.bold('Next:'));
+            console.log('  switchbot doctor        # verify the setup');
+            console.log('  switchbot devices list  # smoke test');
+        }
+        else {
+            console.error(chalk.red(`✗ install failed at step: ${report.failedAt}`));
+            const residue = report.outcomes.some((o) => o.status === 'rollback-failed');
+            for (const o of report.outcomes) {
+                const tag = o.status === 'succeeded' ? chalk.green('✓') :
+                    o.status === 'failed' ? chalk.red('✗') :
+                        o.status === 'rolled-back' ? chalk.yellow('↺') :
+                            o.status === 'rollback-failed' ? chalk.red('!!') :
+                                chalk.dim('·');
+                const msg = o.status === 'failed' || o.status === 'rollback-failed' ? ` — ${o.error}` : '';
+                console.error(`  ${tag} ${o.step} [${o.status}]${msg}`);
+            }
+            if (residue) {
+                console.error(chalk.red('Rollback left residue. Run `switchbot uninstall` to clean up or review output above.'));
+                process.exit(4);
+            }
+            process.exit(3);
+        }
+    });
+}