sjs/vibetunnel
1
0
Fork 0
mirror of https://github.com/samsonjs/vibetunnel.git synced 2026-03-25 09:25:50 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

docs update

Browse source
This commit is contained in:
Peter Steinberger 2025-07-19 02:51:17 +02:00
parent 754f06afb8
commit 342852007b
5 changed files with 219 additions and 693 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

76
docs.json
View file

@ -53,7 +53,8 @@
"docs/INDEX",
"docs/project-overview",
"docs/keyboard-shortcuts",
"docs/CONTRIBUTING"
"docs/CONTRIBUTING",
"CHANGELOG"
]
},
{
@ -61,7 +62,8 @@
"pages": [
"mac/README",
"ios/README",
"web/docs/VT_INSTALLATION"
"web/docs/VT_INSTALLATION",
"docs/custom-node"
]
},
{
@ -74,15 +76,17 @@
"web/docs/spec",
"mac/docs/BuildArchitectures",
"web/docs/socket-protocol",
"docs/authentication"
"docs/authentication",
"docs/security"
]
},
{
"group": "Security",
"group": "Advanced Features",
"pages": [
"docs/security",
"docs/hq",
"docs/push-notification",
"docs/WEBRTC_CONFIG"
"web/docs/terminal-titles",
"docs/TESTING_EXTERNAL_DEVICES"
]
},
{
@ -91,7 +95,8 @@
"docs/development",
"docs/build-system",
"docs/testing",
"docs/logging-style-guide"
"docs/logging-style-guide",
"docs/files"
]
},
{
@ -99,61 +104,68 @@
"pages": [
"mac/docs/BuildRequirements",
"mac/docs/code-signing",
"mac/docs/screencap",
"mac/docs/screencapturekit"
"mac/docs/RELEASE_GUIDE",
"mac/docs/sparkle-keys",
"mac/docs/sparkle-stats-store"
]
},
{
"group": "iOS Development",
"pages": [
"ios/conversion",
"apple/docs/modern-swift",
"apple/docs/swift-concurrency",
"apple/docs/swiftui",
"apple/docs/swift-testing-playbook"
"apple/docs/swift-testing-playbook",
"apple/docs/logging-private-fix"
]
},
{
"group": "iOS Testing",
"pages": [
"ios/VibeTunnelTests/README",
"ios/VibeTunnelTests/TestCoverage",
"ios/VibeTunnelTests/TestingApproach"
]
},
{
"group": "Web Development",
"pages": [
"web/README",
"web/docs/performance",
"web/docs/terminal-titles",
"docs/TESTING_EXTERNAL_DEVICES"
"web/docs/playwright-testing",
"web/src/test/playwright/SEQUENTIAL_OPTIMIZATIONS",
"web/docs/npm"
]
},
{
"group": "Release Process",
"group": "Release & Deployment",
"pages": [
"docs/deployment",
"docs/RELEASE"
]
},
{
"group": "Distribution",
"group": "Experimental",
"pages": [
"web/docs/npm",
"mac/docs/sparkle-keys",
"mac/docs/sparkle-stats-store"
]
},
{
"group": "Configuration",
"pages": [
"docs/custom-node",
"apple/docs/logging-private-fix"
]
},
{
"group": "File Structure",
"pages": [
"docs/files",
".github/workflows/README.md"
"tauri/README",
"tauri/IMPROVEMENTS"
]
},
{
"group": "Tools & Integration",
"pages": [
"docs/claude",
"docs/gemini"
"CLAUDE",
"docs/gemini",
"GEMINI",
".github/workflows/README"
]
},
{
"group": "Maintenance",
"pages": [
"docs/org-migrate"
]
}
]

253
docs/org-migrate.md
View file

@ -1,18 +1,16 @@
# GitHub Organization Migration Plan
This document outlines the migration process for moving the VibeTunnel repository from `amantus-ai/vibetunnel` to `vibetunnel/vibetunnel`.
This document outlines the migration process for moving VibeTunnel from `amantus-ai/vibetunnel` to `vibetunnel/vibetunnel`.
## 1. Fast-lane Transfer (GitHub Built-in Method)
**Status: TODO** - This migration has not been completed yet.
The simplest approach using GitHub's native transfer feature:
## Migration Options
1. Navigate to **Settings → General → Danger Zone → Transfer**
2. Enter the new owner: `vibetunnel`
3. Type the repository name to confirm
4. Accept the invite from the destination org
5. Done! ✅
### Option 1: Simple Transfer (GitHub Built-in)
### What Transfers Automatically
The simplest approach using GitHub's native transfer feature.
#### What Transfers Automatically
✅ **Code & History**
- All branches and commit history
@ -36,7 +34,7 @@ The simplest approach using GitHub's native transfer feature:
- GitHub Actions workflows
- Git LFS objects (copied in background)
### What Needs Manual Updates
#### What Needs Manual Updates
⚠️ **Organization-level Settings**
- Branch protection rules (inherits new org defaults - review carefully)
@ -51,9 +49,19 @@ The simplest approach using GitHub's native transfer feature:
- External webhooks
- Status badges in README
## 2. Zero-Downtime Migration Checklist
### Option 2: Migration with History Cleanup
### Pre-Migration (1-2 days before)
Since `https://github.com/vibetunnel/vibetunnel` may already exist, we can perform a clean migration that:
1. Removes large files from history
2. Cleans up accidental commits
3. Preserves important history
4. Maintains all issues, PRs, and project management features
Use BFG Repo-Cleaner or git-filter-repo to create a cleaned version of the repository.
## Pre-Migration Checklist
### Preparation (1-2 days before)
- [ ] **Prepare Target Organization**
- Create `vibetunnel` organization if not exists
@ -67,54 +75,137 @@ The simplest approach using GitHub's native transfer feature:
- Note branch protection rules
- Identify external services using the repo
- [ ] **Analyze Repository for Cleanup (if using Option 2)**
```bash
# Find large files in history
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
awk '/^blob/ && $3 > 10485760 {print $3, $4}' | \
sort -rn | \
numfmt --field=1 --to=iec
```
- [ ] **Notify Stakeholders**
- Team members about the migration
- Users via issue/discussion if needed
- Update any public documentation
### Migration Day
## Migration Process
- [ ] **Pause Activity (Optional but Recommended)**
- Merge or close active PRs
- Create a migration tag: `pre-migration-snapshot`
- Announce brief maintenance window
### Option 1: Simple Transfer Steps
- [ ] **Execute Transfer**
- Perform the GitHub transfer
- Accept invitation immediately
- Verify all content transferred
1. Navigate to **Settings → General → Danger Zone → Transfer**
2. Enter the new owner: `vibetunnel`
3. Type the repository name to confirm
4. Accept the invite from the destination org
5. Done! ✅
- [ ] **Immediate Post-Transfer**
- Push a test commit to verify write access
- Check Actions are running
- Verify webhooks are firing
### Option 2: Clean Migration Script
### Post-Migration Updates
Save this as `migrate-clean.sh`:
- [ ] **Update Git Remotes**
```bash
# For all local clones
git remote set-url origin git@github.com:vibetunnel/vibetunnel.git
# Verify the change
git remote -v
```
```bash
#!/bin/bash
set -euo pipefail
- [ ] **Update Documentation**
- README badges and links
- Installation instructions
- Contributing guidelines
- API documentation
# Configuration
OLD_REPO="git@github.com:amantus-ai/vibetunnel.git"
NEW_REPO="git@github.com:vibetunnel/vibetunnel.git"
TEMP_DIR="vibetunnel-migration-$(date +%Y%m%d-%H%M%S)"
SIZE_THRESHOLD="10M" # Files larger than this will be removed
- [ ] **Update External Services**
- CI/CD configurations
- Package registry URLs
- Monitoring services
- Documentation sites
echo "🚀 Starting VibeTunnel repository migration with cleanup..."
- [ ] **Update Package Configurations**
# Create temporary directory
mkdir -p "$TEMP_DIR"
cd "$TEMP_DIR"
# Clone the repository (all branches and tags)
echo "📥 Cloning repository with all history..."
git clone --mirror "$OLD_REPO" vibetunnel-mirror
cd vibetunnel-mirror
# Create a backup first
echo "💾 Creating backup..."
cp -r . ../vibetunnel-backup
# Analyze repository for large files
echo "🔍 Analyzing repository for large files..."
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
awk '/^blob/ {print substr($0,6)}' | \
sort --numeric-sort --key=2 --reverse | \
awk '$2 >= 10485760 {print $1, $2, $3}' > ../large-files.txt
echo "📊 Large files found:"
cat ../large-files.txt | while read hash size path; do
echo " - $path ($(numfmt --to=iec $size))"
done
# Download BFG Repo-Cleaner if not available
if ! command -v bfg &> /dev/null && [ ! -f ../bfg.jar ]; then
echo "📦 Downloading BFG Repo-Cleaner..."
curl -L -o ../bfg.jar https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
fi
# Clean large files using BFG
echo "🧹 Removing large files from history..."
java -jar ../bfg.jar --strip-blobs-bigger-than "$SIZE_THRESHOLD" --no-blob-protection
# Clean specific file patterns (customize as needed)
echo "🗑️ Removing unwanted file patterns..."
java -jar ../bfg.jar --delete-files '*.{log,tmp,cache}' --no-blob-protection
java -jar ../bfg.jar --delete-folders '{node_modules,dist,build}' --no-blob-protection
# Clean up the repository
echo "♻️ Cleaning up repository..."
git reflog expire --expire=now --all
git gc --prune=now --aggressive
# Show size comparison
echo "📏 Size comparison:"
cd ..
ORIGINAL_SIZE=$(du -sh vibetunnel-backup | cut -f1)
CLEANED_SIZE=$(du -sh vibetunnel-mirror | cut -f1)
echo " Original: $ORIGINAL_SIZE"
echo " Cleaned: $CLEANED_SIZE"
# Update remote URL and push
cd vibetunnel-mirror
git remote set-url origin "$NEW_REPO"
# Interactive confirmation
echo "⚠️ Ready to push to $NEW_REPO"
read -p "Continue? (y/N) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "❌ Aborted"
exit 1
fi
# Push to new repository
echo "📤 Pushing to new repository..."
git push --mirror "$NEW_REPO"
echo "✅ Migration complete!"
```
## Post-Migration Updates
### Update Git Remotes
```bash
# For all local clones
git remote set-url origin git@github.com:vibetunnel/vibetunnel.git
# Verify the change
git remote -v
```
### Update VibeTunnel Code
- [ ] Update `GITHUB_URL` in `mac/VibeTunnel/version.xcconfig`
- [ ] Update repository URLs in all `package.json` files:
```json
// package.json
{
"repository": {
"type": "git",
@ -126,8 +217,29 @@ The simplest approach using GitHub's native transfer feature:
"homepage": "https://github.com/vibetunnel/vibetunnel#readme"
}
```
- [ ] Update any hardcoded GitHub URLs in documentation
- [ ] Update CLAUDE.md references
- [ ] Update docs.json if it contains repository URLs
## 3. Redirect Behavior
### Update External Services
- [ ] CI/CD configurations
- [ ] npm package registry URLs
- [ ] Monitoring services
- [ ] Documentation sites
- [ ] README badges and links
- [ ] Installation instructions
- [ ] Contributing guidelines
### Build & Release
- [ ] Update GitHub Actions secrets if needed
- [ ] Verify macOS notarization still works
- [ ] Test release workflow with new repo URL
- [ ] Update Sparkle appcast URLs if applicable
- [ ] Consider publishing a patch version with updated URLs
## Redirect Behavior
GitHub automatically sets up redirects:
- `https://github.com/amantus-ai/vibetunnel` → `https://github.com/vibetunnel/vibetunnel`
@ -139,33 +251,7 @@ GitHub automatically sets up redirects:
- Some tools may not follow redirects properly
- Best practice: Update all references ASAP
## 4. Specific VibeTunnel Updates
### Code Updates
- [ ] Update `GITHUB_URL` in `mac/VibeTunnel/version.xcconfig`
- [ ] Update repository URLs in `package.json` files
- [ ] Update any hardcoded GitHub URLs in documentation
- [ ] Update CLAUDE.md references
### Build & Release
- [ ] Update GitHub Actions secrets if needed
- [ ] Verify macOS notarization still works
- [ ] Test release workflow with new repo URL
- [ ] Update Sparkle appcast URLs if applicable
### npm Package
- [ ] Update package.json repository field
- [ ] Consider publishing a patch version with updated URLs
- [ ] Update npm package description if needed
## 5. Rollback Plan
If issues arise:
1. GitHub Support can reverse transfers within a short window
2. Keep the migration tag for reference
3. Document any issues for future reference
## 6. Timeline
## Timeline
**Day 1**: Preparation
- Set up new organization
@ -182,15 +268,26 @@ If issues arise:
- Monitor for issues
- Complete documentation updates
## Notes
## Important Notes
- GitHub's transfer process is well-tested and reliable
- The automatic redirects provide good backward compatibility
- Most disruption comes from external tools, not GitHub itself
- If using history cleanup (Option 2):
- This process rewrites history - all commit SHAs will change
- Contributors will need to re-clone or rebase their work
- Keep the cleaned backup for a few weeks
- Consider doing this during a low-activity period
## Rollback Plan
If issues arise:
1. GitHub Support can reverse transfers within a short window
2. Keep the migration backup (if using Option 2)
3. Document any issues for future reference
## References
- [GitHub Docs: Transferring a repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository)
- [GitHub Docs: About repository transfers](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository#about-repository-transfers)
- [GitHub Docs: Repository redirects](https://docs.github.com/en/repositories/creating-and-managing-repositories/transferring-a-repository#redirects-and-git-operations)
- [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/) (for Option 2)
- [git-filter-repo](https://github.com/newren/git-filter-repo) (alternative to BFG)
- [GitHub: Removing sensitive data](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)

168
tauri/ENHANCEMENTS_COMPLETE.md
View file

@ -1,168 +0,0 @@
# Tauri + Lit Enhancements Complete ✅
## Summary of Additional Improvements
Building on the TypeScript migration, I've implemented several high-priority enhancements from the IMPROVEMENTS.md document:
### 1. **Component Testing Framework** ✅
- Added `@web/test-runner` with Playwright for cross-browser testing
- Created example test files for `vt-button` and `vt-loading` components
- Configured coverage thresholds (80% statements, 70% branches)
- Added `npm test` and `npm test:watch` scripts
### 2. **Accessibility Enhancements** ✅
- Created comprehensive accessibility utilities (`src/utils/accessibility.ts`):
- Screen reader announcements
- Focus trap directive for modals
- Keyboard navigation helpers
- Roving tabindex for lists
- Contrast ratio calculations
- Built accessible components:
- **vt-modal**: Fully accessible modal with focus trap and ARIA attributes
- **vt-list**: List component with keyboard navigation and screen reader support
- All components now include proper ARIA attributes and keyboard support
### 3. **Error Boundaries & Enhanced Error Handling** ✅
- **vt-error-boundary**: Component that catches and displays errors gracefully
- Global error and unhandled rejection handling
- Error logging to session storage
- Development mode with stack traces
- Retry and reload functionality
- **WithErrorHandler mixin**: Adds error handling to any component
- `safeAsync` and `safeSync` wrappers
- Error event dispatching
- Centralized error management
## New Components Created
### 1. **vt-modal** (`src/components/shared/vt-modal.ts`)
```typescript
<vt-modal
.open=${this.showModal}
title="Confirm Action"
@modal-close=${() => this.showModal = false}
>
<p>Are you sure you want to proceed?</p>
<div slot="footer">
<vt-button @click=${this.handleConfirm}>Confirm</vt-button>
</div>
</vt-modal>
```
### 2. **vt-list** (`src/components/shared/vt-list.ts`)
```typescript
<vt-list
.items=${this.listItems}
.selectedId=${this.selectedItem}
@item-select=${this.handleSelect}
title="Select an option"
></vt-list>
```
### 3. **vt-error-boundary** (`src/components/shared/vt-error-boundary.ts`)
```typescript
<vt-error-boundary
.onRetry=${() => this.loadData()}
development
>
<my-component></my-component>
</vt-error-boundary>
```
## Accessibility Features Added
### 1. **Keyboard Navigation**
- Tab, Shift+Tab for focus navigation
- Arrow keys for list navigation
- Escape to close modals
- Enter/Space to activate buttons
### 2. **Screen Reader Support**
- Proper ARIA labels and descriptions
- Live regions for dynamic content
- Role attributes for semantic meaning
- Announcement utilities for state changes
### 3. **Focus Management**
- Focus trap for modals
- Roving tabindex for lists
- Focus restoration after modal close
- Visible focus indicators
### 4. **Reduced Motion Support**
- Respects `prefers-reduced-motion` setting
- Conditional animations based on user preference
## Testing Setup
### Run Tests
```bash
npm test # Run all tests
npm test:watch # Run tests in watch mode
```
### Write New Tests
```typescript
import { html, fixture, expect } from '@open-wc/testing';
import './my-component';
describe('MyComponent', () => {
it('should render', async () => {
const el = await fixture(html`<my-component></my-component>`);
expect(el).to.exist;
});
});
```
## Error Handling Patterns
### Using Error Boundary
```typescript
// Wrap components that might error
<vt-error-boundary
fallbackMessage="Failed to load data"
.onReport=${(error) => console.error(error)}
>
<risky-component></risky-component>
</vt-error-boundary>
```
### Using Error Handler Mixin
```typescript
import { WithErrorHandler } from '../mixins/with-error-handler';
@customElement('my-component')
export class MyComponent extends WithErrorHandler(LitElement) {
async loadData() {
// Automatically catches errors
const data = await this.safeAsync(() =>
fetch('/api/data').then(r => r.json())
);
}
}
```
## Next Steps
The following enhancements from IMPROVEMENTS.md could still be implemented:
### Medium Priority
- **Build Optimizations**: Tree-shaking, CSS purging, source maps
- **Component Library Extraction**: Create npm package for reusability
- **Hot Module Replacement**: For better development experience
- **VS Code Snippets**: Custom snippets for common patterns
### Advanced Features
- **Offline Support**: Service workers for PWA functionality
- **Real-time Collaboration**: WebSocket-based features
- **Plugin System**: Extensibility framework
## Benefits Achieved
1. **Better Testing**: Components can now be tested with real browser environments
2. **Improved Accessibility**: Full keyboard and screen reader support
3. **Robust Error Handling**: Graceful error recovery and debugging
4. **Enhanced UX**: Modal dialogs, better lists, loading states
5. **Developer Experience**: Clear patterns for common tasks
The Tauri app now has a solid foundation with TypeScript, testing, accessibility, and error handling!

137
tauri/TYPESCRIPT_MIGRATION.md
View file

@ -1,137 +0,0 @@
# TypeScript Migration Complete ✅
## Summary of Changes
### 1. **Complete TypeScript Migration**
- ✅ Converted all JavaScript files to TypeScript
- ✅ Added proper type definitions and interfaces
- ✅ Used Lit decorators (@customElement, @property, @state)
- ✅ Removed all `.js` extensions from imports
### 2. **Enhanced Dependencies**
```json
{
"@lit/context": "^1.1.3", // State management
"@lit/task": "^1.0.1", // Async operations
"typescript": "^5.4.5", // TypeScript compiler
"@types/node": "^20.12.0" // Node types
}
```
### 3. **State Management with @lit/context**
- Created `app-context.ts` with comprehensive app state
- Implemented context providers and consumers
- Type-safe state updates across components
### 4. **Async Operations with @lit/task**
- Replaced manual loading states with `Task` from @lit/task
- Automatic error handling and loading states
- Better UX with built-in pending/complete/error states
### 5. **Virtual Scrolling for Performance**
- Created `virtual-terminal-output.ts` component
- Handles 10,000+ lines efficiently
- Only renders visible lines + overscan buffer
- Smooth auto-scrolling with requestAnimationFrame
## Key Files Created/Updated
### Core Infrastructure
- `tsconfig.json` - TypeScript configuration
- `src/contexts/app-context.ts` - Centralized state management
- `src/components/base/tauri-base.ts` - Type-safe Tauri API wrapper
### Component Library
- `src/components/shared/vt-button.ts` - Button component with variants
- `src/components/shared/vt-card.ts` - Card component with animations
- `src/components/shared/vt-loading.ts` - Loading/error/empty states
- `src/components/shared/vt-stepper.ts` - Multi-step wizard component
### Terminal Components
- `src/components/terminal/virtual-terminal-output.ts` - Virtual scrolling
- `src/components/terminal/README.md` - Documentation
### App Components
- `src/components/app-main.ts` - Main app with @lit/task integration
- `src/components/settings-app.ts` - Settings with proper typing
- `src/components/session-detail-app.ts` - Session management
- All other app components converted to TypeScript
## Benefits Achieved
### 1. **Type Safety**
- Catch errors at compile time
- Better IDE support with autocomplete
- Self-documenting code with interfaces
### 2. **Performance**
- Virtual scrolling reduces DOM nodes
- @lit/task prevents unnecessary re-renders
- Optimized change detection with decorators
### 3. **Developer Experience**
- Clear component APIs with typed props
- Centralized state management
- Reusable, typed components
### 4. **Maintainability**
- Consistent patterns across codebase
- Type contracts between components
- Easier refactoring with TypeScript
## Next Steps
1. **Run TypeScript compiler**:
```bash
npm run typecheck
```
2. **Install dependencies**:
```bash
npm install
```
3. **Start development**:
```bash
npm run dev
```
4. **Build for production**:
```bash
npm run build
```
## Usage Examples
### Using Context API
```typescript
import { consume } from '@lit/context';
import { appContext, type AppState } from '../contexts/app-context';
@consume({ context: appContext })
appState!: AppState;
```
### Using @lit/task
```typescript
private _dataTask = new Task(this, {
task: async () => {
const data = await this.fetchData();
return data;
},
args: () => [this.searchQuery]
});
```
### Using Virtual Terminal
```typescript
<virtual-terminal-output
.lines=${this._terminalLines}
.maxLines=${5000}
.autoScroll=${true}
></virtual-terminal-output>
```
## Migration Complete 🎉
All JavaScript files have been successfully migrated to TypeScript with enhanced features!

278
web/docs/org-migrate.md
View file

@ -1,278 +0,0 @@
# GitHub Organization Migration Plan with Repository Cleanup
This document outlines the migration process for moving VibeTunnel to `vibetunnel/vibetunnel` with a clean history.
## Overview
Since `https://github.com/vibetunnel/vibetunnel` already exists, we'll perform a clean migration that:
1. Removes large files from history
2. Cleans up accidental commits
3. Preserves important history
4. Maintains all issues, PRs, and project management features
## Migration Strategy
### Option 1: Clean History Migration (Recommended)
Use BFG Repo-Cleaner or git-filter-repo to create a cleaned version of the repository, then push to the new location.
### Option 2: Fresh Start with Preserved History
Create a new repository with cleaned history while maintaining a reference to the old repository for historical purposes.
## Migration Script
Save this as `migrate-clean.sh`:
```bash
#!/bin/bash
set -euo pipefail
# Configuration
OLD_REPO="git@github.com:amantus-ai/vibetunnel.git"
NEW_REPO="git@github.com:vibetunnel/vibetunnel.git"
TEMP_DIR="vibetunnel-migration-$(date +%Y%m%d-%H%M%S)"
SIZE_THRESHOLD="10M" # Files larger than this will be removed
echo "🚀 Starting VibeTunnel repository migration with cleanup..."
# Create temporary directory
mkdir -p "$TEMP_DIR"
cd "$TEMP_DIR"
# Clone the repository (all branches and tags)
echo "📥 Cloning repository with all history..."
git clone --mirror "$OLD_REPO" vibetunnel-mirror
cd vibetunnel-mirror
# Create a backup first
echo "💾 Creating backup..."
cp -r . ../vibetunnel-backup
# Analyze repository for large files
echo "🔍 Analyzing repository for large files..."
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
awk '/^blob/ {print substr($0,6)}' | \
sort --numeric-sort --key=2 --reverse | \
awk '$2 >= 10485760 {print $1, $2, $3}' > ../large-files.txt
echo "📊 Large files found:"
cat ../large-files.txt | while read hash size path; do
echo " - $path ($(numfmt --to=iec $size))"
done
# Download BFG Repo-Cleaner if not available
if ! command -v bfg &> /dev/null && [ ! -f ../bfg.jar ]; then
echo "📦 Downloading BFG Repo-Cleaner..."
curl -L -o ../bfg.jar https://repo1.maven.org/maven2/com/madgag/bfg/1.14.0/bfg-1.14.0.jar
fi
# Clean large files using BFG
echo "🧹 Removing large files from history..."
java -jar ../bfg.jar --strip-blobs-bigger-than "$SIZE_THRESHOLD" --no-blob-protection
# Clean specific file patterns (customize as needed)
echo "🗑️ Removing unwanted file patterns..."
java -jar ../bfg.jar --delete-files '*.{log,tmp,cache}' --no-blob-protection
java -jar ../bfg.jar --delete-folders '{node_modules,dist,build}' --no-blob-protection
# Remove sensitive data patterns (customize as needed)
echo "🔒 Removing potentially sensitive patterns..."
# Example: Remove files with specific names
# java -jar ../bfg.jar --delete-files 'secrets.json' --no-blob-protection
# Clean up the repository
echo "♻️ Cleaning up repository..."
git reflog expire --expire=now --all
git gc --prune=now --aggressive
# Show size comparison
echo "📏 Size comparison:"
cd ..
ORIGINAL_SIZE=$(du -sh vibetunnel-backup | cut -f1)
CLEANED_SIZE=$(du -sh vibetunnel-mirror | cut -f1)
echo " Original: $ORIGINAL_SIZE"
echo " Cleaned: $CLEANED_SIZE"
# Prepare for push
cd vibetunnel-mirror
# Update remote URL
echo "🔄 Updating remote URL..."
git remote set-url origin "$NEW_REPO"
# Create a migration notes file
cat > MIGRATION_NOTES.md << EOF
# Repository Migration Notes
This repository was migrated from amantus-ai/vibetunnel on $(date +%Y-%m-%d).
## Changes during migration:
- Removed files larger than $SIZE_THRESHOLD from history
- Cleaned up temporary and build files
- Preserved all code, issues, and pull requests
## Original repository:
- https://github.com/amantus-ai/vibetunnel
## Large files removed:
$(cat ../large-files.txt | while read hash size path; do echo "- $path ($(numfmt --to=iec $size))"; done)
EOF
# Interactive confirmation
echo "⚠️ Ready to push to $NEW_REPO"
echo "This will:"
echo " - Push all cleaned branches and tags"
echo " - Permanently remove large files from history"
echo ""
read -p "Continue? (y/N) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
echo "❌ Aborted"
exit 1
fi
# Push to new repository
echo "📤 Pushing to new repository..."
git push --mirror "$NEW_REPO"
echo "✅ Migration complete!"
echo ""
echo "Next steps:"
echo "1. Check the new repository: https://github.com/vibetunnel/vibetunnel"
echo "2. Update all local clones to use the new URL"
echo "3. Update CI/CD configurations"
echo "4. Archive or delete the old repository"
echo ""
echo "Migration backup saved in: $(pwd)/../vibetunnel-backup"
```
## Alternative: Using git-filter-repo (More Powerful)
```bash
#!/bin/bash
# migrate-with-filter-repo.sh
# Install git-filter-repo first:
# brew install git-filter-repo
set -euo pipefail
OLD_REPO="git@github.com:amantus-ai/vibetunnel.git"
NEW_REPO="git@github.com:vibetunnel/vibetunnel.git"
TEMP_DIR="vibetunnel-clean-$(date +%Y%m%d-%H%M%S)"
# Clone repository
git clone "$OLD_REPO" "$TEMP_DIR"
cd "$TEMP_DIR"
# Analyze repository
git filter-repo --analyze
echo "Check .git/filter-repo/analysis for detailed reports"
# Remove large files (size in bytes, 10MB = 10485760)
git filter-repo --strip-blobs-bigger-than 10M
# Remove specific paths
git filter-repo --path node_modules/ --invert-paths
git filter-repo --path dist/ --invert-paths
git filter-repo --path build/ --invert-paths
git filter-repo --path "*.log" --invert-paths
git filter-repo --path "*.tmp" --invert-paths
# Remove specific commits by message pattern (optional)
# git filter-repo --message-callback '
# if b"WIP" in message or b"temp" in message.lower():
# message = b"[CLEANED] " + message
# return message
# '
# Add new remote and push
git remote add new-origin "$NEW_REPO"
git push new-origin --all
git push new-origin --tags
echo "✅ Migration with cleanup complete!"
```
## Pre-Migration Checklist
- [ ] **Identify files to remove**
```bash
# Find large files in history
git rev-list --objects --all | \
git cat-file --batch-check='%(objecttype) %(objectname) %(objectsize) %(rest)' | \
awk '/^blob/ && $3 > 10485760 {print $3, $4}' | \
sort -rn | \
numfmt --field=1 --to=iec
```
- [ ] **List accidental commits**
- Large binary files
- Generated files (dist/, build/)
- Dependencies (node_modules/)
- Log files
- Temporary files
- Any sensitive data
- [ ] **Backup current repository**
```bash
git clone --mirror git@github.com:amantus-ai/vibetunnel.git vibetunnel-backup
```
## What Gets Preserved
✅ **Preserved:**
- All source code
- Commit messages and authors
- Branch structure
- Tags and releases
- Important history
❌ **Removed:**
- Large binary files
- Generated/built files
- Accidentally committed dependencies
- Log and temporary files
- Specified sensitive data
## Post-Migration Steps
1. **Update all references**
- Package.json repository URLs
- Documentation links
- CI/CD configurations
- Local git remotes
2. **Verify the migration**
- Check file sizes
- Verify important history
- Test clone and build
- Ensure CI/CD works
3. **Communicate changes**
- Notify all contributors
- Update README with new URL
- Add note about the migration
## Important Notes
- This process rewrites history - all commit SHAs will change
- Contributors will need to re-clone or rebase their work
- The old repository should be archived, not deleted immediately
- Consider keeping the cleaned backup for a few weeks
## Size Reduction Examples
Common size reductions from cleaning:
- Removing accidentally committed node_modules: 50-200MB
- Removing build artifacts: 10-50MB
- Removing large media files: Variable
- Removing package-lock.json history: 5-20MB
## References
- [BFG Repo-Cleaner](https://rtyley.github.io/bfg-repo-cleaner/)
- [git-filter-repo](https://github.com/newren/git-filter-repo)
- [GitHub: Removing sensitive data](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/removing-sensitive-data-from-a-repository)