@khalido/home 0.1.3 → 0.2.1

package/src/devices.ts

@@ -1,5 +1,6 @@
 import {
   type CastHomeDevice,
+  type CastSnapshot,
   castHomeDevices,
 } from "./connectors/cast/index.ts";
 import {
@@ -16,8 +17,11 @@ import {
   printersHomeDevices,
 } from "./connectors/printers/index.ts";
 import {
+  playingElsewhere,
   type SpotifyHomeDevice,
+  type SpotifyState,
   spotifyHomeDevices,
+  spotifyText,
 } from "./connectors/spotify/index.ts";
 import type { HomeConfig } from "./config.ts";
 import { IDENTITY, sameId } from "./discover.ts";
@@ -59,9 +63,17 @@ export function homeDevices(
   snapshot: Record<string, Part | undefined>,
   config?: Pick<HomeConfig, "devices" | "rooms">,
 ): HomeDevice[] {
-  const all = Object.entries(DEVICES).flatMap(([name, devices]): HomeDevice[] =>
-    devices(snapshot[name] as never),
-  );
+  // Soloist doesn't say where its music went; a Cast device playing that track does, so the speaker's line names it.
+  const on = spotifyElsewhere(snapshot);
+  const all = Object.entries(DEVICES)
+    .flatMap(([name, devices]): HomeDevice[] =>
+      devices(snapshot[name] as never),
+    )
+    .map((d) =>
+      d.connector === "spotify" && on.length
+        ? { ...d, text: spotifyText(d.detail, on) }
+        : d,
+    );
   if (!config) return all;
   const entries = config.devices ?? [];
   const hueRooms = new Map<string, string>(); // a Hue group's or light's id → the config room showing it
@@ -100,3 +112,71 @@ export function homeDevices(
     return { ...d, name, text, ...(room ? { room } : {}) };
   });
 }
+
+/**
+ * Where the account's Spotify is playing when the Soloist speaker says it is on another device: the names of the Cast
+ * devices and groups playing a track of that name in Spotify. A group is named, not its members. Empty when the music is
+ * on the speaker itself, nothing is playing, or it is on something Cast can't see (a phone, a laptop). Matched by the
+ * track's name, since neither side names the other.
+ */
+export function spotifyElsewhere(
+  snapshot: Record<string, Part | undefined>,
+): string[] {
+  const s = snapshot.spotify?.state as SpotifyState | undefined;
+  const cast = snapshot.cast?.state as CastSnapshot | undefined;
+  const name = s?.track?.name;
+  if (!playingElsewhere(s) || !name || !cast) return [];
+  return Object.values(cast.devices)
+    .filter(
+      (d) =>
+        d.status === "connected" &&
+        !d.playingVia && // its group's music: the group is named
+        d.app === "Spotify" &&
+        d.title === name &&
+        (d.playerState === "PLAYING" || d.playerState === "BUFFERING"),
+    )
+    .map((d) => d.name);
+}
+
+/** A room of the home config with the devices placed in it. `noData`: device connectors the config places here that listed nothing in it (never reached, not set up, or a `hueRoom` the bridge doesn't have), so the room isn't empty, it is unread. Per connector, not per device. */
+export type RoomDevices = {
+  id: string;
+  name: string;
+  floor?: string;
+  devices: HomeDevice[];
+  noData: string[];
+};
+
+/**
+ * `homeDevices` room by room, in the config's order, for a map of the home. A connector that is down but has read before
+ * still lists its devices, `available: false`; `noData` names one the config places in the room (a device's `room`, or
+ * `hueRoom`) that has nothing to list. `unplaced`: devices with no room, or one the config doesn't have.
+ */
+export function byRoom(
+  snapshot: Record<string, Part | undefined>,
+  config: Pick<HomeConfig, "devices" | "rooms">,
+): { rooms: RoomDevices[]; unplaced: HomeDevice[] } {
+  const all = homeDevices(snapshot, config);
+  const ids = new Set((config.rooms ?? []).map((r) => r.id));
+  return {
+    rooms: (config.rooms ?? []).map((r) => {
+      const devices = all.filter((d) => d.room === r.id);
+      const expected = new Set([
+        ...(config.devices ?? [])
+          .filter((d) => d.room === r.id)
+          .map((d) => d.connector),
+        ...(r.hueRoom === undefined ? [] : ["hue"]),
+      ]);
+      return {
+        id: r.id,
+        name: r.name,
+        ...(r.floor === undefined ? {} : { floor: r.floor }),
+        devices,
+        noData: [...expected].filter(
+          (c) => c in DEVICES && !devices.some((d) => d.connector === c),
+        ),
+      };
+    }),
+    unplaced: all.filter((d) => !d.room || !ids.has(d.room)),
+  };
+}

package/src/discover.ts

@@ -134,8 +134,7 @@ function newEntry(f: Found): Record<string, string | number> {
     host: f.host,
     [IDENTITY[f.connector]]: f.id,
   };
-  if (f.connector === "hue")
-    return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+  if (f.connector === "hue") return { ...base, key: "HUE_APPLICATION_KEY" };
   if (f.connector === "enphase")
     return { ...base, token: "~/.config/home/enphase-token.json" };
   return base;

package/src/finders-entry.ts

@@ -1,2 +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";
+export { FINDERS, fileCache, MissingTool } from "./finders.ts";

package/src/finders.ts

@@ -32,6 +32,7 @@ import {
 // `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
 
 /** The system's mDNS tool is not installed: discovery can't run until it is. */
+/** The discovery tool isn't installed (`dns-sd` on macOS, `avahi-browse` from avahi-utils on Linux): the message names it. */
 export class MissingTool extends Error {}
 
 /**
@@ -153,21 +154,32 @@ function decoded(v: string): string {
   }
 }
 
-/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050), three times across `ms`, and collect who answers, each unit once. */
 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("message", (msg, from) => {
+      if (!found.some((f) => f.ip === from.address))
+        found.push({ ip: from.address, fields: daikinFields(msg.toString()) });
+    });
+    const asks: ReturnType<typeof setTimeout>[] = [];
+    const done = () => (
+      asks.forEach(clearTimeout),
+      sock.close(),
+      resolve(found)
     );
-    sock.on("error", () => (sock.close(), resolve(found)));
+    sock.on("error", done);
     sock.bind(30000, () => {
       sock.setBroadcast(true);
-      sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
-      setTimeout(() => (sock.close(), resolve(found)), ms);
+      // UDP drops packets, more so while mDNS is busy beside it: one ask missed KO's unit in 2 runs of 3 (2026-11-11). Ask three times.
+      const ask = () =>
+        sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
+      ask();
+      asks.push(setTimeout(ask, ms / 3), setTimeout(ask, (2 * ms) / 3));
+      setTimeout(done, ms);
     });
   });
 }

package/src/home.ts

@@ -140,7 +140,7 @@ function stamped(part: Part, before: Part | undefined, now: string): Part {
 
 /**
  * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
- * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`. `add` and `remove` change the set while it runs.
  */
 export function createHome<I extends Integration<any, string>>(
   integrations: readonly I[],
@@ -148,14 +148,34 @@ export function createHome<I extends Integration<any, string>>(
   options: { clock?: Clock } = {},
 ) {
   type Name = I["name"];
+  type Run = { stop: AbortController; done: Promise<void> };
   const clock = options.clock ?? realClock;
+  const list: I[] = [...integrations]; // the integrations now: `add` and `remove` change it
+  const parts = () => snapshot as Record<string, Part>;
   let snapshot = Object.fromEntries(
-    integrations.map((i) => [i.name, { status: "connecting" }]),
+    list.map((i) => [i.name, { status: "connecting" }]),
   ) as HomeSnapshot<I>;
   const waiting = new Map<string, (() => void)[]>(); // refresh() callers, resolved by the integration's next report
-  const finished = new Set<string>(integrations.map((i) => i.name)); // not running, before start or after its run ended: a refresh of one resolves at once, nothing will report
-  const set = (name: Name, reported: Part) => {
-    const before = (snapshot as Record<string, Part>)[name]!;
+  const runs = new Map<I, Run>(); // the ones running: before start or after its run ended, a refresh resolves at once, nothing will report
+  const latest = new WeakMap<I, Run>(); // each integration's newest run: a report from an older run of the same object is dropped
+  let started: AbortSignal | undefined; // start()'s signal, while it runs
+  let changing: Promise<unknown> = Promise.resolve(); // add and remove, one at a time: two on one name must not overlap
+  let changes = 0; // those under way or queued: start outlasts a replace of its only integration
+  const change = <T>(fn: () => Promise<T>): Promise<T> => {
+    changes++;
+    const done = changing.then(fn).finally(() => changes--);
+    changing = done.catch(() => {});
+    return done;
+  };
+  const heard = (name: string) => {
+    for (const resolve of waiting.get(name) ?? []) resolve();
+    waiting.delete(name);
+  };
+  // A report counts only from the integration now listed under its name: one replaced or removed may still be finishing.
+  const set = (i: I, run: Run, reported: Part) => {
+    const name: Name = i.name;
+    const before = parts()[name];
+    if (latest.get(i) !== run || !list.includes(i) || !before) return;
     const part = stamped(reported, before, asOf(clock));
     snapshot = { ...snapshot, [name]: part };
     Promise.try(() =>
@@ -163,11 +183,45 @@ export function createHome<I extends Integration<any, string>>(
     ).catch((error) =>
       console.error(`onChange threw on ${name}: ${errorText(error)}`),
     ); // the caller's bug, thrown or async, not the device's: the integration keeps running
-    const w = waiting.get(name);
-    if (w) {
-      waiting.delete(name);
-      for (const resolve of w) resolve();
-    }
+    heard(name);
+  };
+  /** Run one integration until the home's signal or its own `stop` aborts. One failing marks itself unavailable. */
+  const launch = (i: I, signal: AbortSignal) => {
+    const stop = new AbortController();
+    const run: Run = { stop, done: Promise.resolve() };
+    runs.set(i, run);
+    latest.set(i, run);
+    run.done = Promise.try(() =>
+      i.run(AbortSignal.any([signal, stop.signal]), (part) =>
+        set(i, run, part),
+      ),
+    )
+      .catch((error) =>
+        set(i, run, {
+          status: "unavailable",
+          reason: "crashed",
+          detail: errorText(error),
+          state: parts()[i.name]?.state, // the last good state stays, as it does through a failed read
+        }),
+      )
+      .finally(() => {
+        if (runs.get(i) !== run) return;
+        runs.delete(i);
+        if (list.includes(i)) heard(i.name); // nothing more will report
+      });
+  };
+  /** Take one out of the list and the snapshot, and wait for its run to end. */
+  const drop = async (name: string) => {
+    const at = list.findIndex((i) => i.name === name);
+    if (at < 0) return false;
+    const [old] = list.splice(at, 1);
+    const { [name]: _, ...rest } = parts();
+    snapshot = rest as HomeSnapshot<I>;
+    heard(name);
+    const run = runs.get(old!);
+    run?.stop.abort();
+    await run?.done;
+    return true;
   };
   return {
     /** The latest snapshot. Never touches a device. */
@@ -178,61 +232,67 @@ export function createHome<I extends Integration<any, string>>(
     integration: <N extends Name>(
       name: N,
     ): Extract<I, { name: N }> | undefined =>
-      integrations.find((i) => i.name === name) as
-        Extract<I, { name: N }> | undefined,
+      list.find((i) => i.name === name) as Extract<I, { name: N }> | undefined,
     /**
      * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
      * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
      */
     refresh(name?: Name): Promise<void> {
       const targets =
-        name === undefined
-          ? integrations
-          : integrations.filter((i) => i.name === name);
-      if (!targets.length)
+        name === undefined ? [...list] : list.filter((i) => i.name === name);
+      if (!targets.length && name !== undefined)
         throw new Error(
-          `no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`,
+          `no integration "${name}"; have ${list.map((i) => i.name).join(", ")}`,
         );
       const reported = targets.map(
         (i) =>
           new Promise<void>((resolve) => {
-            if (finished.has(i.name)) return resolve();
+            if (!runs.has(i)) return resolve();
             waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
           }),
       );
       for (const i of targets) i.refresh();
       return Promise.all(reported).then(() => undefined);
     },
-    /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+    /**
+     * Add an integration while the home runs, or before it starts: a bridge paired just now, a key that arrived late. One
+     * already there under that name is stopped first and its part dropped, so the new one starts from `connecting` and
+     * the two never run together. Resolves once the new one is running; its reports arrive as any other's. Calls on
+     * one home run one at a time. Once `start`'s signal has aborted, an added one waits for the next `start`.
+     */
+    add: (integration: I): Promise<void> =>
+      change(async () => {
+        await drop(integration.name);
+        list.push(integration);
+        const live = started && !started.aborted ? started : undefined;
+        snapshot = {
+          ...snapshot,
+          [integration.name]: {
+            status: "connecting",
+            ...(live ? { downSince: asOf(clock) } : {}),
+          },
+        };
+        if (live) launch(integration, live);
+      }),
+    /** Stop one integration and drop its part from the snapshot. Resolves once its run has ended; false if there was none by that name. */
+    remove: (name: Name): Promise<boolean> => change(() => drop(name)),
+    /** Run every integration, and any added meanwhile, until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
     async start(signal: AbortSignal): Promise<void> {
-      finished.clear(); // a second start, after the first has stopped, runs them all again
+      started = signal;
       const now = asOf(clock); // the wait for a first report counts from here, not from createHome
       snapshot = Object.fromEntries(
-        Object.entries(snapshot as Record<string, Part>).map(([name, p]) => [
+        Object.entries(parts()).map(([name, p]) => [
           name,
           p.status === "connecting"
             ? { ...p, downSince: p.downSince ?? now }
             : p,
         ]),
       ) as HomeSnapshot<I>;
-      await Promise.all(
-        integrations.map((i) =>
-          Promise.try(() => i.run(signal, (part) => set(i.name, part)))
-            .catch((error) =>
-              set(i.name, {
-                status: "unavailable",
-                reason: "crashed",
-                detail: errorText(error),
-                state: (snapshot as Record<string, Part>)[i.name]!.state, // the last good state stays, as it does through a failed read
-              }),
-            )
-            .finally(() => {
-              finished.add(i.name);
-              for (const resolve of waiting.get(i.name) ?? []) resolve(); // nothing more will report
-              waiting.delete(i.name);
-            }),
-        ),
-      );
+      for (const i of list) launch(i, signal); // a second start, after the first has stopped, runs them all again
+      // Until every run has ended, those added meanwhile too.
+      while (runs.size || changes)
+        await Promise.all([...[...runs.values()].map((r) => r.done), changing]);
+      // `started` stays: one added after every run has ended still runs, until the signal aborts.
     },
   };
 }

package/src/index.ts

@@ -22,7 +22,13 @@ export {
   PUSH_DOWN_MS,
   STALE_POLLS,
 } from "./health.ts";
-export { type HomeDevice, homeDevices } from "./devices.ts";
+export {
+  byRoom,
+  type HomeDevice,
+  homeDevices,
+  type RoomDevices,
+  spotifyElsewhere,
+} from "./devices.ts";
 export { asOf, type Clock, realClock } from "./clock.ts";
 export { type ConnectorCode, ConnectorError } from "./connector.ts";
 export {

package/src/node-fetch.ts

@@ -1,5 +1,6 @@
 import { Agent, fetch as undiciFetch } from "undici";
 import type { LoadOptions } from "./config.ts";
+import { HUE_BRIDGE_ROOT_CA } from "./connectors/hue/ca.ts";
 
 // `@khalido/home/node`: the fetches Hue and Enphase need under Node, where Bun's `tls` fetch option does not exist. Node's
 // global `fetch` takes no CA, so these use undici's own `fetch` and `Agent` (one undici on both sides). Outside the
@@ -13,8 +14,11 @@ const through = (dispatcher: Agent) =>
       { ...init, dispatcher } as never,
     )) as unknown as typeof fetch;
 
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export function nodePinnedFetch(bridgeId: string, ca: string): typeof fetch {
+/** A `fetch` that trusts only `ca` (Signify's roots when left out) and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
+export function nodePinnedFetch(
+  bridgeId: string,
+  ca: string = HUE_BRIDGE_ROOT_CA,
+): typeof fetch {
   const checkServerIdentity = (
     _host: string,
     cert: { subject?: { CN?: string | string[] } },