@ajclarkson/homerun 0.0.1-edge.f81eb62 → 0.0.1-edge.fcf7bc5

package/README.md

@@ -131,6 +131,7 @@ const ctx = kitchenLights.context(mockState, mockHAContext);
 | `on_start` | The system is ready and the state cache is fully populated. |
 | `timer_expired` | A named timer set by a previous `timer.start` action expires. |
 | `button` | A Zigbee button entity emits a `single_press`, `double_press`, or `hold` gesture. |
+| `mqtt_in` | A message arrives on a subscribed MQTT topic. |
 
 ```typescript
 triggers: [
@@ -192,7 +193,7 @@ Every pipeline run publishes a decision snapshot to MQTT — whether it complete
   "automation_id": "kitchen:lighting",
   "location": "kitchen",
   "subsystem": "lighting",
-  "type": "decision",
+  "event_type": "decision",
   "decision": "lights_on",
   "inputs": { "motion": true, "lux": 20, "luxThreshold": 40 },
   "actions": [{ "type": "ha.call_service", "domain": "light", "service": "turn_on" }],
@@ -230,6 +231,21 @@ Set `DRY_RUN=true` to run the full pipeline — context, reduce, observability
 
 ---
 
+## API
+
+The server exposes an HTTP API on port `7070` by default.
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/health/live` | Always returns `200 { status: "live" }` — used for liveness probes. |
+| `GET` | `/health/ready` | Returns `200` when the HA state cache is populated and automations are loaded, `503` while starting. Response includes `entities`, `automations` counts, and `dry_run: true` if running in dry-run mode. |
+| `GET` | `/automations` | Lists all registered automations with their `id`, `location`, `subsystem`, and trigger types. |
+| `POST` | `/automations/:id/trigger` | Manually fires an `on_start` event for the given automation. |
+| `POST` | `/reload` | Rescans the automations directory and hot-reloads changed files. |
+| `GET` | `/events` | Server-sent event stream of all pipeline decisions and action events in real time. |
+
+---
+
 ## Architecture
 
 ```

package/dist/src/framework/action-runtime.js

@@ -41,14 +41,14 @@ export class ActionRuntime {
             }
         }
     }
-    makeEvent(ctx, type, action, extra = {}) {
+    makeEvent(ctx, event_type, action, extra = {}) {
         return {
             schema: 'home.events.v1',
             correlation_id: ctx.correlationId,
             automation_id: ctx.automationId,
             location: ctx.location,
             subsystem: ctx.subsystem,
-            type,
+            event_type,
             actions: [action],
             timestamp: new Date().toISOString(),
             ...(this.deps.dryRun ? { dry_run: true } : {}),

package/dist/src/framework/api-server.d.ts

@@ -9,6 +9,7 @@ export interface ApiServerDeps {
     isReady: () => boolean;
     entityCount: () => number;
     observability: Observability;
+    dryRun?: boolean;
 }
 export declare class ApiServer {
     private readonly deps;

package/dist/src/framework/api-server.js

@@ -51,7 +51,8 @@ export class ApiServer {
             id: a.id,
             location: a.location,
             subsystem: a.subsystem,
-            triggerTypes: a.triggers.map((t) => t.type),
+            enabled: a.enabled ?? true,
+            triggers: a.triggers.map(serializeTrigger),
         }));
         json(res, 200, automations);
     }
@@ -84,6 +85,7 @@ export class ApiServer {
             status: 'ready',
             entities: this.deps.entityCount(),
             automations: this.deps.registry.getAll().length,
+            ...(this.deps.dryRun && { dry_run: true }),
         });
     }
     getEvents(req, res) {
@@ -99,6 +101,12 @@ export class ApiServer {
         req.on('close', unsubscribe);
     }
 }
+function serializeTrigger(trigger) {
+    if (trigger.type === 'state_changed' && trigger.entity instanceof RegExp) {
+        return { ...trigger, entity: trigger.entity.toString() };
+    }
+    return trigger;
+}
 function json(res, status, body) {
     const payload = JSON.stringify(body);
     res.writeHead(status, { 'Content-Type': 'application/json' });

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

@@ -45,11 +45,12 @@ export function _deleteFile(filePath, registry, fileToIds = moduleFileToIds) {
     }
     fileToIds.delete(filePath);
 }
+const EXCLUDED_DIRS = new Set(['types', 'lib']);
 const isAutomationFile = (f) => f.endsWith('.ts') &&
     !f.endsWith('.test.ts') &&
     !f.includes('node_modules') &&
     !f.includes('.d.ts') &&
-    !f.split(path.sep).includes('types');
+    !f.split(path.sep).some(seg => EXCLUDED_DIRS.has(seg));
 export async function rescanAutomations(automationsDir, registry, fileToIds = moduleFileToIds, importer = defaultImporter) {
     let files = [];
     try {

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

@@ -6,7 +6,7 @@ export interface ObsEvent {
     automation_id: string;
     location: string;
     subsystem: string;
-    type: 'decision' | 'abort' | 'action_started' | 'action_result';
+    event_type: 'decision' | 'abort' | 'action_started' | 'action_result';
     decision?: string;
     reason?: string;
     inputs?: Record<string, unknown>;
@@ -14,6 +14,14 @@ export interface ObsEvent {
     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;
@@ -21,5 +29,6 @@ export declare class Observability {
     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

@@ -26,6 +26,19 @@ export class Observability {
         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.js

@@ -11,17 +11,22 @@ export async function runPipeline(automation, event, haClient, deps) {
         timestamp,
         ...(deps.dryRun ? { dry_run: true } : {}),
     };
+    // Step 1: Enabled check
+    if (automation.enabled === false) {
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: 'disabled' });
+        return;
+    }
     // Step 2: Context
     let ctx;
     try {
         ctx = automation.context(haClient.state, haClient.context, event);
     }
     catch {
-        deps.observability.publishDecision({ ...base, type: 'abort', reason: 'unhandled_error' });
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
         return;
     }
     if (isAbort(ctx)) {
-        deps.observability.publishDecision({ ...base, type: 'abort', reason: ctx.reason });
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: ctx.reason });
         return;
     }
     // Step 3: Reduce
@@ -30,14 +35,14 @@ export async function runPipeline(automation, event, haClient, deps) {
         result = automation.reduce(ctx);
     }
     catch {
-        deps.observability.publishDecision({ ...base, type: 'abort', reason: 'unhandled_error' });
+        deps.observability.publishDecision({ ...base, event_type: 'abort', reason: 'unhandled_error' });
         return;
     }
     // Step 4: Validate — safe defaults
     const actions = result.actions ?? [];
     const decision = {
         ...base,
-        type: 'decision',
+        event_type: 'decision',
         decision: result.decision,
         reason: result.reason,
         inputs: result.inputs,

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

@@ -13,6 +13,7 @@ export declare class TriggerEngine {
     private readonly onMatch;
     private readonly mqttClient?;
     private readonly buttonHandlers;
+    private regexButtonTriggers;
     private readonly durationTimers;
     constructor(registry: AutomationRegistry, haClient: HAClient, onMatch: (automation: Automation<unknown>, event: TriggerEvent) => void, mqttClient?: MqttClient | undefined);
     private rebuildButtonHandlers;

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

@@ -1,49 +1,72 @@
-const DOUBLE_PRESS_WINDOW_MS = 400;
+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, correlationId) {
+        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, correlation_id: correlationId });
+            }
+            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 (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);
-                }
+            if (!this.supportsDoublePress) {
+                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'single_press', button, correlation_id: correlationId });
             }
             else {
-                this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'hold', button, correlation_id: correlationId });
+                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 {
-            // resolving — waiting for double press
+            // resolving — second short press = 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 });
-            }
+            this.dispatch({ type: 'button', entity_id: this.entityId, gesture: 'double_press', button, correlation_id: correlationId });
         }
     }
 }
@@ -57,7 +80,7 @@ export function parseButtonAction(state) {
     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') {
+    if (/short|click|single/.test(action) || action === 'on' || action === 'toggle' || action === 'release') {
         return { button, pressType: 'short' };
     }
     return null;
@@ -69,6 +92,7 @@ export class TriggerEngine {
     onMatch;
     mqttClient;
     buttonHandlers = new Map();
+    regexButtonTriggers = [];
     durationTimers = new Map();
     constructor(registry, haClient, onMatch, mqttClient) {
         this.registry = registry;
@@ -80,26 +104,50 @@ export class TriggerEngine {
     }
     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 (!entityGestures.has(trigger.entity)) {
-                        entityGestures.set(trigger.entity, new Set());
+                    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);
                     }
-                    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')));
         }
+        for (const [pattern, gestures] of regexGestures) {
+            this.regexButtonTriggers.push({ pattern, gestures });
+        }
     }
     start() {
         this.haClient.ready
             .then(() => {
             this.haClient.on('state_changed', (event) => {
-                const handler = this.buttonHandlers.get(event.entity_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, event.correlation_id);
                 }
@@ -200,7 +248,10 @@ function matchesTrigger(trigger, event) {
         case 'button': {
             if (event.type !== 'button')
                 return false;
-            return (trigger.entity === event.entity_id &&
+            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));
         }

package/dist/src/index.js

@@ -17,8 +17,13 @@ process.on('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);
+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);
@@ -36,7 +41,7 @@ const actionRuntime = new ActionRuntime({
     mqttClient: mqtt,
     timerManager,
     observability,
-    dryRun: process.env.DRY_RUN === 'true',
+    dryRun,
 });
 // 3. Initial automation load — must complete before the engine and scheduler start.
 const automationsDir = path.resolve(process.env.AUTOMATIONS_DIR);
@@ -44,7 +49,7 @@ 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: process.env.DRY_RUN === 'true' }).catch((err) => {
+    runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
         console.error('[homerun] pipeline error:', err);
     });
 }, mqtt);
@@ -55,7 +60,9 @@ scheduler.start();
 startHotReload(automationsDir, registry);
 async function reload() {
     await rescanAutomations(automationsDir, registry);
-    console.log(`[homerun] rescan complete — ${registry.getAll().length} automation(s) registered`);
+    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');
@@ -68,7 +75,7 @@ let haReady = false;
 const apiServer = new ApiServer({
     registry,
     onTrigger: (automation, event) => {
-        runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun: process.env.DRY_RUN === 'true' }).catch((err) => {
+        runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
             console.error('[homerun] pipeline error (http trigger):', err);
         });
     },
@@ -76,13 +83,16 @@ const apiServer = new ApiServer({
     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/testing.d.ts

@@ -4,6 +4,8 @@ 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;

package/dist/src/testing.js

@@ -9,8 +9,8 @@ export function testAutomation(automation, options) {
             entity_id: entityId,
             state: entry.state,
             attributes: entry.attributes ?? {},
-            last_changed: '',
-            last_updated: '',
+            last_changed: entry.last_changed ?? '',
+            last_updated: entry.last_updated ?? '',
         };
     };
     const haContext = {

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

@@ -18,6 +18,7 @@ export interface Automation<C> {
     id: string;
     location: string;
     subsystem: string;
+    enabled?: boolean;
     triggers: Trigger[];
     context: (state: HAState, ha: HAContext, event: TriggerEvent) => C | Abort;
     reduce: (ctx: C) => Decision;

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

@@ -13,7 +13,7 @@ export type Trigger = {
     timerKey: string;
 } | {
     type: 'button';
-    entity: string;
+    entity: string | RegExp;
     gesture: 'single_press' | 'double_press' | 'hold';
     button?: string;
 } | {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@ajclarkson/homerun",
   "type": "module",
-  "version": "0.0.1-edge.f81eb62",
+  "version": "0.0.1-edge.fcf7bc5",
   "description": "TypeScript automation framework for Home Assistant",
   "files": [
     "dist"