@domicile-desktop/system-apps 0.0.0-alpha-a330bf5f3aae

package/README.md

@@ -0,0 +1,50 @@
+# @domicile-desktop/system-apps
+
+Installed applications and bookmarks for a shell's launcher, read through
+[`@domicile-desktop/sdk/system`](../chrome-sdk/README.md). Manganese's launcher
+uses it (`src/launcher/app-search.ts`).
+
+## Usage
+
+```ts
+import { system } from "@domicile-desktop/sdk/system";
+import { appIcons } from "@domicile-desktop/system-apps/app-icons";
+import { dataDirs } from "@domicile-desktop/system-apps/data-dirs";
+import { findApps } from "@domicile-desktop/system-apps/find-apps";
+import { installedApps } from "@domicile-desktop/system-apps/installed";
+
+const host = system(domicile);
+const dirs = (await dataDirs(host)).unwrapOr([]);
+const apps = (await installedApps(host, dirs)).unwrapOr([]);
+const icon = appIcons(host, dirs);
+const editors = findApps(apps, "edit", 50);
+```
+
+## Modules
+
+| Module | What it is |
+| --- | --- |
+| `./data-dirs` | The XDG data directories, from the desktop's environment (`env -0`). |
+| `./installed` | Every desktop entry under them; an earlier directory hides a later one's ID. |
+| `./desktop-entry` | One entry parsed: name, comment, argv, icon and `X-Domicile-Preview`. |
+| `./find-apps`, `./bookmark` | The launcher's matching and ranking; bookmarks and their Zod schema. |
+| `./mime-apps` | A content type's default applications from every `mimeapps.list`, the desktop's own (`domicile-mimeapps.list`) first. |
+| `./omit` | Desktop file IDs left out, as globs. |
+| `./app-icons` | Icon names resolved in `hicolor` and `pixmaps` to `data:` URLs (PNG, SVG, 128 KiB at most). |
+| `./favicon`, `./curl`, `./favicons` | A bookmark's icon: picked from the page, fetched with `curl`, kept and retried. |
+| `./fake-system` | A `System` over an in-memory tree, for tests. |
+
+- Calls resolve `Result`s with the SDK's `SystemError`; a missing or
+  unreadable file or directory is skipped, as the specs say.
+- `./curl` needs `curl` on the desktop's `PATH`. Domicile's Nix package adds
+  it.
+- Launching stays with the shell: pass an entry's `command` to `spawn`.
+
+## Test
+
+```sh
+bun run turbo test --filter @domicile-desktop/system-apps
+```
+
+Entry parsing is tested on files under `src/recorded/`, copied from real
+installs.

package/package.json

@@ -0,0 +1,50 @@
+{
+  "dependencies": {
+    "@cprussin/option-result": "^2.0.1",
+    "@domicile-desktop/sdk": "0.0.0-alpha-a330bf5f3aae",
+    "zod": "^4.5.4"
+  },
+  "description": "Installed applications and bookmarks for a Domicile shell's launcher, read through @domicile-desktop/sdk/system.",
+  "devDependencies": {
+    "@cprussin/tsconfig": "^5.0.0",
+    "@domicile-desktop/test-support": "0.0.0",
+    "@types/bun": "^1.4.2",
+    "typescript": "^7.0.2"
+  },
+  "exports": {
+    "./app-icons": "./src/app-icons.ts",
+    "./bookmark": "./src/bookmark.ts",
+    "./curl": "./src/curl.ts",
+    "./data-dirs": "./src/data-dirs.ts",
+    "./desktop-entry": "./src/desktop-entry.ts",
+    "./fake-system": "./src/fake-system.ts",
+    "./favicon": "./src/favicon.ts",
+    "./favicons": "./src/favicons.ts",
+    "./find-apps": "./src/find-apps.ts",
+    "./installed": "./src/installed.ts",
+    "./mime-apps": "./src/mime-apps.ts",
+    "./omit": "./src/omit.ts"
+  },
+  "files": [
+    "src/**",
+    "!src/**/*.test.ts",
+    "!src/recorded/**"
+  ],
+  "license": "MIT",
+  "name": "@domicile-desktop/system-apps",
+  "private": false,
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "directory": "packages/system-apps",
+    "type": "git",
+    "url": "git+https://github.com/cprussin/domicile.git"
+  },
+  "scripts": {
+    "test:types": "tsc --noEmit",
+    "test:unit": "bun test"
+  },
+  "type": "module",
+  "version": "0.0.0-alpha-a330bf5f3aae"
+}

package/src/app-icons.ts

@@ -0,0 +1,161 @@
+// Desktop-entry icon names resolved to `data:` URLs, for `Icon` and
+// `X-Domicile-Preview`.
+//
+// Follows the icon theme spec: `icons/hicolor/<size>/apps/<name>.<ext>` under
+// each data directory, then `pixmaps/<name>.<ext>`. Only `hicolor` is
+// searched: every application installs into it and every theme inherits it.
+
+import type { Option, Result } from "@cprussin/option-result";
+import { None, Ok, Some } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+
+import { dataUrl } from "./data-url";
+import { allOk, orAbsent } from "./results";
+
+/**
+ * Icon sizes to try, most preferred first. The first few are large enough for
+ * a preview and small enough to draw in every row.
+ */
+const SIZES = [
+  "48x48",
+  "64x64",
+  "32x32",
+  "96x96",
+  "128x128",
+  "scalable",
+  "256x256",
+  "24x24",
+  "22x22",
+  "16x16",
+  "512x512",
+];
+
+/** Extensions a page can draw, preferred first, and their MIME types. */
+const KINDS: Readonly<Record<string, string>> = {
+  png: "image/png",
+  svg: "image/svg+xml",
+};
+
+/** Largest icon read. Every matched row draws one, so a larger file is skipped. */
+const LARGEST = 128 * 1024;
+
+/** An icon by name, as a `data:` URL, or nothing if none is usable. */
+export type IconLookup = (
+  name: string,
+) => Promise<Result<Option<string>, SystemError>>;
+
+/** A directory icons may be in, and the file names it holds. */
+type Listed = { dir: string; names: ReadonlySet<string> };
+
+/**
+ * Icons under `dataDirs`, highest priority first. An absolute name is read as
+ * a file, as the spec allows.
+ *
+ * Lists the theme's directories once, on the first lookup, and each name
+ * once. Make a new lookup to see newly installed icons.
+ */
+export const appIcons = (
+  system: System,
+  dataDirs: readonly string[],
+): IconLookup => {
+  let listed: Promise<Result<Listed[], SystemError>> | undefined;
+  const looked = new Map<
+    string,
+    Promise<Result<Option<string>, SystemError>>
+  >();
+  return (name) => {
+    const known = looked.get(name);
+    if (known === undefined) {
+      listed ??= listings(system, dataDirs);
+      const lookup = name.startsWith("/")
+        ? read(system, name)
+        : listed.then((dirs) =>
+            dirs.andThenAsync((each) => firstUsable(system, each, name)),
+          );
+      looked.set(name, lookup);
+      return lookup;
+    } else {
+      return known;
+    }
+  };
+};
+
+/** Every directory an icon may be in, in the order to search them. */
+const listings = async (
+  system: System,
+  dataDirs: readonly string[],
+): Promise<Result<Listed[], SystemError>> => {
+  const themed = allOk(
+    await Promise.all(dataDirs.map((dir) => themeDirs(system, dir))),
+  ).map((dirs) => dirs.flat());
+  const pixmaps = dataDirs.map((dir) => `${dir}/pixmaps`);
+  return themed.andThenAsync(async (dirs) =>
+    allOk(
+      await Promise.all(
+        [...dirs, ...pixmaps].map(async (dir) =>
+          orAbsent(await system.readDir(dir), []).map(
+            (entries): Listed => ({
+              dir,
+              names: new Set(entries.map((entry) => entry.name)),
+            }),
+          ),
+        ),
+      ),
+    ),
+  );
+};
+
+/** `hicolor`'s `apps` directories under `dataDir`, by preferred size. */
+const themeDirs = async (
+  system: System,
+  dataDir: string,
+): Promise<Result<string[], SystemError>> => {
+  const theme = `${dataDir}/icons/hicolor`;
+  return orAbsent(await system.readDir(theme), []).map((entries) => {
+    const sizes = new Set(entries.map((entry) => entry.name));
+    return SIZES.filter((size) => sizes.has(size)).map(
+      (size) => `${theme}/${size}/apps`,
+    );
+  });
+};
+
+/** The first of `name`'s files in `dirs` that can be drawn. */
+const firstUsable = async (
+  system: System,
+  dirs: readonly Listed[],
+  name: string,
+): Promise<Result<Option<string>, SystemError>> => {
+  const candidates = dirs.flatMap(({ dir, names }) =>
+    Object.keys(KINDS)
+      .map((kind) => `${name}.${kind}`)
+      .filter((file) => names.has(file))
+      .map((file) => `${dir}/${file}`),
+  );
+  for (const path of candidates) {
+    const icon = await read(system, path);
+    if (icon.mapOr(true, (found) => found.isSome())) {
+      return icon;
+    }
+  }
+  return Ok(None());
+};
+
+/** The file at `path` as a `data:` URL, or nothing if it cannot be drawn. */
+const read = async (
+  system: System,
+  path: string,
+): Promise<Result<Option<string>, SystemError>> => {
+  const mime = KINDS[path.slice(path.lastIndexOf(".") + 1)];
+  return mime === undefined
+    ? Ok(None())
+    : orAbsent(
+        await (await system.stat(path)).andThenAsync(async ({ size }) =>
+          size > LARGEST
+            ? Ok(None<string>())
+            : (await system.readFile(path)).map((bytes) =>
+                Some(dataUrl(mime, bytes)),
+              ),
+        ),
+        None(),
+      );
+};

package/src/bookmark.ts

@@ -0,0 +1,39 @@
+// Web pages a launcher offers by name, beside the applications.
+
+import { z } from "zod";
+
+import { ranked } from "./ranked";
+
+/**
+ * A launcher row that opens `url`. Only `http` and `https`: the launcher opens
+ * it as a page and fetches the site's icon from it.
+ */
+const bookmarkSchema = z.strictObject({
+  /** The row's label, which queries match. */
+  name: z.string(),
+  url: z
+    .string()
+    .regex(/^https?:\/\/./i, "a bookmark's URL must be http or https"),
+});
+
+/** A shell's bookmarks, as its config gives them. */
+export const bookmarksSchema = z.array(bookmarkSchema).readonly();
+
+export type Bookmark = z.infer<typeof bookmarkSchema>;
+
+/**
+ * Up to `limit` bookmarks matching `query`, best first.
+ *
+ * Matches as `findApps` does, so rows agree: every query word must appear,
+ * case-insensitively, in the name or URL.
+ */
+export const findBookmarks = (
+  bookmarks: readonly Bookmark[],
+  query: string,
+  limit: number,
+): Bookmark[] =>
+  ranked(bookmarks, query, limit, {
+    name: ({ name }) => name,
+    tieBreak: ({ url }) => url,
+    words: ({ name, url }) => `${name} ${url}`.toLowerCase(),
+  });

package/src/curl.ts

@@ -0,0 +1,54 @@
+// Fetching a web page with `curl`. A shell page cannot: other sites do not
+// allow its origin to read their answers.
+
+import { None, Some } from "@cprussin/option-result";
+import type { System } from "@domicile-desktop/sdk/system";
+
+import type { Fetch, Page } from "./favicon";
+
+/** Seconds a site may take. Lookups run one at a time. */
+const PATIENCE = "10";
+
+/** A browser's user agent, since some sites serve other clients a different page. */
+const USER_AGENT =
+  "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/140.0 Safari/537.36";
+
+/**
+ * Fetches with the `curl` on the desktop's `PATH`, following redirects. Sends
+ * no cookies. A site that does not answer, or answers with an error, is
+ * nothing.
+ */
+export const curlFetch =
+  (system: System): Fetch =>
+  async (url) =>
+    (
+      await system.spawn([
+        "curl",
+        "--silent",
+        "--fail",
+        "--location",
+        "--max-time",
+        PATIENCE,
+        "--user-agent",
+        USER_AGENT,
+        // After the body, on stderr: where it landed, then its type.
+        "--write-out",
+        "%{stderr}%{url_effective}\n%{content_type}",
+        url,
+      ])
+    ).andThenAsync(async (curl) => {
+      const [body, written, exited] = await Promise.all([
+        new Response(curl.stdout).arrayBuffer(),
+        new Response(curl.stderr).text(),
+        curl.exited,
+      ]);
+      return exited.map(({ code }) => {
+        const [landed = url, contentType = ""] = written.split("\n");
+        const page: Page = {
+          body: new Uint8Array(body),
+          contentType: contentType === "" ? undefined : contentType,
+          url: landed,
+        };
+        return code === 0 ? Some(page) : None<Page>();
+      });
+    });

package/src/data-dirs.ts

@@ -0,0 +1,28 @@
+// The XDG data directories, where desktop entries and icons are installed. See
+// https://specifications.freedesktop.org/basedir-spec/latest/.
+
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+
+import { desktopEnvironment, setVariable } from "./environment";
+
+/** The spec's default for an unset or empty `XDG_DATA_DIRS`. */
+const DEFAULT_DATA_DIRS = "/usr/local/share:/usr/share";
+
+/**
+ * The desktop's data directories, highest priority first: `XDG_DATA_HOME`,
+ * then each of `XDG_DATA_DIRS`.
+ *
+ * Read from the environment processes start in, which a page cannot see. An
+ * unset data home is `.local/share`, relative to the home as every system
+ * call's path is.
+ */
+export const dataDirs = async (
+  system: System,
+): Promise<Result<string[], SystemError>> =>
+  (await desktopEnvironment(system)).map((variables) => [
+    setVariable(variables, "XDG_DATA_HOME") ?? ".local/share",
+    ...(setVariable(variables, "XDG_DATA_DIRS") ?? DEFAULT_DATA_DIRS).split(
+      ":",
+    ),
+  ]);

package/src/data-url.ts

@@ -0,0 +1,12 @@
+// Bytes as a `data:` URL, so a page can draw a file it cannot fetch.
+
+/** Bytes passed to `String.fromCharCode` at once, under its argument limit. */
+const CHUNK = 0x80_00;
+
+export const dataUrl = (mime: string, bytes: Uint8Array): string => {
+  const chunks: string[] = [];
+  for (let at = 0; at < bytes.length; at += CHUNK) {
+    chunks.push(String.fromCharCode(...bytes.subarray(at, at + CHUNK)));
+  }
+  return `data:${mime};base64,${btoa(chunks.join(""))}`;
+};

package/src/desktop-entry.ts

@@ -0,0 +1,85 @@
+// A desktop entry file read into a launchable application. See
+// https://specifications.freedesktop.org/desktop-entry-spec/latest/.
+
+import type { Option } from "@cprussin/option-result";
+import { None } from "@cprussin/option-result";
+
+import { unescaped } from "./escapes";
+import { commandOf } from "./exec";
+
+/** The only group keys are read from. */
+const GROUP = "[Desktop Entry]";
+
+/** An application a desktop entry offers. */
+export type DesktopEntry = {
+  /** The desktop file ID: its path under `applications/`, `/` read as `-`. */
+  id: string;
+  name: string;
+  /** Empty for an entry with no `Comment`. */
+  comment: string;
+  /** The argv it runs. */
+  command: readonly string[];
+  /** `Name`, `GenericName` and `Keywords`, in lower case, for `findApps`. */
+  words: string;
+  /** `Icon`: a theme name or an absolute path. See `./app-icons`. */
+  icon: string | undefined;
+  /** `X-Domicile-Preview`, in the same form as `icon`. */
+  preview: string | undefined;
+};
+
+/**
+ * Entry `text` as `id`, or nothing if a launcher should not offer it.
+ *
+ * Reads only unlocalized keys in `[Desktop Entry]`. Rejects non-applications,
+ * `Hidden` or `NoDisplay` entries, entries without a `Name` or a readable
+ * `Exec`, and `Terminal` entries, since no terminal is configured.
+ */
+export const parseDesktopEntry = (
+  id: string,
+  text: string,
+): Option<DesktopEntry> => {
+  const keys = keysOf(text);
+  const flag = (key: string) => keys.get(key) === "true";
+  const name = keys.get("Name");
+  const exec = keys.get("Exec");
+  return keys.get("Type") !== "Application" ||
+    flag("Hidden") ||
+    flag("NoDisplay") ||
+    flag("Terminal") ||
+    name === undefined ||
+    exec === undefined
+    ? None()
+    : commandOf(exec).map((command) => ({
+        command,
+        comment: unescaped(keys.get("Comment") ?? ""),
+        icon: optional(keys.get("Icon")),
+        id,
+        name: unescaped(name),
+        preview: optional(keys.get("X-Domicile-Preview")),
+        words: [name, keys.get("GenericName") ?? "", keys.get("Keywords") ?? ""]
+          .map(unescaped)
+          .join("\n")
+          .toLowerCase(),
+      }));
+};
+
+/** The `[Desktop Entry]` group's keys; the first of a repeated key wins. */
+const keysOf = (text: string): ReadonlyMap<string, string> => {
+  const keys = new Map<string, string>();
+  let group = "";
+  for (const line of text.split("\n").map((each) => each.trim())) {
+    if (line.startsWith("[")) {
+      group = line;
+    } else if (group === GROUP && !line.startsWith("#")) {
+      const equals = line.indexOf("=");
+      const key = line.slice(0, equals).trim();
+      if (equals !== -1 && !keys.has(key)) {
+        keys.set(key, line.slice(equals + 1).trim());
+      }
+    }
+  }
+  return keys;
+};
+
+const optional = (value: string | undefined): string | undefined =>
+  value === undefined ? undefined : unescaped(value);

package/src/environment.ts

@@ -0,0 +1,37 @@
+// The desktop's environment, which a page cannot see.
+
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+
+/** The variables the shell's processes start with, read with `env -0`. */
+export const desktopEnvironment = async (
+  system: System,
+): Promise<Result<ReadonlyMap<string, string>, SystemError>> =>
+  (await system.run(["env", "-0"])).map((ran) => {
+    if (ran.code === 0) {
+      return environmentOf(ran.stdout);
+    } else {
+      throw new Error(`env failed: ${ran.stderr}`);
+    }
+  });
+
+/** Variable `name`, or `undefined` when unset or, per the XDG specs, empty. */
+export const setVariable = (
+  variables: ReadonlyMap<string, string>,
+  name: string,
+): string | undefined => {
+  const value = variables.get(name);
+  return value === "" ? undefined : value;
+};
+
+/** `env -0`'s output: `NAME=value`, each ended by a NUL. */
+const environmentOf = (output: string): ReadonlyMap<string, string> =>
+  new Map(
+    output
+      .split("\0")
+      .filter((variable) => variable.includes("="))
+      .map((variable) => {
+        const equals = variable.indexOf("=");
+        return [variable.slice(0, equals), variable.slice(equals + 1)];
+      }),
+  );

package/src/escapes.ts

@@ -0,0 +1,16 @@
+// The desktop entry spec's string escapes.
+
+const ESCAPES: Readonly<Record<string, string>> = {
+  "\\": "\\",
+  n: "\n",
+  r: "\r",
+  s: " ",
+  t: "\t",
+};
+
+/** `value` with `\s`, `\n`, `\t`, `\r` and `\\` resolved; any other `\` kept. */
+export const unescaped = (value: string): string =>
+  value.replaceAll(
+    /\\(.?)/gs,
+    (sequence, next: string) => ESCAPES[next] ?? sequence,
+  );

package/src/exec.ts

@@ -0,0 +1,44 @@
+// An `Exec` value read into argv, per the desktop entry spec.
+
+import type { Option } from "@cprussin/option-result";
+import { None, Some } from "@cprussin/option-result";
+
+import { unescaped } from "./escapes";
+
+/**
+ * `exec` as argv, or nothing if it is malformed or empty.
+ *
+ * Unescapes strings, then quoting, in the spec's order. Drops field codes,
+ * since a launcher passes no files, URLs or icon, along with any argument
+ * that was only a field code.
+ */
+export const commandOf = (exec: string): Option<string[]> => {
+  const words: string[] = [];
+  let word = "";
+  let quoted = false;
+  // Whether the previous character was a `\` inside quotes, or a `%`.
+  let escaping = false;
+  let fieldCode = false;
+  for (const char of unescaped(exec)) {
+    if (escaping) {
+      word += char;
+      escaping = false;
+    } else if (fieldCode) {
+      word += char === "%" ? "%" : "";
+      fieldCode = false;
+    } else if (char === '"') {
+      quoted = !quoted;
+    } else if (char === "\\" && quoted) {
+      escaping = true;
+    } else if (char === "%") {
+      fieldCode = true;
+    } else if (char === " " && !quoted) {
+      words.push(...(word === "" ? [] : [word]));
+      word = "";
+    } else {
+      word += char;
+    }
+  }
+  words.push(...(word === "" ? [] : [word]));
+  return quoted || words.length === 0 ? None() : Some(words);
+};