@switchbot/openapi-cli 3.1.0 → 3.2.0

package/dist/devices/resources.js

@@ -1,270 +0,0 @@
-/**
- * Declarative metadata for non-device resources exposed by the SwitchBot API:
- * scenes, webhooks, and keypad credentials ("keys").
- *
- * Consumed by `capabilities --json` and `schema export` so AI agents can
- * discover these surfaces the same way they discover device commands.
- *
- * Scope:
- * - Descriptive metadata only (no runtime execution — CLI/MCP handlers stay
- *   source-of-truth for behavior).
- * - Webhook event list is derived from the device catalog and is advisory —
- *   not every SwitchBot device actually pushes every listed event; refer to
- *   the SwitchBot webhook docs for authoritative shapes.
- */
-const COMMON_WEBHOOK_FIELDS = [
-    { name: 'deviceType', type: 'string', description: 'SwitchBot device type string', example: 'WoMeter' },
-    { name: 'deviceMac', type: 'string', description: 'Bluetooth MAC address (uppercase, colon-separated)', example: 'AA:BB:CC:11:22:33' },
-    { name: 'timeOfSample', type: 'timestamp', description: 'Millisecond Unix timestamp when the sample was taken', example: 1700000000000 },
-];
-export const RESOURCE_CATALOG = {
-    scenes: {
-        description: 'Manual scenes (IFTTT-style rules) authored in the SwitchBot app. Execution is fire-and-forget from the cloud — side-effects happen on the user\'s devices.',
-        operations: [
-            {
-                verb: 'list',
-                method: 'GET',
-                endpoint: '/v1.1/scenes',
-                params: [],
-                safetyTier: 'read',
-            },
-            {
-                verb: 'execute',
-                method: 'POST',
-                endpoint: '/v1.1/scenes/{sceneId}/execute',
-                params: [{ name: 'sceneId', required: true, type: 'string' }],
-                safetyTier: 'mutation',
-            },
-            {
-                verb: 'describe',
-                method: 'GET',
-                endpoint: '/v1.1/scenes/{sceneId}',
-                params: [{ name: 'sceneId', required: true, type: 'string' }],
-                safetyTier: 'read',
-            },
-        ],
-    },
-    webhooks: {
-        endpoints: [
-            {
-                verb: 'setup',
-                method: 'POST',
-                path: '/v1.1/webhook/setupWebhook',
-                safetyTier: 'mutation',
-                requiredParams: ['url'],
-            },
-            {
-                verb: 'query',
-                method: 'POST',
-                path: '/v1.1/webhook/queryWebhook',
-                safetyTier: 'read',
-                requiredParams: ['action'],
-            },
-            {
-                verb: 'update',
-                method: 'POST',
-                path: '/v1.1/webhook/updateWebhook',
-                safetyTier: 'mutation',
-                requiredParams: ['url', 'enable'],
-            },
-            {
-                verb: 'delete',
-                method: 'POST',
-                path: '/v1.1/webhook/deleteWebhook',
-                safetyTier: 'destructive',
-                requiredParams: ['url'],
-            },
-        ],
-        events: [
-            {
-                eventType: 'WoMeter',
-                devicePattern: 'Meter / Meter Plus / Indoor-Outdoor Meter',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius', example: 22.5 },
-                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)', example: 45 },
-                    { name: 'battery', type: 'number', description: 'Battery remaining (%)', example: 88 },
-                ],
-            },
-            {
-                eventType: 'WoCO2Sensor',
-                devicePattern: 'CO2 Monitor',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'CO2', type: 'number', description: 'CO2 concentration in ppm', example: 520 },
-                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
-                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
-                ],
-            },
-            {
-                eventType: 'WoPresence',
-                devicePattern: 'Motion Sensor / Video Doorbell motion',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'detectionState', type: 'string', description: 'Detection result word', example: 'DETECTED' },
-                ],
-            },
-            {
-                eventType: 'WoContact',
-                devicePattern: 'Contact Sensor',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'openState', type: 'string', description: 'Door/window state', example: 'open' },
-                    { name: 'moveDetected', type: 'boolean', description: 'Motion detected during this sample' },
-                ],
-            },
-            {
-                eventType: 'WoLock',
-                devicePattern: 'Smart Lock / Smart Lock Lite / Smart Lock Pro',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'lockState', type: 'string', description: 'Lock state: locked, unlocked, jammed', example: 'locked' },
-                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
-                ],
-            },
-            {
-                eventType: 'WoPlug',
-                devicePattern: 'Plug Mini / Plug / Relay Switch',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'power', type: 'string', description: 'Power state (on/off)', example: 'on' },
-                    { name: 'voltage', type: 'number', description: 'Instantaneous voltage (V)' },
-                    { name: 'electricCurrent', type: 'number', description: 'Instantaneous current (A)' },
-                ],
-            },
-            {
-                eventType: 'WoBot',
-                devicePattern: 'Bot',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
-                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
-                ],
-            },
-            {
-                eventType: 'WoCurtain',
-                devicePattern: 'Curtain / Blind Tilt / Roller Shade',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'slidePosition', type: 'number', description: 'Current slide position (0–100)' },
-                    { name: 'calibrate', type: 'boolean', description: 'True if device is calibrated' },
-                ],
-            },
-            {
-                eventType: 'WoDoorbell',
-                devicePattern: 'Video Doorbell button press',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'buttonName', type: 'string', description: 'Identifier of the pressed button' },
-                    { name: 'pressedAt', type: 'timestamp', description: 'Press timestamp in milliseconds' },
-                ],
-            },
-            {
-                eventType: 'WoKeypad',
-                devicePattern: 'Keypad scan / createKey result / deleteKey result',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'eventType', type: 'string', description: 'Sub-event (createKey / deleteKey / invalidCode)' },
-                    { name: 'commandId', type: 'string', description: 'Correlation id returned by the original command' },
-                    { name: 'result', type: 'string', description: 'Outcome (success / failed / timeout)' },
-                ],
-            },
-            {
-                eventType: 'WoColorBulb',
-                devicePattern: 'Color Bulb',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
-                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
-                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
-                    { name: 'colorTemperature', type: 'number', description: 'Color temperature in Kelvin' },
-                ],
-            },
-            {
-                eventType: 'WoStrip',
-                devicePattern: 'Strip Light',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'power', type: 'string', description: 'Power state (on/off)' },
-                    { name: 'brightness', type: 'number', description: 'Brightness (0–100)' },
-                    { name: 'color', type: 'string', description: 'RGB triplet "r:g:b"' },
-                ],
-            },
-            {
-                eventType: 'WoSweeper',
-                devicePattern: 'Robot Vacuum',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'workingStatus', type: 'string', description: 'Cleaning state' },
-                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
-                    { name: 'taskType', type: 'string', description: 'Current task (standby / clean / charge)' },
-                ],
-            },
-            {
-                eventType: 'WoWaterLeakDetect',
-                devicePattern: 'Water Leak Detector',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'waterLeakDetect', type: 'number', description: 'Leak flag (0 = dry, 1 = leak detected)' },
-                    { name: 'battery', type: 'number', description: 'Battery remaining (%)' },
-                ],
-            },
-            {
-                eventType: 'WoHub',
-                devicePattern: 'Hub 2 / Hub 3 (ambient sensors)',
-                fields: [
-                    ...COMMON_WEBHOOK_FIELDS,
-                    { name: 'temperature', type: 'number', description: 'Ambient temperature in Celsius' },
-                    { name: 'humidity', type: 'number', description: 'Relative humidity (%)' },
-                    { name: 'lightLevel', type: 'number', description: 'Illuminance level' },
-                ],
-            },
-        ],
-        constraints: {
-            maxUrlLength: 2048,
-            maxWebhooksPerAccount: 1,
-        },
-    },
-    keys: [
-        {
-            keyType: 'permanent',
-            description: 'Passcode that never expires — valid until manually deleted.',
-            requiredParams: ['name', 'password'],
-            optionalParams: [],
-            supportedDevices: ['Keypad', 'Keypad Touch'],
-            safetyTier: 'destructive',
-        },
-        {
-            keyType: 'timeLimit',
-            description: 'Passcode valid only between startTime and endTime (Unix seconds).',
-            requiredParams: ['name', 'password', 'startTime', 'endTime'],
-            optionalParams: [],
-            supportedDevices: ['Keypad', 'Keypad Touch'],
-            safetyTier: 'destructive',
-        },
-        {
-            keyType: 'disposable',
-            description: 'Passcode that can be used once and then auto-expires.',
-            requiredParams: ['name', 'password'],
-            optionalParams: ['startTime', 'endTime'],
-            supportedDevices: ['Keypad', 'Keypad Touch'],
-            safetyTier: 'destructive',
-        },
-        {
-            keyType: 'urgent',
-            description: 'Emergency passcode (typically tied to panic / audit workflow).',
-            requiredParams: ['name', 'password'],
-            optionalParams: [],
-            supportedDevices: ['Keypad', 'Keypad Touch'],
-            safetyTier: 'destructive',
-        },
-    ],
-};
-/** Convenience: return the list of known webhook event types. */
-export function listWebhookEventTypes() {
-    return RESOURCE_CATALOG.webhooks.events.map((e) => e.eventType);
-}
-/** Convenience: return the list of supported keypad key types. */
-export function listKeyTypes() {
-    return RESOURCE_CATALOG.keys.map((k) => k.keyType);
-}

package/dist/install/default-steps.js

@@ -1,257 +0,0 @@
-/**
- * Default install steps used by `switchbot install` (Phase 3B in-repo).
- *
- * Each factory returns an `InstallStep<InstallContext>` whose `execute`
- * and `undo` both operate on the shared context. Steps are intentionally
- * small — each one either mutates one system (keychain / filesystem /
- * symlink) or captures input, never a mix. The orchestrator composes
- * them in `src/commands/install.ts`.
- *
- * The step runner (`src/install/steps.ts`) handles rollback on failure;
- * these factories just make sure every `execute` records what it needs
- * into the context so the matching `undo` can unwind it.
- */
-import fs from 'node:fs';
-import path from 'node:path';
-import os from 'node:os';
-import { spawnSync } from 'node:child_process';
-import { scaffoldPolicyFile, PolicyFileExistsError, } from '../commands/policy.js';
-import { promptTokenAndSecret, readCredentialsFile } from '../commands/config.js';
-import { selectCredentialStore } from '../credentials/keychain.js';
-// ---------------------------------------------------------------------------
-// Step 1: capture credentials (memory only — no side effects until step 2)
-// ---------------------------------------------------------------------------
-export function stepPromptCredentials() {
-    return {
-        name: 'prompt-credentials',
-        description: 'Collect SwitchBot token + secret (interactive unless --token-file)',
-        async execute(ctx) {
-            if (ctx.credentials)
-                return; // already provided via API consumer
-            if (ctx.tokenFile) {
-                const creds = readCredentialsFile(ctx.tokenFile);
-                ctx.credentials = creds;
-                return;
-            }
-            if (ctx.nonInteractive) {
-                throw new Error('no --token-file and stdin is not a TTY; pass --token-file <path> to install non-interactively');
-            }
-            ctx.credentials = await promptTokenAndSecret();
-        },
-        undo() {
-            // No disk state created; clearing memory is enough.
-            // The calling process will exit shortly after rollback, but null
-            // the field for defence-in-depth.
-            return;
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Step 2: write credentials to keychain (or file fallback)
-// ---------------------------------------------------------------------------
-export function stepWriteKeychain() {
-    return {
-        name: 'write-keychain',
-        description: 'Store credentials in the OS keychain (falls back to ~/.switchbot/config.json)',
-        async execute(ctx) {
-            if (!ctx.credentials) {
-                throw new Error('internal: credentials missing at write-keychain; prompt step must run first');
-            }
-            const store = await selectCredentialStore();
-            const previous = await store.get(ctx.profile);
-            ctx.previousCredentials = previous;
-            await store.set(ctx.profile, ctx.credentials);
-            ctx.credentialStore = store;
-            ctx.credentialsWereStored = true;
-        },
-        async undo(ctx) {
-            if (!ctx.credentialsWereStored || !ctx.credentialStore)
-                return;
-            try {
-                if (ctx.previousCredentials) {
-                    await ctx.credentialStore.set(ctx.profile, ctx.previousCredentials);
-                }
-                else {
-                    await ctx.credentialStore.delete(ctx.profile);
-                }
-            }
-            finally {
-                ctx.credentialsWereStored = false;
-                ctx.previousCredentials = undefined;
-            }
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Step 3: scaffold policy.yaml if missing (skip if present, don't clobber)
-// ---------------------------------------------------------------------------
-export function stepScaffoldPolicy() {
-    return {
-        name: 'scaffold-policy',
-        description: 'Create a starter policy.yaml (only if none exists)',
-        execute(ctx) {
-            try {
-                const result = scaffoldPolicyFile(ctx.policyPath, { skipExisting: true });
-                ctx.policyScaffoldResult = result;
-            }
-            catch (err) {
-                if (err instanceof PolicyFileExistsError) {
-                    // skipExisting is true → this branch is unreachable, but be
-                    // defensive against future changes.
-                    return;
-                }
-                throw err;
-            }
-        },
-        undo(ctx) {
-            const r = ctx.policyScaffoldResult;
-            if (!r || r.skipped)
-                return;
-            // Only remove the file if WE created it (skipped === false means
-            // we wrote fresh content to a path that did not exist before).
-            try {
-                fs.unlinkSync(r.policyPath);
-            }
-            catch {
-                // best-effort; do not fail rollback on cleanup
-            }
-        },
-    };
-}
-// ---------------------------------------------------------------------------
-// Step 4: install skill into the agent's skills directory
-// ---------------------------------------------------------------------------
-/**
- * Compute the on-disk location where an agent expects to find this skill.
- * Only `claude-code` has an automation path today; others are informational
- * (the installer will print a recipe instead of creating anything).
- */
-export function skillLinkPathFor(agent, home = os.homedir()) {
-    if (agent === 'claude-code') {
-        return path.join(home, '.claude', 'skills', 'switchbot');
-    }
-    return null;
-}
-export function stepSymlinkSkill(opts = {}) {
-    return {
-        name: 'symlink-skill',
-        description: 'Link the skill into ~/.claude/skills/switchbot (Claude Code)',
-        execute(ctx) {
-            if (ctx.agent === 'none')
-                return;
-            if (!ctx.skillPath) {
-                // Informational path: print the recipe, do not fail. Undo can
-                // safely no-op in this branch.
-                ctx.skillRecipePrinted = true;
-                return;
-            }
-            const target = path.resolve(ctx.skillPath);
-            if (!fs.existsSync(target)) {
-                throw new Error(`--skill-path does not exist: ${target}`);
-            }
-            const stat = fs.statSync(target);
-            if (!stat.isDirectory()) {
-                throw new Error(`--skill-path is not a directory: ${target}`);
-            }
-            const linkPath = skillLinkPathFor(ctx.agent);
-            if (!linkPath) {
-                // Non-automating agent: print a recipe instead of creating state.
-                ctx.skillRecipePrinted = true;
-                return;
-            }
-            // A2: require a SKILL.md only when we are about to create a link.
-            // Non-automating agents (cursor/copilot) print a recipe and return
-            // above, so they are never blocked by this check.
-            if (!opts.force && !fs.existsSync(path.join(target, 'SKILL.md'))) {
-                throw new Error(`${target} does not look like a skill (no SKILL.md at the root). ` +
-                    'Pass --force if you really mean to link this directory.');
-            }
-            if (fs.existsSync(linkPath)) {
-                const st = fs.lstatSync(linkPath);
-                if (st.isSymbolicLink()) {
-                    // A3: tolerate an existing link only when it points at the same
-                    // target; otherwise the user is likely trying to repoint and we
-                    // should not silently pretend success. --force replaces it.
-                    let existingTarget = null;
-                    try {
-                        existingTarget = path.resolve(path.dirname(linkPath), fs.readlinkSync(linkPath));
-                    }
-                    catch {
-                        existingTarget = null;
-                    }
-                    if (existingTarget === target) {
-                        ctx.skillLinkPath = linkPath;
-                        ctx.skillLinkCreated = false;
-                        return;
-                    }
-                    if (!opts.force) {
-                        throw new Error(`${linkPath} already links to ${existingTarget ?? '(unreadable)'}; ` +
-                            'pass --force to replace it, or run `switchbot uninstall` first.');
-                    }
-                    fs.unlinkSync(linkPath);
-                }
-                else {
-                    throw new Error(`${linkPath} exists and is not a symlink; refusing to clobber (move it aside and re-run)`);
-                }
-            }
-            fs.mkdirSync(path.dirname(linkPath), { recursive: true });
-            // Windows: regular symlinks require admin or Developer Mode. A
-            // directory junction works for any user and is transparent to
-            // most tools. Unix: plain symlink.
-            const linkType = process.platform === 'win32' ? 'junction' : 'dir';
-            fs.symlinkSync(target, linkPath, linkType);
-            ctx.skillLinkPath = linkPath;
-            ctx.skillLinkCreated = true;
-        },
-        undo(ctx) {
-            if (!ctx.skillLinkCreated || !ctx.skillLinkPath)
-                return;
-            try {
-                fs.unlinkSync(ctx.skillLinkPath);
-            }
-            catch {
-                // best-effort
-            }
-        },
-    };
-}
-function defaultDoctorSpawner(cliPath, profile) {
-    const args = profile === 'default' ? [cliPath, 'doctor', '--json'] : [cliPath, '--profile', profile, 'doctor', '--json'];
-    const r = spawnSync(process.execPath, args, { encoding: 'utf-8' });
-    return {
-        ok: r.status === 0,
-        exitCode: r.status,
-        stdout: r.stdout ?? '',
-        stderr: r.stderr ?? '',
-    };
-}
-export function stepDoctorVerify(opts = { cliPath: '' }) {
-    const spawner = opts.spawner ?? defaultDoctorSpawner;
-    const cliPath = opts.cliPath;
-    return {
-        name: 'doctor-verify',
-        description: 'Verify the install with switchbot doctor --json',
-        execute(ctx) {
-            if (!cliPath) {
-                // Fail closed: without a known CLI path we cannot spawn doctor.
-                // Mark not-ok but still succeed (no rollback).
-                ctx.doctorOk = false;
-                ctx.doctorReport = { skipped: true, reason: 'no cliPath provided' };
-                return;
-            }
-            const r = spawner(cliPath, ctx.profile);
-            ctx.doctorOk = r.ok;
-            try {
-                ctx.doctorReport = r.stdout ? JSON.parse(r.stdout) : { exitCode: r.exitCode, stderr: r.stderr };
-            }
-            catch {
-                ctx.doctorReport = { exitCode: r.exitCode, stdout: r.stdout, stderr: r.stderr };
-            }
-            // NOTE: never throw here. Doctor failure is reported; rollback is
-            // opt-in by the user via `switchbot uninstall`.
-        },
-        undo() {
-            return;
-        },
-    };
-}