@domicile-desktop/system-network 0.0.0-alpha-a2a1a1a59e77

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Connor Prussin
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,38 @@
+# @domicile-desktop/system-network
+
+NetworkManager for a Domicile shell: connectivity and the primary connection,
+with the Wi-Fi network's name and signal. Built on
+[`@domicile-desktop/sdk/system`](../chrome-sdk/README.md).
+
+## Usage
+
+```ts
+import { system } from "@domicile-desktop/sdk/system";
+import { watchNetwork } from "@domicile-desktop/system-network/network";
+
+const stop = watchNetwork(system(domicile), (network) => {
+  network.match({
+    Err: () => hide(),
+    Ok: ({ connectivity, link }) => show(connectivity, link),
+  });
+});
+```
+
+- Reports the network once, then after each change NetworkManager signals
+  (`PropertiesChanged`) on the objects it read: the manager, the primary
+  connection and its access point.
+- `link` is `None`, `Wired`, `Wifi` (SSID and strength, 0 through 1) or
+  `Other` (VPNs and the rest), by NetworkManager's connection type.
+- An `Err` is a D-Bus failure, such as NetworkManager not running.
+- A bug or an unexpected reply shape throws, logged to the console.
+
+See [SHELL-SYSTEM-ACCESS.md](/docs/SHELL-SYSTEM-ACCESS.md).
+
+## Test
+
+```sh
+bun run turbo test --filter @domicile-desktop/system-network
+```
+
+Tests replay D-Bus replies, in the compositor's JSON, through an injected
+`System`.

package/dist/network.d.ts

@@ -0,0 +1,54 @@
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+/** Whether the host reaches the internet. */
+export declare enum Connectivity {
+    Unknown = 0,
+    None = 1,
+    /** Behind a captive portal. */
+    Portal = 2,
+    /** On a network, without the internet. */
+    Limited = 3,
+    Full = 4
+}
+export declare enum LinkKind {
+    None = 0,
+    Wired = 1,
+    Wifi = 2,
+    Other = 3
+}
+/** The primary connection. `name` is the connection's name in NetworkManager. */
+export declare const Link: {
+    None: () => {
+        kind: LinkKind.None;
+    };
+    /** A VPN, a bridge, a modem and the rest. */
+    Other: (name: string) => {
+        kind: LinkKind.Other;
+        name: string;
+    };
+    /** `strength` is 0 through 1. */
+    Wifi: (ssid: string, strength: number) => {
+        kind: LinkKind.Wifi;
+        ssid: string;
+        strength: number;
+    };
+    Wired: (name: string) => {
+        kind: LinkKind.Wired;
+        name: string;
+    };
+};
+export type Link = ReturnType<(typeof Link)[keyof typeof Link]>;
+export type Network = {
+    connectivity: Connectivity;
+    link: Link;
+};
+/** The calls this library makes. */
+export type NetworkSystem = Pick<System, "dbusCall" | "dbusMatch">;
+/**
+ * Calls `onNetwork` with the network now and after each change, and returns a
+ * function that stops watching.
+ *
+ * An `Err` is a D-Bus failure, such as NetworkManager not running. The watch
+ * keeps listening after one, so a later change reads again.
+ */
+export declare const watchNetwork: (system: NetworkSystem, onNetwork: (network: Result<Network, SystemError>) => void) => (() => void);

package/dist/network.js

@@ -0,0 +1,206 @@
+// NetworkManager over the system bus: connectivity and the primary
+// connection, kept current. See docs/SHELL-SYSTEM-ACCESS.md.
+import { Err, Ok } from "@cprussin/option-result";
+import { Bus } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+const SERVICE = "org.freedesktop.NetworkManager";
+const ROOT = "/org/freedesktop/NetworkManager";
+/** The object path NetworkManager uses for "none". */
+const NO_OBJECT = "/";
+/** Whether the host reaches the internet. */
+export var Connectivity;
+(function (Connectivity) {
+    Connectivity[Connectivity["Unknown"] = 0] = "Unknown";
+    Connectivity[Connectivity["None"] = 1] = "None";
+    /** Behind a captive portal. */
+    Connectivity[Connectivity["Portal"] = 2] = "Portal";
+    /** On a network, without the internet. */
+    Connectivity[Connectivity["Limited"] = 3] = "Limited";
+    Connectivity[Connectivity["Full"] = 4] = "Full";
+})(Connectivity || (Connectivity = {}));
+export var LinkKind;
+(function (LinkKind) {
+    LinkKind[LinkKind["None"] = 0] = "None";
+    LinkKind[LinkKind["Wired"] = 1] = "Wired";
+    LinkKind[LinkKind["Wifi"] = 2] = "Wifi";
+    LinkKind[LinkKind["Other"] = 3] = "Other";
+})(LinkKind || (LinkKind = {}));
+/** The primary connection. `name` is the connection's name in NetworkManager. */
+export const Link = {
+    None: () => ({ kind: LinkKind.None }),
+    /** A VPN, a bridge, a modem and the rest. */
+    Other: (name) => ({ kind: LinkKind.Other, name }),
+    /** `strength` is 0 through 1. */
+    Wifi: (ssid, strength) => ({
+        kind: LinkKind.Wifi,
+        ssid,
+        strength,
+    }),
+    Wired: (name) => ({ kind: LinkKind.Wired, name }),
+};
+/**
+ * Calls `onNetwork` with the network now and after each change, and returns a
+ * function that stops watching.
+ *
+ * An `Err` is a D-Bus failure, such as NetworkManager not running. The watch
+ * keeps listening after one, so a later change reads again.
+ */
+export const watchNetwork = (system, onNetwork) => {
+    const watch = { listening: undefined, stopped: false };
+    const report = (network) => {
+        if (!watch.stopped) {
+            onNetwork(network);
+        }
+    };
+    follow(system, watch, report).catch((error) => {
+        // biome-ignore lint/suspicious/noConsole: surfacing a background failure
+        console.error("Failed to watch the network", error);
+    });
+    return () => {
+        watch.stopped = true;
+        watch.listening?.stop();
+    };
+};
+/** Listen, read, then read again on each change until the match ends. */
+const follow = async (system, watch, report) => {
+    const matched = await system.dbusMatch({
+        bus: Bus.System,
+        interface: "org.freedesktop.DBus.Properties",
+        member: "PropertiesChanged",
+        sender: SERVICE,
+    });
+    await matched.match({
+        Err: (error) => {
+            report(Err(error));
+            return Promise.resolve();
+        },
+        Ok: async (listening) => {
+            watch.listening = listening;
+            if (watch.stopped) {
+                listening.stop();
+            }
+            await changes(system, listening, report);
+            const ended = await listening.ended;
+            ended.match({
+                Err: (error) => {
+                    report(Err(error));
+                },
+                Ok: () => {
+                    /* stopped by the caller */
+                },
+            });
+        },
+    });
+};
+/** Read now, and again on each signal from an object the network uses. */
+const changes = async (system, listening, report) => {
+    const reader = listening.items.getReader();
+    const first = await read(system);
+    report(first.network);
+    let paths = first.paths;
+    for (let next = await reader.read(); !next.done; next = await reader.read()) {
+        if (paths.has(next.value.path)) {
+            const again = await read(system);
+            report(again.network);
+            paths = again.paths;
+        }
+    }
+};
+const read = async (system) => {
+    const root = await properties(system, ROOT, SERVICE, rootSchema);
+    return root.match({
+        Err: (error) => Promise.resolve({ network: Err(error), paths: new Set([ROOT]) }),
+        Ok: async ({ Connectivity: connectivity, PrimaryConnection: primary }) => {
+            const link = await linkOf(system, primary);
+            return {
+                network: link.result.map((found) => ({
+                    connectivity,
+                    link: found,
+                })),
+                paths: new Set([ROOT, ...link.paths]),
+            };
+        },
+    });
+};
+/** The primary connection at `path`. */
+const linkOf = async (system, path) => {
+    if (path === NO_OBJECT) {
+        return { paths: [], result: Ok(Link.None()) };
+    }
+    else {
+        const active = await properties(system, path, `${SERVICE}.Connection.Active`, activeSchema);
+        return active.match({
+            Err: (error) => Promise.resolve({ paths: [path], result: Err(error) }),
+            Ok: async ({ Id: name, SpecificObject: specific, Type: type, }) => {
+                switch (type) {
+                    case "802-11-wireless": {
+                        const point = await properties(system, specific, `${SERVICE}.AccessPoint`, accessPointSchema);
+                        return {
+                            paths: [path, specific],
+                            result: point.map(({ Ssid: ssid, Strength: strength }) => Link.Wifi(new TextDecoder().decode(new Uint8Array(ssid)), strength / 100)),
+                        };
+                    }
+                    case "802-3-ethernet": {
+                        return { paths: [path], result: Ok(Link.Wired(name)) };
+                    }
+                    default: {
+                        return { paths: [path], result: Ok(Link.Other(name)) };
+                    }
+                }
+            },
+        });
+    }
+};
+/** `Properties.GetAll` on one of NetworkManager's objects, parsed. */
+const properties = async (system, path, interfaceName, schema) => (await system.dbusCall({
+    body: [interfaceName],
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.Properties",
+    member: "GetAll",
+    path,
+    signature: "s",
+})).map(({ body }) => z.tuple([schema]).parse(body)[0]);
+/** A `v`, as `domicile_host::dbus_json` writes it, read as its value. */
+const variant = (value) => z.object({ value }).transform(({ value: held }) => held);
+/** NetworkManager's `NMConnectivityState`. */
+const connectivityOf = (value) => {
+    switch (value) {
+        case 0: {
+            return Connectivity.Unknown;
+        }
+        case 1: {
+            return Connectivity.None;
+        }
+        case 2: {
+            return Connectivity.Portal;
+        }
+        case 3: {
+            return Connectivity.Limited;
+        }
+        case 4: {
+            return Connectivity.Full;
+        }
+    }
+};
+const rootSchema = z.object({
+    Connectivity: variant(z
+        .union([
+        z.literal(0),
+        z.literal(1),
+        z.literal(2),
+        z.literal(3),
+        z.literal(4),
+    ])
+        .transform(connectivityOf)),
+    PrimaryConnection: variant(z.string()),
+});
+const activeSchema = z.object({
+    Id: variant(z.string()),
+    SpecificObject: variant(z.string()),
+    Type: variant(z.string()),
+});
+const accessPointSchema = z.object({
+    Ssid: variant(z.array(z.number())),
+    Strength: variant(z.number()),
+});

package/package.json

@@ -0,0 +1,40 @@
+{
+  "dependencies": {
+    "@cprussin/option-result": "^2.0.1",
+    "@domicile-desktop/sdk": "0.0.0-alpha-a2a1a1a59e77",
+    "zod": "^4.5.4"
+  },
+  "description": "NetworkManager for a Domicile shell: connectivity and the primary connection, with its Wi-Fi network and signal, kept current.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    "./network": {
+      "types": "./dist/network.d.ts",
+      "default": "./dist/network.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/system-network",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/system-network",
+    "type": "git",
+    "url": "git+https://github.com/cprussin/domicile.git"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test:types": "tsc --noEmit",
+    "test:unit": "bun test"
+  },
+  "type": "module",
+  "version": "0.0.0-alpha-a2a1a1a59e77"
+}