@ciphore/radiocli 0.2.1 → 0.2.3

package/dist/alarms/guard.js

@@ -0,0 +1,343 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { randomBytes } from 'node:crypto';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createServer, request } from 'node:http';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { AlarmPowerGuardStore } from './power-guard-store.js';
+import { nextOccurrenceForAlarm } from './schedule.js';
+import { defaultAlarmRuntimeDirectory } from './runner.js';
+export class AlarmGuardService {
+    store;
+    nodePath;
+    cliPath;
+    spawn;
+    now;
+    directory;
+    verify;
+    requestStop;
+    constructor(store, nodePath = process.execPath, cliPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'cli.js'), spawn = spawnGuard, now = () => new Date(), directory = join(defaultAlarmRuntimeDirectory(), 'alarm-guards'), verify = challengeGuard, requestStop = requestGuardStop) {
+        this.store = store;
+        this.nodePath = nodePath;
+        this.cliPath = cliPath;
+        this.spawn = spawn;
+        this.now = now;
+        this.directory = directory;
+        this.verify = verify;
+        this.requestStop = requestStop;
+    }
+    async start(alarm) {
+        return this.withOwnership(alarm.id, () => this.startOwned(alarm));
+    }
+    async startOwned(alarm) {
+        const occurrence = nextOccurrenceForAlarm(alarm, this.now());
+        if (!occurrence)
+            throw new Error('This alarm has no future enabled occurrence.');
+        const occurrenceAt = occurrence.toISOString();
+        const path = this.path(alarm.id, occurrenceAt);
+        const existing = readPid(path);
+        if (existing && await this.verify(existing))
+            return { occurrenceAt, pid: existing.pid };
+        // A recurring alarm may have been edited/rescheduled while its old guard is
+        // alive. Stop that exact process tree before replacing its occurrence state.
+        await this.stopOwned(alarm.id);
+        this.store.request(alarm.id, occurrenceAt);
+        const token = randomBytes(32).toString('hex');
+        const child = this.spawn(this.nodePath, [this.cliPath, 'alarm', 'internal-guard-run', alarm.id, occurrenceAt, path, token], process.env);
+        if (!child.pid) {
+            this.store.markFailed(alarm.id, 'Unable to start alarm guard.', occurrenceAt);
+            throw new Error('Unable to start alarm guard.');
+        }
+        child.unref();
+        for (let attempt = 0; attempt < 40; attempt += 1) {
+            const state = this.store.get(alarm.id);
+            const ownership = readPid(path);
+            if (state?.occurrenceAt === occurrenceAt && state.status === 'active' && ownership?.token === token && await this.verify(ownership))
+                return { occurrenceAt, pid: child.pid };
+            if (state?.occurrenceAt === occurrenceAt && state.status === 'failed') {
+                await terminateGuardTree(child.pid);
+                rmSync(path, { force: true });
+                throw new Error(state.message ?? 'Alarm guard failed to start.');
+            }
+            if (!isAlive(child.pid))
+                break;
+            await delay(50);
+        }
+        await terminateGuardTree(child.pid);
+        this.store.markFailed(alarm.id, 'Alarm guard did not confirm sleep inhibition.', occurrenceAt);
+        rmSync(path, { force: true });
+        throw new Error('Alarm guard did not confirm sleep inhibition.');
+    }
+    async stop(alarmId) {
+        if (alarmId)
+            return this.withOwnership(alarmId, () => this.stopOwned(alarmId));
+        const ids = [...new Set(this.pidFiles().map(readPid).filter((item) => Boolean(item)).map(item => item.alarmId))];
+        const results = await Promise.all(ids.map(id => this.withOwnership(id, () => this.stopOwned(id))));
+        return results.every(Boolean);
+    }
+    async stopOwned(alarmId) {
+        const targets = this.pidFiles()
+            .map(readPid)
+            .filter((item) => Boolean(item))
+            .filter(item => !alarmId || item.alarmId === alarmId);
+        if (!targets.length)
+            return false;
+        for (const current of targets) {
+            const path = this.path(current.alarmId, current.occurrenceAt);
+            if (!(await this.verify(current))) {
+                rmSync(path, { force: true });
+                markIfCurrent(this.store, current, 'Guard ownership challenge failed; the PID was not signaled.');
+                continue;
+            }
+            if (!(await this.requestStop(current))) {
+                markIfCurrent(this.store, current, 'Guard rejected its authenticated stop request; the PID was not signaled.');
+                continue;
+            }
+            for (let attempt = 0; attempt < 20 && isAlive(current.pid); attempt += 1)
+                await delay(50);
+            if (isAlive(current.pid) && await this.verify(current))
+                await terminateGuardTree(current.pid);
+            const alive = isAlive(current.pid);
+            if (alive) {
+                markIfCurrent(this.store, current, 'Unable to stop the guard helper; sleep inhibition may still be active.');
+                continue;
+            }
+            rmSync(path, { force: true });
+            const state = this.store.get(current.alarmId);
+            if (state?.occurrenceAt === current.occurrenceAt && state.status !== 'released') {
+                this.store.markReleased(current.alarmId, new Date(), current.occurrenceAt);
+            }
+        }
+        return targets.every(item => !isAlive(item.pid));
+    }
+    async status() {
+        const guards = [];
+        for (const path of this.pidFiles()) {
+            const pid = readPid(path);
+            if (!pid)
+                continue;
+            if (!(await this.verify(pid))) {
+                rmSync(path, { force: true });
+                markIfCurrent(this.store, pid, 'The guard process exited unexpectedly.');
+                continue;
+            }
+            guards.push({ active: true, alarmId: pid.alarmId, occurrenceAt: pid.occurrenceAt, pid: pid.pid });
+        }
+        return {
+            active: guards.length > 0,
+            guards,
+            message: guards.length ? `${guards.length} alarm guard${guards.length === 1 ? ' is' : 's are'} active.` : 'No alarm guard is active.'
+        };
+    }
+    path(alarmId, occurrenceAt) {
+        return join(this.directory, `${Buffer.from(`${alarmId}\0${occurrenceAt}`).toString('base64url')}.json`);
+    }
+    pidFiles() {
+        if (!existsSync(this.directory))
+            return [];
+        return readdirSync(this.directory).filter(name => name.endsWith('.json')).map(name => join(this.directory, name));
+    }
+    async withOwnership(alarmId, work) { const lock = join(this.directory, `.lock-${Buffer.from(alarmId).toString('base64url')}`); mkdirSync(this.directory, { recursive: true, mode: 0o700 }); const deadline = Date.now() + 3000; while (true) {
+        try {
+            mkdirSync(lock, { mode: 0o700 });
+            writeFileSync(join(lock, 'created'), String(Date.now()), { mode: 0o600 });
+            break;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            let stale = false;
+            try {
+                const created = Number(readFileSync(join(lock, 'created'), 'utf8'));
+                stale = Number.isFinite(created) ? Date.now() - created > 10_000 : Date.now() - statSync(lock).mtimeMs > 10_000;
+            }
+            catch {
+                try {
+                    stale = Date.now() - statSync(lock).mtimeMs > 10_000;
+                }
+                catch { }
+            }
+            if (stale) {
+                rmSync(lock, { recursive: true, force: true });
+                continue;
+            }
+            if (Date.now() > deadline)
+                throw new Error('Alarm Guard ownership is busy.');
+            await delay(20);
+        }
+    } try {
+        return await work();
+    }
+    finally {
+        rmSync(lock, { recursive: true, force: true });
+    } }
+}
+export async function runAlarmGuard(alarmId, occurrenceAtText, inhibitor, store = new AlarmPowerGuardStore(), now = () => new Date(), wait = delay, pidPath, ownershipToken) {
+    if (!/(?:Z|[+-]\d{2}:\d{2})$/.test(occurrenceAtText))
+        throw new Error('Guard occurrence must be an absolute ISO-8601 instant.');
+    const occurrence = new Date(occurrenceAtText);
+    if (!Number.isFinite(occurrence.getTime()))
+        throw new Error('Invalid guard occurrence.');
+    if (occurrence.getTime() <= now().getTime())
+        throw new Error('The guard occurrence has already passed.');
+    const occurrenceAt = occurrence.toISOString();
+    let lease;
+    let released = false;
+    let control;
+    let stopped = false;
+    let resolveSignal = () => { };
+    const signal = new Promise(resolve => { resolveSignal = resolve; });
+    const handler = () => { stopped = true; resolveSignal(); };
+    process.once('SIGTERM', handler);
+    process.once('SIGHUP', handler);
+    process.once('SIGINT', handler);
+    try {
+        lease = await inhibitor.acquire('Keep awake until RadioCLI alarm');
+        if (pidPath && ownershipToken)
+            control = await startGuardControl(pidPath, ownershipToken, alarmId, occurrenceAt, handler);
+        if (!store.get(alarmId))
+            store.request(alarmId, occurrenceAt);
+        store.markActive(alarmId, now(), occurrenceAt);
+        const deadline = occurrence.getTime() + 60_000;
+        const inhibitorExit = lease.unexpectedExit?.then(error => { throw error; });
+        while (!stopped && now().getTime() < deadline) {
+            await Promise.race([wait(Math.min(30_000, 2_000_000_000, deadline - now().getTime())), signal, ...(inhibitorExit ? [inhibitorExit] : [])]);
+        }
+        await lease.release();
+        released = true;
+        store.markReleased(alarmId, now(), occurrenceAt);
+    }
+    catch (error) {
+        const state = store.get(alarmId);
+        const stillOwnsArtifact = !pidPath || !ownershipToken || ownsArtifact(pidPath, ownershipToken);
+        if (!released && stillOwnsArtifact && state?.occurrenceAt === occurrenceAt && state.status !== 'released') {
+            store.markFailed(alarmId, error instanceof Error ? error.message : String(error), occurrenceAt);
+        }
+        throw error;
+    }
+    finally {
+        process.off('SIGTERM', handler);
+        process.off('SIGHUP', handler);
+        process.off('SIGINT', handler);
+        if (!released)
+            await lease?.release().catch(() => undefined);
+        await control?.close();
+        if (pidPath && (!ownershipToken || ownsArtifact(pidPath, ownershipToken)))
+            rmSync(pidPath, { force: true });
+    }
+}
+function markIfCurrent(store, pid, message) {
+    const state = store.get(pid.alarmId);
+    if (state?.occurrenceAt === pid.occurrenceAt && state.status !== 'released' && state.status !== 'failed') {
+        store.markFailed(pid.alarmId, message, pid.occurrenceAt);
+    }
+}
+function spawnGuard(command, args, env) {
+    return nodeSpawn(command, args, { env, detached: true, stdio: 'ignore', windowsHide: true });
+}
+function readPid(path) {
+    if (!existsSync(path))
+        return undefined;
+    try {
+        const value = JSON.parse(readFileSync(path, 'utf8'));
+        if (!Number.isInteger(value.pid) || !Number.isInteger(value.port) || value.port < 1 || value.port > 65535 || !value.alarmId || !/^[a-f0-9]{64}$/.test(value.token) || !/(?:Z|[+-]\d{2}:\d{2})$/.test(value.occurrenceAt) || !Number.isFinite(Date.parse(value.occurrenceAt)))
+            throw new Error();
+        return value;
+    }
+    catch {
+        return undefined;
+    }
+}
+function writePrivate(path, value) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const temp = `${path}.tmp-${process.pid}-${randomBytes(6).toString('hex')}`;
+    writeFileSync(temp, JSON.stringify(value), { mode: 0o600 });
+    renameSync(temp, path);
+    if (process.platform !== 'win32')
+        chmodSync(path, 0o600);
+}
+function isAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ownsArtifact(path, token) {
+    return readPid(path)?.token === token;
+}
+async function startGuardControl(path, token, alarmId, occurrenceAt, onStop) { const server = createServer((req, res) => { if (req.headers.authorization !== `Bearer ${token}`) {
+    res.statusCode = 401;
+    res.end('{}');
+    return;
+} if (req.method === 'POST' && req.url === '/stop') {
+    onStop();
+    res.end('{}');
+    return;
+} if (req.method !== 'GET' || req.url !== '/challenge') {
+    res.statusCode = 404;
+    res.end('{}');
+    return;
+} res.setHeader('content-type', 'application/json'); res.end(JSON.stringify({ alarmId, occurrenceAt, pid: process.pid })); }); await new Promise((resolve, reject) => { server.once('error', reject); server.listen(0, '127.0.0.1', resolve); }); const address = server.address(); if (!address || typeof address === 'string') {
+    server.close();
+    throw new Error('Unable to create Guard ownership endpoint.');
+} writePrivate(path, { alarmId, occurrenceAt, pid: process.pid, port: address.port, token }); return { close: () => new Promise(resolve => server.close(() => resolve())) }; }
+function challengeGuard(guard) { return callGuard(guard, 'GET', '/challenge', true); }
+function requestGuardStop(guard) { return callGuard(guard, 'POST', '/stop', false); }
+function callGuard(guard, method, path, validateIdentity) { return new Promise(resolve => { const req = request({ host: '127.0.0.1', port: guard.port, path, method, headers: { authorization: `Bearer ${guard.token}` } }, res => { let body = ''; res.on('data', value => body += String(value)); res.on('end', () => { if (!validateIdentity) {
+    resolve(res.statusCode === 200);
+    return;
+} try {
+    const reply = JSON.parse(body);
+    resolve(res.statusCode === 200 && reply.alarmId === guard.alarmId && reply.occurrenceAt === guard.occurrenceAt && reply.pid === guard.pid);
+}
+catch {
+    resolve(false);
+} }); }); req.once('error', () => resolve(false)); req.setTimeout(500, () => req.destroy()); req.end(); }); }
+export async function terminateGuardTree(pid, ops = { platform: process.platform, isAlive, kill: (target, signal) => process.kill(target, signal), taskkill: taskkillTree, wait: delay }) {
+    // Kill the entire detached tree first on Windows so a dying parent cannot
+    // orphan its PowerShell execution-state helper.
+    if (ops.platform === 'win32') {
+        await ops.taskkill(pid, false);
+    }
+    else {
+        try {
+            ops.kill(pid, 'SIGTERM');
+        }
+        catch {
+            return;
+        }
+    }
+    for (let index = 0; index < 20 && ops.isAlive(pid); index += 1)
+        await ops.wait(50);
+    if (!ops.isAlive(pid))
+        return;
+    if (ops.platform === 'win32')
+        await ops.taskkill(pid, true);
+    else {
+        // The guard is a detached process-group leader; force-killing the negative
+        // PID guarantees its inhibitor helper cannot survive an unresponsive parent.
+        try {
+            ops.kill(-pid, 'SIGKILL');
+        }
+        catch {
+            try {
+                ops.kill(pid, 'SIGKILL');
+            }
+            catch { }
+        }
+    }
+}
+function taskkillTree(pid, force) {
+    return new Promise(resolve => {
+        const args = ['/PID', String(pid), '/T', ...(force ? ['/F'] : [])];
+        const child = nodeSpawn('taskkill.exe', args, { stdio: 'ignore', windowsHide: true });
+        child.once('close', () => resolve());
+        child.once('error', () => resolve());
+    });
+}
+function delay(milliseconds) {
+    return new Promise(resolve => setTimeout(resolve, milliseconds));
+}

package/dist/alarms/inhibitor.js

@@ -0,0 +1,48 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+// The script contains no interpolated data. It keeps one process-level Windows
+// execution-state request alive until the parent terminates it.
+const windowsInhibitorScript = (parentPid) => `$s='[DllImport("kernel32.dll")]public static extern uint SetThreadExecutionState(uint e);';Add-Type -MemberDefinition $s -Name P -Namespace R;[R.P]::SetThreadExecutionState(0x80000001)|Out-Null;try{while(Get-Process -Id ${parentPid} -ErrorAction SilentlyContinue){Start-Sleep -Seconds 2}}finally{[R.P]::SetThreadExecutionState(0x80000000)|Out-Null}`;
+export function createPowerInhibitor(deps = {}) {
+    const platform = deps.platform ?? process.platform;
+    const spawn = deps.spawn ?? spawnDetached;
+    const exists = deps.commandExists ?? executableExists;
+    const spec = platform === 'darwin'
+        ? { command: 'caffeinate', args: ['-i', '-w', String(process.pid)], message: 'Prevents idle system sleep; the display may sleep.' }
+        : platform === 'linux'
+            ? { command: 'systemd-inhibit', args: ['--what=sleep', '--who=RadioCLI', '--why=Scheduled radio', '--mode=block', 'sh', '-c', 'while kill -0 "$1" 2>/dev/null; do sleep 2; done', 'radiocli-inhibitor', String(process.pid)], message: 'Uses a logind sleep inhibitor; explicit sleep and lid policy may override it.' }
+            : platform === 'win32'
+                ? { command: 'powershell.exe', args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', windowsInhibitorScript(process.pid)], message: 'Prevents idle system sleep; explicit sleep and lid policy may override it.' }
+                : null;
+    let active = false;
+    const supported = Boolean(spec && exists(spec.command));
+    return {
+        status: () => ({ supported, active, message: spec?.message ?? `Power inhibition is unsupported on ${platform}.` }),
+        async acquire(_reason) {
+            if (!spec || !supported)
+                throw new Error(spec?.message ?? `Power inhibition is unsupported on ${platform}.`);
+            const child = spawn(spec.command, spec.args);
+            const exitedEarly = await Promise.race([child.exited.then(() => true), new Promise(resolve => setTimeout(() => resolve(false), 50))]);
+            if (exitedEarly)
+                throw new Error(`${spec.command} exited before sleep inhibition became active.`);
+            active = true;
+            let released = false;
+            const unexpectedExit = child.exited.then(() => released ? new Promise(() => { }) : new Error(`${spec.command} exited unexpectedly; sleep protection was lost.`));
+            return { unexpectedExit, async release() { if (released)
+                    return; released = true; active = false; child.kill('SIGTERM'); if (await exitedWithin(child.exited, 1000))
+                    return; child.kill('SIGKILL'); if (!(await exitedWithin(child.exited, 500)))
+                    throw new Error(`${spec.command} did not terminate; sleep protection state is unknown.`); } };
+        }
+    };
+}
+function executableExists(command) {
+    if (existsSync(command))
+        return true;
+    return Boolean(process.env.PATH?.split(delimiter).some(path => existsSync(join(path, command)) || (process.platform === 'win32' && existsSync(join(path, `${command}.exe`)))));
+}
+function spawnDetached(command, args) {
+    const child = nodeSpawn(command, args, { stdio: 'ignore', windowsHide: true });
+    return { pid: child.pid, kill: signal => child.kill(signal), exited: new Promise(resolve => { child.once('exit', resolve); child.once('error', resolve); }) };
+}
+async function exitedWithin(exited, milliseconds) { return Promise.race([exited.then(() => true), new Promise(resolve => setTimeout(() => resolve(false), milliseconds))]); }

package/dist/alarms/power-guard-store.js

@@ -0,0 +1,169 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { z } from 'zod';
+const instantSchema = z.string()
+    .refine(value => /(?:Z|[+-]\d{2}:\d{2})$/.test(value) && Number.isFinite(Date.parse(value)), { message: 'Expected an absolute ISO-8601 alarm occurrence instant with Z or an offset.' })
+    .transform(value => new Date(value).toISOString());
+const guardSchema = z.object({
+    alarmId: z.string().min(1),
+    occurrenceAt: instantSchema,
+    status: z.enum(['requested', 'active', 'released', 'failed']),
+    acquiredAt: instantSchema.optional(),
+    releasedAt: instantSchema.optional(),
+    message: z.string().max(1000).optional()
+});
+const fileSchema = z.object({ version: z.literal(1), guards: z.array(guardSchema) });
+/** Machine-local, non-portable state for one-shot power-inhibition requests. */
+export class AlarmPowerGuardStore {
+    filePath;
+    now;
+    constructor(filePath = defaultAlarmPowerGuardPath(), options = {}) {
+        this.filePath = filePath;
+        this.now = options.now ?? (() => new Date());
+    }
+    request(alarmId, occurrenceAt) {
+        const guard = guardSchema.parse({ alarmId, occurrenceAt, status: 'requested' });
+        return this.mutate(guards => [guard, ...guards.filter(item => item.alarmId !== alarmId)], guard.alarmId);
+    }
+    get(alarmId) {
+        const guard = this.read().find(item => item.alarmId === alarmId);
+        return guard ? structuredClone(guard) : undefined;
+    }
+    list() {
+        return structuredClone(this.read());
+    }
+    markActive(alarmId, acquiredAt = this.now(), occurrenceAt) {
+        return this.update(alarmId, guard => ({
+            ...assertGuardOccurrence(guard, occurrenceAt),
+            status: 'active',
+            acquiredAt: validDate(acquiredAt, 'power guard acquisition').toISOString(),
+            releasedAt: undefined,
+            message: undefined
+        }));
+    }
+    markFailed(alarmId, message, occurrenceAt) {
+        return this.update(alarmId, guard => ({ ...assertGuardOccurrence(guard, occurrenceAt), status: 'failed', message: message.trim() }));
+    }
+    markReleased(alarmId, releasedAt = this.now(), occurrenceAt) {
+        return this.update(alarmId, guard => ({
+            ...assertGuardOccurrence(guard, occurrenceAt),
+            status: 'released',
+            releasedAt: validDate(releasedAt, 'power guard release').toISOString()
+        }));
+    }
+    clear(alarmId) {
+        const release = acquireFileLock(this.filePath);
+        try {
+            const guards = this.read();
+            if (!guards.some(guard => guard.alarmId === alarmId))
+                return false;
+            this.write(guards.filter(guard => guard.alarmId !== alarmId));
+            return true;
+        }
+        finally {
+            release();
+        }
+    }
+    update(alarmId, change) {
+        const release = acquireFileLock(this.filePath);
+        try {
+            const guards = this.read();
+            const existing = guards.find(guard => guard.alarmId === alarmId);
+            if (!existing)
+                throw new Error(`Alarm power guard not found: ${alarmId}`);
+            const updated = guardSchema.parse(change(existing));
+            this.write(guards.map(guard => guard.alarmId === alarmId ? updated : guard));
+            return structuredClone(updated);
+        }
+        finally {
+            release();
+        }
+    }
+    mutate(change, resultId) {
+        const release = acquireFileLock(this.filePath);
+        try {
+            const next = change(this.read());
+            this.write(next);
+            const result = next.find(guard => guard.alarmId === resultId);
+            if (!result)
+                throw new Error(`Alarm power guard not found after update: ${resultId}`);
+            return structuredClone(result);
+        }
+        finally {
+            release();
+        }
+    }
+    read() {
+        if (!existsSync(this.filePath))
+            return [];
+        try {
+            return fileSchema.parse(JSON.parse(readFileSync(this.filePath, 'utf8'))).guards;
+        }
+        catch {
+            const badPath = `${this.filePath}.bad`;
+            rmSync(badPath, { force: true });
+            renameSync(this.filePath, badPath);
+            return [];
+        }
+    }
+    write(guards) {
+        mkdirSync(dirname(this.filePath), { recursive: true, mode: 0o700 });
+        const tempPath = `${this.filePath}.tmp-${process.pid}-${Date.now()}`;
+        try {
+            writeFileSync(tempPath, `${JSON.stringify({ version: 1, guards }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+            renameSync(tempPath, this.filePath);
+            if (process.platform !== 'win32')
+                chmodSync(this.filePath, 0o600);
+        }
+        catch (error) {
+            rmSync(tempPath, { force: true });
+            throw error;
+        }
+    }
+}
+function defaultAlarmPowerGuardPath() {
+    if (process.env.RADIOCLI_HOME)
+        return join(process.env.RADIOCLI_HOME, 'runtime', 'alarm-power-guards.json');
+    if (process.platform === 'darwin') {
+        return join(homedir(), 'Library', 'Application Support', 'radiocli', 'runtime', 'alarm-power-guards.json');
+    }
+    if (process.platform === 'win32') {
+        return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'RadioCLI', 'runtime', 'alarm-power-guards.json');
+    }
+    return join(process.env.XDG_RUNTIME_DIR ?? join(homedir(), '.local', 'state'), 'radiocli', 'alarm-power-guards.json');
+}
+function validDate(date, label) {
+    if (!Number.isFinite(date.getTime()))
+        throw new Error(`Invalid ${label} time.`);
+    return date;
+}
+function assertGuardOccurrence(guard, occurrenceAt) { if (occurrenceAt && guard.occurrenceAt !== new Date(occurrenceAt).toISOString())
+    throw new Error('Alarm power guard occurrence was superseded.'); return guard; }
+function acquireFileLock(filePath) {
+    const lockPath = `${filePath}.lock`;
+    mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + 1000;
+    while (true) {
+        try {
+            mkdirSync(lockPath, { mode: 0o700 });
+            return () => rmSync(lockPath, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST')
+                throw error;
+            try {
+                if (Date.now() - statSync(lockPath).mtimeMs > 10_000) {
+                    rmSync(lockPath, { recursive: true, force: true });
+                    continue;
+                }
+            }
+            catch {
+                continue;
+            }
+            if (Date.now() >= deadline)
+                throw new Error(`Alarm power guard state is busy: ${filePath}`);
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 10);
+        }
+    }
+}