@switchbot/openapi-cli 2.6.4 → 3.0.0

package/dist/commands/doctor.js

@@ -1,36 +1,134 @@
 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';
+import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError, PolicyYamlParseError, } from '../policy/load.js';
+import { validateLoadedPolicy } from '../policy/validate.js';
+import { selectCredentialStore } from '../credentials/keychain.js';
+import { getActiveProfile } from '../lib/request-context.js';
 export const DOCTOR_SCHEMA_VERSION = 1;
 async function checkCredentials() {
     const envOk = Boolean(process.env.SWITCHBOT_TOKEN && process.env.SWITCHBOT_SECRET);
-    if (envOk)
-        return { name: 'credentials', status: 'ok', detail: 'env: SWITCHBOT_TOKEN + SWITCHBOT_SECRET' };
+    const profile = getActiveProfile() ?? 'default';
+    let backendName = 'file';
+    let backendLabel = 'file';
+    let writable = true;
+    let keychainHasProfile = false;
+    try {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        backendName = store.name;
+        backendLabel = desc.backend;
+        writable = desc.writable;
+        try {
+            const creds = await store.get(profile);
+            keychainHasProfile = Boolean(creds && creds.token && creds.secret);
+        }
+        catch {
+            keychainHasProfile = false;
+        }
+    }
+    catch {
+        // selectCredentialStore falls back to file; a throw here is unexpected but
+        // non-fatal — downstream callers degrade to the file path.
+    }
+    if (envOk) {
+        return {
+            name: 'credentials',
+            status: 'ok',
+            detail: {
+                source: 'env',
+                backend: backendName,
+                backendLabel,
+                writable,
+                profile,
+                message: 'env: SWITCHBOT_TOKEN + SWITCHBOT_SECRET',
+            },
+        };
+    }
+    if (keychainHasProfile && backendName !== 'file') {
+        return {
+            name: 'credentials',
+            status: 'ok',
+            detail: {
+                source: 'keychain',
+                backend: backendName,
+                backendLabel,
+                writable,
+                profile,
+                message: `keychain (${backendLabel}) has credentials for profile "${profile}"`,
+            },
+        };
+    }
     const file = configFilePath();
     if (!fs.existsSync(file)) {
         return {
             name: 'credentials',
             status: 'fail',
-            detail: `No env vars and no config at ${file}. Run 'switchbot config set-token'.`,
+            detail: {
+                source: 'none',
+                backend: backendName,
+                backendLabel,
+                writable,
+                profile,
+                message: `No env vars, no keychain entry for profile "${profile}", and no config at ${file}. Run 'switchbot config set-token' or 'switchbot auth keychain set'.`,
+            },
         };
     }
     try {
         const raw = fs.readFileSync(file, 'utf-8');
         const cfg = JSON.parse(raw);
         if (!cfg.token || !cfg.secret) {
-            return { name: 'credentials', status: 'fail', detail: `Config ${file} missing token/secret.` };
+            return {
+                name: 'credentials',
+                status: 'fail',
+                detail: {
+                    source: 'file',
+                    backend: backendName,
+                    backendLabel,
+                    writable,
+                    profile,
+                    message: `Config ${file} missing token/secret.`,
+                },
+            };
         }
-        return { name: 'credentials', status: 'ok', detail: `file: ${file}` };
+        const status = writable && backendName !== 'file' ? 'warn' : 'ok';
+        const hint = status === 'warn'
+            ? `Consider running 'switchbot auth keychain migrate' to move credentials into ${backendLabel}.`
+            : undefined;
+        return {
+            name: 'credentials',
+            status,
+            detail: {
+                source: 'file',
+                backend: backendName,
+                backendLabel,
+                writable,
+                profile,
+                message: `file: ${file}`,
+                ...(hint ? { hint } : {}),
+            },
+        };
     }
     catch (err) {
         return {
             name: 'credentials',
             status: 'fail',
-            detail: `Unreadable config ${file}: ${err instanceof Error ? err.message : String(err)}`,
+            detail: {
+                source: 'file',
+                backend: backendName,
+                backendLabel,
+                writable,
+                profile,
+                message: `Unreadable config ${file}: ${err instanceof Error ? err.message : String(err)}`,
+            },
         };
     }
 }
@@ -160,15 +258,226 @@ 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 checkPolicy() {
+    // A policy file is optional — many users run the CLI without one. Report
+    // `ok` with `present: false` so agents can tell the difference between
+    // "no policy configured" (fine) and "policy broken" (needs attention).
+    const policyPath = resolvePolicyPath();
+    try {
+        const loaded = loadPolicyFile(policyPath);
+        const result = validateLoadedPolicy(loaded);
+        if (result.valid) {
+            return {
+                name: 'policy',
+                status: 'ok',
+                detail: {
+                    path: policyPath,
+                    present: true,
+                    valid: true,
+                    schemaVersion: result.schemaVersion,
+                },
+            };
+        }
+        return {
+            name: 'policy',
+            status: 'fail',
+            detail: {
+                path: policyPath,
+                present: true,
+                valid: false,
+                schemaVersion: result.schemaVersion,
+                errorCount: result.errors.length,
+                firstError: result.errors[0]
+                    ? {
+                        path: result.errors[0].path,
+                        line: result.errors[0].line,
+                        message: result.errors[0].message,
+                    }
+                    : undefined,
+                message: "run 'switchbot policy validate' for full diagnostics",
+            },
+        };
+    }
+    catch (err) {
+        if (err instanceof PolicyFileNotFoundError) {
+            return {
+                name: 'policy',
+                status: 'ok',
+                detail: {
+                    path: policyPath,
+                    present: false,
+                    message: "no policy file (optional — run 'switchbot policy new' to scaffold one)",
+                },
+            };
+        }
+        if (err instanceof PolicyYamlParseError) {
+            const first = err.yamlErrors[0];
+            return {
+                name: 'policy',
+                status: 'fail',
+                detail: {
+                    path: policyPath,
+                    present: true,
+                    valid: false,
+                    parseError: true,
+                    line: first?.line,
+                    col: first?.col,
+                    message: first?.message ?? err.message,
+                },
+            };
+        }
+        return {
+            name: 'policy',
+            status: 'warn',
+            detail: {
+                path: policyPath,
+                message: `could not read policy file: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        };
     }
 }
 function checkNodeVersion() {
@@ -210,10 +519,161 @@ 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: 'policy', description: 'policy.yaml present + schema-valid (if configured)', run: () => checkPolicy() },
+    { 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 +681,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,29 +734,48 @@ 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) {
                 const icon = c.status === 'ok' ? '✓' : c.status === 'warn' ? '!' : '✗';
-                const detailStr = typeof c.detail === 'string' ? c.detail : JSON.stringify(c.detail);
+                const detailStr = typeof c.detail === 'string'
+                    ? c.detail
+                    : (typeof c.detail.message === 'string'
+                        ? (c.detail.message)
+                        : JSON.stringify(c.detail));
                 console.log(`${icon} ${c.name.padEnd(12)} ${detailStr}`);
             }
             console.log('');
             console.log(`${summary.ok} ok, ${summary.warn} warn, ${summary.fail} fail`);
+            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);