node-version-bridge 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Marcos Reuquen
+
+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/README.md

@@ -0,0 +1,173 @@
+# node-version-bridge
+
+Automatically detects the Node.js version declared in your project and applies it using your preferred version manager.
+
+## Problem
+
+Many Node projects already have files like `.nvmrc` or `.node-version`, but if you use a different version manager than the rest of your team (asdf, nvm, fnm, mise, n), you end up maintaining duplicate files or running manual commands every time you switch projects.
+
+## Solution
+
+`nvb` reads the version files that already exist in your project and automatically applies the correct Node version when you enter the directory — regardless of which version manager you use.
+
+## Supported managers
+
+- **nvm** — `nvm use <version>`
+- **fnm** — `fnm use <version>`
+- **mise** — `mise shell node@<version>`
+- **asdf** — `export ASDF_NODEJS_VERSION=<version>`
+- **n** — `n <version>`
+
+## Detected version files
+
+By default, in this priority order:
+
+1. `.nvmrc`
+2. `.node-version`
+3. `.tool-versions`
+4. `package.json` (`engines.node`)
+
+Aliases like `lts/*`, `lts/iron`, `node`, `stable`, and `latest` are automatically resolved to concrete versions via the nodejs.org API.
+
+## Installation
+
+### Quick install (recommended)
+
+```bash
+git clone https://github.com/marcosreuquen/node-version-bridge.git
+cd node-version-bridge
+bash install.sh
+```
+
+The script will:
+1. Copy `nvb` to `~/.local/share/nvb/`
+2. Automatically add the shell hook to your `.zshrc` or `.bashrc`
+
+Then restart your shell or run `source ~/.zshrc` (or `~/.bashrc`).
+
+### Manual install
+
+If you prefer full control over the installation:
+
+```bash
+git clone https://github.com/marcosreuquen/node-version-bridge.git
+```
+
+Then add the hook to your shell config:
+
+**Zsh** — add to `~/.zshrc`:
+
+```bash
+source /path/to/node-version-bridge/hooks/nvb.zsh
+```
+
+**Bash** — add to `~/.bashrc`:
+
+```bash
+source /path/to/node-version-bridge/hooks/nvb.bash
+```
+
+### Verify installation
+
+```bash
+nvb doctor
+```
+
+## Uninstall
+
+### With the script
+
+From the repository directory:
+
+```bash
+bash uninstall.sh
+```
+
+This removes installed files, the shell hook from your config, and the cache.
+
+### Manual
+
+1. Remove the `source ...nvb.zsh` (or `nvb.bash`) line from your `.zshrc`/`.bashrc`
+2. Delete the install directory: `rm -rf ~/.local/share/nvb`
+3. Optional — delete the cache: `rm -rf ~/.cache/node-version-bridge`
+
+## Usage
+
+```bash
+# Show resolved version vs active version
+nvb current
+
+# Full diagnostics
+nvb doctor
+
+# Manage configuration
+nvb config list
+nvb config set NVB_AUTO_INSTALL true
+
+# Show help
+nvb help
+```
+
+## Configuration
+
+Configuration can be set via environment variables or a config file at `~/.config/nvb/config` (or `$XDG_CONFIG_HOME/nvb/config`). Environment variables always take precedence over the config file.
+
+### Config file
+
+Create `~/.config/nvb/config` (or use `nvb config set`):
+
+```ini
+NVB_MANAGER=fnm
+NVB_LOG_LEVEL=info
+NVB_AUTO_INSTALL=true
+```
+
+### Manage config from the CLI
+
+```bash
+nvb config list                          # Show all config values and sources
+nvb config set NVB_AUTO_INSTALL true     # Enable auto-install
+nvb config set NVB_MANAGER fnm           # Force fnm
+nvb config get NVB_LOG_LEVEL             # Read a value
+nvb config unset NVB_MANAGER             # Remove a key
+nvb config path                          # Show config file path
+```
+
+### Environment variables
+
+| Variable | Description | Default |
+|---|---|---|
+| `NVB_MANAGER` | Force a specific version manager | auto-detect |
+| `NVB_LOG_LEVEL` | Log level: error, warn, info, debug | `error` |
+| `NVB_PRIORITY` | File priority (comma-separated) | `.nvmrc,.node-version,.tool-versions,package.json` |
+| `NVB_CACHE_DIR` | Cache directory | `$XDG_CACHE_HOME/node-version-bridge` |
+| `NVB_AUTO_INSTALL` | Auto-install missing Node versions: true/false | `false` |
+| `NVB_ALIAS_CACHE_TTL` | Alias cache TTL in seconds | `3600` |
+
+## Tests
+
+```bash
+bash test/run.sh
+```
+
+## Expected outcome
+
+- Less daily friction when switching between projects.
+- No need to commit manager-specific files when `.nvmrc`/`.node-version` already exists.
+- Works with any popular Node version manager.
+
+---
+
+## Documentation
+
+- [Product concept](./docs/concept.md)
+- [Technical design](./docs/technical-design.md)
+- [Roadmap](./docs/roadmap.md)
+- [Implementation plan](./docs/implementation-plan.md)
+- [Changelog](./CHANGELOG.md)
+
+## Status
+
+v0.5.0 — partial version resolution for asdf/mise, config file support, and auto-install. See [Changelog](./CHANGELOG.md).
+
+**[Full Documentation](https://marcosreuquen.github.io/node-version-bridge/)**

package/bin/nvb

@@ -0,0 +1,290 @@
+#!/usr/bin/env bash
+# node-version-bridge — CLI entrypoint
+# Detects Node.js version from project files and generates commands
+# to apply it via the user's preferred version manager.
+
+set -euo pipefail
+
+NVB_VERSION="0.5.0"
+
+# Resolve script location (handles symlinks on macOS/Linux)
+_nvb_resolve_root() {
+  local source="${BASH_SOURCE[0]}"
+  while [[ -L "$source" ]]; do
+    local dir
+    dir="$(cd -P "$(dirname "$source")" && pwd)"
+    source="$(readlink "$source")"
+    [[ "$source" != /* ]] && source="${dir}/${source}"
+  done
+  cd -P "$(dirname "$source")/.." && pwd
+}
+NVB_ROOT="$(_nvb_resolve_root)"
+
+# Source libraries
+source "${NVB_ROOT}/lib/log.sh"
+source "${NVB_ROOT}/lib/config.sh"
+source "${NVB_ROOT}/lib/detect.sh"
+source "${NVB_ROOT}/lib/alias.sh"
+source "${NVB_ROOT}/lib/parse.sh"
+source "${NVB_ROOT}/lib/resolve.sh"
+source "${NVB_ROOT}/lib/cache.sh"
+source "${NVB_ROOT}/lib/manager.sh"
+
+# Load configuration file (env vars take precedence)
+nvb_config_load
+
+# --- Commands ---
+
+nvb_cmd_refresh() {
+  # shellcheck disable=SC2119
+  nvb_resolve_version || true
+  local resolved_version="${NVB_RESOLVED_VERSION:-}"
+  local resolved_source="${NVB_RESOLVED_SOURCE:-}"
+
+  if [[ -z "$resolved_version" ]]; then
+    nvb_log debug "No version file found, nothing to do"
+    return 0
+  fi
+
+  # Check cache — skip if nothing changed
+  if nvb_cache_is_current "$PWD" "$resolved_version" "$resolved_source"; then
+    nvb_log debug "Cache hit: ${resolved_version} from ${resolved_source}"
+    return 0
+  fi
+
+  local manager
+  manager="$(nvb_detect_manager)" || {
+    echo "echo '[nvb] No supported version manager found.' >&2"
+    echo "echo '[nvb] Install one of: nvm, fnm, mise, asdf, n' >&2"
+    echo "echo '[nvb] See: https://github.com/marcosreuquen/node-version-bridge#supported-managers' >&2"
+    return 1
+  }
+
+  nvb_log info "Switching to Node ${resolved_version} (from ${resolved_source}) via ${manager}"
+
+  # Resolve partial version (e.g. "18" → "18.20.8") for managers that need exact versions
+  local apply_version
+  apply_version="$(nvb_resolve_installed_version "$manager" "$resolved_version")"
+
+  # Auto-install if enabled
+  local auto_install
+  auto_install="$(nvb_config_get NVB_AUTO_INSTALL false)"
+  if [[ "$auto_install" == "true" ]]; then
+    # If version couldn't be resolved to installed, install it first
+    if [[ "$apply_version" == "$resolved_version" ]] && ! _nvb_is_full_version "$resolved_version"; then
+      nvb_log debug "Auto-install enabled, no installed match for partial version ${resolved_version}"
+      nvb_adapter_install_cmd "$manager" "$resolved_version"
+      # Re-resolve after install (next hook trigger will pick it up if eval'd install succeeds)
+      apply_version="$(nvb_resolve_installed_version "$manager" "$resolved_version")"
+    else
+      nvb_log debug "Auto-install enabled, emitting install command"
+      nvb_adapter_install_cmd "$manager" "$apply_version"
+    fi
+  fi
+
+  # Output eval-able command for the shell hook
+  nvb_adapter_apply_cmd "$manager" "$apply_version"
+
+  # Update cache
+  nvb_cache_update "$PWD" "$resolved_version" "$resolved_source"
+}
+
+nvb_cmd_current() {
+  # shellcheck disable=SC2119
+  nvb_resolve_version || true
+  local resolved_version="${NVB_RESOLVED_VERSION:-}"
+  local resolved_source="${NVB_RESOLVED_SOURCE:-}"
+
+  local active_version
+  active_version="$(node --version 2>/dev/null | sed 's/^v//')" || active_version="(not found)"
+
+  local manager
+  manager="$(nvb_detect_manager 2>/dev/null)" || manager="(none detected)"
+
+  # Resolve partial version to show what would actually be applied
+  local apply_version="${resolved_version}"
+  if [[ -n "$resolved_version" && "$manager" != "(none detected)" ]]; then
+    apply_version="$(nvb_resolve_installed_version "$manager" "$resolved_version" 2>/dev/null)" || apply_version="$resolved_version"
+  fi
+
+  echo "node-version-bridge v${NVB_VERSION}"
+  echo ""
+  echo "  Active Node:    ${active_version}"
+  if [[ -n "$resolved_version" && "$apply_version" != "$resolved_version" ]]; then
+    echo "  Resolved:       ${resolved_version} → ${apply_version}"
+  else
+    echo "  Resolved:       ${resolved_version:-(none)}"
+  fi
+  echo "  Source:         ${resolved_source:-(none)}"
+  echo "  Manager:        ${manager}"
+}
+
+nvb_cmd_doctor() {
+  echo "node-version-bridge v${NVB_VERSION} — diagnostics"
+  echo ""
+
+  # Check version managers
+  echo "Version managers:"
+  local managers=("nvm" "fnm" "mise" "asdf" "n")
+  local active_manager
+  active_manager="$(nvb_detect_manager 2>/dev/null)" || active_manager=""
+
+  for m in "${managers[@]}"; do
+    if nvb_adapter_available "$m"; then
+      if [[ "$m" == "$active_manager" ]]; then
+        echo "  ● ${m} (active)"
+      else
+        echo "  ✓ ${m}"
+      fi
+    else
+      echo "  ✗ ${m}"
+    fi
+  done
+
+  echo ""
+
+  # Check version files
+  echo "Version files (from $PWD):"
+  local priority_str="${NVB_PRIORITY:-.nvmrc,.node-version,.tool-versions,package.json}"
+  IFS=',' read -ra priorities <<< "$priority_str"
+
+  for f in "${priorities[@]}"; do
+    f="$(echo "$f" | xargs)"
+    local found
+    found="$(nvb_detect_file "$f" 2>/dev/null)" || found=""
+    if [[ -n "$found" ]]; then
+      local ver
+      ver="$(nvb_parse_file "$f" "$found" 2>/dev/null)" || ver="(parse error)"
+      echo "  ✓ ${found} → ${ver}"
+    else
+      echo "  ✗ ${f} (not found)"
+    fi
+  done
+
+  echo ""
+
+  # Configuration
+  echo "Configuration:"
+  echo "  NVB_MANAGER:         ${NVB_MANAGER:-(auto-detect)}"
+  echo "  NVB_LOG_LEVEL:       ${NVB_LOG_LEVEL:-error}"
+  echo "  NVB_PRIORITY:        ${NVB_PRIORITY:-.nvmrc,.node-version,.tool-versions,package.json}"
+  echo "  NVB_CACHE_DIR:       ${NVB_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/node-version-bridge}"
+  echo "  NVB_AUTO_INSTALL:    $(nvb_config_get NVB_AUTO_INSTALL false)"
+  echo "  NVB_ALIAS_CACHE_TTL: ${NVB_ALIAS_CACHE_TTL:-3600}"
+  echo "  Config file:         $(nvb_config_file)"
+
+  echo ""
+  local node_ver
+  node_ver="$(node --version 2>/dev/null)" || node_ver="(not found)"
+  echo "Active Node: ${node_ver}"
+}
+
+nvb_cmd_config() {
+  local subcmd="${1:-list}"
+  shift 2>/dev/null || true
+
+  case "$subcmd" in
+    list|ls)
+      nvb_config_list
+      ;;
+    get)
+      local key="${1:-}"
+      if [[ -z "$key" ]]; then
+        echo "Usage: nvb config get <KEY>" >&2
+        return 1
+      fi
+      nvb_config_get "$key"
+      ;;
+    set)
+      local key="${1:-}"
+      local value="${2:-}"
+      if [[ -z "$key" || -z "$value" ]]; then
+        echo "Usage: nvb config set <KEY> <VALUE>" >&2
+        return 1
+      fi
+      nvb_config_set "$key" "$value"
+      echo "Set ${key}=${value} in $(nvb_config_file)"
+      ;;
+    unset)
+      local key="${1:-}"
+      if [[ -z "$key" ]]; then
+        echo "Usage: nvb config unset <KEY>" >&2
+        return 1
+      fi
+      nvb_config_unset "$key"
+      echo "Removed ${key} from $(nvb_config_file)"
+      ;;
+    path)
+      nvb_config_file
+      ;;
+    *)
+      echo "Usage: nvb config <list|get|set|unset|path>" >&2
+      echo "" >&2
+      echo "  list          Show all config values and their sources" >&2
+      echo "  get <KEY>     Get a config value" >&2
+      echo "  set <KEY> <VALUE>  Set a config value" >&2
+      echo "  unset <KEY>   Remove a config value" >&2
+      echo "  path          Show config file path" >&2
+      return 1
+      ;;
+  esac
+}
+
+nvb_cmd_help() {
+  cat <<EOF
+node-version-bridge v${NVB_VERSION}
+
+Automatically applies the Node.js version declared in your project
+using your preferred version manager.
+
+Usage: nvb <command> [options]
+
+Commands:
+  refresh     Detect version and output shell commands to apply it (for eval)
+  current     Show resolved version, source, and active Node version
+  doctor      Check available managers and configuration
+  config      Manage configuration (list, get, set, unset, path)
+  version     Show nvb version
+  help        Show this help
+
+Config examples:
+  nvb config list                          Show all configuration
+  nvb config set NVB_AUTO_INSTALL true     Enable auto-install
+  nvb config set NVB_MANAGER fnm           Force fnm as manager
+  nvb config set NVB_LOG_LEVEL debug       Enable debug logging
+  nvb config unset NVB_MANAGER             Remove manager override
+
+Supported version files: .nvmrc, .node-version, .tool-versions, package.json (engines.node)
+Supported managers: nvm, fnm, mise, asdf, n
+
+Shell integration (add to your shell config):
+  Zsh:   source <path-to-nvb>/hooks/nvb.zsh
+  Bash:  source <path-to-nvb>/hooks/nvb.bash
+
+Environment variables:
+  NVB_MANAGER          Force a specific version manager (nvm, fnm, mise, asdf, n)
+  NVB_LOG_LEVEL        Log verbosity: error, warn, info, debug (default: error)
+  NVB_PRIORITY         Comma-separated file priority (default: .nvmrc,.node-version,.tool-versions,package.json)
+  NVB_CACHE_DIR        Override cache directory
+  NVB_AUTO_INSTALL     Auto-install missing versions: true/false (default: false)
+  NVB_ALIAS_CACHE_TTL  Alias cache TTL in seconds (default: 3600)
+
+Configuration file: $(nvb_config_file)
+EOF
+}
+
+# --- Main dispatch ---
+
+case "${1:-help}" in
+  refresh)     nvb_cmd_refresh ;;
+  current)     nvb_cmd_current ;;
+  doctor)      nvb_cmd_doctor ;;
+  config)      shift; nvb_cmd_config "$@" ;;
+  version|-v)  echo "nvb ${NVB_VERSION}" ;;
+  help|--help|-h) nvb_cmd_help ;;
+  *)
+    nvb_log error "Unknown command: $1"
+    nvb_cmd_help >&2
+    exit 1
+    ;;
+esac

package/hooks/nvb.bash

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# node-version-bridge — Bash hook
+# Source this file in your .bashrc
+
+# Resolve nvb binary path relative to this hook file
+_NVB_BIN="$(cd "$(dirname "${BASH_SOURCE[0]}")/../bin" && pwd)/nvb"
+
+_nvb_hook() {
+  # Skip if directory hasn't changed (fast path, avoids fork)
+  [[ "${_NVB_LAST_DIR:-}" == "$PWD" ]] && return
+  _NVB_LAST_DIR="$PWD"
+  eval "$("${_NVB_BIN}" refresh 2>/dev/null)"
+}
+
+# Append to PROMPT_COMMAND without duplicating
+if [[ ";${PROMPT_COMMAND:-};" != *";_nvb_hook;"* ]]; then
+  PROMPT_COMMAND="_nvb_hook;${PROMPT_COMMAND:-}"
+fi

package/hooks/nvb.zsh

@@ -0,0 +1,19 @@
+#!/usr/bin/env zsh
+# node-version-bridge — Zsh hook
+# Source this file in your .zshrc
+
+# Resolve nvb binary path relative to this hook file
+_NVB_BIN="${0:A:h}/../bin/nvb"
+
+_nvb_hook() {
+  # Skip if directory hasn't changed (fast path)
+  [[ "${_NVB_LAST_DIR:-}" == "$PWD" ]] && return
+  _NVB_LAST_DIR="$PWD"
+  eval "$("${_NVB_BIN}" refresh 2>/dev/null)"
+}
+
+autoload -U add-zsh-hook
+add-zsh-hook chpwd _nvb_hook
+
+# Run once on shell start
+_nvb_hook

package/lib/alias.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# node-version-bridge — Alias resolution
+# Resolves Node.js aliases (lts/*, node, stable) to concrete versions
+# using the Node.js release schedule API.
+
+NVB_ALIAS_CACHE_TTL="${NVB_ALIAS_CACHE_TTL:-3600}" # 1 hour default
+_NVB_NODE_INDEX_URL="https://nodejs.org/dist/index.json"
+
+# Get the alias cache file path
+_nvb_alias_cache_file() {
+  echo "${NVB_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/node-version-bridge}/node-index.json"
+}
+
+# Fetch the Node.js version index (with caching)
+_nvb_fetch_node_index() {
+  local cache_file
+  cache_file="$(_nvb_alias_cache_file)"
+
+  # Check if cache is fresh
+  if [[ -f "$cache_file" ]]; then
+    local mtime now age
+    if stat -f '%m' "$cache_file" &>/dev/null; then
+      # macOS
+      mtime="$(stat -f '%m' "$cache_file")"
+    else
+      # Linux
+      mtime="$(stat -c '%Y' "$cache_file")"
+    fi
+    now="$(date +%s)"
+    age=$(( now - mtime ))
+    if (( age < NVB_ALIAS_CACHE_TTL )); then
+      nvb_log debug "Using cached node index (age: ${age}s)"
+      cat "$cache_file"
+      return 0
+    fi
+  fi
+
+  nvb_log debug "Fetching node index from ${_NVB_NODE_INDEX_URL}"
+
+  local content
+  if command -v curl &>/dev/null; then
+    content="$(curl -sL --max-time 10 "$_NVB_NODE_INDEX_URL" 2>/dev/null)"
+  elif command -v wget &>/dev/null; then
+    content="$(wget -qO- --timeout=10 "$_NVB_NODE_INDEX_URL" 2>/dev/null)"
+  else
+    nvb_log warn "Neither curl nor wget available, cannot resolve aliases"
+    return 1
+  fi
+
+  if [[ -z "$content" ]]; then
+    nvb_log warn "Failed to fetch node index"
+    # Fall back to stale cache if it exists
+    if [[ -f "$cache_file" ]]; then
+      nvb_log debug "Falling back to stale cache"
+      cat "$cache_file"
+      return 0
+    fi
+    return 1
+  fi
+
+  mkdir -p "$(dirname "$cache_file")"
+  echo "$content" > "$cache_file"
+  echo "$content"
+}
+
+# Resolve an alias to a concrete version
+# Supported: lts/*, lts, lts/<codename>, node, stable, latest
+nvb_resolve_alias() {
+  local alias="$1"
+
+  # Normalize
+  alias="$(echo "$alias" | tr '[:upper:]' '[:lower:]')"
+
+  local index
+  index="$(_nvb_fetch_node_index)" || return 1
+
+  local version=""
+
+  case "$alias" in
+    lts|lts/\*)
+      # Latest LTS version
+      version="$(_nvb_extract_latest_lts "$index")"
+      ;;
+    lts/*)
+      # Specific LTS codename (e.g., lts/iron, lts/hydrogen)
+      local codename="${alias#lts/}"
+      version="$(_nvb_extract_lts_by_codename "$index" "$codename")"
+      ;;
+    node|stable|latest)
+      # Latest current version
+      version="$(_nvb_extract_latest "$index")"
+      ;;
+    *)
+      return 1
+      ;;
+  esac
+
+  if [[ -n "$version" ]]; then
+    nvb_log debug "Resolved alias '${alias}' → ${version}"
+    echo "$version"
+    return 0
+  fi
+
+  nvb_log warn "Could not resolve alias '${alias}'"
+  return 1
+}
+
+# Extract the latest LTS version from the index
+_nvb_extract_latest_lts() {
+  local index="$1"
+  # index.json: array of objects with "version":"v22.x.x","lts":"Jod" or "lts":false
+  # First entry with lts !== false is the latest LTS
+  echo "$index" | grep -o '"version":"v[^"]*","date":"[^"]*","files":\[[^]]*\],"npm":"[^"]*","v8":"[^"]*","uv":"[^"]*","zlib":"[^"]*","openssl":"[^"]*","modules":"[^"]*","lts":"[^"]*"' \
+    | grep '"lts":"[^f]' | head -1 | grep -o '"version":"v[^"]*"' | head -1 | sed 's/"version":"v\([^"]*\)"/\1/'
+}
+
+# Extract LTS version by codename
+_nvb_extract_lts_by_codename() {
+  local index="$1"
+  local codename="$2"
+  # Case-insensitive match on codename
+  echo "$index" | grep -oi "\"version\":\"v[^\"]*\"[^}]*\"lts\":\"${codename}\"" \
+    | head -1 | grep -o '"version":"v[^"]*"' | sed 's/"version":"v\([^"]*\)"/\1/'
+}
+
+# Extract the latest (current) version
+_nvb_extract_latest() {
+  local index="$1"
+  echo "$index" | grep -o '"version":"v[^"]*"' | head -1 | sed 's/"version":"v\([^"]*\)"/\1/'
+}
+
+# Check if a string looks like a known alias
+nvb_is_alias() {
+  local value="$1"
+  value="$(echo "$value" | tr '[:upper:]' '[:lower:]')"
+  case "$value" in
+    lts|lts/*|node|stable|latest) return 0 ;;
+    *) return 1 ;;
+  esac
+}

package/lib/cache.sh

@@ -0,0 +1,42 @@
+#!/usr/bin/env bash
+# node-version-bridge — Cache management
+# Avoids redundant version switches when directory/version hasn't changed
+
+NVB_CACHE_DIR="${NVB_CACHE_DIR:-${XDG_CACHE_HOME:-$HOME/.cache}/node-version-bridge}"
+
+nvb_cache_file() {
+  echo "${NVB_CACHE_DIR}/state"
+}
+
+# Check if cached state matches current context
+nvb_cache_is_current() {
+  local cwd="$1" version="$2" source="$3"
+  local cache_file
+  cache_file="$(nvb_cache_file)"
+
+  [[ -f "$cache_file" ]] || return 1
+
+  local cached_cwd cached_version cached_source
+  cached_cwd="$(sed -n '1p' "$cache_file")"
+  cached_version="$(sed -n '2p' "$cache_file")"
+  cached_source="$(sed -n '3p' "$cache_file")"
+
+  [[ "$cached_cwd" == "$cwd" && "$cached_version" == "$version" && "$cached_source" == "$source" ]]
+}
+
+# Update cache with current state
+nvb_cache_update() {
+  local cwd="$1" version="$2" source="$3"
+  local cache_file
+  cache_file="$(nvb_cache_file)"
+
+  mkdir -p "$(dirname "$cache_file")"
+  printf '%s\n%s\n%s\n' "$cwd" "$version" "$source" > "$cache_file"
+}
+
+# Clear stored cache
+nvb_cache_clear() {
+  local cache_file
+  cache_file="$(nvb_cache_file)"
+  rm -f "$cache_file"
+}

package/lib/config.sh

@@ -0,0 +1,124 @@
+#!/usr/bin/env bash
+# node-version-bridge — Configuration file support
+# Loads and manages config from ~/.config/nvb/config
+
+nvb_config_dir() {
+  echo "${XDG_CONFIG_HOME:-$HOME/.config}/nvb"
+}
+
+nvb_config_file() {
+  echo "$(nvb_config_dir)/config"
+}
+
+# Load config file (environment variables take precedence)
+nvb_config_load() {
+  local config_file
+  config_file="$(nvb_config_file)"
+  [[ -f "$config_file" ]] || return 0
+
+  local key value
+  while IFS='=' read -r key value || [[ -n "$key" ]]; do
+    key="$(echo "$key" | xargs)" 2>/dev/null || continue
+    [[ -z "$key" || "$key" == \#* ]] && continue
+    value="$(echo "$value" | sed "s/^[\"']//;s/[\"']$//")"
+    if [[ -z "${!key:-}" ]]; then
+      export "$key=$value"
+    fi
+  done < "$config_file"
+}
+
+# Get a config value (env > file > default)
+nvb_config_get() {
+  local key="$1"
+  local default="${2:-}"
+
+  if [[ -n "${!key:-}" ]]; then
+    echo "${!key}"
+    return 0
+  fi
+
+  local config_file
+  config_file="$(nvb_config_file)"
+  if [[ -f "$config_file" ]]; then
+    local file_value
+    file_value="$(grep "^${key}=" "$config_file" 2>/dev/null | tail -1 | cut -d'=' -f2- | sed "s/^[\"']//;s/[\"']$//")"
+    if [[ -n "$file_value" ]]; then
+      echo "$file_value"
+      return 0
+    fi
+  fi
+
+  echo "$default"
+}
+
+# Set a config value in the file
+nvb_config_set() {
+  local key="$1"
+  local value="$2"
+  local config_dir config_file
+
+  config_dir="$(nvb_config_dir)"
+  config_file="$(nvb_config_file)"
+
+  mkdir -p "$config_dir"
+
+  if [[ -f "$config_file" ]] && grep -q "^${key}=" "$config_file" 2>/dev/null; then
+    local tmp="${config_file}.tmp"
+    sed "s|^${key}=.*|${key}=${value}|" "$config_file" > "$tmp" && mv "$tmp" "$config_file"
+  else
+    echo "${key}=${value}" >> "$config_file"
+  fi
+}
+
+# Remove a config key
+nvb_config_unset() {
+  local key="$1"
+  local config_file
+  config_file="$(nvb_config_file)"
+  [[ -f "$config_file" ]] || return 0
+
+  local tmp="${config_file}.tmp"
+  grep -v "^${key}=" "$config_file" > "$tmp" && mv "$tmp" "$config_file"
+}
+
+# List all config with source info
+nvb_config_list() {
+  local config_file
+  config_file="$(nvb_config_file)"
+
+  echo "Configuration ($(nvb_config_file)):"
+  echo ""
+
+  local keys=("NVB_MANAGER" "NVB_LOG_LEVEL" "NVB_PRIORITY" "NVB_CACHE_DIR" "NVB_ALIAS_CACHE_TTL" "NVB_AUTO_INSTALL")
+  for key in "${keys[@]}"; do
+    local env_val="${!key:-}"
+    local file_val=""
+    local effective=""
+    local source=""
+
+    if [[ -f "$config_file" ]]; then
+      file_val="$(grep "^${key}=" "$config_file" 2>/dev/null | tail -1 | cut -d'=' -f2- | sed "s/^[\"']//;s/[\"']$//")" || true
+    fi
+
+    if [[ -n "$env_val" ]]; then
+      effective="$env_val"
+      if [[ -n "$file_val" ]]; then
+        source="env (overrides file: ${file_val})"
+      else
+        source="env"
+      fi
+    elif [[ -n "$file_val" ]]; then
+      effective="$file_val"
+      source="config file"
+    else
+      effective="(default)"
+      source=""
+    fi
+
+    if [[ -n "$source" ]]; then
+      echo "  ${key}=${effective}  <- ${source}"
+    else
+      echo "  ${key}=${effective}"
+    fi
+  done
+}

package/lib/detect.sh

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# node-version-bridge — Version file detection
+# Walks up directory tree to find version declaration files
+
+# Find a specific file walking up from a directory
+# Usage: nvb_detect_file <filename> [start_dir]
+nvb_detect_file() {
+  local filename="$1"
+  local dir="${2:-$PWD}"
+
+  while [[ "$dir" != "/" ]]; do
+    if [[ -f "${dir}/${filename}" ]]; then
+      echo "${dir}/${filename}"
+      return 0
+    fi
+    dir="$(dirname "$dir")"
+  done
+
+  # Check filesystem root
+  if [[ -f "/${filename}" ]]; then
+    echo "/${filename}"
+    return 0
+  fi
+
+  return 1
+}

package/lib/log.sh

@@ -0,0 +1,27 @@
+#!/usr/bin/env bash
+# node-version-bridge — Logging utilities
+# All log output goes to stderr to keep stdout clean for eval-able commands
+
+nvb_log() {
+  local level="$1"
+  shift
+  local configured="${NVB_LOG_LEVEL:-error}"
+
+  local level_num configured_num
+  level_num=$(_nvb_log_level_num "$level")
+  configured_num=$(_nvb_log_level_num "$configured")
+
+  if (( level_num <= configured_num )); then
+    echo "[nvb:${level}] $*" >&2
+  fi
+}
+
+_nvb_log_level_num() {
+  case "$1" in
+    error) echo 0 ;;
+    warn)  echo 1 ;;
+    info)  echo 2 ;;
+    debug) echo 3 ;;
+    *)     echo 0 ;;
+  esac
+}

package/lib/manager.sh

@@ -0,0 +1,140 @@
+#!/usr/bin/env bash
+# node-version-bridge — Manager detection and adapter dispatch
+# Detects the active Node version manager and generates apply commands
+
+# Check if a version is a full semver (x.y.z)
+_nvb_is_full_version() {
+  [[ "$1" =~ ^[0-9]+\.[0-9]+\.[0-9]+$ ]]
+}
+
+# Resolve a partial version (e.g. "18" or "18.20") to the best matching
+# installed version. For managers that handle partials natively (nvm, fnm, n),
+# returns the version as-is. For asdf/mise, queries installed versions.
+nvb_resolve_installed_version() {
+  local manager="$1"
+  local version="$2"
+
+  # Full semver doesn't need resolution
+  if _nvb_is_full_version "$version"; then
+    echo "$version"
+    return 0
+  fi
+
+  local match=""
+  case "$manager" in
+    asdf)
+      match="$(asdf list nodejs 2>/dev/null | tr -d ' *' | grep -E "^${version}(\.|$)" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)"
+      ;;
+    mise)
+      match="$(mise ls --installed node 2>/dev/null | awk '{print $2}' | grep -E "^${version}(\.|$)" | sort -t. -k1,1n -k2,2n -k3,3n | tail -1)"
+      ;;
+    *)
+      # nvm, fnm, n handle partial versions natively
+      echo "$version"
+      return 0
+      ;;
+  esac
+
+  if [[ -n "$match" ]]; then
+    nvb_log debug "Resolved partial version ${version} → ${match} for ${manager}"
+    echo "$match"
+  else
+    nvb_log debug "No installed version matching ${version} for ${manager}"
+    echo "$version"
+  fi
+}
+
+# Detect which version manager is available
+# Respects NVB_MANAGER override, otherwise auto-detects
+nvb_detect_manager() {
+  local manager="${NVB_MANAGER:-}"
+  if [[ -n "$manager" ]]; then
+    nvb_log debug "Using configured manager: ${manager}"
+    echo "$manager"
+    return 0
+  fi
+
+  # Auto-detect in common preference order
+  if [[ -n "${NVM_DIR:-}" ]]; then nvb_log debug "Detected nvm"; echo "nvm"; return 0; fi
+  if command -v fnm &>/dev/null;  then nvb_log debug "Detected fnm"; echo "fnm"; return 0; fi
+  if command -v mise &>/dev/null; then nvb_log debug "Detected mise"; echo "mise"; return 0; fi
+  if command -v asdf &>/dev/null; then nvb_log debug "Detected asdf"; echo "asdf"; return 0; fi
+  if command -v n &>/dev/null;    then nvb_log debug "Detected n"; echo "n"; return 0; fi
+
+  nvb_log error "No supported version manager detected"
+  return 1
+}
+
+# Check if a specific manager is available
+nvb_adapter_available() {
+  local manager="$1"
+  case "$manager" in
+    nvm)  [[ -n "${NVM_DIR:-}" ]] ;;
+    fnm)  command -v fnm &>/dev/null ;;
+    mise) command -v mise &>/dev/null ;;
+    asdf) command -v asdf &>/dev/null ;;
+    n)    command -v n &>/dev/null ;;
+    *)    return 1 ;;
+  esac
+}
+
+# Output eval-able shell command to switch Node version
+# The output is designed to be eval'd in the user's interactive shell
+nvb_adapter_apply_cmd() {
+  local manager="$1"
+  local version="$2"
+
+  case "$manager" in
+    nvm)
+      echo "nvm use '${version}' >/dev/null 2>&1 || echo '[nvb] Node ${version} not installed via nvm. Run: nvm install ${version}' >&2"
+      ;;
+    fnm)
+      echo "fnm use '${version}' --log-level quiet 2>/dev/null || echo '[nvb] Node ${version} not installed via fnm. Run: fnm install ${version}' >&2"
+      ;;
+    mise)
+      echo "eval \"\$(mise shell node@'${version}' 2>/dev/null)\" 2>/dev/null || echo '[nvb] Node ${version} not available via mise. Run: mise install node@${version}' >&2"
+      ;;
+    asdf)
+      echo "export ASDF_NODEJS_VERSION='${version}'"
+      ;;
+    n)
+      echo "n '${version}' >/dev/null 2>&1 || echo '[nvb] Node ${version} not installed via n. Run: n install ${version}' >&2"
+      ;;
+    *)
+      nvb_log error "Unknown manager: ${manager}"
+      return 1
+      ;;
+  esac
+}
+
+# Output eval-able shell command to install a Node version
+nvb_adapter_install_cmd() {
+  local manager="$1"
+  local version="$2"
+
+  case "$manager" in
+    nvm)
+      echo "nvm install '${version}' >/dev/null 2>&1"
+      ;;
+    fnm)
+      echo "fnm install '${version}' --log-level quiet 2>/dev/null"
+      ;;
+    mise)
+      echo "mise install node@'${version}' >/dev/null 2>&1"
+      ;;
+    asdf)
+      if _nvb_is_full_version "$version"; then
+        echo "asdf install nodejs '${version}' >/dev/null 2>&1"
+      else
+        echo "asdf install nodejs \"\$(asdf latest nodejs '${version}')\" >/dev/null 2>&1"
+      fi
+      ;;
+    n)
+      echo "n '${version}' >/dev/null 2>&1"
+      ;;
+    *)
+      nvb_log error "Unknown manager: ${manager}"
+      return 1
+      ;;
+  esac
+}

package/lib/parse.sh

@@ -0,0 +1,121 @@
+#!/usr/bin/env bash
+# node-version-bridge — Version file parsing
+# Extracts and normalizes Node.js version from various file formats
+
+# Dispatch parsing based on file type
+nvb_parse_file() {
+  local filename="$1"
+  local filepath="$2"
+
+  case "$(basename "$filename")" in
+    .nvmrc)         nvb_parse_nvmrc "$filepath" ;;
+    .node-version)  nvb_parse_node_version "$filepath" ;;
+    .tool-versions) nvb_parse_tool_versions "$filepath" ;;
+    package.json)   nvb_parse_package_json "$filepath" ;;
+    *)
+      nvb_log warn "Unknown file format: ${filename}"
+      return 1
+      ;;
+  esac
+}
+
+# Parse .nvmrc — strips leading 'v', validates semver-like pattern
+nvb_parse_nvmrc() {
+  local filepath="$1"
+  local content
+  content="$(head -1 "$filepath" 2>/dev/null | tr -d '[:space:]')"
+
+  [[ -z "$content" ]] && return 1
+
+  # Strip leading 'v' or 'V'
+  content="${content#v}"
+  content="${content#V}"
+
+  # Resolve aliases (lts/*, node, stable, etc.)
+  if nvb_is_alias "$content"; then
+    local resolved
+    resolved="$(nvb_resolve_alias "$content")" || {
+      nvb_log warn "Could not resolve alias '${content}' in ${filepath} (network unavailable?)"
+      return 1
+    }
+    echo "$resolved"
+    return 0
+  fi
+
+  # Accept partial or full semver: 18, 18.19, 18.19.0
+  if [[ "$content" =~ ^[0-9]+(\.[0-9]+)?(\.[0-9]+)?$ ]]; then
+    echo "$content"
+    return 0
+  fi
+
+  nvb_log warn "Could not parse version from ${filepath}: '${content}'"
+  return 1
+}
+
+# Parse .node-version — same format rules as .nvmrc
+nvb_parse_node_version() {
+  nvb_parse_nvmrc "$1"
+}
+
+# Parse .tool-versions — extract 'nodejs' or 'node' entry
+nvb_parse_tool_versions() {
+  local filepath="$1"
+  local version
+
+  version="$(grep -E '^(nodejs|node)\s+' "$filepath" 2>/dev/null | head -1 | awk '{print $2}' | tr -d '[:space:]')"
+
+  [[ -z "$version" ]] && return 1
+
+  version="${version#v}"
+  version="${version#V}"
+
+  if [[ "$version" =~ ^[0-9]+(\.[0-9]+)?(\.[0-9]+)?$ ]]; then
+    echo "$version"
+    return 0
+  fi
+
+  nvb_log warn "Could not parse nodejs version from ${filepath}: '${version}'"
+  return 1
+}
+
+# Parse package.json — extract engines.node field
+nvb_parse_package_json() {
+  local filepath="$1"
+
+  [[ -f "$filepath" ]] || return 1
+
+  local engines_node
+  # Extract "engines":{..."node":"<value>"...} using grep/sed (no jq dependency)
+  engines_node="$(grep -o '"engines"[[:space:]]*:[[:space:]]*{[^}]*}' "$filepath" 2>/dev/null \
+    | grep -o '"node"[[:space:]]*:[[:space:]]*"[^"]*"' \
+    | head -1 \
+    | sed 's/"node"[[:space:]]*:[[:space:]]*"\([^"]*\)"/\1/')"
+
+  [[ -z "$engines_node" ]] && return 1
+
+  nvb_log debug "Found engines.node: '${engines_node}' in ${filepath}"
+
+  # Handle exact versions: "18.19.0", "v18.19.0", "18"
+  local clean="$engines_node"
+  clean="${clean#v}"
+  clean="${clean#V}"
+
+  if [[ "$clean" =~ ^[0-9]+(\.[0-9]+)?(\.[0-9]+)?$ ]]; then
+    echo "$clean"
+    return 0
+  fi
+
+  # Handle semver ranges: extract the base version
+  # ">=18.0.0", "^18.19.0", "~18.19.0", ">=18"
+  local base
+  base="$(echo "$clean" | sed 's/^[^0-9]*//' | grep -oE '^[0-9]+(\.[0-9]+)?(\.[0-9]+)?')"
+
+  if [[ -n "$base" ]]; then
+    nvb_log info "Interpreted engines.node '${engines_node}' as minimum version ${base}"
+    echo "$base"
+    return 0
+  fi
+
+  nvb_log warn "Could not parse engines.node from ${filepath}: '${engines_node}'"
+  return 1
+}

package/lib/resolve.sh

@@ -0,0 +1,32 @@
+#!/usr/bin/env bash
+# node-version-bridge — Version resolution
+# Applies priority rules to select the target Node.js version
+
+# Resolve the target version from available files
+# Sets: NVB_RESOLVED_VERSION, NVB_RESOLVED_SOURCE
+nvb_resolve_version() {
+  local dir="${1:-$PWD}"
+  local priority_str="${NVB_PRIORITY:-.nvmrc,.node-version,.tool-versions,package.json}"
+
+  NVB_RESOLVED_VERSION=""
+  NVB_RESOLVED_SOURCE=""
+
+  IFS=',' read -ra priorities <<< "$priority_str"
+
+  for filename in "${priorities[@]}"; do
+    filename="$(echo "$filename" | xargs)" # trim whitespace
+    local filepath
+    filepath="$(nvb_detect_file "$filename" "$dir")" || continue
+
+    local version
+    version="$(nvb_parse_file "$filename" "$filepath")" || continue
+
+    export NVB_RESOLVED_VERSION="$version"
+    export NVB_RESOLVED_SOURCE="$filepath"
+    nvb_log debug "Resolved ${version} from ${filepath}"
+    return 0
+  done
+
+  nvb_log debug "No version file found from ${dir}"
+  return 1
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "node-version-bridge",
+  "version": "0.5.0",
+  "description": "Detect Node.js version from project files and apply it via any version manager",
+  "bin": {
+    "nvb": "bin/nvb"
+  },
+  "files": [
+    "bin/",
+    "lib/",
+    "hooks/"
+  ],
+  "keywords": [
+    "node",
+    "version",
+    "nvm",
+    "fnm",
+    "mise",
+    "asdf",
+    "nvmrc"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Marcosreuquen/node-version-bridge.git"
+  },
+  "author": "Marcos Reuquen",
+  "os": [
+    "darwin",
+    "linux"
+  ],
+  "engines": {
+    "node": ">=14"
+  }
+}