pi-smart-voice-notify 0.5.4 → 0.6.0

package/CHANGELOG.md

@@ -2,18 +2,28 @@
 
 ## [Unreleased]
 
+## [0.6.0] - 2026-07-03
+
+### Added
+- Added an `enabled` master toggle to the config so the extension can be disabled without uninstalling. ([76cd96f](https://github.com/MasuRii/pi-smart-voice-notify/commit/76cd96fbbd6bd0658f00e8d7c043c44260f856bd))
+
+### Changed
+- Widened Pi coding-agent and Pi TUI peer dependency ranges to include `^0.80.0` and bumped development dependencies (`@types/node` to `26.1.0`, `@earendil-works/pi-coding-agent` to `^0.80.3`). ([146ff6e](https://github.com/MasuRii/pi-smart-voice-notify/commit/146ff6edf87de680958e61f0e1db34e6d337c729))
+- Extracted shared utilities and consolidated duplicated logic across config, notification, and platform modules. ([76cd96f](https://github.com/MasuRii/pi-smart-voice-notify/commit/76cd96fbbd6bd0658f00e8d7c043c44260f856bd))
+- Extracted shared test helpers and consolidated fixtures across the test suite. ([6cf3ed0](https://github.com/MasuRii/pi-smart-voice-notify/commit/6cf3ed0168c1460ffca3c447f4a7a55565f5cade))
+
 ## [0.5.4] - 2026-06-22
 
 ### Fixed
-- Added a command allowlist to `runAbortableCommand` so non-allowlisted executables are rejected before spawning, preventing arbitrary command injection.
-- Replaced dynamic string-based command spawning in Linux helpers with a typed `LinuxCommandName` union and dedicated `spawnLinuxCommand` switch.
+- Added a command allowlist to `runAbortableCommand` so non-allowlisted executables are rejected before spawning, preventing arbitrary command injection ([2074e30](https://github.com/MasuRii/pi-smart-voice-notify/commit/2074e30)).
+- Replaced dynamic string-based command spawning in Linux helpers with a typed `LinuxCommandName` union and dedicated `spawnLinuxCommand` switch ([2074e30](https://github.com/MasuRii/pi-smart-voice-notify/commit/2074e30)).
 
 ### Changed
-- Added `postinstall` hook that runs `patch-vulnerable-deps.mjs` when installed under `.pi/agent/extensions/`.
-- Pinned `protobufjs` 7.6.3, `ws` 8.21.0, and `uuid` 11.1.1 via npm `overrides` to resolve known vulnerabilities.
-- Added `@earendil-works/pi-coding-agent` as a devDependency for type-checking.
-- Updated README badge styling to for-the-badge, added platform badge and ko-fi support button.
-- Added `config-store-env-override` test to the test script.
+- Added `postinstall` hook that runs `patch-vulnerable-deps.mjs` when installed under `.pi/agent/extensions/` ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Pinned `protobufjs` 7.6.3, `ws` 8.21.0, and `uuid` 11.1.1 via npm `overrides` to resolve known vulnerabilities ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Added `@earendil-works/pi-coding-agent` as a devDependency for type-checking ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
+- Updated README badge styling to for-the-badge, added platform badge and ko-fi support button ([f66fff6](https://github.com/MasuRii/pi-smart-voice-notify/commit/f66fff6)).
+- Added `config-store-env-override` test to the test script ([924e585](https://github.com/MasuRii/pi-smart-voice-notify/commit/924e585)).
 
 ## [0.5.3] - 2026-06-16
 

package/package.json

@@ -1,81 +1,81 @@
-{
-  "name": "pi-smart-voice-notify",
-  "version": "0.5.4",
-  "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
-  "type": "module",
-  "main": "./index.ts",
-  "exports": {
-    ".": "./index.ts"
-  },
-  "files": [
-    "index.ts",
-    "src",
-    "config/config.example.json",
-    "assets",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "build": "npx --yes -p typescript@5.7.3 -p @types/node@20.17.57 tsc -p tsconfig.json --noEmit",
-    "lint": "npm run build",
-    "test": "node --experimental-strip-types --test test/config-store.test.ts test/config-store-no-global.test.ts test/config-store-env-override.test.ts test/abortable-command.test.ts test/reminder-playback.test.ts test/permission-forwarding-watcher.test.ts test/sound-theme.test.ts test/webhook.test.ts test/linux.test.ts test/index.test.ts test/tts.test.ts",
-    "check": "npm run build && npm run test",
-    "postinstall": "node -e \"const fs=require('fs'),cp=require('child_process'),p=require('path');const cwd=process.cwd();const normalized=cwd.split(p.sep).join('/');if(!normalized.includes('/.pi/agent/extensions/'))process.exit(0);const s=p.resolve(cwd,'../../scripts/patch-vulnerable-deps.mjs');if(!fs.existsSync(s))process.exit(0);const r=cp.spawnSync(process.execPath,[s,'--target',cwd,'--quiet'],{stdio:'inherit'});process.exit(r.status||0)\""
-  },
-  "keywords": [
-    "pi-package",
-    "pi",
-    "pi-extension",
-    "pi-coding-agent",
-    "coding-agent",
-    "voice-notify",
-    "desktop-notification",
-    "notifications",
-    "voice",
-    "audio",
-    "text-to-speech",
-    "tts",
-    "windows",
-    "linux",
-    "macos"
-  ],
-  "author": "MasuRii",
-  "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/MasuRii/pi-smart-voice-notify.git"
-  },
-  "homepage": "https://github.com/MasuRii/pi-smart-voice-notify#readme",
-  "bugs": {
-    "url": "https://github.com/MasuRii/pi-smart-voice-notify/issues"
-  },
-  "engines": {
-    "node": ">=24"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "pi": {
-    "extensions": [
-      "./index.ts"
-    ]
-  },
-  "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0"
-  },
-  "dependencies": {
-    "node-notifier": "^10.0.1",
-    "undici": "^8.5.0"
-  },
-  "devDependencies": {
-    "@types/node": "25.9.3",
-    "@earendil-works/pi-coding-agent": "^0.79.7"
-  },
-  "overrides": {
-    "protobufjs": "7.6.3",
-    "ws": "8.21.0",
-    "uuid": "11.1.1"
-  }
-}
+{
+  "name": "pi-smart-voice-notify",
+  "version": "0.6.0",
+  "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
+  "type": "module",
+  "main": "./index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "config/config.example.json",
+    "assets",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "npx --yes -p typescript@5.7.3 -p @types/node@20.17.57 tsc -p tsconfig.json --noEmit",
+    "lint": "npm run build",
+    "test": "node --experimental-strip-types --test test/config-store.test.ts test/config-store-no-global.test.ts test/config-store-env-override.test.ts test/abortable-command.test.ts test/reminder-playback.test.ts test/permission-forwarding-watcher.test.ts test/sound-theme.test.ts test/webhook.test.ts test/linux.test.ts test/index.test.ts test/tts.test.ts",
+    "check": "npm run build && npm run test",
+    "postinstall": "node -e \"const fs=require('fs'),cp=require('child_process'),p=require('path');const cwd=process.cwd();const normalized=cwd.split(p.sep).join('/');if(!normalized.includes('/.pi/agent/extensions/'))process.exit(0);const s=p.resolve(cwd,'../../scripts/patch-vulnerable-deps.mjs');if(!fs.existsSync(s))process.exit(0);const r=cp.spawnSync(process.execPath,[s,'--target',cwd,'--quiet'],{stdio:'inherit'});process.exit(r.status||0)\""
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "coding-agent",
+    "voice-notify",
+    "desktop-notification",
+    "notifications",
+    "voice",
+    "audio",
+    "text-to-speech",
+    "tts",
+    "windows",
+    "linux",
+    "macos"
+  ],
+  "author": "MasuRii",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MasuRii/pi-smart-voice-notify.git"
+  },
+  "homepage": "https://github.com/MasuRii/pi-smart-voice-notify#readme",
+  "bugs": {
+    "url": "https://github.com/MasuRii/pi-smart-voice-notify/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0",
+    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0 || ^0.79.0 || ^0.80.0"
+  },
+  "dependencies": {
+    "node-notifier": "^10.0.1",
+    "undici": "^8.5.0"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.0",
+    "@earendil-works/pi-coding-agent": "^0.80.3"
+  },
+  "overrides": {
+    "protobufjs": "7.6.3",
+    "ws": "8.21.0",
+    "uuid": "11.1.1"
+  }
+}

package/src/abortable-command.ts

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { basename } from "node:path";
 
+import { buildCommandString, attachChildHandlers } from "./shared/index.ts";
+
 const ALLOWED_ABORTABLE_COMMANDS = new Set([
 	"aplay",
 	"edge-tts",
@@ -50,10 +52,6 @@ function stringifyError(error: unknown): string {
 	return String(error);
 }
 
-function buildCommandString(command: string, args: readonly string[]): string {
-	return args.length > 0 ? `${command} ${args.join(" ")}` : command;
-}
-
 function stopChildProcess(child: ReturnType<typeof spawn>, force = false): void {
 	if (child.killed) {
 		return;
@@ -65,8 +63,10 @@ function stopChildProcess(child: ReturnType<typeof spawn>, force = false): void
 			return;
 		}
 		child.kill(force ? "SIGKILL" : "SIGTERM");
-	} catch {
-		// noop
+	} catch (error) {
+		// Killing a process that has already exited can throw on some platforms;
+		// the error is non-actionable for shutdown/abort flows.
+		void error;
 	}
 }
 
@@ -99,7 +99,7 @@ export async function runAbortableCommand(
 	}
 
 	return await new Promise<AbortableCommandResult>((resolve) => {
-		const child = spawn(normalizedCommand, [...args], { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- normalizedCommand is checked against ALLOWED_ABORTABLE_COMMANDS (plus the current Node executable for tests) before spawn; args are passed as an array with shell disabled.
+		const child = spawn(normalizedCommand, Array.from(args), { // nosemgrep: javascript.lang.security.detect-child-process.detect-child-process -- normalizedCommand is checked against ALLOWED_ABORTABLE_COMMANDS (plus the current Node executable for tests) before spawn; args are passed as an array with shell disabled.
 			env: options.env ?? process.env,
 			cwd: options.cwd,
 		});
@@ -148,19 +148,9 @@ export async function runAbortableCommand(
 
 		options.signal?.addEventListener("abort", onAbort, { once: true });
 
-		child.stdout?.on("data", (chunk: Buffer | string) => {
-			stdout += chunk.toString();
-		});
-
-		child.stderr?.on("data", (chunk: Buffer | string) => {
-			stderr += chunk.toString();
-		});
-
-		child.on("error", (error) => {
-			spawnError = error;
-		});
+		attachChildHandlers(child, (text: string) => { stdout += text; }, (text: string) => { stderr += text; }, (error: Error) => { spawnError = error; });
 
-		child.on("close", (code) => {
+		child.on("close", (code: number | null) => {
 			cleanup();
 			resolve({
 				code: code ?? (spawnError || timedOut || aborted ? 1 : 0),

package/src/ai-messages.ts

@@ -1,5 +1,7 @@
 import { normalizeFloat } from "./config-store.ts";
 import { getErrorMessage } from "./logging.ts";
+import { clampRoundedInt } from "./shared/index.ts";
+import type { FlatAIMessageConfig } from "./types.ts";
 
 export const AI_EVENT_TYPES = [
 	"idle",
@@ -24,20 +26,7 @@ export interface AIMessageContext {
 	variables?: Record<string, string | number | boolean | null | undefined>;
 }
 
-export interface AIMessageConfig {
-	enableAIMessages: boolean;
-	aiEndpoint: string;
-	aiModel: string;
-	aiApiKey: string;
-	aiTimeoutMs: number;
-	aiTemperature: number;
-	aiMaxTokens: number;
-	aiFallbackToTemplates: boolean;
-	personality: string;
-	tone: string;
-	enableMessageCache: boolean;
-	messageCacheTtlMs: number;
-	maxCacheEntries: number;
+export interface AIMessageConfig extends FlatAIMessageConfig {
 	templates: Partial<Record<CoreAIEventType, string[]>>;
 }
 
@@ -128,24 +117,17 @@ export const DEFAULT_AI_MESSAGE_CONFIG: AIMessageConfig = {
 	templates: {},
 };
 
-function normalizePositiveInt(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, Math.round(value)));
-}
-
-function normalizeConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageConfig {
+function normalizeAIMessageConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageConfig {
 	return {
 		...DEFAULT_AI_MESSAGE_CONFIG,
 		...overrides,
-		aiTimeoutMs: normalizePositiveInt(
+		aiTimeoutMs: clampRoundedInt(
 			overrides.aiTimeoutMs ?? DEFAULT_AI_MESSAGE_CONFIG.aiTimeoutMs,
 			DEFAULT_AI_MESSAGE_CONFIG.aiTimeoutMs,
 			1_000,
 			60_000,
 		),
-		aiMaxTokens: normalizePositiveInt(
+		aiMaxTokens: clampRoundedInt(
 			overrides.aiMaxTokens ?? DEFAULT_AI_MESSAGE_CONFIG.aiMaxTokens,
 			DEFAULT_AI_MESSAGE_CONFIG.aiMaxTokens,
 			40,
@@ -157,13 +139,13 @@ function normalizeConfig(overrides: Partial<AIMessageConfig> = {}): AIMessageCon
 			0,
 			2,
 		),
-		messageCacheTtlMs: normalizePositiveInt(
+		messageCacheTtlMs: clampRoundedInt(
 			overrides.messageCacheTtlMs ?? DEFAULT_AI_MESSAGE_CONFIG.messageCacheTtlMs,
 			DEFAULT_AI_MESSAGE_CONFIG.messageCacheTtlMs,
 			5_000,
 			600_000,
 		),
-		maxCacheEntries: normalizePositiveInt(
+		maxCacheEntries: clampRoundedInt(
 			overrides.maxCacheEntries ?? DEFAULT_AI_MESSAGE_CONFIG.maxCacheEntries,
 			DEFAULT_AI_MESSAGE_CONFIG.maxCacheEntries,
 			20,
@@ -304,15 +286,15 @@ export class AIMessageService {
 	private readonly debugLog: (message: string, details?: Record<string, unknown>) => void;
 
 	constructor(options: AIMessageServiceOptions = {}) {
-		this.config = normalizeConfig(options.config);
+		this.config = normalizeAIMessageConfig(options.config);
 		this.debugLog = options.debugLog ?? (() => {});
 	}
 
-	public updateConfig(overrides: Partial<AIMessageConfig>): void {
-		this.config = normalizeConfig({ ...this.config, ...overrides });
+	public updateAIMessageConfig(overrides: Partial<AIMessageConfig>): void {
+		this.config = normalizeAIMessageConfig({ ...this.config, ...overrides });
 	}
 
-	public getConfig(): AIMessageConfig {
+	public getAIMessageConfig(): AIMessageConfig {
 		return { ...this.config, templates: { ...this.config.templates } };
 	}
 
@@ -449,7 +431,8 @@ export class AIMessageService {
 		}
 
 		while (this.cache.size > this.config.maxCacheEntries) {
-			const oldestKey = this.cache.keys().next().value;
+			const next = this.cache.keys().next();
+			const oldestKey = typeof next.value === "string" ? next.value : undefined;
 			if (!oldestKey) {
 				break;
 			}

package/src/config-store.ts

@@ -2,6 +2,19 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { isAbsolute, join } from "node:path";
 
 import { resolvePiAgentDir } from "./agent-dir.ts";
+import {
+	clampInt,
+	clampNumber,
+	normalizeFloat,
+	normalizeStringEnum,
+	normalizeStringEnumArray,
+	parseEnvBoolean,
+	readEnvFrom,
+	toRecord,
+	ENGINE_TTS_DEFAULTS,
+} from "./shared/index.ts";
+
+export { clampInt, clampNumber, normalizeFloat, toRecord };
 import type {
 	ConcreteTTSEngine,
 	MessageSet,
@@ -159,25 +172,7 @@ export const DEFAULT_CONFIG: VoiceNotifyConfig = {
 	sapiPitch: "medium",
 	sapiVolume: "loud",
 
-	edgeVoice: "en-US-JennyNeural",
-	edgeRate: "+10%",
-	edgePitch: "+0Hz",
-	edgeVolume: "+0%",
-	espeakVoice: "en",
-	espeakRate: 175,
-	espeakPitch: 50,
-	elevenLabsApiKey: "",
-	elevenLabsVoiceId: "cgSgspJ2msm6clMCkdW9",
-	elevenLabsModel: "eleven_turbo_v2_5",
-	elevenLabsStability: 0.5,
-	elevenLabsSimilarity: 0.75,
-	elevenLabsStyle: 0.5,
-	openaiTtsEndpoint: "",
-	openaiTtsApiKey: "",
-	openaiTtsModel: "tts-1",
-	openaiTtsVoice: "alloy",
-	openaiTtsFormat: "mp3",
-	openaiTtsSpeed: 1,
+	...ENGINE_TTS_DEFAULTS,
 
 	idleSoundFile: "assets/soft-notification.mp3",
 	permissionSoundFile: "assets/attention-alert.mp3",
@@ -261,71 +256,12 @@ export const DEFAULT_CONFIG: VoiceNotifyConfig = {
 	debugLog: false,
 };
 
-export function toRecord(value: unknown): Record<string, unknown> {
-	if (!value || typeof value !== "object" || Array.isArray(value)) {
-		return {};
-	}
-	return value as Record<string, unknown>;
-}
-
 function readEnv(...keys: string[]): string {
-	for (const key of keys) {
-		const value = process.env[key];
-		if (typeof value === "string" && value.trim().length > 0) {
-			return value.trim();
-		}
-	}
-	return "";
+	return readEnvFrom(...keys);
 }
 
 function parseEnvBool(value: string): boolean | undefined {
-	if (!value) {
-		return undefined;
-	}
-	const normalized = value.trim().toLowerCase();
-	if (["1", "true", "yes", "on"].includes(normalized)) {
-		return true;
-	}
-	if (["0", "false", "no", "off"].includes(normalized)) {
-		return false;
-	}
-	return undefined;
-}
-
-function parseNumeric(value: unknown): number | undefined {
-	if (typeof value === "number" && Number.isFinite(value)) {
-		return value;
-	}
-	if (typeof value === "string" && value.trim().length > 0) {
-		const parsed = Number(value.trim());
-		if (Number.isFinite(parsed)) {
-			return parsed;
-		}
-	}
-	return undefined;
-}
-
-export function clampInt(value: unknown, fallback: number, min: number, max: number): number {
-	const numeric = parseNumeric(value);
-	if (numeric === undefined) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, Math.trunc(numeric)));
-}
-
-export function clampNumber(value: unknown, fallback: number, min: number, max: number): number {
-	const numeric = parseNumeric(value);
-	if (numeric === undefined) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, numeric));
-}
-
-export function normalizeFloat(value: number, fallback: number, min: number, max: number): number {
-	if (!Number.isFinite(value)) {
-		return fallback;
-	}
-	return Math.min(max, Math.max(min, value));
+	return parseEnvBoolean(value);
 }
 
 function boolOrDefault(value: unknown, fallback: boolean): boolean {
@@ -402,17 +338,11 @@ function normalizeStringArray(value: unknown): string[] {
 }
 
 function normalizeNotificationTypes(value: unknown, fallback: NotificationType[]): NotificationType[] {
-	const candidates = normalizeStringArray(value)
-		.map((entry) => entry.toLowerCase())
-		.filter((entry): entry is NotificationType => NOTIFICATION_TYPE_VALUES.includes(entry as NotificationType));
-	return candidates.length > 0 ? [...new Set(candidates)] : [...fallback];
+	return normalizeStringEnumArray(value, NOTIFICATION_TYPE_VALUES, fallback);
 }
 
 function normalizeFallbackChain(value: unknown, fallback: ConcreteTTSEngine[]): ConcreteTTSEngine[] {
-	const candidates = normalizeStringArray(value)
-		.map((entry) => entry.toLowerCase())
-		.filter((entry): entry is ConcreteTTSEngine => CONCRETE_TTS_ENGINE_VALUES.includes(entry as ConcreteTTSEngine));
-	return candidates.length > 0 ? [...new Set(candidates)] : [...fallback];
+	return normalizeStringEnumArray(value, CONCRETE_TTS_ENGINE_VALUES, fallback);
 }
 
 function normalizeTemplates(value: unknown): Partial<Record<string, string[]>> {
@@ -484,17 +414,11 @@ function isHttpUrl(url: string): boolean {
 }
 
 export function normalizeMode(value: unknown): NotificationMode {
-	if (typeof value === "string" && NOTIFICATION_MODES.includes(value as NotificationMode)) {
-		return value as NotificationMode;
-	}
-	return DEFAULT_CONFIG.notificationMode;
+	return normalizeStringEnum(value, NOTIFICATION_MODES, DEFAULT_CONFIG.notificationMode);
 }
 
 export function normalizeTtsEngine(value: unknown): TTSEngine {
-	if (typeof value === "string" && TTS_ENGINE_VALUES.includes(value as TTSEngine)) {
-		return value as TTSEngine;
-	}
-	return DEFAULT_CONFIG.ttsEngine;
+	return normalizeStringEnum(value, TTS_ENGINE_VALUES, DEFAULT_CONFIG.ttsEngine);
 }
 
 export function normalizeConfig(raw: unknown): VoiceNotifyConfig {