@ajclarkson/homerun 0.0.1-edge.01eba24

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Adam Clarkson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,276 @@
+# Homerun
+
+**Typed, testable Home Assistant automations in TypeScript.**
+
+> **Status: early development.** The framework is not yet published to npm and the API is not stable. This README documents the intended design; some parts are still being built.
+
+Homerun is a framework that replaces HA automations and Node-RED flows with pure functions. Every automation is a context builder and a reducer — no side effects, no hidden state, no YAML. The pipeline handles observability, error isolation, and action execution.
+
+---
+
+## The problem
+
+Home Assistant automations are YAML. Node-RED flows are JSON blobs. Both are hard to test, hard to review, and impossible to type-check. A bad deploy silently breaks your lights at 2am.
+
+Homerun brings the same discipline you'd apply to application code: pure functions, typed inputs, and a test suite that runs in milliseconds.
+
+---
+
+## How it works
+
+Every automation follows the same pipeline:
+
+```
+Event → context() → reduce() → actions[]
+```
+
+**`context()`** reads from the HA state cache and returns a typed snapshot — or aborts early if the guard condition isn't met. It is the only place that touches external state.
+
+**`reduce()`** is a pure function. It receives the context and returns a decision with a list of declarative actions. No async, no side effects, no HA calls.
+
+**The pipeline** handles everything else: correlation IDs, observability snapshots, error isolation, and action execution.
+
+---
+
+## Example
+
+```typescript
+import { defineAutomation, abort } from './src/types/automation.js';
+
+export const kitchenLights = defineAutomation({
+  id: 'kitchen:lighting',
+  location: 'kitchen',
+  subsystem: 'lighting',
+
+  triggers: [
+    { type: 'state_changed', entity: 'binary_sensor.kitchen_motion' },
+    { type: 'state_changed', entity: 'binary_sensor.kitchen_door' },
+    { type: 'on_start' },
+  ],
+
+  context(state, ha) {
+    const enabled = state('input_boolean.kitchen_automation_lights_enabled');
+    if (enabled?.state !== 'on') return abort('automation_disabled');
+
+    return {
+      motion: state('binary_sensor.kitchen_motion')?.state === 'on',
+      lux: Number(state('sensor.kitchen_sensor_lux')?.state ?? 0),
+      luxThreshold: Number(state('input_number.kitchen_automation_lux_threshold_dark')?.state ?? 40),
+    };
+  },
+
+  reduce(ctx) {
+    const shouldLight = ctx.motion && ctx.lux < ctx.luxThreshold;
+
+    return {
+      decision: shouldLight ? 'lights_on' : 'lights_off',
+      inputs: ctx,
+      actions: [
+        {
+          type: 'ha.call_service',
+          domain: 'light',
+          service: shouldLight ? 'turn_on' : 'turn_off',
+          target: { entity_id: 'light.kitchen_light_ceiling' },
+        },
+      ],
+    };
+  },
+});
+```
+
+---
+
+## Testing
+
+Because `reduce()` is a pure function, tests are just function calls:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import { kitchenLights } from './kitchen-lights';
+
+describe('kitchenLights reducer', () => {
+  it('turns lights on when motion is detected below lux threshold', () => {
+    const result = kitchenLights.reduce({ motion: true, lux: 20, luxThreshold: 40 });
+    expect(result.decision).toBe('lights_on');
+    expect(result.actions[0]).toMatchObject({ service: 'turn_on' });
+  });
+
+  it('turns lights off when lux is already high', () => {
+    const result = kitchenLights.reduce({ motion: true, lux: 80, luxThreshold: 40 });
+    expect(result.decision).toBe('lights_off');
+  });
+
+  it('turns lights off when motion clears', () => {
+    const result = kitchenLights.reduce({ motion: false, lux: 10, luxThreshold: 40 });
+    expect(result.decision).toBe('lights_off');
+  });
+});
+```
+
+No mocking, no HA connection, no async. The context builder can be tested separately with a plain function as the state accessor:
+
+```typescript
+const mockState = (entity: string) => ({
+  'input_boolean.kitchen_automation_lights_enabled': { state: 'on' },
+  'binary_sensor.kitchen_motion': { state: 'on' },
+  'sensor.kitchen_sensor_lux': { state: '20' },
+  'input_number.kitchen_automation_lux_threshold_dark': { state: '40' },
+})[entity] as any;
+
+const ctx = kitchenLights.context(mockState, mockHAContext);
+```
+
+---
+
+## Trigger types
+
+| Trigger | Fires when |
+|---------|-----------|
+| `state_changed` | An entity's state or attributes change. Accepts a string or `RegExp` for the entity ID. |
+| `schedule` | A cron expression fires. |
+| `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: [
+  { type: 'state_changed', entity: 'binary_sensor.parlour_motion' },
+  { type: 'state_changed', entity: /^binary_sensor\..+_motion$/ },
+  { type: 'schedule', cron: '0 22 * * *' },
+  { type: 'on_start' },
+  { type: 'timer_expired', timerKey: 'kitchen:lights:off-delay' },
+  { type: 'button', entity: 'sensor.hallway_button', gesture: 'double_press' },
+]
+```
+
+---
+
+## Action types
+
+Actions are returned from `reduce()` as a plain array. The runtime executes them after the observability snapshot is published.
+
+| Action | Effect |
+|--------|--------|
+| `ha.call_service` | Calls a Home Assistant service |
+| `mqtt.publish` | Publishes to an MQTT topic |
+| `timer.start` | Starts (or restarts) a named timer |
+| `timer.cancel` | Cancels a named timer |
+
+```typescript
+actions: [
+  {
+    type: 'ha.call_service',
+    domain: 'climate',
+    service: 'set_temperature',
+    target: { entity_id: 'climate.bedroom_trv' },
+    data: { temperature: 20 },
+  },
+  {
+    type: 'timer.start',
+    timerKey: 'kitchen:lights:off-delay',
+    delayMs: 120_000,
+  },
+  {
+    type: 'mqtt.publish',
+    topic: 'homerun/decisions/kitchen',
+    payload: JSON.stringify({ decision: 'lights_on' }),
+    retain: false,
+  },
+]
+```
+
+---
+
+## Observability
+
+Every pipeline run publishes a decision snapshot to MQTT — whether it completed, aborted, or threw. Each snapshot carries a `correlation_id` minted at the event source, so you can trace a HA state change through to the TRV setpoint that resulted from it.
+
+```json
+{
+  "schema": "home.events.v1",
+  "correlation_id": "b3d2f1a0-...",
+  "automation_id": "kitchen:lighting",
+  "location": "kitchen",
+  "subsystem": "lighting",
+  "event_type": "decision",
+  "decision": "lights_on",
+  "inputs": { "motion": true, "lux": 20, "luxThreshold": 40 },
+  "actions": [{ "type": "ha.call_service", "domain": "light", "service": "turn_on" }],
+  "timestamp": "2026-06-23T18:00:00.000Z"
+}
+```
+
+---
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `HA_URL` | Home Assistant base URL (e.g. `http://homeassistant.local:8123`) |
+| `HA_TOKEN` | Long-lived access token |
+| `MQTT_URL` | MQTT broker URL (e.g. `mqtt://localhost:1883`) |
+| `AUTOMATIONS_DIR` | Directory of automation files (hot-reloaded on change) |
+| `DRY_RUN` | Set to `true` to log actions without executing them |
+
+---
+
+## Running
+
+> Homerun is not yet published to npm. Clone the repository and run directly from source.
+
+```bash
+# Development — hot-reloads automations on file change
+npm run dev
+
+# Run tests
+npm test
+```
+
+Set `DRY_RUN=true` to run the full pipeline — context, reduce, observability — without making any HA service calls. This is the default for local development.
+
+---
+
+## 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
+
+```
+HAClient ──────────────────────────────────────┐
+  └─ state_changed (per entity, with corr. ID) │
+                                               ▼
+Scheduler (cron / on_start) ──────► TriggerEngine.dispatch()
+TimerManager (setTimeout)  ──────►        │
+                                          ▼
+                                   matchAndFire()
+                                          │
+                              ┌───────────▼──────────┐
+                              │    Pipeline Runner    │
+                              │  context → reduce     │
+                              │  → validate → fanout  │
+                              └──────────┬────────────┘
+                                         │
+                          ┌──────────────┴──────────────┐
+                          ▼                             ▼
+                   Observability                  ActionRuntime
+                 (MQTT snapshot)         (HA calls / timers / MQTT)
+```
+
+---
+
+## License
+
+MIT

package/dist/scripts/generate-ha-types.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export interface HAStatePayload {
+    entity_id: string;
+    state: string;
+    attributes: Record<string, unknown>;
+}
+export declare function inferStateType(entity: HAStatePayload, allObservedStates?: string[]): string;
+export declare function generateFileContent(states: HAStatePayload[]): string;

package/dist/scripts/generate-ha-types.js

@@ -0,0 +1,81 @@
+#!/usr/bin/env node
+import { writeFile, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+// ---------- Inference ----------
+export function inferStateType(entity, allObservedStates) {
+    const domain = entity.entity_id.split('.')[0];
+    switch (domain) {
+        case 'binary_sensor':
+        case 'input_boolean':
+        case 'switch':
+            return "'on' | 'off'";
+        case 'input_select': {
+            const options = entity.attributes.options;
+            if (Array.isArray(options) && options.length > 0) {
+                return options.map((o) => `'${o}'`).join(' | ');
+            }
+            return 'string';
+        }
+        case 'person': {
+            const states = allObservedStates ?? [entity.state];
+            return [...new Set(states)].map((s) => `'${s}'`).join(' | ');
+        }
+        default:
+            return 'string';
+    }
+}
+// ---------- File generation ----------
+export function generateFileContent(states) {
+    const personStates = new Map();
+    for (const s of states) {
+        if (s.entity_id.startsWith('person.')) {
+            const existing = personStates.get(s.entity_id) ?? [];
+            existing.push(s.state);
+            personStates.set(s.entity_id, existing);
+        }
+    }
+    const entries = states
+        .map((s) => {
+        const stateType = inferStateType(s, personStates.get(s.entity_id));
+        return `  '${s.entity_id}': { state: ${stateType} };`;
+    })
+        .join('\n');
+    return `// generated — do not edit — run: npm run generate:ha-types
+export interface HAEntities {
+${entries}
+}
+
+export type HAState = {
+  <E extends keyof HAEntities>(entity: E): HAEntities[E]['state'];
+  <E extends string>(entity: E): string | undefined;
+};
+`;
+}
+// ---------- CLI ----------
+async function main() {
+    const url = process.env.HA_URL;
+    const token = process.env.HA_TOKEN;
+    if (!url || !token) {
+        console.error('Error: HA_URL and HA_TOKEN must be set');
+        process.exit(1);
+    }
+    const res = await fetch(`${url}/api/states`, {
+        headers: { Authorization: `Bearer ${token}` },
+    });
+    if (!res.ok) {
+        console.error(`Error: HA API returned ${res.status} ${res.statusText}`);
+        process.exit(1);
+    }
+    const states = (await res.json());
+    const content = generateFileContent(states);
+    const outPath = path.join(process.cwd(), 'types', 'ha-entities.ts');
+    await mkdir(path.dirname(outPath), { recursive: true });
+    await writeFile(outPath, content, 'utf8');
+    console.log(`Written ${states.length} entities to ${outPath}`);
+}
+if (process.argv[1]?.endsWith('generate-ha-types.ts') || process.argv[1]?.endsWith('generate-ha-types.js') || process.argv[1]?.endsWith('homerun-generate-ha-types')) {
+    main().catch((err) => {
+        console.error('Fatal:', err);
+        process.exit(1);
+    });
+}

package/dist/src/framework/action-runtime.d.ts

@@ -0,0 +1,27 @@
+import type { MqttClient } from 'mqtt';
+import type { Action } from '../types/actions.js';
+import type { HAClient } from './ha-client.js';
+import type { TimerManager } from './timer-manager.js';
+import type { Observability } from './observability.js';
+export interface ExecutionContext {
+    correlationId: string;
+    automationId: string;
+    location: string;
+    subsystem: string;
+}
+interface Deps {
+    haClient: HAClient;
+    mqttClient: MqttClient;
+    timerManager: TimerManager;
+    observability: Observability;
+    dryRun: boolean;
+}
+export declare class ActionRuntime {
+    private readonly deps;
+    constructor(deps: Deps);
+    execute(actions: Action[], ctx: ExecutionContext): Promise<void>;
+    private runAction;
+    private dispatch;
+    private makeEvent;
+}
+export {};

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

@@ -0,0 +1,58 @@
+export class ActionRuntime {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(actions, ctx) {
+        for (const action of actions) {
+            await this.runAction(action, ctx);
+        }
+    }
+    async runAction(action, ctx) {
+        this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_started', action));
+        try {
+            if (!this.deps.dryRun) {
+                await this.dispatch(action);
+            }
+            this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason: 'ok' }));
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            this.deps.observability.publishActionEvent(this.makeEvent(ctx, 'action_result', action, { reason }));
+        }
+    }
+    async dispatch(action) {
+        switch (action.type) {
+            case 'ha.call_service':
+                await this.deps.haClient.callService(action.domain, action.service, action.target, action.data);
+                break;
+            case 'mqtt.publish':
+                await this.deps.mqttClient.publishAsync(action.topic, action.payload, { retain: action.retain ?? false });
+                break;
+            case 'timer.start':
+                this.deps.timerManager.start(action.timerKey, action.delayMs);
+                break;
+            case 'timer.cancel':
+                this.deps.timerManager.cancel(action.timerKey);
+                break;
+            default: {
+                const unknown = action.type;
+                throw new Error(`unknown action type: ${unknown}`);
+            }
+        }
+    }
+    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,
+            event_type,
+            actions: [action],
+            timestamp: new Date().toISOString(),
+            ...(this.deps.dryRun ? { dry_run: true } : {}),
+            ...extra,
+        };
+    }
+}

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

@@ -0,0 +1,29 @@
+import type { AutomationRegistry } from './registry.js';
+import type { Observability } from './observability.js';
+import type { Automation } from '../types/automation.js';
+import type { TriggerEvent } from '../types/triggers.js';
+export interface ApiServerDeps {
+    registry: AutomationRegistry;
+    onTrigger: (automation: Automation<unknown>, event: TriggerEvent) => void;
+    onReload: () => Promise<void>;
+    isReady: () => boolean;
+    entityCount: () => number;
+    observability: Observability;
+    dryRun?: boolean;
+}
+export declare class ApiServer {
+    private readonly deps;
+    private server;
+    private _port;
+    constructor(deps: ApiServerDeps);
+    get port(): number | null;
+    start(port?: number): Promise<void>;
+    stop(): Promise<void>;
+    private handle;
+    private getAutomations;
+    private postTrigger;
+    private postReload;
+    private getHealthLive;
+    private getHealthReady;
+    private getEvents;
+}

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

@@ -0,0 +1,107 @@
+import { createServer } from 'node:http';
+export class ApiServer {
+    deps;
+    server = null;
+    _port = null;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    get port() {
+        return this._port;
+    }
+    start(port = 7070) {
+        return new Promise((resolve, reject) => {
+            this.server = createServer((req, res) => this.handle(req, res));
+            this.server.listen(port, '0.0.0.0', () => {
+                const addr = this.server.address();
+                this._port = typeof addr === 'object' && addr ? addr.port : port;
+                console.log(`[homerun] API server listening on port ${this._port}`);
+                resolve();
+            });
+            this.server.once('error', reject);
+        });
+    }
+    stop() {
+        return new Promise((resolve, reject) => {
+            if (!this.server)
+                return resolve();
+            this.server.close((err) => (err ? reject(err) : resolve()));
+        });
+    }
+    handle(req, res) {
+        const method = req.method ?? 'GET';
+        const url = req.url ?? '/';
+        if (method === 'GET' && url === '/automations')
+            return this.getAutomations(res);
+        if (method === 'POST' && url === '/reload')
+            return this.postReload(res);
+        if (method === 'GET' && url === '/health/live')
+            return this.getHealthLive(res);
+        if (method === 'GET' && url === '/health/ready')
+            return this.getHealthReady(res);
+        if (method === 'GET' && url === '/events')
+            return this.getEvents(req, res);
+        const triggerMatch = method === 'POST' && url.match(/^\/automations\/(.+)\/trigger$/);
+        if (triggerMatch)
+            return this.postTrigger(triggerMatch[1], res);
+        json(res, 404, { error: 'not found' });
+    }
+    getAutomations(res) {
+        const automations = this.deps.registry.getAll().map((a) => ({
+            id: a.id,
+            location: a.location,
+            subsystem: a.subsystem,
+            triggerTypes: a.triggers.map((t) => t.type),
+        }));
+        json(res, 200, automations);
+    }
+    postTrigger(id, res) {
+        const automation = this.deps.registry.getById(id);
+        if (!automation) {
+            json(res, 404, { error: `no automation with id "${id}"` });
+            return;
+        }
+        this.deps.onTrigger(automation, { type: 'on_start', correlation_id: crypto.randomUUID() });
+        json(res, 200, { ok: true });
+    }
+    postReload(res) {
+        this.deps.onReload()
+            .then(() => json(res, 200, { ok: true }))
+            .catch((err) => {
+            console.error('[ApiServer] reload failed:', err);
+            json(res, 500, { error: 'reload failed' });
+        });
+    }
+    getHealthLive(res) {
+        json(res, 200, { status: 'live' });
+    }
+    getHealthReady(res) {
+        if (!this.deps.isReady()) {
+            json(res, 503, { status: 'starting' });
+            return;
+        }
+        json(res, 200, {
+            status: 'ready',
+            entities: this.deps.entityCount(),
+            automations: this.deps.registry.getAll().length,
+            ...(this.deps.dryRun && { dry_run: true }),
+        });
+    }
+    getEvents(req, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive',
+        });
+        res.flushHeaders();
+        const unsubscribe = this.deps.observability.subscribe((event) => {
+            res.write(`data: ${JSON.stringify(event)}\n\n`);
+        });
+        req.on('close', unsubscribe);
+    }
+}
+function json(res, status, body) {
+    const payload = JSON.stringify(body);
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(payload);
+}

package/dist/src/framework/ha-client.d.ts

@@ -0,0 +1,47 @@
+import { type HassServiceTarget } from 'home-assistant-js-websocket';
+import { EventEmitter } from 'node:events';
+export interface EntityState {
+    entity_id: string;
+    state: string;
+    attributes: Record<string, unknown>;
+    last_changed: string;
+    last_updated: string;
+}
+export type HAState = (entity: string) => EntityState | undefined;
+export interface HAContext {
+    entitiesByLabel: (label: string) => string[];
+    labelsFor: (entity: string) => string[];
+    entitiesByArea: (area: string) => string[];
+}
+export interface StateChangedEvent {
+    entity_id: string;
+    old_state: EntityState | undefined;
+    new_state: EntityState;
+    correlation_id: string;
+}
+export declare interface HAClient {
+    on(event: 'state_changed', listener: (e: StateChangedEvent) => void): this;
+    on(event: 'ready', listener: () => void): this;
+    on(event: 'reconnected', listener: () => void): this;
+    emit(event: 'state_changed', e: StateChangedEvent): boolean;
+    emit(event: 'ready'): boolean;
+    emit(event: 'reconnected'): boolean;
+}
+export declare class HAClient extends EventEmitter {
+    private readonly stateCache;
+    private readonly labelToEntities;
+    private readonly entityToLabels;
+    private readonly areaToEntities;
+    private connection;
+    private reconnecting;
+    private _readyResolve;
+    readonly ready: Promise<void>;
+    readonly state: HAState;
+    readonly context: HAContext;
+    get entityCount(): number;
+    callService(domain: string, service: string, target?: HassServiceTarget, data?: Record<string, unknown>): Promise<void>;
+    connect(url: string, token: string): Promise<void>;
+    private repopulateCache;
+    private diffAndUpdate;
+    private loadEntityRegistry;
+}