@khalido/home 0.0.0-stage → 0.1.1

package/dist/discover.js

@@ -0,0 +1,452 @@
+import { applyEdits, modify } from "jsonc-parser";
+import { errorText } from "./connector.js";
+/** mDNS service types worth looking for at home, and what this package does with each. Extend the list as needed. */
+export const KNOWN_SERVICES = {
+    "_hue._tcp": { what: "Philips Hue bridge", connector: "hue" },
+    "_dkapi._tcp": {
+        what: "Daikin AC (Home Assistant's zeroconf type)",
+        connector: "daikin",
+    },
+    "_enphase-envoy._tcp": { what: "Enphase IQ Gateway", connector: "enphase" },
+    "_googlecast._tcp": {
+        what: "Google Cast (Nest speakers and hubs, Chromecast, TVs, speaker groups)",
+        connector: "cast",
+    },
+    "_ipp._tcp": { what: "AirPrint printer (IPP)", connector: "printers" },
+    "_ipps._tcp": {
+        what: "AirPrint printer (IPP over TLS)",
+        connector: "printers",
+    },
+    "_airplay._tcp": { what: "AirPlay (Apple TV, HomePod, speakers)" },
+    "_raop._tcp": { what: "AirPlay audio receiver" },
+    "_matter._tcp": { what: "Matter device (commissioned)" },
+    "_matterc._udp": { what: "Matter device waiting to be commissioned" },
+    "_hap._tcp": { what: "HomeKit accessory" },
+    "_sonos._tcp": { what: "Sonos speaker" },
+    "_esphomelib._tcp": { what: "ESPHome device" },
+    "_shelly._tcp": { what: "Shelly relay or plug" },
+    "_wled._tcp": { what: "WLED light strip" },
+    "_nanoleafapi._tcp": { what: "Nanoleaf panels" },
+    "_eero._tcp": { what: "eero Wi-Fi router (cloud-only API)" },
+    "_home-assistant._tcp": { what: "Home Assistant server" },
+};
+/** Which config field holds each connector's identity, as its discovery reports it. */
+export const IDENTITY = {
+    hue: "bridgeId",
+    daikin: "mac",
+    enphase: "serial",
+    cast: "castId",
+    printers: "uuid",
+};
+/** Connectors with many devices in one integration (every Cast device and group, every printer); the rest allow one device for now. */
+export const MANY = new Set(["cast", "printers"]);
+/** An identity without case, separators or a `urn:uuid:` prefix: "00:17:88:B0" is "001788b0", "urn:uuid:AB-CD" is "abcd". */
+export const idKey = (id) => id
+    .toLowerCase()
+    .replace(/^urn:uuid:/, "")
+    .replace(/[^0-9a-z]/g, "");
+/** Identities compared by `idKey`. */
+export const sameId = (a, b) => idKey(a) === idKey(b);
+/** A new config entry for a found device, with the CLI's default key name and file paths, which `home config check` then verifies. */
+function newEntry(f) {
+    if (f.connector === "cast") {
+        const name = f.name ?? f.id;
+        return {
+            id: name
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "") || "cast",
+            connector: "cast",
+            name,
+            castId: f.id,
+        };
+    }
+    if (f.connector === "printers") {
+        const name = f.name ?? f.id;
+        return {
+            id: name
+                .toLowerCase()
+                .replace(/[^a-z0-9]+/g, "-")
+                .replace(/^-|-$/g, "") || "printer",
+            connector: "printers",
+            name,
+            uuid: f.id,
+            host: f.host,
+            ...(f.port === undefined ? {} : { port: f.port }),
+        };
+    }
+    const base = {
+        id: f.connector,
+        connector: f.connector,
+        host: f.host,
+        [IDENTITY[f.connector]]: f.id,
+    };
+    if (f.connector === "hue")
+        return { ...base, key: "HUE_APPLICATION_KEY", ca: "hue-root-ca.pem" };
+    if (f.connector === "enphase")
+        return { ...base, token: "~/.config/home/enphase-token.json" };
+    return base;
+}
+/** `id`, or `id-2`, `id-3`… : the first not in `taken`. */
+function unique(id, taken) {
+    let out = id;
+    for (let n = 2; taken.has(out); n++)
+        out = `${id}-${n}`;
+    return out;
+}
+/**
+ * Match what discovery found against the config by identity. An entry with no identity yet is matched by host, and a
+ * device at an entry's host with a different identity is a conflict, not a match. New entries get ids no entry has.
+ */
+export function matchFound(config, found) {
+    const devices = config.devices ?? [];
+    const match = {
+        moved: [],
+        renamed: [],
+        added: [],
+        skipped: [],
+        known: [],
+    };
+    const taken = new Set(devices.map((d) => d.id));
+    const identity = (x, field) => x[field];
+    const hostOf = (x) => x?.host;
+    for (const f of found) {
+        const field = IDENTITY[f.connector];
+        const same = devices.filter((x) => x.connector === f.connector);
+        const index = devices.findIndex((d) => d.connector === f.connector &&
+            typeof identity(d, field) === "string" &&
+            sameId(identity(d, field), f.id));
+        const d = devices[index];
+        const atHost = same.find((x) => hostOf(x) === f.host);
+        const from = hostOf(d);
+        const named = d && f.connector === "cast" && f.name !== undefined
+            ? d.name
+            : undefined;
+        if (d && named !== undefined && named !== f.name)
+            match.renamed.push({
+                index,
+                id: d.id,
+                connector: f.connector,
+                from: named,
+                to: f.name,
+            });
+        if (d && from !== undefined && from !== f.host)
+            match.moved.push({
+                index,
+                id: d.id,
+                connector: f.connector,
+                from,
+                to: f.host,
+            });
+        else if (d)
+            match.known.push({ id: d.id, connector: f.connector });
+        else if (atHost && identity(atHost, field) === undefined)
+            match.known.push({
+                id: atHost.id,
+                connector: f.connector,
+                hint: `add "${field}": "${f.id}" to recognise it after a move`,
+            });
+        else if (atHost)
+            match.skipped.push({
+                found: f,
+                why: `answers at ${atHost.id}'s host with a different ${field}`,
+            });
+        else if (!MANY.has(f.connector) &&
+            same.some((x) => identity(x, field) === undefined))
+            match.skipped.push({
+                found: f,
+                why: `could be ${same.find((x) => identity(x, field) === undefined).id} moved; add "${field}" to tell`,
+            });
+        else if (!MANY.has(f.connector) &&
+            (same.length ||
+                match.added.some((a) => a.found.connector === f.connector)))
+            match.skipped.push({
+                found: f,
+                why: `a second ${f.connector} device; one per connector for now`,
+            });
+        else {
+            const entry = newEntry(f);
+            entry.id = unique(String(entry.id), taken);
+            taken.add(String(entry.id));
+            match.added.push({ found: f, entry });
+        }
+    }
+    return match;
+}
+/** One entry as one line of JSON, keys in order: `{ "id": "ac", "connector": "daikin", "host": "…" }`. */
+const oneLine = (entry) => `{ ${Object.entries(entry)
+    .map(([k, v]) => `${JSON.stringify(k)}: ${JSON.stringify(v)}`)
+    .join(", ")} }`;
+/**
+ * The config's text with moved hosts and renamed Cast entries updated and new devices appended, through jsonc-parser's edits: comments, unknown
+ * keys and every other line stay as they were. A new device goes on its own line at its neighbour's indent.
+ */
+export function applyFound(text, match, hasDevices) {
+    // hasDevices: the config has a non-empty devices list
+    let out = text;
+    for (const m of match.moved)
+        out = applyEdits(out, modify(out, ["devices", m.index, "host"], m.to, {}));
+    for (const r of match.renamed)
+        out = applyEdits(out, modify(out, ["devices", r.index, "name"], r.to, {}));
+    if (!hasDevices && match.added.length)
+        return applyEdits(out, modify(out, ["devices"], match.added.map((a) => a.entry), { formattingOptions: { insertSpaces: true, tabSize: 2 } }));
+    for (const { entry } of match.added) {
+        const edits = modify(out, ["devices", -1], entry, {
+            isArrayInsertion: true,
+        });
+        const before = out;
+        out = applyEdits(out, edits.map((e) => {
+            const indent = before
+                .slice(before.lastIndexOf("\n", e.offset - 1) + 1)
+                .match(/^\s*/)[0];
+            return {
+                ...e,
+                content: e.content.replace(JSON.stringify(entry), `\n${indent}${oneLine(entry)}`),
+            };
+        }));
+    }
+    return out;
+}
+/** mDNS and Daikin's broadcast drop answers now and then, so discovery runs this many passes by default… */
+export const DISCOVERY_PASSES = 2;
+/** …this far apart. */
+export const DISCOVERY_GAP_MS = 5000;
+/** A device's key, across discovery passes and in the address cache: its connector and identity, without case or separators. */
+export const addressKey = (connector, id) => `${connector}:${idKey(id)}`;
+export const foundKey = (f) => addressKey(f.connector, f.id);
+/**
+ * One run's view of an address cache. `fresh` is a cached address confirmed since the config was edited (`configAt`,
+ * the config file's time; a config edited since wins); `seen` records an address that answered, writing through when it
+ * changed or was not fresh, so an address confirmed after a config edit is trusted again. A Cast name, when given, is the
+ * device's own (discovery's fn, or its own multizone status, never a config's), so a new one is written too; a call
+ * without a name keeps the one cached.
+ */
+export function addressBook(cache, options = {}) {
+    const entries = cache?.read() ?? {};
+    const now = options.now ?? Date.now;
+    // `seenAt` has whole milliseconds and a file time a fraction: a confirmation in the same millisecond as the edit counts.
+    const isFresh = (c) => options.configAt === undefined ||
+        Date.parse(c.seenAt) >= Math.floor(options.configAt);
+    return {
+        fresh(connector, id) {
+            const c = id === undefined ? undefined : entries[addressKey(connector, id)];
+            return c && isFresh(c) ? c : undefined;
+        },
+        seen(connector, id, address) {
+            if (!cache || id === undefined)
+                return;
+            const key = addressKey(connector, id);
+            const c = entries[key];
+            if (c &&
+                c.host === address.host &&
+                c.port === address.port &&
+                isFresh(c) &&
+                (!address.name || address.name === c.name))
+                return;
+            const name = address.name || c?.name;
+            entries[key] = {
+                host: address.host,
+                ...(address.port === undefined ? {} : { port: address.port }),
+                ...(name ? { name } : {}),
+                seenAt: new Date(now()).toISOString(),
+            };
+            cache.write({ ...entries });
+        },
+        entries: () => ({ ...entries }),
+    };
+}
+/**
+ * Run one discovery `passes` times, `gapMs` apart, and return the union (first answer wins). `onPass` sees each pass's
+ * additions as they come; `done` ends it early once what was looked for has answered. A pass that throws adds nothing;
+ * when every pass threw, discovery never ran, so it throws the last error rather than reporting nothing found. An error
+ * `stopOn` accepts is thrown at once: no later pass could do better.
+ */
+export async function discover(pass, options) {
+    const key = options.key ?? foundKey;
+    const all = new Map();
+    const passes = options.passes ?? DISCOVERY_PASSES;
+    let ran = 0;
+    const errors = [];
+    for (let n = 1; n <= passes && !options.signal?.aborted; n++) {
+        if (n > 1)
+            await options.clock.sleep(options.gapMs ?? DISCOVERY_GAP_MS, options.signal);
+        if (options.signal?.aborted)
+            break;
+        ran++;
+        const answers = await pass().catch((error) => {
+            if (options.stopOn?.(error))
+                throw error;
+            errors.push(error);
+            return [];
+        });
+        const added = answers.filter((t) => !all.has(key(t)) && all.set(key(t), t));
+        options.onPass?.(n, added);
+        if (options.done?.([...all.values()]))
+            break;
+    }
+    if (ran && errors.length === ran)
+        throw errors.at(-1);
+    return [...all.values()];
+}
+/** Discovery runs after this many failed reads in a row. */
+export const RESCAN_AFTER_FAILURES = 3;
+/** Then again after these delays, then hourly for as long as reads fail. */
+export const RESCAN_DELAYS_MS = [60_000, 5 * 60_000, 15 * 60_000];
+export const HOUR = 3_600_000;
+/** The wait before the next scan after `attempt` scans have missed: 1, 5 and 15 minutes, then hourly. The relocator and Cast's re-discovery share it. */
+export const rescanDelay = (attempt) => RESCAN_DELAYS_MS[attempt] ?? HOUR;
+/** After this long without a read, the detail says a day has passed; the scans carry on hourly. */
+export const DAY_MS = 24 * HOUR;
+/**
+ * A polling connector's address, rescanned only on failure. `failed()` after each failed read runs `find` once reads
+ * have failed `RESCAN_AFTER_FAILURES` times in a row, then on the backoff, then hourly with no end, so a device that comes
+ * back is found without a restart. `ok()` after a good read, `reset()` on a refresh (the next failure scans at once).
+ * Without `find` or an identity it never scans. `cached`: the starting host came from an address cache, so the first
+ * failure scans at once. `failed(signal)` takes the run's signal, so a shutdown does not wait out a scan.
+ */
+export function relocator(options) {
+    let host = options.host;
+    let failures = 0;
+    let fromCache = options.cached === true; // a cached address that fails is stale: scan on its first failure
+    let attempts = 0;
+    let firstScan;
+    let nextScan = 0;
+    let seenHere;
+    let discoveryFailed;
+    const reset = () => ((attempts = 0),
+        (firstScan = undefined),
+        (nextScan = 0),
+        (seenHere = undefined),
+        (discoveryFailed = undefined));
+    return {
+        host: () => host,
+        ok: () => ((failures = 0), (fromCache = false), reset()),
+        reset,
+        async failed(signal) {
+            failures++;
+            const { find, id, clock } = options;
+            if (!find || !id || failures < (fromCache ? 1 : RESCAN_AFTER_FAILURES))
+                return {};
+            const now = clock.now();
+            const state = () => ({
+                ...(firstScan !== undefined && now - firstScan >= DAY_MS
+                    ? { overADay: true }
+                    : {}),
+                ...(seenHere === undefined ? {} : { seenHere }),
+                ...(discoveryFailed === undefined ? {} : { discoveryFailed }),
+            });
+            if (now < nextScan)
+                return state();
+            firstScan ??= now;
+            let at;
+            try {
+                at = (await discover(find, {
+                    clock,
+                    signal,
+                    done: (all) => all.some((f) => sameId(f.id, id)),
+                })).find((f) => sameId(f.id, id))?.host;
+                discoveryFailed = undefined;
+            }
+            catch (error) {
+                discoveryFailed = errorText(error);
+            }
+            if (at && at !== host) {
+                const from = host;
+                host = at;
+                failures = 0;
+                reset();
+                return { moved: `moved from ${from} to ${at}` };
+            }
+            seenHere = discoveryFailed === undefined ? at === host : undefined;
+            nextScan = now + rescanDelay(attempts);
+            attempts++;
+            return state();
+        },
+    };
+}
+/** A failed read's detail, saying what discovery found: never "not found" unless a scan looked and missed it. */
+export function lostDetail(lost, error) {
+    const what = lost.discoveryFailed !== undefined
+        ? `discovery failed: ${lost.discoveryFailed}`
+        : lost.seenHere === true
+            ? "discovery finds it at its address but reads fail"
+            : lost.seenHere === false
+                ? "not found by discovery"
+                : "";
+    const why = errorText(error);
+    return [lost.overADay ? "no answer for a day" : "", what, why]
+        .filter(Boolean)
+        .join("; ");
+}
+/** Instance names from `dns-sd -B`, each once. */
+export const parseBrowse = (text) => [
+    ...new Set([...text.matchAll(/ Add .*?\.\s+\S+\.\s+(.+)$/gm)].map((m) => m[1].trim())),
+];
+const utf8 = new TextEncoder();
+/** Undo DNS-SD text escapes, as `dns-sd` and `avahi-browse` print them: `\ ` or `\.` for the character, `\226\128\153` for each byte of a UTF-8 character. */
+function unescapeDnsSd(token) {
+    const bytes = [];
+    for (let i = 0; i < token.length; i++) {
+        const decimal = token[i] === "\\" ? token.slice(i + 1, i + 4) : "";
+        if (/^\d{3}$/.test(decimal))
+            (bytes.push(Number(decimal)), (i += 3));
+        else
+            bytes.push(...utf8.encode(token[token[i] === "\\" ? ++i : i]));
+    }
+    return new TextDecoder().decode(Uint8Array.from(bytes));
+}
+/** TXT strings as a record: `key=value`, and a bare `key` or `key=` as an empty value. */
+const txtRecord = (pairs) => Object.fromEntries(pairs
+    .filter((p) => p && !p.startsWith("="))
+    .map((p) => p.includes("=")
+    ? [p.slice(0, p.indexOf("=")), p.slice(p.indexOf("=") + 1)]
+    : [p, ""]));
+/**
+ * `avahi-browse --parsable --resolve` (Linux): each resolved instance once, IPv4 only (the config keeps IPv4 addresses).
+ * A resolved line is `=;interface;IPv4;name;type;domain;hostname;address;port;"txt" "txt"`; names and TXT strings use
+ * the same escapes as `dns-sd` (`\059` for a `;` in a name, `\"` inside TXT). An instance seen on two interfaces is kept
+ * once, the first; loopback is skipped. Checked against avahi-utils on Debian trixie, 2026-10-16.
+ */
+export function parseAvahi(text) {
+    const seen = new Map();
+    for (const line of text.split("\n")) {
+        const f = line.split(";");
+        // By the address itself: column 3 is the protocol the service was seen on, not necessarily the address's. Loopback is a service on this machine.
+        if (f[0] !== "=" ||
+            f.length < 10 ||
+            !/^\d+\.\d+\.\d+\.\d+$/.test(f[7]) ||
+            f[1] === "lo" ||
+            f[7].startsWith("127."))
+            continue;
+        const instance = unescapeDnsSd(f[3]);
+        const port = Number(f[8]);
+        if (seen.has(instance) || !f[7] || !Number.isInteger(port))
+            continue;
+        const txt = txtRecord([
+            ...f
+                .slice(9)
+                .join(";")
+                .matchAll(/"((?:\\.|[^"\\])*)"/g),
+        ].map((m) => unescapeDnsSd(m[1])));
+        seen.set(instance, { instance, hostname: f[6], host: f[7], port, txt });
+    }
+    return [...seen.values()];
+}
+/** Instance names from `avahi-browse --parsable` (a `+` line per instance and interface), each once. */
+export const parseAvahiBrowse = (text) => [
+    ...new Set(text
+        .split("\n")
+        .flatMap((l) => l.startsWith("+;") ? [unescapeDnsSd(l.split(";")[3] ?? "")] : [])),
+].filter(Boolean);
+/**
+ * One `dns-sd -L` answer: the host and port it can be reached at, and its TXT record. TXT values come escaped (`\ ` for
+ * a space, `\226\128\153` for each byte of a UTF-8 character); these are undone, so `fn` reads as the Google Home app shows it.
+ */
+export function parseResolve(text) {
+    const at = text.match(/can be reached at (\S+?)\.?:(\d+)/);
+    if (!at)
+        return undefined;
+    const line = text.slice(at.index).split("\n")[1] ?? "";
+    const tokens = (line.trim().match(/(?:\\.|[^\s\\])+/g) ?? []).map(unescapeDnsSd);
+    return { hostname: at[1], port: Number(at[2]), txt: txtRecord(tokens) };
+}

package/dist/energy.d.ts

@@ -0,0 +1,61 @@
+import type { AmberState, PriceInterval } from "./connectors/amber/client.ts";
+import type { EnphaseState } from "./connectors/enphase/client.ts";
+import type { EnphaseSnapshot } from "./connectors/enphase/index.ts";
+/** The home's energy right now: power from Enphase, prices from Amber, and what the grid flow costs per hour. */
+export type EnergyNow = {
+    solarW?: number;
+    solarPeakTodayW?: number;
+    usingW?: number;
+    gridW?: number;
+    importCents?: number;
+    exportCents?: number;
+    centsPerHour?: number;
+    renewables?: number;
+    priceDescriptor?: string;
+    spike?: string;
+    estimate?: boolean;
+    negativePrice?: "paid to use" | "exporting at a loss";
+    flow?: "importing" | "exporting" | "balanced";
+    surplusW?: number;
+    surplusCentsPerHour?: number;
+};
+/**
+ * Within this many watts either way the grid flow reads as "balanced": a display rule for the word and the animation,
+ * so a meter wobbling around zero does not flip between importing and exporting. `gridW` and `surplusW` stay as read.
+ */
+export declare const BALANCED_W = 20;
+/** One owner for the combined number, so every view (CLI, jaldi, the bot) shows the same thing. */
+export declare function energyNow(power?: EnphaseState & Partial<Pick<EnphaseSnapshot, "productionWPeakToday">>, prices?: AmberState): EnergyNow;
+/**
+ * How brightly to draw the panels: `solarW` as a fraction of the array's rated `capacityW` when the config has it,
+ * else of today's peak so far, with which scale it is (they mean different things, so a drawing says which).
+ * Never clamped: above 1 is above the scale. Undefined when there is no solar reading or nothing to scale by.
+ */
+export declare function solarLevel(now: EnergyNow, capacityW?: number): {
+    fraction: number;
+    scale: "capacity" | "today's peak";
+} | undefined;
+/**
+ * The grid flow in words every view shares: "exporting 1.2 kW, earning 42 c/h", "importing 0.8 kW, costing 33 c/h",
+ * "balanced (-10 W)", or "" with no grid reading. Rounded for reading only; the numbers above stay as read.
+ */
+export declare function gridText(now: EnergyNow): string;
+/** A run of the forecast and its time-weighted averages: import price, feed-in price and the grid's renewable share. */
+export type PriceWindow = {
+    start: string;
+    end: string;
+    importCents?: number;
+    exportCents?: number;
+    renewables?: number;
+};
+/**
+ * The best `hours` to run something in, from Amber's forecast: the cheapest by import price (Amber's `perKwh`), or the
+ * greenest by the grid's renewable share. The window runs over unbroken intervals that each have the number it is judged by,
+ * starting no earlier than `from` (pass the clock's now; it defaults to the forecast's first interval, which began up to
+ * 5 minutes ago). Prices are flat within an interval, so the best window starts or ends on an interval's edge: both are
+ * tried. Averages weigh each interval by the time it covers; the earliest wins a tie. Undefined when nothing fits.
+ */
+export declare function bestWindow(forecast: PriceInterval[] | undefined, hours: number, options?: {
+    by?: "price" | "renewables";
+    from?: number;
+}): PriceWindow | undefined;

package/dist/energy.js

@@ -0,0 +1,162 @@
+import { kw } from "./manifest.js";
+/**
+ * Within this many watts either way the grid flow reads as "balanced": a display rule for the word and the animation,
+ * so a meter wobbling around zero does not flip between importing and exporting. `gridW` and `surplusW` stay as read.
+ */
+export const BALANCED_W = 20;
+/** The grid flow in a word, from the raw `gridW`. */
+function flowOf(gridW) {
+    if (gridW === undefined)
+        return undefined;
+    return Math.abs(gridW) <= BALANCED_W
+        ? "balanced"
+        : gridW > 0
+            ? "importing"
+            : "exporting";
+}
+/**
+ * `"paid to use"` when the import price is below zero, else `"exporting at a loss"` when the export price is (Amber's
+ * feed-in `perKwh` above zero), else undefined. Both can hold in one interval; the import side wins.
+ */
+function negativePrice(prices) {
+    if (prices?.importCents !== undefined && prices.importCents < 0)
+        return "paid to use";
+    if (prices?.exportCents !== undefined && prices.exportCents < 0)
+        return "exporting at a loss";
+    return undefined;
+}
+/** One owner for the combined number, so every view (CLI, jaldi, the bot) shows the same thing. */
+export function energyNow(power, prices) {
+    const gridW = power?.netW;
+    const surplusW = gridW === undefined ? undefined : gridW < 0 ? -gridW : 0;
+    const rate = gridW === undefined
+        ? undefined
+        : gridW >= 0
+            ? prices?.importCents
+            : prices?.exportCents;
+    return {
+        solarW: power?.productionW,
+        solarPeakTodayW: power?.productionWPeakToday,
+        usingW: power?.consumptionW,
+        gridW,
+        importCents: prices?.importCents,
+        exportCents: prices?.exportCents,
+        centsPerHour: gridW === undefined || rate === undefined
+            ? undefined
+            : (gridW / 1000) * rate, // export: negative kW × earned c/kWh = negative cost
+        renewables: prices?.renewables,
+        priceDescriptor: prices?.priceDescriptor,
+        spike: prices?.spike,
+        estimate: prices?.estimate,
+        negativePrice: negativePrice(prices),
+        flow: flowOf(gridW),
+        surplusW,
+        surplusCentsPerHour: surplusW === undefined || prices?.exportCents === undefined
+            ? undefined
+            : (surplusW / 1000) * prices.exportCents,
+    };
+}
+/**
+ * How brightly to draw the panels: `solarW` as a fraction of the array's rated `capacityW` when the config has it,
+ * else of today's peak so far, with which scale it is (they mean different things, so a drawing says which).
+ * Never clamped: above 1 is above the scale. Undefined when there is no solar reading or nothing to scale by.
+ */
+export function solarLevel(now, capacityW) {
+    if (now.solarW === undefined)
+        return undefined;
+    if (capacityW !== undefined && capacityW > 0)
+        return { fraction: now.solarW / capacityW, scale: "capacity" };
+    if (now.solarPeakTodayW !== undefined && now.solarPeakTodayW > 0)
+        return {
+            fraction: now.solarW / now.solarPeakTodayW,
+            scale: "today's peak",
+        };
+    return undefined;
+}
+/**
+ * The grid flow in words every view shares: "exporting 1.2 kW, earning 42 c/h", "importing 0.8 kW, costing 33 c/h",
+ * "balanced (-10 W)", or "" with no grid reading. Rounded for reading only; the numbers above stay as read.
+ */
+export function gridText(now) {
+    const rate = (c, positive, negative) => c === undefined
+        ? ""
+        : `, ${c >= 0 ? positive : negative} ${Math.round(Math.abs(c))} c/h`;
+    if (now.flow === "exporting" && now.surplusW !== undefined)
+        return `exporting ${kw(now.surplusW)}${rate(now.surplusCentsPerHour, "earning", "costing")}`;
+    if (now.flow === "importing" && now.gridW !== undefined)
+        return `importing ${kw(now.gridW)}${rate(now.centsPerHour, "costing", "earning")}`;
+    return now.flow === "balanced" ? `balanced (${now.gridW} W)` : "";
+}
+const HOUR_MS = 3_600_000;
+/**
+ * The best `hours` to run something in, from Amber's forecast: the cheapest by import price (Amber's `perKwh`), or the
+ * greenest by the grid's renewable share. The window runs over unbroken intervals that each have the number it is judged by,
+ * starting no earlier than `from` (pass the clock's now; it defaults to the forecast's first interval, which began up to
+ * 5 minutes ago). Prices are flat within an interval, so the best window starts or ends on an interval's edge: both are
+ * tried. Averages weigh each interval by the time it covers; the earliest wins a tie. Undefined when nothing fits.
+ */
+export function bestWindow(forecast, hours, options = {}) {
+    if (!(hours > 0 && Number.isFinite(hours)))
+        throw new RangeError(`bestWindow: hours must be above 0, got ${hours}`);
+    const by = options.by ?? "price";
+    const rows = (forecast ?? []).map((r) => ({
+        ...r,
+        t0: Date.parse(r.start),
+        t1: Date.parse(r.end),
+    }));
+    const from = options.from ?? rows[0]?.t0 ?? 0;
+    const length = Math.round(hours * HOUR_MS); // whole ms, so the covered time adds up to it exactly
+    const starts = [
+        ...new Set(rows
+            .flatMap((r) => [Math.max(r.t0, from), r.t1 - length])
+            .filter((t) => t >= from)),
+    ].sort((a, b) => a - b);
+    let best;
+    let bestScore = Infinity;
+    for (const start of starts) {
+        const window = windowAt(rows, start, length, by);
+        const score = window && (by === "price" ? window.importCents : -window.renewables);
+        if (window && score < bestScore)
+            ((best = window), (bestScore = score));
+    }
+    return best;
+}
+/** The window of `length` ms from `start`, or undefined when an interval in it is missing, or lacks the number `by` needs. Any other average is left out unless every interval has it. */
+function windowAt(rows, start, length, by) {
+    const end = start + length;
+    const sum = {
+        importCents: 0,
+        exportCents: 0,
+        renewables: 0,
+        importMs: 0,
+        exportMs: 0,
+        renewablesMs: 0,
+    };
+    let at = start;
+    for (const r of rows) {
+        if (r.t1 <= at)
+            continue;
+        if (at >= end)
+            break;
+        if (r.t0 > at ||
+            (by === "price" ? r.importCents : r.renewables) === undefined)
+            return undefined; // a gap, or no number to judge by
+        const ms = Math.min(r.t1, end) - at;
+        if (r.importCents !== undefined)
+            ((sum.importCents += r.importCents * ms), (sum.importMs += ms));
+        if (r.exportCents !== undefined)
+            ((sum.exportCents += r.exportCents * ms), (sum.exportMs += ms));
+        if (r.renewables !== undefined)
+            ((sum.renewables += r.renewables * ms), (sum.renewablesMs += ms));
+        at += ms;
+    }
+    if (at < end)
+        return undefined;
+    return {
+        start: new Date(start).toISOString(),
+        end: new Date(end).toISOString(),
+        importCents: sum.importMs === length ? sum.importCents / length : undefined,
+        exportCents: sum.exportMs === length ? sum.exportCents / length : undefined,
+        renewables: sum.renewablesMs === length ? sum.renewables / length : undefined,
+    };
+}

package/dist/finders-entry.d.ts

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

package/dist/finders-entry.js

@@ -0,0 +1,2 @@
+// `@khalido/home/finders`: what a Node consumer passes to `loadHome`. The rest of finders.ts is the CLI's.
+export { FINDERS, fileCache } from "./finders.js";