@khalido/home 0.0.0-stage → 0.1.1

package/dist/finders.d.ts

@@ -0,0 +1,48 @@
+import { type AddressCache, type Connector, type Finder, type Found } from "./discover.ts";
+/** The system's mDNS tool is not installed: discovery can't run until it is. */
+export declare class MissingTool extends Error {
+}
+/**
+ * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
+ * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in
+ * 4–13 ms (Bun 1.4.2, measured 2026-10-13), so the wait is for a cold cache only. A missing binary rejects, naming it.
+ * `command` is for tests.
+ */
+export declare function dnsSd(argv: string[], options?: {
+    maxMs?: number;
+    quietMs?: number;
+    done?: (out: string) => boolean;
+    command?: string;
+    install?: string;
+}): Promise<string>;
+/** Instance names of one mDNS service type: what has answered, once answers stop for 200 ms. */
+export declare const browse: (type: string) => Promise<string[]>;
+/** Every instance of one mDNS type, resolved to an IPv4 address (the config keeps addresses, not names), its port and its TXT record. */
+export declare function mdnsResolve(type: string): Promise<{
+    instance: string;
+    hostname: string;
+    host: string;
+    port: number;
+    txt: Record<string, string>;
+}[]>;
+/** Daikin's `key=value,key=value` answers, percent-decoded. */
+export declare const daikinFields: (text: string) => any;
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+export declare function findDaikins(ms?: number): Promise<{
+    ip: string;
+    fields: Record<string, string>;
+}[]>;
+/** A Daikin's broadcast answer as a found device, by its MAC. */
+export declare const daikinFound: (d: {
+    ip: string;
+    fields: Record<string, string>;
+}) => Found[];
+/** Each connector's discovery, as `loadHome` (rescans, and every Cast address) and `home discover` use it. */
+export declare const FINDERS: Record<Connector, Finder>;
+/**
+ * An address cache in one JSON file, owner-only (0600, its folder 0700), replaced atomically on each write. A missing
+ * file is an empty cache; so is a file that does not parse, which the next write replaces (a cache, not KO's data).
+ */
+export declare function fileCache(path: string): AddressCache;
+/** Write a file only its owner can read (0600, its folder 0700), replaced atomically: the address cache, the Enphase token. */
+export declare function writePrivate(path: string, text: string): void;

package/dist/finders.js

@@ -0,0 +1,176 @@
+import { spawn } from "node:child_process";
+import { chmodSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
+import { dirname } from "node:path";
+import { createSocket } from "node:dgram";
+import { lookup } from "node:dns/promises";
+import { printersFound } from "./connectors/printers/found.js";
+import { parseAvahi, parseAvahiBrowse, parseBrowse, parseResolve, } from "./discover.js";
+// Each connector's discovery on the network: mDNS through the system's own daemon (macOS `dns-sd`, Linux `avahi-browse`),
+// and Daikin's UDP broadcast. Node APIs (child_process, dgram, dns), so this file sits outside the runtime-neutral build like
+// weather/ftp.ts and cast/tls.ts; `home`, jaldi's sidecar and chota-bot import it from `@khalido/home/finders` and pass `FINDERS`
+// to `loadHome`. Runs in Bun and Node. The system daemon keeps an mDNS cache, so answers come from memory in milliseconds and
+// nothing here binds UDP 5353 beside it; a slow device (the Enphase gateway took 4 s to answer a fresh query; Bun 1.4.3, 2026-10-16)
+// does not slow a scan. Without the tool the mDNS finders throw, naming it, rather than "nothing answered".
+// `fileCache` keeps the addresses discovery found in a file between runs, so the next run connects straight away.
+/** The system's mDNS tool is not installed: discovery can't run until it is. */
+export class MissingTool extends Error {
+}
+/**
+ * Run a long-lived `dns-sd` query (or `avahi-browse`, by `command`) and return what it printed. It never exits by itself, so it is stopped once `done`
+ * says the answer is in, or `quietMs` after the last output, or at `maxMs`. The system's mDNS cache usually answers in
+ * 4–13 ms (Bun 1.4.2, measured 2026-10-13), so the wait is for a cold cache only. A missing binary rejects, naming it.
+ * `command` is for tests.
+ */
+export function dnsSd(argv, options = {}) {
+    const { maxMs = 1500, quietMs, done, command = "dns-sd", install } = options;
+    return new Promise((resolve, reject) => {
+        let out = "";
+        const proc = spawn(command, argv, { stdio: ["ignore", "pipe", "ignore"] });
+        const stop = () => proc.kill();
+        const timer = setTimeout(stop, maxMs);
+        let quiet;
+        proc.stdout.setEncoding("utf8").on("data", (d) => {
+            out += d;
+            if (done?.(out))
+                return stop();
+            if (quietMs !== undefined)
+                (clearTimeout(quiet), (quiet = setTimeout(stop, quietMs)));
+        });
+        const finish = () => (clearTimeout(timer),
+            clearTimeout(quiet),
+            resolve(out));
+        proc.on("error", (error) => {
+            (clearTimeout(timer), clearTimeout(quiet));
+            reject(error.code === "ENOENT"
+                ? new MissingTool(`${command} not found; mDNS discovery needs it${install ? ` (${install})` : ""}`)
+                : new Error(`${command}: ${error.message}`));
+        });
+        proc.on("close", finish);
+    });
+}
+/** Linux asks avahi-daemon, which Raspberry Pi OS runs by default; its command-line tool is a separate package. */
+const LINUX = process.platform === "linux";
+/** `avahi-browse` prints what avahi-daemon's cache holds, resolves it, and exits (`--terminate`); `maxMs` caps a slow resolve. */
+const avahi = (args) => dnsSd(["--parsable", "--terminate", ...args], {
+    command: "avahi-browse",
+    install: "apt install avahi-utils",
+    maxMs: 3000,
+});
+/** Instance names of one mDNS service type: what has answered, once answers stop for 200 ms. */
+export const browse = async (type) => LINUX
+    ? parseAvahiBrowse(await avahi([type]))
+    : parseBrowse(await dnsSd(["-B", type], { quietMs: 200 }));
+/** A resolve is in once its TXT line (the line after "can be reached at") is complete. */
+const resolved = (out) => /can be reached at [^\n]*\n[^\n]*\n/.test(out);
+/** Every instance of one mDNS type, resolved to an IPv4 address (the config keeps addresses, not names), its port and its TXT record. */
+export async function mdnsResolve(type) {
+    if (LINUX)
+        return parseAvahi(await avahi(["--resolve", type]));
+    const found = await Promise.all((await browse(type)).map(async (name) => {
+        const r = parseResolve(await dnsSd(["-L", name, type], { done: resolved }));
+        const host = r
+            ? await lookup(r.hostname, { family: 4 }).then((x) => x.address, () => undefined)
+            : undefined;
+        return r && host ? [{ ...r, host, instance: name }] : [];
+    }));
+    return found.flat();
+}
+/** Every device of one mDNS type with its identity from a TXT key, named by its mDNS instance. */
+const mdnsFind = async (type, txtKey, connector) => (await mdnsResolve(type)).flatMap((r) => r.txt[txtKey]
+    ? [{ connector, id: r.txt[txtKey], host: r.host, name: r.instance }]
+    : []);
+/** Daikin's `key=value,key=value` answers, percent-decoded. */
+export const daikinFields = (text) => Object.fromEntries(text
+    .trim()
+    .split(",")
+    .map((kv) => kv.split("="))
+    .map(([k, v = ""]) => [k, decoded(v)]));
+/** A percent-encoded value, or as sent when it is not valid encoding (a stray "%"): one odd field never fails the read. */
+function decoded(v) {
+    try {
+        return decodeURIComponent(v);
+    }
+    catch {
+        return v;
+    }
+}
+/** Broadcast pydaikin's discovery packet (UDP 30000 → 30050) and collect who answers within `ms`. */
+export function findDaikins(ms = 1500) {
+    return new Promise((resolve) => {
+        const found = [];
+        const sock = createSocket({ type: "udp4", reuseAddr: true });
+        sock.on("message", (msg, from) => found.push({ ip: from.address, fields: daikinFields(msg.toString()) }));
+        sock.on("error", () => (sock.close(), resolve(found)));
+        sock.bind(30000, () => {
+            sock.setBroadcast(true);
+            sock.send("DAIKIN_UDP/common/basic_info", 30050, "255.255.255.255");
+            setTimeout(() => (sock.close(), resolve(found)), ms);
+        });
+    });
+}
+/** A Daikin's broadcast answer as a found device, by its MAC. */
+export const daikinFound = (d) => d.fields.mac
+    ? [
+        {
+            connector: "daikin",
+            id: d.fields.mac,
+            host: d.ip,
+            name: d.fields.name,
+        },
+    ]
+    : [];
+/** Each connector's discovery, as `loadHome` (rescans, and every Cast address) and `home discover` use it. */
+export const FINDERS = {
+    hue: () => mdnsFind("_hue._tcp", "bridgeid", "hue"),
+    enphase: () => mdnsFind("_enphase-envoy._tcp", "serialnum", "enphase"),
+    daikin: async () => (await findDaikins()).flatMap(daikinFound),
+    cast: async () => (await mdnsResolve("_googlecast._tcp")).flatMap(({ txt, host, port }) => txt.id
+        ? [
+            {
+                connector: "cast",
+                id: txt.id,
+                host,
+                port,
+                name: txt.fn,
+                model: txt.md,
+                group: txt.md === "Google Cast Group",
+            },
+        ]
+        : []),
+    printers: async () => {
+        const [ipp, ipps] = await Promise.all([
+            mdnsResolve("_ipp._tcp"),
+            mdnsResolve("_ipps._tcp"),
+        ]);
+        return printersFound(ipp, ipps);
+    },
+};
+/**
+ * An address cache in one JSON file, owner-only (0600, its folder 0700), replaced atomically on each write. A missing
+ * file is an empty cache; so is a file that does not parse, which the next write replaces (a cache, not KO's data).
+ */
+export function fileCache(path) {
+    return {
+        read() {
+            try {
+                const parsed = JSON.parse(readFileSync(path, "utf8"));
+                return parsed && typeof parsed === "object" && !Array.isArray(parsed)
+                    ? parsed
+                    : {};
+            }
+            catch {
+                return {};
+            }
+        },
+        write: (entries) => writePrivate(path, `${JSON.stringify(entries, null, 2)}\n`),
+    };
+}
+/** Write a file only its owner can read (0600, its folder 0700), replaced atomically: the address cache, the Enphase token. */
+export function writePrivate(path, text) {
+    mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.tmp`;
+    rmSync(tmp, { force: true }); // so the mode applies to a fresh file
+    writeFileSync(tmp, text, { mode: 0o600 });
+    chmodSync(tmp, 0o600);
+    renameSync(tmp, path);
+}

package/dist/health.d.ts

@@ -0,0 +1,28 @@
+import type { Part, Status } from "./home.ts";
+/**
+ * How one integration is doing, judged by time: `ok`, `stale` (no good read for a while, last values still shown) or `down`.
+ * The thresholds come with it, so a page can say "stale after 4 min". Push connectors (Hue, Cast) have no poll to be late
+ * for: never stale, down when not connected for `PUSH_DOWN_MS`.
+ */
+export type Health = {
+    level: "ok" | "stale" | "down";
+    status: Status;
+    lastGoodAt?: string;
+    downSince?: string;
+    staleAfterMs?: number;
+    downAfterMs: number;
+    detail?: string;
+};
+/** A polling connector is stale after this many polls with no good read: two missed, plus half of one so a slow read that ends in a timeout does not flap it, */
+export declare const STALE_POLLS = 2.5;
+/** and down after this many polls not connected. */
+export declare const DOWN_POLLS = 3;
+/** A push connector is down after this long not connected: a reconnect takes seconds, a backoff at most a minute. */
+export declare const PUSH_DOWN_MS = 120000;
+/**
+ * Each integration's health at `now` (ms), from the times `createHome` stamps on its part. `pollSeconds` overrides a
+ * connector's own interval (its manifest's, so pass the weather's when the config changes it), or names one the library does not know.
+ */
+export declare function health(snapshot: Record<string, Part | undefined>, now: number, options?: {
+    pollSeconds?: Record<string, number>;
+}): Record<string, Health>;

package/dist/health.js

@@ -0,0 +1,35 @@
+import { MANIFESTS } from "./manifests.js";
+/** A polling connector is stale after this many polls with no good read: two missed, plus half of one so a slow read that ends in a timeout does not flap it, */
+export const STALE_POLLS = 2.5;
+/** and down after this many polls not connected. */
+export const DOWN_POLLS = 3;
+/** A push connector is down after this long not connected: a reconnect takes seconds, a backoff at most a minute. */
+export const PUSH_DOWN_MS = 120_000;
+const POLL_SECONDS = Object.fromEntries(MANIFESTS.map((m) => [m.name, m.pollSeconds]));
+/**
+ * Each integration's health at `now` (ms), from the times `createHome` stamps on its part. `pollSeconds` overrides a
+ * connector's own interval (its manifest's, so pass the weather's when the config changes it), or names one the library does not know.
+ */
+export function health(snapshot, now, options = {}) {
+    const poll = (name) => options.pollSeconds?.[name] ?? POLL_SECONDS[name];
+    return Object.fromEntries(Object.entries(snapshot).flatMap(([name, part]) => part ? [[name, healthOf(part, now, poll(name))]] : []));
+}
+function healthOf(part, now, pollSeconds) {
+    const staleAfterMs = pollSeconds === undefined ? undefined : STALE_POLLS * pollSeconds * 1000;
+    const downAfterMs = pollSeconds === undefined ? PUSH_DOWN_MS : DOWN_POLLS * pollSeconds * 1000;
+    const age = (iso) => iso === undefined ? undefined : now - Date.parse(iso);
+    const down = part.status === "unavailable" ||
+        (part.status !== "connected" && (age(part.downSince) ?? 0) >= downAfterMs);
+    const goodAge = age(part.lastGoodAt) ?? age(part.downSince); // never good: as old as the wait for it
+    const stale = staleAfterMs !== undefined && (goodAge ?? 0) >= staleAfterMs;
+    const { status, lastGoodAt, downSince, detail } = part;
+    return {
+        level: down ? "down" : stale ? "stale" : "ok",
+        status,
+        lastGoodAt,
+        downSince,
+        staleAfterMs,
+        downAfterMs,
+        detail,
+    };
+}

package/dist/home.d.ts

@@ -0,0 +1,81 @@
+import { z } from "zod";
+import { type Clock } from "./clock.ts";
+/** A secret in a home config is the name of an environment variable, never the secret: a pasted key fails here. */
+export declare const envName: z.ZodString;
+/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+export declare const filePath: z.ZodString;
+/** How an integration is doing. "unavailable" means it stopped and will not retry by itself. */
+export type Status = "connecting" | "connected" | "disconnected" | "unavailable";
+/**
+ * One integration's slice of the home: its status, a human detail, anything odd the device reported, and its state.
+ * `createHome` stamps the times (UTC ISO). `lastGoodAt`: its last report while connected, or the read time a connected report
+ * gives when it repeats an older read (weather's 5-minute sun tick). `downSince`: when it stopped being connected (or started,
+ * if it never has); none while connected. Any other time an integration sets is ignored.
+ */
+export type Part<S = unknown> = {
+    status: Status;
+    detail?: string;
+    anomaly?: string;
+    state?: S;
+    lastGoodAt?: string;
+    downSince?: string;
+};
+/**
+ * An integration is a folder in `src/` that exports a factory returning this.
+ * `run` keeps its state current until `signal` aborts, reporting each change through `update`.
+ * `refresh` asks for a fresh read now, ahead of the integration's schedule; it returns at once and the read reports through `update`.
+ */
+export type Integration<S = unknown, N extends string = string> = {
+    name: N;
+    run(signal: AbortSignal, update: (part: Part<S>) => void): Promise<void>;
+    refresh(): void;
+};
+/** The state an integration reports. */
+export type StateOf<I> = I extends Integration<infer S, string> ? S : never;
+/**
+ * The whole home: one `Part` per integration, by name, each typed by its integration (`snapshot.weather?.state` is a
+ * `WeatherState`). A name can be missing: a config need not have every connector. This is the cache every read comes from.
+ */
+export type HomeSnapshot<I extends Integration<any, string> = Integration<unknown, string>> = {
+    [X in I as X["name"]]?: Part<StateOf<X>>;
+};
+/** One report: which integration, its part before and after. Typed by name, so `change.after.state` is that integration's state. */
+export type Change<I extends Integration<any, string> = Integration<unknown, string>> = {
+    [X in I as X["name"]]: {
+        name: X["name"];
+        before: Part<StateOf<X>>;
+        after: Part<StateOf<X>>;
+    };
+}[I["name"]];
+/**
+ * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ */
+export declare function createHome<I extends Integration<any, string>>(integrations: readonly I[], onChange?: (home: HomeSnapshot<I>, change: Change<I>) => void, options?: {
+    clock?: Clock;
+}): {
+    /** The latest snapshot. Never touches a device. */
+    snapshot: () => HomeSnapshot<I>;
+    /** One integration's part, typed by its name: `home.part("weather")?.state?.blocks`. */
+    part: <N extends I["name"]>(name: N) => HomeSnapshot<I>[N];
+    /** One integration by name, for its writes: `home.integration("daikin")?.client.write(setPower(true))`. */
+    integration: <N extends I["name"]>(name: N) => Extract<I, {
+        name: N;
+    }> | undefined;
+    /**
+     * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
+     * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+     */
+    refresh(name?: I["name"]): Promise<void>;
+    /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+    start(signal: AbortSignal): Promise<void>;
+};
+/**
+ * One read of everything, for a script, a test or a one-shot command: run the integrations until each has answered
+ * (connected or not), at most `ms` (15 s by default) or until `signal` aborts, then stop them and return the snapshot.
+ */
+export declare function settle<I extends Integration<any, string>>(integrations: readonly I[], options?: {
+    ms?: number;
+    clock?: Clock;
+    signal?: AbortSignal;
+}): Promise<HomeSnapshot<I>>;

package/dist/home.js

@@ -0,0 +1,114 @@
+import { z } from "zod";
+import { asOf, realClock } from "./clock.js";
+import { errorText } from "./connector.js";
+/** A secret in a home config is the name of an environment variable, never the secret: a pasted key fails here. */
+export const envName = z
+    .string()
+    .regex(/^[A-Z_][A-Z0-9_]*$/, "an environment variable name (e.g. AMBER_KEY), not the secret itself");
+/** A file a connector needs (a CA, a token), relative to the config file. The caller reads it; the library reads no files. */
+export const filePath = z.string().min(1);
+/** The times `createHome` keeps on a part, from the one before it: when it was last good, and when it stopped being. */
+function stamped(part, before, now) {
+    if (part.status === "connected")
+        return {
+            ...part,
+            lastGoodAt: part.lastGoodAt ?? now,
+            downSince: undefined,
+        };
+    return {
+        ...part,
+        lastGoodAt: before?.lastGoodAt,
+        downSince: before?.downSince ?? now,
+    };
+}
+/**
+ * Load a home: run each integration, keep one snapshot, call `onChange` with it and what changed after every report.
+ * `clock` stamps each part's `lastGoodAt` and `downSince`.
+ */
+export function createHome(integrations, onChange, options = {}) {
+    const clock = options.clock ?? realClock;
+    let snapshot = Object.fromEntries(integrations.map((i) => [i.name, { status: "connecting" }]));
+    const waiting = new Map(); // refresh() callers, resolved by the integration's next report
+    const finished = new Set(); // integrations whose run has ended: a refresh of one resolves at once, nothing will report
+    const set = (name, reported) => {
+        const before = snapshot[name];
+        const part = stamped(reported, before, asOf(clock));
+        snapshot = { ...snapshot, [name]: part };
+        onChange?.(snapshot, { name, before, after: part });
+        const w = waiting.get(name);
+        if (w) {
+            waiting.delete(name);
+            for (const resolve of w)
+                resolve();
+        }
+    };
+    return {
+        /** The latest snapshot. Never touches a device. */
+        snapshot: () => snapshot,
+        /** One integration's part, typed by its name: `home.part("weather")?.state?.blocks`. */
+        part: (name) => snapshot[name],
+        /** One integration by name, for its writes: `home.integration("daikin")?.client.write(setPower(true))`. */
+        integration: (name) => integrations.find((i) => i.name === name),
+        /**
+         * Read now: one integration by name, or every one. Results arrive through the snapshot and `onChange` as usual; the
+         * promise resolves once each target has reported (its next update, good or bad), or at once for one whose run has ended.
+         */
+        refresh(name) {
+            const targets = name === undefined
+                ? integrations
+                : integrations.filter((i) => i.name === name);
+            if (!targets.length)
+                throw new Error(`no integration "${name}"; have ${integrations.map((i) => i.name).join(", ")}`);
+            const reported = targets.map((i) => new Promise((resolve) => {
+                if (finished.has(i.name))
+                    return resolve();
+                waiting.set(i.name, [...(waiting.get(i.name) ?? []), resolve]);
+            }));
+            for (const i of targets)
+                i.refresh();
+            return Promise.all(reported).then(() => undefined);
+        },
+        /** Run every integration until `signal` aborts. One failing marks itself unavailable; the rest carry on. */
+        async start(signal) {
+            finished.clear(); // a second start, after the first has stopped, runs them all again
+            const now = asOf(clock); // the wait for a first report counts from here, not from createHome
+            snapshot = Object.fromEntries(Object.entries(snapshot).map(([name, p]) => [
+                name,
+                p.status === "connecting"
+                    ? { ...p, downSince: p.downSince ?? now }
+                    : p,
+            ]));
+            await Promise.all(integrations.map((i) => i
+                .run(signal, (part) => set(i.name, part))
+                .catch((error) => set(i.name, { status: "unavailable", detail: errorText(error) }))
+                .finally(() => {
+                finished.add(i.name);
+                for (const resolve of waiting.get(i.name) ?? [])
+                    resolve(); // nothing more will report
+                waiting.delete(i.name);
+            })));
+        },
+    };
+}
+/** Answered: past connecting, and when the state lists sources (the weather), every source has read. */
+const answered = (p) => !!p &&
+    p.status !== "connecting" &&
+    Object.values(p.state?.sources ?? {}).every((s) => s.read);
+/**
+ * One read of everything, for a script, a test or a one-shot command: run the integrations until each has answered
+ * (connected or not), at most `ms` (15 s by default) or until `signal` aborts, then stop them and return the snapshot.
+ */
+export async function settle(integrations, options = {}) {
+    const { ms = 15_000, clock = realClock, signal } = options;
+    const stop = new AbortController();
+    const run = signal ? AbortSignal.any([signal, stop.signal]) : stop.signal; // the caller's signal stops it too, with nothing left on it after
+    const home = createHome(integrations, (snapshot) => {
+        if (Object.values(snapshot).every(answered))
+            stop.abort();
+    }, { clock });
+    const running = home.start(run);
+    await Promise.race([clock.sleep(ms, run), running]);
+    stop.abort();
+    await running;
+    return home.snapshot();
+}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export { type Change, createHome, envName, filePath, settle, type HomeSnapshot, type Integration, type Part, type StateOf, type Status, } from "./home.ts";
+export { DOWN_POLLS, type Health, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.ts";
+export { asOf, type Clock, realClock } from "./clock.ts";
+export { ConnectorError } from "./connector.ts";
+export { bestWindow, type EnergyNow, energyNow, gridText, type PriceWindow, solarLevel, } from "./energy.ts";
+export { checkHome, checkPlan, Device, HomeConfig, HomeConfigError, type HomeIntegration, type LoadOptions, loadHome, parseJsonc, Room, type Setup, } from "./config.ts";
+export type { AddressCache, CachedAddress, Connector, Finder, Found, } from "./discover.ts";
+export { type SunNow, sunNow } from "./connectors/weather/sun.ts";
+export { type RainSoon, rainSoon } from "./connectors/weather/rain.ts";
+export { type BlockDef, BLOCKS, blockText, type DayBlock, type DayBlocks, dayBlocks, } from "./connectors/weather/blocks.ts";
+export type { EnvVar, IotClass, Manifest } from "./manifest.ts";

package/dist/index.js

@@ -0,0 +1,11 @@
+// The root entry: the home, its config, discovery types, the clock, energy, and the sun, rain and day-block helpers. The weather types are in `./weather`.
+// Each connector has its own entry point (`@khalido/home/hue` and so on). Every export is named; test/exports.test.ts lists them.
+export { createHome, envName, filePath, settle, } from "./home.js";
+export { DOWN_POLLS, health, PUSH_DOWN_MS, STALE_POLLS, } from "./health.js";
+export { asOf, realClock } from "./clock.js";
+export { ConnectorError } from "./connector.js";
+export { bestWindow, energyNow, gridText, solarLevel, } from "./energy.js";
+export { checkHome, checkPlan, Device, HomeConfig, HomeConfigError, loadHome, parseJsonc, Room, } from "./config.js";
+export { sunNow } from "./connectors/weather/sun.js";
+export { rainSoon } from "./connectors/weather/rain.js";
+export { BLOCKS, blockText, dayBlocks, } from "./connectors/weather/blocks.js";

package/dist/lane.d.ts

@@ -0,0 +1,17 @@
+import { type Clock } from "./clock.ts";
+export type LaneOptions = {
+    /** Minimum time between two sends on the lane, across slots. */
+    gapMs: number;
+    /** At most this many sends per slot in any minute; more wait their turn, still coalescing. None: no cap. */
+    perMinute?: number;
+    clock?: Clock;
+};
+/**
+ * A write lane for one device or bridge. `send(slot, body, write, merge)` resolves with the result of the send that
+ * carried its body: a write merged into a later one resolves (or rejects) with that later one. `merge(older, newer)`
+ * defaults to the newer body alone.
+ */
+export declare function writeLane(options: LaneOptions): {
+    send<B, T>(slot: string, body: B, write: (body: B) => Promise<T>, merge?: (older: B, newer: B) => B): Promise<T>;
+};
+export type WriteLane = ReturnType<typeof writeLane>;

package/dist/lane.js

@@ -0,0 +1,74 @@
+import { realClock } from "./clock.js";
+const MINUTE = 60_000;
+/**
+ * A write lane for one device or bridge. `send(slot, body, write, merge)` resolves with the result of the send that
+ * carried its body: a write merged into a later one resolves (or rejects) with that later one. `merge(older, newer)`
+ * defaults to the newer body alone.
+ */
+export function writeLane(options) {
+    if (options.perMinute !== undefined && !(options.perMinute >= 1))
+        throw new RangeError(`writeLane: perMinute must be at least 1, got ${options.perMinute}`);
+    const clock = options.clock ?? realClock;
+    const queue = []; // in order of each slot's first waiting write
+    const sent = new Map(); // send times per slot, the last minute's
+    let lastAt = -Infinity;
+    let running = false;
+    let wake = new AbortController();
+    const recent = (slot) => (sent.get(slot) ?? []).filter((t) => t > clock.now() - MINUTE);
+    function readyAt(slot) {
+        const times = recent(slot);
+        const capped = options.perMinute !== undefined && times.length >= options.perMinute
+            ? times[times.length - options.perMinute] + MINUTE
+            : -Infinity;
+        return Math.max(lastAt + options.gapMs, capped);
+    }
+    async function run() {
+        running = true;
+        while (queue.length) {
+            const now = clock.now();
+            const next = queue.find((p) => readyAt(p.slot) <= now);
+            if (!next) {
+                wake = new AbortController();
+                await clock.sleep(Math.min(...queue.map((p) => readyAt(p.slot))) - now, wake.signal);
+                continue;
+            }
+            queue.splice(queue.indexOf(next), 1);
+            lastAt = now;
+            sent.set(next.slot, [...recent(next.slot), now]);
+            try {
+                const result = await next.write(next.body);
+                for (const w of next.waiters)
+                    w.resolve(result);
+            }
+            catch (error) {
+                for (const w of next.waiters)
+                    w.reject(error);
+            }
+        }
+        running = false;
+    }
+    return {
+        send(slot, body, write, merge = (_, newer) => newer) {
+            return new Promise((resolve, reject) => {
+                const waiter = { resolve, reject };
+                const waiting = queue.find((p) => p.slot === slot);
+                if (waiting) {
+                    waiting.body = merge(waiting.body, body);
+                    waiting.write = write;
+                    waiting.waiters.push(waiter);
+                    return;
+                }
+                queue.push({
+                    slot,
+                    body,
+                    write: write,
+                    waiters: [waiter],
+                });
+                if (running)
+                    wake.abort(); // a sleeping lane looks again: this slot may be ready sooner
+                else
+                    void run();
+            });
+        },
+    };
+}

package/dist/locate.d.ts

@@ -0,0 +1,27 @@
+export type Located = {
+    name: string;
+    latitude: number;
+    longitude: number;
+};
+/**
+ * The best match for `address`, or undefined when Nominatim finds none. Its usage policy requires a User-Agent that
+ * names the application, and allows one request a second: this is for a one-off lookup, not a loop.
+ */
+export declare function geocode(address: string, options: {
+    fetch?: typeof fetch;
+    userAgent: string;
+    signal?: AbortSignal;
+}): Promise<Located | undefined>;
+/**
+ * A config's text with `location.latitude` and `.longitude` set and, when it has none, `.timezone`, through
+ * jsonc-parser's edits: comments and every other key stay. With no `location` (absent or commented out) a fresh one is
+ * added, and `fresh` says so; a commented-out one is left as it was.
+ */
+export declare function applyLocation(text: string, at: {
+    latitude: number;
+    longitude: number;
+}, timeZone: string): {
+    text: string;
+    fresh: boolean;
+    timezoneSet: boolean;
+};