dsh-github-router 0.3.1 → 0.4.0

package/lib/client.js

@@ -1,28 +1,28 @@
 /**
  * dsh-github-router — client half (hand-written factory bundle, no build step).
  *
- * 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`).
+ * One configuration page for the plugin's Loader row, registered into the
+ * Plugins page's `plugins.row.config` slot under the row key
+ * `<package name>#<row id>` (DSH ≥ 0.1.7-rc.2). The Plugins page owns the
+ * frame — title, icon, crumb, and the row's Configure control — and asks this
+ * entry for `view: 'summary'` (the row's one-liner) or `view: 'page'` (the
+ * form). No plugin-owned HTTP route exists: reads and writes ride the shared
+ * configuration form the settings domain provides per Host entry
+ * (`ctx.configForms.get(namespace)`), whose writes are revision-fenced and
+ * recovered by the framework.
  *
  * 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.
+ * written only on save; leaving the page drops them. The card verifies the
+ * user layer after a write and keeps drafts that did not land. Secret fields
+ * (the GitHub token) never ride a response, so the token control starts blank
+ * and a blank draft writes nothing — the describe mirror's secret-slot list is
+ * the only signal that one is configured, and an explicit clear control stages
+ * the `unset` that removes it.
  *
- * The module requires only `react` and
- * `@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.
+ * The bundle requires only `react` and `@deepseek-ai/dsh-client-store`, both
+ * members of the shell's frozen platform module table, so it declares no
+ * `dsh.client.inject` rows. All copy goes through the framework locale service
+ * under the `dsh-github-router` namespace.
  */
 window.__ModuleLoader__.load({
   id: 'dsh-github-router',
@@ -34,6 +34,10 @@ window.__ModuleLoader__.load({
 
     var NAMESPACE = 'dsh-github-router';
     var NS = 'dsh-github-router';
+    // `plugins.row.config` is keyed by `<package name>#<row id>`; this bundle's
+    // cordis.patch.yml declares both as `dsh-github-router`, so the row page
+    // and the settings namespace address the same entry.
+    var ROW_CONFIG_KEY = 'dsh-github-router#dsh-github-router';
 
     // ------------------------------------------------------------ specs
     function textSpec(field) {
@@ -114,17 +118,18 @@ window.__ModuleLoader__.load({
 
     // ------------------------------------------------------------- i18n
     var zhDict = {
-      'nav': 'GitHub 路由',
       'description': 'GitHub 读取的路由与缓存配置。',
       'advanced': '高级设置',
       'save': '保存',
       'saving': '保存中…',
-      'discard': '放弃修改',
       'failed': '保存失败，请重试。',
       'readOnly': '当前部署不允许修改设置。',
+      'unavailable': '该插件当前未加载，暂时无法配置。',
       'invalid': '无效值',
       'overridden': '已覆盖',
       'configured': '已配置',
+      'clearToken': '清除已保存的 token',
+      'willClear': '保存后清除',
       'field.token': 'GitHub Token',
       'field.tokenEnv': 'Token 环境变量',
       'field.proxy': '代理地址',
@@ -142,7 +147,7 @@ window.__ModuleLoader__.load({
       'field.mirrors': '镜像基址（逗号分隔）',
       'field.repos': '本地仓库白名单（逗号分隔）',
       'field.gitCacheDir': 'git 缓存目录',
-      'hint.token': '仅写入：留空并保存 = 清除已配置的 token；优先使用 tokenEnv。',
+      'hint.token': '只写字段：留空保存表示保持当前 token 不变；用「清除」按钮删除已保存的 token。优先使用 tokenEnv。',
       'hint.tokenEnv': '指向 token 的环境变量名，例如 GITHUB_TOKEN。',
       'hint.proxy': '空 = 继承环境代理；direct = 永不代理；其余为代理 URL。',
       'hint.maxBytes': '每个响应体的字节上限（16384..8388608）。',
@@ -154,17 +159,18 @@ window.__ModuleLoader__.load({
       'hint.gitCacheDir': '空 = <DSH_HOME>/storages/dsh-github-router/git。',
     };
     var enDict = {
-      'nav': 'GitHub Router',
       'description': 'Routing and cache configuration for GitHub reads.',
       'advanced': 'Advanced settings',
       'save': 'Save',
       'saving': 'Saving…',
-      'discard': 'Discard',
       'failed': 'The save failed. Please retry.',
       'readOnly': 'This deployment does not allow settings edits.',
+      'unavailable': 'This plugin is not loaded, so it cannot be configured right now.',
       'invalid': 'invalid',
       'overridden': 'overridden',
       'configured': 'configured',
+      'clearToken': 'Clear stored token',
+      'willClear': 'clears on save',
       'field.token': 'GitHub token',
       'field.tokenEnv': 'Token env var',
       'field.proxy': 'Proxy URL',
@@ -182,7 +188,7 @@ window.__ModuleLoader__.load({
       'field.mirrors': 'Mirror bases (comma-separated)',
       'field.repos': 'Local repo allowlist (comma-separated)',
       'field.gitCacheDir': 'Git cache directory',
-      'hint.token': 'Write-only: a blank save clears the configured token; prefer tokenEnv.',
+      'hint.token': 'Write-only: a blank draft keeps the stored token; the Clear control removes it. 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).',
@@ -201,16 +207,20 @@ window.__ModuleLoader__.load({
     }
 
     /**
-     * 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.
+     * Stages one page's edits over the plugin's settings namespace and writes
+     * them on save.
+     *
+     * The scope is the shared configuration form the settings domain provides
+     * for this Host entry (`ctx.configForms.get(namespace)`): its snapshot
+     * carries the redacted resolved section
+     * (`status`/`value`/`base`/`user`/`revision`/`writable`/`mode`), and
+     * `set`/`unset` queue one revision-fenced, recovered write each. The
+     * describe mirror supplements the snapshot with the secret-slot list, the
+     * only signal that a redacted field (the token) is configured.
+     * @param scope - the shared configuration form of this entry.
+     * @param describe - the deployment-wide describe face, or null when absent.
      */
-    function GithubRouterForm(scope, mirror) {
+    function GithubRouterForm(scope, describe) {
       var staged = new Map(); // field -> { text, clear }
       var saving = false;
       var failed = false;
@@ -237,14 +247,25 @@ 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). */
+      /**
+       * Whether a redacted secret slot holds a value. Secret fields never ride
+       * the namespace value, so the describe mirror's per-namespace `secrets`
+       * list is the only source for this fact.
+       */
       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;
+        if (describe === null || typeof describe.getSnapshot !== 'function') return false;
+        var mirror = describe.getSnapshot();
+        var view = mirror === null || mirror === undefined ? undefined : mirror.view;
+        var rows = view !== undefined && view !== null && Array.isArray(view.namespaces) ? view.namespaces : [];
+        for (var i = 0; i < rows.length; i++) {
+          var row = rows[i];
+          if (row === null || row === undefined || row.ns !== NAMESPACE) continue;
+          var secrets = Array.isArray(row.secrets) ? row.secrets : [];
+          for (var j = 0; j < secrets.length; j++) {
+            var slot = secrets[j];
+            if (Array.isArray(slot.path) && slot.path.length === 1 && slot.path[0] === field) return slot.set === true;
+          }
+          return false;
         }
         return false;
       }
@@ -257,10 +278,12 @@ window.__ModuleLoader__.load({
           var stagedEntry = staged.get(f.field);
           var text;
           var overridden;
+          var clearing = false;
           var invalidField = false;
           if (stagedEntry !== undefined) {
             text = stagedEntry.text;
-            if (stagedEntry.clear) {
+            clearing = stagedEntry.clear === true;
+            if (clearing) {
               overridden = false;
             } else {
               var parsedStaged = f.spec.parse(stagedEntry.text);
@@ -271,14 +294,15 @@ window.__ModuleLoader__.load({
             }
           } else {
             text = f.kind === 'secret' ? '' : f.spec.format(sectionValue(f.field));
-            overridden = f.kind === 'secret' ? secretSet(f.field) : stored(f.field);
+            overridden = f.kind === 'secret' ? false : stored(f.field);
           }
           if (invalidField) invalid = true;
           fields[f.field] = {
             text: text,
             overridden: overridden,
             invalid: invalidField,
-            configured: f.kind === 'secret' && stagedEntry === undefined ? secretSet(f.field) : undefined,
+            configured: f.kind === 'secret' ? secretSet(f.field) : false,
+            clearing: clearing,
           };
         });
         store.set({
@@ -291,12 +315,16 @@ window.__ModuleLoader__.load({
           fields: fields,
         });
       }
-      scope.subscribe(publish);
-      if (mirror !== null && typeof mirror.subscribe === 'function') mirror.subscribe(publish);
+      var offScope = scope.subscribe(publish);
+      var offDescribe = describe !== null && typeof describe.subscribe === 'function' ? describe.subscribe(publish) : null;
       publish();
 
       function edit(field, text) {
-        staged.set(field, { text: String(text), clear: false });
+        var value = String(text);
+        // A blank secret draft carries no write: the stored secret stays, and
+        // the explicit clear control is what removes it.
+        if (field === 'token' && value.trim() === '') staged.delete(field);
+        else staged.set(field, { text: value, clear: false });
         failed = false;
         publish();
       }
@@ -317,29 +345,10 @@ window.__ModuleLoader__.load({
         var blocked = false;
         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).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.
+            // A blank draft never clears a configured token; only the clear
+            // control stages the `unset`, and only while one is configured.
+            if (stagedEntry.clear) {
               if (secretSet(field)) {
                 writes.push({
                   field: field,
@@ -348,14 +357,24 @@ window.__ModuleLoader__.load({
               }
               return;
             }
+            if (stagedEntry.text.trim() === '') return;
             writes.push({
               field: field,
               run: (function (value) {
                 return function () { return scope.set(field, value).then(function () { return secretSet(field); }); };
-              })(tokenText),
+              })(stagedEntry.text.trim()),
             });
             return;
           }
+          if (stagedEntry.clear) {
+            if (stored(field)) {
+              writes.push({
+                field: field,
+                run: function () { return scope.unset(field).then(function () { return !stored(field); }); },
+              });
+            }
+            return;
+          }
           if (stagedEntry.text === spec.format(sectionValue(field))) return;
           var write = spec.parse(stagedEntry.text);
           if (write === undefined) {
@@ -363,10 +382,12 @@ window.__ModuleLoader__.load({
             return;
           }
           if (write.kind === 'clear') {
-            writes.push({
-              field: field,
-              run: function () { return scope.unset(field).then(function () { return !stored(field); }); },
-            });
+            if (stored(field)) {
+              writes.push({
+                field: field,
+                run: function () { return scope.unset(field).then(function () { return !stored(field); }); },
+              });
+            }
           } else {
             writes.push({
               field: field,
@@ -399,25 +420,28 @@ window.__ModuleLoader__.load({
           publish();
         });
       }
+      function dispose() {
+        if (typeof offScope === 'function') offScope();
+        if (typeof offDescribe === 'function') offDescribe();
+      }
 
-      function inject(t) {
+      function inject() {
         return {
-          // 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,
+          // The slots runtime synthesizes a `use<Key>` hook for every entry of
+          // this `hooks` object (the shipped plugin pages' `hooks` →
+          // `useShellCard` contract).
+          hooks: { gitHubRouterCard: store },
           edit: edit,
           resetField: resetField,
           save: save,
           discard: discard,
         };
       }
-      return { inject: inject, store: store, save: save, edit: edit, discard: discard, resetField: resetField };
+      return { inject: inject, store: store, dispose: dispose };
     }
 
-    // ------------------------------------------------------------- card
-    var cardStyle = { padding: '4px 0 16px' };
+    // ------------------------------------------------------------- page
+    var pageStyle = { padding: '4px 0 16px' };
     var gridStyle = {
       display: 'grid',
       gridTemplateColumns: 'minmax(180px, 1fr) minmax(180px, 1fr)',
@@ -433,6 +457,7 @@ window.__ModuleLoader__.load({
       color: 'inherit',
     };
     var boolRowStyle = { display: 'flex', alignItems: 'center', gap: '6px', fontSize: '13px' };
+    var markerStyle = { marginLeft: '6px', opacity: 0.6 };
     var footerStyle = { display: 'flex', alignItems: 'center', gap: '8px', marginTop: '12px' };
     var buttonStyle = {
       padding: '4px 12px',
@@ -442,17 +467,23 @@ window.__ModuleLoader__.load({
       color: 'inherit',
       cursor: 'pointer',
     };
+    var clearButtonStyle = Object.assign({}, buttonStyle, { padding: '2px 8px', fontSize: '12px' });
 
     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;
+      // Hooks run before the view branches so one occupied slot keeps a
+      // constant hook count whether it renders the one-liner or the page.
+      var state = props.useGitHubRouterCard(function (s) { return s; });
+      // Leaving the page drops every staged edit, the same posture the shipped
+      // settings pages follow.
+      React.useEffect(function () {
+        return function () { props.discard(); };
+      }, []);
+      // The Plugins page asks for the row's one-liner before it asks for the page.
+      if (props.view === 'summary') return t('description');
 
       function renderField(f) {
-        var fieldState = state.fields[f.field] || { text: '', overridden: false, invalid: false, configured: false };
+        var fieldState = state.fields[f.field] || { text: '', overridden: false, invalid: false, configured: false, clearing: false };
         if (f.kind === 'bool') {
           return React.createElement(
             'label',
@@ -468,34 +499,46 @@ window.__ModuleLoader__.load({
         }
         var marker;
         if (f.kind === 'secret') {
-          marker = fieldState.configured === true
-            ? React.createElement('span', { style: { marginLeft: '6px', opacity: 0.6 } }, t('configured'))
-            : null;
+          marker = fieldState.clearing
+            ? React.createElement('span', { style: markerStyle }, t('willClear'))
+            : fieldState.configured
+              ? React.createElement('span', { style: markerStyle }, t('configured'))
+              : null;
         } else {
           marker = fieldState.overridden
-            ? React.createElement('span', { style: { marginLeft: '6px', opacity: 0.6 } }, t('overridden'))
+            ? React.createElement('span', { style: markerStyle }, t('overridden'))
             : null;
         }
+        var clearControl = f.kind === 'secret' && fieldState.configured && !fieldState.clearing
+          ? React.createElement('button', {
+            type: 'button',
+            style: clearButtonStyle,
+            disabled: !state.writable || state.saving,
+            onClick: function () { props.resetField(f.field); },
+          }, t('clearToken'))
+          : 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), marker),
           React.createElement('input', {
             type: f.kind === 'number' ? 'number' : f.kind === 'secret' ? 'password' : 'text',
+            autoComplete: f.kind === 'secret' ? 'new-password' : undefined,
             value: fieldState.text,
             disabled: !state.writable,
             style: inputStyle,
             onChange: function (event) { props.edit(f.field, event.target.value); },
           }),
           fieldState.invalid ? React.createElement('span', { style: { color: '#c00' } }, t('invalid')) : null,
+          clearControl,
         );
       }
 
       return React.createElement(
         'section',
-        { style: cardStyle },
-        React.createElement('p', { style: { margin: '0 0 12px', opacity: 0.75, fontSize: '13px' } }, t('description')),
-        !state.writable ? React.createElement('div', { style: { color: '#c00', fontSize: '13px', marginBottom: '8px' } }, t('readOnly')) : null,
+        { style: pageStyle },
+        !state.available ? React.createElement('p', { style: labelStyle }, t('unavailable')) : null,
+        !state.writable ? React.createElement('p', { style: { color: '#c00', fontSize: '13px', marginBottom: '8px' } }, t('readOnly')) : null,
         React.createElement('div', { style: gridStyle }, PRIMARY_FIELDS.map(renderField)),
         React.createElement(
           'details',
@@ -506,22 +549,17 @@ window.__ModuleLoader__.load({
         React.createElement('footer', { style: footerStyle },
           React.createElement('button', {
             style: buttonStyle,
-            disabled: !state.dirty || state.invalid || state.saving,
+            disabled: !state.writable || !state.dirty || state.invalid || state.saving,
             onClick: props.save,
           }, state.saving ? t('saving') : t('save')),
-          React.createElement('button', {
-            style: buttonStyle,
-            disabled: !state.dirty || state.saving,
-            onClick: props.discard,
-          }, t('discard')),
           state.failed ? React.createElement('span', { style: { color: '#c00', fontSize: '13px' } }, t('failed')) : null,
         ),
       );
     }
 
-    // ------------------------------------------------------------- plugin
+    // ------------------------------------------------------------ plugin
     var name = 'dsh-github-router';
-    var inject = ['slots', 'locale', 'settingsScope', 'connection'];
+    var inject = ['slots', 'locale', 'configForms'];
     function apply(ctx) {
       console.info('[dsh-github-router] client bundle loaded');
       try {
@@ -529,18 +567,29 @@ window.__ModuleLoader__.load({
         ctx.effect(function () {
           ctx.locale.register(NS, { zh: zhDict, en: enDict });
         }, 'dsh-github-router: locale dictionaries');
-        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.plugin.item',
-            key: NAMESPACE,
-            locale: NS,
-            inject: function () { return form.inject(t); },
-          }, GithubRouterCard);
-        });
-        console.info('[dsh-github-router] settings card registered');
+        // The shared form for this Host entry, plus the deployment-wide describe
+        // face the secret-slot state is read from.
+        var scope = ctx.configForms.get(NAMESPACE);
+        var describe = typeof ctx.configForms.describe === 'function' ? ctx.configForms.describe() : null;
+        var form = new GithubRouterForm(scope, describe);
+        ctx.effect(function () {
+          return function () { form.dispose(); };
+        }, 'dsh-github-router: form subscriptions');
+        // The page exists while the Host serves this namespace, so a
+        // deployment whose host half is missing shows no trace of it.
+        ctx.effect(function () {
+          return ctx.configForms.whileServed([NAMESPACE], function () {
+            return ctx.slots.inject('plugins.row.config', function () {
+              return ctx.slots.register({
+                name: 'plugins.row.config',
+                key: ROW_CONFIG_KEY,
+                locale: NS,
+                inject: function () { return form.inject(); },
+              }, GithubRouterCard);
+            });
+          });
+        }, 'dsh-github-router: settings page');
+        console.info('[dsh-github-router] settings page registered');
       } catch (error) {
         console.error('[dsh-github-router] client apply failed', error);
       }