ja7ad / ja7ad/hydra

Build and test safari extension and publish

Open
#1 0 comments 0 reactions 0 assignees View on GitHub
good first issue help wanted
Dominant language
Rust
Stars
528
Forks
38
Avg merge
5h 26m
Merged PRs (30d)
131

Description

Help us build, test, and validate the Hydra Safari extension across different macOS versions and hardware configurations.

## What we need
- ✅ Build verification on various macOS versions (currently targeting Safari 16.4+)
- ✅ End-to-end testing of extension features
- ✅ Bug reports and compatibility findings
- ✅ User experience feedback

## Prerequisites
Before you start, you'll need:

- **macOS** (10.15+, tested on 12.x+)
- **Full Xcode** installed (not just Command Line Tools)
```bash
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
```
- **Rust** (with Apple Silicon or Intel target support)
- Git and the hydra repository cloned locally

## Build Instructions

1. Clone and navigate to the repo:
```bash
git clone https://github.com/your-org/hydra.git
cd hydra
```

2. Run the Safari extension build script:
```bash
scripts/build-safari-extension.sh
```

The script will:
- Sync resources from the shared Chrome extension code
- Generate the Safari wrapper app
- Install the native handler (SafariWebExtensionHandler.swift)
- Configure sandbox exceptions and ATS settings
- Build the final extension

3. Install in Safari:
- Open the built app from `target/release/` once
- Go to **Safari → Settings → Extensions → Hydra**
- Enable the Hydra extension
- For unsigned dev builds: enable **Develop → Allow Unsigned Extensions** (Safari clears this on restart)

## Testing Checklist

### Basic Features (All Platforms)
- [ ] Right-click menu → "Download with Hydra" works on links
- [ ] Selection pill appears when hovering over links (visual indicator)
- [ ] "Download all links on page" menu option functions
- [ ] Extension popup opens and shows status
- [ ] Status badge appears on extension icon
- [ ] Toggle capture on/off from popup

### Integration with Hydra App
- [ ] Clicking "Download with Hydra" launches the app (if not running)
- [ ] App receives download requests via WebSocket
- [ ] Extension communicates with local app on port 6799
- [ ] Status updates reflect in both app and extension

### Known Limitations (Expected Behavior)
- [ ] ⚠️ Automatic download capture does NOT work (Safari limitation: no downloads API)
- *This is expected and cannot be fixed — use right-click menu or selection pill instead*

## Reporting Issues

When filing a bug report, please include:

```markdown
**macOS Version:** (e.g., 12.5, 13.2)
**Safari Version:** (e.g., 16.4)
**Hardware:** (Intel / Apple Silicon)
**Hydra App Version:** [hash or version]

**Feature Tested:**
**Expected Behavior:**
**Actual Behavior:**

**Steps to Reproduce:**
1.
2.
3.

**Screenshots/Recordings:** (if applicable)
```

## Technical Details

The Safari extension uses a unique architecture:
- **Shared code**: Extension source in `extensions/chrome/` is browser-neutral (binds `browser` namespace, handles both messaging dialects)
- **Platform manifest**: Safari-specific config in `extensions/safari/manifest.json`
- **Resources sync**: `scripts/sync-extension-resources.sh safari` regenerates `extensions/safari/Resources/`
- **Native handler**: `SafariWebExtensionHandler.swift` forwards requests to the Hydra app via line-protocol socket
- **Transport**: Extension talks to Hydra over WebSocket on loopback port 6799

**Important**: Edit `extensions/chrome/*`, not `extensions/safari/Resources/*` — the latter is auto-generated.

## Platform Support Matrix

| Feature | Status | Notes |
|---------|--------|-------|
| Right-click download | ✅ Works | Core feature, fully functional |
| Selection pill | ✅ Works | Visual UI element working |
| Download all links | ✅ Works | Batch download support |
| Status badge | ✅ Works | Icon indicator functional |
| Media sniffing | ⚠️ Partial | Works where Safari exposes `webRequest` |
| **Auto-capture downloads** | ❌ N/A | Safari API limitation, not a bug |

Contributor guide

Open the contributing guide

Research direction

Start with scripts/build-safari-extension.sh and scripts/sync-extension-resources.sh, then inspect extensions/chrome/, extensions/safari/manifest.json, and SafariWebExtensionHandler.swift. Run the build on the available macOS and hardware setup, install the result in Safari, and work through the listed feature and Hydra integration checklist. Done means build results, compatibility findings, and reproducible bug reports are recorded.

Written by the indexing model from the issue text.

Assessment

Tech stack
git, macos, rust, swift
Domain
build-system, desktop, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
48/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.