dsh-plugin-github-issues 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kanner
+
+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

@@ -1,3 +1,154 @@
-# Temporary Holding Version
+# dsh-plugin-github-issues
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+English | [中文](docs/README.zh.md)
+
+[![ci](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/ci.yml/badge.svg)](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/ci.yml)
+[![release](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/release.yml/badge.svg)](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/release.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-github-issues.svg)](https://www.npmjs.com/package/dsh-plugin-github-issues)
+[![license](https://img.shields.io/npm/l/dsh-plugin-github-issues.svg)](LICENSE)
+
+Adds a GitHub Issues work surface to [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness):
+browse issues from your repositories and Projects v2 boards, read their details, and hand one to the
+agent. A handoff opens a new Session in the matching Workspace and stages the issue as an
+attachment-style card inside the composer; sending turns that card into the issue's task prompt.
+Handed-over issues show which Sessions own them, can be entered, and can be unlinked; one issue may be
+worked in several Sessions.
+
+![The GitHub panel with the fixed cascade toolbar and the detail pane](assets/panel.png)
+
+It is **read-only**: the plugin never writes to GitHub.
+
+## Install
+
+From the npm registry (recommended — the package ships the built Host half and browser bundle):
+
+```sh
+dsh plugin --profile <name> add dsh-plugin-github-issues
+```
+
+Pin a version when you want reproducible profiles:
+
+```sh
+dsh plugin --profile <name> add dsh-plugin-github-issues@0.4.7
+```
+
+Restart the harness afterwards: a profile is composed at startup. Remove it with:
+
+```sh
+dsh plugin --profile <name> remove dsh-plugin-github-issues
+```
+
+From a checkout (a linked install: rebuild and restart after edits):
+
+```sh
+npm install
+npm run build
+dsh plugin --profile <name> add /path/to/dsh-plugin-github-issues
+```
+
+Every [release](https://github.com/ckanner/dsh-plugin-github-issues/releases) also carries a packed
+tarball (`dsh-plugin-github-issues.tgz`), installable by path.
+
+## Requirements
+
+- DSH Desktop with a Web GUI (developed and verified against `0.2.1-rc.3`).
+- A [`gh`](https://cli.github.com/) CLI logged in for the GitHub host you use:
+  `gh auth login`. The token stays in the OS keychain and is never written into this package's config.
+- Projects v2 support additionally needs the `read:project` scope, once:
+
+  ```sh
+  gh auth refresh -h github.com -s read:project
+  ```
+
+  Without it the panel still works; the project picker explains what is missing.
+
+## What you get
+
+| Surface | Where | What |
+|---|---|---|
+| GitHub panel | left rail icon → main panel | organization → project/repository → **milestone** → assignee → state cascade (remembered across restarts) in one fixed toolbar; only the list scrolls, search sits above it, and the detail pane scrolls independently (body, milestone progress, labels, priority, assignees, linked/mentioned PRs with checks and review state) |
+| Issues right column | right sidebar tab | the same filtered issue list beside the Conversation, for drag-and-drop handoff |
+| Composer card | inside the input box | the staged issue: `[GitHub] owner/repo#number ×`. Type extra instructions or nothing; send converts the card into the issue prompt |
+| Linked chip | composer dock under the input | the Session's linked issue: state dot (green open / red closed) + `owner/repo#number`; click for a detail popover, remove to unlink |
+| Handoff actions | issue detail | one-click **enter Session** (latest link), **new Session for this issue**, plus a linked-Session list with per-Session enter/unlink |
+| GitHub settings | Settings → GitHub | `gh` auth status and scopes, handoff behavior, prompt template |
+
+## Use
+
+1. Click the **GitHub** icon in the left rail.
+2. Pick an organization, a Projects v2 board or a repository, then a milestone (when the scope is a
+   repository) and an assignee/state filter. The selection is remembered in the profile's UI state
+   (not in the plugin config).
+3. Click a row for the detail pane. `owner/repo#number` opens GitHub in the browser.
+4. Hand an issue over:
+   - **One-click** in the detail: **Hand to agent** / **New session for this issue** opens a new
+     Session in the matching Workspace with the issue staged inside the composer.
+   - **Drag** a row from the right-column **Issues** tab into the composer: it stages into the current
+     Session.
+   - Type whatever context you want, then send. The card is converted into the issue's task prompt
+     (the template from Settings) plus your text; the issue ↔ Session link is recorded at that moment.
+5. The linked chip appears under the composer. Reopen the issue later to enter that Session, start
+   another one, or unlink it. Unlinking never deletes the Session.
+6. Open the right column from the panel header (**Right column**) or from the right sidebar's own add
+   menu (page type **Issues**).
+
+### Which Session does a handoff use?
+
+- If the issue is already linked: **enter Session** opens the most recent link; the linked-Session list
+  lets you enter any of them.
+- A new handoff picks a Workspace by this priority: the Workspace of the current Session → the
+  Workspace of a Session already linked to the same repository → a Workspace whose directory/title
+  matches the repository name → the Host's current/most-recent Workspace.
+
+### Prompt template
+
+Settings → GitHub → Prompt template. Variables: `{{repo}}`, `{{number}}`, `{{title}}`, `{{url}}`,
+`{{state}}`, `{{milestone}}`, `{{priority}}`, `{{assignees}}`, `{{labels}}`, `{{prs}}`.
+
+## Privacy and tokens
+
+- The token is resolved by the Host process from `gh` and lives only in memory. It never reaches the
+  page, the plugin config, or logs.
+- GitHub requests are made by the Host; the browser only receives view models.
+- Persisted UI state is limited to filter preferences, the prompt template, and issue ↔ Session links,
+  stored at `$DSH_HOME/github-issues/state.json` (mode `0600`).
+- The plugin is read-only toward GitHub.
+
+## Limitations
+
+- Read-only: no comments, label/assignee/state writes.
+- Projects v2 needs `read:project`; priority falls back project field → organization Issue Field →
+  `P0`–`P4` labels. The milestone filter is disabled on a board because Projects v2 item filters have
+  no milestone equivalent.
+- Milestone choices come from the selected repository's full milestone list; in an all-repositories
+  scope they are accumulated from the issues already loaded.
+- The list polls every 60–120 s while visible; use **Refresh** for an immediate update.
+- The detail pane first asks for the body only and lazily loads cross-referenced PRs, so the slow
+  timeline never blocks the pane.
+- Converting the composer card into the prompt intercepts the native send button / Enter, which relies
+  on the composer DOM of the verified DSH version; re-check after a DSH upgrade.
+- Workspace matching for a new handoff is the heuristic priority above, not a fixed mapping.
+
+## Development
+
+```sh
+npm install
+npm run typecheck      # Host + browser halves
+npm test               # node --test (queries, VM mapping, prompt, state, workspace rules)
+npm run test:render    # offline react-dom/server smoke of the panel, dock, sidebar, drop target
+npm run build          # Host (tsc) + browser bundle (esbuild)
+npm run verify:client  # loader contract + slot/Remote registration of the browser bundle
+npm run verify:package # what npm publish would ship (host, client, bundle patch, locale, icon)
+npm run check          # all of the above, in order
+```
+
+## Releases
+
+`ci.yml` runs on every push and pull request. `release.yml` runs on a `v*` tag (or by hand): it repeats
+every CI check, publishes the new version to npm (a repository `NPM_TOKEN` secret, or npm trusted
+publishing), and records a GitHub Release carrying `dsh-plugin-github-issues.tgz`. Maintainer notes:
+[docs/RELEASING.md](https://github.com/ckanner/dsh-plugin-github-issues/blob/main/docs/RELEASING.md).
+
+## License
+
+MIT © Kanner

package/cordis.patch.yml

@@ -0,0 +1,20 @@
+# The dsh-plugin-github-issues bundle patch.
+#
+# One row: the plugin that owns the GitHub Issues panel, the composer dock
+# handoff strip, and the GitHub settings page. `authMode: gh` reuses the
+# already-authenticated `gh` CLI (the token never leaves the Host process and
+# is never written to this file). `stateDir` holds only non-secret UI state.
+#
+# Projects v2 additionally needs `read:project` on the token — the settings page
+# shows the exact one-line command (`gh auth refresh -h github.com -s read:project`)
+# instead of the plugin escalating auth itself.
+
+- insert:
+    - id: github-issues
+      name: 'dsh-plugin-github-issues'
+      config:
+        authMode: gh
+        host: github.com
+        handoffMode: draft
+        pollSeconds: 90
+        stateDir: !!js (process.env.DSH_HOME ?? process.env.HOME + '/.dsh') + '/github-issues'

package/docs/README.zh.md

@@ -0,0 +1,138 @@
+# dsh-plugin-github-issues
+
+[English](../README.md) | 中文
+
+[![ci](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/ci.yml/badge.svg)](https://github.com/ckanner/dsh-plugin-github-issues/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/dsh-plugin-github-issues.svg)](https://www.npmjs.com/package/dsh-plugin-github-issues)
+
+给 [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) 增加一个 GitHub Issue 工作区：
+按组织 / Projects v2 项目 / 仓库浏览 Issue，查看详情，并把 Issue 交给 Agent。交办会在匹配的
+Workspace 里新开一个 Session，并在输入框内以"附件卡片"的形式暂存这个 Issue；点击发送时卡片会
+转成 Issue 的提示词。已交办的 Issue 会显示处理它的 Session，可以进入，也可以解除关联；同一个
+Issue 可以关联多个 Session。
+
+![GitHub 面板：固定筛选栏 + 独立滚动的详情栏](../assets/panel.png)
+
+插件对 GitHub **只读**，不会写入任何内容。
+
+## 安装
+
+从 npm 安装（推荐，包内已带构建好的 Host 半和浏览器 bundle）：
+
+```sh
+dsh plugin --profile <name> add dsh-plugin-github-issues
+```
+
+锁定版本：
+
+```sh
+dsh plugin --profile <name> add dsh-plugin-github-issues@0.4.7
+```
+
+安装后重启 DSH（profile 在启动时组装）。卸载：
+
+```sh
+dsh plugin --profile <name> remove dsh-plugin-github-issues
+```
+
+从源码目录安装（link 方式，改代码后需要重新 build 并重启）：
+
+```sh
+npm install
+npm run build
+dsh plugin --profile <name> add /path/to/dsh-plugin-github-issues
+```
+
+每个 [Release](https://github.com/ckanner/dsh-plugin-github-issues/releases) 也附带打包好的
+`dsh-plugin-github-issues.tgz`，可以通过路径安装。
+
+## 前置条件
+
+- DSH Desktop（Web GUI；开发与验证于 `0.2.1-rc.3`）。
+- 已登录的 `gh` CLI：`gh auth login`。token 留在系统钥匙串，不会写进插件配置。
+- 需要 Projects v2 时一次性补权限：
+
+  ```sh
+  gh auth refresh -h github.com -s read:project
+  ```
+
+  没有该权限时面板照常工作，项目选择器会说明缺什么。
+
+## 功能
+
+| 界面 | 位置 | 内容 |
+|---|---|---|
+| GitHub 面板 | 左侧栏图标 → 主面板 | 组织 → 项目/仓库 → **里程碑** → assignee → 状态 级联筛选（记住上次选择）固定在一行；只有列表滚动，搜索在列表上方固定；详情栏独立滚动（正文、Milestone 进度、标签、优先级、assignee、关联/提及 PR 的 checks 与 review） |
+| Issues 右栏 | 右侧栏页签 | 与对话同屏的同一份筛选列表，用于拖拽交办 |
+| 输入框卡片 | 输入框内部 | 暂存的 Issue：`[GitHub] owner/repo#number ×`。可以补充自己的文字，也可以不写；发送时卡片转成提示词 |
+| 已关联 chip | 输入框下方 dock | 当前 Session 关联的 Issue：状态圆点（open 绿 / closed 红）+ `owner/repo#number`；点击看详情，× 解除关联 |
+| 交办操作 | Issue 详情 | 一键「进入 Session」（最新关联）、「再开一个 Session」；处理中的 Session 列表里每一项都能进入或解除 |
+| GitHub 设置 | 设置 → GitHub | `gh` 登录状态与权限、交办行为、Prompt 模板 |
+
+## 使用
+
+1. 点击左侧栏 **GitHub** 图标。
+2. 选择组织、Projects v2 板或仓库，再选里程碑（仓库范围时）和 assignee/状态。选择会记在 profile
+   的 UI 状态里（不在插件配置中）。
+3. 点一行查看详情；点 `owner/repo#number` 在浏览器打开 GitHub。
+4. 交办：
+   - 详情里点「交给 Agent」/「再开一个 Session」：在匹配的 Workspace 新开 Session，输入框内出现
+     Issue 卡片；
+   - 从右栏 **Issues** 页签拖一行到输入框：暂存到**当前** Session；
+   - 输入想补充的内容（可不填）后发送：卡片转成 Issue 提示词（模板来自设置）+ 你输入的内容，
+     同时记录 Issue ↔ Session 关联；
+5. 输入框下方出现已关联 chip。之后可以进入那个 Session、再开一个，或解除关联（解除不会删除
+   Session）。
+6. 右栏可以从面板右上角「右栏」按钮打开，也可以在右侧栏自己的添加菜单里选 **Issues** 页签。
+
+### 交办会去哪个 Session？
+
+- 已关联：主按钮进入最新关联的那个；下方 Session 列表可以逐个进入；
+- 新交办选择 Workspace 的优先级：当前 Session 的 Workspace → 已关联同仓库 Session 的 Workspace →
+  目录名/标题与仓库名匹配的 Workspace → Host 当前/最近 Workspace。
+
+### Prompt 模板
+
+设置 → GitHub → Prompt 模板。变量：`{{repo}}`、`{{number}}`、`{{title}}`、`{{url}}`、`{{state}}`、
+`{{milestone}}`、`{{priority}}`、`{{assignees}}`、`{{labels}}`、`{{prs}}`。
+
+## 隐私与 token
+
+- token 由 Host 进程从 `gh` 读取，只在内存中复用；不进页面、不进插件配置、不进日志。
+- GitHub 请求都在 Host 完成，浏览器只拿到视图模型。
+- 落盘的只有筛选偏好、Prompt 模板和 Issue ↔ Session 关联，位于
+  `$DSH_HOME/github-issues/state.json`（权限 `0600`）。
+
+## 限制
+
+- 只读：不发评论、不改标签/指派/状态。
+- Projects v2 需要 `read:project`；优先级回退顺序：项目字段 → 组织 Issue Field → `P0`–`P4` 标签。
+  Projects v2 的条目筛选没有里程碑等价物，因此选中项目板时里程碑筛选会禁用。
+- 里程碑的可选项：选中仓库时取该仓库的完整里程碑列表；全部仓库范围时从已加载的 Issue 中累积。
+- 列表可见时每 60–120 秒轮询一次；需要立刻更新点「刷新」。
+- 详情先请求正文，交叉引用 PR 懒加载，慢的 timeline 不阻塞面板。
+- "发送时卡片转提示词"依赖 composer 的 DOM（原生发送按钮 / 回车），DSH 升级后需要重新核对。
+- 新交办的 Workspace 匹配是上面的启发式优先级，不是固定映射。
+
+## 开发
+
+```sh
+npm install
+npm run typecheck
+npm test               # node --test（查询、VM 映射、prompt、状态、workspace 规则）
+npm run test:render    # 离线 react-dom/server 渲染烟测
+npm run build          # Host (tsc) + 浏览器 bundle (esbuild)
+npm run verify:client  # bundle 的加载契约与槽位/Remote 注册
+npm run verify:package # npm publish 实际会带上的文件
+npm run check          # 以上全部
+```
+
+## 发布
+
+`ci.yml` 在 push / PR 时运行；`release.yml` 在 `v*` tag（或手动）时运行：重复所有检查、发布 npm
+（仓库 `NPM_TOKEN` secret 或 npm trusted publishing），并创建携带 `dsh-plugin-github-issues.tgz`
+的 GitHub Release。维护者说明见 [RELEASING.md](https://github.com/ckanner/dsh-plugin-github-issues/blob/main/docs/RELEASING.md)。
+
+## License
+
+MIT © Kanner

package/icon.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="GitHub Issues">
+  <rect x="2" y="2" width="60" height="60" rx="14" fill="#1f6feb"/>
+  <circle cx="24" cy="22" r="7" fill="none" stroke="#ffffff" stroke-width="4"/>
+  <circle cx="24" cy="22" r="2.5" fill="#ffffff"/>
+  <path d="M24 29v13a6 6 0 0 0 6 6h9" fill="none" stroke="#ffffff" stroke-width="4" stroke-linecap="round"/>
+  <circle cx="44" cy="48" r="4.5" fill="#ffffff"/>
+  <path d="M44 34v9" fill="none" stroke="#ffffff" stroke-width="4" stroke-linecap="round"/>
+  <circle cx="44" cy="31" r="4" fill="none" stroke="#ffffff" stroke-width="3.5"/>
+</svg>