@khalido/home 0.0.0-stage → 0.1.1

package/src/cli/probe.ts

@@ -0,0 +1,274 @@
+// `home probe`: read-only checks that need no key: Hue's public config, Daikin discovery and state, the IQ Gateway's
+// /info, each Cast device's status, each printer's status, each weather source.
+import { type CastSnapshot, castDevices } from "../connectors/cast/index.ts";
+import {
+  type PrintersState,
+  printerList,
+} from "../connectors/printers/index.ts";
+import { gatewayHost } from "../connectors/enphase/client.ts";
+import { bunPinnedFetch } from "../connectors/hue/index.ts";
+import { type WeatherSource } from "../connectors/weather/index.ts";
+import {
+  DEFAULT_POLL_MINUTES,
+  sourcePollMinutes,
+} from "../connectors/weather/source.ts";
+import { checkHome } from "../config.ts";
+import { daikinFields, findDaikins } from "../finders.ts";
+import { castNow } from "./cast.ts";
+import { printersNow } from "./printers.ts";
+import { settle } from "../home.ts";
+import {
+  configPathOf,
+  env,
+  fail,
+  fromConfig,
+  type Options,
+  printJson,
+  readConfig,
+} from "./context.ts";
+import { bridge, ca } from "./hue.ts";
+import { place, weatherSources } from "./status.ts";
+
+/** The env names `probe` reads, filled from a config's addresses (secrets by the names it gives), so probe needs no second reading of it. */
+function envFromConfig(path: string): Record<string, string> {
+  const { config, problems } = checkHome(readConfig(path), env);
+  if (!config) fail(`${path}: ${problems.join("; ")}`);
+  const out: Record<string, string | undefined> = {};
+  for (const d of config!.devices ?? []) {
+    if (d.connector === "hue")
+      Object.assign(out, {
+        HUE_BRIDGE_HOST: d.host,
+        HUE_BRIDGE_ID: d.bridgeId,
+        HUE_CA_FILE: fromConfig(path, d.ca),
+        HUE_APPLICATION_KEY: env[d.key],
+      });
+    if (d.connector === "daikin") out.DAIKIN_HOST = d.host;
+    if (d.connector === "enphase") out.IQ_GATEWAY_HOST = d.host;
+    if (d.connector === "amber")
+      Object.assign(out, { AMBER_KEY: env[d.key], AMBER_SITE_ID: d.siteId });
+  }
+  const at = config!.location;
+  if (at)
+    Object.assign(out, {
+      HOME_LATITUDE: String(at.latitude),
+      HOME_LONGITUDE: String(at.longitude),
+      HOME_BOM_FORECAST: at.bomForecast,
+    });
+  const g = config!.weather?.googleKey;
+  if (g) out.GOOGLE_WEATHER_KEY = env[g];
+  return Object.fromEntries(
+    Object.entries(out).filter(
+      (e): e is [string, string] => e[1] !== undefined,
+    ),
+  );
+}
+
+/** GET a URL and return its text, or the error, within 5 s. */
+const tryGet = (url: string, init: RequestInit = {}) =>
+  fetch(url, { ...init, signal: AbortSignal.timeout(5000) }).then(
+    async (r) => ({ status: r.status, body: await r.text() }),
+    (e: Error) => ({ status: 0, body: e.message }),
+  );
+
+const pick = (o: Record<string, unknown>, keys: string[]) =>
+  Object.fromEntries(keys.map((k) => [k, o[k]]));
+
+/** What `basic_info` and the UDP answer may show: the adapter and firmware, never its name, MAC, Wi-Fi name or password. */
+const DAIKIN_SHOWN = [
+  "ret",
+  "type",
+  "reg",
+  "ver",
+  "rev",
+  "adp_kind",
+  "pv",
+  "cpv",
+  "method",
+  "err",
+  "en_setzone",
+];
+
+/** The BRP084 reply's response codes only: its `adp_i` node holds the adapter's MAC (pydaikin reads it there). */
+const answered = (reply: {
+  responses?: { fr?: string; rsc?: number }[];
+  notJson?: string;
+}) =>
+  reply.notJson
+    ? reply
+    : {
+        status: "answers",
+        responses: reply.responses?.map((r) => ({ from: r.fr, code: r.rsc })),
+      };
+
+/** JSON, or the start of the body as text when it is not. */
+const jsonOr = (body: string) => {
+  try {
+    return JSON.parse(body);
+  } catch {
+    return { notJson: body.slice(0, 80) };
+  }
+};
+
+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
+  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"]),
+          };
+  } catch (error) {
+    out.hue = { status: "unavailable", detail: (error as Error).message };
+  }
+  const daikins = env.DAIKIN_HOST
+    ? [{ ip: env.DAIKIN_HOST, fields: {} }]
+    : await findDaikins();
+  out.daikin = daikins.length
+    ? await Promise.all(
+        daikins.map(async (d) => {
+          const info = await tryGet(`http://${d.ip}/common/basic_info`);
+          const control = await tryGet(
+            `http://${d.ip}/aircon/get_control_info`,
+          );
+          const sensor = await tryGet(`http://${d.ip}/aircon/get_sensor_info`);
+          const f = (r: { status: number; body: string }) =>
+            r.status === 200
+              ? daikinFields(r.body)
+              : { status: r.status, error: r.body.slice(0, 80) };
+          const shown = (r: typeof info) =>
+            r.status === 200 ? pick(daikinFields(r.body), DAIKIN_SHOWN) : f(r);
+          const result: Record<string, unknown> = {
+            ip: d.ip,
+            udp: pick(d.fields, DAIKIN_SHOWN),
+            basic_info: shown(info),
+            control_info: f(control),
+            sensor_info: f(sensor),
+          };
+          if (info.status === 404) {
+            // Not the BRP069 API. Try the newer JSON one (BRP084): op 2 is a read of the adapter's info, as pydaikin does.
+            const body = JSON.stringify({
+              requests: [
+                { op: 2, to: "/dsiot/edge.adp_i" },
+                {
+                  op: 2,
+                  to: "/dsiot/edge/adr_0100.dgc_status?filter=pv,pt,md",
+                },
+              ],
+            });
+            const r = await tryGet(`http://${d.ip}/dsiot/multireq`, {
+              method: "POST",
+              headers: { "content-type": "application/json" },
+              body,
+            });
+            result.dsiot =
+              r.status === 200
+                ? answered(jsonOr(r.body))
+                : { status: r.status, error: r.body.slice(0, 80) };
+          }
+          return result;
+        }),
+      )
+    : {
+        status:
+          "no answer to the UDP broadcast; set DAIKIN_HOST to try one address",
+      };
+  const gateway = env.IQ_GATEWAY_HOST && gatewayHost(env.IQ_GATEWAY_HOST);
+  if (gateway) {
+    // Bun cannot verify the gateway's chain (README); this unauthenticated read sends nothing secret.
+    const r = await tryGet(`https://${gateway}/info`, {
+      tls: { rejectUnauthorized: false },
+    } as RequestInit);
+    const tag = (t: string) =>
+      r.body.match(new RegExp(`<${t}>([^<]*)</${t}>`))?.[1];
+    const serial = tag("sn");
+    out.enphase =
+      r.status === 200
+        ? {
+            status: "answers",
+            software: tag("software") ?? tag("version"),
+            part: tag("pn"),
+            serialMatchesEnv: env.IQ_GATEWAY_SERIAL_NUMBER
+              ? serial === env.IQ_GATEWAY_SERIAL_NUMBER
+              : "IQ_GATEWAY_SERIAL_NUMBER unset",
+          }
+        : {
+            status: "unavailable",
+            detail: `${r.status} ${r.body.slice(0, 80)}`,
+          };
+  } else out.enphase = { status: "needs IQ_GATEWAY_HOST" };
+  // Cast: connect to every device and group, read receiver (and group) status, close. Nothing is launched or changed.
+  const c = (await settle([castNow()], { ms: 10_000 })).cast!;
+  const devices = (c.state as CastSnapshot | undefined)?.devices ?? {};
+  out.cast = {
+    status: c.status,
+    detail: c.detail,
+    anomaly: c.anomaly,
+    devices: castDevices({ devices, asOf: "" }).map(
+      ({ host: _, asOf: __, ...d }) => d,
+    ),
+  };
+  // Printers: one Get-Printer-Attributes to each AirPrint printer that answers mDNS (or the address cache). Nothing is sent but the read.
+  const pr = (await settle([printersNow()], { ms: 15_000 })).printers!;
+  out.printers = {
+    status: pr.status,
+    detail: pr.detail,
+    anomaly: pr.anomaly,
+    printers: printerList(
+      (pr.state as PrintersState | undefined) ?? { printers: {}, asOf: "" },
+    ).map(({ host: _, asOf: __, ...p }) => p),
+  };
+  const needs = ["HOME_LATITUDE", "HOME_LONGITUDE"].filter((n) => !env[n]);
+  if (needs.length) out.weather = { status: `needs ${needs.join(", ")}` };
+  else {
+    const at = place();
+    const now = Date.now();
+    const probeOne = async (source: WeatherSource) => {
+      const t = performance.now();
+      const r = await source.read({
+        place: at,
+        at: now,
+        pollMinutes: sourcePollMinutes(source, DEFAULT_POLL_MINUTES),
+      });
+      const when = (s?: { at: string; modelled: boolean }) =>
+        s ? `${s.at}${s.modelled ? " (modelled)" : ""}` : undefined;
+      return {
+        status: r.stop
+          ? "unavailable"
+          : r.now || r.forecast || r.sky || r.rain
+            ? "answers"
+            : "no data",
+        ms: Math.round(performance.now() - t),
+        now: when(r.now),
+        station: r.now?.station,
+        forecastIssued: r.forecast?.issuedAt ?? when(r.forecast),
+        sky: when(r.sky),
+        rain: when(r.rain),
+        problem: r.stop ?? r.problem,
+        anomaly: r.anomaly,
+      };
+    };
+    const probed = await Promise.all(
+      weatherSources().map(async (s) => [s.name, await probeOne(s)] as const),
+    );
+    out.weather = {
+      ...Object.fromEntries(probed),
+      ...(env.GOOGLE_WEATHER_KEY
+        ? {}
+        : { google: { status: "no key: set GOOGLE_WEATHER_KEY" } }),
+    };
+  }
+  printJson(out);
+}

package/src/cli/spotify.ts

@@ -0,0 +1,76 @@
+// `home spotify pause|play [link]|next|volume <0-100>`: one write to the Soloist speaker. Opens the socket, waits for
+// Soloist to answer (at most 5 s), sends the command and closes.
+import { spotify } from "../connectors/spotify/index.ts";
+import type { Part } from "../home.ts";
+import {
+  type Applied,
+  type SpotifyState,
+  spotifyText,
+} from "../connectors/spotify/index.ts";
+import { env, fail, usage, type Verbs } from "./context.ts";
+
+/** SOLOIST_MAX_VOLUME as a number 0–100, or undefined when unset. */
+function maxVolume(): number | undefined {
+  const raw = env.SOLOIST_MAX_VOLUME;
+  if (!raw) return undefined;
+  const n = Number(raw);
+  return Number.isInteger(n) && n >= 0 && n <= 100
+    ? n
+    : fail(`SOLOIST_MAX_VOLUME: a whole number 0-100, not ${raw}`);
+}
+
+/** The speaker from SOLOIST_WS and SOLOIST_MAX_VOLUME, for `home status` and the verbs: both need SOLOIST_WS. */
+export const spotifyFromEnv = () =>
+  spotify({
+    url:
+      env.SOLOIST_WS ||
+      fail(
+        "needs SOLOIST_WS, Soloist's --ws address as a URL (see .env.example)",
+      ),
+    maxVolume: maxVolume(),
+  });
+
+export const SPOTIFY_USAGE =
+  "usage: home spotify pause | play [link] | next | volume <0-100>";
+
+async function withSpotify<T>(
+  act: (s: ReturnType<typeof spotify>) => Promise<T>,
+): Promise<T> {
+  const s = spotifyFromEnv();
+  const stop = new AbortController();
+  let last: Part<SpotifyState> | undefined;
+  const running = s.run(stop.signal, (p) => (last = p));
+  try {
+    for (
+      const until = Date.now() + 5000;
+      Date.now() < until && (last?.status ?? "connecting") === "connecting";
+    )
+      await Bun.sleep(50);
+    if (last?.status !== "connected")
+      fail(last?.detail ?? "Soloist did not answer in 5 s", "network");
+    return await act(s);
+  } finally {
+    stop.abort();
+    await running;
+  }
+}
+
+/** What a write left, in a line: the speaker as Soloist then reported it, or that it has not reported the change yet. */
+const said = ({ state, confirmed }: Applied) =>
+  console.log(
+    confirmed
+      ? spotifyText(state)
+      : `sent; Soloist has not reported it yet (${spotifyText(state)})`,
+  );
+
+export const spotifyVerbs: Verbs = {
+  pause: () => withSpotify((s) => s.pause()).then(said),
+  next: () => withSpotify((s) => s.next()).then(said),
+  play: ([link]) => withSpotify((s) => s.play(link)).then(said),
+  async volume([value]) {
+    const n = Number(value);
+    if (value === undefined || value.trim() === "" || !(n >= 0 && n <= 100))
+      usage(SPOTIFY_USAGE);
+    said(await withSpotify((s) => s.setVolume(n)));
+  },
+};

package/src/cli/status.ts

@@ -0,0 +1,228 @@
+// `home status` and `home <connector>`: build each integration (from a config, else from the shell's env names), run
+// them until each has answered, and print each through its connector's manifest.
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { amber } from "../connectors/amber/index.ts";
+import { tlsConnect } from "../connectors/cast/tls.ts";
+import { daikin } from "../connectors/daikin/index.ts";
+import {
+  bom,
+  google,
+  openMeteo,
+  weather,
+  type WeatherSource,
+} from "../connectors/weather/index.ts";
+import { ftpFetch } from "../connectors/weather/ftp.ts";
+import { loadHome } from "../config.ts";
+import { energyNow, gridText } from "../energy.ts";
+import { FINDERS } from "../finders.ts";
+import { type Integration, type Part, type Status, settle } from "../home.ts";
+import { kw, type Manifest } from "../manifest.ts";
+import { MANIFESTS, manifestOf } from "../manifests.ts";
+import { castNow } from "./cast.ts";
+import { printersNow } from "./printers.ts";
+import { spotifyFromEnv } from "./spotify.ts";
+import {
+  addresses,
+  CliError,
+  configPathOf,
+  env,
+  fail,
+  fromConfig,
+  homeTimeZone,
+  type Options,
+  printJson,
+  readConfig,
+  TOKEN_FILE,
+} from "./context.ts";
+import { enphaseFromEnv } from "./enphase.ts";
+import { hueFromEnv } from "./hue.ts";
+import { upFromEnv } from "./up.ts";
+
+/** One connector's row: its part, or "not set up" with the env names (and steps) it still needs. */
+type Row = Omit<Part, "status"> & {
+  status: Status | "not set up";
+  needs: string[];
+};
+
+/** HOME_LATITUDE and HOME_LONGITUDE as numbers; the manifest's `needs` has already checked they are set. */
+export function place(): { latitude: number; longitude: number } {
+  const latitude = Number(env.HOME_LATITUDE);
+  const longitude = Number(env.HOME_LONGITUDE);
+  return Number.isFinite(latitude) && Number.isFinite(longitude)
+    ? { latitude, longitude }
+    : fail("HOME_LATITUDE and HOME_LONGITUDE must be numbers");
+}
+
+/** The weather sources KO's env sets up, in preference order: BOM (opt-in, with the FTP transport), Open-Meteo, then Google if keyed, as the last resort. */
+export const weatherSources = (): WeatherSource[] => [
+  bom({ fetch: ftpFetch(), forecastLocation: env.HOME_BOM_FORECAST }),
+  openMeteo(),
+  ...(env.GOOGLE_WEATHER_KEY ? [google({ key: env.GOOGLE_WEATHER_KEY })] : []),
+];
+
+/**
+ * Each connector from the shell's env names, once the manifest's non-optional names are set. `needs` adds a step that
+ * is not an env name (Enphase's token file). Addresses come from the env only; `home probe` and `home discover` search.
+ */
+const FROM_ENV: Record<
+  string,
+  {
+    needs?: () => string[];
+    build: () => Integration<any> | Promise<Integration<any>>;
+  }
+> = {
+  hue: { build: hueFromEnv },
+  daikin: { build: () => daikin({ host: env.DAIKIN_HOST!, fetch }) },
+  enphase: {
+    needs: () => (existsSync(TOKEN_FILE) ? [] : ["`home enphase login`"]),
+    build: enphaseFromEnv,
+  },
+  amber: {
+    build: () =>
+      amber({ key: env.AMBER_KEY!, siteId: env.AMBER_SITE_ID, fetch }),
+  },
+  up: { build: upFromEnv },
+  weather: {
+    build: () =>
+      weather({
+        ...place(),
+        sources: weatherSources(),
+        timeZone: homeTimeZone(),
+      }),
+  },
+  cast: { build: castNow },
+  printers: { build: printersNow },
+  spotify: { build: spotifyFromEnv },
+};
+
+/** The rows for these manifests from the shell: not set up, failed to build, or run until each has answered. */
+async function statusFromEnv(
+  manifests: Manifest[],
+): Promise<Record<string, Row>> {
+  const rows: Record<string, Row> = {};
+  const built = await Promise.all(
+    // in parallel: Hue's build can wait on mDNS
+    manifests.map(async (m): Promise<Integration<any>[]> => {
+      const from = FROM_ENV[m.name]!;
+      const needs = [
+        ...m.env.filter((e) => !e.optional && !env[e.name]).map((e) => e.name),
+        ...(from.needs?.() ?? []),
+      ];
+      rows[m.name] = {
+        status: needs.length ? "not set up" : "connecting",
+        needs,
+      };
+      if (needs.length) return [];
+      try {
+        return [await from.build()];
+      } catch (error) {
+        const fix =
+          error instanceof CliError && error.fix
+            ? ` (run \`${error.fix}\`)`
+            : "";
+        rows[m.name] = {
+          status: "unavailable",
+          needs,
+          detail: `${(error as Error).message}${fix}`,
+        };
+        return [];
+      }
+    }),
+  );
+  for (const [name, part] of Object.entries(
+    (await settle(built.flat())) as Record<string, Part>,
+  ))
+    rows[name] = { ...part, needs: [] };
+  return rows;
+}
+
+/** The rows from a config: its integrations (or the one named) run until each has answered (weather: every source), at most 15 s. */
+async function statusFromConfig(
+  path: string,
+  only?: string,
+): Promise<Record<string, Row>> {
+  const options = {
+    env,
+    readFile: (p: string) => readFileSync(fromConfig(path, p), "utf8"),
+    ftpFetch: ftpFetch(),
+    finders: FINDERS,
+    castConnect: tlsConnect,
+    cache: addresses.cache,
+    configAt: statSync(path).mtimeMs,
+  };
+  const all = loadHome(readConfig(path), options);
+  const integrations =
+    only === undefined ? all : all.filter((i) => i.name === only);
+  if (!integrations.length) fail(`no ${only} in ${path}`);
+  return Object.fromEntries(
+    Object.entries(await settle(integrations)).map(([name, p]) => [
+      name,
+      { ...p, needs: [] },
+    ]),
+  );
+}
+
+/** A row as `--json` prints it: status, needs and access, then the state as the connector's manifest shapes it. */
+function rowRecord(name: string, r: Row): Record<string, unknown> {
+  const m = manifestOf(name);
+  return {
+    status: r.status,
+    needs: r.needs,
+    access: m?.access ?? "",
+    detail: r.detail,
+    anomaly: r.anomaly,
+    ...(m?.record && r.state ? m.record(r as Part) : (r.state as object)),
+  };
+}
+
+/** A row's text: "name    status · summary · needs … · detail · odd: …  (access)", then its children indented. */
+function rowLines(name: string, r: Row): string[] {
+  const m = manifestOf(name);
+  const [summary = "", ...children] =
+    r.state === undefined ? [] : (m?.lines(r as Part) ?? []);
+  const parts = [
+    r.status,
+    summary,
+    r.needs.length ? `needs ${r.needs.join(", ")}` : "",
+    r.detail ?? "",
+    r.anomaly ? `odd: ${r.anomaly}` : "",
+  ];
+  return [
+    `${name.padEnd(9)}${parts.filter(Boolean).join(" · ")}  (${m?.access ?? ""})`,
+    ...children.map((line) => `  ${line}`),
+  ];
+}
+
+/** `home status`: every connector, with the energy now on top. With `only` (`home <connector>`), that connector alone. */
+export async function status(o: Options, only?: string): Promise<void> {
+  const path = configPathOf(o);
+  const manifests = only === undefined ? MANIFESTS : [manifestOf(only)!];
+  const rows = path
+    ? await statusFromConfig(path, only)
+    : await statusFromEnv(manifests);
+  if (only !== undefined) {
+    const row = rows[only]!;
+    if (row.status !== "connected") process.exitCode = 1; // `home <connector>` is a check a script can test; `home` alone lists every one and exits 0
+    return o.json
+      ? printJson(rowRecord(only, row))
+      : console.log(rowLines(only, row).join("\n"));
+  }
+  const connected = (name: string) =>
+    rows[name]?.status === "connected"
+      ? (rows[name]!.state as never)
+      : undefined;
+  const now = energyNow(connected("enphase"), connected("amber"));
+  if (o.json)
+    return printJson({
+      now,
+      ...Object.fromEntries(
+        Object.entries(rows).map(([name, r]) => [name, rowRecord(name, r)]),
+      ),
+    });
+  if (now.gridW !== undefined)
+    console.log(
+      `now      solar ${kw(now.solarW)} · using ${kw(now.usingW)} · ${gridText(now)}`,
+    );
+  for (const [name, r] of Object.entries(rows))
+    console.log(rowLines(name, r).join("\n"));
+}