refactor: refactor and add docs for setup-apt functions

packages/setup-apt/README.md

@@ -19,76 +19,130 @@ npm install --save setup-apt
 
 <!-- INSERT GENERATED DOCS START -->
 
+### `updateAptAlternatives` (function)
+
+Update the alternatives for a package
+
+**Parameters:**
+
+- name (`string`) - The name of the package
+- path (`string`) - The path to the binary
+- priority (`number`) - The priority of the alternative (Defaults to `40`)
+
+**returns:** Promise<void>
+
+### `addUpdateAlternativesToRc` (function)
+
+Add the update-alternatives command to the rc file
+
+**Parameters:**
+
+- name (`string`) - The name of the package
+- path (`string`) - The path to the binary
+- rcOptions (`RcOptions`) - The options for the rc file to add the update-alternatives command to
+- priority (`number`) - The priority of the alternative (Defaults to `40`)
+
+**returns:** Promise<void>
+
+### `isAptPackInstalled` (function)
+
+Check if a package is installed
+
+**Parameters:**
+
+- pack (`string`) - The package to check
+
+**returns:** Promise<boolean>
+
+### `isAptPackRegexInstalled` (function)
+
+Check if a package matching a regexp is installed
+
+**Parameters:**
+
+- regexp (`string`) - The regexp to check
+
+**returns:** Promise<boolean>
+
+### `updateRepos` (function)
+
+Update the apt repositories
+
+**Parameters:**
+
+- apt (`string`) - The apt command to use (optional)
+
+**returns:** void
+
 ### `InstallationInfo` (type)
 
+The information about an installation result
+
 ### `aptTimeout` (variable)
 
+The timeout to use for apt commands
+Wait up to 300 seconds if the apt-get lock is held
+
 ### `AptPackage` (type)
 
+The information about an apt package
+
 ### `installAptPack` (function)
 
-A function that installs a package using apt
+Install a package using apt
 
 **Parameters:**
 
-- packages (`AptPackage[]`)
-- update (`boolean`)
+- packages (`AptPackage[]`) - The packages to install (name, and optional info like version and repositories)
+- update (`boolean`) - Whether to update the package list before installing (Defaults to `false`)
 
 **returns:** Promise<InstallationInfo>
 
 ### `hasNala` (function)
 
+Check if nala is installed
+
 **returns:** boolean
 
 ### `getApt` (function)
 
-**returns:** string
-
-### `addAptKeyViaServer` (function)
-
-**Parameters:**
+Get the apt command to use
+If nala is installed, use that, otherwise use apt-get
 
-- keys (`string[]`)
-- name (`string`)
-- server (`string`)
+**returns:** string
 
-**returns:** Promise<string>
+### `getEnv` (function)
 
-### `addAptKeyViaDownload` (function)
+Get the environment variables to use for the apt command
 
 **Parameters:**
 
-- name (`string`)
-- url (`string`)
+- apt (`string`) - The apt command to use
 
-**returns:** Promise<string>
-
-### `updateAptAlternatives` (function)
-
-**Parameters:**
-
-- name (`string`)
-- path (`string`)
-- rcOptions (`RcOptions`)
-- priority (`number`)
+**returns:** ProcessEnv
 
-**returns:** Promise<void>
+### `addAptKeyViaServer` (function)
 
-### `isAptPackInstalled` (function)
+Add an apt key via a keyserver
 
 **Parameters:**
 
-- pack (`string`)
+- keys (`string[]`) - The keys to add
+- name (`string`) - The name of the key
+- server (`string`) - The keyserver to use (Defaults to `keyserver.ubuntu.com`)
 
-**returns:** Promise<boolean>
+**returns:** Promise<string>
 
-### `isAptPackRegexInstalled` (function)
+### `addAptKeyViaDownload` (function)
+
+Add an apt key via a download
 
 **Parameters:**
 
-- regexp (`string`)
+- name (`string`) - The name of the key
+- url (`string`) - The URL of the key
 
-**returns:** Promise<boolean>
+**returns:** Promise<string>
 
 <!-- INSERT GENERATED DOCS END -->
 

packages/setup-apt/src/alternatives.ts

@@ -0,0 +1,40 @@
+import { promises } from "fs"
+import { execRoot } from "admina"
+import { GITHUB_ACTIONS } from "ci-info"
+import { sourceRC } from "os-env"
+import type { RcOptions } from "os-env/dist/rc-file.js"
+const { appendFile } = promises
+
+/**
+ * Update the alternatives for a package
+ * @param name The name of the package
+ * @param path The path to the binary
+ * @param priority The priority of the alternative (Defaults to `40`)
+ */
+export async function updateAptAlternatives(name: string, path: string, priority: number = 40) {
+  await execRoot("update-alternatives", ["--install", `/usr/bin/${name}`, name, path, priority.toString()])
+}
+
+/**
+ * Add the update-alternatives command to the rc file
+ * @param name The name of the package
+ * @param path The path to the binary
+ * @param rcOptions The options for the rc file to add the update-alternatives command to
+ * @param priority The priority of the alternative (Defaults to `40`)
+ */
+export async function addUpdateAlternativesToRc(
+  name: string,
+  path: string,
+  rcOptions: RcOptions,
+  priority: number = 40,
+) {
+  if (GITHUB_ACTIONS) {
+    await updateAptAlternatives(name, path, priority)
+  } else {
+    await sourceRC(rcOptions)
+    await appendFile(
+      rcOptions.rcPath,
+      `\nif [ $UID -eq 0 ]; then update-alternatives --install /usr/bin/${name} ${name} ${path} ${priority}; fi\n`,
+    )
+  }
+}

packages/setup-apt/src/apt-key.ts

@@ -0,0 +1,62 @@
+import { execRoot, execRootSync } from "admina"
+import { warning } from "ci-log"
+import { execa } from "execa"
+import { pathExists } from "path-exists"
+import { installAptPack } from "./install.js"
+
+function initGpg() {
+  execRootSync("gpg", ["-k"])
+}
+
+/**
+ * Add an apt key via a keyserver
+ * @param keys The keys to add
+ * @param name The name of the key
+ * @param server The keyserver to use (Defaults to `keyserver.ubuntu.com`)
+ * @returns The file name of the key that was added or `undefined` if it failed
+ */
+export async function addAptKeyViaServer(keys: string[], name: string, server = "keyserver.ubuntu.com") {
+  try {
+    const fileName = `/etc/apt/trusted.gpg.d/${name}`
+    if (!(await pathExists(fileName))) {
+      initGpg()
+
+      await Promise.all(
+        keys.map(async (key) => {
+          await execRoot("gpg", [
+            "--no-default-keyring",
+            "--keyring",
+            `gnupg-ring:${fileName}`,
+            "--keyserver",
+            server,
+            "--recv-keys",
+            key,
+          ])
+          await execRoot("chmod", ["644", fileName])
+        }),
+      )
+    }
+    return fileName
+  } catch (err) {
+    warning(`Failed to add apt key via server ${server}: ${err}`)
+    return undefined
+  }
+}
+
+/**
+ * Add an apt key via a download
+ * @param name The name of the key
+ * @param url The URL of the key
+ * @returns The file name of the key that was added
+ */
+export async function addAptKeyViaDownload(name: string, url: string) {
+  const fileName = `/etc/apt/trusted.gpg.d/${name}`
+  if (!(await pathExists(fileName))) {
+    initGpg()
+    await installAptPack([{ name: "curl" }, { name: "ca-certificates" }], undefined)
+    await execa("curl", ["-s", url, "-o", `/tmp/${name}`])
+    execRootSync("gpg", ["--no-default-keyring", "--keyring", `gnupg-ring:${fileName}`, "--import", `/tmp/${name}`])
+    execRootSync("chmod", ["644", fileName])
+  }
+  return fileName
+}