@ajclarkson/homerun 0.0.1-edge.d1f2721 → 0.0.1-edge.db0717b

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

@@ -84,6 +84,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) {

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

@@ -3,5 +3,7 @@ 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

@@ -12,7 +12,10 @@ export async function _reloadFile(filePath, registry, importer = defaultImporter
             platform: 'node',
             format: 'esm',
             write: false,
-            alias: { '@ajclarkson/homerun': path.resolve(import.meta.dirname, '../lib.js') },
+            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')}`;
@@ -36,13 +39,49 @@ export async function _reloadFile(filePath, registry, importer = defaultImporter
         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`;
-    watch(target, { ignoreInitial: true, ignored: /node_modules/ }).on('change', (filePath) => {
+    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

@@ -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.d.ts

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

@@ -9,6 +9,7 @@ export async function runPipeline(automation, event, haClient, deps) {
         location: automation.location,
         subsystem: automation.subsystem,
         timestamp,
+        ...(deps.dryRun ? { dry_run: true } : {}),
     };
     // Step 2: Context
     let ctx;
@@ -16,11 +17,11 @@ export async function runPipeline(automation, event, haClient, deps) {
         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
@@ -29,14 +30,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/index.js

@@ -1,5 +1,4 @@
 import 'dotenv/config';
-import { readdir } from 'node:fs/promises';
 import path from 'node:path';
 import { connect } from 'mqtt';
 import { HAClient } from './framework/ha-client.js';
@@ -9,7 +8,7 @@ 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 { _reloadFile, startHotReload } from './framework/hot-reload.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) => {
@@ -18,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);
@@ -37,31 +41,15 @@ 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);
-const isAutomation = (f) => f.endsWith('.ts') &&
-    !f.includes('node_modules') &&
-    !f.includes('.d.ts') &&
-    !f.split(path.sep).includes('types');
-async function loadAutomations() {
-    let files = [];
-    try {
-        files = (await readdir(automationsDir, { recursive: true }));
-    }
-    catch {
-        console.warn(`[homerun] AUTOMATIONS_DIR not found: ${automationsDir} — starting with no automations`);
-    }
-    for (const file of files.filter(isAutomation)) {
-        await _reloadFile(path.join(automationsDir, file), registry);
-    }
-}
-await loadAutomations();
+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 }).catch((err) => {
+    runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
         console.error('[homerun] pipeline error:', err);
     });
 }, mqtt);
@@ -71,8 +59,10 @@ scheduler.start();
 // 5. Start hot-reload watcher (dev) and SIGUSR1 rescan (git-sync sidecar in K8s).
 startHotReload(automationsDir, registry);
 async function reload() {
-    await loadAutomations();
-    console.log(`[homerun] rescan complete — ${registry.getAll().length} automation(s) registered`);
+    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');
@@ -85,7 +75,7 @@ let haReady = false;
 const apiServer = new ApiServer({
     registry,
     onTrigger: (automation, event) => {
-        runPipeline(automation, event, haClient, { observability, actionRuntime }).catch((err) => {
+        runPipeline(automation, event, haClient, { observability, actionRuntime, dryRun }).catch((err) => {
             console.error('[homerun] pipeline error (http trigger):', err);
         });
     },
@@ -93,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/package.json

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