dsh-plugin-notify-sounds 1.8.6 → 1.9.2

package/lib/index.js

@@ -4,7 +4,7 @@
  * All behavior lives in the browser entry (`./client`): the sounds themselves
  * are Web Audio synthesis, and the triggers are the Client's own
  * `uiSession.sessionStatus` facts (pending interactions and running→idle
- * transitions). This Node half owns the four things the browser cannot:
+ * transitions). This Node half owns the five things the browser cannot:
  *
  *   - the volatile Config schema below is what the Host Settings document
  *     serves under the `notify-sounds` namespace, so the Settings section the
@@ -19,7 +19,11 @@
  *     manager, so the row reports and points, and never writes a file;
  *   - `/notify-sounds/goal` answers one session's goal phase from the Host's
  *     authoritative projection. The browser only carries sessions it has
- *     opened, and a goal-mode completion edge can belong to one it has not.
+ *     opened, and a goal-mode completion edge can belong to one it has not;
+ *   - `/notify-sounds/sound` is the uploaded-sound store: the page reads a
+ *     stored clip by content hash, posts a new one, or deletes a clip nothing
+ *     references. It is the only place this plugin writes a file, and it only
+ *     ever touches its own directory under the profile.
  *
  * `apply` also asks the settings namespace to hold off any auto-generated
  * inventory page for this entry, because the Client contributes a dedicated
@@ -32,8 +36,9 @@
 
 import z from "@deepseek-ai/schemastery";
 import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
 import { createRequire } from "node:module";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
@@ -41,7 +46,7 @@ import { fileURLToPath } from "node:url";
 export const name = "notify-sounds";
 
 /** Sound ids shared with the Client half's preset table (spelled, not imported: the browser bundle is self-contained). Exported so the tests can cross-check the two spellings. */
-export const SOUND_IDS = ["bell", "chime", "ding", "drop", "pulse", "arc", "coin", "success", "knock", "custom", "none"];
+export const SOUND_IDS = ["bell", "chime", "ding", "drop", "pulse", "arc", "coin", "success", "knock", "custom1", "custom2", "custom3", "custom", "none"];
 
 /** Quiet-hours time-of-day pattern, "HH:MM". Exported for the same cross-check. */
 export const TIME_OF_DAY = /^(?:[01]\d|2[0-3]):[0-5]\d$/;
@@ -690,6 +695,167 @@ async function readCappedBytes(response, cap) {
 	return merged;
 }
 
+/**
+ * Route the page uses to read and write uploaded sounds. Exported so the
+ * tests can cross-check the Client half's spelling.
+ */
+export const SOUND_PATH = "/notify-sounds/sound";
+
+/** Largest uploaded sound accepted, in bytes. */
+export const SOUND_MAX_BYTES = 3 * 1024 * 1024;
+
+/**
+ * The only file names the sound directory may contain: a lowercase sha256 and
+ * a short extension. Anything else is refused outright rather than cleaned, so
+ * a hand-edited configuration cannot walk out of the directory.
+ */
+const SOUND_FILE_PATTERN = /^[a-f0-9]{64}\.(?:mp3|wav|ogg|m4a|flac)$/;
+
+/** Directory under the profile that holds uploaded sounds. */
+const SOUND_DIRECTORY = "notify-sounds";
+
+/** Container formats this store accepts, identified by magic bytes. */
+const SOUND_FORMATS = [
+	{ extension: "flac", mime: "audio/flac", matches: (b) => b[0] === 0x66 && b[1] === 0x4c && b[2] === 0x61 && b[3] === 0x43 },
+	{ extension: "ogg", mime: "audio/ogg", matches: (b) => b[0] === 0x4f && b[1] === 0x67 && b[2] === 0x67 && b[3] === 0x53 },
+	{
+		extension: "wav",
+		mime: "audio/wav",
+		matches: (b) => b[0] === 0x52 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x46 && b[8] === 0x57 && b[9] === 0x41 && b[10] === 0x56 && b[11] === 0x45,
+	},
+	{ extension: "m4a", mime: "audio/mp4", matches: (b) => b[4] === 0x66 && b[5] === 0x74 && b[6] === 0x79 && b[7] === 0x70 },
+	{
+		extension: "mp3",
+		mime: "audio/mpeg",
+		matches: (b) => (b[0] === 0x49 && b[1] === 0x44 && b[2] === 0x33) || (b[0] === 0xff && (b[1] & 0xe0) === 0xe0),
+	},
+];
+
+/**
+ * The uploaded-sound directory for this installation, or undefined when there
+ * is no profile (a development checkout): then nothing is stored and the page
+ * keeps using the legacy inline payload.
+ *
+ * @returns the absolute directory, or undefined.
+ */
+function soundsDirectory() {
+	const profile = profileDirectory();
+	return profile === undefined ? undefined : join(profile, SOUND_DIRECTORY, "sounds");
+}
+
+/**
+ * Resolve one stored sound by name, refusing anything that is not a plain
+ * digest-plus-extension inside the directory.
+ *
+ * @param fileName - the name the page asked for.
+ * @returns the absolute path, or undefined when the name is not one of ours.
+ */
+export function soundFilePath(fileName) {
+	if (typeof fileName !== "string" || !SOUND_FILE_PATTERN.test(fileName)) return undefined;
+	const directory = soundsDirectory();
+	return directory === undefined ? undefined : join(directory, fileName);
+}
+
+/**
+ * Write one uploaded sound and return the name it was stored under.
+ *
+ * The name is the sha256 of the bytes, so the same audio uploaded twice — or
+ * migrated twice — lands on the same file and nothing has to be reconciled.
+ * A partially written file is never visible: the bytes go to `<name>.tmp` and
+ * are renamed into place, and an existing target is left untouched because its
+ * content is by definition already identical.
+ *
+ * @param bytes - the uploaded audio.
+ * @returns the stored name, or undefined when the bytes are not audio this
+ *   store accepts (or there is no profile to store them in).
+ */
+export function writeSoundFile(bytes) {
+	try {
+		const buffer = Buffer.isBuffer(bytes) ? bytes : Buffer.from(bytes);
+		if (buffer.length === 0 || buffer.length > SOUND_MAX_BYTES) return undefined;
+		const format = SOUND_FORMATS.find((candidate) => candidate.matches(buffer));
+		if (format === undefined) return undefined;
+		const directory = soundsDirectory();
+		if (directory === undefined) return undefined;
+		const fileName = `${createHash("sha256").update(buffer).digest("hex")}.${format.extension}`;
+		const target = join(directory, fileName);
+		if (existsSync(target)) return fileName;
+		mkdirSync(directory, { recursive: true });
+		const temporary = `${target}.tmp`;
+		writeFileSync(temporary, buffer);
+		try {
+			renameSync(temporary, target);
+		} catch (error) {
+			// POSIX renames straight over an existing file; Windows refuses with
+			// EPERM/EEXIST. Two windows uploading the same bytes race here: the
+			// other one already wrote this exact content-addressed file, so a
+			// refusal is the outcome we wanted, not a failure.
+			if (existsSync(target)) {
+				rmSync(temporary, { force: true });
+				return fileName;
+			}
+			rmSync(temporary, { force: true });
+			throw error;
+		}
+		return fileName;
+	} catch (error) {
+		// A read-only profile or a full disk must not take the route down: the
+		// caller reports "not stored" and the page keeps whatever it had.
+		warn(`sound write failed: ${error?.message ?? error}`);
+		return undefined;
+	}
+}
+
+/**
+ * Delete one stored sound, ignoring a name that is not ours and a file that is
+ * already gone.
+ *
+ * @param fileName - the name to remove.
+ */
+export function deleteSoundFile(fileName) {
+	const path = soundFilePath(fileName);
+	if (path === undefined) return;
+	try {
+		rmSync(path, { force: true });
+	} catch (error) {
+		warn(`sound delete failed: ${error?.message ?? error}`);
+	}
+}
+
+
+/**
+ * The MIME type for a stored name.
+ *
+ * @param fileName - a name already accepted by `soundFilePath`.
+ * @returns the content type to serve it with.
+ */
+export function soundMimeType(fileName) {
+	const extension = fileName.slice(fileName.lastIndexOf(".") + 1);
+	return SOUND_FORMATS.find((format) => format.extension === extension)?.mime ?? "application/octet-stream";
+}
+
+/**
+ * Read a request body no larger than `limit`.
+ *
+ * The stream is abandoned the moment the cap is crossed rather than read to
+ * the end: an oversized upload is a mistake or an attack, and neither deserves
+ * the bandwidth.
+ *
+ * @param req - the incoming request.
+ * @param limit - the largest body accepted.
+ * @returns the body, or undefined when it is too large.
+ */
+async function readRequestBytes(req, limit) {
+	const chunks = [];
+	let total = 0;
+	for await (const chunk of req) {
+		total += chunk.length;
+		if (total > limit) return undefined;
+		chunks.push(chunk);
+	}
+	return Buffer.concat(chunks);
+}
+
 /**
  * The profile directory that owns this installation, when there is one.
  *
@@ -886,6 +1052,14 @@ export const Config = z.object({
 	enabled: z.boolean().default(true).volatile(),
 	/** Playback loudness in percent. */
 	volume: z.number().step(1).min(0).max(100).default(60).volatile(),
+	/**
+	 * Which loudness scale the stored `volume` speaks.
+	 *
+	 * 1.9.1 made every preset ~10 dB louder at the same number, so the page
+	 * re-scales a stored value once and sets this to 1. A config without it has
+	 * never been re-scaled, including one written by an older release.
+	 */
+	volumeRev: z.number().default(0).volatile(),
 	/** Preset played when a Session gains a pending approval or plan review. */
 	decisionSound: z.union(SOUND_IDS).default("bell").volatile(),
 	/** Preset played when a Session gains a pending question. */
@@ -898,10 +1072,42 @@ export const Config = z.object({
 	updateAutoCheck: z.boolean().default(true).volatile(),
 	/** Play only while the page is not visible (background tab or window). */
 	onlyWhenHidden: z.boolean().default(false).volatile(),
-	/** Uploaded audio for the `custom` preset, as base64; empty when none. */
+	/**
+	 * The user's own sounds: up to three, each a stored file plus the name it
+	 * is shown under. A trigger picks one by slot id (`custom1`…`custom3`).
+	 *
+	 * Slots are FIXED, not compacted: deleting the second sound leaves slot 2
+	 * empty rather than shifting slot 3 into it, so a trigger pointing at
+	 * `custom3` keeps meaning the same recording.
+	 */
+	custom1File: z.string().default("").volatile(),
+	custom1Name: z.string().default("").volatile(),
+	custom2File: z.string().default("").volatile(),
+	custom2Name: z.string().default("").volatile(),
+	custom3File: z.string().default("").volatile(),
+	custom3Name: z.string().default("").volatile(),
+	/**
+	 * Legacy inline audio (up to 1.8.6), base64; empty when none.
+	 *
+	 * Kept readable so an install that updated itself from an older release
+	 * keeps its sound: the browser migrates it into slot 1 on first run and
+	 * only then clears it. Nothing writes this field any more.
+	 */
 	customSound: z.string().default("").volatile(),
-	/** Original file name of the uploaded custom sound, for display. */
+	/** Legacy display name that belonged to `customSound`. */
 	customSoundName: z.string().default("").volatile(),
+	/** Legacy per-trigger reference from 1.9.0, migrated into the list then cleared. */
+	customDecisionFile: z.string().default("").volatile(),
+	/** Legacy display name that belonged to `customDecisionFile`. */
+	customDecisionName: z.string().default("").volatile(),
+	/** Legacy per-trigger reference from 1.9.0. */
+	customQuestionFile: z.string().default("").volatile(),
+	/** Legacy display name that belonged to `customQuestionFile`. */
+	customQuestionName: z.string().default("").volatile(),
+	/** Legacy per-trigger reference from 1.9.0. */
+	customCompletionFile: z.string().default("").volatile(),
+	/** Legacy display name that belonged to `customCompletionFile`. */
+	customCompletionName: z.string().default("").volatile(),
 	/** Show an OS notification (when the page is hidden) in addition to the sound. */
 	systemNotify: z.boolean().default(false).volatile(),
 	/** Prefix the window title with a word (待处理 / 已完成) while the page is hidden. */
@@ -1077,4 +1283,88 @@ export function apply(ctx) {
 			},
 		}), "notify-sounds: goal phase route");
 	});
+
+	// Uploaded sounds (1.9.0): the bytes live as files beside the profile, not
+	// inside the configuration, and the page asks for them by content hash.
+	//
+	// This is deliberately STATELESS: the Host does not read its own config
+	// here. Volatile config values are live cells rather than plain strings,
+	// so a Host-side read would have to unwrap them — and the browser already
+	// holds the authoritative snapshot. The page therefore names the file it
+	// wants (`?file=<sha>.<ext>`), and the Host only ever touches the one
+	// directory it owns, after checking the name against a hash pattern.
+	ctx.inject(["webServer", "connection"], (child) => {
+		child.effect(() => child.webServer.register({
+			kind: "exact",
+			path: SOUND_PATH,
+			handler: async (req, res) => {
+				const rejection = child.connection.requestRejection(req);
+				if (rejection !== undefined) {
+					res.statusCode = rejection;
+					res.end();
+					return;
+				}
+				const url = new URL(req.url ?? "/", "http://localhost");
+				try {
+					if (req.method === "GET" || req.method === "HEAD") {
+						const name = url.searchParams.get("file") ?? "";
+						const file = soundFilePath(name);
+						// Read, do not stat: one call closes the window between
+						// "the file exists" and "here are its bytes".
+						let bytes;
+						try {
+							bytes = file === undefined ? undefined : readFileSync(file);
+						} catch {
+							bytes = undefined;
+						}
+						if (bytes === undefined) {
+							res.statusCode = 404;
+							res.end();
+							return;
+						}
+						res.statusCode = 200;
+						// Content-addressed: the name IS the digest, so the bytes
+						// behind it can never change.
+						res.setHeader("cache-control", "public, max-age=31536000, immutable");
+						res.setHeader("content-type", soundMimeType(name));
+						res.setHeader("content-length", String(bytes.length));
+						res.end(req.method === "HEAD" ? undefined : bytes);
+						return;
+					}
+					if (req.method === "POST") {
+							const bytes = await readRequestBytes(req, SOUND_MAX_BYTES);
+						if (bytes === undefined) {
+							res.statusCode = 413;
+							res.end();
+							return;
+						}
+						const name = writeSoundFile(bytes);
+						if (name === undefined) {
+							res.statusCode = 415;
+							res.end();
+							return;
+						}
+						res.statusCode = 200;
+						res.setHeader("content-type", "application/json");
+						res.end(JSON.stringify({ file: name }));
+						return;
+					}
+					if (req.method === "DELETE") {
+						const name = url.searchParams.get("file") ?? "";
+						deleteSoundFile(name);
+						res.statusCode = 204;
+						res.end();
+						return;
+					}
+					res.statusCode = 405;
+					res.setHeader("allow", "GET, POST, DELETE");
+					res.end();
+				} catch (error) {
+					warn(`sound store failed: ${error?.message ?? error}`);
+					res.statusCode = 500;
+					res.end();
+				}
+			},
+		}), "notify-sounds: sound store route");
+	});
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-plugin-notify-sounds",
-  "version": "1.8.6",
+  "version": "1.9.2",
   "description": "DeepSeek Harness 原生风格提示音插件：需要决策或任务完成时播放提示音，点击系统通知可回到窗口；支持重复提醒、静音时段，以及目标模式下只在最终轮提醒。 · Native-style notification sounds for DeepSeek Harness: a chime when the agent needs your decision or finishes a task, click a system notification to jump back, plus repeat reminders, quiet hours, and goal-mode alerts that wait for the final round.",
   "type": "module",
   "main": "lib/index.js",