@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/api/client.js

@@ -3,7 +3,7 @@ import chalk from 'chalk';
 import { buildAuthHeaders } from '../auth.js';
 import { loadConfig } from '../config.js';
 import { isVerbose, isDryRun, getTimeout, getRetryOn429, getRetryOn5xx, getBackoffStrategy, isQuotaDisabled, } from '../utils/flags.js';
-import { nextRetryDelayMs, sleep } from '../utils/retry.js';
+import { nextRetryDelayMs, sleep, CircuitBreaker, CircuitOpenError } from '../utils/retry.js';
 import { recordRequest, checkDailyCap } from '../utils/quota.js';
 import { readProfileMeta } from '../config.js';
 import { getActiveProfile } from '../lib/request-context.js';
@@ -40,6 +40,17 @@ export class DryRunSignal extends Error {
         this.name = 'DryRunSignal';
     }
 }
+/**
+ * Module-level circuit breaker for the SwitchBot API. Shared across all
+ * client instances in the process. Opens after 5 consecutive 5xx / network
+ * errors; resets to half-open after 60 s.
+ * Exported for health-check inspection.
+ */
+export const apiCircuitBreaker = new CircuitBreaker('switchbot-api', {
+    failureThreshold: 5,
+    resetTimeoutMs: 60_000,
+});
+export { CircuitOpenError };
 export function createClient() {
     const { token, secret } = loadConfig();
     const verbose = isVerbose();
@@ -57,6 +68,8 @@ export function createClient() {
     });
     // Inject auth headers; optionally log the request; short-circuit on --dry-run.
     client.interceptors.request.use((config) => {
+        // Circuit breaker check — fail fast when the API is consistently down.
+        apiCircuitBreaker.checkAndAllow();
         // Pre-flight cap check: refuse the call before it touches the network.
         if (dailyCap) {
             const check = checkDailyCap(dailyCap);
@@ -110,6 +123,8 @@ export function createClient() {
                 `API error code: ${data.statusCode}`;
             throw new ApiError(msg, data.statusCode);
         }
+        // Successful HTTP response — record for circuit breaker.
+        apiCircuitBreaker.recordSuccess();
         return response;
     }, (error) => {
         if (error instanceof DryRunSignal)
@@ -131,6 +146,8 @@ export function createClient() {
                         return sleep(delay).then(() => client.request(config));
                     }
                 }
+                // Network-level failure — record for circuit breaker.
+                apiCircuitBreaker.recordFailure();
                 throw new ApiError(`Request timed out after ${getTimeout()}ms (override with --timeout <ms>)`, 0, { transient: true, retryable: isIdempotentRead });
             }
             const status = error.response?.status;
@@ -165,6 +182,11 @@ export function createClient() {
                     return sleep(delay).then(() => client.request(config));
                 }
             }
+            // Record 5xx and network errors for circuit breaker. 4xx errors are
+            // expected business responses — don't count toward circuit threshold.
+            if (status === undefined || status >= 500) {
+                apiCircuitBreaker.recordFailure();
+            }
             // P8: quota already recorded in the request interceptor before
             // dispatch — no extra bookkeeping needed here on the error path.
             // Timeouts, DNS failures, 5xx, and exhausted retries all counted

package/dist/commands/agent-bootstrap.js

@@ -5,6 +5,9 @@ import { readProfileMeta } from '../config.js';
 import { todayUsage, DAILY_QUOTA } from '../utils/quota.js';
 import { ALL_STRATEGIES } from '../utils/name-resolver.js';
 import { IDENTITY } from './identity.js';
+import { resolvePolicyPath, loadPolicyFile, PolicyFileNotFoundError, PolicyYamlParseError, } from '../policy/load.js';
+import { validateLoadedPolicy } from '../policy/validate.js';
+import { selectCredentialStore } from '../credentials/keychain.js';
 import { createRequire } from 'node:module';
 const require = createRequire(import.meta.url);
 const { version: pkgVersion } = require('../../package.json');
@@ -28,7 +31,47 @@ const QUICK_REFERENCE = {
     observability: ['doctor --json', 'quota status', 'cache status', 'events mqtt-tail'],
     history: ['history range <id> --since 7d', 'history stats <id>'],
     meta: ['devices meta set <id> --alias <name>', 'devices meta list', 'devices meta get <id>'],
+    policy: ['policy validate', 'policy new', 'policy migrate'],
+    auth: ['auth keychain describe', 'auth keychain migrate', 'auth keychain get'],
 };
+function readPolicyStatus() {
+    // Lightweight read — used by the bootstrap payload so agents know whether
+    // a policy file exists and is healthy without shelling out to
+    // `switchbot policy validate`. Parallel to `checkPolicy` in doctor but
+    // returns a more compact shape (no first-error drill-down; agents who
+    // want that run the dedicated command).
+    const policyPath = resolvePolicyPath();
+    try {
+        const loaded = loadPolicyFile(policyPath);
+        const result = validateLoadedPolicy(loaded);
+        return {
+            present: true,
+            valid: result.valid,
+            path: policyPath,
+            schemaVersion: result.schemaVersion,
+            errorCount: result.valid ? 0 : result.errors.length,
+        };
+    }
+    catch (err) {
+        if (err instanceof PolicyFileNotFoundError) {
+            return { present: false, valid: null, path: policyPath };
+        }
+        if (err instanceof PolicyYamlParseError) {
+            return { present: true, valid: false, path: policyPath, errorCount: 1 };
+        }
+        return { present: false, valid: null, path: policyPath };
+    }
+}
+async function readCredentialsBackend() {
+    try {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        return { name: store.name, label: desc.backend, writable: desc.writable };
+    }
+    catch {
+        return { name: 'file', label: 'File (~/.switchbot/config.json)', writable: true };
+    }
+}
 export function registerAgentBootstrapCommand(program) {
     program
         .command('agent-bootstrap')
@@ -49,12 +92,13 @@ Examples:
   $ switchbot agent-bootstrap | jq '.devices | length'
   $ switchbot agent-bootstrap --compact | jq '.quickReference'
 `)
-        .action((opts) => {
+        .action(async (opts) => {
         const compact = Boolean(opts.compact);
         const cache = loadCache();
         const catalog = getEffectiveCatalog();
         const usage = todayUsage();
         const meta = readProfileMeta(undefined);
+        const credentialsBackend = await readCredentialsBackend();
         const cachedDevices = cache
             ? Object.entries(cache.devices).map(([id, d]) => ({
                 deviceId: id,
@@ -91,7 +135,6 @@ Examples:
                         command: c.command,
                         parameter: c.parameter,
                         safetyTier: tier,
-                        destructive: tier === 'destructive',
                         idempotent: Boolean(c.idempotent),
                     };
                 }),
@@ -120,6 +163,8 @@ Examples:
                 remaining: usage.remaining,
                 dailyLimit: DAILY_QUOTA,
             },
+            policyStatus: readPolicyStatus(),
+            credentialsBackend,
             devices: cachedDevices,
             catalog: {
                 scope: cachedDevices.length > 0 ? 'used' : 'all',

package/dist/commands/auth.js

@@ -0,0 +1,354 @@
+/**
+ * `switchbot auth` command group (v2.9 preview, part of Phase 3A).
+ *
+ * Surfaces the credential store abstraction added in F1/F2 so users
+ * can introspect, write to, delete from, and migrate into the OS
+ * keychain without editing `~/.switchbot/config.json` by hand.
+ *
+ * All subcommands honour the active `--profile <name>` flag so a user
+ * who runs multiple accounts keeps the keychain entries cleanly
+ * partitioned.
+ *
+ * No credential material is ever printed in plain text. `get` emits
+ * a masked summary only; `set` reads via a TTY prompt (echo-off) or a
+ * file passed via `--stdin-file <path>`. `migrate` never touches the
+ * keychain unless the backend reports `writable: true`.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import readline from 'node:readline';
+import { exitWithError, isJsonMode, printJson } from '../utils/output.js';
+import { stringArg } from '../utils/arg-parsers.js';
+import { getActiveProfile } from '../lib/request-context.js';
+import { selectCredentialStore, } from '../credentials/keychain.js';
+function activeProfile() {
+    return getActiveProfile() ?? 'default';
+}
+function maskValue(value) {
+    if (value.length === 0)
+        return '';
+    if (value.length <= 4)
+        return '*'.repeat(value.length);
+    const head = value.slice(0, 2);
+    const tail = value.slice(-2);
+    return `${head}${'*'.repeat(Math.max(4, value.length - 4))}${tail}`;
+}
+async function promptSecret(question) {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+    return new Promise((resolve) => {
+        process.stderr.write(question);
+        const stdin = process.stdin;
+        let answer = '';
+        const onData = (chunk) => {
+            const s = chunk.toString('utf-8');
+            for (const ch of s) {
+                if (ch === '\r' || ch === '\n') {
+                    stdin.removeListener('data', onData);
+                    if (stdin.setRawMode)
+                        stdin.setRawMode(false);
+                    stdin.pause();
+                    process.stderr.write('\n');
+                    rl.close();
+                    resolve(answer);
+                    return;
+                }
+                if (ch === '\u0003') {
+                    process.exit(130);
+                }
+                if (ch === '\u007f' || ch === '\b') {
+                    answer = answer.slice(0, -1);
+                    continue;
+                }
+                answer += ch;
+            }
+        };
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        stdin.on('data', onData);
+    });
+}
+function readStdinFile(filePath) {
+    if (!fs.existsSync(filePath)) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: `--stdin-file: file not found: ${filePath}`,
+        });
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    }
+    catch (err) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: `--stdin-file: invalid JSON: ${err instanceof Error ? err.message : String(err)}`,
+        });
+    }
+    if (!parsed ||
+        typeof parsed !== 'object' ||
+        typeof parsed.token !== 'string' ||
+        typeof parsed.secret !== 'string') {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: '--stdin-file must contain a JSON object with "token" and "secret" strings.',
+        });
+    }
+    const { token, secret } = parsed;
+    if (!token || !secret) {
+        exitWithError({
+            code: 2,
+            kind: 'usage',
+            message: '--stdin-file: token and secret must be non-empty.',
+        });
+    }
+    return { token, secret };
+}
+function cleanupMigratedSourceFile(sourceFile, parsed) {
+    const next = { ...parsed };
+    delete next.token;
+    delete next.secret;
+    if (Object.keys(next).length === 0) {
+        fs.unlinkSync(sourceFile);
+        return 'deleted';
+    }
+    fs.writeFileSync(sourceFile, JSON.stringify(next, null, 2), { mode: 0o600 });
+    return 'scrubbed';
+}
+export function registerAuthCommand(program) {
+    const auth = program
+        .command('auth')
+        .description('Manage SwitchBot credentials in the OS keychain (preview)');
+    const keychain = auth
+        .command('keychain')
+        .description('OS keychain backend (describe/get/set/delete/migrate)');
+    keychain
+        .command('describe')
+        .description('Show which credential backend is active on this machine')
+        .action(async () => {
+        const store = await selectCredentialStore();
+        const desc = store.describe();
+        if (isJsonMode()) {
+            printJson(desc);
+            return;
+        }
+        console.log(`backend : ${desc.backend}`);
+        console.log(`tag     : ${desc.tag}`);
+        console.log(`writable: ${desc.writable ? 'yes' : 'no'}`);
+        if (desc.notes)
+            console.log(`notes   : ${desc.notes}`);
+    });
+    keychain
+        .command('get')
+        .description('Check whether the active profile has credentials (masked output)')
+        .action(async () => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        const creds = await store.get(profile);
+        if (!creds) {
+            if (isJsonMode()) {
+                printJson({ profile, backend: store.name, present: false });
+                return;
+            }
+            console.log(`No credentials found for profile "${profile}" in backend "${store.name}".`);
+            process.exit(1);
+        }
+        if (isJsonMode()) {
+            printJson({
+                profile,
+                backend: store.name,
+                present: true,
+                token: { length: creds.token.length, masked: maskValue(creds.token) },
+                secret: { length: creds.secret.length, masked: maskValue(creds.secret) },
+            });
+            return;
+        }
+        console.log(`profile : ${profile}`);
+        console.log(`backend : ${store.name}`);
+        console.log(`token   : ${maskValue(creds.token)} (${creds.token.length} chars)`);
+        console.log(`secret  : ${maskValue(creds.secret)} (${creds.secret.length} chars)`);
+    });
+    keychain
+        .command('set')
+        .description('Write token and secret to the keychain for the active profile')
+        .option('--stdin-file <path>', 'Read {"token","secret"} JSON from file (for non-TTY environments)', stringArg('--stdin-file'))
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!store.describe().writable) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `backend "${store.name}" is not writable on this machine`,
+                hint: 'Install the OS keychain helper or use ~/.switchbot/config.json directly.',
+            });
+        }
+        let bundle;
+        if (options.stdinFile) {
+            bundle = readStdinFile(options.stdinFile);
+        }
+        else if (process.stdin.isTTY) {
+            const token = (await promptSecret('Token : ')).trim();
+            const secret = (await promptSecret('Secret: ')).trim();
+            if (!token || !secret) {
+                exitWithError({
+                    code: 2,
+                    kind: 'usage',
+                    message: 'Both token and secret are required.',
+                });
+            }
+            bundle = { token, secret };
+        }
+        else {
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: 'Non-TTY input requires --stdin-file <path>.',
+            });
+        }
+        try {
+            await store.set(profile, bundle);
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain write failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (isJsonMode()) {
+            printJson({ profile, backend: store.name, written: true });
+            return;
+        }
+        console.log(`Stored credentials for profile "${profile}" in backend "${store.name}".`);
+    });
+    keychain
+        .command('delete')
+        .description('Remove credentials for the active profile from the keychain')
+        .option('--yes', 'Skip the interactive confirmation prompt')
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!options.yes && process.stdin.isTTY) {
+            const reply = (await promptSecret(`Delete credentials for profile "${profile}" from backend "${store.name}"? type DELETE to confirm: `)).trim();
+            if (reply !== 'DELETE') {
+                if (isJsonMode()) {
+                    printJson({ profile, backend: store.name, deleted: false, reason: 'cancelled' });
+                    return;
+                }
+                console.log('Aborted.');
+                process.exit(0);
+            }
+        }
+        try {
+            await store.delete(profile);
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain delete failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        if (isJsonMode()) {
+            printJson({ profile, backend: store.name, deleted: true });
+            return;
+        }
+        console.log(`Deleted credentials for profile "${profile}" in backend "${store.name}".`);
+    });
+    keychain
+        .command('migrate')
+        .description('Copy credentials from ~/.switchbot/config.json (or --profile) into the keychain')
+        .option('--delete-file', 'Remove the source credential file when possible; otherwise scrub token/secret and keep metadata')
+        .action(async (options) => {
+        const profile = activeProfile();
+        const store = await selectCredentialStore();
+        if (!store.describe().writable) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `backend "${store.name}" is not writable on this machine`,
+            });
+        }
+        const sourceFile = profile === 'default'
+            ? path.join(os.homedir(), '.switchbot', 'config.json')
+            : path.join(os.homedir(), '.switchbot', 'profiles', `${profile}.json`);
+        if (!fs.existsSync(sourceFile)) {
+            exitWithError({
+                code: 2,
+                kind: 'usage',
+                message: `source file not found: ${sourceFile}`,
+                hint: 'Run "switchbot config set-token" first or use "switchbot auth keychain set" directly.',
+            });
+        }
+        let parsed;
+        try {
+            const raw = JSON.parse(fs.readFileSync(sourceFile, 'utf-8'));
+            if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+                throw new Error('expected a JSON object');
+            }
+            parsed = raw;
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `failed to parse ${sourceFile}: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        const token = typeof parsed.token === 'string' ? parsed.token : '';
+        const secret = typeof parsed.secret === 'string' ? parsed.secret : '';
+        if (!token || !secret) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `source file missing token or secret: ${sourceFile}`,
+            });
+        }
+        try {
+            await store.set(profile, { token, secret });
+        }
+        catch (err) {
+            exitWithError({
+                code: 1,
+                kind: 'runtime',
+                message: `keychain write failed: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+        let cleanup = 'kept';
+        if (options.deleteFile) {
+            try {
+                cleanup = cleanupMigratedSourceFile(sourceFile, parsed);
+            }
+            catch (err) {
+                // Non-fatal: migration succeeded, we just couldn't clean up.
+                console.error(`warning: could not remove ${sourceFile}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+        if (isJsonMode()) {
+            printJson({
+                profile,
+                backend: store.name,
+                migrated: true,
+                sourceFile,
+                sourceDeleted: cleanup === 'deleted',
+                sourceScrubbed: cleanup === 'scrubbed',
+            });
+            return;
+        }
+        console.log(`Migrated profile "${profile}" to backend "${store.name}".`);
+        const cleanupNote = cleanup === 'deleted'
+            ? ' (deleted)'
+            : cleanup === 'scrubbed'
+                ? ' (credentials removed; metadata kept)'
+                : '';
+        console.log(`source: ${sourceFile}${cleanupNote}`);
+        if (!options.deleteFile) {
+            console.log('Source file kept — pass --delete-file on the next run to remove it.');
+        }
+    });
+}

package/dist/commands/batch.js

@@ -6,6 +6,7 @@ import { parseFilter, applyFilter, FilterSyntaxError } from '../utils/filter.js'
 import { isDryRun } from '../utils/flags.js';
 import { DryRunSignal } from '../api/client.js';
 import { getCachedTypeMap, getCachedDevice, loadStatusCache } from '../devices/cache.js';
+import { allowsDirectDestructiveExecution, destructiveExecutionHint } from '../lib/destructive-mode.js';
 const DEFAULT_CONCURRENCY = 5;
 const COMMAND_TYPES = ['command', 'customize'];
 /**
@@ -98,7 +99,7 @@ export function registerBatchCommand(devices) {
         .option('--stagger <ms>', 'Fixed delay between task starts in ms (default 0 = random 20-60ms jitter)', intArg('--stagger', { min: 0 }), '0')
         .option('--plan', '[DEPRECATED, use --emit-plan] With --dry-run: emit a plan JSON document instead of executing anything')
         .option('--emit-plan', 'With --dry-run: emit a plan JSON document instead of executing anything')
-        .option('--yes', 'Allow destructive commands (Smart Lock unlock, garage open, ...)')
+        .option('--yes', 'Allow destructive commands only from an explicit dev profile')
         .option('--type <commandType>', '"command" (default) or "customize" for user-defined IR buttons', enumArg('--type', COMMAND_TYPES), 'command')
         .option('--stdin', 'Read deviceIds from stdin, one per line (same as trailing "-")')
         .option('--idempotency-key-prefix <prefix>', 'Client-supplied prefix for idempotency keys (key per device: <prefix>-<deviceId>). process-local 60s window; cache is per Node process (MCP session, batch run, plan run). Independent CLI invocations do not share cache.', stringArg('--idempotency-key-prefix'))
@@ -134,7 +135,8 @@ Planning:
 
 Safety:
   Destructive commands (Smart Lock unlock, Garage Door Opener turnOn/turnOff,
-  Keypad createKey/deleteKey) are blocked by default. Pass --yes to override.
+  Keypad createKey/deleteKey) are blocked by default. Use the reviewed plan
+  flow instead of direct execution.
   --dry-run intercepts every POST and reports the intended calls without
   hitting the API.
 
@@ -142,7 +144,7 @@ Examples:
   $ switchbot devices batch turnOff --filter 'type~=Light,family=home'
   $ switchbot devices batch turnOn --ids ID1,ID2,ID3
   $ switchbot devices list --format=id --filter 'type=Bot' | switchbot devices batch toggle -
-  $ switchbot devices batch unlock --filter 'type=Smart Lock' --yes
+  $ switchbot devices batch unlock --filter 'type=Smart Lock' --dry-run --emit-plan
 `)
         .action(async (cmd, parameter, options, commandObj) => {
         // Trailing "-" sentinel selects stdin mode.
@@ -234,10 +236,24 @@ Examples:
                 code: 2,
                 kind: 'guard',
                 message: `Refusing to run destructive command "${cmd}" on ${blockedForDestructive.length} device(s) without --yes: ${deviceIds.join(', ')}`,
-                hint: 'Re-issue the call with --yes to proceed.',
+                hint: 'Re-issue the call with --yes only from an explicit dev profile, or use the reviewed plan flow.',
                 context: { command: cmd, deviceIds },
             });
         }
+        if (blockedForDestructive.length > 0 && options.yes && !allowsDirectDestructiveExecution()) {
+            exitWithError({
+                code: 2,
+                kind: 'guard',
+                message: `Direct destructive execution is disabled for batch command "${cmd}".`,
+                hint: destructiveExecutionHint(),
+                context: {
+                    command: cmd,
+                    blockedCount: blockedForDestructive.length,
+                    deviceIds: blockedForDestructive.map((item) => item.deviceId),
+                    requiredWorkflow: 'plan-approval',
+                },
+            });
+        }
         // parameter may be a JSON object string; mirror the single-command action.
         let parsedParam = parameter ?? 'default';
         if (parameter) {