refactor: improve avante.nvim configuration with better environment variable handling and documentation

- Replace DEEPSEEK_API_KEY check with THIRD_PARTY_AI_ASSISTANT for more flexible AI integration
- Add comprehensive code comments and documentation for better maintainability
- Improve configuration structure and readability

lazy-lock.json

@@ -1,63 +1,51 @@
 {
-  "AstroNvim": { "branch": "main", "commit": "8246795ea910498211b7e14822bc7831bc015b5d" },
+  "AstroNvim": { "branch": "main", "commit": "55a2b084eabe880c4ffa377f82bb972caec57e09" },
-  "Comment.nvim": { "branch": "master", "commit": "e30b7f2008e52442154b66f7c519bfd2f1e32acb" },
   "LuaSnip": { "branch": "master", "commit": "458560534a73f7f8d7a11a146c801db00b081df0" },
-  "aerial.nvim": { "branch": "master", "commit": "d8343d0c935a72382413f9344ae0e39072405b7d" },
+  "aerial.nvim": { "branch": "master", "commit": "6ab1a0ce4874d21610fc5a67a6c82c7b943c635b" },
-  "alpha-nvim": { "branch": "main", "commit": "41283fb402713fc8b327e60907f74e46166f4cfd" },
+  "astrocommunity": { "branch": "main", "commit": "378c6d88f6648475057992709594b0ff5419c083" },
-  "astrocommunity": { "branch": "main", "commit": "5f74d5fb8d8dc9b8e2904846809121068d7afaca" },
+  "astrocore": { "branch": "main", "commit": "c797dd5a592e2bd154f2503e231b8a4083659534" },
-  "astrocore": { "branch": "main", "commit": "44a3dc0bf1591022b2a6bc89dccdfac1be17bec9" },
+  "astrolsp": { "branch": "main", "commit": "0befe28a4ea96e46b7f7c01e4a634c04225ba55a" },
-  "astrolsp": { "branch": "main", "commit": "fd2666a283af98182b1e8b01c85656071093a825" },
+  "astrotheme": { "branch": "main", "commit": "4a2af93815e4e6adfe69c836e46047a9451de858" },
-  "astrotheme": { "branch": "main", "commit": "ab0cb19c32181126f92b8239700cec97ba81b0fd" },
+  "astroui": { "branch": "main", "commit": "4943abbd42674b43249313afe83b91065a40e4be" },
-  "astroui": { "branch": "main", "commit": "e923a84c488d879a260fc9cfb2dc27dd870fb6ac" },
+  "avante.nvim": { "branch": "main", "commit": "7e50de89049ea3540f0d39acec7b68a74a5d1edb" },
-  "better-escape.nvim": { "branch": "master", "commit": "7e86edafb8c7e73699e0320f225464a298b96d12" },
+  "better-escape.nvim": { "branch": "master", "commit": "199dcc2643dec5d8dbdab4ec672cf405224dcb3b" },
-  "cmp-buffer": { "branch": "main", "commit": "3022dbc9166796b644a841a02de8dd1cc1d311fa" },
+  "blink-cmp-avante": { "branch": "master", "commit": "4f494c6e124acbe31a8f5d58effa0c14aa38a6d5" },
+  "blink.cmp": { "branch": "main", "commit": "327fff91fe6af358e990be7be1ec8b78037d2138" },
+  "blink.compat": { "branch": "main", "commit": "2ed6d9a28b07fa6f3bface818470605f8896408c" },
   "cmp-dap": { "branch": "master", "commit": "ea92773e84c0ad3288c3bc5e452ac91559669087" },
-  "cmp-nvim-lsp": { "branch": "main", "commit": "39e2eda76828d88b773cc27a3f61d2ad782c922d" },
+  "friendly-snippets": { "branch": "main", "commit": "572f5660cf05f8cd8834e096d7b4c921ba18e175" },
-  "cmp-path": { "branch": "main", "commit": "91ff86cd9c29299a64f968ebb45846c485725f23" },
+  "gitsigns.nvim": { "branch": "main", "commit": "7010000889bfb6c26065e0b0f7f1e6aa9163edd9" },
-  "cmp_luasnip": { "branch": "master", "commit": "05a9ab28b53f71d1aece421ef32fee2cb857a843" },
+  "guess-indent.nvim": { "branch": "main", "commit": "84a4987ff36798c2fc1169cbaff67960aed9776f" },
-  "dressing.nvim": { "branch": "master", "commit": "71349f24c6e07b39f33600985843c289ca735308" },
-  "friendly-snippets": { "branch": "main", "commit": "682157939e57bd6a2c86277dfd4d6fbfce63dbac" },
-  "gitsigns.nvim": { "branch": "main", "commit": "0b04035bb7b3c83e999b9676e2fb46fd0aa9f910" },
-  "guess-indent.nvim": { "branch": "main", "commit": "6c75506e71836f34fe5c5efa322dfce3e0494e7b" },
   "heirline.nvim": { "branch": "master", "commit": "fae936abb5e0345b85c3a03ecf38525b0828b992" },
-  "indent-blankline.nvim": { "branch": "master", "commit": "005b56001b2cb30bfa61b7986bc50657816ba4ba" },
   "lazy.nvim": { "branch": "main", "commit": "6c3bda4aca61a13a9c63f1c1d1b16b9d3be90d7a" },
-  "lspkind.nvim": { "branch": "master", "commit": "1735dd5a5054c1fb7feaf8e8658dbab925f4f0cf" },
+  "lazydev.nvim": { "branch": "main", "commit": "f59bd14a852ca43db38e3662395354cb2a9b13e0" },
   "mason-lspconfig.nvim": { "branch": "main", "commit": "1a31f824b9cd5bc6f342fc29e9a53b60d74af245" },
   "mason-null-ls.nvim": { "branch": "main", "commit": "2b8433f76598397fcc97318d410e0c4f7a4bea6a" },
   "mason-nvim-dap.nvim": { "branch": "main", "commit": "4c2cdc69d69fe00c15ae8648f7e954d99e5de3ea" },
   "mason-tool-installer.nvim": { "branch": "main", "commit": "517ef5994ef9d6b738322664d5fdd948f0fdeb46" },
-  "mason.nvim": { "branch": "main", "commit": "fc98833b6da5de5a9c5b1446ac541577059555be" },
+  "mason.nvim": { "branch": "main", "commit": "ad7146aa61dcaeb54fa900144d768f040090bff0" },
-  "mini.bufremove": { "branch": "main", "commit": "931a3bb514147d9e812767275c4beba6b779b1d3" },
+  "mini.icons": { "branch": "main", "commit": "397ed3807e96b59709ef3292f0a3e253d5c1dc0a" },
-  "neo-tree.nvim": { "branch": "main", "commit": "cea666ef965884414b1b71f6b39a537f9238bdb2" },
+  "neo-tree.nvim": { "branch": "main", "commit": "4c60a198e3f92098778a32a1c76d2bd7ba46a3b5" },
-  "neoconf.nvim": { "branch": "main", "commit": "054c602dcf143337151ecaa7fd4465ecfa7d27f0" },
+  "neoconf.nvim": { "branch": "main", "commit": "7a8d7fd36f95f5cbbf57d4a5c463f6c54ad54cd3" },
-  "neodev.nvim": { "branch": "main", "commit": "1f4ebcc10852518166ce165e57d425a4265a10d4" },
+  "none-ls.nvim": { "branch": "main", "commit": "6617d47fbf275d197e3335022a3d33ff310a4b93" },
-  "none-ls.nvim": { "branch": "main", "commit": "0d1b3fa2ad0b371b94cb4b9a27ba6e5a1a915c91" },
+  "nui.nvim": { "branch": "main", "commit": "f535005e6ad1016383f24e39559833759453564e" },
-  "nui.nvim": { "branch": "main", "commit": "a0fd35fcbb4cb479366f1dc5f20145fd718a3733" },
+  "nvim-autopairs": { "branch": "master", "commit": "23320e75953ac82e559c610bec5a90d9c6dfa743" },
-  "nvim-autopairs": { "branch": "master", "commit": "c15de7e7981f1111642e7e53799e1211d4606cb9" },
+  "nvim-dap": { "branch": "master", "commit": "7367cec8e8f7a0b1e4566af9a7ef5959d11206a7" },
-  "nvim-cmp": { "branch": "main", "commit": "a110e12d0b58eefcf5b771f533fc2cf3050680ac" },
+  "nvim-dap-ui": { "branch": "master", "commit": "cf91d5e2d07c72903d052f5207511bf7ecdb7122" },
-  "nvim-colorizer.lua": { "branch": "master", "commit": "85855b38011114929f4058efc97af1059ab3e41d" },
+  "nvim-highlight-colors": { "branch": "main", "commit": "e0c4a58ec8c3ca7c92d3ee4eb3bc1dd0f7be317e" },
-  "nvim-dap": { "branch": "master", "commit": "6f79b822997f2e8a789c6034e147d42bc6706770" },
+  "nvim-lspconfig": { "branch": "master", "commit": "fa2662510d30b06168b6e2e6915518decde6bbac" },
-  "nvim-dap-ui": { "branch": "master", "commit": "b7267003ba4dd860350be86f75b9d9ea287cedca" },
-  "nvim-lspconfig": { "branch": "master", "commit": "53a3c6444ec5006b567071614c83edc8ad651f6d" },
   "nvim-nio": { "branch": "master", "commit": "21f5324bfac14e22ba26553caf69ec76ae8a7662" },
-  "nvim-notify": { "branch": "master", "commit": "a3020c2cf4dfc4c4f390c4a21e84e35e46cf5d17" },
+  "nvim-treesitter": { "branch": "master", "commit": "42fc28ba918343ebfd5565147a42a26580579482" },
-  "nvim-treesitter": { "branch": "master", "commit": "ffd7725102f47e7391d7a5e7621d178689602a52" },
+  "nvim-treesitter-textobjects": { "branch": "master", "commit": "71385f191ec06ffc60e80e6b0c9a9d5daed4824c" },
-  "nvim-treesitter-textobjects": { "branch": "master", "commit": "34867c69838078df7d6919b130c0541c0b400c47" },
+  "nvim-ts-autotag": { "branch": "main", "commit": "c4ca798ab95b316a768d51eaaaee48f64a4a46bc" },
-  "nvim-ts-autotag": { "branch": "main", "commit": "ddfccbf0df1b9349c2b9e9b17f4afa8f9b6c1ed1" },
-  "nvim-ts-context-commentstring": { "branch": "main", "commit": "cb064386e667def1d241317deed9fd1b38f0dc2e" },
-  "nvim-ufo": { "branch": "main", "commit": "61463090a4f55f5d080236ea62f09d1cd8976ff3" },
-  "nvim-web-devicons": { "branch": "master", "commit": "c0cfc1738361b5da1cd0a962dd6f774cc444f856" },
   "nvim-window-picker": { "branch": "main", "commit": "6382540b2ae5de6c793d4aa2e3fe6dbb518505ec" },
-  "pendulum-nvim": { "branch": "main", "commit": "b884353d7c3e7a6fde477d8adcf0d0acf5ed077d" },
+  "pendulum-nvim": { "branch": "main", "commit": "c129ae3d69f164b3e51e067b0eca45a8d3da29ee" },
-  "plenary.nvim": { "branch": "master", "commit": "a3e3bc82a3f95c5ed0d7201546d5d2c19b20d683" },
+  "plenary.nvim": { "branch": "master", "commit": "b9fd5226c2f76c951fc8ed5923d85e4de065e509" },
-  "promise-async": { "branch": "main", "commit": "38a4575da9497326badd3995e768b4ccf0bb153e" },
   "resession.nvim": { "branch": "master", "commit": "cc819b0489938d03e4f3532a583354f0287c015b" },
   "smart-splits.nvim": { "branch": "master", "commit": "ddb23c1a1cf1507bda487cda7f6e4690965ef9f5" },
-  "telescope-fzf-native.nvim": { "branch": "main", "commit": "9ef21b2e6bb6ebeaf349a0781745549bbb870d27" },
+  "snacks.nvim": { "branch": "main", "commit": "da230e3ca8146da4b73752daaf0a1d07d343c12d" },
-  "telescope.nvim": { "branch": "master", "commit": "a0bbec21143c7bc5f8bb02e0005fa0b982edc026" },
+  "todo-comments.nvim": { "branch": "main", "commit": "304a8d204ee787d2544d8bc23cd38d2f929e7cc5" },
-  "todo-comments.nvim": { "branch": "main", "commit": "ae0a2afb47cf7395dc400e5dc4e05274bf4fb9e0" },
   "toggleterm.nvim": { "branch": "main", "commit": "50ea089fc548917cc3cc16b46a8211833b9e3c7c" },
-  "vim-illuminate": { "branch": "master", "commit": "5eeb7951fc630682c322e88a9bbdae5c224ff0aa" },
+  "vim-illuminate": { "branch": "master", "commit": "0d1e93684da00ab7c057410fecfc24f434698898" },
-  "which-key.nvim": { "branch": "main", "commit": "0539da005b98b02cf730c1d9da82b8e8edb1c2d2" }
+  "which-key.nvim": { "branch": "main", "commit": "fcbf4eea17cb299c02557d576f0d568878e354a4" }
 }

lua/community.lua

@@ -2,10 +2,72 @@
 -- We import this file in `lazy_setup.lua` before the `plugins/` folder.
 -- This guarantees that the specs are processed before any user plugins.
 
+--- @alias FrameworkModuleSpec { import: string }
+
+--- @alias FrameworkModules table<string, FrameworkModuleSpec[]>
+
+-- Framework-specific community module configurations
+--- @type FrameworkModules
+local FRAMEWORK_COMMUNITY_MODULES = {
+  -- Base Lua pack - always included
+  lua = {
+    { import = "astrocommunity.pack.lua" },
+  },
+
+  -- Vue.js framework modules
+  vue = {
+    { import = "astrocommunity.pack.vue" },
+  },
+}
+
+--- Retrieves the appropriate community modules based on the current framework environment
+--- @return LazySpec[] List of community modules to import for the detected framework
+local function get_framework_modules()
+  --- @type string|nil
+  local current_framework = os.getenv "FRAMEWORK"
+  --- @type LazySpec[]
+  local modules = {}
+
+  -- Always include base Lua pack
+  for _, module in ipairs(FRAMEWORK_COMMUNITY_MODULES.lua) do
+    table.insert(modules, module)
+  end
+
+  -- If framework is not set or empty string, use only base modules
+  if not current_framework or current_framework == "" then return modules end
+
+  -- Check if framework is valid (vue or python)
+  if current_framework ~= "vue" and current_framework ~= "python" then
+    error("Invalid framework: '" .. current_framework .. "'. Valid frameworks are: vue, python")
+  end
+
+  -- Add framework-specific modules if framework is valid
+  if FRAMEWORK_COMMUNITY_MODULES[current_framework] then
+    for _, module in ipairs(FRAMEWORK_COMMUNITY_MODULES[current_framework]) do
+      table.insert(modules, module)
+    end
+  end
+
+  return modules
+end
+
+--- Checks if third-party AI assistant is enabled and adds Avante-nvim if true
+--- @return LazySpec|nil Avante-nvim module if AI is enabled, nil otherwise
+local function get_ai_modules()
+  -- Check if third-party AI assistant is enabled
+  local ai_enabled = os.getenv "THIRD_PARTY_AI_ASSISTANT"
+  if ai_enabled and ai_enabled:lower() == "true" then return { import = "astrocommunity.completion.avante-nvim" } end
+  return nil
+end
+
 ---@type LazySpec
 return {
+  -- Base AstroCommunity plugin
   "AstroNvim/astrocommunity",
-  { import = "astrocommunity.pack.lua" },
+
-  -- { import = "astrocommunity.completion.avante-nvim" },
+  -- Framework-specific modules
-  -- import/override with your plugins folder
+  unpack(get_framework_modules()),
+
+  -- AI modules if enabled
+  get_ai_modules(),
 }

lua/plugins/avante-nvim.lua

@@ -1,26 +1,48 @@
-if true then return {} end -- WARN: REMOVE THIS LINE TO ACTIVATE THIS FILE
+-- Configuration module for avante.nvim plugin with DeepSeek API support
+-- Returns configuration only if THIRD_PARTY_AI_ASSISTANT environment variable is set
 
----@type LazySpec
+-- Check for the required environment variable containing the API key
+-- If the key is not set, returns an empty table and the plugin won't load
+local ai_enabled = os.getenv "THIRD_PARTY_AI_ASSISTANT"
+if not ai_enabled or ai_enabled:lower() ~= "true" then return {} end
+
+-- Main plugin configuration object
+---@type LazyPluginSpec[]
 return {
-  { -- further customize the options set by the community
+  {
+    -- Plugin identifier in GitHub repository
     "yetone/avante.nvim",
-    version = "0.0.23",
+    -- Plugin version for compatibility assurance
-    ---@type avante.Config
+    version = "0.0.27",
+    -- Plugin configuration options
+    -- Remove the type annotation if avante.Config is undefined
     opts = {
+      -- Primary AI provider for code generation
       provider = "deepseek",
+      -- Provider for automatic code suggestions (autocompletion)
       auto_suggestions_provider = "deepseek",
+      -- Plugin operation mode (commented out, uses default value)
       -- mode = "legacy",
+      -- Plugin behavior settings (commented out)
       -- behaviour = {
       --   auto_apply_diff_after_generation = false,
       --   auto_focus_on_diff_view = true,
       -- },
+      -- AI providers configuration
       providers = {
+        -- Specific configuration for DeepSeek provider
         deepseek = {
+          -- Inheritance of base configuration from OpenAI provider
           __inherited_from = "openai",
+          -- Environment variable name containing the API key
           api_key_name = "DEEPSEEK_API_KEY",
+          -- API endpoint for DeepSeek requests
           endpoint = "https://api.deepseek.com",
+          -- AI model to use (specialized for programming)
           model = "deepseek-coder",
+          -- Maximum number of tokens in model response
           max_tokens = 8192,
+          -- Tools disable flag (commented out)
           -- disable_tools = true,
         },
       },

lua/plugins/mason/.gitignore

@@ -1 +0,0 @@
-init.lua

lua/plugins/mason/init.lua

@@ -0,0 +1,47 @@
+-- Mason plugin configuration for automatic tool installation
+-- Dynamically installs tools based on the FRAMEWORK environment variable
+
+-- Framework-specific tool configurations
+local FRAMEWORK_TOOLS = {
+  python = {
+    "black",
+    "python-lsp-server",
+    "mypy",
+    "pylint",
+    "flake8",
+    "pylama",
+    "bandit",
+    "pydocstyle",
+    "pyproject-flake8",
+    "pyproject-fmt",
+    "reorder-python-imports",
+  },
+  vue = {
+    "eslint-lsp",
+    "stylelint-lsp",
+    "tailwindcss-language-server",
+    "typescript-language-server",
+    "vue-language-server",
+    "stylelint",
+    "prettier",
+  }
+}
+
+--- Retrieves the appropriate tool set based on the current framework environment
+--- @return table List of tools to install for the detected framework
+local function get_framework_tools()
+  local current_framework = os.getenv("FRAMEWORK")
+  return FRAMEWORK_TOOLS[current_framework] or {}
+end
+
+---@type LazySpec
+return {
+  -- Mason tool installer for automatic package management
+  {
+    "WhoIsSethDaniel/mason-tool-installer.nvim",
+    opts = {
+      -- Install tools based on the detected framework
+      ensure_installed = get_framework_tools(),
+    },
+  },
+}

lua/plugins/mason/python.lua

@@ -1,27 +0,0 @@
--- Customize Mason
-
----@type LazySpec
-return {
-  -- use mason-tool-installer for automatically installing Mason packages
-  {
-    "WhoIsSethDaniel/mason-tool-installer.nvim",
-    -- overrides `require("mason-tool-installer").setup(...)`
-    opts = {
-      -- Make sure to use the names found in `:Mason`
-      ensure_installed = {
-        -- { "vue-language-server", version = "1.8.27" },
-        "black",
-        "python-lsp-server",
-        "mypy",
-        "pylint",
-        "flake8",
-        "pylama",
-        "bandit",
-        "pydocstyle",
-        "pyproject-flake8",
-        "pyproject-fmt",
-        "reorder-python-imports",
-      },
-    },
-  },
-}

lua/plugins/mason/vue.lua

@@ -1,26 +0,0 @@
--- Customize Mason
-
----@type LazySpec
-return {
-  -- use mason-tool-installer for automatically installing Mason packages
-  {
-    "WhoIsSethDaniel/mason-tool-installer.nvim",
-    -- overrides `require("mason-tool-installer").setup(...)`
-    opts = {
-      -- Make sure to use the names found in `:Mason`
-      ensure_installed = {
-        -- lspconfig
-        "eslint-lsp",
-        "stylelint-lsp",
-        "tailwindcss-language-server",
-        "typescript-language-server",
-        "vue-language-server",
-        -- { "vue-language-server", version = "1.8.27" },
-
-        -- null_ls
-        "stylelint",
-        "prettier",
-      },
-    },
-  },
-}