pi-ding 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,80 @@
+# pi-ding
+
+A [pi](https://github.com/badlogic/pi-mono) extension that plays a sound when the agent finishes processing a prompt (when it’s ready for the next input).
+
+## Install
+
+### Install from npm
+
+```bash
+pi install npm:pi-ding
+```
+
+### Install from git
+
+```bash
+pi install git:github.com/ninlds/pi-ding@v0.1.0
+```
+
+### Try without installing
+
+```bash
+pi -e npm:pi-ding
+# or
+pi -e git:github.com/ninlds/pi-ding@v0.1.0
+```
+
+## Configure (recommended)
+
+pi-ding stores its config inside pi’s settings files, so you can configure once and then just run `pi`.
+
+Settings locations (project overrides global):
+
+- Global: `~/.pi/agent/settings.json`
+- Project: `<project>/.pi/settings.json`
+
+Add a `ding` key:
+
+```json
+{
+  "ding": {
+    "enabled": true,
+    "player": "mpv",
+    "args": ["--no-video", "--really-quiet"],
+    "path": "~/sounds/done.mkv"
+  }
+}
+```
+
+Notes:
+- `args` is optional.
+- If `player` is omitted, pi-ding tries common players automatically (`mpv`, `ffplay`, `paplay`, `afplay`, `aplay`).
+- Supported audio formats depend on the chosen player.
+
+### Easiest way: edit from inside pi
+
+Inside pi:
+- `/ding edit` → edits **project** config (`.pi/settings.json`)
+- `/ding edit global` → edits **global** config (`~/.pi/agent/settings.json`)
+
+## Commands (inside pi)
+
+- `/ding` — toggle enabled (saved to **project** settings by default)
+- `/ding on` / `/ding off` — set enabled
+- `/ding test` — play sound immediately
+- `/ding info` — show debug info (effective config, resolved file, players)
+- `/ding reload` — reload settings from disk
+
+## Optional CLI overrides
+
+You typically won’t need these once config exists, but they can override settings for a single run:
+
+```bash
+pi --no-ding
+pi --ding-player mpv --ding-path "./done.mkv"
+pi --ding-args '["--no-video","--really-quiet"]'
+```
+
+## License
+
+MIT

package/extensions/ding.ts

@@ -0,0 +1,412 @@
+/**
+ * pi-ding
+ *
+ * Play a sound (or terminal bell) when pi finishes a prompt.
+ *
+ * Configuration is stored in pi settings files (project overrides global):
+ *   - Global:  ~/.pi/agent/settings.json
+ *   - Project: <project>/.pi/settings.json
+ *
+ * Add a `ding` object to either settings file:
+ *
+ * {
+ *   "ding": {
+ *     "enabled": true,
+ *     "player": "mpv",
+ *     "args": ["--no-video", "--really-quiet"],
+ *     "path": "~/sounds/done.mkv"
+ *   }
+ * }
+ *
+ * Notes:
+ * - `args` is optional.
+ * - If `player` is omitted, the extension will try common players automatically.
+ * - If `path` is omitted or does not exist, it falls back to the terminal bell.
+ * - Supported formats depend on the chosen player.
+ *
+ * CLI overrides (optional):
+ *   --no-ding
+ *   --ding-player <player>
+ *   --ding-path <path>
+ *   --ding-args <json-array>
+ *
+ * Commands:
+ *   /ding                 Toggle enabled (writes to project settings by default)
+ *   /ding on|off           Set enabled (writes to project settings by default)
+ *   /ding test             Play now
+ *   /ding info             Show config/debug info
+ *   /ding edit [project|global]   Edit ding config JSON in editor
+ *   /ding reload           Reload settings from disk
+ */
+
+import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+type DingConfig = {
+	enabled?: boolean;
+	player?: string;
+	args?: string[];
+	path?: string;
+};
+
+type ConfigSource = "project" | "global" | "default";
+
+const SETTINGS_KEY = "ding";
+
+const DEFAULT_CONFIG: Required<Pick<DingConfig, "enabled">> = {
+	enabled: true,
+};
+
+function terminalBell() {
+	process.stdout.write("\x07");
+}
+
+function trySpawnDetached(command: string, args: string[], onError: () => void) {
+	try {
+		const child = spawn(command, args, {
+			detached: true,
+			stdio: "ignore",
+		});
+		child.on("error", onError);
+		child.unref();
+	} catch {
+		onError();
+	}
+}
+
+function expandTilde(p: string): string {
+	if (p.startsWith("~/") && process.env.HOME) return path.join(process.env.HOME, p.slice(2));
+	return p;
+}
+
+function resolveMaybeRelative(ctx: ExtensionContext, p: string): string {
+	const expanded = expandTilde(p.trim());
+	return path.isAbsolute(expanded) ? expanded : path.join(ctx.cwd, expanded);
+}
+
+function isStringArray(v: unknown): v is string[] {
+	return Array.isArray(v) && v.every((x) => typeof x === "string");
+}
+
+function sanitizeConfig(input: unknown): DingConfig {
+	if (!input || typeof input !== "object") return { ...DEFAULT_CONFIG };
+	const o = input as any;
+	return {
+		...DEFAULT_CONFIG,
+		...(typeof o.enabled === "boolean" ? { enabled: o.enabled } : {}),
+		...(typeof o.player === "string" ? { player: o.player } : {}),
+		...(isStringArray(o.args) ? { args: o.args } : {}),
+		...(typeof o.path === "string" ? { path: o.path } : {}),
+	};
+}
+
+function mergeConfig(base: DingConfig, override: DingConfig): DingConfig {
+	// shallow merge is enough for this shape; arrays should override.
+	return {
+		...base,
+		...Object.fromEntries(Object.entries(override).filter(([, v]) => v !== undefined)),
+	};
+}
+
+function readJsonFile(filePath: string): { ok: true; data: any } | { ok: false; error: string } {
+	try {
+		if (!fs.existsSync(filePath)) return { ok: true, data: {} };
+		const raw = fs.readFileSync(filePath, "utf8");
+		return { ok: true, data: JSON.parse(raw) };
+	} catch (e) {
+		const msg = e instanceof Error ? e.message : String(e);
+		return { ok: false, error: msg };
+	}
+}
+
+function writeJsonFile(filePath: string, data: any) {
+	fs.mkdirSync(path.dirname(filePath), { recursive: true });
+	fs.writeFileSync(filePath, JSON.stringify(data, null, 2) + "\n", "utf8");
+}
+
+function getProjectSettingsPath(ctx: ExtensionContext): string {
+	// pi config dir is .pi by default
+	return path.join(ctx.cwd, ".pi", "settings.json");
+}
+
+function getGlobalSettingsPath(): string {
+	return path.join(getAgentDir(), "settings.json");
+}
+
+function extractDingConfigFromSettings(settings: any): DingConfig {
+	if (!settings || typeof settings !== "object" || !(SETTINGS_KEY in settings)) return {};
+	return sanitizeConfig(settings[SETTINGS_KEY]);
+}
+
+function findInPath(cmd: string): string | undefined {
+	const PATH = process.env.PATH || "";
+	for (const p of PATH.split(path.delimiter)) {
+		if (!p) continue;
+		const full = path.join(p, cmd);
+		try {
+			fs.accessSync(full, fs.constants.X_OK);
+			return full;
+		} catch {
+			// ignore
+		}
+	}
+	return undefined;
+}
+
+function playAuto(filePath: string) {
+	if (!fs.existsSync(filePath)) {
+		terminalBell();
+		return;
+	}
+
+	const candidates: Array<{ cmd: string; args: string[] }> = [
+		{ cmd: "mpv", args: ["--no-video", "--really-quiet", filePath] },
+		{ cmd: "ffplay", args: ["-nodisp", "-autoexit", "-loglevel", "quiet", filePath] },
+		{ cmd: "paplay", args: [filePath] },
+		{ cmd: "afplay", args: [filePath] },
+		{ cmd: "aplay", args: [filePath] },
+	];
+
+	const runAt = (i: number) => {
+		if (i >= candidates.length) {
+			terminalBell();
+			return;
+		}
+		const { cmd, args } = candidates[i];
+		trySpawnDetached(cmd, args, () => runAt(i + 1));
+	};
+
+	runAt(0);
+}
+
+export default function (pi: ExtensionAPI) {
+	// Per-run overrides. The point of settings-based config is that most users will not need these.
+	pi.registerFlag("ding", {
+		description: "Enable pi-ding (disable with --no-ding)",
+		type: "boolean",
+		default: true,
+	});
+	pi.registerFlag("ding-player", { description: "Override player executable", type: "string" });
+	pi.registerFlag("ding-path", { description: "Override sound file path", type: "string" });
+	pi.registerFlag("ding-args", {
+		description: "Override args as JSON array string, e.g. --ding-args '[\"--no-video\"]'",
+		type: "string",
+	});
+
+	let globalPath: string | undefined;
+	let projectPath: string | undefined;
+	let loadedFrom: ConfigSource = "default";
+	let lastLoadError: string | undefined;
+	let config: DingConfig = { ...DEFAULT_CONFIG };
+	let globalConfig: DingConfig = {};
+	let projectConfig: DingConfig = {};
+
+	function parseArgsFlag(): string[] | undefined {
+		const raw = pi.getFlag("ding-args");
+		if (typeof raw !== "string" || raw.trim().length === 0) return undefined;
+		try {
+			const parsed = JSON.parse(raw);
+			return isStringArray(parsed) ? parsed : undefined;
+		} catch {
+			return undefined;
+		}
+	}
+
+	function loadSettings(ctx: ExtensionContext) {
+		lastLoadError = undefined;
+		globalPath = getGlobalSettingsPath();
+		projectPath = getProjectSettingsPath(ctx);
+
+		const g = readJsonFile(globalPath);
+		const p = readJsonFile(projectPath);
+
+		if (!g.ok) lastLoadError = `Invalid JSON in ${globalPath}: ${g.error}`;
+		if (!p.ok) lastLoadError = lastLoadError ?? `Invalid JSON in ${projectPath}: ${p.error}`;
+
+		const globalCfg = g.ok ? extractDingConfigFromSettings(g.data) : { ...DEFAULT_CONFIG };
+		const projectCfg = p.ok ? extractDingConfigFromSettings(p.data) : {};
+		globalConfig = globalCfg;
+		projectConfig = projectCfg;
+
+		config = mergeConfig(globalCfg, projectCfg);
+
+		// Determine source used (best-effort)
+		const projectHasKey = p.ok && p.data && typeof p.data === "object" && SETTINGS_KEY in p.data;
+		const globalHasKey = g.ok && g.data && typeof g.data === "object" && SETTINGS_KEY in g.data;
+		loadedFrom = projectHasKey ? "project" : globalHasKey ? "global" : "default";
+	}
+
+	function getEffectiveConfig(): DingConfig {
+		const player = pi.getFlag("ding-player");
+		const p = pi.getFlag("ding-path");
+		const args = parseArgsFlag();
+		return {
+			...config,
+			...(typeof player === "string" && player.trim().length > 0 ? { player } : {}),
+			...(typeof p === "string" && p.trim().length > 0 ? { path: p } : {}),
+			...(args ? { args } : {}),
+		};
+	}
+
+	function isEnabled(cfg: DingConfig): boolean {
+		const runFlag = pi.getFlag("ding");
+		const runEnabled = typeof runFlag === "boolean" ? runFlag : true;
+		const cfgEnabled = cfg.enabled ?? true;
+		return runEnabled && cfgEnabled;
+	}
+
+	function play(ctx: ExtensionContext, options?: { force?: boolean }) {
+		const cfg = getEffectiveConfig();
+		if (!options?.force && !isEnabled(cfg)) return;
+
+		if (!cfg.path || cfg.path.trim().length === 0) {
+			terminalBell();
+			return;
+		}
+
+		const resolvedPath = resolveMaybeRelative(ctx, cfg.path);
+		if (!fs.existsSync(resolvedPath)) {
+			terminalBell();
+			return;
+		}
+
+		const player = typeof cfg.player === "string" ? cfg.player.trim() : "";
+		const args = isStringArray(cfg.args) ? cfg.args : [];
+
+		if (player.length > 0) {
+			trySpawnDetached(player, [...args, resolvedPath], () => terminalBell());
+			return;
+		}
+
+		playAuto(resolvedPath);
+	}
+
+	function updateSettingsDing(ctx: ExtensionContext, target: "project" | "global", newDing: DingConfig) {
+		const settingsPath = target === "project" ? getProjectSettingsPath(ctx) : getGlobalSettingsPath();
+		const current = readJsonFile(settingsPath);
+		if (!current.ok) {
+			throw new Error(`Can't write ${settingsPath}: invalid JSON (${current.error})`);
+		}
+		const root = current.data && typeof current.data === "object" ? current.data : {};
+		root[SETTINGS_KEY] = sanitizeConfig(newDing);
+		writeJsonFile(settingsPath, root);
+		// Reload to sync in-memory
+		loadSettings(ctx);
+	}
+
+	function defaultWriteTarget(): "project" | "global" {
+		// Prefer project so teams can commit `.pi/settings.json`.
+		return "project";
+	}
+
+	pi.on("session_start", async (_event, ctx) => {
+		loadSettings(ctx);
+		if (ctx.hasUI && lastLoadError) ctx.ui.notify(lastLoadError, "warning");
+	});
+
+	pi.on("agent_end", async (_event, ctx) => {
+		if (!ctx.hasUI) return;
+		play(ctx);
+	});
+
+	pi.registerCommand("ding", {
+		description: "Configure and test pi-ding (usage: /ding [on|off|test|info|edit|reload])",
+		handler: async (args, ctx) => {
+			const tokens = (args || "").trim().split(/\s+/).filter(Boolean);
+			const sub = (tokens[0] || "").toLowerCase();
+
+			if (sub === "test") {
+				play(ctx, { force: true });
+				ctx.ui.notify("Played ding", "info");
+				return;
+			}
+
+			if (sub === "reload") {
+				loadSettings(ctx);
+				ctx.ui.notify("Reloaded ding settings", "info");
+				if (lastLoadError) ctx.ui.notify(lastLoadError, "warning");
+				return;
+			}
+
+			if (sub === "edit") {
+				const scope = (tokens[1] || "").toLowerCase();
+				const target: "project" | "global" = scope === "global" ? "global" : "project";
+
+				const rootPath = target === "project" ? getProjectSettingsPath(ctx) : getGlobalSettingsPath();
+				const current = readJsonFile(rootPath);
+				if (!current.ok) {
+					ctx.ui.notify(`Invalid JSON in ${rootPath}: ${current.error}`, "error");
+					return;
+				}
+
+				const existingRoot =
+					current.data && typeof current.data === "object" ? (current.data as any) : {};
+				const existingDing = sanitizeConfig(existingRoot[SETTINGS_KEY]);
+
+				const prefill = JSON.stringify(existingDing, null, 2) + "\n";
+				const edited = await ctx.ui.editor(`Edit ding config (${target})`, prefill);
+				if (edited === undefined) return;
+
+				try {
+					const parsed = JSON.parse(edited);
+					updateSettingsDing(ctx, target, sanitizeConfig(parsed));
+					ctx.ui.notify(`Saved ding config to ${rootPath}`, "info");
+				} catch (e) {
+					const msg = e instanceof Error ? e.message : String(e);
+					ctx.ui.notify(`Invalid JSON: ${msg}`, "error");
+				}
+				return;
+			}
+
+			if (sub === "info") {
+				const effective = getEffectiveConfig();
+				const resolved = effective.path ? resolveMaybeRelative(ctx, effective.path) : undefined;
+				const exists = resolved ? fs.existsSync(resolved) : undefined;
+				const players = ["mpv", "ffplay", "paplay", "afplay", "aplay"].map((c) => {
+					const found = findInPath(c);
+					return `${c}: ${found ?? "not found"}`;
+				});
+
+				const lines = [
+					`loadedFrom: ${loadedFrom}`,
+					`projectSettings: ${projectPath ?? "(unknown)"}`,
+					`globalSettings: ${globalPath ?? "(unknown)"}`,
+					lastLoadError ? `loadError: ${lastLoadError}` : undefined,
+					"",
+					`effective.enabled: ${isEnabled(effective)}`,
+					`effective.player: ${effective.player ?? "(auto)"}`,
+					`effective.args: ${isStringArray(effective.args) ? JSON.stringify(effective.args) : "(none)"}`,
+					`effective.path: ${effective.path ?? "(none)"}`,
+					`resolved.path: ${resolved ?? "(n/a)"}`,
+					`resolved.exists: ${typeof exists === "boolean" ? exists : "(n/a)"}`,
+					"",
+					"Players in PATH:",
+					...players,
+				].filter((l): l is string => typeof l === "string");
+
+				ctx.ui.notify(lines.join("\n"), "info");
+				return;
+			}
+
+			// Default: toggle enabled, persist
+			const target = defaultWriteTarget();
+			const current = config.enabled ?? true;
+			let next: boolean;
+			if (sub === "on") next = true;
+			else if (sub === "off") next = false;
+			else next = !current;
+
+			try {
+				const base = target === "project" ? projectConfig : globalConfig;
+				updateSettingsDing(ctx, target, mergeConfig(base, { enabled: next }));
+				ctx.ui.notify(`Ding ${next ? "enabled" : "disabled"} (saved to ${target})`, "info");
+			} catch (e) {
+				const msg = e instanceof Error ? e.message : String(e);
+				ctx.ui.notify(msg, "error");
+			}
+		},
+	});
+}

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "pi-ding",
+  "version": "0.1.0",
+  "description": "Pi extension: play a sound when the agent finishes a prompt",
+  "type": "module",
+  "keywords": ["pi-package", "pi-extension", "pi"],
+  "license": "MIT",
+  "author": "ninlds",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ninlds/pi-ding.git"
+  },
+  "bugs": {
+    "url": "https://github.com/ninlds/pi-ding/issues"
+  },
+  "homepage": "https://github.com/ninlds/pi-ding#readme",
+  "pi": {
+    "extensions": ["./extensions"]
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*"
+  },
+  "files": [
+    "extensions",
+    "README.md",
+    "LICENSE",
+    "package.json"
+  ]
+}