docs: add ai-toolset setup and deployment guide
Comprehensive guide for initializing and using the ai-toolset repository. Includes: - Repository setup options - Submodule integration - CI/CD examples - Customization guide - Troubleshooting 🤖 Generated with Claude Code Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Administrator
338
AI_TOOLSET_SETUP.md
Normal file
338
AI_TOOLSET_SETUP.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# AI Toolset Repository Setup
|
||||
|
||||
This document provides instructions for setting up the ai-toolset repository and using it as a submodule.
|
||||
|
||||
## Current Status
|
||||
|
||||
✅ **Main Repository:** Successfully pushed to `ssh://git@194.163.145.241:2222/copper-tone-tech/mev-beta.git`
|
||||
|
||||
⚠️ **AI Toolset Remote:** Configured but needs initialization
|
||||
|
||||
## Repository URLs
|
||||
|
||||
- **Main Project:** `ssh://git@194.163.145.241:2222/copper-tone-tech/mev-beta.git`
|
||||
- **AI Toolset:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
|
||||
|
||||
## Option 1: Force Push to ai-toolset (New Repository)
|
||||
|
||||
If the ai-toolset repository is empty or you want to replace its contents:
|
||||
|
||||
```bash
|
||||
# Force push current branch as main
|
||||
git push ai-toolset v2-master-dev:main --force
|
||||
|
||||
# Verify
|
||||
git ls-remote ai-toolset
|
||||
```
|
||||
|
||||
## Option 2: Initialize ai-toolset Repository (Recommended)
|
||||
|
||||
If you want to keep ai-toolset separate and sync changes:
|
||||
|
||||
```bash
|
||||
# Create a dedicated branch for ai-toolset
|
||||
git checkout -b ai-toolset-main
|
||||
|
||||
# Push to ai-toolset
|
||||
git push ai-toolset ai-toolset-main:main
|
||||
|
||||
# Return to development branch
|
||||
git checkout v2-master-dev
|
||||
```
|
||||
|
||||
## Option 3: Use as Submodule in Other Projects
|
||||
|
||||
Once the ai-toolset repository is set up, other projects can include it:
|
||||
|
||||
### In Your Other Project
|
||||
|
||||
```bash
|
||||
# Navigate to your project
|
||||
cd /path/to/your-project
|
||||
|
||||
# Add as submodule
|
||||
git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset
|
||||
|
||||
# Initialize
|
||||
git submodule update --init --recursive
|
||||
|
||||
# Commit
|
||||
git add .gitmodules tools/ai-toolset
|
||||
git commit -m "Add ai-toolset for audit and testing infrastructure"
|
||||
```
|
||||
|
||||
### Using the Scripts
|
||||
|
||||
After adding as submodule:
|
||||
|
||||
```bash
|
||||
# Run audit
|
||||
./tools/ai-toolset/scripts/audit.sh
|
||||
|
||||
# Run tests
|
||||
./tools/ai-toolset/scripts/test.sh all
|
||||
|
||||
# Check compliance
|
||||
./tools/ai-toolset/scripts/check-compliance.sh
|
||||
|
||||
# Check documentation
|
||||
./tools/ai-toolset/scripts/check-docs.sh
|
||||
```
|
||||
|
||||
## What's Included in ai-toolset
|
||||
|
||||
### 🔧 Audit & Testing Scripts
|
||||
|
||||
1. **audit.sh** (394 lines)
|
||||
- 12-section comprehensive audit
|
||||
- SPEC.md compliance
|
||||
- Security scanning
|
||||
- Code quality analysis
|
||||
- Colored output with severity levels
|
||||
|
||||
2. **test.sh** (267 lines)
|
||||
- 7 test types
|
||||
- Container-based execution
|
||||
- Coverage reports (HTML + percentage)
|
||||
- Verbose mode support
|
||||
|
||||
3. **check-compliance.sh** (321 lines)
|
||||
- 8 MUST DO requirements
|
||||
- 7 MUST NOT DO violations
|
||||
- Architecture validation
|
||||
- Foundry integration check
|
||||
|
||||
4. **check-docs.sh** (238 lines)
|
||||
- Package documentation
|
||||
- Exported symbols coverage
|
||||
- README validation
|
||||
- Comment density analysis
|
||||
|
||||
### 📚 Documentation (1,700+ lines)
|
||||
|
||||
- **SPEC.md** - Technical specification
|
||||
- **docs/AUDIT_AND_TESTING.md** - Complete testing guide (600+ lines)
|
||||
- **docs/SCRIPTS_REFERENCE.md** - All scripts documented (700+ lines)
|
||||
- **docs/README.md** - Documentation index
|
||||
- **docs/DEVELOPMENT_SETUP.md** - Environment setup
|
||||
- **docs/REFACTORING_PLAN.md** - Systematic refactoring plan
|
||||
|
||||
### 🛠️ Development Infrastructure
|
||||
|
||||
- **scripts/dev.sh** - Unified development script
|
||||
- **scripts/dev-up.sh** - Start containers
|
||||
- **scripts/dev-down.sh** - Stop containers
|
||||
- **scripts/generate-bindings.sh** - Contract binding generation
|
||||
- **scripts/extract-official-abis.sh** - ABI extraction
|
||||
|
||||
### 📦 Code Quality Improvements
|
||||
|
||||
- **pkg/validation/helpers.go** - Address/amount validation
|
||||
- **pkg/sequencer/selector_registry.go** - Function selector registry
|
||||
- Fixed race conditions (13 atomic metrics)
|
||||
- Added error logging (0 silent failures)
|
||||
- Address validation at ingress points
|
||||
|
||||
## Quick Start (After Repository Setup)
|
||||
|
||||
### As a Submodule User
|
||||
|
||||
```bash
|
||||
# 1. Add to your project
|
||||
git submodule add ssh://git@194.163.145.241:2222/administrator/ai-toolset tools/ai-toolset
|
||||
|
||||
# 2. Create symlinks (optional but recommended)
|
||||
mkdir -p scripts
|
||||
ln -s ../tools/ai-toolset/scripts/audit.sh scripts/audit.sh
|
||||
ln -s ../tools/ai-toolset/scripts/test.sh scripts/test.sh
|
||||
ln -s ../tools/ai-toolset/scripts/check-compliance.sh scripts/check-compliance.sh
|
||||
ln -s ../tools/ai-toolset/scripts/check-docs.sh scripts/check-docs.sh
|
||||
|
||||
# 3. Use from your project root
|
||||
./scripts/audit.sh
|
||||
./scripts/test.sh all
|
||||
./scripts/check-compliance.sh
|
||||
```
|
||||
|
||||
### Updating the Submodule
|
||||
|
||||
```bash
|
||||
# Update to latest version
|
||||
cd tools/ai-toolset
|
||||
git pull origin main
|
||||
cd ../..
|
||||
|
||||
# Commit the update
|
||||
git add tools/ai-toolset
|
||||
git commit -m "Update ai-toolset to latest version"
|
||||
```
|
||||
|
||||
## CI/CD Integration Examples
|
||||
|
||||
### GitHub Actions
|
||||
|
||||
```yaml
|
||||
# .github/workflows/audit.yml
|
||||
name: Code Audit
|
||||
|
||||
on: [push, pull_request]
|
||||
|
||||
jobs:
|
||||
audit:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v3
|
||||
with:
|
||||
submodules: recursive
|
||||
|
||||
- name: Run Audit
|
||||
run: ./tools/ai-toolset/scripts/audit.sh
|
||||
|
||||
- name: Run Tests
|
||||
run: ./tools/ai-toolset/scripts/test.sh all
|
||||
|
||||
- name: Check Compliance
|
||||
run: ./tools/ai-toolset/scripts/check-compliance.sh
|
||||
```
|
||||
|
||||
### GitLab CI
|
||||
|
||||
```yaml
|
||||
# .gitlab-ci.yml
|
||||
audit:
|
||||
stage: test
|
||||
script:
|
||||
- git submodule update --init --recursive
|
||||
- ./tools/ai-toolset/scripts/audit.sh
|
||||
- ./tools/ai-toolset/scripts/test.sh all
|
||||
- ./tools/ai-toolset/scripts/check-compliance.sh
|
||||
```
|
||||
|
||||
## Customization for Your Project
|
||||
|
||||
### 1. SPEC.md
|
||||
|
||||
The included SPEC.md is for the MEV bot. Create your own:
|
||||
|
||||
```bash
|
||||
# Copy as template
|
||||
cp tools/ai-toolset/SPEC.md ./SPEC.md
|
||||
|
||||
# Customize for your project
|
||||
vim SPEC.md
|
||||
```
|
||||
|
||||
### 2. Scripts
|
||||
|
||||
Scripts are designed to be project-agnostic but can be customized:
|
||||
|
||||
```bash
|
||||
# Copy and modify
|
||||
cp tools/ai-toolset/scripts/audit.sh ./scripts/audit-custom.sh
|
||||
|
||||
# Edit for your needs
|
||||
vim scripts/audit-custom.sh
|
||||
```
|
||||
|
||||
### 3. Documentation Structure
|
||||
|
||||
Use the documentation as a template:
|
||||
|
||||
```bash
|
||||
# Copy structure
|
||||
cp -r tools/ai-toolset/docs/* ./docs/
|
||||
|
||||
# Adapt to your project
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Submodule Not Initialized
|
||||
|
||||
```bash
|
||||
git submodule update --init --recursive
|
||||
```
|
||||
|
||||
### Permission Denied
|
||||
|
||||
```bash
|
||||
chmod +x tools/ai-toolset/scripts/*.sh
|
||||
```
|
||||
|
||||
### Cannot Push to ai-toolset
|
||||
|
||||
If the repository already exists with content:
|
||||
|
||||
```bash
|
||||
# Fetch existing content
|
||||
git fetch ai-toolset
|
||||
|
||||
# Merge or rebase
|
||||
git pull ai-toolset main --allow-unrelated-histories
|
||||
|
||||
# Then push
|
||||
git push ai-toolset v2-master-dev:main
|
||||
```
|
||||
|
||||
### Fresh Start
|
||||
|
||||
If you want to completely replace ai-toolset content:
|
||||
|
||||
```bash
|
||||
git push ai-toolset v2-master-dev:main --force
|
||||
```
|
||||
|
||||
## Verification
|
||||
|
||||
After setup, verify everything works:
|
||||
|
||||
```bash
|
||||
# Clone test
|
||||
git clone --recursive ssh://git@194.163.145.241:2222/administrator/ai-toolset test-ai-toolset
|
||||
cd test-ai-toolset
|
||||
|
||||
# Test scripts
|
||||
./scripts/audit.sh
|
||||
./scripts/test.sh --help
|
||||
./scripts/check-compliance.sh --help
|
||||
|
||||
# Verify documentation
|
||||
ls -la docs/
|
||||
```
|
||||
|
||||
## Summary of Changes
|
||||
|
||||
This setup provides:
|
||||
|
||||
- ✅ **34 files** added/modified in latest commit
|
||||
- ✅ **7,514 lines** of code and documentation
|
||||
- ✅ **4 comprehensive audit scripts**
|
||||
- ✅ **5 documentation files** (1,700+ lines)
|
||||
- ✅ **9 development scripts**
|
||||
- ✅ **Phase 1 refactoring** complete (race conditions fixed, validation added)
|
||||
- ✅ **Build status:** All packages compile
|
||||
- ✅ **SPEC.md violations:** Reduced from 7 to 5
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. **Push to ai-toolset** using one of the options above
|
||||
2. **Test as submodule** in another project
|
||||
3. **Configure CI/CD** with the provided examples
|
||||
4. **Customize** SPEC.md for your project
|
||||
5. **Run audits** regularly as part of your development workflow
|
||||
|
||||
## Support
|
||||
|
||||
For detailed usage information:
|
||||
|
||||
- Read `SUBMODULE_USAGE.md` for comprehensive guide
|
||||
- Check `docs/SCRIPTS_REFERENCE.md` for all script documentation
|
||||
- Review `docs/AUDIT_AND_TESTING.md` for testing guidelines
|
||||
- See commit history for examples and patterns
|
||||
|
||||
---
|
||||
|
||||
**Repository:** `ssh://git@194.163.145.241:2222/administrator/ai-toolset`
|
||||
**Status:** Ready for initial push
|
||||
**Last Updated:** 2025-11-11
|
||||
**Commits:** 2 (audit infrastructure + submodule documentation)
|
||||
Reference in New Issue
Block a user