feat: add self-hosted forges support

A self-hosted forge is described as a "family" adapter, holding the
forge logic, then built with the `instanceOf` function. Public instances
are new instances of a family: Codeberg for Forgejo, GitLab for GitLab
(CE/EE).
About configuration for self-hosted instances:
- the configuration is described into the options page
- host permissions are optional and requested via the options page when
  an instance is added.

Forgejo and GitLab CE/EE are the two self-hosted forges covered as
adapters already exists.

Author: Linkid

DOCUMENTATION.md

@@ -102,7 +102,8 @@ as an `Authorization` header to that forge's API.
 
 The options page is forge-agnostic: it renders one token field per forge that
 declares authentication support (see `authForges()` in `forges.js`), so a new
-authenticated forge needs no options-page change.
+authenticated forge needs no options-page change. Self-hosted instances (see
+[Forges](#forges)) get their own token field too, keyed per instance.
 
 For GitHub, create a [personal access token][gh-token] (classic or
 fine-grained) — no scope is required for public repositories; grant repository
@@ -121,15 +122,18 @@ in your account settings with repository read scope. For GitLab, create a
 
 Forge endpoints are configured in `forges.js`, which defines one **adapter**
 per forge that normalizes its API and URL quirks behind a common interface,
-plus a `forgeForHostname()` registry lookup.
+plus a `forgeForHostname()` registry lookup. Single-host forges (GitHub,
+Bitbucket) are plain adapter objects; multi-host forges (GitLab, Forgejo/Gitea)
+are *families* whose instances — public and self-hosted alike — are built with
+`instanceOf()` (see [Families and self-hosted forges](#families-and-self-hosted-forges)).
 
 Here is the interface for each forge:
 
 | Member       | Purpose                                                            |
 | ------------ | ------------------------------------------------------------------ |
 | `label`      | human-readable forge name                                          |
-| `hostnames`  | array of hostnames (static forges only)                            |
-| `base_url`   | API URL (static forges only)                                       |
+| `hostnames`  | array of hostnames matched against the page (one per family instance) |
+| `base_url`   | API root URL the endpoint builders are hung off of                |
 | `parseUrl`   | `(URL) → { projectKey, repoSlug, filepath, origin }` or `null`     |
 | `listPRsUrl` | API endpoint listing the repo's open PRs                           |
 | `pullRequests` | `(listResponse) → array of PR objects` (unwraps paginated envelopes) |
@@ -157,6 +161,43 @@ Supported forges:
 - **Codeberg** (Forgejo, Gitea-compatible API): https://forgejo.org/docs/latest/user/api-usage/
 - **GitLab**: https://docs.gitlab.com/ee/api/merge_requests.html.
 
+### Families and self-hosted forges
+
+**GitLab (CE/EE)** and **Forgejo/Gitea** can each run on many hosts. Rather than
+hardcode one adapter per host, `forges.js` defines a *family* holding the shared
+API/URL logic (`gitlabFamily`, `forgejoFamily`) and builds concrete adapters
+from it with `instanceOf(family, { hostname, label, tokenStorageKey })`, which
+sets the instance-specific fields (`hostnames`, `base_url` = `https://<hostname>`
++ the family `apiPath`, `tokenStorageKey`) and inherits everything else through
+the prototype chain.
+
+The public instances are built this exact way — `codeberg` is
+`instanceOf(forgejoFamily, …)` and `gitlab` is `instanceOf(gitlabFamily, …)` —
+so a public forge is **not special**: it is just a built-in instance. A
+self-hosted forge is the same `instanceOf`, only built at runtime:
+
+- the user adds an instance (its hostname + which software it runs); the entry
+  is stored under the `selfHostedInstances` key in `browser.storage.local`;
+- `buildSelfHostedForge({ type, hostname })` picks the family from
+  `selfHostedFamilies` (`{ gitlab: gitlabFamily, forgejo: forgejoFamily }`),
+  builds the adapter with the same `instanceOf`, and tags it `selfHosted`;
+- `forgeForHostname(hostname, instances)` matches a page against the built-in
+  instances first, then the configured self-hosted instances (by exact
+  hostname).
+
+Because Manifest V3 cannot declare arbitrary hosts up front, the manifest
+declares `optional_host_permissions` and the options page **requests the host
+permission** for an instance origin when it is added (a user gesture), and
+gives it back with `permissions.remove()` when the instance is removed. The
+background script skips an instance page until its permission is granted.
+
+Bitbucket Data Center is **not** covered: it speaks a different REST API than
+Bitbucket Cloud and would need its own adapter.
+
+To support a new self-hosted software, define its family and add it to
+`selfHostedFamilies`; the public instance (if any) is then just another
+`instanceOf` of that family.
+
 ## Internationalization
 
 Translations live in `_locales/<lang>/messages.json`. The default locale is

README.md

@@ -25,3 +25,5 @@ API rate limit and list pull requests from private repositories.
 - Bitbucket
 - Codeberg
 - GitLab
+- self-hosted GitLab (CE/EE) and Forgejo/Gitea instances (add them in the
+  extension's options)

_locales/en/messages.json

@@ -46,5 +46,45 @@
   "optionsCleared": {
     "message": "Token cleared",
     "description": "Status message shown after clearing the token"
+  },
+  "optionsSelfHostedTitle": {
+    "message": "Self-hosted forges",
+    "description": "Title of the self-hosted forges section on the options page"
+  },
+  "optionsSelfHostedHint": {
+    "message": "Add your own GitLab (CE/EE) or Forgejo/Gitea instance. Adding one asks for permission to access that site.",
+    "description": "Hint explaining the self-hosted forges section"
+  },
+  "optionsAddInstance": {
+    "message": "Add",
+    "description": "Label of the button that adds a self-hosted instance"
+  },
+  "optionsHostnamePlaceholder": {
+    "message": "git.example.com",
+    "description": "Placeholder for the self-hosted instance hostname input"
+  },
+  "optionsRemove": {
+    "message": "Remove",
+    "description": "Label of the button that removes a self-hosted instance"
+  },
+  "optionsInvalidHostname": {
+    "message": "Enter a valid hostname",
+    "description": "Status message when the entered instance hostname is invalid"
+  },
+  "optionsInstanceExists": {
+    "message": "This instance is already configured",
+    "description": "Status message when adding an instance that already exists"
+  },
+  "optionsInstanceAdded": {
+    "message": "Instance added",
+    "description": "Status message shown after adding a self-hosted instance"
+  },
+  "optionsInstanceRemoved": {
+    "message": "Instance removed",
+    "description": "Status message shown after removing a self-hosted instance"
+  },
+  "optionsPermissionDenied": {
+    "message": "Permission to access this instance was denied",
+    "description": "Status message when the host permission request is denied"
   }
 }

_locales/fr/messages.json

@@ -46,5 +46,45 @@
   "optionsCleared": {
     "message": "Jeton effacé",
     "description": "Message affiché après l'effacement du jeton"
+  },
+  "optionsSelfHostedTitle": {
+    "message": "Forges auto-hébergées",
+    "description": "Titre de la section des forges auto-hébergées sur la page d'options"
+  },
+  "optionsSelfHostedHint": {
+    "message": "Ajoutez votre propre instance GitLab (CE/EE) ou Forgejo/Gitea. L'ajout demande l'autorisation d'accéder à ce site.",
+    "description": "Aide expliquant la section des forges auto-hébergées"
+  },
+  "optionsAddInstance": {
+    "message": "Ajouter",
+    "description": "Libellé du bouton d'ajout d'une instance auto-hébergée"
+  },
+  "optionsHostnamePlaceholder": {
+    "message": "git.exemple.com",
+    "description": "Texte indicatif du champ de nom d'hôte de l'instance auto-hébergée"
+  },
+  "optionsRemove": {
+    "message": "Supprimer",
+    "description": "Libellé du bouton de suppression d'une instance auto-hébergée"
+  },
+  "optionsInvalidHostname": {
+    "message": "Saisissez un nom d'hôte valide",
+    "description": "Message affiché quand le nom d'hôte saisi est invalide"
+  },
+  "optionsInstanceExists": {
+    "message": "Cette instance est déjà configurée",
+    "description": "Message affiché lors de l'ajout d'une instance déjà présente"
+  },
+  "optionsInstanceAdded": {
+    "message": "Instance ajoutée",
+    "description": "Message affiché après l'ajout d'une instance auto-hébergée"
+  },
+  "optionsInstanceRemoved": {
+    "message": "Instance supprimée",
+    "description": "Message affiché après la suppression d'une instance auto-hébergée"
+  },
+  "optionsPermissionDenied": {
+    "message": "L'autorisation d'accéder à cette instance a été refusée",
+    "description": "Message affiché quand la demande d'autorisation d'hôte est refusée"
   }
 }

_locales/template.json

@@ -46,5 +46,45 @@
   "optionsCleared": {
     "message": "",
     "description": ""
+  },
+  "optionsSelfHostedTitle": {
+    "message": "",
+    "description": ""
+  },
+  "optionsSelfHostedHint": {
+    "message": "",
+    "description": ""
+  },
+  "optionsAddInstance": {
+    "message": "",
+    "description": ""
+  },
+  "optionsHostnamePlaceholder": {
+    "message": "",
+    "description": ""
+  },
+  "optionsRemove": {
+    "message": "",
+    "description": ""
+  },
+  "optionsInvalidHostname": {
+    "message": "",
+    "description": ""
+  },
+  "optionsInstanceExists": {
+    "message": "",
+    "description": ""
+  },
+  "optionsInstanceAdded": {
+    "message": "",
+    "description": ""
+  },
+  "optionsInstanceRemoved": {
+    "message": "",
+    "description": ""
+  },
+  "optionsPermissionDenied": {
+    "message": "",
+    "description": ""
   }
 }

background.js

@@ -163,15 +163,32 @@ function render(prs, tabId) {
     browser.storage.local.set({ tabId, prs })
 }
 
+// load the user's configured self-hosted instances from storage
+// returns an array of { type, hostname } (empty when none configured)
+async function loadInstances() {
+    const stored = await browser.storage.local.get("selfHostedInstances")
+    return stored.selfHostedInstances || []
+}
+
 async function main(tab) {
     // split the url
     const url = new URL(tab.url)
 
-    // get the forge adapter by hostname
-    const forge = forgeForHostname(url.hostname)
+    // get the forge adapter by hostname, considering configured self-hosted
+    // instances alongside the built-in forges
+    const instances = await loadInstances()
+    const forge = forgeForHostname(url.hostname, instances)
     if (forge == null) {
         return
     }
+
+    // self-hosted instances need an optional host permission before the
+    // extension may call their API; skip quietly until the user grants it
+    if (forge.selfHosted &&
+        !(await browser.permissions.contains({ origins: [`*://${url.hostname}/*`] }))) {
+        return
+    }
+
     browser.action.enable(tab.id)
 
     // get project info from the URL (forge-specific parsing)