@switchbot/openapi-cli 2.6.4 → 3.0.0

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,21 @@ 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,
+        ...(reason ? { safetyReason: reason } : {}),
         ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
     };
 }
@@ -31,13 +35,16 @@ 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,
+            };
+        }),
         statusFields: e.statusFields ?? [],
     };
 }
@@ -54,7 +61,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 +144,7 @@ Examples:
         };
         if (!options.compact) {
             payload.generatedAt = new Date().toISOString();
+            payload.resources = RESOURCE_CATALOG;
             payload.cliAddedFields = [
                 {
                     field: '_fetchedAt',

package/dist/commands/status-sync.js

@@ -0,0 +1,131 @@
+import { stringArg } from '../utils/arg-parsers.js';
+import { handleError, isJsonMode, printJson } from '../utils/output.js';
+import { getStatusSyncStatus, runStatusSyncForeground, startStatusSync, stopStatusSync, } from '../status-sync/manager.js';
+function printHumanStatus(status) {
+    if (!status.running) {
+        console.log('status-sync is not running');
+        console.log(`state:  ${status.stateDir}`);
+        console.log(`stdout: ${status.stdoutLog}`);
+        console.log(`stderr: ${status.stderrLog}`);
+        return;
+    }
+    console.log(`status-sync is running (PID ${status.pid})`);
+    console.log(`started: ${status.startedAt}`);
+    console.log(`state:   ${status.stateDir}`);
+    console.log(`stdout:  ${status.stdoutLog}`);
+    console.log(`stderr:  ${status.stderrLog}`);
+}
+export function registerStatusSyncCommand(program) {
+    const statusSync = program
+        .command('status-sync')
+        .description('Manage a background MQTT -> OpenClaw status-sync bridge powered by events mqtt-tail');
+    statusSync
+        .command('run')
+        .description('Run the status-sync bridge in the foreground for a supervisor or terminal session')
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)', stringArg('--openclaw-url'))
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)', stringArg('--openclaw-token'))
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to (or env OPENCLAW_MODEL)', stringArg('--openclaw-model'))
+        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)', stringArg('--topic'))
+        .addHelpText('after', `
+Runs the same MQTT -> OpenClaw bridge logic as \'status-sync start\',
+but keeps the process attached to the current terminal. This is the best fit
+for agent supervisors, service managers, or container entrypoints that want
+foreground process semantics.
+
+Examples:
+  $ switchbot status-sync run --openclaw-model home-agent
+  $ OPENCLAW_TOKEN=abc OPENCLAW_MODEL=home-agent switchbot status-sync run
+`)
+        .action(async (options) => {
+        try {
+            const exitCode = await runStatusSyncForeground(options);
+            if (exitCode !== 0) {
+                process.exit(exitCode);
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    statusSync
+        .command('start')
+        .description('Start the background status-sync bridge')
+        .option('--openclaw-url <url>', 'OpenClaw gateway URL (default: http://localhost:18789)', stringArg('--openclaw-url'))
+        .option('--openclaw-token <token>', 'Bearer token for OpenClaw (or env OPENCLAW_TOKEN)', stringArg('--openclaw-token'))
+        .option('--openclaw-model <id>', 'OpenClaw agent model ID to route events to (or env OPENCLAW_MODEL)', stringArg('--openclaw-model'))
+        .option('--topic <pattern>', 'MQTT topic filter (default: SwitchBot shadow topic from credential)', stringArg('--topic'))
+        .option('--state-dir <path>', 'Override the status-sync state directory (or env SWITCHBOT_STATUS_SYNC_HOME)', stringArg('--state-dir'))
+        .option('--force', 'Stop any existing status-sync bridge before starting a new one')
+        .addHelpText('after', `
+Starts a detached child process that runs:
+  switchbot status-sync run ...
+
+State files:
+  state.json   process metadata (pid, startedAt, command)
+  stdout.log   redirected stdout from the child process
+  stderr.log   redirected stderr from the child process
+
+Examples:
+  $ switchbot status-sync start --openclaw-model home-agent
+  $ OPENCLAW_TOKEN=abc OPENCLAW_MODEL=home-agent switchbot status-sync start
+  $ switchbot status-sync start --state-dir ~/.switchbot/custom-status-sync --force
+`)
+        .action((options) => {
+        try {
+            const status = startStatusSync(options);
+            if (isJsonMode()) {
+                printJson(status);
+                return;
+            }
+            console.log(`Started status-sync (PID ${status.pid}).`);
+            console.log(`state:  ${status.stateDir}`);
+            console.log(`stdout: ${status.stdoutLog}`);
+            console.log(`stderr: ${status.stderrLog}`);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    statusSync
+        .command('stop')
+        .description('Stop the background status-sync bridge')
+        .option('--state-dir <path>', 'Override the status-sync state directory (or env SWITCHBOT_STATUS_SYNC_HOME)', stringArg('--state-dir'))
+        .action((options) => {
+        try {
+            const result = stopStatusSync(options);
+            if (isJsonMode()) {
+                printJson(result);
+                return;
+            }
+            if (result.stopped) {
+                console.log(`Stopped status-sync (PID ${result.pid}).`);
+            }
+            else if (result.stale) {
+                console.log(`Removed stale status-sync state for PID ${result.pid}.`);
+            }
+            else {
+                console.log('status-sync is not running');
+            }
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+    statusSync
+        .command('status')
+        .description('Inspect the current status-sync bridge state')
+        .option('--state-dir <path>', 'Override the status-sync state directory (or env SWITCHBOT_STATUS_SYNC_HOME)', stringArg('--state-dir'))
+        .action((options) => {
+        try {
+            const status = getStatusSyncStatus(options);
+            if (isJsonMode()) {
+                printJson(status);
+                return;
+            }
+            printHumanStatus(status);
+        }
+        catch (error) {
+            handleError(error);
+        }
+    });
+}

package/dist/commands/uninstall.js

@@ -0,0 +1,237 @@
+/**
+ * `switchbot uninstall` — reverse of `switchbot install`.
+ *
+ * Unlike install, uninstall is not rollback-safe (there's nothing to
+ * roll back to). It removes individual pieces independently and keeps
+ * going if any single removal fails — the user gets a report and can
+ * clean up leftovers manually. Every destructive step defaults to
+ * confirmation; `--yes` skips the prompt.
+ *
+ * What it removes, from least to most destructive:
+ *   1. skill symlink  (~/.claude/skills/switchbot)     — default: yes
+ *   2. credentials    (keychain entry for the profile) — default: yes  (requires --remove-creds OR --yes)
+ *   3. policy.yaml    (only on --remove-policy)         — default: no  (user edits may live here)
+ *
+ * The CLI itself is never uninstalled: install did not install it,
+ * and yanking your own binary mid-run is impolite. Users who want it
+ * gone run `npm rm -g @switchbot/openapi-cli`.
+ */
+import { InvalidArgumentError } from 'commander';
+import fs from 'node:fs';
+import readline from 'node:readline';
+import { resolvePolicyPath } from '../policy/load.js';
+import { skillLinkPathFor } from '../install/default-steps.js';
+import { selectCredentialStore } from '../credentials/keychain.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;
+}
+async function prompt(question, defaultYes) {
+    if (!process.stdin.isTTY)
+        return defaultYes;
+    const rl = readline.createInterface({ input: process.stdin, output: process.stderr });
+    return new Promise((resolve) => {
+        const suffix = defaultYes ? ' [Y/n] ' : ' [y/N] ';
+        rl.question(question + suffix, (ans) => {
+            rl.close();
+            const a = ans.trim().toLowerCase();
+            if (!a)
+                return resolve(defaultYes);
+            resolve(a === 'y' || a === 'yes');
+        });
+    });
+}
+export function registerUninstallCommand(program) {
+    program
+        .command('uninstall')
+        .description('Reverse of `switchbot install`: remove skill link, credentials, (optionally) policy')
+        .option('--agent <name>', `target agent: ${AGENT_VALUES.join(' | ')} (default: claude-code)`)
+        .option('--remove-creds', 'delete credentials from the OS keychain (default: prompt)')
+        .option('--remove-policy', 'also delete policy.yaml (default: keep — user edits may live there)')
+        .option('-y, --yes', 'assume yes to every confirmation prompt (non-interactive)')
+        .option('--purge', 'shorthand for --yes --remove-creds --remove-policy: remove everything without prompting')
+        .addHelpText('after', `
+The global --dry-run flag previews what would be removed.
+Global --json emits a structured removal report.
+
+What is never removed here:
+  - the CLI itself (use: npm rm -g @switchbot/openapi-cli)
+  - audit.log (it's your receipt; delete by hand if you want)
+
+Examples:
+  # Interactive: prompts before each destructive step
+  switchbot uninstall
+
+  # Non-interactive, remove everything including the policy
+  switchbot uninstall --yes --remove-policy
+
+  # One-shot: remove absolutely everything without prompting
+  switchbot uninstall --purge
+`)
+        .action(async (opts, command) => {
+        const agent = parseAgent(opts.agent);
+        const profile = getActiveProfile() ?? 'default';
+        const purge = Boolean(opts.purge);
+        const yes = Boolean(opts.yes) || purge;
+        const removePolicy = Boolean(opts.removePolicy) || purge;
+        const removeCreds = Boolean(opts.removeCreds) || yes;
+        const globalOpts = command.parent?.opts() ?? {};
+        const dryRun = Boolean(globalOpts.dryRun);
+        const policyPath = resolvePolicyPath();
+        const skillLink = skillLinkPathFor(agent);
+        const plan = [];
+        // --- Plan: skill symlink removal (default yes) ---
+        if (skillLink) {
+            plan.push({
+                action: 'remove-skill-link',
+                detail: skillLink,
+                run: async () => {
+                    if (!fs.existsSync(skillLink)) {
+                        return { action: 'remove-skill-link', status: 'absent', detail: skillLink };
+                    }
+                    const stat = fs.lstatSync(skillLink);
+                    if (!stat.isSymbolicLink()) {
+                        return {
+                            action: 'remove-skill-link',
+                            status: 'skipped',
+                            detail: `${skillLink} exists but is not a symlink — leaving it alone`,
+                        };
+                    }
+                    const ok = yes ? true : await prompt(`Remove skill link ${skillLink}?`, true);
+                    if (!ok)
+                        return { action: 'remove-skill-link', status: 'skipped', detail: skillLink };
+                    try {
+                        fs.unlinkSync(skillLink);
+                        return { action: 'remove-skill-link', status: 'removed', detail: skillLink };
+                    }
+                    catch (err) {
+                        return {
+                            action: 'remove-skill-link',
+                            status: 'failed',
+                            detail: skillLink,
+                            error: err instanceof Error ? err.message : String(err),
+                        };
+                    }
+                },
+            });
+        }
+        // --- Plan: credential removal (requires --remove-creds OR --yes) ---
+        plan.push({
+            action: 'remove-credentials',
+            detail: `profile=${profile}`,
+            run: async () => {
+                if (!removeCreds) {
+                    return {
+                        action: 'remove-credentials',
+                        status: 'skipped',
+                        detail: 'pass --remove-creds to delete keychain entry',
+                    };
+                }
+                const ok = yes ? true : await prompt(`Delete credentials for profile "${profile}" from the keychain?`, false);
+                if (!ok)
+                    return { action: 'remove-credentials', status: 'skipped', detail: `profile=${profile}` };
+                try {
+                    const store = await selectCredentialStore();
+                    await store.delete(profile);
+                    return {
+                        action: 'remove-credentials',
+                        status: 'removed',
+                        detail: `profile=${profile} (backend=${store.describe().tag})`,
+                    };
+                }
+                catch (err) {
+                    return {
+                        action: 'remove-credentials',
+                        status: 'failed',
+                        detail: `profile=${profile}`,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            },
+        });
+        // --- Plan: policy.yaml removal (opt-in) ---
+        plan.push({
+            action: 'remove-policy',
+            detail: policyPath,
+            run: async () => {
+                if (!removePolicy) {
+                    return {
+                        action: 'remove-policy',
+                        status: 'skipped',
+                        detail: 'pass --remove-policy to delete policy.yaml',
+                    };
+                }
+                if (!fs.existsSync(policyPath)) {
+                    return { action: 'remove-policy', status: 'absent', detail: policyPath };
+                }
+                const ok = yes ? true : await prompt(`Delete policy file ${policyPath}?`, false);
+                if (!ok)
+                    return { action: 'remove-policy', status: 'skipped', detail: policyPath };
+                try {
+                    fs.unlinkSync(policyPath);
+                    return { action: 'remove-policy', status: 'removed', detail: policyPath };
+                }
+                catch (err) {
+                    return {
+                        action: 'remove-policy',
+                        status: 'failed',
+                        detail: policyPath,
+                        error: err instanceof Error ? err.message : String(err),
+                    };
+                }
+            },
+        });
+        if (dryRun) {
+            if (isJsonMode()) {
+                printJson({
+                    dryRun: true,
+                    profile,
+                    agent,
+                    plan: plan.map(({ action, detail }) => ({ action, detail })),
+                });
+            }
+            else {
+                console.log(chalk.bold('switchbot uninstall — dry run'));
+                console.log(`  profile: ${profile}`);
+                console.log(`  agent:   ${agent}`);
+                console.log('');
+                console.log(chalk.bold('Would run:'));
+                for (const p of plan)
+                    console.log(`  • ${p.action}  — ${p.detail}`);
+                console.log('');
+                console.log(chalk.dim('No changes made. Re-run without --dry-run (add --yes to skip prompts).'));
+            }
+            return;
+        }
+        const outcomes = [];
+        for (const p of plan) {
+            outcomes.push(await p.run());
+        }
+        const anyFailed = outcomes.some((o) => o.status === 'failed');
+        if (isJsonMode()) {
+            printJson({ ok: !anyFailed, profile, agent, outcomes });
+        }
+        else {
+            console.log(chalk.bold('switchbot uninstall'));
+            for (const o of outcomes) {
+                const tag = o.status === 'removed' ? chalk.green('✓') :
+                    o.status === 'absent' ? chalk.dim('·') :
+                        o.status === 'skipped' ? chalk.yellow('↷') :
+                            chalk.red('✗');
+                console.log(`  ${tag} ${o.action} [${o.status}]  ${o.detail ?? ''}`);
+                if (o.error)
+                    console.log(`      ${chalk.red(o.error)}`);
+            }
+        }
+        if (anyFailed)
+            process.exit(3);
+    });
+}

package/dist/commands/watch.js

@@ -1,10 +1,11 @@
-import { printJson, isJsonMode, handleError, UsageError } from '../utils/output.js';
+import { printJson, isJsonMode, handleError, UsageError, emitStreamHeader } from '../utils/output.js';
 import { fetchDeviceStatus } from '../lib/devices.js';
 import { getCachedDevice } from '../devices/cache.js';
 import { parseDurationToMs, getFields } from '../utils/flags.js';
 import { intArg, durationArg, stringArg } from '../utils/arg-parsers.js';
 import { createClient } from '../api/client.js';
 import { resolveDeviceId } from '../utils/name-resolver.js';
+import { resolveFieldList, listAllCanonical } from '../schema/field-aliases.js';
 const DEFAULT_INTERVAL_MS = 30_000;
 const MIN_INTERVAL_MS = 1_000;
 function diff(prev, next, fields) {
@@ -101,7 +102,15 @@ Examples:
                 maxTicks = Math.floor(n);
             }
             const forMs = options.for ? parseDurationToMs(options.for) : null;
-            const fields = getFields() ?? null;
+            const rawFields = getFields() ?? null;
+            // Resolve aliases upfront against the static canonical registry.
+            // Validating here lets UsageError exit the command before any
+            // polling starts, and keeps mid-loop error handling free of
+            // "misuse" concerns. Unknown fields that are not registered as
+            // aliases but happen to match an API key pass through unchanged.
+            const fields = rawFields
+                ? resolveFieldList(rawFields, listAllCanonical())
+                : null;
             const ac = new AbortController();
             const onSig = () => ac.abort();
             process.on('SIGINT', onSig);
@@ -109,6 +118,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 so consumers can route by eventKind/cadence.
+            if (isJsonMode())
+                emitStreamHeader({ eventKind: 'tick', cadence: 'poll' });
             try {
                 const prev = new Map();
                 const client = createClient();

package/dist/config.js

@@ -4,6 +4,7 @@ import os from 'node:os';
 import { getConfigPath } from './utils/flags.js';
 import { getActiveProfile } from './lib/request-context.js';
 import { emitJsonError, isJsonMode } from './utils/output.js';
+import { getPrimedCredentials } from './credentials/prime.js';
 function sanitizeOptionalString(v) {
     if (typeof v !== 'string')
         return undefined;
@@ -46,6 +47,14 @@ export function loadConfig() {
     if (envToken && envSecret) {
         return { token: envToken, secret: envSecret };
     }
+    // After env, try the OS keychain (via the priming cache populated at
+    // command start). When --config is passed we skip the keychain so the
+    // override remains authoritative.
+    if (!getConfigPath()) {
+        const primed = getPrimedCredentials(getActiveProfile() ?? 'default');
+        if (primed)
+            return primed;
+    }
     const file = configFilePath();
     if (!fs.existsSync(file)) {
         const profile = getActiveProfile();
@@ -94,6 +103,11 @@ export function tryLoadConfig() {
     const envSecret = process.env.SWITCHBOT_SECRET;
     if (envToken && envSecret)
         return { token: envToken, secret: envSecret };
+    if (!getConfigPath()) {
+        const primed = getPrimedCredentials(getActiveProfile() ?? 'default');
+        if (primed)
+            return primed;
+    }
     const file = configFilePath();
     if (!fs.existsSync(file))
         return null;

package/dist/credentials/backends/file.js

@@ -0,0 +1,101 @@
+/**
+ * File-backed credential store.
+ *
+ * Reads/writes the same `~/.switchbot/config.json` shape the CLI has
+ * used since v1.0, so a fresh install on a machine without a keychain
+ * still works and legacy users can migrate in-place via
+ * `switchbot auth keychain migrate` without data loss.
+ *
+ * Profile layout (inherited from `src/config.ts`):
+ *   - default profile → `~/.switchbot/config.json`
+ *   - named profile   → `~/.switchbot/profiles/<name>.json`
+ *
+ * This backend only owns the `token` and `secret` fields — label /
+ * description / limits / defaults are preserved on write by merging
+ * with the existing JSON, keeping parity with `saveConfig()`.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { KeychainError, } from '../keychain.js';
+function profilePath(profile) {
+    if (profile === 'default') {
+        return path.join(os.homedir(), '.switchbot', 'config.json');
+    }
+    return path.join(os.homedir(), '.switchbot', 'profiles', `${profile}.json`);
+}
+function readJson(file) {
+    if (!fs.existsSync(file))
+        return null;
+    try {
+        const raw = fs.readFileSync(file, 'utf-8');
+        const parsed = JSON.parse(raw);
+        return parsed && typeof parsed === 'object' ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function createFileBackend() {
+    return {
+        name: 'file',
+        async get(profile) {
+            const file = profilePath(profile);
+            const data = readJson(file);
+            if (!data)
+                return null;
+            const token = typeof data.token === 'string' ? data.token : '';
+            const secret = typeof data.secret === 'string' ? data.secret : '';
+            if (!token || !secret)
+                return null;
+            return { token, secret };
+        },
+        async set(profile, creds) {
+            const file = profilePath(profile);
+            const dir = path.dirname(file);
+            try {
+                fs.mkdirSync(dir, { recursive: true });
+                const existing = readJson(file) ?? {};
+                const next = { ...existing, token: creds.token, secret: creds.secret };
+                fs.writeFileSync(file, JSON.stringify(next, null, 2), { mode: 0o600 });
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new KeychainError('file', 'set', msg);
+            }
+        },
+        async delete(profile) {
+            const file = profilePath(profile);
+            try {
+                if (!fs.existsSync(file))
+                    return;
+                const existing = readJson(file);
+                if (existing) {
+                    delete existing.token;
+                    delete existing.secret;
+                    if (Object.keys(existing).length === 0) {
+                        fs.unlinkSync(file);
+                    }
+                    else {
+                        fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
+                    }
+                }
+                else {
+                    fs.unlinkSync(file);
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                throw new KeychainError('file', 'delete', msg);
+            }
+        },
+        describe() {
+            return {
+                backend: 'File (~/.switchbot/)',
+                tag: 'file',
+                writable: true,
+                notes: 'Last-resort fallback; credentials stored in a 0600 JSON file.',
+            };
+        },
+    };
+}