@ajclarkson/homerun 0.0.1-edge.01eba24

package/dist/src/framework/ha-client.js

@@ -0,0 +1,125 @@
+import { callService, createConnection, createLongLivedTokenAuth, subscribeEntities, } from 'home-assistant-js-websocket';
+import { EventEmitter } from 'node:events';
+export class HAClient extends EventEmitter {
+    stateCache = new Map();
+    labelToEntities = new Map();
+    entityToLabels = new Map();
+    areaToEntities = new Map();
+    connection = null;
+    // True between a disconnect event and the next subscribeEntities callback.
+    // During this window we repopulate silently — no state_changed events emitted.
+    reconnecting = false;
+    _readyResolve;
+    ready = new Promise((resolve) => {
+        this._readyResolve = resolve;
+    });
+    // Synchronous accessors passed into context builders.
+    state = (entity) => this.stateCache.get(entity);
+    context = {
+        entitiesByLabel: (label) => Array.from(this.labelToEntities.get(label) ?? []),
+        labelsFor: (entity) => this.entityToLabels.get(entity) ?? [],
+        entitiesByArea: (area) => Array.from(this.areaToEntities.get(area) ?? []),
+    };
+    get entityCount() {
+        return this.stateCache.size;
+    }
+    async callService(domain, service, target, data) {
+        if (!this.connection)
+            throw new Error('HAClient not connected');
+        await callService(this.connection, domain, service, data, target);
+    }
+    async connect(url, token) {
+        const auth = createLongLivedTokenAuth(url, token);
+        this.connection = await createConnection({ auth });
+        // Reload registry and repopulate cache silently on reconnect.
+        this.connection.addEventListener('disconnected', () => {
+            this.reconnecting = true;
+        });
+        await this.loadEntityRegistry();
+        let firstSnapshot = true;
+        subscribeEntities(this.connection, (entities) => {
+            if (firstSnapshot) {
+                firstSnapshot = false;
+                this.repopulateCache(entities);
+                this._readyResolve();
+                this.emit('ready');
+            }
+            else if (this.reconnecting) {
+                this.reconnecting = false;
+                // Reload registry in the background — don't block the cache repopulate.
+                this.loadEntityRegistry().catch((err) => {
+                    console.error('[ha-client] registry reload failed after reconnect:', err);
+                });
+                this.repopulateCache(entities);
+                this.emit('reconnected');
+            }
+            else {
+                this.diffAndUpdate(entities);
+            }
+        });
+    }
+    // ---------- Private ----------
+    repopulateCache(entities) {
+        this.stateCache.clear();
+        for (const [id, entity] of Object.entries(entities)) {
+            this.stateCache.set(id, toEntityState(id, entity));
+        }
+    }
+    diffAndUpdate(entities) {
+        for (const [id, rawEntity] of Object.entries(entities)) {
+            const old_state = this.stateCache.get(id);
+            const new_state = toEntityState(id, rawEntity);
+            // last_updated changes whenever state or attributes change in HA.
+            if (!old_state || old_state.last_updated !== new_state.last_updated) {
+                this.stateCache.set(id, new_state);
+                this.emit('state_changed', { entity_id: id, old_state, new_state, correlation_id: crypto.randomUUID() });
+            }
+        }
+        // Prune entities that disappeared from the snapshot.
+        for (const id of this.stateCache.keys()) {
+            if (!(id in entities)) {
+                this.stateCache.delete(id);
+            }
+        }
+    }
+    async loadEntityRegistry() {
+        if (!this.connection)
+            return;
+        const entries = (await this.connection.sendMessagePromise({
+            type: 'config/entity_registry/list',
+        }));
+        this.labelToEntities.clear();
+        this.entityToLabels.clear();
+        this.areaToEntities.clear();
+        for (const entry of entries) {
+            const labels = entry.labels ?? [];
+            this.entityToLabels.set(entry.entity_id, labels);
+            for (const label of labels) {
+                let set = this.labelToEntities.get(label);
+                if (!set) {
+                    set = new Set();
+                    this.labelToEntities.set(label, set);
+                }
+                set.add(entry.entity_id);
+            }
+            if (entry.area_id) {
+                let set = this.areaToEntities.get(entry.area_id);
+                if (!set) {
+                    set = new Set();
+                    this.areaToEntities.set(entry.area_id, set);
+                }
+                set.add(entry.entity_id);
+            }
+        }
+    }
+}
+// ---------- Helpers ----------
+function toEntityState(entity_id, entity) {
+    return {
+        entity_id,
+        state: entity.state,
+        attributes: entity.attributes,
+        last_changed: entity.last_changed,
+        last_updated: entity.last_updated,
+    };
+}

package/dist/src/framework/hot-reload.d.ts

@@ -0,0 +1,9 @@
+import type { AutomationRegistry } from './registry.js';
+type Importer = (dataUri: string) => Promise<{
+    default: unknown;
+}>;
+export declare function _reloadFile(filePath: string, registry: AutomationRegistry, importer?: Importer, fileToIds?: Map<string, string[]>): Promise<void>;
+export declare function _deleteFile(filePath: string, registry: AutomationRegistry, fileToIds?: Map<string, string[]>): void;
+export declare function rescanAutomations(automationsDir: string, registry: AutomationRegistry, fileToIds?: Map<string, string[]>, importer?: Importer): Promise<void>;
+export declare function startHotReload(automationsDir: string, registry: AutomationRegistry): void;
+export {};

package/dist/src/framework/hot-reload.js

@@ -0,0 +1,87 @@
+import path from 'node:path';
+import { watch } from 'chokidar';
+import { build } from 'esbuild';
+const defaultImporter = (dataUri) => import(dataUri);
+// Module-level file→IDs map used in production. Tests pass their own instance.
+const moduleFileToIds = new Map();
+export async function _reloadFile(filePath, registry, importer = defaultImporter, fileToIds = moduleFileToIds) {
+    try {
+        const result = await build({
+            entryPoints: [filePath],
+            bundle: true,
+            platform: 'node',
+            format: 'esm',
+            write: false,
+            alias: {
+                '@ajclarkson/homerun/testing': path.resolve(import.meta.dirname, '../testing.js'),
+                '@ajclarkson/homerun': path.resolve(import.meta.dirname, '../lib.js'),
+            },
+        });
+        const code = result.outputFiles[0].text;
+        const dataUri = `data:text/javascript;base64,${Buffer.from(code).toString('base64')}`;
+        const mod = await importer(dataUri);
+        if (!mod.default) {
+            throw new Error(`${filePath} has no default export`);
+        }
+        const automations = Array.isArray(mod.default)
+            ? mod.default
+            : [mod.default];
+        // Deregister previous automations from this file only after successful load.
+        for (const id of fileToIds.get(filePath) ?? []) {
+            registry.unregister(id);
+        }
+        for (const auto of automations) {
+            registry.register(auto);
+        }
+        fileToIds.set(filePath, automations.map((a) => a.id));
+    }
+    catch (err) {
+        console.error(`[hot-reload] failed to reload ${filePath}:`, err);
+    }
+}
+export function _deleteFile(filePath, registry, fileToIds = moduleFileToIds) {
+    for (const id of fileToIds.get(filePath) ?? []) {
+        registry.unregister(id);
+    }
+    fileToIds.delete(filePath);
+}
+const isAutomationFile = (f) => f.endsWith('.ts') &&
+    !f.endsWith('.test.ts') &&
+    !f.includes('node_modules') &&
+    !f.includes('.d.ts') &&
+    !f.split(path.sep).includes('types');
+export async function rescanAutomations(automationsDir, registry, fileToIds = moduleFileToIds, importer = defaultImporter) {
+    let files = [];
+    try {
+        const { readdir } = await import('node:fs/promises');
+        files = (await readdir(automationsDir, { recursive: true }));
+    }
+    catch {
+        console.warn(`[homerun] AUTOMATIONS_DIR not found: ${automationsDir} — starting with no automations`);
+    }
+    const currentPaths = new Set(files.filter(isAutomationFile).map((f) => path.join(automationsDir, f)));
+    for (const trackedPath of [...fileToIds.keys()]) {
+        if (!currentPaths.has(trackedPath)) {
+            _deleteFile(trackedPath, registry, fileToIds);
+        }
+    }
+    for (const filePath of currentPaths) {
+        await _reloadFile(filePath, registry, importer, fileToIds);
+    }
+}
+export function startHotReload(automationsDir, registry) {
+    const target = process.env.AUTOMATION
+        ? path.join(automationsDir, `${process.env.AUTOMATION}.ts`)
+        : `${automationsDir}/**/*.ts`;
+    const watcher = watch(target, { ignoreInitial: true, ignored: [/node_modules/, /\.test\.ts$/] });
+    const reload = (filePath) => {
+        _reloadFile(filePath, registry).catch((err) => {
+            console.error('[hot-reload] unexpected error:', err);
+        });
+    };
+    watcher.on('add', reload);
+    watcher.on('change', reload);
+    watcher.on('unlink', (filePath) => {
+        _deleteFile(filePath, registry);
+    });
+}

package/dist/src/framework/observability.d.ts

@@ -0,0 +1,34 @@
+import type { MqttClient } from 'mqtt';
+import type { Action } from '../types/actions.js';
+export interface ObsEvent {
+    schema: 'home.events.v1';
+    correlation_id: string;
+    automation_id: string;
+    location: string;
+    subsystem: string;
+    event_type: 'decision' | 'abort' | 'action_started' | 'action_result';
+    decision?: string;
+    reason?: string;
+    inputs?: Record<string, unknown>;
+    actions?: Action[];
+    dry_run?: boolean;
+    timestamp: string;
+}
+export type LifecycleEventType = 'server_started' | 'rescan_complete' | 'ha_reconnected';
+export interface LifecycleEvent {
+    schema: 'home.lifecycle.v1';
+    type: LifecycleEventType;
+    automation_count: number;
+    timestamp: string;
+    dry_run?: boolean;
+}
+export declare class Observability {
+    private readonly mqtt;
+    private readonly listeners;
+    constructor(mqtt: MqttClient);
+    subscribe(listener: (event: ObsEvent) => void): () => void;
+    publishDecision(event: ObsEvent): void;
+    publishActionEvent(event: ObsEvent): void;
+    publishLifecycle(type: LifecycleEventType, automationCount: number, dryRun?: boolean): void;
+    private publish;
+}

package/dist/src/framework/observability.js

@@ -0,0 +1,47 @@
+export class Observability {
+    mqtt;
+    listeners = [];
+    constructor(mqtt) {
+        this.mqtt = mqtt;
+    }
+    subscribe(listener) {
+        this.listeners.push(listener);
+        return () => {
+            const idx = this.listeners.indexOf(listener);
+            if (idx !== -1)
+                this.listeners.splice(idx, 1);
+        };
+    }
+    publishDecision(event) {
+        const payload = JSON.stringify(event);
+        const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+        this.publish(`${ns}/events`, payload, false);
+        this.publish(`${ns}/${event.location}/${event.subsystem}/decision`, payload, true);
+        for (const l of this.listeners)
+            l(event);
+    }
+    publishActionEvent(event) {
+        const ns = event.dry_run ? 'homerun/dev' : 'homerun';
+        this.publish(`${ns}/events`, JSON.stringify(event), false);
+        for (const l of this.listeners)
+            l(event);
+    }
+    publishLifecycle(type, automationCount, dryRun = false) {
+        const event = {
+            schema: 'home.lifecycle.v1',
+            type,
+            automation_count: automationCount,
+            timestamp: new Date().toISOString(),
+            ...(dryRun && { dry_run: true }),
+        };
+        const ns = dryRun ? 'homerun/dev' : 'homerun';
+        const payload = JSON.stringify(event);
+        this.publish(`${ns}/lifecycle`, payload, false);
+        this.publish(`${ns}/status`, JSON.stringify({ status: 'online', automation_count: automationCount, timestamp: event.timestamp }), true);
+    }
+    publish(topic, payload, retain) {
+        this.mqtt.publishAsync(topic, payload, { retain }).catch((err) => {
+            console.error(`[Observability] MQTT publish failed on ${topic}:`, err);
+        });
+    }
+}

package/dist/src/framework/pipeline.d.ts

@@ -0,0 +1,12 @@
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+import type { HAClient } from './ha-client.js';
+import type { Observability } from './observability.js';
+import type { ActionRuntime } from './action-runtime.js';
+interface Deps {
+    observability: Observability;
+    actionRuntime: ActionRuntime;
+    dryRun?: boolean;
+}
+export declare function runPipeline(automation: Automation<unknown>, event: TriggerEvent, haClient: HAClient, deps: Deps): Promise<void>;
+export {};

package/dist/src/framework/pipeline.js

@@ -0,0 +1,56 @@
+import { isAbort } from '../types/automation.js';
+export async function runPipeline(automation, event, haClient, deps) {
+    const correlationId = event.correlation_id;
+    const timestamp = new Date().toISOString();
+    const base = {
+        schema: 'home.events.v1',
+        correlation_id: correlationId,
+        automation_id: automation.id,
+        location: automation.location,
+        subsystem: automation.subsystem,
+        timestamp,
+        ...(deps.dryRun ? { dry_run: true } : {}),
+    };
+    // Step 2: Context
+    let ctx;
+    try {
+        ctx = automation.context(haClient.state, haClient.context, event);
+    }
+    catch {
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
+        return;
+    }
+    if (isAbort(ctx)) {
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: ctx.reason });
+        return;
+    }
+    // Step 3: Reduce
+    let result;
+    try {
+        result = automation.reduce(ctx);
+    }
+    catch {
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
+        return;
+    }
+    // Step 4: Validate — safe defaults
+    const actions = result.actions ?? [];
+    const decision = {
+        ...base,
+        event_type: 'decision',
+        decision: result.decision,
+        reason: result.reason,
+        inputs: result.inputs,
+        actions,
+    };
+    // Step 5: Fanout
+    await Promise.all([
+        Promise.resolve(deps.observability.publishDecision(decision)),
+        deps.actionRuntime.execute(actions, {
+            correlationId,
+            automationId: automation.id,
+            location: automation.location,
+            subsystem: automation.subsystem,
+        }),
+    ]);
+}

package/dist/src/framework/registry.d.ts

@@ -0,0 +1,10 @@
+import type { Automation } from '../types/automation.js';
+export declare class AutomationRegistry {
+    private readonly automations;
+    private readonly changeCallbacks;
+    onChange(cb: () => void): void;
+    register(automation: Automation<unknown>): void;
+    unregister(id: string): void;
+    getAll(): Automation<unknown>[];
+    getById(id: string): Automation<unknown> | undefined;
+}

package/dist/src/framework/registry.js

@@ -0,0 +1,21 @@
+export class AutomationRegistry {
+    automations = new Map();
+    changeCallbacks = [];
+    onChange(cb) {
+        this.changeCallbacks.push(cb);
+    }
+    register(automation) {
+        this.automations.set(automation.id, automation);
+        for (const cb of this.changeCallbacks)
+            cb();
+    }
+    unregister(id) {
+        this.automations.delete(id);
+    }
+    getAll() {
+        return Array.from(this.automations.values());
+    }
+    getById(id) {
+        return this.automations.get(id);
+    }
+}

package/dist/src/framework/scheduler.d.ts

@@ -0,0 +1,11 @@
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+export declare class Scheduler {
+    private readonly automations;
+    private readonly dispatch;
+    private readonly ready;
+    private readonly cleanups;
+    constructor(automations: Automation<unknown>[], dispatch: (event: TriggerEvent) => void, ready: Promise<void>);
+    start(): void;
+    stop(): void;
+}

package/dist/src/framework/scheduler.js

@@ -0,0 +1,35 @@
+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() {
+        for (const automation of this.automations) {
+            for (const trigger of automation.triggers) {
+                if (trigger.type === 'schedule') {
+                    const { cron: expression } = trigger;
+                    const task = cron.schedule(expression, () => {
+                        this.dispatch({ type: 'schedule', cron: expression, correlation_id: crypto.randomUUID() });
+                    });
+                    this.cleanups.push(() => task.stop());
+                }
+            }
+        }
+        this.ready.then(() => {
+            this.dispatch({ type: 'on_start', correlation_id: crypto.randomUUID() });
+        }).catch((err) => {
+            console.error('[scheduler] ready promise rejected:', err);
+        });
+    }
+    stop() {
+        for (const cleanup of this.cleanups)
+            cleanup();
+        this.cleanups.length = 0;
+    }
+}

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

@@ -0,0 +1,8 @@
+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;
+}

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

@@ -0,0 +1,22 @@
+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);
+            this.dispatch({ type: 'timer_expired', timerKey, correlation_id: crypto.randomUUID() });
+        }, delayMs);
+        this.timers.set(timerKey, handle);
+    }
+    cancel(timerKey) {
+        const handle = this.timers.get(timerKey);
+        if (handle !== undefined) {
+            clearTimeout(handle);
+            this.timers.delete(timerKey);
+        }
+    }
+}

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

@@ -0,0 +1,22 @@
+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';
+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 buttonHandlers;
+    private readonly durationTimers;
+    constructor(registry: AutomationRegistry, haClient: HAClient, onMatch: (automation: Automation<unknown>, event: TriggerEvent) => void, mqttClient?: MqttClient | undefined);
+    private rebuildButtonHandlers;
+    start(): void;
+    dispatch(event: TriggerEvent): void;
+    private matchAndFire;
+}