dsh-github-router 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -5,7 +5,25 @@ All notable changes to this project are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
+## [0.3.0] - 2026-08-28
+
+### Changed
+
+- Adapted to DeepSeek Harness 0.1.2-alpha.1
+
+## [0.2.1] - 2026-08-28
+
+### Changed
+
+- Declare compatibility for dsh 0.1.1-rc.2
+
+## [0.2.0] - 2026-08-21
+
+### Changed
+
+- **Migrated plugin configuration to the framework's plugin-settings mechanism** (requires DSH ≥ 0.1.0-rc.7, which serves every registered settings namespace and dispatches plugin-owned configuration cards). The browser half now registers a `settings.plugin.item` card keyed by the `dsh-github-router` namespace inside Settings → Plugins, bound through `ctx.settingsScope` (shared describe mirror, revision fencing, recovery reads, reconnect invalidation); the plugin-owned `/dsh-github-router/config` web routes and the standalone `settings.section` page are removed. The Host keeps the same `settings.register` seam and adds `applies: 'live'`.
+- The token control is now a true write-only field: the configured state comes from the describe mirror's secret slot list (badge: "已配置/configured"), a typed value writes the token, and a blank save clears a configured one.
+- Runtime requirements: the settings card needs DSH ≥ 0.1.0-rc.7; the Host-side settings seam alone still works on older compositions (tools resolve the composition config as before).
 
 ## [0.1.0] - 2026-08-19
 

package/README.md

@@ -46,6 +46,15 @@ dsh plugin --profile web add github:<owner>/dsh-github-router
 
 Then **restart the DSH backend** — the host composition loads at process start. The tools appear in new sessions: `github_probe`, `github_pr`, `github_issue`, `github_file`, `github_api`, plus the `github-router` skill.
 
+## Compatibility
+
+Choose the plugin version that matches your DeepSeek Harness release:
+
+| DeepSeek Harness | Install |
+| --- | --- |
+| 0.1.1 or earlier | `dsh-github-router@0.2.1` |
+| 0.1.2-alpha or later | the latest `dsh-github-router` |
+
 ## Usage
 
 Agent side:
@@ -76,13 +85,14 @@ Behavior notes:
 
 ## Configuration
 
-Settings → **GitHub Router** opens an independent settings page (a nav
-entry registered into `settings.section`, the same mechanism as the 通知
-section): edits are staged locally and written only on save, fields
-overridden by the user are badged, and blank fields fall back to the
-defaults below. The same values can be set in the composition (profile
-`cordis.patch.yml`) as the plugin's base config; the Settings UI overrides
-per user.
+Settings → **Plugins** shows the **GitHub Router** card on the configurable
+tab (the framework's `settings.plugin.item` card slot keyed by the settings
+namespace; requires DSH ≥ 0.1.0-rc.7): edits are staged locally and written
+only on save, fields overridden by the user are badged, and blank fields
+fall back to the defaults below. The token is a write-only field — a blank
+save clears a configured token. The same values can be set in the
+composition (profile `cordis.patch.yml`) as the plugin's base config; the
+Settings UI overrides per user.
 
 | Field | Default | Meaning |
 | --- | --- | --- |
@@ -112,8 +122,8 @@ per user.
 | Path | Purpose |
 | ---- | ------- |
 | `cordis.patch.yml` | Profile patch layer inserting the `dsh-github-router` row |
-| `lib/index.js` | Host plugin: settings section, five tools, skill, guidance |
-| `lib/client.js` | Browser half: the independent Settings page (hand-written factory bundle, no build step) |
+| `lib/index.js` | Host plugin: settings namespace, five tools, skill, guidance |
+| `lib/client.js` | Browser half: the settings card (hand-written factory bundle, no build step) |
 | `lib/config.js` | Settings schema, defaults, runtime option resolution |
 | `lib/net.js`, `lib/tunnel.js` | Route-aware HTTP layer; zero-dependency CONNECT proxy tunnel |
 | `lib/routes/` | One module per route: `api` (GET-only REST), `gh` (CLI), `git` (protocol), `html` (page parse), `mirror` (raw mirrors) |

package/README.zh.md

@@ -15,7 +15,7 @@
 - **一次调用、结构化结果** —— PR 一次返回元数据、讨论、评审、提交、变更文件与 diff，每个部件标注来源路由；失败时返回路由矩阵，而不是十几条重试过的终端命令。
 - **连通性探针** —— `github_probe` 一次调用报告宿主侧哪些路由存活，附耗时与推荐路由链。
 - **零运行时依赖** —— peer 依赖由 DSH profile 解析；代理请求走插件自带的 CONNECT 隧道（不依赖第三方 HTTP 栈），因此可以完全离线安装。
-- **独立设置页** —— 设置中出现独立的「GitHub 路由」入口（与「通知」同机制）：`dsh-github-router` 设置命名空间（secret token、代理、路由开关、缓存 TTL、字节上限），编辑暂存、保存/放弃、覆盖徽标。
+- **框架级插件设置卡片** —— 设置 → **Plugins（插件）** 的可配置页中出现「GitHub 路由」卡片（框架的 `settings.plugin.item` 机制，按设置命名空间配对，需 DSH ≥ 0.1.0-rc.7）：`dsh-github-router` 设置命名空间（secret token、代理、路由开关、缓存 TTL、字节上限），编辑暂存、保存/放弃、覆盖徽标、token 已配置徽标。
 - **上下文效率** —— 按类别 TTL 的响应缓存、全局字节上限、带截断注记的列表上限，以及限流余量提示。
 
 ## 环境要求
@@ -48,6 +48,15 @@ dsh plugin --profile web add github:<owner>/dsh-github-router
 `github_probe`、`github_pr`、`github_issue`、`github_file`、`github_api`，
 以及 `github-router` 技能。
 
+## 兼容性
+
+请选择与你的 DeepSeek Harness 版本匹配的插件版本：
+
+| DeepSeek Harness | 安装 |
+| --- | --- |
+| 0.1.1 及更早 | `dsh-github-router@0.2.1` |
+| 0.1.2-alpha 及更新 | 最新版 `dsh-github-router` |
+
 ## 使用
 
 Agent 侧：
@@ -78,11 +87,12 @@ github_api { path: "/repos/o/r/commits", query: { per_page: 5 } }
 
 ## 配置
 
-设置 → **GitHub 路由** 打开独立设置页（注册进 `settings.section` 的导航
-入口，与「通知」区块同机制）：编辑内容先本地暂存、点保存才落盘，被用户
-覆盖的字段带标记，留空字段回退到下方默认值。同样的值也可以在组合
-（profile 的 `cordis.patch.yml`）中作为插件基础配置写入；设置 UI 按用户
-覆盖。
+设置 → **Plugins（插件）** → 可配置页中的「GitHub 路由」卡片（注册进
+`settings.plugin.item` 槽、以设置命名空间为 key 的框架插件卡片，需要
+DSH ≥ 0.1.0-rc.7）：编辑内容先本地暂存、点保存才落盘，被用户覆盖的
+字段带标记，留空字段回退到下方默认值；token 为只写字段，留空保存会
+清除已配置的 token。同样的值也可以在组合（profile 的
+`cordis.patch.yml`）中作为插件基础配置写入；设置 UI 按用户覆盖。
 
 | 字段 | 默认 | 含义 |
 | --- | --- | --- |

package/docs/design.md

@@ -107,44 +107,50 @@ substitute bytes. When enabled, each configured base yields two candidates
 per file (raw passthrough and the `github.com` `/raw/` route), tried in
 order.
 
-## Settings page
+## Settings card
 
 The Host registers the `dsh-github-router` settings namespace on the
 official settings seam (durable document, schema validation, revision
-fencing); the browser half (`lib/client.js`, a hand-written ModuleLoader
-factory bundle with no build step) registers an INDEPENDENT settings nav
-entry into the `settings.section` slot — the same mechanism
-dsh-notification uses.
-
-### Framework limitation: the settings exposure allowlist
-
-The framework's api-proxy serves settings namespaces to configuration
-clients ONLY through its hardcoded allowlist (`WEB_SETTINGS_NAMESPACES` /
-`PRODUCT_SETTINGS_NAMESPACES` / model-provider namespaces in
-`dsh-host-apiproxy`) — a third-party namespace answers
-`settings-not-exposed` on both reads and writes even when registered, and
-the browser `settingsScope` therefore reports it `unavailable`. Exposing a
-namespace from `settings.register()` is explicitly deferred framework
-work.
-
-### Plugin-owned configuration routes
-
-The channel is the dsh-market pattern: the Host mounts its own routes on
-the shared web server (`ctx.webServer.register`, prefix
-`/dsh-github-router`) and the browser page talks to them with plain
-same-origin fetch — no typert, no gateway, no allowlist. The routes are
-backed by the SAME settings seam (`lib/remote.js`): GET returns a redacted
-view (`value`/`base`/`user`/`revision`/`writable`, secrets stripped); POST
-applies single-field `set`/`unset` ops with revision fencing (conflicts
-answer 409 and the client reloads the view); writes require same-origin
-POSTs and are body-capped. The page's row activates on the
-notification-proven service set (`slots`, `locale`).
-
-Because the routes write **scalar fields by name**, the settings schema
-is deliberately flat (`routesApi`, `cacheTtlMeta`, …); the Host projects
-it into the nested runtime shape (`routes.api`, `cacheTtlSeconds.meta`) in
+fencing, `applies: 'live'`). The browser half (`lib/client.js`, a
+hand-written ModuleLoader factory bundle with no build step) registers one
+plugin configuration CARD into the `settings.plugin.item` slot keyed by the
+namespace — the framework's mechanism for plugins distributed outside the
+repository (DSH ≥ 0.1.0-rc.7): the Settings → Plugins configurable tab
+reads which namespaces the Host serves and dispatches the intersection of
+that ledger and the registered cards, so the card appears only when the
+namespace is registered and served.
+
+### Framework transport
+
+Since DSH 0.1.0-rc.7 the api-proxy serves every registered settings
+namespace (the earlier `WEB_SETTINGS_NAMESPACES` allowlist and its
+`settings-not-exposed` answer retired in PR #2404), so the card binds the
+namespace through the framework settings transport:
+`ctx.settingsScope.bind({ namespace })` returns a `SettingsScope` whose
+snapshot carries the redacted resolved section
+(`status`/`value`/`base`/`user`/`revision`/`writable`). All consumers
+derive from one shared describe mirror, so reads never block activation,
+writes carry revision fencing and recovery re-reads, and the mirror
+refreshes on `settings/document-updated` and `connection/reset` — a Host
+restart no longer strands the form in a failed state. No plugin-owned HTTP
+route exists.
+
+### Card form
+
+Edits are staged locally and written only on save, one field per
+`scope.set`/`scope.unset`; after each write the card verifies the user
+layer (JSON-shaped deep equality) and keeps drafts that did not land.
+Secret fields never ride a response, so the token control is write-only:
+its configured state comes from the describe mirror's secret slot list
+(the snapshot itself redacts it from every layer), a typed value writes the
+token through `settings.mutate` (the one direction secrets cross the wire),
+and a blank draft clears a configured one.
+
+Because the scope writes **scalar fields by name**, the settings schema is
+deliberately flat (`routesApi`, `cacheTtlMeta`, …); the Host projects it
+into the nested runtime shape (`routes.api`, `cacheTtlSeconds.meta`) in
 `resolveOptions`. The composition layer can still carry the same flat
-keys. The page shows the common fields up top (token, proxy, main route
+keys. The card shows the common fields up top (token, proxy, main route
 switches) and the long tail (timeouts, retries, cache TTLs, mirrors,
 repos, git cache dir) in a collapsed "Advanced settings" disclosure.
 

package/lib/client.js

@@ -1,23 +1,28 @@
 /**
  * dsh-github-router — client half (hand-written factory bundle, no build step).
  *
- * One INDEPENDENT settings page (Settings → "GitHub 路由"), registered into
- * the `settings.section` slot exactly like dsh-notification does. The
- * configuration channel is the dsh-market pattern: the Host mounts
- * `/dsh-github-router/config` on the shared web server and this page talks
- * to it with plain same-origin fetch (GET = redacted view, POST = staged
- * writes with revision fencing). Edits are staged locally and written only
- * on save; a rejected write reloads the view so the next save fences
- * correctly.
+ * One plugin configuration CARD inside the framework's Settings → Plugins →
+ * configurable tab, registered into the `settings.plugin.item` slot keyed by
+ * the settings namespace — the framework mechanism for plugins distributed
+ * outside the repository (DSH ≥ 0.1.0-rc.7): the Host registers the
+ * namespace, the browser registers the card under the same key, and the tab
+ * pairs the two. No plugin-owned HTTP route exists anymore; reads and writes
+ * ride the framework settings transport (`ctx.settingsScope`).
  *
- * Layout: the common fields (token, proxy, route switches) sit up top; the
- * long tail (timeouts, retries, cache TTLs, mirrors, repos, git cache dir)
- * lives in a collapsed "Advanced settings" disclosure below.
+ * The form keeps the staged-editing model: edits are staged locally and
+ * written only on save; each write goes through the bound settings scope
+ * (revision fencing, recovery reads on failure) and the card verifies the
+ * user layer afterwards, keeping drafts that did not land. Secret fields
+ * (the GitHub token) never ride a response, so the token control is
+ * write-only: it starts blank, a typed value writes the token, and a blank
+ * draft clears a configured one — the configured state comes from the
+ * describe mirror's secret slot list.
  *
  * The module requires only `react` and
- * `@deepseek-ai/dsh-client-runtime/client` (the browser subpath — the bare
- * package name resolves to the Node half). All copy goes through the
- * framework locale service under the `dsh-github-router` namespace.
+ * `@deepseek-ai/dsh-client-store` (the shared browser snapshot-store seed —
+ * the only runtime API it uses is `createSnapshotStore`). All copy goes
+ * through the framework locale service under the `dsh-github-router`
+ * namespace.
  */
 window.__ModuleLoader__.load({
   id: 'dsh-github-router',
@@ -25,12 +30,12 @@ window.__ModuleLoader__.load({
     var module = { exports: {} };
     var exports = module.exports;
     var React = require('react');
-    var runtime = require('@deepseek-ai/dsh-client-runtime/client');
+    var runtime = require('@deepseek-ai/dsh-client-store');
+
+    var NAMESPACE = 'dsh-github-router';
+    var NS = 'dsh-github-router';
 
     // ------------------------------------------------------------ specs
-    // Flat scalar fields only: the client settings scope writes one field
-    // per call (`scope.set(field, value)`), so nested schema objects are
-    // deliberately absent from this page.
     function textSpec(field) {
       return {
         field: field,
@@ -83,7 +88,7 @@ window.__ModuleLoader__.load({
 
     // ------------------------------------------------------ field catalog
     var PRIMARY_FIELDS = [
-      { field: 'token', kind: 'text', spec: textSpec('token'), labelKey: 'field.token', hintKey: 'hint.token' },
+      { field: 'token', kind: 'secret', spec: textSpec('token'), labelKey: 'field.token', hintKey: 'hint.token' },
       { field: 'tokenEnv', kind: 'text', spec: textSpec('tokenEnv'), labelKey: 'field.tokenEnv', hintKey: 'hint.tokenEnv' },
       { field: 'proxy', kind: 'text', spec: textSpec('proxy'), labelKey: 'field.proxy', hintKey: 'hint.proxy' },
       { field: 'routesApi', kind: 'bool', spec: boolSpec('routesApi'), labelKey: 'field.routesApi', hintKey: null },
@@ -108,12 +113,10 @@ window.__ModuleLoader__.load({
     FIELDS.forEach(function (f) { SPECS[f.field] = f.spec; });
 
     // ------------------------------------------------------------- i18n
-    var NS = 'dsh-github-router';
     var zhDict = {
       'nav': 'GitHub 路由',
       'description': 'GitHub 读取的路由与缓存配置。',
       'advanced': '高级设置',
-      'unavailable': '无法从宿主加载配置。',
       'save': '保存',
       'saving': '保存中…',
       'discard': '放弃修改',
@@ -121,6 +124,7 @@ window.__ModuleLoader__.load({
       'readOnly': '当前部署不允许修改设置。',
       'invalid': '无效值',
       'overridden': '已覆盖',
+      'configured': '已配置',
       'field.token': 'GitHub Token',
       'field.tokenEnv': 'Token 环境变量',
       'field.proxy': '代理地址',
@@ -138,7 +142,7 @@ window.__ModuleLoader__.load({
       'field.mirrors': '镜像基址（逗号分隔）',
       'field.repos': '本地仓库白名单（逗号分隔）',
       'field.gitCacheDir': 'git 缓存目录',
-      'hint.token': '留空表示清除；优先使用 tokenEnv。',
+      'hint.token': '仅写入：留空并保存 = 清除已配置的 token；优先使用 tokenEnv。',
       'hint.tokenEnv': '指向 token 的环境变量名，例如 GITHUB_TOKEN。',
       'hint.proxy': '空 = 继承环境代理；direct = 永不代理；其余为代理 URL。',
       'hint.maxBytes': '每个响应体的字节上限（16384..8388608）。',
@@ -153,7 +157,6 @@ window.__ModuleLoader__.load({
       'nav': 'GitHub Router',
       'description': 'Routing and cache configuration for GitHub reads.',
       'advanced': 'Advanced settings',
-      'unavailable': 'The configuration could not be loaded from the host.',
       'save': 'Save',
       'saving': 'Saving…',
       'discard': 'Discard',
@@ -161,6 +164,7 @@ window.__ModuleLoader__.load({
       'readOnly': 'This deployment does not allow settings edits.',
       'invalid': 'invalid',
       'overridden': 'overridden',
+      'configured': 'configured',
       'field.token': 'GitHub token',
       'field.tokenEnv': 'Token env var',
       'field.proxy': 'Proxy URL',
@@ -178,7 +182,7 @@ window.__ModuleLoader__.load({
       'field.mirrors': 'Mirror bases (comma-separated)',
       'field.repos': 'Local repo allowlist (comma-separated)',
       'field.gitCacheDir': 'Git cache directory',
-      'hint.token': 'Blank clears the value; prefer tokenEnv.',
+      'hint.token': 'Write-only: a blank save clears the configured token; prefer tokenEnv.',
       'hint.tokenEnv': 'Environment variable naming the token, e.g. GITHUB_TOKEN.',
       'hint.proxy': "Empty = inherit ambient proxy env; 'direct' = never proxy; anything else is a proxy URL.",
       'hint.maxBytes': 'Byte cap per response body (16384..8388608).',
@@ -191,100 +195,22 @@ window.__ModuleLoader__.load({
     };
 
     // ------------------------------------------------------------- form
-    /**
-     * The configuration channel is the dsh-market pattern: the Host mounts
-     * `/dsh-github-router/config` on the shared web server, and this page
-     * uses plain same-origin fetch (GET = redacted view, POST = writes).
-     * The framework's settings scope is NOT used — its api-proxy serves
-     * settings namespaces through a hardcoded allowlist that third-party
-     * plugins cannot join.
-     */
-
-    /** One `/dsh-github-router/config` call (GET or POST). */
-    function configCall(payload) {
-      var init = payload === undefined
-        ? { method: 'GET', cache: 'no-store' }
-        : {
-            method: 'POST',
-            cache: 'no-store',
-            headers: { 'content-type': 'application/json' },
-            body: JSON.stringify(payload),
-          };
-      return fetch('/dsh-github-router/config', init).then(function (response) {
-        return response.json().then(function (envelope) {
-          if (!envelope || envelope.ok !== true) {
-            var message = envelope && envelope.error !== undefined ? String(envelope.error) : 'config call failed (HTTP ' + response.status + ')';
-            throw new Error('dsh-github-router: ' + message);
-          }
-          return envelope.value;
-        });
-      });
+    /** JSON-shaped deep equality for verifying writes against the user layer. */
+    function sameJson(a, b) {
+      return JSON.stringify(a) === JSON.stringify(b);
     }
 
-    /** Scope adapter over the plugin routes: same interface the form uses. */
-    function RemoteScope() {
-      var listeners = new Set();
-      var snapshot = { status: 'loading', value: {}, base: {}, user: {}, revision: undefined, writable: false, mode: 'host' };
-
-      function publish() {
-        listeners.forEach(function (fn) { fn(); });
-      }
-      function accept(view) {
-        snapshot = {
-          status: 'ready',
-          value: view && typeof view.value === 'object' ? view.value : {},
-          base: view && typeof view.base === 'object' ? view.base : {},
-          user: view && typeof view.user === 'object' ? view.user : {},
-          revision: view && view.revision,
-          writable: !!(view && view.writable),
-          mode: 'host',
-        };
-        publish();
-      }
-      function fail(message) {
-        snapshot = { status: 'unavailable', value: {}, base: {}, user: {}, revision: undefined, writable: false, mode: 'memory' };
-        console.error('[dsh-github-router] config load failed', message);
-        publish();
-      }
-      function load() {
-        return configCall().then(accept, fail);
-      }
-      function write(op) {
-        return configCall({ ops: [op], expectedRevision: snapshot.revision }).then(accept, function (error) {
-          // A rejected write may mean the document moved (revision conflict)
-          // or storage failed — re-read so the next save fences correctly.
-          return load().then(function () { throw error; });
-        });
-      }
-
-      load();
-      return {
-        getSnapshot: function () { return snapshot; },
-        subscribe: function (fn) {
-          listeners.add(fn);
-          return function () { listeners.delete(fn); };
-        },
-        set: function (field, value) {
-          return write({ op: 'set', path: [field], value: value });
-        },
-        unset: function (field) {
-          return write({ op: 'unset', path: [field] });
-        },
-      };
-    }
-
-    /** A static scope stub for environments without fetch. */
-    function unavailableScope() {
-      var snapshot = { status: 'unavailable', value: {}, base: {}, user: {}, revision: undefined, writable: false, mode: 'memory' };
-      return {
-        getSnapshot: function () { return snapshot; },
-        subscribe: function () { return function () {}; },
-        set: function () { return Promise.resolve(); },
-        unset: function () { return Promise.resolve(); },
-      };
-    }
-
-    function GithubRouterForm(scope) {
+    /**
+     * Stages one card's edits over the plugin's settings namespace and writes
+     * them on save. The scope is the framework-bound settings scope
+     * (`ctx.settingsScope.bind({ namespace })`): its snapshot carries the
+     * redacted resolved section (`status`/`value`/`base`/`user`/`revision`/
+     * `writable`), and `set`/`unset` write one field each with revision
+     * fencing and recovery reads. The describe mirror supplements the
+     * snapshot with the secret slot list, the only signal that a redacted
+     * field (the token) is configured.
+     */
+    function GithubRouterForm(scope, mirror) {
       var staged = new Map(); // field -> { text, clear }
       var saving = false;
       var failed = false;
@@ -311,6 +237,17 @@ window.__ModuleLoader__.load({
         var s = snap();
         return !!(s.user && typeof s.user === 'object' && Object.prototype.hasOwnProperty.call(s.user, field));
       }
+      /** Whether a redacted secret slot holds a value (from the describe mirror). */
+      function secretSet(field) {
+        if (mirror === null || typeof mirror.namespace !== 'function') return false;
+        var row = mirror.namespace(NAMESPACE);
+        if (row === undefined || !Array.isArray(row.secrets)) return false;
+        for (var i = 0; i < row.secrets.length; i++) {
+          var slot = row.secrets[i];
+          if (Array.isArray(slot.path) && slot.path.length === 1 && slot.path[0] === field) return slot.set === true;
+        }
+        return false;
+      }
 
       function publish() {
         var s = snap();
@@ -323,14 +260,26 @@ window.__ModuleLoader__.load({
           var invalidField = false;
           if (stagedEntry !== undefined) {
             text = stagedEntry.text;
-            overridden = !stagedEntry.clear;
-            if (!stagedEntry.clear) invalidField = f.spec.parse(stagedEntry.text) === undefined;
+            if (stagedEntry.clear) {
+              overridden = false;
+            } else {
+              var parsedStaged = f.spec.parse(stagedEntry.text);
+              // The badge previews the save outcome: a staged blank that
+              // parses to a clear is not an override anymore.
+              overridden = parsedStaged !== undefined && parsedStaged.kind === 'set';
+              invalidField = parsedStaged === undefined;
+            }
           } else {
-            text = f.spec.format(sectionValue(f.field));
-            overridden = stored(f.field);
+            text = f.kind === 'secret' ? '' : f.spec.format(sectionValue(f.field));
+            overridden = f.kind === 'secret' ? secretSet(f.field) : stored(f.field);
           }
           if (invalidField) invalid = true;
-          fields[f.field] = { text: text, overridden: overridden, invalid: invalidField };
+          fields[f.field] = {
+            text: text,
+            overridden: overridden,
+            invalid: invalidField,
+            configured: f.kind === 'secret' && stagedEntry === undefined ? secretSet(f.field) : undefined,
+          };
         });
         store.set({
           available: s.status === 'ready',
@@ -343,6 +292,7 @@ window.__ModuleLoader__.load({
         });
       }
       scope.subscribe(publish);
+      if (mirror !== null && typeof mirror.subscribe === 'function') mirror.subscribe(publish);
       publish();
 
       function edit(field, text) {
@@ -368,9 +318,42 @@ window.__ModuleLoader__.load({
         staged.forEach(function (stagedEntry, field) {
           var spec = SPECS[field];
           if (stagedEntry.clear) {
+            if (field === 'token') {
+              // A blank draft clears the token only when one is configured.
+              if (secretSet(field)) {
+                writes.push({
+                  field: field,
+                  run: function () { return scope.unset(field).then(function () { return !secretSet(field); }); },
+                });
+              }
+              return;
+            }
             if (stored(field)) {
-              writes.push({ field: field, run: function () { return scope.unset(field); } });
+              writes.push({
+                field: field,
+                run: function () { return scope.unset(field).then(function () { return !stored(field); }); },
+              });
+            }
+            return;
+          }
+          if (field === 'token') {
+            var tokenText = stagedEntry.text.trim();
+            if (tokenText === '') {
+              // A blank draft clears the token when one is configured.
+              if (secretSet(field)) {
+                writes.push({
+                  field: field,
+                  run: function () { return scope.unset(field).then(function () { return !secretSet(field); }); },
+                });
+              }
+              return;
             }
+            writes.push({
+              field: field,
+              run: (function (value) {
+                return function () { return scope.set(field, value).then(function () { return secretSet(field); }); };
+              })(tokenText),
+            });
             return;
           }
           if (stagedEntry.text === spec.format(sectionValue(field))) return;
@@ -380,9 +363,22 @@ window.__ModuleLoader__.load({
             return;
           }
           if (write.kind === 'clear') {
-            writes.push({ field: field, run: function () { return scope.unset(field); } });
+            writes.push({
+              field: field,
+              run: function () { return scope.unset(field).then(function () { return !stored(field); }); },
+            });
           } else {
-            writes.push({ field: field, run: (function (value) { return function () { return scope.set(field, value); }; })(write.value) });
+            writes.push({
+              field: field,
+              run: (function (value) {
+                return function () {
+                  return scope.set(field, value).then(function () {
+                    var current = snap().user;
+                    return !!(current && typeof current === 'object' && Object.prototype.hasOwnProperty.call(current, field) && sameJson(current[field], value));
+                  });
+                };
+              })(write.value),
+            });
           }
         });
         if (blocked || writes.length === 0) return;
@@ -393,7 +389,7 @@ window.__ModuleLoader__.load({
         var chain = Promise.resolve();
         writes.forEach(function (w) {
           chain = chain.then(function () {
-            return w.run().catch(function () { landed = false; });
+            return w.run().then(function (ok) { if (ok !== true) landed = false; }, function () { landed = false; });
           });
         });
         chain.then(function () {
@@ -406,9 +402,9 @@ window.__ModuleLoader__.load({
 
       function inject(t) {
         return {
-          // The settings section shell synthesizes a `use<Key>` hook for
-          // every entry of this `hooks` object (dsh-notification's
-          // `hooks: { settings }` → `useSettings` is the working example).
+          // The slots runtime synthesizes a `use<Key>` hook for every entry
+          // of this `hooks` object (the shipped plugin cards' `hooks` →
+          // `useBashCard` contract).
           hooks: { settings: store },
           t: t,
           edit: edit,
@@ -420,8 +416,8 @@ window.__ModuleLoader__.load({
       return { inject: inject, store: store, save: save, edit: edit, discard: discard, resetField: resetField };
     }
 
-    // ------------------------------------------------------------- page
-    var pageStyle = { padding: '4px 0 24px' };
+    // ------------------------------------------------------------- card
+    var cardStyle = { padding: '4px 0 16px' };
     var gridStyle = {
       display: 'grid',
       gridTemplateColumns: 'minmax(180px, 1fr) minmax(180px, 1fr)',
@@ -447,12 +443,16 @@ window.__ModuleLoader__.load({
       cursor: 'pointer',
     };
 
-    function GithubRouterSection(props) {
+    function GithubRouterCard(props) {
       var state = props.useSettings(function (s) { return s; });
       var t = props.t;
 
+      // The framework cards render nothing until their namespace is served;
+      // this card follows the same posture.
+      if (!state.available) return null;
+
       function renderField(f) {
-        var fieldState = state.fields[f.field] || { text: '', overridden: false, invalid: false };
+        var fieldState = state.fields[f.field] || { text: '', overridden: false, invalid: false, configured: false };
         if (f.kind === 'bool') {
           return React.createElement(
             'label',
@@ -466,15 +466,22 @@ window.__ModuleLoader__.load({
             t(f.labelKey),
           );
         }
+        var marker;
+        if (f.kind === 'secret') {
+          marker = fieldState.configured === true
+            ? React.createElement('span', { style: { marginLeft: '6px', opacity: 0.6 } }, t('configured'))
+            : null;
+        } else {
+          marker = fieldState.overridden
+            ? React.createElement('span', { style: { marginLeft: '6px', opacity: 0.6 } }, t('overridden'))
+            : null;
+        }
         return React.createElement(
           'label',
           { key: f.field, style: rowStyle, title: f.hintKey ? t(f.hintKey) : undefined },
-          React.createElement('span', { style: labelStyle },
-            t(f.labelKey),
-            fieldState.overridden ? React.createElement('span', { style: { marginLeft: '6px', opacity: 0.6 } }, t('overridden')) : null,
-          ),
+          React.createElement('span', { style: labelStyle }, t(f.labelKey), marker),
           React.createElement('input', {
-            type: f.kind === 'number' ? 'number' : 'text',
+            type: f.kind === 'number' ? 'number' : f.kind === 'secret' ? 'password' : 'text',
             value: fieldState.text,
             disabled: !state.writable,
             style: inputStyle,
@@ -486,18 +493,17 @@ window.__ModuleLoader__.load({
 
       return React.createElement(
         'section',
-        { style: pageStyle },
+        { style: cardStyle },
         React.createElement('p', { style: { margin: '0 0 12px', opacity: 0.75, fontSize: '13px' } }, t('description')),
-        !state.available ? React.createElement('div', { style: { color: '#c00', fontSize: '13px' } }, t('unavailable')) : null,
-        state.available && !state.writable ? React.createElement('div', { style: { color: '#c00', fontSize: '13px' } }, t('readOnly')) : null,
-        state.available ? React.createElement('div', { style: gridStyle }, PRIMARY_FIELDS.map(renderField)) : null,
-        state.available ? React.createElement(
+        !state.writable ? React.createElement('div', { style: { color: '#c00', fontSize: '13px', marginBottom: '8px' } }, t('readOnly')) : null,
+        React.createElement('div', { style: gridStyle }, PRIMARY_FIELDS.map(renderField)),
+        React.createElement(
           'details',
           { style: { marginTop: '12px' } },
           React.createElement('summary', { style: { cursor: 'pointer', fontSize: '13px', opacity: 0.85 } }, t('advanced')),
           React.createElement('div', { style: Object.assign({ marginTop: '8px' }, gridStyle) }, ADVANCED_FIELDS.map(renderField)),
-        ) : null,
-        state.available ? React.createElement('footer', { style: footerStyle },
+        ),
+        React.createElement('footer', { style: footerStyle },
           React.createElement('button', {
             style: buttonStyle,
             disabled: !state.dirty || state.invalid || state.saving,
@@ -509,13 +515,13 @@ window.__ModuleLoader__.load({
             onClick: props.discard,
           }, t('discard')),
           state.failed ? React.createElement('span', { style: { color: '#c00', fontSize: '13px' } }, t('failed')) : null,
-        ) : null,
+        ),
       );
     }
 
     // ------------------------------------------------------------- plugin
     var name = 'dsh-github-router';
-    var inject = ['slots', 'locale'];
+    var inject = ['slots', 'locale', 'settingsScope', 'connection'];
     function apply(ctx) {
       console.info('[dsh-github-router] client bundle loaded');
       try {
@@ -523,24 +529,18 @@ window.__ModuleLoader__.load({
         ctx.effect(function () {
           ctx.locale.register(NS, { zh: zhDict, en: enDict });
         }, 'dsh-github-router: locale dictionaries');
-        var form = null;
-        ctx.slots.inject('settings.section', function* () {
+        var scope = ctx.settingsScope.bind({ namespace: NAMESPACE });
+        var mirror = typeof ctx.settingsScope.describe === 'function' ? ctx.settingsScope.describe() : null;
+        var form = new GithubRouterForm(scope, mirror);
+        ctx.slots.inject('settings.plugin.item', function* () {
           yield ctx.slots.register({
-            name: 'settings.section',
-            id: 'dsh-github-router',
-            order: 65,
-            label: function () { return t('nav'); },
+            name: 'settings.plugin.item',
+            key: NAMESPACE,
             locale: NS,
-            inject: function () {
-              if (form === null) {
-                var scope = typeof fetch === 'function' ? new RemoteScope() : unavailableScope();
-                form = new GithubRouterForm(scope);
-              }
-              return form.inject(t);
-            },
-          }, GithubRouterSection);
+            inject: function () { return form.inject(t); },
+          }, GithubRouterCard);
         });
-        console.info('[dsh-github-router] settings section registered');
+        console.info('[dsh-github-router] settings card registered');
       } catch (error) {
         console.error('[dsh-github-router] client apply failed', error);
       }

package/lib/config.js

@@ -2,9 +2,10 @@
  * Settings schema and runtime-option resolution for dsh-github-router.
  *
  * The settings section (`dsh-github-router` namespace) is registered through
- * `installSettingsSection`; the Settings UI renders a plugin card for it.
- * Secrets are declared with `.role('secret')` so they are redacted on every
- * wire boundary and rendered as write-only inputs.
+ * the official settings seam (`ctx.settings.register`, see `lib/settings.js`);
+ * the Settings UI renders a plugin card for it (Settings → Plugins, DSH ≥
+ * 0.1.0-rc.7). Secrets are declared with `.role('secret')` so they are
+ * redacted on every wire boundary and rendered as write-only inputs.
  *
  * The schema is deliberately FLAT: the client settings scope writes scalar
  * fields by name (`scope.set(field, value)`), so nested objects cannot be

package/lib/index.js

@@ -19,14 +19,15 @@
  * 4. Plugin-owned state (fetch cache, response cache) lives under
  *    <DSH_HOME>/storages/dsh-github-router; user repositories are only ever
  *    read (log/diff/show) and only when explicitly granted.
- * 5. Configuration rides the official settings seam (`dsh-github-router`
- *    namespace: durable document, schema validation, revision fencing) and
- *    is exposed to the browser through a plugin-owned remote API
- *    (`githubRouterSettings/{describe,mutate}`), because the framework's
- *    api-proxy only serves settings namespaces on its hardcoded allowlist.
+ * 5. Configuration rides the official settings seam end to end
+ *    (`dsh-github-router` namespace: durable document, schema validation,
+ *    revision fencing). Since DSH 0.1.0-rc.7 the framework serves every
+ *    registered settings namespace to the browser and renders the plugin's
+ *    configuration card in Settings → Plugins, so no plugin-owned HTTP
+ *    route exists.
  * @module dsh-github-router
  */
-import { installRemote } from './remote.js'
+import { installSettings } from './settings.js'
 import { registerGuidance } from './guidance.js'
 import { registerSkill } from './skill.js'
 import { registerApiTool } from './tools/api.js'
@@ -39,8 +40,7 @@ export const name = 'dsh-github-router'
 export const inject = ['tools', 'subprocess', 'skills', 'systemPrompt']
 
 export function apply(ctx, config = {}) {
-  const remote = installRemote(ctx, config)
-  const options = remote.options
+  const options = installSettings(ctx, config).options
 
   registerSkill(ctx)
   registerGuidance(ctx)

package/lib/settings.js

@@ -0,0 +1,38 @@
+/**
+ * Host-side settings wiring for dsh-github-router.
+ *
+ * The `dsh-github-router` namespace rides the official settings seam
+ * (`ctx.settings.register`): the framework persists the section in the user
+ * settings document, validates it against the schema, fences writes with
+ * revisions, and redacts secret-role fields on every wire boundary.
+ *
+ * Since DSH 0.1.0-rc.7 the api-proxy serves every registered settings
+ * namespace to the (loopback) browser and the Settings → Plugins section
+ * dispatches a plugin-owned card for it, so the client half binds the same
+ * namespace through `ctx.settingsScope` and the plugin needs no HTTP routes
+ * of its own. This module only registers the namespace and exposes the
+ * runtime-options thunk the tools consume; a settings change therefore
+ * applies to the NEXT tool call.
+ * @module dsh-github-router/settings
+ */
+import { Config, NAMESPACE, resolveOptions } from './config.js'
+
+/**
+ * Register the settings namespace and return the runtime-options thunk.
+ * @param ctx - the plugin context.
+ * @param config - the composition-layer config subset (the `base` layer).
+ */
+export function installSettings(ctx, config) {
+  const holder = { scope: null }
+
+  ctx.inject(['settings'], (sctx) => {
+    holder.scope = sctx.settings.register(NAMESPACE, Config, { base: config, applies: 'live' })
+    sctx.effect(() => () => {
+      holder.scope = null
+    }, 'dsh-github-router: settings scope teardown')
+  })
+
+  return {
+    options: () => (holder.scope !== null ? resolveOptions(holder.scope.get()) : resolveOptions(config)),
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-github-router",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "DeepSeek Harness plugin: read-only GitHub access for agents (github_probe / github_pr / github_issue / github_file / github_api). Routes every request inside the tool — api.github.com (direct or proxy), gh CLI, git protocol (plugin-owned fetch cache plus read-only local repo reads), PR/issue page HTML with strict JSON embeddedData extraction, and optional user-configured raw mirrors — so agents never burn turns fighting sandbox TLS/proxy failures in a shell. No write/push capability exists anywhere in the plugin.",
   "keywords": [
     "dsh-plugin",
@@ -46,13 +46,20 @@
     "docs"
   ],
   "dsh": {
+    "compatibility": {
+      "node": ">=20",
+      "dshReleases": {
+        "0.1.2-alpha.1": "compatible",
+        "0.1.1-rc.2": "incompatible"
+      }
+    },
     "bundle": {
       "patch": "./cordis.patch.yml"
     },
     "client": {
       "platform": "web",
       "inject": [
-        "@deepseek-ai/dsh-client-runtime"
+        "@deepseek-ai/dsh-client-store"
       ]
     }
   },
@@ -61,14 +68,14 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-settings": "^0.1.0-rc.6",
-    "@deepseek-ai/dsh-credentials": "^0.1.0-rc.6",
-    "@deepseek-ai/schemastery": "^2.0.0"
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-settings": "^0.1.2-alpha.1",
+    "@deepseek-ai/dsh-credentials": "^0.1.2-alpha.1",
+    "@deepseek-ai/schemastery": "^3.18.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-tools": "^0.1.0-rc.6"
+    "@deepseek-ai/dsh-tools": "^0.1.2-alpha.1"
   },
   "publishConfig": {
     "access": "public"

package/lib/remote.js

@@ -1,169 +0,0 @@
-/**
- * Host-side configuration routes for the browser settings page.
- *
- * The channel is the dshmarket pattern: the plugin mounts its own HTTP
- * routes on the shared web server (`ctx.webServer.register`, prefix
- * `/dsh-github-router`) and the browser page talks to them with plain
- * same-origin fetch — no typert, no gateway, no framework allowlist. The
- * routes are backed by the SAME official settings seam: the namespace
- * stays durable in the settings document, with schema validation,
- * revision fencing, and secret redaction.
- *
- * Mutating requests are POST-only, same-origin-checked (Origin === Host)
- * and body-capped, mirroring dsh-market's route security posture.
- * @module dsh-github-router/remote
- */
-import { Config, NAMESPACE, resolveOptions } from './config.js'
-
-const ROUTE_PREFIX = '/dsh-github-router'
-const MAX_BODY_BYTES = 16384
-
-function sendJson(response, status, payload) {
-  response.writeHead(status, {
-    'cache-control': 'no-store',
-    'content-type': 'application/json; charset=utf-8',
-  })
-  response.end(JSON.stringify(payload))
-}
-
-/** Same-origin enforcement for mutating routes (dsh-market posture). */
-function sameOrigin(request) {
-  const origin = request.headers.origin
-  const host = request.headers.host
-  if (origin === undefined || host === undefined) return false
-  try {
-    return new URL(origin).host === host
-  } catch {
-    return false
-  }
-}
-
-/** Read and parse a JSON request body with a hard byte cap. */
-async function readJsonBody(request, maxBytes = MAX_BODY_BYTES) {
-  const chunks = []
-  let size = 0
-  for await (const chunk of request) {
-    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk)
-    size += buffer.length
-    if (size > maxBytes) throw new Error('request body too large')
-    chunks.push(buffer)
-  }
-  return JSON.parse(Buffer.concat(chunks).toString('utf8'))
-}
-
-/**
- * Install the settings-namespace registration, the options thunk, and the
- * `/dsh-github-router/config` routes in one wiring. Returns the
- * runtime-options thunk the tools consume.
- */
-export function installRemote(ctx, config) {
-  const holder = { scope: null, settings: null }
-
-  ctx.inject(['settings'], (sctx) => {
-    holder.settings = sctx.settings
-    holder.scope = sctx.settings.register(NAMESPACE, Config, { base: config })
-    sctx.effect(() => () => {
-      holder.scope = null
-      holder.settings = null
-    }, 'dsh-github-router: settings scope teardown')
-  })
-
-  /** Redacted wire view of this namespace (value/base/user/revision/writable). */
-  function viewOf() {
-    if (holder.scope === null || holder.settings === null) return null
-    const descriptors = holder.settings.describe({ redactSecrets: true })
-    const descriptor = descriptors.find((d) => String(d.ns) === NAMESPACE)
-    if (descriptor === undefined) return null
-    return {
-      value: descriptor.value ?? {},
-      base: descriptor.base ?? {},
-      user: descriptor.user ?? {},
-      revision: descriptor.revision,
-      writable: holder.settings.writable === true,
-    }
-  }
-
-  function validateOps(payload) {
-    if (payload === null || typeof payload !== 'object' || !Array.isArray(payload.ops) || payload.ops.length === 0) {
-      return 'payload.ops must be a non-empty array'
-    }
-    if (payload.ops.length > 40) return 'too many ops in one write'
-    for (const op of payload.ops) {
-      if (op === null || typeof op !== 'object' || (op.op !== 'set' && op.op !== 'unset')) {
-        return 'each op must be { op: "set" | "unset", path: [field] }'
-      }
-      if (!Array.isArray(op.path) || op.path.length !== 1 || typeof op.path[0] !== 'string' || op.path[0].length === 0 || op.path[0].length > 64) {
-        return 'op.path must be a single field name'
-      }
-      if (op.op === 'set' && op.value === undefined) return 'set ops require a value'
-    }
-    return null
-  }
-
-  const routeHandler = async (request, response) => {
-    const pathname = new URL(request.url ?? '/', 'http://x').pathname
-    if (pathname !== ROUTE_PREFIX + '/config') {
-      sendJson(response, 404, { ok: false, error: 'unknown dsh-github-router route' })
-      return
-    }
-    if (request.method === 'GET') {
-      if (holder.scope === null || holder.settings === null) {
-        sendJson(response, 503, { ok: false, error: 'the settings service is not mounted in this deployment' })
-        return
-      }
-      const view = viewOf()
-      if (view === null) {
-        sendJson(response, 503, { ok: false, error: 'settings namespace is not registered' })
-        return
-      }
-      sendJson(response, 200, { ok: true, value: view })
-      return
-    }
-    if (request.method === 'POST') {
-      if (!sameOrigin(request)) {
-        sendJson(response, 403, { ok: false, error: 'configuration writes are limited to same-origin requests' })
-        return
-      }
-      if (holder.scope === null || holder.settings === null) {
-        sendJson(response, 503, { ok: false, error: 'the settings service is not mounted in this deployment' })
-        return
-      }
-      let payload
-      try {
-        payload = await readJsonBody(request)
-      } catch (error) {
-        sendJson(response, 400, { ok: false, error: `unreadable request body: ${String(error && error.message ? error.message : error)}` })
-        return
-      }
-      const invalid = validateOps(payload)
-      if (invalid !== null) {
-        sendJson(response, 400, { ok: false, error: invalid })
-        return
-      }
-      const expectedRevision = Number.isInteger(payload.expectedRevision) ? payload.expectedRevision : undefined
-      try {
-        await holder.scope.mutate(payload.ops, expectedRevision)
-      } catch (error) {
-        sendJson(response, 409, { ok: false, error: error instanceof Error ? error.message : String(error) })
-        return
-      }
-      const view = viewOf()
-      if (view === null) {
-        sendJson(response, 503, { ok: false, error: 'settings namespace disappeared after the write' })
-        return
-      }
-      sendJson(response, 200, { ok: true, value: view })
-      return
-    }
-    response.writeHead(405, { allow: 'GET, POST' })
-    response.end()
-  }
-
-  ctx.inject(['webServer'], (hctx) => {
-    hctx.effect(() => hctx.webServer.register({ kind: 'prefix', path: ROUTE_PREFIX, handler: routeHandler }), 'dsh-github-router: settings routes')
-  })
-
-  return {
-    options: () => (holder.scope !== null ? resolveOptions(holder.scope.get()) : resolveOptions(config)),
-  }
-}