mev-beta/AI_TOOLSET_SETUP.md

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:

# 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:

# 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

# 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:

# 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

# 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

# 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

# .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

# .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:

# 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:

# 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:

# Copy structure
cp -r tools/ai-toolset/docs/* ./docs/

# Adapt to your project

Troubleshooting

Submodule Not Initialized

git submodule update --init --recursive

Permission Denied

chmod +x tools/ai-toolset/scripts/*.sh

Cannot Push to ai-toolset

If the repository already exists with content:

# 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:

git push ai-toolset v2-master-dev:main --force

Verification

After setup, verify everything works:

# 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)