@goodandready/dsh-github-ops 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -2,6 +2,43 @@
 
 Notable changes to `@goodandready/dsh-github-ops`.
 
+## 0.2.0
+
+The development wave: reliability, reports, writing without a checkout, and the user surfaces.
+
+### Reliability and reach
+- a short TTL read cache (`cacheTtlMs`) so a composed report does not spend the rate limit
+  twice; writes always go to the network and clear the cache;
+- the turn's cancellation reaches the request in flight, and a cancelled call says so instead
+  of pretending to be a timeout; reads retry on a network failure, a timeout or a 5xx, and a
+  429 is honoured through `Retry-After` or the rate-limit reset;
+- every list is cut locally as well, because GitHub sometimes ignores the page size;
+- failures say what to do next (401, 403, 404, 409, 422, timeouts, a broken `/etc/hosts`);
+- `gh_help` lists every tool, grouped by area, built from the registrations;
+- a short paragraph in the system prompt explains how to use them (`guidance`, `guidanceText`).
+
+### Reports
+- `gh_repo_report`, `gh_weekly_digest`, `gh_notifications`, `gh_repo_health`, `gh_compare`,
+  `gh_trending`, `gh_contributors`, `gh_user_repos`, `gh_commits`.
+
+### Writing without a checkout, and signing in
+- `gh_repo_tree`, `gh_push_files` (blobs, tree, commit, ref — `force` never implied),
+  `gh_upload_project`, `gh_delete_file`, `gh_delete_branch`;
+- `gh_auth_login` / `gh_auth_finish` / `gh_auth_status` / `gh_auth_logout`: GitHub device flow,
+  stored in the plugin's own file with mode 0600 and never returned in a result. The access
+  chain is now credentials → environment → this plugin's sign-in → `gh` CLI.
+
+### User surfaces
+- the access status in the plugin card (source, account, scopes, rate limit, cache) from a
+  local-only host route;
+- a **Source Control** tab in the session view ring: repository header, change groups, diff
+  viewer, merge/rebase state, branches, tags and stashes — read-only for now;
+- a **GitHub panel** in the sidebar (better-sidebar and the built-in right sidebar): repository
+  switcher, Code tree with file preview, Issues, Pull requests, Actions and an inbox;
+- a pull request bar above the composer that hands an instruction to the composer instead of
+  writing by itself, and opt-in remembering of the repository behind a github.com link;
+- `docs/design/DESIGN.md` describes all of it, with the states and the locked decisions.
+
 ## 0.1.2
 
 - Removed the write-approval contour the plugin never should have had: no `tools/pre-execute`

package/README.md

@@ -67,6 +67,14 @@ Requires a GitHub token in the DSH credential service. Store the token under a n
 | `maxRetries` | `2` | Retries for a failed read (never for a write). |
 | `reviewRulesJson` | *(empty)* | Review-rule overrides as JSON: `sensitivePaths`, `sensitiveSeverity`, `attentionPaths`, `migrationPaths`, `testsRequired`, `sourcePatterns`, `testPatterns`, `largeDiffLines`. |
 | `reviewJobTimeoutMs` | `120000` | How long a background review job may run. |
+| `cacheTtlMs` | `60000` | How long a read is served from the in-memory cache. Writes always go to the network and clear it. Set `0` to switch the cache off. |
+| `interceptLinks` | `false` | Let a `github.com` link clicked in the conversation record which repository the Source Control tab and the panel should follow. The link always opens in the browser either way. |
+| `guidance` | `true` | Add a short paragraph about this plugin to the system prompt. |
+| `guidanceText` | *(empty)* | Replace that paragraph with your own text. |
+| `oauthClientId` | the public `gh` CLI application | OAuth application used by `gh_auth_login`. |
+| `oauthScope` | `repo workflow gist read:org` | Scope requested by `gh_auth_login`. |
+| `oauthClientSecretRef` | *(empty)* | Optional credential name holding the OAuth client secret. |
+| `accessFile` | `$DSH_HOME/github-ops-auth.json` | Where `gh_auth_login` stores the sign-in (written `0600`). |
 
 ## Tools
 
@@ -142,6 +150,42 @@ published because it is part of the package.
 | `gh_ruleset_list/view/apply/delete` | Repository rulesets: read, create, update, delete. |
 | `gh_branch_protection_get/set/delete` | Classic branch protection: required reviews, status checks, admin enforcement, force-push and deletion flags. |
 
+### Reports
+
+| Tool | What it does |
+|---|---|
+| `gh_repo_report` | Everything about a repository in one call: overview, latest release, open issues, recent commits, top contributors. A failing part degrades that part instead of failing the report. |
+| `gh_weekly_digest` | What happened inside a window: releases, new issues, merged or closed pull requests, commits. Pull requests are reported separately, not as “new issues”. |
+| `gh_notifications` | The attention queue for the account — mentions, review requests, assignments — grouped by reason. |
+| `gh_repo_health` | A transparent maintenance score: five weighted dimensions, each with its evidence, plus the risks found and concrete next actions. A heuristic over public signals, not a security audit. |
+| `gh_compare` | Two repositories side by side with numeric deltas for stars, forks and open issues. |
+| `gh_contributors` | Top contributors of a repository by commit count. |
+| `gh_user_repos` | A user's or organization's repositories sorted by stars. |
+| `gh_trending` | Recently created repositories by stars, optionally filtered by language (uses the search quota). |
+| `gh_commits` | Recent commits, optionally since a timestamp and on a specific branch. |
+| `gh_help` | Every tool of this plugin, grouped by area, built from the registrations so it cannot go stale. |
+
+### Files and branches
+
+These publish content without a local checkout: the client builds a commit the way git does.
+
+| Tool | What it does |
+|---|---|
+| `gh_repo_tree` | The file tree at a ref, recursively by default, with the truncation flag — far cheaper than walking directories. |
+| `gh_push_files` | Commit files to a branch: blobs, a tree on top of the branch tree, a commit, then the ref moves. Creates the branch when it does not exist. `force` is never implied and needs `confirm: true`. |
+| `gh_upload_project` | Create a repository, publish files into it and optionally open a pull request — one call. An existing repository is used as is instead of failing. |
+| `gh_delete_file` | Delete one file (the blob sha is resolved first). Requires `confirm: true`. |
+| `gh_delete_branch` | Delete a branch. Requires `confirm: true`. |
+
+### Account and sign-in
+
+| Tool | What it does |
+|---|---|
+| `gh_auth_login` | Start a GitHub device-flow sign-in: returns a short code and a URL for the human. |
+| `gh_auth_finish` | Collect a started sign-in. The granted value is written to this plugin's own file with mode `0600` and is never returned in a result. |
+| `gh_auth_status` | Where the access comes from (credential, environment, this plugin's sign-in, `gh` CLI), the account, the reported scopes and the remaining rate limit. |
+| `gh_auth_logout` | Forget the sign-in stored by this plugin; other sources are untouched. Requires `confirm: true`. |
+
 ## Background reviews and commands
 
 `gh_review_job` starts a review and returns a job id immediately; `gh_review_job_status`
@@ -160,6 +204,42 @@ Slash commands are the fast path for a human:
 A command never writes to GitHub itself: it hands the model an instruction, so the write
 still passes through the approval gate.
 
+## Reliability
+
+- Reads are cached for `cacheTtlMs`, so a composed report or a repeated listing does not
+  spend the rate limit twice. Writes always reach the network and clear the cache.
+- A cancelled turn cancels the request in flight, and the failure says so instead of
+  pretending to be a timeout.
+- Reads retry on a network failure, a timeout or a server error. Writes never retry: a
+  repeated write is a decision, not an accident.
+- Every list is also cut locally, because the API sometimes ignores the requested page size.
+- A failure says what to do next: a missing credential, a missing scope, an object that is
+  invisible (a draft release is only reachable by id), a conflict to re-read, a payload to
+  fix, a timeout to retry — and a broken `/etc/hosts` entry when the network is unreachable.
+
+## User interface
+
+The plugin contributes four small surfaces, all read-only except the two documented
+confirmations:
+
+- **Access status in the plugin card.** Source, account, scopes, remaining rate limit and
+  cache state. It is loaded from a local-only host route, so the access value never enters
+  the conversation. States: loading, not configured (with guidance), ok, error.
+- **Source Control tab** in the session view ring: repository path and branch with
+  ahead/behind, change groups (conflicts, staged, changes, untracked), a diff pane for the
+  selected file, an in-progress merge/rebase banner, and branches, tags and stashes. Reading
+  only for now: the commit bar and the branch/stash actions are the next step.
+- **GitHub panel** in the sidebar — it registers in better-sidebar and in the built-in right
+  sidebar. Repository switcher with public search, a Code tree with a file preview, and
+  Issues, Pull requests, Actions and Inbox tabs.
+- **Pull request bar** above the composer. It appears when the branch has commits the
+  upstream does not, and its buttons put an instruction on the clipboard instead of writing:
+  the call still goes through the normal approval contour.
+
+A short paragraph about the plugin is added to the system prompt (`guidance`), and a
+`github.com` link clicked in the conversation can record which repository to follow
+(`interceptLinks`, off by default).
+
 ## Safety
 
 - The token lives in the DSH credential service; settings hold only its name.
@@ -193,6 +273,17 @@ Tests live next to the code they cover and never touch the network: the transpor
 parameter, so failure modes (404, rate limit, timeout, non-JSON body, short pages) are
 exercised directly.
 
+## Visual verification
+
+The settings card, rendered by this release candidate on an isolated test server and captured
+from the real interface in both themes:
+
+![GitHub ops settings card, dark and light theme](media/visual-verification.png)
+
+What the picture shows: the plugin card with its title and description, the credential-name and
+access-source fields with their hints, and the access block the card loads from the host route.
+Both frames come from the same candidate and the same data.
+
 ## License
 
 MIT — see [LICENSE](LICENSE).

package/README.ru.md

@@ -67,6 +67,14 @@ dsh plugin --profile web add @goodandready/dsh-github-ops
 | `maxRetries` | `2` | Повторы для неудачного чтения (запись не повторяется). |
 | `reviewRulesJson` | пусто | Переопределение правил ревью в JSON: `sensitivePaths`, `sensitiveSeverity`, `attentionPaths`, `migrationPaths`, `testsRequired`, `sourcePatterns`, `testPatterns`, `largeDiffLines`. |
 | `reviewJobTimeoutMs` | `120000` | Сколько может работать фоновая задача ревью. |
+| `cacheTtlMs` | `60000` | Сколько живёт прочитанное в кэше. Записи всегда идут в сеть и сбрасывают кэш. `0` выключает кэш. |
+| `interceptLinks` | `false` | Разрешить ссылке `github.com` из чата запоминать репозиторий, за которым следуют вкладка Source Control и панель. Сама ссылка в любом случае открывается в браузере. |
+| `guidance` | `true` | Добавлять короткий абзац о плагине в системный промпт. |
+| `guidanceText` | *(пусто)* | Заменить этот абзац своим текстом. |
+| `oauthClientId` | публичное приложение `gh` CLI | OAuth-приложение, которым пользуется `gh_auth_login`. |
+| `oauthScope` | `repo workflow gist read:org` | Скоупы, которые запрашивает `gh_auth_login`. |
+| `oauthClientSecretRef` | *(пусто)* | Необязательное имя креденшела с секретом OAuth-приложения. |
+| `accessFile` | `$DSH_HOME/github-ops-auth.json` | Где `gh_auth_login` хранит вход (пишется с правами `0600`). |
 
 ## Инструменты
 
@@ -149,6 +157,42 @@ Allowlist — состав `package.json → files` плюс `.gitignore`, `LICE
 таймаут. Карточка проверяет **статус** снимка настроек и честно сообщает, когда сервис
 настроек недоступен, вместо того чтобы рисовать рабочий на вид формы.
 
+### Отчёты
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_repo_report` | Всё о репозитории одним вызовом: обзор, последний релиз, открытые issues, свежие коммиты, основные контрибьюторы. Если часть не удалась, деградирует только она, а не весь отчёт. |
+| `gh_weekly_digest` | Что случилось за окно: релизы, новые issues, слитые и закрытые PR, коммиты. PR идут отдельно и не выдаются за «новые issues». |
+| `gh_notifications` | Очередь внимания по аккаунту — упоминания, запросы ревью, назначения — сгруппированная по причинам. |
+| `gh_repo_health` | Прозрачная оценка сопровождения: пять измерений с доказательством по каждому, найденные риски и конкретные следующие действия. Это эвристика по публичным сигналам, а не аудит безопасности. |
+| `gh_compare` | Два репозитория рядом с числовыми разницами по звёздам, форкам и открытым issues. |
+| `gh_contributors` | Основные контрибьюторы репозитория по числу коммитов. |
+| `gh_user_repos` | Репозитории пользователя или организации по звёздам. |
+| `gh_trending` | Недавно созданные репозитории по звёздам, при желании — по языку (тратит квоту поиска). |
+| `gh_commits` | Свежие коммиты, при желании — начиная с даты и в конкретной ветке. |
+| `gh_help` | Все инструменты плагина по группам; каталог собирается из регистраций и не может устареть. |
+
+### Файлы и ветки
+
+Публикуют содержимое без локальной копии: коммит собирается так же, как это делает git.
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_repo_tree` | Дерево файлов на указанном ref, по умолчанию рекурсивно, с флагом обрезки — намного дешевле обхода каталогов. |
+| `gh_push_files` | Коммит файлов в ветку: blob'ы, дерево поверх дерева ветки, коммит, затем сдвиг ref. Ветка создаётся, если её нет. `force` никогда не подразумевается и требует `confirm: true`. |
+| `gh_upload_project` | Создать репозиторий, залить файлы и при желании открыть PR — одним вызовом. Существующий репозиторий используется как есть, а не роняет вызов. |
+| `gh_delete_file` | Удалить файл (сначала резолвится blob sha). Требует `confirm: true`. |
+| `gh_delete_branch` | Удалить ветку. Требует `confirm: true`. |
+
+### Аккаунт и вход
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_auth_login` | Начать вход по GitHub device flow: возвращает короткий код и ссылку для человека. |
+| `gh_auth_finish` | Забрать начатый вход. Выданное значение пишется в файл плагина с правами `0600` и никогда не возвращается в результате. |
+| `gh_auth_status` | Откуда взят доступ (креденшел, окружение, вход этого плагина, `gh` CLI), аккаунт, выданные скоупы и остаток лимита. |
+| `gh_auth_logout` | Забыть вход, сохранённый этим плагином; остальные источники не трогаются. Требует `confirm: true`. |
+
 ## Фоновые обзоры и команды
 
 `gh_review_job` запускает обзор и сразу возвращает id задачи, `gh_review_job_status` читает
@@ -160,6 +204,43 @@ Allowlist — состав `package.json → files` плюс `.gitignore`, `LICE
 в GitHub сама: она передаёт модели инструкцию, поэтому запись всё равно проходит через
 подтверждение.
 
+## Надёжность
+
+- Прочитанное кэшируется на `cacheTtlMs`, поэтому составной отчёт или повторный список не
+  тратят лимит дважды. Записи всегда идут в сеть и сбрасывают кэш.
+- Отменённый ход отменяет запрос в полёте, и в ошибке так и сказано — вместо маскировки под
+  таймаут.
+- Чтения повторяются при сбое сети, таймауте или ошибке сервера. Записи не повторяются
+  никогда: повторная запись — это решение, а не случайность.
+- Каждый список дополнительно режется локально: API иногда игнорирует запрошенный размер
+  страницы.
+- Ошибка говорит, что делать дальше: нет доступа, не хватает скоупа, объект невидим
+  (черновик релиза доступен только по id), конфликт — перечитать, payload — исправить,
+  таймаут — повторить; а при недоступной сети прямо называется битая запись `/etc/hosts`.
+
+## Интерфейс
+
+Плагин добавляет четыре небольшие поверхности; все они только читают, кроме двух явных
+подтверждений:
+
+- **Статус доступа в карточке плагина.** Источник, аккаунт, скоупы, остаток лимита и
+  состояние кэша. Грузится с локального хост-маршрута, поэтому значение доступа не попадает
+  в переписку. Состояния: загрузка, не настроено (с подсказкой), всё в порядке, ошибка.
+- **Вкладка Source Control** в кольце вкладок сессии: путь и ветка с ahead/behind, группы
+  изменений (конфликты, проиндексированные, изменённые, неотслеживаемые), панель диффа для
+  выбранного файла, баннер незавершённых merge/rebase, ветки, теги и stash. Пока только
+  чтение: строка коммита и действия с ветками и stash — следующий шаг.
+- **Панель GitHub** в сайдбаре — регистрируется в better-sidebar и во встроенном правом
+  сайдбаре. Переключатель репозиториев с поиском публичных, дерево Code с просмотром файла
+  и вкладки Issues, Pull requests, Actions, Inbox.
+- **Полоса PR** над полем ввода. Появляется, когда в ветке есть коммиты, которых нет в
+  upstream, а её кнопки кладут инструкцию в буфер обмена вместо записи: вызов всё равно идёт
+  через штатный контур подтверждений.
+
+Короткий абзац о плагине добавляется в системный промпт (`guidance`), а клик по ссылке
+`github.com` из чата может запомнить, за каким репозиторием следить (`interceptLinks`, по
+умолчанию выключено).
+
 ## Безопасность
 
 - Токен живёт в сервисе учётных данных DSH; в настройках только его имя.

package/README.zh.md

@@ -64,6 +64,14 @@ dsh plugin --profile web add @goodandready/dsh-github-ops
 | `maxRetries` | `2` | 读取失败时的重试次数（写入不重试）。 |
 | `reviewRulesJson` | 空 | 以 JSON 覆盖评审规则：`sensitivePaths`、`sensitiveSeverity`、`attentionPaths`、`migrationPaths`、`testsRequired`、`sourcePatterns`、`testPatterns`、`largeDiffLines`。 |
 | `reviewJobTimeoutMs` | `120000` | 后台评审任务的最长运行时间。 |
+| `cacheTtlMs` | `60000` | 读取结果在内存缓存中的存活时间。写入始终访问网络并清空缓存；设为 `0` 关闭缓存。 |
+| `interceptLinks` | `false` | 允许会话中点击的 `github.com` 链接记录仓库，供 Source Control 标签页与侧边栏面板跟随。无论如何链接都会在浏览器中打开。 |
+| `guidance` | `true` | 在系统提示中加入一段关于本插件的简短说明。 |
+| `guidanceText` | *(空)* | 用自定义文本替换该说明。 |
+| `oauthClientId` | 公开的 `gh` CLI 应用 | `gh_auth_login` 使用的 OAuth 应用。 |
+| `oauthScope` | `repo workflow gist read:org` | `gh_auth_login` 请求的权限范围。 |
+| `oauthClientSecretRef` | *(空)* | 可选的、保存 OAuth 客户端密钥的凭据名称。 |
+| `accessFile` | `$DSH_HOME/github-ops-auth.json` | `gh_auth_login` 保存登录信息的位置（权限 `0600`）。 |
 
 ## 工具
 
@@ -143,6 +151,42 @@ dsh plugin --profile web add @goodandready/dsh-github-ops
 `settings.plugin.item`）：凭据名称、默认仓库、API 地址、请求超时。卡片会检查设置快照的
 **状态**，在设置服务不可用时明确说明，而不是画出一个看似可用的表单。
 
+### 报告
+
+| 工具 | 作用 |
+|---|---|
+| `gh_repo_report` | 一次调用给出仓库全貌：概览、最新 Release、打开的 Issue、近期提交、主要贡献者。某一部分失败只影响该部分，不会让整份报告失败。 |
+| `gh_weekly_digest` | 时间窗口内发生了什么：Release、新 Issue、已合并或关闭的 PR、提交。PR 单独统计，不会被当作“新 Issue”。 |
+| `gh_notifications` | 账号的关注队列——提及、评审请求、指派——按原因分组。 |
+| `gh_repo_health` | 透明的维护评分：五个加权维度，每项都带证据，另有风险与具体下一步。它是基于公开信号的启发式判断，不是安全审计。 |
+| `gh_compare` | 两个仓库并排比较，给出星标、Fork、打开 Issue 的数值差异。 |
+| `gh_contributors` | 按提交数排列的主要贡献者。 |
+| `gh_user_repos` | 用户或组织的仓库，按星标排序。 |
+| `gh_trending` | 近期创建的热门仓库，可按语言筛选（消耗搜索配额）。 |
+| `gh_commits` | 近期提交，可按时间与分支过滤。 |
+| `gh_help` | 本插件的全部工具，按领域分组，由注册表生成，不会过期。 |
+
+### 文件与分支
+
+无需本地检出即可发布内容：提交按 git 的方式组装。
+
+| 工具 | 作用 |
+|---|---|
+| `gh_repo_tree` | 指定 ref 的文件树，默认递归，并给出截断标志——比逐层遍历目录便宜得多。 |
+| `gh_push_files` | 向分支提交文件：blob → 基于分支树的 tree → commit → 移动 ref。分支不存在会创建。`force` 绝不隐含，且需要 `confirm: true`。 |
+| `gh_upload_project` | 创建仓库、发布文件并可选地打开 PR——一次调用。仓库已存在时直接使用，而不是失败。 |
+| `gh_delete_file` | 删除单个文件（先解析 blob sha）。需要 `confirm: true`。 |
+| `gh_delete_branch` | 删除分支。需要 `confirm: true`。 |
+
+### 账号与登录
+
+| 工具 | 作用 |
+|---|---|
+| `gh_auth_login` | 启动 GitHub device flow 登录：返回短码与供人工确认的网址。 |
+| `gh_auth_finish` | 收取已启动的登录。授权值写入本插件自己的文件（权限 `0600`），绝不会出现在工具结果里。 |
+| `gh_auth_status` | 访问来源（凭据、环境变量、本插件登录、`gh` CLI）、账号、已授权范围与剩余速率限制。 |
+| `gh_auth_logout` | 忘记本插件保存的登录；其他来源不受影响。需要 `confirm: true`。 |
+
 ## 后台评审与斜杠命令
 
 `gh_review_job` 立即返回任务 id，`gh_review_job_status` 读取结果。宿主提供任务注册表时，
@@ -152,6 +196,25 @@ dsh plugin --profile web add @goodandready/dsh-github-ops
 `/issue new <title> | list | show <number>`、`/gh [分组|工具]`。命令本身**不会**写入 GitHub，
 只是把指令交给模型，因此写入仍然经过审批关卡。
 
+## 可靠性
+
+- 读取结果按 `cacheTtlMs` 缓存，因此组合报告或重复列表不会重复消耗速率限制。写入始终访问网络并清空缓存。
+- 被取消的回合会取消在途请求，错误会如实说明，而不是伪装成超时。
+- 读取会在网络失败、超时或服务端错误时重试；写入从不重试——重复写入是决策，不是意外。
+- 每个列表同时会在本地截断，因为 API 有时会忽略请求的分页大小。
+- 失败会说明下一步该做什么：缺少凭据、权限范围不足、对象不可见（草稿 Release 只能按 id 访问）、需要重新读取的冲突、需要修正的载荷、可以重试的超时；网络不可达时还会指出 `/etc/hosts` 被写坏。
+
+## 界面
+
+插件提供四个小界面，除两处明确确认外均为只读：
+
+- **插件卡片中的访问状态。** 来源、账号、权限范围、剩余速率限制与缓存状态。数据来自仅本机可访问的宿主路由，访问值不会进入对话。状态：加载中、未配置（附指引）、正常、错误。
+- **Source Control 标签页**（会话视图环）：仓库路径与分支的 ahead/behind、变更分组（冲突、已暂存、已修改、未跟踪）、所选文件的差异面板、进行中的 merge/rebase 提示，以及分支、标签与 stash。目前只读：提交栏与分支/stash 操作是下一步。
+- **侧边栏 GitHub 面板**——同时注册到 better-sidebar 与内置右侧栏。带公开搜索的仓库切换器、带文件预览的 Code 树，以及 Issues、Pull requests、Actions、Inbox 四个标签。
+- **输入框上方的 Pull Request 条**。当分支存在上游没有的提交时出现；其按钮把指令复制到剪贴板而不是直接写入——调用仍走正常的审批链路。
+
+系统提示中会加入一段关于本插件的简短说明（`guidance`）；会话中点击的 `github.com` 链接可以记录要跟随的仓库（`interceptLinks`，默认关闭）。
+
 ## 安全边界
 
 - token 只存在于 DSH 凭据服务，设置中只有名称；

package/lib/auth-device.js

@@ -0,0 +1,150 @@
+// Signing in without a terminal.
+//
+// GitHub's device flow: ask for a code, show it to the human, poll until they approve. The
+// polling loop takes its clock and its transport as parameters, so it is testable without
+// waiting a minute or touching the network.
+//
+// The granted value is written to this plugin's own file with mode 0600 (the DSH credentials
+// service is the preferred home, but it is not writable by a plugin). The value is never
+// logged, never echoed in an error, and never returned in a tool result.
+
+import { promises as fs } from 'node:fs'
+import { homedir } from 'node:os'
+import { dirname, join } from 'node:path'
+
+/** GitHub CLI's public OAuth application id: the one the gh CLI itself signs in with. */
+export const DEFAULT_CLIENT_ID = '178c6fc778ccc68e1d6a'
+export const DEFAULT_SCOPE = 'repo workflow gist read:org'
+
+export const DEVICE_CODE_URL = 'https://github.com/login/device/code'
+export const ACCESS_TOKEN_URL = 'https://github.com/login/oauth/access_token'
+
+/** Where a device-flow sign-in is stored. `$DSH_HOME` wins, then `~/.dsh`. */
+export function accessFilePath(env = process.env) {
+  const home = env.DSH_HOME && env.DSH_HOME.trim() ? env.DSH_HOME.trim() : join(homedir(), '.dsh')
+  return join(home, 'github-ops-auth.json')
+}
+
+async function postJson(fetchImpl, url, body, accept = 'application/json') {
+  const response = await fetchImpl(url, {
+    method: 'POST',
+    headers: { accept, 'content-type': 'application/json', 'user-agent': 'dsh-github-ops' },
+    body: JSON.stringify(body),
+  })
+  const text = typeof response.text === 'function' ? await response.text() : ''
+  let payload = {}
+  if (text) {
+    try {
+      payload = JSON.parse(text)
+    } catch {
+      const params = new URLSearchParams(text)
+      payload = Object.fromEntries(params.entries())
+    }
+  }
+  if (!response.ok) {
+    const message = payload.error_description || payload.error || `HTTP ${response.status}`
+    const err = new Error(String(message))
+    err.status = response.status
+    throw err
+  }
+  return payload
+}
+
+/** Ask GitHub for a user code. Nothing is stored yet. */
+export async function startDeviceFlow({ clientId = DEFAULT_CLIENT_ID, scope = DEFAULT_SCOPE, fetchImpl = globalThis.fetch } = {}) {
+  if (typeof fetchImpl !== 'function') throw new Error('no fetch implementation available')
+  const payload = await postJson(fetchImpl, DEVICE_CODE_URL, { client_id: clientId, scope })
+  if (!payload.device_code || !payload.user_code) {
+    throw new Error('GitHub did not return a device code')
+  }
+  return {
+    deviceCode: payload.device_code,
+    userCode: payload.user_code,
+    verificationUri: payload.verification_uri || payload.verification_uri_complete || 'https://github.com/login/device',
+    expiresInSeconds: Number(payload.expires_in) || 900,
+    intervalSeconds: Number(payload.interval) || 5,
+    scope,
+  }
+}
+
+/**
+ * Poll until the human approves, the code expires, or the wait budget runs out.
+ *
+ * @returns {{status: 'authorized', token: string, scope: string} | {status: 'pending'|'expired'|'denied', message: string}}
+ */
+export async function pollDeviceFlow({
+  clientId = DEFAULT_CLIENT_ID,
+  deviceCode,
+  clientSecret,
+  fetchImpl = globalThis.fetch,
+  sleepImpl,
+  intervalSeconds = 5,
+  maxWaitMs = 120000,
+} = {}) {
+  if (!deviceCode) throw new Error('deviceCode is required')
+  const sleep = typeof sleepImpl === 'function'
+    ? sleepImpl
+    : (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+  let interval = Math.max(1, Number(intervalSeconds) || 5)
+  const deadline = Date.now() + Math.max(1000, Number(maxWaitMs) || 120000)
+
+  while (Date.now() < deadline) {
+    const body = { client_id: clientId, device_code: deviceCode, grant_type: 'urn:ietf:params:oauth:grant-type:device_code' }
+    if (clientSecret) body.client_secret = clientSecret
+    let payload
+    try {
+      payload = await postJson(fetchImpl, ACCESS_TOKEN_URL, body)
+    } catch (err) {
+      // the endpoint answers 200 with an error field; a transport failure is a real failure
+      return { status: 'denied', message: String((err && err.message) || err) }
+    }
+    if (payload.access_token) {
+      return { status: 'authorized', token: String(payload.access_token), scope: String(payload.scope || '') }
+    }
+    const error = String(payload.error || '')
+    if (error === 'authorization_pending') {
+      await sleep(interval * 1000)
+      continue
+    }
+    if (error === 'slow_down') {
+      interval += 5
+      await sleep(interval * 1000)
+      continue
+    }
+    if (error === 'expired_token') return { status: 'expired', message: 'the code expired: start the sign-in again' }
+    if (error === 'access_denied') return { status: 'denied', message: 'the sign-in was denied' }
+    return { status: 'denied', message: payload.error_description || error || 'unexpected answer from GitHub' }
+  }
+  return { status: 'pending', message: 'still waiting for approval: ask again to keep polling' }
+}
+
+/** Store a granted value. Written 0600 and never returned to the caller. */
+export async function writeAccessFile(path, { token, login = '', scope = '', source = 'device-flow' } = {}) {
+  if (!token) throw new Error('token is required')
+  await fs.mkdir(dirname(path), { recursive: true })
+  const record = { token, login, scope, source, savedAt: new Date().toISOString() }
+  await fs.writeFile(path, `${JSON.stringify(record, null, 2)}\n`, { mode: 0o600 })
+  await fs.chmod(path, 0o600).catch(() => {})
+  return { path, login, scope }
+}
+
+/** Read the stored sign-in, or null when there is none. */
+export async function readAccessFile(path) {
+  try {
+    const text = await fs.readFile(path, 'utf8')
+    const parsed = JSON.parse(text)
+    return parsed && parsed.token ? parsed : null
+  } catch {
+    return null
+  }
+}
+
+/** Forget the stored sign-in. */
+export async function clearAccessFile(path) {
+  try {
+    await fs.rm(path, { force: true })
+    return { removed: true, path }
+  } catch (err) {
+    return { removed: false, path, error: String((err && err.message) || err) }
+  }
+}

package/lib/auth.js

@@ -1,7 +1,8 @@
 // Access resolution across the sources a GitHub user actually has.
 //
-// Order (tokenSource: "auto"): the DSH credentials service, then the environment
-// variable of the same name, then the `gh` CLI session. The credential service stays
+// Order (tokenSource: "auto"): the DSH credentials service, then the environment variable of
+// the same name, then the sign-in this plugin stored itself (gh_auth_login), then the `gh` CLI
+// session. The credential service stays
 // the recommended source — it is the only one DSH manages and rotates — but a machine
 // with `gh auth login` already done should not need a second copy of the same secret.
 //
@@ -10,9 +11,10 @@
 
 export const NO_ACCESS_GUIDANCE = 'Configure one of: 1) a DSH credential with this name '
   + '($DSH_HOME/.credentials.yaml) — recommended, 2) the same-named environment variable, '
-  + '3) `gh auth login` for the gh CLI. Set tokenSource in the plugin settings to pin one source.'
+  + '3) gh_auth_login to sign in from here, 4) `gh auth login` for the gh CLI. '
+  + 'Set tokenSource in the plugin settings to pin one source.'
 
-export const ACCESS_SOURCES = ['credentials', 'env', 'gh']
+export const ACCESS_SOURCES = ['credentials', 'env', 'file', 'gh']
 
 /**
  * Resolve access for one operation. Nothing is cached: a rotated credential reaches the
@@ -25,7 +27,7 @@ export const ACCESS_SOURCES = ['credentials', 'env', 'gh']
  * @param runGh - async () => string; returns the gh CLI access value, '' when unavailable
  * @returns {Promise<{ value: string, source: string, guidance: string }>}
  */
-export async function resolveAccess({ credentials, tokenEnv, tokenSource = 'auto', env = process.env, runGh } = {}) {
+export async function resolveAccess({ credentials, tokenEnv, tokenSource = 'auto', env = process.env, runGh, runFile } = {}) {
   const order = tokenSource === 'auto' ? ACCESS_SOURCES : [tokenSource]
   for (const source of order) {
     if (source === 'credentials') {
@@ -45,6 +47,16 @@ export async function resolveAccess({ credentials, tokenEnv, tokenSource = 'auto
       if (value) return { value, source, guidance: '' }
       continue
     }
+    if (source === 'file') {
+      let value = ''
+      try {
+        value = runFile ? String((await runFile()) || '').trim() : ''
+      } catch {
+        value = ''
+      }
+      if (value) return { value, source, guidance: '' }
+      continue
+    }
     if (source === 'gh') {
       let value = ''
       try {