@khalido/home 0.1.2 → 0.2.0

package/dist/devices.js

@@ -0,0 +1,115 @@
+import { castHomeDevices, } from "./connectors/cast/index.js";
+import { daikinHomeDevices, } from "./connectors/daikin/index.js";
+import { enphaseHomeDevices, } from "./connectors/enphase/index.js";
+import { hueHomeDevices } from "./connectors/hue/index.js";
+import { printersHomeDevices, } from "./connectors/printers/index.js";
+import { playingElsewhere, spotifyHomeDevices, spotifyText, } from "./connectors/spotify/index.js";
+import { IDENTITY, sameId } from "./discover.js";
+import { manifestOf } from "./manifests.js";
+/** Each connector's devices from its part, in the order `home status` lists the connectors. */
+export const DEVICES = {
+    hue: hueHomeDevices,
+    daikin: daikinHomeDevices,
+    enphase: enphaseHomeDevices,
+    cast: castHomeDevices,
+    printers: printersHomeDevices,
+    spotify: spotifyHomeDevices,
+};
+/** Connectors that read a service, not a device: nothing to list. */
+export const SERVICES = ["amber", "up", "weather"];
+/**
+ * Every device in the snapshot. With the home `config`, a device takes the `room` its entry gives it, a Hue room or zone
+ * (and its lights) the room whose `hueRoom` names it (a light in a room and a zone, the room's), and a device that reports
+ * no name of its own (the Daikin, the Enphase gateway) the entry's `name`. A device's own name is never replaced.
+ */
+export function homeDevices(snapshot, config) {
+    // 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]) => devices(snapshot[name]))
+        .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(); // a Hue group's or light's id → the config room showing it
+    for (const d of all)
+        if (d.connector === "hue" && d.kind === "group") {
+            const room = config.rooms?.find((r) => r.hueRoom !== undefined &&
+                (r.hueRoom === d.id || r.hueRoom === d.detail.groupedLightId))?.id;
+            // A light in a room and a zone takes the room's: rooms come first, and the first one stays.
+            if (room)
+                for (const id of [d.id, ...d.detail.lightIds])
+                    if (!hueRooms.has(id))
+                        hueRooms.set(id, room);
+        }
+    return all.map((d) => {
+        const mine = entries.filter((e) => e.connector === d.connector);
+        const field = IDENTITY[d.connector];
+        // One device for the connector: its entry is this device. Many: the entry whose identity is this device's id.
+        const entry = d.id === d.connector
+            ? mine[0]
+            : mine.find((e) => {
+                const id = field && e[field];
+                return typeof id === "string" && sameId(id, d.id);
+            });
+        const room = d.room ?? entry?.room ?? hueRooms.get(d.id);
+        // A device with no name of its own carries its connector's title: only then does the entry's name replace it.
+        const unnamed = d.name === manifestOf(d.connector)?.title;
+        const name = unnamed ? (entry?.name ?? d.name) : d.name;
+        // Its line opens with its name, so a new name opens the line too.
+        const text = name !== d.name && d.text.startsWith(`${d.name}: `)
+            ? name + d.text.slice(d.name.length)
+            : d.text;
+        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) {
+    const s = snapshot.spotify?.state;
+    const cast = snapshot.cast?.state;
+    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);
+}
+/**
+ * `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, config) {
+    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/dist/discover.js

@@ -82,7 +82,7 @@ function newEntry(f) {
         [IDENTITY[f.connector]]: f.id,
     };
     if (f.connector === "hue")
-        return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+        return { ...base, key: "HUE_APPLICATION_KEY" };
     if (f.connector === "enphase")
         return { ...base, token: "~/.config/home/enphase-token.json" };
     return base;

package/dist/finders-entry.d.ts

@@ -1 +1 @@
-export { FINDERS, fileCache } from "./finders.ts";
+export { FINDERS, fileCache, MissingTool } from "./finders.ts";

package/dist/finders-entry.js

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

package/dist/finders.d.ts

@@ -1,5 +1,6 @@
 import { type AddressCache, type Connector, type Finder, type Found } from "./discover.ts";
 /** 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 declare class MissingTool extends Error {
 }
 /**
@@ -27,7 +28,7 @@ export declare function mdnsResolve(type: string): Promise<{
 }[]>;
 /** Daikin's `key=value,key=value` answers, percent-decoded. */
 export declare const daikinFields: (text: string) => any;
-/** 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 declare function findDaikins(ms?: number): Promise<{
     ip: string;
     fields: Record<string, string>;

package/dist/finders.js

@@ -13,6 +13,7 @@ import { parseAvahi, parseAvahiBrowse, parseBrowse, parseResolve, } from "./disc
 // 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.
 /** 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 {
 }
 /**
@@ -94,17 +95,27 @@ function decoded(v) {
         return v;
     }
 }
-/** 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) {
     return new Promise((resolve) => {
         const found = [];
         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.on("message", (msg, from) => {
+            if (!found.some((f) => f.ip === from.address))
+                found.push({ ip: from.address, fields: daikinFields(msg.toString()) });
+        });
+        const asks = [];
+        const done = () => (asks.forEach(clearTimeout),
+            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/dist/health.d.ts

@@ -1,4 +1,4 @@
-import type { Part, Status } from "./home.ts";
+import type { Part, Reason, Status } from "./home.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
@@ -12,6 +12,7 @@ export type Health = {
     staleAfterMs?: number;
     downAfterMs: number;
     detail?: string;
+    reason?: Reason;
 };
 /** 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 declare const STALE_POLLS = 2.5;

package/dist/health.js

@@ -22,7 +22,7 @@ function healthOf(part, now, pollSeconds) {
         (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;
+    const { status, lastGoodAt, downSince, detail, reason } = part;
     return {
         level: down ? "down" : stale ? "stale" : "ok",
         status,
@@ -31,5 +31,6 @@ function healthOf(part, now, pollSeconds) {
         staleAfterMs,
         downAfterMs,
         detail,
+        reason,
     };
 }

package/dist/home.d.ts

@@ -2,12 +2,14 @@ import { z } from "zod";
 import { type Clock } from "./clock.ts";
 /** A secret in a home config is the name of an environment variable, never the secret: a pasted key fails here. */
 export declare const envName: z.ZodString;
-/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+/** A file a connector needs (a CA, a token), relative to the config file or from `~/`. The caller reads it, and expands `~/`; the library reads no files. */
 export declare const filePath: z.ZodString;
 /** How an integration is doing. "unavailable" means it stopped and will not retry by itself. */
 export type Status = "connecting" | "connected" | "disconnected" | "unavailable";
+/** Why a part is `unavailable`, for code to switch on; `detail` is the text for people. `auth`: a key or token was rejected or is unusable, so a person must re-key. `config`: a setting or a file is wrong. `crashed`: its `run` threw. */
+export type Reason = "auth" | "config" | "crashed";
 /**
- * One integration's slice of the home: its status, a human detail, anything odd the device reported, and its state.
+ * One integration's slice of the home: its status, a human detail, `reason` (why it is `unavailable`, for code to switch on), anything odd the device reported, and its state.
  * `createHome` stamps the times (UTC ISO). `lastGoodAt`: its last report while connected, or the read time a connected report
  * gives when it repeats an older read (weather's 5-minute sun tick). `downSince`: when it stopped being connected (or started,
  * if it never has); none while connected. Any other time an integration sets is ignored.
@@ -15,11 +17,47 @@ export type Status = "connecting" | "connected" | "disconnected" | "unavailable"
 export type Part<S = unknown> = {
     status: Status;
     detail?: string;
+    reason?: Reason;
     anomaly?: string;
     state?: S;
     lastGoodAt?: string;
     downSince?: string;
 };
+/**
+ * The few things every device answers, whatever it is, in the same words; a connector's `<name>HomeDevices(part)` returns
+ * these and `homeDevices(snapshot)` collects them. Everything particular to its kind is in `detail`, the connector's own
+ * typed row, and `connector` (with `kind`) says which type that is. Unknown stays absent, never guessed.
+ * - `id`: the device's own stable id (a Hue light id, a castId, a printer's UUID), or the connector's name when it has one device.
+ * - `kind`: light, group, speaker, display, tv, ac, printer, solar (and `cast` for a Cast model this library doesn't know).
+ * - `available`: it answered and can be used now. When it is false, `reason` says why in one word: `offline`, or the
+ *   connector's own reason for being `unavailable` (`auth`, `config`, `crashed`).
+ * - `asOf`: when the device last reported (a push connector) or was last read (a polled one). A quiet light can be hours
+ *   old and current: `available` says whether it is.
+ * - `state`: one short word in that kind's vocabulary: on, off, idle, busy, cool, printing.
+ * - `text`: one line for people, "Kitchen: on · 60%".
+ * - `room`: a room id from the home config, when one places it.
+ * - `members`: a group's device ids.
+ */
+export type DeviceRecord<C extends string = string, K extends string = string, S extends string = string, D = unknown> = {
+    connector: C;
+    id: string;
+    name: string;
+    kind: K;
+    available?: boolean;
+    reason?: Reason | "offline";
+    asOf?: string;
+    state?: S;
+    text: string;
+    room?: string;
+    members?: string[];
+    detail: D;
+};
+/**
+ * A connector's device records from its part. While the connector isn't connected none is `available`, and each keeps its
+ * last values, as the part's state does. A device that isn't available gets its `reason`: the part's when it stopped for
+ * good, else `offline`.
+ */
+export declare const deviceRecords: <R extends DeviceRecord>(part: Part | undefined, records: R[]) => R[];
 /**
  * An integration is a folder in `src/` that exports a factory returning this.
  * `run` keeps its state current until `signal` aborts, reporting each change through `update`.
@@ -49,7 +87,7 @@ export type Change<I extends Integration<any, string> = Integration<unknown, str
 }[I["name"]];
 /**
  * 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 declare function createHome<I extends Integration<any, string>>(integrations: readonly I[], onChange?: (home: HomeSnapshot<I>, change: Change<I>) => void, options?: {
     clock?: Clock;
@@ -64,10 +102,19 @@ export declare function createHome<I extends Integration<any, string>>(integrati
     }> | 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 whose run has ended.
+     * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
      */
     refresh(name?: I["name"]): Promise<void>;
-    /** 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>;
+    /** 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: I["name"]) => Promise<boolean>;
+    /** Run every integration, and any added meanwhile, until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
     start(signal: AbortSignal): Promise<void>;
 };
 /**

package/dist/home.js

@@ -5,8 +5,21 @@ import { errorText } from "./connector.js";
 export const envName = z
     .string()
     .regex(/^[A-Z_][A-Z0-9_]*$/, "an environment variable name (e.g. AMBER_KEY), not the secret itself");
-/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+/** A file a connector needs (a CA, a token), relative to the config file or from `~/`. The caller reads it, and expands `~/`; the library reads no files. */
 export const filePath = z.string().min(1);
+/**
+ * A connector's device records from its part. While the connector isn't connected none is `available`, and each keeps its
+ * last values, as the part's state does. A device that isn't available gets its `reason`: the part's when it stopped for
+ * good, else `offline`.
+ */
+export const deviceRecords = (part, records) => {
+    const up = part?.status === "connected";
+    // A part that stopped for good without saying why is a custom integration's: `config` is the nearest true word, since it won't come back by itself.
+    const why = part?.status === "unavailable" ? (part.reason ?? "config") : "offline";
+    return records.map((r) => up && r.available !== false
+        ? r
+        : { ...r, available: false, reason: up ? "offline" : why });
+};
 /** The times `createHome` keeps on a part, from the one before it: when it was last good, and when it stopped being. */
 function stamped(part, before, now) {
     if (part.status === "connected")
@@ -23,24 +36,75 @@ function stamped(part, before, now) {
 }
 /**
  * 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(integrations, onChange, options = {}) {
     const clock = options.clock ?? realClock;
-    let snapshot = Object.fromEntries(integrations.map((i) => [i.name, { status: "connecting" }]));
+    const list = [...integrations]; // the integrations now: `add` and `remove` change it
+    const parts = () => snapshot;
+    let snapshot = Object.fromEntries(list.map((i) => [i.name, { status: "connecting" }]));
     const waiting = new Map(); // refresh() callers, resolved by the integration's next report
-    const finished = new Set(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
-    const set = (name, reported) => {
-        const before = snapshot[name];
+    const runs = new Map(); // the ones running: before start or after its run ended, a refresh resolves at once, nothing will report
+    const latest = new WeakMap(); // each integration's newest run: a report from an older run of the same object is dropped
+    let started; // start()'s signal, while it runs
+    let changing = 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 = (fn) => {
+        changes++;
+        const done = changing.then(fn).finally(() => changes--);
+        changing = done.catch(() => { });
+        return done;
+    };
+    const heard = (name) => {
+        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, run, reported) => {
+        const 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 };
-        onChange?.(snapshot, { name, before, after: part });
-        const w = waiting.get(name);
-        if (w) {
-            waiting.delete(name);
-            for (const resolve of w)
-                resolve();
-        }
+        Promise.try(() => onChange?.(snapshot, { name, before, after: part })).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
+        heard(name);
+    };
+    /** Run one integration until the home's signal or its own `stop` aborts. One failing marks itself unavailable. */
+    const launch = (i, signal) => {
+        const stop = new AbortController();
+        const 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) => {
+        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;
+        heard(name);
+        const run = runs.get(old);
+        run?.stop.abort();
+        await run?.done;
+        return true;
     };
     return {
         /** The latest snapshot. Never touches a device. */
@@ -48,19 +112,17 @@ export function createHome(integrations, onChange, options = {}) {
         /** One integration's part, typed by its name: `home.part("weather")?.state?.blocks`. */
         part: (name) => snapshot[name],
         /** One integration by name, for its writes: `home.integration("daikin")?.client.write(setPower(true))`. */
-        integration: (name) => integrations.find((i) => i.name === name),
+        integration: (name) => list.find((i) => i.name === name),
         /**
          * 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 whose run has ended.
+         * promise resolves once each target has reported (its next update, good or bad), or at once for one that isn't running.
          */
         refresh(name) {
-            const targets = name === undefined
-                ? integrations
-                : integrations.filter((i) => i.name === name);
-            if (!targets.length)
-                throw new Error(`no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`);
+            const targets = name === undefined ? [...list] : list.filter((i) => i.name === name);
+            if (!targets.length && name !== undefined)
+                throw new Error(`no integration "${name}"; have ${list.map((i) => i.name).join(", ")}`);
             const reported = targets.map((i) => new Promise((resolve) => {
-                if (finished.has(i.name))
+                if (!runs.has(i))
                     return resolve();
                 waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
             }));
@@ -68,25 +130,44 @@ export function createHome(integrations, onChange, options = {}) {
                 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) => 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) => 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) {
-            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).map(([name, p]) => [
+            snapshot = Object.fromEntries(Object.entries(parts()).map(([name, p]) => [
                 name,
                 p.status === "connecting"
                     ? { ...p, downSince: p.downSince ?? now }
                     : p,
             ]));
-            await Promise.all(integrations.map((i) => i
-                .run(signal, (part) => set(i.name, part))
-                .catch((error) => set(i.name, { status: "unavailable", detail: errorText(error) }))
-                .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/dist/index.d.ts

@@ -1,7 +1,8 @@
-export { type Change, createHome, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type StateOf, type Status, } from "./home.ts";
+export { type Change, createHome, type DeviceRecord, deviceRecords, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type Reason, type StateOf, type Status, } from "./home.ts";
 export { DOWN_POLLS, type Health, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.ts";
+export { byRoom, type HomeDevice, homeDevices, type RoomDevices, spotifyElsewhere, } from "./devices.ts";
 export { asOf, type Clock, realClock } from "./clock.ts";
-export { ConnectorError } from "./connector.ts";
+export { type ConnectorCode, ConnectorError } from "./connector.ts";
 export { bestWindow, type EnergyNow, energyNow, gridText, type PriceWindow, solarLevel, } from "./energy.ts";
 export { checkHome, checkPlan, Device, HomeConfig, HomeConfigError, type HomeIntegration, type LoadOptions, loadHome, parseJsonc, Room, type Setup, } from "./config.ts";
 export type { AddressCache, CachedAddress, Connector, Finder, Found, } from "./discover.ts";

package/dist/index.js

@@ -1,7 +1,8 @@
 // The root entry: the home, its config, discovery types, the clock, energy, and the sun, rain and day-block helpers. The weather types are in `./weather`.
 // Each connector has its own entry point (`@khalido/home/hue` and so on). Every export is named; test/exports.test.ts lists them.
-export { createHome, envName, filePath, settle, } from "./home.js";
+export { createHome, deviceRecords, envName, filePath, settle, } from "./home.js";
 export { DOWN_POLLS, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.js";
+export { byRoom, homeDevices, spotifyElsewhere, } from "./devices.js";
 export { asOf, realClock } from "./clock.js";
 export { ConnectorError } from "./connector.js";
 export { bestWindow, energyNow, gridText, solarLevel, } from "./energy.js";

package/dist/node-fetch.d.ts

@@ -1,5 +1,5 @@
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export declare 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 declare function nodePinnedFetch(bridgeId: string, ca?: string): typeof fetch;
 /** A `fetch` for the Enphase gateway that skips certificate verification, for its requests only: Node's `bunGatewayFetch`. */
 export declare function nodeGatewayFetch(): typeof fetch;
 /** What `loadHome` takes as `tls` under Node. */

package/dist/node-fetch.js

@@ -1,11 +1,12 @@
 import { Agent, fetch as undiciFetch } from "undici";
+import { HUE_BRIDGE_ROOT_CA } from "./connectors/hue/ca.js";
 // `@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
 // runtime-neutral build, like cast/tls.ts; a Node consumer passes `NODE_TLS` to `loadHome`, or one fetch to `hue()` or `enphase()`.
 /** undici's `fetch` through `dispatcher`. Takes a URL, not a `Request`, and returns undici's own `Response`. */
 const through = (dispatcher) => ((input, init) => undiciFetch(input, { ...init, dispatcher }));
-/** A `fetch` that trusts only `ca` and accepts only a certificate whose CN is `bridgeId`: Node's `bunPinnedFetch`. */
-export function nodePinnedFetch(bridgeId, ca) {
+/** 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, ca = HUE_BRIDGE_ROOT_CA) {
     const checkServerIdentity = (_host, cert) => {
         const cn = [cert.subject?.CN].flat()[0];
         return cn?.toLowerCase() === bridgeId.toLowerCase()

package/docs/cli.md

@@ -3,11 +3,16 @@
 ```sh
 home <connector> [--json]     # one connector's lines: amber, cast, daikin, enphase, hue, printers, spotify, up, weather
 home [status|doctor] [--json] # each integration: connected or not, which env names it still needs, rooms
+home devices [--json]         # every device the connectors read, one line each: its state, its room (with a config), and why when it isn't available
 home up transactions | categories | uncategorised | spend | categorise | tag | webhooks  # Up Bank's lists and reports; categorise and tag write
-home lights off               # one write to the whole-home group
-home room <name> on|off|<1-100>
-home scene <name>
-home pair                     # press the bridge's button first; prints the env lines to set
+home lights off               # one write to the whole-home group; prints how many lights are off, or how many the bridge still reports on
+home light <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]  # one light: `home light "Desk lamp" 40 2700k`, `home light Shelf ff8800`
+home room <name> [on|off] [<1-100>] [<kelvin>k] [<hex colour>]   # every light in a room or zone, one write
+home scene <name> [in <room>]  # a scene; name the room when several have one by that name
+home pair                     # waits 60 s for the bridge's button, counting down; prints the env lines to set
+home daikin on | off           # power only: the AC comes back as it was last left
+home daikin cool | heat | auto [°C] | dry | fan  # mode, on, and the setpoint: the one given, else cool 25 and heat 27; prints what the unit then reports. Live on KO's unit: on, and dry to cool at 25 (2026-11-11); the rest untried
+                              # --dry-run on a hue or daikin write (lights, light, room, scene, daikin …): check it and print what would be sent; nothing is sent. Refused on every other command
 home enphase login            # once a year: mints the Enphase owner token into ~/.config/home/ (0600)
 home discover [--json] [--passes n]  # which smart-home devices answer here (mDNS + Daikin UDP), which this package supports, then with a config how they match it; two passes 5 s apart
 home cache [clear]            # the addresses kept between runs, or delete them so the next run discovers afresh
@@ -19,6 +24,7 @@ home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>)
 home cast volume <name> <0-100>
 home cast mute <name> on|off
 home cast stop <name>         # end the running app; the device returns to its idle screen
+                              # volume, mute and stop print the device's line once it reports the change (within 2 s), else "sent; the device has not reported it yet"
 home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
 ```
 
@@ -26,16 +32,16 @@ home spotify activate | pause | play [link] | next | volume <0-100>  # the Soloi
 
 - **stdout is data, stderr everything else.** Notes such as "nothing to categorise" or "no webhooks" go to stderr, so `home … | jq` never sees them.
 - **Bun on PATH.** The command starts with `#!/usr/bin/env bun`. A non-login SSH shell may not have `~/.bun/bin` on its PATH: run `PATH="$HOME/.bun/bin:$PATH" home`.
-- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
+- **`--json` shapes.** `home --json` is one object keyed by connector, with `now` (`energyNow`) first. `home devices --json` is the array `homeDevices` returns; a connector that isn't connected is named on stderr, and the command exits 0. `home <connector> --json` is that connector's object: `status`, `needs`, `access`, `detail`, `reason` (why it is `unavailable`, when known: `auth`, `config` or `crashed`), `anomaly`, then its state (the weather adds `line`, its text). Lists (`home up transactions`, `uncategorised`, `spend --by merchant`) are arrays, `[]` when empty.
 - **Errors under `--json`** are one object on stderr: `{"error": "…", "code": "usage" | "auth" | "network" | "error", "fix": "home enphase login"}`; `fix` is there only when one command resolves it. In text: `home: <error> (run \`<fix>\`)`.
 - **Exit codes.** 0 success, empty results included. 1 a failure, and `home <connector>` when that connector is not `connected`, so a script can test one. 2 a wrong command, verb or argument. `home` alone lists every connector and exits 0 whatever their state.
 
 With `--config <home.jsonc>` or `HOME_CONFIG`, `status` runs the integrations the config describes until each has answered (at most 15 s) and `probe` takes its addresses from it; keys still come from the shell, by the names in the file. Without one, it reads `HUE_*` and the other names in `.env.example` from the shell, and parses arguments with [cac](https://github.com/cacjs/cac), which also generates `home --help`. Every connector has a verb of its own: `home amber`, `home cast`, `home hue` print only that connector's lines (`--json` for its record), and the verbs that need more sit under it (`home hue pair`, `home enphase login`, `home cast announce …`). The commands come from each connector's manifest (`src/manifest.ts`), as does `.env.example` (`bun run gen`). With no `HUE_BRIDGE_HOST` it finds the bridge by mDNS (`dns-sd`, macOS) every time and caches nothing. `home` with no arguments is `status`:
 
 ```
-hue      not set up · needs HUE_APPLICATION_KEY, HUE_CA_FILE  (local HTTPS, key from `home pair`)
+hue      not set up · needs HUE_APPLICATION_KEY  (local HTTPS, key from `home pair`)
 daikin   connected · off · cool 25 °C · room 24 °C · outdoor unit 19.5 °C  (local HTTP JSON (dsiot), no key)
 weather  connected · Sydney - Observatory Hill (1.1 km) 20:20: 16.6 °C, feels 16.7, 93%, 23.6 mm since 9am to 20:23 · today showers rain 80%, tomorrow 14–19 °C cloudy rain 30% (bom) · cloud 100%, UV 0, 0 W/m² (open-meteo) · sun -17°, setting, rises 06:15  (BOM anonymous FTP, Open-Meteo, Google with GOOGLE_WEATHER_KEY; sun computed)
 ```
 
-Startup is about 10 ms and 38 MB RSS for `home status` without a key; with Enphase, Amber and the Daikin live it takes 0.4–0.8 s, the devices read in parallel (Bun 1.4.2, Apple M5, measured 2026-10-13). The weather line adds 1.8–2.0 s, nearly all of it BOM's FTP (two files, one connection each). Cast takes about 0.3 s: `dns-sd` answers from the system's mDNS cache in 4–13 ms, the browse waits 200 ms of quiet for stragglers, each resolve ends on its TXT line, and seven sockets connect and answer in 50–80 ms (`home status` from a Cast-only config: 0.33–0.44 s, was 3.2 s with fixed 1.5 s windows; Bun 1.4.2, measured 2026-10-13). A configured entry discovery misses costs the second pass, 5 s more. `status` reads addresses from the environment only, except Cast, which has none to read; `discover` and `probe` do the other network searches. A full-screen TUI was considered (OpenTUI 0.6.2, 52 MB of native binaries) and skipped for now.
+Startup is about 10 ms and 38 MB RSS for `home status` without a key; with Enphase, Amber and the Daikin live it takes 0.4–0.8 s, the devices read in parallel (Bun 1.4.2, Apple M5, measured 2026-10-13). The weather line adds 1.8–2.0 s, nearly all of it BOM's FTP (two files, one connection each). Cast takes about 0.3 s: `dns-sd` answers from the system's mDNS cache in 4–13 ms, the browse waits 200 ms of quiet for stragglers, each resolve ends on its TXT line, and seven sockets connect and answer in 50–80 ms (`home status` from a Cast-only config: 0.33–0.44 s, was 3.2 s with fixed 1.5 s windows; Bun 1.4.2, measured 2026-10-13). A configured entry discovery misses costs the second pass, 5 s more. `status` reads addresses from the environment, except Cast, which has none to read, and the Daikin, found by UDP broadcast when `DAIKIN_HOST` is unset (1.5 s); `discover` and `probe` do the other network searches. A full-screen TUI was considered (OpenTUI 0.6.2, 52 MB of native binaries) and skipped for now.