@ciphore/radiocli 0.2.3 → 0.2.5

package/dist/alarms/runner.js

@@ -1,6 +1,7 @@
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync } from 'node:fs';
-import { homedir } from 'node:os';
+import { platformPaths } from '../platform/paths.js';
 import { dirname, join } from 'node:path';
+import { createHash } from 'node:crypto';
 import { assessScheduledOccurrence, NATIVE_DISPATCH_TOLERANCE_MS, nextOccurrenceForAlarm } from './schedule.js';
 import { startActiveAlarmSession } from './active-session.js';
 export async function runAlarm(alarmId, scheduledAtText, deps) {
@@ -25,20 +26,41 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
     let lease;
     let systemVolumeLease;
     let listening = false;
+    let historyStarted = false;
     let firedAt;
+    const runnerWarnings = new Set();
+    const recordRunnerWarning = (message) => { runnerWarnings.add(message); try {
+        deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: listening, message: [...runnerWarnings].join(' ') });
+    }
+    catch { } };
     let preserveNextOverride = false;
     let preserveSystemVolume = false;
+    let handoffOutput;
     let validTerminalOccurrence = false;
+    let completeLock = true;
+    const tuneAbort = new AbortController();
     let signalReceived = false;
     let resolveEarlySignal = () => { };
     let onPlaybackSignal = () => { };
     const earlySignal = new Promise(resolve => { resolveEarlySignal = resolve; });
-    const unsubscribeSignals = deps.subscribeSignals?.(() => { signalReceived = true; resolveEarlySignal(); onPlaybackSignal(); void deps.player.stop().catch(() => undefined); });
+    const unsubscribeSignals = deps.subscribeSignals?.(() => { signalReceived = true; tuneAbort.abort(); resolveEarlySignal(); onPlaybackSignal(); void deps.player.stop().catch(() => undefined); });
     const finish = (status, message) => ({ status, scheduledAt: scheduledAt.toISOString(), ...(firedAt ? { firedAt: firedAt.toISOString() } : {}), finishedAt: deps.now().toISOString(), ...(message ? { message } : {}) });
     let action;
     let keepPlaying = false;
     let resolveAction = () => { };
     const actionPromise = new Promise(resolve => { resolveAction = resolve; });
+    let backendMessage;
+    let playbackStarted = false;
+    let backendEndedAt;
+    const unsubscribePlayer = deps.player.onChange?.(state => {
+        if ((!listening && !playbackStarted) || action || !['error', 'stopped', 'idle'].includes(state.state))
+            return;
+        backendMessage = state.message ?? 'Alarm stream ended before its scheduled stop.';
+        backendEndedAt = deps.now();
+        action = 'backend-ended';
+        resolveAction('backend-ended');
+        resolveEarlySignal();
+    });
     try {
         if (!alarm || !alarm.enabled)
             return { message: 'Alarm is missing or disabled.' };
@@ -49,6 +71,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         }
         const assessment = assessScheduledOccurrence(scheduledAt, deps.now(), alarm.reliability.missedRunGraceMinutes);
         if (assessment === 'pending') {
+            completeLock = false;
             outcome = finish('failed', 'Scheduler launched the alarm before its occurrence.');
             return { status: outcome.status, message: outcome.message };
         }
@@ -59,13 +82,13 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         }
         const claimingStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: alarm.station.name, station: alarm.station, startedAt: deps.now().toISOString(), state: 'starting' };
         const creatingSession = deps.createSession(claimingStatus, {
-            onDismiss: () => { action = 'dismissed'; resolveAction('dismissed'); resolveEarlySignal(); },
-            onSnooze: minutes => { deps.store.snoozeAlarm(alarmId, new Date(deps.now().getTime() + minutes * 60_000)); preserveNextOverride = true; action = 'snoozed'; resolveAction('snoozed'); resolveEarlySignal(); },
+            onDismiss: () => { tuneAbort.abort(); action = 'dismissed'; resolveAction('dismissed'); resolveEarlySignal(); },
+            onSnooze: async (minutes) => { await deps.store.snoozeAlarm(alarmId, new Date(deps.now().getTime() + minutes * 60_000)); preserveNextOverride = true; tuneAbort.abort(); action = 'snoozed'; resolveAction('snoozed'); resolveEarlySignal(); },
             onKeepPlaying: () => { keepPlaying = true; session?.update({ keepPlaying: true }); },
-            onHandoff: () => { if (!listening)
-                throw new Error('Alarm playback is still starting.'); preserveSystemVolume = true; action = 'handoff'; resolveAction('handoff'); }
+            onHandoff: async () => { if (!listening)
+                throw new Error('Alarm playback is still starting.'); handoffOutput = (systemVolumeLease?.release({ preserve: true }) ?? Promise.resolve()).then(() => { preserveSystemVolume = true; }); await handoffOutput; action = 'handoff'; resolveAction('handoff'); }
         });
-        void creatingSession.then(created => { if (signalReceived)
+        void creatingSession.then(created => { if (signalReceived || action)
             void created.close().catch(() => undefined); }).catch(() => { });
         const created = await Promise.race([creatingSession.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
         if ('signal' in created) {
@@ -87,7 +110,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         const candidates = [alarm.station, alarm.station, alarm.playback.fallbackStation].filter((item) => Boolean(item));
         for (const [candidateIndex, candidate] of candidates.entries()) {
             try {
-                const resolved = await Promise.race([deps.providers.resolve(candidate).then(stream => ({ stream })), earlySignal.then(() => ({ signal: true }))]);
+                const resolved = await Promise.race([deps.providers.resolve(candidate, { signal: tuneAbort.signal }).then(stream => ({ stream })), earlySignal.then(() => ({ signal: true }))]);
                 if ('signal' in resolved) {
                     outcome = finish('dismissed', 'Alarm interrupted before playback started.');
                     return { status: 'dismissed', message: outcome.message };
@@ -101,6 +124,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                         deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm continued after interactive playback could not be stopped cleanly: ${errorMessage(error)}` });
                     }
                 }
+                tuneAbort.signal.throwIfAborted();
                 if (!outputPrepared) {
                     outputPrepared = true;
                     if (deps.systemVolume)
@@ -112,7 +136,8 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                             deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: false, message: `Alarm will use player volume, but system output could not be raised: ${errorMessage(error)}` });
                         }
                 }
-                const playPromise = deps.player.play(candidate, resolved.stream.url);
+                tuneAbort.signal.throwIfAborted();
+                const playPromise = deps.player.play(candidate, resolved.stream.url, { signal: tuneAbort.signal });
                 const tuned = await Promise.race([playPromise.then(() => ({ played: true })), earlySignal.then(() => ({ signal: true }))]);
                 if ('signal' in tuned || signalReceived) {
                     void playPromise.then(() => deps.player.stop()).catch(() => undefined);
@@ -139,15 +164,19 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         }
         if (lastError)
             throw lastError;
+        playbackStarted = true;
+        const initialPlayback = deps.player.getState();
+        if (initialPlayback.state && ['error', 'stopped', 'idle'].includes(initialPlayback.state))
+            throw new Error(initialPlayback.message ?? 'Alarm stream ended before playback could be published.');
         firedAt = deps.now();
         try {
             const acquiring = deps.inhibitor.acquire('RadioCLI alarm playback');
-            void acquiring.then(acquired => { if (signalReceived)
+            void acquiring.then(acquired => { if (signalReceived || action)
                 void acquired.release().catch(() => undefined); }).catch(() => { });
             const acquired = await Promise.race([acquiring.then(value => ({ value })), earlySignal.then(() => ({ signal: true }))]);
             if ('signal' in acquired) {
-                outcome = finish('dismissed', 'Alarm interrupted while sleep protection was starting.');
-                return { status: 'dismissed', message: outcome.message };
+                outcome = finish(backendEndedAt ? 'failed' : 'dismissed', backendEndedAt ? backendMessage : 'Alarm interrupted while sleep protection was starting.');
+                return { status: outcome.status, message: outcome.message };
             }
             lease = acquired.value;
             deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: true, active: true, message: 'Sleep inhibition active while playing.' });
@@ -159,16 +188,27 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         catch (error) {
             deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'power', healthy: false, active: false, message: `Playback continues without sleep protection: ${errorMessage(error)}` });
         }
+        if (backendEndedAt)
+            throw new Error(backendMessage ?? 'Alarm stream ended while sleep protection was starting.');
         const startedAt = deps.now();
-        deps.store.addRecent(resolvedStation);
-        deps.store.startListeningSession(resolvedStation, startedAt);
         listening = true;
+        try {
+            await deps.store.addRecent(resolvedStation);
+        }
+        catch (error) {
+            recordRunnerWarning(`Recent listening history could not be saved: ${errorMessage(error)}`);
+        }
+        try {
+            await deps.store.startListeningSession(resolvedStation, startedAt);
+            historyStarted = true;
+        }
+        catch (error) {
+            recordRunnerWarning(`Listening history could not be started: ${errorMessage(error)}`);
+        }
         const activeStatus = { alarmId, scheduledAt: scheduledAt.toISOString(), stationName: resolvedStation.name, station: resolvedStation, startedAt: startedAt.toISOString(), state: 'playing' };
         session.update(activeStatus);
-        void deps.openControls?.(activeStatus).catch(error => { try {
-            deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'runner', healthy: false, active: true, message: `Alarm is playing, but RadioCLI controls could not open automatically: ${errorMessage(error)}` });
-        }
-        catch { } });
+        void deps.openControls?.(activeStatus).then(result => { if (result && !result.opened && result.terminal !== 'existing-tui')
+            recordRunnerWarning(`RadioCLI controls are unavailable or unverified: ${result.message}`); }).catch(error => { recordRunnerWarning(`RadioCLI controls could not open automatically: ${errorMessage(error)}`); });
         onPlaybackSignal = () => { action = 'signal'; resolveAction('signal'); };
         if (signalReceived)
             onPlaybackSignal();
@@ -203,19 +243,23 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                 action = await Promise.race([actionPromise, timeout]);
             }
         }
-        outcome = finish(action === 'dismissed' || action === 'snoozed' || action === 'signal' ? 'dismissed' : 'played', action === 'snoozed' ? 'Snoozed.' : action === 'handoff' ? 'Handed off to interactive playback.' : action === 'signal' ? 'Interrupted.' : undefined);
+        outcome = finish(action === 'backend-ended' ? 'failed' : action === 'dismissed' || action === 'snoozed' || action === 'signal' ? 'dismissed' : 'played', action === 'backend-ended' ? backendMessage : action === 'snoozed' ? 'Snoozed.' : action === 'handoff' ? 'Handed off to interactive playback.' : action === 'signal' ? 'Interrupted.' : undefined);
         return { status: outcome.status, message: outcome.message };
     }
     catch (error) {
-        outcome = finish('failed', errorMessage(error));
-        return { status: 'failed', message: outcome.message };
+        outcome = finish(tuneAbort.signal.aborted && action !== 'backend-ended' ? 'dismissed' : 'failed', errorMessage(error));
+        return { status: outcome.status, message: outcome.message };
     }
     finally {
+        listening = false;
+        unsubscribePlayer?.();
+        tuneAbort.abort();
         unsubscribeSignals?.();
         try {
             await deps.player.stop();
         }
         catch { }
+        await handoffOutput?.catch(() => undefined);
         if (!preserveSystemVolume)
             try {
                 await systemVolumeLease?.release();
@@ -226,12 +270,20 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
                 }
                 catch { }
             }
-        if (listening) {
+        if (historyStarted) {
+            const endedAt = backendEndedAt ?? deps.now();
             try {
-                deps.store.checkpointActiveListeningSession(deps.now());
-                deps.store.finishActiveListeningSession(deps.now());
+                await deps.store.checkpointActiveListeningSession(endedAt);
+            }
+            catch (error) {
+                recordRunnerWarning(`Listening history could not be checkpointed: ${errorMessage(error)}`);
+            }
+            try {
+                await deps.store.finishActiveListeningSession(endedAt);
+            }
+            catch (error) {
+                recordRunnerWarning(`Listening history could not be finished: ${errorMessage(error)}`);
             }
-            catch { }
         }
         try {
             await lease?.release();
@@ -250,12 +302,14 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
         catch { }
         if (alarm && outcome) {
             try {
-                deps.store.recordAlarmOutcome(alarmId, outcome, { clearNextOverride: !preserveNextOverride });
+                await deps.store.recordAlarmOutcome(alarmId, outcome, { clearNextOverride: validTerminalOccurrence && !preserveNextOverride });
                 const latest = deps.store.getAlarm(alarmId);
                 if (alarm.schedule.type === 'once' && latest?.schedule.type === 'once' && latest.schedule.at === alarm.schedule.at && validTerminalOccurrence && !preserveNextOverride)
-                    deps.store.toggleAlarm(alarmId, false);
+                    await deps.store.toggleAlarm(alarmId, false);
+            }
+            catch (error) {
+                recordRunnerWarning(`Alarm outcome or completion state could not be saved: ${errorMessage(error)}`);
             }
-            catch { }
         }
         alarm = deps.store.getAlarm(alarmId);
         if (alarm)
@@ -267,7 +321,7 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             }
             catch { }
         try {
-            releaseLock();
+            releaseLock(completeLock);
         }
         catch (error) {
             try {
@@ -275,22 +329,31 @@ export async function runAlarm(alarmId, scheduledAtText, deps) {
             }
             catch { }
         }
-        try {
-            await deps.scheduler.completeOccurrence?.(alarmId, scheduledAt);
-        }
-        catch (error) {
+        if (completeLock)
             try {
-                deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'scheduler', healthy: false, message: `Completed launch job cleanup failed: ${errorMessage(error)}` });
+                await deps.scheduler.completeOccurrence?.(alarmId, scheduledAt);
+            }
+            catch (error) {
+                try {
+                    deps.health?.record({ alarmId, occurrenceAt: scheduledAt.toISOString(), component: 'scheduler', healthy: false, message: `Completed launch job cleanup failed: ${errorMessage(error)}` });
+                }
+                catch { }
             }
-            catch { }
-        }
     }
 }
 export function acquireOccurrenceLock(alarmId, scheduledAt, root = defaultAlarmRuntimeDirectory()) {
-    const safe = `${alarmId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80)}-${Buffer.from(scheduledAt).toString('base64url')}`;
-    const path = join(root, 'locks', safe);
+    const occurrence = Buffer.from(scheduledAt).toString('base64url');
+    // Keep existing claims for application-generated UUIDs. Other accepted IDs
+    // need a bounded, case/normalization-safe identity on every filesystem. The
+    // dot prefix cannot be produced by the old lossy sanitizer.
+    const id = /^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(alarmId)
+        ? alarmId : `.id-${createHash('sha256').update(JSON.stringify(alarmId)).digest('hex')}`;
+    const path = join(root, 'locks', `${id}-${occurrence}`);
+    const legacyPath = join(root, 'locks', `${alarmId.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 80)}-${occurrence}`);
     mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
     pruneCompletedOccurrenceLocks(root);
+    if (path !== legacyPath && hasLegacyOccurrenceClaim(legacyPath, alarmId))
+        return null;
     try {
         mkdirSync(path, { mode: 0o700 });
     }
@@ -310,8 +373,42 @@ export function acquireOccurrenceLock(alarmId, scheduledAt, root = defaultAlarmR
             return null;
         }
     }
-    writeFileSync(join(path, 'running'), String(process.pid), { mode: 0o600 });
-    return () => { rmSync(join(path, 'running'), { force: true }); writeFileSync(join(path, 'completed'), new Date().toISOString(), { mode: 0o600 }); };
+    try {
+        writeFileSync(join(path, 'running'), String(process.pid), { mode: 0o600 });
+        writeFileSync(join(path, 'alarm-id'), JSON.stringify(alarmId), { mode: 0o600 });
+    }
+    catch (error) {
+        try {
+            rmSync(path, { recursive: true, force: true });
+        }
+        catch { }
+        throw error;
+    }
+    return (completed = true) => { if (!completed) {
+        rmSync(path, { recursive: true, force: true });
+        return;
+    } rmSync(join(path, 'running'), { force: true }); writeFileSync(join(path, 'completed'), new Date().toISOString(), { mode: 0o600 }); };
+}
+function hasLegacyOccurrenceClaim(path, alarmId) {
+    if (!existsSync(path))
+        return false;
+    try {
+        try {
+            if (JSON.parse(readFileSync(join(path, 'alarm-id'), 'utf8')) !== alarmId)
+                return false;
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        if (existsSync(join(path, 'completed')))
+            return true;
+        const pid = Number(readFileSync(join(path, 'running'), 'utf8'));
+        return !Number.isInteger(pid) || pid < 1 || processAlive(pid);
+    }
+    catch {
+        return existsSync(path); /* Unknown legacy ownership fails closed. */
+    }
 }
 export function pruneCompletedOccurrenceLocks(root = defaultAlarmRuntimeDirectory(), olderThanMs = 30 * 24 * 60 * 60_000, now = Date.now()) { const directory = join(root, 'locks'); if (!existsSync(directory))
     return 0; let removed = 0; for (const name of readdirSync(directory)) {
@@ -324,17 +421,15 @@ export function pruneCompletedOccurrenceLocks(root = defaultAlarmRuntimeDirector
     }
     catch { }
 } return removed; }
-export function defaultAlarmRuntimeDirectory() { if (process.env.RADIOCLI_HOME)
-    return join(process.env.RADIOCLI_HOME, 'runtime'); if (process.platform === 'win32')
-    return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime'); return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli'); }
+export function defaultAlarmRuntimeDirectory() { return platformPaths().runtime; }
 export const defaultRunnerUtilities = { acquireLock: acquireOccurrenceLock, createSession: startActiveAlarmSession, wait: (milliseconds) => new Promise(resolve => setTimeout(resolve, milliseconds)), subscribeSignals: (handler) => { process.once('SIGTERM', handler); process.once('SIGHUP', handler); process.once('SIGINT', handler); return () => { process.off('SIGTERM', handler); process.off('SIGHUP', handler); process.off('SIGINT', handler); }; } };
 function errorMessage(error) { return error instanceof Error ? error.message : String(error); }
 function processAlive(pid) { try {
     process.kill(pid, 0);
     return true;
 }
-catch {
-    return false;
+catch (error) {
+    return error.code !== 'ESRCH';
 } }
 function nextExpectedOccurrence(alarm, scheduledAt) { if (alarm.nextOverride)
     return new Date(alarm.nextOverride.at); if (alarm.schedule.type === 'once')

package/dist/alarms/schedule.js

@@ -1,5 +1,7 @@
 export const NATIVE_DISPATCH_TOLERANCE_MS = 30_000;
 const formatterCache = new Map();
+const timezoneCache = new Map();
+const civilOccurrenceCache = new Map();
 export function isValidTimeZone(timezone) {
     try {
         new Intl.DateTimeFormat('en-US', { timeZone: timezone }).format();
@@ -11,10 +13,27 @@ export function isValidTimeZone(timezone) {
 }
 export function canonicalizeTimeZone(timezone) {
     const value = timezone.trim();
-    if (!isValidTimeZone(value)) {
+    const cached = timezoneCache.get(value);
+    if (cached) {
+        timezoneCache.delete(value);
+        timezoneCache.set(value, cached);
+        return cached;
+    }
+    try {
+        if (!value)
+            throw new Error('Empty timezone.');
+        // The constructor validates the zone and resolves its canonical name.
+        // Constructing twice made large-library validation expensive on Node 22
+        // Intel hosts; keep one native validation for every supplied value.
+        const canonical = new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
+        timezoneCache.set(value, canonical);
+        while (timezoneCache.size > 256)
+            timezoneCache.delete(timezoneCache.keys().next().value);
+        return canonical;
+    }
+    catch {
         throw new Error(`Invalid IANA timezone: ${timezone}`);
     }
-    return new Intl.DateTimeFormat('en-US', { timeZone: value }).resolvedOptions().timeZone;
 }
 export function canonicalizeAlarmTime(time) {
     const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
@@ -99,6 +118,8 @@ function zonedParts(instant, timezone) {
             hourCycle: 'h23'
         });
         formatterCache.set(timezone, formatter);
+        while (formatterCache.size > 128)
+            formatterCache.delete(formatterCache.keys().next().value);
     }
     const values = Object.fromEntries(formatter.formatToParts(instant)
         .filter(part => part.type !== 'literal')
@@ -112,6 +133,20 @@ function zonedParts(instant, timezone) {
     };
 }
 function resolveCivilOccurrence(target, timezone) {
+    const key = `${timezone}:${target.year}:${target.month}:${target.day}:${target.hour}:${target.minute}`;
+    if (civilOccurrenceCache.has(key)) {
+        const cached = civilOccurrenceCache.get(key);
+        civilOccurrenceCache.delete(key);
+        civilOccurrenceCache.set(key, cached);
+        return cached === null ? null : new Date(cached);
+    }
+    const result = scanCivilOccurrence(target, timezone);
+    civilOccurrenceCache.set(key, result?.getTime() ?? null);
+    while (civilOccurrenceCache.size > 2048)
+        civilOccurrenceCache.delete(civilOccurrenceCache.keys().next().value);
+    return result;
+}
+function scanCivilOccurrence(target, timezone) {
     const estimate = Date.UTC(target.year, target.month - 1, target.day, target.hour, target.minute);
     const start = estimate - 18 * 60 * 60_000;
     const end = estimate + 18 * 60 * 60_000;