@switchbot/openapi-cli 3.2.0 → 3.2.1

package/dist/lib/devices.js

@@ -0,0 +1,383 @@
+import { createClient } from '../api/client.js';
+import { idempotencyCache } from './idempotency.js';
+import { findCatalogEntry, suggestedActions, getEffectiveCatalog, deriveSafetyTier, getCommandSafetyReason, } from '../devices/catalog.js';
+import { getCachedDevice, updateCacheFromDeviceList, loadCache, isListCacheFresh, getCachedStatus, setCachedStatus, } from '../devices/cache.js';
+import { getCacheMode } from '../utils/flags.js';
+import { writeAudit } from '../utils/audit.js';
+import { isDryRun } from '../utils/flags.js';
+export class DeviceNotFoundError extends Error {
+    deviceId;
+    constructor(deviceId) {
+        super(`No device with id "${deviceId}" found on this account.`);
+        this.deviceId = deviceId;
+        this.name = 'DeviceNotFoundError';
+    }
+}
+export class CommandValidationError extends Error {
+    kind;
+    hint;
+    constructor(message, kind, hint) {
+        super(message);
+        this.kind = kind;
+        this.hint = hint;
+        this.name = 'CommandValidationError';
+    }
+}
+/** Fetch the full device + IR remote inventory and refresh the local cache. */
+export async function fetchDeviceList(client) {
+    // TTL-gated read: when the on-disk cache is younger than the configured
+    // list TTL, skip the API call and synthesize a DeviceListBody from the
+    // metadata cache.
+    const mode = getCacheMode();
+    if (mode.listTtlMs > 0 && isListCacheFresh(mode.listTtlMs)) {
+        const cached = loadCache();
+        if (cached) {
+            const deviceList = [];
+            const infraredRemoteList = [];
+            for (const [deviceId, entry] of Object.entries(cached.devices)) {
+                if (entry.category === 'physical') {
+                    deviceList.push({
+                        deviceId,
+                        deviceName: entry.name,
+                        deviceType: entry.type,
+                        enableCloudService: entry.enableCloudService ?? true,
+                        hubDeviceId: entry.hubDeviceId ?? '',
+                        roomID: entry.roomID,
+                        roomName: entry.roomName,
+                        familyName: entry.familyName,
+                        controlType: entry.controlType,
+                    });
+                }
+                else {
+                    infraredRemoteList.push({
+                        deviceId,
+                        deviceName: entry.name,
+                        remoteType: entry.type,
+                        hubDeviceId: entry.hubDeviceId ?? '',
+                        controlType: entry.controlType,
+                    });
+                }
+            }
+            return { deviceList, infraredRemoteList };
+        }
+    }
+    const c = client ?? createClient();
+    const res = await c.get('/v1.1/devices');
+    updateCacheFromDeviceList(res.data.body);
+    return res.data.body;
+}
+/** Fetch live status for a single physical device. IR remotes have no status channel. */
+export async function fetchDeviceStatus(deviceId, client) {
+    const mode = getCacheMode();
+    if (mode.statusTtlMs > 0) {
+        const cached = getCachedStatus(deviceId, mode.statusTtlMs);
+        if (cached)
+            return cached;
+    }
+    const c = client ?? createClient();
+    const res = await c.get(`/v1.1/devices/${deviceId}/status`);
+    if (mode.statusTtlMs > 0) {
+        setCachedStatus(deviceId, res.data.body, new Date(), mode.statusTtlMs);
+    }
+    return res.data.body;
+}
+/**
+ * Execute a command on a device. `parameter` is the fully-parsed value already
+ * (JSON-object when applicable), not a raw CLI string — callers should parse
+ * upstream if needed.
+ */
+export async function executeCommand(deviceId, cmd, parameter, commandType, client, options) {
+    const c = client ?? createClient();
+    const body = {
+        command: cmd,
+        parameter: parameter ?? 'default',
+        commandType,
+    };
+    const baseAudit = {
+        t: new Date().toISOString(),
+        kind: 'command',
+        deviceId,
+        command: cmd,
+        parameter,
+        commandType,
+        dryRun: isDryRun(),
+        ...(options?.planId ? { planId: options.planId } : {}),
+    };
+    // Wrap in idempotency cache if key is provided
+    const execute = async () => {
+        try {
+            const res = await c.post(`/v1.1/devices/${deviceId}/commands`, body);
+            writeAudit({ ...baseAudit, result: 'ok' });
+            return res.data.body;
+        }
+        catch (err) {
+            // Dry-run intercepts throw DryRunSignal — still log the intent.
+            if (err instanceof Error && err.name === 'DryRunSignal') {
+                writeAudit({ ...baseAudit, result: 'ok' });
+            }
+            else {
+                writeAudit({
+                    ...baseAudit,
+                    result: 'error',
+                    error: err instanceof Error ? err.message : String(err),
+                });
+            }
+            throw err;
+        }
+    };
+    const { result, replayed } = await idempotencyCache.run(options?.idempotencyKey, execute, { command: cmd, parameter });
+    if (!replayed)
+        return result;
+    // Cached hit — attach replayed marker without mutating the original.
+    if (result && typeof result === 'object') {
+        return { ...result, replayed: true };
+    }
+    return { value: result, replayed: true };
+}
+/**
+ * Validate a command against the locally-cached device → catalog mapping.
+ * Returns `{ ok: true }` when validation passes or is skipped (unknown device,
+ * custom IR button, etc.). On a case-only mismatch the canonical command name
+ * is returned via `normalized` along with a `caseNormalizedFrom` field so the
+ * caller can emit a warning and continue with the canonical name.
+ * Returns `{ ok: false, error }` only when the caller should refuse the call.
+ */
+export function validateCommand(deviceId, cmd, parameter, commandType) {
+    if (commandType === 'customize')
+        return { ok: true };
+    const cached = getCachedDevice(deviceId);
+    if (!cached)
+        return { ok: true };
+    const match = findCatalogEntry(cached.type);
+    if (!match || Array.isArray(match))
+        return { ok: true };
+    const builtinCommands = match.commands.filter((c) => c.commandType !== 'customize');
+    if (match.readOnly || builtinCommands.length === 0) {
+        return {
+            ok: false,
+            error: new CommandValidationError(`${cached.name} (${cached.type}) is a read-only sensor — it has no control commands.`, 'read-only-device', `Use 'switchbot devices status ${deviceId}' to read this device instead.`),
+        };
+    }
+    let spec = builtinCommands.find((c) => c.command === cmd);
+    let caseNormalizedFrom;
+    let normalizedCmd = cmd;
+    if (!spec) {
+        const unique = [...new Set(builtinCommands.map((c) => c.command))];
+        const caseMatch = unique.find((c) => c.toLowerCase() === cmd.toLowerCase());
+        if (caseMatch) {
+            // Case-only mismatch: normalize and continue.
+            caseNormalizedFrom = cmd;
+            normalizedCmd = caseMatch;
+            spec = builtinCommands.find((c) => c.command === caseMatch);
+        }
+        else {
+            const hint = `Supported commands: ${unique.join(', ')}`;
+            return {
+                ok: false,
+                error: new CommandValidationError(`"${cmd}" is not a supported command for ${cached.name} (${cached.type}).`, 'unknown-command', hint),
+            };
+        }
+    }
+    if (!spec)
+        return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
+    const noParamExpected = spec.parameter === '—';
+    const userProvidedParam = parameter !== undefined && parameter !== 'default';
+    if (noParamExpected && userProvidedParam) {
+        return {
+            ok: false,
+            error: new CommandValidationError(`"${normalizedCmd}" takes no parameter, but one was provided: "${parameter}".`, 'unexpected-parameter', `Try: switchbot devices command ${deviceId} ${normalizedCmd}`),
+        };
+    }
+    // Warn when a parameter is required but the user omitted it
+    const paramRequired = !noParamExpected && spec.parameter !== 'default';
+    if (paramRequired && !userProvidedParam) {
+        const example = spec.exampleParams?.[0];
+        return {
+            ok: false,
+            error: new CommandValidationError(`"${normalizedCmd}" requires a parameter (${spec.parameter}).`, 'missing-parameter', example
+                ? `Example: switchbot devices command <deviceId> ${normalizedCmd} "${example}"`
+                : `See: switchbot devices commands ${cached.type}`),
+        };
+    }
+    return { ok: true, normalized: normalizedCmd, caseNormalizedFrom };
+}
+/**
+ * Inspect catalog annotations to decide whether a command is destructive,
+ * i.e. has hard-to-reverse real-world effects and should require an explicit
+ * confirmation from an agent / operator before execution. Customize commands
+ * are considered non-destructive here — they're user-defined IR buttons
+ * whose behavior the catalog can't know about.
+ */
+export function isDestructiveCommand(deviceType, cmd, commandType) {
+    if (commandType === 'customize')
+        return false;
+    if (!deviceType)
+        return false;
+    const match = findCatalogEntry(deviceType);
+    if (!match || Array.isArray(match))
+        return false;
+    const spec = match.commands.find((c) => c.command === cmd);
+    if (!spec)
+        return false;
+    return deriveSafetyTier(spec, match) === 'destructive';
+}
+/** Return the safetyReason for a command, or null if not destructive / not found. */
+export function getDestructiveReason(deviceType, cmd, commandType) {
+    if (commandType === 'customize')
+        return null;
+    if (!deviceType)
+        return null;
+    const match = findCatalogEntry(deviceType);
+    if (!match || Array.isArray(match))
+        return null;
+    const spec = match.commands.find((c) => c.command === cmd);
+    return spec ? getCommandSafetyReason(spec) : null;
+}
+/**
+ * Describe a device by id: metadata + catalog entry (if known) +
+ * optional live status. Throws `DeviceNotFoundError` when the id is unknown.
+ */
+export async function describeDevice(deviceId, options = {}, client) {
+    const body = await fetchDeviceList(client);
+    const { deviceList, infraredRemoteList } = body;
+    const physical = deviceList.find((d) => d.deviceId === deviceId);
+    const ir = infraredRemoteList.find((d) => d.deviceId === deviceId);
+    if (!physical && !ir)
+        throw new DeviceNotFoundError(deviceId);
+    const typeName = physical ? (physical.deviceType ?? '') : ir.remoteType;
+    const match = typeName ? findCatalogEntry(typeName) : null;
+    const catalogEntry = !match || Array.isArray(match) ? null : match;
+    let liveStatus;
+    if (options.live && physical) {
+        try {
+            liveStatus = await fetchDeviceStatus(deviceId, client);
+        }
+        catch (err) {
+            liveStatus = { error: err instanceof Error ? err.message : String(err) };
+        }
+    }
+    const source = catalogEntry
+        ? liveStatus
+            ? 'catalog+live'
+            : 'catalog'
+        : liveStatus
+            ? 'live'
+            : 'none';
+    const capabilities = catalogEntry
+        ? {
+            role: catalogEntry.role ?? null,
+            readOnly: catalogEntry.readOnly ?? false,
+            commands: catalogEntry.commands.map((c) => {
+                const tier = deriveSafetyTier(c, catalogEntry);
+                const reason = getCommandSafetyReason(c);
+                return {
+                    ...c,
+                    safetyTier: tier,
+                    ...(reason ? { safetyReason: reason } : {}),
+                };
+            }),
+            statusFields: catalogEntry.statusFields ?? [],
+            ...(liveStatus !== undefined ? { liveStatus } : {}),
+        }
+        : liveStatus !== undefined
+            ? { liveStatus }
+            : null;
+    return {
+        device: (physical ?? ir),
+        isPhysical: Boolean(physical),
+        typeName,
+        controlType: physical?.controlType ?? ir?.controlType ?? null,
+        catalog: catalogEntry,
+        capabilities,
+        source,
+        suggestedActions: catalogEntry ? suggestedActions(catalogEntry) : [],
+        inheritedLocation: ir ? buildHubLocationMap(deviceList).get(ir.hubDeviceId) : undefined,
+    };
+}
+/** Build a map from hubDeviceId → room/family/roomID for IR-remote inheritance. */
+export function buildHubLocationMap(deviceList) {
+    const map = new Map();
+    for (const d of deviceList) {
+        if (!d.deviceId)
+            continue;
+        map.set(d.deviceId, {
+            family: d.familyName ?? undefined,
+            room: d.roomName ?? undefined,
+            roomID: d.roomID ?? undefined,
+        });
+    }
+    return map;
+}
+/**
+ * Search the local catalog by type name / alias. Returns up to `limit`
+ * entries whose type or alias contains the query (case-insensitive).
+ * Intended for MCP's `search_catalog` tool — not for dispatching commands.
+ */
+export function searchCatalog(query, limit = 20) {
+    const catalog = getEffectiveCatalog();
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return catalog.slice(0, limit);
+    const hits = [];
+    for (const entry of catalog) {
+        const haystack = [entry.type, ...(entry.aliases ?? [])].map((s) => s.toLowerCase());
+        if (haystack.some((h) => h.includes(q))) {
+            hits.push(entry);
+            if (hits.length >= limit)
+                break;
+        }
+    }
+    return hits;
+}
+/** Convert a DescribeResult to the shape validated by the MCP outputSchema. */
+export function toMcpDescribeShape(r) {
+    const d = r.device;
+    return {
+        device: {
+            deviceId: d.deviceId,
+            deviceName: d.deviceName,
+            ...(d.deviceType !== undefined ? { deviceType: d.deviceType } : {}),
+            ...('enableCloudService' in d ? { enableCloudService: d.enableCloudService } : {}),
+            ...(d.hubDeviceId !== undefined ? { hubDeviceId: d.hubDeviceId } : {}),
+            ...(d.roomID !== undefined ? { roomID: d.roomID } : {}),
+            ...(d.roomName !== undefined ? { roomName: d.roomName } : {}),
+            ...(d.familyName !== undefined ? { familyName: d.familyName } : {}),
+            ...(d.controlType !== undefined ? { controlType: d.controlType } : {}),
+            ...('remoteType' in d && d.remoteType !== undefined ? { remoteType: d.remoteType } : {}),
+        },
+        isPhysical: r.isPhysical,
+        typeName: r.typeName,
+        controlType: r.controlType,
+        source: r.source,
+        capabilities: r.capabilities,
+        suggestedActions: r.suggestedActions,
+        ...(r.inheritedLocation !== undefined
+            ? { inheritedLocation: { family: r.inheritedLocation.family, room: r.inheritedLocation.room } }
+            : {}),
+    };
+}
+/** Shapes the device list body for the MCP list_devices outputSchema. */
+export function toMcpDeviceListShape(d) {
+    return {
+        deviceId: d.deviceId,
+        deviceName: d.deviceName,
+        deviceType: d.deviceType,
+        enableCloudService: d.enableCloudService,
+        hubDeviceId: d.hubDeviceId,
+        roomID: d.roomID,
+        roomName: d.roomName,
+        familyName: d.familyName,
+        controlType: d.controlType,
+    };
+}
+/** Shapes an infrared remote for the MCP list_devices outputSchema. */
+export function toMcpIrDeviceShape(d) {
+    return {
+        deviceId: d.deviceId,
+        deviceName: d.deviceName,
+        remoteType: d.remoteType,
+        hubDeviceId: d.hubDeviceId,
+        controlType: d.controlType,
+    };
+}
+//# sourceMappingURL=devices.js.map

package/dist/lib/devices.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"devices.js","sourceRoot":"","sources":["../../src/lib/devices.ts"],"names":[],"mappings":"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"}

package/dist/lib/idempotency.d.ts

@@ -0,0 +1,46 @@
+/**
+ * In-memory LRU cache for idempotent request deduplication.
+ * Caches the outcome of a keyed operation for 60 seconds;
+ * duplicate keys within the window return the cached result (with a
+ * `replayed: true` marker). Duplicate keys within the window for a DIFFERENT
+ * (command, parameter) shape raise {@link IdempotencyConflictError}.
+ *
+ * Keys are stored in-memory as a SHA-256 fingerprint of the user-provided
+ * key — the original string never touches the Map keys, so a later heap dump
+ * or inadvertent log capture does not leak the raw token.
+ *
+ * Process-local only — not shared across replicas.
+ */
+export declare class IdempotencyConflictError extends Error {
+    readonly key: string;
+    readonly existingShape: string;
+    readonly newShape: string;
+    constructor(message: string, key: string, existingShape: string, newShape: string);
+}
+export declare class IdempotencyCache {
+    private cache;
+    private readonly ttlMs;
+    private readonly maxEntries;
+    constructor(ttlMs?: number, maxEntries?: number);
+    /**
+     * Execute fn if the key is not cached, or return the cached result if it is.
+     * On new execution, caches the result for ttlMs.
+     *
+     * When `shape` is provided, a cached hit is validated against the original
+     * (command, parameter) fingerprint; mismatched shape raises
+     * {@link IdempotencyConflictError}.
+     *
+     * Returns a tuple-esque object with `replayed: true` when the cached
+     * result is served. The `result` field is the original cached value.
+     */
+    run<T>(key: string | undefined, fn: () => Promise<T>, shape?: {
+        command: string;
+        parameter: unknown;
+    }): Promise<{
+        result: T;
+        replayed: boolean;
+    }>;
+    clear(): void;
+    size(): number;
+}
+export declare const idempotencyCache: IdempotencyCache;

package/dist/lib/idempotency.js

@@ -0,0 +1,107 @@
+/**
+ * In-memory LRU cache for idempotent request deduplication.
+ * Caches the outcome of a keyed operation for 60 seconds;
+ * duplicate keys within the window return the cached result (with a
+ * `replayed: true` marker). Duplicate keys within the window for a DIFFERENT
+ * (command, parameter) shape raise {@link IdempotencyConflictError}.
+ *
+ * Keys are stored in-memory as a SHA-256 fingerprint of the user-provided
+ * key — the original string never touches the Map keys, so a later heap dump
+ * or inadvertent log capture does not leak the raw token.
+ *
+ * Process-local only — not shared across replicas.
+ */
+import crypto from 'node:crypto';
+const DEFAULT_TTL_MS = 60000; // 60 seconds
+const DEFAULT_MAX_ENTRIES = 1024;
+export class IdempotencyConflictError extends Error {
+    key;
+    existingShape;
+    newShape;
+    constructor(message, key, existingShape, newShape) {
+        super(message);
+        this.key = key;
+        this.existingShape = existingShape;
+        this.newShape = newShape;
+        this.name = 'IdempotencyConflictError';
+    }
+}
+function hashKey(key) {
+    return crypto.createHash('sha256').update(key).digest('hex');
+}
+function shapeSignature(command, parameter) {
+    // Canonical-ish JSON — stable enough for object equality with no nested sort
+    // (callers can pass primitives or small objects).
+    let parm;
+    try {
+        parm = JSON.stringify(parameter ?? 'default');
+    }
+    catch {
+        parm = String(parameter);
+    }
+    return `${command}::${parm}`;
+}
+export class IdempotencyCache {
+    cache = new Map();
+    ttlMs;
+    maxEntries;
+    constructor(ttlMs, maxEntries) {
+        this.ttlMs = ttlMs ?? DEFAULT_TTL_MS;
+        this.maxEntries = maxEntries ?? DEFAULT_MAX_ENTRIES;
+    }
+    /**
+     * Execute fn if the key is not cached, or return the cached result if it is.
+     * On new execution, caches the result for ttlMs.
+     *
+     * When `shape` is provided, a cached hit is validated against the original
+     * (command, parameter) fingerprint; mismatched shape raises
+     * {@link IdempotencyConflictError}.
+     *
+     * Returns a tuple-esque object with `replayed: true` when the cached
+     * result is served. The `result` field is the original cached value.
+     */
+    async run(key, fn, shape) {
+        if (!key) {
+            const result = await fn();
+            return { result, replayed: false };
+        }
+        const hashed = hashKey(key);
+        const now = Date.now();
+        const cached = this.cache.get(hashed);
+        const currentShape = shape ? shapeSignature(shape.command, shape.parameter) : '*';
+        if (cached && cached.expiresAt > now) {
+            if (shape && cached.shape !== '*' && cached.shape !== currentShape) {
+                throw new IdempotencyConflictError(`idempotency_conflict: key was first used for ${cached.shape.replace('::', ' ')}; refusing new shape ${currentShape.replace('::', ' ')}`, '<redacted>', cached.shape, currentShape);
+            }
+            return { result: cached.result, replayed: true };
+        }
+        const result = await fn();
+        if (this.cache.size >= this.maxEntries) {
+            const toRemove = Math.ceil(this.maxEntries * 0.1);
+            let removed = 0;
+            for (const [k, v] of this.cache.entries()) {
+                if (removed >= toRemove)
+                    break;
+                if (v.expiresAt <= now) {
+                    this.cache.delete(k);
+                    removed++;
+                }
+            }
+            if (this.cache.size >= this.maxEntries) {
+                const firstKey = this.cache.keys().next().value;
+                if (firstKey)
+                    this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(hashed, { result, expiresAt: now + this.ttlMs, shape: currentShape });
+        return { result, replayed: false };
+    }
+    clear() {
+        this.cache.clear();
+    }
+    size() {
+        return this.cache.size;
+    }
+}
+export const idempotencyCache = new IdempotencyCache();
+//# sourceMappingURL=idempotency.js.map

package/dist/lib/idempotency.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"idempotency.js","sourceRoot":"","sources":["../../src/lib/idempotency.ts"],"names":[],"mappings":"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"}

package/dist/lib/plan-store.d.ts

@@ -0,0 +1,19 @@
+import type { Plan } from '../commands/plan.js';
+export declare const PLANS_DIR: string;
+export type PlanStatus = 'pending' | 'approved' | 'rejected' | 'executed' | 'failed';
+export interface PlanRecord {
+    planId: string;
+    createdAt: string;
+    status: PlanStatus;
+    approvedAt?: string;
+    executedAt?: string;
+    /** Set when status transitions to 'failed'. */
+    failedAt?: string;
+    /** Summary of why the plan failed (e.g. "1 error, 2 skipped"). */
+    failureReason?: string;
+    plan: Plan;
+}
+export declare function savePlanRecord(plan: Plan): PlanRecord;
+export declare function loadPlanRecord(planId: string): PlanRecord | null;
+export declare function updatePlanRecord(planId: string, updates: Partial<PlanRecord>): PlanRecord;
+export declare function listPlanRecords(): PlanRecord[];

package/dist/lib/plan-store.js

@@ -0,0 +1,69 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+export const PLANS_DIR = path.join(os.homedir(), '.switchbot', 'plans');
+function ensurePlansDir() {
+    fs.mkdirSync(PLANS_DIR, { recursive: true, mode: 0o700 });
+}
+function planPath(planId) {
+    return path.join(PLANS_DIR, `${planId}.json`);
+}
+const UUID_V4_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function assertValidPlanId(planId) {
+    if (!UUID_V4_RE.test(planId)) {
+        throw new Error(`invalid planId: ${planId}`);
+    }
+}
+export function savePlanRecord(plan) {
+    ensurePlansDir();
+    const record = {
+        planId: randomUUID(),
+        createdAt: new Date().toISOString(),
+        status: 'pending',
+        plan,
+    };
+    fs.writeFileSync(planPath(record.planId), JSON.stringify(record, null, 2), { mode: 0o600 });
+    return record;
+}
+export function loadPlanRecord(planId) {
+    assertValidPlanId(planId);
+    try {
+        const raw = fs.readFileSync(planPath(planId), 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export function updatePlanRecord(planId, updates) {
+    assertValidPlanId(planId);
+    const record = loadPlanRecord(planId);
+    if (!record)
+        throw new Error(`Plan ${planId} not found in ${PLANS_DIR}`);
+    const updated = { ...record, ...updates };
+    fs.writeFileSync(planPath(planId), JSON.stringify(updated, null, 2), { mode: 0o600 });
+    return updated;
+}
+export function listPlanRecords() {
+    try {
+        if (!fs.existsSync(PLANS_DIR))
+            return [];
+        return fs
+            .readdirSync(PLANS_DIR)
+            .filter((f) => f.endsWith('.json'))
+            .flatMap((f) => {
+            try {
+                return [JSON.parse(fs.readFileSync(path.join(PLANS_DIR, f), 'utf-8'))];
+            }
+            catch {
+                return [];
+            }
+        })
+            .sort((a, b) => a.createdAt.localeCompare(b.createdAt));
+    }
+    catch {
+        return [];
+    }
+}
+//# sourceMappingURL=plan-store.js.map

package/dist/lib/plan-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan-store.js","sourceRoot":"","sources":["../../src/lib/plan-store.ts"],"names":[],"mappings":"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"}