bin-home 0.1.0

package/README.md

@@ -0,0 +1,105 @@
+# bin-home
+
+bin-home is a CLI tool that finds which global npm package provides a given
+command. It helps when you know the command name (for example, `codex`) but not
+the package you need to install or manage (for example, `@openai/codex`).
+
+## Installation
+
+```bash
+npm install -g bin-home
+```
+
+## Usage
+
+```bash
+bin-home <command> [--open]
+```
+
+### Examples
+
+```bash
+bin-home codex
+```
+
+Expected output:
+
+```text
+npm: @openai/codex
+npm url: https://www.npmjs.com/package/@openai/codex
+github: https://github.com/openai/codex
+```
+
+Open npm package page automatically:
+
+```bash
+bin-home codex --open
+```
+
+### Options
+
+- `--help`, `-h`: Show help
+- `--version`, `-v`: Show version
+- `--open`, `-o`: Open npm package page in browser
+
+## Publishing
+
+To publish to npm and GitHub:
+
+1. Update `package.json` metadata (name, version, repository, author).
+2. Create a GitHub repository and push the code.
+3. Run `npm publish`.
+
+---
+
+# bin-home（中文）
+
+bin-home 是一个 CLI 工具，用于查找某个命令来自哪个全局 npm 包。它解决了
+“知道命令名但不知道包名”的痛点，比如命令是 `codex`，但包名是
+`@openai/codex`。
+
+## 安装
+
+```bash
+npm install -g bin-home
+```
+
+## 使用方法
+
+```bash
+bin-home <命令名> [--open]
+```
+
+### 示例
+
+```bash
+bin-home codex
+```
+
+预期输出：
+
+```text
+npm: @openai/codex
+npm url: https://www.npmjs.com/package/@openai/codex
+github: https://github.com/openai/codex
+```
+
+自动打开 npm 包页面：
+
+```bash
+bin-home codex --open
+```
+
+### 选项
+
+- `--help`, `-h`: 显示帮助
+- `--version`, `-v`: 显示版本号
+- `--open`, `-o`: 打开 npm 包页面
+
+## 发布说明
+
+发布到 npm 和 GitHub 的步骤：
+
+1. 更新 `package.json` 元数据（name、version、repository、author）。
+2. 创建 GitHub 仓库并推送代码。
+3. 运行 `npm publish`。

package/bin/cli.js

@@ -0,0 +1,82 @@
+#!/usr/bin/env node
+const path = require("path");
+const validateCommand = require("../lib/commandValidator");
+const findPackageForCommand = require("../lib/packageFinder");
+const displayPackageInfo = require("../lib/packageInfoFormatter");
+
+const COMMAND_NOT_FOUND_EXIT_CODE = 1;
+const PACKAGE_NOT_FOUND_EXIT_CODE = 2;
+
+function printHelp() {
+  console.log("Usage: bin-home <command> [--open]");
+  console.log("");
+  console.log("Options:");
+  console.log("  --help, -h     Show help");
+  console.log("  --version, -v  Show version");
+  console.log("  --open, -o     Open npm package page in browser");
+}
+
+function printVersion() {
+  const packageJson = require(path.join(__dirname, "..", "package.json"));
+  console.log(packageJson.version);
+}
+
+function parseArgs(argv) {
+  const flags = new Set();
+  let commandName = null;
+
+  for (const arg of argv) {
+    if (arg.startsWith("-")) {
+      flags.add(arg);
+    } else if (!commandName) {
+      commandName = arg;
+    }
+  }
+
+  return {
+    commandName,
+    help: flags.has("--help") || flags.has("-h"),
+    version: flags.has("--version") || flags.has("-v"),
+    open: flags.has("--open") || flags.has("-o")
+  };
+}
+
+async function run() {
+  const { commandName, help, version, open } = parseArgs(process.argv.slice(2));
+
+  if (version) {
+    printVersion();
+    return;
+  }
+
+  if (help || !commandName) {
+    printHelp();
+    return;
+  }
+
+  const commandExists = await validateCommand(commandName);
+  if (!commandExists) {
+    console.error(`Command '${commandName}' not found in system PATH`);
+    process.exit(COMMAND_NOT_FOUND_EXIT_CODE);
+  }
+
+  const packageInfo = await findPackageForCommand(commandName);
+  if (!packageInfo) {
+    console.error(
+      `No npm package found for command '${commandName}'. It may not be installed via npm.`
+    );
+    process.exit(PACKAGE_NOT_FOUND_EXIT_CODE);
+  }
+
+  await displayPackageInfo(commandName, packageInfo, open);
+}
+
+run().catch((error) => {
+  if (typeof error.exitCode === "number") {
+    console.error(error.message);
+    process.exit(error.exitCode);
+  }
+
+  console.error(`Unexpected error: ${error.message}`);
+  process.exit(1);
+});

package/lib/commandValidator.js

@@ -0,0 +1,16 @@
+const which = require("which");
+
+async function validateCommand(commandName) {
+  if (!commandName || typeof commandName !== "string") {
+    return false;
+  }
+
+  try {
+    await which(commandName);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}
+
+module.exports = validateCommand;

package/lib/index.js

@@ -0,0 +1,6 @@
+module.exports = {
+  validateCommand: require("./commandValidator"),
+  findPackageForCommand: require("./packageFinder"),
+  parseRepository: require("./repositoryParser"),
+  displayPackageInfo: require("./packageInfoFormatter")
+};

package/lib/packageFinder.js

@@ -0,0 +1,236 @@
+const { exec } = require("child_process");
+const which = require("which");
+const fs = require("fs/promises");
+const path = require("path");
+
+const NPM_LIST_EXIT_CODE = 3;
+const PACKAGE_JSON_EXIT_CODE = 4;
+
+function execNpmList() {
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  const command = `${npmCommand} ls -g --depth=0 --json`;
+  return new Promise((resolve, reject) => {
+    exec(
+      command,
+      { maxBuffer: 10 * 1024 * 1024, windowsHide: true },
+      (error, stdout) => {
+        if (error) {
+          const err = new Error(
+            `Failed to list global npm packages: ${error.message}`
+          );
+          err.exitCode = NPM_LIST_EXIT_CODE;
+          return reject(err);
+        }
+        resolve(stdout);
+      }
+    );
+  });
+}
+
+function execNpmRoot() {
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  const command = `${npmCommand} root -g`;
+  return new Promise((resolve, reject) => {
+    exec(command, { windowsHide: true }, (error, stdout) => {
+      if (error) {
+        const err = new Error(
+          `Failed to list global npm packages: ${error.message}`
+        );
+        err.exitCode = NPM_LIST_EXIT_CODE;
+        return reject(err);
+      }
+      resolve(stdout.trim());
+    });
+  });
+}
+
+function getCommandNamesForStringBin(packageName) {
+  const names = new Set();
+  if (packageName) {
+    names.add(packageName);
+    if (packageName.startsWith("@")) {
+      const parts = packageName.split("/");
+      if (parts[1]) {
+        names.add(parts[1]);
+      }
+    }
+  }
+  return names;
+}
+
+async function readPackageJson(packagePath, packageName) {
+  const packageJsonPath = path.join(packagePath, "package.json");
+  try {
+    const contents = await fs.readFile(packageJsonPath, "utf8");
+    return JSON.parse(contents);
+  } catch (error) {
+    const err = new Error(
+      `Failed to read package.json for ${packageName}: ${error.message}`
+    );
+    err.exitCode = PACKAGE_JSON_EXIT_CODE;
+    throw err;
+  }
+}
+
+async function listGlobalPackages(nodeModulesRoot) {
+  try {
+    const entries = await fs.readdir(nodeModulesRoot, { withFileTypes: true });
+    const packages = [];
+
+    for (const entry of entries) {
+      if (!entry.isDirectory()) {
+        continue;
+      }
+
+      if (entry.name.startsWith("@")) {
+        const scopePath = path.join(nodeModulesRoot, entry.name);
+        const scopedEntries = await fs.readdir(scopePath, {
+          withFileTypes: true
+        });
+        for (const scopedEntry of scopedEntries) {
+          if (!scopedEntry.isDirectory()) {
+            continue;
+          }
+          packages.push({
+            name: `${entry.name}/${scopedEntry.name}`,
+            path: path.join(scopePath, scopedEntry.name)
+          });
+        }
+      } else {
+        packages.push({
+          name: entry.name,
+          path: path.join(nodeModulesRoot, entry.name)
+        });
+      }
+    }
+
+    return packages;
+  } catch (error) {
+    const err = new Error(
+      `Failed to read package.json for global packages: ${error.message}`
+    );
+    err.exitCode = PACKAGE_JSON_EXIT_CODE;
+    throw err;
+  }
+}
+
+async function resolveVoltaPackage(commandName) {
+  try {
+    await which("volta");
+  } catch (error) {
+    return null;
+  }
+
+  const command = `volta which ${commandName}`;
+  const voltaPath = await new Promise((resolve, reject) => {
+    exec(command, { windowsHide: true }, (error, stdout) => {
+      if (error) {
+        return reject(error);
+      }
+      resolve(stdout.trim());
+    });
+  }).catch(() => null);
+
+  if (!voltaPath) {
+    return null;
+  }
+
+  const parts = path.normalize(voltaPath).split(path.sep);
+  const packagesIndex = parts.lastIndexOf("packages");
+  if (packagesIndex === -1 || !parts[packagesIndex + 1]) {
+    return null;
+  }
+
+  const packageName = parts[packagesIndex + 1];
+  const packagePath = path.join(
+    ...parts.slice(0, packagesIndex + 2),
+    "node_modules",
+    packageName
+  );
+
+  const packageJson = await readPackageJson(packagePath, packageName);
+  return { packageName, packagePath, packageJson };
+}
+
+async function findPackageForCommand(commandName) {
+  const [output, npmRoot] = await Promise.all([
+    execNpmList(),
+    execNpmRoot()
+  ]);
+
+  let parsed;
+  try {
+    parsed = JSON.parse(output);
+  } catch (error) {
+    const err = new Error(
+      `Failed to list global npm packages: ${error.message}`
+    );
+    err.exitCode = NPM_LIST_EXIT_CODE;
+    throw err;
+  }
+
+  const dependencies = parsed.dependencies || {};
+  const nodeModulesRoot = npmRoot || "";
+  const checked = new Set();
+
+  for (const packageName of Object.keys(dependencies)) {
+    const packagePath = path.join(nodeModulesRoot, packageName);
+    checked.add(packageName);
+    const packageJson = await readPackageJson(packagePath, packageName);
+    const bin = packageJson.bin;
+
+    if (typeof bin === "string") {
+      const candidateNames = getCommandNamesForStringBin(
+        packageJson.name || packageName
+      );
+      if (candidateNames.has(commandName)) {
+        return { packageName, packagePath, packageJson };
+      }
+    } else if (bin && typeof bin === "object") {
+      if (Object.prototype.hasOwnProperty.call(bin, commandName)) {
+        return { packageName, packagePath, packageJson };
+      }
+    }
+  }
+
+  if (nodeModulesRoot) {
+    const packages = await listGlobalPackages(nodeModulesRoot);
+    for (const pkg of packages) {
+      if (checked.has(pkg.name)) {
+        continue;
+      }
+      const packageJson = await readPackageJson(pkg.path, pkg.name);
+      const bin = packageJson.bin;
+
+      if (typeof bin === "string") {
+        const candidateNames = getCommandNamesForStringBin(
+          packageJson.name || pkg.name
+        );
+        if (candidateNames.has(commandName)) {
+          return {
+            packageName: pkg.name,
+            packagePath: pkg.path,
+            packageJson
+          };
+        }
+      } else if (bin && typeof bin === "object") {
+        if (Object.prototype.hasOwnProperty.call(bin, commandName)) {
+          return {
+            packageName: pkg.name,
+            packagePath: pkg.path,
+            packageJson
+          };
+        }
+      }
+    }
+  }
+
+  const voltaPackage = await resolveVoltaPackage(commandName);
+  if (voltaPackage) {
+    return voltaPackage;
+  }
+
+  return null;
+}
+
+module.exports = findPackageForCommand;

package/lib/packageInfoFormatter.js

@@ -0,0 +1,35 @@
+const parseRepository = require("./repositoryParser");
+
+async function resolveOpen() {
+  const mod = await import("open");
+  return mod.default || mod;
+}
+
+async function displayPackageInfo(
+  commandName,
+  packageInfo,
+  shouldOpen = false,
+  openImpl
+) {
+  const packageName = packageInfo.packageName;
+  const npmUrl = `https://www.npmjs.com/package/${packageName}`;
+  const repoUrl = parseRepository(packageInfo.packageJson.repository);
+
+  console.log(`npm: ${packageName}`);
+  console.log(`npm url: ${npmUrl}`);
+  console.log(`github: ${repoUrl || "unavailable"}`);
+
+  if (shouldOpen) {
+    try {
+      const openFn = openImpl || (await resolveOpen());
+      if (typeof openFn !== "function") {
+        throw new Error("open is not a function");
+      }
+      await openFn(npmUrl);
+    } catch (error) {
+      console.error(`Failed to open URL in browser: ${error.message}`);
+    }
+  }
+}
+
+module.exports = displayPackageInfo;

package/lib/repositoryParser.js

@@ -0,0 +1,56 @@
+function normalizeGitHubUrl(repo) {
+  if (!repo || typeof repo !== "string") {
+    return null;
+  }
+
+  const trimmed = repo.trim();
+  if (!trimmed) {
+    return null;
+  }
+
+  let candidate = trimmed;
+
+  if (candidate.startsWith("git+")) {
+    candidate = candidate.slice(4);
+  }
+
+  if (candidate.startsWith("github:")) {
+    candidate = candidate.slice("github:".length);
+  } else if (
+    !candidate.startsWith("http://") &&
+    !candidate.startsWith("https://") &&
+    /^[a-z]+:/i.test(candidate)
+  ) {
+    return null;
+  }
+
+  const githubMatch =
+    candidate.match(/github\.com[:/]+([^/]+)\/([^/]+?)(?:\.git)?$/i) ||
+    candidate.match(/^([^/]+)\/([^/]+)$/);
+
+  if (!githubMatch) {
+    return null;
+  }
+
+  const owner = githubMatch[1];
+  const repoName = githubMatch[2].replace(/\.git$/, "");
+  return `https://github.com/${owner}/${repoName}`;
+}
+
+function parseRepository(repository) {
+  if (!repository) {
+    return null;
+  }
+
+  if (typeof repository === "string") {
+    return normalizeGitHubUrl(repository);
+  }
+
+  if (typeof repository === "object" && typeof repository.url === "string") {
+    return normalizeGitHubUrl(repository.url);
+  }
+
+  return null;
+}
+
+module.exports = parseRepository;

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "bin-home",
+  "version": "0.1.0",
+  "description": "Find which global npm package provides a CLI command",
+  "author": "bin-home",
+  "license": "MIT",
+  "bin": {
+    "bin-home": "bin/cli.js"
+  },
+  "main": "lib/index.js",
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yourname/bin-home.git"
+  },
+  "keywords": [
+    "cli",
+    "npm",
+    "bin",
+    "package",
+    "finder"
+  ],
+  "engines": {
+    "node": ">=14.0.0"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "README.md"
+  ],
+  "dependencies": {
+    "open": "^9.1.0",
+    "which": "^4.0.0"
+  }
+}