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

package/src/fake-system.ts

@@ -0,0 +1,176 @@
+// A `System` over an in-memory tree, for a shell's tests.
+
+import type { Result } from "@cprussin/option-result";
+import { Err, Ok } from "@cprussin/option-result";
+import type {
+  DirEntry,
+  Ran,
+  Stat,
+  Subprocess,
+  System,
+  SystemError,
+} from "@domicile-desktop/sdk/system";
+import { FileType, SystemErrorKind } from "@domicile-desktop/sdk/system";
+
+/**
+ * A file's contents, a symlink to another path in the tree, or a path every
+ * call on fails.
+ */
+export type Node =
+  | string
+  | Uint8Array
+  | { linksTo: string }
+  | { fails: SystemErrorKind };
+
+/** What a spawned argv writes and how it ends. */
+export type Spawned = {
+  stdout: Uint8Array | string;
+  stderr: string;
+  code: number;
+};
+
+export type FakeSystem = System & {
+  /** Every path read, listed or statted, in order. */
+  touched: string[];
+};
+
+type Tree = Readonly<Record<string, Node>>;
+
+/**
+ * A system whose files are `tree`, keyed by path, with the directories
+ * between them implied. `spawned` answers `spawn` and `run`.
+ */
+export const fakeSystem = (
+  tree: Tree,
+  spawned: (argv: readonly string[]) => Spawned = unexpected,
+): FakeSystem => {
+  const touched: string[] = [];
+  const at = (path: string): Result<Found, SystemError> => {
+    touched.push(path);
+    return found(tree, path);
+  };
+  const readFile = (path: string): Result<Uint8Array, SystemError> =>
+    at(path).andThen((node) =>
+      typeof node === "string" || node instanceof Uint8Array
+        ? Ok(bytesOf(node))
+        : Err({ kind: SystemErrorKind.IsADirectory, message: path }),
+    );
+  return {
+    dbusCall: unexpected,
+    dbusMatch: unexpected,
+    readDir: (path) =>
+      Promise.resolve(
+        at(path).andThen((node) =>
+          typeof node === "string" || node instanceof Uint8Array
+            ? Err({ kind: SystemErrorKind.NotADirectory, message: path })
+            : Ok(listing(tree, node.directory)),
+        ),
+      ),
+    readFile: (path) => Promise.resolve(readFile(path)),
+    readTextFile: (path) =>
+      Promise.resolve(
+        readFile(path).map((bytes) => new TextDecoder().decode(bytes)),
+      ),
+    run: (argv) => {
+      const { code, stderr, stdout } = spawned(argv);
+      const ran: Ran = {
+        code,
+        signal: undefined,
+        stderr,
+        stdout: new TextDecoder().decode(bytesOf(stdout)),
+      };
+      return Promise.resolve(Ok(ran));
+    },
+    spawn: (argv) => Promise.resolve(Ok(subprocess(spawned(argv)))),
+    stat: (path) =>
+      Promise.resolve(
+        at(path).map(
+          (node): Stat =>
+            typeof node === "string" || node instanceof Uint8Array
+              ? {
+                  fileType: FileType.File,
+                  modifiedMs: undefined,
+                  size: bytesOf(node).byteLength,
+                }
+              : {
+                  fileType: FileType.Directory,
+                  modifiedMs: undefined,
+                  size: 0,
+                },
+        ),
+      ),
+    touched,
+    watch: unexpected,
+    writeFile: unexpected,
+  };
+};
+
+/** A file's contents, or the directory a path resolved to. */
+type Found = string | Uint8Array | { directory: string };
+
+/** What is at `path`, following symlinks. */
+const found = (tree: Tree, path: string): Result<Found, SystemError> => {
+  const node = tree[path];
+  const linkedParent = Object.entries(tree)
+    .flatMap(([link, each]) =>
+      typeof each === "object" && "linksTo" in each
+        ? [{ link, to: each.linksTo }]
+        : [],
+    )
+    .find(({ link }) => path.startsWith(`${link}/`));
+  if (linkedParent !== undefined) {
+    const { link, to } = linkedParent;
+    return found(tree, `${to}${path.slice(link.length)}`);
+  } else if (node === undefined) {
+    return Object.keys(tree).some((each) => each.startsWith(`${path}/`))
+      ? Ok({ directory: path })
+      : Err({ kind: SystemErrorKind.NotFound, message: path });
+  } else if (typeof node === "string" || node instanceof Uint8Array) {
+    return Ok(node);
+  } else {
+    return "linksTo" in node
+      ? found(tree, node.linksTo)
+      : Err({ kind: node.fails, message: path });
+  }
+};
+
+const listing = (tree: Tree, path: string): DirEntry[] => {
+  const names = new Map<string, FileType>();
+  for (const [each, node] of Object.entries(tree)) {
+    if (each.startsWith(`${path}/`)) {
+      const [name = "", ...below] = each.slice(path.length + 1).split("/");
+      names.set(name, below.length > 0 ? FileType.Directory : ownType(node));
+    }
+  }
+  return [...names].map(([name, fileType]) => ({ fileType, name }));
+};
+
+/** A node's type without following it. */
+const ownType = (node: Node): FileType =>
+  typeof node === "object" && "linksTo" in node
+    ? FileType.Symlink
+    : FileType.File;
+
+const subprocess = ({ code, stderr, stdout }: Spawned): Subprocess => ({
+  closeStdin: unexpected,
+  exited: Promise.resolve(Ok({ code, signal: undefined })),
+  kill: unexpected,
+  stderr: streamOf(bytesOf(stderr)),
+  stdout: streamOf(bytesOf(stdout)),
+  write: unexpected,
+});
+
+const bytesOf = (data: string | Uint8Array): Uint8Array =>
+  typeof data === "string" ? new TextEncoder().encode(data) : data;
+
+const streamOf = (bytes: Uint8Array): ReadableStream<Uint8Array> =>
+  new ReadableStream({
+    start: (controller) => {
+      controller.enqueue(bytes);
+      controller.close();
+    },
+  });
+
+const unexpected = (): never => {
+  throw new Error("the code under test made a call this fake does not take");
+};

package/src/favicon.ts

@@ -0,0 +1,164 @@
+// A bookmark's icon, picked as a browser picks one: the page's
+// `<link rel="icon">`, else `/favicon.ico`. The caller does the fetching.
+
+import type { Option, Result } from "@cprussin/option-result";
+import { None, Ok, Some } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+
+import { dataUrl } from "./data-url";
+
+/** Largest icon drawn, as for an application's. */
+const LARGEST = 128 * 1024;
+
+/** Assumed size of an unsized touch icon, per Apple. */
+const TOUCH_ICON_SIZE = 180;
+
+/** Assumed size of an unsized icon, as in a browser tab. */
+const UNSIZED = 16;
+
+/** How an icon's bytes start, for a server that names no image type. */
+const MAGIC: readonly [start: readonly number[], mime: string][] = [
+  [[0x89, 0x50, 0x4e, 0x47], "image/png"],
+  [[0, 0, 1, 0], "image/x-icon"],
+  [[0x47, 0x49, 0x46, 0x38], "image/gif"],
+  [[0xff, 0xd8, 0xff], "image/jpeg"],
+  [[0x3c, 0x73, 0x76, 0x67], "image/svg+xml"],
+];
+
+/** A fetched URL: where it landed after redirects, its type and its body. */
+export type Page = {
+  url: string;
+  contentType: string | undefined;
+  body: Uint8Array;
+};
+
+/** Fetches a URL, or nothing if it does not answer. */
+export type Fetch = (url: string) => Promise<Result<Option<Page>, SystemError>>;
+
+/**
+ * The icon for `url` as a `data:` URL, or nothing if none is usable.
+ *
+ * Tries the page's icon links first, SVG then largest. Links are ignored if
+ * the page redirected off-site, for example to a sign-in page; a parent or
+ * subdomain such as `www.` counts as the same site. Then tries
+ * `/favicon.ico`.
+ */
+export const favicon = async (
+  url: string,
+  fetch: Fetch,
+): Promise<Result<Option<string>, SystemError>> => {
+  const asked = new URL(url);
+  return (await fetch(url)).andThenAsync((page) =>
+    firstPicture(
+      [
+        ...page.match({
+          None: () => [],
+          Some: (found) =>
+            isHtml(found) && sameSite(asked, new URL(found.url))
+              ? iconLinks(found)
+              : [],
+        }),
+        new URL("/favicon.ico", asked).href,
+      ],
+      fetch,
+    ),
+  );
+};
+
+/** The first of `urls` that answers with a picture. */
+const firstPicture = async (
+  urls: readonly string[],
+  fetch: Fetch,
+): Promise<Result<Option<string>, SystemError>> => {
+  for (const url of urls) {
+    const found = (await fetch(url)).map((page) =>
+      page.andThen((answer) => picture(answer)),
+    );
+    if (found.mapOr(true, (icon) => icon.isSome())) {
+      return found;
+    }
+  }
+  return Ok(None());
+};
+
+const isHtml = ({ contentType }: Page): boolean => {
+  const type = contentType?.toLowerCase() ?? "";
+  return (
+    type.startsWith("text/html") || type.startsWith("application/xhtml+xml")
+  );
+};
+
+/** Whether the hosts match or one is a subdomain of the other. */
+const sameSite = (asked: URL, landed: URL): boolean =>
+  asked.hostname === landed.hostname ||
+  asked.hostname.endsWith(`.${landed.hostname}`) ||
+  landed.hostname.endsWith(`.${asked.hostname}`);
+
+/** The icons `page` links, resolved against it, best first. */
+const iconLinks = (page: Page): string[] =>
+  [
+    ...new DOMParser()
+      .parseFromString(new TextDecoder().decode(page.body), "text/html")
+      .querySelectorAll("link"),
+  ]
+    .flatMap((link) => {
+      const rels = (link.getAttribute("rel") ?? "").toLowerCase().split(/\s+/);
+      const touch = rels.includes("apple-touch-icon");
+      const href = link.getAttribute("href");
+      if (
+        (rels.includes("icon") || touch) &&
+        href !== null &&
+        URL.canParse(href, page.url)
+      ) {
+        const url = new URL(href, page.url);
+        const drawn =
+          link.getAttribute("type")?.toLowerCase() === "image/svg+xml" ||
+          url.pathname.toLowerCase().endsWith(".svg");
+        const size =
+          largestSize(link.getAttribute("sizes") ?? "") ??
+          (touch ? TOUCH_ICON_SIZE : UNSIZED);
+        return [{ drawn, size, url: url.href }];
+      } else {
+        return [];
+      }
+    })
+    // Stable, so page order holds among equal icons.
+    .toSorted((a, b) => Number(b.drawn) - Number(a.drawn) || b.size - a.size)
+    .map(({ url }) => url);
+
+/** The largest size in a `sizes` attribute; `any` is largest. */
+const largestSize = (sizes: string): number | undefined => {
+  const each = sizes
+    .toLowerCase()
+    .split(/\s+/)
+    .map((size) => {
+      const [width, height] = size.split("x").map(Number);
+      return size === "any"
+        ? Number.POSITIVE_INFINITY
+        : Math.max(width ?? Number.NaN, height ?? Number.NaN);
+    })
+    .filter((size) => !Number.isNaN(size));
+  return each.length === 0 ? undefined : Math.max(...each);
+};
+
+/**
+ * `page` as a `data:` URL if it is a small enough picture. Sniffs the body
+ * when the type is not `image/*`, since some servers send `.ico` without one.
+ */
+const picture = ({ body, contentType }: Page): Option<string> => {
+  const said = contentType?.split(";")[0]?.trim();
+  const mime = said?.toLowerCase().startsWith("image/") ? said : sniffed(body);
+  return mime === undefined || body.length > LARGEST
+    ? None()
+    : Some(dataUrl(mime, body));
+};
+
+const sniffed = (body: Uint8Array): string | undefined => {
+  const start = body.findIndex(
+    (byte) => ![0x20, 0x09, 0x0a, 0x0d, 0x0c].includes(byte),
+  );
+  const trimmed = start === -1 ? new Uint8Array() : body.subarray(start);
+  return MAGIC.find(([magic]) =>
+    magic.every((byte, at) => trimmed[at] === byte),
+  )?.[1];
+};

package/src/favicons.ts

@@ -0,0 +1,117 @@
+// Bookmark icons, looked up in the background and kept for the page's life. A
+// site can take seconds to answer, so a search shows the icons found so far.
+
+import type { Option, Result } from "@cprussin/option-result";
+import { None, Some } from "@cprussin/option-result";
+import type { SystemError } from "@domicile-desktop/sdk/system";
+
+/** How long to wait before asking again a site that gave no icon. */
+const RETRY_AFTER_MS = 60_000;
+
+enum LookedKind {
+  InFlight,
+  Found,
+  /** The site gave no icon, or the lookup failed. */
+  Missed,
+}
+
+const Looked = {
+  Found: (icon: string) => ({ icon, kind: LookedKind.Found as const }),
+  InFlight: () => ({ kind: LookedKind.InFlight as const }),
+  Missed: (atMs: number) => ({ atMs, kind: LookedKind.Missed as const }),
+};
+
+type Looked = ReturnType<(typeof Looked)[keyof typeof Looked]>;
+
+export type Favicons = {
+  /** The icon found for `url`, if one has been. */
+  icon: (url: string) => Option<string>;
+  /**
+   * Looks up, one at a time, each of `urls` that is new or whose miss is due
+   * a retry. Settles when they are done.
+   */
+  lookFor: (urls: readonly string[]) => Promise<void>;
+};
+
+/** How {@link favicons} keeps time and reports failures; for tests. */
+export type FaviconsOptions = {
+  retryAfterMs?: number;
+  now?: () => number;
+  /** Told of each failed lookup, which is retried later. Logs by default. */
+  failed?: (url: string, error: SystemError) => void;
+};
+
+/**
+ * Icons `find` finds, by bookmark URL. A miss or a failure is asked again
+ * after a minute, since the network may come up after the desktop.
+ */
+export const favicons = (
+  find: (url: string) => Promise<Result<Option<string>, SystemError>>,
+  {
+    failed = logged,
+    now = Date.now,
+    retryAfterMs = RETRY_AFTER_MS,
+  }: FaviconsOptions = {},
+): Favicons => {
+  const looked = new Map<string, Looked>();
+  return {
+    icon: (url) => {
+      const known = looked.get(url);
+      return known?.kind === LookedKind.Found ? Some(known.icon) : None();
+    },
+    lookFor: async (urls) => {
+      const wanted = [...new Set(urls)].filter((url) =>
+        due(looked.get(url), now(), retryAfterMs),
+      );
+      for (const url of wanted) {
+        looked.set(url, Looked.InFlight());
+      }
+      for (const url of wanted) {
+        looked.set(url, lookedOf(await find(url), url, now(), failed));
+      }
+    },
+  };
+};
+
+const due = (
+  known: Looked | undefined,
+  nowMs: number,
+  retryAfterMs: number,
+): boolean => {
+  if (known === undefined) {
+    return true;
+  } else {
+    switch (known.kind) {
+      case LookedKind.Missed: {
+        return nowMs - known.atMs >= retryAfterMs;
+      }
+      case LookedKind.InFlight:
+      case LookedKind.Found: {
+        return false;
+      }
+    }
+  }
+};
+
+const lookedOf = (
+  found: Result<Option<string>, SystemError>,
+  url: string,
+  nowMs: number,
+  failed: (url: string, error: SystemError) => void,
+): Looked =>
+  found.match({
+    Err: (error): Looked => {
+      failed(url, error);
+      return Looked.Missed(nowMs);
+    },
+    Ok: (icon) =>
+      icon.match({
+        None: (): Looked => Looked.Missed(nowMs),
+        Some: (each): Looked => Looked.Found(each),
+      }),
+  });
+
+const logged = (url: string, error: SystemError): void => {
+  // biome-ignore lint/suspicious/noConsole: surfacing a lookup that is retried later
+  console.error(`could not look for ${url}'s icon`, error);
+};

package/src/find-apps.ts

@@ -0,0 +1,21 @@
+// A launcher's search over installed applications.
+
+import type { DesktopEntry } from "./desktop-entry";
+import { ranked } from "./ranked";
+
+/**
+ * Up to `limit` applications matching `query`, best first.
+ *
+ * Every query word must appear, case-insensitively, in the name, generic name
+ * or keywords. Names that start with the query rank first, then sort by name.
+ */
+export const findApps = (
+  entries: readonly DesktopEntry[],
+  query: string,
+  limit: number,
+): DesktopEntry[] =>
+  ranked(entries, query, limit, {
+    name: ({ name }) => name,
+    tieBreak: ({ id }) => id,
+    words: ({ words }) => words,
+  });

package/src/installed.ts

@@ -0,0 +1,112 @@
+// Every application installed in the XDG data directories.
+
+import type { Result } from "@cprussin/option-result";
+import { None, Ok, Some } from "@cprussin/option-result";
+import type {
+  DirEntry,
+  System,
+  SystemError,
+} from "@domicile-desktop/sdk/system";
+import { FileType } from "@domicile-desktop/sdk/system";
+
+import type { DesktopEntry } from "./desktop-entry";
+import { parseDesktopEntry } from "./desktop-entry";
+import { allOk, orAbsent } from "./results";
+
+/** A desktop file ID and the file it names. */
+type EntryFile = { id: string; path: string };
+
+/**
+ * Every application in `applications/` under `dataDirs`, unordered.
+ *
+ * `dataDirs` is highest priority first (see `./data-dirs`). An ID in an
+ * earlier directory hides the same ID in later ones, even when the earlier
+ * entry is `Hidden`: that is how a user removes a system entry. Missing
+ * directories and unreadable files are skipped.
+ */
+export const installedApps = async (
+  system: System,
+  dataDirs: readonly string[],
+): Promise<Result<DesktopEntry[], SystemError>> => {
+  const listed = allOk(
+    await Promise.all(
+      dataDirs.map((dir) => entryFiles(system, `${dir}/applications`, "")),
+    ),
+  );
+  return (
+    await listed.andThenAsync(async (dirs) =>
+      allOk(
+        await Promise.all(
+          firstOfEach(dirs.flat()).map((file) => read(system, file)),
+        ),
+      ),
+    )
+  ).map((read) =>
+    read.flatMap((entry) =>
+      entry.match({ None: () => [], Some: (found) => [found] }),
+    ),
+  );
+};
+
+/** Each ID's first file, in priority order. */
+const firstOfEach = (files: readonly EntryFile[]): EntryFile[] => {
+  const seen = new Set<string>();
+  return files.filter(({ id }) => {
+    const first = !seen.has(id);
+    seen.add(id);
+    return first;
+  });
+};
+
+/** `file` parsed, or nothing for an unreadable file or one not to offer. */
+const read = async (system: System, { id, path }: EntryFile) =>
+  orAbsent(
+    (await system.readTextFile(path)).map((text) =>
+      parseDesktopEntry(id, text),
+    ),
+    None<DesktopEntry>(),
+  );
+
+/**
+ * Every `.desktop` file under `dir`, recursively, with its ID: `prefix` plus
+ * its path under `dir`, `/` read as `-`.
+ */
+const entryFiles = async (
+  system: System,
+  dir: string,
+  prefix: string,
+): Promise<Result<EntryFile[], SystemError>> =>
+  orAbsent(await system.readDir(dir), []).andThenAsync(async (entries) =>
+    allOk(
+      await Promise.all(
+        entries.map((entry) => filesAt(system, dir, prefix, entry)),
+      ),
+    ).map((found) => found.flat()),
+  );
+
+/** The entry files `entry` in `dir` holds: itself, or those under it. */
+const filesAt = async (
+  system: System,
+  dir: string,
+  prefix: string,
+  { fileType, name }: DirEntry,
+): Promise<Result<EntryFile[], SystemError>> => {
+  const path = `${dir}/${name}`;
+  const below = () => entryFiles(system, path, `${prefix}${name}-`);
+  if (fileType === FileType.Directory) {
+    return below();
+  } else if (name.endsWith(".desktop")) {
+    return Ok([{ id: `${prefix}${name}`, path }]);
+  } else if (fileType === FileType.Symlink) {
+    return orAbsent(
+      (await system.stat(path)).map(({ fileType: target }) =>
+        target === FileType.Directory ? Some(target) : None<FileType>(),
+      ),
+      None<FileType>(),
+    ).andThenAsync((linked) =>
+      linked.isSome() ? below() : Promise.resolve(Ok([])),
+    );
+  } else {
+    return Ok([]);
+  }
+};

package/src/mime-apps.ts

@@ -0,0 +1,81 @@
+// The default applications `mimeapps.list` names for a content type. See
+// https://specifications.freedesktop.org/mime-apps-spec/latest/.
+
+import type { Result } from "@cprussin/option-result";
+import type { System, SystemError } from "@domicile-desktop/sdk/system";
+
+import { desktopEnvironment, setVariable } from "./environment";
+import { allOk, orAbsent } from "./results";
+
+/** The group defaults are read from. */
+const GROUP = "[Default Applications]";
+
+/**
+ * The desktop file IDs, `.desktop` included, set as `contentType`'s default,
+ * most preferred first. The caller takes the first it can offer.
+ *
+ * Reads every `mimeapps.list` the spec names, the current desktop's own
+ * (`domicile-mimeapps.list`) before each plain one. Missing lists are
+ * skipped.
+ */
+export const defaultApps = async (
+  system: System,
+  contentType: string,
+): Promise<Result<string[], SystemError>> =>
+  (await desktopEnvironment(system)).andThenAsync(async (variables) =>
+    allOk(
+      await Promise.all(
+        listPaths(variables).map(async (path) =>
+          orAbsent(await system.readTextFile(path), "").map((text) =>
+            defaultsIn(text, contentType),
+          ),
+        ),
+      ),
+    ).map((found) => found.flat()),
+  );
+
+/** Every list to read, in the spec's order. */
+const listPaths = (variables: ReadonlyMap<string, string>): string[] => {
+  const desktops = (setVariable(variables, "XDG_CURRENT_DESKTOP") ?? "")
+    .split(":")
+    .filter((desktop) => desktop !== "")
+    .map((desktop) => desktop.toLowerCase());
+  const names = [
+    ...desktops.map((desktop) => `${desktop}-mimeapps.list`),
+    "mimeapps.list",
+  ];
+  const dataDirs = [
+    setVariable(variables, "XDG_DATA_HOME") ?? ".local/share",
+    ...(
+      setVariable(variables, "XDG_DATA_DIRS") ?? "/usr/local/share:/usr/share"
+    ).split(":"),
+  ].map((dir) => `${dir}/applications`);
+  return [
+    setVariable(variables, "XDG_CONFIG_HOME") ?? ".config",
+    ...(setVariable(variables, "XDG_CONFIG_DIRS") ?? "/etc/xdg").split(":"),
+    ...dataDirs,
+  ].flatMap((dir) => names.map((name) => `${dir}/${name}`));
+};
+
+/** The IDs list `text` sets for `contentType`. */
+const defaultsIn = (text: string, contentType: string): string[] => {
+  let group = "";
+  const found: string[] = [];
+  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("=");
+      if (equals !== -1 && line.slice(0, equals).trim() === contentType) {
+        found.push(
+          ...line
+            .slice(equals + 1)
+            .split(";")
+            .map((id) => id.trim())
+            .filter((id) => id !== ""),
+        );
+      }
+    }
+  }
+  return found;
+};