# git-forge-plugin

GitHub and Gitea/Forgejo integration for the DeepSeek Harness (DSH): **clone repositories into new workspaces** from the Web UI and give agents **`forge_*` tools** for repos, issues, pull requests and authenticated push. Tokens never leave the Host — they stay with the `gh` and `tea`/`tea-cli` CLIs.

## Features

### Web UI
- **Add workspace → Clone repository**: browse repos of every authorized account (or paste any git URL) and clone straight into a new workspace (default clone root: your home directory).
- **Add workspace → Open local folder**: folder browser (up/home/show hidden).
- **Settings → Plugins → Git Forge → Accounts**: list authorized accounts, check tokens, log out, and add accounts:
  - GitHub via `gh`: browser device-code flow or a personal access token (classic, scopes `repo`, `read:org`, `gist`).
  - Gitea / Forgejo via `tea-cli`: host + token, or user + password (tea creates a token).

### Agent tools
| Tool | Purpose |
| --- | --- |
| `forge_accounts` | List authorized GitHub (gh) and Gitea/Forgejo (tea-cli) accounts. |
| `forge_repos` | list / search / get / create / edit / fork / delete / branches / releases. |
| `forge_issues` | list / get / create / comment / edit / close / reopen. |
| `forge_pulls` | list / get / diff / create / comment / merge / close / reopen. |
| `forge_clone` | Clone with account credentials (private repos; SSH URLs switched to HTTPS+token when no SSH key). |
| `forge_push` | Push with the account token (sets upstream; `--force-with-lease` only on request). |
| `forge_api` | Raw authenticated REST call (GitHub `https://api.github.com`, Gitea/Forgejo `/api/v1`). |

Clone and push use a bundled git **credential helper** (`credential-helper.mjs`) passed via `git -c credential.helper=…`; it answers with the token of the gh/tea account whose host matches, and prints nothing otherwise (git falls through to your normal helpers). Your global git config is not modified.

## Requirements

- [`gh`](https://cli.github.com/) for GitHub accounts (optional).
- [`tea`](https://gitea.com/gitea/tea) (binary named `tea-cli` or `tea`) for Gitea/Forgejo accounts (optional).
- `git` and Node.js (already required by DSH).

At least one of `gh` / `tea` must be installed and logged in for the account features to do anything.

## Files

| File | Role |
| --- | --- |
| `index.js` | Host plugin: HTTP routes under `/git-forge/*` (accounts, repos, auth, ls, clone) and the `forge_*` tools. Injects `webServer`, `connection`, `tools`. |
| `forge.mjs` | Account discovery (gh + tea), REST access, git URL parsing, clone and push. |
| `auth.mjs` | Drives `gh auth login` / `tea login add` / logout for the settings panel. |
| `credential-helper.mjs` | git credential helper used by clone/push. |
| `client.js` | Web client: clone dialog, local folder picker, accounts settings panel. |
| `locale/*.json` | Plugin title/description (en, zh). |
| `cordis.patch.yml` | Bundle patch inserting the `git-forge` row. |

## Installation

Requirements: a working DeepSeek Harness (`dsh`) install with the **web** profile (or any profile that includes the Web UI).

### Option A — install from git (recommended)

```bash
dsh plugin --profile web add git+https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git
```

You can also paste `git+https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git` into **Settings → Plugins → Install** in the Web UI, or ask the agent to install it with its `plugin_manager` tool (`install_bundle`).

The plugin manager adds `@local/git-forge` to `dependencies` and to `dsh.profile.bundles` in `~/.dsh/profiles/web/package.json`.

### Option B — local checkout (for development)

```bash
git clone https://git.rizzy.dev/DSH-Plugins/git-forge-plugin.git ~/dsh-plugins/git-forge-plugin
dsh plugin --profile web add link:$HOME/dsh-plugins/git-forge-plugin
```

With a `link:` install, edits in the checkout are picked up directly (client changes reload on page refresh, Host changes after a DSH restart or HMR reload).

### Enable / verify

1. Make sure `@local/git-forge` is listed in `dsh.profile.bundles` of `~/.dsh/profiles/web/package.json` (the installer does this; add it by hand if you edited `package.json` manually).
2. Restart DSH (`dsh web`) or reload the page.
3. Check **Settings → Plugins**: the `@local/git-forge` bundle should be enabled.

### Uninstall

```bash
dsh plugin --profile web remove @local/git-forge
```

### Updating

Re-run the `add` command from Option A (or `git pull` in your Option B checkout).

## Setup after install

1. Install and log in the CLIs on the Host machine (or use the settings panel to do it):
   ```bash
   gh auth login                                   # GitHub
   tea login add --url https://gitea.example.com --token <TOKEN>   # Gitea/Forgejo
   ```
2. Open **Settings → Plugins → Git Forge** and press **Check tokens** — each account should show *Token valid*.
3. In a chat, ask the agent e.g. *"list my repos"*; it will use `forge_repos`.