@general-liquidity/gordon-cli 0.8.21 → 0.8.24

package/README.md

@@ -19,12 +19,34 @@
 npm install -g @general-liquidity/gordon-cli
 ```
 
+If global npm install fails with `EACCES` / permission errors on Linux or macOS, use the user-local npm path instead:
+
+```bash
+npx @general-liquidity/gordon-cli@latest install
+```
+
+That installs Gordon into a user-writable bin directory without `sudo`.
+
 `bun`:
 
 ```bash
 bun add -g @general-liquidity/gordon-cli
 ```
 
+`Homebrew`:
+
+```bash
+brew tap general-liquidity/gordon-cli-dist https://github.com/general-liquidity/gordon-cli-dist
+brew install general-liquidity/gordon-cli-dist/gordon
+```
+
+`Scoop`:
+
+```powershell
+scoop bucket add gordon https://github.com/general-liquidity/gordon-cli-dist
+scoop install gordon/gordon
+```
+
 Standalone install script:
 
 ```bash
@@ -39,6 +61,26 @@ irm https://raw.githubusercontent.com/general-liquidity/gordon-cli-dist/main/ins
 
 The npm package is a thin wrapper. It downloads the matching prebuilt binary for your platform during install.
 
+## npm Permission Fallback
+
+Global `npm install -g` can fail on Unix machines when the npm global prefix is root-owned. Gordon now supports a universal npm fallback:
+
+```bash
+npx @general-liquidity/gordon-cli@latest install
+```
+
+If the chosen install directory is not already on `PATH`, Gordon prints the exact command to add it.
+
+## Upgrades
+
+Once installed, Gordon can upgrade itself with:
+
+```bash
+gordon --upgrade
+```
+
+That now resolves through the active install channel for npm, the user-local `npx` installer, Homebrew, Scoop, and the standalone install scripts.
+
 ## Supported binaries
 
 - macOS arm64

package/bin/gordon.cjs

@@ -4,8 +4,21 @@ const fs = require("fs");
 const path = require("path");
 const { spawn } = require("child_process");
 const { getInstalledBinaryPath } = require("../lib/platform.cjs");
+const { runSelfInstall } = require("../lib/self-install.cjs");
 
 const packageRoot = path.resolve(__dirname, "..");
+const args = process.argv.slice(2);
+
+if (args[0] === "install") {
+  runSelfInstall(args.slice(1), { packageRoot }).then(
+    (code) => process.exit(code || 0),
+    (error) => {
+      console.error(`[gordon] ${error.message}`);
+      process.exit(1);
+    }
+  );
+  return;
+}
 
 let binaryPath;
 try {
@@ -17,12 +30,12 @@ try {
 
 if (!fs.existsSync(binaryPath)) {
   console.error(
-    "[gordon] The Gordon binary is missing. Reinstall with `npm install -g @general-liquidity/gordon-cli`."
+    "[gordon] The Gordon binary is missing. Reinstall with `npm install -g @general-liquidity/gordon-cli` or run `npx @general-liquidity/gordon-cli@latest install` for a user-local install."
   );
   process.exit(1);
 }
 
-const child = spawn(binaryPath, process.argv.slice(2), { stdio: "inherit" });
+const child = spawn(binaryPath, args, { stdio: "inherit" });
 
 child.on("error", (error) => {
   console.error(`[gordon] Failed to launch ${path.basename(binaryPath)}: ${error.message}`);

package/lib/self-install.cjs

@@ -0,0 +1,343 @@
+const fs = require("fs");
+const os = require("os");
+const path = require("path");
+const https = require("https");
+const { pipeline } = require("stream/promises");
+const { getDownloadUrl, getInstalledBinaryPath, getTarget } = require("./platform.cjs");
+const pkg = require("../package.json");
+const INSTALL_METADATA_FILENAME = "gordon-install.json";
+
+function log(message) {
+  console.log(`[gordon] ${message}`);
+}
+
+function parseArgs(args) {
+  const options = {
+    help: false,
+    targetDir: null
+  };
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (arg === "--help" || arg === "-h") {
+      options.help = true;
+      continue;
+    }
+
+    if ((arg === "--target-dir" || arg === "--dir") && args[index + 1]) {
+      options.targetDir = path.resolve(args[index + 1]);
+      index += 1;
+      continue;
+    }
+
+    throw new Error(`Unknown install option: ${arg}`);
+  }
+
+  return options;
+}
+
+function printHelp() {
+  console.log(`gordon install
+
+Install Gordon into a user-writable bin directory without requiring \`npm install -g\`.
+
+Usage:
+  npx @general-liquidity/gordon-cli@latest install
+  gordon install --target-dir <directory>
+
+Options:
+  --target-dir <dir>   Override the install directory
+  -h, --help           Show this help
+`);
+}
+
+function normalizeForCompare(value) {
+  const resolved = path.resolve(value);
+  return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+}
+
+function splitPathEntries(envPath = process.env.PATH || "") {
+  return envPath.split(path.delimiter).filter(Boolean);
+}
+
+function pathContainsDirectory(directory, env = process.env) {
+  const target = normalizeForCompare(directory);
+  return splitPathEntries(env.PATH).some((entry) => {
+    try {
+      return normalizeForCompare(entry) === target;
+    } catch {
+      return false;
+    }
+  });
+}
+
+function uniqueDirectories(values) {
+  const seen = new Set();
+  const result = [];
+  for (const value of values) {
+    if (!value) {
+      continue;
+    }
+
+    const normalized = normalizeForCompare(value);
+    if (seen.has(normalized)) {
+      continue;
+    }
+
+    seen.add(normalized);
+    result.push(path.resolve(value));
+  }
+  return result;
+}
+
+async function isWritableDirectory(directory, { create } = { create: false }) {
+  try {
+    if (create) {
+      await fs.promises.mkdir(directory, { recursive: true });
+    } else {
+      const stats = await fs.promises.stat(directory);
+      if (!stats.isDirectory()) {
+        return false;
+      }
+    }
+
+    const probePath = path.join(directory, `.gordon-write-test-${process.pid}-${Date.now()}`);
+    await fs.promises.writeFile(probePath, "");
+    await fs.promises.rm(probePath, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function resolveInstallDirectory(explicitTargetDir = null, env = process.env) {
+  if (explicitTargetDir) {
+    return {
+      directory: explicitTargetDir,
+      inPath: pathContainsDirectory(explicitTargetDir, env)
+    };
+  }
+
+  const homeDirectory = os.homedir();
+  const pathEntries = splitPathEntries(env.PATH);
+  const standardCandidates = [];
+  const pathCandidates = [];
+
+  if (process.platform === "win32") {
+    if (env.APPDATA) {
+      standardCandidates.push(path.join(env.APPDATA, "npm"));
+    }
+    if (env.LOCALAPPDATA) {
+      standardCandidates.push(path.join(env.LOCALAPPDATA, "Microsoft", "WinGet", "Links"));
+      standardCandidates.push(path.join(env.LOCALAPPDATA, "gordon"));
+    }
+
+    for (const entry of pathEntries) {
+      const resolvedEntry = path.resolve(entry);
+      const normalizedEntry = normalizeForCompare(resolvedEntry);
+      const userRoots = uniqueDirectories([
+        env.USERPROFILE,
+        env.LOCALAPPDATA,
+        env.APPDATA,
+        homeDirectory
+      ]);
+      const withinUserRoot = userRoots.some((root) => {
+        const normalizedRoot = normalizeForCompare(root);
+        return normalizedEntry === normalizedRoot || normalizedEntry.startsWith(`${normalizedRoot}${path.sep}`);
+      });
+      if (
+        withinUserRoot
+        && !normalizedEntry.includes(`${path.sep}node_modules${path.sep}`)
+      ) {
+        pathCandidates.push(resolvedEntry);
+      }
+    }
+  } else {
+    standardCandidates.push(path.join(homeDirectory, ".local", "bin"));
+    standardCandidates.push(path.join(homeDirectory, "bin"));
+
+    for (const entry of pathEntries) {
+      const resolvedEntry = path.resolve(entry);
+      const normalizedEntry = normalizeForCompare(resolvedEntry);
+      const normalizedHome = `${normalizeForCompare(homeDirectory)}${path.sep}`;
+      if (
+        normalizedEntry.startsWith(normalizedHome)
+        && !normalizedEntry.includes(`${path.sep}node_modules${path.sep}`)
+      ) {
+        pathCandidates.push(resolvedEntry);
+      }
+    }
+  }
+
+  const orderedCandidates = uniqueDirectories([
+    ...standardCandidates.filter((candidate) => pathContainsDirectory(candidate, env)),
+    ...pathCandidates,
+    ...standardCandidates
+  ]);
+
+  for (const candidate of orderedCandidates) {
+    const create = standardCandidates.some((standardCandidate) => normalizeForCompare(standardCandidate) === normalizeForCompare(candidate));
+    if (await isWritableDirectory(candidate, { create })) {
+      return {
+        directory: candidate,
+        inPath: pathContainsDirectory(candidate, env)
+      };
+    }
+  }
+
+  throw new Error("Could not find a writable user install directory.");
+}
+
+async function downloadBinary(url, destinationPath, redirectCount = 0) {
+  if (redirectCount > 5) {
+    throw new Error(`Too many redirects while downloading ${url}`);
+  }
+
+  await new Promise((resolve, reject) => {
+    const request = https.get(
+      url,
+      { headers: { "User-Agent": "gordon-npm-installer" } },
+      async (response) => {
+        if (
+          response.statusCode &&
+          response.statusCode >= 300 &&
+          response.statusCode < 400 &&
+          response.headers.location
+        ) {
+          response.resume();
+          try {
+            await downloadBinary(response.headers.location, destinationPath, redirectCount + 1);
+            resolve();
+          } catch (error) {
+            reject(error);
+          }
+          return;
+        }
+
+        if (response.statusCode !== 200) {
+          response.resume();
+          reject(new Error(`Download failed with status ${response.statusCode} for ${url}`));
+          return;
+        }
+
+        const fileStream = fs.createWriteStream(destinationPath);
+        pipeline(response, fileStream).then(resolve, reject);
+      }
+    );
+
+    request.on("error", reject);
+  });
+}
+
+async function finalizeBinary(tempPath, targetPath) {
+  if (process.platform !== "win32") {
+    await fs.promises.chmod(tempPath, 0o755);
+  }
+
+  await fs.promises.rm(targetPath, { force: true });
+  await fs.promises.rename(tempPath, targetPath);
+}
+
+async function writeInstallMetadata(targetDirectory, version, channel) {
+  const metadataPath = path.join(targetDirectory, INSTALL_METADATA_FILENAME);
+  const payload = {
+    channel,
+    installDir: targetDirectory,
+    version,
+    installedAt: new Date().toISOString()
+  };
+  await fs.promises.writeFile(metadataPath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+
+function getUnixPathHint(directory, env = process.env) {
+  const shell = env.SHELL || "";
+  if (shell.includes("fish")) {
+    return {
+      profile: "~/.config/fish/config.fish",
+      command: `fish_add_path ${directory.replace(os.homedir(), "$HOME")}`
+    };
+  }
+
+  if (shell.includes("zsh")) {
+    return {
+      profile: "~/.zshrc",
+      command: `echo 'export PATH=\"${directory.replace(os.homedir(), "$HOME")}:$PATH\"' >> ~/.zshrc`
+    };
+  }
+
+  return {
+    profile: "~/.bashrc",
+    command: `echo 'export PATH=\"${directory.replace(os.homedir(), "$HOME")}:$PATH\"' >> ~/.bashrc`
+  };
+}
+
+function printPathGuidance(directory) {
+  if (process.platform === "win32") {
+    log(`Add ${directory} to your user PATH, then open a new terminal.`);
+    return;
+  }
+
+  const hint = getUnixPathHint(directory);
+  log(`Add ${directory} to PATH if your shell cannot find \`gordon\` yet.`);
+  console.log(`      ${hint.command}`);
+  console.log(`      # then restart your shell or source ${hint.profile}`);
+}
+
+async function installBinary({ targetDirectory, sourceBinaryPath, version }) {
+  const { binaryName, assetName } = getTarget();
+  await fs.promises.mkdir(targetDirectory, { recursive: true });
+
+  const installPath = path.join(targetDirectory, binaryName);
+  const tempPath = `${installPath}.tmp`;
+  await fs.promises.rm(tempPath, { force: true });
+
+  if (sourceBinaryPath && fs.existsSync(sourceBinaryPath)) {
+    log(`Copying ${path.basename(sourceBinaryPath)} to ${installPath}`);
+    await fs.promises.copyFile(sourceBinaryPath, tempPath);
+  } else {
+    const downloadUrl = getDownloadUrl(version);
+    log(`Downloading ${assetName} from ${downloadUrl}`);
+    await downloadBinary(downloadUrl, tempPath);
+  }
+
+  await finalizeBinary(tempPath, installPath);
+  return installPath;
+}
+
+async function runSelfInstall(args, options = {}) {
+  const parsed = parseArgs(args);
+  if (parsed.help) {
+    printHelp();
+    return 0;
+  }
+
+  const packageRoot = options.packageRoot || path.resolve(__dirname, "..");
+  const version = String(options.version || pkg.version).replace(/^v/, "");
+  const bundledBinaryPath = options.sourceBinaryPath || getInstalledBinaryPath(packageRoot);
+  const sourceBinaryPath = fs.existsSync(bundledBinaryPath) ? bundledBinaryPath : null;
+  const { directory, inPath } = await resolveInstallDirectory(parsed.targetDir);
+  const installPath = await installBinary({
+    targetDirectory: directory,
+    sourceBinaryPath,
+    version
+  });
+  await writeInstallMetadata(directory, version, options.channel || "npx");
+
+  console.log("");
+  log(`Installed Gordon v${version} to ${installPath}`);
+  if (!inPath) {
+    printPathGuidance(directory);
+  }
+  console.log("");
+  console.log("Next steps:");
+  console.log("  gordon --help");
+  console.log("  gordon");
+
+  return 0;
+}
+
+module.exports = {
+  parseArgs,
+  resolveInstallDirectory,
+  runSelfInstall
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@general-liquidity/gordon-cli",
-  "version": "0.8.21",
+  "version": "0.8.24",
   "description": "The Frontier Trading Agent",
   "author": "General Liquidity, Inc.",
   "license": "MIT",