dsh-plugin-restart-notify 0.1.0

package/README.md

@@ -0,0 +1,63 @@
+# dsh-plugin-restart-notify
+
+检测到"**新构建已落地但服务器未重启**"时弹出**系统桌面通知**的 dsh web 插件（`dsh-plugin` 社区插件）。
+
+## 功能
+
+- host 半（`src/host/`）：检测 `.dsh-build/client-build-environment.json` 的写入时间晚于服务器启动时间 → 向页面注入 `__DSH_BUILD_STALE__`
+- client 半：读到 stale 标志 → 弹出系统通知「检测到新构建，请手动重启 dsh web」
+- 权限在用户首次交互时请求（浏览器要求手势）；被拒则静默
+
+## 组成
+
+| 半 | 文件 | 职责 |
+|---|---|---|
+| host | `src/host/index.ts` | 构建记录检测 + `webserver/index-inject` 注入标志 |
+| client | `src/client/index.ts` | 读标志 + 桌面通知 |
+
+## 依赖
+
+peer 依赖（npm 已发布）：
+- `@deepseek-ai/cordis`
+- `@deepseek-ai/dsh-client-locale`
+- `@deepseek-ai/dsh-client-runtime`
+- `@deepseek-ai/dsh-client-ui-slots`
+- `@deepseek-ai/dsh-host-webserver`（host 半的 index-inject 类型）
+- `@deepseek-ai/schemastery`（host 半 Config schema）
+
+## 构建
+
+```sh
+pnpm install
+pnpm run build
+```
+
+产物：`lib/index.js`（host 半）、`lib/client.js`（浏览器半）。
+
+## 挂载
+
+在 dsh profile 的 `cordis.patch.yml` 加行：
+
+```yaml
+- insert:
+    - id: restart-notify
+      name: dsh-plugin-restart-notify
+      config:
+        root: !!js process.env.DSH_REPO_ROOT   # 指向仓库根（含 .dsh-build/client-build-environment.json）
+```
+
+`root` 配置必须指向仓库根目录（构建记录所在处）。安装包/无 checkout 场景没有构建记录，检测自然跳过。
+
+## 发布
+
+```sh
+npm publish
+```
+
+GitHub 仓库添加 `dsh-plugin` 话题。
+
+## 已知限制
+
+- **仅源码 checkout 检测**：构建记录来自仓库根；无 checkout 则无信号
+- **页面加载时静态读取**：标志只在启动时读取一次；需刷新页面触发
+- **需要通知权限**：首次交互时请求；被拒则静默

package/lib/client.js

@@ -0,0 +1,110 @@
+window.__ModuleLoader__.load({
+	id: "dsh-plugin-restart-notify",
+	factory: (require) => {
+		var module = { exports: {} };
+		var exports = module.exports;
+		Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+		//#region src/client/locales.ts
+		/** `restartNotify` namespace dictionaries (the restart notification's copy). */
+		/** Simplified Chinese dictionary (the key-set source of truth). */
+		const zh = {
+			"notification.title": "检测到新构建",
+			"notification.body": "请手动重启 dsh web 并刷新页面以应用新构建。"
+		};
+		/** English dictionary, checked complete against the zh key set. */
+		const en = {
+			"notification.title": "New build detected",
+			"notification.body": "Restart dsh web and refresh to apply the new build."
+		};
+		//#endregion
+		//#region src/client/index.ts
+		/** Dictionary namespace owned by this plugin. */
+		const NS = "restartNotify";
+		/** The stale-build global injected by the plugin's host half. */
+		const BUILD_STALE_GLOBAL = "__DSH_BUILD_STALE__";
+		/** Required services: the locale seat (no slot — the notice is a notification, not UI). */
+		const inject = ["locale"];
+		/**
+		* Resolve the browser Notification constructor, or undefined where absent.
+		* The returned surface adapts the constructor: `create` wraps `new
+		* Notification(title, options)`.
+		* @returns the Notification surface when available.
+		*/
+		function browserNotification() {
+			const ctor = globalThis.Notification;
+			if (typeof ctor !== "function") return void 0;
+			const native = ctor;
+			if (typeof native.permission !== "string" || typeof native.requestPermission !== "function") return;
+			return {
+				get permission() {
+					return native.permission;
+				},
+				requestPermission: () => native.requestPermission(),
+				create: (title, options) => new native(title, options)
+			};
+		}
+		/**
+		* Raise the restart notification through the browser Notification API.
+		* Permission must already be granted.
+		* @param api - the browser Notification surface.
+		* @param title - the notification title.
+		* @param body - the notification body.
+		*/
+		function notifyRestart(api, title, body) {
+			if (api.permission !== "granted") return;
+			api.create(title, { body });
+		}
+		/**
+		* Whether the host flagged a stale build for this page load.
+		* @returns true when the host injected the stale-build flag.
+		*/
+		function buildIsStale() {
+			return globalThis[BUILD_STALE_GLOBAL] === true;
+		}
+		/**
+		* Client plugin body: when the host flags a stale build, request notification
+		* permission on the user's first interaction and raise the restart
+		* notification once granted.
+		* @param ctx - client root context.
+		*/
+		function apply(ctx) {
+			const locale = ctx.locale;
+			ctx.effect(() => locale.register(NS, {
+				zh,
+				en
+			}), "dsh-plugin-restart-notify: dictionaries");
+			if (!buildIsStale()) return;
+			const notify = browserNotification();
+			if (notify === void 0) return;
+			const t = locale.bind(NS);
+			const raise = () => {
+				if (notify.permission !== "granted") return;
+				notifyRestart(notify, t("notification.title"), t("notification.body"));
+			};
+			if (notify.permission === "granted") {
+				raise();
+				return;
+			}
+			if (notify.permission === "denied" || typeof document === "undefined") return;
+			const requestOnce = () => {
+				document.removeEventListener("pointerdown", requestOnce);
+				document.removeEventListener("keydown", requestOnce);
+				notify.requestPermission().then(() => {
+					raise();
+				});
+			};
+			document.addEventListener("pointerdown", requestOnce, { once: true });
+			document.addEventListener("keydown", requestOnce, { once: true });
+		}
+		//#endregion
+		exports.BUILD_STALE_GLOBAL = BUILD_STALE_GLOBAL;
+		exports.apply = apply;
+		exports.browserNotification = browserNotification;
+		exports.buildIsStale = buildIsStale;
+		exports.inject = inject;
+		exports.notifyRestart = notifyRestart;
+		return module.exports;
+	}
+});
+
+//# sourceMappingURL=client.js.map

package/lib/index.js

@@ -0,0 +1,52 @@
+import { existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+import z from "@deepseek-ai/schemastery";
+//#region lib/types/host/index.js
+/**
+* Host half of dsh-plugin-restart-notify: detects when a rebuild landed that
+* this running server has not loaded, and injects the `__DSH_BUILD_STALE__`
+* global into the served index so the browser half can raise a restart
+* notification. This replaces the harness-internal detection so the plugin
+* is self-contained; install this package and add its host entry to the
+* profile cordis.yml alongside the client row.
+*/
+/** Global the browser half reads to show the restart notice. */
+const BUILD_STALE_GLOBAL = "__DSH_BUILD_STALE__";
+/** Repository-relative build record written by every complete `pnpm run build`. */
+const BUILD_RECORD_PATH = ".dsh-build/client-build-environment.json";
+/** Services required: the web server's index injection seat. */
+const inject = ["webServer"];
+/** Validate the plugin config. */
+const Config = z.object({ root: z.string() });
+/**
+* The index injection signaling a stale build: when the build record was
+* written after this server started, a complete build landed on disk that
+* this process has not loaded. Absent a record no injection is produced.
+* @param root - repository root whose build record is consulted.
+* @param startedAt - server start time in epoch milliseconds.
+* @returns the global injection, or undefined when no stale build exists.
+*/
+function buildStaleInjection(root, startedAt) {
+	const recordPath = join(root, BUILD_RECORD_PATH);
+	if (!existsSync(recordPath)) return void 0;
+	return statSync(recordPath).mtimeMs > startedAt ? {
+		kind: "global",
+		name: BUILD_STALE_GLOBAL,
+		value: true
+	} : void 0;
+}
+/**
+* Mount the stale-build detection: consult the build record against this
+* process's start time and inject the flag on every served index.
+* @param ctx - Host context carrying the webServer service.
+* @param config - plugin config (repository root).
+*/
+function apply(ctx, config) {
+	const startedAt = Date.now();
+	ctx.on("webserver/index-inject", (table) => {
+		const stale = buildStaleInjection(config.root, startedAt);
+		if (stale !== void 0) table.push(stale);
+	});
+}
+//#endregion
+export { BUILD_STALE_GLOBAL, Config, apply, buildStaleInjection, inject };

package/lib/types/client/index.d.ts

@@ -0,0 +1,59 @@
+/**
+ * Restart-notify surface plugin, browser half: when the host flags a stale
+ * build (`window.__DSH_BUILD_STALE__`, injected by this plugin's host half),
+ * raise a system desktop notification telling the user to restart dsh web.
+ * Permission is requested on the user's first interaction (browsers require
+ * a gesture); a denied permission stays silent.
+ */
+import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client';
+import { type RestartNotifyKey } from './locales.js';
+export type { RestartNotifyKey } from './locales.js';
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The restart notification copy. */
+        restartNotify: RestartNotifyKey;
+    }
+}
+/** The stale-build global injected by the plugin's host half. */
+export declare const BUILD_STALE_GLOBAL = "__DSH_BUILD_STALE__";
+/** Required services: the locale seat (no slot — the notice is a notification, not UI). */
+export declare const inject: string[];
+/**
+ * The browser Notification surface narrowed to what this plugin uses, so
+ * tests can stub it and non-browser environments degrade silently.
+ */
+export interface NotificationApi {
+    readonly permission: NotificationPermission;
+    requestPermission(): Promise<NotificationPermission>;
+    create(title: string, options?: {
+        body?: string;
+    }): unknown;
+}
+/**
+ * Resolve the browser Notification constructor, or undefined where absent.
+ * The returned surface adapts the constructor: `create` wraps `new
+ * Notification(title, options)`.
+ * @returns the Notification surface when available.
+ */
+export declare function browserNotification(): NotificationApi | undefined;
+/**
+ * Raise the restart notification through the browser Notification API.
+ * Permission must already be granted.
+ * @param api - the browser Notification surface.
+ * @param title - the notification title.
+ * @param body - the notification body.
+ */
+export declare function notifyRestart(api: NotificationApi, title: string, body: string): void;
+/**
+ * Whether the host flagged a stale build for this page load.
+ * @returns true when the host injected the stale-build flag.
+ */
+export declare function buildIsStale(): boolean;
+/**
+ * Client plugin body: when the host flags a stale build, request notification
+ * permission on the user's first interaction and raise the restart
+ * notification once granted.
+ * @param ctx - client root context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,14 @@
+/** `restartNotify` namespace dictionaries (the restart notification's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'notification.title': string;
+    'notification.body': string;
+};
+/** The restartNotify namespace key union. */
+export type RestartNotifyKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'notification.title': string;
+    'notification.body': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/host/index.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Host half of dsh-plugin-restart-notify: detects when a rebuild landed that
+ * this running server has not loaded, and injects the `__DSH_BUILD_STALE__`
+ * global into the served index so the browser half can raise a restart
+ * notification. This replaces the harness-internal detection so the plugin
+ * is self-contained; install this package and add its host entry to the
+ * profile cordis.yml alongside the client row.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import type { IndexInjection } from '@deepseek-ai/dsh-host-webserver';
+import z from '@deepseek-ai/schemastery';
+/** Global the browser half reads to show the restart notice. */
+export declare const BUILD_STALE_GLOBAL = "__DSH_BUILD_STALE__";
+/** Services required: the web server's index injection seat. */
+export declare const inject: string[];
+/** Plugin config: the repository root whose build record is consulted. */
+export interface Config {
+    /** Absolute path of the repository root carrying `.dsh-build/client-build-environment.json`. */
+    root: string;
+}
+/** Validate the plugin config. */
+export declare const Config: z<Config>;
+/**
+ * The index injection signaling a stale build: when the build record was
+ * written after this server started, a complete build landed on disk that
+ * this process has not loaded. Absent a record no injection is produced.
+ * @param root - repository root whose build record is consulted.
+ * @param startedAt - server start time in epoch milliseconds.
+ * @returns the global injection, or undefined when no stale build exists.
+ */
+export declare function buildStaleInjection(root: string, startedAt: number): IndexInjection | undefined;
+/**
+ * Mount the stale-build detection: consult the build record against this
+ * process's start time and inject the flag on every served index.
+ * @param ctx - Host context carrying the webServer service.
+ * @param config - plugin config (repository root).
+ */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * dsh-plugin-restart-notify entry: the host half that detects a stale build
+ * and injects the flag the browser half reads. Mount this package's entry
+ * (named `restart-notify`) in the profile cordis.yml with a `root` config
+ * pointing at the repository root, and add the `dsh.client` row for the
+ * browser half.
+ */
+export { apply, inject, Config, buildStaleInjection, BUILD_STALE_GLOBAL } from './host/index.js';
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "dsh-plugin-restart-notify",
+  "description": "Desktop notification for dsh web telling the user to restart after a rebuild the running server has not loaded",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/build-client.mjs",
+    "bundle": "node scripts/build-client.mjs",
+    "watch": "node scripts/build-client.mjs --watch"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-runtime": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-client-ui-slots": "0.1.1-rc.2",
+    "@deepseek-ai/dsh-host-webserver": "0.1.1-rc.2",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3",
+    "tsdown": "^0.22.2"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "keywords": ["dsh-plugin", "deepseek-harness", "restart", "notification"]
+}