envsafe 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 65634c2098bf1fa34dd0b3ef2c127cd4c4f3a1390a05f3ab2f6a58828692efbb
+  data.tar.gz: 8cf9215b84fcf108b6eba6bdc9af69c7f7b35422e068c3c4174e36b37f79cd02
+SHA512:
+  metadata.gz: e2a80fa8cfa100525f2a11c767089a80dcfa51de22c93ded2291f9a401872fef347940378f18a1dd614d09402ff5504c582be0201ab150f536c79d4585445b33
+  data.tar.gz: 35f51b8ab9ab3de95ca9807b1301c250eb7f465101d5987a96755ed42a315e831ad53f9453a881e07d090538443e63b26c79f2ddcbb7be410787db181acced68

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Kaiser Sakhi
+
+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,201 @@
+# Envsafe
+
+A Ruby CLI tool for safely managing and versioning your `.env` files. Envsafe provides backup, restore, and history management capabilities to prevent accidental loss of environment variables.
+
+## Features
+
+- 📁 **Backup Management**: Create tagged or automatic backups of your `.env` files
+- 🔄 **Restore System**: Restore any previous backup by tag or index
+- 📋 **History Tracking**: List all backups with timestamps and tags
+- ⏪ **Undo Operations**: Quickly undo the last write operation
+- 👀 **File Preview**: View contents of any backup without restoring
+- 🗑️ **Selective Cleanup**: Delete specific backups or clear all history
+- 🔒 **Git Integration**: Automatically add `.envsafe` to your `.gitignore`
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'envsafe'
+```
+
+And then execute:
+
+```bash
+$ bundle install
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install envsafe
+```
+
+## Usage
+
+### Basic Commands
+
+#### Backup your .env file
+
+```bash
+# Create a backup with automatic timestamp
+$ envsafe backup
+
+# Create a tagged backup for easy identification
+$ envsafe backup --tag "before-production-deploy"
+$ envsafe backup -t "pre-feature-update"
+```
+
+#### List all backups
+
+```bash
+# Show all backups
+$ envsafe list
+
+# Limit the number of backups shown
+$ envsafe list 5
+```
+
+#### Restore a backup
+
+```bash
+# Restore by tag
+$ envsafe restore --tag "before-production-deploy"
+$ envsafe restore -t "pre-feature-update"
+
+# Restore by stack index (use 'list' command to see indices)
+$ envsafe restore --sindex 0
+$ envsafe restore -i 2
+```
+
+#### Quick undo
+
+```bash
+# Undo the last write operation to .env
+$ envsafe undo
+```
+
+### Advanced Commands
+
+#### View backup contents
+
+```bash
+# Show contents by tag
+$ envsafe show --tag "production-config"
+$ envsafe show -t "staging-setup"
+
+# Show contents by stack index
+$ envsafe show --sindex 0
+$ envsafe show -i 1
+```
+
+#### Delete specific backups
+
+```bash
+# Delete by tag
+$ envsafe delete --tag "old-config"
+$ envsafe delete -t "temporary-backup"
+
+# Delete by stack index
+$ envsafe delete --sindex 3
+$ envsafe delete -i 0
+```
+
+#### Cleanup operations
+
+```bash
+# Delete all backups
+$ envsafe clear
+
+# Add .envsafe directory to .gitignore
+$ envsafe ignore
+```
+
+## Command Reference
+
+| Command        | Description                                | Options                                                                           |
+| -------------- | ------------------------------------------ | --------------------------------------------------------------------------------- |
+| `backup`       | Create a backup of current `.env` file     | `-t, --tag TAG` - Optional tag for the backup                                     |
+| `list [LIMIT]` | List all backups, optionally limit results | `LIMIT` - Number of backups to show                                               |
+| `restore`      | Restore a specific backup to `.env`        | `-t, --tag TAG` - Restore by tag<br>`-i, --sindex INDEX` - Restore by stack index |
+| `undo`         | Undo last write operation to `.env`        | None                                                                              |
+| `show`         | Show contents of a backup file             | `-t, --tag TAG` - Show by tag<br>`-i, --sindex INDEX` - Show by stack index       |
+| `delete`       | Delete a specific backup                   | `-t, --tag TAG` - Delete by tag<br>`-i, --sindex INDEX` - Delete by stack index   |
+| `clear`        | Delete all backups                         | None                                                                              |
+| `ignore`       | Add `.envsafe` to `.gitignore`             | None                                                                              |
+
+## Workflow Examples
+
+### Development Workflow
+
+```bash
+# Before making changes
+$ envsafe backup -t "stable-config"
+
+# Make your changes to .env
+$ vim .env
+
+# If something goes wrong, quickly undo
+$ envsafe undo
+
+# Or restore the tagged backup
+$ envsafe restore -t "stable-config"
+```
+
+### Deployment Workflow
+
+```bash
+# Backup before deployment
+$ envsafe backup -t "pre-deploy-$(date +%Y%m%d)"
+
+# Deploy and update environment variables
+# ... deployment process ...
+
+# If rollback needed
+$ envsafe restore -t "pre-deploy-20240108"
+```
+
+### Team Collaboration
+
+```bash
+# Setup git ignore for the team
+$ envsafe ignore
+
+# Create backups with descriptive tags
+$ envsafe backup -t "feature-auth-setup"
+$ envsafe backup -t "database-migration-config"
+
+# Share backup strategies in documentation
+$ envsafe list
+```
+
+## File Structure
+
+Envsafe stores backups in a `.envsafe` directory in your project root:
+
+```
+your-project/
+├── .env
+├── .envsafe/
+│   ├── backup-001.env
+│   ├── backup-002.env
+│   └── metadata.json
+└── .gitignore
+```
+
+## Best Practices
+
+1. **Tag Important Backups**: Use descriptive tags for backups before major changes
+2. **Regular Cleanup**: Periodically review and clean old backups with `envsafe clear`
+3. **Git Ignore**: Always run `envsafe ignore` to prevent committing backup files
+4. **Pre-deployment**: Create tagged backups before deployments for easy rollback
+5. **Team Coordination**: Establish tagging conventions for team projects
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/yourusername/envsafe.
+
+## License
+
+The gem is available as open source under the terms of the MIT License.

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/envsafe

@@ -0,0 +1,3 @@
+#!/usr/bin/env ruby
+
+require "envsafe"

data/lib/envsafe/back_stack.rb

@@ -0,0 +1,171 @@
+require_relative "constants"
+require_relative "file_store"
+
+"""
+
+stack_entry = {
+  :file
+  :tag
+  :timestamp
+}
+
+"""
+
+class Envsafe::BackStack
+  class << self
+    def stack
+      stack_instance
+    end
+
+    # Restores last backuped up file
+    def pop()
+      if stack_instance.nil? || stack_instance.size.zero?
+        puts "There are no backups to restore."
+
+        return
+      end
+
+      entry = stack_instance.shift
+
+      if Envsafe::FileStore.restore(entry)
+        write()
+        puts "✅ Successfully retored the last backup"
+
+      else
+        stack_instance.unshift(entry)
+
+        puts "❌ Something went wrong will retoring the last backup."
+      end
+    end
+
+    def push(tag)
+      unless File.exist?(Envsafe::ENV_FILE)
+        puts "❌ No .env file found in current directory."
+        return
+      end
+
+
+      filename, timestamp = Envsafe::FileStore.new_filename(tag)
+
+      Envsafe::FileStore.copy_env(filename)
+
+      push_entry(filename, tag, timestamp)
+
+      puts "✅ Backed up .env as #{filename}"
+    end
+
+    def restore_by_tag(tag)
+      entry = stack_instance.find { |e| e["tag"] == tag }
+
+      return nil if entry.nil?
+
+      Envsafe::FileStore.restore(entry)
+
+      true
+    end
+
+    def restore_by_sindex(sindex)
+      entry = stack_instance[sindex]
+
+      Envsafe::FileStore.restore(entry)
+
+      true
+    end
+
+    def restore_top
+      return nil if stack_instance.empty?
+
+      entry = stack_instance[0]
+
+      Envsafe::FileStore.restore(entry)
+
+      true
+    end
+
+    def show_top()
+      return if stack_instance.empty?
+
+      stack_entry = stack_instance[0]
+
+      file_content = Envsafe::FileStore.file_content(stack_entry)
+
+      Envsafe::Utils.print_with_less(file_content)
+    end
+
+    def show_by_tag(tag)
+      stack_entry = stack_instance.find { |se| se["tag"] == tag }
+
+      file_content = Envsafe::FileStore.file_content(stack_entry)
+
+      Envsafe::Utils.print_with_less(file_content)
+    end
+
+    def show_by_sindex(sindex)
+      stack_entry = stack_instance[sindex]
+
+      file_content = Envsafe::FileStore.file_content(stack_entry)
+
+      Envsafe::Utils.print_with_less(file_content)
+    end
+
+    def remove_by_sindex(sindex)
+      stack_entry = stack_instance[sindex]
+
+      if Envsafe::FileStore.delete_backup(stack_entry)
+        stack_instance = stack_instance.reject { |se| se == stack_entry }
+
+        write()
+
+        true
+      else
+        false
+      end
+    end
+
+    def remove_by_tag(tag)
+      stack_entry = stack_instance.find { |se| se["tag"] == tag }
+
+
+      if Envsafe::FileStore.delete_backup(stack_entry)
+        stack_instance = stack_instance.reject { |se| se == stack_entry }
+
+        write()
+
+        true
+      else
+        false
+      end
+    end
+
+    private
+
+    def push_entry(filename, tag, timestamp)
+      entry = {
+        "file" => filename,
+        "tag" => tag,
+        "timestamp" => timestamp
+      }
+
+      stack_instance.unshift(entry)
+
+      write()
+    end
+
+    def stack_instance
+      @stack_instance ||= read() || []
+    end
+
+    def read
+      return unless File.exist?(Envsafe::STACK_FILE)
+
+      stk_content = File.read(Envsafe::STACK_FILE)
+
+      JSON.parse(stk_content)
+    end
+
+    # Writes stack_instace to stack.json
+    def write
+      File.write(Envsafe::STACK_FILE, JSON.pretty_generate(stack_instance))
+    end
+  end
+end

data/lib/envsafe/cli.rb

@@ -0,0 +1,72 @@
+require "thor"
+require_relative "commands/backup"
+require_relative "commands/ignore"
+require_relative "commands/list"
+require_relative "commands/clear"
+require_relative "commands/restore"
+require_relative "commands/undo"
+require_relative "commands/show"
+require_relative "commands/delete"
+
+module Envsafe
+  class CLI < Thor
+    desc("backup", "Backup current .env")
+    option(:tag, aliases: "-t", type: :string, desc: "Optional tag for the backup")
+    def backup
+      Envsafe::Commands::Backup.run(tag: options[:tag])
+    end
+
+    desc("ignore", "Add .envsafe to git ignore")
+    def ignore
+      Envsafe::Commands::Ignore.run()
+    end
+
+    desc("list [LIMIT]", "List all backups, optionally limit the number shown")
+    def list(limit = nil)
+      Envsafe::Commands::List.run(limit)
+    end
+
+    desc("clear", "Delete all backups")
+    def clear
+      Envsafe::Commands::Clear.run()
+    end
+
+    desc("restore", "Restore a specific backup to .env")
+    option(:tag, aliases: "-t", type: :string, desc: "Restores tagged backup")
+    option(:sindex, aliases: "-i", type: :string, desc: "Restores backup by stack index. Use 'list' command to know the index.")
+    def restore()
+      Envsafe::Commands::Restore.run(tag: options[:tag], sindex: options[:sindex])
+    end
+
+    desc("undo", "Undo last write operation to .env")
+    def undo()
+      Envsafe::Commands::Undo.run()
+    end
+
+    desc("show", "Show contents of file using either version or stack index")
+    option(:tag, aliases: "-t", type: :string, desc: "Show by tag")
+    option(:sindex, aliases: "-i", type: :string, desc: "Show by stack index")
+    def show()
+      Envsafe::Commands::Show.run(tag: options[:tag], sindex: options[:sindex])
+    end
+
+    desc("delete", "Delete a specifiic backup by tag or sindex")
+    option(:tag, aliases: "-t", type: :string, desc: "Delete by tag")
+    option(:sindex, aliases: "-i", type: :string, desc: "Delete by stack index")
+    def delete()
+      Envsafe::Commands::Delete.run(tag: options[:tag], sindex: options[:sindex])
+    end
+  end
+end
+
+#✅ # backup [--tag TAG]        "backup current .env with optional tag"
+#✅# list     n                "list all save .env version"
+#✅# restore version/tag      "restore a specific backup to .env"
+# current                   "show which backup is currenly checked out if any"
+# delete  version/tag       "delete a specific backup version"
+#✅# clear                     "clear all backups"
+# check                     "compare .env with .example.env"
+# sync                      "sync .example with .env creates if doesn't exist"
+# diff  version/tag         "show diff with the currrent and provided version or tag"
+#✅# undo                      "retores last edit" if i say "envsafe restore" it will overwrite but keep the option for user to retore the last modified version.
+#✅ show

data/lib/envsafe/commands/backup.rb

@@ -0,0 +1,54 @@
+require "fileutils"
+require "json"
+
+require_relative "../utils"
+require_relative "../constants"
+require_relative "../back_stack"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Backup
+  class << self
+    def run(tag: nil)
+      tag = nil if tag == "tag" # Set it to nil and ignore "tag" string as an invalid tag.
+
+      if tag && Envsafe::Utils.invalid_tag?(tag)
+        puts "❌ Invalid tag...."
+        puts "Use alphanumeric or pure numbers"
+        puts "Special symbols are invalid except: hyphen and underscore"
+
+        return
+      end
+
+      if tag && Envsafe::Utils.tag_present?(tag, Envsafe::BackStack.stack)
+        puts "❌ Tag already exists in the stack. Please use a different tag."
+
+        return
+      end
+
+
+      Envsafe::BackStack.push(tag)
+    end
+
+    private
+
+    def update_stack(filename, timestamp, tag)
+      stack = []
+
+      if File.exist?(Envsafe::STACK_FILE)
+        content = File.read(Envsafe::STACK_FILE)
+        stack = JSON.parse(content)
+      end
+
+      entry = {
+        "file" => filename,
+        "tag" => tag,
+        "timestamp" => timestamp
+      }
+
+      stack.unshift(entry)
+
+      File.write(Envsafe::STACK_FILE, JSON.pretty_generate(stack))
+    end
+  end
+end

data/lib/envsafe/commands/clear.rb

@@ -0,0 +1,38 @@
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Clear
+  class << self
+    def run
+      return unless user_sure?
+
+      # TODO: check if .envsafe exists only then continue
+      if system("rm", "-rf", ".envsafe")
+        puts "✅ .envsafe removed successfully!"
+      else
+        puts "❌ Something went wrong...."
+      end
+    end
+
+    private
+
+    def user_sure?
+
+      while true
+        STDOUT.write "This action will delete .envsafe folder along will all versions of .env, are you sure? (yes/no): "
+        STDOUT.flush
+
+        response = STDIN.gets.chomp.downcase
+
+        next if response.nil?
+
+        if response == "yes"
+          return true
+        elsif response == "no"
+          return false
+        else
+          puts "Please type yes/no"
+        end
+      end
+    end
+  end
+end

data/lib/envsafe/commands/delete.rb

@@ -0,0 +1,40 @@
+require_relative "../back_stack"
+require_relative "../utils"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Delete
+  class << self
+    def run(tag:, sindex:)
+      if tag.nil? && sindex.nil?
+        puts "❌ Please provide either a tag or an index."
+        return
+      end
+
+
+      back_stack = Envsafe::BackStack.stack()
+      parsed_sindex = Envsafe::Utils.parse_int(sindex)
+
+      if back_stack.empty?
+        puts "❌ No backup found. Please create one with 'backup' command."
+        return
+      end
+
+      if tag && not Envsafe::Utils.tag_present?(tag, back_stack)
+        puts "❌ Tag not found. Please check with 'list' command."
+        return
+      end
+
+      if sindex && (parsed_sindex < 0 || parsed_sindex >= back_stack.size)
+        puts "❌ Invalid index. Please check with 'list' command."
+        return
+      end
+
+
+      if (Envsafe::BackStack.remove_by_sindex(parsed_sindex) if sindex) ||
+      (Envsafe::BackStack.remove_by_tag(tag) if tag )
+        puts "✅ Backup deleted successfully."
+      end
+    end
+  end
+end

data/lib/envsafe/commands/ignore.rb

@@ -0,0 +1,27 @@
+require_relative '../constants'
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Ignore
+  class << self
+    def run
+      unless File.exist?(Envsafe::IGNORE_FILE) && File.readable?(Envsafe::IGNORE_FILE) && File.writable?(Envsafe::IGNORE_FILE)
+        puts "❌ Couldn't load .gitignore or either the file can't be read or written."
+        return
+      end
+
+      File.foreach(Envsafe::IGNORE_FILE) do |line|
+        if line.strip() == ".envsafe"
+          puts "✅ .envsafe is already ignored."
+
+          return
+        end
+      end
+
+      File.open(Envsafe::IGNORE_FILE, "a") do |file|
+        file.puts(".envsafe")
+        puts "✅ .envsafe has been ignored."
+      end
+    end
+  end
+end

data/lib/envsafe/commands/list.rb

@@ -0,0 +1,48 @@
+require "terminal-table"
+
+require_relative "../constants"
+require_relative "../back_stack"
+require_relative "../utils"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::List
+  class << self
+    def run(limit = 10)
+
+      limit = limit.nil? ? limit : limit.to_i
+
+      if !limit.nil? && (limit.zero? || limit < 0)
+        puts "❌ Limit must be an Integer and greater than zero."
+        puts()
+        puts "Example: envsafe list 5"
+        puts "Default limit is 10"
+        return
+      end
+
+      unless File.exist?(Envsafe::STACK_FILE)
+        puts "❌ There is nothing to show or the main .envstack/stack.json is missing."
+
+        return
+      end
+
+      file_content = read_lines(limit)
+      Envsafe::Utils.print_with_less(file_content)
+    end
+
+    private
+
+    def read_lines(n)
+      stack = Envsafe::BackStack.stack()
+
+      n = n.nil? ? stack.length : n
+      n = stack.size if n > stack.size
+
+      stack = stack[0, n]
+
+      rows = stack.each_with_index.map { |item, index| [index, File.join(Envsafe::BACKUP_DIR, item["file"]), item["tag"], item["timestamp"], Time.at(item["timestamp"])] }
+
+      Terminal::Table.new(headings: ["Index", "File", "Tag", "Timestamp", "Backed up at"], rows: rows)
+    end
+  end
+end

data/lib/envsafe/commands/restore.rb

@@ -0,0 +1,43 @@
+require_relative "../back_stack"
+require_relative "../utils"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Restore
+  class << self
+    def run(tag:, sindex:)
+      back_stack = Envsafe::BackStack.stack()
+      parsed_sindex = Envsafe::Utils.parse_int(sindex)
+
+      if sindex && (parsed_sindex.nil? || parsed_sindex < 0 || parsed_sindex >= back_stack.size)
+        puts "❌ Invalid sindex provided or out of range."
+
+        return
+      end
+
+      if tag && not Envsafe::Utils.tag_present?(tag, back_stack)
+        puts "❌ Tag not found in the backup stack. Check with 'envsafe list'"
+
+        return
+      end
+
+      if tag.nil? && sindex.nil?
+        puts "ℹ️ Tag or sindex is not provided restoring the last backed version."
+      end
+
+      has_restored = if tag
+        Envsafe::BackStack.restore_by_tag(tag)
+      elsif sindex
+        Envsafe::BackStack.restore_by_sindex(parsed_sindex)
+      else
+        Envsafe::BackStack.restore_top
+      end
+
+      if has_restored
+        puts "✅ Restored successfully."
+      else
+        puts "❌ Failed to restore."
+      end
+    end
+  end
+end

data/lib/envsafe/commands/show.rb

@@ -0,0 +1,37 @@
+require_relative "../constants"
+require_relative "../back_stack"
+require_relative "../utils"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Show
+  class << self
+    def run(tag:, sindex:)
+      back_stack = Envsafe::BackStack.stack()
+      parsed_sindex = Envsafe::Utils.parse_int(sindex)
+
+      if back_stack.empty?
+        puts "❌ No backup found. Please create one with 'backup' command."
+        return
+      end
+
+      if tag && not Envsafe::Utils.tag_present?(tag, back_stack)
+        puts "❌ Tag not found. Please check with 'list' command."
+        return
+      end
+
+      if sindex && (parsed_sindex < 0 || parsed_sindex >= back_stack.size)
+        puts "❌ Invalid index. Please check with 'list' command."
+        return
+      end
+
+      if sindex
+        Envsafe::BackStack.show_by_sindex(parsed_sindex)
+      elsif tag
+        Envsafe::BackStack.show_by_tag(tag)
+      else
+        Envsafe::BackStack.show_top()
+      end
+    end
+  end
+end

data/lib/envsafe/commands/undo.rb

@@ -0,0 +1,19 @@
+require_relative "../constants"
+
+module Envsafe::Commands; end
+
+class Envsafe::Commands::Undo
+  class << self
+    def run()
+      puts "Undoing the last write operation...."
+
+      if File.exist?(Envsafe::MAIN_ENV)
+        FileUtils.cp(Envsafe::MAIN_ENV, Envsafe::ENV_FILE)
+
+        puts "✅ Undo was successful"
+      else
+        puts "❌ Undo failed, have you backed up your .env?"
+      end
+    end
+  end
+end

data/lib/envsafe/constants.rb

@@ -0,0 +1,9 @@
+module Envsafe
+  ENVSAFE_DIR = ".envsafe"
+  BACKUP_DIR = File.join(ENVSAFE_DIR, "backups")
+  MAIN_ENV = File.join(ENVSAFE_DIR, "main.env")
+  STACK_FILE = File.join(ENVSAFE_DIR, "stack.json")
+  ENV_FILE = ".env"
+  ENV_EXAMPLE = ".example.env"
+  IGNORE_FILE = ".gitignore"
+end

data/lib/envsafe/file_store.rb

@@ -0,0 +1,81 @@
+require "fileutils"
+
+class Envsafe::FileStore
+  class << self
+    def copy_env(filename)
+      FileUtils.mkdir_p(Envsafe::BACKUP_DIR)
+
+      unless File.exist?(Envsafe::MAIN_ENV)
+        backup_current_to_main_env()
+      end
+
+      dest_path = File.join(Envsafe::BACKUP_DIR, filename)
+
+      FileUtils.cp(Envsafe::ENV_FILE, dest_path)
+    end
+
+    def delete_backup(stack_entry)
+      File.delete(full_filepath(stack_entry))
+
+      File.exist?(full_filepath(stack_entry))
+    end
+
+
+    def new_filename(tag)
+      timestamp = Time.now.utc.to_i
+
+      [(tag ? "#{timestamp}_#{tag}.env" : "#{timestamp}.env"), timestamp]
+    end
+
+    def restore(stack_entry)
+      filepath = full_filepath(stack_entry)
+
+      backup_current_to_main_env()
+
+      FileUtils.cp(filepath, Envsafe::ENV_FILE)
+    end
+
+    # Deletes the file after copying it to main.
+    def restore_main(stack_entry)
+      backup_current_to_main_env()
+
+      FileUtils.cp(full_filepath(stack_entry), Envsafe::ENV_FILE)
+
+      delete_backup(stack_entry)
+    end
+
+    def backup_current_to_main_env
+       FileUtils.cp(Envsafe::ENV_FILE, Envsafe::MAIN_ENV)
+    end
+
+    # Overwrites .env with main.env
+    def undo_last_restore
+      FileUtils.cp(Envsafe::MAIN_ENV, Envsafe::ENV_FILE)
+    end
+
+
+    def filename(stack_entry)
+      return if stack_entry.nil?
+
+      file, tag, timestamp = dse(stack_entry)
+
+      tag ? "#{timestamp}_#{tag}.env" : "#{timestamp}.env"
+    end
+
+    def full_filepath(stack_entry)
+      File.join(Envsafe::BACKUP_DIR, filename(stack_entry))
+    end
+
+    def file_content(stack_entry)
+      File.read(full_filepath(stack_entry))
+    end
+
+    private
+
+    # Destructured Stack Entry (dse)
+    def dse(se)
+      [se["file"], se["tag"], se["timestamp"]]
+    end
+
+  end
+end

data/lib/envsafe/utils.rb

@@ -0,0 +1,31 @@
+module Envsafe
+  module Utils
+    def self.valid_tag?(tag)
+      /\A[a-zA-Z0-9_-]+\z/.match?(tag)
+    end
+
+    def self.invalid_tag?(tag)
+      not valid_tag?(tag)
+    end
+
+    def self.tag_present?(tag, back_stack)
+      back_stack.any? { |entry| entry["tag"] == tag }
+    end
+
+    def self.unique_tag?(tag, back_stack)
+      not(tag_present?(tag, back_stack))
+    end
+
+    def self.parse_int(num)
+      return nil if num.nil?
+
+      Integer(num)
+    rescue Error
+      nil
+    end
+
+    def self.print_with_less(content)
+       IO.popen("less", "w") { |io| io.write(content)}
+    end
+  end
+end

data/lib/envsafe/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Envsafe
+  VERSION = "0.1.0"
+end

data/lib/envsafe.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require_relative "envsafe/version"
+require_relative "envsafe/cli"
+
+module Envsafe; end
+module Envsafe::Commands; end
+
+module Envsafe
+  class Error < StandardError; end
+  # Your code goes here...
+end

data/sig/envsafe.rbs

@@ -0,0 +1,4 @@
+module Envsafe
+  VERSION: String
+  # See the writing guide of rbs: https://github.com/ruby/rbs#guides
+end

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: envsafe
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Kaiser Sakhi
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Envsafe is a standalone CLI utility for managing your .env files without project integration.
+
+  Quickly back up your current environment, restore from any saved version, and compare your .env file
+  against .env.example to catch missing or extra variables. Think of it as git stash for your .env.
+
+  Core features:
+    - Backup and restore .env files with optional tags
+    - Pop the latest backup off the stack
+    - Checkout any saved .env version or return to main
+    - Validate .env vs .env.example
+    - CLI-native — no Gemfile or code integration required
+
+  Envsafe gives you safe, versioned control of your app’s environment variables — without the overhead.
+email:
+- mail@kaisersakhi.com
+executables:
+- envsafe
+extensions: []
+extra_rdoc_files: []
+files:
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/envsafe
+- lib/envsafe.rb
+- lib/envsafe/back_stack.rb
+- lib/envsafe/cli.rb
+- lib/envsafe/commands/backup.rb
+- lib/envsafe/commands/clear.rb
+- lib/envsafe/commands/delete.rb
+- lib/envsafe/commands/ignore.rb
+- lib/envsafe/commands/list.rb
+- lib/envsafe/commands/restore.rb
+- lib/envsafe/commands/show.rb
+- lib/envsafe/commands/undo.rb
+- lib/envsafe/constants.rb
+- lib/envsafe/file_store.rb
+- lib/envsafe/utils.rb
+- lib/envsafe/version.rb
+- sig/envsafe.rbs
+homepage: https://github.com/kaisersakhi/envsafe
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/kaisersakhi/envsafe
+  source_code_uri: https://github.com/kaisersakhi/envsafe
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.7.0
+specification_version: 4
+summary: A simple CLI tool to back up, restore, and validate your .env files.
+test_files: []