@switchbot/openapi-cli 3.1.1 → 3.2.0

package/dist/utils/flags.js

@@ -1,186 +0,0 @@
-/**
- * Read global flags directly from process.argv (same pattern as isJsonMode).
- * Kept simple so subcommand actions don't need to thread program.opts() down.
- */
-function getFlagValue(...flagNames) {
-    for (const flag of flagNames) {
-        const idx = process.argv.indexOf(flag);
-        if (idx !== -1 && idx + 1 < process.argv.length) {
-            return process.argv[idx + 1];
-        }
-        // Also accept the `--flag=value` token form. Commander.js recognizes it at
-        // the option layer but global-flag scans like this one used to miss it,
-        // so `--format=json` silently fell back to the default (table).
-        const prefix = `${flag}=`;
-        const combined = process.argv.find((arg) => arg.startsWith(prefix));
-        if (combined !== undefined) {
-            return combined.slice(prefix.length);
-        }
-    }
-    return undefined;
-}
-export function isVerbose() {
-    return process.argv.includes('--verbose') || process.argv.includes('-v');
-}
-/**
- * Opt-in: disable header redaction in verbose traces. Adds a big warning on
- * stderr. Use only when actively debugging an auth issue — never in logs or
- * CI output.
- */
-export function isTraceUnsafe() {
-    return process.argv.includes('--trace-unsafe');
-}
-export function isDryRun() {
-    return process.argv.includes('--dry-run');
-}
-/** HTTP request timeout in milliseconds. Default 30s. Minimum 100ms (values below 100ms are ignored). */
-export function getTimeout() {
-    const v = getFlagValue('--timeout');
-    if (!v)
-        return 30_000;
-    const n = Number(v);
-    if (!Number.isFinite(n) || n <= 0)
-        return 30_000;
-    if (n < 100) {
-        process.stderr.write(`Warning: --timeout ${n}ms is too low to complete any request; using 100ms minimum.\n`);
-        return 100;
-    }
-    return n;
-}
-/** Override for the credentials file path. */
-export function getConfigPath() {
-    return getFlagValue('--config');
-}
-/** Named profile → ~/.switchbot/profiles/<name>.json. */
-export function getProfile() {
-    return getFlagValue('--profile');
-}
-/**
- * Audit log path. `--audit-log` enables JSONL append on every mutating command.
- * Use `--audit-log-path <path>` to specify a custom file; otherwise defaults to
- * ~/.switchbot/audit.log. Returns null when --audit-log is absent.
- */
-export function getAuditLog() {
-    if (!process.argv.includes('--audit-log'))
-        return null;
-    const customPath = getFlagValue('--audit-log-path');
-    if (customPath)
-        return customPath;
-    return `${process.env.HOME ?? process.env.USERPROFILE ?? '.'}/.switchbot/audit.log`;
-}
-/**
- * Max 429 retries before surfacing the error. Default 3. `--no-retry`
- * disables retries entirely; `--retry-on-429 <n>` overrides the count.
- */
-export function getRetryOn429() {
-    if (process.argv.includes('--no-retry'))
-        return 0;
-    const v = getFlagValue('--retry-on-429');
-    if (v === undefined)
-        return 3;
-    const n = Number(v);
-    if (!Number.isFinite(n) || n < 0)
-        return 3;
-    return Math.floor(n);
-}
-/** Backoff strategy for 429 retries. Default 'exponential'. */
-export function getBackoffStrategy() {
-    const v = getFlagValue('--backoff');
-    if (v === 'linear')
-        return 'linear';
-    return 'exponential';
-}
-/**
- * Max retries on 5xx / gateway-timeout responses for idempotent (GET) reads.
- * Default 2. `--no-retry` disables retries entirely. POSTs are not retried
- * automatically — use --idempotency-key and let the server dedupe.
- */
-export function getRetryOn5xx() {
-    if (process.argv.includes('--no-retry'))
-        return 0;
-    const v = getFlagValue('--retry-on-5xx');
-    if (v === undefined)
-        return 2;
-    const n = Number(v);
-    if (!Number.isFinite(n) || n < 0)
-        return 2;
-    return Math.floor(n);
-}
-/**
- * Whether local quota counting is disabled. Quota counting is best-effort
- * (see src/utils/quota.ts) — this lets scripts opt out entirely when even
- * best-effort file I/O is unwelcome.
- */
-export function isQuotaDisabled() {
-    return process.argv.includes('--no-quota');
-}
-const DEFAULT_LIST_TTL_MS = 60 * 60 * 1000;
-function parseDurationToMs(v) {
-    const m = /^(\d+)(ms|s|m|h|d|w)?$/.exec(v.trim().toLowerCase());
-    if (!m)
-        return null;
-    const n = Number(m[1]);
-    if (!Number.isFinite(n) || n < 0)
-        return null;
-    const unit = m[2] ?? 'ms';
-    switch (unit) {
-        case 'ms': return n;
-        case 's': return n * 1000;
-        case 'm': return n * 60 * 1000;
-        case 'h': return n * 60 * 60 * 1000;
-        case 'd': return n * 24 * 60 * 60 * 1000;
-        case 'w': return n * 7 * 24 * 60 * 60 * 1000;
-        default: return null;
-    }
-}
-export { parseDurationToMs };
-/** The --format flag value, or undefined when absent. */
-export function getFormat() {
-    return getFlagValue('--format');
-}
-/** Comma-separated --fields value, split into an array. */
-export function getFields() {
-    const v = getFlagValue('--fields');
-    if (!v)
-        return undefined;
-    return v.split(',').map((f) => f.trim()).filter(Boolean);
-}
-export function getTableStyle() {
-    const v = getFlagValue('--table-style');
-    if (v === 'unicode' || v === 'ascii' || v === 'simple' || v === 'markdown')
-        return v;
-    if (getFormat() === 'markdown')
-        return 'markdown';
-    // TTY → pretty unicode borders. Non-TTY (pipe/redirect) → ascii to avoid
-    // mojibake in consumer logs.
-    return process.stdout.isTTY ? 'unicode' : 'ascii';
-}
-export function getCacheMode() {
-    if (process.argv.includes('--no-cache')) {
-        return { listTtlMs: 0, statusTtlMs: 0 };
-    }
-    // Individual TTL overrides take precedence over the combined --cache flag.
-    const listFlag = getFlagValue('--cache-list');
-    const statusFlag = getFlagValue('--cache-status');
-    if (listFlag !== undefined || statusFlag !== undefined) {
-        const listTtlMs = listFlag !== undefined
-            ? (parseDurationToMs(listFlag) ?? DEFAULT_LIST_TTL_MS)
-            : DEFAULT_LIST_TTL_MS;
-        const statusTtlMs = statusFlag !== undefined
-            ? (parseDurationToMs(statusFlag) ?? 0)
-            : 0;
-        return { listTtlMs, statusTtlMs };
-    }
-    const v = getFlagValue('--cache');
-    if (!v || v === 'auto') {
-        return { listTtlMs: DEFAULT_LIST_TTL_MS, statusTtlMs: 0 };
-    }
-    if (v === 'off') {
-        return { listTtlMs: 0, statusTtlMs: 0 };
-    }
-    const ms = parseDurationToMs(v);
-    if (ms === null || ms === 0) {
-        return { listTtlMs: DEFAULT_LIST_TTL_MS, statusTtlMs: 0 };
-    }
-    return { listTtlMs: ms, statusTtlMs: ms };
-}

package/dist/utils/format.js

@@ -1,117 +0,0 @@
-import { printTable, printJson, isJsonMode, UsageError, emitJsonError } from './output.js';
-import { getFormat, getFields } from './flags.js';
-import { dump as yamlDump } from 'js-yaml';
-export function parseFormat(flag) {
-    if (!flag)
-        return 'table';
-    const lower = flag.toLowerCase();
-    switch (lower) {
-        case 'table': return 'table';
-        case 'json': return 'json';
-        case 'jsonl': return 'jsonl';
-        case 'tsv': return 'tsv';
-        case 'yaml': return 'yaml';
-        case 'id': return 'id';
-        case 'markdown': return 'markdown';
-        default: {
-            const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id, markdown.`;
-            if (isJsonMode()) {
-                emitJsonError({ code: 2, kind: 'usage', message: msg });
-            }
-            else {
-                console.error(msg);
-            }
-            process.exit(2);
-        }
-    }
-}
-export function resolveFormat() {
-    if (process.argv.includes('--json'))
-        return 'json';
-    return parseFormat(getFormat());
-}
-export function resolveFields() {
-    return getFields();
-}
-export function filterFields(headers, rows, fields, aliases) {
-    if (!fields || fields.length === 0)
-        return { headers, rows };
-    const resolved = aliases ? fields.map((f) => aliases[f] ?? f) : fields;
-    const unknown = fields.filter((_, i) => !headers.includes(resolved[i]));
-    if (unknown.length > 0) {
-        throw new UsageError(`Unknown field(s): ${unknown.map((f) => `"${f}"`).join(', ')}. ` +
-            `Allowed: ${headers.map((f) => `"${f}"`).join(', ')}.`);
-    }
-    const indices = resolved.map((f) => headers.indexOf(f));
-    return {
-        headers: indices.map((i) => headers[i]),
-        rows: rows.map((row) => indices.map((i) => row[i])),
-    };
-}
-function cellToString(cell) {
-    if (cell === null || cell === undefined)
-        return '';
-    if (typeof cell === 'boolean')
-        return cell ? 'true' : 'false';
-    if (typeof cell === 'object')
-        return JSON.stringify(cell);
-    return String(cell);
-}
-function rowToObject(headers, row) {
-    const obj = {};
-    for (let i = 0; i < headers.length; i++) {
-        obj[headers[i]] = row[i] ?? null;
-    }
-    return obj;
-}
-export function renderRows(headers, rows, format, fields, aliases) {
-    const filtered = filterFields(headers, rows, fields, aliases);
-    const h = filtered.headers;
-    const r = filtered.rows;
-    // Markdown format is rendered as table with markdown style forced regardless
-    // of the user's --table-style, so `--format markdown` is a self-contained
-    // contract (bug #8).
-    if (format === 'markdown') {
-        printTable(h, r, 'markdown');
-        return;
-    }
-    switch (format) {
-        case 'table':
-            printTable(h, r);
-            break;
-        case 'json':
-            printJson(r.map((row) => rowToObject(h, row)));
-            break;
-        case 'jsonl':
-            for (const row of r) {
-                console.log(JSON.stringify(rowToObject(h, row)));
-            }
-            break;
-        case 'tsv':
-            console.log(h.join('\t'));
-            for (const row of r) {
-                console.log(row.map(cellToString).join('\t'));
-            }
-            break;
-        case 'yaml':
-            for (const row of r) {
-                const obj = rowToObject(h, row);
-                console.log('---');
-                console.log(yamlDump(obj, { lineWidth: -1 }).trimEnd());
-            }
-            break;
-        case 'id': {
-            const idIdx = h.indexOf('deviceId') !== -1 ? h.indexOf('deviceId')
-                : h.indexOf('sceneId') !== -1 ? h.indexOf('sceneId')
-                    : -1;
-            if (idIdx === -1) {
-                throw new UsageError(`--format=id requires a "deviceId" or "sceneId" column. ` +
-                    `This command outputs: ${h.map((c) => `"${c}"`).join(', ')}.`);
-            }
-            for (const row of r) {
-                console.log(cellToString(row[idIdx]));
-            }
-            break;
-        }
-    }
-}

package/dist/utils/health.js

@@ -1,101 +0,0 @@
-/**
- * Health report utilities — collects process, quota, audit, and circuit
- * breaker state into a single snapshot suitable for /health-style checks
- * and Prometheus-compatible metrics export.
- *
- * No side effects: reading is safe to call from any context.
- */
-import fs from 'node:fs';
-import os from 'node:os';
-import path from 'node:path';
-import { todayUsage, DAILY_QUOTA } from './quota.js';
-import { readAudit } from './audit.js';
-import { apiCircuitBreaker } from '../api/client.js';
-const DEFAULT_AUDIT_PATH = path.join(os.homedir(), '.switchbot', 'audit.log');
-const AUDIT_ERROR_WINDOW_MS = 24 * 60 * 60 * 1000; // 24h
-export function getHealthReport(auditPath = DEFAULT_AUDIT_PATH) {
-    const now = new Date();
-    // Process info
-    const procHealth = {
-        pid: process.pid,
-        uptimeSeconds: Math.floor(process.uptime()),
-        platform: process.platform,
-        nodeVersion: process.version,
-        memoryMb: Math.round(process.memoryUsage().rss / 1024 / 1024),
-    };
-    // Quota
-    const { total: used } = todayUsage(now);
-    const pct = Math.round((used / DAILY_QUOTA) * 100);
-    const quotaHealth = {
-        used,
-        limit: DAILY_QUOTA,
-        percentUsed: pct,
-        remaining: Math.max(0, DAILY_QUOTA - used),
-        status: pct >= 90 ? 'critical' : pct >= 70 ? 'warn' : 'ok',
-    };
-    // Audit error rate (last 24h)
-    let auditHealth;
-    if (!fs.existsSync(auditPath)) {
-        auditHealth = { present: false, recentErrors: 0, recentTotal: 0, errorRatePercent: 0, status: 'ok' };
-    }
-    else {
-        const entries = readAudit(auditPath);
-        const windowStart = now.getTime() - AUDIT_ERROR_WINDOW_MS;
-        const recent = entries.filter((e) => new Date(e.t).getTime() >= windowStart);
-        const errors = recent.filter((e) => e.result === 'error').length;
-        const total = recent.length;
-        const errorRate = total > 0 ? Math.round((errors / total) * 100) : 0;
-        auditHealth = {
-            present: true,
-            recentErrors: errors,
-            recentTotal: total,
-            errorRatePercent: errorRate,
-            status: errorRate >= 30 ? 'warn' : 'ok',
-        };
-    }
-    // Circuit breaker
-    const cbStats = apiCircuitBreaker.getStats();
-    const circuitHealth = {
-        name: apiCircuitBreaker.name,
-        state: cbStats.state,
-        failures: cbStats.failures,
-        status: cbStats.state === 'open' ? 'open' : 'ok',
-    };
-    // Overall
-    const degraded = quotaHealth.status !== 'ok' ||
-        auditHealth.status !== 'ok' ||
-        circuitHealth.status !== 'ok';
-    const down = circuitHealth.status === 'open';
-    const overall = down ? 'down' : degraded ? 'degraded' : 'ok';
-    return {
-        generatedAt: now.toISOString(),
-        overall,
-        process: procHealth,
-        quota: quotaHealth,
-        audit: auditHealth,
-        circuit: circuitHealth,
-    };
-}
-/**
- * Render a minimal Prometheus-compatible text metrics export.
- * Only includes the most actionable gauges.
- */
-export function toPrometheusText(report) {
-    const lines = [];
-    const push = (name, value, help) => {
-        if (help)
-            lines.push(`# HELP ${name} ${help}`);
-        lines.push(`# TYPE ${name} gauge`);
-        lines.push(`${name} ${value}`);
-    };
-    push('switchbot_quota_used_total', report.quota.used, 'SwitchBot API requests used today');
-    push('switchbot_quota_remaining', report.quota.remaining, 'SwitchBot API quota remaining today');
-    push('switchbot_quota_percent_used', report.quota.percentUsed, 'SwitchBot API quota percent used today');
-    push('switchbot_audit_recent_errors', report.audit.recentErrors, 'Audit log errors in the last 24h');
-    push('switchbot_audit_error_rate_percent', report.audit.errorRatePercent, 'Audit error rate percent (last 24h)');
-    push('switchbot_circuit_open', report.circuit.state === 'open' ? 1 : 0, 'API circuit breaker open (1=open, 0=closed/half-open)');
-    push('switchbot_circuit_failures', report.circuit.failures, 'Consecutive API failures recorded by circuit breaker');
-    push('switchbot_process_uptime_seconds', report.process.uptimeSeconds, 'Process uptime in seconds');
-    push('switchbot_process_memory_mb', report.process.memoryMb, 'Process RSS memory usage in MB');
-    return lines.join('\n') + '\n';
-}

package/dist/utils/help-json.js

@@ -1,54 +0,0 @@
-import { IDENTITY } from '../commands/identity.js';
-export function commandToJson(cmd, opts = {}) {
-    const args = cmd.registeredArguments.map((a) => ({
-        name: a.name(),
-        required: a.required,
-        variadic: a.variadic,
-        description: a.description ?? '',
-    }));
-    const options = cmd.options
-        .filter((o) => o.long !== '--help' && o.long !== '--version')
-        .map((o) => {
-        const entry = { flags: o.flags, description: o.description ?? '' };
-        if (o.defaultValue !== undefined)
-            entry.defaultValue = o.defaultValue;
-        if (o.argChoices && o.argChoices.length > 0)
-            entry.choices = o.argChoices;
-        return entry;
-    });
-    const subcommands = cmd.commands
-        .filter((c) => !c.name().startsWith('_'))
-        .map((c) => ({ name: c.name(), description: c.description() }));
-    const out = {
-        name: cmd.name(),
-        description: cmd.description(),
-        arguments: args,
-        options,
-        subcommands,
-    };
-    if (opts.includeIdentity) {
-        out.product = IDENTITY.product;
-        out.domain = IDENTITY.domain;
-        out.vendor = IDENTITY.vendor;
-        out.apiVersion = IDENTITY.apiVersion;
-        out.apiDocs = IDENTITY.apiDocs;
-        out.productCategories = IDENTITY.productCategories;
-    }
-    return out;
-}
-/** Walk argv tokens (skipping flags) to find the deepest matching subcommand. */
-export function resolveTargetCommand(root, argv) {
-    let cmd = root;
-    for (const token of argv) {
-        if (token.startsWith('-'))
-            continue;
-        const sub = cmd.commands.find((c) => c.name() === token || c.aliases().includes(token));
-        if (sub) {
-            cmd = sub;
-        }
-        else {
-            break;
-        }
-    }
-    return cmd;
-}

package/dist/utils/name-resolver.js

@@ -1,137 +0,0 @@
-import { loadCache } from '../devices/cache.js';
-import { loadDeviceMeta } from '../devices/device-meta.js';
-import { levenshtein, normalizeDeviceName } from './string.js';
-import { UsageError, StructuredUsageError } from './output.js';
-export const ALL_STRATEGIES = [
-    'exact', 'prefix', 'substring', 'fuzzy', 'first', 'require-unique',
-];
-export function isValidStrategy(s) {
-    return ALL_STRATEGIES.includes(s);
-}
-function resolveDeviceByName(query, opts = {}) {
-    const strategy = opts.strategy ?? 'fuzzy';
-    const cache = loadCache();
-    if (!cache || Object.keys(cache.devices).length === 0) {
-        return { ok: false, ambiguous: false };
-    }
-    const meta = loadDeviceMeta();
-    const q = normalizeDeviceName(query);
-    const threshold = Math.min(3, Math.floor(q.length * 0.3));
-    const typeFilter = opts.type ? opts.type.toLowerCase() : null;
-    const roomFilter = opts.room ? opts.room.toLowerCase() : null;
-    const candidates = [];
-    for (const [deviceId, device] of Object.entries(cache.devices)) {
-        // narrow filters first
-        if (opts.category && device.category !== opts.category)
-            continue;
-        if (typeFilter && device.type.toLowerCase() !== typeFilter)
-            continue;
-        if (roomFilter) {
-            const rn = (device.roomName ?? '').toLowerCase();
-            if (rn !== roomFilter && !rn.includes(roomFilter))
-                continue;
-        }
-        const alias = meta.devices[deviceId]?.alias;
-        const rawName = normalizeDeviceName(device.name);
-        const normAlias = alias ? normalizeDeviceName(alias) : null;
-        // exact alias/name wins immediately for lenient strategies.
-        // Under require-unique we must NOT short-circuit: there may be other devices
-        // that also match (e.g. via substring), making the result ambiguous.  Collect
-        // the exact hit as a candidate and let the full ambiguity check decide below.
-        if ((normAlias && normAlias === q) || rawName === q) {
-            if (strategy !== 'require-unique') {
-                return { ok: true, deviceId };
-            }
-            // require-unique: treat exact match as a high-priority candidate (score 0)
-            candidates.push({ deviceId, name: device.name, score: 0 });
-            continue;
-        }
-        if (strategy === 'exact')
-            continue;
-        if (strategy === 'prefix') {
-            if ((normAlias && normAlias.startsWith(q)) || rawName.startsWith(q)) {
-                candidates.push({ deviceId, name: device.name, score: 1 });
-            }
-            continue;
-        }
-        // substring + fuzzy + require-unique + first all share substring match
-        if ((normAlias && normAlias.includes(q)) || rawName.includes(q)) {
-            candidates.push({ deviceId, name: device.name, score: 1 });
-            continue;
-        }
-        if (strategy === 'substring')
-            continue;
-        // fuzzy / require-unique / first → also levenshtein
-        if (strategy === 'fuzzy' || strategy === 'require-unique' || strategy === 'first') {
-            const distName = levenshtein(rawName, q);
-            const distAlias = normAlias ? levenshtein(normAlias, q) : Number.POSITIVE_INFINITY;
-            const dist = Math.min(distName, distAlias);
-            if (dist <= threshold) {
-                candidates.push({ deviceId, name: device.name, score: dist + 1 });
-            }
-        }
-    }
-    if (candidates.length === 0)
-        return { ok: false, ambiguous: false };
-    candidates.sort((a, b) => a.score - b.score);
-    if (strategy === 'first') {
-        return { ok: true, deviceId: candidates[0].deviceId };
-    }
-    if (strategy === 'require-unique') {
-        if (candidates.length === 1)
-            return { ok: true, deviceId: candidates[0].deviceId };
-        return { ok: false, ambiguous: true, candidates: candidates.slice(0, 4) };
-    }
-    // fuzzy / substring / prefix: collapse cluster of near-ties
-    const best = candidates[0].score;
-    const top = candidates.filter((c) => c.score <= best + 1);
-    if (top.length === 1)
-        return { ok: true, deviceId: top[0].deviceId };
-    return { ok: false, ambiguous: true, candidates: top.slice(0, 4) };
-}
-export function resolveDeviceId(deviceId, nameQuery, opts = {}) {
-    if (deviceId && nameQuery) {
-        throw new UsageError('Provide either a deviceId argument or --name, not both.');
-    }
-    if (deviceId)
-        return deviceId;
-    if (!nameQuery) {
-        throw new UsageError('A deviceId argument or --name flag is required.');
-    }
-    if (opts.strategy && !isValidStrategy(opts.strategy)) {
-        throw new UsageError(`--name-strategy must be one of: ${ALL_STRATEGIES.join(', ')} (got "${opts.strategy}")`);
-    }
-    const cache = loadCache();
-    if (!cache) {
-        throw new UsageError(`--name requires the device cache. Run 'switchbot devices list' first to populate it.`);
-    }
-    const result = resolveDeviceByName(nameQuery, opts);
-    if (result.ok)
-        return result.deviceId;
-    if (result.ambiguous) {
-        const candidates = result.candidates.map((c) => ({ deviceId: c.deviceId, name: c.name }));
-        const narrow = [];
-        if (!opts.type)
-            narrow.push('--type');
-        if (!opts.category)
-            narrow.push('--category');
-        if (!opts.room)
-            narrow.push('--room');
-        const strategyHint = opts.strategy === 'fuzzy'
-            ? `pass --name-strategy=first to pick the best match`
-            : `pass --name-strategy=fuzzy or --name-strategy=first to pick the best match`;
-        const hint = narrow.length > 0
-            ? `Narrow with ${narrow.join(' / ')}, refine the name, use the deviceId directly, or ${strategyHint}.`
-            : `Refine the name, use the deviceId directly, or ${strategyHint}.`;
-        throw new StructuredUsageError(`"${nameQuery}" is ambiguous — ${candidates.length} devices match.`, {
-            error: 'ambiguous_name_match',
-            query: nameQuery,
-            candidates,
-            hint,
-        });
-    }
-    const noMatchNarrow = opts.type || opts.category || opts.room
-        ? ' after applying --type/--category/--room filters'
-        : '';
-    throw new UsageError(`No device matches "${nameQuery}"${noMatchNarrow}. Run 'switchbot devices list' to see device names.`);
-}