pi-smart-voice-notify 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # Changelog
 
+## [Unreleased]
+
+## [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.
+
+### 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.
+
+## [0.5.3] - 2026-06-16
+
+### Fixed
+- Filtered blank template entries so whitespace-only overrides no longer produce empty notification messages.
+- Added a final fallback (`"Notification: Please check the terminal."`) when all template expansions and defaults yield empty output.
+
 ## [0.5.2] - 2026-06-01
 
 ### Changed

package/README.md

@@ -1,13 +1,18 @@
-# 🔔 pi-smart-voice-notify
+<div align="center">
 
-[![npm version](https://img.shields.io/npm/v/pi-smart-voice-notify?style=flat-square)](https://www.npmjs.com/package/pi-smart-voice-notify) [![License](https://img.shields.io/github/license/MasuRii/pi-smart-voice-notify?style=flat-square)](LICENSE)
+# pi-smart-voice-notify
 
-Windows-optimized smart notification extension for the Pi coding agent.
+[![npm version](https://img.shields.io/npm/v/pi-smart-voice-notify?style=for-the-badge)](https://www.npmjs.com/package/pi-smart-voice-notify)
+[![License](https://img.shields.io/github/license/MasuRii/pi-smart-voice-notify?style=for-the-badge)](LICENSE)
+[![Platform](https://img.shields.io/badge/Platform-macOS%20%7C%20Linux%20%7C%20Windows-blue?style=for-the-badge)]()
 
-**pi-smart-voice-notify** monitors Pi session and tool events to alert you via **multi-engine TTS**, **sound playback**, **desktop toast notifications**, and optional **webhook/AI-assisted messaging** when the agent requires your attention.
+[![ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/Y8Y01PSSVR)
 
+Windows-optimized smart notification extension for the Pi coding agent.
+**pi-smart-voice-notify** monitors Pi session and tool events to alert you via **multi-engine TTS**, **sound playback**, **desktop toast notifications**, and optional **webhook/AI-assisted messaging** when the agent requires your attention.
 <img width="1360" height="752" alt="image" src="https://github.com/user-attachments/assets/c215a7fe-31b4-4bc4-a89e-992a4847819d" />
 
+</div>
 
 ## Features
 
@@ -99,6 +104,7 @@ Configuration is stored at:
 ```text
 Default global path: ~/.pi/agent/extensions/pi-smart-voice-notify/config.json
 Actual global path: $PI_CODING_AGENT_DIR/extensions/pi-smart-voice-notify/config.json when PI_CODING_AGENT_DIR is set
+Local config path: <repo>/.pi/extensions/pi-smart-voice-notify/config.json
 ```
 
 A starter template is provided in `config/config.example.json`. On startup, the extension creates `config.json` with defaults if missing.
@@ -302,4 +308,4 @@ npm run check      # build + test
 
 ## License
 
-MIT
+[MIT](LICENSE)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-smart-voice-notify",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Windows-optimized smart voice, sound, and desktop notifications for Pi coding agent.",
   "type": "module",
   "main": "./index.ts",
@@ -19,8 +19,9 @@
   "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/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"
+    "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",
@@ -61,14 +62,20 @@
     ]
   },
   "peerDependencies": {
-    "@earendil-works/pi-coding-agent": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0",
-    "@earendil-works/pi-tui": "^0.74.0 || ^0.75.0 || ^0.77.0 || ^0.78.0"
+    "@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.3.0"
+    "undici": "^8.5.0"
   },
   "devDependencies": {
-    "@types/node": "25.9.1"
+    "@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"
   }
 }

package/src/abortable-command.ts

@@ -1,4 +1,31 @@
 import { spawn } from "node:child_process";
+import { basename } from "node:path";
+
+const ALLOWED_ABORTABLE_COMMANDS = new Set([
+	"aplay",
+	"edge-tts",
+	"espeak-ng",
+	"ffplay",
+	"gdbus",
+	"paplay",
+	"powershell",
+	"powershell.exe",
+	"swaymsg",
+	"where",
+	"which",
+	"xdotool",
+	"xprop",
+]);
+
+function normalizeCommandName(command: string): string {
+	return basename(command).trim().toLowerCase();
+}
+
+function isAllowedAbortableCommand(command: string): boolean {
+	const normalized = normalizeCommandName(command);
+	const nodeExecutable = normalizeCommandName(process.execPath);
+	return normalized === nodeExecutable || ALLOWED_ABORTABLE_COMMANDS.has(normalized);
+}
 
 export interface AbortableCommandOptions {
 	timeoutMs?: number;
@@ -55,6 +82,9 @@ export async function runAbortableCommand(
 	if (!Array.isArray(args)) {
 		throw new Error("runAbortableCommand: args must be an array of strings");
 	}
+	if (!isAllowedAbortableCommand(normalizedCommand)) {
+		throw new Error(`runAbortableCommand: command is not allowlisted: ${normalizedCommand}`);
+	}
 
 	const commandLabel = buildCommandString(normalizedCommand, args);
 	if (options.signal?.aborted) {
@@ -69,7 +99,7 @@ export async function runAbortableCommand(
 	}
 
 	return await new Promise<AbortableCommandResult>((resolve) => {
-		const child = spawn(normalizedCommand, [...args], {
+		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.
 			env: options.env ?? process.env,
 			cwd: options.cwd,
 		});

package/src/agent-dir.ts

@@ -1,32 +1,32 @@
-import { homedir } from "node:os";
-import { join } from "node:path";
-
-const PI_AGENT_DIR_ENV_VAR = "PI_CODING_AGENT_DIR";
-
-interface AgentDirEnvironment {
-	[name: string]: string | undefined;
-}
-
-function expandHomeDirectory(configuredDir: string, homeDirectory: string): string {
-	if (configuredDir === "~") {
-		return homeDirectory;
-	}
-
-	if (configuredDir.startsWith("~/") || configuredDir.startsWith("~\\")) {
-		return join(homeDirectory, configuredDir.slice(2));
-	}
-
-	return configuredDir;
-}
-
-export function resolvePiAgentDir(
-	env: AgentDirEnvironment = process.env,
-	homeDirectory = homedir(),
-): string {
-	const configuredDir = env[PI_AGENT_DIR_ENV_VAR];
-	if (!configuredDir) {
-		return join(homeDirectory, ".pi", "agent");
-	}
-
-	return expandHomeDirectory(configuredDir, homeDirectory);
-}
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const PI_AGENT_DIR_ENV_VAR = "PI_CODING_AGENT_DIR";
+
+interface AgentDirEnvironment {
+	[name: string]: string | undefined;
+}
+
+function expandHomeDirectory(configuredDir: string, homeDirectory: string): string {
+	if (configuredDir === "~") {
+		return homeDirectory;
+	}
+
+	if (configuredDir.startsWith("~/") || configuredDir.startsWith("~\\")) {
+		return join(homeDirectory, configuredDir.slice(2));
+	}
+
+	return configuredDir;
+}
+
+export function resolvePiAgentDir(
+	env: AgentDirEnvironment = process.env,
+	homeDirectory = homedir(),
+): string {
+	const configuredDir = env[PI_AGENT_DIR_ENV_VAR];
+	if (!configuredDir) {
+		return join(homeDirectory, ".pi", "agent");
+	}
+
+	return expandHomeDirectory(configuredDir, homeDirectory);
+}

package/src/ai-messages.ts

@@ -237,6 +237,10 @@ function sanitizeMessage(message: string, maxLength = DEFAULT_MAX_MESSAGE_LENGTH
 	return `${clipped.slice(0, safeBoundary).trimEnd()}...`;
 }
 
+function getUsableTemplates(templates: string[]): string[] {
+	return templates.filter((template) => template.trim().length > 0);
+}
+
 function pickTemplate(templates: string[]): string {
 	const index = Math.floor(Math.random() * templates.length);
 	return templates[index] ?? templates[0] ?? "Notification";
@@ -252,8 +256,11 @@ function getTemplatesForEvent(eventType: string, config: AIMessageConfig): strin
 	}
 
 	const overrideTemplates = config.templates[eventType];
-	if (Array.isArray(overrideTemplates) && overrideTemplates.length > 0) {
-		return overrideTemplates;
+	if (Array.isArray(overrideTemplates)) {
+		const usableTemplates = getUsableTemplates(overrideTemplates);
+		if (usableTemplates.length > 0) {
+			return usableTemplates;
+		}
 	}
 	return DEFAULT_TEMPLATES[eventType];
 }
@@ -317,8 +324,20 @@ export class AIMessageService {
 		const templates = getTemplatesForEvent(eventType, this.config);
 		const template = pickTemplate(templates);
 		const variables = buildTemplateVariables(eventType, context);
-		const message = applyTemplateVariables(template, variables);
-		return sanitizeMessage(message);
+		const message = sanitizeMessage(applyTemplateVariables(template, variables));
+		if (message.length > 0) {
+			return message;
+		}
+
+		if (isCoreEventType(eventType)) {
+			const fallbackTemplate = pickTemplate(DEFAULT_TEMPLATES[eventType]);
+			const fallbackMessage = sanitizeMessage(applyTemplateVariables(fallbackTemplate, variables));
+			if (fallbackMessage.length > 0) {
+				return fallbackMessage;
+			}
+		}
+
+		return "Notification: Please check the terminal.";
 	}
 
 	public async generateAIMessage(eventType: string, context: AIMessageContext = {}): Promise<string | null> {

package/src/config-store.ts

@@ -16,6 +16,11 @@ export const EXTENSION_ID = "pi-smart-voice-notify";
 export const STATUS_KEY = "smart-voice-notify";
 export const CONFIG_DIR = join(resolvePiAgentDir(), "extensions", EXTENSION_ID);
 export const CONFIG_PATH = join(CONFIG_DIR, "config.json");
+
+/** Project-local override config: <projectRoot>/.pi/extensions/<id>/config.json (read-only). */
+export function resolveProjectConfigPath(projectRoot: string): string {
+	return join(projectRoot, ".pi", "extensions", EXTENSION_ID, "config.json");
+}
 export const DEBUG_DIR = join(CONFIG_DIR, "debug");
 export const DEBUG_LOG_PATH = join(DEBUG_DIR, `${EXTENSION_ID}.log`);
 
@@ -979,28 +984,74 @@ export function ensureDebugDirectory(): void {
 	}
 }
 
-export function readConfigFromDisk(): VoiceNotifyConfig {
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Deep-merge `override` onto `base`. Nested objects merge; arrays and scalars replace. */
+export function deepMergeConfigRecords(
+	base: Record<string, unknown>,
+	override: Record<string, unknown>,
+): Record<string, unknown> {
+	const result: Record<string, unknown> = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		const existing = result[key];
+		result[key] = isPlainObject(existing) && isPlainObject(value)
+			? deepMergeConfigRecords(existing, value)
+			: value;
+	}
+	return result;
+}
+
+function readConfigRecord(path: string): Record<string, unknown> | null {
+	if (!existsSync(path)) {
+		return null;
+	}
+	try {
+		return toRecord(JSON.parse(readFileSync(path, "utf-8")) as unknown);
+	} catch {
+		return null;
+	}
+}
+
+/** Load and self-heal the global config file, returning its raw record. */
+function loadGlobalConfigRecord(): Record<string, unknown> {
 	ensureConfigDirectory();
+	const defaultsSerialized = `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`;
 	if (!existsSync(CONFIG_PATH)) {
-		writeFileSync(CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf-8");
-		return applyEnvironmentOverrides({ ...DEFAULT_CONFIG, webhook: { ...DEFAULT_CONFIG.webhook, events: [...DEFAULT_CONFIG.webhook.events] } });
+		writeFileSync(CONFIG_PATH, defaultsSerialized, "utf-8");
+		return toRecord(JSON.parse(defaultsSerialized));
 	}
 
 	try {
 		const raw = readFileSync(CONFIG_PATH, "utf-8");
 		const parsed = JSON.parse(raw) as unknown;
-		const normalized = normalizeConfig(parsed);
-		const validation = validateConfig(normalized);
-		const serialized = `${JSON.stringify(validation.config, null, 2)}\n`;
+		const serialized = `${JSON.stringify(validateConfig(normalizeConfig(parsed)).config, null, 2)}\n`;
 		if (raw !== serialized) {
 			writeFileSync(CONFIG_PATH, serialized, "utf-8");
 		}
-		const runtimeConfig = applyEnvironmentOverrides(validation.config);
-		return validateConfig(runtimeConfig).config;
+		return toRecord(parsed);
 	} catch {
-		writeFileSync(CONFIG_PATH, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}\n`, "utf-8");
-		return applyEnvironmentOverrides({ ...DEFAULT_CONFIG, webhook: { ...DEFAULT_CONFIG.webhook, events: [...DEFAULT_CONFIG.webhook.events] } });
+		writeFileSync(CONFIG_PATH, defaultsSerialized, "utf-8");
+		return toRecord(JSON.parse(defaultsSerialized));
+	}
+}
+
+/**
+ * Read the effective config. When `projectRoot` is given and a project config
+ * exists, it deep-merges over the global config; environment variables still
+ * override both. The project file is read-only — only the global file is healed.
+ */
+export function readConfigFromDisk(projectRoot?: string): VoiceNotifyConfig {
+	let record = loadGlobalConfigRecord();
+	if (projectRoot) {
+		const projectRecord = readConfigRecord(resolveProjectConfigPath(projectRoot));
+		if (projectRecord) {
+			record = deepMergeConfigRecords(record, projectRecord);
+		}
 	}
+	const runtimeConfig = applyEnvironmentOverrides(validateConfig(normalizeConfig(record)).config);
+	return validateConfig(runtimeConfig).config;
 }
 
 export function writeConfigToDisk(config: VoiceNotifyConfig): void {

package/src/index.ts

@@ -1814,7 +1814,7 @@ export default function smartVoiceNotifyExtension(
 		}
 
 		if (subcommand === "reload") {
-			config = readConfig();
+			config = readConfig(ctx.cwd);
 			refreshIntegratedServiceConfig();
 			await syncPermissionForwardingWatcher();
 			refreshQuestionToolAvailability();
@@ -1880,7 +1880,7 @@ export default function smartVoiceNotifyExtension(
 		shutdownRequested = false;
 		shutdownPromise = null;
 		cancelPendingAgentErrorNotification("session_start");
-		config = readConfig();
+		config = readConfig(ctx.cwd);
 		refreshIntegratedServiceConfig();
 		activeSessionContext = ctx;
 		await syncPermissionForwardingWatcher();

package/src/linux.ts

@@ -11,6 +11,7 @@ import type {
 const DEFAULT_TIMEOUT_MS = 8_000;
 const DEFAULT_AUDIO_TIMEOUT_MS = 20_000;
 type DebugLog = (message: string) => void;
+type LinuxCommandName = "xset" | "gdbus" | "pactl" | "amixer" | "paplay" | "aplay" | "xprintidle";
 
 function createDebugLog(options?: LinuxUtilsOptions): DebugLog {
 	return options?.debugLog ?? (() => {});
@@ -23,13 +24,32 @@ function buildCommandString(command: string, args: string[]): string {
 	return `${command} ${args.join(" ")}`;
 }
 
+function spawnLinuxCommand(command: LinuxCommandName, args: string[]) {
+	switch (command) {
+		case "xset":
+			return spawn("xset", args, { env: process.env });
+		case "gdbus":
+			return spawn("gdbus", args, { env: process.env });
+		case "pactl":
+			return spawn("pactl", args, { env: process.env });
+		case "amixer":
+			return spawn("amixer", args, { env: process.env });
+		case "paplay":
+			return spawn("paplay", args, { env: process.env });
+		case "aplay":
+			return spawn("aplay", args, { env: process.env });
+		case "xprintidle":
+			return spawn("xprintidle", args, { env: process.env });
+	}
+}
+
 async function runSpawnCommand(
-	command: string,
+	command: LinuxCommandName,
 	args: string[],
 	timeoutMs = DEFAULT_TIMEOUT_MS,
 ): Promise<LinuxCommandResult> {
 	return await new Promise<LinuxCommandResult>((resolve) => {
-		const child = spawn(command, args, { env: process.env });
+		const child = spawnLinuxCommand(command, args);
 		const fullCommand = buildCommandString(command, args);
 		let stdout = "";
 		let stderr = "";
@@ -139,7 +159,7 @@ export async function wakeMonitor(options: LinuxUtilsOptions = {}): Promise<bool
 	}
 
 	const session = detectLinuxSession();
-	const wakeCommands = [
+	const wakeCommands: Array<{ name: string; command: LinuxCommandName; args: string[] }> = [
 		{
 			name: "xset",
 			command: "xset",