@henryqw/pi-bark 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Wang
+
+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,184 @@
+# `@henryqw/pi-bark`
+
+Use Bark as an out-of-band status channel for Pi sessions. The extension reports when Pi finishes or waits for input. `/copyb` can also send the last agent message.
+
+## Install
+
+```bash
+pi install npm:@henryqw/pi-bark
+```
+
+### Setup
+
+1. Open the Bark App and copy its test URL.
+2. Take the Device Key from the URL.
+3. Run `/set-bark` in Pi.
+
+For Bark's public server:
+
+```text
+/set-bark your-device-key
+```
+
+For a self-hosted Bark server:
+
+```text
+/set-bark your-device-key https://bark.example.com
+```
+
+A test URL such as `https://api.day.app/your-device-key/Test` contains the Device Key after the host. Do not include sample push content such as `/Test`.
+
+Treat the Device Key as a secret. Anyone with it can send push notifications to your device.
+
+## Use
+
+Run `/copyb` with no arguments.
+
+The command copies the last agent message to your clipboard. It then sends a Bark V2 push request to `<serverUrl>/push`.
+
+Without push encryption, the JSON request uses Bark's standard parameter names:
+
+```json
+{
+  "device_key": "your-device-key",
+  "body": "the last agent message"
+}
+```
+
+The `body` value is the same text that Pi's `/copy` command selects. Markdown, code blocks, spacing, and line breaks stay unchanged.
+
+| Surface | Type | Purpose |
+| --- | --- | --- |
+| `/copyb` | command | Copy the last agent message and send a Bark push notification. |
+| `/set-bark <device-key> [server-url]` | command | Save the Device Key and Bark server URL. |
+| `/bark-notifications on\|off\|inherit` | command | Override automatic status notifications for the current CWD. |
+| `/bark-notifications default on\|off` | command | Set the default for CWDs without an override. |
+| `pi-bark-key [--force \| --disable]` | executable | Generate, replace, or disable the Custom Encryption Key. |
+
+### Automatic status notifications
+
+After setup, pi-bark sends two status-only notifications:
+
+- **Pi needs input** when Pi opens a blocking user prompt, including `ask_question`.
+- **Pi finished** after the agent has fully settled and will not continue automatically.
+
+Each notification includes Pi's current session name. Herdr shows the same name when `pi-herdr-rename` is active. pi-bark does not call Herdr or read Herdr state.
+
+An unset session name appears as `Unnamed`. Status notifications do not include prompts or agent output. No notification is sent when a prompt closes.
+
+Automatic notifications are enabled by default. Disable them only in the current CWD:
+
+```text
+/bark-notifications off
+```
+
+Use `on` to enable the current CWD explicitly. Use `inherit` to remove its override. The CWD then follows the global default.
+
+Change that default for all CWDs without an override:
+
+```text
+/bark-notifications default off
+```
+
+These settings do not affect `/copyb`. CWD overrides live in pi-bark's global config, not in project files.
+
+## Flow
+
+```mermaid
+flowchart LR
+    copy["/copyb"] --> clipboard["Clipboard"]
+    copy --> bark["pi-bark"]
+    status["Pi status event"] --> bark
+    bark --> request["Bark V2 /push request"]
+    request --> server["Bark server"]
+    server --> app["Bark App"]
+```
+
+## Config
+
+Package-owned: `~/.pi/agent/config/pi-bark/config.json`
+
+| Name | Description | Values | Default |
+| --- | --- | --- | --- |
+| `serverUrl` | Base URL of the Bark server that accepts push requests. | HTTP or HTTPS URL with an optional path and no query or fragment. | `"https://api.day.app"` |
+| `deviceKey` | Identifies the Bark App installation that receives the push notification. | Non-empty string or `null`. | `null` |
+| `encryption` | Custom Encryption Key and matching Bark encryption settings. | AES256-GCM settings object or `null`. | `null` |
+| `statusNotifications` | Controls automatic status notifications by CWD. | Global boolean default and absolute-CWD boolean overrides. | Enabled with no overrides. |
+
+### Push encryption
+
+Push encryption is optional. It prevents the Bark server and Apple Push Notification service from reading the push content.
+
+Generate and store a Custom Encryption Key:
+
+```bash
+npx @henryqw/pi-bark
+```
+
+The script prints the generated key once. Enter these exact settings in **Bark App → Push Encryption**:
+
+| Setting | Value |
+| --- | --- |
+| Algorithm | `AES256` |
+| Mode | `GCM` |
+| Padding | `noPadding` |
+| Key | The generated 32-character key |
+
+Do not paste script output into shared logs. The Custom Encryption Key can decrypt your push content.
+
+When enabled, pi-bark encrypts the JSON push content with a fresh 12-character IV. This includes status titles and session names. It sends `device_key`, `ciphertext`, and `iv` to the Bark server.
+
+The GCM authentication tag is appended to the ciphertext before Base64 encoding, as Bark requires.
+
+The script protects an existing Custom Encryption Key. Replace it only when you intend to update the Bark App too:
+
+```bash
+npx @henryqw/pi-bark --force
+```
+
+Disable push encryption in pi-bark with:
+
+```bash
+npx @henryqw/pi-bark --disable
+```
+
+Disable Push Encryption in the Bark App too. Otherwise its settings no longer match pi-bark.
+
+The config file has this shape:
+
+```json
+{
+  "serverUrl": "https://api.day.app",
+  "deviceKey": "your-device-key",
+  "encryption": {
+    "algorithm": "AES256",
+    "mode": "GCM",
+    "padding": "noPadding",
+    "key": "your-32-character-custom-key"
+  },
+  "statusNotifications": {
+    "defaultEnabled": true,
+    "cwdOverrides": {
+      "/srv/quiet-project": false
+    }
+  }
+}
+```
+
+Set `encryption` to `null` when push encryption is disabled.
+
+- A missing config stays missing until a command or the key script writes it.
+- `/set-bark` preserves Push Encryption and status notification settings.
+- The server URL must use HTTP or HTTPS. It cannot contain a query or fragment delimiter.
+- Config writes are private and atomic.
+- Pi commands never print the Device Key, server URL, or Custom Encryption Key.
+
+## Limits and recovery
+
+Bark and Apple Push Notification service limit notification payload sizes. This extension does not truncate push content. Bark returns an error when a message is too large.
+
+`/copyb` waits up to 15 seconds for the Bark server. If the push request fails after the clipboard copy, your clipboard still contains the message.
+
+Invalid config files cause a visible error and remain unchanged. Fix or move the malformed file, then retry the command.
+
+See Bark's [Push Encryption documentation](https://github.com/Finb/Bark/blob/master/docs/en-us/encryption.md) for the encryption model.

package/dist/scripts/generate-encryption-key.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { createBarkConfigStore, ENCRYPTION_ALGORITHM, ENCRYPTION_MODE, ENCRYPTION_PADDING, } from "../src/config.js";
+import { generateEncryptionKey } from "../src/encryption.js";
+const args = process.argv.slice(2);
+const force = args.length === 1 && args[0] === "--force";
+const disable = args.length === 1 && args[0] === "--disable";
+if (args.length > 1 || (args.length === 1 && !force && !disable)) {
+    console.error("Usage: pi-bark-key [--force | --disable]");
+    process.exitCode = 1;
+}
+else {
+    const store = createBarkConfigStore();
+    try {
+        if (disable) {
+            await store.update((config) => ({ ...config, encryption: null }));
+            console.log("Disabled Bark push encryption.");
+        }
+        else {
+            let key = "";
+            await store.update((config) => {
+                if (config.encryption && !force) {
+                    throw new Error("A Bark Custom Encryption Key already exists. Use --force to replace it.");
+                }
+                key = generateEncryptionKey();
+                return {
+                    ...config,
+                    encryption: {
+                        algorithm: ENCRYPTION_ALGORITHM,
+                        mode: ENCRYPTION_MODE,
+                        padding: ENCRYPTION_PADDING,
+                        key,
+                    },
+                };
+            });
+            console.log("Generated and saved a Bark Custom Encryption Key.");
+            console.log(`Algorithm: ${ENCRYPTION_ALGORITHM}`);
+            console.log(`Mode: ${ENCRYPTION_MODE}`);
+            console.log(`Padding: ${ENCRYPTION_PADDING}`);
+            console.log(`Key: ${key}`);
+            console.log("Enter these settings in Bark App > Push Encryption.");
+        }
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : String(error));
+        process.exitCode = 1;
+    }
+}

package/dist/src/config.js

@@ -0,0 +1,111 @@
+import { isAbsolute, resolve } from "node:path";
+import { createConfigStore } from "@henryqw/pi-config-store";
+export const DEFAULT_SERVER_URL = "https://api.day.app";
+export const ENCRYPTION_ALGORITHM = "AES256";
+export const ENCRYPTION_MODE = "GCM";
+export const ENCRYPTION_PADDING = "noPadding";
+export const ENCRYPTION_KEY_BYTES = 32;
+export function parseServerUrl(value) {
+    const input = value.trim();
+    let url;
+    try {
+        url = new URL(input);
+    }
+    catch {
+        throw new Error("Bark server URL must be a valid HTTP or HTTPS URL.");
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:") {
+        throw new Error("Bark server URL must use HTTP or HTTPS.");
+    }
+    if (input.includes("?") || input.includes("#")) {
+        throw new Error("Bark server URL must not include a query or fragment.");
+    }
+    return url.href.replace(/\/$/, "");
+}
+export function parseDeviceKey(value) {
+    if (value === null)
+        return null;
+    if (typeof value !== "string" || !value.trim()) {
+        throw new Error('Invalid Bark config: "deviceKey" must be a non-empty string.');
+    }
+    return value.trim();
+}
+function parseEncryption(value) {
+    if (value === null)
+        return null;
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error('Invalid Bark config: "encryption" must be an object or null.');
+    }
+    const encryption = value;
+    if (Object.keys(encryption).length !== 4 ||
+        encryption.algorithm !== ENCRYPTION_ALGORITHM ||
+        encryption.mode !== ENCRYPTION_MODE ||
+        encryption.padding !== ENCRYPTION_PADDING ||
+        typeof encryption.key !== "string" ||
+        Buffer.byteLength(encryption.key, "utf8") !== ENCRYPTION_KEY_BYTES) {
+        throw new Error(`Invalid Bark encryption config: expected ${ENCRYPTION_ALGORITHM}, ${ENCRYPTION_MODE}, ${ENCRYPTION_PADDING}, and a ${ENCRYPTION_KEY_BYTES}-byte UTF-8 key.`);
+    }
+    return {
+        algorithm: ENCRYPTION_ALGORITHM,
+        mode: ENCRYPTION_MODE,
+        padding: ENCRYPTION_PADDING,
+        key: encryption.key,
+    };
+}
+function parseStatusNotifications(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error('Invalid Bark config: "statusNotifications" must be an object.');
+    }
+    const notifications = value;
+    const overrides = notifications.cwdOverrides;
+    if (Object.keys(notifications).length !== 2 ||
+        typeof notifications.defaultEnabled !== "boolean" ||
+        !overrides ||
+        typeof overrides !== "object" ||
+        Array.isArray(overrides)) {
+        throw new Error('Invalid Bark config: expected "defaultEnabled" and "cwdOverrides" notification settings.');
+    }
+    const entries = Object.entries(overrides);
+    if (entries.some(([cwd, enabled]) => !isAbsolute(cwd) || typeof enabled !== "boolean")) {
+        throw new Error("Invalid Bark config: CWD notification overrides must map absolute paths to booleans.");
+    }
+    return {
+        defaultEnabled: notifications.defaultEnabled,
+        cwdOverrides: Object.fromEntries(entries),
+    };
+}
+function parseBarkConfig(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid Bark config: expected Bark settings object.");
+    }
+    const config = value;
+    if (Object.keys(config).length !== 4 ||
+        typeof config.serverUrl !== "string" ||
+        !("deviceKey" in config) ||
+        !("encryption" in config) ||
+        !("statusNotifications" in config)) {
+        throw new Error("Invalid Bark config: expected server, device, encryption, and notification settings.");
+    }
+    return {
+        serverUrl: parseServerUrl(config.serverUrl),
+        deviceKey: parseDeviceKey(config.deviceKey),
+        encryption: parseEncryption(config.encryption),
+        statusNotifications: parseStatusNotifications(config.statusNotifications),
+    };
+}
+export function statusNotificationsEnabled(config, cwd) {
+    return config.statusNotifications.cwdOverrides[resolve(cwd)] ?? config.statusNotifications.defaultEnabled;
+}
+export function createBarkConfigStore(agentDir) {
+    return createConfigStore({
+        extensionId: "pi-bark",
+        agentDir,
+        defaults: () => ({
+            serverUrl: DEFAULT_SERVER_URL,
+            deviceKey: null,
+            encryption: null,
+            statusNotifications: { defaultEnabled: true, cwdOverrides: {} },
+        }),
+        parse: parseBarkConfig,
+    });
+}

package/dist/src/encryption.js

@@ -0,0 +1,20 @@
+import { createCipheriv, randomBytes } from "node:crypto";
+import { ENCRYPTION_KEY_BYTES } from "./config.js";
+const RANDOM_TEXT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const GCM_IV_BYTES = 12;
+function randomText(length) {
+    return Array.from(randomBytes(length), (byte) => RANDOM_TEXT_ALPHABET[byte & 63]).join("");
+}
+export function generateEncryptionKey() {
+    return randomText(ENCRYPTION_KEY_BYTES);
+}
+export function encryptPushContent(content, encryption) {
+    const iv = randomText(GCM_IV_BYTES);
+    const cipher = createCipheriv("aes-256-gcm", Buffer.from(encryption.key, "utf8"), Buffer.from(iv, "utf8"));
+    const encrypted = Buffer.concat([
+        cipher.update(JSON.stringify(content), "utf8"),
+        cipher.final(),
+        cipher.getAuthTag(),
+    ]);
+    return { ciphertext: encrypted.toString("base64"), iv };
+}

package/extensions/bark.ts

@@ -0,0 +1,190 @@
+import { resolve } from "node:path";
+import { copyToClipboard, type ExtensionAPI, type SessionEntry } from "@earendil-works/pi-coding-agent";
+import {
+	createBarkConfigStore,
+	DEFAULT_SERVER_URL,
+	parseDeviceKey,
+	parseServerUrl,
+	statusNotificationsEnabled,
+	type BarkConfig,
+} from "../src/config.ts";
+import { encryptPushContent } from "../src/encryption.ts";
+
+const REQUEST_TIMEOUT_MS = 15_000;
+
+type BarkPushContent = { body: string } & Record<string, string>;
+
+type BarkExtensionOptions = {
+	agentDir?: string;
+	copy?: (text: string) => Promise<void>;
+	fetch?: typeof globalThis.fetch;
+};
+
+export function lastAssistantText(entries: readonly SessionEntry[]): string | undefined {
+	for (let index = entries.length - 1; index >= 0; index--) {
+		const entry = entries[index];
+		if (entry.type !== "message" || entry.message.role !== "assistant") continue;
+		const message = entry.message;
+		if (message.stopReason === "aborted" && message.content.length === 0) continue;
+		const text = message.content
+			.filter((part): part is { type: "text"; text: string } => part.type === "text")
+			.map((part) => part.text)
+			.join("")
+			.trim();
+		if (text) return text;
+	}
+	return undefined;
+}
+
+async function sendPush(
+	config: BarkConfig,
+	content: BarkPushContent,
+	fetchImpl: typeof globalThis.fetch,
+	cancelSignal?: AbortSignal,
+): Promise<void> {
+	if (!config.deviceKey) throw new Error("Bark Device Key is required.");
+	const payload = config.encryption ? encryptPushContent(content, config.encryption) : content;
+	let response: Response;
+	try {
+		response = await fetchImpl(`${config.serverUrl}/push`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json; charset=utf-8" },
+			body: JSON.stringify({ device_key: config.deviceKey, ...payload }),
+			signal: cancelSignal
+				? AbortSignal.any([cancelSignal, AbortSignal.timeout(REQUEST_TIMEOUT_MS)])
+				: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+		});
+	} catch (error) {
+		if (cancelSignal?.aborted) return;
+		throw new Error(`Bark push request failed: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (!response.ok) throw new Error(`Bark push request failed with HTTP ${response.status}.`);
+}
+
+export default function barkExtension(pi: ExtensionAPI, options: BarkExtensionOptions = {}): void {
+	const configStore = createBarkConfigStore(options.agentDir);
+	const copy = options.copy ?? copyToClipboard;
+	const fetchImpl = options.fetch ?? globalThis.fetch;
+
+	let statusPushQueue = Promise.resolve();
+	let pendingFinishedPush: AbortController | undefined;
+	const queueStatus = (
+		title: string,
+		cwd: string,
+		shouldSend?: Promise<boolean>,
+		cancelSignal?: AbortSignal,
+	): Promise<void> => {
+		let configSnapshot: BarkConfig;
+		try {
+			configSnapshot = configStore.loadSync().value;
+		} catch (error) {
+			return Promise.reject(error);
+		}
+		if (!configSnapshot.deviceKey || !statusNotificationsEnabled(configSnapshot, cwd)) return Promise.resolve();
+		const sessionName = pi.getSessionName()?.trim() || "Unnamed";
+		const contentSnapshot = { title, body: `Pi session: ${sessionName}` };
+		const send = async () => {
+			if (shouldSend && !(await shouldSend)) return;
+			await sendPush(configSnapshot, contentSnapshot, fetchImpl, cancelSignal);
+		};
+		const push = statusPushQueue.then(send, send);
+		statusPushQueue = push;
+		return push;
+	};
+
+	pi.on("ui_prompt_start", (_event, ctx) => {
+		void queueStatus("Pi needs input", ctx.cwd).catch((error) => {
+			ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+		});
+	});
+
+	pi.on("agent_start", () => {
+		pendingFinishedPush?.abort();
+		pendingFinishedPush = undefined;
+	});
+
+	pi.on("agent_settled", (_event, ctx) => {
+		if (!ctx.isIdle()) return;
+		const controller = new AbortController();
+		pendingFinishedPush?.abort();
+		pendingFinishedPush = controller;
+		const shouldSend = new Promise<boolean>((resolve) => {
+			setImmediate(() => resolve(ctx.isIdle()));
+		});
+		void queueStatus("Pi finished", ctx.cwd, shouldSend, controller.signal)
+			.catch((error) => {
+				ctx.ui.notify(error instanceof Error ? error.message : String(error), "warning");
+			})
+			.finally(() => {
+				if (pendingFinishedPush === controller) pendingFinishedPush = undefined;
+			});
+	});
+
+	pi.registerCommand("bark-notifications", {
+		description: "Configure automatic Bark status notifications",
+		handler: async (args, ctx) => {
+			const [first, second, extra] = args.trim().split(/\s+/);
+			if (extra || (first === "default" ? !["on", "off"].includes(second) : second)) {
+				throw new Error("Usage: /bark-notifications <on|off|inherit> | default <on|off>");
+			}
+			if (first === "default") {
+				const enabled = second === "on";
+				await configStore.update((config) => ({
+					...config,
+					statusNotifications: { ...config.statusNotifications, defaultEnabled: enabled },
+				}));
+				ctx.ui.notify(`${enabled ? "Enabled" : "Disabled"} Bark status notifications by default.`, "info");
+				return;
+			}
+			if (!(["on", "off", "inherit"] as const).includes(first as "on" | "off" | "inherit")) {
+				throw new Error("Usage: /bark-notifications <on|off|inherit> | default <on|off>");
+			}
+			const cwd = resolve(ctx.cwd);
+			await configStore.update((config) => {
+				const cwdOverrides = { ...config.statusNotifications.cwdOverrides };
+				if (first === "inherit") delete cwdOverrides[cwd];
+				else cwdOverrides[cwd] = first === "on";
+				return {
+					...config,
+					statusNotifications: { ...config.statusNotifications, cwdOverrides },
+				};
+			});
+			ctx.ui.notify(
+				first === "inherit"
+					? "This CWD now inherits the default Bark notification setting."
+					: `${first === "on" ? "Enabled" : "Disabled"} Bark status notifications for this CWD.`,
+				"info",
+			);
+		},
+	});
+
+	pi.registerCommand("copyb", {
+		description: "Copy the last agent message and send a Bark push notification",
+		handler: async (args, ctx) => {
+			if (args.trim()) throw new Error("Usage: /copyb");
+			const config = configStore.loadSync().value;
+			if (!config.deviceKey) throw new Error("Bark is not configured. Run /set-bark <device-key> [server-url] first.");
+
+			const text = lastAssistantText(ctx.sessionManager.buildContextEntries());
+			if (!text) throw new Error("No agent messages to copy yet.");
+
+			await copy(text);
+			await sendPush(config, { body: text }, fetchImpl);
+			ctx.ui.notify("Copied the last agent message and sent a Bark push notification.", "info");
+		},
+	});
+
+	pi.registerCommand("set-bark", {
+		description: "Set the Bark Device Key and optional server URL",
+		handler: async (args, ctx) => {
+			const [deviceKey, serverUrl = DEFAULT_SERVER_URL, extra] = args.trim().split(/\s+/);
+			if (!deviceKey || extra) throw new Error("Usage: /set-bark <device-key> [server-url]");
+			await configStore.update((config) => ({
+				...config,
+				serverUrl: parseServerUrl(serverUrl),
+				deviceKey: parseDeviceKey(deviceKey),
+			}));
+			ctx.ui.notify("Saved the Bark Device Key and server URL.", "info");
+		},
+	});
+}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@henryqw/pi-bark",
+  "version": "0.1.2",
+  "description": "Send Pi session status and agent output to Bark on iOS.",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "bark",
+    "ios",
+    "notification"
+  ],
+  "type": "module",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "license": "MIT",
+  "files": [
+    "LICENSE",
+    "dist",
+    "extensions",
+    "scripts",
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "pi-bark-key": "./dist/scripts/generate-encryption-key.js"
+  },
+  "scripts": {
+    "build": "tsc --project tsconfig.build.json",
+    "generate:key": "npm run build && node dist/scripts/generate-encryption-key.js",
+    "test": "npm run build && node --test test/*.test.ts",
+    "typecheck": "tsc --noEmit --allowImportingTsExtensions --target ES2022 --module NodeNext --moduleResolution NodeNext --skipLibCheck extensions/bark.ts scripts/*.ts src/*.ts test/*.test.ts",
+    "prepack": "npm run build",
+    "pack:check": "npm pack --dry-run"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.85.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/HenryQW/pi-harness.git",
+    "directory": "extensions/pi-bark"
+  },
+  "bugs": {
+    "url": "https://github.com/HenryQW/pi-harness/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/bark.ts"
+    ]
+  },
+  "dependencies": {
+    "@henryqw/pi-config-store": "^1.1.0"
+  }
+}

package/scripts/generate-encryption-key.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+
+import {
+	createBarkConfigStore,
+	ENCRYPTION_ALGORITHM,
+	ENCRYPTION_MODE,
+	ENCRYPTION_PADDING,
+} from "../src/config.ts";
+import { generateEncryptionKey } from "../src/encryption.ts";
+
+const args = process.argv.slice(2);
+const force = args.length === 1 && args[0] === "--force";
+const disable = args.length === 1 && args[0] === "--disable";
+
+if (args.length > 1 || (args.length === 1 && !force && !disable)) {
+	console.error("Usage: pi-bark-key [--force | --disable]");
+	process.exitCode = 1;
+} else {
+	const store = createBarkConfigStore();
+	try {
+		if (disable) {
+			await store.update((config) => ({ ...config, encryption: null }));
+			console.log("Disabled Bark push encryption.");
+		} else {
+			let key = "";
+			await store.update((config) => {
+				if (config.encryption && !force) {
+					throw new Error("A Bark Custom Encryption Key already exists. Use --force to replace it.");
+				}
+				key = generateEncryptionKey();
+				return {
+					...config,
+					encryption: {
+						algorithm: ENCRYPTION_ALGORITHM,
+						mode: ENCRYPTION_MODE,
+						padding: ENCRYPTION_PADDING,
+						key,
+					},
+				};
+			});
+			console.log("Generated and saved a Bark Custom Encryption Key.");
+			console.log(`Algorithm: ${ENCRYPTION_ALGORITHM}`);
+			console.log(`Mode: ${ENCRYPTION_MODE}`);
+			console.log(`Padding: ${ENCRYPTION_PADDING}`);
+			console.log(`Key: ${key}`);
+			console.log("Enter these settings in Bark App > Push Encryption.");
+		}
+	} catch (error) {
+		console.error(error instanceof Error ? error.message : String(error));
+		process.exitCode = 1;
+	}
+}

package/src/config.ts

@@ -0,0 +1,141 @@
+import { isAbsolute, resolve } from "node:path";
+import { createConfigStore } from "@henryqw/pi-config-store";
+
+export const DEFAULT_SERVER_URL = "https://api.day.app";
+export const ENCRYPTION_ALGORITHM = "AES256";
+export const ENCRYPTION_MODE = "GCM";
+export const ENCRYPTION_PADDING = "noPadding";
+export const ENCRYPTION_KEY_BYTES = 32;
+
+export type BarkEncryption = {
+	algorithm: typeof ENCRYPTION_ALGORITHM;
+	mode: typeof ENCRYPTION_MODE;
+	padding: typeof ENCRYPTION_PADDING;
+	key: string;
+};
+
+export type BarkConfig = {
+	serverUrl: string;
+	deviceKey: string | null;
+	encryption: BarkEncryption | null;
+	statusNotifications: {
+		defaultEnabled: boolean;
+		cwdOverrides: Record<string, boolean>;
+	};
+};
+
+export function parseServerUrl(value: string): string {
+	const input = value.trim();
+	let url: URL;
+	try {
+		url = new URL(input);
+	} catch {
+		throw new Error("Bark server URL must be a valid HTTP or HTTPS URL.");
+	}
+	if (url.protocol !== "http:" && url.protocol !== "https:") {
+		throw new Error("Bark server URL must use HTTP or HTTPS.");
+	}
+	if (input.includes("?") || input.includes("#")) {
+		throw new Error("Bark server URL must not include a query or fragment.");
+	}
+	return url.href.replace(/\/$/, "");
+}
+
+export function parseDeviceKey(value: unknown): string | null {
+	if (value === null) return null;
+	if (typeof value !== "string" || !value.trim()) {
+		throw new Error('Invalid Bark config: "deviceKey" must be a non-empty string.');
+	}
+	return value.trim();
+}
+
+function parseEncryption(value: unknown): BarkEncryption | null {
+	if (value === null) return null;
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error('Invalid Bark config: "encryption" must be an object or null.');
+	}
+	const encryption = value as Record<string, unknown>;
+	if (
+		Object.keys(encryption).length !== 4 ||
+		encryption.algorithm !== ENCRYPTION_ALGORITHM ||
+		encryption.mode !== ENCRYPTION_MODE ||
+		encryption.padding !== ENCRYPTION_PADDING ||
+		typeof encryption.key !== "string" ||
+		Buffer.byteLength(encryption.key, "utf8") !== ENCRYPTION_KEY_BYTES
+	) {
+		throw new Error(
+			`Invalid Bark encryption config: expected ${ENCRYPTION_ALGORITHM}, ${ENCRYPTION_MODE}, ${ENCRYPTION_PADDING}, and a ${ENCRYPTION_KEY_BYTES}-byte UTF-8 key.`,
+		);
+	}
+	return {
+		algorithm: ENCRYPTION_ALGORITHM,
+		mode: ENCRYPTION_MODE,
+		padding: ENCRYPTION_PADDING,
+		key: encryption.key,
+	};
+}
+
+function parseStatusNotifications(value: unknown): BarkConfig["statusNotifications"] {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error('Invalid Bark config: "statusNotifications" must be an object.');
+	}
+	const notifications = value as Record<string, unknown>;
+	const overrides = notifications.cwdOverrides;
+	if (
+		Object.keys(notifications).length !== 2 ||
+		typeof notifications.defaultEnabled !== "boolean" ||
+		!overrides ||
+		typeof overrides !== "object" ||
+		Array.isArray(overrides)
+	) {
+		throw new Error('Invalid Bark config: expected "defaultEnabled" and "cwdOverrides" notification settings.');
+	}
+	const entries = Object.entries(overrides);
+	if (entries.some(([cwd, enabled]) => !isAbsolute(cwd) || typeof enabled !== "boolean")) {
+		throw new Error("Invalid Bark config: CWD notification overrides must map absolute paths to booleans.");
+	}
+	return {
+		defaultEnabled: notifications.defaultEnabled,
+		cwdOverrides: Object.fromEntries(entries) as Record<string, boolean>,
+	};
+}
+
+function parseBarkConfig(value: unknown): BarkConfig {
+	if (!value || typeof value !== "object" || Array.isArray(value)) {
+		throw new Error("Invalid Bark config: expected Bark settings object.");
+	}
+	const config = value as Record<string, unknown>;
+	if (
+		Object.keys(config).length !== 4 ||
+		typeof config.serverUrl !== "string" ||
+		!("deviceKey" in config) ||
+		!("encryption" in config) ||
+		!("statusNotifications" in config)
+	) {
+		throw new Error("Invalid Bark config: expected server, device, encryption, and notification settings.");
+	}
+	return {
+		serverUrl: parseServerUrl(config.serverUrl),
+		deviceKey: parseDeviceKey(config.deviceKey),
+		encryption: parseEncryption(config.encryption),
+		statusNotifications: parseStatusNotifications(config.statusNotifications),
+	};
+}
+
+export function statusNotificationsEnabled(config: BarkConfig, cwd: string): boolean {
+	return config.statusNotifications.cwdOverrides[resolve(cwd)] ?? config.statusNotifications.defaultEnabled;
+}
+
+export function createBarkConfigStore(agentDir?: string) {
+	return createConfigStore<BarkConfig>({
+		extensionId: "pi-bark",
+		agentDir,
+		defaults: () => ({
+			serverUrl: DEFAULT_SERVER_URL,
+			deviceKey: null,
+			encryption: null,
+			statusNotifications: { defaultEnabled: true, cwdOverrides: {} },
+		}),
+		parse: parseBarkConfig,
+	});
+}

package/src/encryption.ts

@@ -0,0 +1,27 @@
+import { createCipheriv, randomBytes } from "node:crypto";
+import { ENCRYPTION_KEY_BYTES, type BarkEncryption } from "./config.ts";
+
+const RANDOM_TEXT_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+const GCM_IV_BYTES = 12;
+
+function randomText(length: number): string {
+	return Array.from(randomBytes(length), (byte) => RANDOM_TEXT_ALPHABET[byte & 63]).join("");
+}
+
+export function generateEncryptionKey(): string {
+	return randomText(ENCRYPTION_KEY_BYTES);
+}
+
+export function encryptPushContent(
+	content: Readonly<Record<string, string>>,
+	encryption: BarkEncryption,
+): { ciphertext: string; iv: string } {
+	const iv = randomText(GCM_IV_BYTES);
+	const cipher = createCipheriv("aes-256-gcm", Buffer.from(encryption.key, "utf8"), Buffer.from(iv, "utf8"));
+	const encrypted = Buffer.concat([
+		cipher.update(JSON.stringify(content), "utf8"),
+		cipher.final(),
+		cipher.getAuthTag(),
+	]);
+	return { ciphertext: encrypted.toString("base64"), iv };
+}