@dsh-plus/notify-email 0.1.6 → 0.1.8

package/lib/index.d.ts

@@ -1,9 +1,6 @@
 import z from "@deepseek-ai/schemastery";
-import "@deepseek-ai/dsh-settings";
 import { Context, Service } from "@deepseek-ai/cordis";
-
 //#region src/config.d.ts
-
 declare const Config: z<Schemastery.ObjectS<{
   enabled: z<boolean, boolean>;
   smtp: z<Schemastery.ObjectS<{

package/lib/index.js

@@ -1,26 +1,20 @@
-import z from "@deepseek-ai/schemastery";
 import { installSettingsSection, settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
 import { Context, Service } from "@deepseek-ai/cordis";
 import { dshHomePath } from "@deepseek-ai/dsh-home-paths";
 import { appendFile, mkdir } from "node:fs/promises";
 import { dirname } from "node:path";
 import nodemailer from "nodemailer";
-
-//#region src/ns.ts
-/**
-* settings 命名空间字面量（纯常量，零依赖，浏览器半可安全引入）。
-* 服务端经 settingsNamespace() 品牌化后使用（config.ts），浏览器半将其作为
-* settings.plugin.item keyed 槽位的 key —— 同一字面量两处共用，防止漂移。
-* 契约：dsh rc7 起该槽位按「卡片编辑的 settings 命名空间」作 key 分发，
-* 官方配置页只渲染 key 命中 Host 已注册命名空间的卡片。
-* @module notify-email/ns
-*/
-const SETTINGS_NS$1 = "dsh-plus-notify-email";
-
 //#endregion
 //#region src/config.ts
+/**
+* 配置单一事实源：cordis 行级 Config（组合默认值，dev/prod patch 层可覆盖）
+* 与 settings namespace（用户层，经 dsh-settings-file 持久化到 $DSH_HOME/settings.yaml）
+* 共用同一 schemastery schema。SMTP 密码标记 secret 角色，任何读取通道不得回传。
+* @module notify-email/config
+*/
 /** settings 命名空间；webui 配置卡片与插件运行期读取同一份（字面量见 ./ns.ts）。 */
-const SETTINGS_NS = settingsNamespace(SETTINGS_NS$1);
+const SETTINGS_NS = settingsNamespace("dsh-plus-notify-email");
 const SmtpSchema = z.object({
 	host: z.string().description("SMTP 服务器主机名").default(""),
 	port: z.natural().max(65535).description("SMTP 端口").default(465),
@@ -58,9 +52,14 @@ const Config = z.object({
 	maxBodyChars: z.natural().min(200).description("邮件正文内容截断长度").default(4e3),
 	dryRun: z.boolean().description("仅记录日志不真实发送（开发调试用）").default(false)
 });
-
 //#endregion
 //#region src/audit.ts
+/**
+* 通知投递审计：每次发送尝试追加一行 JSONL 到 $DSH_HOME/logs/notify-email.jsonl。
+* 让 dry-run 可观测（dev 实例 logger 不落盘），也为生产排查「为什么没收到邮件」留痕。
+* 记录正文截断 2000 字符；永远不含 SMTP 凭据。写失败只告警不阻断。
+* @module notify-email/audit
+*/
 const BODY_EXCERPT_CHARS = 2e3;
 function buildAuditRecord(subject, text, to, result) {
 	return {
@@ -80,9 +79,51 @@ function createJsonlAuditSink(path, onError) {
 		});
 	};
 }
-
+//#endregion
+//#region src/config-api.ts
+const ROUTE_TEST = "/dsh-plus/notify-email/test";
+function sendJson(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+async function handleTest(service, res) {
+	const result = await service.sendTest();
+	sendJson(res, result.ok ? 200 : 502, result);
+}
+/** 注册测试发信路由；返回是否注册成功（webServer 缺失时由调用方保证不调用）。 */
+function registerTestApi(ctx, service) {
+	const logger = ctx.logger("notify-email");
+	const guard = (handler) => {
+		return async (req, res) => {
+			try {
+				await handler(req, res);
+			} catch (error) {
+				const message = error instanceof Error ? error.message : String(error);
+				logger.warn(`test api ${req.method ?? "?"} ${req.url ?? "?"} failed: ${message}`);
+				if (!res.headersSent) sendJson(res, 400, { error: message });
+				else res.end();
+			}
+		};
+	};
+	ctx.webServer.register({
+		kind: "exact",
+		path: ROUTE_TEST,
+		handler: guard(async (req, res) => {
+			if (req.method !== "POST") {
+				sendJson(res, 405, { error: "method not allowed" });
+				return;
+			}
+			await handleTest(service, res);
+		})
+	});
+}
 //#endregion
 //#region src/mailer.ts
+/**
+* 邮件发送：nodemailer 封装 + dry-run 兜底。
+* Transport 抽象为函数注入，单元测试以假 transport 断言参数，零网络。
+* @module notify-email/mailer
+*/
 /**  nodemailer 连接/问候/套接字超时（毫秒），防 SMTP 不可达时挂住通知链路。 */
 const CONNECTION_TIMEOUT_MS = 1e4;
 const GREETING_TIMEOUT_MS = 1e4;
@@ -160,46 +201,6 @@ var Mailer = class {
 		return result;
 	}
 };
-
-//#endregion
-//#region src/config-api.ts
-const ROUTE_TEST = "/dsh-plus/notify-email/test";
-function sendJson(res, status, body) {
-	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
-	res.end(JSON.stringify(body));
-}
-async function handleTest(service, res) {
-	const result = await service.sendTest();
-	sendJson(res, result.ok ? 200 : 502, result);
-}
-/** 注册测试发信路由；返回是否注册成功（webServer 缺失时由调用方保证不调用）。 */
-function registerTestApi(ctx, service) {
-	const logger = ctx.logger("notify-email");
-	const guard = (handler) => {
-		return async (req, res) => {
-			try {
-				await handler(req, res);
-			} catch (error) {
-				const message = error instanceof Error ? error.message : String(error);
-				logger.warn(`test api ${req.method ?? "?"} ${req.url ?? "?"} failed: ${message}`);
-				if (!res.headersSent) sendJson(res, 400, { error: message });
-				else res.end();
-			}
-		};
-	};
-	ctx.webServer.register({
-		kind: "exact",
-		path: ROUTE_TEST,
-		handler: guard(async (req, res) => {
-			if (req.method !== "POST") {
-				sendJson(res, 405, { error: "method not allowed" });
-				return;
-			}
-			await handleTest(service, res);
-		})
-	});
-}
-
 //#endregion
 //#region src/triggers/render.ts
 function truncate(text, maxChars) {
@@ -264,7 +265,6 @@ function renderAbortedNotice(info) {
 		text: header("任务被用户取消", info)
 	};
 }
-
 //#endregion
 //#region src/triggers/builtin.ts
 /** 官方决策工具名 → 渲染函数 + 对应 toggle。 */
@@ -289,7 +289,6 @@ function createTurnEndTrigger(resolveConfig) {
 		}
 	};
 }
-
 //#endregion
 //#region src/watchers/decision.ts
 function installDecisionWatcher(ctx, service) {
@@ -310,11 +309,10 @@ function installDecisionWatcher(ctx, service) {
 		return next();
 	});
 }
-
 //#endregion
 //#region src/watchers/turn-end.ts
 /** 只有这三类 turn 结束对用户有可决策价值；blocked/max-tokens/interrupted 不通知。 */
-const NOTIFY_KINDS = new Set([
+const NOTIFY_KINDS = /* @__PURE__ */ new Set([
 	"completed",
 	"error",
 	"aborted"
@@ -397,9 +395,16 @@ function installTurnEndWatcher(ctx, service, resolveConfig) {
 		watches.clear();
 	}, "notify-email: turn-end timers");
 }
-
 //#endregion
 //#region src/service.ts
+/**
+* NotifyEmailService：通知编排中枢。
+* - 配置：installSettingsSection 接入 settings 用户层（$DSH_HOME/settings.yaml，热生效），
+*   无 settings provider 时退化为 cordis 行级 config。
+* - 触发器：registerTrigger 是第三方插件的扩展接口；内置官方适配器同路径注册。
+* - 投递：首个非空 EmailNotice 经 Mailer 发送；单个触发器抛错不影响其余。
+* @module @dsh-plus/notify-email
+*/
 var NotifyEmailService = class extends Service {
 	static [Context.inject] = ["agents", "tools"];
 	triggers = [];
@@ -415,7 +420,8 @@ var NotifyEmailService = class extends Service {
 			onChange: () => {}
 		});
 		const logger = ctx.logger("notify-email");
-		this.mailer = new Mailer(() => this.current(), logger, void 0, createJsonlAuditSink(dshHomePath("logs", "notify-email.jsonl"), (message) => logger.warn(`audit write failed: ${message}`)));
+		const audit = createJsonlAuditSink(dshHomePath("logs", "notify-email.jsonl"), (message) => logger.warn(`audit write failed: ${message}`));
+		this.mailer = new Mailer(() => this.current(), logger, void 0, audit);
 		this.registerTrigger(createDecisionTrigger(() => this.current()));
 		this.registerTrigger(createTurnEndTrigger(() => this.current()));
 		installDecisionWatcher(ctx, this);
@@ -456,7 +462,7 @@ var NotifyEmailService = class extends Service {
 	async sendNotice(notice) {
 		return this.mailer.send(notice);
 	}
-	async dispatch(kind, payload, produce) {
+	async dispatch(kind, _payload, produce) {
 		for (const trigger of [...this.triggers]) {
 			let notice;
 			try {
@@ -472,7 +478,6 @@ var NotifyEmailService = class extends Service {
 		}
 	}
 };
-
 //#endregion
 //#region src/index.ts
 const name = "dsh-plus-notify-email";
@@ -480,6 +485,5 @@ const inject = ["agents", "tools"];
 function apply(ctx, config) {
 	ctx.plugin(NotifyEmailService, config);
 }
-
 //#endregion
-export { Config, NotifyEmailService, apply, inject, name };
+export { Config, NotifyEmailService, apply, inject, name };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dsh-plus/notify-email",
-  "version": "0.1.6",
+  "version": "0.1.8",
   "description": "dsh-plus service+ui plugin: 任务结束/等待决策/出错时向指定邮箱发送邮件通知",
   "type": "module",
   "main": "lib/index.js",
@@ -42,13 +42,13 @@
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "4.0.1",
-    "@deepseek-ai/dsh-agent": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-home-paths": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-host-webserver": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-llm": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-session": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-settings": "0.1.0-rc.8",
-    "@deepseek-ai/dsh-tools": "0.1.0-rc.8",
+    "@deepseek-ai/dsh-agent": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-home-paths": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-llm": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-session": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-settings": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-tools": "0.1.1-rc.2",
     "@deepseek-ai/schemastery": "3.18.1",
     "@types/nodemailer": "8.0.1",
     "@types/react": "~18.3.1",

package/src/client/card.tsx

@@ -7,7 +7,7 @@
  * 保存经 settings.update 深合并（空 pass 剔除 = 保持不变）。
  * @module notify-email/client/card
  */
-import { useEffect, useMemo, useSyncExternalStore, useState, type ReactElement } from 'react'
+import { type ReactElement, useEffect, useMemo, useState, useSyncExternalStore } from 'react'
 
 import { SETTINGS_NS } from '../ns.ts'
 import { sendTest } from './api.ts'
@@ -97,7 +97,10 @@ function toPatch(draft: Draft): Record<string, unknown> {
       pass: draft.pass,
       from: draft.from.trim(),
     },
-    to: draft.toText.split(',').map((s) => s.trim()).filter((s) => s.length > 0),
+    to: draft.toText
+      .split(',')
+      .map((s) => s.trim())
+      .filter((s) => s.length > 0),
     triggers: { ...draft.triggers },
     idleDebounceMs: Number(draft.idleDebounceMs),
     maxBodyChars: Number(draft.maxBodyChars),
@@ -128,14 +131,17 @@ export function NotifyEmailCard(props: CardProps): ReactElement | null {
   }, [value, draft])
 
   // passConfigured 探测：scope 快照不含 secrets，经 describe 的 secrets 列表判断。
+  // biome-ignore lint/correctness/useExhaustiveDependencies: snapshot 变化（保存后 revision 推进）时刻意重探 secrets 状态
   useEffect(() => {
     let alive = true
-    api.describe({})
+    api
+      .describe({})
       .then((response) => {
         if (!alive || !response.result.ok) return
         const view = response.result.value?.namespaces.find((ns) => ns.ns === SETTINGS_NS)
         setPassConfigured(
-          view?.secrets.some((secret) => secret.path.join('.') === 'smtp.pass' && secret.set) ?? false,
+          view?.secrets.some((secret) => secret.path.join('.') === 'smtp.pass' && secret.set) ??
+            false,
         )
       })
       .catch(() => {})
@@ -146,20 +152,27 @@ export function NotifyEmailCard(props: CardProps): ReactElement | null {
 
   const dirty = useMemo(
     () =>
-      value !== undefined && draft !== null &&
+      value !== undefined &&
+      draft !== null &&
       JSON.stringify(toPatch(draft)) !== JSON.stringify(toPatch(draftFromValue(value))),
     [value, draft],
   )
   const invalid = useMemo(
     () =>
       draft !== null &&
-      (!isPositiveInt(draft.port) || !isPositiveInt(draft.idleDebounceMs) ||
-        !isPositiveInt(draft.maxBodyChars) || Number(draft.maxBodyChars) < 200),
+      (!isPositiveInt(draft.port) ||
+        !isPositiveInt(draft.idleDebounceMs) ||
+        !isPositiveInt(draft.maxBodyChars) ||
+        Number(draft.maxBodyChars) < 200),
     [draft],
   )
 
   if (value === undefined || draft === null) {
-    return <li className="dne-card"><p className="dne-readOnly">{t('loading')}</p></li>
+    return (
+      <li className="dne-card">
+        <p className="dne-readOnly">{t('loading')}</p>
+      </li>
+    )
   }
   const edit = <K extends keyof Draft>(key: K, editValue: Draft[K]): void => {
     setDraft({ ...draft, [key]: editValue })
@@ -175,11 +188,12 @@ export function NotifyEmailCard(props: CardProps): ReactElement | null {
       delete (patch['smtp'] as Record<string, unknown>)['pass']
     }
     const revision = scope.getSnapshot().revision
-    api.update({
-      ns: SETTINGS_NS,
-      patch,
-      ...(revision !== undefined ? { expectedRevision: revision } : {}),
-    })
+    api
+      .update({
+        ns: SETTINGS_NS,
+        patch,
+        ...(revision !== undefined ? { expectedRevision: revision } : {}),
+      })
       .then(async (response) => {
         if (!response.result.ok) {
           throw new Error(response.result.error?.message ?? t('saveFailed'))
@@ -200,14 +214,20 @@ export function NotifyEmailCard(props: CardProps): ReactElement | null {
     sendTest()
       .then((result) => {
         if (result.ok) {
-          setStatus({ kind: 'ok', text: result.detail === 'dry-run' ? t('testDryRun') : t('testOk') })
+          setStatus({
+            kind: 'ok',
+            text: result.detail === 'dry-run' ? t('testDryRun') : t('testOk'),
+          })
         } else {
           const why = result.detail === 'incomplete' ? t('incomplete') : result.detail
           setStatus({ kind: 'error', text: `${t('testFailed')}${why}` })
         }
       })
       .catch((error: unknown) => {
-        setStatus({ kind: 'error', text: `${t('testFailed')}${error instanceof Error ? error.message : ''}` })
+        setStatus({
+          kind: 'error',
+          text: `${t('testFailed')}${error instanceof Error ? error.message : ''}`,
+        })
       })
       .finally(() => setTesting(false))
   }
@@ -231,58 +251,155 @@ export function NotifyEmailCard(props: CardProps): ReactElement | null {
       </button>
       {open ? (
         <div className="dne-body">
-          {disabled ? <p className="dne-readOnly" role="status">{t('readOnly')}</p> : null}
-          <CheckRow id="dne-enabled" label={t('enabled')} checked={draft.enabled} disabled={disabled}
-            onEdit={(v) => edit('enabled', v)} />
-          <TextField id="dne-host" label={t('host')} hint={t('hostHint')} value={draft.host}
-            disabled={disabled} onEdit={(v) => edit('host', v)} />
-          <TextField id="dne-port" label={t('port')} hint={t('portHint')} value={draft.port} numeric
-            disabled={disabled} invalid={!isPositiveInt(draft.port)} invalidLabel={t('invalidNumber')}
-            onEdit={(v) => edit('port', v)} />
-          <CheckRow id="dne-secure" label={t('secure')} checked={draft.secure} disabled={disabled}
-            onEdit={(v) => edit('secure', v)} />
-          <TextField id="dne-user" label={t('user')} hint={t('userHint')} value={draft.user}
-            disabled={disabled} onEdit={(v) => edit('user', v)} />
-          <TextField id="dne-pass" label={t('pass')} hint={t('passHint')} value={draft.pass} password
+          {disabled ? (
+            <p className="dne-readOnly" role="status">
+              {t('readOnly')}
+            </p>
+          ) : null}
+          <CheckRow
+            id="dne-enabled"
+            label={t('enabled')}
+            checked={draft.enabled}
+            disabled={disabled}
+            onEdit={(v) => edit('enabled', v)}
+          />
+          <TextField
+            id="dne-host"
+            label={t('host')}
+            hint={t('hostHint')}
+            value={draft.host}
+            disabled={disabled}
+            onEdit={(v) => edit('host', v)}
+          />
+          <TextField
+            id="dne-port"
+            label={t('port')}
+            hint={t('portHint')}
+            value={draft.port}
+            numeric
+            disabled={disabled}
+            invalid={!isPositiveInt(draft.port)}
+            invalidLabel={t('invalidNumber')}
+            onEdit={(v) => edit('port', v)}
+          />
+          <CheckRow
+            id="dne-secure"
+            label={t('secure')}
+            checked={draft.secure}
+            disabled={disabled}
+            onEdit={(v) => edit('secure', v)}
+          />
+          <TextField
+            id="dne-user"
+            label={t('user')}
+            hint={t('userHint')}
+            value={draft.user}
             disabled={disabled}
-            badge={{ text: passConfigured ? t('passSet') : t('passUnset'), set: passConfigured }}
-            onEdit={(v) => edit('pass', v)} />
-          <TextField id="dne-from" label={t('from')} hint={t('fromHint')} value={draft.from}
-            disabled={disabled} onEdit={(v) => edit('from', v)} />
-          <TextField id="dne-to" label={t('to')} hint={t('toHint')} value={draft.toText}
-            disabled={disabled} onEdit={(v) => edit('toText', v)} />
+            onEdit={(v) => edit('user', v)}
+          />
+          <TextField
+            id="dne-pass"
+            label={t('pass')}
+            hint={t('passHint')}
+            value={draft.pass}
+            password
+            disabled={disabled}
+            badge={{
+              text: passConfigured ? t('passSet') : t('passUnset'),
+              set: passConfigured,
+            }}
+            onEdit={(v) => edit('pass', v)}
+          />
+          <TextField
+            id="dne-from"
+            label={t('from')}
+            hint={t('fromHint')}
+            value={draft.from}
+            disabled={disabled}
+            onEdit={(v) => edit('from', v)}
+          />
+          <TextField
+            id="dne-to"
+            label={t('to')}
+            hint={t('toHint')}
+            value={draft.toText}
+            disabled={disabled}
+            onEdit={(v) => edit('toText', v)}
+          />
           <p className="dne-groupLabel">{t('triggerGroup')}</p>
           {TRIGGER_KEYS.map((key) => (
-            <CheckRow key={key} id={`dne-${key}`} label={t(key)} checked={draft.triggers[key]}
-              disabled={disabled} onEdit={(v) => editTrigger(key, v)} />
+            <CheckRow
+              key={key}
+              id={`dne-${key}`}
+              label={t(key)}
+              checked={draft.triggers[key]}
+              disabled={disabled}
+              onEdit={(v) => editTrigger(key, v)}
+            />
           ))}
-          <TextField id="dne-debounce" label={t('idleDebounceMs')} hint={t('idleDebounceMsHint')}
-            value={draft.idleDebounceMs} numeric disabled={disabled}
-            invalid={!isPositiveInt(draft.idleDebounceMs)} invalidLabel={t('invalidNumber')}
-            onEdit={(v) => edit('idleDebounceMs', v)} />
-          <TextField id="dne-maxchars" label={t('maxBodyChars')} hint={t('maxBodyCharsHint')}
-            value={draft.maxBodyChars} numeric disabled={disabled}
+          <TextField
+            id="dne-debounce"
+            label={t('idleDebounceMs')}
+            hint={t('idleDebounceMsHint')}
+            value={draft.idleDebounceMs}
+            numeric
+            disabled={disabled}
+            invalid={!isPositiveInt(draft.idleDebounceMs)}
+            invalidLabel={t('invalidNumber')}
+            onEdit={(v) => edit('idleDebounceMs', v)}
+          />
+          <TextField
+            id="dne-maxchars"
+            label={t('maxBodyChars')}
+            hint={t('maxBodyCharsHint')}
+            value={draft.maxBodyChars}
+            numeric
+            disabled={disabled}
             invalid={!isPositiveInt(draft.maxBodyChars) || Number(draft.maxBodyChars) < 200}
             invalidLabel={t('invalidNumber')}
-            onEdit={(v) => edit('maxBodyChars', v)} />
-          <CheckRow id="dne-dryrun" label={t('dryRun')} checked={draft.dryRun} disabled={disabled}
-            onEdit={(v) => edit('dryRun', v)} />
+            onEdit={(v) => edit('maxBodyChars', v)}
+          />
+          <CheckRow
+            id="dne-dryrun"
+            label={t('dryRun')}
+            checked={draft.dryRun}
+            disabled={disabled}
+            onEdit={(v) => edit('dryRun', v)}
+          />
           <div className="dne-footer">
             {status.kind !== 'idle' ? (
-              <p className={`dne-status${status.kind === 'error' ? ' dne-statusError' : ''}`} role="status">
+              <p
+                className={`dne-status${status.kind === 'error' ? ' dne-statusError' : ''}`}
+                role="status"
+              >
                 {status.text}
               </p>
             ) : null}
-            <button type="button" className="dne-btn dne-btnGhost" disabled={testing}
-              onClick={onTest}>
+            <button
+              type="button"
+              className="dne-btn dne-btnGhost"
+              disabled={testing}
+              onClick={onTest}
+            >
               {t(testing ? 'testing' : 'test')}
             </button>
-            <button type="button" className="dne-btn dne-btnGhost" disabled={!dirty || saving}
-              onClick={() => { setDraft(draftFromValue(value)); setStatus(IDLE_STATUS) }}>
+            <button
+              type="button"
+              className="dne-btn dne-btnGhost"
+              disabled={!dirty || saving}
+              onClick={() => {
+                setDraft(draftFromValue(value))
+                setStatus(IDLE_STATUS)
+              }}
+            >
               {t('discard')}
             </button>
-            <button type="button" className="dne-btn dne-btnPrimary" disabled={!dirty || invalid || saving || disabled}
-              onClick={onSave}>
+            <button
+              type="button"
+              className="dne-btn dne-btnPrimary"
+              disabled={!dirty || invalid || saving || disabled}
+              onClick={onSave}
+            >
               {t(saving ? 'saving' : 'save')}
             </button>
           </div>

package/src/client/client.ts

@@ -63,7 +63,12 @@ interface ClientContext {
  * （loopback 或 tailnet 信任域名）下行为一致。
  */
 function createApiScope(api: SettingsApi, ns: string, c: ClientContext): Scope {
-  let state: ScopeSnapshot = { status: 'loading', value: undefined, revision: undefined, writable: false }
+  let state: ScopeSnapshot = {
+    status: 'loading',
+    value: undefined,
+    revision: undefined,
+    writable: false,
+  }
   const listeners = new Set<() => void>()
   let generation = 0
   const publish = (next: ScopeSnapshot): void => {
@@ -72,7 +77,7 @@ function createApiScope(api: SettingsApi, ns: string, c: ClientContext): Scope {
   }
   const load = async (): Promise<void> => {
     const gen = ++generation
-    let response
+    let response: Awaited<ReturnType<SettingsApi['describe']>>
     try {
       response = await api.describe({})
     } catch {
@@ -82,10 +87,20 @@ function createApiScope(api: SettingsApi, ns: string, c: ClientContext): Scope {
     const writable = response.result.value?.writable ?? false
     const view = response.result.value?.namespaces.find((candidate) => candidate.ns === ns)
     if (view === undefined) {
-      publish({ status: 'unavailable', value: undefined, revision: undefined, writable })
+      publish({
+        status: 'unavailable',
+        value: undefined,
+        revision: undefined,
+        writable,
+      })
       return
     }
-    publish({ status: 'ready', value: view.value, revision: view.revision, writable })
+    publish({
+      status: 'ready',
+      value: view.value,
+      revision: view.revision,
+      writable,
+    })
   }
   const refresh = (namespace?: unknown): void => {
     if (namespace !== undefined && namespace !== ns) return
@@ -125,10 +140,7 @@ export function apply(ctx: Context): void {
     },
     'notify-email: style',
   )
-  c.effect(
-    () => c.locale.register(NS, { zh, en }),
-    'notify-email: locale',
-  )
+  c.effect(() => c.locale.register(NS, { zh, en }), 'notify-email: locale')
   const api = c.get('connection').api.settings
   const scope = createApiScope(api, SETTINGS_NS, c)
   c.slots.inject('settings.plugin.item', () =>

package/src/client/scope.ts

@@ -31,7 +31,29 @@ export interface Scope {
 
 /** connection api.settings 的 RPC 面（本插件用到的三个方法）。 */
 export interface SettingsApi {
-  describe(payload?: Record<string, never>): Promise<{ result: { ok: boolean; value?: { writable: boolean; namespaces: Array<{ ns: string; value: unknown; revision: number; secrets: Array<{ path: string[]; set: boolean }> }> }; error?: { message?: string } } }>
-  update(request: { ns: string; patch: Record<string, unknown>; expectedRevision?: number }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
-  replace(request: { ns: string; section: Record<string, unknown>; expectedRevision?: number }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
+  describe(payload?: Record<string, never>): Promise<{
+    result: {
+      ok: boolean
+      value?: {
+        writable: boolean
+        namespaces: Array<{
+          ns: string
+          value: unknown
+          revision: number
+          secrets: Array<{ path: string[]; set: boolean }>
+        }>
+      }
+      error?: { message?: string }
+    }
+  }>
+  update(request: {
+    ns: string
+    patch: Record<string, unknown>
+    expectedRevision?: number
+  }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
+  replace(request: {
+    ns: string
+    section: Record<string, unknown>
+    expectedRevision?: number
+  }): Promise<{ result: { ok: boolean; error?: { message?: string } } }>
 }