@goodandready/dsh-github-ops 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,81 @@
+# Changelog
+
+Notable changes to `@goodandready/dsh-github-ops`.
+
+## 0.1.1
+
+- Retries and rate-limit respect: a read (GET/HEAD) is retried on a network failure, a
+  timeout or a 5xx, and a 429 is honoured through `Retry-After` or the rate-limit reset.
+  A write is never retried automatically. `maxRetries` in settings.
+- A call may omit the repository inside a checkout: it is taken from the origin remote.
+  `owner/repo#12` and a bare `12` are understood.
+- Review findings are configuration now: glob paths, severities, the large-diff threshold
+  and whether tests are required (`reviewRulesJson`).
+- Tool results render as cards (links, branch pairs, verdicts, failing steps) instead of a
+  JSON blob.
+- Writes pass through the approval contour: every write maps to a named action, an action
+  outside `allowedActions` is denied, destructive actions always ask, and only
+  `DSH_GITHUB_OPS_UNATTENDED=1` with `autoApprove` can skip a prompt.
+- Background reviews: `gh_review_job` starts one and answers immediately;
+  `gh_review_job_status` reads it.
+- Slash commands: `/pr create [title]`, `/review [number]`, `/issue new|list|show`, `/gh`.
+  A command never writes itself — it hands the model an instruction, so the write still goes
+  through the approval gate.
+- Access can come from the DSH credential, the environment variable or the `gh` CLI session
+  (`tokenSource`), which is why a machine with `gh auth login` needs no extra configuration.
+
+## 0.1.0 — first release
+
+The plugin is **not released yet**: it must first carry the full tool set — parity with
+the reference GitHub plugin plus the operations our release pipeline needs.
+
+### Added
+- GitHub API client (`lib/github.js`): REST v3 and GraphQL v4 behind one transport that
+  is injected (`fetchImpl`), so every caller and every test runs without a network.
+  Failures are normalized into one shape — `status`, `code` (`http_error`,
+  `rate_limited`, `timeout`, `network`, `graphql_error`), `rateLimit` with the reset
+  time — so a tool never throws a turn away because GitHub answered 404 or 403.
+- Release tools: `gh_release_list`, `gh_release_view`, `gh_release_create`,
+  `gh_release_edit` (including `makeLatest`), `gh_release_delete`.
+- Tag tools: `gh_tag_list`, `gh_tag_create` (lightweight or annotated), `gh_tag_delete`.
+- `gh_api`: guarded generic pass-through — reads are free, `POST`/`PATCH`/`PUT`/`DELETE`
+  require `confirm: true`, and deleting a repository, transferring one or deleting an
+  organization is refused outright.
+- Tests without a harness and without a network: 51 cases covering URL building, error
+  mapping, rate limits, timeouts, pagination, GraphQL, tag object ordering, base64 file
+  decoding, issue normalization, diff truncation, the CI rollup and the `gh_api` safety
+  boundary.
+- Repository tools: `gh_repo`, `gh_file` (file content at a ref, or a directory
+  listing), `gh_repo_search`, `gh_repo_create`, `gh_repo_edit`.
+- Issue tools: `gh_issue`, `issue_open`, `issue_comment`, `issue_close`, `gh_search`.
+- Pull request tools: `pr_create`, `pr_update`, `pr_merge` (merge/squash/rebase,
+  optional head-branch delete), `gh_review` (metadata, areas, capped diff, comments,
+  CI rollup and deterministic findings), `review_post` (summary or inline),
+  `gh_checks`, `ci_run` (one-shot review with a rule-based verdict).
+
+- Mirror tools: `gh_mirror_check` (read-only plan: what would be published, what stays
+  behind, and why a publication must be refused) and `gh_mirror_publish` (one commit on
+  top of the mirror branch, fast-forward, never a force; `dryRun`, `confirm: true`).
+  The allowlist is the package manifest's own `files` plus README/LICENSE/CHANGELOG/
+  `cordis.patch.yml`; `docs/**` and agent instructions are forbidden even when a manifest
+  lists them, while shipped tooling such as `scripts/**` is published because it is part
+  of the package.
+- Workflow-run tools: `gh_run_list`, `gh_run_view`, `gh_run_jobs` (failed steps named),
+  `gh_run_rerun` (all or failed-only), `gh_run_cancel`, `gh_run_logs` (returns the zip
+  URL instead of pulling a binary into the conversation).
+- Repository settings tools: `gh_variable_list/set/delete`, `gh_secret_list/set/delete`,
+  `gh_ruleset_list/view/apply/delete`, `gh_branch_protection_get/set/delete`.
+  Setting a secret uses GitHub sealed-box encryption through the optional `tweetnacl`
+  package; without it the tool explains what to install rather than writing a broken
+  value.
+- Browser half: a settings card on the plugin's own page (the plugin-list seat
+  `plugins.item`, plus the row seat and the legacy `settings.plugin.item` card) with
+  locales `en`/`zh`, a snapshot-status check so an unavailable settings service is stated
+  instead of hidden, all-changed-fields saving with per-field failure reporting, and a
+  style element tagged `data-dsh-plugin="dsh-github-ops"`.
+
+### Planned (release blockers)
+- Release notes for `dsh-russian-lang` (the card adds no new user-facing strings beyond
+  the four settings, but the translation issue must be filed before publishing).
+- Verification on the isolated DSH test server, then acceptance on production, then the
+  public release (npm + GitHub) after an explicit go-ahead.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 GooDAnDReaDY
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,163 @@
+# dsh-github-ops
+
+GitHub operations for [DeepSeek Harness](https://github.com/topics/dsh-plugin): releases,
+tags, a guarded generic API pass-through, workflow runs, secrets and sanitized mirror
+publication.
+
+The plugin exists because the release pipeline needs operations the existing GitHub
+plugin does not provide — releases and tags first, then a way to publish a GitHub mirror
+that carries the **product** and not the whole development tree.
+
+> **Status: work in progress, not released.** The public release happens only after the
+> plugin carries the full tool set (see [Roadmap](#roadmap)).
+
+## Install
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-github-ops
+```
+
+Requires a GitHub token in the DSH credential service. Store the token under a name
+(default `GITHUB_TOKEN`) and put only that **name** in the plugin settings.
+
+## Settings
+
+| Setting | Default | Meaning |
+|---|---|---|
+| `tokenEnv` | `GITHUB_TOKEN` | Name looked up in the DSH credentials, then the environment, then the `gh` CLI. The value is never stored in settings. |
+| `tokenSource` | `auto` | Where access comes from: `auto` tries the DSH credential, then the environment variable, then the `gh` CLI session; pin it to `credentials`, `env` or `gh`. |
+| `defaultRepository` | *(empty)* | `owner/repo` used by tools that omit `repository`. |
+| `baseUrl` | `https://api.github.com` | API base; change it for GitHub Enterprise. |
+| `timeoutMs` | `30000` | Per-request timeout. |
+| `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`. |
+| `allowedActions` | *(all)* | Write actions the plugin may perform; anything else is denied. Each one still asks. |
+| `autoApprove` | *(empty)* | Actions an unattended run (`DSH_GITHUB_OPS_UNATTENDED=1`) may perform without asking. Destructive actions are never auto-approved. |
+| `reviewJobTimeoutMs` | `120000` | How long a background review job may run. |
+
+## Tools
+
+### Releases
+
+| Tool | What it does |
+|---|---|
+| `gh_release_list` | List releases, newest first (read-only). |
+| `gh_release_view` | Read one release by tag: flags, notes, assets (read-only). |
+| `gh_release_create` | Create a release for a tag, optionally on a specific commit. |
+| `gh_release_edit` | Edit title, notes, draft/prerelease, and **which release is latest**. |
+| `gh_release_delete` | Delete a release (requires `confirm: true`). |
+
+`gh_release_edit` with `makeLatest: true` is the step that keeps the repository badge on
+the current version: creating older releases afterwards otherwise moves “Latest” back.
+
+### Tags
+
+| Tool | What it does |
+|---|---|
+| `gh_tag_list` | List tags with their commit SHAs (read-only). |
+| `gh_tag_create` | Create a tag — lightweight, or annotated when `message` is given. |
+| `gh_tag_delete` | Delete a tag (requires `confirm: true`). |
+
+### Generic API
+
+`gh_api` reaches anything the typed tools do not cover (refs, rulesets, organizations,
+gists). Reads are free. `POST`/`PATCH`/`PUT`/`DELETE` require `confirm: true`. Deleting a
+repository, transferring a repository or deleting an organization is refused outright —
+a single confirmation cannot make those safe.
+
+### Issues and pull requests
+
+| Tool | What it does |
+|---|---|
+| `gh_issue` | List or read issues (`action: list\|get\|comments`); pull requests come back as `kind: "pr"`. |
+| `issue_open`, `issue_comment`, `issue_close` | Create an issue, comment on an issue or PR, close it (optionally with a state reason). |
+| `gh_search` | Search issues and PRs with GitHub search syntax (separate quota). |
+| `pr_create`, `pr_update` | Open a pull request from a head branch; edit title, body, state or base. |
+| `pr_merge` | Merge a PR (merge/squash/rebase), optionally deleting the head branch. |
+| `gh_review` | One review pack: metadata, areas, capped diff, comments, CI rollup and deterministic findings (secrets, migrations, CI config, source without tests, large diff). |
+| `review_post` | Publish a review as one summary comment, or as line-anchored inline comments. |
+| `gh_checks` | Check runs, legacy statuses and one rollup verdict for a commit. |
+| `ci_run` | One-shot review of a PR with a rule-based verdict. |
+
+### Mirror publication
+
+| Tool | What it does |
+|---|---|
+| `gh_mirror_check` | Read-only plan: which product files would reach the mirror, how many stay behind, and why a publication must be refused. |
+| `gh_mirror_publish` | Publish the sanitized tree: one commit on top of the mirror branch, fast-forward, **never a force**. `dryRun: true` previews; writing needs `confirm: true`. |
+
+The allowlist is the package manifest's own `files` plus `.gitignore`, `LICENSE`,
+README trio, `CHANGELOG.md` and `cordis.patch.yml`. `docs/**` and agent instructions are
+forbidden even when a manifest lists them; shipped tooling such as `scripts/**` is
+published because it is part of the package.
+
+### Workflow runs
+
+| Tool | What it does |
+|---|---|
+| `gh_run_list`, `gh_run_view` | List runs (branch, workflow, status filters) and read one run. |
+| `gh_run_jobs` | Jobs with their steps, and the steps that failed — usually enough to diagnose a failure. |
+| `gh_run_rerun`, `gh_run_cancel` | Re-run all or only failed jobs; cancel an in-progress run (needs `confirm: true`). |
+| `gh_run_logs` | Returns the logs archive URL: GitHub answers with a redirect to a zip, which is not pulled into the conversation. |
+
+### Repository settings
+
+| Tool | What it does |
+|---|---|
+| `gh_variable_list/set/delete` | Actions variables, repository-wide or per environment. |
+| `gh_secret_list/set/delete` | Actions secrets. Setting one uses sealed-box encryption through the optional `tweetnacl` package; without it the tool says what to install instead of writing a broken value. |
+| `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. |
+
+## Background reviews and commands
+
+`gh_review_job` starts a review and returns a job id immediately; `gh_review_job_status`
+reports it. With a host job registry the work is visible and cancellable in the UI; without
+one it runs inside the plugin.
+
+Slash commands are the fast path for a human:
+
+| Command | What it does |
+|---|---|
+| `/pr create [title]` | Reads the current branch and origin, then instructs the model to call `pr_create`. |
+| `/review [number]` | Reviews a pull request (or the one for the current branch). |
+| `/issue new <title>` \| `/issue list` \| `/issue show <number>` | Opens, lists or reads issues. |
+| `/gh [group\|tool]` | Points at the tools for releases, tags, mirror, runs, secrets, variables, rulesets or branch protection. |
+
+A command never writes to GitHub itself: it hands the model an instruction, so the write
+still passes through the approval gate.
+
+## Safety
+
+- The token lives in the DSH credential service; settings hold only its name.
+- Read operations never change state; mutations are confirmed explicitly, and deleting a
+  repository, transferring one or deleting an organization is refused outright.
+- The client never logs the token, and every failure is reported as a value
+  (`ok: false` with `status`, `code`, `rateLimit`) instead of an exception.
+- Findings from `gh_review` are deterministic rules: they point at what needs attention
+  and are never presented as a verdict on correctness.
+
+## Roadmap
+
+Everything planned for the first release is implemented. What remains is the release
+process itself:
+
+1. Preflight (`dsh-plugin-preflight`) and the package check.
+2. Verification of the exact `.tgz` on the isolated DSH test server.
+3. Acceptance of the same candidate on production.
+4. Translation notes for `dsh-russian-lang`.
+5. Public release (npm + GitHub) after an explicit go-ahead.
+
+## Development
+
+```bash
+npm test        # node --test, no harness and no network: fetch is injected
+```
+
+Tests live next to the code they cover and never touch the network: the transport is a
+parameter, so failure modes (404, rate limit, timeout, non-JSON body, short pages) are
+exercised directly.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/README.ru.md

@@ -0,0 +1,161 @@
+# dsh-github-ops
+
+Операции с GitHub для [DeepSeek Harness](https://github.com/topics/dsh-plugin): релизы,
+теги, защищённый универсальный доступ к API, запуски workflow, секреты и публикация
+санитизированного зеркала.
+
+Плагин появился потому, что релизному конвейеру нужны операции, которых нет в
+существующем GitHub-плагине: сначала релизы и теги, затем способ публиковать
+GitHub-зеркало, которое несёт **продукт**, а не всё дерево разработки.
+
+> **Статус: в работе, релиза нет.** Публикация состоится только после того, как в плагине
+> появятся все инструменты (см. [План](#план)).
+
+## Установка
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-github-ops
+```
+
+Нужен токен GitHub в сервисе учётных данных DSH. Имя по умолчанию — `GITHUB_TOKEN`,
+в настройках плагина хранится только это **имя**.
+
+## Настройки
+
+| Настройка | Значение по умолчанию | Смысл |
+|---|---|---|
+| `tokenEnv` | `GITHUB_TOKEN` | Имя, которое ищется в креденшелах DSH, затем в переменной окружения, затем в `gh` CLI. Само значение в настройках не хранится. |
+| `tokenSource` | `auto` | Откуда берётся доступ: `auto` — креденшел DSH, затем переменная окружения, затем сессия `gh`; можно зафиксировать `credentials`, `env` или `gh`. |
+| `defaultRepository` | пусто | `owner/repo`, если в вызове инструмента репозиторий не указан. |
+| `baseUrl` | `https://api.github.com` | База API; меняется для GitHub Enterprise. |
+| `timeoutMs` | `30000` | Таймаут одного запроса. |
+| `maxRetries` | `2` | Повторы для неудачного чтения (запись не повторяется). |
+| `reviewRulesJson` | пусто | Переопределение правил ревью в JSON: `sensitivePaths`, `sensitiveSeverity`, `attentionPaths`, `migrationPaths`, `testsRequired`, `sourcePatterns`, `testPatterns`, `largeDiffLines`. |
+| `allowedActions` | все | Разрешённые записи; всё остальное отклоняется, и каждая всё равно спрашивает подтверждение. |
+| `autoApprove` | пусто | Действия, которые неавтономный прогон (`DSH_GITHUB_OPS_UNATTENDED=1`) может выполнить без вопроса; разрушительные не автоутверждаются никогда. |
+| `reviewJobTimeoutMs` | `120000` | Сколько может работать фоновая задача ревью. |
+
+## Инструменты
+
+### Релизы
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_release_list` | Список релизов от новых к старым (только чтение). |
+| `gh_release_view` | Чтение релиза по тегу: флаги, заметки, артефакты (только чтение). |
+| `gh_release_create` | Создание релиза для тега, при необходимости на конкретном коммите. |
+| `gh_release_edit` | Правка заголовка, заметок, draft/prerelease и **того, какой релиз считается latest**. |
+| `gh_release_delete` | Удаление релиза (нужно `confirm: true`). |
+
+`gh_release_edit` с `makeLatest: true` — тот шаг, который держит бейдж репозитория на
+актуальной версии: если после этого создать релиз старой версии, «Latest» уедет назад.
+
+### Теги
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_tag_list` | Список тегов с SHA коммитов (только чтение). |
+| `gh_tag_create` | Создание тега — обычного, либо аннотированного при наличии `message`. |
+| `gh_tag_delete` | Удаление тега (нужно `confirm: true`). |
+
+### Универсальный API
+
+`gh_api` закрывает всё, что не покрыто типизированными инструментами (refs, rulesets,
+организации, gists). Чтение свободно; `POST`/`PATCH`/`PUT`/`DELETE` требуют
+`confirm: true`. Удаление репозитория, его перенос и удаление организации отклоняются
+сразу: одно подтверждение не делает такие вызовы безопасными.
+
+### Issues и pull requests
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_issue` | Список или чтение issues (`action: list/get/comments`); PR приходят с `kind: "pr"`. |
+| `issue_open`, `issue_comment`, `issue_close` | Создать issue, прокомментировать, закрыть (с причиной). |
+| `gh_search` | Поиск issues и PR синтаксисом GitHub (отдельная квота). |
+| `pr_create`, `pr_update` | Открыть PR из head-ветки; правка заголовка, тела, состояния, базовой ветки. |
+| `pr_merge` | Слияние PR (merge/squash/rebase) с опциональным удалением head-ветки. |
+| `gh_review` | Один обзорный пакет: метаданные, области, дифф с лимитом, комменты, сводка CI и детерминированные находки (секреты, миграции, CI-конфиг, изменения в исходниках без тестов, крупный дифф). |
+| `review_post` | Публикация обзора: сводный комментарий или построчные inline-замечания. |
+| `gh_checks` | Check-runs, статусы коммита и единый вердикт. |
+| `ci_run` | Одноразовый обзор PR с вердиктом по правилам. |
+
+### Публикация зеркала
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_mirror_check` | Read-only план: какие продуктовые файлы уедут в зеркало, сколько останется и почему публикация должна быть отклонена. |
+| `gh_mirror_publish` | Публикация санитизированного дерева: один коммит поверх зеркальной ветки, fast-forward, **никогда не force**. `dryRun: true` — только превью; запись требует `confirm: true`. |
+
+Allowlist — состав `package.json → files` плюс `.gitignore`, `LICENSE`, README-трио,
+`CHANGELOG.md` и `cordis.patch.yml`. `docs/**` и инструкции агентов запрещены даже при
+наличии в манифесте; поставляемый инструментарий вроде `scripts/**` публикуется, потому
+что входит в пакет.
+
+### Запуски workflow
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_run_list`, `gh_run_view` | Список запусков (фильтры по ветке, workflow, статусу) и чтение одного запуска. |
+| `gh_run_jobs` | Джобы с шагами и отдельно — упавшие шаги; обычно этого достаточно для диагноза. |
+| `gh_run_rerun`, `gh_run_cancel` | Перезапуск всех или только упавших джоб; отмена идущего запуска (нужно `confirm: true`). |
+| `gh_run_logs` | Возвращает адрес архива логов: GitHub отвечает редиректом на zip, который не тянется в разговор. |
+
+### Настройки репозитория
+
+| Инструмент | Что делает |
+|---|---|
+| `gh_variable_list/set/delete` | Actions-переменные: в репозитории или в конкретном окружении. |
+| `gh_secret_list/set/delete` | Actions-секреты. Установка использует sealed-box шифрование через опциональный `tweetnacl`; без него инструмент говорит, что установить, а не пишет испорченное значение. |
+| `gh_ruleset_list/view/apply/delete` | Rulesets: чтение, создание, обновление, удаление. |
+| `gh_branch_protection_get/set/delete` | Классическая защита веток: обязательные ревью, статус-чеки, принуждение для админов, флаги force-push и удаления. |
+
+### Карточка настроек
+
+Настройки живут на странице плагина (списочная посадка `plugins.item`, плюс посадка строки
+и легаси `settings.plugin.item`): имя учётной записи, репозиторий по умолчанию, база API и
+таймаут. Карточка проверяет **статус** снимка настроек и честно сообщает, когда сервис
+настроек недоступен, вместо того чтобы рисовать рабочий на вид формы.
+
+## Фоновые обзоры и команды
+
+`gh_review_job` запускает обзор и сразу возвращает id задачи, `gh_review_job_status` читает
+результат. Если в композиции есть реестр задач, работа видна и отменяема в интерфейсе; если
+нет — выполняется внутри плагина.
+
+Слэш-команды — быстрый путь для человека: `/pr create [title]`, `/review [number]`,
+`/issue new <title> | list | show <number>`, `/gh [группа|инструмент]`. Команда **не пишет**
+в GitHub сама: она передаёт модели инструкцию, поэтому запись всё равно проходит через
+подтверждение.
+
+## Безопасность
+
+- Токен живёт в сервисе учётных данных DSH; в настройках только его имя.
+- Чтение не меняет состояние; изменения подтверждаются явно; удаление репозитория, его
+  перенос и удаление организации отклоняются сразу.
+- Клиент никогда не печатает токен, а любая ошибка возвращается значением
+  (`ok: false` с `status`, `code`, `rateLimit`), а не исключением.
+
+## План
+
+Блокеры релиза, по порядку:
+
+1. **Паритет** — `pr_create`, `pr_update`, `pr_merge`, `gh_review`, `review_post`,
+   `gh_issue`, `issue_open`, `issue_comment`, `issue_close`, `gh_search`,
+   `gh_repo_search`, `gh_repo`, `gh_file`, `gh_checks`, `ci_run`.
+2. **Зеркало** — `gh_mirror_check`, `gh_mirror_publish`: санитизированное дерево продукта
+   (allowlist из `package.json → files`), один коммит поверх зеркальной ветки,
+   fast-forward, никогда не force.
+3. **Запуски workflow** — `gh_run_list/view/rerun/cancel/logs`.
+4. **Настройки репозитория** — секреты, переменные, rulesets, защита веток,
+   `gh_repo_create`, `gh_repo_edit`.
+5. Карточка настроек на странице плагинов, локали `en`/`zh`, дизайн-контракт.
+
+## Разработка
+
+```bash
+npm test        # node --test, без харнесса и без сети: fetch подменяется
+```
+
+## Лицензия
+
+MIT — см. [LICENSE](LICENSE).

package/README.zh.md

@@ -0,0 +1,151 @@
+# dsh-github-ops
+
+面向 [DeepSeek Harness](https://github.com/topics/dsh-plugin) 的 GitHub 操作插件：发布（release）、
+标签（tag）、受保护的通用 API 直通、工作流运行、密钥，以及经过净化的镜像发布。
+
+插件的存在理由：发布流水线需要现有 GitHub 插件没有提供的能力——首先是 release 和 tag，
+其次是只发布**产品**、而不是整个开发树的 GitHub 镜像。
+
+> **状态：开发中，尚未发布。** 只有在插件具备完整工具集之后才会公开发布（见[路线图](#路线图)）。
+
+## 安装
+
+```bash
+dsh plugin --profile web add @goodandready/dsh-github-ops
+```
+
+需要在 DSH 凭据服务中保存 GitHub token。默认凭据名为 `GITHUB_TOKEN`，插件设置里只保存
+这个**名称**。
+
+## 设置
+
+| 设置 | 默认值 | 含义 |
+|---|---|---|
+| `tokenEnv` | `GITHUB_TOKEN` | 依次在 DSH 凭据、环境变量与 `gh` CLI 中查找该名称；取值本身不写入设置。 |
+| `tokenSource` | `auto` | 访问来源：`auto` 依次尝试 DSH 凭据、环境变量与 `gh` CLI 会话；可固定为 `credentials`、`env` 或 `gh`。 |
+| `defaultRepository` | 空 | 未传 `repository` 时使用的 `owner/repo`。 |
+| `baseUrl` | `https://api.github.com` | API 地址，GitHub Enterprise 时修改。 |
+| `timeoutMs` | `30000` | 单次请求超时。 |
+| `maxRetries` | `2` | 读取失败时的重试次数（写入不重试）。 |
+| `reviewRulesJson` | 空 | 以 JSON 覆盖评审规则：`sensitivePaths`、`sensitiveSeverity`、`attentionPaths`、`migrationPaths`、`testsRequired`、`sourcePatterns`、`testPatterns`、`largeDiffLines`。 |
+| `allowedActions` | 全部 | 允许执行的写操作；其余一律拒绝，且每个都会询问确认。 |
+| `autoApprove` | 空 | 非交互运行（`DSH_GITHUB_OPS_UNATTENDED=1`）可免除询问的操作；破坏性操作永远不会被自动批准。 |
+| `reviewJobTimeoutMs` | `120000` | 后台评审任务的最长运行时间。 |
+
+## 工具
+
+### Release
+
+| 工具 | 作用 |
+|---|---|
+| `gh_release_list` | 按时间倒序列出 release（只读）。 |
+| `gh_release_view` | 按 tag 读取单个 release：标记、说明、附件（只读）。 |
+| `gh_release_create` | 为 tag 创建 release，可指定 commit。 |
+| `gh_release_edit` | 修改标题、说明、draft/prerelease，以及**哪个 release 是 latest**。 |
+| `gh_release_delete` | 删除 release（需要 `confirm: true`）。 |
+
+`gh_release_edit` 配合 `makeLatest: true` 是保持仓库徽章指向当前版本的关键一步：之后再创建
+旧版本的 release 会把 “Latest” 移回旧版本。
+
+### Tag
+
+| 工具 | 作用 |
+|---|---|
+| `gh_tag_list` | 列出 tag 及其 commit SHA（只读）。 |
+| `gh_tag_create` | 创建 tag；带 `message` 时创建附带注释的 tag。 |
+| `gh_tag_delete` | 删除 tag（需要 `confirm: true`）。 |
+
+### 通用 API
+
+`gh_api` 用于覆盖类型化工具未涉及的接口（refs、rulesets、organization、gist）。读取无需确认；
+`POST`/`PATCH`/`PUT`/`DELETE` 需要 `confirm: true`。删除仓库、转移仓库、删除组织会被直接拒绝——
+这类操作无法靠一次确认变得安全。
+
+### Issue 与 Pull Request
+
+| 工具 | 作用 |
+|---|---|
+| `gh_issue` | 列出或读取 issue（`action: list/get/comments`）；PR 以 `kind: "pr"` 返回。 |
+| `issue_open`、`issue_comment`、`issue_close` | 创建 issue、评论、关闭（可带原因）。 |
+| `gh_search` | 使用 GitHub 搜索语法检索 issue 与 PR（独立配额）。 |
+| `pr_create`、`pr_update` | 从 head 分支创建 PR；修改标题、正文、状态或目标分支。 |
+| `pr_merge` | 合并 PR（merge/squash/rebase），可选择删除 head 分支。 |
+| `gh_review` | 一个完整评审包：元数据、涉及范围、限量 diff、评论、CI 汇总与确定性发现（密钥、迁移、CI 配置、改源码未改测试、超大 diff）。 |
+| `review_post` | 发布评审：一条汇总评论，或按行内联评论。 |
+| `gh_checks` | 某个提交的 check runs、旧式状态与统一结论。 |
+| `ci_run` | 对 PR 做一次性评审并给出基于规则的结论。 |
+
+### 镜像发布
+
+| 工具 | 作用 |
+|---|---|
+| `gh_mirror_check` | 只读计划：哪些产品文件会进入镜像、多少文件会留在原地、以及为何必须拒绝发布。 |
+| `gh_mirror_publish` | 发布净化后的树：在镜像分支之上一个提交，fast-forward，**绝不 force**。`dryRun: true` 仅预览；写入需要 `confirm: true`。 |
+
+白名单取自包清单自身的 `files`，加上 `.gitignore`、`LICENSE`、README 三件套、
+`CHANGELOG.md` 和 `cordis.patch.yml`。即使清单里列了 `docs/**` 与代理说明文件也会被禁止；
+像 `scripts/**` 这种随包发布的工具则会进入镜像，因为它属于包内容。
+
+### 工作流运行
+
+| 工具 | 作用 |
+|---|---|
+| `gh_run_list`、`gh_run_view` | 列出运行（可按分支、工作流、状态过滤）与读取单个运行。 |
+| `gh_run_jobs` | 作业及其步骤，并单独列出失败的步骤——通常足以定位失败原因。 |
+| `gh_run_rerun`、`gh_run_cancel` | 重跑全部或仅失败作业；取消进行中的运行（需要 `confirm: true`）。 |
+| `gh_run_logs` | 返回日志压缩包地址：GitHub 以 302 指向 zip，不会把二进制拉进对话。 |
+
+### 仓库设置
+
+| 工具 | 作用 |
+|---|---|
+| `gh_variable_list/set/delete` | Actions 变量，仓库级或按环境。 |
+| `gh_secret_list/set/delete` | Actions 密钥。写入使用 sealed-box 加密，需要可选的 `tweetnacl`；缺失时会明确说明需要安装什么，而不是写入无效值。 |
+| `gh_ruleset_list/view/apply/delete` | 仓库 ruleset：读取、创建、更新、删除。 |
+| `gh_branch_protection_get/set/delete` | 经典分支保护：必需评审、状态检查、管理员强制、force push 与删除开关。 |
+
+### 插件设置卡片
+
+设置在插件自己的页面上（插件列表座位 `plugins.item`，并保留行座位与旧版
+`settings.plugin.item`）：凭据名称、默认仓库、API 地址、请求超时。卡片会检查设置快照的
+**状态**，在设置服务不可用时明确说明，而不是画出一个看似可用的表单。
+
+## 后台评审与斜杠命令
+
+`gh_review_job` 立即返回任务 id，`gh_review_job_status` 读取结果。宿主提供任务注册表时，
+任务可在界面中查看与取消；否则在插件内部运行。
+
+斜杠命令是人类的快捷入口：`/pr create [title]`、`/review [number]`、
+`/issue new <title> | list | show <number>`、`/gh [分组|工具]`。命令本身**不会**写入 GitHub，
+只是把指令交给模型，因此写入仍然经过审批关卡。
+
+## 安全边界
+
+- token 只存在于 DSH 凭据服务，设置中只有名称；
+- 读取操作不改变状态，写入必须显式确认；删除仓库、转移仓库、删除组织会被直接拒绝；
+- 客户端不会输出 token，失败以返回值形式报告（`ok: false` 及 `status`、`code`、`rateLimit`），
+  不会中断整个回合；
+- `gh_review` 的发现是确定性规则：指出需要关注的地方，绝不冒充正确性结论。
+
+## 路线图
+
+按顺序的发布阻塞项：
+
+1. **功能对齐** —— `pr_create`、`pr_update`、`pr_merge`、`gh_review`、`review_post`、
+   `gh_issue`、`issue_open`、`issue_comment`、`issue_close`、`gh_search`、
+   `gh_repo_search`、`gh_repo`、`gh_file`、`gh_checks`、`ci_run`。
+2. **镜像** —— `gh_mirror_check`、`gh_mirror_publish`：净化后的产品树（白名单取自
+   `package.json → files`），在镜像分支之上一个提交，fast-forward，绝不 force。
+3. **工作流运行** —— `gh_run_list/view/rerun/cancel/logs`。
+4. **仓库设置** —— secrets、variables、rulesets、分支保护、`gh_repo_create`、`gh_repo_edit`。
+5. 插件页设置卡片、`en`/`zh` 语言包、设计契约。
+
+## 开发
+
+```bash
+npm test        # node --test，不需要 harness，也不访问网络：fetch 是注入的
+```
+
+## 许可证
+
+MIT —— 见 [LICENSE](LICENSE)。

package/cordis.patch.yml

@@ -0,0 +1,3 @@
+- insert:
+    - id: dsh-github-ops
+      name: '@goodandready/dsh-github-ops'