Add clear-values command and improve audit reporting

Introduces the clear-values command to remove all values from an environment file with PIN confirmation. Enhances the audit command to report keys with missing values. Updates file arrangement logic to insert blank lines between variable prefixes and improves YAML conversion to preserve order and formatting. Documentation is updated with new examples and command descriptions.

Author: YoungMayor

README.md

@@ -112,12 +112,51 @@ envdoc create-example [file] [output]
 ```
 Generates an example file with empty values based on keys in the source file.
 
+**Example Output:**
+```env
+DATABASE_HOST=
+DATABASE_PORT=
+DATABASE_NAME=
+DATABASE_USER=
+DATABASE_PASSWORD=
+
+API_KEY=
+API_SECRET=
+API_BASE_URL=
+```
+
 ##### Create JSON Schema
 ```bash
 envdoc create-schema [file] [output]
 ```
 Generates a JSON schema defining all environment variables.
 
+**Example Schema:**
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "DATABASE_HOST": {
+      "type": "string",
+      "description": "Database Configuration"
+    },
+    "DATABASE_PORT": {
+      "type": "string"
+    },
+    "API_KEY": {
+      "type": "string",
+      "description": "API Configuration"
+    }
+  },
+  "required": [
+    "DATABASE_HOST",
+    "DATABASE_PORT",
+    "API_KEY"
+  ]
+}
+```
+
 -----------------------------------------------------------------------
 
 #### 📑 File Management
@@ -126,7 +165,27 @@ Generates a JSON schema defining all environment variables.
 ```bash
 envdoc arrange [file]
 ```
-Sorts and groups environment variables alphabetically.
+Sorts and groups environment variables alphabetically with blank lines separating different prefixes.
+
+**Example Output:**
+```env
+APP_DEBUG=true
+APP_ENV=development
+APP_NAME=MyApp
+
+AWS_ACCESS_KEY_ID=key123
+AWS_SECRET_ACCESS_KEY=secret456
+
+DATABASE_HOST=localhost
+DATABASE_PORT=5432
+DATABASE_NAME=myapp
+```
+
+##### Clear Values
+```bash
+envdoc clear-values [file]
+```
+Clears all values from an environment file, leaving only the keys. This is a dangerous operation requiring PIN confirmation.
 
 ##### Sync
 ```bash
@@ -142,14 +201,64 @@ Synchronizes keys across multiple files, adding missing keys with empty values.
 ```bash
 envdoc audit [file]
 ```
-Generates a report of duplicate keys in a file.
+Generates a report of duplicate keys and missing values in a file.
+
+**Example Report:**
+```markdown
+# Environment Variables Audit Report
+
+## Overview
+
+**File:** `.env`
+**Total Keys:** 15
+**Duplicate Keys:** 1
+**Keys with Missing Values:** 3
+
+## Duplicate Keys
+
+| Key |
+|-----|
+| `API_KEY` |
+
+## Keys with Missing Values
+
+| Key |
+|-----|
+| `DATABASE_PASSWORD` |
+| `API_SECRET` |
+| `SMTP_PASSWORD` |
+```
 
 ##### Compare
 ```bash
 envdoc compare [file1] [file2] [fileN...]
 ```
 Generates a comparison report showing missing keys across files.
 
+**Example Report:**
+```markdown
+# Environment Variables Comparison Report
+
+## Overview
+
+**Files Compared:** 3
+
+## Files Analyzed
+
+- `.env.development` (10 keys)
+- `.env.staging` (12 keys)
+- `.env.production` (12 keys)
+
+## Missing Keys
+
+### Missing in `.env.development`
+
+| Key |
+|-----|
+| `SSL_CERT` |
+| `SSL_KEY` |
+```
+
 ##### Doctor
 ```bash
 envdoc doctor

cmd/envdoc/root.go

@@ -45,6 +45,7 @@ func init() {
 
 	// Utility commands
 	rootCmd.AddCommand(commands.NewArrangeCmd())
+	rootCmd.AddCommand(commands.NewClearValuesCmd())
 
 	// Info commands
 	rootCmd.AddCommand(commands.NewVersionCmd())

internal/commands/audit.go

@@ -49,8 +49,11 @@ and duplicated keys in the specified file.`,
 			// Find duplicates
 			duplicates := parser.FindDuplicates(envVars)
 
+			// Find keys with missing values
+			missingValues := findKeysWithMissingValues(envVars)
+
 			// Generate report
-			report := generateAuditReport(inputFile, duplicates, len(envVars))
+			report := generateAuditReport(inputFile, duplicates, missingValues, len(envVars))
 
 			// Show options
 			handleReportOutput(report, "envdoc-audit")
@@ -112,18 +115,31 @@ across multiple specified files.`,
 	}
 }
 
-func generateAuditReport(filename string, duplicates []string, totalKeys int) string {
+// findKeysWithMissingValues finds keys that have empty or missing values
+func findKeysWithMissingValues(envVars []parser.EnvVar) []string {
+	var missing []string
+	for _, envVar := range envVars {
+		if envVar.Value == "" {
+			missing = append(missing, envVar.Key)
+		}
+	}
+	return missing
+}
+
+func generateAuditReport(filename string, duplicates []string, missingValues []string, totalKeys int) string {
 	var sb strings.Builder
 
 	sb.WriteString("# Environment Variables Audit Report\n\n")
 	sb.WriteString("## Table of Contents\n")
 	sb.WriteString("- [Overview](#overview)\n")
-	sb.WriteString("- [Duplicate Keys](#duplicate-keys)\n\n")
+	sb.WriteString("- [Duplicate Keys](#duplicate-keys)\n")
+	sb.WriteString("- [Keys with Missing Values](#keys-with-missing-values)\n\n")
 
 	sb.WriteString("## Overview\n\n")
 	sb.WriteString(fmt.Sprintf("**File:** `%s`\n\n", filename))
 	sb.WriteString(fmt.Sprintf("**Total Keys:** %d\n\n", totalKeys))
 	sb.WriteString(fmt.Sprintf("**Duplicate Keys:** %d\n\n", len(duplicates)))
+	sb.WriteString(fmt.Sprintf("**Keys with Missing Values:** %d\n\n", len(missingValues)))
 
 	sb.WriteString("## Duplicate Keys\n\n")
 	if len(duplicates) == 0 {
@@ -137,6 +153,18 @@ func generateAuditReport(filename string, duplicates []string, totalKeys int) st
 		sb.WriteString("\n")
 	}
 
+	sb.WriteString("## Keys with Missing Values\n\n")
+	if len(missingValues) == 0 {
+		sb.WriteString("✓ No keys with missing values found.\n\n")
+	} else {
+		sb.WriteString("| Key |\n")
+		sb.WriteString("|-----|\n")
+		for _, key := range missingValues {
+			sb.WriteString(fmt.Sprintf("| `%s` |\n", key))
+		}
+		sb.WriteString("\n")
+	}
+
 	return sb.String()
 }
 

internal/commands/clearvalues.go

@@ -0,0 +1,100 @@
+package commands
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/MayR-Labs/envdoc-go/internal/parser"
+	"github.com/MayR-Labs/envdoc-go/internal/utils"
+	"github.com/spf13/cobra"
+)
+
+// NewClearValuesCmd returns the clear-values command
+func NewClearValuesCmd() *cobra.Command {
+	return &cobra.Command{
+		Use:   "clear-values [file]",
+		Short: "Clear all values from an environment file",
+		Long: `Clears all values from the specified environment file, leaving only the keys.
+This is a dangerous operation and requires PIN confirmation.`,
+		Args: cobra.MaximumNArgs(1),
+		Run: func(cmd *cobra.Command, args []string) {
+			var inputFile string
+			var err error
+
+			// Get input file
+			if len(args) > 0 {
+				inputFile = args[0]
+			} else {
+				inputFile, err = utils.PromptForEnvFile("Select the .env file to clear values:")
+				if err != nil {
+					fmt.Printf("Error: %v\n", err)
+					os.Exit(1)
+				}
+			}
+
+			// Check if input file exists
+			if !utils.FileExists(inputFile) {
+				fmt.Printf("Error: File '%s' does not exist\n", inputFile)
+				os.Exit(1)
+			}
+
+			// First warning
+			fmt.Printf("\n⚠️  WARNING: This operation will CLEAR ALL VALUES from '%s'\n", inputFile)
+			fmt.Println("⚠️  This action is IRREVERSIBLE and will remove all sensitive data!")
+			fmt.Println("⚠️  Make sure you have a backup before proceeding.")
+
+			// First PIN confirmation
+			confirmed, err := utils.ConfirmWithPin("To proceed with clearing all values, please confirm with PIN")
+			if err != nil {
+				fmt.Printf("Error: %v\n", err)
+				os.Exit(1)
+			}
+			if !confirmed {
+				fmt.Println("Operation cancelled.")
+				return
+			}
+
+			// Second warning - final confirmation
+			fmt.Printf("\n⚠️  FINAL WARNING: You are about to PERMANENTLY CLEAR all values in '%s'\n", inputFile)
+			fmt.Println("⚠️  This is your LAST CHANCE to cancel this operation!")
+
+			// Second confirmation (yes/no)
+			finalConfirm, err := utils.PromptForConfirmation("Are you ABSOLUTELY SURE you want to continue?")
+			if err != nil {
+				fmt.Printf("Error: %v\n", err)
+				os.Exit(1)
+			}
+			if !finalConfirm {
+				fmt.Println("Operation cancelled.")
+				return
+			}
+
+			// Parse input file
+			envVars, err := parser.ParseEnvFile(inputFile)
+			if err != nil {
+				fmt.Printf("Error parsing file: %v\n", err)
+				os.Exit(1)
+			}
+
+			// Clear all values
+			clearedVars := make([]parser.EnvVar, len(envVars))
+			for i, envVar := range envVars {
+				clearedVars[i] = parser.EnvVar{
+					Key:        envVar.Key,
+					Value:      "",
+					Comment:    envVar.Comment,
+					BlankAfter: envVar.BlankAfter,
+				}
+			}
+
+			// Write back to file
+			if err := parser.WriteEnvFile(inputFile, clearedVars); err != nil {
+				fmt.Printf("Error writing file: %v\n", err)
+				os.Exit(1)
+			}
+
+			fmt.Printf("✓ All values cleared from: %s\n", inputFile)
+			fmt.Printf("✓ %d keys retained with empty values\n", len(clearedVars))
+		},
+	}
+}

internal/commands/convert.go

@@ -64,16 +64,15 @@ func NewToCmd() *cobra.Command {
 				os.Exit(1)
 			}
 
-			// Convert to map
-			envMap := make(map[string]string)
-			for _, envVar := range envVars {
-				envMap[envVar.Key] = envVar.Value
-			}
-
 			// Convert to target format
 			var output string
 			var ext string
 			if format == "json" {
+				// Convert to map for JSON (order doesn't matter for JSON display)
+				envMap := make(map[string]string)
+				for _, envVar := range envVars {
+					envMap[envVar.Key] = envVar.Value
+				}
 				jsonData, err := json.MarshalIndent(envMap, "", "  ")
 				if err != nil {
 					fmt.Printf("Error converting to JSON: %v\n", err)
@@ -82,12 +81,9 @@ func NewToCmd() *cobra.Command {
 				output = string(jsonData)
 				ext = ".json"
 			} else {
-				yamlData, err := yaml.Marshal(envMap)
-				if err != nil {
-					fmt.Printf("Error converting to YAML: %v\n", err)
-					os.Exit(1)
-				}
-				output = string(yamlData)
+				// For YAML, arrange by prefix and generate manually to preserve order
+				arrangedVars := parser.ArrangeByPrefix(envVars)
+				output = convertToYAMLWithBlankLines(arrangedVars)
 				ext = ".yaml"
 			}
 
@@ -197,3 +193,26 @@ func NewFromCmd() *cobra.Command {
 		},
 	}
 }
+
+// convertToYAMLWithBlankLines converts environment variables to YAML format with blank lines between different prefixes
+func convertToYAMLWithBlankLines(envVars []parser.EnvVar) string {
+	var sb strings.Builder
+
+	for i, envVar := range envVars {
+		// Escape special characters in value if needed
+		value := envVar.Value
+		if strings.ContainsAny(value, ":#{}[],&*!|>'\"%@`") || strings.HasPrefix(value, " ") || strings.HasSuffix(value, " ") {
+			// Quote the value if it contains special YAML characters
+			value = fmt.Sprintf("\"%s\"", strings.ReplaceAll(value, "\"", "\\\""))
+		}
+
+		sb.WriteString(fmt.Sprintf("%s: %s\n", envVar.Key, value))
+
+		// Add blank line if this variable is marked for a blank line after it
+		if envVar.BlankAfter && i < len(envVars)-1 {
+			sb.WriteString("\n")
+		}
+	}
+
+	return sb.String()
+}