aitbc
31c7e3f6a9
Development Environment Cleanup - Complete: ✅ DUPLICATE PACKAGE.JSON REMOVED: Cleaned up redundant smart contracts development setup - /opt/aitbc/dev/env/package.json completely removed (duplicate configuration) - /opt/aitbc/dev/env/package-lock.json removed (duplicate lock file) - /opt/aitbc/dev/env/node_modules/ removed (duplicate dependencies) - Root cause: dev/env/package.json was basic duplicate of contracts/package.json ✅ DUPLICATION ANALYSIS COMPLETED: 📊 Main Package: contracts/package.json (complete smart contracts setup) 📋 Duplicate: dev/env/package.json (basic setup with limited dependencies) 🔗 Dependencies: Both had @openzeppelin/contracts, ethers, hardhat 📝 Scripts: Both had compile and deploy scripts 📁 Structure: Both standard Node.js package structure ✅ PRIMARY PACKAGE PRESERVED: 📁 Location: /opt/aitbc/contracts/package.json (main smart contracts setup) 📦 Dependencies: Complete set of smart contracts development tools 🔧 Scripts: Comprehensive Hardhat scripts for compilation and deployment ⚙️ Configuration: Full Hardhat configuration with all necessary plugins ✅ DEVELOPMENT ENVIRONMENT CLEANED: 📁 dev/env/: Now contains only essential environment directories 📦 node_modules/: Removed duplicate (use contracts/node_modules/) 📋 .venv/: Python virtual environment for development 🗑️ package.json: Removed (use contracts/package.json) ✅ DOCUMENTATION UPDATED: 📚 Development Guidelines: Removed duplicate package.json references 📁 File Organization: Updated to reflect clean structure 📖 Documentation: Consistent with actual directory structure ✅ ROOT CAUSE RESOLVED: - Problem: Duplicate smart contracts development setup in dev/env - Development History: Basic package.json created during early development - Current State: Complete package.json available in contracts/ - Solution: Remove duplicate, use contracts/package.json as primary ✅ BENEFITS ACHIEVED: ✅ Single Source of Truth: One package.json for smart contracts development ✅ Reduced Duplication: No duplicate node_modules or package files ✅ Cleaner Structure: dev/env focused on environment, not package management ✅ Consistent Workflow: Use contracts/ directory for all smart contracts work ✅ Disk Space Savings: Removed duplicate node_modules DIRECTORY STRUCTURE IMPROVEMENT: 📁 contracts/: Complete smart contracts development setup 📁 dev/env/: Clean environment directories only 🗑️ dev/env/package.json: Removed (duplicate) 🗑️ dev/env/package-lock.json: Removed (duplicate) 🗑️ dev/env/node_modules/: Removed (duplicate) RESULT: Successfully removed duplicate package.json from dev/env directory, consolidating smart contracts development setup in contracts/ directory and achieving clean, non-duplicate development environment structure.
230 lines
5.4 KiB
Markdown
230 lines
5.4 KiB
Markdown
# Developer File Organization Guidelines
|
|
|
|
## 📁 Where to Put Files
|
|
|
|
### Essential Root Files (Keep at Root)
|
|
- `.editorconfig` - Editor configuration
|
|
- `.env.example` - Environment template
|
|
- `.gitignore` - Git ignore rules
|
|
- `LICENSE` - Project license
|
|
- `README.md` - Project documentation
|
|
- `pyproject.toml` - Python project configuration
|
|
- `poetry.lock` - Dependency lock file
|
|
- `pytest.ini` - Test configuration
|
|
- `scripts/testing/run_all_tests.sh` - Main test runner
|
|
|
|
### Development Scripts → `dev/scripts/`
|
|
```bash
|
|
# Development fixes and patches
|
|
dev/scripts/fix_*.py
|
|
dev/scripts/fix_*.sh
|
|
dev/scripts/patch_*.py
|
|
dev/scripts/simple_test.py
|
|
```
|
|
|
|
### Test Files → `dev/tests/`
|
|
```bash
|
|
# Test scripts and scenarios
|
|
dev/tests/test_*.py
|
|
dev/tests/test_*.sh
|
|
dev/tests/test_scenario_*.sh
|
|
dev/tests/run_mc_test.sh
|
|
dev/tests/simple_test_results.json
|
|
```
|
|
|
|
### Multi-Chain Testing → `dev/multi-chain/`
|
|
```bash
|
|
# Multi-chain specific files
|
|
dev/multi-chain/MULTI_*.md
|
|
dev/multi-chain/test_multi_chain*.py
|
|
dev/multi-chain/test_multi_site.py
|
|
```
|
|
|
|
### Configuration Files → `config/`
|
|
```bash
|
|
# Configuration and environment files
|
|
config/.aitbc.yaml
|
|
config/.aitbc.yaml.example
|
|
config/.env.production
|
|
config/.nvmrc
|
|
config/.lycheeignore
|
|
```
|
|
|
|
### Development Environment → `dev/env/`
|
|
```bash
|
|
# Environment directories
|
|
dev/env/node_modules/
|
|
dev/env/.venv/
|
|
```
|
|
|
|
### Cache and Temporary → `dev/cache/`
|
|
```bash
|
|
# Cache and temporary directories
|
|
dev/cache/.pytest_cache/
|
|
dev/cache/.ruff_cache/
|
|
dev/cache/logs/
|
|
dev/cache/.vscode/
|
|
```
|
|
|
|
## 🚀 Quick Start Commands
|
|
|
|
### Creating New Files
|
|
```bash
|
|
# Create a new test script
|
|
touch dev/tests/test_my_feature.py
|
|
|
|
# Create a new development script
|
|
touch dev/scripts/fix_my_issue.py
|
|
|
|
# Create a new patch script
|
|
touch dev/scripts/patch_component.py
|
|
```
|
|
|
|
### Checking Organization
|
|
```bash
|
|
# Check current file organization
|
|
./scripts/check-file-organization.sh
|
|
|
|
# Auto-fix organization issues
|
|
./scripts/move-to-right-folder.sh --auto
|
|
```
|
|
|
|
### Git Integration
|
|
```bash
|
|
# Git will automatically check file locations on commit
|
|
git add .
|
|
git commit -m "My changes" # Will run pre-commit hooks
|
|
```
|
|
|
|
## ⚠️ Common Mistakes to Avoid
|
|
|
|
### ❌ Don't create these files at root:
|
|
- `test_*.py` or `test_*.sh` → Use `dev/tests/`
|
|
- `patch_*.py` or `fix_*.py` → Use `dev/scripts/`
|
|
- `MULTI_*.md` → Use `dev/multi-chain/`
|
|
- `node_modules/` or `.venv/` → Use `dev/env/`
|
|
- `.pytest_cache/` or `.ruff_cache/` → Use `dev/cache/`
|
|
|
|
### ✅ Do this instead:
|
|
```bash
|
|
# Right way to create test files
|
|
touch dev/tests/test_new_feature.py
|
|
|
|
# Right way to create patch files
|
|
touch dev/scripts/fix_bug.py
|
|
|
|
# Right way to handle dependencies
|
|
npm install # Will go to dev/env/node_modules/
|
|
python -m venv dev/env/.venv
|
|
```
|
|
|
|
## 🔧 IDE Configuration
|
|
|
|
### VS Code
|
|
The project includes `.vscode/settings.json` with:
|
|
- Excluded patterns for cache directories
|
|
- File watcher exclusions
|
|
- Auto-format on save
|
|
- Organize imports on save
|
|
|
|
### Git Hooks
|
|
Pre-commit hooks automatically:
|
|
- Check file locations
|
|
- Suggest correct locations
|
|
- Prevent commits with misplaced files
|
|
|
|
## 📞 Getting Help
|
|
|
|
If you're unsure where to put a file:
|
|
1. Run `./scripts/check-file-organization.sh`
|
|
2. Check this guide
|
|
3. Ask in team chat
|
|
4. When in doubt, use `dev/` subdirectories
|
|
|
|
## 🔄 Maintenance
|
|
|
|
- Weekly: Run organization check
|
|
- Monthly: Review new file patterns
|
|
- As needed: Update guidelines for new file types
|
|
|
|
## 🛡️ Prevention System
|
|
|
|
The project includes a comprehensive prevention system:
|
|
|
|
### 1. Git Pre-commit Hooks
|
|
- Automatically check file locations before commits
|
|
- Block commits with misplaced files
|
|
- Provide helpful suggestions
|
|
|
|
### 2. Automated Scripts
|
|
- `check-file-organization.sh` - Scan for issues
|
|
- `move-to-right-folder.sh` - Auto-fix organization
|
|
|
|
### 3. IDE Configuration
|
|
- VS Code settings hide clutter
|
|
- File nesting for better organization
|
|
- Tasks for easy access to tools
|
|
|
|
### 4. CI/CD Validation
|
|
- Pull request checks for file organization
|
|
- Automated comments with suggestions
|
|
- Block merges with organization issues
|
|
|
|
## 🎯 Best Practices
|
|
|
|
### File Naming
|
|
- Use descriptive names
|
|
- Follow existing patterns
|
|
- Include file type in name (test_, patch_, fix_)
|
|
|
|
### Directory Structure
|
|
- Keep related files together
|
|
- Use logical groupings
|
|
- Maintain consistency
|
|
|
|
### Development Workflow
|
|
1. Create files in correct location initially
|
|
2. Use IDE tasks to check organization
|
|
3. Run scripts before commits
|
|
4. Fix issues automatically when prompted
|
|
|
|
## 🔍 Troubleshooting
|
|
|
|
### Common Issues
|
|
|
|
#### "Git commit blocked due to file organization"
|
|
```bash
|
|
# Run the auto-fix script
|
|
./scripts/move-to-right-folder.sh --auto
|
|
|
|
# Then try commit again
|
|
git add .
|
|
git commit -m "My changes"
|
|
```
|
|
|
|
#### "Can't find my file"
|
|
```bash
|
|
# Check if it was moved automatically
|
|
find . -name "your-file-name"
|
|
|
|
# Or check organization status
|
|
./scripts/check-file-organization.sh
|
|
```
|
|
|
|
#### "VS Code shows too many files"
|
|
- The `.vscode/settings.json` excludes cache directories
|
|
- Reload VS Code to apply settings
|
|
- Check file explorer settings
|
|
|
|
## 📚 Additional Resources
|
|
|
|
- [Project Organization Workflow](../../.windsurf/workflows/project-organization.md)
|
|
- [File Organization Prevention System](../../.windsurf/workflows/file-organization-prevention.md)
|
|
- [Git Hooks Documentation](https://git-scm.com/book/en/v2/Customizing-Git-Git-Hooks)
|
|
- [VS Code Settings](https://code.visualstudio.com/docs/getstarted/settings)
|
|
|
|
---
|
|
|
|
*Last updated: March 2, 2026*
|
|
*For questions or suggestions, please open an issue or contact the development team.*
|