@trackseries/cli 0.1.0-preview.1

package/README.md

@@ -0,0 +1,60 @@
+# TrackSeries CLI
+
+The TrackSeries CLI provides terminal and agent-friendly access to your TrackSeries account. This public repository contains the npm installer and downloadable releases; the application source is maintained separately.
+
+## Install with npm
+
+Node.js 20 or newer is required. Install the latest stable release with:
+
+```bash
+npm install --global @trackseries/cli
+trackseries auth login
+```
+
+Before the first stable release, install the current preview with:
+
+```bash
+npm install --global @trackseries/cli@next
+```
+
+The npm installer downloads and checksum-verifies the matching release artifact for the current operating system and architecture. The installed `trackseries` command is a standalone executable and does not use Node.js while running.
+
+Supported targets:
+
+- glibc-based Linux x64 and ARM64
+- macOS x64 and ARM64
+- Windows x64 and ARM64
+
+## Direct download
+
+Archives and SHA-256 checksums are available from [GitHub Releases](https://github.com/TrackSeries/cli/releases).
+
+After installation, authenticate and inspect the available commands:
+
+```bash
+trackseries auth login
+trackseries auth status
+trackseries skill
+```
+
+`trackseries skill` prints version-matched instructions designed for coding agents and other automated tools.
+
+## Updates
+
+Install the latest published version with:
+
+```bash
+npm install --global @trackseries/cli@latest
+```
+
+Preview releases are published under the npm `next` tag:
+
+```bash
+npm install --global @trackseries/cli@next
+```
+
+## Security
+
+Authentication uses the OAuth device authorization flow. Credentials are stored in the platform-specific TrackSeries configuration directory and are never stored in this repository or the npm package.
+
+Release archives are verified against their accompanying SHA-256 checksum before installation. The initial binaries are not code-signed, so Windows SmartScreen or macOS Gatekeeper may require manual approval.

package/bin/trackseries.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const executableName = process.platform === "win32" ? "trackseries.exe" : "trackseries";
+const executablePath = resolve(packageRoot, "vendor", executableName);
+
+if (!existsSync(executablePath)) {
+  console.error("The TrackSeries CLI executable is missing. Reinstall @trackseries/cli.");
+  process.exit(1);
+}
+
+const result = spawnSync(executablePath, process.argv.slice(2), {
+  stdio: "inherit"
+});
+
+if (result.error) {
+  console.error(`Unable to start the TrackSeries CLI: ${result.error.message}`);
+  process.exit(1);
+}
+
+if (result.signal) {
+  process.kill(process.pid, result.signal);
+}
+
+process.exit(result.status ?? 1);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@trackseries/cli",
+  "version": "0.1.0-preview.1",
+  "description": "Install and run the TrackSeries CLI.",
+  "type": "module",
+  "bin": {
+    "trackseries": "./bin/trackseries.js"
+  },
+  "files": [
+    "bin/trackseries.js",
+    "scripts/install.js",
+    "scripts/platform.js"
+  ],
+  "scripts": {
+    "postinstall": "node scripts/install.js",
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "fflate": "0.8.3",
+    "tar": "7.5.22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/TrackSeries/cli.git"
+  },
+  "homepage": "https://github.com/TrackSeries/cli#readme",
+  "bugs": {
+    "url": "https://github.com/TrackSeries/cli/issues"
+  }
+}

package/scripts/install.js

@@ -0,0 +1,110 @@
+import { createHash } from "node:crypto";
+import { chmod, copyFile, lstat, mkdir, mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { unzipSync } from "fflate";
+import { x as extractTar } from "tar";
+import { assertSupportedRuntime, releaseArtifact } from "./platform.js";
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const metadata = JSON.parse(await readFile(resolve(packageRoot, "package.json"), "utf8"));
+assertSupportedRuntime();
+const artifact = releaseArtifact(metadata.version);
+const releaseBaseUrl =
+  process.env.TRACKSERIES_CLI_RELEASE_BASE_URL ?? `https://github.com/TrackSeries/cli/releases/download/cli-v${metadata.version}`;
+const temporaryDirectory = await mkdtemp(resolve(tmpdir(), "trackseries-cli-"));
+const archivePath = resolve(temporaryDirectory, artifact);
+const extractionPath = resolve(temporaryDirectory, "extracted");
+const executableName = process.platform === "win32" ? "trackseries.exe" : "trackseries";
+const installedExecutable = resolve(packageRoot, "vendor", executableName);
+const pendingExecutable = `${installedExecutable}.${process.pid}.tmp`;
+
+async function download(url) {
+  let lastError;
+
+  for (let attempt = 1; attempt <= 3; attempt += 1) {
+    let response;
+    try {
+      response = await fetch(url, {
+        headers: {
+          "User-Agent": `@trackseries/cli/${metadata.version}`
+        },
+        signal: AbortSignal.timeout(60_000)
+      });
+    } catch (error) {
+      lastError = error;
+    }
+
+    if (response?.ok) {
+      return Buffer.from(await response.arrayBuffer());
+    }
+
+    if (response) {
+      lastError = new Error(`HTTP ${response.status}`);
+      if (response.status < 500 && response.status !== 408 && response.status !== 429) break;
+    }
+
+    if (attempt < 3) {
+      await new Promise((resolveDelay) => setTimeout(resolveDelay, attempt * 1_000));
+    }
+  }
+
+  throw new Error(`Unable to download ${url}: ${lastError instanceof Error ? lastError.message : String(lastError)}.`);
+}
+
+try {
+  const [archive, checksumFile] = await Promise.all([
+    download(`${releaseBaseUrl}/${artifact}`),
+    download(`${releaseBaseUrl}/${artifact}.sha256`)
+  ]);
+  const expectedChecksum = checksumFile.toString("utf8").trim().split(/\s+/)[0]?.toLowerCase();
+  const actualChecksum = createHash("sha256").update(archive).digest("hex");
+
+  if (!expectedChecksum || actualChecksum !== expectedChecksum) {
+    throw new Error(`Checksum verification failed for ${artifact}.`);
+  }
+
+  await mkdir(extractionPath, { recursive: true });
+  await writeFile(archivePath, archive);
+
+  if (process.platform === "win32") {
+    const executable = unzipSync(archive, {
+      filter: (file) => file.name === executableName
+    })[executableName];
+    if (!executable) {
+      throw new Error(`${artifact} does not contain ${executableName}.`);
+    }
+    await writeFile(resolve(extractionPath, executableName), executable);
+  } else {
+    await extractTar({
+      cwd: extractionPath,
+      file: archivePath,
+      filter: (path, entry) => (path === executableName || path === `./${executableName}`) && entry.type === "File"
+    });
+  }
+
+  const extractedExecutable = resolve(extractionPath, executableName);
+  if (!(await lstat(extractedExecutable)).isFile()) {
+    throw new Error(`${artifact} does not contain a regular ${executableName} file.`);
+  }
+
+  await mkdir(dirname(installedExecutable), { recursive: true });
+  await copyFile(extractedExecutable, pendingExecutable);
+
+  if (process.platform !== "win32") {
+    await chmod(pendingExecutable, 0o755);
+  } else {
+    await rm(installedExecutable, { force: true });
+  }
+
+  await rename(pendingExecutable, installedExecutable);
+} catch (error) {
+  throw new Error(
+    `Unable to install TrackSeries CLI ${metadata.version}. Download ${artifact} manually from ${releaseBaseUrl}.`,
+    { cause: error }
+  );
+} finally {
+  await rm(pendingExecutable, { force: true });
+  await rm(temporaryDirectory, { force: true, recursive: true });
+}

package/scripts/platform.js

@@ -0,0 +1,22 @@
+export function releaseArtifact(version, platform = process.platform, architecture = process.arch) {
+  const platformNames = {
+    darwin: "macos",
+    linux: "linux",
+    win32: "windows"
+  };
+  const architectures = new Set(["arm64", "x64"]);
+  const platformName = platformNames[platform];
+
+  if (!platformName || !architectures.has(architecture)) {
+    throw new Error(`TrackSeries CLI does not support ${platform}-${architecture}.`);
+  }
+
+  const extension = platform === "win32" ? "zip" : "tar.gz";
+  return `trackseries-${version}-${platformName}-${architecture}.${extension}`;
+}
+
+export function assertSupportedRuntime(platform = process.platform, report = process.report?.getReport()) {
+  if (platform === "linux" && !report?.header?.glibcVersionRuntime) {
+    throw new Error("TrackSeries CLI requires a glibc-based Linux distribution. Alpine and other musl-based systems are not yet supported.");
+  }
+}