@switchbot/openapi-cli 3.1.1 → 3.2.0

package/dist/commands/scenes.js

@@ -1,264 +0,0 @@
-import { printJson, isJsonMode, handleError, StructuredUsageError } from '../utils/output.js';
-import { resolveFormat, resolveFields, renderRows } from '../utils/format.js';
-import { fetchScenes, executeScene } from '../lib/scenes.js';
-import { isDryRun } from '../utils/flags.js';
-export function registerScenesCommand(program) {
-    const scenes = program
-        .command('scenes')
-        .description('Manage and execute SwitchBot scenes');
-    // switchbot scenes list
-    scenes
-        .command('list')
-        .description('List all manual scenes (scenes created in the SwitchBot app)')
-        .addHelpText('after', `
-Output columns: sceneId, sceneName
---fields accepts any subset of these names (exit 2 on unknown names).
-
-Examples:
-  $ switchbot scenes list
-  $ switchbot scenes list --format tsv --fields sceneId,sceneName
-  $ switchbot scenes list --format id
-  $ switchbot scenes list --json
-`)
-        .action(async () => {
-        try {
-            const scenes = await fetchScenes();
-            const fmt = resolveFormat();
-            if (fmt === 'json' && process.argv.includes('--json')) {
-                printJson(scenes);
-                return;
-            }
-            renderRows(['sceneId', 'sceneName'], scenes.map((s) => [s.sceneId, s.sceneName]), fmt, resolveFields(), { id: 'sceneId', name: 'sceneName' });
-            if (fmt === 'table' && scenes.length === 0) {
-                console.log('No scenes found');
-            }
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    // switchbot scenes execute <sceneId>
-    scenes
-        .command('execute')
-        .description('Execute a manual scene by its ID')
-        .argument('<sceneId>', 'Scene ID from "scenes list"')
-        .addHelpText('after', `
-Example:
-  $ switchbot scenes execute T12345678
-`)
-        .action(async (sceneId) => {
-        try {
-            const sceneList = await fetchScenes();
-            const found = sceneList.find((s) => s.sceneId === sceneId);
-            if (!found) {
-                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
-                    error: 'scene_not_found',
-                    sceneId,
-                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
-                });
-            }
-            if (isDryRun()) {
-                const wouldSend = { method: 'POST', url: `/v1.1/scenes/${sceneId}/execute`, sceneId, sceneName: found.sceneName };
-                if (isJsonMode()) {
-                    printJson({ dryRun: true, wouldSend });
-                }
-                else {
-                    console.log(`[dry-run] Would POST /v1.1/scenes/${sceneId}/execute (${found.sceneName})`);
-                }
-                return;
-            }
-            await executeScene(sceneId);
-            if (isJsonMode()) {
-                printJson({ ok: true, sceneId });
-            }
-            else {
-                console.log(`✓ Scene executed: ${sceneId}`);
-            }
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    // switchbot scenes describe <sceneId>
-    scenes
-        .command('describe')
-        .description('Show metadata for a scene by its ID (SwitchBot API v1.1 does not expose step detail)')
-        .argument('<sceneId>', 'Scene ID from "scenes list"')
-        .addHelpText('after', `
-Note: SwitchBot API v1.1 does not return scene step detail. Only the scene name is available.
-
-Example:
-  $ switchbot scenes describe T12345678
-`)
-        .action(async (sceneId) => {
-        try {
-            const sceneList = await fetchScenes();
-            const found = sceneList.find((s) => s.sceneId === sceneId);
-            if (!found) {
-                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
-                    error: 'scene_not_found',
-                    sceneId,
-                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
-                });
-            }
-            const result = {
-                sceneId: found.sceneId,
-                sceneName: found.sceneName,
-                stepCount: null,
-                note: 'SwitchBot API v1.1 does not expose scene steps — displayed name only',
-            };
-            if (isJsonMode()) {
-                printJson(result);
-            }
-            else {
-                console.log(`sceneId:   ${result.sceneId}`);
-                console.log(`sceneName: ${result.sceneName}`);
-                console.log(`stepCount: (not available)`);
-                console.log(`note:      ${result.note}`);
-            }
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    // switchbot scenes validate [sceneId...]
-    scenes
-        .command('validate')
-        .description('Verify that one or more scenes exist. If no IDs are given, validates all scenes are reachable.')
-        .argument('[sceneId...]', 'Scene IDs to validate (default: all scenes)')
-        .addHelpText('after', `
-Note: SwitchBot API v1.1 does not expose scene steps; validation only confirms
-the scene IDs exist in your account.
-
-Examples:
-  $ switchbot scenes validate
-  $ switchbot scenes validate T12345678 T87654321
-`)
-        .action(async (sceneIds) => {
-        try {
-            const sceneList = await fetchScenes();
-            const sceneMap = new Map(sceneList.map((s) => [s.sceneId, s.sceneName]));
-            const targets = sceneIds.length > 0 ? sceneIds : sceneList.map((s) => s.sceneId);
-            const results = targets.map((id) => ({
-                sceneId: id,
-                sceneName: sceneMap.get(id) ?? null,
-                valid: sceneMap.has(id),
-            }));
-            const allValid = results.every((r) => r.valid);
-            if (isJsonMode()) {
-                printJson({ ok: allValid, results });
-                if (!allValid)
-                    process.exit(1);
-                return;
-            }
-            for (const r of results) {
-                const icon = r.valid ? '✓' : '✗';
-                const label = r.valid ? r.sceneName : '(not found)';
-                console.log(`${icon} ${r.sceneId}  ${label}`);
-            }
-            if (!allValid)
-                process.exit(1);
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    // switchbot scenes simulate <sceneId>
-    scenes
-        .command('simulate')
-        .description('Show what `scenes execute` would do without actually executing the scene.')
-        .argument('<sceneId>', 'Scene ID from "scenes list"')
-        .addHelpText('after', `
-Note: SwitchBot API v1.1 does not expose scene step details. Simulation reports
-the scene name, confirms it exists, and shows the POST that would be issued.
-
-Example:
-  $ switchbot scenes simulate T12345678
-`)
-        .action(async (sceneId) => {
-        try {
-            const sceneList = await fetchScenes();
-            const found = sceneList.find((s) => s.sceneId === sceneId);
-            if (!found) {
-                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
-                    error: 'scene_not_found',
-                    sceneId,
-                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
-                });
-            }
-            const simulation = {
-                sceneId: found.sceneId,
-                sceneName: found.sceneName,
-                wouldSend: { method: 'POST', url: `/v1.1/scenes/${sceneId}/execute` },
-                note: 'SwitchBot API v1.1 does not expose individual scene steps.',
-            };
-            if (isJsonMode()) {
-                printJson({ simulated: true, ...simulation });
-                return;
-            }
-            console.log(`sceneId:   ${simulation.sceneId}`);
-            console.log(`sceneName: ${simulation.sceneName}`);
-            console.log(`wouldSend: ${simulation.wouldSend.method} ${simulation.wouldSend.url}`);
-            console.log(`note:      ${simulation.note}`);
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-    // switchbot scenes explain <sceneId>
-    scenes
-        .command('explain')
-        .description('Explain in plain language what a scene does and how to execute it safely.')
-        .argument('<sceneId>', 'Scene ID from "scenes list"')
-        .addHelpText('after', `
-Shows the scene name, action description, risk level, and the exact command to
-run. Unlike "simulate" (which shows raw HTTP detail), "explain" is aimed at a
-human or agent deciding whether to proceed.
-
-Note: SwitchBot API v1.1 does not expose scene step details; risk is reported
-as "low" because scenes only trigger pre-configured automations in the app.
-
-Example:
-  $ switchbot scenes explain T12345678
-`)
-        .action(async (sceneId) => {
-        try {
-            const sceneList = await fetchScenes();
-            const found = sceneList.find((s) => s.sceneId === sceneId);
-            if (!found) {
-                throw new StructuredUsageError(`scene not found: ${sceneId}`, {
-                    error: 'scene_not_found',
-                    sceneId,
-                    candidates: sceneList.map((s) => ({ sceneId: s.sceneId, sceneName: s.sceneName })),
-                });
-            }
-            const explanation = {
-                sceneId: found.sceneId,
-                sceneName: found.sceneName,
-                action: `Trigger scene (POST /v1.1/scenes/${found.sceneId}/execute)`,
-                riskLevel: 'low',
-                idempotent: null,
-                toExecute: `switchbot scenes execute ${found.sceneId}`,
-                dryRun: isDryRun(),
-                note: 'SwitchBot API v1.1 does not expose individual scene steps.',
-            };
-            if (isJsonMode()) {
-                printJson(explanation);
-                return;
-            }
-            console.log(`sceneId:    ${explanation.sceneId}`);
-            console.log(`sceneName:  ${explanation.sceneName}`);
-            console.log(`action:     ${explanation.action}`);
-            console.log(`riskLevel:  ${explanation.riskLevel}`);
-            console.log(`idempotent: unknown (scene steps not exposed by API)`);
-            console.log(`toExecute:  ${explanation.toExecute}`);
-            if (explanation.dryRun) {
-                console.log(`dryRun:     true  (pass --dry-run to execute would be a no-op)`);
-            }
-            console.log(`note:       ${explanation.note}`);
-        }
-        catch (error) {
-            handleError(error);
-        }
-    });
-}

package/dist/commands/schema.js

@@ -1,177 +0,0 @@
-import { enumArg, stringArg } from '../utils/arg-parsers.js';
-import { printJson } from '../utils/output.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 {
-        type: e.type,
-        description: e.description ?? '',
-        category: e.category,
-        aliases: e.aliases ?? [],
-        role: e.role ?? null,
-        readOnly: e.readOnly ?? false,
-        commands: e.commands.map((c) => toSchemaCommand(c, e)),
-        statusFields: e.statusFields ?? [],
-    };
-}
-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),
-        safetyTier: tier,
-        ...(reason ? { safetyReason: reason } : {}),
-        ...(c.exampleParams ? { exampleParams: c.exampleParams } : {}),
-    };
-}
-function toCompactEntry(e) {
-    return {
-        type: e.type,
-        category: e.category,
-        role: e.role ?? null,
-        readOnly: e.readOnly ?? false,
-        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 ?? [],
-    };
-}
-function projectFields(entry, fields) {
-    const out = {};
-    for (const f of fields) {
-        if (f in entry)
-            out[f] = entry[f];
-    }
-    return out;
-}
-export function registerSchemaCommand(program) {
-    const ROLES = ['lighting', 'security', 'sensor', 'climate', 'media', 'cleaning', 'curtain', 'fan', 'power', 'hub', 'other'];
-    const CATEGORIES = ['physical', 'ir'];
-    const schema = program
-        .command('schema')
-        .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)')
-        .option('--type <type>', 'Restrict to a single device type (e.g. "Strip Light")', stringArg('--type'))
-        .option('--types <csv>', 'Restrict to multiple device types (comma-separated)', stringArg('--types'))
-        .option('--role <role>', 'Restrict to a functional role: lighting, security, sensor, climate, media, cleaning, curtain, fan, power, hub, other', enumArg('--role', ROLES))
-        .option('--category <cat>', 'Restrict to "physical" or "ir"', enumArg('--category', CATEGORIES))
-        .option('--compact', 'Drop descriptions/aliases/example params — emit ~60% smaller payload. Useful for agent prompts.')
-        .option('--used', 'Restrict to device types present in the local devices cache (run "devices list" first)')
-        .option('--project <csv>', 'Project per-type fields (e.g. --project type,commands,statusFields)', stringArg('--project'))
-        .addHelpText('after', `
-Output is always JSON (this command ignores --format). The output is a
-catalog export — not a formal JSON Schema standard document — suitable for
-pre-baking LLM prompts or regenerating docs when the catalog changes.
-
-Size tips:
-  --compact --used          Smallest realistic payload for a given account
-                            (< 15 KB on most accounts).
-  --fields type,commands    Strip statusFields / role / etc. when only
-                            commands are needed.
-  --type + --compact        Inspect one type with minimum footprint.
-
-Common top-level fields:
-  schemaVersion             CLI schema version (stable for agent contracts)
-  data.version              Catalog schema version
-  data.types                Array of SchemaEntry (or CompactSchemaEntry with --compact)
-  data._fetchedAt           CLI-added; present on live-query responses ('devices status'),
-                            not on this offline export.
-
-Examples:
-  $ switchbot schema export > catalog.json
-  $ switchbot schema export --compact --used | wc -c   # small prompt-ready payload
-  $ switchbot schema export --type Bot | jq '.data.types[0].commands'
-  $ switchbot schema export --types "Bot,Curtain,Color Bulb"
-  $ switchbot schema export --role lighting | jq '[.data.types[].type]'
-  $ switchbot schema export --role security --category physical
-  $ switchbot schema export --project type,commands,statusFields
-`)
-        .action((options) => {
-        const catalog = getEffectiveCatalog();
-        let filtered = catalog;
-        if (options.type) {
-            const q = options.type.toLowerCase();
-            filtered = filtered.filter((e) => e.type.toLowerCase() === q ||
-                (e.aliases ?? []).some((a) => a.toLowerCase() === q));
-        }
-        if (options.types) {
-            const set = new Set(options.types.split(',').map((s) => s.trim().toLowerCase()).filter(Boolean));
-            filtered = filtered.filter((e) => set.has(e.type.toLowerCase()) ||
-                (e.aliases ?? []).some((a) => set.has(a.toLowerCase())));
-        }
-        if (options.role) {
-            const q = options.role.toLowerCase();
-            filtered = filtered.filter((e) => (e.role ?? 'other') === q);
-        }
-        if (options.category) {
-            const q = options.category.toLowerCase();
-            filtered = filtered.filter((e) => e.category === q);
-        }
-        if (options.used) {
-            const cache = loadCache();
-            if (cache) {
-                const usedTypes = new Set(Object.values(cache.devices).map((d) => d.type.toLowerCase()));
-                filtered = filtered.filter((e) => usedTypes.has(e.type.toLowerCase()) ||
-                    (e.aliases ?? []).some((a) => usedTypes.has(a.toLowerCase())));
-            }
-            else {
-                filtered = [];
-            }
-        }
-        const mapped = options.compact
-            ? filtered.map(toCompactEntry)
-            : filtered.map(toSchemaEntry);
-        const projected = options.project
-            ? mapped.map((e) => projectFields(e, options.project.split(',').map((s) => s.trim()).filter(Boolean)))
-            : mapped;
-        const payload = {
-            version: '1.0',
-            types: projected,
-        };
-        if (!options.compact) {
-            payload.generatedAt = new Date().toISOString();
-            payload.resources = RESOURCE_CATALOG;
-            payload.cliAddedFields = [
-                {
-                    field: '_fetchedAt',
-                    appliesTo: ['devices status', 'devices describe'],
-                    type: 'string (ISO-8601)',
-                    description: 'CLI-synthesized timestamp indicating when this status response was fetched or served from the cache. Not part of the upstream SwitchBot API.',
-                },
-                {
-                    field: 'replayed',
-                    appliesTo: ['devices command (with --idempotency-key)'],
-                    type: 'boolean',
-                    description: 'CLI-synthesized flag — true when the response was served from the idempotency cache instead of re-executing the command.',
-                },
-                {
-                    field: 'verification',
-                    appliesTo: ['devices command'],
-                    type: 'object',
-                    description: 'CLI-synthesized receipt-acknowledgment metadata. For IR devices, verifiable:false signals that no device-side confirmation is possible.',
-                },
-                {
-                    field: 'hints',
-                    appliesTo: ['agent-bootstrap'],
-                    type: 'string[]',
-                    description: 'CLI-synthesized advisory messages for the calling agent. Always emitted; empty array ([]) means no hints to report — never null and not a disabled-field signal.',
-                },
-            ];
-        }
-        printJson(payload);
-    });
-}

package/dist/commands/status-sync.js

@@ -1,131 +0,0 @@
-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);
-        }
-    });
-}