dsh-plugin-discourse 1.0.0 → 1.1.0

package/README.md

@@ -1,10 +1,14 @@
 # dsh-plugin-discourse
 
+[![npm](https://img.shields.io/npm/v/dsh-plugin-discourse.svg)](https://www.npmjs.com/package/dsh-plugin-discourse)
+[![Publish to npm](https://github.com/AkarinLiu/dsh-plugin-discourse/actions/workflows/publish.yml/badge.svg)](https://github.com/AkarinLiu/dsh-plugin-discourse/actions/workflows/publish.yml)
+
 Discourse administration and agent tools for the [DeepSeek Harness](https://github.com/deepseek-ai).
 
-One Host plugin registers 16 model-facing tools over the Discourse REST API: an agent can search a
-forum, read topics and profiles, publish posts, and carry out the moderator and administrator work a
-staff account would do in the web UI.
+One Host plugin registers 17 model-facing tools over the Discourse REST API: an agent can search a
+forum, read topics and profiles, publish posts, carry out the moderator and administrator work a
+staff account would do in the web UI, and sign in through the user's browser with a scoped user API
+key.
 
 ```
 User → DSH agent → discourse_* tools → Discourse REST API → forum
@@ -14,6 +18,7 @@ User → DSH agent → discourse_* tools → Discourse REST API → forum
 
 | Tool | Group | What it does | Key needed |
 |---|---|---|---|
+| `discourse_login` | auth | Start browser authorization, report the session, finish an older payload page, cancel a pending attempt, or sign out | no |
 | `discourse_search` | read | Search topics, posts, and users | no |
 | `discourse_topics` | read | List a feed (`latest`/`new`/`unread`/`top`) or one category | no |
 | `discourse_topic` | read | Read a topic and a slice of its posts | no |
@@ -37,27 +42,62 @@ thread search never floods the model context. Results keep ids, so a follow-up c
 ## Install
 
 The bundle is a profile plugin: it is installed into one DSH profile and selected in that profile's
-bundle list.
+bundle list. Install it through the Web UI when you can: DSH's bundle installer replaces an existing
+copy or local link before it writes the package, while the CLI is a thin pnpm wrapper.
 
-**From the Web UI** — open *Settings → Plugins → Install bundle* and give it the package directory
-(for a clone) or a package spec such as `github:AkarinLiu/dsh-plugin-discourse`. DSH installs the
-package, adds it to the profile's bundle list, and activates it.
+**From the Web UI (recommended)** — open *Settings → Plugins → Install bundle* and enter
+`dsh-plugin-discourse` for the npm package, or `github:AkarinLiu/dsh-plugin-discourse`, or a local
+clone path. DSH installs the package, adds it to the profile's bundle list, and activates it.
 
-**From the CLI** — the launcher passes everything after `plugin` to pnpm:
+**From npm on the CLI** — the launcher passes everything after `plugin` to pnpm, so this is a plain
+pnpm install rather than the bundle installer:
 
 ```bash
-gh repo clone AkarinLiu/dsh-plugin-discourse
-dsh plugin --profile desktop add ./dsh-plugin-discourse
+dsh plugin --profile desktop add dsh-plugin-discourse
 ```
 
-That installs the package; select `dsh-plugin-discourse` once in the Plugins page (or through the
+After a CLI install, select `dsh-plugin-discourse` once in the Plugins page (or through the
 `plugin_manager` tool) so the profile records it as a bundle.
 
+**From a clone** — `gh repo clone AkarinLiu/dsh-plugin-discourse`, then
+`dsh plugin --profile desktop add ./dsh-plugin-discourse`. On Windows this creates a directory
+junction in the profile; read the next section before moving that profile to the npm package.
+
 To remove it, uninstall the bundle from the Plugins page, which drops the dependency and the bundle
 entry together.
 
 > The plugin is Host-only: no build step, no dependencies, no client assets.
 
+### Windows: EPERM when replacing a local link
+
+A clone install leaves `node_modules\dsh-plugin-discourse` as a directory junction. pnpm's hoisted
+linker does not always record or prune that junction, so a later npm install cannot replace it and
+Windows refuses the rename:
+
+```text
+[ERR_PNPM_EPERM] [importPackage ...\node_modules\dsh-plugin-discourse]
+EPERM: operation not permitted, rename '...dsh-plugin-discourse_tmp_...' -> '...dsh-plugin-discourse'
+```
+
+The checkout is untouched; only the link is stale. From a clone of this repository, let the bundled
+doctor remove the link and then reinstall:
+
+```bash
+node scripts/doctor.mjs --profile desktop --fix
+dsh plugin --profile desktop add dsh-plugin-discourse
+```
+
+Or delete the junction by hand and retry:
+
+```powershell
+$link = "$env:USERPROFILE\.dsh\profiles\desktop\node_modules\dsh-plugin-discourse"
+if ((Get-Item $link -Force -ErrorAction SilentlyContinue).LinkType -eq 'Junction') {
+  (Get-Item $link -Force).Delete()
+}
+```
+
+Restart the Harness after the package is replaced so the new module generation loads.
+
 ## Configure
 
 The bundle ships its defaults in `cordis.patch.yml`, which DSH applies as the bundle layer. To point
@@ -73,6 +113,11 @@ it at your forum, add an override to your **profile's** `cordis.patch.yml` (`$DS
     readOnly: true
     timeoutMs: 20000
     maxItems: 12
+    authMode: auto
+    loginScopes: read,write,session_info
+    loginClientId: dsh-plugin-discourse
+    loginApplicationName: DeepSeek Harness
+    loginTimeoutMs: 600000
 ```
 
 A loader override replaces the row's `config` wholesale, so restate every key you want to keep.
@@ -85,6 +130,11 @@ A loader override replaces the row's `config` wholesale, so restate every key yo
 | `readOnly` | `false` | Blocks every mutating tool when `true`. |
 | `timeoutMs` | `20000` | Per-request deadline, 1000–120000. |
 | `maxItems` | `12` | Default listing size, 1–50. |
+| `authMode` | `auto` | `auto` uses a stored browser session for normal calls and `apiKey` for staff/admin calls; `api-key` ignores the session; `user` requires it for every call. |
+| `loginScopes` | `read,write,session_info` | Comma-separated scopes requested by browser sign-in. Narrow or extend this to match the forum's `allow_user_api_key_scopes`. |
+| `loginClientId` | `dsh-plugin-discourse` | Client id Discourse records with the authorized key. |
+| `loginApplicationName` | `DeepSeek Harness` | Application name shown on the forum authorization page. |
+| `loginTimeoutMs` | `600000` | Browser sign-in deadline, 30000–1800000. Discourse's device code lives 10 minutes. |
 
 Anonymous reads work out of the box against the default forum, so you can try `discourse_topics`
 before configuring anything.
@@ -106,11 +156,54 @@ export DISCOURSE_API_USERNAME="staff-bot"
 
 Row config wins over the environment when both are present.
 
+### Browser sign-in
+
+`discourse_login` obtains a **user API key** for the signed-in forum account, so the plugin can act as
+that user without an admin key in the profile. On current Discourse releases it uses the device
+authorization flow (`Auth API` version 4):
+
+1. `discourse_login` with `action: "start"` returns a verification URL and an eight-character code.
+2. Open the URL, sign in to the forum if needed, and confirm the code.
+3. `discourse_login` with `action: "status"` reports the signed-in account.
+
+The tool also accepts `waitSeconds` on `status` (0–120) when the caller wants to wait for the browser
+step before reporting. `action: "cancel"` withdraws a pending attempt without touching a stored
+session.
+
+Forums older than the device flow get the classic `/user-api-key/new` page instead. The plugin asks
+for the encrypted payload that page shows after approval, and
+`discourse_login` with `action: "complete"` and the pasted `payload` finishes the sign-in. Neither
+path needs an `auth_redirect`, a callback listener, or a change to
+`allowed_user_api_auth_redirects`.
+
+The authorized key is stored as the `discourse/session` record in the DSH credential store — never in
+`cordis.patch.yml` and never in a tool result. `discourse_login` with `action: "logout"` revokes it at
+the forum when possible and deletes the local record. `readOnly` still permits sign-in and sign-out:
+they manage authentication, not forum content.
+
+`authMode` decides which credential a request uses:
+
+- `auto` (default) — normal reads and posts use the stored session; staff/admin tools keep using
+  `apiKey` when one is configured, so moderation and administration still work.
+- `api-key` — ignore any stored session and always use `apiKey`.
+- `user` — require the stored session for every call; requests fail with a sign-in hint when it is
+  missing or expired.
+
+A user API key is limited to the account's own permissions and the scopes granted on the consent
+page. It cannot call admin endpoints such as `/admin/users.json`; those tools need `apiKey` (or fail
+with the forum's 403). A forum that does not allow `write` in `allow_user_api_key_scopes` needs
+`loginScopes: read,session_info`.
+
 ## Safety
 
-- `readOnly: true` is enforced inside the plugin, before any mutating request is built.
+- `readOnly: true` blocks every content-mutating tool before any forum request is built. Browser
+  sign-in and sign-out remain available because they manage the credential rather than content.
+- `discourse_login` stores the user API key in the credential store and never prints it. Use
+  `action: "logout"` to revoke it at the forum and remove the local record.
 - `discourse_moderate_user` and the site-settings tools require an admin-scoped key; a key without
-  those scopes receives the forum's 403 response, and the tool reports it instead of retrying.
+  those scopes receives the forum's 403 response, and the tool reports it instead of retrying. A
+  browser session does not widen a user key into an admin key; `authMode: auto` therefore prefers a
+  configured `apiKey` for staff and admin calls.
 - Failures carry the HTTP status and Discourse's own error text, so a wrong id or a missing scope is
   visible in the transcript.
 - Writes should be exercised with a staging forum first — `discourse_delete_post` with
@@ -121,22 +214,72 @@ Row config wins over the environment when both are present.
 The package is plain ESM with no runtime dependencies; `index.js` is the whole plugin.
 
 ```bash
-node --check index.js          # syntax
-node scripts/smoke.mjs         # register every tool and validate definitions offline
-node scripts/smoke.mjs --live  # additionally call read-only tools against the configured forum
+node --check index.js                          # syntax
+npm test                                      # register every tool, validate definitions, and exercise browser login offline
+node scripts/smoke.mjs --live                 # additionally call read-only tools against the forum
+node scripts/login-test.mjs                   # browser login flow against a stubbed forum and credential store
+npm run verify                                # build the npm tarball and check its file list
+node scripts/doctor.mjs --profile desktop     # inspect a profile for a stale local link
 ```
 
 `scripts/smoke.mjs` drives `apply()` with a stub context, so it exercises the real registration path
-without starting a Harness.
+without starting a Harness. `scripts/login-test.mjs` drives the same `apply()` path with a stub
+credential store, authorization seam, and forum: it starts the classic page, completes it with an RSA
+payload, reads the status, and signs out, then repeats the device-code path. `scripts/verify-package.mjs`
+packs the package with `npm pack` and fails when a runtime file is missing from `files`, when the
+manifest loses `dsh.bundle`, or when a locale loses its display metadata. `prepack` runs the smoke and
+login tests, so a broken package cannot be published.
+
+## Release
+
+Releases are automated by [`.github/workflows/publish.yml`](.github/workflows/publish.yml): every
+push to `main` or a `v*` tag, and every pull request, verifies the package, and a `v*` tag publishes it to
+[npmjs.com](https://www.npmjs.com/package/dsh-plugin-discourse) with
+[provenance](https://docs.npmjs.com/generating-provenance-statements).
+
+1. Bump `version` in `package.json` (the tag must match it exactly).
+2. Commit, then tag and push:
+
+   ```bash
+   git tag -a v1.1.0 -m "dsh-plugin-discourse 1.1.0"
+   git push origin main --follow-tags
+   ```
+
+3. The workflow runs on Node 24, verifies the tarball, checks `v<version>`, and publishes with
+   `--provenance --access public`.
+
+Before the first release, add a **Trusted Publisher** on npmjs.com (package page → *Settings* →
+*Trusted Publishing* → *GitHub Actions*):
+
+| Field | Value |
+|---|---|
+| Repository | `AkarinLiu/dsh-plugin-discourse` |
+| Workflow file | `publish.yml` |
+| Environment | *(leave empty)* |
+| Allowed action | `npm publish` |
+
+With the trusted publisher in place the workflow needs no long-lived credential: it exchanges the
+GitHub OIDC token (`id-token: write`) for publish rights and attaches provenance. Until that setting
+exists, the publish job falls back to the repository's `NPM_TOKEN` secret, and it fails with a
+diagnostic when neither credential is available. npm now requires an interactive 2FA challenge for
+token and trusted-publisher management, so the one-time setup happens in the browser; after it, tagged
+releases are fully automatic.
 
 ## 中文说明
 
-- 这是一个 **Host 插件**，向 DSH 智能体提供 16 个 Discourse 工具（读取 / 发帖 / 版主 / 管理员）。
-- 安装：在 DSH Web UI 的 *设置 → 插件 → 安装 bundle* 中选择本仓库目录，或填入 `github:AkarinLiu/dsh-plugin-discourse`。
+- 这是一个 **Host 插件**，向 DSH 智能体提供 17 个 Discourse 工具（登录 / 读取 / 发帖 / 版主 / 管理员）。
+- 浏览器授权登录：先调用 `discourse_login`（`action: "start"`），插件会返回论坛授权页地址和 8 位验证码；在浏览器中登录论坛并确认验证码后，再用 `action: "status"` 查看登录结果。中途放弃可用 `action: "cancel"`。新版 Discourse 使用设备授权码流程；旧版论坛会显示加密 payload，把该 payload 交给 `action: "complete"` 即可完成。两种方式都不需要配置 `auth_redirect`，也不需要修改 `allowed_user_api_auth_redirects`。
+- 登录得到的用户 API Key 保存在 DSH 凭据存储的 `discourse/session` 记录中，不会写进 `cordis.patch.yml`，也不会出现在工具结果里；`action: "logout"` 会尽量在论坛撤销它并删除本地记录。
+- `authMode: auto`（默认）下，普通读取和发帖使用已登录的会话，版主/管理员工具继续使用 `apiKey`；改为 `api-key` 可完全忽略会话，改为 `user` 则所有请求都必须先登录。
+- 用户 API Key 只拥有该账号的权限，不能调用 `/admin/*` 管理接口；管理工具仍需 `apiKey`。如果论坛不允许 `write` scope，请把 `loginScopes` 调成 `read,session_info`。
+- 安装：优先用 Web UI 的 *设置 → 插件 → 安装 bundle*，填入 `dsh-plugin-discourse`（npm）或 `github:AkarinLiu/dsh-plugin-discourse`；安装器会先替换旧的本地链接。
+- 命令行：`dsh plugin --profile desktop add dsh-plugin-discourse` 只是把参数转交给 pnpm，安装后还需在插件页选中该 bundle。
+- Windows 从本地克隆切到 npm 时报 `ERR_PNPM_EPERM ... rename ...dsh-plugin-discourse...`：这是 profile 里遗留的目录联接；运行 `node scripts/doctor.mjs --profile desktop --fix` 后再安装（脚本只删链接，不动源码），然后重启 Harness。
+- 发布：推送 `v*` 标签会触发 `.github/workflows/publish.yml`。首次发布前在 npmjs.com 的包设置 → *Trusted Publishing* 添加 GitHub Actions（仓库 `AkarinLiu/dsh-plugin-discourse`、工作流 `publish.yml`、环境留空、允许 `npm publish`），之后不需要 `NPM_TOKEN`，由 OIDC 发布并生成 provenance。
 - 配置：在 profile 的 `cordis.patch.yml` 中加一条 `id: discourse` 的覆盖，把 `baseUrl` 改成你的论坛并填入 `apiKey`（覆盖会整体替换 `config`，请把其它键一并写全）。
-- 不需要 API Key 即可试用只读工具（默认指向 `https://meta.discourse.org`）。
+- 不需要 API Key 即可试用只读工具（默认指向 `https://meta.discourse.org`），也可以直接用浏览器登录获得用户会话。
 - 密钥建议通过环境变量 `DISCOURSE_API_KEY` / `DISCOURSE_API_USERNAME` 提供，避免写进配置文件。
-- 不需要写入权限时把 `readOnly` 设为 `true`，所有写操作会被插件直接拒绝。
+- 不需要写入权限时把 `readOnly` 设为 `true`，所有写操作会被插件直接拒绝；登录和退出仍可使用。
 
 ## License
 

package/cordis.patch.yml

@@ -1,6 +1,7 @@
 # Inserts the Discourse tool bundle into the current DSH profile.
 # Change `baseUrl` to your forum and point `apiKey` at an admin-scoped key
-# before enabling writes.
+# before enabling writes. Browser sign-in stores a scoped user API key in the
+# DSH credential store, so no key is required in this file for `discourse_login`.
 - insert:
     - id: discourse
       name: dsh-plugin-discourse
@@ -11,3 +12,8 @@
         readOnly: false
         timeoutMs: 20000
         maxItems: 12
+        authMode: auto
+        loginScopes: read,write,session_info
+        loginClientId: dsh-plugin-discourse
+        loginApplicationName: DeepSeek Harness
+        loginTimeoutMs: 600000