@domicile-desktop/system-bluetooth 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-bluetooth
+
+BlueZ for a Domicile shell: each adapter and whether it is powered, the
+connected devices, and turning an adapter on or off. Built on
+[`@domicile-desktop/sdk/system`](../chrome-sdk/README.md).
+
+## Usage
+
+```ts
+import { system } from "@domicile-desktop/sdk/system";
+import { setPowered, watchBluetooth } from "@domicile-desktop/system-bluetooth/bluetooth";
+
+const host = system(domicile);
+const stop = watchBluetooth(host, (bluetooth) => {
+  bluetooth.match({
+    Err: () => hide(),
+    Ok: ({ adapters, connected }) => show(adapters, connected),
+  });
+});
+await setPowered(host, "/org/bluez/hci0", false);
+```
+
+- Reads `GetManagedObjects` once, then again when an object comes or goes or
+  an adapter's `Powered` or a device's `Connected` or `Alias` changes.
+- An `Err` is a D-Bus failure, such as BlueZ not running or an adapter
+  blocked by rfkill.
+- 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-bluetooth
+```
+
+Tests replay D-Bus replies, in the compositor's JSON, through an injected
+`System`.

package/dist/bluetooth.d.ts

@@ -0,0 +1,28 @@
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+/** A controller, such as `/org/bluez/hci0`. */
+export type Adapter = {
+    path: string;
+    powered: boolean;
+};
+/** A connected device. `name` is its alias, which BlueZ fills from its name. */
+export type Device = {
+    path: string;
+    name: string;
+};
+export type Bluetooth = {
+    adapters: Adapter[];
+    connected: Device[];
+};
+/** The calls this library makes. */
+export type BluetoothSystem = Pick<System, "dbusCall" | "dbusMatch">;
+/**
+ * Calls `onBluetooth` with the adapters and connected devices now and after
+ * each change, and returns a function that stops watching.
+ *
+ * An `Err` is a D-Bus failure, such as BlueZ not running. The watch keeps
+ * listening after one, so a later change reads again.
+ */
+export declare const watchBluetooth: (system: BluetoothSystem, onBluetooth: (bluetooth: Result<Bluetooth, SystemError>) => void) => (() => void);
+/** Turn the adapter at `adapter` on or off. */
+export declare const setPowered: (system: Pick<System, "dbusCall">, adapter: string, powered: boolean) => Promise<Result<"set", SystemError>>;

package/dist/bluetooth.js

@@ -0,0 +1,138 @@
+// BlueZ over the system bus: adapters and connected devices, kept current.
+// See docs/SHELL-SYSTEM-ACCESS.md.
+import { Err } from "@cprussin/option-result";
+import { Bus } from "@domicile-desktop/sdk/system";
+import { z } from "zod";
+const SERVICE = "org.bluez";
+const ADAPTER = "org.bluez.Adapter1";
+const DEVICE = "org.bluez.Device1";
+/** The properties whose changes alter a {@link Bluetooth}, by interface. */
+const WATCHED = {
+    [ADAPTER]: ["Powered"],
+    [DEVICE]: ["Alias", "Connected"],
+};
+/**
+ * Calls `onBluetooth` with the adapters and connected devices now and after
+ * each change, and returns a function that stops watching.
+ *
+ * An `Err` is a D-Bus failure, such as BlueZ not running. The watch keeps
+ * listening after one, so a later change reads again.
+ */
+export const watchBluetooth = (system, onBluetooth) => {
+    const watch = { listening: undefined, stopped: false };
+    const report = (bluetooth) => {
+        if (!watch.stopped) {
+            onBluetooth(bluetooth);
+        }
+    };
+    follow(system, watch, report).catch((error) => {
+        // biome-ignore lint/suspicious/noConsole: surfacing a background failure
+        console.error("Failed to watch Bluetooth", error);
+    });
+    return () => {
+        watch.stopped = true;
+        watch.listening?.stop();
+    };
+};
+/** Turn the adapter at `adapter` on or off. */
+export const setPowered = async (system, adapter, powered) => (await system.dbusCall({
+    body: [ADAPTER, "Powered", { signature: "b", value: powered }],
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.Properties",
+    member: "Set",
+    path: adapter,
+    signature: "ssv",
+})).map(() => "set");
+/** 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, 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 that changes what was read. */
+const changes = async (system, listening, report) => {
+    const reader = listening.items.getReader();
+    report(await read(system));
+    for (let next = await reader.read(); !next.done; next = await reader.read()) {
+        if (matters(next.value)) {
+            report(await read(system));
+        }
+    }
+};
+/**
+ * Whether `signal` can change a {@link Bluetooth}: an object coming or going,
+ * or a watched property. Signal strength and the like change often during a
+ * scan and are skipped.
+ */
+const matters = (signal) => {
+    switch (signal.member) {
+        case "InterfacesAdded":
+        case "InterfacesRemoved": {
+            return true;
+        }
+        case "PropertiesChanged": {
+            const [iface, changed] = propertiesChangedSchema.parse(signal.body);
+            return (WATCHED[iface] ?? []).some((name) => name in changed);
+        }
+        default: {
+            return false;
+        }
+    }
+};
+const read = async (system) => (await system.dbusCall({
+    bus: Bus.System,
+    destination: SERVICE,
+    interface: "org.freedesktop.DBus.ObjectManager",
+    member: "GetManagedObjects",
+    path: "/",
+})).map(({ body }) => bluetoothOf(managedObjectsSchema.parse(body)[0]));
+const bluetoothOf = (objects) => {
+    const entries = Object.entries(objects);
+    return {
+        adapters: entries.flatMap(([path, held]) => held[ADAPTER] === undefined
+            ? []
+            : [{ path, powered: held[ADAPTER].Powered }]),
+        connected: entries.flatMap(([path, held]) => held[DEVICE]?.Connected === true
+            ? [{ name: held[DEVICE].Alias, path }]
+            : []),
+    };
+};
+/** A `v`, as `domicile_host::dbus_json` writes it, read as its value. */
+const variant = (value) => z.object({ value }).transform(({ value: held }) => held);
+const managedObjectsSchema = z.tuple([
+    z.record(z.string(), z.object({
+        [ADAPTER]: z.object({ Powered: variant(z.boolean()) }).optional(),
+        [DEVICE]: z
+            .object({
+            Alias: variant(z.string()),
+            Connected: variant(z.boolean()),
+        })
+            .optional(),
+    })),
+]);
+const propertiesChangedSchema = z.tuple([
+    z.string(),
+    z.record(z.string(), z.unknown()),
+    z.array(z.string()),
+]);

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": "BlueZ for a Domicile shell: whether each adapter is powered and which devices are connected, kept current, and turning adapters on and off.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    "./bluetooth": {
+      "types": "./dist/bluetooth.d.ts",
+      "default": "./dist/bluetooth.js"
+    }
+  },
+  "files": [
+    "dist/**"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/system-bluetooth",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/system-bluetooth",
+    "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"
+}