🌲 ecolog.nvim (Alpha)

Ecolog (эколог) - your environment guardian in Neovim. Named after the Russian word for "environmentalist", this plugin protects and manages your environment variables with the same care an ecologist shows for nature.

A Neovim plugin for seamless environment variable integration and management. Provides intelligent autocompletion, type checking, and value peeking for environment variables in your projects. All in one place.

📦 Installation

Using lazy.nvim:

Plugin Setup

{
  'philosofonusus/ecolog.nvim',
  dependencies = {
    'hrsh7th/nvim-cmp', -- Optional: for autocompletion support (recommended)
  },
  -- Optional: you can add some keybindings
  -- (I personally use lspsaga so check out lspsaga integration or lsp integration for a smoother experience without separate keybindings)
  keys = {
    { '<leader>ge', '<cmd>EcologGoto<cr>', desc = 'Go to env file' },
    { '<leader>ep', '<cmd>EcologPeek<cr>', desc = 'Ecolog peek variable' },
    { '<leader>es', '<cmd>EcologSelect<cr>', desc = 'Switch env file' },
  },
  -- Lazy loading is done internally
  lazy = false,
  opts = {
    integrations = {
        -- WARNING: for both cmp integrations see readme section below
        nvim_cmp = true, -- If you dont plan to use nvim_cmp set to false, enabled by default
        -- If you are planning to use blink cmp uncomment this line
        -- blink_cmp = true,
    },
    -- Enables shelter mode for sensitive values
    shelter = {
        configuration = {
            partial_mode = false, -- false by default, disables partial mode, for more control check out shelter partial mode
            mask_char = "*",   -- Character used for masking
        },
        modules = {
            cmp = true,       -- Mask values in completion
            peek = false,      -- Mask values in peek view
            files = false,     -- Mask values in files
            telescope = false  -- Mask values in telescope
        }
    },
    -- true by default, enables built-in types (database_url, url, etc.)
    types = true,
    path = vim.fn.getcwd(), -- Path to search for .env files
    preferred_environment = "development", -- Optional: prioritize specific env files
  },
}

Setup auto-completion with nvim-cmp:

require('cmp').setup({
  sources = {
    { name = 'ecolog' },
    -- your other sources...
  },

If you use blink.cmp see Blink-cmp Integration guide

✨ Features

🔍 Environment Variable Peeking

Quick peek at environment variable values and metadata
Intelligent context detection
Type-aware value display
Preview inline comments directly in your code

🤖 Smart Autocompletion

Integration with nvim-cmp
Context-aware suggestions
Type-safe completions
Intelligent provider detection

🛡️ Shelter Mode Protection

Mask sensitive values in completion menu
Visual protection for .env file content
Secure value peeking with masking
Flexible per-feature control
Real-time visual masking

🔄 Real-time Updates

Automatic cache management
Live environment file monitoring
Instant mask updates
File change detection

📁 Multi-Environment Support

Multiple .env file handling
Priority-based file loading
Environment-specific configurations
Smart file selection

💡 Intelligent Type System

Automatic type inference
Type validation and checking
Smart type suggestions
Custom type definitions
Context-based type detection

🚀 Usage

Available Commands

Command	Description
`:EcologPeek [variable_name]`	Peek at environment variable value and metadata
`:EcologPeek`	Peek at environment variable under cursor
`:EcologRefresh`	Refresh environment variable cache
`:EcologSelect`	Open a selection window to choose environment file
`:EcologGoto`	Open selected environment file in buffer
`:EcologGotoVar`	Go to specific variable definition in env file
`:EcologGotoVar [variable_name]`	Go to specific variable definition in env file with variable under cursor
`:EcologShelterToggle [command] [feature]`	Control shelter mode for masking sensitive values
`:EcologShelterLinePeek`	Temporarily reveal value on current line in env file
`:Telescope ecolog env`	Alternative way to open Telescope picker

📝 Environment File Priority

Files are loaded in the following priority order:

.env.{preferred_environment} (if preferred_environment is set)
.env
Other .env.* files (alphabetically)

🔌 Environment File Priority

Files are loaded in the following priority order:

.env.{preferred_environment} (if preferred_environment is set)
.env
Other .env.* files (alphabetically)

🔌 Shell Variables Integration

Ecolog can load environment variables directly from your shell environment. This is useful when you want to:

Access system environment variables
Work with variables set by your shell profile
Handle dynamic environment variables

Basic Usage

Enable shell variable loading with default settings:

require('ecolog').setup({
  load_shell = true
})

Advanced Configuration

For more control over shell variable handling:

require('ecolog').setup({
  load_shell = {
    enabled = true,     -- Enable shell variable loading
    override = false,   -- When false, .env files take precedence over shell variables
    -- Optional: filter specific shell variables
    filter = function(key, value)
      -- Example: only load specific variables
      return key:match("^(PATH|HOME|USER)$") ~= nil
    end,
    -- Optional: transform shell variables before loading
    transform = function(key, value)
      -- Example: prefix shell variables for clarity
      return "[shell] " .. value
    end
  }
})

Configuration Options

Option	Type	Default	Description
`enabled`	boolean	`false`	Enable/disable shell variable loading
`override`	boolean	`false`	When true, shell variables take precedence over .env files
`filter`	function\|nil	`nil`	Optional function to filter which shell variables to load
`transform`	function\|nil	`nil`	Optional function to transform shell variable values

Features

Full integration with all Ecolog features (completion, peek, shelter mode)
Shell variables are marked with "shell" as their source
Configurable precedence between shell and .env file variables
Optional filtering and transformation of shell variables
Type detection and value transformation support

Best Practices

Use filter to limit which shell variables are loaded to avoid cluttering
Consider using transform to clearly mark shell-sourced variables
Be mindful of the override setting when working with both shell and .env variables
Apply shelter mode settings to shell variables containing sensitive data

💡 Integrations

Nvim-cmp Integration

Add ecolog to your nvim-cmp sources:

require('cmp').setup({
  sources = {
    { name = 'ecolog' },
    -- your other sources...
  },

})

Nvim-cmp integration is enabled by default. To disable it:

require('ecolog').setup({
  integrations = {
    nvim_cmp = false,
  },
})

Blink-cmp Integration

PS: When blink_cmp is enabled, nvim_cmp is disabled by default.

Ecolog provides an integration with blink.cmp for environment variable completions. To enable it:

Enable the integration in your Ecolog setup:

require('ecolog').setup({
  integrations = {
    blink_cmp = true,
  },
})

Configure Blink CMP to use the Ecolog source:

{
  "saghen/blink.cmp",
  opts = {
    sources = {
      completion = {
        enabled_providers = { 'ecolog', 'lsp', 'path', 'snippets', 'buffer' },
      },
      providers = {
        ecolog = { name = 'ecolog', module = 'ecolog.integrations.cmp.blink_cmp' },
      },
    },
  },
}

LSP Integration (Experimental)

⚠️ Warning: The LSP integration is currently experimental and may interfere with your existing LSP setup. Use with caution.

Ecolog provides optional LSP integration that enhances the hover and definition functionality for environment variables. When enabled, it will:

Show environment variable values when hovering over them
Jump to environment variable definitions using goto-definition

meaning you dont need any custom keymaps

Setup

To enable LSP integration, add this to your Neovim configuration:

require('ecolog').setup({
    integrations = {
        lsp = true,
    }
})

PS: If you're using lspsaga, please see section LSP Saga Integration don't use lsp integration use one or the other.

Features

Hover Preview: When you hover (K) over an environment variable, it will show the value and metadata in a floating window
Goto Definition: Using goto-definition (gd) on an environment variable will jump to its definition in the .env file

Known Limitations

The integration overrides the default LSP hover and definition handlers
May conflict with other plugins that modify LSP hover behavior
Performance impact on LSP operations (though optimized and should be unnoticable)

Disabling LSP Integration

If you experience any issues, you can disable the LSP integration:

require('ecolog').setup({
    integrations = {
        lsp = false,
    }
})

Please report such issues on our GitHub repository

LSP Saga Integration

Ecolog provides integration with lspsaga.nvim that enhances hover and goto-definition functionality for environment variables while preserving Saga's features for other code elements.

Setup

To enable LSP Saga integration, add this to your configuration:

require('ecolog').setup({
    integrations = {
        lspsaga = true,
    }
})

PS: If you're using lspsaga then don't use lsp integration use one or the other.

Features

The integration adds two commands that intelligently handle both environment variables and regular code:

EcologSagaHover:
- Shows environment variable value when hovering over env vars
- Falls back to Saga's hover for other code elements
- Automatically replaces existing Saga hover keymaps
EcologSagaGD (Goto Definition):
- Jumps to environment variable definition in .env file
- Uses Saga's goto definition for other code elements
- Automatically replaces existing Saga goto-definition keymaps

💡 Note: When enabled, the integration automatically detects and updates your existing Lspsaga keymaps to use Ecolog's enhanced functionality. No manual keymap configuration required!

Example Configuration

{
  'philosofonusus/ecolog.nvim',
  dependencies = {
    'nvimdev/lspsaga.nvim',
    'hrsh7th/nvim-cmp',
  },
  opts = {
    integrations = {
      lspsaga = true,
    }
  },
}

💡 Note: The LSP Saga integration provides a smoother experience than the experimental LSP integration if you're already using Saga in your setup.

Telescope Integration

First, load the extension:

require('telescope').load_extension('ecolog')

Then configure it in your Telescope setup (optional):

require('telescope').setup({
  extensions = {
    ecolog = {
      shelter = {
        -- Whether to show masked values when copying to clipboard
        mask_on_copy = false,
      },
      -- Default keybindings
      mappings = {
        -- Key to copy value to clipboard
        copy_value = "<C-y>",
        -- Key to copy name to clipboard
        copy_name = "<C-n>",
        -- Key to append value to buffer
        append_value = "<C-a>",
        -- Key to append name to buffer (defaults to <CR>)
        append_name = "<CR>",
      },
    }
  }
})

🔧 Language Support

🟢 Currently Supported and Tested

Language	Environment Access & Autocompletion trigger	Description
Javascript/TypeScript/React	`import.meta.env['` `process.env['` `import.meta.env["` `process.env["`	Full support for Node.js, Vite environment variables
JavaScript/Typescript/React	`process.env.` `import.meta.env.`	Complete support for both types of annotations
Deno	`Deno.env.get("*` `Deno.env.get('`	Deno runtime environment variable access
Bun	`Bun.env.` `Bun.env["` `Bun.env['`	Bun runtime environment variable access
Python	`os.environ.get('` `os.environ['` `os.environ["*`	Native Python environment variable access
Lua	`os.getenv("` `os.getenv('`	Native Lua environment variable access
Rust	`std::env::var()` `env::var()`	Rust standard library environment access

🔴 Supported but Not Thoroughly Tested (may be broken)

Language	Environment Access & Autocompletion trigger	Description
PHP	`getenv()` `_ENV[]`	Support for both modern and legacy PHP env access
Go	`os.Getenv("*`	Go standard library environment access

🚧 Coming Soon

Language	Planned Support	Status
C#	`Environment.GetEnvironmentVariable()`	Planned
Shell	`$VAR`, `${VAR}`	Planned
Ruby	`ENV[]` `ENV.fetch()`	Planned
Docker	`ARG ` `ENV ` `${*`	Planned

💡 Want support for another language?
Feel free to contribute by adding a new provider! Or just check out the Custom Providers section.

🔌 Custom Providers

You can add support for additional languages by registering custom providers. Each provider defines how environment variables are detected and extracted in specific file types.

Example: Adding Ruby Support

require('ecolog').setup({
  providers = {
    {
      -- Pattern to match environment variable access
      pattern = "ENV%[['\"]%w['\"]%]",
      -- Filetype(s) this provider supports (string or table)
      filetype = "ruby",
      -- Function to extract variable name from the line
      extract_var = function(line, col)
        local before_cursor = line:sub(1, col + 1)
        return before_cursor:match("ENV%['\"['\"]%]$")
      end,
      -- Function to return completion trigger pattern
      get_completion_trigger = function()
        return "ENV['"
      end
    }
  }
})

🛡️ Shelter Mode

Shelter mode provides a secure way to work with sensitive environment variables by masking their values in different contexts. This feature helps prevent accidental exposure of sensitive data like API keys, passwords, tokens, and other credentials.

🔧 Configuration

require('ecolog').setup({
    shelter = {
        configuration = {
            -- Partial mode configuration:
            -- false: completely mask values (default)
            -- true: use default partial masking settings
            -- table: customize partial masking
            -- partial_mode = false,
            -- or with custom settings:
            partial_mode = {
                show_start = 3,    -- Show first 3 characters
                show_end = 3,      -- Show last 3 characters
                min_mask = 3,      -- Minimum masked characters
            },
            mask_char = "*",   -- Character used for masking
        },
        modules = {
            cmp = false,       -- Mask values in completion
            peek = false,      -- Mask values in peek view
            files = false,     -- Mask values in files
            telescope = false  -- Mask values in telescope
        }
    },
    path = vim.fn.getcwd(), -- Path to search for .env files
    preferred_environment = "development", -- Optional: prioritize specific env files
})

🎯 Features

Partial Masking

Three modes of operation:

Full Masking (Default)

partial_mode = false
-- Example: "my-secret-key" -> "************"

Default Partial Masking

partial_mode = true
-- Example: "my-secret-key" -> "my-***-key"

Custom Partial Masking

partial_mode = {
    show_start = 4,    -- Show more start characters
    show_end = 2,      -- Show fewer end characters
    min_mask = 3,      -- Minimum mask length
}
-- Example: "my-secret-key" -> "my-s***ey"

1. Completion Protection (cmp)

Masks sensitive values in the completion menu
Preserves variable names and types for context
Integrates seamlessly with nvim-cmp

Example completion item:

DB_PASSWORD  Type: string
Value: ********

2. Peek Window Protection

Masks values when using :EcologPeek
Shows metadata (type, source) while protecting the value

Example peek window:

Name     : DB_PASSWORD
Type     : string
Source   : .env.development
Value    : ********
Comment  : Very important value

3. File Content Protection

Visually masks values in .env files
Preserves the actual file content (masks are display-only)
Updates automatically on file changes
Maintains file structure and comments
Only masks the value portion after =
Supports quoted and unquoted values

🎮 Commands

:EcologShelterToggle provides flexible control over shelter mode:

Basic Usage:

:EcologShelterToggle              " Toggle between all-off and initial settings

Global Control:

:EcologShelterToggle enable       " Enable all shelter modes
:EcologShelterToggle disable      " Disable all shelter modes

Feature-Specific Control:

:EcologShelterToggle enable cmp   " Enable shelter for completion only
:EcologShelterToggle disable peek " Disable shelter for peek only
:EcologShelterToggle enable files " Enable shelter for file display

Quick Value Reveal:
```
:EcologShelterLinePeek           " Temporarily reveal value on current line
```
- Shows the actual value for the current line
- Value is hidden again when cursor moves away
- Only works when shelter mode is enabled for files

📝 Example

Original .env file:

# Authentication
JWT_SECRET=my-super-secret-key
AUTH_TOKEN="bearer 1234567890"

# Database Configuration
DB_HOST=localhost
DB_USER=admin
DB_PASS=secure_password123

With full masking (partial_mode = false):

# Authentication
JWT_SECRET=********************
AUTH_TOKEN=******************

# Database Configuration
DB_HOST=*********
DB_USER=*****
DB_PASS=******************

Partial Masking Examples

With default settings (show_start=3, show_end=3, min_mask=3):

"mysecretkey"     -> "mys***key"    # Enough space for min_mask (3) characters
"secret"          -> "******"        # Not enough space for min_mask between shown parts
"api_key"         -> "*******"       # Would only have 1 char for masking, less than min_mask
"very_long_key"   -> "ver*****key"   # Plenty of space for masking

The min_mask setting ensures that sensitive values are properly protected by requiring a minimum number of masked characters between the visible parts. If this minimum cannot be met, the entire value is masked for security.

Telescope Integration

The plugin provides a Telescope extension for searching and managing environment variables.

Usage

Open the environment variables picker:

:Telescope ecolog env

Features

🔍 Search through all environment variables
📋 Copy variable names or values to clipboard
⌨️ Insert variables into your code
🛡️ Integrated with shelter mode for sensitive data protection
📝 Shows variable metadata (type, source file)

Default Keymaps

Key	Action
`<CR>`	Insert variable name
`<C-y>`	Copy value to clipboard
`<C-n>`	Copy name to clipboard
`<C-a>`	Append value to buffer

All keymaps are customizable through the configuration.

🛡 Ecolog Types

Ecolog includes a flexible type system for environment variables with built-in and custom types.

Type Configuration

Configure types through the types option in setup:

require('ecolog').setup({
  custom_types = {
      semver = {
        pattern = "^v?%d+%.%d+%.%d+%-?[%w]*$",
        validate = function(value)
          local major, minor, patch = value:match("^v?(%d+)%.(%d+)%.(%d+)")
          return major and minor and patch
        end,
      },
     aws_region = {
      pattern = "^[a-z]{2}%-[a-z]+%-[0-9]$",
      validate = function(value)
        local valid_regions = {
          ["us-east-1"] = true,
          ["us-west-2"] = true,
          -- ... etc
        }
        return valid_regions[value] == true
      end
    }
  },
  types = {
    -- Built-in types
    url = true,          -- URLs (http/https)
    localhost = true,    -- Localhost URLs
    ipv4 = true,        -- IPv4 addresses
    database_url = true, -- Database connection strings
    number = true,       -- Integers and decimals
    boolean = true,      -- true/false/yes/no/1/0
    json = true,         -- JSON objects and arrays
    iso_date = true,     -- ISO 8601 dates (YYYY-MM-DD)
    iso_time = true,     -- ISO 8601 times (HH:MM:SS)
    hex_color = true,    -- Hex color codes (#RGB or #RRGGBB)
  }
})

You can also:

Enable all built-in types: types = true
Disable all built-in types: types = false
Enable specific types and add custom ones:

require('ecolog').setup({
  custom_types = {
    jwt = {
      pattern = "^[A-Za-z0-9%-_]+%.[A-Za-z0-9%-_]+%.[A-Za-z0-9%-_]+$",
      validate = function(value)
        local parts = vim.split(value, ".", { plain = true })
        return #parts == 3
      end
    },
  }
  types = {
    url = true,
    number = true,
  }
})

Custom Type Definition

Each custom type requires:

pattern (required): A Lua pattern string for initial matching
validate (optional): A function for additional validation
transform (optional): A function to transform the value

Example usage in .env files:

VERSION=v1.2.3                  # Will be detected as semver type
REGION=us-east-1               # Will be detected as aws_region type
AUTH_TOKEN=eyJhbG.eyJzd.iOiJ  # Will be detected as jwt type

💡 Tips

Selective Protection: Enable shelter mode only for sensitive environments:

-- In your config
if vim.fn.getcwd():match("production") then
  require('ecolog').setup({
    shelter = {
        configuration = {
            partial_mode = {
                show_start = 3,    -- Number of characters to show at start
                show_end = 3,      -- Number of characters to show at end
                min_mask = 3,      -- Minimum number of mask characters
            }
           mask_char = "*",   -- Character used for masking
        },
        modules = {
            cmp = true,       -- Mask values in completion
            peek = true,      -- Mask values in peek view
            files = true,     -- Mask values in files
            telescope = false -- Mask values in telescope
        }
    },
    path = vim.fn.getcwd(), -- Path to search for .env files
    preferred_environment = "development", -- Optional: prioritize specific env files
  })
end

Custom Masking: Use different characters for masking:

shelter = {
    configuration = {
       mask_char = "•"  -- Use dots
    }
}
-- or
shelter = {
    configuration = {
       mask_char = "█"  -- Use blocks
    }
}

Temporary Viewing: Use :EcologShelterToggle disable temporarily when you need to view values, then re-enable with :EcologShelterToggle enable
Security Best Practices:
- Enable shelter mode by default for production environments
- Use file shelter mode during screen sharing or pair programming
- Enable completion shelter mode to prevent accidental exposure in screenshots

🎨 Theme Integration

The plugin seamlessly integrates with your current colorscheme:

Element	Color Source
Variable names	`Identifier`
Types	`Type`
Values	`String`
Sources	`Directory`

🛠️ Author Setup

It's author's (philosofonusus) personal setup for ecolog.nvim if you don't want to think much of a setup and reading docs:

return {
  {
    'philosofonusus/ecolog.nvim',
    keys = {
      { '<leader>ge', '<cmd>EcologGoto<cr>', desc = 'Go to env file' },
      { '<leader>es', '<cmd>EcologSelect<cr>', desc = 'Switch env file' },
      { '<leader>eS', '<cmd>EcologShelterToggle<cr>', desc = 'Ecolog shelter toggle' },
    },
    dependencies = { 'nvim-telescope/telescope.nvim' },
    lazy = false,
    opts = {
      preferred_environment = 'local',
      types = true,
      integrations = {
        lspsaga = true, -- if you don't use lspsaga replace this line with lsp = true,
      },
      shelter = {
        configuration = {
          partial_mode = true,
          mask_char = '*',
        },
        modules = {
          files = true,
          peek = false,
          telescope = false,
          cmp = true,
        },
      },
      path = vim.fn.getcwd(),
    },
  },
}

🤝 Contributing

Contributions are welcome! Feel free to:

🐛 Report bugs
💡 Suggest features
🔧 Submit pull requests

📄 License

MIT License - See LICENSE for details.

Made with ❤️ by TENTACLE

Files

README.md

Latest commit

History

README.md

File metadata and controls

🌲 ecolog.nvim (Alpha)

Table of Contents

📦 Installation

Plugin Setup

✨ Features

🚀 Usage

Available Commands

📝 Environment File Priority

🔌 Environment File Priority

🔌 Shell Variables Integration

Basic Usage

Advanced Configuration

Configuration Options

Features

Best Practices

💡 Integrations

Nvim-cmp Integration

Blink-cmp Integration

LSP Integration (Experimental)

Setup

Features

Known Limitations

Disabling LSP Integration

LSP Saga Integration

Setup

Features

Example Configuration

Telescope Integration

🔧 Language Support

🟢 Currently Supported and Tested

🔴 Supported but Not Thoroughly Tested (may be broken)

🚧 Coming Soon

🔌 Custom Providers

Example: Adding Ruby Support

🛡️ Shelter Mode

🔧 Configuration

🎯 Features

Partial Masking

1. Completion Protection (cmp)

2. Peek Window Protection

3. File Content Protection

🎮 Commands

📝 Example

Partial Masking Examples

Telescope Integration

Usage

Features

Default Keymaps

🛡 Ecolog Types

Type Configuration

Custom Type Definition

💡 Tips

🎨 Theme Integration

🛠️ Author Setup

🤝 Contributing

📄 License