@switchbot/openapi-cli 2.3.0 → 2.5.0

package/dist/mcp/device-history.js

@@ -2,31 +2,102 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 const MAX_HISTORY = 100;
+const JSONL_ROTATE_BYTES = 50 * 1024 * 1024; // 50 MB
+const JSONL_KEEP_ROTATIONS = 3; // .1 .2 .3
 function historyDir() {
     return path.join(os.homedir(), '.switchbot', 'device-history');
 }
 export class DeviceHistoryStore {
-    dir;
-    constructor() {
-        this.dir = historyDir();
+    // In-memory size counter so we don't stat() on every append.
+    jsonlSizes = new Map();
+    /** Reset the in-memory size counter. Tests use this between runs. */
+    resetSizes() {
+        this.jsonlSizes.clear();
+    }
+    get dir() {
+        return historyDir();
     }
     record(deviceId, topic, deviceType, payload, t) {
+        const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
         try {
             if (!fs.existsSync(this.dir))
                 fs.mkdirSync(this.dir, { recursive: true });
+            // 1. Ring-buffer JSON (back-compat with existing consumers).
             const file = path.join(this.dir, `${deviceId}.json`);
             const existing = fs.existsSync(file)
                 ? JSON.parse(fs.readFileSync(file, 'utf-8'))
                 : { latest: null, history: [] };
-            const entry = { t: t ?? new Date().toISOString(), topic, deviceType, payload };
             existing.latest = entry;
             existing.history = [entry, ...existing.history].slice(0, MAX_HISTORY);
             fs.writeFileSync(file, JSON.stringify(existing, null, 2), { mode: 0o600 });
+            // 2. Append-only JSONL for range queries.
+            this.writeJsonl(deviceId, entry);
         }
         catch {
             // best-effort — history loss is non-fatal
         }
     }
+    /** Append a mqtt control event (no deviceId) to the dedicated __control.jsonl file. */
+    recordControl(event) {
+        try {
+            if (!fs.existsSync(this.dir))
+                fs.mkdirSync(this.dir, { recursive: true });
+            this.writeJsonl('__control', event);
+        }
+        catch {
+            // best-effort — never block the event stream
+        }
+    }
+    writeJsonl(fileKey, record) {
+        try {
+            const jsonlPath = path.join(this.dir, `${fileKey}.jsonl`);
+            const line = JSON.stringify(record) + '\n';
+            const lineBytes = Buffer.byteLength(line, 'utf-8');
+            // Seed size counter from disk on first touch (avoids drift across restarts).
+            let size = this.jsonlSizes.get(fileKey);
+            if (size === undefined) {
+                try {
+                    size = fs.existsSync(jsonlPath) ? fs.statSync(jsonlPath).size : 0;
+                }
+                catch {
+                    size = 0;
+                }
+            }
+            if (size + lineBytes > JSONL_ROTATE_BYTES) {
+                this.rotateJsonl(fileKey);
+                size = 0;
+            }
+            fs.appendFileSync(jsonlPath, line, { mode: 0o600 });
+            this.jsonlSizes.set(fileKey, size + lineBytes);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    rotateJsonl(fileKey) {
+        const base = path.join(this.dir, `${fileKey}.jsonl`);
+        // .jsonl.3 is dropped; .2 → .3, .1 → .2, current → .1
+        try {
+            const oldest = `${base}.${JSONL_KEEP_ROTATIONS}`;
+            if (fs.existsSync(oldest))
+                fs.rmSync(oldest);
+        }
+        catch { /* swallow */ }
+        for (let i = JSONL_KEEP_ROTATIONS - 1; i >= 1; i--) {
+            const from = `${base}.${i}`;
+            const to = `${base}.${i + 1}`;
+            try {
+                if (fs.existsSync(from))
+                    fs.renameSync(from, to);
+            }
+            catch { /* swallow */ }
+        }
+        try {
+            if (fs.existsSync(base))
+                fs.renameSync(base, `${base}.1`);
+        }
+        catch { /* swallow */ }
+    }
     getLatest(deviceId) {
         try {
             const file = path.join(this.dir, `${deviceId}.json`);
@@ -54,13 +125,21 @@ export class DeviceHistoryStore {
         try {
             if (!fs.existsSync(this.dir))
                 return [];
-            return fs.readdirSync(this.dir)
-                .filter((f) => f.endsWith('.json'))
-                .map((f) => f.slice(0, -5));
+            const seen = new Set();
+            for (const f of fs.readdirSync(this.dir)) {
+                if (f.endsWith('.json'))
+                    seen.add(f.slice(0, -5));
+                else if (f.endsWith('.jsonl'))
+                    seen.add(f.slice(0, -6));
+            }
+            return Array.from(seen);
         }
         catch {
             return [];
         }
     }
+    getHistoryDir() {
+        return this.dir;
+    }
 }
 export const deviceHistoryStore = new DeviceHistoryStore();

package/dist/utils/audit.js

@@ -1,6 +1,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { getAuditLog } from './flags.js';
+/** Bump when breaking changes to the audit line shape land. */
+export const AUDIT_VERSION = 1;
 function resolveAuditPath() {
     const flag = getAuditLog();
     if (flag === null)
@@ -16,7 +18,8 @@ export function writeAudit(entry) {
         if (!fs.existsSync(dir)) {
             fs.mkdirSync(dir, { recursive: true });
         }
-        fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+        const stamped = { auditVersion: AUDIT_VERSION, ...entry };
+        fs.appendFileSync(file, JSON.stringify(stamped) + '\n');
     }
     catch {
         // Best-effort — never let audit failures break the actual command.
@@ -40,3 +43,65 @@ export function readAudit(file) {
     }
     return out;
 }
+export function verifyAudit(file) {
+    const report = {
+        file,
+        totalLines: 0,
+        parsedLines: 0,
+        skippedBlankLines: 0,
+        malformedLines: 0,
+        unversionedEntries: 0,
+        versionCounts: {},
+        problems: [],
+    };
+    if (!fs.existsSync(file)) {
+        report.fileMissing = true;
+        return report;
+    }
+    const raw = fs.readFileSync(file, 'utf-8');
+    const lines = raw.split(/\r?\n/);
+    let minT;
+    let maxT;
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        if (!trimmed) {
+            report.skippedBlankLines++;
+            continue;
+        }
+        report.totalLines++;
+        let entry = null;
+        try {
+            entry = JSON.parse(trimmed);
+        }
+        catch {
+            report.malformedLines++;
+            report.problems.push({
+                line: i + 1,
+                reason: 'JSON parse failed',
+                preview: trimmed.slice(0, 80),
+            });
+            continue;
+        }
+        report.parsedLines++;
+        const v = entry.auditVersion;
+        if (v === undefined) {
+            report.unversionedEntries++;
+            report.versionCounts['unversioned'] = (report.versionCounts['unversioned'] ?? 0) + 1;
+        }
+        else {
+            const key = String(v);
+            report.versionCounts[key] = (report.versionCounts[key] ?? 0) + 1;
+        }
+        if (entry.t) {
+            if (!minT || entry.t < minT)
+                minT = entry.t;
+            if (!maxT || entry.t > maxT)
+                maxT = entry.t;
+        }
+    }
+    if (minT)
+        report.earliest = minT;
+    if (maxT)
+        report.latest = maxT;
+    return report;
+}

package/dist/utils/flags.js

@@ -14,6 +14,14 @@ function getFlagValue(...flagNames) {
 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');
 }
@@ -111,6 +119,16 @@ export function getFields() {
         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 };

package/dist/utils/format.js

@@ -12,8 +12,9 @@ export function parseFormat(flag) {
         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.`;
+            const msg = `Unknown --format "${flag}". Expected: table, json, jsonl, tsv, yaml, id, markdown.`;
             if (isJsonMode()) {
                 console.error(JSON.stringify({ error: { code: 2, kind: 'usage', message: msg } }));
             }
@@ -67,6 +68,13 @@ 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);

package/dist/utils/name-resolver.js

@@ -2,7 +2,14 @@ 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';
-function resolveDeviceByName(query) {
+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 };
@@ -10,52 +17,79 @@ function resolveDeviceByName(query) {
     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)) {
-        // alias exact match (highest priority)
-        const alias = meta.devices[deviceId]?.alias;
-        if (alias && normalizeDeviceName(alias) === q) {
-            return { ok: true, deviceId };
+        // 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);
-        // exact match
-        if (rawName === q)
-            return { ok: true, deviceId };
-        // alias substring/fuzzy (only query ⊂ alias, not the reverse)
-        if (alias) {
-            const normAlias = normalizeDeviceName(alias);
-            if (normAlias.includes(q)) {
-                candidates.push({ deviceId, name: device.name, score: 1 });
-                continue;
+        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 };
             }
-            const dist = levenshtein(normAlias, q);
-            if (dist <= threshold) {
-                candidates.push({ deviceId, name: device.name, score: dist + 1 });
-                continue;
+            // 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;
         }
-        // name substring (only query ⊂ name, not the reverse — avoids long queries
-        // collapsing onto short device names)
-        if (rawName.includes(q)) {
+        // 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;
         }
-        // levenshtein
-        const dist = levenshtein(rawName, q);
-        if (dist <= threshold) {
-            candidates.push({ deviceId, name: device.name, score: dist + 1 });
+        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) {
+export function resolveDeviceId(deviceId, nameQuery, opts = {}) {
     if (deviceId && nameQuery) {
         throw new UsageError('Provide either a deviceId argument or --name, not both.');
     }
@@ -64,15 +98,37 @@ export function resolveDeviceId(deviceId, nameQuery) {
     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);
+    const result = resolveDeviceByName(nameQuery, opts);
     if (result.ok)
         return result.deviceId;
     if (result.ambiguous) {
-        throw new StructuredUsageError(`"${nameQuery}" is ambiguous — be more specific or use the deviceId directly.`, { candidates: result.candidates.map((c) => ({ deviceId: c.deviceId, name: c.name })) });
+        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 hint = narrow.length > 0
+            ? `Narrow with ${narrow.join(' / ')} or use the deviceId directly, or pass --name-strategy first to pick the best match.`
+            : `Use the deviceId directly, or pass --name-strategy first to pick the best match.`;
+        throw new StructuredUsageError(`"${nameQuery}" is ambiguous — ${candidates.length} devices match.`, {
+            error: 'ambiguous_name_match',
+            query: nameQuery,
+            candidates,
+            hint,
+        });
     }
-    throw new UsageError(`No device matches "${nameQuery}". Run 'switchbot devices list' to see device names.`);
+    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.`);
 }

package/dist/utils/output.js

@@ -1,7 +1,7 @@
 import Table from 'cli-table3';
 import chalk from 'chalk';
 import { ApiError, DryRunSignal } from '../api/client.js';
-import { getFormat } from './flags.js';
+import { getFormat, getTableStyle } from './flags.js';
 export const SCHEMA_VERSION = '1.1';
 export function isJsonMode() {
     return process.argv.includes('--json') || getFormat() === 'json';
@@ -9,33 +9,96 @@ export function isJsonMode() {
 export function printJson(data) {
     console.log(JSON.stringify({ schemaVersion: SCHEMA_VERSION, data }, null, 2));
 }
-export function printTable(headers, rows) {
-    const table = new Table({
-        head: headers.map((h) => chalk.cyan(h)),
-        style: { border: ['grey'] },
-    });
+function escapeMarkdownCell(s) {
+    // Pipes break markdown table layout; backslash-escape them. Collapse
+    // newlines into <br> so each row stays on one line.
+    return s.replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');
+}
+function formatCell(cell, style) {
+    if (cell === null || cell === undefined)
+        return style === 'markdown' ? '—' : chalk.grey('—');
+    if (typeof cell === 'boolean') {
+        if (style === 'markdown')
+            return cell ? 'Yes' : 'No';
+        return cell ? chalk.green('✓') : chalk.red('✗');
+    }
+    return String(cell);
+}
+function renderMarkdownTable(headers, rows) {
+    const head = `| ${headers.map(escapeMarkdownCell).join(' | ')} |`;
+    const sep = `| ${headers.map(() => '---').join(' | ')} |`;
+    const body = rows.map((r) => `| ${r
+        .map((c) => escapeMarkdownCell(formatCell(c, 'markdown')))
+        .join(' | ')} |`);
+    return [head, sep, ...body].join('\n');
+}
+function renderSimpleTable(headers, rows) {
+    const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => String(formatCell(r[i], 'simple')).length)));
+    const fmt = (cells) => cells.map((c, i) => c.padEnd(widths[i])).join('  ').trimEnd();
+    return [
+        fmt(headers),
+        ...rows.map((r) => fmt(r.map((c) => String(formatCell(c, 'simple'))))),
+    ].join('\n');
+}
+const ASCII_BORDER_CHARS = {
+    top: '-', 'top-mid': '+', 'top-left': '+', 'top-right': '+',
+    bottom: '-', 'bottom-mid': '+', 'bottom-left': '+', 'bottom-right': '+',
+    left: '|', 'left-mid': '+', mid: '-', 'mid-mid': '+',
+    right: '|', 'right-mid': '+', middle: '|',
+};
+export function printTable(headers, rows, styleOverride) {
+    const style = styleOverride ?? getTableStyle();
+    if (style === 'markdown') {
+        console.log(renderMarkdownTable(headers, rows));
+        return;
+    }
+    if (style === 'simple') {
+        console.log(renderSimpleTable(headers, rows));
+        return;
+    }
+    const tableOpts = {
+        head: headers.map((h) => (style === 'ascii' ? h : chalk.cyan(h))),
+        style: style === 'ascii' ? { border: [], head: [] } : { border: ['grey'] },
+    };
+    if (style === 'ascii') {
+        tableOpts.chars = ASCII_BORDER_CHARS;
+    }
+    const table = new Table(tableOpts);
     for (const row of rows) {
-        table.push(row.map((cell) => {
-            if (cell === null || cell === undefined)
-                return chalk.grey('—');
-            if (typeof cell === 'boolean')
-                return cell ? chalk.green('✓') : chalk.red('✗');
-            return String(cell);
-        }));
+        table.push(row.map((cell) => formatCell(cell, style)));
     }
     console.log(table.toString());
 }
 export function printKeyValue(data) {
-    const table = new Table({
-        style: { border: ['grey'] },
-    });
+    const style = getTableStyle();
+    if (style === 'markdown') {
+        const entries = Object.entries(data).filter(([, v]) => v !== null && v !== undefined);
+        const rows = entries.map(([k, v]) => [k, typeof v === 'object' ? JSON.stringify(v) : String(v)]);
+        console.log(renderMarkdownTable(['Key', 'Value'], rows));
+        return;
+    }
+    if (style === 'simple') {
+        for (const [key, value] of Object.entries(data)) {
+            if (value === null || value === undefined)
+                continue;
+            const displayValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+            console.log(`${key}  ${displayValue}`);
+        }
+        return;
+    }
+    const tableOpts = {
+        style: style === 'ascii' ? { border: [], head: [] } : { border: ['grey'] },
+    };
+    if (style === 'ascii') {
+        tableOpts.chars = ASCII_BORDER_CHARS;
+    }
+    const table = new Table(tableOpts);
     for (const [key, value] of Object.entries(data)) {
         if (value === null || value === undefined)
             continue;
-        const displayValue = typeof value === 'object'
-            ? JSON.stringify(value)
-            : String(value);
-        table.push({ [chalk.cyan(key)]: displayValue });
+        const displayValue = typeof value === 'object' ? JSON.stringify(value) : String(value);
+        const keyLabel = style === 'ascii' ? key : chalk.cyan(key);
+        table.push({ [keyLabel]: displayValue });
     }
     console.log(table.toString());
 }
@@ -82,6 +145,35 @@ export function buildErrorPayload(error) {
     if (error instanceof UsageError) {
         return { code: 2, kind: 'usage', message: error.message, errorClass: 'usage', transient: false };
     }
+    // Idempotency conflict → exit 2 with kind:guard so scripts can react.
+    if (error instanceof Error && error.name === 'IdempotencyConflictError') {
+        return {
+            code: 2,
+            kind: 'guard',
+            message: error.message,
+            errorClass: 'guard',
+            transient: false,
+            context: {
+                existingShape: error.existingShape,
+                newShape: error.newShape,
+            },
+        };
+    }
+    // Local daily-cap refusal → exit 2 (usage-style refusal before touching net).
+    if (error instanceof Error && error.name === 'DailyCapExceededError') {
+        return {
+            code: 2,
+            kind: 'guard',
+            message: error.message,
+            errorClass: 'guard',
+            transient: false,
+            context: {
+                cap: error.cap,
+                total: error.total,
+                profile: error.profile,
+            },
+        };
+    }
     const code = error instanceof ApiError ? error.code : 1;
     const kind = error instanceof ApiError ? 'api' : 'runtime';
     const message = error instanceof Error ? error.message : 'An unknown error occurred';
@@ -127,6 +219,10 @@ export function handleError(error) {
         console.error(payload.message);
         process.exit(2);
     }
+    if (payload.kind === 'guard') {
+        console.error(chalk.yellow(`Guard: ${payload.message}`));
+        process.exit(payload.code === 2 ? 2 : 1);
+    }
     if (error instanceof ApiError) {
         console.error(chalk.red(`Error (code ${error.code}): ${payload.message}`));
         if (payload.hint)

package/dist/utils/quota.js

@@ -211,3 +211,17 @@ export function todayUsage(now = new Date()) {
         endpoints: { ...bucket.endpoints },
     };
 }
+/**
+ * Check whether today's call count is at or over the given cap. Returns the
+ * current counter either way so callers can render a helpful refusal message.
+ * Undefined cap → returns { over: false } without loading anything.
+ */
+export function checkDailyCap(dailyCap, now = new Date()) {
+    const date = today(now);
+    if (!dailyCap || dailyCap <= 0) {
+        return { over: false, total: 0, date };
+    }
+    const data = loadQuota();
+    const total = data.days[date]?.total ?? 0;
+    return { over: total >= dailyCap, total, cap: dailyCap, date };
+}