feat(cli): support self-updated binaries

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Copilot-Session: 5a30d535-428b-49ca-892c-e2a25c137a5f

Author: adrifer

bin/trackseries.js

@@ -3,6 +3,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { ensureBinary } from "../scripts/install.js";
+import { binaryRoot } from "../scripts/platform.js";
 
 let executablePath;
 try {
@@ -13,6 +14,10 @@ try {
 }
 
 const result = spawnSync(executablePath, process.argv.slice(2), {
+  env: {
+    ...process.env,
+    TRACKSERIES_CLI_BINARY_ROOT: binaryRoot()
+  },
   stdio: "inherit"
 });
 

bin/trackseries.test.js

@@ -0,0 +1,34 @@
+import assert from "node:assert/strict";
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import test from "node:test";
+
+test("launches the active self-updated binary with the managed root", async () => {
+  const dataHome = await mkdtemp(resolve(tmpdir(), "trackseries-launcher-test-"));
+  const binaryRoot = resolve(dataHome, "trackseries", "bin");
+  const binaryDirectory = resolve(binaryRoot, "9.9.9");
+  const executablePath = resolve(binaryDirectory, "trackseries");
+
+  try {
+    await mkdir(binaryDirectory, { recursive: true });
+    await writeFile(resolve(binaryRoot, "current.json"), JSON.stringify({ version: "9.9.9" }));
+    await writeFile(executablePath, '#!/bin/sh\nprintf "%s\\n" "$TRACKSERIES_CLI_BINARY_ROOT" "$*"\n');
+    await chmod(executablePath, 0o755);
+
+    const result = spawnSync(process.execPath, ["bin/trackseries.js", "stats", "--json"], {
+      cwd: resolve(import.meta.dirname, ".."),
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        XDG_DATA_HOME: dataHome
+      }
+    });
+
+    assert.equal(result.status, 0, result.stderr);
+    assert.equal(result.stdout, `${binaryRoot}\nstats --json\n`);
+  } finally {
+    await rm(dataHome, { force: true, recursive: true });
+  }
+});

package-lock.json

@@ -19,6 +19,7 @@
   },
   "dependencies": {
     "fflate": "0.8.3",
+    "semver": "7.8.5",
     "tar": "7.5.22"
   },
   "publishConfig": {

package.json

@@ -1,50 +1,15 @@
-const candidate = parseVersion(process.argv[2]);
-const published = process.argv[3] ? parseVersion(process.argv[3]) : undefined;
+import { gt, valid } from "semver";
 
-if (published && compareVersions(candidate, published) <= 0) {
-  throw new Error(`${candidate.source} must be newer than the current npm tag version ${published.source}.`);
-}
-
-function parseVersion(source) {
-  const match = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+[0-9A-Za-z.-]+)?$/.exec(source);
-  if (!match) {
-    throw new Error(`${source} is not a supported semantic version.`);
-  }
+const candidate = assertVersion(process.argv[2]);
+const published = process.argv[3] ? assertVersion(process.argv[3]) : undefined;
 
-  return {
-    source,
-    core: [Number(match[1]), Number(match[2]), Number(match[3])],
-    prerelease: match[4]?.split(".")
-  };
+if (published && !gt(candidate, published)) {
+  throw new Error(`${candidate} must be newer than the current npm tag version ${published}.`);
 }
 
-function compareVersions(left, right) {
-  for (let index = 0; index < left.core.length; index += 1) {
-    if (left.core[index] !== right.core[index]) {
-      return left.core[index] - right.core[index];
-    }
-  }
-
-  if (!left.prerelease || !right.prerelease) {
-    if (!left.prerelease && !right.prerelease) return 0;
-    return left.prerelease ? -1 : 1;
-  }
-
-  const length = Math.max(left.prerelease.length, right.prerelease.length);
-  for (let index = 0; index < length; index += 1) {
-    const leftIdentifier = left.prerelease[index];
-    const rightIdentifier = right.prerelease[index];
-    if (leftIdentifier === undefined) return -1;
-    if (rightIdentifier === undefined) return 1;
-    if (leftIdentifier === rightIdentifier) continue;
-
-    const leftNumeric = /^\d+$/.test(leftIdentifier);
-    const rightNumeric = /^\d+$/.test(rightIdentifier);
-    if (leftNumeric && rightNumeric) return Number(leftIdentifier) - Number(rightIdentifier);
-    if (leftNumeric) return -1;
-    if (rightNumeric) return 1;
-    return leftIdentifier < rightIdentifier ? -1 : 1;
+function assertVersion(source) {
+  if (!source || !valid(source)) {
+    throw new Error(`${source} is not a supported semantic version.`);
   }
-
-  return 0;
+  return source;
 }

scripts/assert-newer-version.js

@@ -4,8 +4,9 @@ import { tmpdir } from "node:os";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { unzipSync } from "fflate";
+import { gt, valid } from "semver";
 import { x as extractTar } from "tar";
-import { assertSupportedRuntime, binaryDirectory, releaseArtifact } from "./platform.js";
+import { assertSupportedRuntime, binaryDirectory, binaryRoot, releaseArtifact } from "./platform.js";
 
 const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
 const metadata = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
@@ -54,11 +55,13 @@ async function isRegularFile(path) {
 
 export async function ensureBinary() {
   assertSupportedRuntime();
-  const artifact = releaseArtifact(metadata.version);
+  const root = binaryRoot();
+  const version = await resolveBinaryVersion(metadata.version, root);
+  const artifact = releaseArtifact(version);
   const releaseBaseUrl =
-    process.env.TRACKSERIES_CLI_RELEASE_BASE_URL ?? `https://github.com/TrackSeries/cli/releases/download/cli-v${metadata.version}`;
+    process.env.TRACKSERIES_CLI_RELEASE_BASE_URL ?? `https://github.com/TrackSeries/cli/releases/download/cli-v${version}`;
   const executableName = process.platform === "win32" ? "trackseries.exe" : "trackseries";
-  const installedExecutable = resolve(binaryDirectory(metadata.version), executableName);
+  const installedExecutable = resolve(binaryDirectory(version), executableName);
 
   if (await isRegularFile(installedExecutable)) return installedExecutable;
 
@@ -67,7 +70,7 @@ export async function ensureBinary() {
   const extractionPath = resolve(temporaryDirectory, "extracted");
   const pendingExecutable = `${installedExecutable}.${process.pid}.tmp`;
 
-  console.error(`Downloading TrackSeries CLI ${metadata.version} for ${process.platform}-${process.arch}...`);
+  console.error(`Downloading TrackSeries CLI ${version} for ${process.platform}-${process.arch}...`);
 
   try {
     const [archive, checksumFile] = await Promise.all([
@@ -119,11 +122,30 @@ export async function ensureBinary() {
   } catch (error) {
     const reason = error instanceof Error ? error.message : String(error);
     throw new Error(
-      `Unable to install TrackSeries CLI ${metadata.version}: ${reason} Download ${artifact} manually from ${releaseBaseUrl}.`,
+      `Unable to install TrackSeries CLI ${version}: ${reason} Download ${artifact} manually from ${releaseBaseUrl}.`,
       { cause: error }
     );
   } finally {
     await rm(pendingExecutable, { force: true });
     await rm(temporaryDirectory, { force: true, recursive: true });
   }
 }
+
+export async function resolveBinaryVersion(packageVersion, root) {
+  const manifestPath = resolve(root, "current.json");
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch (error) {
+    if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") {
+      return packageVersion;
+    }
+    throw new Error(`Unable to read the TrackSeries CLI update state at ${manifestPath}.`, { cause: error });
+  }
+
+  const activeVersion = typeof manifest?.version === "string" ? valid(manifest.version) : null;
+  if (!activeVersion) {
+    throw new Error(`The TrackSeries CLI update state at ${manifestPath} contains an invalid version.`);
+  }
+  return gt(activeVersion, packageVersion) ? activeVersion : packageVersion;
+}

scripts/install.js

@@ -0,0 +1,46 @@
+import assert from "node:assert/strict";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { resolve } from "node:path";
+import test from "node:test";
+
+import { resolveBinaryVersion } from "./install.js";
+
+test("uses the package version without an active self-update", async () => {
+  const root = await mkdtemp(resolve(tmpdir(), "trackseries-launcher-test-"));
+  try {
+    assert.equal(await resolveBinaryVersion("1.2.0", root), "1.2.0");
+  } finally {
+    await rm(root, { force: true, recursive: true });
+  }
+});
+
+test("uses a newer self-updated binary version", async () => {
+  const root = await mkdtemp(resolve(tmpdir(), "trackseries-launcher-test-"));
+  try {
+    await writeFile(resolve(root, "current.json"), JSON.stringify({ version: "1.3.0-preview.1" }));
+    assert.equal(await resolveBinaryVersion("1.2.0", root), "1.3.0-preview.1");
+  } finally {
+    await rm(root, { force: true, recursive: true });
+  }
+});
+
+test("prefers a newer npm package over an old self-update", async () => {
+  const root = await mkdtemp(resolve(tmpdir(), "trackseries-launcher-test-"));
+  try {
+    await writeFile(resolve(root, "current.json"), JSON.stringify({ version: "1.1.0" }));
+    assert.equal(await resolveBinaryVersion("1.2.0", root), "1.2.0");
+  } finally {
+    await rm(root, { force: true, recursive: true });
+  }
+});
+
+test("rejects an invalid self-update manifest", async () => {
+  const root = await mkdtemp(resolve(tmpdir(), "trackseries-launcher-test-"));
+  try {
+    await writeFile(resolve(root, "current.json"), JSON.stringify({ version: "../../escape" }));
+    await assert.rejects(resolveBinaryVersion("1.2.0", root), /contains an invalid version/);
+  } finally {
+    await rm(root, { force: true, recursive: true });
+  }
+});

scripts/install.test.js

@@ -25,6 +25,11 @@ export function assertSupportedRuntime(platform = process.platform, report = pro
 }
 
 export function binaryDirectory(version, platform = process.platform, environment = process.env, home = homedir()) {
+  const path = platform === "win32" ? win32 : posix;
+  return path.join(binaryRoot(platform, environment, home), version);
+}
+
+export function binaryRoot(platform = process.platform, environment = process.env, home = homedir()) {
   const path = platform === "win32" ? win32 : posix;
   let dataDirectory;
 
@@ -36,5 +41,5 @@ export function binaryDirectory(version, platform = process.platform, environmen
     dataDirectory = environment.XDG_DATA_HOME ?? path.join(home, ".local", "share");
   }
 
-  return path.join(dataDirectory, "trackseries", "bin", version);
+  return path.join(dataDirectory, "trackseries", "bin");
 }

scripts/platform.js

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { assertSupportedRuntime, binaryDirectory, releaseArtifact } from "./platform.js";
+import { assertSupportedRuntime, binaryDirectory, binaryRoot, releaseArtifact } from "./platform.js";
 
 test("maps supported platforms to release archives", () => {
   assert.equal(releaseArtifact("1.2.3", "linux", "x64"), "trackseries-1.2.3-linux-x64.tar.gz");
@@ -20,6 +20,7 @@ test("rejects musl-based Linux installations", () => {
 });
 
 test("uses platform-specific user data directories", () => {
+  assert.equal(binaryRoot("linux", { XDG_DATA_HOME: "/data" }, "/home/user"), "/data/trackseries/bin");
   assert.equal(binaryDirectory("1.2.3", "linux", { XDG_DATA_HOME: "/data" }, "/home/user"), "/data/trackseries/bin/1.2.3");
   assert.equal(
     binaryDirectory("1.2.3", "darwin", {}, "/Users/user"),