bookmarks-but-better 1.0.0

package/lib/cli.mjs

@@ -0,0 +1,134 @@
+// What `npx bookmarks-but-better …` was asked to do, read out of `argv` with no
+// I/O — which is what lets `test/cli.test.mjs` cover every command, option and
+// mistake without spawning anything.
+
+export const COMMANDS = ["status", "install", "uninstall", "vault"];
+export const VAULT_SUBCOMMANDS = ["list", "add", "remove"];
+
+export const USAGE = `Usage: npx bookmarks-but-better [command] [options]
+
+Installs and looks after the Bookmarks But Better daemon on this machine. Run
+with no command, it is a menu: it installs the daemon when none is installed,
+and otherwise shows the status and offers what can be done about it. Every
+command asks for what it was not given; --yes answers with the defaults.
+
+Commands:
+  status                 What is installed, configured, running and connected,
+                         and the one command that fixes anything that is not.
+  install                Install or update the daemon, configure the first
+                         vault, and install and start the background service.
+                         Safe to run again: an update keeps every vault.
+  uninstall              Stop and remove the service and the daemon. Vaults are
+                         never touched; the configuration is kept unless
+                         --purge-config says otherwise.
+  vault list             The configured vaults and what is true of each.
+  vault add [<id> <path>]
+                         Configure another vault and restart the service.
+  vault remove [<id>]    Drop a vault from the configuration (the directory
+                         stays) and restart the service. Removing the last
+                         one removes the service too, until a vault is added.
+
+Options:
+  -y, --yes              Never ask; take every default. For scripts.
+  --json                 Machine-readable output (status, vault list).
+  --vault <dir>          install: where the first vault lives. Asked when left
+                         out; ~/Bookmarks with --yes.
+  --version <tag>        install: exactly this daemon release, e.g.
+                         v4.2.0-beta.1, instead of the one this tool was
+                         released for.
+  --install-dir <dir>    install: where daemon versions are unpacked.
+  --bin-dir <dir>        install: where the bookmarks-but-better symlink goes.
+                         macOS and Linux only.
+  --purge-config         uninstall: also remove the configuration file.
+  -h, --help             Show this help.`;
+
+const OPTIONS = new Map([
+  ["-y", { key: "yes" }],
+  ["--yes", { key: "yes" }],
+  ["--json", { key: "json" }],
+  ["--purge-config", { key: "purgeConfig" }],
+  ["--version", { key: "version", takesValue: true }],
+  ["--install-dir", { key: "installDir", takesValue: true }],
+  ["--bin-dir", { key: "binDir", takesValue: true }],
+  ["--vault", { key: "vault", takesValue: true }],
+]);
+
+export const SUPPORTED_OPTIONS = [...OPTIONS.keys()];
+
+/**
+ * Splits `argv` into a command, its arguments and its options. Every mistake
+ * is collected rather than thrown, so a user who made two gets told about
+ * both; an unknown option or command is refused here rather than guessed at.
+ */
+export function parseArgs(argv) {
+  const options = {};
+  const positionals = [];
+  const errors = [];
+  let help = false;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "-h" || argument === "--help") {
+      help = true;
+      continue;
+    }
+    if (!argument.startsWith("-")) {
+      positionals.push(argument);
+      continue;
+    }
+    const option = OPTIONS.get(argument);
+    if (!option) {
+      errors.push(`unrecognized option: ${argument}`);
+      continue;
+    }
+    if (!option.takesValue) {
+      options[option.key] = true;
+      continue;
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith("-")) {
+      errors.push(`${argument} needs an argument`);
+      continue;
+    }
+    index += 1;
+    options[option.key] = value;
+  }
+
+  const [command = null, ...rest] = positionals;
+  let subcommand = null;
+  let args = rest;
+
+  if (command !== null && !COMMANDS.includes(command)) {
+    errors.push(`unknown command: ${command}`);
+  } else if (command === "vault") {
+    subcommand = rest[0] ?? null;
+    args = rest.slice(1);
+    if (!VAULT_SUBCOMMANDS.includes(subcommand)) {
+      errors.push("vault needs one of: list, add <id> <path>, remove <id>");
+    } else if (subcommand === "add" && args.length !== 0 && args.length !== 2) {
+      errors.push("vault add takes an id and a path, or nothing and asks for both");
+    } else if (subcommand === "remove" && args.length > 1) {
+      errors.push("vault remove takes one id, or nothing and offers a choice");
+    } else if (subcommand === "list" && args.length !== 0) {
+      errors.push("vault list takes no arguments");
+    }
+  } else if (command !== null && rest.length > 0) {
+    errors.push(`${command} takes no arguments`);
+  }
+
+  return { command, subcommand, args, options, help, errors };
+}
+
+/**
+ * The flags `install` hands the installer script. Left to itself the tool
+ * installs `daemonVersion` — the daemon release it was published for, whose
+ * `--json` output it reads (package.json's `daemon.version`). `--version` is
+ * the explicit way to choose otherwise, for trying a prerelease.
+ */
+export function installerFlags({ options, daemonVersion, vault = null }) {
+  const flags = ["--version", options.version || `v${daemonVersion}`];
+  if (options.installDir) flags.push("--install-dir", options.installDir);
+  if (options.binDir) flags.push("--bin-dir", options.binDir);
+  if (vault) flags.push("--vault", vault);
+  return flags;
+}

package/lib/daemon.mjs

@@ -0,0 +1,158 @@
+// Everything that touches the machine: running the daemon binary's own
+// commands, reading their `--json` answers, and asking a running daemon how it
+// is. The decisions about what those answers mean live in `status.mjs`.
+
+import { execFile, spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { promisify } from "node:util";
+
+import { emptyReport, formatOrigin, parseVersionOutput } from "./status.mjs";
+
+const execFileAsync = promisify(execFile);
+
+/** Runs `binary args…` and returns what it printed, never throwing. */
+export async function runQuiet(binary, args, { env = process.env } = {}) {
+  try {
+    const { stdout, stderr } = await execFileAsync(binary, args, {
+      encoding: "utf8",
+      maxBuffer: 8 * 1024 * 1024,
+      env,
+    });
+    return { ok: true, code: 0, stdout, stderr };
+  } catch (error) {
+    return {
+      ok: false,
+      code: typeof error.code === "number" ? error.code : 1,
+      stdout: error.stdout ?? "",
+      stderr: error.stderr ?? String(error.message ?? error),
+    };
+  }
+}
+
+/** Runs `command args…` with the terminal attached, resolving to its exit code. */
+export function runVisible(command, args, { env = process.env } = {}) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, { stdio: "inherit", env });
+    child.on("error", reject);
+    child.on("close", (code) => resolve(code ?? 1));
+  });
+}
+
+/** Runs a `--json` command and parses its answer. */
+async function readJson(binary, args) {
+  const result = await runQuiet(binary, args);
+  if (!result.ok) {
+    // The first line only: a binary too old to know the command answers with
+    // its whole usage text, and the one line that says so is enough.
+    const said = result.stderr.trim().split("\n")[0]?.replace(/^error:\s*/, "");
+    return { value: null, error: said || `exit code ${result.code}` };
+  }
+  try {
+    return { value: JSON.parse(result.stdout), error: null };
+  } catch {
+    return { value: null, error: `unreadable output from \`${args.join(" ")}\`` };
+  }
+}
+
+async function readVersion(binary) {
+  const result = await runQuiet(binary, ["--version"]);
+  return result.ok ? parseVersionOutput(result.stdout) : null;
+}
+
+export async function readRegistry(binary) {
+  return readJson(binary, ["vault", "list", "--json"]);
+}
+
+export async function readService(binary) {
+  return readJson(binary, ["service", "status", "--json"]);
+}
+
+/** `GET /api/v1/health`, with a short timeout: loopback answers at once or not at all. */
+async function fetchHealth(origin, { timeoutMs = 2000 } = {}) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await fetch(`${origin}/api/v1/health`, { signal: controller.signal });
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`);
+    }
+    return await response.json();
+  } catch (error) {
+    throw new Error(error.name === "AbortError" ? "timed out" : error.cause?.code ?? error.message);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/** Health, retried while a just-started daemon opens its vaults. */
+export async function waitForHealth(origin, { attempts = 40, delayMs = 250 } = {}) {
+  let last = null;
+  for (let attempt = 0; attempt < attempts; attempt += 1) {
+    try {
+      return await fetchHealth(origin);
+    } catch (error) {
+      last = error;
+      await sleep(delayMs);
+    }
+  }
+  throw last ?? new Error("no answer");
+}
+
+/** The daemon's address, from the configuration, else the service, else the defaults. */
+export function originOf({ registry, service }) {
+  return formatOrigin(registry?.bind ?? undefined, registry?.port ?? service?.port ?? undefined);
+}
+
+/** Reads everything `status` reports into one shape. */
+export async function gather({ layout, toolVersion, daemonVersion }) {
+  const report = emptyReport({ toolVersion, daemonVersion, binaryPath: layout.binary });
+  if (!existsSync(layout.binary)) return report;
+
+  report.binary.installed = true;
+  report.binary.version = await readVersion(layout.binary);
+
+  const registry = await readRegistry(layout.binary);
+  report.registry = registry.value;
+  report.registryError = registry.error;
+
+  const service = await readService(layout.binary);
+  report.service = service.value;
+  report.serviceError = service.error;
+
+  report.origin = originOf({ registry: report.registry, service: report.service });
+  try {
+    report.health = await fetchHealth(report.origin);
+  } catch (error) {
+    report.healthError = error.message;
+  }
+  return report;
+}
+
+/** Whether the registry lists any vault; `null` when it could not be read. */
+export async function registryHasVaults(binary) {
+  const { value } = await readRegistry(binary);
+  return value ? value.vaults.length > 0 : null;
+}
+
+/** Whether a service definition is installed; `null` when it could not be asked. */
+export async function serviceIsInstalled(binary) {
+  const { value } = await readService(binary);
+  return value ? value.state !== "not-installed" : null;
+}
+
+/**
+ * Takes `entry` off the user's PATH on Windows, where install.ps1 put it. A
+ * PowerShell one-liner because the user PATH lives in the registry, and
+ * `[Environment]::SetEnvironmentVariable` is the supported way to write it.
+ */
+export async function removeFromUserPath(entry) {
+  const script = [
+    "$entries = [Environment]::GetEnvironmentVariable('Path', 'User') -split ';'",
+    `$kept = $entries | Where-Object { $_ -and $_ -ne '${entry.replace(/'/g, "''")}' }`,
+    "[Environment]::SetEnvironmentVariable('Path', ($kept -join ';'), 'User')",
+  ].join("; ");
+  const result = await runQuiet("powershell", ["-NoProfile", "-NonInteractive", "-Command", script]);
+  return result.ok;
+}

package/lib/layout.mjs

@@ -0,0 +1,86 @@
+// Where the installers put things, computed the same way they compute it, so
+// this tool finds the daemon the installer left behind and nothing else.
+// String answers only: nothing here touches the filesystem.
+
+import path from "node:path";
+
+/**
+ * The install layout for `platform`. `installDir`/`binDir` are the explicit
+ * `--install-dir`/`--bin-dir` the user gave, which beat the environment,
+ * which beats the installer's defaults — the same precedence install.sh
+ * applies.
+ */
+export function installLayout({
+  platform,
+  env = {},
+  homedir,
+  installDir = null,
+  binDir = null,
+}) {
+  if (platform === "win32") {
+    const p = path.win32;
+    const root =
+      installDir ||
+      env.BOOKMARKS_BUT_BETTER_INSTALL_ROOT ||
+      p.join(env.LOCALAPPDATA || p.join(homedir, "AppData", "Local"), "bookmarks-but-better");
+    const current = p.join(root, "current");
+    return {
+      platform,
+      installRoot: root,
+      current,
+      binary: p.join(current, "bookmarks-but-better.exe"),
+      uiDir: p.join(current, "ui"),
+      // install.ps1 puts `current` on the user's PATH instead of a symlink.
+      binDir: null,
+      binLink: null,
+    };
+  }
+
+  const p = path.posix;
+  const root =
+    installDir ||
+    env.BOOKMARKS_BUT_BETTER_INSTALL_ROOT ||
+    p.join(homedir, ".local", "share", "bookmarks-but-better");
+  const links = binDir || env.BOOKMARKS_BUT_BETTER_BIN_DIR || p.join(homedir, ".local", "bin");
+  const current = p.join(root, "current");
+  return {
+    platform,
+    installRoot: root,
+    current,
+    binary: p.join(current, "bookmarks-but-better"),
+    uiDir: p.join(current, "ui"),
+    binDir: links,
+    binLink: p.join(links, "bookmarks-but-better"),
+  };
+}
+
+/**
+ * Where the daemon keeps its Vault Registry (ADR-0005), computed as the daemon
+ * computes it, for the one moment there is no daemon binary left to ask: the
+ * end of `uninstall`.
+ */
+export function configPath({ platform, env = {}, homedir }) {
+  const p = platform === "win32" ? path.win32 : path.posix;
+  const configHome = env.XDG_CONFIG_HOME || p.join(homedir, ".config");
+  return p.join(configHome, "bookmarks-but-better", "config.toml");
+}
+
+/** `~` and `~/…` as the shell would read them; anything else unchanged. */
+export function expandHome(input, homedir) {
+  if (input === "~") return homedir;
+  if (input.startsWith("~/") || input.startsWith("~\\")) {
+    return path.join(homedir, input.slice(2));
+  }
+  return input;
+}
+
+/** The inverse, for display: a path under the home directory shown as `~/…`. */
+export function contractHome(input, homedir) {
+  if (!homedir || !input) return input;
+  if (input === homedir) return "~";
+  const separator = input.includes("\\") && !input.includes("/") ? "\\" : "/";
+  if (input.startsWith(homedir + separator)) {
+    return `~${separator}${input.slice(homedir.length + 1)}`;
+  }
+  return input;
+}

package/lib/prompt.mjs

@@ -0,0 +1,57 @@
+// The only place this tool asks anything, drawn with @clack/prompts. `--yes`
+// answers every question with its default, and a question with no terminal
+// to ask on is an error rather than a silent default — the same rule the
+// daemon's own commands follow.
+
+import * as p from "@clack/prompts";
+
+/** The user pressed Ctrl-C or Escape on a question. */
+export class Cancelled extends Error {
+  constructor() {
+    super("cancelled");
+    this.name = "Cancelled";
+  }
+}
+
+export function createPrompter({ yes = false, input = process.stdin } = {}) {
+  const interactive = Boolean(input.isTTY) && !yes;
+
+  function refuse(question, fallback) {
+    return new Error(
+      `${question} — there is no terminal to ask on; pass --yes to take the default (${fallback}), or say it on the command line`,
+    );
+  }
+
+  function unwrap(answer) {
+    if (p.isCancel(answer)) throw new Cancelled();
+    return answer;
+  }
+
+  /** A free-text answer; empty takes `fallback`. */
+  async function ask(question, fallback, { validate } = {}) {
+    if (yes) return fallback;
+    if (!interactive) throw refuse(question, fallback);
+    const answer = unwrap(
+      await p.text({ message: question, placeholder: fallback, defaultValue: fallback, validate }),
+    );
+    return String(answer).trim() || fallback;
+  }
+
+  /**
+   * A yes/no answer. `fallback` is what Enter means; `whenYes` is what `--yes`
+   * means, which for a destructive question is not always the default.
+   */
+  async function confirm(question, { fallback = true, whenYes = fallback } = {}) {
+    if (yes) return whenYes;
+    if (!interactive) throw refuse(question, fallback ? "yes" : "no");
+    return unwrap(await p.confirm({ message: question, initialValue: fallback }));
+  }
+
+  /** One of `options` (`{ value, label, hint? }`). A choice has no default, so it needs a terminal. */
+  async function select(question, options) {
+    if (!interactive) throw refuse(question, options.map((option) => option.value).join(" | "));
+    return unwrap(await p.select({ message: question, options }));
+  }
+
+  return { ask, confirm, select, interactive };
+}

package/lib/release.mjs

@@ -0,0 +1,112 @@
+// Where the installer comes from and how it is run: which script this
+// platform needs, which GitHub Release URL it is fetched from, and how the
+// flags `install` chose reach it. Pure functions of their inputs, so
+// `test/release.test.mjs` covers them without a network or a spawned process.
+
+export const REPO = "farhadeidi/bookmarks-but-better";
+export const DEFAULT_GITHUB_BASE = "https://github.com";
+
+/** The fixed-name installer each platform's release carries. */
+export function installerAssetName(platform) {
+  return platform === "win32" ? "install.ps1" : "install.sh";
+}
+
+/**
+ * A GitHub Release asset URL, and never anything else — an installer fetched
+ * from a branch or from the website is not the one that was released and
+ * checksummed.
+ *
+ * `tag` of `null` means the latest release, which GitHub serves under its own
+ * `/releases/latest/download/` path.
+ */
+export function releaseAssetUrl({
+  name,
+  tag = null,
+  repo = REPO,
+  base = DEFAULT_GITHUB_BASE,
+}) {
+  const root = `${base.replace(/\/+$/, "")}/${repo}/releases`;
+  return tag
+    ? `${root}/download/${tag}/${name}`
+    : `${root}/latest/download/${name}`;
+}
+
+/** The `<hash>  <filename>` sidecar published next to every release asset. */
+export function checksumAssetName(name) {
+  return `${name}.sha256`;
+}
+
+/** The hash out of a `sha256sum`/`shasum -a 256` sidecar line. */
+export function parseChecksumSidecar(text) {
+  const hash = String(text).trim().split(/\s+/)[0] ?? "";
+  if (!/^[0-9a-f]{64}$/i.test(hash)) {
+    throw new Error(`malformed .sha256 sidecar: ${JSON.stringify(text)}`);
+  }
+  return hash.toLowerCase();
+}
+
+/**
+ * The release whose installer to fetch: the one named by `--version`, so the
+ * script that runs is the one published alongside the archive it installs.
+ * The manager always names one.
+ */
+export function releaseTagFor(flags) {
+  const index = flags.indexOf("--version");
+  if (index === -1) throw new Error("the installer flags name no --version");
+  const version = flags[index + 1];
+  return version.startsWith("v") ? version : `v${version}`;
+}
+
+// Every flag forwarded to the installers, and what install.ps1 calls it.
+// `null` marks a flag install.ps1 has no equivalent for.
+const FLAGS = new Map([
+  ["--version", { takesValue: true, windows: "-Version" }],
+  ["--install-dir", { takesValue: true, windows: "-InstallDir" }],
+  ["--bin-dir", { takesValue: true, windows: null }],
+  ["--vault", { takesValue: true, windows: "-Vault" }],
+]);
+
+/**
+ * How the downloaded installer is executed on this platform, including the
+ * translation of the forwarded flags into install.ps1's parameter names.
+ *
+ * Throws when a flag has no equivalent on the target platform — silently
+ * dropping it would install to somewhere other than where the user asked.
+ */
+export function commandFor({ platform, scriptPath, forwarded = [] }) {
+  if (platform !== "win32") {
+    // `bash`, never `sh`: install.sh uses `set -o pipefail`, a bash builtin
+    // option, and /bin/sh is dash on Debian and Ubuntu.
+    return { command: "bash", args: [scriptPath, ...forwarded] };
+  }
+
+  const translated = [];
+  for (let index = 0; index < forwarded.length; index += 1) {
+    const flag = forwarded[index];
+    const option = FLAGS.get(flag);
+    if (!option) {
+      throw new Error(`cannot forward ${flag}`);
+    }
+    if (option.windows === null) {
+      throw new Error(`${flag} is not supported on Windows`);
+    }
+    translated.push(option.windows);
+    if (option.takesValue) {
+      index += 1;
+      translated.push(forwarded[index]);
+    }
+  }
+
+  return {
+    command: "powershell",
+    args: [
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-File",
+      scriptPath,
+      ...translated,
+    ],
+  };
+}