forgeo-cli 0.11.0__tar.gz → 0.12.0__tar.gz

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.12.0] - 2026-09-03
+
+### Added
+
+- Browser-based OAuth login for GitHub, GitLab, and Jira, with cached tokens and setup guidance.
+
+### Fixed
+
+- Stabilized the CI lint configuration.
+
 ## [0.11.0] - 2026-08-31
 
 ### Added
@@ -429,7 +439,8 @@ Initial release of the scheduled, agent-driven software forgeo.
   overlapping-run skipping.
 - Dogfooding docs removed; local configs kept out of the repository.
 
-[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.11.0...HEAD
+[Unreleased]: https://github.com/lucaGazzola/forgeo/compare/v0.12.0...HEAD
+[0.12.0]: https://github.com/lucaGazzola/forgeo/compare/v0.11.0...v0.12.0
 [0.11.0]: https://github.com/lucaGazzola/forgeo/compare/v0.10.0...v0.11.0
 [0.10.0]: https://github.com/lucaGazzola/forgeo/compare/v0.9.0...v0.10.0
 [0.9.0]: https://github.com/lucaGazzola/forgeo/compare/v0.8.0...v0.9.0

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: forgeo-cli
-Version: 0.11.0
+Version: 0.12.0
 Summary: A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input.
 Project-URL: Homepage, https://forgeo.org
 Project-URL: Documentation, https://forgeo.org
@@ -99,7 +99,7 @@ pipx install forgeo-cli                          # Python 3.11+
 forgeo init
 ```
 
-Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github`/`gitlab`/`jira` it auto-detects `owner/repo` and offers `PAT` (`GITHUB_TOKEN` → `~/.config/forgeo/`) or browser OAuth (`forgeo auth login` → `~/.config/forgeo/tokens/`).
 
 ### 3. Fill the backlog
 

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/README.md

@@ -45,7 +45,7 @@ pipx install forgeo-cli                          # Python 3.11+
 forgeo init
 ```
 
-Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github` it auto-detects `owner/repo` and can persist `GITHUB_TOKEN` to `~/.config/forgeo/`.
+Wizard in your project root. Creates `forgeo.yaml` and `.forgeo/` (backlog, logs, blockers). Prompts for backlog provider (`file` / `github` / `gitlab` / `jira` / `http`) and agent command. For `github`/`gitlab`/`jira` it auto-detects `owner/repo` and offers `PAT` (`GITHUB_TOKEN` → `~/.config/forgeo/`) or browser OAuth (`forgeo auth login` → `~/.config/forgeo/tokens/`).
 
 ### 3. Fill the backlog
 

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/docs/backlog.md

@@ -166,6 +166,7 @@ Runtime files (`backlog.lock`, `runs.jsonl`, etc.) go in `state_dir` (defaults t
 ## A Jira backlog
 
 ```yaml
+# PAT:
 backlog_provider: jira
 backlog: https://jira.example.com
 jira:
@@ -173,6 +174,12 @@ jira:
   project_key: APP
   auth: {scheme: basic, username_env: JIRA_USER, token_env: JIRA_TOKEN}
   workflow: {open_statuses: ["10000", "10001"], open_status: "10000", running_status: "3", completed_status: "10002"}
+# OAuth 3LO (Cloud):
+# jira:
+#   jql: 'project = APP AND labels = forgeo'
+#   auth:
+#     oauth: {client_id: xxxx, client_secret_env: JIRA_CLIENT_SECRET, scope: "offline_access read:jira-user read:jira-work"}
+# # then: forgeo auth login --provider jira --client-id xxxx
 ```
 
 - Jira keys → task IDs; `summary`/`description`/`created`/`updated` → task fields.
@@ -185,9 +192,13 @@ jira:
 ## A GitHub backlog
 
 ```yaml
+# PAT:
 backlog_provider: github
 backlog: https://api.github.com   # or https://github.example.com/api/v3
-github: {repo: owner/repo, token_env: GITHUB_TOKEN}
+github: {repo: owner/repo, auth: {token_env: GITHUB_TOKEN}}
+# OAuth (browser/device):
+# github: {repo: owner/repo, auth: {oauth: {client_id: Iv1.xxxx, flow: device, scope: repo}}}
+# # then: forgeo auth login --provider github --client-id Iv1.xxxx
 ```
 
 - Issue numbers → task IDs; `title`/`body`/`created_at`/`updated_at` → task fields.
@@ -204,9 +215,13 @@ GITHUB_TOKEN=... ./scripts/test-github-backlog-e2e.sh
 ## A GitLab backlog
 
 ```yaml
+# PAT:
 backlog_provider: gitlab
 backlog: https://gitlab.example.com   # instance root, /api/v4 appended
-gitlab: {repo: group/project, token_env: GITLAB_TOKEN}
+gitlab: {repo: group/project, auth: {token_env: GITLAB_TOKEN}}
+# OAuth (browser PKCE):
+# gitlab: {repo: group/project, auth: {oauth: {client_id: abc, flow: browser, scope: api}}}
+# # then: forgeo auth login --provider gitlab --client-id abc
 ```
 
 - `iid` → task ID; `opened`/`closed` → `OPEN`/`COMPLETED`; same hidden-block and label mechanics as GitHub.

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/docs/cli-reference.md

@@ -125,6 +125,29 @@ Unregister (never touches config/repo). Errors if unknown.
 
 Table of all instances: name, daemon state, last outcome (from `runs.jsonl`). Exits `0` with hint if none.
 
+## `forgeo auth`
+
+Browser/OAuth login for `github`/`gitlab`/`jira` (alternative to `*_TOKEN` PAT). Tokens stored `0600` in `~/.config/forgeo/tokens/` and read by `forgeo validate`/`start`/`once`.
+
+### `forgeo auth login --provider <github|gitlab|jira>`
+
+| Flag | Description |
+| --- | --- |
+| `--provider` | `github` (default) / `gitlab` / `jira`. |
+| `--config <file>` | `forgeo.yaml` to read `auth.oauth.client_id` (defaults to `./forgeo.yaml`). |
+| `--client-id <id>` | OAuth client ID (overrides config; required if not in `forgeo.yaml`). |
+| `--flow <device|browser>` | `device` (GitHub CLI) / `browser` (PKCE loopback `127.0.0.1:0/callback`). Defaults: `device` for GitHub, `browser` for GitLab/Jira. |
+| `--scope <scope>` | Scope (default `repo` / `api` / `offline_access read:jira-user read:jira-work`). |
+| `--token-file <path>` | Where to store token (default per-provider per-host `~/.config/forgeo/tokens/<provider>.json`). |
+| `--api-base <url>` | Provider API base (default from `forgeo.yaml` backlog or `https://api.github.com`/`https://gitlab.com`). |
+| `--no-open-browser` | Print URL instead of `webbrowser.open()`. |
+
+Device flow: prints `https://github.com/login/device` + `user_code`, polls `…/login/oauth/access_token`. Browser flow: opens `…/oauth/authorize` + PKCE `code_challenge`, listens on loopback, exchanges `code` for `access_token` (`refresh_token` for Jira). `forgeo init` with `browser` writes `auth.oauth` and offers `Run browser login now?`.
+
+### `forgeo auth status --provider <p>` / `forgeo auth logout --provider <p>`
+
+`status` masks token (`ghp_…1234`), shows `scope`/`expires_in`/`cloud_id` (Jira). `logout` removes the file. Both honour `--token-file`/`--api-base`/`--config`.
+
 ## `forgeo web`
 
 Central dashboard aggregating every registered instance (reads files directly, works whether daemons are running).

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/docs/configuration.md

@@ -70,6 +70,7 @@ Add `backlog_auth` for OAuth2-protected HTTP endpoints (see below). A failed HTT
 ### Jira
 
 ```yaml
+# PAT / basic (Server/DC):
 backlog_provider: jira
 backlog: https://jira.example.com
 state_dir: .forgeo
@@ -86,6 +87,16 @@ jira:
     open_status: "10000"
     running_status: "3"
     completed_status: "10002"
+# OAuth 3LO (Cloud, browser):
+# jira:
+#   jql: 'project = APP AND labels = forgeo'
+#   auth:
+#     oauth:
+#       client_id: xxxx
+#       client_secret_env: JIRA_CLIENT_SECRET
+#       scope: offline_access read:jira-user read:jira-work
+#       token_file: ~/.config/forgeo/tokens/jira.json  # optional
+# # then: forgeo auth login --provider jira --client-id xxxx
 ```
 
 | Key | Default | Description |
@@ -109,11 +120,23 @@ Status values can be names or IDs (IDs preferred). Jira keys become task IDs. En
 ### GitHub
 
 ```yaml
+# PAT:
 backlog_provider: github
 backlog: https://api.github.com   # or https://github.example.com/api/v3
 github:
   repo: owner/repo
-  token_env: GITHUB_TOKEN
+  auth:
+    token_env: GITHUB_TOKEN
+# OAuth / browser (device flow for CLI, browser PKCE):
+# github:
+#   repo: owner/repo
+#   auth:
+#     oauth:
+#       client_id: Iv1.xxxx
+#       flow: device              # device | browser
+#       scope: repo
+#       token_file: ~/.config/forgeo/tokens/github.json
+# # then: forgeo auth login --provider github --client-id Iv1.xxxx
 ```
 
 | Key | Default | Description |
@@ -134,11 +157,23 @@ Issue numbers become task IDs; `open`/`closed` maps to `OPEN`/`COMPLETED`; `forg
 ### GitLab
 
 ```yaml
+# PAT:
 backlog_provider: gitlab
 backlog: https://gitlab.example.com   # instance root, /api/v4 appended
 gitlab:
   repo: group/project
-  token_env: GITLAB_TOKEN
+  auth:
+    token_env: GITLAB_TOKEN
+# OAuth (browser PKCE, device if enabled):
+# gitlab:
+#   repo: group/project
+#   auth:
+#     oauth:
+#       client_id: abc123
+#       flow: browser             # browser | device
+#       scope: api
+#       token_file: ~/.config/forgeo/tokens/gitlab.json
+# # then: forgeo auth login --provider gitlab --client-id abc123
 ```
 
 Same keys as GitHub (`gitlab.*`), including `workflow` and `fields` for the same 7 mappings. Issue `iid` becomes task ID; `opened`/`closed` maps to `OPEN`/`COMPLETED`; hidden `<!-- forgeo: {...} -->` block for engine state.

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/docs/getting-started.md

@@ -32,7 +32,7 @@ The wizard asks for:
 3. **Agent command** — bare command for your agent (default `opencode run --auto`). Forgeo appends the task prompt (`$FORGEO_TASK`); if your command already references `$FORGEO_TASK` it is kept verbatim.
 4. **Refactor prompt** — used when the backlog is empty.
 
-Writes `forgeo.yaml`, creates the folder, and appends it to `.gitignore` (opt-out available). With `github`/`gitlab`/`jira` it also sets `backlog_provider`, `backlog` URL, provider block, and `state_dir`.
+Writes `forgeo.yaml`, creates the folder, and appends it to `.gitignore` (opt-out available). With `github`/`gitlab`/`jira` it also sets `backlog_provider`, `backlog` URL, provider block, and `state_dir`. For `github`/`gitlab`/`jira` you can pick `PAT` or `browser` (OAuth) — browser stores a token in `~/.config/forgeo/tokens/`.
 
 ```bash
 forgeo init --force    # overwrite existing config
@@ -58,10 +58,14 @@ forgeo init --force    # overwrite existing config
 
 You can also add tasks from the dashboard once Forgeo is running — no file editing needed.
 
-**Remote providers** — `forgeo.yaml` already points at the provider. Export credentials and validate:
+**Remote providers** — `forgeo.yaml` already points at the provider. Authenticate with PAT **or** browser:
 
 ```bash
+# PAT:
 export GITHUB_TOKEN=ghp_...   # or GITLAB_TOKEN / JIRA_USER + JIRA_TOKEN
+# Browser OAuth (device flow preferred for CLI):
+forgeo auth login --provider github --client-id Iv1.xxx   # or gitlab/jira
+forgeo auth status   # forgeo auth logout to clear
 forgeo validate
 ```
 

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/install.sh

@@ -14,7 +14,7 @@ set -eu
 
 REPO_OWNER="lucaGazzola"
 REPO_NAME="forgeo"
-DEFAULT_VERSION="0.11.0"
+DEFAULT_VERSION="0.12.0"
 MIN_PYTHON="3.11"
 PYPI_PACKAGE="forgeo-cli"
 PREFIX="${FORGEO_PREFIX:-${HOME:-}/.local}"

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "forgeo-cli"
-version = "0.11.0"
+version = "0.12.0"
 description = "A scheduled software forgeo: executes backlog tasks on main, refactors when idle, and writes BLOCKER.md when it needs human input."
 readme = "README.md"
 requires-python = ">=3.11"
@@ -61,6 +61,9 @@ asyncio_default_fixture_loop_scope = "function"
 line-length = 100
 target-version = "py311"
 
+[tool.ruff.lint]
+select = ["E4", "E7", "E9", "F"]
+
 [tool.mypy]
 python_version = "3.11"
 mypy_path = "src"

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/src/forgeo/__init__.py

@@ -7,4 +7,4 @@ try:
 
     __version__ = _pkg_version("forgeo-cli")
 except PackageNotFoundError:  # standalone binary: no installed package metadata
-    __version__ = "0.11.0"
+    __version__ = "0.12.0"

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/src/forgeo/backlog_github.py

@@ -57,11 +57,43 @@ class GithubClient:
     def __init__(self, base_url: str, config: GithubBacklogConfig) -> None:
         self.base_url = base_url.rstrip("/")
         self.config = config
+        self._oauth_provider: Any | None = None  # lazy GithubOAuthTokenProvider when oauth is used
+
+    def _oauth_token_provider(self) -> Any | None:
+        if self._oauth_provider is not None:
+            return self._oauth_provider
+        auth = self.config.auth
+        if auth.oauth is None:
+            return None
+        from forgeo.oauth_github import GithubOAuthTokenProvider, GithubTokenStore
+
+        token_file = auth.oauth.token_file
+        store = GithubTokenStore(path=token_file, api_base=self.base_url) if token_file is not None else GithubTokenStore(api_base=self.base_url)
+        provider = GithubOAuthTokenProvider(store)
+        self._oauth_provider = provider
+        return provider
 
     def _auth_header(self) -> str:
-        token = require_env_token(self.config.auth.token_env, "GitHub", GithubRequestError)
-        # GitHub accepts Bearer or token; use Bearer for consistency
-        return f"Bearer {token}"
+        auth = self.config.auth
+        if auth.token_env is not None:
+            token = require_env_token(auth.token_env, "GitHub", GithubRequestError)
+            return f"Bearer {token}"
+        if auth.oauth is not None:
+            provider = self._oauth_token_provider()
+            assert provider is not None
+            try:
+                token = provider.token()
+            except Exception as exc:
+                # Wrap file errors as GithubRequestError so callers surface a clear message
+                if isinstance(exc, GithubRequestError):
+                    raise
+                from forgeo.oauth_github import GithubOAuthError
+
+                if isinstance(exc, GithubOAuthError):
+                    raise GithubRequestError(str(exc)) from exc
+                raise GithubRequestError(str(exc)) from exc
+            return f"Bearer {token}"
+        raise GithubRequestError("GitHub auth is not configured (token_env or oauth required)")
 
     def _api_url(self, path: str, query: dict[str, Any] | None = None) -> str:
         url = f"{self.base_url}{path}"
@@ -77,23 +109,42 @@ class GithubClient:
         query: dict[str, Any] | None = None,
         payload: dict[str, Any] | None = None,
     ) -> Any:
-        body = None
-        if payload is not None:
-            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
-        request = urllib.request.Request(
-            self._api_url(path, query),
-            data=body,
-            method=method,
-            headers={
-                "Accept": "application/vnd.github+json",
-                "Authorization": self._auth_header(),
-                "X-GitHub-Api-Version": "2022-11-28",
-                **({"Content-Type": "application/json"} if body is not None else {}),
-            },
-        )
-        return execute_json_request(
-            request, self.config.timeout_seconds, GithubRequestError, method
-        )
+        # Retry once when GitHub rejects an OAuth token (revoked/expired)
+        for attempt in (0, 1):
+            body = None
+            if payload is not None:
+                body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            auth_header = self._auth_header()
+            request = urllib.request.Request(
+                self._api_url(path, query),
+                data=body,
+                method=method,
+                headers={
+                    "Accept": "application/vnd.github+json",
+                    "Authorization": auth_header,
+                    "X-GitHub-Api-Version": "2022-11-28",
+                    **({"Content-Type": "application/json"} if body is not None else {}),
+                },
+            )
+            try:
+                return execute_json_request(
+                    request, self.config.timeout_seconds, GithubRequestError, method
+                )
+            except GithubRequestError as exc:
+                # On 401/403 with OAuth, invalidate cache and retry once so a freshly
+                # written token (e.g. after `forgeo auth login`) is picked up.
+                if (
+                    attempt == 0
+                    and exc.status in (401, 403)
+                    and self.config.auth.oauth is not None
+                    and self._oauth_provider is not None
+                ):
+                    try:
+                        self._oauth_provider.invalidate()  # noqa: BLE001
+                    except Exception:  # noqa: BLE001
+                        pass
+                    continue
+                raise
 
     def _repo_path(self) -> str:
         # GitHub API expects owner/repo as two separate path segments;

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/src/forgeo/backlog_gitlab.py

@@ -57,11 +57,43 @@ class GitlabClient:
     def __init__(self, base_url: str, config: GitlabBacklogConfig) -> None:
         self.base_url = base_url.rstrip("/")
         self.config = config
+        self._oauth_provider: Any | None = None
+
+    def _oauth_token_provider(self) -> Any | None:
+        if self._oauth_provider is not None:
+            return self._oauth_provider
+        auth = self.config.auth
+        if auth.oauth is None:
+            return None
+        from forgeo.oauth_gitlab import GitlabOAuthTokenProvider, GitlabTokenStore
+
+        token_file = auth.oauth.token_file
+        store = GitlabTokenStore(path=token_file, api_base=self.base_url) if token_file is not None else GitlabTokenStore(api_base=self.base_url)
+        provider = GitlabOAuthTokenProvider(store)
+        self._oauth_provider = provider
+        return provider
 
     def _auth_headers(self) -> dict[str, str]:
-        token = require_env_token(self.config.auth.token_env, "GitLab", GitlabRequestError)
-        # GitLab prefers PRIVATE-TOKEN, but also accepts Bearer
-        return {"PRIVATE-TOKEN": token, "Authorization": f"Bearer {token}"}
+        auth = self.config.auth
+        if auth.token_env is not None:
+            token = require_env_token(auth.token_env, "GitLab", GitlabRequestError)
+            # GitLab prefers PRIVATE-TOKEN, but also accepts Bearer
+            return {"PRIVATE-TOKEN": token, "Authorization": f"Bearer {token}"}
+        if auth.oauth is not None:
+            provider = self._oauth_token_provider()
+            assert provider is not None
+            try:
+                token = provider.token()
+            except Exception as exc:
+                if isinstance(exc, GitlabRequestError):
+                    raise
+                from forgeo.oauth_gitlab import GitlabOAuthError
+
+                if isinstance(exc, GitlabOAuthError):
+                    raise GitlabRequestError(str(exc)) from exc
+                raise GitlabRequestError(str(exc)) from exc
+            return {"Authorization": f"Bearer {token}"}
+        raise GitlabRequestError("GitLab auth is not configured (token_env or oauth required)")
 
     def _project_path(self) -> str:
         # GitLab API expects URL-encoded project path or numeric id
@@ -81,20 +113,35 @@ class GitlabClient:
         query: dict[str, Any] | None = None,
         payload: dict[str, Any] | None = None,
     ) -> Any:
-        body = None
-        if payload is not None:
-            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
-        headers = {
-            "Accept": "application/json",
-            **self._auth_headers(),
-            **({"Content-Type": "application/json"} if body is not None else {}),
-        }
-        request = urllib.request.Request(
-            self._api_url(path, query), data=body, method=method, headers=headers
-        )
-        return execute_json_request(
-            request, self.config.timeout_seconds, GitlabRequestError, method
-        )
+        for attempt in (0, 1):
+            body = None
+            if payload is not None:
+                body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            headers = {
+                "Accept": "application/json",
+                **self._auth_headers(),
+                **({"Content-Type": "application/json"} if body is not None else {}),
+            }
+            request = urllib.request.Request(
+                self._api_url(path, query), data=body, method=method, headers=headers
+            )
+            try:
+                return execute_json_request(
+                    request, self.config.timeout_seconds, GitlabRequestError, method
+                )
+            except GitlabRequestError as exc:
+                if (
+                    attempt == 0
+                    and exc.status in (401, 403)
+                    and self.config.auth.oauth is not None
+                    and self._oauth_provider is not None
+                ):
+                    try:
+                        self._oauth_provider.invalidate()  # noqa: BLE001
+                    except Exception:  # noqa: BLE001
+                        pass
+                    continue
+                raise
 
     def search_issues(self, *, page: int = 1, per_page: int = 20) -> list[dict[str, Any]]:
         path = f"/projects/{self._project_path()}/issues"

{forgeo_cli-0.11.0 → forgeo_cli-0.12.0}/src/forgeo/backlog_jira.py

@@ -83,22 +83,85 @@ class JiraClient:
         self.base_url = base_url.rstrip("/")
         self.config = config
         self.api_version = config.api_version or DEFAULT_API_VERSION
+        self._oauth_provider: Any | None = None
+
+    def _oauth_token_provider(self) -> Any | None:
+        if self._oauth_provider is not None:
+            return self._oauth_provider
+        auth = self.config.auth
+        if auth.oauth is None:
+            return None
+        from forgeo.oauth_jira import JiraOAuthTokenProvider, JiraTokenStore
+
+        token_file = auth.oauth.token_file
+        store = JiraTokenStore(path=token_file, api_base=self.base_url) if token_file is not None else JiraTokenStore(api_base=self.base_url)
+        provider = JiraOAuthTokenProvider(
+            store, client_id=auth.oauth.client_id, client_secret_env=auth.oauth.client_secret_env
+        )
+        self._oauth_provider = provider
+        return provider
 
     def _api_url(self, path: str, query: dict[str, Any] | None = None) -> str:
-        url = f"{self.base_url}/rest/api/{self.api_version}{path}"
+        # When OAuth is used with cloud_id, Jira Cloud API lives at api.atlassian.com/ex/jira/{cloudId}
+        base = self.base_url
+        auth = self.config.auth
+        if auth.oauth is not None:
+            # Prefer cloud_id from config oauth, else from token file
+            cloud_id: str | None = auth.oauth.cloud_id
+            if cloud_id is None and self._oauth_provider is not None:
+                try:
+                    data = self._oauth_provider.store.load()
+                    if isinstance(data, dict) and isinstance(data.get("cloud_id"), str):
+                        cloud_id = data["cloud_id"]
+                except Exception:
+                    pass
+            elif cloud_id is None:
+                # Try to load directly via store without provider cache
+                try:
+                    from forgeo.oauth_jira import JiraTokenStore
+
+                    tmp_store = JiraTokenStore(
+                        path=auth.oauth.token_file, api_base=self.base_url
+                    ) if auth.oauth.token_file is not None else JiraTokenStore(api_base=self.base_url)
+                    data = tmp_store.load()
+                    if isinstance(data, dict) and isinstance(data.get("cloud_id"), str):
+                        cloud_id = data["cloud_id"]
+                except Exception:
+                    pass
+            if cloud_id:
+                base = f"https://api.atlassian.com/ex/jira/{cloud_id}"
+        url = f"{base}/rest/api/{self.api_version}{path}"
         if query:
             url += "?" + urlencode(query, doseq=True)
         return url
 
     def _auth_header(self) -> str:
-        token = require_env_token(self.config.auth.token_env, "Jira", JiraRequestError)
-        if self.config.auth.scheme == "bearer":
+        auth = self.config.auth
+        if auth.oauth is not None:
+            provider = self._oauth_token_provider()
+            assert provider is not None
+            try:
+                token = provider.token()
+            except Exception as exc:
+                if isinstance(exc, JiraRequestError):
+                    raise
+                from forgeo.oauth_jira import JiraOAuthError
+
+                if isinstance(exc, JiraOAuthError):
+                    raise JiraRequestError(str(exc)) from exc
+                raise JiraRequestError(str(exc)) from exc
+            return f"Bearer {token}"
+        # PAT branch
+        if auth.token_env is None or not auth.token_env.strip():
+            raise JiraRequestError("Jira token environment variable is not set")
+        token = require_env_token(auth.token_env, "Jira", JiraRequestError)
+        if auth.scheme == "bearer":
             return f"Bearer {token}"
-        username = self.config.auth.username
-        if self.config.auth.username_env is not None:
-            username = os.environ.get(self.config.auth.username_env)
+        username = auth.username
+        if auth.username_env is not None:
+            username = os.environ.get(auth.username_env)
         if not username:
-            source = self.config.auth.username_env or "username"
+            source = auth.username_env or "username"
             raise JiraRequestError(f"Jira username {source!r} is not set")
         encoded = base64.b64encode(f"{username}:{token}".encode()).decode("ascii")
         return f"Basic {encoded}"
@@ -112,25 +175,41 @@ class JiraClient:
         payload: dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         """Perform one authenticated request and decode its JSON response."""
-        body = None
-        if payload is not None:
-            body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
-        request = urllib.request.Request(
-            self._api_url(path, query),
-            data=body,
-            method=method,
-            headers={
-                "Accept": "application/json",
-                "Authorization": self._auth_header(),
-                **({"Content-Type": "application/json"} if body is not None else {}),
-            },
-        )
-        data = execute_json_request(
-            request, self.config.timeout_seconds, JiraRequestError, method
-        )
-        if not isinstance(data, dict):
-            raise JiraRequestError(f"{method} {request.full_url} returned a non-object JSON body")
-        return data
+        for attempt in (0, 1):
+            body = None
+            if payload is not None:
+                body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+            request = urllib.request.Request(
+                self._api_url(path, query),
+                data=body,
+                method=method,
+                headers={
+                    "Accept": "application/json",
+                    "Authorization": self._auth_header(),
+                    **({"Content-Type": "application/json"} if body is not None else {}),
+                },
+            )
+            try:
+                data = execute_json_request(
+                    request, self.config.timeout_seconds, JiraRequestError, method
+                )
+            except JiraRequestError as exc:
+                if (
+                    attempt == 0
+                    and exc.status in (401, 403)
+                    and self.config.auth.oauth is not None
+                    and self._oauth_provider is not None
+                ):
+                    try:
+                        self._oauth_provider.invalidate()  # noqa: BLE001
+                    except Exception:  # noqa: BLE001
+                        pass
+                    continue
+                raise
+            if not isinstance(data, dict):
+                raise JiraRequestError(f"{method} {request.full_url} returned a non-object JSON body")
+            return data
+        raise JiraRequestError(f"{method} {self._api_url(path, query)} failed after retry")
 
     def search_issues(
         self,