dsh-plugin-discourse 0.0.0-stage → 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AkarinLiu
+
+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,221 @@
-# Temporary Holding Version
+# dsh-plugin-discourse
 
-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.
+[![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.
+
+```
+User → DSH agent → discourse_* tools → Discourse REST API → forum
+```
+
+## Tools
+
+| Tool | Group | What it does | Key needed |
+|---|---|---|---|
+| `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 |
+| `discourse_categories` | read | List categories and subcategories with ids | no |
+| `discourse_user` | read | Read one profile with roles, trust level, and activity counts | no |
+| `discourse_create_topic` | author | Create a topic with category and tags | yes |
+| `discourse_reply` | author | Reply to a topic, optionally to a specific post | yes |
+| `discourse_update_post` | author | Replace a post body | yes |
+| `discourse_flag_post` | author | Flag a post as spam, inappropriate, or off-topic | yes |
+| `discourse_review_queue` | moderate | List flagged items awaiting a decision | moderator |
+| `discourse_delete_post` | moderate | Delete or permanently destroy a post | moderator |
+| `discourse_restore_post` | moderate | Restore a deleted post | moderator |
+| `discourse_admin_users` | admin | Search the user directory by status and order | admin |
+| `discourse_moderate_user` | admin | Suspend, silence, lift a sanction, or activate an account | admin |
+| `discourse_site_settings` | admin | Read settings, or change one by name | admin |
+| `discourse_admin_stats` | admin | Read a dashboard report as a time series | admin |
+
+Every listing is bounded (12 items by default, 50 maximum) and every post body is clipped, so a
+thread search never floods the model context. Results keep ids, so a follow-up call reads the detail.
+
+## Install
+
+The bundle is a profile plugin: it is installed into one DSH profile and selected in that profile's
+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 (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 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
+dsh plugin --profile desktop add dsh-plugin-discourse
+```
+
+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
+it at your forum, add an override to your **profile's** `cordis.patch.yml` (`$DSH_HOME/profiles/<name>/cordis.patch.yml`):
+
+```yaml
+- id: discourse
+  name: dsh-plugin-discourse
+  config:
+    baseUrl: https://forum.example.com
+    apiKey: ''
+    apiUsername: ''
+    readOnly: true
+    timeoutMs: 20000
+    maxItems: 12
+```
+
+A loader override replaces the row's `config` wholesale, so restate every key you want to keep.
+
+| Key | Default | Meaning |
+|---|---|---|
+| `baseUrl` | `https://meta.discourse.org` | Forum origin. Point this at your own forum. |
+| `apiKey` | `''` | Discourse API key. Empty means anonymous, read-only access. |
+| `apiUsername` | `''` → `system` | Username the key acts as. |
+| `readOnly` | `false` | Blocks every mutating tool when `true`. |
+| `timeoutMs` | `20000` | Per-request deadline, 1000–120000. |
+| `maxItems` | `12` | Default listing size, 1–50. |
+
+Anonymous reads work out of the box against the default forum, so you can try `discourse_topics`
+before configuring anything.
+
+### Credentials
+
+Generate a key in Discourse under *Admin → API → API keys*. Two shapes work:
+
+- **Global key with an admin user** — full tool coverage, including `discourse_admin_*`.
+- **Granular key** — grant only the scopes you want (`topics:write`, `posts:write`, `users:moderate`,
+  and similar). Any tool whose scope is missing fails with the forum's own 403 message.
+
+Rather than storing the secret in YAML, the plugin also reads it from the environment:
+
+```bash
+export DISCOURSE_API_KEY="..."
+export DISCOURSE_API_USERNAME="staff-bot"
+```
+
+Row config wins over the environment when both are present.
+
+## Safety
+
+- `readOnly: true` is enforced inside the plugin, before any mutating request is built.
+- `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.
+- 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
+  `permanent: true` is irreversible.
+
+## Development
+
+The package is plain ESM with no runtime dependencies; `index.js` is the whole plugin.
+
+```bash
+node --check index.js                          # syntax
+npm test                                      # register every tool and validate definitions offline
+node scripts/smoke.mjs --live                 # additionally call read-only tools against the forum
+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. `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 test, 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.0.1 -m "dsh-plugin-discourse 1.0.1"
+   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` |
+
+No `NPM_TOKEN` secret is needed: the workflow exchanges the GitHub OIDC token
+(`id-token: write`) for publish rights and attaches provenance. npm now requires an interactive 2FA
+challenge for token and trusted-publisher management, so this one-time setup happens in the browser;
+after it, tagged releases are fully automatic.
+
+## 中文说明
+
+- 这是一个 **Host 插件**，向 DSH 智能体提供 16 个 Discourse 工具（读取 / 发帖 / 版主 / 管理员）。
+- 安装：优先用 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`）。
+- 密钥建议通过环境变量 `DISCOURSE_API_KEY` / `DISCOURSE_API_USERNAME` 提供，避免写进配置文件。
+- 不需要写入权限时把 `readOnly` 设为 `true`，所有写操作会被插件直接拒绝。
+
+## License
+
+MIT © 2026 AkarinLiu. See [LICENSE](LICENSE).

package/cordis.patch.yml

@@ -0,0 +1,13 @@
+# 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.
+- insert:
+    - id: discourse
+      name: dsh-plugin-discourse
+      config:
+        baseUrl: https://meta.discourse.org
+        apiKey: ''
+        apiUsername: ''
+        readOnly: false
+        timeoutMs: 20000
+        maxItems: 12

package/icon.svg

@@ -0,0 +1,15 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64" width="64" height="64" role="img" aria-label="Discourse forum tools">
+  <defs>
+    <linearGradient id="discourse-bg" x1="0" y1="0" x2="1" y2="1">
+      <stop offset="0" stop-color="#3b5bdb"/>
+      <stop offset="1" stop-color="#0ea5a3"/>
+    </linearGradient>
+  </defs>
+  <rect width="64" height="64" rx="15" fill="url(#discourse-bg)"/>
+  <path d="M17 15h30a6 6 0 0 1 6 6v16a6 6 0 0 1-6 6H31l-10 8v-8h-4a6 6 0 0 1-6-6V21a6 6 0 0 1 6-6z" fill="#ffffff" opacity="0.96"/>
+  <circle cx="23" cy="29" r="2.6" fill="#3b5bdb"/>
+  <circle cx="32" cy="29" r="2.6" fill="#3b5bdb"/>
+  <circle cx="41" cy="29" r="2.6" fill="#3b5bdb"/>
+  <path d="M46 38l7 3v6.5c0 4.2-3 7.6-7 8.5-4-0.9-7-4.3-7-8.5V41l7-3z" fill="#ffffff" opacity="0.96"/>
+  <path d="M43.4 46.4l2.1 2.1 4-4.4" fill="none" stroke="#0ea5a3" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>