@ciphore/radiocli 0.2.1 → 0.2.3

package/dist/storage/store.js

@@ -1,8 +1,10 @@
 import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { dirname, isAbsolute, join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
 import { defaultReceiverStyle, receiverStyleNames, themeNames } from '../types.js';
+import { canonicalizeAlarmTime, canonicalizeIsoWeekdays, canonicalizeTimeZone } from '../alarms/schedule.js';
 import { backupBadFile } from '../providers/cache.js';
 import { migrateReceiverStyle } from '../ui/visualizers/receiver-style-registry.js';
 const stationSchema = z
@@ -35,6 +37,7 @@ const defaultMediaKeys = {
     playPause: [],
     next: []
 };
+const MAX_ALARMS = 500;
 const settingsSchema = z.object({
     theme: z.enum(themeNames).default('green'),
     receiverStyle: z.preprocess(migrateReceiverStyle, z.enum(receiverStyleNames).default(defaultReceiverStyle)),
@@ -58,7 +61,102 @@ const settingsSchema = z.object({
     transparentBackground: z.boolean().default(false),
     asciiMode: z.boolean().default(false),
     reduceMotion: z.boolean().default(false),
-    mouseSupport: z.boolean().default(true)
+    mouseSupport: z.boolean().default(true),
+    automaticUpdateChecks: z.boolean().default(true),
+    agentControl: z.object({
+        enabled: z.boolean().default(false),
+        openUiOnPlay: z.boolean().default(true),
+        focusNowPlaying: z.boolean().default(true),
+        completionPreset: z.object({
+            action: z.enum(['play', 'pause', 'resume', 'stop']).default('play'),
+            source: z.enum(['recent', 'favorite', 'popular', 'country']).default('recent'),
+            countryCode: z.string().length(2).optional(),
+            ifPlaying: z.enum(['keep', 'replace']).default('keep'),
+            openUi: z.boolean().optional()
+        }).default({ action: 'play', source: 'recent', ifPlaying: 'keep' })
+    }).default({
+        enabled: false,
+        openUiOnPlay: true,
+        focusNowPlaying: true,
+        completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+    })
+});
+const absoluteInstantSchema = z.string().refine(value => /(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value)), { message: 'Expected an absolute ISO-8601 instant with a timezone offset.' });
+const alarmMinuteInstantSchema = absoluteInstantSchema.refine(value => new Date(value).getUTCSeconds() === 0 && new Date(value).getUTCMilliseconds() === 0, { message: 'Alarm occurrences use minute precision; seconds must be zero.' });
+const alarmScheduleSchema = z.discriminatedUnion('type', [
+    z.object({ type: z.literal('once'), at: alarmMinuteInstantSchema }),
+    z.object({
+        type: z.literal('recurring'),
+        time: z.string().refine(value => {
+            try {
+                canonicalizeAlarmTime(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, { message: 'Invalid alarm time; expected HH:mm.' }),
+        weekdays: z.array(z.number().int().min(1).max(7).transform(value => value)).min(1, 'Choose at least one ISO weekday.'),
+        timezone: z.string().refine(value => {
+            try {
+                canonicalizeTimeZone(value);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        }, { message: 'Invalid IANA timezone.' })
+    })
+]);
+const alarmPlaybackSchema = z.object({
+    volume: z.number().int().min(0).max(100),
+    fadeSeconds: z.number().int().min(0).max(3600),
+    stopAfterMinutes: z.number().int().min(1).max(7 * 24 * 60),
+    fallbackStation: stationSchema.optional()
+});
+const alarmReliabilitySchema = z.object({
+    missedRunGraceMinutes: z.number().int().min(0).max(7 * 24 * 60),
+    wakeIfSupported: z.boolean(),
+    keepAwakeUntilAlarm: z.boolean().default(false)
+});
+const alarmRunRecordSchema = z.object({
+    status: z.enum(['played', 'failed', 'missed', 'dismissed']),
+    scheduledAt: absoluteInstantSchema,
+    firedAt: absoluteInstantSchema.optional(),
+    finishedAt: absoluteInstantSchema.optional(),
+    message: z.string().max(1000).optional()
+});
+const alarmSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().trim().min(1).max(120),
+    enabled: z.boolean(),
+    station: stationSchema,
+    schedule: alarmScheduleSchema,
+    playback: alarmPlaybackSchema,
+    reliability: alarmReliabilitySchema,
+    createdAt: absoluteInstantSchema,
+    updatedAt: absoluteInstantSchema,
+    lastRun: alarmRunRecordSchema.optional(),
+    nextOverride: z.object({
+        at: alarmMinuteInstantSchema,
+        createdAt: absoluteInstantSchema,
+        reason: z.literal('snooze')
+    }).optional()
+});
+const alarmArraySchema = z.array(alarmSchema)
+    .max(MAX_ALARMS, `RadioCLI supports at most ${MAX_ALARMS} alarms.`)
+    .superRefine((alarms, context) => {
+    const seen = new Set();
+    for (const [index, alarm] of alarms.entries()) {
+        if (seen.has(alarm.id)) {
+            context.addIssue({
+                code: 'custom',
+                message: `Duplicate alarm ID: ${alarm.id}`,
+                path: [index, 'id']
+            });
+        }
+        seen.add(alarm.id);
+    }
 });
 const librarySchema = z.object({
     recent: z
@@ -78,6 +176,7 @@ const librarySchema = z.object({
     }))
         .default([]),
     searchHistory: z.array(z.string()).default([]),
+    alarms: alarmArraySchema.default([]),
     updateCheck: z
         .object({
         checkedAt: z.string(),
@@ -113,6 +212,13 @@ const librarySchema = z.object({
         tuneTimeoutSeconds: 12,
         skipBrokenStreams: true,
         mouseSupport: true,
+        automaticUpdateChecks: true,
+        agentControl: {
+            enabled: false,
+            openUiOnPlay: true,
+            focusNowPlaying: true,
+            completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+        },
         mediaKeys: defaultMediaKeys
     })
 });
@@ -126,8 +232,12 @@ const legacyLibraryBackupSchema = z.object({ settings: z.unknown() }).passthroug
 export class JsonLibraryStore {
     filePath;
     state;
-    constructor(filePath = defaultStorePath()) {
+    idGenerator;
+    now;
+    constructor(filePath = defaultStorePath(), options = {}) {
         this.filePath = filePath;
+        this.idGenerator = options.idGenerator ?? randomUUID;
+        this.now = options.now ?? (() => new Date());
         this.state = this.read();
     }
     snapshot() {
@@ -162,6 +272,8 @@ export class JsonLibraryStore {
         }
         const parsed = JSON.parse(readFileSync(sourcePath, 'utf8'));
         const backupResult = libraryBackupSchema.safeParse(parsed);
+        if (!backupResult.success && isRadioCliBackup(parsed))
+            throw backupResult.error;
         const importedState = migrateLibraryState(backupResult.success
             ? backupResult.data.library
             : librarySchema.parse(legacyLibraryBackupSchema.parse(parsed)));
@@ -194,6 +306,107 @@ export class JsonLibraryStore {
     updateCheckState(updateCheck) {
         return this.commit({ ...this.state, updateCheck });
     }
+    addAlarm(input) {
+        const release = acquireStoreLock(this.filePath);
+        try {
+            const latestState = this.read();
+            if (latestState.alarms.length >= MAX_ALARMS) {
+                throw new Error(`RadioCLI supports at most ${MAX_ALARMS} alarms.`);
+            }
+            const existingIds = new Set([...this.state.alarms, ...latestState.alarms].map(alarm => alarm.id));
+            let id;
+            for (let attempt = 0; attempt < 100; attempt += 1) {
+                const candidate = this.idGenerator();
+                if (candidate && !existingIds.has(candidate)) {
+                    id = candidate;
+                    break;
+                }
+            }
+            if (!id)
+                throw new Error('Unable to allocate a unique alarm ID after 100 attempts.');
+            const timestamp = this.now().toISOString();
+            const alarm = normalizeAlarm(alarmSchema.parse({
+                ...input,
+                id,
+                createdAt: timestamp,
+                updatedAt: timestamp
+            }));
+            const nextState = { ...this.state, alarms: [alarm, ...this.state.alarms] };
+            const mergedState = mergeLibraryChanges(this.state, latestState, nextState);
+            this.write(mergedState);
+            this.state = mergedState;
+            return structuredClone(alarm);
+        }
+        finally {
+            release();
+        }
+    }
+    updateAlarm(id, updates) {
+        return this.mutateAlarm(id, existing => normalizeAlarm(alarmSchema.parse({
+            ...existing,
+            ...updates,
+            updatedAt: this.now().toISOString()
+        })));
+    }
+    removeAlarm(id) {
+        const release = acquireStoreLock(this.filePath);
+        try {
+            const latestState = this.read();
+            if (!latestState.alarms.some(alarm => alarm.id === id)) {
+                this.state = latestState;
+                return false;
+            }
+            const nextState = { ...latestState, alarms: latestState.alarms.filter(alarm => alarm.id !== id) };
+            this.write(nextState);
+            this.state = nextState;
+            return true;
+        }
+        finally {
+            release();
+        }
+    }
+    toggleAlarm(id, enabled) {
+        return this.mutateAlarm(id, existing => alarmSchema.parse({
+            ...existing,
+            enabled: enabled ?? !existing.enabled,
+            updatedAt: this.now().toISOString()
+        }));
+    }
+    getAlarm(id) {
+        const alarm = this.state.alarms.find(item => item.id === id);
+        return alarm ? structuredClone(alarm) : undefined;
+    }
+    listAlarms() {
+        return structuredClone(this.state.alarms);
+    }
+    recordAlarmOutcome(id, outcome, options = {}) {
+        return this.mutateAlarm(id, existing => alarmSchema.parse({
+            ...existing,
+            lastRun: outcome,
+            nextOverride: options.clearNextOverride === false ? existing.nextOverride : undefined,
+            updatedAt: this.now().toISOString()
+        }));
+    }
+    snoozeAlarm(id, until) {
+        if (!Number.isFinite(until.getTime()))
+            throw new Error('Invalid alarm snooze instant.');
+        const now = this.now();
+        const canonicalUntil = new Date(Math.ceil(until.getTime() / 60_000) * 60_000);
+        if (canonicalUntil.getTime() <= now.getTime())
+            throw new Error('Alarm snooze must be set to a future time.');
+        return this.mutateAlarm(id, existing => alarmSchema.parse({
+            ...existing,
+            nextOverride: { at: canonicalUntil.toISOString(), createdAt: now.toISOString(), reason: 'snooze' },
+            updatedAt: now.toISOString()
+        }));
+    }
+    clearAlarmSnooze(id) {
+        return this.mutateAlarm(id, existing => alarmSchema.parse({
+            ...existing,
+            nextOverride: undefined,
+            updatedAt: this.now().toISOString()
+        }));
+    }
     addRecent(station) {
         const key = stationKey(station);
         const recent = [
@@ -299,6 +512,28 @@ export class JsonLibraryStore {
         const key = stationKey(station);
         return this.state.favorites.some(item => stationKey(item) === key);
     }
+    mutateAlarm(id, change) {
+        const release = acquireStoreLock(this.filePath);
+        try {
+            const latestState = this.read();
+            const existing = latestState.alarms.find(alarm => alarm.id === id);
+            if (!existing) {
+                this.state = latestState;
+                throw new Error(`Alarm not found: ${id}`);
+            }
+            const alarm = change(existing);
+            const nextState = {
+                ...latestState,
+                alarms: latestState.alarms.map(item => item.id === id ? alarm : item)
+            };
+            this.write(nextState);
+            this.state = nextState;
+            return structuredClone(alarm);
+        }
+        finally {
+            release();
+        }
+    }
     read() {
         if (!existsSync(this.filePath)) {
             return defaultState();
@@ -412,6 +647,7 @@ function defaultState() {
         imported: [],
         trackHistory: [],
         searchHistory: [],
+        alarms: [],
         activity: { sessions: [] },
         settings: {
             theme: 'green',
@@ -425,6 +661,13 @@ function defaultState() {
             tuneTimeoutSeconds: 12,
             skipBrokenStreams: true,
             mouseSupport: true,
+            automaticUpdateChecks: true,
+            agentControl: {
+                enabled: false,
+                openUiOnPlay: true,
+                focusNowPlaying: true,
+                completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+            },
             mediaKeys: defaultMediaKeys
         }
     };
@@ -432,6 +675,7 @@ function defaultState() {
 function migrateLibraryState(state) {
     return {
         ...state,
+        alarms: state.alarms.map(normalizeAlarm),
         settings: {
             ...state.settings,
             preferredBackend: state.settings.preferredBackend === 'airplay' ? 'auto' : state.settings.preferredBackend,
@@ -440,6 +684,10 @@ function migrateLibraryState(state) {
         }
     };
 }
+function isRadioCliBackup(value) {
+    return typeof value === 'object' && value !== null && 'format' in value
+        && value.format === 'radiocli-backup';
+}
 function libraryStateForDisk(state) {
     return state.settings.preferredBackend === 'airplay'
         ? {
@@ -501,6 +749,7 @@ function mergeLibraryChanges(base, disk, next) {
         imported: mergeKeyedChanges(base.imported, disk.imported, next.imported, stationKey, 1000, true),
         trackHistory: mergeKeyedChanges(base.trackHistory, disk.trackHistory, next.trackHistory, item => `${item.at}:${item.stationKey}:${item.title}`, 100),
         searchHistory: mergeSearchHistory(base.searchHistory, disk.searchHistory, next.searchHistory),
+        alarms: mergeKeyedChanges(base.alarms, disk.alarms, next.alarms, alarm => alarm.id, MAX_ALARMS, true),
         updateCheck: sameValue(base.updateCheck, next.updateCheck) ? disk.updateCheck : next.updateCheck,
         activity: {
             sessions: mergeKeyedChanges(base.activity.sessions, disk.activity.sessions, next.activity.sessions, item => item.id, 2000)
@@ -508,6 +757,17 @@ function mergeLibraryChanges(base, disk, next) {
         settings: mergeSettings(base.settings, disk.settings, next.settings)
     };
 }
+function normalizeAlarm(alarm) {
+    const schedule = alarm.schedule.type === 'once'
+        ? { type: 'once', at: new Date(alarm.schedule.at).toISOString() }
+        : {
+            type: 'recurring',
+            time: canonicalizeAlarmTime(alarm.schedule.time),
+            weekdays: canonicalizeIsoWeekdays(alarm.schedule.weekdays),
+            timezone: canonicalizeTimeZone(alarm.schedule.timezone)
+        };
+    return { ...alarm, schedule };
+}
 function mergeKeyedChanges(base, disk, next, keyFor, limit, applyRemovals = false) {
     const baseByKey = new Map(base.map(item => [keyFor(item), item]));
     const nextKeys = new Set(next.map(keyFor));

package/dist/types.js

@@ -2,3 +2,9 @@ import { defaultReceiverStyle, receiverStyleNames } from './ui/visualizers/recei
 export { defaultReceiverStyle, receiverStyleNames };
 const providerIds = ['radio-browser', 'radio-garden', 'playlist'];
 export const themeNames = ['green', 'amber', 'blue', 'ruby', 'ice', 'teal', 'violet', 'copper', 'cyan', 'lime', 'coral', 'rose', 'slate', 'mono'];
+export const defaultAgentControlSettings = {
+    enabled: false,
+    openUiOnPlay: true,
+    focusNowPlaying: true,
+    completionPreset: { action: 'play', source: 'recent', ifPlaying: 'keep' }
+};