@ajclarkson/homerun 0.0.1-edge.01eba24

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

@@ -0,0 +1,223 @@
+const DOUBLE_PRESS_WINDOW_MS = 400;
+class ButtonGestureHandler {
+    entityId;
+    dispatch;
+    supportsDoublePress;
+    gestureState = 'idle';
+    resolveTimer = null;
+    constructor(entityId, dispatch, supportsDoublePress) {
+        this.entityId = entityId;
+        this.dispatch = dispatch;
+        this.supportsDoublePress = supportsDoublePress;
+    }
+    handle(actionState, correlationId) {
+        const parsed = parseButtonAction(actionState);
+        if (!parsed)
+            return;
+        const { button, pressType } = parsed;
+        if (this.gestureState === 'idle') {
+            if (pressType === 'short') {
+                if (!this.supportsDoublePress) {
+                    this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, correlation_id: correlationId });
+                }
+                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, correlation_id: correlationId });
+                    }, DOUBLE_PRESS_WINDOW_MS);
+                }
+            }
+            else {
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, correlation_id: correlationId });
+            }
+        }
+        else {
+            // resolving — waiting for double press
+            clearTimeout(this.resolveTimer);
+            this.resolveTimer = null;
+            this.gestureState = 'idle';
+            if (pressType === 'short') {
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'double_press', button, correlation_id: correlationId });
+            }
+            else {
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, correlation_id: correlationId });
+            }
+        }
+    }
+}
+// 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 === 'press' || action === 'on' || action === 'toggle') {
+        return { button, pressType: 'short' };
+    }
+    return null;
+}
+// ---------- Trigger Engine ----------
+export class TriggerEngine {
+    registry;
+    haClient;
+    onMatch;
+    mqttClient;
+    buttonHandlers = new Map();
+    durationTimers = new Map();
+    constructor(registry, haClient, onMatch, mqttClient) {
+        this.registry = registry;
+        this.haClient = haClient;
+        this.onMatch = onMatch;
+        this.mqttClient = mqttClient;
+        this.rebuildButtonHandlers();
+        registry.onChange(() => this.rebuildButtonHandlers());
+    }
+    rebuildButtonHandlers() {
+        this.buttonHandlers.clear();
+        const entityGestures = new Map();
+        for (const automation of this.registry.getAll()) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'button') {
+                    if (!entityGestures.has(trigger.entity)) {
+                        entityGestures.set(trigger.entity, new Set());
+                    }
+                    entityGestures.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')));
+        }
+    }
+    start() {
+        this.haClient.ready
+            .then(() => {
+            this.haClient.on('state_changed', (event) => {
+                const handler = this.buttonHandlers.get(event.entity_id);
+                if (handler) {
+                    handler.handle(event.new_state.state, event.correlation_id);
+                }
+                else {
+                    this.dispatch({
+                        type: 'state_changed',
+                        entity_id: event.entity_id,
+                        old_state: event.old_state,
+                        new_state: event.new_state,
+                        correlation_id: event.correlation_id,
+                    });
+                }
+            });
+        })
+            .catch((err) => {
+            console.error('[trigger-engine] failed to start:', err);
+        });
+        if (this.mqttClient) {
+            const topics = new Set();
+            for (const automation of this.registry.getAll()) {
+                for (const trigger of automation.triggers) {
+                    if (trigger.type === 'mqtt_in')
+                        topics.add(trigger.topic);
+                }
+            }
+            for (const topic of topics) {
+                this.mqttClient.subscribe(topic);
+            }
+            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;
+                    }
+                    this.onMatch(automation, { type: 'on_start', correlation_id: crypto.randomUUID() });
+                    return;
+                }
+                this.dispatch({
+                    type: 'mqtt_in',
+                    topic,
+                    payload: payload.toString(),
+                    correlation_id: `mqtt-${Date.now()}`,
+                });
+            });
+        }
+    }
+    // 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;
+            return typeof trigger.entity === 'string'
+                ? trigger.entity === event.entity_id
+                : trigger.entity.test(event.entity_id);
+        }
+        case 'timer_expired': {
+            if (event.type !== 'timer_expired')
+                return false;
+            return trigger.timerKey === event.timerKey;
+        }
+        case 'button': {
+            if (event.type !== 'button')
+                return false;
+            return (trigger.entity === event.entity_id &&
+                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 @@
+import 'dotenv/config';

package/dist/src/index.js

@@ -0,0 +1,98 @@
+import 'dotenv/config';
+import path from 'node:path';
+import { connect } from 'mqtt';
+import { HAClient } from './framework/ha-client.js';
+import { AutomationRegistry } from './framework/registry.js';
+import { Observability } from './framework/observability.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';
+process.on('uncaughtException', (err) => {
+    console.error('[homerun] uncaughtException:', err);
+});
+process.on('unhandledRejection', (reason) => {
+    console.error('[homerun] unhandledRejection:', reason);
+});
+const dryRun = process.env.DRY_RUN === 'true';
+const lwtTopic = dryRun ? 'homerun/dev/status' : 'homerun/status';
+const lwtPayload = JSON.stringify({ status: 'offline', timestamp: new Date().toISOString() });
+// 1. Connect MQTT before anything else (Observability and ActionRuntime need it).
+const mqtt = connect(process.env.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 observability = new Observability(mqtt);
+let engine;
+const timerManager = new TimerManager((e) => engine.dispatch(e));
+const actionRuntime = new ActionRuntime({
+    haClient,
+    mqttClient: mqtt,
+    timerManager,
+    observability,
+    dryRun,
+});
+// 3. Initial automation load — must complete before the engine and scheduler start.
+const automationsDir = path.resolve(process.env.AUTOMATIONS_DIR);
+await rescanAutomations(automationsDir, registry);
+console.log(`[homerun] loaded ${registry.getAll().length} automation(s)`);
+// 4. Wire up the engine and scheduler.
+engine = new TriggerEngine(registry, haClient, (automation, event) => {
+    runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
+        console.error('[homerun] pipeline error:', err);
+    });
+}, mqtt);
+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);
+    const count = registry.getAll().length;
+    console.log(`[homerun] rescan complete — ${count} automation(s) registered`);
+    observability.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: (automation, event) => {
+        runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
+            console.error('[homerun] pipeline error (http trigger):', err);
+        });
+    },
+    onReload: reload,
+    isReady: () => haReady,
+    entityCount: () => haClient.entityCount,
+    observability,
+    dryRun,
+});
+await apiServer.start(Number(process.env.API_PORT ?? 7070));
+// 7. Connect to HA last — state_changed events start flowing once ready resolves.
+haClient.on('reconnected', () => {
+    console.log(`[homerun] reconnected — ${haClient.entityCount} entities refreshed`);
+    observability.publishLifecycle('ha_reconnected', registry.getAll().length, dryRun);
+});
+await haClient.connect(process.env.HA_URL, process.env.HA_TOKEN);
+await haClient.ready;
+haReady = true;
+console.log(`[homerun] ready — ${haClient.entityCount} entities cached`);
+observability.publishLifecycle('server_started', registry.getAll().length, dryRun);

package/dist/src/lib.d.ts

@@ -0,0 +1,4 @@
+export { defineAutomation, abort } 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';

package/dist/src/lib.js

@@ -0,0 +1 @@
+export { defineAutomation, abort } from './types/automation.js';

package/dist/src/testing.d.ts

@@ -0,0 +1,16 @@
+import type { Automation, Decision, Abort } from './types/automation.js';
+import type { TriggerEvent } from './types/triggers.js';
+import type { HAContext } from './framework/ha-client.js';
+type TestStateEntry = {
+    state: string;
+    attributes?: Record<string, unknown>;
+    last_changed?: string;
+    last_updated?: string;
+};
+interface TestOptions {
+    event: TriggerEvent;
+    state?: Record<string, TestStateEntry>;
+    ha?: Partial<HAContext>;
+}
+export declare function testAutomation<C>(automation: Automation<C>, options: TestOptions): Decision | Abort;
+export {};

package/dist/src/testing.js

@@ -0,0 +1,25 @@
+import { isAbort } from './types/automation.js';
+export function testAutomation(automation, options) {
+    const { event, state = {}, ha = {} } = options;
+    const stateFunc = (entityId) => {
+        const entry = state[entityId];
+        if (!entry)
+            return undefined;
+        return {
+            entity_id: entityId,
+            state: entry.state,
+            attributes: entry.attributes ?? {},
+            last_changed: entry.last_changed ?? '',
+            last_updated: entry.last_updated ?? '',
+        };
+    };
+    const haContext = {
+        entitiesByLabel: ha.entitiesByLabel ?? (() => []),
+        labelsFor: ha.labelsFor ?? (() => []),
+        entitiesByArea: ha.entitiesByArea ?? (() => []),
+    };
+    const ctx = automation.context(stateFunc, haContext, event);
+    if (isAbort(ctx))
+        return ctx;
+    return automation.reduce(ctx);
+}

package/dist/src/types/actions.d.ts

@@ -0,0 +1,21 @@
+export type Action = {
+    type: 'ha.call_service';
+    domain: string;
+    service: string;
+    target?: {
+        entity_id: string;
+    };
+    data?: Record<string, unknown>;
+} | {
+    type: 'mqtt.publish';
+    topic: string;
+    payload: string;
+    retain?: boolean;
+} | {
+    type: 'timer.start';
+    timerKey: string;
+    delayMs: number;
+} | {
+    type: 'timer.cancel';
+    timerKey: string;
+};

package/dist/src/types/actions.js

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

package/dist/src/types/automation.d.ts

@@ -0,0 +1,25 @@
+import type { HAState, HAContext } from '../framework/ha-client.js';
+import type { Trigger, TriggerEvent } from './triggers.js';
+import type { Action } from './actions.js';
+export type { HAState, HAContext };
+export interface Decision {
+    decision: string;
+    reason?: string;
+    actions: Action[];
+    inputs?: Record<string, unknown>;
+}
+export type Abort = {
+    abort: true;
+    reason: string;
+};
+export declare const abort: (reason: string) => Abort;
+export declare function isAbort(value: unknown): value is Abort;
+export interface Automation<C> {
+    id: string;
+    location: string;
+    subsystem: string;
+    triggers: Trigger[];
+    context: (state: HAState, ha: HAContext, event: TriggerEvent) => C | Abort;
+    reduce: (ctx: C) => Decision;
+}
+export declare function defineAutomation<C>(automation: Automation<C>): Automation<C>;

package/dist/src/types/automation.js

@@ -0,0 +1,9 @@
+export const abort = (reason) => ({ abort: true, reason });
+export function isAbort(value) {
+    return typeof value === 'object' && value !== null && value.abort === true;
+}
+// Identity function — provides type inference on C so the reduce argument
+// is typed correctly without the user annotating the context shape explicitly.
+export function defineAutomation(automation) {
+    return automation;
+}

package/dist/src/types/triggers.d.ts

@@ -0,0 +1,50 @@
+import type { EntityState } from '../framework/ha-client.js';
+export type Trigger = {
+    type: 'state_changed';
+    entity: string | RegExp;
+    duration?: number;
+} | {
+    type: 'schedule';
+    cron: string;
+} | {
+    type: 'on_start';
+} | {
+    type: 'timer_expired';
+    timerKey: string;
+} | {
+    type: 'button';
+    entity: string;
+    gesture: 'single_press' | 'double_press' | 'hold';
+    button?: string;
+} | {
+    type: 'mqtt_in';
+    topic: string;
+};
+type TriggerEventBase = {
+    correlation_id: string;
+    parent_correlation_id?: string;
+};
+export type TriggerEvent = TriggerEventBase & ({
+    type: 'state_changed';
+    entity_id: string;
+    old_state: EntityState | undefined;
+    new_state: EntityState;
+} | {
+    type: 'schedule';
+    cron: string;
+} | {
+    type: 'on_start';
+} | {
+    type: 'timer_expired';
+    timerKey: string;
+} | {
+    type: 'button';
+    entity_id: string;
+    gesture: 'single_press' | 'double_press' | 'hold';
+    button?: string;
+} | {
+    type: 'mqtt_in';
+    topic: string;
+    payload: string;
+});
+export {};

package/dist/src/types/triggers.js

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

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@ajclarkson/homerun",
+  "type": "module",
+  "version": "0.0.1-edge.01eba24",
+  "description": "TypeScript automation framework for Home Assistant",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/src/lib.js",
+  "types": "./dist/src/lib.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/lib.d.ts",
+      "default": "./dist/src/lib.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing.d.ts",
+      "default": "./dist/src/testing.js"
+    }
+  },
+  "scripts": {
+    "dev": "tsx watch src/index.ts",
+    "build": "tsc",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "generate:ha-types": "tsx scripts/generate-ha-types.ts",
+    "generate:ha-types:compiled": "homerun-generate-ha-types"
+  },
+  "bin": {
+    "homerun": "./dist/src/index.js",
+    "homerun-generate-ha-types": "./dist/scripts/generate-ha-types.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ajclarkson/homerun"
+  },
+  "keywords": [],
+  "author": "Adam Clarkson",
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^5.0.0",
+    "dotenv": "^17.4.2",
+    "esbuild": "^0.28.1",
+    "home-assistant-js-websocket": "^9.6.0",
+    "mqtt": "^5.15.1",
+    "node-cron": "^4.4.1",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}