@eduwork/dsh-mail 0.1.0-alpha.5 → 0.1.0

package/docs/getting-started.md

@@ -5,8 +5,8 @@
 ## 前置条件
 
 - Node.js 22+；
-- DeepSeek Harness `0.1.2-alpha.2`；
-- Profile 中已经有 Settings、Credentials、Tools、Filesystem、Approval 和 Web Client；
+- DeepSeek Harness `0.1.2-rc.1`；
+- Profile 中已经有 Settings、Credentials、Tools、Filesystem、Permission Presets、Approval 和 Web Client；
 - 一个开启了 IMAP/SMTP 的邮箱账号，以及邮箱服务商签发的客户端授权码或应用专用密码。
 
 ## 安装
@@ -14,7 +14,7 @@
 普通使用固定经过复核的 npm 精确版本：
 
 ```bash
-dsh plugin --profile web add @eduwork/dsh-mail@0.1.0-alpha.5
+dsh plugin --profile web add @eduwork/dsh-mail@0.1.0
 ```
 
 需要审计、开发或验证尚未发布的改动时，使用源码 checkout：
@@ -29,7 +29,7 @@ dsh plugin --profile web add .
 
 安装只向 Profile 加入一个 Bundle。插件配置为空也能正常启动；不会在启动时探测服务器或安装额外运行时。
 
-源码安装会把 checkout 链接进 Profile，因此目录必须持续存在。团队部署应固定 npm 精确版本；只有明确希望持续跟随预发布更新时才使用 `@eduwork/dsh-mail@alpha`。
+源码安装会把 checkout 链接进 Profile，因此目录必须持续存在。团队部署应固定经复核的 npm 精确版本。
 
 ## 配置
 

package/docs/release-checklist.en.md

@@ -2,11 +2,11 @@
 
 [简体中文](release-checklist.md) | **English**
 
-A release pull request records reviewers, date, command-output links, and exceptions. Every item blocks a stable release; an alpha release must complete all applicable items and state remaining risk.
+A release pull request or release record captures the maintainer decision, date, command-output links, independent technical-review evidence, and exceptions. A sole maintainer owns publication during the project's initial stage; do not invent a second human approver who does not exist. Any applicable incomplete security or publication check blocks a stable release. Additional maintainers and multi-person review remain future governance goals.
 
 ## Authority and metadata
 
-- [ ] Repository owner approved public release and the MIT license.
+- [ ] The current maintainer approved public release and the MIT license and recorded technical-review evidence and remaining risk.
 - [ ] GitHub repository, npm name, homepage, issues, and private security-report URLs are correct.
 - [ ] Version, changelog, compatibility, and install commands agree.
 - [ ] Chinese is the default language and every Markdown document has an English mirror with reciprocal entries.
@@ -43,9 +43,10 @@ A release pull request records reviewers, date, command-output links, and except
 
 ## Supply chain and publication
 
-- [ ] Clean `npm ci` and `npm run check` pass on Windows and Linux with Node 22.
+- [ ] Clean `npm ci` and `npm run check` pass on Windows and Linux with Node 22/24.
 - [ ] `npm audit`, CodeQL, direct/transitive licenses, and install scripts receive human review.
 - [ ] GitHub Actions use immutable commits; Dependabot and branch protection are active.
 - [ ] `npm pack --dry-run` and the extracted tarball contain only expected files; the Host bundle has no bare IMAP/SMTP imports.
 - [ ] Tag, release notes, tarball checksum, deprecation, and rollback are ready.
-- [ ] Stable publication uses npm Trusted Publishing/OIDC and provenance rather than a long-lived token.
+- [ ] Publish the first stable release from the reviewed frozen package with the npm CLI and maintainer-confirmed browser 2FA; record that Trusted Publishing is not configured and make no provenance claim for this release.
+- [ ] For later releases, enable OIDC/provenance only after verifying that npm Trusted Publishing is bound to this repository's `.github/workflows/release.yml` and environment `npm`; never use a long-lived publish token.

package/docs/release-checklist.md

@@ -2,11 +2,11 @@
 
 **简体中文** | [English](release-checklist.en.md)
 
-发布 Pull Request 应记录审查人、日期、命令输出链接和例外。任何未完成项目都会阻止稳定发布；alpha 发布也必须完成与本次改动相关的项目并明确剩余风险。
+发布 Pull Request 或发布记录应记维护者决策、日期、命令输出链接、独立技术复核证据和例外。项目初期由单一维护者负责发布；不得虚构尚不存在的第二位人工批准人。任何适用且未完成的安全或发布检查都会阻止稳定发布；未来增加替补和多人审查作为治理目标记录。
 
 ## 授权与元数据
 
-- [ ] 仓库所有者确认公开发布和 MIT 许可证。
+- [ ] 当前维护者确认公开发布和 MIT 许可证，并记录技术复核证据与剩余风险。
 - [ ] GitHub 仓库、npm 包名、主页、Issue 和安全报告地址准确。
 - [ ] 版本、Changelog、兼容性和安装命令一致。
 - [ ] 默认文档为中文，每份 Markdown 文档都有英文镜像和双向入口。
@@ -43,9 +43,10 @@
 
 ## 供应链与发布
 
-- [ ] Windows 与 Linux 使用 Node 22 完成干净 `npm ci` 和 `npm run check`。
+- [ ] Windows 与 Linux 使用 Node 22/24 完成干净 `npm ci` 和 `npm run check`。
 - [ ] `npm audit`、CodeQL、直接/间接许可证和安装脚本已人工审查。
 - [ ] GitHub Actions 固定到不可变 commit，Dependabot 与分支保护有效。
 - [ ] `npm pack --dry-run` 和解压后的 tarball 只包含预期文件；Host bundle 没有外部 IMAP/SMTP 裸导入。
 - [ ] tag、发布说明、tarball checksum、弃用和回滚方案已准备。
-- [ ] 稳定发布使用 npm Trusted Publishing/OIDC 和 provenance，不使用长期 Token。
+- [ ] 首次稳定版从经复核的冻结包使用 npm CLI 发布，由维护者在浏览器完成 2FA；本次记录 Trusted Publishing 尚未配置，不声明 provenance。
+- [ ] 后续发布在验证 npm Trusted Publisher 已绑定本仓库的 `.github/workflows/release.yml` 与 Environment `npm` 后，再启用 OIDC/provenance 发布路径；不使用长期 Token。

package/lib/client.js

@@ -33,8 +33,8 @@ window.__ModuleLoader__.load({
 		const inject = [
 			"slots",
 			"remote",
-			"remote.settings",
-			"remote.credentials"
+			"remote.credentials",
+			"settingsScope"
 		];
 		const NS = "dsh-mail-assistant";
 		const PASSWORD_REF = "DSH_MAIL_ASSISTANT_PASSWORD";
@@ -90,6 +90,8 @@ window.__ModuleLoader__.load({
 			usage: "保存后，在对话里让 Agent“查一下最近邮件”即可验证。插件不会在启动或保存时主动连接邮箱。",
 			error: "保存失败",
 			reload: "重新加载",
+			unavailable: "当前 DSH 连接未提供此设置命名空间。",
+			readOnly: "当前连接为只读模式，无法保存设置。",
 			credentialPartial: "授权码已经保存，但其他配置保存失败；请修正后再次保存。"
 		} : {
 			nav: "Mail assistant",
@@ -143,6 +145,8 @@ window.__ModuleLoader__.load({
 			usage: "After saving, ask the agent to find recent mail. The plugin never connects to a mailbox during startup or save.",
 			error: "Save failed",
 			reload: "Reload",
+			unavailable: "This DSH connection does not expose the mail settings namespace.",
+			readOnly: "This connection exposes settings in read-only mode.",
 			credentialPartial: "The app password was stored, but the remaining settings failed to save. Fix the form and save again."
 		};
 		const defaults = {
@@ -219,33 +223,37 @@ window.__ModuleLoader__.load({
 		}
 		function MailSettings({ service }) {
 			const [draft, setDraft] = (0, react.useState)(null);
-			const [revision, setRevision] = (0, react.useState)(0);
 			const [passwordConfigured, setPasswordConfigured] = (0, react.useState)(false);
+			const [credentialWritable, setCredentialWritable] = (0, react.useState)(false);
 			const [password, setPassword] = (0, react.useState)("");
 			const [busy, setBusy] = (0, react.useState)(false);
 			const [notice, setNotice] = (0, react.useState)("");
 			const [error, setError] = (0, react.useState)("");
 			const [preset, setPreset] = (0, react.useState)("custom");
 			const [advancedOpen, setAdvancedOpen] = (0, react.useState)(false);
+			const subscribe = (0, react.useMemo)(() => service.scope.subscribe.bind(service.scope), [service.scope]);
+			const getSnapshot = (0, react.useMemo)(() => service.scope.getSnapshot.bind(service.scope), [service.scope]);
+			const snapshot = (0, react.useSyncExternalStore)(subscribe, getSnapshot, getSnapshot);
 			const load = async () => {
 				setError("");
 				setNotice("");
-				const [settings, credentials] = await Promise.all([unwrap(service.settings.describe()), unwrap(service.credentials.describe([PASSWORD_REF]))]);
-				const namespace = settings.namespaces.find((candidate) => candidate.ns === NS);
-				if (!namespace) throw new Error("dsh-mail-assistant settings namespace is not available");
-				const next = {
-					...defaults,
-					...namespace.value ?? {}
-				};
-				setDraft(next);
-				setPreset(detectPreset(next));
-				setRevision(namespace.revision ?? 0);
+				const credentials = await unwrap(service.credentials.describe([PASSWORD_REF]));
 				setPasswordConfigured(credentials[PASSWORD_REF]?.configured === true);
+				setCredentialWritable(credentials[PASSWORD_REF]?.writable === true);
 				setPassword("");
 			};
 			(0, react.useEffect)(() => {
 				load().catch((cause) => setError(cause?.message || String(cause)));
 			}, []);
+			(0, react.useEffect)(() => {
+				if (snapshot.status !== "ready") return;
+				const next = {
+					...defaults,
+					...snapshot.value ?? {}
+				};
+				setDraft(next);
+				setPreset(detectPreset(next));
+			}, [snapshot]);
 			const set = (key, value) => setDraft((current) => ({
 				...current,
 				[key]: value
@@ -269,12 +277,12 @@ window.__ModuleLoader__.load({
 						setPasswordConfigured(true);
 						setPassword("");
 					}
-					const namespace = await unwrap(service.settings.replace(NS, draft, revision));
-					setDraft({
-						...defaults,
-						...namespace.value ?? draft
-					});
-					setRevision(namespace.revision ?? revision + 1);
+					const ops = Object.entries(draft).map(([field, value]) => ({
+						op: "set",
+						path: [field],
+						value
+					}));
+					await service.scope.mutate(ops, snapshot.revision);
 					setNotice(copy.saved);
 				} catch (cause) {
 					setError(passwordStored ? copy.credentialPartial : cause?.message || `${copy.error}`);
@@ -361,7 +369,7 @@ window.__ModuleLoader__.load({
 			};
 			if (!draft) return /* @__PURE__ */ (0, react_jsx_runtime.jsxs)("div", {
 				style: styles.root,
-				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: error || copy.loading }), error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
+				children: [/* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", { children: error || (snapshot.status === "unavailable" ? copy.unavailable : copy.loading) }), error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 					style: styles.button,
 					onClick: () => load(),
 					children: copy.reload
@@ -531,6 +539,7 @@ window.__ModuleLoader__.load({
 												type: "password",
 												autoComplete: "new-password",
 												value: password,
+												disabled: busy || !credentialWritable,
 												placeholder: copy.credentialPlaceholder,
 												onChange: (event) => setPassword(event.currentTarget.value),
 												style: styles.input
@@ -538,7 +547,7 @@ window.__ModuleLoader__.load({
 											/* @__PURE__ */ (0, react_jsx_runtime.jsx)("span", { children: copy.passwordHint }),
 											passwordConfigured && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 												type: "button",
-												disabled: busy,
+												disabled: busy || !credentialWritable,
 												style: {
 													...styles.button,
 													justifySelf: "start",
@@ -710,6 +719,14 @@ window.__ModuleLoader__.load({
 						},
 						children: copy.usage
 					}),
+					!snapshot.writable && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
+						role: "status",
+						style: {
+							color: colors.secondary,
+							fontSize: 12
+						},
+						children: copy.readOnly
+					}),
 					error && /* @__PURE__ */ (0, react_jsx_runtime.jsx)("p", {
 						role: "alert",
 						style: {
@@ -728,7 +745,7 @@ window.__ModuleLoader__.load({
 					}),
 					/* @__PURE__ */ (0, react_jsx_runtime.jsx)("button", {
 						type: "button",
-						disabled: busy,
+						disabled: busy || !snapshot.writable,
 						onClick: save,
 						style: styles.primary,
 						children: busy ? copy.saving : copy.save
@@ -738,7 +755,7 @@ window.__ModuleLoader__.load({
 		}
 		function apply(ctx) {
 			const service = {
-				settings: ctx.remote.settings,
+				scope: ctx.settingsScope.bind({ namespace: NS }),
 				credentials: ctx.remote.credentials
 			};
 			ctx.slots.inject("settings.section", () => ctx.slots.register({