Metadata-Version: 2.4
Name: gh-browse-or-reload
Version: 0.1.1
Summary: A wrapper around gh browse that reloads an existing browser tab if possible.
Author-email: Ishan <ishandutta2007@gmail.com>
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# 🌐 gh-browse-or-reload

<p align="center">
  <a href="https://github.com/ishandutta2007/Awesome-Awesome-Awesome"><img src="https://img.shields.io/badge/Awesome-%E2%9C%94-blueviolet?style=flat-square&logo=github" alt="Awesome"/></a>
  <a href="https://discord.gg/jc4xtF58Ve"><img src="https://img.shields.io/badge/Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white" alt="Discord" /></a>
  <a href="https://pypi.org/project/gh-browse-or-reload/"><img src="https://img.shields.io/pypi/v/gh-browse-or-reload.svg" alt="PyPI version" /></a>
  <a href="https://github.com/ishandutta2007/gh-browse-or-reload/blob/main/LICENSE"><img src="https://img.shields.io/github/license/ishandutta2007/gh-browse-or-reload.svg" alt="License" /></a>
  <a href="https://github.com/ishandutta2007"><img alt="GitHub followers" src="https://img.shields.io/github/followers/ishandutta2007?label=Follow" /></a>
</p>

<p align="center">
  <img src="assets/banner.svg" alt="gh-browse-or-reload animated banner">
</p>

**gh-browse-or-reload** is a smart, SEO-optimized GitHub CLI (`gh`) extension and browser tab management tool. Instead of repeatedly opening brand-new browser tabs and cluttering your workspace, this lightweight Python script intelligently searches your currently open tabs. If the target GitHub repository, issue, or pull request page is already open, the tool seamlessly reloads and focuses that exact tab. If not, it falls back to the default `gh browse` behavior to open a new tab. Perfect for developers looking to optimize their command-line to browser workflow!

---

## 📖 For Users

### 🛠️ Prerequisites
- 🐍 Python 3.7+
- 🐙 [GitHub CLI (`gh`)](https://cli.github.com/) installed and authenticated.

### 1️⃣ Install the CLI Package

Install the CLI tool globally using `pip`:
```bash
pip install gh-browse-or-reload
```

### 2️⃣ Load the Browser Bridge Extension

Because standard shell scripts cannot natively snoop on your browser tabs due to security restrictions, a companion browser extension is required to act as a "bridge".

1. 🌐 Open Chrome/Edge and navigate to `chrome://extensions/` (or `edge://extensions/`).
2. ⚙️ Toggle the **Developer mode** switch in the top-right corner.
3. 📂 Click **Load unpacked** in the top-left corner.
4. 📁 Select the `extension/` directory (containing `manifest.json` and `background.js`) from this repository.
5. 📋 Copy the **Extension ID** generated by the browser (a long string of random lowercase letters).

### 3️⃣ Configure the Extension ID

The first time you run `gh-browse-or-reload`, the tool will detect that it needs an extension ID and interactively prompt you for it:
```text
--- First Run Setup ---
To enable seamless tab reloading on Windows/Linux, you need the companion browser extension installed.
Please enter your Chrome/Edge Extension ID (or press Enter to skip and fallback to default 'gh browse'):
> 
```
Once entered, it will be securely saved to `~/.config/gh-browse-or-reload/config.json` and you will never be asked again! 🛑

*(Advanced users: You can still override this on the fly by exporting `GH_BROWSER_EXTENSION_ID` in your shell).*

### 4️⃣ (Optional) Create a Shell Alias

For an optimal and lightning-fast workflow, alias `gh-browse` to use this script automatically:

```bash
alias gh-browse="gh-browse-or-reload"
```

### 🎯 Usage Examples
The tool accepts all flags native to the official [GitHub CLI Browse Command](https://cli.github.com/manual/gh_browse).

```bash
# 🔄 Open or refresh current repository
gh-browse-or-reload

# 🐛 Target specific sub-panels like issues or pull requests
gh-browse-or-reload --issues
gh-browse-or-reload --settings

# 🌍 Target a completely different repository path
gh-browse-or-reload cli/cli
```

---

## 💻 For Developers

If you want to contribute to the project or run it locally from source.

### 🏗️ Local Development Setup

1. **Clone the repository:**
   ```bash
   git clone https://github.com/ishandutta2007/gh-browse-or-reload.git
   cd gh-browse-or-reload
   ```
2. **Install the package in editable mode:**
   ```bash
   pip install -e .
   ```
   This will link the CLI command `gh-browse-or-reload` to your live source files in the `src/` directory. You can now modify `src/gh_browse_or_reload/cli.py` and see the changes immediately when you run the command.

### 🏛️ Architecture
- **CLI (`src/gh_browse_or_reload/cli.py`)**: Intercepts `gh browse`, determines the target URL using `gh browse --no-browser`, and delegates the task to the browser using a clever local HTTP server bridge.
- **MacOS Fallback**: On macOS, the script falls back to an automated AppleScript bridge that loops through open Google Chrome windows/tabs to reload them natively.
- **Extension Bridge (`extension/`)**: Used on Windows/Linux environments to securely bridge the communication gap between the OS and the browser without background daemons.

---

## 🚀 For Package Publishers (Automated CI/CD)

This repository is configured with a GitHub Actions workflow that automatically builds and publishes the package to PyPI whenever a new version tag is pushed.

### 1️⃣ Initial Repository Setup (One-Time)
PyPI uses **Trusted Publishers** (OpenID Connect) to securely authenticate GitHub Actions — no API tokens needed!

1. 🔑 Log into [PyPI](https://pypi.org/) and go to your account's **Publishing** settings.
2. ➕ Under **Add a new pending publisher** (or on the project page under **Manage** → **Publishing**), fill in:
   - **PyPI Project Name:** `gh-browse-or-reload`
   - **Owner:** `ishandutta2007`
   - **Repository name:** `gh-browse-or-reload`
   - **Workflow name:** `publish.yml`
   - **Environment name:** *(leave blank)*
3. ✅ Click **Add**. That's all — no secrets or tokens to manage!

### 2️⃣ How to Publish a New Release
Whenever you are ready to publish a new version to PyPI, simply follow these steps:

1. **Update the Version:** Open `pyproject.toml` and bump the `version` field (e.g., from `"0.1.0"` to `"0.1.1"`). Commit and push this change to your main branch:
   ```bash
   git add pyproject.toml
   git commit -m "Bump version to 0.1.1"
   git push origin main
   ```

2. **Create and Push a Tag:** Create a git tag matching your new version (must start with `v`) and push it to GitHub:
   ```bash
   git tag v0.1.1
   git push origin v0.1.1
   ```

That's it! 🎉 Pushing the `v*` tag will automatically trigger the GitHub Actions workflow. The system will build the `.tar.gz` and `.whl` distributions and securely upload them directly to PyPI via OIDC. You can watch the progress in the **Actions** tab of your GitHub repository.

---

## ⭐ Star History
[![Star History Chart](https://star-history.dera.page/svg?repos=ishandutta2007/gh-browse-or-reload&type=date&legend=top-left)](https://star-history.dera.page/#ishandutta2007/gh-browse-or-reload&type=date&legend=top-left)
