@ajclarkson/homerun 0.0.1-edge.0131fc6

package/dist/src/framework/scheduler.js

@@ -0,0 +1,55 @@
+import cron from 'node-cron';
+export class Scheduler {
+    automations;
+    dispatch;
+    ready;
+    cleanups = [];
+    constructor(automations, dispatch, ready) {
+        this.automations = automations;
+        this.dispatch = dispatch;
+        this.ready = ready;
+    }
+    start() {
+        this.registerCronTriggers(this.automations);
+        this.ready.then(() => {
+            const correlation_id = crypto.randomUUID();
+            this.dispatch({ type: 'on_start', correlation_id, root_correlation_id: correlation_id });
+        }).catch((err) => {
+            console.error('[scheduler] ready promise rejected:', err);
+        });
+    }
+    sync(automations) {
+        this.stop();
+        this.registerCronTriggers(automations);
+    }
+    stop() {
+        for (const cleanup of this.cleanups)
+            cleanup();
+        this.cleanups.length = 0;
+    }
+    registerCronTriggers(automations) {
+        const automationIdsByExpression = new Map();
+        for (const automation of automations) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'schedule') {
+                    const ids = automationIdsByExpression.get(trigger.cron) ?? [];
+                    ids.push(automation.id);
+                    automationIdsByExpression.set(trigger.cron, ids);
+                }
+            }
+        }
+        for (const [expression, automationIds] of automationIdsByExpression) {
+            try {
+                const task = cron.schedule(expression, () => {
+                    const correlation_id = crypto.randomUUID();
+                    this.dispatch({ type: 'schedule', cron: expression, correlation_id, root_correlation_id: correlation_id });
+                });
+                this.cleanups.push(() => task.stop());
+                console.log(`[scheduler] registered cron "${expression}" for ${automationIds.join(', ')}`);
+            }
+            catch (err) {
+                console.error(`[scheduler] failed to register cron "${expression}" for ${automationIds.join(', ')}:`, err);
+            }
+        }
+    }
+}

package/dist/src/framework/timer-manager.d.ts

@@ -0,0 +1,9 @@
+import type { TriggerEvent } from '../types/triggers.js';
+export declare class TimerManager {
+    private readonly dispatch;
+    private readonly timers;
+    constructor(dispatch: (event: TriggerEvent) => void);
+    start(timerKey: string, delayMs: number): void;
+    cancel(timerKey: string): void;
+    cancelAll(): void;
+}

package/dist/src/framework/timer-manager.js

@@ -0,0 +1,28 @@
+export class TimerManager {
+    dispatch;
+    timers = new Map();
+    constructor(dispatch) {
+        this.dispatch = dispatch;
+    }
+    start(timerKey, delayMs) {
+        this.cancel(timerKey);
+        const handle = setTimeout(() => {
+            this.timers.delete(timerKey);
+            const correlation_id = crypto.randomUUID();
+            this.dispatch({ type: 'timer_expired', timerKey, correlation_id, root_correlation_id: correlation_id });
+        }, delayMs);
+        this.timers.set(timerKey, handle);
+    }
+    cancel(timerKey) {
+        const handle = this.timers.get(timerKey);
+        if (handle !== undefined) {
+            clearTimeout(handle);
+            this.timers.delete(timerKey);
+        }
+    }
+    cancelAll() {
+        for (const handle of this.timers.values())
+            clearTimeout(handle);
+        this.timers.clear();
+    }
+}

package/dist/src/framework/trigger-engine.d.ts

@@ -0,0 +1,28 @@
+import type { MqttClient } from 'mqtt';
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+import type { HAClient } from './ha-client.js';
+import type { AutomationRegistry } from './registry.js';
+import type { MetricsBackend } from './metrics.js';
+export declare function parseButtonAction(state: string): {
+    button?: string;
+    pressType: 'short' | 'hold';
+} | null;
+export declare class TriggerEngine {
+    private readonly registry;
+    private readonly haClient;
+    private readonly onMatch;
+    private readonly mqttClient?;
+    private readonly metrics?;
+    private readonly buttonHandlers;
+    private regexButtonTriggers;
+    private readonly durationTimers;
+    private readonly subscribedTopics;
+    private started;
+    constructor(registry: AutomationRegistry, haClient: HAClient, onMatch: (automation: Automation<unknown>, event: TriggerEvent) => void, mqttClient?: MqttClient | undefined, metrics?: MetricsBackend | undefined);
+    private syncMqttSubscriptions;
+    private rebuildButtonHandlers;
+    start(): void;
+    dispatch(event: TriggerEvent): void;
+    private matchAndFire;
+}

package/dist/src/framework/trigger-engine.js

@@ -0,0 +1,321 @@
+const DOUBLE_PRESS_WINDOW_MS = 250;
+class ButtonGestureHandler {
+    entityId;
+    dispatch;
+    supportsDoublePress;
+    gestureState = 'idle';
+    resolveTimer = null;
+    holdFired = false;
+    // Set when 'release' fires a short press; suppresses the trailing confirmation
+    // event ('on', 'toggle', etc.) so the same physical press doesn't fire twice.
+    shortFired = false;
+    constructor(entityId, dispatch, supportsDoublePress) {
+        this.entityId = entityId;
+        this.dispatch = dispatch;
+        this.supportsDoublePress = supportsDoublePress;
+    }
+    handle(actionState, corr) {
+        if (actionState === '')
+            return;
+        const parsed = parseButtonAction(actionState);
+        if (!parsed)
+            return;
+        const { button, pressType } = parsed;
+        const isRelease = actionState.toLowerCase() === 'release';
+        if (pressType === 'hold') {
+            // Cancel any pending double-press window and fire hold exactly once per physical hold.
+            if (this.resolveTimer) {
+                clearTimeout(this.resolveTimer);
+                this.resolveTimer = null;
+                this.gestureState = 'idle';
+            }
+            if (!this.holdFired) {
+                this.holdFired = true;
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, ...corr });
+            }
+            return;
+        }
+        // pressType === 'short'
+        if (isRelease && this.holdFired) {
+            // Physical release after a hold — reset hold state, don't fire short press.
+            this.holdFired = false;
+            return;
+        }
+        if (!isRelease && this.shortFired) {
+            // Confirmation event ('on', 'toggle', etc.) after 'release' already fired — suppress.
+            this.shortFired = false;
+            return;
+        }
+        if (isRelease)
+            this.shortFired = true;
+        if (this.gestureState === 'idle') {
+            if (!this.supportsDoublePress) {
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, ...corr });
+            }
+            else {
+                this.gestureState = 'resolving';
+                this.resolveTimer = setTimeout(() => {
+                    this.resolveTimer = null;
+                    this.gestureState = 'idle';
+                    this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, ...corr });
+                }, DOUBLE_PRESS_WINDOW_MS);
+            }
+        }
+        else {
+            // resolving — second short press = double press
+            clearTimeout(this.resolveTimer);
+            this.resolveTimer = null;
+            this.gestureState = 'idle';
+            this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'double_press', button, ...corr });
+        }
+    }
+}
+// Classifies a Z2M action state string.
+// Numeric button prefix ("1_short_release") is separated out and returned as `button`.
+// Recognises common Z2M short/hold conventions; returns null for unrecognised values.
+export function parseButtonAction(state) {
+    const s = state.toLowerCase();
+    const prefixed = s.match(/^(\d+)[_-](.+)$/);
+    const button = prefixed?.[1];
+    const action = prefixed ? prefixed[2] : s;
+    if (/long|hold/.test(action))
+        return { button, pressType: 'hold' };
+    if (/short|click|single/.test(action) || action === 'on' || action === 'toggle' || action === 'release') {
+        return { button, pressType: 'short' };
+    }
+    return null;
+}
+// ---------- Trigger Engine ----------
+export class TriggerEngine {
+    registry;
+    haClient;
+    onMatch;
+    mqttClient;
+    metrics;
+    buttonHandlers = new Map();
+    regexButtonTriggers = [];
+    durationTimers = new Map();
+    subscribedTopics = new Set();
+    started = false;
+    constructor(registry, haClient, onMatch, mqttClient, metrics) {
+        this.registry = registry;
+        this.haClient = haClient;
+        this.onMatch = onMatch;
+        this.mqttClient = mqttClient;
+        this.metrics = metrics;
+        this.rebuildButtonHandlers();
+        registry.onChange(() => {
+            this.rebuildButtonHandlers();
+            this.syncMqttSubscriptions();
+        });
+    }
+    // Reconciles the set of subscribed mqtt_in topics against the registry's current
+    // automations. Called on start() and again whenever the registry changes (hot
+    // reload / git-sync rescan) so topics added or removed after startup take effect.
+    syncMqttSubscriptions() {
+        if (!this.mqttClient || !this.started)
+            return;
+        const desired = new Set();
+        for (const automation of this.registry.getAll()) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'mqtt_in')
+                    desired.add(trigger.topic);
+            }
+        }
+        for (const topic of desired) {
+            if (!this.subscribedTopics.has(topic)) {
+                this.mqttClient.subscribe(topic);
+                this.subscribedTopics.add(topic);
+                console.log(`[trigger-engine] mqtt subscribed: ${topic}`);
+            }
+        }
+        for (const topic of this.subscribedTopics) {
+            if (!desired.has(topic)) {
+                this.mqttClient.unsubscribe(topic);
+                this.subscribedTopics.delete(topic);
+                console.log(`[trigger-engine] mqtt unsubscribed: ${topic}`);
+            }
+        }
+    }
+    rebuildButtonHandlers() {
+        this.buttonHandlers.clear();
+        this.regexButtonTriggers = [];
+        const entityGestures = new Map();
+        const regexGestures = new Map();
+        for (const automation of this.registry.getAll()) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'button') {
+                    if (typeof trigger.entity === 'string') {
+                        if (!entityGestures.has(trigger.entity))
+                            entityGestures.set(trigger.entity, new Set());
+                        entityGestures.get(trigger.entity).add(trigger.gesture);
+                    }
+                    else {
+                        if (!regexGestures.has(trigger.entity))
+                            regexGestures.set(trigger.entity, new Set());
+                        regexGestures.get(trigger.entity).add(trigger.gesture);
+                    }
+                }
+            }
+        }
+        for (const [entity, gestures] of entityGestures) {
+            this.buttonHandlers.set(entity, new ButtonGestureHandler(entity, (e) => this.dispatch(e), gestures.has('double_press')));
+        }
+        for (const [pattern, gestures] of regexGestures) {
+            this.regexButtonTriggers.push({ pattern, gestures });
+        }
+    }
+    start() {
+        this.haClient.ready
+            .then(() => {
+            this.haClient.on('state_changed', (event) => {
+                this.metrics?.incrementCounter('homerun_ha_events_received_total', { event_type: 'state_changed' });
+                const corr = {
+                    correlation_id: event.correlation_id,
+                    ...(event.parent_correlation_id && { parent_correlation_id: event.parent_correlation_id }),
+                    ...(event.root_correlation_id && { root_correlation_id: event.root_correlation_id }),
+                    ...(event.parent_automation_id && { parent_automation_id: event.parent_automation_id }),
+                };
+                let handler = this.buttonHandlers.get(event.entity_id);
+                if (!handler) {
+                    const matchingGestures = new Set();
+                    for (const { pattern, gestures } of this.regexButtonTriggers) {
+                        if (pattern.test(event.entity_id)) {
+                            for (const g of gestures)
+                                matchingGestures.add(g);
+                        }
+                    }
+                    if (matchingGestures.size > 0) {
+                        handler = new ButtonGestureHandler(event.entity_id, (e) => this.dispatch(e), matchingGestures.has('double_press'));
+                        this.buttonHandlers.set(event.entity_id, handler);
+                    }
+                }
+                if (handler) {
+                    handler.handle(event.new_state.state, corr);
+                }
+                else {
+                    this.dispatch({
+                        type: 'state_changed',
+                        entity_id: event.entity_id,
+                        old_state: event.old_state,
+                        new_state: event.new_state,
+                        ...corr,
+                    });
+                }
+            });
+        })
+            .catch((err) => {
+            console.error('[trigger-engine] failed to start:', err);
+        });
+        if (this.mqttClient) {
+            this.started = true;
+            this.syncMqttSubscriptions();
+            this.mqttClient.subscribe('homerun/trigger/+');
+            this.mqttClient.on('message', (topic, payload) => {
+                if (topic.startsWith('homerun/trigger/')) {
+                    const automationId = topic.slice('homerun/trigger/'.length);
+                    const automation = this.registry.getById(automationId);
+                    if (!automation) {
+                        console.warn(`[trigger-engine] manual trigger: no automation with id "${automationId}"`);
+                        return;
+                    }
+                    const correlation_id = crypto.randomUUID();
+                    this.onMatch(automation, { type: 'on_start', correlation_id, root_correlation_id: correlation_id });
+                    return;
+                }
+                const correlation_id = `mqtt-${Date.now()}`;
+                this.dispatch({
+                    type: 'mqtt_in',
+                    topic,
+                    payload: payload.toString(),
+                    correlation_id,
+                    root_correlation_id: correlation_id,
+                });
+            });
+        }
+    }
+    // Entry point for Timer Manager loopback and resolved button gestures.
+    dispatch(event) {
+        this.matchAndFire(event);
+    }
+    // ---------- Private ----------
+    matchAndFire(event) {
+        for (const automation of this.registry.getAll()) {
+            for (const trigger of automation.triggers) {
+                if (matchesTrigger(trigger, event)) {
+                    if (trigger.type === 'state_changed' && trigger.duration && event.type === 'state_changed') {
+                        const key = `${automation.id}:${event.entity_id}`;
+                        const existing = this.durationTimers.get(key);
+                        if (existing !== undefined)
+                            clearTimeout(existing);
+                        const timer = setTimeout(() => {
+                            this.durationTimers.delete(key);
+                            if (this.haClient.state(event.entity_id)?.state === event.new_state.state) {
+                                this.onMatch(automation, event);
+                            }
+                        }, trigger.duration);
+                        this.durationTimers.set(key, timer);
+                    }
+                    else {
+                        this.onMatch(automation, event);
+                    }
+                    break; // don't fire the same automation twice for one event
+                }
+            }
+        }
+    }
+}
+// ---------- Trigger matching ----------
+function matchesTrigger(trigger, event) {
+    if (trigger.type !== event.type)
+        return false;
+    switch (trigger.type) {
+        case 'state_changed': {
+            if (event.type !== 'state_changed')
+                return false;
+            const entityMatch = typeof trigger.entity === 'string'
+                ? trigger.entity === event.entity_id
+                : trigger.entity.test(event.entity_id);
+            if (!entityMatch)
+                return false;
+            if (trigger.to !== undefined) {
+                const allowed = Array.isArray(trigger.to) ? trigger.to : [trigger.to];
+                if (!allowed.includes(event.new_state.state))
+                    return false;
+                if (event.old_state?.state === event.new_state.state)
+                    return false;
+            }
+            return true;
+        }
+        case 'timer_expired': {
+            if (event.type !== 'timer_expired')
+                return false;
+            return trigger.timerKey === event.timerKey;
+        }
+        case 'button': {
+            if (event.type !== 'button')
+                return false;
+            const entityMatch = typeof trigger.entity === 'string'
+                ? trigger.entity === event.entity_id
+                : trigger.entity.test(event.entity_id);
+            return (entityMatch &&
+                trigger.gesture === event.gesture &&
+                (trigger.button === undefined || trigger.button === event.button));
+        }
+        case 'schedule': {
+            if (event.type !== 'schedule')
+                return false;
+            return trigger.cron === event.cron;
+        }
+        case 'on_start':
+            return event.type === 'on_start';
+        case 'mqtt_in':
+            if (event.type !== 'mqtt_in')
+                return false;
+            return trigger.topic === event.topic;
+        default: {
+            const _exhaustive = trigger;
+            return false;
+        }
+    }
+}

package/dist/src/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.js

@@ -0,0 +1,157 @@
+import path from 'node:path';
+import { connect } from 'mqtt';
+import { loadConfig } from './framework/config.js';
+import { HAClient } from './framework/ha-client.js';
+import { AutomationRegistry } from './framework/registry.js';
+import { EventPublisher } from './framework/event-publisher.js';
+import { TimerManager } from './framework/timer-manager.js';
+import { ActionRuntime } from './framework/action-runtime.js';
+import { TriggerEngine } from './framework/trigger-engine.js';
+import { Scheduler } from './framework/scheduler.js';
+import { rescanAutomations, startHotReload } from './framework/hot-reload.js';
+import { runPipeline } from './framework/pipeline.js';
+import { ApiServer } from './framework/api-server.js';
+import { PromMetricsBackend } from './framework/metrics-prom.js';
+import { NoopMetricsBackend } from './framework/metrics.js';
+process.on('uncaughtException', (err) => {
+    console.error('[homerun] uncaughtException:', err);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error('[homerun] unhandledRejection:', reason);
+});
+// 0. Load and validate configuration before anything else.
+const config = await loadConfig();
+const { dry_run: dryRun } = config.options;
+const metricsBackend = config.metrics.enabled ? new PromMetricsBackend(true) : new NoopMetricsBackend();
+const lwtTopic = dryRun ? 'homerun/dev/status' : 'homerun/status';
+const lwtPayload = JSON.stringify({ status: 'offline', timestamp: new Date().toISOString() });
+// 1. Connect MQTT before anything else (EventPublisher and ActionRuntime need it).
+const mqtt = connect(config.mqtt.url, {
+    will: { topic: lwtTopic, payload: lwtPayload, qos: 1, retain: true },
+});
+await new Promise((resolve, reject) => {
+    mqtt.once('connect', () => resolve());
+    mqtt.once('error', reject);
+});
+// 2. Instantiate components in dependency order.
+//    TimerManager holds a closure over `engine` — the late binding is intentional;
+//    `engine` is assigned before any timer can fire.
+const haClient = new HAClient();
+const registry = new AutomationRegistry();
+const eventPublisher = new EventPublisher(mqtt, config.events.enabled);
+let engine;
+const timerManager = new TimerManager((e) => engine.dispatch(e));
+const actionRuntime = new ActionRuntime({
+    haClient,
+    mqttClient: mqtt,
+    timerManager,
+    eventPublisher,
+    dryRun,
+    metrics: metricsBackend,
+    commandAck: config.commandAck,
+});
+// 3. Initial automation load — must complete before the engine and scheduler start.
+const automationsDir = path.resolve(config.automations.dir);
+await rescanAutomations(automationsDir, registry);
+const initialCount = registry.getAll().length;
+metricsBackend.setGauge('homerun_automations_loaded', initialCount);
+console.log(`[homerun] loaded ${initialCount} automation(s)`);
+// 4. Wire up the engine and scheduler.
+//    Track in-flight pipelines so graceful shutdown can drain before exit.
+let shuttingDown = false;
+let inFlight = 0;
+let drainResolve = null;
+function dispatchPipeline(automation, event) {
+    if (shuttingDown)
+        return;
+    inFlight++;
+    runPipeline(automation, event, haClient, { eventPublisher, actionRuntime, dryRun, metrics: metricsBackend })
+        .catch((err) => { console.error('[homerun] pipeline error:', err); })
+        .finally(() => {
+        inFlight--;
+        if (inFlight === 0 && drainResolve) {
+            drainResolve();
+            drainResolve = null;
+        }
+    });
+}
+engine = new TriggerEngine(registry, haClient, dispatchPipeline, mqtt, metricsBackend);
+const scheduler = new Scheduler(registry.getAll(), (e) => engine.dispatch(e), haClient.ready);
+engine.start();
+scheduler.start();
+// 5. Start hot-reload watcher (dev) and SIGUSR1 rescan (git-sync sidecar in k8s).
+startHotReload(automationsDir, registry);
+async function reload() {
+    await rescanAutomations(automationsDir, registry);
+    scheduler.sync(registry.getAll());
+    const count = registry.getAll().length;
+    metricsBackend.setGauge('homerun_automations_loaded', count);
+    console.log(`[homerun] rescan complete — ${count} automation(s) registered`);
+    eventPublisher.publishLifecycle('rescan_complete', count, dryRun);
+}
+process.on('SIGUSR1', () => {
+    console.log('[homerun] SIGUSR1 received — rescanning automations');
+    reload().catch((err) => {
+        console.error('[homerun] rescan failed:', err);
+    });
+});
+// 6. Start the HTTP API server.
+let haReady = false;
+const apiServer = new ApiServer({
+    registry,
+    onTrigger: dispatchPipeline,
+    onReload: reload,
+    isReady: () => haReady,
+    entityCount: () => haClient.entityCount,
+    eventPublisher,
+    dryRun,
+    metrics: config.metrics.enabled ? metricsBackend : undefined,
+});
+await apiServer.start(config.server.port);
+// 7. Connect to HA last — state_changed events start flowing once ready resolves.
+haClient.on('reconnected', () => {
+    console.log(`[homerun] reconnected — ${haClient.entityCount} entities refreshed`);
+    eventPublisher.publishLifecycle('ha_reconnected', registry.getAll().length, dryRun);
+});
+await haClient.connect(config.homeassistant.url, config.homeassistant.token);
+await haClient.ready;
+haReady = true;
+const { labels, areas } = haClient.registryStats;
+console.log(`[homerun] ready — ${haClient.entityCount} entities cached (${labels} labels, ${areas} areas)`);
+eventPublisher.publishLifecycle('server_started', registry.getAll().length, dryRun);
+// 8. Graceful SIGTERM shutdown.
+process.on('SIGTERM', () => {
+    console.log('[homerun] SIGTERM received — starting graceful shutdown');
+    const { shutdown_timeout_ms: timeoutMs } = config.server;
+    shuttingDown = true;
+    const automationCount = registry.getAll().length;
+    eventPublisher.publishLifecycle('server_stopping', automationCount, dryRun);
+    const drain = () => {
+        if (inFlight === 0)
+            return Promise.resolve();
+        console.log(`[homerun] draining ${inFlight} in-flight pipeline(s)...`);
+        return new Promise((resolve) => {
+            drainResolve = resolve;
+            setTimeout(() => {
+                if (drainResolve) {
+                    console.warn(`[homerun] shutdown: drain timed out with ${inFlight} pipeline(s) still running`);
+                    drainResolve = null;
+                    resolve();
+                }
+            }, timeoutMs);
+        });
+    };
+    Promise.resolve()
+        .then(() => apiServer.stop())
+        .then(() => { scheduler.stop(); timerManager.cancelAll(); })
+        .then(drain)
+        .then(() => { haClient.disconnect(); return mqtt.endAsync(); })
+        .then(() => {
+        console.log('[homerun] shutdown complete');
+        process.exit(0);
+    })
+        .catch((err) => {
+        console.error('[homerun] shutdown error:', err);
+        process.exit(1);
+    });
+});

package/dist/src/lib.d.ts

@@ -0,0 +1,6 @@
+export { defineAutomation, abort, requireState, requireNumericState, UnavailableInputError } from './types/automation.js';
+export type { Automation, Decision, Abort, HAState, HAContext } from './types/automation.js';
+export type { Trigger, TriggerEvent } from './types/triggers.js';
+export type { Action } from './types/actions.js';
+export { HomeAssistant } from './services.js';
+export type { LightTurnOnData, HvacMode, ClimateSetTemperatureData, MediaPlayerPlayMediaData, MediaPlayerRepeat } from './services.js';

package/dist/src/lib.js

@@ -0,0 +1,2 @@
+export { defineAutomation, abort, requireState, requireNumericState, UnavailableInputError } from './types/automation.js';
+export { HomeAssistant } from './services.js';