@switchbot/openapi-cli 2.7.2 → 3.1.0

package/dist/commands/capabilities.js

@@ -28,6 +28,16 @@ const AGENT_GUIDE = {
         action: 'Mutates device or cloud state but is reversible and routine (turnOn, setColor).',
         destructive: 'Hard to reverse / physical-world side effects (unlock, garage open, delete key). Requires explicit user confirmation.',
     },
+    riskLevels: {
+        low: 'Read-only or non-mutating. Safe to call autonomously.',
+        medium: 'Mutates state (action tier). Prefer `plan` workflow. Reversible.',
+        high: 'Destructive / hard-to-reverse. Must go through review-before-execute. Direct --yes execution is reserved for explicit dev profiles.',
+    },
+    recommendedModes: {
+        direct: 'May be called directly without a plan step.',
+        plan: 'Prefer batching in a plan for traceability and dry-run support.',
+        'review-before-execute': 'Must be reviewed/approved before execution. Use `plan save`, `plan review`, `plan approve`, then `plan execute`.',
+    },
     verifiability: {
         local: 'Result is fully verifiable from the CLI return value itself.',
         deviceConfirmed: 'Device returns an ack with an observable state field.',
@@ -35,55 +45,128 @@ const AGENT_GUIDE = {
         none: 'No feedback — e.g. IR transmission. Pair with an external sensor to confirm.',
     },
 };
+function deriveRiskMeta(meta) {
+    const riskLevel = meta.agentSafetyTier === 'destructive' ? 'high'
+        : meta.agentSafetyTier === 'action' ? 'medium' : 'low';
+    return {
+        riskLevel,
+        requiresConfirmation: meta.agentSafetyTier === 'destructive',
+        supportsDryRun: meta.mutating,
+        idempotencyHint: meta.idempotencySupported ? 'safe' : meta.mutating ? 'non-idempotent' : 'safe',
+        recommendedMode: meta.agentSafetyTier === 'destructive' ? 'review-before-execute'
+            : meta.agentSafetyTier === 'action' ? 'plan' : 'direct',
+    };
+}
+function meta(mutating, consumesQuota, idempotencySupported, agentSafetyTier, verifiability, typicalLatencyMs) {
+    return { mutating, consumesQuota, idempotencySupported, agentSafetyTier, verifiability, typicalLatencyMs };
+}
+const READ_LOCAL = meta(false, false, false, 'read', 'local', 20);
+const READ_REMOTE = meta(false, true, false, 'read', 'local', 500);
+const ACTION_LOCAL = meta(true, false, false, 'action', 'local', 20);
+const ACTION_REMOTE = meta(true, true, false, 'action', 'deviceDependent', 900);
+const ACTION_REMOTE_IDEMPOTENT = meta(true, true, true, 'action', 'deviceDependent', 900);
+const DESTRUCTIVE_LOCAL = meta(true, false, false, 'destructive', 'local', 20);
+const DESTRUCTIVE_REMOTE = meta(true, true, false, 'destructive', 'deviceDependent', 1200);
+const READ_NONE = meta(false, false, false, 'read', 'none', 50);
 const COMMAND_META = {
-    // devices: reads
-    'devices list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
-    'devices status': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'devices describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 600 },
-    'devices types': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'devices commands': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'devices watch': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    // devices meta (local metadata — no quota, no API call)
-    'devices meta set': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta get': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta list': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'devices meta clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    // devices: actions
-    'devices command': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 800 },
-    'devices batch': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1200 },
-    // scenes
-    'scenes list': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'scenes execute': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1500 },
-    'scenes describe': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    // webhook
-    'webhook setup': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 500 },
-    'webhook query': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'webhook delete': { mutating: true, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 500 },
-    // quota
-    'quota status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'quota show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'quota reset': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 10 },
-    // doctor / schema / capabilities / catalog / config / cache / events / history / plan
-    'doctor': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 900 },
-    'schema export': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'capabilities': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
-    'catalog': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 15 },
-    'config set-token': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'destructive', verifiability: 'local', typicalLatencyMs: 5 },
-    'config show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'config list-profiles': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'cache status': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'cache clear': { mutating: true, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'action', verifiability: 'local', typicalLatencyMs: 5 },
-    'events mqtt-tail': { mutating: false, consumesQuota: true, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 500 },
-    'history show': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'history replay': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 1000 },
-    'history range': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 50 },
-    'history stats': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 20 },
-    'history aggregate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 80 },
-    'plan run': { mutating: true, consumesQuota: true, idempotencySupported: true, agentSafetyTier: 'action', verifiability: 'deviceDependent', typicalLatencyMs: 2000 },
-    'plan validate': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'plan schema': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
-    'completion': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 5 },
-    'mcp serve': { mutating: false, consumesQuota: false, idempotencySupported: false, agentSafetyTier: 'read', verifiability: 'local', typicalLatencyMs: 10 },
+    'agent-bootstrap': READ_LOCAL,
+    'auth keychain describe': READ_LOCAL,
+    'auth keychain get': READ_LOCAL,
+    'auth keychain set': DESTRUCTIVE_LOCAL,
+    'auth keychain delete': DESTRUCTIVE_LOCAL,
+    'auth keychain migrate': DESTRUCTIVE_LOCAL,
+    'cache show': READ_LOCAL,
+    'cache clear': ACTION_LOCAL,
+    'capabilities': READ_LOCAL,
+    'catalog path': READ_LOCAL,
+    'catalog show': READ_LOCAL,
+    'catalog search': READ_LOCAL,
+    'catalog diff': READ_LOCAL,
+    'catalog refresh': ACTION_LOCAL,
+    'completion': READ_LOCAL,
+    'config set-token': DESTRUCTIVE_LOCAL,
+    'config show': READ_LOCAL,
+    'config list-profiles': READ_LOCAL,
+    'config agent-profile': ACTION_LOCAL,
+    'daemon start': ACTION_LOCAL,
+    'daemon stop': ACTION_LOCAL,
+    'daemon status': READ_LOCAL,
+    'daemon reload': ACTION_LOCAL,
+    'devices list': READ_REMOTE,
+    'devices status': READ_REMOTE,
+    'devices command': ACTION_REMOTE_IDEMPOTENT,
+    'devices types': READ_LOCAL,
+    'devices commands': READ_LOCAL,
+    'devices describe': READ_REMOTE,
+    'devices batch': ACTION_REMOTE_IDEMPOTENT,
+    'devices watch': READ_REMOTE,
+    'devices explain': READ_LOCAL,
+    'devices expand': READ_LOCAL,
+    'devices meta set': ACTION_LOCAL,
+    'devices meta get': READ_LOCAL,
+    'devices meta list': READ_LOCAL,
+    'devices meta clear': ACTION_LOCAL,
+    'doctor': READ_LOCAL,
+    'events tail': READ_NONE,
+    'events mqtt-tail': READ_REMOTE,
+    'health check': READ_LOCAL,
+    'health serve': READ_LOCAL,
+    'history show': READ_LOCAL,
+    'history replay': ACTION_REMOTE_IDEMPOTENT,
+    'history range': READ_LOCAL,
+    'history stats': READ_LOCAL,
+    'history verify': READ_LOCAL,
+    'history aggregate': READ_LOCAL,
+    'install': ACTION_LOCAL,
+    'mcp serve': READ_LOCAL,
+    'plan schema': READ_LOCAL,
+    'plan validate': READ_LOCAL,
+    'plan suggest': READ_LOCAL,
+    'plan run': ACTION_REMOTE_IDEMPOTENT,
+    'plan save': ACTION_LOCAL,
+    'plan list': READ_LOCAL,
+    'plan review': READ_LOCAL,
+    'plan approve': DESTRUCTIVE_LOCAL,
+    'plan execute': DESTRUCTIVE_REMOTE,
+    'policy validate': READ_LOCAL,
+    'policy new': ACTION_LOCAL,
+    'policy migrate': ACTION_LOCAL,
+    'policy diff': READ_LOCAL,
+    'policy add-rule': ACTION_LOCAL,
+    'policy backup': READ_LOCAL,
+    'policy restore': DESTRUCTIVE_LOCAL,
+    'quota status': READ_LOCAL,
+    'quota reset': ACTION_LOCAL,
+    'rules suggest': READ_LOCAL,
+    'rules lint': READ_LOCAL,
+    'rules list': READ_LOCAL,
+    'rules run': ACTION_REMOTE,
+    'rules reload': ACTION_LOCAL,
+    'rules tail': READ_LOCAL,
+    'rules replay': READ_LOCAL,
+    'rules webhook-rotate-token': DESTRUCTIVE_LOCAL,
+    'rules webhook-show-token': DESTRUCTIVE_LOCAL,
+    'rules conflicts': READ_LOCAL,
+    'rules doctor': READ_LOCAL,
+    'rules summary': READ_LOCAL,
+    'rules last-fired': READ_LOCAL,
+    'schema export': READ_LOCAL,
+    'scenes list': READ_REMOTE,
+    'scenes execute': ACTION_REMOTE,
+    'scenes describe': READ_REMOTE,
+    'scenes validate': READ_REMOTE,
+    'scenes simulate': READ_REMOTE,
+    'scenes explain': READ_REMOTE,
+    'status-sync run': ACTION_REMOTE,
+    'status-sync start': ACTION_LOCAL,
+    'status-sync stop': ACTION_LOCAL,
+    'status-sync status': READ_LOCAL,
+    'uninstall': ACTION_LOCAL,
+    'upgrade-check': READ_REMOTE,
+    'webhook setup': ACTION_REMOTE,
+    'webhook query': READ_REMOTE,
+    'webhook update': ACTION_REMOTE,
+    'webhook delete': DESTRUCTIVE_REMOTE,
 };
 function metaFor(command) {
     return COMMAND_META[command] ?? null;
@@ -110,27 +193,30 @@ const IDEMPOTENCY_CONTRACT = {
     scope: 'Process-local. Replay + conflict apply within a single long-lived process (MCP session, devices batch, plan run, history replay). Independent CLI invocations do NOT share cache — each fresh `node` process starts empty.',
     mcp: 'MCP send_command accepts the same idempotencyKey field with identical semantics.',
 };
+function enumerateLeafNames(program, prefix = '') {
+    const out = [];
+    for (const cmd of program.commands) {
+        const full = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
+        if (cmd.commands.length === 0)
+            out.push(full);
+        else
+            out.push(...enumerateLeafNames(cmd, full));
+    }
+    return out;
+}
+function validateCommandMetaCoverage(program) {
+    const leaves = enumerateLeafNames(program);
+    return leaves.filter((leaf) => !COMMAND_META[leaf]).sort().map((leaf) => `missing:${leaf}`);
+}
 function enumerateLeaves(program, prefix = '') {
     const out = [];
     for (const cmd of program.commands) {
         const full = prefix ? `${prefix} ${cmd.name()}` : cmd.name();
         if (cmd.commands.length === 0) {
             const meta = metaFor(full);
-            if (meta) {
-                out.push({ name: full, ...meta });
-            }
-            else {
-                // Unknown leaf → default to read-safe with a warning flag so agents notice.
-                out.push({
-                    name: full,
-                    mutating: false,
-                    consumesQuota: false,
-                    idempotencySupported: false,
-                    agentSafetyTier: 'read',
-                    verifiability: 'local',
-                    typicalLatencyMs: 50,
-                });
-            }
+            if (!meta)
+                throw new Error(`capabilities metadata missing for leaf command "${full}"`);
+            out.push({ name: full, ...meta, ...deriveRiskMeta(meta) });
         }
         else {
             out.push(...enumerateLeaves(cmd, full));
@@ -157,6 +243,10 @@ export function registerCapabilitiesCommand(program) {
         .option('--surface <s>', 'Restrict surfaces block to one of: cli, mcp, plan, mqtt, all (default: all)', enumArg('--surface', SURFACES))
         .option('--project <csv>', 'Project top-level fields (e.g. --project identity,commands,agentGuide)', stringArg('--project'))
         .action((opts) => {
+        const coverageIssues = validateCommandMetaCoverage(program);
+        if (coverageIssues.length > 0) {
+            throw new Error(`capabilities metadata coverage error: ${coverageIssues.join(', ')}`);
+        }
         const compact = Boolean(opts.minimal || opts.compact);
         const catalog = getEffectiveCatalog();
         const leaves = enumerateLeaves(program);
@@ -246,8 +336,8 @@ export function registerCapabilitiesCommand(program) {
             // Flat command → meta map keyed by full command path. Published in
             // addition to the tree (where every leaf `subcommands[*]` already
             // carries the same fields via spread) so agents can do O(1) lookup
-            // without walking the tree.
-            commandMeta: COMMAND_META,
+            // without walking the tree. Includes derived risk metadata fields.
+            commandMeta: Object.fromEntries(Object.entries(COMMAND_META).map(([k, v]) => [k, { ...v, ...deriveRiskMeta(v) }])),
             ...(globalFlags ? { globalFlags } : {}),
             catalog: {
                 typeCount: catalog.length,

package/dist/commands/config.js

@@ -1,4 +1,6 @@
 import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
 import readline from 'node:readline';
 import { execFileSync } from 'node:child_process';
 import { stringArg } from '../utils/arg-parsers.js';
@@ -89,6 +91,36 @@ async function promptSecret(question) {
         void mutableStdout;
     });
 }
+/**
+ * Interactive echo-off prompt for token + secret. Used by both
+ * `switchbot config set-token` and the install orchestrator. Throws if
+ * stdin is not a TTY.
+ */
+export async function promptTokenAndSecret() {
+    if (!process.stdin.isTTY) {
+        throw new Error('interactive prompt requires a TTY');
+    }
+    const token = (await promptSecret('Token: ')).trim();
+    const secret = (await promptSecret('Secret: ')).trim();
+    if (!token || !secret) {
+        throw new Error('token and secret are both required');
+    }
+    return { token, secret };
+}
+/**
+ * Read a two-line credential file (line 1 = token, line 2 = secret)
+ * and unlink it on success. The installer's `--token-file` escape
+ * hatch uses this; keeps credentials off the command line and shell
+ * history for CI-style installs.
+ */
+export function readCredentialsFile(filePath) {
+    const raw = fs.readFileSync(filePath, 'utf-8');
+    const lines = raw.split(/\r?\n/).filter((l) => l.length > 0);
+    if (lines.length < 2) {
+        throw new Error(`credential file ${filePath} must contain two lines: token, then secret`);
+    }
+    return { token: lines[0].trim(), secret: lines[1].trim() };
+}
 export function registerConfigCommand(program) {
     const config = program
         .command('config')
@@ -221,6 +253,24 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
         }
         else {
             console.log(chalk.green('✓ Credentials saved'));
+            // Keychain-first hint: proactively suggest storing in OS keychain when
+            // the user is on a supported platform and saved to file (default path).
+            try {
+                const { selectCredentialStore } = await import('../credentials/keychain.js');
+                const store = await selectCredentialStore();
+                if (store.describe().backend === 'file') {
+                    const platform = process.platform;
+                    if (platform === 'darwin' || platform === 'win32') {
+                        console.error(chalk.grey('Tip: Your OS supports a native keychain. Run `switchbot auth keychain store` to move credentials off the plain config file for better security.'));
+                    }
+                    else if (platform === 'linux') {
+                        console.error(chalk.grey('Tip: If you have GNOME Keyring (secret-tool) installed, run `switchbot auth keychain store` to store credentials more securely.'));
+                    }
+                }
+            }
+            catch {
+                // Keychain probe failed — silently skip the tip
+            }
         }
     });
     config
@@ -264,4 +314,63 @@ Files are written with mode 0600. Profiles live under ~/.switchbot/profiles/<nam
             console.log(bits.join(' '));
         }
     });
+    // switchbot config agent-profile [--write]
+    config
+        .command('agent-profile')
+        .description('Emit (or write) an agent-safe profile template with conservative rate limits and audit logging.')
+        .option('--write', 'Write the template to ~/.switchbot/profiles/agent.json (requires --profile agent config set-token to add credentials).')
+        .option('--force', 'Overwrite an existing agent.json when used with --write.')
+        .addHelpText('after', `
+Outputs a starter profile.json suitable for AI agent / MCP integration:
+  - dailyCap: 100 (conservative; prevents runaway automation)
+  - label: "agent"
+  - description: "AI agent profile — conservative limits + audit enabled"
+  - defaults: { auditLog: true }  (enables audit logging by default)
+
+After writing, add credentials:
+  $ switchbot --profile agent config set-token <token> <secret>
+
+Then use the profile:
+  $ switchbot --profile agent devices list
+`)
+        .action((opts) => {
+        const template = {
+            label: 'agent',
+            description: 'AI agent profile — conservative limits + audit enabled',
+            limits: {
+                dailyCap: 100,
+            },
+            defaults: {
+                auditLog: true,
+            },
+        };
+        if (opts.write) {
+            const dir = path.join(os.homedir(), '.switchbot', 'profiles');
+            const dest = path.join(dir, 'agent.json');
+            if (!opts.force && fs.existsSync(dest)) {
+                exitWithError({ code: 2, kind: 'usage', message: `Agent profile already exists: ${dest}. Use --force to overwrite.` });
+            }
+            if (!fs.existsSync(dir)) {
+                fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+            }
+            fs.writeFileSync(dest, JSON.stringify(template, null, 2), { mode: 0o600 });
+            if (isJsonMode()) {
+                printJson({ ok: true, path: dest, template });
+            }
+            else {
+                console.log(`Agent profile written: ${dest}`);
+                console.log(`Next: switchbot --profile agent config set-token <token> <secret>`);
+            }
+        }
+        else {
+            if (isJsonMode()) {
+                printJson(template);
+            }
+            else {
+                console.log(JSON.stringify(template, null, 2));
+                console.log('');
+                console.log('Write with: switchbot config agent-profile --write');
+            }
+        }
+    });
 }