Add custom stage support with centralized validation

jszobody · claude · happy-otter · jszobody · commit fe49aac10269 · 2025-08-29T22:27:59.000-04:00
- Created StageAddCommand for adding custom stages at any time - Extracted stage validation logic into ValidatesStages trait - Updated ConfigureCommand to use centralized validation - Added "custom" option in configure command for immediate stage creation - Enforced lowercase alphanumeric pattern for stage names (a-z0-9_-) - Comprehensive test coverage for stage management Generated with [Claude Code](https://claude.ai/code) via [Happy](https://happy.engineering) Co-Authored-By: Claude <noreply@anthropic.com> Co-Authored-By: Happy <yesreply@happy.engineering>
diff --git a/src/Commands/Concerns/ValidatesStages.php b/src/Commands/Concerns/ValidatesStages.php
@@ -0,0 +1,43 @@
+<?php
+
+namespace STS\Keep\Commands\Concerns;
+
+trait ValidatesStages
+{
+    protected function isValidStageName(string $name): bool
+    {
+        return preg_match('/^[a-z0-9_-]+$/', $name) === 1;
+    }
+    
+    protected function getStageValidationError(string $name): ?string
+    {
+        if (empty($name)) {
+            return 'Stage name is required';
+        }
+        
+        if (!$this->isValidStageName($name)) {
+            return 'Stage name can only contain lowercase letters, numbers, hyphens, and underscores';
+        }
+        
+        return null;
+    }
+    
+    protected function stageExists(string $name, array $existingStages): bool
+    {
+        return in_array($name, $existingStages, true);
+    }
+    
+    protected function validateNewStageName(string $name, array $existingStages): ?string
+    {
+        $error = $this->getStageValidationError($name);
+        if ($error) {
+            return $error;
+        }
+        
+        if ($this->stageExists($name, $existingStages)) {
+            return "Stage '{$name}' already exists";
+        }
+        
+        return null;
+    }
+}
diff --git a/src/Commands/ConfigureCommand.php b/src/Commands/ConfigureCommand.php
@@ -4,6 +4,7 @@
 
 use Illuminate\Support\Str;
 use STS\Keep\Commands\Concerns\ConfiguresVaults;
+use STS\Keep\Commands\Concerns\ValidatesStages;
 use STS\Keep\Data\Settings;
 use STS\Keep\Facades\Keep;
 
@@ -15,7 +16,7 @@
 
 class ConfigureCommand extends BaseCommand
 {
-    use ConfiguresVaults;
+    use ConfiguresVaults, ValidatesStages;
 
     protected $signature = 'configure';
 
@@ -55,11 +56,26 @@ protected function process()
                 'staging' => 'Staging (pre-production)',
                 'sandbox' => 'Sandbox (demos / experiments)',
                 'production' => 'Production (live)',
+                'custom' => '➕ Add custom stage...',
             ],
             default: $existingSettings['stages'] ?? ['local', 'staging', 'production'],
             scroll: 6,
-            hint: 'You can add more later. Toggle with space bar, confirm with enter.',
+            hint: 'You can add more later with "keep stage:add". Toggle with space bar, confirm with enter.',
         );
+        
+        // Handle custom stage input
+        if (in_array('custom', $stages)) {
+            $stages = array_diff($stages, ['custom']); // Remove 'custom' from list
+            
+            $customStages = text(
+                label: 'Enter custom stage names (comma-separated, lowercase only)',
+                placeholder: 'e.g., dev2, demo, integration',
+                validate: fn($value) => $this->validateCustomStagesInput($value)
+            );
+            
+            $customStagesList = array_map('trim', explode(',', $customStages));
+            $stages = array_merge($stages, $customStagesList);
+        }
 
         // Create configuration structure
         $this->createKeepDirectory();
@@ -139,4 +155,21 @@ private function createGlobalSettings(string $appName, string $namespace, array
             'version' => '1.0',
         ])->save();
     }
+
+    private function validateCustomStagesInput(string $value): ?string
+    {
+        if (empty($value)) {
+            return 'Please enter at least one custom stage name';
+        }
+        
+        $stages = array_map('trim', explode(',', $value));
+        foreach ($stages as $stage) {
+            $error = $this->getStageValidationError($stage);
+            if ($error) {
+                return $error;
+            }
+        }
+        
+        return null;
+    }
 }
diff --git a/src/Commands/StageAddCommand.php b/src/Commands/StageAddCommand.php
@@ -0,0 +1,82 @@
+<?php
+
+namespace STS\Keep\Commands;
+
+use STS\Keep\Commands\Concerns\ValidatesStages;
+use STS\Keep\Data\Settings;
+use function Laravel\Prompts\text;
+use function Laravel\Prompts\info;
+use function Laravel\Prompts\error;
+use function Laravel\Prompts\confirm;
+
+class StageAddCommand extends BaseCommand
+{
+    use ValidatesStages;
+    
+    protected $signature = 'stage:add {name? : The name of the stage to add}';
+    
+    protected $description = 'Add a custom stage/environment';
+
+    protected function requiresInitialization(): bool
+    {
+        return true;
+    }
+
+    public function process()
+    {
+        $settings = Settings::load();
+        $stageName = $this->getStageName($settings);
+        
+        if (!$stageName) {
+            return self::FAILURE;
+        }
+        
+        $this->line('Current stages: ' . implode(', ', $settings->stages()));
+        
+        if (!confirm("Add '{$stageName}' as a new stage?")) {
+            info('Stage addition cancelled.');
+            return self::SUCCESS;
+        }
+        
+        $this->addStage($settings, $stageName);
+        
+        info("✅ Stage '{$stageName}' has been added successfully!");
+        $this->line('You can now use this stage with any Keep command using --stage=' . $stageName);
+        
+        return self::SUCCESS;
+    }
+    
+    private function getStageName(Settings $settings): ?string
+    {
+        $stageName = $this->argument('name') ?: $this->promptForStageName($settings);
+        
+        $error = $this->validateNewStageName($stageName, $settings->stages());
+        if ($error) {
+            error($error);
+            return null;
+        }
+        
+        return $stageName;
+    }
+    
+    private function promptForStageName(Settings $settings): string
+    {
+        return text(
+            label: 'Enter the name of the new stage',
+            placeholder: 'e.g., qa, demo, sandbox, dev2',
+            required: true,
+            validate: fn($value) => $this->validateNewStageName($value, $settings->stages())
+        );
+    }
+    
+    private function addStage(Settings $settings, string $stageName): void
+    {
+        Settings::fromArray([
+            'app_name' => $settings->appName(),
+            'namespace' => $settings->namespace(),
+            'stages' => [...$settings->stages(), $stageName],
+            'default_vault' => $settings->defaultVault(),
+            'created_at' => $settings->createdAt(),
+        ])->save();
+    }
+}
diff --git a/src/KeepApplication.php b/src/KeepApplication.php
@@ -37,6 +37,8 @@ public function __construct(protected KeepInstall $install)
             Commands\VaultEditCommand::class,
             Commands\VaultListCommand::class,
 
+            Commands\StageAddCommand::class,
+
             Commands\GetCommand::class,
             Commands\SetCommand::class,
             Commands\CopyCommand::class,
diff --git a/tests/Feature/StageAddCommandTest.php b/tests/Feature/StageAddCommandTest.php
@@ -0,0 +1,114 @@
+<?php
+
+use STS\Keep\Data\Settings;
+
+describe('StageAddCommand', function () {
+    
+    describe('adding custom stages', function () {
+        
+        it('adds a new custom stage via argument', function () {
+            $initialSettings = Settings::load();
+            
+            // Use a unique stage name for this test
+            $stageName = 'test-stage-' . uniqid();
+            
+            expect($initialSettings->stages())->not->toContain($stageName);
+            
+            // Add a custom stage (auto-confirmed in non-interactive mode)
+            $commandTester = runCommand('stage:add', [
+                'name' => $stageName
+            ]);
+            
+            expect($commandTester->getStatusCode())->toBe(0);
+            
+            // Verify stage was added
+            $updatedSettings = Settings::load();
+            expect($updatedSettings->stages())->toContain($stageName);
+        });
+        
+        it('validates stage name format', function () {
+            // Try to add an invalid stage name
+            $commandTester = runCommand('stage:add', [
+                'name' => 'invalid stage!' // Contains space and special char
+            ]);
+            
+            expect($commandTester->getStatusCode())->toBe(1);
+            expect($commandTester->getDisplay())->toContain('can only contain');
+            
+            // Verify stage was not added
+            $settings = Settings::load();
+            expect($settings->stages())->not->toContain('invalid stage!');
+        });
+        
+        it('prevents duplicate stage names', function () {
+            $settings = Settings::load();
+            $existingStage = $settings->stages()[0]; // Get first existing stage
+            
+            // Try to add a duplicate
+            $commandTester = runCommand('stage:add', [
+                'name' => $existingStage
+            ]);
+            
+            expect($commandTester->getStatusCode())->toBe(1);
+            
+            // Count should remain the same
+            $updatedSettings = Settings::load();
+            expect(count($updatedSettings->stages()))->toBe(count($settings->stages()));
+        });
+        
+        it('allows lowercase alphanumeric names with hyphens and underscores', function () {
+            $validNames = ['dev-2', 'test_env', 'qa1', 'prod-backup'];
+            
+            foreach ($validNames as $stageName) {
+                // Remove stage if it exists (cleanup from previous tests)
+                $settings = Settings::load();
+                $stages = array_diff($settings->stages(), [$stageName]);
+                Settings::fromArray([
+                    'app_name' => $settings->appName(),
+                    'namespace' => $settings->namespace(),
+                    'stages' => array_values($stages),
+                    'default_vault' => $settings->defaultVault(),
+                    'created_at' => $settings->createdAt(),
+                ])->save();
+                
+                // Add the stage
+                $commandTester = runCommand('stage:add', [
+                    'name' => $stageName
+                ]);
+                
+                expect($commandTester->getStatusCode())->toBe(0);
+                
+                // Verify it was added
+                $updatedSettings = Settings::load();
+                expect($updatedSettings->stages())->toContain($stageName);
+            }
+        });
+    });
+    
+    
+    describe('integration with other commands', function () {
+        
+        it('makes custom stage available for use', function () {
+            // Add a unique custom stage
+            $stageName = 'integration-' . uniqid();
+            $commandTester = runCommand('stage:add', ['name' => $stageName]);
+            
+            expect($commandTester->getStatusCode())->toBe(0);
+            expect($commandTester->getDisplay())->toContain("Stage '{$stageName}' has been added successfully");
+            
+            // Verify the custom stage is persisted in settings
+            $settings = Settings::load();
+            expect($settings->stages())->toContain($stageName);
+            
+            // Verify multiple custom stages can be added
+            $secondStage = 'secondary-' . uniqid();
+            $secondCommand = runCommand('stage:add', ['name' => $secondStage]);
+            
+            expect($secondCommand->getStatusCode())->toBe(0);
+            
+            $updatedSettings = Settings::load();
+            expect($updatedSettings->stages())->toContain($stageName);
+            expect($updatedSettings->stages())->toContain($secondStage);
+        });
+    });
+});
