plx-cli 0.0.0-stage → 0.5.0

package/src/install.mjs

@@ -0,0 +1,85 @@
+// @ts-check
+// What the Tailscale commands and `plx connect` share: steps that print a line as they start and
+// a ✓ or ✗ line as they end, and finding a computer's OS and the release to install there.
+
+import { parseDetails, parseUname, POSIX_DETAILS, UNAME_COMMAND, WINDOWS_DETAILS } from "./detect.mjs";
+import { appName, fetchReleases, pickAsset, pickRelease, withSha256 } from "./releases.mjs";
+
+/** @typedef {import("./releases.mjs").Channel} Channel */
+/** @typedef {import("./releases.mjs").Os} Os */
+/** @typedef {import("./detect.mjs").Target} Target */
+/** @typedef {import("./run.mjs").Runner} Runner */
+
+/** A step failed. Its ✗ line is already printed. */
+export class StepFailed extends Error {}
+
+/**
+ * Prints `title`, runs `run`, then prints its ✓ line, or ✗ with the error's message.
+ * @template T
+ * @param {string} title
+ * @param {() => Promise<[string, T]>} run Resolves to the ✓ line's text and the step's value.
+ * @returns {Promise<T>}
+ */
+export async function step(title, run) {
+  console.log(`→ ${title}`);
+  try {
+    const [done, value] = await run();
+    console.log(`✓ ${done}`);
+    return value;
+  } catch (error) {
+    console.log(`✗ ${error instanceof Error ? error.message : String(error)}`);
+    throw new StepFailed();
+  }
+}
+
+/** This computer's OS as releases name it, or undefined where Parallax doesn't run. @returns {Os | undefined} */
+export const localOs = () =>
+  process.platform === "darwin" ? "macos" : process.platform === "linux" ? "linux" : process.platform === "win32" ? "windows" : undefined;
+
+/** The target's OS and details, with the runner's shell. @param {Runner} runner @param {Os} os */
+export async function readDetails(runner, os) {
+  const windows = os === "windows";
+  const { code, stdout } = await runner.script(windows ? "powershell" : "sh", windows ? WINDOWS_DETAILS : POSIX_DETAILS, true);
+  if (code !== 0) throw new Error(`Couldn't read the computer's details (exit ${code}).`);
+  return parseDetails(os, stdout);
+}
+
+/**
+ * Connects to `destination` over ssh, then finds its OS and details, as two steps.
+ * @param {Runner} runner The ssh runner for `destination`.
+ * @param {string} name What to call the computer.
+ * @param {string} destination
+ * @param {string} instead The command to run there when ssh can't connect.
+ */
+export async function sshTarget(runner, name, destination, instead) {
+  const os = await step(`Connecting to ${name} (${destination}) over SSH`, async () => {
+    const { code, stdout } = await runner.command(UNAME_COMMAND);
+    if (code === 255) {
+      throw new Error(
+        `SSH couldn't connect to ${destination}. Turn on Remote Login (macOS), OpenSSH Server (Windows), or sshd (Linux) there, or run ${instead} on it.`,
+      );
+    }
+    return [`Connected to ${name}`, parseUname(stdout, code)];
+  });
+  return step(`Finding ${name}'s OS`, async () => {
+    const target = await readDetails(runner, os);
+    return [`${target.label}: ${target.version} (${target.arch})`, target];
+  });
+}
+
+/** The product a plxd-only install, or else the app, is called. @param {boolean} plxdOnly @param {Channel} channel */
+export const product = (plxdOnly, channel) => (plxdOnly ? "plxd" : appName(channel));
+
+/**
+ * The newest release's asset for `target`, with the SHA-256 the script checks it against.
+ * @param {Target} target
+ * @param {Channel} channel
+ * @param {boolean} plxdOnly
+ */
+export function findInstaller(target, channel, plxdOnly) {
+  return step(`Finding the newest ${channel} release`, async () => {
+    const found = pickAsset(pickRelease(await fetchReleases(), channel), target.os, target.arch, plxdOnly);
+    const installer = await withSha256(found);
+    return [`${product(plxdOnly, channel)} ${installer.version}: ${installer.name}`, installer];
+  });
+}

package/src/plxd.mjs

@@ -0,0 +1,92 @@
+// @ts-check
+// A JSON-RPC connection to the running plxd over `plxd attach`'s stdio, which is plxd's trusted
+// local connection, as `doctor` and the app use it. Requests may overlap, so `access/get` can wait
+// for a change while another request goes out. plxd closes a connection that sends nothing for
+// 90 s, so an open one sends `host/health` every 30 s, as the editor does, to outlast a long wait.
+
+import { readFileSync } from "node:fs";
+
+/** plx's version, for `initialize`. */
+export const VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+/**
+ * @typedef {object} Plxd
+ * @property {(method: string, params?: object) => Promise<any>} call Sends a request and resolves
+ *   to its result, or rejects with plxd's error message.
+ * @property {() => void} close Ends `plxd attach`.
+ */
+
+/** How often an open connection sends `host/health`, well under plxd's 90 s idle limit. */
+const KEEPALIVE_MS = 30_000;
+
+/**
+ * Speaks JSON-RPC with `child`, a `plxd attach`, and sends `initialize` first. Resolves once plxd
+ * answered it.
+ * @param {import("node:child_process").ChildProcess} child
+ * @param {{ keepaliveMs?: number }} [options] `keepaliveMs` is shorter in tests.
+ * @returns {Promise<Plxd>}
+ */
+export async function attach(child, { keepaliveMs = KEEPALIVE_MS } = {}) {
+  /** @type {Map<number, { resolve: (value: any) => void, reject: (error: Error) => void }>} */
+  const waiting = new Map();
+  let next = 1;
+  /** @type {Error | undefined} */
+  let ended;
+  /** @type {NodeJS.Timeout | undefined} */
+  let keepalive;
+  const end = (/** @type {Error} */ error) => {
+    clearInterval(keepalive);
+    ended ??= error;
+    for (const { reject } of waiting.values()) reject(ended);
+    waiting.clear();
+  };
+  child.once("error", (error) => end(new Error(`Couldn't start plxd: ${error.message}`)));
+  child.once("exit", () => end(new Error("plxd stopped answering.")));
+  child.stdin?.on("error", () => {});
+
+  let pending = "";
+  child.stdout?.setEncoding("utf8");
+  child.stdout?.on("data", (/** @type {string} */ chunk) => {
+    const lines = (pending + chunk).split("\n");
+    pending = lines.pop() ?? "";
+    for (const line of lines) {
+      /** @type {{ id?: unknown, result?: unknown, error?: { message?: string } }} */
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        continue;
+      }
+      const request = typeof message.id === "number" ? waiting.get(message.id) : undefined;
+      if (!request) continue;
+      waiting.delete(/** @type {number} */ (message.id));
+      if (message.error) request.reject(new Error(message.error.message ?? "plxd refused the request."));
+      else request.resolve(message.result);
+    }
+  });
+
+  /** @type {Plxd["call"]} */
+  const call = (method, params = {}) =>
+    new Promise((resolve, reject) => {
+      if (ended) return reject(ended);
+      const id = next++;
+      waiting.set(id, { resolve, reject });
+      child.stdin?.write(`${JSON.stringify({ jsonrpc: "2.0", id, method, params })}\n`);
+    });
+
+  try {
+    await call("initialize", { protocol: { min: 1, max: 1 }, client: { name: "plx", version: VERSION }, capabilities: {} });
+  } catch (error) {
+    child.kill();
+    throw error;
+  }
+  if (!ended) keepalive = setInterval(() => call("host/health").catch(() => {}), keepaliveMs).unref();
+  return {
+    call,
+    close() {
+      clearInterval(keepalive);
+      child.stdin?.end();
+      child.kill();
+    },
+  };
+}

package/src/releases.mjs

@@ -0,0 +1,133 @@
+// @ts-check
+// Which Parallax installer to download, from the repo's GitHub Releases (0028, 0029, 0030).
+
+/** @typedef {"stable" | "nightly"} Channel */
+/** @typedef {"macos" | "linux" | "windows"} Os */
+/** @typedef {"arm64" | "x64"} Arch */
+
+/**
+ * @typedef {object} Release The fields plx reads from GitHub's release list.
+ * @property {string} tag_name
+ * @property {boolean} prerelease
+ * @property {boolean} [draft]
+ * @property {Asset[]} assets
+ */
+
+/**
+ * @typedef {object} Asset
+ * @property {string} name
+ * @property {string} browser_download_url
+ * @property {string | null} [digest] GitHub's `sha256:<hex>` of the file, on assets uploaded since
+ *   mid-2025.
+ */
+
+/**
+ * @typedef {object} Installer What an install script downloads.
+ * @property {string} version The release's version: its tag without the `v`.
+ * @property {string} name The asset's file name.
+ * @property {string} url Where to download it.
+ * @property {string} sha256 Its SHA-256 as the release reports it, in hex. The script refuses a
+ *   file that doesn't match.
+ */
+
+/**
+ * @typedef {Omit<Installer, "sha256"> & { sha256?: string, sha256Url?: string }} Found
+ *   An asset {@link pickAsset} chose: with its SHA-256 from GitHub's digest, or where its
+ *   `.sha256` asset is, or neither. {@link withSha256} makes it an {@link Installer}.
+ */
+
+const RELEASES_URL = "https://api.github.com/repos/ryan-stoffel/parallax/releases?per_page=30";
+
+const OS_NAMES = { macos: "macOS", linux: "Linux", windows: "Windows" };
+
+/** The app's name for a channel: a nightly build is "Parallax (Nightly)" (PLX-286). @param {Channel} channel */
+export const appName = (channel) => (channel === "nightly" ? "Parallax (Nightly)" : "Parallax");
+
+/** The release list, newest first, from GitHub's API. */
+export async function fetchReleases() {
+  const response = await fetch(RELEASES_URL, {
+    headers: { accept: "application/vnd.github+json", "user-agent": "plx-cli" },
+    signal: AbortSignal.timeout(20_000),
+  });
+  if (!response.ok) throw new Error(`GitHub answered ${response.status} ${response.statusText} for the release list.`);
+  return /** @type {Release[]} */ (await response.json());
+}
+
+/**
+ * The newest release of `channel` in `releases` (GitHub lists newest first): for nightly, a
+ * prerelease tagged `*-nightly`; for stable, any release that isn't a prerelease. Throws a message
+ * for people when there's none.
+ * @param {Release[]} releases
+ * @param {Channel} channel
+ */
+export function pickRelease(releases, channel) {
+  const release = releases.find(
+    (r) => !r.draft && (channel === "nightly" ? r.prerelease && r.tag_name.endsWith("-nightly") : !r.prerelease),
+  );
+  if (release) return release;
+  if (channel === "stable") throw new Error("Parallax has no stable release yet. Run again with --channel nightly.");
+  throw new Error("Parallax has no nightly release.");
+}
+
+/**
+ * The asset in `release` for `os` and `arch`: the dmg on macOS (arm64 only) and the NSIS exe on
+ * Windows, or with `headless`, plxd by itself (`parallax-plxd-<v>-mac-arm64`,
+ * `parallax-plxd-<v>-win-<arch>.exe`). Linux always gets plxd by itself (PLX-642's asset), which
+ * runs where the AppImage's runtime can't, such as NixOS. Throws a message for people when the
+ * release has none.
+ * @param {Release} release
+ * @param {Os} os
+ * @param {Arch} arch
+ * @param {boolean} [headless]
+ * @returns {Found}
+ */
+export function pickAsset(release, os, arch, headless = false) {
+  const version = release.tag_name.replace(/^v/, "");
+  if (os === "macos" && arch !== "arm64") throw new Error("Parallax has no build for Intel Macs, only Apple silicon.");
+  const plxdOnly = os === "linux" || headless;
+  const tag = { macos: "mac", windows: "win", linux: "linux" }[os];
+  const name = plxdOnly
+    ? `parallax-plxd-${version}-${tag}-${arch}${os === "windows" ? ".exe" : ""}`
+    : `parallax-${version}-${tag}-${arch}.${os === "macos" ? "dmg" : "exe"}`;
+  const asset = release.assets.find((a) => a.name === name);
+  if (!asset) {
+    const kind = release.prerelease ? "nightly" : "release";
+    const what = plxdOnly && os !== "linux" ? "plxd" : "build";
+    throw new Error(`The newest ${kind}, ${release.tag_name}, has no ${OS_NAMES[os]} ${arch} ${what}.`);
+  }
+  const digest = /^sha256:([0-9a-f]{64})$/i.exec(asset.digest ?? "")?.[1]?.toLowerCase();
+  const sums = release.assets.find((a) => a.name === `${name}.sha256`);
+  return {
+    version,
+    name,
+    url: asset.browser_download_url,
+    ...(digest ? { sha256: digest } : sums && { sha256Url: sums.browser_download_url }),
+  };
+}
+
+/**
+ * `found` with its SHA-256: GitHub's digest, else the hash its `.sha256` asset lists for it
+ * (`<hex>  <name>`, as `shasum -a 256` writes). Throws a message for people when there's neither,
+ * so nothing is installed unchecked.
+ * @param {Found} found
+ * @param {(url: string) => Promise<string>} [fetchText]
+ * @returns {Promise<Installer>}
+ */
+export async function withSha256({ sha256Url, ...found }, fetchText = fetchUrl) {
+  if (found.sha256) return { ...found, sha256: found.sha256 };
+  const listed = sha256Url
+    ? (await fetchText(sha256Url))
+        .split(/\r?\n/)
+        .map((line) => /^([0-9a-f]{64}) [ *]?(.+)$/i.exec(line.trim()))
+        .find((m) => m?.[2] === found.name)?.[1]
+    : undefined;
+  if (!listed) throw new Error(`The release has no SHA-256 for ${found.name}, so plx won't install it.`);
+  return { ...found, sha256: listed.toLowerCase() };
+}
+
+/** The text at `url`. @param {string} url */
+async function fetchUrl(url) {
+  const response = await fetch(url, { headers: { "user-agent": "plx-cli" }, signal: AbortSignal.timeout(20_000) });
+  if (!response.ok) throw new Error(`GitHub answered ${response.status} ${response.statusText} for ${url}.`);
+  return response.text();
+}

package/src/run.mjs

@@ -0,0 +1,141 @@
+// @ts-check
+// Running a script, or `plxd attach`, on the target: over the system ssh for `add` and
+// `connect add`, or here for `setup` and `connect`.
+
+import { spawn } from "node:child_process";
+import { mkdtempSync, rmSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { POWERSHELL_ARGS } from "./scripts.mjs";
+
+/** @typedef {"sh" | "powershell"} Shell */
+/** @typedef {{ code: number, stdout: string }} Result */
+
+/**
+ * @typedef {object} Runner
+ * @property {(command: string) => Promise<Result>} command Runs `command` in the target's own
+ *   shell, keeping stdout. Only SSH targets have one to run it in.
+ * @property {(shell: Shell, script: string, capture: boolean) => Promise<Result>} script Runs
+ *   `script` with `sh -s` or PowerShell, from stdin. With `capture`, keeps stdout; without, prints
+ *   stdout and stderr indented as they arrive.
+ * @property {(os: import("./releases.mjs").Os) => import("node:child_process").ChildProcess} attach
+ *   Starts `plxd attach` from `~/.parallax-plxd` there, where the install put it (0072), with
+ *   stdin and stdout piped for plxd's JSON-RPC.
+ * @property {() => void} close Ends what the runner keeps open.
+ */
+
+/** Where the install puts plxd on this computer (0072). */
+export const localPlxd = () =>
+  path.join(os.homedir(), ".parallax-plxd", process.platform === "win32" ? "plxd.exe" : "plxd");
+
+/**
+ * The remote command that starts `plxd attach` from `~/.parallax-plxd` on an `os` computer: in
+ * sh, or on Windows in cmd, OpenSSH's default shell there, which expands `%USERPROFILE%`.
+ * @param {import("./releases.mjs").Os} os
+ */
+export const remoteAttach = (os) =>
+  os === "windows" ? `cmd /c "%USERPROFILE%\\.parallax-plxd\\plxd.exe" attach` : `"$HOME/.parallax-plxd/plxd" attach`;
+
+/**
+ * ssh's arguments to run `command` on `destination`. Host keys are accepted the first time,
+ * since the tailnet already authenticated the node (0056). With `controlDir`, the calls share
+ * one connection, so a password is asked once. Not BatchMode: the app runs this in a terminal,
+ * where ssh can ask for a password.
+ * @param {string} destination `[user@]host`
+ * @param {{ port?: string, controlDir?: string }} options
+ * @param {string[]} command
+ */
+export function sshArgs(destination, options, command) {
+  const args = ["-o", "StrictHostKeyChecking=accept-new", "-o", "ConnectTimeout=10"];
+  if (options.controlDir) {
+    args.push("-o", "ControlMaster=auto", "-o", `ControlPath=${options.controlDir}/%C`, "-o", "ControlPersist=120");
+  }
+  if (options.port) args.push("-p", options.port);
+  return [...args, "--", destination, ...command];
+}
+
+/** The remote command that reads a script of `shell` from stdin. @param {Shell} shell */
+const remoteReader = (shell) => (shell === "sh" ? ["sh -s"] : [`powershell ${POWERSHELL_ARGS.join(" ")}`]);
+
+/**
+ * A runner for `destination` over ssh. Windows' OpenSSH client has no ControlMaster, so there
+ * each call connects on its own. The control socket's folder is under /tmp, since the path of a
+ * Unix socket is limited to about 104 bytes and macOS' tmpdir is long.
+ * @param {string} destination
+ * @param {{ port?: string }} options
+ * @returns {Runner}
+ */
+export function sshRunner(destination, options) {
+  const controlDir = process.platform === "win32" ? undefined : mkdtempSync(path.join("/tmp", "plxc-"));
+  const ssh = process.platform === "win32" ? "ssh.exe" : "ssh";
+  const args = (/** @type {string[]} */ command) => sshArgs(destination, { ...options, controlDir }, command);
+  return {
+    command: (command) => exec(ssh, args([command]), { capture: true }),
+    script: (shell, script, capture) => exec(ssh, args(remoteReader(shell)), { input: script, capture }),
+    attach: (os) => spawn(ssh, args([remoteAttach(os)]), { stdio: ["pipe", "pipe", "ignore"] }),
+    close() {
+      if (!controlDir) return;
+      spawn(ssh, ["-O", "exit", ...args([])], { stdio: "ignore" }).once("close", () =>
+        rmSync(controlDir, { recursive: true, force: true }),
+      );
+    },
+  };
+}
+
+/** A runner for this computer. @returns {Runner} */
+export function localRunner() {
+  return {
+    command: () => Promise.reject(new Error("no shell command runs locally")),
+    script: (shell, script, capture) =>
+      shell === "sh"
+        ? exec("sh", ["-s"], { input: script, capture })
+        : exec("powershell.exe", POWERSHELL_ARGS, { input: script, capture }),
+    attach: () => spawn(localPlxd(), ["attach"], { stdio: ["pipe", "pipe", "ignore"] }),
+    close() {},
+  };
+}
+
+/**
+ * Runs `file` and resolves to its exit code (255 when it couldn't start, as ssh reports a failed
+ * connection) and, with `capture`, its stdout. stderr always reaches the terminal: the first ssh
+ * call may become a background ControlMaster that keeps stderr open, so it is never piped then.
+ * @param {string} file
+ * @param {string[]} args
+ * @param {{ input?: string, capture: boolean }} options
+ * @returns {Promise<Result>}
+ */
+function exec(file, args, { input, capture }) {
+  return new Promise((resolve) => {
+    const child = spawn(file, args, {
+      stdio: [input === undefined ? "inherit" : "pipe", "pipe", capture ? "inherit" : "pipe"],
+    });
+    let stdout = "";
+    if (capture) child.stdout?.on("data", (chunk) => (stdout += chunk));
+    else {
+      indent(child.stdout);
+      indent(child.stderr);
+    }
+    child.once("error", (error) => {
+      console.log(`  ${file}: ${error.message}`);
+      resolve({ code: 255, stdout });
+    });
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout }));
+    if (input !== undefined) child.stdin?.end(input);
+  });
+}
+
+/** Prints what `stream` sends, a line at a time, indented under the step it belongs to. @param {import("node:stream").Readable | null} stream */
+function indent(stream) {
+  if (!stream) return;
+  let pending = "";
+  stream.setEncoding("utf8");
+  stream.on("data", (/** @type {string} */ chunk) => {
+    const lines = (pending + chunk).split("\n");
+    pending = lines.pop() ?? "";
+    for (const line of lines) console.log(`  ${line.replace(/\r$/, "")}`);
+  });
+  stream.on("end", () => {
+    if (pending) console.log(`  ${pending.replace(/\r$/, "")}`);
+  });
+}