some python scripts that are sometimes helpful to me

### run a script
only general requirement is [`uv`](https://docs.astral.sh/uv/getting-started/installation/)

```bash
chmod +x <script-name>
./<script-name> <...>
```

## scripts

- [`analyze-github-followers`](#analyze-github-followers)
- [`check-files-for-bad-links`](#check-files-for-bad-links)
- [`dm-me-when-a-flight-passes-over`](#dm-me-when-a-flight-passes-over)
- [`find-longest-bsky-thread`](#find-longest-bsky-thread)
- [`find-stale-bsky-follows`](#find-stale-bsky-follows)
- [`kill-processes`](#kill-processes)
- [`predict-github-stars`](#predict-github-stars)
- [`update-lights`](#update-lights)
- [`update-readme`](#update-readme)

---

### `analyze-github-followers`

analyze your github followers and following.

usage:
    ./analyze-github-followers
    ./analyze-github-followers --summary-only  # skip detailed analysis

details:
- uses github rest api to fetch followers/following
- shows rich tables with follower stats
- identifies mutual follows, notable followers, etc.
- requires GITHUB_TOKEN in .env file

---

### `check-files-for-bad-links`

Check files for bad links.

Usage:

```bash
./check-files-for-bad-links *.md
```

Details:
- uses [`httpx`](https://www.python-httpx.org/) to check links
- uses [`anyio`](https://anyio.readthedocs.io/en/stable/) to run the checks concurrently
- pass include globs to scan (e.g. `*.md`)
- pass exclude globs to skip (e.g. `*.md`)
- pass ignore-url prefixes to ignore (e.g. `http://localhost` or `https://localhost`)
- pass concurrency to run the checks concurrently (default is 50)

---

### `dm-me-when-a-flight-passes-over`

Monitor flights passing overhead and send BlueSky DMs.

Usage:
    # Single user mode (backward compatible)
    ./dm-me-when-a-flight-passes-over

    # Multi-subscriber mode with JSON file
    ./dm-me-when-a-flight-passes-over --subscribers subscribers.json

    # Multi-subscriber mode with stdin
    echo '[{"handle": "user1.bsky.social", "latitude": 41.8781, "longitude": -87.6298, "radius_miles": 5}]' | ./dm-me-when-a-flight-passes-over --subscribers -

This script monitors flights within a configurable radius and sends DMs on BlueSky
when flights pass overhead. Supports multiple subscribers with different locations.

## Future Architecture Ideas

### Web App Deployment Options

1. **FastAPI + Fly.io/Railway/Render**
   - REST API with endpoints:
     - POST /subscribe - Register user with BlueSky handle
     - DELETE /unsubscribe - Remove subscription
     - POST /update-location - Update user's location
     - GET /status - Check subscription status
   - Background worker using Celery/RQ/APScheduler
   - PostgreSQL/SQLite for subscriber persistence
   - Redis for caching flight data & deduplication

2. **Vercel/Netlify Edge Functions**
   - Serverless approach with scheduled cron jobs
   - Use Vercel KV or Upstash Redis for state
   - Challenge: Long-running monitoring needs workarounds
   - Solution: Trigger checks via cron every minute

3. **Self-Hosted with ngrok/Cloudflare Tunnel**
   - Quick prototype option
   - Run this script as daemon
   - Expose simple Flask/FastAPI wrapper
   - Security concerns: rate limiting, auth required

### Mobile/Browser Integration

1. **Progressive Web App (PWA)**
   - Service worker for background location updates
   - Geolocation API for current position
   - Push notifications instead of/alongside DMs
   - IndexedDB for offline capability

2. **iOS Shortcuts Integration**
   - Create shortcut that gets location
   - Calls webhook with location + BlueSky handle
   - Could run automatically based on focus modes

3. **Browser Extension**
   - Background script polls location
   - Lighter weight than full app
   - Cross-platform solution

### Architecture Components

1. **Location Services Layer**
   - Browser Geolocation API
   - IP-based geolocation fallback
   - Manual location picker UI
   - Privacy: Only send location when checking flights

2. **Notification Options**
   - BlueSky DMs (current)
   - Web Push Notifications
   - Webhooks to other services
   - Email/SMS via Twilio/SendGrid

3. **Subscription Management**
   - OAuth with BlueSky for auth
   - User preferences: radius, notification types
   - Quiet hours/Do Not Disturb
   - Rate limiting per user

4. **Data Optimization**
   - Cache FlightRadar API responses
   - Batch location updates
   - Aggregate nearby users for efficiency
   - WebSocket for real-time updates

### Implementation Approach

Phase 1: Web API Wrapper
- FastAPI with /subscribe endpoint
- SQLite for subscribers
- Run monitoring in background thread
- Deploy to Fly.io free tier

Phase 2: Web UI
- Simple React/Vue form
- Geolocation permission request
- Show nearby flights on map
- Subscription management

Phase 3: Mobile Experience
- PWA with service workers
- Background location updates
- Local notifications
- Offline support

### Security Considerations
- Rate limit FlightRadar API calls
- Authenticate BlueSky handles
- Validate location bounds
- Prevent subscription spam
- GDPR compliance for location data

---

### `find-longest-bsky-thread`

Find the longest reply thread from a Bluesky post.

Usage:

```bash
./find-longest-bsky-thread https://bsky.app/profile/nerditry.bsky.social/post/3lnofix5nlc23
```

Details:
- uses [`atproto`](https://github.com/MarshalX/atproto) to fetch the thread
- uses [`jinja2`](https://github.com/pallets/jinja) to render the thread

---

### `find-stale-bsky-follows`

Find stale/inactive accounts among those you follow on Bluesky.

Usage:

```bash
./find-stale-bsky-follows
# or with custom inactivity threshold (days)
./find-stale-bsky-follows --days 180
```

Details:
- uses [`atproto`](https://github.com/MarshalX/atproto) to fetch following list
- uses [`rich`](https://github.com/Textualize/rich) for pretty output
- identifies accounts with no recent posts

---

### `kill-processes`

AI-powered TUI for killing processes.

Usage:

```bash
./kill-processes
```

Details:
- uses [`textual`](https://textual.textualize.io/) for the TUI
- uses [`marvin`](https://github.com/prefecthq/marvin) (built on [`pydantic-ai`](https://github.com/pydantic/pydantic-ai)) to annotate processes

---

### `predict-github-stars`

Predict when a GitHub repository will reach a target number of stars.

Usage:
    ./predict-github-stars owner/repo 10000

Details:
- Uses GitHub REST API to fetch star history (with timestamps).
- Fits polynomial regression (degree 1–3) to full history.
- Falls back to recent‑trend linear extrapolation if the polynomial
  cannot reach the target within ten years.
- Shows recent growth rate and a caution for long‑range estimates.
- Requires `GITHUB_TOKEN` in the environment for higher rate limits (optional).

---

### `update-lights`

Make some change to my phillips hue network of lights via agent + MCP server.

Usage:

```bash
./update-lights -m "turn on sahara in the living room and nightlight in the kitchen"
```

Details:
- uses a [`marvin`](https://github.com/prefecthq/marvin) (built on [`pydantic-ai`](https://github.com/pydantic/pydantic-ai)) agent
- the agent spins up a [`fastmcp`](https://github.com/jlowin/fastmcp) MCP server that talks to my [`phue`](https://github.com/studioimaginaire/phue) bridge
- set `HUE_BRIDGE_IP` and `HUE_BRIDGE_USERNAME` in `.env` or otherwise in environment
- uses `OPENAI_API_KEY` by default, but you can set `AI_MODEL` in `.env` or otherwise in environment to use a different model

---

### `update-readme`

Update the README.md file with a list of all the scripts in the current directory.

Usage:

```bash
./update-readme
```