capistrano-node-dotenv 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: fd4e85e20f0d755f17df29ea83a5e1de85c2b79431e55fb88aaa8a0b40b4d96a
+  data.tar.gz: 406b1bd86cd41345fd1c3521712465cc7441eb6c6b963dffd920fc55a024a0d3
+SHA512:
+  metadata.gz: 52723bdc7a45285bb5ec6599fd0f63cbdcdab0140a27580699a36ee8e0f4445161bcf86ba218f770383f2936b978799fdb4019f328b334552fc7b15bee920ee6
+  data.tar.gz: cf4705e7b70b3bf1d339b3db871302b386ea43be90ac11c09ac096116cbd6ccf45cf8da6a91a730339c739e00e167cdd1e1cbe34811a69ba6dd880c3d446013e

data/.github/workflows/release.yml

@@ -0,0 +1,25 @@
+name: Release
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: write
+  id-token: write
+
+jobs:
+  publish:
+    name: Push gem to RubyGems.org
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+
+      - uses: rubygems/release-gem@v1

data/.gitignore

@@ -0,0 +1,10 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.gem

data/.rubocop.yml

@@ -0,0 +1,88 @@
+# RuboCop configuration for ms-graph-mailer gem
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+  SuggestExtensions: false
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+
+# Metrics
+
+Metrics/BlockLength:
+  Max: 50
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Metrics/ClassLength:
+  Max: 150
+
+Metrics/MethodLength:
+  Max: 40
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/AbcSize:
+  Max: 65
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+# Style
+
+Style/Documentation:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: single_quotes
+
+Style/FrozenStringLiteralComment:
+  Enabled: true
+  EnforcedStyle: always
+
+Style/TrailingCommaInArrayLiteral:
+  EnforcedStyleForMultiline: no_comma
+
+Style/TrailingCommaInHashLiteral:
+  EnforcedStyleForMultiline: no_comma
+
+Style/TrailingCommaInArguments:
+  EnforcedStyleForMultiline: no_comma
+
+# Layout
+
+Layout/LineLength:
+  Max: 150
+  AllowedPatterns:
+    - '\s+# '
+
+Layout/EmptyLinesAroundAttributeAccessor:
+  Enabled: true
+
+Layout/SpaceAroundMethodCallOperator:
+  Enabled: true
+
+# Lint
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Gemspec/RequireMFA:
+  Enabled: false
+
+Lint/RaiseException:
+  Enabled: true
+
+Lint/StructNewOverride:
+  Enabled: true

data/.ruby-version

@@ -0,0 +1 @@
+3.3.5

data/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2026-03-02
+
+### Added
+
+- Initial release
+- `dotenv:setup` – upload local `config/application.yml` to the remote shared folder as a `.env` file
+- `dotenv:update` – interactively compare local config with remote `.env` and push selected changes
+- `dotenv:get` – interactively compare remote `.env` with local config and pull selected changes
+- `dotenv:init` – bootstrap local `config/application.yml` by pulling `.env` files from all stages
+- `dotenv:show` – print the content of the remote `.env` file for the current stage
+- `dotenv:backup` – create a timestamped backup of the remote `.env` file (retains latest 5)
+- `dotenv:rollback` – restore the remote `.env` from the most recent backup
+- `dotenv:check` – pre-deploy checks (file exists, not git-tracked, stage config present)
+- Automatic symlinking of the remote `.env` via `deploy:started` hook
+- Section-marker format in generated `.env` files for deterministic parsing (`# Begin/End <stage> envs`)
+- `Parser` module for reading and writing section-annotated `.env` files
+- `Helpers` module with backup management, hash diffing, and interactive prompts
+- `Paths` module for resolving local and remote file paths via Capistrano `fetch`

data/Gemfile

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in capistrano-ops.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 zauberware
+
+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.

data/README.md

@@ -0,0 +1,235 @@
+# capistrano-node-dotenv
+
+A [Capistrano](https://capistranorb.com/) plugin for managing `.env` files on remote servers running Node.js applications. It handles uploading, syncing, backing up, and rolling back the `.env` file that lives in your deployment's shared folder.
+
+## Table of Contents
+
+<details>
+<summary>Click to expand</summary>
+
+- [How it works](#how-it-works)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Tasks](#tasks)
+  - [dotenv:setup](#dotenvsetup)
+  - [dotenv:update](#dotenvupdate)
+  - [dotenv:get](#dotenvget)
+  - [dotenv:init](#dotenvinit)
+  - [dotenv:show](#dotenvshow)
+  - [dotenv:backup](#dotenvbackup)
+  - [dotenv:rollback](#dotenvrollback)
+  - [dotenv:check](#dotenvcheck)
+- [Automatic symlinking](#automatic-symlinking)
+- [Backup behaviour](#backup-behaviour)
+- [Requirements](#requirements)
+- [Contributing](#contributing)
+- [License](#license)
+
+</details>
+
+## How it works
+
+The gem stores your environment configuration locally in `config/application.yml` — a YAML file where top-level keys are global variables and nested keys are stage-specific variables. On deploy, the relevant keys are extracted, assembled into a proper `.env` file, and uploaded to the server's shared folder. The `.env` file is automatically added to Capistrano's `linked_files` so it gets symlinked into each release.
+
+### Local config format (`config/application.yml`)
+
+```yaml
+# Global variables shared across all stages
+DATABASE_URL: postgres://localhost/myapp
+
+# Stage-specific variables
+production:
+  NODE_ENV: production
+  API_KEY: secret-prod
+
+staging:
+  NODE_ENV: staging
+  API_KEY: secret-staging
+```
+
+### Remote `.env` file format
+
+The generated `.env` file uses section markers so the gem can parse it back:
+
+```
+# Begin global envs 2026-03-02 10:00:00
+DATABASE_URL=postgres://localhost/myapp
+# End global envs 2026-03-02 10:00:00
+# Begin production envs 2026-03-02 10:00:00
+NODE_ENV=production
+API_KEY=secret-prod
+# End production envs 2026-03-02 10:00:00
+```
+
+[↑](#)
+
+## Installation
+
+Add to your `Gemfile`:
+
+```ruby
+gem 'capistrano-node-dotenv'
+```
+
+Then run:
+
+```bash
+bundle install
+```
+
+Require the gem in your `Capfile`:
+
+```ruby
+require 'capistrano/node/dotenv'
+```
+
+Make sure `config/application.yml` is **not** tracked by git:
+
+```bash
+git rm --cached config/application.yml
+echo 'config/application.yml' >> .gitignore
+```
+
+[↑](#)
+
+## Configuration
+
+Set these variables in `config/deploy.rb` or a stage file. All have sensible defaults.
+
+| Variable               | Default                               | Description                                              |
+| ---------------------- | ------------------------------------- | -------------------------------------------------------- |
+| `dotenv_local_path`    | `config/application.yml`              | Path to the local YAML config file                       |
+| `dotenv_remote_path`   | `.env`                                | Path to the `.env` file relative to the shared folder    |
+| `dotenv_env`           | `fetch(:node_env) \|\| fetch(:stage)` | The environment/stage key to extract from the local YAML |
+| `dotenv_remote_backup` | `false`                               | Whether to automatically back up on deploy               |
+
+Example:
+
+```ruby
+# config/deploy.rb
+set :dotenv_local_path,  'config/application.yml'
+set :dotenv_remote_path, '.env'
+set :dotenv_env,         -> { fetch(:stage) }
+```
+
+[↑](#)
+
+## Tasks
+
+```
+cap dotenv:setup      # Upload local config/application.yml to the server (first-time or full overwrite)
+cap dotenv:update     # Compare local vs remote .env interactively and push selected changes
+cap dotenv:get        # Compare remote vs local .env and optionally pull remote values into local
+cap dotenv:init       # Build local config/application.yml by pulling .env files from all stages
+cap dotenv:show       # Print the content of the remote .env file for the current stage
+cap dotenv:backup     # Create a timestamped backup of the remote .env file (keeps latest 5)
+cap dotenv:rollback   # Roll back the remote .env file to the most recent backup
+cap dotenv:check      # Run all pre-deploy checks (file exists, not git-tracked, stage config present)
+```
+
+### dotenv:setup
+
+Reads `config/application.yml`, extracts global keys and stage-specific keys, generates a `.env` file with section markers, and uploads it to `shared/<dotenv_remote_path>`. Use this the first time you deploy or when you want to fully overwrite the remote file.
+
+```bash
+cap production dotenv:setup
+```
+
+### dotenv:update
+
+Compares your local `config/application.yml` with the current remote `.env`. Displays any differences and interactively asks whether to overwrite the remote globals and/or stage section. Automatically creates a backup before writing.
+
+```bash
+cap production dotenv:update
+```
+
+### dotenv:get
+
+The reverse of `dotenv:update`. Compares the remote `.env` with your local file and interactively asks whether to pull remote values back into `config/application.yml`.
+
+```bash
+cap production dotenv:get
+```
+
+### dotenv:init
+
+Iterates over all configured Capistrano stages, downloads each stage's `.env` file, and merges everything into a local `config/application.yml`. Useful for bootstrapping a fresh local environment from existing servers.
+
+```bash
+cap production dotenv:init
+```
+
+### dotenv:show
+
+Prints the raw content of the remote `.env` file to stdout.
+
+```bash
+cap production dotenv:show
+```
+
+### dotenv:backup
+
+Creates a timestamped backup (e.g. `.env-2026-03-02-10-00-00.bak`) in the shared folder. Automatically removes older backups, keeping only the 5 most recent.
+
+```bash
+cap production dotenv:backup
+```
+
+### dotenv:rollback
+
+Restores the remote `.env` from the most recent `.bak` file. Does nothing if no backup exists.
+
+```bash
+cap production dotenv:rollback
+```
+
+### dotenv:check
+
+Runs three pre-deploy checks in sequence:
+
+1. **`check_dotenv_file_exists`** – Verifies that `config/application.yml` exists locally.
+2. **`check_git_tracking`** – Ensures the file is not accidentally committed to git.
+3. **`check_config_present`** – Confirms that the current stage's config is not empty.
+
+```bash
+cap production dotenv:check
+```
+
+[↑](#)
+
+## Automatic symlinking
+
+The gem hooks into `deploy:started` and automatically adds the remote `.env` path to `linked_files`. No manual configuration in `deploy.rb` is needed — the file will be symlinked into every release directory.
+
+[↑](#)
+
+## Backup behaviour
+
+- Backups are named `<filename>-YYYY-MM-DD-HH-MM-SS.bak` and stored next to the `.env` in the shared folder.
+- At most 5 backups are retained; older ones are deleted automatically.
+- `dotenv:update` always creates a backup before writing to the remote file.
+
+[↑](#)
+
+## Requirements
+
+- Ruby `>= 3.1.4, < 3.4.0`
+- Capistrano 3.x
+
+[↑](#)
+
+## Contributing
+
+1. Fork it ( https://github.com/zauberware/capistrano-node-dotenv/fork )
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+[↑](#)
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).
+
+[↑](#)

data/Rakefile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+namespace :version do
+  desc 'Bump patch version (0.1.0 -> 0.1.1)'
+  task :patch do
+    ruby 'scripts/bump_version.rb patch'
+  end
+
+  desc 'Bump minor version (0.1.0 -> 0.2.0)'
+  task :minor do
+    ruby 'scripts/bump_version.rb minor'
+  end
+
+  desc 'Bump major version (0.1.0 -> 1.0.0)'
+  task :major do
+    ruby 'scripts/bump_version.rb major'
+  end
+end

data/capistrano-node-dotenv.gemspec

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.push File.expand_path('lib', __dir__)
+
+require 'capistrano/node/dotenv/version'
+
+Gem::Specification.new do |s|
+  s.name          = 'capistrano-node-dotenv'
+  s.version       = Capistrano::Node::Dotenv::VERSION
+  s.platform      = Gem::Platform::RUBY
+  s.authors       = ['Florian Crusius']
+  s.email         = ['florian@zauberware.com']
+  s.license       = 'MIT'
+  s.homepage      = 'https://github.com/zauberware/capistrano-node-dotenv'
+  s.summary       = 'dotenv tasks for node applications'
+  s.description   = 'A collection of dotenv tasks for node applications'
+  s.files         = `git ls-files`.split("\n")
+  s.executables   = `git ls-files -- bin/*`.split("\n").map { |f| File.basename(f) }
+  s.require_paths = ['lib']
+
+  s.required_ruby_version = '>= 3.1.4', '< 3.4.0'
+  s.add_development_dependency 'bundler', '~> 2.0'
+  s.add_development_dependency 'rake', '~> 13.0'
+  s.add_development_dependency 'rspec', '~> 3.0'
+  s.add_development_dependency 'rubocop', '~> 1.0'
+  s.add_development_dependency 'rubocop-rake', '~> 0.6'
+  s.add_development_dependency 'rubocop-rspec', '~> 2.0'
+end

data/lib/capistrano/node/dotenv/helpers.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module Capistrano
+  module Node
+    module Dotenv
+      module Helpers
+        def remote_file_exists?
+          test("[ -f #{dotenv_remote_path} ]")
+        end
+
+        def remote_backup_exists?
+          count_remote_files.positive?
+        end
+
+        def rollback_remote_backup
+          latest_backup = latest_remote_backup
+          puts "mv #{dotenv_remote_path.parent.join(latest_backup)} #{dotenv_remote_path}"
+          execute :mv, dotenv_remote_path.parent.join(latest_backup), dotenv_remote_path
+          execute :ls, '-la', dotenv_remote_path.parent
+        end
+
+        def latest_remote_backup
+          command = "ls -a1t #{dotenv_remote_path.parent} | grep -E '#{backup_regex}' | head -n 1"
+          capture(command).strip
+        end
+
+        def backup_regex
+          # filename we are looking for "#{dotenv_remote_path.basename}-yyyy-mm-dd-HH-MM-SS.bak"
+          "#{dotenv_remote_path.basename}-[0-9]{4}-[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{2}-[0-9]{2}.bak"
+        end
+
+        def count_remote_files
+          command = "ls -a1 #{dotenv_remote_path.parent} | grep -E '#{backup_regex}' | wc -l"
+          capture(command).to_i
+        end
+
+        def create_remote_backup
+          backup_file = "#{dotenv_remote_path.basename}-#{Time.now.strftime('%Y-%m-%d-%H-%M-%S')}.bak"
+          # puts "cp #{dotenv_remote_path} #{dotenv_remote_path.parent.join(backup_file)}"
+          execute :cp, dotenv_remote_path, dotenv_remote_path.parent.join(backup_file)
+        end
+
+        def cleanup_remote_backups
+          number_of_backups = count_remote_files
+          return unless number_of_backups > 5
+
+          diff = number_of_backups - 5
+          # remove older backups and keep the latest 5
+          command = "ls -a1t #{dotenv_remote_path.parent} | grep -E '#{backup_regex}' | tail -n #{diff}"
+
+          capture(command).split("\n").each do |file|
+            execute "rm #{dotenv_remote_path.parent.join(file)}"
+          end
+        end
+
+        def local_dotenv(_env)
+          @local_dotenv ||= YAML.load(ERB.new(File.read(dotenv_local_path)).result)
+
+          @local_dotenv || {}
+        end
+
+        def local_yaml
+          YAML.safe_load_file(dotenv_local_path) || {}
+        end
+
+        def dotenv_env
+          fetch(:dotenv_env).to_s
+        end
+
+        def dotenv_content
+          local_dotenv(dotenv_env).to_yaml
+        end
+
+        def configs(yaml, env)
+          env_str = env.to_s
+          stage_yml = yaml[env_str]&.sort.to_h
+          global_yml = remove_nested(yaml)&.sort.to_h
+
+          other_stages_yml = stages.each_with_object({}) do |f, hash|
+            f_str = f.to_s
+            next if f_str == env_str
+
+            hash[f_str] = yaml[f_str]&.sort.to_h
+          end.compact
+
+          [global_yml, stage_yml, other_stages_yml]
+        end
+
+        def remove_nested(hash)
+          hash.each_with_object({}) do |(key, value), new_hash|
+            new_hash[key] = value unless value.is_a?(Hash)
+          end
+        end
+
+        def sort_with_nested(hash)
+          hash.each_with_object({}) do |(key, value), new_hash|
+            new_hash[key] = value.is_a?(Hash) ? sort_with_nested(value) : value
+          end.sort.to_h
+        end
+
+        def compare_hashes(hash1, hash2)
+          all_keys = hash1.keys | hash2.keys # Union of all keys from both hashes
+          all_keys.each_with_object({}) do |key, changes_hash|
+            old_value = hash2[key].nil? ? 'nil' : hash2[key].to_s
+            new_value = hash1[key].nil? ? 'nil' : hash1[key].to_s
+
+            changes_hash[key] = { old: old_value, new: new_value } if old_value != new_value
+          end.tap { |changes| return changes.empty? ? nil : changes }
+        end
+
+        # selection helpers
+        def ask_to_overwrite(question)
+          answer = ''
+          until %w[y n].include?(answer)
+            print "#{question}? (y/N): "
+            answer = $stdin.gets.strip.downcase
+          end
+          answer == 'y'
+        end
+
+        # info helpers
+
+        def print_changes(changes, message)
+          return unless changes
+
+          puts "#{message}:\n\n"
+          changes.each do |key, diff|
+            puts "#{key}: #{diff[:old]} => #{diff[:new]}"
+          end
+          puts "\n"
+        end
+
+        # error helpers
+
+        def check_git_tracking_error
+          puts
+          puts "Error - please remove '#{fetch(:dotenv_local_path)}' from git:"
+          puts
+          puts "    $ git rm --cached #{fetch(:dotenv_local_path)}"
+          puts
+          puts 'and gitignore it:'
+          puts
+          puts "    $ echo '#{fetch(:dotenv_local_path)}' >> .gitignore"
+          puts
+        end
+
+        def check_config_present_error
+          puts
+          puts "Error - '#{dotenv_env}' config not present in '#{fetch(:dotenv_local_path)}'."
+          puts 'Please populate it.'
+          puts
+        end
+
+        def check_dotenv_file_exists_error
+          puts
+          puts "Error - '#{fetch(:dotenv_local_path)}' file does not exists, and it's required."
+          puts
+        end
+
+        # file helpers
+        def write_to_file(file, content)
+          File.write(file, content)
+        end
+
+        def write_combined_yaml(yamls_combined)
+          if yamls_combined.empty?
+            info 'No data to write.'
+          else
+            # write to new file
+            info 'writing to config/application.yml'
+            write_to_file(dotenv_local_path, yamls_combined.to_yaml)
+          end
+        end
+      end
+    end
+  end
+end