docs(http-client.env): add docs for .private.json. (#251)

* docs(http-client.env): add docs for `.private.json`.

* docs(parser): fix comment

* feat(env): add support for http-client.private.env.json

* fix(docs): rename to `private.env.json`

See: https://www.jetbrains.com/help/idea/exploring-http-syntax.html#example-working-with-environment-files

* feat(schema): add `private.env.schema.json`

See: https://www.jetbrains.com/help/idea/exploring-http-syntax.html#example-working-with-environment-files

docs/docs/usage/dotenv-and-http-client.env.json-support.md

@@ -39,16 +39,20 @@ define environment variables in it.
 {
   "$schema": "https://raw.githubusercontent.com/mistweaverco/kulala.nvim/main/schemas/http-client.env.schema.json",
   "dev": {
-    "API_KEY": "your-api-key"
+    "API_URL": "https://httpbin.org/post?env=dev",
+    "API_KEY": ""
   },
   "testing": {
-    "API_KEY": "your-api-key"
+    "API_URL": "https://httpbin.org/post?env=testing",
+    "API_KEY": ""
   },
   "staging": {
-    "API_KEY": "your-api-key"
+    "API_URL": "https://httpbin.org/post?env=staging",
+    "API_KEY": ""
   },
   "prod": {
-    "API_KEY": "your-api-key"
+    "API_URL": "https://httpbin.org/post?env=prod",
+    "API_KEY": ""
   }
 }
 ```
@@ -74,11 +78,44 @@ command to select an environment using a telescope prompt.
 
 :::
 
+As you can see in the example above,
+we defined the `API_URL` and `API_KEY` environment variables,
+but left the `API_KEY` empty.
+
+This is by intention, because we can define the `API_KEY` in the
+`http-client.private.env.json` file.
+
+:::danger
+
+You should never commit sensitive data like API keys to your repository.
+So always use the `http-client.private.env.json` file for that and
+add it to your `.gitignore` file.
+
+:::
+
+```json title="http-client.private.env.json"
+{
+  "$schema": "https://raw.githubusercontent.com/mistweaverco/kulala.nvim/main/schemas/http-client.private.env.schema.json",
+  "dev": {
+    "API_KEY": "d3v"
+  },
+  "testing": {
+    "API_KEY": "t3st1ng"
+  },
+  "staging": {
+    "API_KEY": "st4g1ng"
+  },
+  "prod": {
+    "API_KEY": "pr0d"
+  }
+}
+```
+
 Then, you can reference the environment variables
 in your HTTP requests like this:
 
 ```http title="examples.http"
-POST https://httpbin.org/post HTTP/1.1
+POST {{API_URL}} HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{API_KEY}}
 
@@ -104,7 +141,8 @@ the `$default_headers` will be merged with the headers from the HTTP requests.
     },
   },
   "dev": {
-    "API_KEY": "your-api-key"
+    "API_URL": "https://httpbin.org/post?env=dev",
+    "API_KEY": ""
   }
 }
 ```
@@ -129,14 +167,15 @@ define environment variables in it.
 The file should look like this:
 
 ```env title=".env"
+API_URL=https://httpbin.org/post
 API_KEY=your-api-key
 ```
 
 Then, you can reference the environment variables
 in your HTTP requests like this:
 
 ```http title="examples.http"
-POST https://httpbin.org/post HTTP/1.1
+POST {{API_URL}} HTTP/1.1
 Content-Type: application/json
 Authorization: Bearer {{API_KEY}}
 

lua/kulala/parser/env.lua

@@ -6,6 +6,7 @@ local M = {}
 
 M.get_env = function()
   local http_client_env_json = FS.find_file_in_parent_dirs("http-client.env.json")
+  local http_client_private_env_json = FS.find_file_in_parent_dirs("http-client.private.env.json")
   local dotenv = FS.find_file_in_parent_dirs(".env")
   local env = {}
 
@@ -76,6 +77,16 @@ M.get_env = function()
     DB.update().http_client_env = vim.tbl_deep_extend("force", DB.find_unique("http_client_env"), f)
   end
 
+  if http_client_private_env_json then
+    local f = vim.fn.json_decode(vim.fn.readfile(http_client_private_env_json))
+    if f["$shared"] then
+      DB.update().http_client_env_shared =
+        vim.tbl_deep_extend("force", DB.find_unique("http_client_env_shared"), f["$shared"])
+    end
+    f["$shared"] = nil
+    DB.update().http_client_env = vim.tbl_deep_extend("force", DB.find_unique("http_client_env"), f)
+  end
+
   local http_client_env_shared = DB.find_unique("http_client_env_shared") or {}
   for key, value in pairs(http_client_env_shared) do
     if key ~= "$default_headers" then

lua/kulala/parser/init.lua

@@ -570,7 +570,7 @@ function M.parse(start_request_linenr)
     -- check if we are a graphql query
     -- we need this here, because the user could have defined the content-type
     -- as application/json, but the body is a graphql query
-    -- This can happen when the user is using http-client.env.json with DEFAULT_HEADERS.
+    -- This can happen when the user is using http-client.env.json with $shared -> $default_headers.
     if is_graphql then
       local gql_json = GRAPHQL_PARSER.get_json(res.body)
       if gql_json then

schemas/http-client.private.env.schema.json

@@ -0,0 +1,43 @@
+{
+  "$id": "https://raw.githubusercontent.com/mistweaverco/kulala.nvim/main/schemas/http-client.private.env.schema.json",
+  "title": "HTTP Client Private Environment Variables",
+  "description": "The private environment variables required for the HTTP client",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "$shared": {
+      "type": "object",
+      "properties": {
+        "$default_headers": {
+          "type": "object",
+          "patternProperties": {
+            "^.*$": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        }
+      },
+      "patternProperties": {
+        "^([A-Za-z0-9_]+)$": {
+          "type": ["string", "number"]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "patternProperties": {
+    "^.*$": {
+      "type": "object",
+      "patternProperties": {
+        "^([A-Za-z0-9_]+)$": {
+          "type": ["string", "number"]
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false
+}