# 012.0-DEV-EXIT-CODE-REFINEMENT: Exit Code Refinement & Standardization

## Release Goal

**Release 0.8: CI/CD Integration - Exit Codes**

Refine and standardize exit codes to enable robust CI/CD integration. Clear, documented exit codes allow automated scripts to make decisions based on whether safe updates are available.

## How This Story Contributes

Enables automated workflows to detect and respond to available updates. CI/CD pipelines can fail builds, send notifications, or take other actions based on whether safe updates are available.

## User Story

**Format**: So that my CI/CD pipeline can detect when safe updates are available and take appropriate action, as a developer, I want dry-aged-deps to use standardized exit codes that indicate different outcomes (no updates, updates available, errors).

**INVEST Criteria Compliance**:

- **Independent**: Refines existing exit code behavior without changing core functionality
- **Negotiable**: Specific exit code values can be refined
- **Valuable**: Enables automated decision-making in CI/CD
- **Estimable**: Clear scope - standardize exit codes and document
- **Small**: Single iteration to refine exit codes
- **Testable**: Can verify exit codes for all scenarios

## Acceptance Criteria

- [ ] **Exit 0**: No safe updates available (dependencies up to date)
- [ ] **Exit 1**: Safe updates available (non-error status for automation)
- [ ] **Exit 2**: Error - command execution failed (npm outdated failed, invalid config, etc.)
- [ ] **Consistent Behavior**: Exit codes consistent across all output formats (table, JSON, XML)
- [ ] **Documentation**: Exit codes documented in README and --help
- [ ] **Test Coverage**: Tests verify exit codes for all scenarios
- [ ] **Backward Compatible**: Existing behavior preserved where possible

## Requirements (Current Implementation or To Be Implemented)

- **REQ-EXIT-0**: Exit code 0 when no errors occurred AND no safe updates available
- **REQ-EXIT-1**: Exit code 1 when safe updates are available
- **REQ-EXIT-2**: Exit code 2 when command execution failed (errors)
- **REQ-CONSISTENCY**: Same exit codes regardless of --format flag
- **REQ-DOCUMENTATION**: Document exit codes in README and help text
- **REQ-ERROR-TYPES**: Clear distinction between "no updates" (0) and "errors" (2)

## Exit Code Specification

| Exit Code | Meaning           | When                                                     | CI/CD Use Case                                |
| --------- | ----------------- | -------------------------------------------------------- | --------------------------------------------- |
| 0         | No updates needed | No safe updates available OR all dependencies up to date | ✅ Pass - dependencies are current            |
| 1         | Updates available | One or more safe updates found                           | ⚠️ Warning - notify team of available updates |
| 2         | Error occurred    | npm command failed, invalid config, filesystem errors    | ❌ Fail - something went wrong                |

## Usage Examples

**Check if updates available (exit code only)**:

```bash
dry-aged-deps > /dev/null
echo $?
# 0 = no updates needed
# 1 = safe updates available
# 2 = error occurred
```

**CI/CD Pipeline Integration**:

```yaml
# GitHub Actions example
- name: Check for safe dependency updates
  run: |
    dry-aged-deps --format=json > updates.json
    EXIT_CODE=$?

    if [ $EXIT_CODE -eq 1 ]; then
      echo "Safe updates available!"
      # Could send notification, create issue, etc.
    elif [ $EXIT_CODE -eq 2 ]; then
      echo "Error checking dependencies"
      exit 1
    fi
```

## Dependencies

- None - refines existing behavior

## Definition of Done

- [ ] All acceptance criteria met
- [ ] Code reviewed and approved
- [ ] Unit tests verify exit codes for all scenarios:
  - No outdated packages → exit 0
  - Outdated packages but none mature/safe → exit 0
  - Safe updates available → exit 1
  - npm outdated fails → exit 2
  - Invalid CLI flags → exit 2
  - Invalid config file → exit 2
- [ ] Integration tests with different scenarios
- [ ] Documentation updated (README.md shows exit codes)
- [ ] Help text mentions exit codes
- [ ] Backward compatible with existing usage

---

## Story Notes

**Gall's Law Compliance**: Refines existing exit code behavior to be more predictable and useful. No breaking changes to core functionality.

**Standard Convention**: Exit code 0 = success, non-zero = something to pay attention to. Exit code 1 is informational (updates available), exit code 2 is an actual error.

**CI/CD Enabler**: Well-defined exit codes enable sophisticated CI/CD workflows. Pipelines can distinguish between "everything's fine" (0), "updates available but not urgent" (1), and "something broke" (2).

**Backward Compatibility**: Current exit code behavior should be preserved where it makes sense. Review existing tests to ensure no breaking changes.

**Future Enhancement**: Could add additional exit codes for specific scenarios (e.g., exit 3 for vulnerable dependencies found), but keep it simple for now.

**Testing Focus**: Comprehensive test coverage for exit codes is critical. Every scenario should have verified exit code behavior.
