@khalido/home 0.0.0-stage → 0.1.0

package/src/energy.ts

@@ -0,0 +1,221 @@
+import type { AmberState, PriceInterval } from "./connectors/amber/client.ts";
+import type { EnphaseState } from "./connectors/enphase/client.ts";
+import type { EnphaseSnapshot } from "./connectors/enphase/index.ts";
+
+/** The home's energy right now: power from Enphase, prices from Amber, and what the grid flow costs per hour. */
+export type EnergyNow = {
+  solarW?: number;
+  solarPeakTodayW?: number; // the highest solarW read so far today (Enphase's day, since its peakSince)
+  usingW?: number;
+  gridW?: number; // positive importing, negative exporting
+  importCents?: number;
+  exportCents?: number; // what you are paid per kWh; below zero, exporting costs you
+  centsPerHour?: number; // positive costs you, negative earns you
+  renewables?: number;
+  priceDescriptor?: string; // Amber's descriptor for the import price ("extremelyLow" … "spike")
+  spike?: string; // Amber's spikeStatus: "none" | "potential" | "spike"
+  estimate?: boolean; // the current price can still move
+  negativePrice?: "paid to use" | "exporting at a loss";
+  flow?: "importing" | "exporting" | "balanced"; // undefined when gridW is; balanced within BALANCED_W, a display rule
+  surplusW?: number; // power going out to the grid, positive: -gridW when exporting, else 0
+  surplusCentsPerHour?: number; // what that export earns now at the export price (negative when exporting costs you)
+};
+
+/**
+ * Within this many watts either way the grid flow reads as "balanced": a display rule for the word and the animation,
+ * so a meter wobbling around zero does not flip between importing and exporting. `gridW` and `surplusW` stay as read.
+ */
+export const BALANCED_W = 20;
+
+/** The grid flow in a word, from the raw `gridW`. */
+function flowOf(gridW?: number): EnergyNow["flow"] {
+  if (gridW === undefined) return undefined;
+  return Math.abs(gridW) <= BALANCED_W
+    ? "balanced"
+    : gridW > 0
+      ? "importing"
+      : "exporting";
+}
+
+/**
+ * `"paid to use"` when the import price is below zero, else `"exporting at a loss"` when the export price is (Amber's
+ * feed-in `perKwh` above zero), else undefined. Both can hold in one interval; the import side wins.
+ */
+function negativePrice(prices?: AmberState): EnergyNow["negativePrice"] {
+  if (prices?.importCents !== undefined && prices.importCents < 0)
+    return "paid to use";
+  if (prices?.exportCents !== undefined && prices.exportCents < 0)
+    return "exporting at a loss";
+  return undefined;
+}
+
+/** One owner for the combined number, so every view (CLI, jaldi, the bot) shows the same thing. */
+export function energyNow(
+  power?: EnphaseState & Partial<Pick<EnphaseSnapshot, "productionWPeakToday">>,
+  prices?: AmberState,
+): EnergyNow {
+  const gridW = power?.netW;
+  const surplusW = gridW === undefined ? undefined : gridW < 0 ? -gridW : 0;
+  const rate =
+    gridW === undefined
+      ? undefined
+      : gridW >= 0
+        ? prices?.importCents
+        : prices?.exportCents;
+  return {
+    solarW: power?.productionW,
+    solarPeakTodayW: power?.productionWPeakToday,
+    usingW: power?.consumptionW,
+    gridW,
+    importCents: prices?.importCents,
+    exportCents: prices?.exportCents,
+    centsPerHour:
+      gridW === undefined || rate === undefined
+        ? undefined
+        : (gridW / 1000) * rate, // export: negative kW × earned c/kWh = negative cost
+    renewables: prices?.renewables,
+    priceDescriptor: prices?.priceDescriptor,
+    spike: prices?.spike,
+    estimate: prices?.estimate,
+    negativePrice: negativePrice(prices),
+    flow: flowOf(gridW),
+    surplusW,
+    surplusCentsPerHour:
+      surplusW === undefined || prices?.exportCents === undefined
+        ? undefined
+        : (surplusW / 1000) * prices.exportCents,
+  };
+}
+
+/**
+ * How brightly to draw the panels: `solarW` as a fraction of the array's rated `capacityW` when the config has it,
+ * else of today's peak so far, with which scale it is (they mean different things, so a drawing says which).
+ * Never clamped: above 1 is above the scale. Undefined when there is no solar reading or nothing to scale by.
+ */
+export function solarLevel(
+  now: EnergyNow,
+  capacityW?: number,
+): { fraction: number; scale: "capacity" | "today's peak" } | undefined {
+  if (now.solarW === undefined) return undefined;
+  if (capacityW !== undefined && capacityW > 0)
+    return { fraction: now.solarW / capacityW, scale: "capacity" };
+  if (now.solarPeakTodayW !== undefined && now.solarPeakTodayW > 0)
+    return {
+      fraction: now.solarW / now.solarPeakTodayW,
+      scale: "today's peak",
+    };
+  return undefined;
+}
+
+/**
+ * The grid flow in words every view shares: "exporting 1.2 kW, earning 42 c/h", "importing 0.8 kW, costing 33 c/h",
+ * "balanced (-10 W)", or "" with no grid reading. Rounded for reading only; the numbers above stay as read.
+ */
+export function gridText(now: EnergyNow): string {
+  const kw = (w: number) => `${(w / 1000).toFixed(1)} kW`;
+  const rate = (c: number | undefined, positive: string, negative: string) =>
+    c === undefined
+      ? ""
+      : `, ${c >= 0 ? positive : negative} ${Math.round(Math.abs(c))} c/h`;
+  if (now.flow === "exporting" && now.surplusW !== undefined)
+    return `exporting ${kw(now.surplusW)}${rate(now.surplusCentsPerHour, "earning", "costing")}`;
+  if (now.flow === "importing" && now.gridW !== undefined)
+    return `importing ${kw(now.gridW)}${rate(now.centsPerHour, "costing", "earning")}`;
+  return now.flow === "balanced" ? `balanced (${now.gridW} W)` : "";
+}
+
+/** A run of the forecast and its time-weighted averages: import price, feed-in price and the grid's renewable share. */
+export type PriceWindow = {
+  start: string;
+  end: string;
+  importCents?: number;
+  exportCents?: number;
+  renewables?: number;
+};
+
+const HOUR_MS = 3_600_000;
+
+/**
+ * The best `hours` to run something in, from Amber's forecast: the cheapest by import price (Amber's `perKwh`), or the
+ * greenest by the grid's renewable share. The window runs over unbroken intervals that each have the number it is judged by,
+ * starting no earlier than `from` (pass the clock's now; it defaults to the forecast's first interval, which began up to
+ * 5 minutes ago). Prices are flat within an interval, so the best window starts or ends on an interval's edge: both are
+ * tried. Averages weigh each interval by the time it covers; the earliest wins a tie. Undefined when nothing fits.
+ */
+export function bestWindow(
+  forecast: PriceInterval[] | undefined,
+  hours: number,
+  options: { by?: "price" | "renewables"; from?: number } = {},
+): PriceWindow | undefined {
+  if (!(hours > 0 && Number.isFinite(hours)))
+    throw new RangeError(`bestWindow: hours must be above 0, got ${hours}`);
+  const by = options.by ?? "price";
+  const rows = (forecast ?? []).map((r) => ({
+    ...r,
+    t0: Date.parse(r.start),
+    t1: Date.parse(r.end),
+  }));
+  const from = options.from ?? rows[0]?.t0 ?? 0;
+  const length = Math.round(hours * HOUR_MS); // whole ms, so the covered time adds up to it exactly
+  const starts = [
+    ...new Set(
+      rows
+        .flatMap((r) => [Math.max(r.t0, from), r.t1 - length])
+        .filter((t) => t >= from),
+    ),
+  ].sort((a, b) => a - b);
+  let best: PriceWindow | undefined;
+  let bestScore = Infinity;
+  for (const start of starts) {
+    const window = windowAt(rows, start, length, by);
+    const score =
+      window && (by === "price" ? window.importCents! : -window.renewables!);
+    if (window && score! < bestScore) ((best = window), (bestScore = score!));
+  }
+  return best;
+}
+
+/** The window of `length` ms from `start`, or undefined when an interval in it is missing, or lacks the number `by` needs. Any other average is left out unless every interval has it. */
+function windowAt(
+  rows: (PriceInterval & { t0: number; t1: number })[],
+  start: number,
+  length: number,
+  by: "price" | "renewables",
+): PriceWindow | undefined {
+  const end = start + length;
+  const sum = {
+    importCents: 0,
+    exportCents: 0,
+    renewables: 0,
+    importMs: 0,
+    exportMs: 0,
+    renewablesMs: 0,
+  };
+  let at = start;
+  for (const r of rows) {
+    if (r.t1 <= at) continue;
+    if (at >= end) break;
+    if (
+      r.t0 > at ||
+      (by === "price" ? r.importCents : r.renewables) === undefined
+    )
+      return undefined; // a gap, or no number to judge by
+    const ms = Math.min(r.t1, end) - at;
+    if (r.importCents !== undefined)
+      ((sum.importCents += r.importCents * ms), (sum.importMs += ms));
+    if (r.exportCents !== undefined)
+      ((sum.exportCents += r.exportCents * ms), (sum.exportMs += ms));
+    if (r.renewables !== undefined)
+      ((sum.renewables += r.renewables * ms), (sum.renewablesMs += ms));
+    at += ms;
+  }
+  if (at < end) return undefined;
+  return {
+    start: new Date(start).toISOString(),
+    end: new Date(end).toISOString(),
+    importCents: sum.importMs === length ? sum.importCents / length : undefined,
+    exportCents: sum.exportMs === length ? sum.exportCents / length : undefined,
+    renewables:
+      sum.renewablesMs === length ? sum.renewables / length : undefined,
+  };
+}

package/src/finders-entry.ts

@@ -0,0 +1,2 @@
+// `@khalido/home/finders`: what a Node consumer passes to `loadHome`. The rest of finders.ts is the CLI's.
+export { FINDERS, fileCache } from "./finders.ts";

package/src/finders.ts

@@ -0,0 +1,247 @@
+import { spawn } from "node:child_process";
+import {
+  chmodSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname } from "node:path";
+import { createSocket } from "node:dgram";
+import { lookup } from "node:dns/promises";
+import { printersFound } from "./connectors/printers/found.ts";
+import {
+  type AddressCache,
+  type CachedAddress,
+  type Connector,
+  type Finder,
+  type Found,
+  parseAvahi,
+  parseAvahiBrowse,
+  parseBrowse,
+  parseResolve,
+} from "./discover.ts";
+
+// Each connector's discovery on the network: mDNS through the system's own daemon (macOS `dns-sd`, Linux `avahi-browse`),
+// and Daikin's UDP broadcast. Node APIs (child_process, dgram, dns), so this file sits outside the runtime-neutral build like
+// weather/ftp.ts and cast/tls.ts; `home`, jaldi's sidecar and chota-bot import it from `@khalido/home/finders` and pass `FINDERS`
+// to `loadHome`. Runs in Bun and Node. The system daemon keeps an mDNS cache, so answers come from memory in milliseconds and
+// nothing here binds UDP 5353 beside it; a slow device (the Enphase gateway took 4 s to answer a fresh query; Bun 1.4.3, 2026-10-16)
+// does not slow a scan. Without the tool the mDNS finders throw, naming it, rather than "nothing answered".
+// `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
+
+/**
+ * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
+ * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in
+ * 4–13 ms (Bun 1.4.2, measured 2026-10-13), so the wait is for a cold cache only. A missing binary rejects, naming it.
+ * `command` is for tests.
+ */
+export function dnsSd(
+  argv: string[],
+  options: {
+    maxMs?: number;
+    quietMs?: number;
+    done?: (out: string) => boolean;
+    command?: string;
+    install?: string;
+  } = {},
+): Promise<string> {
+  const { maxMs = 1500, quietMs, done, command = "dns-sd", install } = options;
+  return new Promise((resolve, reject) => {
+    let out = "";
+    const proc = spawn(command, argv, { stdio: ["ignore", "pipe", "ignore"] });
+    const stop = () => proc.kill();
+    const timer = setTimeout(stop, maxMs);
+    let quiet: ReturnType<typeof setTimeout> | undefined;
+    proc.stdout.setEncoding("utf8").on("data", (d: string) => {
+      out += d;
+      if (done?.(out)) return stop();
+      if (quietMs !== undefined)
+        (clearTimeout(quiet), (quiet = setTimeout(stop, quietMs)));
+    });
+    const finish = () => (
+      clearTimeout(timer),
+      clearTimeout(quiet),
+      resolve(out)
+    );
+    proc.on("error", (error: NodeJS.ErrnoException) => {
+      (clearTimeout(timer), clearTimeout(quiet));
+      reject(
+        new Error(
+          error.code === "ENOENT"
+            ? `${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`
+            : `${command}: ${error.message}`,
+        ),
+      );
+    });
+    proc.on("close", finish);
+  });
+}
+
+/** Linux asks avahi-daemon, which Raspberry Pi OS runs by default; its command-line tool is a separate package. */
+const LINUX = process.platform === "linux";
+/** `avahi-browse` prints what avahi-daemon's cache holds, resolves it, and exits (`--terminate`); `maxMs` caps a slow resolve. */
+const avahi = (args: string[]) =>
+  dnsSd(["--parsable", "--terminate", ...args], {
+    command: "avahi-browse",
+    install: "apt install avahi-utils",
+    maxMs: 3000,
+  });
+
+/** Instance names of one mDNS service type: what has answered, once answers stop for 200 ms. */
+export const browse = async (type: string) =>
+  LINUX
+    ? parseAvahiBrowse(await avahi([type]))
+    : parseBrowse(await dnsSd(["-B", type], { quietMs: 200 }));
+
+/** A resolve is in once its TXT line (the line after "can be reached at") is complete. */
+const resolved = (out: string) =>
+  /can be reached at [^\n]*\n[^\n]*\n/.test(out);
+
+/** Every instance of one mDNS type, resolved to an IPv4 address (the config keeps addresses, not names), its port and its TXT record. */
+export async function mdnsResolve(type: string) {
+  if (LINUX) return parseAvahi(await avahi(["--resolve", type]));
+  const found = await Promise.all(
+    (await browse(type)).map(async (name) => {
+      const r = parseResolve(
+        await dnsSd(["-L", name, type], { done: resolved }),
+      );
+      const host = r
+        ? await lookup(r.hostname, { family: 4 }).then(
+            (x) => x.address,
+            () => undefined,
+          )
+        : undefined;
+      return r && host ? [{ ...r, host, instance: name }] : [];
+    }),
+  );
+  return found.flat();
+}
+
+/** Every device of one mDNS type with its identity from a TXT key, named by its mDNS instance. */
+const mdnsFind = async (
+  type: string,
+  txtKey: string,
+  connector: Connector,
+): Promise<Found[]> =>
+  (await mdnsResolve(type)).flatMap((r) =>
+    r.txt[txtKey]
+      ? [{ connector, id: r.txt[txtKey]!, host: r.host, name: r.instance }]
+      : [],
+  );
+
+/** Daikin's `key=value,key=value` answers, percent-decoded. */
+export const daikinFields = (text: string) =>
+  Object.fromEntries(
+    text
+      .trim()
+      .split(",")
+      .map((kv) => kv.split("="))
+      .map(([k, v = ""]) => [k, decoded(v)]),
+  );
+
+/** A percent-encoded value, or as sent when it is not valid encoding (a stray "%"): one odd field never fails the read. */
+function decoded(v: string): string {
+  try {
+    return decodeURIComponent(v);
+  } catch {
+    return v;
+  }
+}
+
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+export function findDaikins(
+  ms = 1500,
+): Promise<{ ip: string; fields: Record<string, string> }[]> {
+  return new Promise((resolve) => {
+    const found: { ip: string; fields: Record<string, string> }[] = [];
+    const sock = createSocket({ type: "udp4", reuseAddr: true });
+    sock.on("message", (msg, from) =>
+      found.push({ ip: from.address, fields: daikinFields(msg.toString()) }),
+    );
+    sock.on("error", () => (sock.close(), resolve(found)));
+    sock.bind(30000, () => {
+      sock.setBroadcast(true);
+      sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
+      setTimeout(() => (sock.close(), resolve(found)), ms);
+    });
+  });
+}
+
+/** A Daikin's broadcast answer as a found device, by its MAC. */
+export const daikinFound = (d: {
+  ip: string;
+  fields: Record<string, string>;
+}): Found[] =>
+  d.fields.mac
+    ? [
+        {
+          connector: "daikin",
+          id: d.fields.mac,
+          host: d.ip,
+          name: d.fields.name,
+        },
+      ]
+    : [];
+
+/** Each connector's discovery, as `loadHome` (rescans, and every Cast address) and `home discover` use it. */
+export const FINDERS: Record<Connector, Finder> = {
+  hue: () => mdnsFind("_hue._tcp", "bridgeid", "hue"),
+  enphase: () => mdnsFind("_enphase-envoy._tcp", "serialnum", "enphase"),
+  daikin: async () => (await findDaikins()).flatMap(daikinFound),
+  cast: async () =>
+    (await mdnsResolve("_googlecast._tcp")).flatMap(({ txt, host, port }) =>
+      txt.id
+        ? [
+            {
+              connector: "cast" as const,
+              id: txt.id,
+              host,
+              port,
+              name: txt.fn,
+              model: txt.md,
+              group: txt.md === "Google Cast Group",
+            },
+          ]
+        : [],
+    ),
+  printers: async () => {
+    const [ipp, ipps] = await Promise.all([
+      mdnsResolve("_ipp._tcp"),
+      mdnsResolve("_ipps._tcp"),
+    ]);
+    return printersFound(ipp, ipps);
+  },
+};
+
+/**
+ * An address cache in one JSON file, owner-only (0600, its folder 0700), replaced atomically on each write. A missing
+ * file is an empty cache; so is a file that does not parse, which the next write replaces (a cache, not KO's data).
+ */
+export function fileCache(path: string): AddressCache {
+  return {
+    read(): Record<string, CachedAddress> {
+      try {
+        const parsed = JSON.parse(readFileSync(path, "utf8")) as unknown;
+        return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+          ? (parsed as Record<string, CachedAddress>)
+          : {};
+      } catch {
+        return {};
+      }
+    },
+    write: (entries) =>
+      writePrivate(path, `${JSON.stringify(entries, null, 2)}\n`),
+  };
+}
+
+/** Write a file only its owner can read (0600, its folder 0700), replaced atomically: the address cache, the Enphase token. */
+export function writePrivate(path: string, text: string): void {
+  mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  const tmp = `${path}.tmp`;
+  rmSync(tmp, { force: true }); // so the mode applies to a fresh file
+  writeFileSync(tmp, text, { mode: 0o600 });
+  chmodSync(tmp, 0o600);
+  renameSync(tmp, path);
+}

package/src/health.ts

@@ -0,0 +1,74 @@
+import type { Part, Status } from "./home.ts";
+import { MANIFESTS } from "./manifests.ts";
+
+/**
+ * How one integration is doing, judged by time: `ok`, `stale` (no good read for a while, last values still shown) or `down`.
+ * The thresholds come with it, so a page can say "stale after 4 min". Push connectors (Hue, Cast) have no poll to be late
+ * for: never stale, down when not connected for `PUSH_DOWN_MS`.
+ */
+export type Health = {
+  level: "ok" | "stale" | "down";
+  status: Status;
+  lastGoodAt?: string;
+  downSince?: string;
+  staleAfterMs?: number;
+  downAfterMs: number;
+  detail?: string;
+};
+
+/** A polling connector is stale after this many polls with no good read: two missed, plus half of one so a slow read that ends in a timeout does not flap it, */
+export const STALE_POLLS = 2.5;
+/** and down after this many polls not connected. */
+export const DOWN_POLLS = 3;
+/** A push connector is down after this long not connected: a reconnect takes seconds, a backoff at most a minute. */
+export const PUSH_DOWN_MS = 120_000;
+
+const POLL_SECONDS: Record<string, number | undefined> = Object.fromEntries(
+  MANIFESTS.map((m) => [m.name, m.pollSeconds]),
+);
+
+/**
+ * Each integration's health at `now` (ms), from the times `createHome` stamps on its part. `pollSeconds` overrides a
+ * connector's own interval (its manifest's, so pass the weather's when the config changes it), or names one the library does not know.
+ */
+export function health(
+  snapshot: Record<string, Part | undefined>,
+  now: number,
+  options: { pollSeconds?: Record<string, number> } = {},
+): Record<string, Health> {
+  const poll = (name: string) =>
+    options.pollSeconds?.[name] ?? POLL_SECONDS[name];
+  return Object.fromEntries(
+    Object.entries(snapshot).flatMap(([name, part]) =>
+      part ? [[name, healthOf(part, now, poll(name))]] : [],
+    ),
+  );
+}
+
+function healthOf(
+  part: Part,
+  now: number,
+  pollSeconds: number | undefined,
+): Health {
+  const staleAfterMs =
+    pollSeconds === undefined ? undefined : STALE_POLLS * pollSeconds * 1000;
+  const downAfterMs =
+    pollSeconds === undefined ? PUSH_DOWN_MS : DOWN_POLLS * pollSeconds * 1000;
+  const age = (iso?: string) =>
+    iso === undefined ? undefined : now - Date.parse(iso);
+  const down =
+    part.status === "unavailable" ||
+    (part.status !== "connected" && (age(part.downSince) ?? 0) >= downAfterMs);
+  const goodAge = age(part.lastGoodAt) ?? age(part.downSince); // never good: as old as the wait for it
+  const stale = staleAfterMs !== undefined && (goodAge ?? 0) >= staleAfterMs;
+  const { status, lastGoodAt, downSince, detail } = part;
+  return {
+    level: down ? "down" : stale ? "stale" : "ok",
+    status,
+    lastGoodAt,
+    downSince,
+    staleAfterMs,
+    downAfterMs,
+    detail,
+  };
+}