@khalido/home 0.1.1 → 0.1.3

package/dist/devices.js

@@ -0,0 +1,61 @@
+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 { spotifyHomeDevices, } 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) {
+    const all = Object.entries(DEVICES).flatMap(([name, devices]) => devices(snapshot[name]));
+    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 } : {}) };
+    });
+}

package/dist/discover.d.ts

@@ -85,6 +85,7 @@ export type CachedAddress = {
     host: string;
     port?: number;
     name?: string;
+    model?: string;
     seenAt: string;
 };
 /**
@@ -111,6 +112,7 @@ export declare function addressBook(cache: AddressCache | undefined, options?: {
         host: string;
         port?: number;
         name?: string;
+        model?: string;
     }): void;
     entries: () => {
         [x: string]: CachedAddress;

package/dist/discover.js

@@ -241,13 +241,16 @@ export function addressBook(cache, options = {}) {
                 c.host === address.host &&
                 c.port === address.port &&
                 isFresh(c) &&
-                (!address.name || address.name === c.name))
+                (!address.name || address.name === c.name) &&
+                (!address.model || address.model === c.model))
                 return;
             const name = address.name || c?.name;
+            const model = address.model || c?.model;
             entries[key] = {
                 host: address.host,
                 ...(address.port === undefined ? {} : { port: address.port }),
                 ...(name ? { name } : {}),
+                ...(model ? { model } : {}),
                 seenAt: new Date(now()).toISOString(),
             };
             cache.write({ ...entries });

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`.
@@ -64,7 +102,7 @@ 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. */

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")
@@ -29,12 +42,12 @@ export function createHome(integrations, onChange, options = {}) {
     const clock = options.clock ?? realClock;
     let snapshot = Object.fromEntries(integrations.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 finished = new Set(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, reported) => {
         const before = snapshot[name];
         const part = stamped(reported, before, asOf(clock));
         snapshot = { ...snapshot, [name]: part };
-        onChange?.(snapshot, { name, before, after: part });
+        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
         const w = waiting.get(name);
         if (w) {
             waiting.delete(name);
@@ -51,7 +64,7 @@ export function createHome(integrations, onChange, options = {}) {
         integration: (name) => integrations.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
@@ -78,9 +91,13 @@ export function createHome(integrations, onChange, options = {}) {
                     ? { ...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) }))
+            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[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) ?? [])

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 { type HomeDevice, homeDevices } 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 { homeDevices } from "./devices.js";
 export { asOf, realClock } from "./clock.js";
 export { ConnectorError } from "./connector.js";
 export { bestWindow, energyNow, gridText, solarLevel, } from "./energy.js";

package/dist/lane.js

@@ -24,28 +24,32 @@ export function writeLane(options) {
     }
     async function run() {
         running = true;
-        while (queue.length) {
-            const now = clock.now();
-            const next = queue.find((p) => readyAt(p.slot) <= now);
-            if (!next) {
-                wake = new AbortController();
-                await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
-                continue;
-            }
-            queue.splice(queue.indexOf(next), 1);
-            lastAt = now;
-            sent.set(next.slot, [...recent(next.slot), now]);
-            try {
-                const result = await next.write(next.body);
-                for (const w of next.waiters)
-                    w.resolve(result);
-            }
-            catch (error) {
-                for (const w of next.waiters)
-                    w.reject(error);
+        try {
+            while (queue.length) {
+                const now = clock.now();
+                const next = queue.find((p) => readyAt(p.slot) <= now);
+                if (!next) {
+                    wake = new AbortController();
+                    await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
+                    continue;
+                }
+                queue.splice(queue.indexOf(next), 1);
+                lastAt = now;
+                sent.set(next.slot, [...recent(next.slot), now]);
+                try {
+                    const result = await next.write(next.body);
+                    for (const w of next.waiters)
+                        w.resolve(result);
+                }
+                catch (error) {
+                    for (const w of next.waiters)
+                        w.reject(error);
+                }
             }
         }
-        running = false;
+        finally {
+            running = false; // a throw here must not leave the lane stuck
+        }
     }
     return {
         send(slot, body, write, merge = (_, newer) => newer) {

package/docs/cast.md

@@ -109,7 +109,7 @@ No host: a group's host changes with its leader. All entries fold into one `cast
 - `announce(target, clip, { volume?, timeoutMs? })`, target a device or group, `clip` a URL or bytes with their type (KO's own dictation as recorded, or TTS output; the library never synthesises) served by `serveClip`. The result names each member it could not restore. Read status, set volume, launch Default Media Receiver (`CC1AD845`), `LOAD` the clip, wait for `IDLE`/`FINISHED` (with a timeout), then restore: a prior Default Media Receiver `contentId` is re-loaded at its `currentTime`, an idle device gets `STOP`, then the volume. Spotify, YouTube and other apps cannot be resumed generically (our launch ends their session); the result says so.
 - `castUrl(name, url)` launches DashCast (`84912283`, pychromecast's list) with the URL. HA casts its dashboard with its own registered receiver (`A078F6B0`), a hint at DashCast's limits. KO's own receiver costs a one-off Cast SDK fee and must be published (unpublished ones run only on serial-registered devices). Try DashCast first.
 
-**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3, AAC, WAV; not AIFF): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
+**TTS.** The library plays a URL, never synthesises. The speaker fetches it, so it must be HTTP on the LAN, not loopback, and in a format Default Media Receiver plays (MP3 or AAC; not AIFF; a 24 kHz mono WAV failed on audio-only Nest speakers, live 2026-11-09): `say -o msg.m4a --file-format=m4af --data-format=aac "…"` (m4af alone holds uncompressed PCM). Smallest server: a ~25-line `serveClip(bytes, type)` over `node:http` beside `tls.ts`, bound to the Mac's LAN address, random port, unguessable path, closed when the clip has played or after a minute (not after the first fetch, so a probe before it does no harm). The consumer runs `say`; `serveClip` picks the address on the target's network; the sidecar will raise macOS's local-network prompt once. A cloud voice later is MP3 bytes served the same way.
 
 **CLI.** `home status`: `cast  7 · Display A idle 47% · TV B standby · Whole house (3, led by Display A) idle`. `home probe`: this probe.
 

package/docs/cli.md

@@ -15,18 +15,18 @@ home config check [path]      # validate a home config: what it would set up, se
 home discover --write [path]  # with a config (the path, else --config or HOME_CONFIG): match what answers by identity, add new devices, update moved hosts and renamed Cast names in place
 home probe                    # read-only, no keys: Hue's public config, Daikin by UDP broadcast, the IQ Gateway's /info, each weather source, each Cast device's and printer's status
 home locate "<street address>" [--write [path]]  # latitude and longitude from OpenStreetMap's Nominatim; --write sets them in the config's location (and timezone, when absent, to this machine's)
-home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100]  # play a clip, then put back what was playing and the volume
+home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100]  # exit 1 if any didn't play; play a clip, then put back what was playing and the volume
 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
-home spotify pause | play [link] | next | volume <0-100>  # the Soloist speaker at SOLOIST_WS; volume held to SOLOIST_MAX_VOLUME; prints what Soloist then reported
+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
 ```
 
 ## Output
 
 - **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 <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.
 

package/docs/config.md

@@ -4,12 +4,17 @@ One JSONC file lays out the home, so the `home` command, jaldi and chota-bot rea
 
 ```ts
 import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { createHome, loadHome, parseJsonc } from "@khalido/home";
 import { ftpFetch } from "@khalido/home/weather/ftp";
 
 const path = "/path/to/home.jsonc";
-const readFile = (p: string) => readFileSync(resolve(dirname(path), p), "utf8"); // paths in the config are relative to it
+const readFile = (p: string) =>
+  readFileSync(
+    resolve(dirname(path), p.replace(/^~(?=\/)/, homedir())),
+    "utf8",
+  ); // relative to the config, or from ~/
 const home = createHome(
   loadHome(parseJsonc(readFileSync(path, "utf8")), {
     env: process.env,
@@ -22,12 +27,12 @@ const home = createHome(
 `loadHome` runs on Bun and Node. Hue and Enphase need a fetch that handles their certificates: Bun's `tls` fetch option by default, and under Node `tls: NODE_TLS` from `@khalido/home/node`. Under Node, a config with Hue or Enphase and no `tls` is a problem `loadHome` names, not a silent failure at the first read.
 
 - **A device entry is only how to reach it and where it is**: its identity (the Hue `bridgeId`, a Daikin's `mac`, the Enphase `serial`, a Cast `castId`), its last known `host`, a key's env name, a file's path, its `room`. What a device reports about itself (model, firmware) comes live; a note about it is a comment.
-- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config; the library reads nothing.
+- **Secrets are env variable names** (`"key": "AMBER_KEY"`), resolved against the `env` the caller passes; a pasted key fails the schema. Files (`ca`, `token`) are paths the caller reads, relative to the config or from `~/`, which the caller expands (`home discover --write` writes Enphase's token as `~/.config/home/enphase-token.json`); the library reads nothing.
 - **Problems name the field**: an unknown connector, a missing env name or a device in a missing room is an error, never a skip. `checkHome` returns them all; `loadHome` throws them all. Unknown keys pass through for a consumer's own settings.
 - **One device per connector** for now (each integration is named by its connector), except printers (one entry each, by `uuid`) and Cast: one entry per device and speaker group (`name`, the Google Home name, and `castId`, the mDNS id), all read by one `cast` integration that finds every address by discovery, since a group's moves with its leader. A `spotify` entry is only its Soloist `url` (and `maxVolume`): a socket on the same machine, with nothing to discover.
 - **Identity, not address.** A device is recognised by the id its own discovery reports; `host` is a cache. `home discover` lists what answers (mDNS, Daikin's UDP broadcast), in two passes 5 s apart since both drop answers now and then: the first pass prints at once, the second only what it adds (`--passes 1` for a quick look; `--json` waits for both); with a config (`--config` or `HOME_CONFIG`) it then matches those against it by identity and prints new devices, moved addresses and conflicts (a different device at an entry's host). `home discover --write <file>` adds the new ones (each with an id no entry has), updates moved hosts and refreshes the `name` of a Cast entry renamed in the Google Home app through `jsonc-parser`'s edits, every comment and other line left as it was, and writes only a result that passes `checkPlan`. Nothing else writes the file; the library never does. Two devices with one id are a config problem.
 - **A device that moves is found again, without periodic scans**, when the caller passes `finders` to `loadHome` (`FINDERS` from `@khalido/home/finders`, Node-side like `weather/ftp`; the CLI does, and jaldi and chota-bot can). After three failed reads in a row (Hue: three failed reconnects of its event stream), Hue, Daikin and Enphase run their discovery (two passes, the second skipped when the first finds the device), switch to the address their identity now answers at and say "moved from a to b" in `detail` (persist it with `home discover --write`); otherwise they look again at 1, 5 and 15 minutes, then hourly for as long as reads fail, so a device back from the wall socket reads again without a restart. The detail says what discovery found ("not found by discovery", or "discovery finds it at its address but reads fail", or "discovery failed: …" when it could not run), and "no answer for a day" once a day has passed; the part stays `disconnected`, since `unavailable` is for a rejected key. `refresh()` resets the wait. Amber and the weather have no discovery and do not take part. Cast always needs `finders.cast`: discovery is how it finds every address.
-- **Discovery is rare: addresses are cached between runs.** `loadHome(config, { cache, configAt })` takes an `AddressCache` (`read()` and `write(entries)`, keyed by connector and identity, each entry `{ host, port?, name?, seenAt }`). A cached address newer than the config (`configAt`, the file's modified time) is tried first, a failure there scans at once rather than after three, and each address that answers is written back when it changed or predates the config, so a config edit is re-trusted at the first good read. Nothing evicts an entry but `home cache clear`: a device gone for good keeps its entry, and `home status` without a config, which reads every Cast entry from the cache, shows it as not found until then. The consumer persists it: the CLI keeps `$XDG_CACHE_HOME/home/addresses.json` (default `~/.cache/home/addresses.json`, 0600) through `fileCache` from `@khalido/home/finders`, written at the end of `status`, `probe` and `discover`; jaldi's sidecar and chota-bot pass `FINDERS` and their own cache the same way. The config's `host` stays the human-set fallback and `home discover --write` the way to change the config. `home status` from a Cast config: 0.33–0.44 s cold, 0.13 s with a warm cache, 1.4 s once when a cached address has gone stale (Bun 1.4.2, measured 2026-10-13).
+- **Discovery is rare: addresses are cached between runs.** `loadHome(config, { cache, configAt })` takes an `AddressCache` (`read()` and `write(entries)`, keyed by connector and identity, each entry `{ host, port?, name?, seenAt }`). A cached address newer than the config (`configAt`, the file's modified time) is tried first, a failure there scans at once rather than after three, and each address that answers is written back when it changed or predates the config, so a config edit is re-trusted at the first good read. Nothing evicts an entry but `home cache clear`: a device gone for good keeps its entry, and `home status` without a config, which reads every Cast entry from the cache, shows it as not found until then. The consumer persists it: the CLI keeps `$XDG_CACHE_HOME/home/addresses.json` (default `~/.cache/home/addresses.json`, 0600) through `fileCache` from `@khalido/home/finders`, written at the end of `status`, `probe` and `discover`; another consumer passes `FINDERS` and its own cache the same way. The config's `host` stays the human-set fallback and `home discover --write` the way to change the config. `home status` from a Cast config: 0.33–0.44 s cold, 0.13 s with a warm cache, 1.4 s once when a cached address has gone stale (Bun 1.4.2, measured 2026-10-13).
 - **Parsing** is through `jsonc-parser` (comments and trailing commas), on Bun and Node alike; a syntax error throws. `bun run schema` rewrites `home.schema.json` from the zod schema, and a test fails if they drift.
 - `createHome` stays for code-first use.
 

package/docs/decisions.md

@@ -148,3 +148,8 @@ KO's decisions on this package, newest block last. They override every other doc
 - **Signed out reads as waiting**, everywhere: `speakerState` says `waiting`, the detail says "waiting for someone to pick it", the write error's code is `waiting`.
 - **Stalls (Soloist issue #5) are noticed by default and repaired only when asked** (`repairStalls: true`): the repair is the library's first write nobody asked for, so a consumer opts in. Two signals, since the issue doesn't say whether the reported position freezes: a frozen position across fresh reports, and still playing well past the track's end, the symptom actually reported. One repair per track, never a loop. The nudges (seek, then pause and play; a skip past the end) are guesses until a stall is seen live.
 - **The project is home.ts; the npm package stays `@khalido/home`** (KO, 2026-11-08), so imports stay short (`@khalido/home/spotify`). It is home automation for TypeScript, starting with the devices in KO's house, and is meant to grow into more of the basics.
+- **Spotify: inactive is refused, and activating is the caller's choice** (KO, 2026-11-09). Soloist accepts and drops `set_volume` while it isn't the active device. `setVolume` refuses with code `inactive`, and `activate()` is separate, because activating makes a new stream and can jump the volume to the level last saved. `duck` runs `fn` anyway, with `music: "untouched"`, because the announcement matters more. `play` goes active itself, since someone asking for music wants it to start; `resume` doesn't, since it worked inactive. The `maxVolume` cap says "lowered" only once Soloist reports it.
+
+- **`Part.reason`, only on `unavailable`** (KO, 2026-11-09). An admin page had to match `detail` text like "pair again" to know a person must re-key. `reason` is `auth` (a key or token rejected or unusable), `config` (a setting or file is wrong) or `crashed` (a `run` threw), for code to switch on; `detail` stays the text for people. `disconnected` gets none: it already says unreachable. Additive, so a patch. `config` came a day later (KO, 2026-11-10), so "re-key", "fix a setting" and "report a bug" are three answers; `crashed` stays though nothing reads it yet. Weather has one too: each source says why it stopped (`stopReason`), the part is `auth` if any stopped source is, else `config`, and `state.sources.<name>.reason` shows a dead key while another source keeps the part `connected`.
+- **Google's key goes in the `X-Goog-Api-Key` header, not the URL** (KO, 2026-11-10), so nothing that prints a URL can print it. Its rejection is read from the error body: a bad key and a bad latitude are both HTTP 400, and only the key's carries `API_KEY_INVALID` (live, 2026-11-10).
+- **Every device answers the same few questions** (KO, 2026-11-10: "nice and consistent so we can easily and consistently add devices"). `DeviceRecord` is identity, availability, one word of state and one line of text, the same for a light, a speaker and a printer; `homeDevices(snapshot, config?)` lists them all. Everything particular to a kind stays in the connector's own typed row, carried as `detail`, so the common record never grows a field only one kind has. Three levels, each inside the last: the house list, the connector's typed row, the raw snapshot. Each connector exports its own typed function, listed by hand in `src/devices.ts`, and not a manifest field: `MANIFESTS` is untyped, and `detail` must narrow by `connector`. The list is read-only: a write means something different for a light, a speaker and an air conditioner, so there is no generic `turnOn`. Not done, for a 0.2.0: Hue's `reachable` becoming `available`, and its groups joining its lights in one call.

package/docs/using.md

@@ -37,6 +37,23 @@ health(home.snapshot(), Date.now()); // per integration: ok, stale or down, with
 
 `createHome` stamps each part with `lastGoodAt` (its last good read) and `downSince` (when it stopped being connected). `health` judges from those: a polling connector is stale after 2½ polls with no good read and down after 3 polls not connected; Hue and Cast are down after 2 minutes not connected. Health takes each connector's interval from its manifest; a home that changes one (the weather's `pollMinutes`) passes it: `health(snapshot, now, { pollSeconds: { weather: 60 * 60 } })`. For a one-shot read (a script, a printed brief), `settle(integrations, { ms })` runs them until each has answered and returns the snapshot.
 
+## Every device, the same way
+
+`homeDevices(home.snapshot(), config)` lists every device the home has: each Hue light, room and zone, the Daikin, the Enphase gateway, each Cast device and group, each printer and the Soloist speaker. Each answers the same questions in the same words: `connector`, `id`, `name`, `kind` (light, group, speaker, display, tv, ac, printer, solar; `cast` for a Cast model the library doesn't know), `available` (and when it is false, `reason`: `offline`, `auth`, `config` or `crashed`), `asOf` (when the device last reported or was last read; a quiet light can be hours old and current), `state` (one word: on, off, idle, busy, cool, printing), `text` (one line for people), `room` and, for a group, `members`. A field the device hasn't reported is absent. The config is optional: with it a device takes its entry's `room`, and a device with no name of its own (the Daikin, the gateway) its entry's `name`; a device's own name is never replaced. While a connector isn't connected none of its devices is `available`, and each keeps its last values.
+
+To drill down, `detail` is the connector's own typed row, and `connector` (with `kind` for Hue) tells TypeScript which:
+
+```ts
+for (const d of homeDevices(home.snapshot(), config)) {
+  console.log(d.text); // "Kitchen: on · 60%"
+  if (d.connector === "cast") d.detail.volume; // CastStatus
+  if (d.connector === "hue" && d.kind === "light") d.detail.brightness; // LightView
+  if (d.connector === "printers") d.detail.markers; // Printer
+}
+```
+
+Below that is the connector's snapshot, exactly as the device sent it (`home.part("hue")?.state`). One connector alone: `castHomeDevices(home.part("cast"))`, and likewise `hueHomeDevices`, `daikinHomeDevices`, `enphaseHomeDevices`, `printersHomeDevices`, `spotifyHomeDevices`. The list is for reading; a write goes to the device's connector, with `d.id` where it takes one.
+
 ## Writes
 
 Writes hang off the integration: `home.integration("daikin")?.client.write(setMode("cool"))`, `home.integration("hue")?.client.recallScene(id)`, `home.integration("cast")?.setVolume(…)`, `home.integration("spotify")?.play(link)`. Each goes through the device's write lane: spaced, and a burst to one light or the AC merges so the last value lands. Spotify's writes resolve with `{ state, confirmed }`, the state once Soloist reported the change, and `duck(fn, { to })` and `interrupt(fn)` turn the music down or pause it around an announcement, returning what happened to it (`music`: `untouched`, `restored`, `kept` or `failed`). `speakerState(part)` says the speaker in one word (offline, waiting, idle, playing, paused) and `spotifyChanges(change.before, change.after)` turns an `onChange` into events (started, resumed, paused, stopped, track, stalled, recovered, offline, waiting, picked), those from the library's own `duck` or `interrupt` marked `own`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@khalido/home",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "home.ts: small, typed home automation for TypeScript: Hue, Daikin, Enphase, Google Cast, AirPrint printers and a Spotify Soloist speaker on the local network; Amber prices, Up Bank spending and the weather from the cloud.",
   "license": "MIT",
   "author": "Khalid Omar",

package/skills/use-home/SKILL.md

@@ -29,13 +29,13 @@ The contract (in `docs/cli.md`): stdout is data, stderr everything else. `--json
 
 What a status means:
 
-| Status         | Meaning                                                                            | What to do                                        |
-| -------------- | ---------------------------------------------------------------------------------- | ------------------------------------------------- |
-| `connected`    | read and current                                                                   | use it                                            |
-| `connecting`   | still starting (a 15 s cap in the CLI)                                             | wait, or run again                                |
-| `disconnected` | the device or service did not answer; the last good state is kept, with its `asOf` | say so; check the device is on and at its address |
-| `unavailable`  | stopped for good: a key rejected, a setting wrong                                  | the `detail` names it; fix the key or setting     |
-| `not set up`   | env names or a file missing (`needs` lists them)                                   | set them, or say what is needed                   |
+| Status         | Meaning                                                                                                                                                         | What to do                                        |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- |
+| `connected`    | read and current                                                                                                                                                | use it                                            |
+| `connecting`   | still starting (a 15 s cap in the CLI)                                                                                                                          | wait, or run again                                |
+| `disconnected` | the device or service did not answer; the last good state is kept, with its `asOf`                                                                              | say so; check the device is on and at its address |
+| `unavailable`  | stopped for good: a key rejected, a setting wrong; `reason`, when present, is `auth` (a person must re-key), `config` (a setting or file is wrong) or `crashed` | the `detail` names it; fix the key or setting     |
+| `not set up`   | env names or a file missing (`needs` lists them)                                                                                                                | set them, or say what is needed                   |
 
 Weather: `blocks` holds morning, afternoon and evening for today and tomorrow in the home's time zone; `rainSoon` says when rain starts in the next two hours (needs the Google key). Energy: `now` in `home --json` is the one owner of solar, use, grid flow and cost per hour; never recompute it.
 

package/src/cli/cast.ts

@@ -34,6 +34,7 @@ export function castNow() {
           {
             castId: key.slice(5),
             name: c.name ?? key.slice(5),
+            model: c.model,
             host: c.host,
             port: c.port,
           },
@@ -71,7 +72,7 @@ async function withCast<T>(
 }
 
 export const CAST_USAGE =
-  'usage: home cast announce --to <name> (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
+  'usage: home cast announce --to <name> [--to <name>…] (--say "<text>" | --file <path>) [--volume 0-100] | volume <name> <0-100> | mute <name> on|off | stop <name>';
 
 /** A 0–100 argument as the 0–1 a Cast device takes. */
 function percentLevel(value: string | undefined): number {
@@ -96,7 +97,7 @@ const AUDIO_TYPES: Record<string, string> = {
 export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
   [
     "--to <name>",
-    "announce: the device or group, by name or castId",
+    "announce: the device or group, by name or castId; repeat for several",
     { type: [String] },
   ],
   ["--say <text>", "announce: words spoken by macOS `say`", { type: [String] }],
@@ -119,7 +120,8 @@ export const castVerbs: Verbs = {
     await withCast((c) => c.stop(name!));
   },
   async announce(_, o) {
-    const [to, say, file] = [text(o.to), text(o.say), text(o.file)];
+    const [say, file] = [text(o.say), text(o.file)];
+    const to = [o.to].flat().filter(Boolean).map(String); // --to can repeat
     // cac gives "true" for a flag with no value: `--say` alone must not speak the word "true", so each flag needs a value after it.
     const bare = ["--to", "--say", "--file"].some((f) =>
       process.argv.some(
@@ -130,7 +132,7 @@ export const castVerbs: Verbs = {
       ),
     );
     if (bare) usage(CAST_USAGE);
-    if (!to || !say === !file) usage(CAST_USAGE);
+    if (!to.length || !say === !file) usage(CAST_USAGE);
     const volume =
       o.volume === undefined ? undefined : percentLevel(text(o.volume));
     let type: string;
@@ -160,13 +162,19 @@ export const castVerbs: Verbs = {
       }
       type = "audio/mp4";
     }
-    const r = await withCast((c) =>
-      c.announce(to!, { bytes, type }, { volume }),
+    const results = await withCast((c) =>
+      c.announceAll(to, { bytes, type }, { volume }),
     );
-    if (o.json) return printJson(r);
-    console.log(r.played ? "played" : `not played: ${r.why}`);
-    if (r.restored.length) console.log(`restored: ${r.restored.join(", ")}`);
-    for (const n of r.notRestored)
-      console.log(`not restored: ${n.name}: ${n.why}`);
+    if (results.some((r) => !r.played)) process.exitCode = 1; // docs/cli.md: 1 is a failure, so a script can tell
+    if (o.json) return printJson(to.length === 1 ? results[0] : results);
+    const named = results.length > 1;
+    for (const r of results) {
+      const who = named ? `${r.target}: ` : "";
+      console.log(`${who}${r.played ? "played" : `not played: ${r.why}`}`);
+      if (r.restored.length)
+        console.log(`${who}restored: ${r.restored.join(", ")}`);
+      for (const n of r.notRestored)
+        console.log(`${who}not restored: ${n.name}: ${n.why}`);
+    }
   },
 };

package/src/cli/enphase.ts

@@ -23,7 +23,11 @@ export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
     const { token } = JSON.parse(text) as { token: string };
     return { token, expiresAt: tokenExpiry(token) };
   } catch (error) {
-    return fail(`${TOKEN_FILE}: ${(error as Error).message}`);
+    return fail(
+      `${TOKEN_FILE}: ${(error as Error).message}`,
+      "auth",
+      "home enphase login",
+    );
   }
 }
 

package/src/cli/spotify.ts

@@ -31,7 +31,7 @@ export const spotifyFromEnv = () =>
   });
 
 export const SPOTIFY_USAGE =
-  "usage: home spotify pause | play [link] | next | volume <0-100>";
+  "usage: home spotify activate | pause | play [link] | next | volume <0-100>";
 
 async function withSpotify<T>(
   act: (s: ReturnType<typeof spotify>) => Promise<T>,
@@ -64,6 +64,7 @@ const said = ({ state, confirmed }: Applied) =>
   );
 
 export const spotifyVerbs: Verbs = {
+  activate: () => withSpotify((s) => s.activate()).then(said),
   pause: () => withSpotify((s) => s.pause()).then(said),
   next: () => withSpotify((s) => s.next()).then(said),
   play: ([link]) => withSpotify((s) => s.play(link)).then(said),