@khalido/home 0.0.0-stage → 0.1.0

package/src/cli/discover.ts

@@ -0,0 +1,175 @@
+// `home discover [--passes n] [--write [path]]`: what smart-home devices answer on this network, and which this package
+// supports. mDNS (macOS dns-sd) plus Daikin's UDP broadcast; with a config, how they match it.
+import { existsSync, readFileSync, statSync, writeFileSync } from "node:fs";
+import { realClock } from "../clock.ts";
+import { checkPlan, parseJsonc } from "../config.ts";
+import {
+  addressBook,
+  applyFound,
+  discover as discoverAll,
+  DISCOVERY_GAP_MS,
+  DISCOVERY_PASSES,
+  type Found,
+  foundKey,
+  KNOWN_SERVICES,
+  matchFound,
+} from "../discover.ts";
+import { browse, daikinFound, FINDERS, findDaikins } from "../finders.ts";
+import {
+  addresses,
+  configPathOf,
+  fail,
+  type Options,
+  printJson,
+  writeTo,
+} from "./context.ts";
+
+export async function discover(o: Options): Promise<void> {
+  const write = writeTo(o);
+  const path = write || configPathOf(o);
+  if (write !== undefined && !path)
+    fail("--write needs a path, --config or HOME_CONFIG");
+  const text = path ? readFileSync(path, "utf8") : undefined;
+  const plan = text === undefined ? undefined : checkPlan(parseJsonc(text));
+  if (plan && !plan.config) fail(`${path}: ${plan.problems.join("; ")}`);
+  const passes = o.passes === undefined ? undefined : Number(o.passes);
+  if (passes !== undefined && !(Number.isInteger(passes) && passes >= 1))
+    fail(`--passes must be a whole number from 1, got ${o.passes}`);
+  // One pass: every connector's discovery (Daikin's broadcast once), and the instances of every other known mDNS type.
+  type Seen = { what: string; connector?: string; name: string; found?: Found };
+  const what = (c: string) =>
+    c === "daikin"
+      ? "Daikin AC (UDP broadcast)"
+      : Object.values(KNOWN_SERVICES).find((s) => s.connector === c)!.what;
+  const pass = async (): Promise<Seen[]> => {
+    const others = Object.entries(KNOWN_SERVICES).filter(
+      ([, info]) => !info.connector,
+    );
+    const [services, daikins, mdns] = await Promise.all([
+      Promise.all(
+        others.map(async ([type, info]) =>
+          (await browse(type)).map((name) => ({ what: info.what, name })),
+        ),
+      ).then((all) => all.flat()),
+      findDaikins(),
+      Promise.all([
+        FINDERS.hue(),
+        FINDERS.enphase(),
+        FINDERS.cast(),
+        FINDERS.printers(),
+      ]).then((all) => all.flat()),
+    ]);
+    return [
+      ...[...mdns, ...daikins.flatMap(daikinFound)].map((f) => ({
+        what: what(f.connector),
+        connector: f.connector,
+        name: f.name ?? f.id,
+        found: f,
+      })),
+      ...services,
+    ];
+  };
+  const listing = (seen: Seen[]) => {
+    for (const w of [...new Set(seen.map((x) => x.what))]) {
+      const rows = seen.filter((x) => x.what === w);
+      const connector = rows[0]!.connector;
+      console.log(
+        `${w} · ${rows.length} found · ${connector ? `supported: ${connector}` : "not supported"}`,
+      );
+      if (connector) for (const r of rows) console.log(`  ${r.name}`);
+    }
+  };
+  const seen = await discoverAll(pass, {
+    clock: realClock,
+    passes,
+    key: (x) => (x.found ? foundKey(x.found) : `${x.what}:${x.name}`),
+    onPass: (n, added) => {
+      if (o.json) return;
+      const tty = process.stderr.isTTY;
+      const label = (k: number) => (k === 2 ? "second pass" : `pass ${k}`);
+      if (tty && n > 1) process.stderr.write("\r\x1b[K");
+      if (n === 1) listing(added);
+      else
+        console.log(
+          added.length
+            ? added
+                .map((x) => `${label(n)}: found ${x.what}: ${x.name}`)
+                .join("\n")
+            : `${label(n)}: nothing new`,
+        );
+      // The wait before the next pass is otherwise silent: say so on stderr, where a pipe does not see it.
+      if (tty && n < (passes ?? DISCOVERY_PASSES))
+        process.stderr.write(
+          `${label(n + 1)} in ${DISCOVERY_GAP_MS / 1000} s…`,
+        );
+    },
+  });
+  const found = seen.flatMap((x) => (x.found ? [x.found] : []));
+  const rows = [...new Set(seen.map((x) => x.what))].map((w) => {
+    const these = seen.filter((x) => x.what === w);
+    return {
+      what: w,
+      connector: these[0]!.connector,
+      names: these.map((x) => x.name),
+    };
+  });
+  // With a config: match what answers by identity; write moved hosts and new devices only with --write, and only a result that checks.
+  const match = plan?.config && matchFound(plan.config, found);
+  let wrote: string | undefined;
+  const changes = match
+    ? match.moved.length + match.renamed.length + match.added.length
+    : 0;
+  if (match && write !== undefined && changes) {
+    const out = applyFound(text!, match, !!plan!.config!.devices?.length);
+    let after: string[];
+    try {
+      after = checkPlan(parseJsonc(out)).problems;
+    } catch (error) {
+      after = [String(error)];
+    }
+    if (after.length)
+      fail(
+        `${path} not written: the result would have problems: ${after.join("; ")}`,
+      );
+    writeFileSync(path!, out);
+    wrote = `wrote ${path}: ${match.moved.length} moved, ${match.renamed.length} renamed, ${match.added.length} added; check it with \`home config check\``;
+  }
+  // Into the cache after the config is written, against its new time, so every address just confirmed is fresh.
+  const book = addressBook(addresses.cache, {
+    configAt: path && existsSync(path) ? statSync(path).mtimeMs : undefined,
+  });
+  for (const f of found)
+    book.seen(f.connector, f.id, {
+      host: f.host,
+      port: f.port,
+      name: f.connector === "cast" ? f.name : undefined,
+    });
+  if (o.json) return printJson(match ? { services: rows, match, wrote } : rows);
+  if (!match) return;
+  console.log(`\n${path}:`);
+  for (const k of match.known)
+    console.log(
+      `known   ${k.connector} ${k.id}${k.hint ? ` · ${k.hint}` : ""}`,
+    );
+  for (const m of match.moved)
+    console.log(`moved   ${m.connector} ${m.id}: ${m.from} → ${m.to}`);
+  for (const r of match.renamed)
+    console.log(`renamed ${r.connector} ${r.id}: "${r.from}" → "${r.to}"`);
+  for (const a of match.added)
+    console.log(
+      `new     ${a.found.connector} ${a.found.name ? `"${a.found.name}" ` : ""}${a.found.id} at ${a.found.host}`,
+    );
+  for (const s of match.skipped)
+    console.log(
+      `skipped ${s.found.connector} ${s.found.id} at ${s.found.host} · ${s.why}`,
+    );
+  if (!found.length)
+    console.error("home: nothing answered (mDNS and the Daikin broadcast)");
+  else if (write === undefined)
+    console.error(
+      changes
+        ? `home: run with --write ${path} to update it`
+        : "home: the config is current",
+    );
+  else console.error(`home: ${wrote ?? "nothing to write"}`);
+}

package/src/cli/enphase.ts

@@ -0,0 +1,62 @@
+// `home enphase login`: mint the owner token once a year and keep it owner-only.
+import { readFileSync } from "node:fs";
+import {
+  bunGatewayFetch,
+  enphase,
+  mintToken,
+  tokenExpiry,
+} from "../connectors/enphase/index.ts";
+import { daysLeft } from "../connectors/enphase/client.ts";
+import { writePrivate } from "../finders.ts";
+import { env, fail, homeTimeZone, TOKEN_FILE, type Verbs } from "./context.ts";
+
+/** The cached Enphase token, or undefined if `home enphase login` has not run. A corrupt file throws, naming it. */
+export function enphaseToken(): { token: string; expiresAt: Date } | undefined {
+  let text: string;
+  try {
+    text = readFileSync(TOKEN_FILE, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+    throw error;
+  }
+  try {
+    const { token } = JSON.parse(text) as { token: string };
+    return { token, expiresAt: tokenExpiry(token) };
+  } catch (error) {
+    return fail(`${TOKEN_FILE}: ${(error as Error).message}`);
+  }
+}
+
+/** Enphase as an integration from IQ_GATEWAY_HOST and the token file, for `home status`. */
+export function enphaseFromEnv() {
+  const t =
+    enphaseToken() ?? fail("no Enphase token", "auth", "home enphase login");
+  return enphase({
+    host: env.IQ_GATEWAY_HOST!,
+    token: t.token,
+    fetch: bunGatewayFetch(),
+    timeZone: homeTimeZone(),
+  });
+}
+
+export const enphaseVerbs: Verbs = {
+  /** Mint the owner token and cache it. Prints the days left, nothing else. */
+  async login() {
+    const need = (n: string) => env[n] ?? fail(`set ${n}`);
+    const { token, expiresAt } = await mintToken({
+      username: need("ENPHASE_USERNAME"),
+      password: need("ENPHASE_PASSWORD"),
+      serial: need("IQ_GATEWAY_SERIAL_NUMBER"),
+      fetch,
+    });
+    writePrivate(
+      TOKEN_FILE,
+      JSON.stringify({
+        token,
+        expiresAt: expiresAt.toISOString(),
+        mintedAt: new Date().toISOString(),
+      }),
+    );
+    console.log(`${daysLeft(expiresAt, new Date())} days left`);
+  },
+};

package/src/cli/hue.ts

@@ -0,0 +1,124 @@
+// `home lights off`, `home room`, `home scene`, `home pair` (also as `home hue <verb>`): one write to the bridge each.
+import { readFileSync } from "node:fs";
+import { hostname } from "node:os";
+import {
+  bunPinnedFetch,
+  groups,
+  homeGroupedLightId,
+  hue,
+  hueClient,
+  pair,
+  scenes,
+} 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";
+
+/** The bridge from HUE_BRIDGE_HOST and HUE_BRIDGE_ID, else found by mDNS, cached nowhere. */
+export async function bridge(): Promise<{ host: string; id: string }> {
+  if (env.HUE_BRIDGE_HOST && env.HUE_BRIDGE_ID)
+    return { host: env.HUE_BRIDGE_HOST, id: env.HUE_BRIDGE_ID };
+  const b =
+    (await FINDERS.hue())[0] ??
+    fail("no Hue bridge found by mDNS; set HUE_BRIDGE_HOST and HUE_BRIDGE_ID");
+  return { host: env.HUE_BRIDGE_HOST ?? b.host, id: env.HUE_BRIDGE_ID ?? b.id };
+}
+
+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)",
+      );
+
+const key = () =>
+  env.HUE_APPLICATION_KEY ??
+  fail("set HUE_APPLICATION_KEY", "auth", "home pair");
+
+/** Hue as an integration from the shell's env names, for `home status`. */
+export async function hueFromEnv() {
+  const b = await bridge();
+  return hue({ host: b.host, bridgeId: b.id, key: key(), ca: ca() });
+}
+
+async function client() {
+  const b = await bridge();
+  return hueClient({
+    host: b.host,
+    key: key(),
+    fetch: bunPinnedFetch(b.id, ca()),
+  });
+}
+
+/** 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(", ")}`)
+  );
+}
+
+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 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",
+    );
+    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>");
+    const c = await client();
+    await c.recallScene(
+      byName(scenes(snapshotFrom(await c.get(), "")), name, "scene").id,
+    );
+  },
+
+  async pair() {
+    const b = await bridge();
+    const { key } = await pair({
+      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),
+    );
+    console.error(
+      "Paired. Put this in your shell environment (never in a repo):",
+    );
+    console.log(
+      `HUE_APPLICATION_KEY=${key}\nHUE_BRIDGE_HOST=${b.host}\nHUE_BRIDGE_ID=${b.id}`,
+    );
+  },
+};

package/src/cli/locate.ts

@@ -0,0 +1,47 @@
+// `home locate "<street address>" [--write [path]]`: the address's latitude and longitude from OpenStreetMap's Nominatim,
+// printed; with --write, set in the config's `location` (and its `timezone`, when absent, to this machine's). The address
+// itself goes only into the one query, never into the config or a file.
+import { readFileSync, writeFileSync } from "node:fs";
+import { checkPlan, parseJsonc } from "../config.ts";
+import { applyLocation, geocode } from "../locate.ts";
+import {
+  configPathOf,
+  fail,
+  type Options,
+  printJson,
+  usage,
+  writeTo,
+} from "./context.ts";
+
+export async function locate(words: string[], o: Options): Promise<void> {
+  const address =
+    words.join(" ").trim() ||
+    usage(
+      'usage: home locate "<street address>" [--write [path]]   (the address first: a word after --write is its path)',
+    );
+  const { version } = JSON.parse(
+    readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
+  ) as { version: string };
+  const at =
+    (await geocode(address, { fetch, userAgent: `khalido-home/${version}` })) ??
+    fail("Nominatim found no match; try the street, suburb and state");
+  const write = writeTo(o);
+  if (o.json && write === undefined) return printJson(at);
+  console.log(`${at.name}\n${at.latitude}, ${at.longitude}`);
+  if (write === undefined) return;
+  const path =
+    write ||
+    configPathOf(o) ||
+    fail("--write needs a path, --config or HOME_CONFIG");
+  const timeZone = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  const r = applyLocation(readFileSync(path, "utf8"), at, timeZone);
+  const problems = checkPlan(parseJsonc(r.text)).problems;
+  if (problems.length)
+    fail(
+      `${path} not written: the result would have problems: ${problems.join("; ")}`,
+    );
+  writeFileSync(path, r.text);
+  console.log(
+    `wrote ${path}: location ${at.latitude}, ${at.longitude}${r.timezoneSet ? `, timezone ${timeZone}` : ""}${r.fresh ? " (a new location object: the config had none, or only a commented-out one, left as it was)" : ""}`,
+  );
+}

package/src/cli/main.ts

@@ -0,0 +1,182 @@
+#!/usr/bin/env bun
+// `home`: the terminal layer. Commands come from cac; one `home <connector>` per manifest, its verbs from src/cli/<connector>.ts.
+import { cac } from "cac";
+import { ConnectorError, errorText } from "../connector.ts";
+import { MANIFESTS } from "../manifests.ts";
+import { cacheCommand } from "./cache.ts";
+import { CAST_OPTIONS, CAST_USAGE, castVerbs } from "./cast.ts";
+import { configCommand } from "./config.ts";
+import {
+  addresses,
+  CliError,
+  type ErrorCode,
+  type Options,
+  usage,
+  type Verbs,
+} from "./context.ts";
+import { discover } from "./discover.ts";
+import { enphaseVerbs } from "./enphase.ts";
+import { 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 { 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",
+};
+
+/** Each connector's verbs beyond its status, the usage a wrong one prints, and any options of its own. */
+const VERBS: Record<
+  string,
+  {
+    verbs: Verbs;
+    usage: string;
+    options?: [string, string, { type: unknown[] }?][];
+  }
+> = {
+  hue: {
+    verbs: hueVerbs,
+    usage: `usage: home hue ${Object.values(HUE_HELP)
+      .map((h) => h.split(":")[0])
+      .join(" | ")}`,
+  },
+  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 },
+  spotify: { verbs: spotifyVerbs, usage: SPOTIFY_USAGE },
+};
+
+const cli = cac("home");
+cli.option("--json", "print JSON");
+cli.option(
+  "--config <path>",
+  "a home config (JSONC); else HOME_CONFIG, else the env names in .env.example",
+);
+
+const statusCommand = cli
+  .command(
+    "status",
+    "each integration: connected or not, which env names it still needs (the default)",
+  )
+  .alias("doctor")
+  .alias("!") // cac's marker for the default command: `home` alone runs status
+  .action((o: Options) => status(o));
+cli
+  .command(
+    "discover",
+    "which smart-home devices answer here (mDNS + Daikin UDP); with a config, how they match it",
+  )
+  .option("--passes <n>", "discovery passes, 5 s apart (default 2)")
+  .option(
+    "--write [path]",
+    "match what answers by identity: add new devices, update moved hosts and renamed Cast names in the config",
+  )
+  .action((o: Options) => discover(o));
+cli
+  .command(
+    "probe",
+    "read-only, no keys: Hue's public config, Daikin, the IQ Gateway's /info, each Cast device, each printer, each weather source",
+  )
+  .action((o: Options) => probe(o));
+cli
+  .command(
+    "config [verb] [path]",
+    "config check [path]: what a home config would set up, secrets as set or unset, every problem",
+  )
+  .action(configCommand);
+cli
+  .command(
+    "cache [verb]",
+    "the addresses kept between runs; `cache clear` deletes them",
+  )
+  .action(cacheCommand);
+cli
+  .command(
+    "locate [...address]",
+    "latitude and longitude of a street address from OpenStreetMap's Nominatim",
+  )
+  .option(
+    "--write [path]",
+    "set them in the config's location (and timezone, when absent)",
+  )
+  .action(locate);
+
+for (const m of MANIFESTS) {
+  const v = VERBS[m.name];
+  const c = cli.command(
+    `${m.name} [verb] [...args]`,
+    `${m.title}: its status${v ? `; ${Object.keys(v.verbs).join(", ")}` : ""}`,
+  );
+  for (const [raw, what, config] of v?.options ?? [])
+    c.option(raw, what, config);
+  c.action((verb: string | undefined, args: string[], o: Options) =>
+    verb === undefined
+      ? status(o, m.name)
+      : (v && Object.hasOwn(v.verbs, verb)
+          ? v.verbs[verb]!
+          : () => usage(v?.usage ?? `usage: home ${m.name}`))(args, o),
+  );
+}
+// 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));
+
+cli.help();
+
+/** An error as `home` reports it: what went wrong, a coarse code, and the command that fixes it when there is one. */
+function describe(e: unknown): {
+  error: string;
+  code: ErrorCode;
+  fix?: string;
+} {
+  const error = errorText(e);
+  if (e instanceof CliError) return { error, code: e.code, fix: e.fix };
+  if (e instanceof Error && e.name === "CACError")
+    return { error, code: "usage" }; // cac: a missing argument or an unknown option
+  if (e instanceof ConnectorError && (e.status === 401 || e.status === 403))
+    return { error, code: "auth" };
+  // A timeout, or a socket error Bun and Node tag with a code (ECONNREFUSED, ENOTFOUND). A bare TypeError is more likely a bug.
+  const socket =
+    typeof (e as { code?: unknown })?.code === "string" &&
+    /^E[A-Z]+$/.test((e as { code: string }).code);
+  if (
+    e instanceof Error &&
+    (e.name === "TimeoutError" || e.name === "AbortError" || socket)
+  )
+    return { error, code: "network" };
+  return { error, code: "error" };
+}
+
+let failed: unknown;
+try {
+  cli.parse(process.argv, { run: false });
+  if (cli.matchedCommand === statusCommand && cli.args.length)
+    usage(`unknown command "${cli.args[0]}"; \`home --help\` lists them`);
+  else await cli.runMatchedCommand();
+} catch (e) {
+  failed = e ?? "failed";
+} finally {
+  // Addresses discovery confirmed are kept whether the command succeeded or not; a cache that cannot be written is a warning, not a failure.
+  try {
+    addresses.flush();
+  } catch (e) {
+    console.error(`home: address cache not written: ${errorText(e)}`);
+  }
+}
+// stdout is data, stderr everything else: under --json an error is one JSON object on stderr. Exit 2 for usage, 1 for the rest.
+if (failed !== undefined) {
+  const r = describe(failed);
+  console.error(
+    process.argv.includes("--json")
+      ? JSON.stringify(r)
+      : `home: ${r.error}${r.fix ? ` (run \`${r.fix}\`)` : ""}`,
+  );
+  process.exit(r.code === "usage" ? 2 : 1);
+}

package/src/cli/printers.ts

@@ -0,0 +1,21 @@
+// Printers without a config: what `home status`, `home printers` and `home probe` run. Cached addresses first, then
+// discovery (AirPrint over mDNS) finds the rest. Read-only; the integration has no writes yet.
+import { printers } from "../connectors/printers/index.ts";
+import { addressBook } from "../discover.ts";
+import { FINDERS } from "../finders.ts";
+import { addresses } from "./context.ts";
+
+/** Every printer the address cache knows plus whatever discovery finds, read once. */
+export function printersNow() {
+  const book = addressBook(addresses.cache);
+  const known = Object.entries(book.entries()).flatMap(([key, c]) =>
+    key.startsWith("printers:")
+      ? [{ uuid: key.slice(9), name: c.name, host: c.host, port: c.port }]
+      : [],
+  );
+  return printers({
+    printers: known,
+    find: FINDERS.printers,
+    seen: (uuid, a) => book.seen("printers", uuid, a),
+  });
+}