From f458b4f29f63d10b88b72ade873c307a93b6b5bf Mon Sep 17 00:00:00 2001 From: Ankan Saha Date: Sun, 15 Mar 2026 09:58:11 +0530 Subject: [PATCH] feat: Update ContainDB to version 7.19.43-stable - Added new development skill documentation for ContainDB CLI tool. - Created configuration files for OpenAI Codex and GitHub Copilot. - Established core rules and guidelines for development and testing. - Updated installation instructions to reflect the new version. - Modified installer script and version files to version 7.19.43-stable. - Enhanced error handling and documentation across various files. - Ensured cross-platform compatibility and Docker SDK usage. --- .agents/skills/containdb-development/SKILL.md | 420 ++++++++++++++++++ .codex/config.toml | 68 +++ .cursor/rules/containdb-core.mdc | 140 ++++++ .gemini/settings.json | 34 ++ .github/copilot/instructions.md | 120 +++++ .github/copilot/settings.json | 87 ++++ AGENTS.md | 182 ++++++++ CLAUDE.md | 304 +++++++++++++ GEMINI.md | 151 +++++++ INSTALLATION.md | 4 +- Scripts/installer.sh | 2 +- VERSION | 2 +- npm/package.json | 2 +- src/Core/main.go | 2 +- src/base/Banner.go | 2 +- 15 files changed, 1513 insertions(+), 7 deletions(-) create mode 100644 .agents/skills/containdb-development/SKILL.md create mode 100644 .codex/config.toml create mode 100644 .cursor/rules/containdb-core.mdc create mode 100644 .gemini/settings.json create mode 100644 .github/copilot/instructions.md create mode 100644 .github/copilot/settings.json create mode 100644 AGENTS.md create mode 100644 CLAUDE.md create mode 100644 GEMINI.md diff --git a/.agents/skills/containdb-development/SKILL.md b/.agents/skills/containdb-development/SKILL.md new file mode 100644 index 0000000..bb8a23a --- /dev/null +++ b/.agents/skills/containdb-development/SKILL.md @@ -0,0 +1,420 @@ +--- +name: containdb-development +description: Development rules and patterns for ContainDB CLI tool +version: 1.0.0 +tags: [golang, docker, cli, cross-platform, containers] +author: ContainDB Team +--- + +# ContainDB Development Skill + +## Project Identity + +**ContainDB** - Database Container Management Made Simple + +- Go (Golang) ≥1.18 +- Cross-platform CLI tool (Linux, macOS, Windows) +- Docker-based database management +- Distribution: npm package + native binaries + +## Mandatory Workflows + +### After EVERY Code Change +```bash +go build -o containdb src/Core/main.go +go test ./... +go fmt ./... +go vet ./... +``` + +### For ANY Feature Change +1. Test on Linux, macOS, Windows +2. Update documentation (README, DESIGN, INSTALLATION) +3. Update CHANGELOG.md +4. Verify auto-rollback works +5. Test error scenarios + +## Definition of "Done" + +A task is NOT complete until ALL are true: +- ✅ Code follows Go standards +- ✅ `go build` passes +- ✅ `go test ./...` passes +- ✅ `go vet ./...` passes +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback implemented +- ✅ Error messages clear and actionable + +## Architecture + +### Layered Design +``` +CLI Entry Point (src/Core/main.go) + ↓ +Base Operations (src/base/) + ├── Create.go - Database creation + ├── Remove.go - Resource cleanup + ├── Export.go - docker-compose export + └── Import.go - docker-compose import + ↓ +Docker Abstraction (src/Docker/) + ├── Container.go - Container operations + ├── Volume.go - Volume management + └── Network.go - Network operations + ↓ +Docker Engine +``` + +### Module Structure +``` +src/ +├── Core/ # main.go - CLI entry point +├── base/ # Business logic +├── Docker/ # Docker SDK wrapper +└── tools/ # Management tools (phpMyAdmin, etc.) + +Scripts/ +├── BinBuilder.sh # Multi-platform builder +├── PackageBuilder.sh # Debian package builder +└── installer.sh # Linux installer +``` + +## Go Standards (STRICT) + +### Error Handling - Descriptive Context +```go +// ✅ REQUIRED +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ FORBIDDEN +if err != nil { + return err // Too generic! +} +``` + +### Type Safety - Use Structs +```go +// ✅ GOOD - Clear options struct +type ContainerOptions struct { + Name string + Image string + Port int + RestartPolicy string + Volumes map[string]string + Environment map[string]string +} + +func CreateContainer(opts ContainerOptions) error { } + +// ❌ BAD - Too many parameters +func CreateContainer(name, image string, port int, restart string, vols map[string]string, env map[string]string) error { } +``` + +### Package Organization +```go +// ✅ GOOD - Clear package boundaries +package docker + +import ( + "github.com/docker/docker/client" +) + +func CreateContainer(opts ContainerOptions) error { } + +// ❌ BAD - Mixed concerns in main +package main + +func CreateContainer() error { } +func RemoveContainer() error { } +func ParseConfig() error { } +``` + +## Key Patterns + +### 1. Auto-Rollback on Failure (CRITICAL) +```go +func CreateDatabase(opts Options) error { + // Track all created resources + created := []string{} + + // Cleanup on any error + defer func() { + if err != nil { + log.Println("Error occurred, rolling back...") + for _, resourceID := range created { + if err := cleanup(resourceID); err != nil { + log.Printf("Failed to cleanup %s: %v", resourceID, err) + } + } + } + }() + + // Create container + container, err := CreateContainer(opts) + if err != nil { + return fmt.Errorf("container creation failed: %w", err) + } + created = append(created, container.ID) + + // Create volume + volume, err := CreateVolume(opts.VolumeName) + if err != nil { + return fmt.Errorf("volume creation failed: %w", err) + } + created = append(created, volume.Name) + + return nil +} +``` + +### 2. Interactive Prompts for Sensitive Data +```go +// ✅ ALWAYS prompt for passwords +import "github.com/manifoldco/promptui" + +prompt := promptui.Prompt{ + Label: "Enter database password", + Mask: '*', +} +password, err := prompt.Run() + +// ❌ NEVER hardcode or use defaults +password := "password123" // FORBIDDEN +``` + +### 3. Docker SDK Usage (NOT Commands) +```go +// ✅ REQUIRED - Use official Docker SDK +import ( + "github.com/docker/docker/client" + "github.com/docker/docker/api/types/container" +) + +cli, err := client.NewClientWithOpts(client.FromEnv, client.WithAPIVersionNegotiation()) +if err != nil { + return fmt.Errorf("failed to create Docker client: %w", err) +} + +resp, err := cli.ContainerCreate(ctx, &container.Config{ + Image: "mysql:8.0", +}, nil, nil, nil, "my-mysql") + +// ❌ FORBIDDEN - Don't execute docker commands +cmd := exec.Command("docker", "run", "-d", "--name", "mysql", "mysql:8.0") +``` + +### 4. Cross-Platform Path Handling +```go +// ✅ GOOD - Use filepath package +import "path/filepath" + +configPath := filepath.Join(homeDir, ".containdb", "config.yaml") + +// ❌ BAD - Hardcoded separators +configPath := homeDir + "/.containdb/config.yaml" // Fails on Windows +``` + +## Security Standards + +### 1. Credential Handling +```go +// ✅ NEVER log passwords +log.Printf("Creating database with user: %s", username) // OK +log.Printf("Creating database with password: %s", password) // FORBIDDEN + +// ✅ Prompt for sensitive data +password := promptSecure("Enter password:") + +// ❌ No hardcoded secrets +const DefaultPassword = "admin123" // FORBIDDEN +``` + +### 2. Input Validation +```go +// ✅ Validate all user inputs +func ValidatePort(port int) error { + if port < 1024 || port > 65535 { + return fmt.Errorf("port must be between 1024 and 65535") + } + return nil +} + +func ValidateContainerName(name string) error { + if !regexp.MustCompile(`^[a-zA-Z0-9_-]+$`).MatchString(name) { + return fmt.Errorf("name must contain only alphanumeric, dash, or underscore") + } + return nil +} +``` + +### 3. Privilege Management +```go +// ✅ Warn users about root requirements +if os.Geteuid() != 0 { + log.Println("WARNING: ContainDB requires root/sudo privileges for Docker operations") + log.Println("Please run: sudo containdb") + os.Exit(1) +} +``` + +## Documentation Requirements + +### Update when features change: + +1. **README.md** + - Installation instructions + - Usage examples + - Feature list + - Troubleshooting + +2. **DESIGN.md** + - Architecture diagrams + - Technical decisions + - Module descriptions + +3. **INSTALLATION.md** + - Platform-specific guides + - Prerequisites + - Verification steps + +4. **CHANGELOG.md** + - Version changes + - New features + - Bug fixes + +5. **Code Comments** + ```go + // CreateDatabase creates a new containerized database instance. + // + // It performs the following steps: + // 1. Creates a Docker network (if not exists) + // 2. Creates a volume for data persistence + // 3. Starts the database container + // 4. Auto-rollback on any failure + // + // Parameters: + // - opts: Configuration options for the database + // + // Returns: + // - error: nil on success, descriptive error on failure + func CreateDatabase(opts DatabaseOptions) error + ``` + +## Testing Requirements + +### Unit Tests +```go +func TestCreateContainer(t *testing.T) { + tests := []struct { + name string + opts ContainerOptions + wantErr bool + }{ + {"valid MySQL", ContainerOptions{Name: "mysql", Image: "mysql:8.0"}, false}, + {"invalid name", ContainerOptions{Name: "my sql", Image: "mysql:8.0"}, true}, + {"missing image", ContainerOptions{Name: "mysql"}, true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := CreateContainer(tt.opts) + if (err != nil) != tt.wantErr { + t.Errorf("CreateContainer() error = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} +``` + +### Integration Tests +- Test full CLI workflows +- Test with real Docker containers +- Test auto-rollback scenarios +- Test on Linux, macOS, Windows + +## Build & Distribution + +### Multi-Platform Build +```bash +# Build for all platforms +./Scripts/BinBuilder.sh + +# Output: +# bin/containdb-linux-amd64 +# bin/containdb-darwin-amd64 +# bin/containdb-darwin-arm64 +# bin/containdb-windows-amd64.exe +``` + +### Debian Package +```bash +# Build .deb package +./Scripts/PackageBuilder.sh + +# Output: Packages/containDB_.deb +``` + +### npm Distribution +```bash +cd npm/ +npm run build +npm publish +``` + +## Anti-Patterns (FORBIDDEN) + +❌ Platform-specific code without fallbacks +❌ Hardcoded credentials or secrets +❌ Direct docker command execution (use SDK) +❌ Breaking changes to CLI interface +❌ Missing error handling +❌ Incomplete auto-rollback +❌ Skipping cross-platform testing +❌ Generic error messages +❌ Missing documentation updates +❌ Logging sensitive data + +## Workflow Guidelines + +### When Adding Database Support +1. Read `DESIGN.md` architecture section +2. Add database config to `src/base/Create.go` +3. Add default ports, images, environment vars +4. Implement auto-rollback for new resources +5. Add management tool support (if available) +6. Update README with usage examples +7. Test on all platforms +8. Update CHANGELOG.md + +### When Fixing Bugs +1. Write failing test that reproduces bug +2. Fix the bug +3. Verify test passes +4. Test on all platforms +5. Check for similar issues elsewhere +6. Document in CHANGELOG.md + +### When Refactoring +1. Ensure backward compatibility +2. Run all tests before and after +3. Test on all platforms +4. Update architecture docs if structure changes +5. Maintain CLI interface + +## Success Criteria + +Every task must meet ALL: +- ✅ Builds successfully (`go build`) +- ✅ Tests pass (`go test ./...`) +- ✅ Lints pass (`go vet ./...`, `go fmt ./...`) +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated (README, DESIGN, INSTALLATION) +- ✅ Backward compatible (CLI interface unchanged) +- ✅ Auto-rollback implemented and tested +- ✅ Clear, actionable error messages +- ✅ No hardcoded credentials +- ✅ Input validation implemented diff --git a/.codex/config.toml b/.codex/config.toml new file mode 100644 index 0000000..a9e89ee --- /dev/null +++ b/.codex/config.toml @@ -0,0 +1,68 @@ +# OpenAI Codex CLI Configuration for ContainDB + +[project] +name = "ContainDB" +description = "Database Container Management CLI Tool" +language = "Go" +runtime = "Go ≥1.18" + +[model] +default = "gpt-4-turbo" +temperature = 0.2 +max_tokens = 4096 + +[approval] +mode = "strict" +ask_before_install = true +ask_before_delete = true +ask_before_build = true + +[build] +command = "go build -o containdb src/Core/main.go" +required = true +run_after_changes = true + +[test] +command = "go test ./..." +required = true + +[style] +use_go_fmt = true +use_go_vet = true +error_handling = "descriptive_with_context" + +[rules] +cross_platform = true +docker_sdk_only = true +auto_rollback = true +interactive_prompts = true +no_hardcoded_secrets = true + +[security] +validate_inputs = true +no_log_passwords = true +warn_root_required = true +use_docker_networks = true + +[documentation] +update_readme = true +update_design = true +update_installation = true +update_changelog = true + +[antipatterns] +no_platform_specific_without_fallback = true +no_hardcoded_credentials = true +no_docker_commands = true +no_breaking_cli_changes = true +no_incomplete_rollback = true + +[completion] +required = [ + "go build passes", + "go test ./... passes", + "Works on Linux, macOS, Windows", + "Documentation updated", + "Backward compatible", + "Auto-rollback implemented" +] diff --git a/.cursor/rules/containdb-core.mdc b/.cursor/rules/containdb-core.mdc new file mode 100644 index 0000000..f7a9486 --- /dev/null +++ b/.cursor/rules/containdb-core.mdc @@ -0,0 +1,140 @@ +# ContainDB Core Rules for Cursor IDE + +## Project Context + +**ContainDB** is a CLI tool for managing containerized databases. Written in Go, cross-platform (Linux/macOS/Windows), distributed via npm and native binaries. + +## Mandatory Workflows + +### After EVERY Code Change +```bash +go build -o containdb src/Core/main.go +go test ./... +go fmt ./... +go vet ./... +``` + +### For ANY Feature Change +1. Test on Linux, macOS, Windows +2. Update docs (README, DESIGN, INSTALLATION) +3. Verify auto-rollback works +4. Test error scenarios + +## Definition of "Done" + +- ✅ `go build` passes +- ✅ `go test ./...` passes +- ✅ Works on all platforms +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback implemented +- ✅ Clear error messages + +## Architecture + +### Layers +``` +CLI (main.go) → Base Operations → Docker SDK → Docker Engine +``` + +### Structure +``` +src/ +├── Core/main.go # Entry point +├── base/ # Logic (Create, Remove, Export, Import) +├── Docker/ # SDK wrapper +└── tools/ # Management tools +``` + +## Go Standards + +### Error Handling +```go +// ✅ REQUIRED +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ FORBIDDEN +if err != nil { + return err +} +``` + +### Type Safety +```go +// ✅ Use structs +type ContainerOptions struct { + Name string + Image string + Port int +} + +// ❌ Too many params +func Create(name, image string, port int) error +``` + +## Key Patterns + +### Auto-Rollback (CRITICAL) +```go +created := []string{} +defer func() { + if err != nil { + for _, id := range created { + cleanup(id) + } + } +}() +``` + +### Docker SDK (NOT Commands) +```go +// ✅ Use SDK +import "github.com/docker/docker/client" + +cli, err := client.NewClientWithOpts(client.FromEnv) + +// ❌ Don't execute commands +exec.Command("docker", "run", ...) +``` + +### Interactive Prompts +```go +// ✅ Prompt for passwords +password := promptSecure("Enter password:") + +// ❌ No hardcoded defaults +password := "password123" +``` + +## Security + +- Never log passwords +- Validate all inputs (ports, names) +- Warn about root requirements +- Use Docker networks for isolation + +## Testing + +- Unit tests for core logic +- Integration tests for CLI +- Test on Linux, macOS, Windows +- Test error scenarios + +## Anti-Patterns (FORBIDDEN) + +❌ Platform-specific code without fallbacks +❌ Hardcoded credentials +❌ Direct docker commands +❌ Breaking CLI interface +❌ Missing error handling +❌ Incomplete rollback + +## Success Criteria + +- ✅ Builds successfully +- ✅ Tests pass +- ✅ Works cross-platform +- ✅ Docs updated +- ✅ Backward compatible diff --git a/.gemini/settings.json b/.gemini/settings.json new file mode 100644 index 0000000..10694e7 --- /dev/null +++ b/.gemini/settings.json @@ -0,0 +1,34 @@ +{ + "version": "1.0", + "description": "Gemini CLI settings for ContainDB", + + "project": { + "name": "ContainDB", + "type": "CLI Tool", + "language": "Go", + "runtime": "Go ≥1.18" + }, + + "model": { + "name": "gemini-3-pro", + "temperature": 0.2, + "maxTokens": 8192 + }, + + "context": { + "fileName": ["GEMINI.md"], + "hierarchical": true + }, + + "tools": { + "enabled": ["codeSearch", "fileOperations", "shellCommands"] + }, + + "features": { + "codeCompletion": true, + "codeGeneration": true, + "debugging": true, + "refactoring": true, + "testing": true + } +} diff --git a/.github/copilot/instructions.md b/.github/copilot/instructions.md new file mode 100644 index 0000000..f37d9e0 --- /dev/null +++ b/.github/copilot/instructions.md @@ -0,0 +1,120 @@ +# GitHub Copilot Instructions for ContainDB + +## Project Overview + +**ContainDB** - Database Container Management CLI + +- **Language**: Go ≥1.18 +- **Type**: CLI tool for Docker database management +- **Platform**: Linux, macOS, Windows +- **Distribution**: npm package + native binaries + +## Core Rules (NON-NEGOTIABLE) + +### 1. Cross-Platform Compatibility +**ALWAYS test on Linux, macOS, Windows** +- Use `filepath` package for paths +- No platform-specific code without fallbacks +- Test on all target platforms + +### 2. Docker SDK Only +```go +// ✅ Use official Docker SDK +import "github.com/docker/docker/client" + +cli, err := client.NewClientWithOpts(client.FromEnv) + +// ❌ NEVER execute docker commands +exec.Command("docker", "run", ...) +``` + +### 3. Auto-Rollback on Failure +```go +created := []string{} +defer func() { + if err != nil { + for _, id := range created { + cleanup(id) + } + } +}() +``` + +### 4. Clear Error Messages +```go +// ✅ GOOD - Descriptive with context +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ BAD - Generic +if err != nil { + return err +} +``` + +### 5. Interactive Prompts +```go +// ✅ ALWAYS prompt for sensitive data +password := promptSecure("Enter database password:") + +// ❌ NEVER hardcode +password := "password123" +``` + +## Architecture + +``` +CLI Entry Point (main.go) + ↓ +Base Operations (src/base/) + ↓ +Docker Abstraction (src/Docker/) + ↓ +Docker Engine +``` + +## Commands + +```bash +# Build & Test +go build -o containdb src/Core/main.go +go test ./... +go fmt ./... +go vet ./... + +# Distribution +./Scripts/BinBuilder.sh # Multi-platform build +./Scripts/PackageBuilder.sh # Debian package +``` + +## Documentation + +Update when features change: +- README.md - Usage, installation +- DESIGN.md - Architecture +- INSTALLATION.md - Platform guides +- CHANGELOG.md - Version changes + +## Security + +- Never log or display passwords +- Validate all user inputs +- Warn about root requirements +- No hardcoded secrets + +## Testing + +- Unit tests for logic +- Integration tests for CLI +- Cross-platform testing +- Error scenario testing + +## Success Criteria + +- ✅ `go build` passes +- ✅ `go test ./...` passes +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback works diff --git a/.github/copilot/settings.json b/.github/copilot/settings.json new file mode 100644 index 0000000..2c23b4f --- /dev/null +++ b/.github/copilot/settings.json @@ -0,0 +1,87 @@ +{ + "version": "1.0", + "description": "GitHub Copilot settings for ContainDB", + + "project": { + "name": "ContainDB", + "type": "CLI Tool", + "language": "Go", + "runtime": "Go ≥1.18" + }, + + "build": { + "command": "go build -o containdb src/Core/main.go", + "required": true, + "runAfterChanges": true + }, + + "test": { + "command": "go test ./...", + "required": true + }, + + "codeStyle": { + "useGoFmt": true, + "useGoVet": true, + "errorHandling": "descriptive" + }, + + "instructions": [ + "CRITICAL: Test on Linux, macOS, Windows before release", + "CRITICAL: Use Docker SDK, never execute docker commands directly", + "CRITICAL: Implement auto-rollback for all resource creation", + "CRITICAL: Never log or hardcode passwords", + "Use filepath package for cross-platform path handling", + "Prompt users for sensitive data interactively", + "Provide clear, actionable error messages with context", + "Validate all user inputs (ports, names, paths)", + "Update documentation when features change", + "Maintain backward compatibility for CLI interface" + ], + + "patterns": { + "autoRollback": { + "description": "Cleanup resources on any error", + "required": true + }, + "dockerSDK": { + "description": "Use official Docker SDK, not commands", + "required": true + }, + "interactivePrompts": { + "description": "Prompt for sensitive data", + "required": true + }, + "errorHandling": { + "description": "Descriptive errors with context", + "required": true + } + }, + + "security": [ + "Never log passwords or sensitive data", + "Validate all user inputs", + "Warn about root/sudo requirements", + "No hardcoded secrets or credentials", + "Use Docker networks for container isolation" + ], + + "antiPatterns": [ + "Never use platform-specific code without fallbacks", + "Never hardcode credentials", + "Never execute docker commands directly", + "Never break CLI interface compatibility", + "Never skip cross-platform testing" + ], + + "completionCriteria": { + "required": [ + "go build passes", + "go test ./... passes", + "Works on Linux, macOS, Windows", + "Documentation updated", + "Backward compatible", + "Auto-rollback implemented" + ] + } +} diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..3acd790 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,182 @@ +# AGENTS.md + +OpenAI Codex CLI Instructions for ContainDB + +## Project Overview + +**ContainDB** - Database Container Management CLI + +- **Language**: Go ≥1.18 +- **Type**: Docker database management tool +- **Platform**: Cross-platform (Linux, macOS, Windows) +- **Distribution**: npm package + native binaries + +## Build Commands + +```bash +# Development +go build -o containdb src/Core/main.go +go run src/Core/main.go +go test ./... + +# Production +./Scripts/BinBuilder.sh # Multi-platform binaries +./Scripts/PackageBuilder.sh # Debian package +npm run build && npm publish # npm distribution +``` + +## Core Principles + +### 1. Cross-Platform Compatibility +- Must work on Linux, macOS, Windows +- Test on all platforms +- No platform-specific code without fallbacks + +### 2. User Experience +- Interactive prompts for sensitive data +- Smart defaults +- Clear error messages +- Auto-rollback on failures + +### 3. Docker Integration +- Use official Docker SDK +- No direct docker commands +- Handle all Docker scenarios gracefully + +## Architecture + +### Layers +1. **CLI Entry Point** (`src/Core/main.go`) +2. **Base Operations** (`src/base/`) - Business logic +3. **Docker Abstraction** (`src/Docker/`) - SDK wrapper +4. **Docker Engine** - Container runtime + +### Structure +``` +src/ +├── Core/main.go # CLI entry +├── base/ # Logic +│ ├── Create.go # DB creation +│ ├── Remove.go # Cleanup +│ ├── Export.go # docker-compose export +│ └── Import.go # docker-compose import +├── Docker/ # SDK wrapper +│ ├── Container.go +│ ├── Volume.go +│ └── Network.go +└── tools/ # Management tools +``` + +## Go Standards + +### Error Handling +```go +// ✅ GOOD - Descriptive with context +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ BAD - Generic +if err != nil { + return err +} +``` + +### Type Safety +```go +// ✅ Struct for options +type ContainerOptions struct { + Name string + Image string + Port int + RestartPolicy string +} + +func CreateContainer(opts ContainerOptions) error + +// ❌ Too many parameters +func CreateContainer(name, image string, port int, restart string) error +``` + +## Key Patterns + +### Auto-Rollback +```go +func CreateDatabase(opts Options) error { + created := []string{} + + defer func() { + if err != nil { + for _, resource := range created { + cleanup(resource) + } + } + }() + + container, err := CreateContainer(opts) + if err != nil { + return err + } + created = append(created, container.ID) +} +``` + +### Docker SDK Usage +```go +// ✅ Use official SDK +import "github.com/docker/docker/client" + +cli, err := client.NewClientWithOpts(client.FromEnv) + +// ❌ Don't execute commands +exec.Command("docker", "run", ...) +``` + +## Documentation + +Update when features change: +- `README.md` - Usage, features, installation +- `DESIGN.md` - Architecture, technical decisions +- `INSTALLATION.md` - Platform-specific guides +- `CONTRIBUTING.md` - Development guidelines + +## Security + +- Never log or display passwords +- Validate all user inputs +- Warn users about root requirements +- Use Docker networks for isolation +- No hardcoded secrets + +## Testing + +- Unit tests: Core logic +- Integration tests: Full CLI workflows +- Cross-platform: Linux, macOS, Windows +- Error scenarios: Network failures, conflicts + +## Supported Databases + +- **SQL**: MySQL, PostgreSQL, MariaDB +- **NoSQL**: MongoDB, Redis +- **Tools**: phpMyAdmin, pgAdmin, RedisInsight, MongoDB Compass + +## Anti-Patterns + +❌ Platform-specific code without fallbacks +❌ Hardcoded credentials +❌ Direct docker commands (use SDK) +❌ Breaking CLI interface +❌ Missing error handling +❌ Incomplete rollback +❌ Skipping cross-platform tests + +## Success Criteria + +- ✅ `go build` passes +- ✅ `go test ./...` passes +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback on errors +- ✅ Clear error messages diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..c4b70d8 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,304 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**ContainDB** - Database Container Management Made Simple + +- **Language**: Go (Golang) ≥1.18 +- **Type**: CLI Tool for Docker-based database management +- **Platform**: Linux, macOS, Windows +- **Distribution**: npm package + native binaries (.deb, direct binary) +- **Purpose**: Simplify containerized database setup and management + +## Commands + +```bash +# Build +go build -o containdb src/Core/main.go # Build CLI binary +./Scripts/BinBuilder.sh # Build for all platforms +./Scripts/PackageBuilder.sh # Build Debian package + +# Development +go run src/Core/main.go # Run directly +go test ./... # Run all tests +go fmt ./... # Format code +go vet ./... # Lint code + +# Distribution +npm run build # Build npm package +npm publish # Publish to npm +``` + +## Core Rules (NON-NEGOTIABLE) + +1. **ALWAYS test**: Test on Linux, macOS, Windows before release +2. **ALWAYS build**: Run `go build` after code changes +3. **NEVER break compatibility**: Support Go 1.18+, maintain CLI interface +4. **Respect Docker**: All operations use Docker API, no direct container manipulation +5. **Error handling**: Always provide clear, actionable error messages +6. **Update docs**: README.md, DESIGN.md, INSTALLATION.md when features change + +## Critical Constraints + +### Cross-Platform Compatibility +- **Must work on**: Linux, macOS, Windows +- **Go version**: ≥1.18 (for generics and performance) +- **Docker**: Docker Engine 20.10+ +- **No platform-specific code** without fallbacks + +### User Experience +- **Interactive prompts** for all sensitive inputs (credentials, ports) +- **Smart defaults** for common scenarios +- **Clear error messages** with actionable solutions +- **Auto-rollback** on failures (cleanup partial state) + +## Architecture Overview + +See `DESIGN.md` for complete details. + +### Layered Architecture +``` +CLI Entry Point (main.go) + ↓ +Base Operations Package (src/base/) + ├── Database creation logic + ├── Container lifecycle management + └── Volume & network handling + ↓ +Docker Abstraction (src/Docker/) + ├── Docker SDK wrapper + ├── Container operations + ├── Volume operations + └── Network operations + ↓ +Docker Engine +``` + +### Module Structure +``` +src/ +├── Core/ # main.go - CLI entry point +├── base/ # Core business logic +│ ├── Create.go # Database creation +│ ├── Remove.go # Resource cleanup +│ ├── Export.go # docker-compose export +│ └── Import.go # docker-compose import +├── Docker/ # Docker API abstraction +│ ├── Container.go # Container operations +│ ├── Volume.go # Volume management +│ └── Network.go # Network operations +└── tools/ # Management tools (phpMyAdmin, pgAdmin, etc.) + +Scripts/ +├── BinBuilder.sh # Multi-platform binary builder +├── PackageBuilder.sh # Debian package builder +└── installer.sh # Linux installer script +``` + +## Go Standards + +### Error Handling +```go +// ✅ GOOD - Descriptive errors with context +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ BAD - Generic errors +if err != nil { + return err +} +``` + +### Package Organization +```go +// ✅ GOOD - Clear package structure +package docker + +import ( + "github.com/docker/docker/client" +) + +func CreateContainer(opts ContainerOptions) error { } + +// ❌ BAD - Mixed concerns +package main + +func CreateContainer() error { } +func ParseConfig() error { } +``` + +### Type Safety +```go +// ✅ GOOD - Use structs for options +type ContainerOptions struct { + Name string + Image string + Port int + RestartPolicy string +} + +func CreateContainer(opts ContainerOptions) error { } + +// ❌ BAD - Too many parameters +func CreateContainer(name, image string, port int, restart string) error { } +``` + +## Key Patterns + +### Auto-Rollback on Failure +```go +func CreateDatabase(opts Options) error { + // Track created resources + created := []string{} + + // Cleanup on error + defer func() { + if err != nil { + for _, resource := range created { + cleanup(resource) + } + } + }() + + // Create resources + container, err := CreateContainer(opts) + if err != nil { + return err + } + created = append(created, container.ID) + + // Continue... +} +``` + +### Interactive Prompts +```go +// ✅ Always prompt for sensitive data +password := promptSecure("Enter database password:") + +// ❌ Never hardcode or use default passwords +password := "password123" +``` + +### Docker API Usage +```go +// ✅ Use official Docker SDK +import "github.com/docker/docker/client" + +cli, err := client.NewClientWithOpts(client.FromEnv) +if err != nil { + return fmt.Errorf("failed to create Docker client: %w", err) +} + +// ❌ Don't execute docker commands directly +exec.Command("docker", "run", ...) +``` + +## Documentation Requirements + +**Update when features change**: +1. **README.md** - Usage examples, installation, features +2. **DESIGN.md** - Architecture diagrams, technical decisions +3. **INSTALLATION.md** - Platform-specific installation instructions +4. **CONTRIBUTING.md** - Development setup, guidelines +5. **Code comments** - All exported functions and complex logic + +## Security + +1. **Credential Handling**: Never log or display passwords +2. **Privilege Management**: Warn users about root requirements +3. **Input Validation**: Validate all user inputs (ports, names, paths) +4. **Container Isolation**: Use Docker networks for container communication +5. **No Hardcoded Secrets**: All credentials via prompts or env vars + +## Testing + +- **Unit tests**: Core logic in `src/base/`, `src/Docker/` +- **Integration tests**: Full CLI workflow tests +- **Cross-platform**: Test on Linux, macOS, Windows +- **Docker scenarios**: Test with/without existing containers, volumes, networks +- **Error cases**: Network failures, permission errors, conflicts + +## Supported Databases + +- **SQL**: MySQL, PostgreSQL, MariaDB +- **NoSQL**: MongoDB, Redis +- **Management Tools**: phpMyAdmin, pgAdmin, RedisInsight, MongoDB Compass + +## Build & Distribution + +### Binary Distribution +```bash +# Build for all platforms +./Scripts/BinBuilder.sh + +# Output: +# - bin/containdb-linux-amd64 +# - bin/containdb-darwin-amd64 +# - bin/containdb-windows-amd64.exe +``` + +### Debian Package +```bash +# Build .deb package +./Scripts/PackageBuilder.sh + +# Output: Packages/containDB_.deb +``` + +### npm Package +```bash +# Build and publish +cd npm/ +npm run build +npm publish +``` + +## Anti-Patterns (FORBIDDEN) + +❌ Platform-specific code without fallbacks +❌ Hardcoded credentials or defaults +❌ Direct docker command execution (use SDK) +❌ Breaking changes to CLI interface +❌ Missing error handling +❌ Incomplete rollback on errors +❌ Skipping cross-platform testing +❌ Missing documentation for new features + +## Workflow Guidelines + +### When Adding Database Support +1. Read `DESIGN.md` to understand architecture +2. Add database configuration to `src/base/Create.go` +3. Add management tool support (if applicable) +4. Update documentation (README, DESIGN) +5. Test on all platforms +6. Update version in `VERSION` file + +### When Fixing Bugs +1. Write failing test that reproduces bug +2. Fix the bug +3. Verify test passes +4. Check for similar issues elsewhere +5. Document the fix in CHANGELOG.md + +### When Refactoring +1. Ensure backward compatibility +2. Run all tests before and after +3. Test on all platforms +4. Update architecture diagrams if structure changes + +## Success Criteria + +Every task must meet ALL: +- ✅ Builds successfully (`go build`) +- ✅ Tests pass (`go test ./...`) +- ✅ Lints pass (`go vet ./...`, `go fmt ./...`) +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback works on errors +- ✅ Clear error messages diff --git a/GEMINI.md b/GEMINI.md new file mode 100644 index 0000000..38d9cf3 --- /dev/null +++ b/GEMINI.md @@ -0,0 +1,151 @@ +# GEMINI.md + +This file provides guidance to Gemini Code Assist when working with code in this repository. + +## Project Overview + +**ContainDB** - Database Container Management CLI Tool + +- **Language**: Go ≥1.18 +- **Type**: CLI for Docker database management +- **Platform**: Linux, macOS, Windows +- **Distribution**: npm + native binaries + +## Commands + +```bash +# Build & Run +go build -o containdb src/Core/main.go +go run src/Core/main.go +./Scripts/BinBuilder.sh # Multi-platform build + +# Test & Lint +go test ./... +go fmt ./... +go vet ./... +``` + +## Core Rules (NON-NEGOTIABLE) + +1. **Cross-platform**: Must work on Linux, macOS, Windows +2. **ALWAYS test**: Test on all platforms before release +3. **ALWAYS build**: Run `go build` after changes +4. **Docker API only**: Use SDK, not direct commands +5. **Auto-rollback**: Cleanup on failures +6. **Update docs**: README, DESIGN, INSTALLATION + +## Architecture + +### Layers +``` +CLI (main.go) + ↓ +Base Operations (src/base/) + ↓ +Docker Abstraction (src/Docker/) + ↓ +Docker Engine +``` + +### Structure +``` +src/ +├── Core/ # main.go +├── base/ # Business logic +│ ├── Create.go +│ ├── Remove.go +│ ├── Export.go +│ └── Import.go +├── Docker/ # Docker SDK wrapper +└── tools/ # Management tools +``` + +## Go Standards + +### Error Handling +```go +// ✅ GOOD +if err != nil { + return fmt.Errorf("failed to create container '%s': %w", name, err) +} + +// ❌ BAD +if err != nil { + return err +} +``` + +### Type Safety +```go +// ✅ Use structs +type ContainerOptions struct { + Name string + Image string + Port int +} + +// ❌ Too many params +func Create(name, image string, port int) error +``` + +## Key Patterns + +### Auto-Rollback +```go +created := []string{} +defer func() { + if err != nil { + for _, id := range created { + cleanup(id) + } + } +}() +``` + +### Docker SDK +```go +// ✅ Use Docker SDK +import "github.com/docker/docker/client" + +cli, err := client.NewClientWithOpts(client.FromEnv) + +// ❌ Don't execute commands +exec.Command("docker", "run", ...) +``` + +## Documentation + +Update when features change: +- `README.md` - Usage, installation +- `DESIGN.md` - Architecture +- `INSTALLATION.md` - Platform guides +- Code comments for exported functions + +## Security + +- Never log passwords +- Validate all inputs +- Warn about root requirements +- Use Docker networks for isolation + +## Testing + +- Unit tests for core logic +- Integration tests for CLI +- Cross-platform testing +- Error case scenarios + +## Supported Systems + +- MySQL, PostgreSQL, MariaDB +- MongoDB, Redis +- phpMyAdmin, pgAdmin, RedisInsight + +## Definition of "Done" + +- ✅ `go build` passes +- ✅ `go test ./...` passes +- ✅ Works on Linux, macOS, Windows +- ✅ Documentation updated +- ✅ Backward compatible +- ✅ Auto-rollback works diff --git a/INSTALLATION.md b/INSTALLATION.md index f14eb97..75ed606 100644 --- a/INSTALLATION.md +++ b/INSTALLATION.md @@ -19,10 +19,10 @@ This is the simplest method for Debian-based systems like Ubuntu, Debian, Linux ```bash # Download the latest .deb release -wget https://github.com/nexoral/ContainDB/releases/download/v7.19.42-stable/containDB_7.19.42-stable_amd64.deb +wget https://github.com/nexoral/ContainDB/releases/download/v7.19.43-stable/containDB_7.19.43-stable_amd64.deb # Install the package -sudo dpkg -i containDB_7.19.42-stable_amd64.deb +sudo dpkg -i containDB_7.19.43-stable_amd64.deb # If you see dependency errors, run: sudo apt-get install -f diff --git a/Scripts/installer.sh b/Scripts/installer.sh index f8a3309..9f68ae3 100755 --- a/Scripts/installer.sh +++ b/Scripts/installer.sh @@ -7,7 +7,7 @@ ARCH=$(dpkg --print-architecture) echo "Detected architecture: $ARCH" -VERSION="7.19.42-stable" +VERSION="7.19.43-stable" if [[ "$ARCH" == "amd64" ]]; then PKG="containdb_${VERSION}_amd64.deb" diff --git a/VERSION b/VERSION index 3211a6c..b5892ba 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -7.19.42-stable +7.19.43-stable diff --git a/npm/package.json b/npm/package.json index 8b99e64..9fd23f4 100644 --- a/npm/package.json +++ b/npm/package.json @@ -1,6 +1,6 @@ { "name": "containdb", - "version": "7.19.42", + "version": "7.19.43", "description": "The Ultimate Docker Database Manager. Automate the creation, management, and monitoring of containerized databases (MongoDB, MySQL, PostgreSQL, Redis) and their GUI tools (Compass, phpMyAdmin, PgAdmin, RedisInsight) with a simple CLI. No complex Docker commands—just productivity.", "bin": { "containdb": "./InstallController.js" diff --git a/src/Core/main.go b/src/Core/main.go index 9e8bddc..272ccd1 100644 --- a/src/Core/main.go +++ b/src/Core/main.go @@ -11,7 +11,7 @@ import ( ) func main() { - VERSION := "7.19.42-stable" + VERSION := "7.19.43-stable" // handle version flag without requiring sudo if len(os.Args) > 1 && os.Args[1] == "--version" { diff --git a/src/base/Banner.go b/src/base/Banner.go index 54f6be3..7941b1e 100644 --- a/src/base/Banner.go +++ b/src/base/Banner.go @@ -9,7 +9,7 @@ import ( "github.com/fatih/color" ) -const Version = "7.19.42-stable" +const Version = "7.19.43-stable" func ShowBanner() { // Define styles