Goca Safety & Dependency Management Features

Overview

Goca's safety and dependency management system protects your project from accidental overwrites and automates go.mod maintenance. As of v1.18.7, the --dry-run, --force, and --backup flags are fully wired through all 12 file-generating commands.

New Features

1. Dry-Run Mode (`--dry-run`)

Preview all changes before they are made to your project.

Usage (any file-generating command):

goca feature User --fields "name:string,email:string" --dry-run
goca entity Product --fields "Name:string,Price:float64" --dry-run
goca usecase Order --dry-run
goca init myapp --module github.com/acme/myapp --dry-run

Output:

🔍 DRY-RUN MODE: Previewing changes without creating files

📝 [DRY-RUN] Would create: internal/domain/user.go (1234 bytes)
📝 [DRY-RUN] Would create: internal/usecase/user_service.go (2345 bytes)
📝 [DRY-RUN] Would create: internal/repository/postgres_user_repository.go (1567 bytes)
📝 [DRY-RUN] Would create: internal/handler/http/user_handler.go (2890 bytes)

📋 DRY-RUN SUMMARY:
   Would create 15 files
   ⚠️  2 conflicts detected:
      - internal/domain/user.go
      - internal/usecase/user_service.go

💡 Run without --dry-run to actually create files
   Use --force to overwrite existing files
   Use --backup to backup files before overwriting

2. File Conflict Detection

Automatically detects existing files and prevents accidental overwrites.

Scenarios:

Scenario A: File Exists (No Force)

goca feature User --fields "name:string"

❌ file already exists: internal/domain/user.go (use --force to overwrite or --backup to backup first)

Scenario B: Force Overwrite

goca feature User --fields "name:string" --force

⚠️  Overwriting: internal/domain/user.go
✅ Created: internal/domain/user.go

Scenario C: Backup Before Overwrite

goca feature User --fields "name:string" --force --backup

📦 Backed up: internal/domain/user.go -> .goca-backup/internal/domain/user.go.backup
✅ Created: internal/domain/user.go

3. Name Conflict Detection

Detects duplicate entity/feature names across the project.

Example:

# User feature already exists
goca feature User --fields "email:string"

❌ feature 'User' already exists in the project
💡 Use --force to generate anyway

Existing Entities Detection: The system scans internal/domain/ for existing entities and prevents duplicates.

4. Automatic go.mod Management

Automatically updates go.mod when generating features with dependencies.

Features:

✅ Adds required dependencies automatically
✅ Runs go mod tidy after generation
✅ Verifies dependency compatibility
✅ Suggests optional dependencies

Example:

goca feature Auth --fields "username:string,password:string" --validation

7️⃣  Managing dependencies...
✅ Added dependency: github.com/go-playground/validator/v10 v10.16.0
✅ Added dependency: github.com/golang-jwt/jwt/v5 v5.2.0

📦 Updating go.mod...
✅ Updated go.mod and go.sum

💡 OPTIONAL DEPENDENCIES:
   The following dependencies might be useful for your feature:

   📦 golang.org/x/crypto v0.17.0
      Reason: password hashing
      Install: go get golang.org/x/crypto@v0.17.0

5. Version Compatibility Checking

Verifies Go version and dependency compatibility.

Features:

✅ Checks minimum Go version (1.21+)
✅ Verifies dependency versions are compatible
✅ Warns about potential conflicts

Example:

goca init myproject --module github.com/user/myproject

✅ Go version check: go1.25.2 (compatible with go1.21+)
✅ All dependencies verified

6. Optional Dependency Suggestions

Intelligently suggests dependencies based on feature characteristics.

Dependency Categories:

Validation

📦 github.com/go-playground/validator/v10
   Reason: struct validation for DTOs

Authentication

📦 github.com/golang-jwt/jwt/v5
   Reason: JWT authentication
   
📦 golang.org/x/crypto
   Reason: password hashing

Testing

📦 github.com/stretchr/testify
   Reason: testing assertions and mocks
   
📦 github.com/golang/mock
   Reason: mock generation for testing

gRPC

📦 google.golang.org/grpc
   Reason: gRPC protocol support
   
📦 google.golang.org/protobuf
   Reason: Protocol Buffers

Implementation Details

New Files Created

cmd/safety.go
- SafetyManager: Handles dry-run, force, and backup modes
- NameConflictDetector: Scans for existing entities/features
- File conflict detection logic
- Backup system
cmd/dependency_manager.go
- DependencyManager: Manages go.mod updates
- Dependency suggestion system
- Version compatibility checking
- Automatic dependency installation

Updated Files

All 12 generator commands (cmd/entity.go, cmd/usecase.go, cmd/repository.go, cmd/handler.go, cmd/di.go, cmd/messages.go, cmd/interfaces.go, cmd/mocks.go, cmd/init.go, cmd/integrate.go, cmd/feature.go, cmd/test_integration.go)
- --dry-run, --force, --backup flags registered on each
- SafetyManager threaded through all sub-generators
- feature and integrate forward SafetyManager to every generator they call
cmd/utils.go (v1.18.7)
- writeFile() and writeGoFile() accept variadic *SafetyManager parameter
- When provided, all writes route through SafetyManager.WriteFile()

Command Flag Reference

All Commands Support

As of v1.18.7, --dry-run, --force, and --backup are registered and fully functional on every file-generating command:

Command	`--dry-run`	`--force`	`--backup`
`goca entity`	✅	✅	✅
`goca usecase`	✅	✅	✅
`goca repository`	✅	✅	✅
`goca handler`	✅	✅	✅
`goca di`	✅	✅	✅
`goca messages`	✅	✅	✅
`goca interfaces`	✅	✅	✅
`goca mocks`	✅	✅	✅
`goca init`	✅	✅	✅
`goca integrate`	✅	✅	✅
`goca feature`	✅	✅	✅
`goca test-integration`	✅	✅	✅

Flag	Type	Description
`--dry-run`	bool	Preview changes without creating files
`--force`	bool	Overwrite existing files without asking
`--backup`	bool	Backup files before overwriting

Safety Workflow

# 1. Preview changes first
goca feature Product --fields "name:string,price:float64" --dry-run

# 2. If satisfied, generate for real
goca feature Product --fields "name:string,price:float64"

# 3. If files exist and you want to update
goca feature Product --fields "name:string,price:float64" --force --backup

Benefits

For Developers

✅ Safety: Preview changes before committing ✅ Confidence: Know exactly what will be created ✅ No Accidents: Automatic conflict detection ✅ Easy Recovery: Automatic backups ✅ Less Manual Work: Automatic dependency management

For Teams

✅ Consistency: Standardized dependency versions ✅ Documentation: Clear what each feature requires ✅ Onboarding: Suggestions help new developers ✅ Best Practices: Automatic inclusion of common libraries

Configuration

.goca.yaml Support

Safety and dependency features are configured via CLI flags (--dry-run, --force, --backup) on each command. Dedicated safety: and dependencies: config sections in .goca.yaml are not yet implemented.

Examples

Example 1: Safe Feature Generation

# Step 1: Preview
goca feature Order --fields "customer_id:int,total:float64,status:string" --dry-run

# Step 2: Check for conflicts
# (automatically done)

# Step 3: Generate with backup
goca feature Order --fields "customer_id:int,total:float64,status:string" --backup

# Step 4: Dependencies auto-added
# go.mod updated automatically

Example 2: Update Existing Feature

# Backup and force update
goca feature User --fields "name:string,email:string,age:int,role:string" --force --backup

# Old files saved to .goca-backup/
# New files generated
# Dependencies updated

Example 3: Team Workflow

# Developer A: Preview changes
goca feature Payment --fields "amount:float64,method:string" --dry-run

# Share preview output in PR
# Team reviews

# Developer B: Generate with exact same command
goca feature Payment --fields "amount:float64,method:string"

# Consistent results across team

Best Practices

1. Always Dry-Run First

# Good
goca feature NewFeature --fields "..." --dry-run
goca feature NewFeature --fields "..."

# Risky
goca feature NewFeature --fields "..."

2. Use Backup for Updates

# Safe
goca feature ExistingFeature --fields "..." --force --backup

# Risky
goca feature ExistingFeature --fields "..." --force

3. Review Dependency Suggestions

# After generation, review suggested dependencies
# Install only what you need
go get github.com/suggested/package@version

4. Commit Backups

# Add backups to .gitignore
echo ".goca-backup/" >> .gitignore

# Or commit them for safety
git add .goca-backup/
git commit -m "Backup before updating User feature"

Troubleshooting

Issue: "file already exists"

Solution: Use --force and --backup:

goca feature User --fields "..." --force --backup

Issue: "feature already exists"

Solution: Either:

Use a different name
Use --force to regenerate
Delete existing feature files first

Issue: "dependency verification failed"

Solution: Run manually:

cd your-project
go mod tidy
go mod verify

Issue: Dry-run shows many conflicts

Solution: This is expected if updating an existing feature. Use --force --backup to proceed safely.

Migration Guide

Existing Projects

No changes needed! New features are opt-in via flags.

Updating Commands

Old command:

goca feature User --fields "name:string"

New (safer):

# Preview first
goca feature User --fields "name:string" --dry-run

# Then generate
goca feature User --fields "name:string"

Future Enhancements

Planned for a future release:

Interactive conflict resolution
Merge tool for conflicting files
Undo/rollback command
Dependency version suggestions
Security vulnerability scanning

Contributing

These features are open for community contribution. See:

cmd/safety.go - Safety manager implementation
cmd/dependency_manager.go - Dependency management
Tests in internal/testing/tests/safety_test.go

Support

📚 Documentation: https://sazardev.github.io/goca
🐛 Issues: https://github.com/sazardev/goca/issues
💬 Discussions: https://github.com/sazardev/goca/discussions

Uh oh!

FilesExpand file tree

safety-and-dependencies.md

Latest commit

History

safety-and-dependencies.md

File metadata and controls

Goca Safety & Dependency Management Features

Overview

New Features

1. Dry-Run Mode (--dry-run)

2. File Conflict Detection

Scenario A: File Exists (No Force)

Scenario B: Force Overwrite

Scenario C: Backup Before Overwrite

3. Name Conflict Detection

4. Automatic go.mod Management

5. Version Compatibility Checking

6. Optional Dependency Suggestions

Validation

Authentication

Testing

gRPC

Implementation Details

New Files Created

Updated Files

Command Flag Reference

All Commands Support

Safety Workflow

Benefits

For Developers

For Teams

Configuration

.goca.yaml Support

Examples

Example 1: Safe Feature Generation

Example 2: Update Existing Feature

Example 3: Team Workflow

Best Practices

1. Always Dry-Run First

2. Use Backup for Updates

3. Review Dependency Suggestions

4. Commit Backups

Troubleshooting

Issue: "file already exists"

Issue: "feature already exists"

Issue: "dependency verification failed"

Issue: Dry-run shows many conflicts

Migration Guide

Existing Projects

Updating Commands

Future Enhancements

Contributing

Support

1. Dry-Run Mode (`--dry-run`)