chore: import upstream snapshot with attribution
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,257 @@
|
||||
---
|
||||
summary: "Fork quick start: differences, commands, and planned features."
|
||||
read_when:
|
||||
- Onboarding to the fork workflow
|
||||
- Reviewing fork-specific changes
|
||||
- Running fork maintenance commands
|
||||
---
|
||||
|
||||
# CodexBar Fork - Quick Start Guide
|
||||
|
||||
**Fork Maintainer:** Brandon Charleson ([topoffunnel.com](https://topoffunnel.com))
|
||||
**Original Author:** Peter Steinberger ([steipete](https://twitter.com/steipete))
|
||||
**Fork Repository:** https://github.com/topoffunnel/CodexBar
|
||||
|
||||
---
|
||||
|
||||
## 🎯 What Makes This Fork Different?
|
||||
|
||||
### Key Enhancements
|
||||
1. **Augment Provider Support** - Full integration with Augment Code API
|
||||
2. **Enhanced Security** - Improved keychain handling, no permission prompts
|
||||
3. **Better Cookie Management** - Automatic session keepalive, Chrome Beta support
|
||||
4. **Bug Fixes** - Cursor bonus credits, cookie domain filtering
|
||||
|
||||
### Planned Features
|
||||
- Multi-account management per provider
|
||||
- Enhanced diagnostics and logging
|
||||
- Upstream sync automation
|
||||
- Usage history tracking
|
||||
|
||||
---
|
||||
|
||||
## 🚀 Quick Commands
|
||||
|
||||
### Development
|
||||
```bash
|
||||
# Build and run (kills old instances, builds, tests, packages, relaunches)
|
||||
./Scripts/compile_and_run.sh
|
||||
|
||||
# Quick build
|
||||
swift build
|
||||
|
||||
# Run tests
|
||||
make test
|
||||
|
||||
# Format code
|
||||
swiftformat Sources Tests
|
||||
swiftlint --strict
|
||||
|
||||
# Package app
|
||||
./Scripts/package_app.sh
|
||||
|
||||
# Restart app after rebuild
|
||||
pkill -x CodexBar || pkill -f CodexBar.app || true
|
||||
cd /Users/steipete/Projects/codexbar && open -n /Users/steipete/Projects/codexbar/CodexBar.app
|
||||
```
|
||||
|
||||
### Release
|
||||
```bash
|
||||
# Edit .mac-release.env first: MAC_RELEASE_REPO, feed URL, download URL,
|
||||
# bundle id, and Sparkle public/signing key must point at your fork.
|
||||
./Scripts/release.sh
|
||||
|
||||
# See full release process
|
||||
cat docs/RELEASING.md
|
||||
```
|
||||
|
||||
### Git Workflow
|
||||
```bash
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# Create feature branch
|
||||
git checkout -b feature/my-feature
|
||||
|
||||
# Commit changes
|
||||
git add -A
|
||||
git commit -m "feat: description"
|
||||
|
||||
# Push to fork
|
||||
git push origin feature/my-feature
|
||||
|
||||
# Sync with upstream (TBD - see docs/FORK_ROADMAP.md Phase 4)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 📁 Key Files & Directories
|
||||
|
||||
### Source Code
|
||||
- `Sources/CodexBar/` - Swift 6 menu bar app
|
||||
- `Sources/CodexBarCore/` - Core logic, providers, utilities
|
||||
- `Sources/CodexBarCore/Providers/Augment/` - Augment provider implementation
|
||||
- `Tests/CodexBarTests/` - XCTest coverage
|
||||
|
||||
### Scripts
|
||||
- `Scripts/compile_and_run.sh` - Main development script
|
||||
- `Scripts/package_app.sh` - Package app bundle
|
||||
- `Scripts/sign-and-notarize.sh` - Release signing
|
||||
- `Scripts/make_appcast.sh` - Generate appcast XML
|
||||
|
||||
### Documentation
|
||||
- `docs/augment.md` - Augment provider guide
|
||||
- `docs/FORK_ROADMAP.md` - Development roadmap
|
||||
- `docs/RELEASING.md` - Release process
|
||||
- `docs/DEVELOPMENT.md` - Build instructions
|
||||
- `README.md` - Main documentation
|
||||
|
||||
---
|
||||
|
||||
## 🔧 Common Tasks
|
||||
|
||||
### Adding a New Feature
|
||||
1. Create feature branch: `git checkout -b feature/my-feature`
|
||||
2. Make changes in `Sources/`
|
||||
3. Add tests in `Tests/`
|
||||
4. Run `./Scripts/compile_and_run.sh` to verify
|
||||
5. Run `swiftformat Sources Tests && swiftlint --strict`
|
||||
6. Commit with descriptive message
|
||||
7. Push and create PR
|
||||
|
||||
### Debugging Augment Issues
|
||||
1. Enable debug logging: `export CODEXBAR_LOG_LEVEL=debug`
|
||||
2. Check Console.app for "com.steipete.codexbar"
|
||||
3. Use Settings → Debug → Augment → Show Debug Info
|
||||
4. Check `docs/augment.md` troubleshooting section
|
||||
|
||||
### Testing Changes
|
||||
```bash
|
||||
# Run all tests
|
||||
make test
|
||||
|
||||
# Run specific test
|
||||
swift test --filter AugmentTests
|
||||
|
||||
# Build and test together
|
||||
./Scripts/compile_and_run.sh --test
|
||||
```
|
||||
|
||||
### Updating Documentation
|
||||
1. Edit relevant `.md` file in `docs/`
|
||||
2. Update `README.md` if needed
|
||||
3. Commit with `docs:` prefix
|
||||
4. No need to rebuild app
|
||||
|
||||
---
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### App Won't Launch
|
||||
```bash
|
||||
# Kill all instances
|
||||
pkill -x CodexBar || pkill -f CodexBar.app || true
|
||||
|
||||
# Rebuild and relaunch
|
||||
./Scripts/compile_and_run.sh
|
||||
```
|
||||
|
||||
### Build Errors
|
||||
```bash
|
||||
# Clean build
|
||||
swift package clean
|
||||
swift build
|
||||
|
||||
# Check for format issues
|
||||
swiftformat Sources Tests --lint
|
||||
swiftlint --strict
|
||||
```
|
||||
|
||||
### Cookie Issues (Augment)
|
||||
1. Check browser is logged into app.augmentcode.com
|
||||
2. Verify cookie source in Settings → Providers → Augment
|
||||
3. Try manual cookie import (see `docs/augment.md`)
|
||||
4. Check debug logs for cookie import details
|
||||
|
||||
### Keychain Permission Prompts
|
||||
- This fork includes fixes to eliminate prompts
|
||||
- If you still see prompts, check `Sources/CodexBarCore/Keychain/`
|
||||
- Ensure you're running the latest build
|
||||
|
||||
---
|
||||
|
||||
## 📚 Learning Resources
|
||||
|
||||
### Understanding the Codebase
|
||||
1. Start with `Sources/CodexBar/CodexbarApp.swift` - App entry point
|
||||
2. Review `Sources/CodexBarCore/UsageStore.swift` - Main state management
|
||||
3. Check `Sources/CodexBarCore/Providers/` - Provider implementations
|
||||
4. Read `docs/provider.md` - Provider authoring guide
|
||||
|
||||
### Swift 6 & SwiftUI
|
||||
- Uses `@Observable` macro (not `ObservableObject`)
|
||||
- Prefer `@State` ownership over `@StateObject`
|
||||
- Use `@Bindable` in views for two-way binding
|
||||
- Strict concurrency checking enabled
|
||||
|
||||
### Coding Style
|
||||
- 4-space indentation
|
||||
- 120-character line limit
|
||||
- Explicit `self` is intentional (don't remove)
|
||||
- Follow existing `MARK` organization
|
||||
- Use descriptive variable names
|
||||
|
||||
---
|
||||
|
||||
## 🤝 Contributing
|
||||
|
||||
### To This Fork
|
||||
1. Fork the fork repository
|
||||
2. Create feature branch
|
||||
3. Make changes with tests
|
||||
4. Submit PR to `topoffunnel/CodexBar`
|
||||
|
||||
### To Upstream
|
||||
1. Check if feature benefits all users
|
||||
2. Create PR to `steipete/CodexBar`
|
||||
3. Reference this fork if relevant
|
||||
4. Be patient with review process
|
||||
|
||||
See `docs/FORK_ROADMAP.md` for contribution strategy.
|
||||
|
||||
---
|
||||
|
||||
## 📞 Support
|
||||
|
||||
### Fork-Specific Issues
|
||||
- GitHub Issues: https://github.com/topoffunnel/CodexBar/issues
|
||||
- Email: [your-email]@topoffunnel.com
|
||||
|
||||
### Upstream Issues
|
||||
- GitHub Issues: https://github.com/steipete/CodexBar/issues
|
||||
- Twitter: [@steipete](https://twitter.com/steipete)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Next Steps
|
||||
|
||||
1. **Read the Roadmap:** `docs/FORK_ROADMAP.md`
|
||||
2. **Set Up Development:** `./Scripts/compile_and_run.sh`
|
||||
3. **Review Augment Docs:** `docs/augment.md`
|
||||
4. **Check Current Issues:** GitHub Issues tab
|
||||
5. **Join Development:** Pick a task from Phase 2-5
|
||||
|
||||
---
|
||||
|
||||
## 🎉 Quick Wins
|
||||
|
||||
Want to contribute but not sure where to start? Try these:
|
||||
|
||||
- [ ] Add more test coverage for Augment provider
|
||||
- [ ] Improve error messages in cookie import
|
||||
- [ ] Add screenshots to `docs/augment.md`
|
||||
- [ ] Test on different macOS versions
|
||||
- [ ] Report bugs you find
|
||||
- [ ] Suggest UI improvements
|
||||
|
||||
Happy coding! 🚀
|
||||
Reference in New Issue
Block a user