pi-boop 0.0.1

package/CHANGELOG.md

@@ -0,0 +1 @@
+# pi-boop

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Braden Lamb
+
+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,64 @@
+# pi-boop
+
+A [Pi](https://pi.dev) extension that plays the terminal bell or a custom sound when Pi finishes a turn and is waiting for your input.
+
+## Install
+
+```bash
+# from npm
+pi install npm:pi-boop
+
+# or from git
+pi install git:github.com/bradennss/pi-boop
+
+# try it for a single run without installing
+pi -e npm:pi-boop
+```
+
+## Usage
+
+Once installed, pi-boop rings the terminal bell every time Pi settles and waits for you.
+
+Run `/boop` at any time to play the sound and check your setup.
+
+### Play a custom sound
+
+Point pi-boop at an audio file to play it instead of the bell:
+
+```bash
+export PI_BOOP_SOUND=~/sounds/ready.wav
+```
+
+Or set it for a single run:
+
+```bash
+pi --boop-sound ~/sounds/ready.wav
+```
+
+pi-boop plays the file with the platform's player (`afplay` on macOS, `paplay` on Linux, PowerShell on Windows). If the file cannot be played, it falls back to the terminal bell.
+
+### Turn it off
+
+```bash
+export PI_BOOP_DISABLE=1   # every run
+pi --boop-off              # a single run
+```
+
+## Requirements
+
+- Node.js >= 20.
+
+## Development
+
+```bash
+pnpm install
+pnpm run check
+```
+
+## Contributing
+
+Every change that affects the published package needs a [changeset](https://github.com/changesets/changesets):
+
+```bash
+pnpm changeset
+```

package/SECURITY.md

@@ -0,0 +1,13 @@
+# Security Policy
+
+## Scope and behavior
+
+`pi-boop` is a Pi extension. Like all Pi extensions it runs with your full user permissions. This extension:
+
+- Writes the terminal bell character to standard error when Pi settles and waits for input.
+- When `PI_BOOP_SOUND` or `--boop-sound` is set, spawns the platform audio player (`afplay`, `paplay`, or PowerShell) with the path you provide to play that file.
+- Has no network calls, no telemetry, and no credential access. It has no runtime dependencies.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately via a [GitHub security advisory](https://github.com/bradennss/pi-boop/security/advisories/new). You will receive an acknowledgement within a few days.

package/index.ts

@@ -0,0 +1,54 @@
+/**
+ * pi-boop plays the terminal bell or a custom sound file when Pi finishes a
+ * turn and is waiting for user input.
+ */
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  resolveConfig,
+  settingsFromEnv,
+  type BoopConfig,
+  type RawBoopSettings,
+} from "./src/boop.ts";
+import { boop } from "./src/player.ts";
+
+const SOUND_FLAG = "boop-sound";
+const OFF_FLAG = "boop-off";
+
+export default function piBoop(pi: ExtensionAPI): void {
+  pi.registerFlag(SOUND_FLAG, {
+    type: "string",
+    description: "Path to a custom sound file to play when Pi waits for input.",
+  });
+  pi.registerFlag(OFF_FLAG, {
+    type: "boolean",
+    default: false,
+    description: "Disable pi-boop for this run.",
+  });
+
+  function currentConfig(): BoopConfig {
+    const env = settingsFromEnv(process.env);
+    const soundFlag = pi.getFlag(SOUND_FLAG);
+    const offFlag = pi.getFlag(OFF_FLAG);
+    const raw: RawBoopSettings = {
+      soundFile:
+        typeof soundFlag === "string" && soundFlag ? soundFlag : env.soundFile,
+      disabled: offFlag === true || env.disabled,
+    };
+    return resolveConfig(raw);
+  }
+
+  pi.on("agent_settled", async (_event, ctx) => {
+    if (!ctx.isIdle()) {
+      return;
+    }
+    boop(currentConfig());
+  });
+
+  pi.registerCommand("boop", {
+    description: "Play the pi-boop sound now to test your configuration.",
+    handler: async (_args, ctx) => {
+      boop(currentConfig());
+      ctx.ui.notify("Played pi-boop.", "info");
+    },
+  });
+}

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "pi-boop",
+  "version": "0.0.1",
+  "description": "Pi extension that plays the terminal bell or a custom sound when Pi waits for input.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Braden Lamb <hi@braden.lol>",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bradennss/pi-boop.git"
+  },
+  "homepage": "https://github.com/bradennss/pi-boop#readme",
+  "bugs": {
+    "url": "https://github.com/bradennss/pi-boop/issues"
+  },
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "pi-coding-agent",
+    "sound",
+    "bell",
+    "notify"
+  ],
+  "exports": {
+    ".": {
+      "types": "./index.ts",
+      "import": "./index.ts",
+      "default": "./index.ts"
+    }
+  },
+  "files": [
+    "index.ts",
+    "src",
+    "README.md",
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "packageManager": "pnpm@10.32.1",
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "check": "pnpm run typecheck && pnpm run lint && pnpm run format:check && pnpm test",
+    "prepack": "pnpm run check"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "devDependencies": {
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.1",
+    "@earendil-works/pi-coding-agent": "^0.84.2",
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^22.0.0",
+    "eslint": "^10.8.1",
+    "eslint-config-prettier": "^10.1.8",
+    "prettier": "^3.9.6",
+    "typescript": "^5.6.0",
+    "typescript-eslint": "^8.67.0",
+    "vitest": "^4.1.11"
+  }
+}

package/src/boop.ts

@@ -0,0 +1,65 @@
+/** The ASCII BEL character. Writing it to a terminal rings the terminal bell. */
+export const BELL = "\u0007";
+
+/** Resolved runtime behavior for a single boop. */
+export interface BoopConfig {
+  enabled: boolean;
+  soundFile: string | undefined;
+}
+
+/** Unnormalized settings gathered from the environment or CLI flags. */
+export interface RawBoopSettings {
+  soundFile?: string;
+  disabled?: boolean;
+}
+
+/** Normalize raw settings into a config the player can act on. */
+export function resolveConfig(raw: RawBoopSettings): BoopConfig {
+  const soundFile = raw.soundFile?.trim() ?? "";
+  return {
+    enabled: raw.disabled !== true,
+    soundFile: soundFile.length > 0 ? soundFile : undefined,
+  };
+}
+
+const TRUTHY = new Set(["1", "true", "yes", "on"]);
+
+/** Read raw settings from process environment variables. */
+export function settingsFromEnv(
+  env: Record<string, string | undefined>,
+): RawBoopSettings {
+  return {
+    soundFile: env.PI_BOOP_SOUND,
+    disabled: TRUTHY.has((env.PI_BOOP_DISABLE ?? "").trim().toLowerCase()),
+  };
+}
+
+/** A spawnable command that plays an audio file. */
+export interface PlayerCommand {
+  command: string;
+  args: string[];
+}
+
+/** Pick the command that plays a sound file on the given platform. */
+export function soundPlayerCommand(
+  platform: NodeJS.Platform,
+  soundFile: string,
+): PlayerCommand | undefined {
+  switch (platform) {
+    case "darwin":
+      return { command: "afplay", args: [soundFile] };
+    case "linux":
+      return { command: "paplay", args: [soundFile] };
+    case "win32":
+      return {
+        command: "powershell",
+        args: [
+          "-NoProfile",
+          "-Command",
+          `(New-Object Media.SoundPlayer '${soundFile}').PlaySync()`,
+        ],
+      };
+    default:
+      return undefined;
+  }
+}

package/src/player.ts

@@ -0,0 +1,48 @@
+import { spawn } from "node:child_process";
+import { BELL, soundPlayerCommand, type BoopConfig } from "./boop.ts";
+
+/** Injectable side effects so the player can be tested without real audio. */
+export interface PlayerDeps {
+  platform: NodeJS.Platform;
+  ringBell: () => void;
+  spawn: typeof spawn;
+}
+
+/** Real dependencies wired to the current process. */
+export function defaultDeps(): PlayerDeps {
+  return {
+    platform: process.platform,
+    ringBell: () => {
+      process.stderr.write(BELL);
+    },
+    spawn,
+  };
+}
+
+/**
+ * Play a single boop. Plays the configured sound file when one is set and the
+ * platform has a player, otherwise rings the terminal bell. A failed sound
+ * player also falls back to the bell.
+ */
+export function boop(
+  config: BoopConfig,
+  deps: PlayerDeps = defaultDeps(),
+): void {
+  if (!config.enabled) {
+    return;
+  }
+
+  if (config.soundFile) {
+    const command = soundPlayerCommand(deps.platform, config.soundFile);
+    if (command) {
+      const child = deps.spawn(command.command, command.args, {
+        stdio: "ignore",
+      });
+      child.on("error", deps.ringBell);
+      child.unref();
+      return;
+    }
+  }
+
+  deps.ringBell();
+}