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:

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