@khalido/home 0.1.2 → 0.2.0

package/src/cli/cast.ts

@@ -7,9 +7,12 @@ import { tmpdir } from "node:os";
 import { extname, join } from "node:path";
 import {
   cast,
+  type CastDevice,
   type CastSnapshot,
+  castText,
   resolvedFrom,
 } from "../connectors/cast/index.ts";
+import { findCast } from "../connectors/cast/state.ts";
 import { serveClip } from "../connectors/cast/serve.ts";
 import { tlsConnect } from "../connectors/cast/tls.ts";
 import { addressBook } from "../discover.ts";
@@ -52,7 +55,10 @@ export function castNow() {
 
 /** Open every Cast socket, wait until each has answered (at most 10 s), run one write over them, then close them all. */
 async function withCast<T>(
-  act: (c: ReturnType<typeof castNow>) => Promise<T>,
+  act: (
+    c: ReturnType<typeof castNow>,
+    state: () => CastSnapshot | undefined,
+  ) => Promise<T>,
 ): Promise<T> {
   const c = castNow();
   const stop = new AbortController();
@@ -64,7 +70,7 @@ async function withCast<T>(
       Date.now() < until && (last?.status ?? "connecting") === "connecting";
     )
       await Bun.sleep(50);
-    return await act(c);
+    return await act(c, () => last?.state);
   } finally {
     stop.abort();
     await running;
@@ -105,19 +111,59 @@ export const CAST_OPTIONS: [string, string, { type: unknown[] }?][] = [
   ["--volume <0-100>", "announce: the volume for the clip"],
 ];
 
+/** How long a write waits for the device to report the change before saying it was only sent. */
+const SHOWN_MS = 2000;
+
+/** One write, then the device's line once it reports what was asked, or that it has not yet. */
+const wrote = (
+  name: string,
+  write: (c: ReturnType<typeof castNow>) => Promise<void>,
+  shown: (d: CastDevice) => boolean,
+) =>
+  withCast(async (c, state) => {
+    await write(c);
+    const now = () => {
+      const s = state();
+      const d = s && findCast(s.devices, name);
+      return s && d ? { line: castText(d, s), ok: shown(d) } : undefined;
+    };
+    for (const until = Date.now() + SHOWN_MS; Date.now() < until;) {
+      if (now()?.ok) break;
+      await Bun.sleep(50);
+    }
+    const after = now();
+    console.log(
+      after?.ok
+        ? after.line
+        : `sent; the device has not reported it yet${after ? ` (${after.line})` : ""}`,
+    );
+  });
+
 export const castVerbs: Verbs = {
   async volume([name, value]) {
     if (!name) usage(CAST_USAGE);
     const level = percentLevel(value);
-    await withCast((c) => c.setVolume(name!, level));
+    await wrote(
+      name!,
+      (c) => c.setVolume(name!, level),
+      (d) => d.volume !== undefined && Math.abs(d.volume - level) < 0.006,
+    );
   },
   async mute([name, value]) {
     if (!name || (value !== "on" && value !== "off")) usage(CAST_USAGE);
-    await withCast((c) => c.setMuted(name!, value === "on"));
+    await wrote(
+      name!,
+      (c) => c.setMuted(name!, value === "on"),
+      (d) => d.muted === (value === "on"),
+    );
   },
   async stop([name]) {
     if (!name) usage(CAST_USAGE);
-    await withCast((c) => c.stop(name!));
+    await wrote(
+      name!,
+      (c) => c.stop(name!),
+      (d) => d.idle === true,
+    );
   },
   async announce(_, o) {
     const [say, file] = [text(o.say), text(o.file)];

package/src/cli/context.ts

@@ -38,6 +38,8 @@ export const usage = (message: string): never => fail(message, "usage");
 /** The options cac parses: the global ones, and each command's own. */
 export type Options = {
   json?: boolean;
+  /** `--dry-run`: Hue and Daikin writes check and say what they would send, and send nothing. */
+  dryRun?: boolean;
   config?: string;
   write?: string | true;
   passes?: number | string;

package/src/cli/daikin.ts

@@ -0,0 +1,71 @@
+// `home daikin on|off` and `home daikin cool|heat|auto|dry|fan [°C]`: one write to the AC, then what it reports.
+// Live on KO's unit (2026-11-11): on, and dry to cool at 25. Off, heat, auto, fan and a fan speed are untried.
+import {
+  acText,
+  type DaikinApplied,
+  daikinClient,
+  DEFAULT_TARGET_C,
+  type Mode,
+  setTarget,
+} from "../connectors/daikin/index.ts";
+import { findDaikins } from "../finders.ts";
+import { env, fail, type Options, usage, type Verbs } from "./context.ts";
+
+export const DAIKIN_USAGE = `usage: home daikin on | off | cool [°C] | heat [°C] | auto [°C] | dry | fan  (cool ${DEFAULT_TARGET_C.cool} and heat ${DEFAULT_TARGET_C.heat} when no °C is given)`;
+
+let found: Promise<string | undefined> | undefined;
+/** The unit's address: DAIKIN_HOST, else the first to answer the UDP broadcast (asked once a run). Undefined when none does. */
+export const daikinHost = (): Promise<string | undefined> =>
+  (found ??= env.DAIKIN_HOST
+    ? Promise.resolve(env.DAIKIN_HOST)
+    : findDaikins().then((units) => units[0]?.ip));
+
+async function unit() {
+  const host =
+    (await daikinHost()) ??
+    fail("no Daikin answered the UDP broadcast; set DAIKIN_HOST", "network");
+  return daikinClient({ host, fetch });
+}
+
+/** What a write left, in a line: the unit as it then reported, that it has not reported the change yet, or what a dry run would send. */
+const said = ({ state, confirmed, wouldSend }: DaikinApplied) =>
+  console.log(
+    wouldSend
+      ? `dry run, nothing sent: would set ${JSON.stringify(wouldSend.sets)} (now ${acText(state)})`
+      : confirmed
+        ? acText(state)
+        : `sent; the unit has not reported it yet (${acText(state)})`,
+  );
+
+const power =
+  (on: boolean) =>
+  async ([extra]: string[], o: Options) =>
+    extra
+      ? usage(DAIKIN_USAGE)
+      : said(await (await unit()).power(on, { dryRun: !!o.dryRun }));
+
+const mode =
+  (m: Mode) =>
+  async ([value, extra]: string[], o: Options) => {
+    if (extra || (value !== undefined && !/^\d+(\.\d+)?$/.test(value)))
+      usage(DAIKIN_USAGE);
+    const c = value === undefined ? undefined : Number(value);
+    // A setpoint the mode can't take is a usage error, said before looking for the unit.
+    if (c !== undefined)
+      try {
+        setTarget(c, m);
+      } catch (e) {
+        usage(`${(e as Error).message}; ${DAIKIN_USAGE}`);
+      }
+    said(await (await unit()).mode(m, c, { dryRun: !!o.dryRun }));
+  };
+
+export const daikinVerbs: Verbs = {
+  on: power(true),
+  off: power(false),
+  cool: mode("cool"),
+  heat: mode("heat"),
+  auto: mode("auto"),
+  dry: mode("dry"),
+  fan: mode("fan"),
+};

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/hue.ts

@@ -1,16 +1,20 @@
-// `home lights off`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each.
+// `home lights off`, `home light`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each,
+// then what the bridge reports. The name lookups and the checks are the library's (`client.light`, `room`, `scene`).
 import { readFileSync } from "node:fs";
 import { hostname } from "node:os";
 import {
   bunPinnedFetch,
-  groups,
-  homeGroupedLightId,
+  type GroupView,
+  type HueApplied,
+  type HueRequest,
+  HueError,
   hue,
   hueClient,
-  pair,
-  scenes,
+  hueText,
+  type LightChange,
+  type LightView,
+  pairWhenPressed,
 } from "../connectors/hue/index.ts";
-import { snapshotFrom } from "../connectors/hue/state.ts";
 import { FINDERS } from "../finders.ts";
 import { env, fail, usage, type Verbs } from "./context.ts";
 
@@ -24,12 +28,9 @@ export async function bridge(): Promise<{ host: string; id: string }> {
   return { host: env.HUE_BRIDGE_HOST ?? b.host, id: env.HUE_BRIDGE_ID ?? b.id };
 }
 
+/** HUE_CA_FILE when set; else undefined, and the package's own copy of Signify's roots is used. */
 export const ca = () =>
-  env.HUE_CA_FILE
-    ? readFileSync(env.HUE_CA_FILE, "utf8")
-    : fail(
-        "set HUE_CA_FILE to Signify's root CA (see src/connectors/hue/README.md)",
-      );
+  env.HUE_CA_FILE ? readFileSync(env.HUE_CA_FILE, "utf8") : undefined;
 
 const key = () =>
   env.HUE_APPLICATION_KEY ??
@@ -50,72 +51,159 @@ async function client() {
   });
 }
 
-/** Find one room, zone or scene by name, case-insensitively; a miss lists what exists. */
-function byName<T extends { name?: string }>(
-  items: T[],
-  name: string,
-  what: string,
-): T {
-  return (
-    items.find((i) => i.name?.toLowerCase() === name.toLowerCase()) ??
-    fail(`no ${what} "${name}"; have: ${items.map((i) => i.name).join(", ")}`)
+/** What a write left, in a line: the light or room as the bridge then reported it, or that it has not reported the change yet. */
+const said = ({
+  state,
+  confirmed,
+  wouldSend,
+}: HueApplied<LightView | GroupView>) =>
+  console.log(
+    wouldSend
+      ? dryLine(wouldSend, hueText(state))
+      : confirmed
+        ? hueText(state)
+        : `sent; the bridge has not reported it yet (${hueText(state)})`,
   );
+const dryLine = (r: HueRequest, now: string) =>
+  `dry run, nothing sent: would PUT ${r.path} ${JSON.stringify(r.body)} (now ${now})`;
+
+export const CHANGE_USAGE = "[on|off] [<1-100>] [<kelvin>k] [<hex colour>]";
+/** The words after a name as a change: `on`, `off`, `40` (brightness), `2700k` (white), `ff8800` (colour), in any order. */
+export function changeFrom(words: string[], usageLine: string): LightChange {
+  const change: LightChange = {};
+  for (const w of words) {
+    if (w === "on" || w === "off") {
+      if (change.on !== undefined && change.on !== (w === "on"))
+        usage(`on or off, not both; ${usageLine}`);
+      change.on = w === "on";
+    } else if (/^\d{1,3}%?$/.test(w))
+      change.brightness = Number.parseInt(w, 10);
+    else if (/^\d{4,5}k$/i.test(w)) change.kelvin = Number.parseInt(w, 10);
+    else if (/^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.test(w)) change.color = w;
+    else
+      usage(
+        `"${w}" is not on, off, a brightness, a temperature like 2700k or a colour like ff8800; ${usageLine}`,
+      );
+  }
+  if (!words.length) usage(usageLine);
+  return change;
 }
 
+/** A change the bridge can't make (an unknown name, a value off the light's range) is a usage error; anything else passes through. */
+const orUsage = (e: unknown): never => {
+  if (e instanceof HueError && e.code === "invalid") usage(e.message);
+  throw e;
+};
+
+/** How long `home pair` waits for the button: time to walk to the bridge. */
+const PAIR_WAIT_MS = 60_000;
+
 export const hueVerbs: Verbs = {
-  async lights([state]) {
-    if (state !== "off") usage("usage: home lights off");
-    const c = await client();
-    const id =
-      homeGroupedLightId(snapshotFrom(await c.get(), "")) ??
-      fail("the bridge has no home group");
-    await c.put("grouped_light", id, { on: { on: false } });
+  async lights([word], o) {
+    if (word !== "off") usage("usage: home lights off");
+    const { state, confirmed, wouldSend } = await (
+      await client()
+    )
+      .allOff({ dryRun: !!o.dryRun })
+      .catch(orUsage);
+    const on = state.filter((l) => l.on && l.reachable !== false).length;
+    console.log(
+      wouldSend
+        ? dryLine(wouldSend, `${on} of ${state.length} on`)
+        : confirmed
+          ? `${state.length} lights off`
+          : `sent; the bridge still reports ${on} of ${state.length} on`,
+    );
   },
 
-  async room([name, value]) {
-    if (!name || !value) usage("usage: home room <name> on|off|<1-100>");
-    const c = await client();
-    const room = byName(
-      groups(snapshotFrom(await c.get(), "")),
-      name!,
-      "room or zone",
+  async light([name, ...words], o) {
+    const line = `usage: home light <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .light(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
     );
-    if (!room.groupedLightId) fail(`${room.name} has no grouped light`);
-    const level = Number(value);
-    if (value !== "on" && value !== "off" && !(level >= 1 && level <= 100))
-      usage(`brightness must be 1-100, got ${value}`);
-    const body =
-      value === "on" || value === "off"
-        ? { on: { on: value === "on" } }
-        : { on: { on: true }, dimming: { brightness: level } };
-    await c.put("grouped_light", room.groupedLightId!, body);
   },
 
-  async scene(words) {
-    const name = words.join(" ") || usage("usage: home scene <name>");
+  async room([name, ...words], o) {
+    const line = `usage: home room <name> ${CHANGE_USAGE}`;
+    if (!name) usage(line);
+    const change = changeFrom(words, line);
+    said(
+      await (
+        await client()
+      )
+        .room(name!, change, { dryRun: !!o.dryRun })
+        .catch(orUsage),
+    );
+  },
+
+  async scene(words, o) {
+    const line = "usage: home scene <name> [in <room>]";
+    if (!words.length) usage(line);
     const c = await client();
-    await c.recallScene(
-      byName(scenes(snapshotFrom(await c.get(), "")), name, "scene").id,
+    // "Relax in Bedroom" is the scene Relax in that room, unless a scene is named all of it.
+    const at = words.lastIndexOf("in");
+    const dry = { dryRun: !!o.dryRun };
+    const whole = () => c.scene(words.join(" "), undefined, dry);
+    said(
+      await (
+        at > 0 && at < words.length - 1
+          ? whole().catch(() =>
+              c.scene(
+                words.slice(0, at).join(" "),
+                words.slice(at + 1).join(" "),
+                dry,
+              ),
+            )
+          : whole()
+      ).catch(orUsage),
     );
   },
 
-  async pair() {
+  async pair(_, o) {
+    if (o.dryRun) usage("home pair has no dry run");
     const b = await bridge();
-    const { key } = await pair({
+    console.error(`Hue bridge ${b.id.slice(-6).toUpperCase()} at ${b.host}.`);
+    // The countdown redraws one line on a terminal; piped, it is one line said once.
+    const live = process.stderr.isTTY;
+    const until = Date.now() + PAIR_WAIT_MS;
+    const prompt = () =>
+      `Press the link button on the bridge: ${Math.max(0, Math.ceil((until - Date.now()) / 1000))} s left`;
+    let tick: ReturnType<typeof setInterval> | undefined;
+    const { key } = await pairWhenPressed({
       host: b.host,
       fetch: bunPinnedFetch(b.id, ca()),
       deviceType: `home#${hostname().slice(0, 19)}`,
-    }).catch((e) =>
-      e.code === "link_button"
-        ? fail(
-            "press the link button on the bridge, then pair again within 30 s",
-            "auth",
-            "home pair",
-          )
-        : Promise.reject(e),
-    );
+      timeoutMs: PAIR_WAIT_MS,
+      onWaiting() {
+        if (!live) return console.error(prompt());
+        process.stderr.write(prompt());
+        tick = setInterval(
+          () => process.stderr.write(`\r\x1b[K${prompt()}`),
+          1000,
+        );
+      },
+    })
+      .finally(() => {
+        clearInterval(tick);
+        if (tick) process.stderr.write("\r\x1b[K");
+      })
+      .catch((e) =>
+        e.code === "link_button"
+          ? fail(
+              `no button press detected in ${PAIR_WAIT_MS / 1000} s; nothing was changed`,
+              "auth",
+              "home pair",
+            )
+          : Promise.reject(e),
+      );
     console.error(
-      "Paired. Put this in your shell environment (never in a repo):",
+      "Paired. Put these in your shell environment or .env (never in a repo):",
     );
     console.log(
       `HUE_APPLICATION_KEY=${key}\nHUE_BRIDGE_HOST=${b.host}\nHUE_BRIDGE_ID=${b.id}`,

package/src/cli/main.ts

@@ -14,23 +14,31 @@ import {
   usage,
   type Verbs,
 } from "./context.ts";
+import { DAIKIN_USAGE, daikinVerbs } from "./daikin.ts";
 import { discover } from "./discover.ts";
 import { enphaseVerbs } from "./enphase.ts";
-import { hueVerbs } from "./hue.ts";
+import { CHANGE_USAGE, hueVerbs } from "./hue.ts";
 import { locate } from "./locate.ts";
 import { probe } from "./probe.ts";
 import { SPOTIFY_USAGE, spotifyVerbs } from "./spotify.ts";
-import { status } from "./status.ts";
+import { devices, status } from "./status.ts";
 import { UP_OPTIONS, UP_USAGE, upVerbs } from "./up.ts";
 
 const HUE_HELP: Record<string, string> = {
   lights: "lights off: one write to the whole-home group",
-  room: "room <name> on|off|<1-100>",
-  scene: "scene <name>",
-  pair: "pair: press the bridge's button first; prints the env lines to set",
+  light: `light <name> ${CHANGE_USAGE}`,
+  room: `room <name> ${CHANGE_USAGE}: every light in a room or zone, one write`,
+  scene: "scene <name> [in <room>]",
+  pair: "pair: waits 60 s for the bridge's button, counting down; prints the env lines to set",
 };
 
 /** Each connector's verbs beyond its status, the usage a wrong one prints, and any options of its own. */
+/** Only where a write reads it: on any other command cac refuses it, so `--dry-run` never lets a real write through. */
+const DRY_RUN: [string, string] = [
+  "--dry-run",
+  "check the write and print what would be sent; send nothing",
+];
+
 const VERBS: Record<
   string,
   {
@@ -41,10 +49,12 @@ const VERBS: Record<
 > = {
   hue: {
     verbs: hueVerbs,
+    options: [DRY_RUN],
     usage: `usage: home hue ${Object.values(HUE_HELP)
       .map((h) => h.split(":")[0])
       .join(" | ")}`,
   },
+  daikin: { verbs: daikinVerbs, usage: DAIKIN_USAGE, options: [DRY_RUN] },
   enphase: { verbs: enphaseVerbs, usage: "usage: home enphase login" },
   cast: { verbs: castVerbs, usage: CAST_USAGE, options: CAST_OPTIONS },
   up: { verbs: upVerbs, usage: UP_USAGE, options: UP_OPTIONS },
@@ -66,6 +76,12 @@ const statusCommand = cli
   .alias("doctor")
   .alias("!") // cac's marker for the default command: `home` alone runs status
   .action((o: Options) => status(o));
+cli
+  .command(
+    "devices",
+    "every device the connectors read, one line each: its state, its room, and why when it isn't available",
+  )
+  .action((o: Options) => devices(o));
 cli
   .command(
     "discover",
@@ -123,10 +139,11 @@ for (const m of MANIFESTS) {
   );
 }
 // Hue's verbs also stand alone, as typed before the CLI had `home hue`: `home lights off`, `home room …`, `home scene …`, `home pair`.
-for (const [verb, run] of Object.entries(hueVerbs))
-  cli
-    .command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`)
-    .action((args: string[], o: Options) => run(args, o));
+for (const [verb, run] of Object.entries(hueVerbs)) {
+  const c = cli.command(`${verb} [...args]`, `Hue: ${HUE_HELP[verb]}`);
+  if (verb !== "pair") c.option(...DRY_RUN);
+  c.action((args: string[], o: Options) => run(args, o));
+}
 
 cli.help();
 
@@ -150,7 +167,15 @@ function describe(e: unknown): {
     e instanceof Error &&
     (e.name === "TimeoutError" || e.name === "AbortError" || socket)
   )
-    return { error, code: "network" };
+    return {
+      // macOS answers "no route to host" for a LAN address when the terminal app lacks the Local Network permission.
+      error:
+        (e as { code?: string }).code === "EHOSTUNREACH" &&
+        process.platform === "darwin"
+          ? `${error} If the device is up, allow this terminal under System Settings > Privacy & Security > Local Network.`
+          : error,
+      code: "network",
+    };
   return { error, code: "error" };
 }
 

package/src/cli/probe.ts

@@ -6,6 +6,7 @@ import {
   printerList,
 } from "../connectors/printers/index.ts";
 import { gatewayHost } from "../connectors/enphase/client.ts";
+import { fetchTimeout } from "../connector.ts";
 import { bunPinnedFetch } from "../connectors/hue/index.ts";
 import { type WeatherSource } from "../connectors/weather/index.ts";
 import {
@@ -39,7 +40,7 @@ function envFromConfig(path: string): Record<string, string> {
       Object.assign(out, {
         HUE_BRIDGE_HOST: d.host,
         HUE_BRIDGE_ID: d.bridgeId,
-        HUE_CA_FILE: fromConfig(path, d.ca),
+        HUE_CA_FILE: d.ca && fromConfig(path, d.ca),
         HUE_APPLICATION_KEY: env[d.key],
       });
     if (d.connector === "daikin") out.DAIKIN_HOST = d.host;
@@ -111,25 +112,28 @@ const jsonOr = (body: string) => {
 
 export async function probe(o: Options): Promise<void> {
   const configPath = configPathOf(o);
-  if (configPath) Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  if (configPath) {
+    delete env.HUE_CA_FILE; // the config's `ca` or the package's roots, never the shell's file
+    Object.assign(env, envFromConfig(configPath)); // the config's addresses, for this one command
+  }
   const out: Record<string, unknown> = {};
   try {
     const b = await bridge();
-    const fetchPinned = env.HUE_CA_FILE
-      ? bunPinnedFetch(b.id, ca())
-      : undefined;
-    const r = fetchPinned
-      ? await fetchPinned(`https://${b.host}/api/0/config`).then((x) =>
-          x.json(),
-        )
-      : "needs HUE_CA_FILE";
-    out.hue =
-      typeof r === "string"
-        ? { status: r }
-        : {
-            status: "answers",
-            ...pick(r, ["name", "modelid", "apiversion", "swversion"]),
-          };
+    const r = await fetchTimeout(
+      bunPinnedFetch(b.id, ca()),
+      `https://${b.host}/api/0/config`,
+      {},
+      { timeoutMs: 5000 },
+    ).then((x) => x.json());
+    out.hue = {
+      status: "answers",
+      ...pick(r as Record<string, unknown>, [
+        "name",
+        "modelid",
+        "apiversion",
+        "swversion",
+      ]),
+    };
   } catch (error) {
     out.hue = { status: "unavailable", detail: (error as Error).message };
   }