nvm-auto-use.fish/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Fish shell plugin that automatically loads the correct Node.js version from .nvmrc files when changing directories. The plugin uses Fisher as its package manager.

Architecture

The plugin consists of two main Fish functions:

• nvm_auto_use.fish - Main function that triggers on directory changes (--on-variable PWD) and handles the automatic Node.js version switching
• nvm_find_nvmrc.fish - Utility function that searches for .nvmrc files in the current directory and parent directories

Development Commands

Linting and Code Quality

The project uses a comprehensive linting setup with automatic tool installation:

# Install all linting tools (markdownlint-cli, jsonlint, jq, editorconfig-checker)
make install-tools

# Run all linting checks (Fish, Markdown, JSON, EditorConfig)
make lint

# Fix auto-fixable linting issues
make lint-fix

# Individual linting commands
make lint-fish         # Lint Fish shell files (formatting + syntax)
make lint-markdown     # Lint Markdown files (style, headers, lists)
make lint-json         # Lint JSON files (syntax validation)
make lint-editorconfig # Check EditorConfig compliance (line endings, indentation)

Supported Linting Tools

• Fish shell: fish_indent for formatting, fish -n for syntax validation
• Markdown: markdownlint-cli with custom configuration (.markdownlint.json)
• JSON: jsonlint or jq for syntax validation
• EditorConfig: editorconfig-checker (auto-installed if missing)

The linting system automatically downloads missing tools and follows XDG standards for installation.

Manual Fish Commands

# Format all Fish files (required before commits)
find . -name "*.fish" -exec fish_indent --write {} \;

# Check formatting without modifying files
find . -name "*.fish" -exec fish_indent --check {} \;

# Validate Fish syntax
fish -n functions/*.fish completions/*.fish

Testing

# Run all tests (unit + integration)
tests/test_runner.fish

# Run specific test types
make test-unit        # Unit tests only
make test-integration # Integration tests only

# Test plugin installation
make test             # Local installation test
make test-ci          # CI environment test

Manual Installation Commands

# Install the plugin locally for testing
fisher install .

# Remove the plugin
fisher remove ivuorinen/nvm-auto-use.fish

Configuration Commands

# View current configuration
nvm_auto_use_config

# Enable/disable features
nvm_auto_use_config silent on
nvm_auto_use_config auto_install off
nvm_auto_use_config manager fnm

# Set debounce timing
nvm_auto_use_config debounce 1000

# Exclude directories
nvm_auto_use_config exclude "build"

Developer Tools

# Security and validation
nvm_security check_version "18.17.0"  # Validate version format and policies
nvm_security audit                    # Comprehensive security audit
nvm_security policy set min_version "16.0.0"  # Set security policies

# Smart recommendations
nvm_recommendations suggest_version new_project  # Get version recommendations
nvm_recommendations upgrade_path                 # Plan upgrade strategy
nvm_recommendations security_update              # Security-focused updates

# Diagnostics and debugging
nvm_doctor check           # Comprehensive health check
nvm_doctor system          # System information
nvm_doctor managers        # Check version managers
nvm_doctor fix all         # Auto-fix common issues

# Cache management
nvm_cache stats            # Cache statistics
nvm_cache clear            # Clear all cache
nvm_cache get "key"        # Get cached value

# Async operations
nvm_async version_check "file"  # Non-blocking version check
nvm_async cleanup              # Clean up background jobs

# Error recovery
nvm_error_recovery manager_failure "nvm" "18.0.0"  # Handle manager failures

Testing the Functions

# Test the nvmrc finder function
nvm_find_nvmrc

# Test version extraction
nvm_extract_version .nvmrc

# Test directory change trigger (create a test .nvmrc file)
echo "18.0.0" > .nvmrc
cd .  # This should trigger nvm_auto_use

# Check version status
nvm_version_status

Key Implementation Details

Core Architecture

• The plugin hooks into Fish's variable change system using --on-variable PWD
• Supports multiple Node.js version managers: nvm, fnm, volta, asdf
• Supports multiple file formats: .nvmrc, .node-version, .tool-versions, package.json engines.node
• The search for version files traverses up the directory tree until it finds one or reaches the root directory

Performance Features

• XDG-compliant caching with configurable TTL for version lookups and manager availability
• Async operations for non-blocking version checks using Fish background jobs
• Debouncing to prevent rapid version switching during directory navigation
• Smart directory exclusions to skip unnecessary processing

Security & Reliability

• Version validation with format checking and policy enforcement
• Security vulnerability scanning with CVE checking (online and offline)
• Error recovery mechanisms with graceful degradation and fallback strategies
• Input sanitization to prevent injection attacks through version files

Advanced Capabilities

• Smart recommendations for version selection, upgrades, and security updates
• Comprehensive diagnostics with the nvm_doctor command for troubleshooting
• Extensive testing suite with unit and integration tests
• Configuration management with persistent settings and policy enforcement

Code Quality Standards

Fish Shell Code

• All Fish code must be formatted with fish_indent before committing
• Functions should include description flags (-d "description")
• Use proper Fish conventions for variable scoping (set -l, set -g, set -gx)
• Include comprehensive error handling and input validation
• Follow Fish best practices for command substitution and string handling

General Standards

• Makefile: 80-character line limit, tab indentation
• Markdown: 120-character line limit, consistent heading structure
• JSON: Valid syntax, proper formatting
• EditorConfig: Consistent line endings (LF), final newlines, no trailing whitespace

CI/CD Integration

• GitHub Actions automatically runs all linting checks on push/PR
• All linting must pass before merging
• Use make test-ci for testing plugin installation in CI environments

Tool Installation

• Missing linting tools are automatically installed during make install-tools
• Installation respects XDG standards: $XDG_BIN_HOME → $HOME/bin → /usr/local/bin
• Uses secure temporary directories (mktemp) for downloads