@betterborg/cli 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 BetterBorg
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,7 @@
+BetterBorg CLI
+Copyright 2026 BetterBorg
+
+This product includes software developed by BetterBorg
+(https://github.com/betterborg).
+
+BetterBorg CLI is distributed under the MIT License. See LICENSE.

package/bin/borg.js

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+
+"use strict";
+
+const metadata = require("../package.json");
+const { main, reportFailure } = require("../lib/launcher");
+
+main(process.argv.slice(2), { version: metadata.version }).catch(reportFailure);

package/lib/launcher.js

@@ -0,0 +1,421 @@
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+
+const REPOSITORY = "betterborg/betterborg-cli";
+const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"];
+const SIGNAL_EXIT_CODES = { SIGHUP: 129, SIGINT: 130, SIGTERM: 143 };
+
+function targetFor(platform, architecture) {
+  const operatingSystems = { darwin: "darwin", linux: "linux" };
+  const architectures = { arm64: "arm64", x64: "x86_64" };
+  const operatingSystem = operatingSystems[platform];
+  const targetArchitecture = architectures[architecture];
+  if (!operatingSystem || !targetArchitecture) {
+    return null;
+  }
+  return `borg-${operatingSystem}-${targetArchitecture}`;
+}
+
+function translateVersionArguments(arguments_) {
+  if (
+    arguments_.length === 1 &&
+    (arguments_[0] === "--version" || arguments_[0] === "-V")
+  ) {
+    return ["version"];
+  }
+  return [...arguments_];
+}
+
+function executableNames(name, platform, environment) {
+  if (platform !== "win32") {
+    return [name];
+  }
+  const extensions = (environment.PATHEXT || ".EXE;.CMD;.BAT;.COM")
+    .split(";")
+    .filter(Boolean);
+  return [name, ...extensions.map((extension) => `${name}${extension}`)];
+}
+
+function samePath(left, right, platform) {
+  if (platform === "win32") {
+    return left.toLowerCase() === right.toLowerCase();
+  }
+  return left === right;
+}
+
+function isWindowsCommandScript(command, platform) {
+  return platform === "win32" && /\.(?:cmd|bat)$/i.test(command);
+}
+
+const WINDOWS_SHELL_META_CHARACTERS = /([()\][%!^"`<>&|;, *?])/g;
+
+function escapeWindowsCommand(command) {
+  return command.replace(WINDOWS_SHELL_META_CHARACTERS, "^$1");
+}
+
+function escapeWindowsArgument(argument) {
+  let escaped = String(argument)
+    .replace(/(\\*)"/g, '$1$1\\"')
+    .replace(/(\\*)$/, "$1$1");
+  escaped = `"${escaped}"`;
+  return escaped.replace(WINDOWS_SHELL_META_CHARACTERS, "^$1");
+}
+
+function commandInvocation(command, arguments_, options, dependencies) {
+  if (!isWindowsCommandScript(command, dependencies.platform)) {
+    return { command, arguments: arguments_, options };
+  }
+  if ([command, ...arguments_].some((value) => /[\r\n]/.test(value))) {
+    throw new Error(
+      "Windows command shims cannot safely forward paths or arguments containing line breaks",
+    );
+  }
+
+  const shell =
+    dependencies.environment.ComSpec ||
+    dependencies.environment.COMSPEC ||
+    "cmd.exe";
+  const shellCommand = [
+    escapeWindowsCommand(command),
+    ...arguments_.map(escapeWindowsArgument),
+  ].join(" ");
+  return {
+    command: shell,
+    arguments: ["/d", "/s", "/v:off", "/c", `"${shellCommand}"`],
+    options: { ...options, windowsVerbatimArguments: true },
+  };
+}
+
+function launcherExecutables(dependencies) {
+  if (!dependencies.launcherPath) {
+    return [];
+  }
+  const executables = [dependencies.launcherPath];
+  let directory = dependencies.pathModule.dirname(dependencies.launcherPath);
+  while (dependencies.pathModule.dirname(directory) !== directory) {
+    if (
+      dependencies.pathModule.basename(directory).toLowerCase() ===
+      "node_modules"
+    ) {
+      const shimDirectories = [
+        dependencies.pathModule.join(directory, ".bin"),
+      ];
+      if (dependencies.platform === "win32") {
+        shimDirectories.push(dependencies.pathModule.dirname(directory));
+      }
+      const names =
+        dependencies.platform === "win32"
+          ? ["borg", "borg.cmd", "borg.ps1"]
+          : ["borg"];
+      for (const shimDirectory of shimDirectories) {
+        for (const name of names) {
+          executables.push(dependencies.pathModule.resolve(shimDirectory, name));
+        }
+      }
+    }
+    directory = dependencies.pathModule.dirname(directory);
+  }
+  return executables;
+}
+
+function executableOnPath(name, dependencies, excludedPaths = []) {
+  const {
+    environment,
+    fileSystem,
+    pathModule,
+    platform,
+    pathDelimiter,
+  } = dependencies;
+  const pathValue = environment.PATH || environment.Path || "";
+  for (const directory of pathValue.split(pathDelimiter)) {
+    if (!directory) {
+      continue;
+    }
+    for (const executableName of executableNames(name, platform, environment)) {
+      const candidate = pathModule.resolve(directory, executableName);
+      try {
+        fileSystem.accessSync(candidate, fileSystem.constants.X_OK);
+        const resolvedCandidate = fileSystem.realpathSync(candidate);
+        if (
+          !excludedPaths.some((excludedPath) =>
+            samePath(resolvedCandidate, excludedPath, platform),
+          )
+        ) {
+          return candidate;
+        }
+      } catch {
+        // A PATH entry that is missing or not executable is not a candidate.
+      }
+    }
+  }
+  return null;
+}
+
+function installedCli(version, dependencies) {
+  const candidate = executableOnPath(
+    "borg",
+    dependencies,
+    launcherExecutables(dependencies),
+  );
+  if (!candidate) {
+    return null;
+  }
+  const invocation = commandInvocation(
+    candidate,
+    ["version"],
+    {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 5000,
+    },
+    dependencies,
+  );
+  const completed = dependencies.spawnSync(
+    invocation.command,
+    invocation.arguments,
+    invocation.options,
+  );
+  if (
+    completed.status === 0 &&
+    completed.stdout.trim() === `borg ${version}`
+  ) {
+    return candidate;
+  }
+  return null;
+}
+
+function digest(pathname, fileSystem = fs) {
+  return crypto
+    .createHash("sha256")
+    .update(fileSystem.readFileSync(pathname))
+    .digest("hex");
+}
+
+function verifiedBinary(binaryPath, checksumPath, target, fileSystem = fs) {
+  try {
+    const checksum = fileSystem.readFileSync(checksumPath, "utf8");
+    const match = checksum.match(/^([a-f0-9]{64})  ([^\r\n]+)\n$/);
+    return Boolean(
+      match &&
+        match[2] === target &&
+        digest(binaryPath, fileSystem) === match[1],
+    );
+  } catch {
+    return false;
+  }
+}
+
+async function downloadToFile(url, destination) {
+  const response = await fetch(url, { redirect: "follow" });
+  if (!response.ok) {
+    throw new Error(`download returned HTTP ${response.status} for ${url}`);
+  }
+  const content = Buffer.from(await response.arrayBuffer());
+  fs.writeFileSync(destination, content, { flag: "wx" });
+}
+
+function defaultCacheDirectory(version, dependencies) {
+  const root = dependencies.environment.XDG_CACHE_HOME
+    ? dependencies.pathModule.resolve(dependencies.environment.XDG_CACHE_HOME)
+    : dependencies.pathModule.join(dependencies.homeDirectory, ".cache");
+  return dependencies.pathModule.join(root, "betterborg", "cli", version);
+}
+
+async function cachedRelease(version, target, dependencies) {
+  const directory =
+    dependencies.cacheDirectory || defaultCacheDirectory(version, dependencies);
+  const binaryPath = dependencies.pathModule.join(directory, target);
+  const checksumPath = dependencies.pathModule.join(directory, `${target}.sha256`);
+  if (
+    verifiedBinary(binaryPath, checksumPath, target, dependencies.fileSystem)
+  ) {
+    dependencies.fileSystem.chmodSync(binaryPath, 0o755);
+    return binaryPath;
+  }
+
+  dependencies.fileSystem.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const nonce = dependencies.randomBytes(8).toString("hex");
+  const temporaryBinary = `${binaryPath}.${nonce}.tmp`;
+  const temporaryChecksum = `${checksumPath}.${nonce}.tmp`;
+  const releaseRoot = `https://github.com/${REPOSITORY}/releases/download/v${version}`;
+  try {
+    await dependencies.download(`${releaseRoot}/${target}`, temporaryBinary);
+    await dependencies.download(
+      `${releaseRoot}/${target}.sha256`,
+      temporaryChecksum,
+    );
+    if (
+      !verifiedBinary(
+        temporaryBinary,
+        temporaryChecksum,
+        target,
+        dependencies.fileSystem,
+      )
+    ) {
+      throw new Error(`downloaded ${target} failed SHA-256 verification`);
+    }
+    dependencies.fileSystem.chmodSync(temporaryBinary, 0o755);
+    dependencies.fileSystem.renameSync(temporaryBinary, binaryPath);
+    dependencies.fileSystem.renameSync(temporaryChecksum, checksumPath);
+    return binaryPath;
+  } finally {
+    dependencies.fileSystem.rmSync(temporaryBinary, { force: true });
+    dependencies.fileSystem.rmSync(temporaryChecksum, { force: true });
+  }
+}
+
+function withDefaults(overrides = {}) {
+  let launcherPath = null;
+  try {
+    launcherPath = fs.realpathSync(process.argv[1]);
+  } catch {
+    // Tests and unusual embeddings may not have a filesystem entry in argv[1].
+  }
+  return {
+    cacheDirectory: null,
+    download: downloadToFile,
+    environment: process.env,
+    fileSystem: fs,
+    homeDirectory: os.homedir(),
+    launcherPath,
+    pathDelimiter: path.delimiter,
+    pathModule: path,
+    platform: process.platform,
+    architecture: process.arch,
+    process,
+    randomBytes: crypto.randomBytes,
+    spawn,
+    spawnSync,
+    ...overrides,
+  };
+}
+
+async function resolveCli(version, overrides = {}) {
+  const dependencies = withDefaults(overrides);
+  const installed = installedCli(version, dependencies);
+  if (installed) {
+    return { command: installed, argumentsPrefix: [], source: "installed" };
+  }
+
+  const target = targetFor(dependencies.platform, dependencies.architecture);
+  let releaseFailure = null;
+  if (target) {
+    try {
+      const binary = await cachedRelease(version, target, dependencies);
+      return { command: binary, argumentsPrefix: [], source: "release" };
+    } catch (error) {
+      releaseFailure = error instanceof Error ? error.message : String(error);
+    }
+  }
+
+  const uvx = executableOnPath("uvx", dependencies);
+  if (uvx) {
+    return {
+      command: uvx,
+      argumentsPrefix: ["--from", `betterborg==${version}`, "borg"],
+      source: "uvx",
+    };
+  }
+
+  const targetDescription = target
+    ? `could not install the ${target} release${releaseFailure ? ` (${releaseFailure})` : ""}`
+    : `no standalone release supports ${dependencies.platform}/${dependencies.architecture}`;
+  throw new Error(
+    `${targetDescription}, and uvx is not on PATH. Install uv from https://docs.astral.sh/uv/ or install betterborg==${version} so borg is on PATH.`,
+  );
+}
+
+function launch(resolved, arguments_, overrides = {}) {
+  const dependencies = withDefaults(overrides);
+  return new Promise((resolve, reject) => {
+    let settled = false;
+    let child;
+    try {
+      const invocation = commandInvocation(
+        resolved.command,
+        [...resolved.argumentsPrefix, ...arguments_],
+        { stdio: "inherit" },
+        dependencies,
+      );
+      child = dependencies.spawn(
+        invocation.command,
+        invocation.arguments,
+        invocation.options,
+      );
+    } catch (error) {
+      reject(error);
+      return;
+    }
+
+    const handlers = new Map(
+      FORWARDED_SIGNALS.map((signal) => [
+        signal,
+        () => {
+          child.kill(signal);
+        },
+      ]),
+    );
+    for (const [signal, handler] of handlers) {
+      dependencies.process.on(signal, handler);
+    }
+    const cleanup = () => {
+      for (const [signal, handler] of handlers) {
+        dependencies.process.removeListener(signal, handler);
+      }
+    };
+
+    child.once("error", (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(new Error(`could not start BetterBorg CLI: ${error.message}`));
+    });
+    child.once("close", (code, signal) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      if (signal) {
+        if (typeof dependencies.process.kill === "function") {
+          dependencies.process.kill(dependencies.process.pid, signal);
+        } else {
+          dependencies.process.exitCode = SIGNAL_EXIT_CODES[signal] || 1;
+        }
+      } else {
+        dependencies.process.exitCode = code === null ? 1 : code;
+      }
+      resolve();
+    });
+  });
+}
+
+async function main(arguments_, overrides = {}) {
+  if (!overrides.version) {
+    throw new Error("npm package version metadata is missing");
+  }
+  const resolved = await resolveCli(overrides.version, overrides);
+  await launch(resolved, translateVersionArguments(arguments_), overrides);
+}
+
+function reportFailure(error, dependencies = {}) {
+  const logger = dependencies.console || console;
+  const processLike = dependencies.process || process;
+  const message = error instanceof Error ? error.message : String(error);
+  logger.error(`borg: ${message}`);
+  processLike.exitCode = 1;
+}
+
+module.exports = {
+  cachedRelease,
+  launch,
+  main,
+  reportFailure,
+  resolveCli,
+  targetFor,
+  translateVersionArguments,
+  verifiedBinary,
+};

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@betterborg/cli",
-  "version": "0.0.1",
-  "description": "Placeholder reserving @betterborg/cli. The first real release is 0.1.0.",
+  "version": "0.1.0",
+  "description": "Installer and launcher for the BetterBorg CLI",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/betterborg/betterborg-cli.git",
     "directory": "npm"
   },
-  "homepage": "https://github.com/betterborg/betterborg-cli",
-  "publishConfig": { "access": "public" },
-  "files": ["README.md"]
+  "homepage": "https://github.com/betterborg/betterborg-cli#readme",
+  "bugs": "https://github.com/betterborg/betterborg-cli/issues",
+  "type": "commonjs",
+  "bin": {
+    "borg": "bin/borg.js"
+  },
+  "files": [
+    "LICENSE",
+    "NOTICE",
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "lint": "node --check bin/borg.js && node --check lib/launcher.js && node --check test/launcher.test.js",
+    "test": "node --test test/launcher.test.js"
+  }
 }

package/README.md

@@ -1,11 +0,0 @@
-# @betterborg/cli
-
-Placeholder reserving this package name. It contains no code.
-
-The first published release is `0.1.0`. Install that instead:
-
-```bash
-npx --yes @betterborg/cli
-```
-
-See [betterborg/betterborg-cli](https://github.com/betterborg/betterborg-cli).