deepseek-harness-background 0.2.0

package/lib/index.js

@@ -0,0 +1,540 @@
+import { settingsNamespace } from "@deepseek-ai/dsh-settings";
+import z from "@deepseek-ai/schemastery";
+import { randomBytes } from "node:crypto";
+import { existsSync, mkdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from "node:fs";
+import { extname, join } from "node:path";
+import { homedir } from "node:os";
+//#region src/settings.ts
+/** Durable background settings — pure constants/types shared by both halves. */
+/** Settings namespace owned by the background plugin. */
+const BACKGROUND_SETTINGS_NAMESPACE = "ui-background";
+/**
+* The schema's field names, in schema order. Used as a whitelist when a
+* section write commits: the settings layer keeps unknown keys in the user
+* document (a legacy schema field would linger forever under a merge-only
+* write), so the write path strips everything outside this list.
+*/
+const BACKGROUND_SETTINGS_FIELDS = [
+	"enabled",
+	"uploadId",
+	"url",
+	"opacity",
+	"scrim",
+	"panelOpacity",
+	"blur",
+	"wallpaperBlur",
+	"fit"
+];
+/** Browser-facing base path of the background API (shared with the host routes). */
+const BACKGROUND_API_PREFIX = "/api/bg-wallpaper";
+/** Minimum scrim opacity (0 = no veil at all). */
+const SCRIM_MIN = 0;
+/** Maximum scrim opacity (a nearly opaque veil keeps text legible over any art). */
+const SCRIM_MAX = .95;
+/** Default scrim strength applied over user art (a light readability veil). */
+const DEFAULT_SCRIM = .25;
+/** Default background image opacity (1 = fully opaque). */
+const DEFAULT_OPACITY = 1;
+/** Minimum background image opacity (0 = fully invisible). */
+const OPACITY_MIN = 0;
+/** Maximum background image opacity (1 = fully opaque). */
+const OPACITY_MAX = 1;
+/** Default panel opacity (0..1); 1 = fully opaque official surfaces, 0 = fully transparent glass. */
+const DEFAULT_PANEL_OPACITY = .15;
+/** Default background rendering mode. */
+const DEFAULT_FIT = "cover";
+/** Image positioning modes. `cover` fills the frame (cropping as needed); `contain` fits the whole image inside the frame (letterboxing). */
+const FIT_MODES = ["cover", "contain"];
+//#endregion
+//#region src/schema.ts
+/** Host-side schema for the `ui-background` settings namespace. */
+/**
+* Durable background section; also the wire envelope the browser scope
+* validates against. `uploadId` and `url` name the two exclusive sources; the
+* schema stays structural (no trim/transform — a function callback would break
+* the schema's toJSON wire serialization).
+*/
+const BackgroundSettingsSchema = z.object({
+	enabled: z.boolean().default(false),
+	/** Content-addressed local upload id or empty. */
+	uploadId: z.string().default(""),
+	/** Image URL or empty (mutually exclusive with uploadId at runtime). */
+	url: z.string().default(""),
+	opacity: z.number().min(0).max(1).default(1),
+	scrim: z.number().min(0).max(SCRIM_MAX).default(DEFAULT_SCRIM),
+	panelOpacity: z.number().min(0).max(1).default(DEFAULT_PANEL_OPACITY),
+	blur: z.number().min(0).max(40).default(16),
+	wallpaperBlur: z.number().min(0).max(60).default(0),
+	fit: z.union([...FIT_MODES]).default(DEFAULT_FIT)
+});
+//#endregion
+//#region src/harness-home.ts
+/**
+* Harness-home resolution — where the uploaded wallpaper images live.
+*
+* Mirrors the dsh launcher's precedence (see apps/cli reference and the
+* skin-center harness-home.ts in dsh-web-ui): an explicit `--home`-formatted
+* override, else `$DSH_HOME`, else `<homedir>/.dsh`. Kept as a tiny pure
+* function so the host half needs no out-of-tree dependency on the internal
+* home-paths package.
+*/
+/** First non-blank string in a candidate list, else undefined. */
+function firstNonBlank(...values) {
+	for (const value of values) if (typeof value === "string" && value.trim() !== "") return value.trim();
+}
+/**
+* Resolve the harness home (the directory containing `profiles/`): explicit
+* override wins, then `$DSH_HOME`, then `~/.dsh`.
+* @param env - environment (defaults to process.env).
+* @returns the absolute harness home directory.
+*/
+function resolveHarnessHome(env = process.env) {
+	return firstNonBlank(env.DSH_HOME) ?? join(homedir(), ".dsh");
+}
+/** Subdirectory under the harness home that this plugin owns. */
+const PLUGIN_HOME_REL = join("deepseek-harness-background");
+//#endregion
+//#region src/routes.ts
+/**
+* Host HTTP routes for the background plugin — the browser half talks to the
+* host through plain same-origin endpoints (no settings RPC involved, so the
+* api-proxy's settings allowlist cannot shadow the namespace). The section
+* still lives in the official settings document: reads/writes go through
+* `ctx.settings` in-process, which the allowlist only gates at the RPC
+* boundary.
+*
+* Route family (`/api/bg-wallpaper`):
+*   GET  /settings        read the section
+*   POST /settings        write the section (cross-site fenced)
+*   POST /upload          accept an uploaded image body, store it under the
+*                         harness home, return its content-addressed url
+*   GET  /image/<id>      serve a stored upload (path-escape fenced)
+*
+* Same pattern as dsh-web-ui's `/api/skin-center` and `/api/pet` families.
+*/
+/** Resolved section when the stored document has no user layer. */
+const DEFAULTS = {
+	enabled: false,
+	uploadId: "",
+	url: "",
+	opacity: 1,
+	scrim: DEFAULT_SCRIM,
+	panelOpacity: DEFAULT_PANEL_OPACITY,
+	blur: 16,
+	wallpaperBlur: 0,
+	fit: DEFAULT_FIT
+};
+/** Keep only the schema's known fields (see BACKGROUND_SETTINGS_FIELDS). */
+function pickKnown(section) {
+	const out = {};
+	const src = section;
+	for (const key of BACKGROUND_SETTINGS_FIELDS) if (key in src) out[key] = src[key];
+	return out;
+}
+/** Accepted upload MIME type → file extension. */
+const ACCEPTED_TYPES = {
+	"image/jpeg": "jpg",
+	"image/png": "png",
+	"image/webp": "webp",
+	"image/gif": "gif"
+};
+/** Numeric knob bounds — same ranges as the schema, duplicated here so the
+* POST route can reject out-of-range numbers before they reach the schema's
+* JSON layer (that layer runs `Number(...)` on string inputs, which silently
+* coerces e.g. `"2"` into `2` instead of rejecting the body). */
+const NUM_BOUNDS = {
+	opacity: {
+		min: 0,
+		max: 1
+	},
+	scrim: {
+		min: 0,
+		max: SCRIM_MAX
+	},
+	panelOpacity: {
+		min: 0,
+		max: 1
+	},
+	blur: {
+		min: 0,
+		max: 40
+	},
+	wallpaperBlur: {
+		min: 0,
+		max: 60
+	}
+};
+/** Magic-byte signatures for the accepted formats (first bytes). */
+function sniffImage(bytes) {
+	if (bytes.length >= 3 && bytes[0] === 255 && bytes[1] === 216 && bytes[2] === 255) return "jpg";
+	if (bytes.length >= 8 && bytes[0] === 137 && bytes[1] === 80 && bytes[2] === 78 && bytes[3] === 71 && bytes[4] === 13 && bytes[5] === 10 && bytes[6] === 26 && bytes[7] === 10) return "png";
+	if (bytes.length >= 12 && bytes[0] === 82 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 70 && bytes[8] === 87 && bytes[9] === 69 && bytes[10] === 66 && bytes[11] === 80) return "webp";
+	if (bytes.length >= 6 && bytes[0] === 71 && bytes[1] === 73 && bytes[2] === 70 && bytes[3] === 56) return "gif";
+	return null;
+}
+/** Per-upload size cap (20 MiB). */
+const MAX_UPLOAD_BYTES = 20971520;
+/** A stored upload id is `<up-` + hex + `>`; the on-disk file appends its extension. */
+function isUploadId(id) {
+	return /^up-[a-f0-9]+$/.test(id);
+}
+/** One JSON response. */
+function json(res, status, body) {
+	res.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+	res.end(JSON.stringify(body));
+}
+/** Require the method or answer 405. */
+function requireMethod(req, res, method) {
+	if (req.method === method) return true;
+	json(res, 405, {
+		ok: false,
+		error: "method-not-allowed"
+	});
+	return false;
+}
+/**
+* Same-origin fence. Browsers send `Sec-Fetch-Site` on every fetch; a
+* cross-site fetch is always rejected, and an `Origin` that does not match
+* the request `Host` is rejected. Requests without either header (curl, node
+* http) pass — this is a local single-user tool, and the fence only targets
+* the cross-site browser vector.
+*/
+function isSameOriginRequest(req) {
+	const site = req.headers["sec-fetch-site"];
+	if (typeof site === "string" && site === "cross-site") return false;
+	const origin = req.headers.origin;
+	if (typeof origin === "string" && origin !== "" && origin !== "null") {
+		const host = req.headers.host;
+		if (typeof host !== "string" || host === "") return false;
+		try {
+			return new URL(origin).host === host;
+		} catch {
+			return false;
+		}
+	}
+	return true;
+}
+/** Read the raw request body (bounded; rejects without destroying the socket
+* so the caller can still write a clean error response). */
+function readRawBody(req, limit) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let size = 0;
+		let tooLarge = false;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > limit) {
+				tooLarge = true;
+				req.pause();
+				reject(/* @__PURE__ */ new Error("body-too-large"));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		req.on("end", () => {
+			if (tooLarge) return;
+			resolve(Buffer.concat(chunks));
+		});
+		req.on("error", reject);
+	});
+}
+/** Read the request body as JSON (bounded; rejects without destroying the socket). */
+function readJsonBody(req) {
+	return new Promise((resolve, reject) => {
+		const parts = [];
+		let size = 0;
+		let tooLarge = false;
+		req.on("data", (chunk) => {
+			size += chunk.length;
+			if (size > 65536) {
+				tooLarge = true;
+				req.pause();
+				reject(/* @__PURE__ */ new Error("body-too-large"));
+				return;
+			}
+			parts.push(chunk);
+		});
+		req.on("end", () => {
+			if (tooLarge) return;
+			try {
+				const text = Buffer.concat(parts).toString("utf8");
+				resolve(text === "" ? {} : JSON.parse(text));
+			} catch {
+				reject(/* @__PURE__ */ new Error("invalid-json"));
+			}
+		});
+		req.on("error", reject);
+	});
+}
+/**
+* Validate a client-posted section body. Returns an error code when the body
+* must be rejected, or null when it may be written. Beyond shape checks this
+* enforces the section's exclusivity contract (`uploadId` and `url` are
+* alternative sources — at most one may be set) and that a referenced upload
+* actually exists on disk, so a stale id cannot render a blank backdrop.
+* @param body - the parsed JSON body.
+* @param home - the plugin home used to resolve upload ids (tests inject a surrogate).
+* @returns an error code, or null when the body is acceptable.
+*/
+function validateSectionBody(body, home) {
+	const url = body.url;
+	const uploadId = body.uploadId;
+	if (url !== void 0) {
+		if (typeof url !== "string" || url.length > 4096 || url !== "" && !/^https?:\/\//i.test(url)) return "invalid-url";
+	}
+	if (uploadId !== void 0) {
+		if (typeof uploadId !== "string" || uploadId !== "" && !isUploadId(uploadId)) return "invalid-upload-id";
+		if (uploadId !== "" && typeof url === "string" && url !== "") return "mutually-exclusive-source";
+		if (uploadId !== "" && uploadPath(uploadId, home) === "") return "upload-not-found";
+	}
+	for (const [key, { min, max }] of Object.entries(NUM_BOUNDS)) {
+		const raw = body[key];
+		if (raw === void 0) continue;
+		if (typeof raw !== "number" || !Number.isFinite(raw) || raw < min || raw > max) return "invalid-range";
+	}
+	return null;
+}
+/**
+* The directory this plugin owns under the harness home. `homeOverride`
+* injects a surrogate for tests; default resolves via process.env.
+*/
+function pluginHome(homeOverride) {
+	return join(homeOverride ?? resolveHarnessHome(), PLUGIN_HOME_REL);
+}
+/** Ensure and return the uploads directory. */
+function ensurePluginHome(homeOverride) {
+	const dir = pluginHome(homeOverride);
+	mkdirSync(dir, { recursive: true });
+	return dir;
+}
+/**
+* Stores a validated image body under the plugin home, content-addressed by a
+* fresh random id. Returns the id and the browser-facing url.
+*/
+function storeUpload(bytes, mime, homeOverride) {
+	const declaredExt = ACCEPTED_TYPES[mime];
+	const sniffed = sniffImage(bytes);
+	if (declaredExt === void 0 || sniffed === null || declaredExt !== sniffed) throw new Error("unsupported-or-mismatched-image");
+	if (bytes.length > MAX_UPLOAD_BYTES) throw new Error("upload-too-large");
+	const id = "up-" + randomBytes(12).toString("hex");
+	const dir = ensurePluginHome(homeOverride);
+	writeFileSync(join(dir, `${id}.${sniffed}`), bytes);
+	return {
+		id,
+		url: `${BACKGROUND_API_PREFIX}/image/${id}`
+	};
+}
+/** Resolve an upload id to its on-disk path (or "" if invalid / missing). */
+function uploadPath(id, homeOverride) {
+	if (!isUploadId(id)) return "";
+	const dir = ensurePluginHome(homeOverride);
+	for (const ext of [
+		"jpg",
+		"jpeg",
+		"png",
+		"webp",
+		"gif"
+	]) {
+		const candidate = join(dir, `${id}.${ext}`);
+		if (existsSync(candidate)) return candidate;
+	}
+	return "";
+}
+/**
+* Delete one stored upload file. Missing files are ignored; only well-formed
+* upload ids reach the disk (the same path-escape fence as uploadPath).
+*/
+function deleteUploadFile(id, homeOverride) {
+	if (!isUploadId(id)) return;
+	const abs = uploadPath(id, homeOverride);
+	if (abs === "") return;
+	try {
+		unlinkSync(abs);
+	} catch {}
+}
+/** MIME for a stored file path. */
+function mimeForPath(path) {
+	const ext = extname(path).slice(1);
+	if (ext === "jpg" || ext === "jpeg") return "image/jpeg";
+	if (ext === "png") return "image/png";
+	if (ext === "webp") return "image/webp";
+	if (ext === "gif") return "image/gif";
+}
+/** One background API route family over the settings provider + home. */
+function makeBackgroundRoutes(settings, opts = {}) {
+	const readSection = () => {
+		const section = settings.get(BACKGROUND_SETTINGS_NAMESPACE);
+		return {
+			...DEFAULTS,
+			...section
+		};
+	};
+	return [
+		{
+			kind: "exact",
+			path: `${BACKGROUND_API_PREFIX}/settings`,
+			handler: async (req, res) => {
+				if (!isSameOriginRequest(req)) {
+					json(res, 403, {
+						ok: false,
+						error: "cross-site-request-rejected"
+					});
+					return;
+				}
+				if (req.method === "GET") {
+					json(res, 200, {
+						ok: true,
+						value: readSection()
+					});
+					return;
+				}
+				if (req.method === "POST") {
+					try {
+						const before = readSection();
+						const body = await readJsonBody(req);
+						const validationError = validateSectionBody(body, opts.home);
+						if (validationError !== null) {
+							json(res, 400, {
+								ok: false,
+								error: validationError
+							});
+							return;
+						}
+						const merged = {
+							...pickKnown(readSection()),
+							...pickKnown(body)
+						};
+						await settings.replace(BACKGROUND_SETTINGS_NAMESPACE, merged);
+						const after = readSection();
+						if (before.uploadId !== "" && before.uploadId !== after.uploadId) deleteUploadFile(before.uploadId, opts.home);
+						json(res, 200, {
+							ok: true,
+							value: after
+						});
+					} catch (error) {
+						json(res, 400, {
+							ok: false,
+							error: error instanceof Error ? error.message : String(error)
+						});
+					}
+					return;
+				}
+				json(res, 405, {
+					ok: false,
+					error: "method-not-allowed"
+				});
+			}
+		},
+		{
+			kind: "exact",
+			path: `${BACKGROUND_API_PREFIX}/upload`,
+			handler: async (req, res) => {
+				if (!isSameOriginRequest(req)) {
+					json(res, 403, {
+						ok: false,
+						error: "cross-site-request-rejected"
+					});
+					return;
+				}
+				if (!requireMethod(req, res, "POST")) return;
+				const mime = req.headers["content-type"]?.split(";")[0]?.trim() ?? "";
+				if (!ACCEPTED_TYPES[mime]) {
+					json(res, 400, {
+						ok: false,
+						error: "unsupported-media-type"
+					});
+					return;
+				}
+				if (req.readableAborted || req.destroyed) {
+					json(res, 400, {
+						ok: false,
+						error: "request-aborted"
+					});
+					return;
+				}
+				try {
+					const body = await readRawBody(req, 20971521);
+					if (body.length === 0) {
+						json(res, 400, {
+							ok: false,
+							error: "empty-body"
+						});
+						return;
+					}
+					const { id, url } = storeUpload(body, mime, opts.home);
+					json(res, 200, {
+						ok: true,
+						id,
+						url
+					});
+				} catch (error) {
+					json(res, 400, {
+						ok: false,
+						error: error instanceof Error ? error.message : String(error)
+					});
+				}
+			}
+		},
+		{
+			kind: "prefix",
+			path: `${BACKGROUND_API_PREFIX}/image`,
+			handler: (req, res) => {
+				if (!isSameOriginRequest(req)) {
+					json(res, 403, {
+						ok: false,
+						error: "cross-site-request-rejected"
+					});
+					return;
+				}
+				if (!requireMethod(req, res, "GET")) return;
+				const rawPath = new URL(req.url ?? "/", "http://x").pathname;
+				const abs = uploadPath(rawPath.startsWith(`/api/bg-wallpaper/image/`) ? decodeURIComponent(rawPath.slice(`${BACKGROUND_API_PREFIX}/image/`.length)) : "", opts.home);
+				if (abs === "") {
+					json(res, 404, {
+						ok: false,
+						error: "not-found"
+					});
+					return;
+				}
+				try {
+					const data = readFileSync(abs);
+					const mime = mimeForPath(abs) ?? "application/octet-stream";
+					const stat = statSync(abs);
+					res.writeHead(200, {
+						"content-type": mime,
+						"content-length": String(data.length),
+						"last-modified": stat.mtime.toUTCString(),
+						"cache-control": "public, max-age=31536000, immutable"
+					});
+					res.end(data);
+				} catch {
+					json(res, 404, {
+						ok: false,
+						error: "not-found"
+					});
+				}
+			}
+		}
+	];
+}
+//#endregion
+//#region src/index.ts
+const BACKGROUND_NAMESPACE = settingsNamespace(BACKGROUND_SETTINGS_NAMESPACE);
+/**
+* Register the durable background section and its API routes when the Host
+* settings/webServer services are composed. Effect timing is `live`: the
+* browser half repaints through the route without a restart.
+* @param ctx - Host context that may acquire the settings and webServer services.
+*/
+function apply(ctx) {
+	ctx.inject(["settings", "webServer"], (hostCtx) => {
+		hostCtx.settings.register(BACKGROUND_NAMESPACE, BackgroundSettingsSchema, { applies: "live" });
+		try {
+			for (const route of makeBackgroundRoutes(hostCtx.settings)) hostCtx.effect(() => hostCtx.webServer.register(route), "deepseek-harness-background: settings route");
+		} catch (error) {
+			console.error("[deepseek-harness-background] route registration failed:", error);
+		}
+	});
+}
+//#endregion
+export { BACKGROUND_API_PREFIX, BACKGROUND_SETTINGS_NAMESPACE, BackgroundSettingsSchema, DEFAULT_FIT, DEFAULT_OPACITY, DEFAULT_PANEL_OPACITY, DEFAULT_SCRIM, FIT_MODES, OPACITY_MAX, OPACITY_MIN, PLUGIN_HOME_REL, SCRIM_MAX, SCRIM_MIN, apply, makeBackgroundRoutes, resolveHarnessHome };

package/package.json

@@ -0,0 +1,88 @@
+{
+  "name": "deepseek-harness-background",
+  "description": "Custom background image plugin for the DeepSeek Harness web GUI: upload a local picture or paste an image URL, and render it behind the whole app surface with adjustable opacity, scrim, panel transparency and frosted-glass blur.",
+  "version": "0.2.0",
+  "keywords": [
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "dsh-plugin",
+    "theme",
+    "wallpaper",
+    "background",
+    "web-ui"
+  ],
+  "author": "HaoyueQin",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HaoyueQin/deepseek-harness-background.git"
+  },
+  "homepage": "https://github.com/HaoyueQin/deepseek-harness-background",
+  "packageManager": "pnpm@11.9.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web"
+    }
+  },
+  "scripts": {
+    "build": "tsdown",
+    "prepare": "tsdown",
+    "watch": "tsdown --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "license": "MIT",
+  "files": [
+    "lib",
+    "cordis.patch.yml",
+    "README.md",
+    "README.zh.md"
+  ],
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
+    "react": "^18.2.0"
+  },
+  "dependencies": {
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-host-webserver": "^0.1.0-rc.8",
+    "@deepseek-ai/dsh-settings": "^0.1.0-rc.8",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "clsx": "^2.1.1",
+    "jsdom": "^29.1.1",
+    "lightningcss": "^1.33.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "tsdown": "^0.22.14",
+    "typescript": "^5.8.0",
+    "vitest": "^4.1.8"
+  }
+}