dondon-notify 0.1.0

package/src/notify.ts

@@ -0,0 +1,521 @@
+/**
+ * notify
+ * Native OS notifications for OpenCode
+ *
+ * Philosophy: "Notify the human when the AI needs them back, not for every micro-event."
+ *
+ * Features:
+ * - Auto-detects terminal emulator (Ghostty, Kitty, iTerm, WezTerm, etc.)
+ * - Suppresses notifications when terminal is focused (like Ghostty does)
+ * - Click notification to focus terminal
+ * - Parent session only by default (no spam from sub-tasks)
+ *
+ * Uses node-notifier which bundles native binaries:
+ * - macOS: terminal-notifier (native NSUserNotificationCenter)
+ * - Windows: SnoreToast (native toast notifications)
+ * - Linux: notify-send (native desktop notifications)
+ */
+
+import * as fs from "node:fs/promises"
+import * as os from "node:os"
+import * as path from "node:path"
+import type { Plugin } from "@opencode-ai/plugin"
+import type { Event } from "@opencode-ai/sdk"
+import detectTerminal from "detect-terminal"
+import notifier from "node-notifier"
+import type { OpencodeClient } from "./plugin/kdco-primitives/types"
+
+interface NotifyConfig {
+	/** Notify for child/sub-session events (default: false) */
+	notifyChildSessions: boolean
+	/** Sound configuration per event type */
+	sounds: {
+		idle: string
+		error: string
+		permission: string
+	}
+	/** Quiet hours configuration */
+	quietHours: {
+		enabled: boolean
+		start: string // "HH:MM" format
+		end: string // "HH:MM" format
+	}
+	/** Override terminal detection (optional) */
+	terminal?: string
+	/** Kitty-specific configuration */
+	kitty?: {
+		/** Use native Kitty notifications (default: true when Kitty detected) */
+		enabled: boolean
+		/** Enable notification sounds (default: false, Kitty doesn't support sounds) */
+		sounds: boolean
+		/** Auto-focus terminal when notification is clicked (default: true) */
+		focusOnClick: boolean
+	}
+}
+
+interface TerminalInfo {
+	name: string | null
+	bundleId: string | null
+	processName: string | null
+	windowId?: string | null // Kitty window ID for Linux focus detection
+}
+
+const DEFAULT_CONFIG: NotifyConfig = {
+	notifyChildSessions: false,
+	sounds: {
+		idle: "Glass",
+		error: "Basso",
+		permission: "Submarine",
+	},
+	quietHours: {
+		enabled: false,
+		start: "22:00",
+		end: "08:00",
+	},
+	kitty: {
+		enabled: true,
+		sounds: false,
+		focusOnClick: true,
+	},
+}
+
+// Terminal name to process name mapping (for focus detection)
+const TERMINAL_PROCESS_NAMES: Record<string, string> = {
+	ghostty: "Ghostty",
+	kitty: "kitty",
+	iterm: "iTerm2",
+	iterm2: "iTerm2",
+	wezterm: "WezTerm",
+	alacritty: "Alacritty",
+	terminal: "Terminal",
+	apple_terminal: "Terminal",
+	hyper: "Hyper",
+	warp: "Warp",
+	vscode: "Code",
+	"vscode-insiders": "Code - Insiders",
+}
+
+// ==========================================
+// CONFIGURATION
+// ==========================================
+
+let cachedConfig: NotifyConfig | null = null
+
+async function loadConfig(): Promise<NotifyConfig> {
+	// Return cached config if available
+	if (cachedConfig) {
+		return cachedConfig
+	}
+
+	const configPath = path.join(os.homedir(), ".config", "opencode", "dondon-notify.json")
+
+	try {
+		const content = await fs.readFile(configPath, "utf8")
+		const userConfig = JSON.parse(content) as Partial<NotifyConfig>
+
+		// Merge with defaults
+		const config = {
+			...DEFAULT_CONFIG,
+			...userConfig,
+			sounds: {
+				...DEFAULT_CONFIG.sounds,
+				...userConfig.sounds,
+			},
+			quietHours: {
+				...DEFAULT_CONFIG.quietHours,
+				...userConfig.quietHours,
+			},
+			kitty: {
+				...DEFAULT_CONFIG.kitty,
+				...userConfig.kitty,
+			},
+		}
+		
+		// Cache the config
+		cachedConfig = config
+		return config
+	} catch {
+		// Config doesn't exist or is invalid, use defaults
+		cachedConfig = DEFAULT_CONFIG
+		return DEFAULT_CONFIG
+	}
+}
+
+function loadConfigSync(): NotifyConfig | null {
+	return cachedConfig
+}
+
+// ==========================================
+// TERMINAL DETECTION (macOS)
+// ==========================================
+
+async function runOsascript(script: string): Promise<string | null> {
+	if (process.platform !== "darwin") return null
+
+	try {
+		const proc = Bun.spawn(["osascript", "-e", script], {
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		const output = await new Response(proc.stdout).text()
+		return output.trim()
+	} catch {
+		return null
+	}
+}
+
+async function getBundleId(appName: string): Promise<string | null> {
+	return runOsascript(`id of application "${appName}"`)
+}
+
+// ==========================================
+// KITTY-SPECIFIC FUNCTIONS (Linux)
+// ==========================================
+
+function isKittyTerminal(): boolean {
+	// Check if we're running in Kitty
+	return process.env.TERM?.toLowerCase().includes("kitty") || 
+		   process.env.TERMINAL?.toLowerCase().includes("kitty") ||
+		   detectTerminal()?.toLowerCase() === "kitty"
+}
+
+async function getKittyWindowId(): Promise<string | null> {
+	try {
+		// Kitty sets WINDOWID environment variable
+		return process.env.WINDOWID || null
+	} catch {
+		return null
+	}
+}
+
+async function isKittyWindowFocused(windowId: string): Promise<boolean> {
+	try {
+		// Use xprop to check if the window is focused
+		const proc = Bun.spawn(["xprop", "-root", "_NET_ACTIVE_WINDOW"], {
+			stdout: "pipe",
+			stderr: "pipe",
+		})
+		const output = await new Response(proc.stdout).text()
+		
+		// Extract the active window ID from xprop output
+		const activeWindowMatch = output.match(/_NET_ACTIVE_WINDOW.*?# (0x[0-9a-f]+)/i)
+		if (!activeWindowMatch) return false
+		
+		const activeWindowId = activeWindowMatch[1]
+		return activeWindowId.toLowerCase() === windowId.toLowerCase()
+	} catch {
+		// If xprop fails or isn't available, assume not focused to be safe
+		return false
+	}
+}
+
+interface KittyNotificationOptions {
+	title: string
+	message: string
+	sound?: string
+	focusOnClick?: boolean
+}
+
+function sendKittyNotification(options: KittyNotificationOptions): void {
+	const { title, message, sound, focusOnClick = true } = options
+	
+	try {
+		// Build Kitty OSC 99 notification metadata
+		const metadataParts = ["i=1", "d=1"]
+		
+		// Add focus action if requested
+		if (focusOnClick) {
+			metadataParts.push("a=focus")
+		}
+		
+		// Add sound if configured ( Kitty supports some sound names)
+		if (sound && sound !== "silent") {
+			metadataParts.push(`s=${sound}`)
+		}
+		
+		const metadata = metadataParts.join(":")
+		const titlePayload = `p=title;${title}`
+		const bodyPayload = `p=body;${message}`
+		
+		// Create the escape sequence
+		const escapeSequence = `\x1b]99;${metadata};${titlePayload}\x1b\\\x1b]99;${metadata};${bodyPayload}\x1b\\`
+		
+		// Send to stdout
+		process.stdout.write(escapeSequence)
+	} catch (error) {
+		// Fall back to system notification if Kitty notification fails
+		console.warn("Kitty notification failed, falling back to system notification:", error)
+		notifier.notify({ title, message, sound })
+	}
+}
+
+async function getFrontmostApp(): Promise<string | null> {
+	return runOsascript(
+		'tell application "System Events" to get name of first application process whose frontmost is true',
+	)
+}
+
+async function detectTerminalInfo(config: NotifyConfig): Promise<TerminalInfo> {
+	// Use config override if provided
+	const terminalName = config.terminal || detectTerminal() || null
+
+	if (!terminalName) {
+		return { name: null, bundleId: null, processName: null, windowId: null }
+	}
+
+	// Get process name for focus detection
+	const processName = TERMINAL_PROCESS_NAMES[terminalName.toLowerCase()] || terminalName
+
+	// Dynamically get bundle ID from macOS (no hardcoding!)
+	const bundleId = await getBundleId(processName)
+
+	// Get Kitty window ID for Linux focus detection
+	let windowId: string | null = null
+	if (terminalName.toLowerCase() === "kitty" && process.platform === "linux") {
+		windowId = await getKittyWindowId()
+	}
+
+	return {
+		name: terminalName,
+		bundleId,
+		processName,
+		windowId,
+	}
+}
+
+async function isTerminalFocused(terminalInfo: TerminalInfo): Promise<boolean> {
+	if (!terminalInfo.processName) return false
+
+	if (process.platform === "darwin") {
+		// macOS focus detection
+		const frontmost = await getFrontmostApp()
+		if (!frontmost) return false
+		return frontmost.toLowerCase() === terminalInfo.processName.toLowerCase()
+	} else if (process.platform === "linux" && terminalInfo.name?.toLowerCase() === "kitty" && terminalInfo.windowId) {
+		// Kitty focus detection on Linux
+		return await isKittyWindowFocused(terminalInfo.windowId)
+	}
+
+	return false
+}
+
+// ==========================================
+// QUIET HOURS CHECK
+// ==========================================
+
+function isQuietHours(config: NotifyConfig): boolean {
+	if (!config.quietHours.enabled) return false
+
+	const now = new Date()
+	const currentMinutes = now.getHours() * 60 + now.getMinutes()
+
+	const [startHour, startMin] = config.quietHours.start.split(":").map(Number)
+	const [endHour, endMin] = config.quietHours.end.split(":").map(Number)
+
+	const startMinutes = startHour * 60 + startMin
+	const endMinutes = endHour * 60 + endMin
+
+	// Handle overnight quiet hours (e.g., 22:00 - 08:00)
+	if (startMinutes > endMinutes) {
+		return currentMinutes >= startMinutes || currentMinutes < endMinutes
+	}
+
+	return currentMinutes >= startMinutes && currentMinutes < endMinutes
+}
+
+// ==========================================
+// PARENT SESSION DETECTION
+// ==========================================
+
+async function isParentSession(client: OpencodeClient, sessionID: string): Promise<boolean> {
+	try {
+		const session = await client.session.get({ path: { id: sessionID } })
+		// No parentID means this IS the parent/root session
+		return !session.data?.parentID
+	} catch {
+		// If we can't fetch, assume it's a parent to be safe (notify rather than miss)
+		return true
+	}
+}
+
+// ==========================================
+// NOTIFICATION SENDER
+// ==========================================
+
+interface NotificationOptions {
+	title: string
+	message: string
+	sound: string
+	terminalInfo: TerminalInfo
+}
+
+function sendNotification(options: NotificationOptions): void {
+	const { title, message, sound, terminalInfo } = options
+
+	// Use Kitty notifications if available and on supported platform
+	if (terminalInfo.name?.toLowerCase() === "kitty" && process.platform === "linux") {
+		// Use default Kitty settings (simpler approach)
+		sendKittyNotification({
+			title,
+			message,
+			sound, // Kitty doesn't support sounds, but we pass it for fallback
+			focusOnClick: true,
+		})
+		return
+	}
+
+	// Fall back to system notifications
+	const notifyOptions: Record<string, unknown> = {
+		title,
+		message,
+		sound,
+	}
+
+	// macOS-specific: click notification to focus terminal
+	if (process.platform === "darwin" && terminalInfo.bundleId) {
+		notifyOptions.activate = terminalInfo.bundleId
+	}
+
+	notifier.notify(notifyOptions)
+}
+
+// ==========================================
+// EVENT HANDLERS
+// ==========================================
+
+async function handleSessionIdle(
+	client: OpencodeClient,
+	sessionID: string,
+	config: NotifyConfig,
+	terminalInfo: TerminalInfo,
+): Promise<void> {
+	// Check if we should notify for this session
+	if (!config.notifyChildSessions) {
+		const isParent = await isParentSession(client, sessionID)
+		if (!isParent) return
+	}
+
+	// Check quiet hours
+	if (isQuietHours(config)) return
+
+	// Check if terminal is focused (suppress notification if user is already looking)
+	if (await isTerminalFocused(terminalInfo)) return
+
+	// Get session info for context
+	let sessionTitle = "Task"
+	try {
+		const session = await client.session.get({ path: { id: sessionID } })
+		if (session.data?.title) {
+			sessionTitle = session.data.title.slice(0, 50)
+		}
+	} catch {
+		// Use default title
+	}
+
+	sendNotification({
+		title: "Ready for review",
+		message: sessionTitle,
+		sound: config.sounds.idle,
+		terminalInfo,
+	})
+}
+
+async function handleSessionError(
+	client: OpencodeClient,
+	sessionID: string,
+	error: string | undefined,
+	config: NotifyConfig,
+	terminalInfo: TerminalInfo,
+): Promise<void> {
+	// Check if we should notify for this session
+	if (!config.notifyChildSessions) {
+		const isParent = await isParentSession(client, sessionID)
+		if (!isParent) return
+	}
+
+	// Check quiet hours
+	if (isQuietHours(config)) return
+
+	// Check if terminal is focused (suppress notification if user is already looking)
+	if (await isTerminalFocused(terminalInfo)) return
+
+	const errorMessage = error?.slice(0, 100) || "Something went wrong"
+
+	sendNotification({
+		title: "Something went wrong",
+		message: errorMessage,
+		sound: config.sounds.error,
+		terminalInfo,
+	})
+}
+
+async function handlePermissionUpdated(
+	config: NotifyConfig,
+	terminalInfo: TerminalInfo,
+): Promise<void> {
+	// Always notify for permission events - AI is blocked waiting for human
+	// No parent check needed: permissions always need human attention
+
+	// Check quiet hours
+	if (isQuietHours(config)) return
+
+	// Check if terminal is focused (suppress notification if user is already looking)
+	if (await isTerminalFocused(terminalInfo)) return
+
+	sendNotification({
+		title: "Waiting for you",
+		message: "OpenCode needs your input",
+		sound: config.sounds.permission,
+		terminalInfo,
+	})
+}
+
+// ==========================================
+// PLUGIN EXPORT
+// ==========================================
+
+export const NotifyPlugin: Plugin = async (ctx) => {
+	const { client } = ctx
+
+	// Load config once at startup
+	const config = await loadConfig()
+
+	// Detect terminal once at startup (cached for performance)
+	const terminalInfo = await detectTerminalInfo(config)
+
+	return {
+		event: async ({ event }: { event: Event }): Promise<void> => {
+			switch (event.type) {
+				case "session.idle": {
+					const sessionID = event.properties.sessionID
+					if (sessionID) {
+						await handleSessionIdle(client as OpencodeClient, sessionID, config, terminalInfo)
+					}
+					break
+				}
+				case "session.error": {
+					const sessionID = event.properties.sessionID
+					const error = event.properties.error
+					const errorMessage = typeof error === "string" ? error : error ? String(error) : undefined
+					if (sessionID) {
+						await handleSessionError(
+							client as OpencodeClient,
+							sessionID,
+							errorMessage,
+							config,
+							terminalInfo,
+						)
+					}
+					break
+				}
+
+				case "permission.updated": {
+					await handlePermissionUpdated(config, terminalInfo)
+					break
+				}
+			}
+		},
+	}
+}
+
+export default NotifyPlugin

package/src/plugin/kdco-primitives/get-project-id.ts

@@ -0,0 +1,172 @@
+/**
+ * Project ID generation for kdco registry plugins.
+ *
+ * Generates a stable, unique identifier for a project based on its git history.
+ * Used for cross-worktree consistency in delegation storage, state databases,
+ * and other plugin data that should be shared across worktrees.
+ *
+ * @module kdco-primitives/get-project-id
+ */
+
+import * as crypto from "node:crypto"
+import { stat } from "node:fs/promises"
+import * as path from "node:path"
+import { logWarn } from "./log-warn"
+import type { OpencodeClient } from "./types"
+import { TimeoutError, withTimeout } from "./with-timeout"
+
+/**
+ * Generate a short hash from a path for project ID fallback.
+ *
+ * Used when git root commit is unavailable (non-git repos, empty repos).
+ * Produces a 16-character hex string for reasonable uniqueness.
+ *
+ * @param projectRoot - Absolute path to hash
+ * @returns 16-char hex hash
+ */
+function hashPath(projectRoot: string): string {
+	const hash = crypto.createHash("sha256").update(projectRoot).digest("hex")
+	return hash.slice(0, 16)
+}
+
+/**
+ * Generate a unique project ID from the project root path.
+ *
+ * **Strategy:**
+ * 1. Uses the first root commit SHA for stability across renames/moves
+ * 2. Falls back to path hash for non-git repos or empty repos
+ * 3. Caches result in .git/opencode for performance
+ *
+ * **Git Worktree Support:**
+ * When .git is a file (worktree), resolves the actual .git directory
+ * and uses the shared cache. This ensures all worktrees share the same
+ * project ID and associated data.
+ *
+ * @param projectRoot - Absolute path to the project root
+ * @param client - Optional OpenCode client for logging warnings
+ * @returns 40-char hex SHA (git root) or 16-char hash (fallback)
+ * @throws {Error} When projectRoot is invalid or .git file has invalid format
+ *
+ * @example
+ * ```ts
+ * const projectId = await getProjectId("/home/user/my-repo")
+ * // Returns: "abc123..." (40-char git hash)
+ *
+ * const projectId = await getProjectId("/home/user/non-git-folder")
+ * // Returns: "def456..." (16-char path hash)
+ * ```
+ */
+export async function getProjectId(projectRoot: string, client?: OpencodeClient): Promise<string> {
+	// Guard: Validate projectRoot (Law 1: Early Exit, Law 4: Fail Fast)
+	if (!projectRoot || typeof projectRoot !== "string") {
+		throw new Error("getProjectId: projectRoot is required and must be a string")
+	}
+
+	const gitPath = path.join(projectRoot, ".git")
+
+	// Check if .git exists and what type it is
+	const gitStat = await stat(gitPath).catch(() => null)
+
+	// Guard: No .git directory - not a git repo (Law 1: Early Exit)
+	if (!gitStat) {
+		logWarn(client, "project-id", `No .git found at ${projectRoot}, using path hash`)
+		return hashPath(projectRoot)
+	}
+
+	let gitDir = gitPath
+
+	// Handle worktree case: .git is a file containing gitdir reference
+	if (gitStat.isFile()) {
+		const content = await Bun.file(gitPath).text()
+		const match = content.match(/^gitdir:\s*(.+)$/m)
+
+		// Guard: Invalid .git file format (Law 4: Fail Fast)
+		if (!match) {
+			throw new Error(`getProjectId: .git file exists but has invalid format at ${gitPath}`)
+		}
+
+		// Resolve path (handles both relative and absolute)
+		const gitdirPath = match[1].trim()
+		const resolvedGitdir = path.resolve(projectRoot, gitdirPath)
+
+		// The gitdir contains a 'commondir' file pointing to shared .git
+		const commondirPath = path.join(resolvedGitdir, "commondir")
+		const commondirFile = Bun.file(commondirPath)
+
+		if (await commondirFile.exists()) {
+			const commondirContent = (await commondirFile.text()).trim()
+			gitDir = path.resolve(resolvedGitdir, commondirContent)
+		} else {
+			// Fallback to ../.. assumption for older git or unusual setups
+			gitDir = path.resolve(resolvedGitdir, "../..")
+		}
+
+		// Guard: Resolved gitdir must be a directory (Law 4: Fail Fast)
+		const gitDirStat = await stat(gitDir).catch(() => null)
+		if (!gitDirStat?.isDirectory()) {
+			throw new Error(`getProjectId: Resolved gitdir ${gitDir} is not a directory`)
+		}
+	}
+
+	// Check cache in .git/opencode
+	const cacheFile = path.join(gitDir, "opencode")
+	const cache = Bun.file(cacheFile)
+
+	if (await cache.exists()) {
+		const cached = (await cache.text()).trim()
+		// Validate cache content (40-char hex for git hash, or 16-char for path hash)
+		if (/^[a-f0-9]{40}$/i.test(cached) || /^[a-f0-9]{16}$/i.test(cached)) {
+			return cached
+		}
+		logWarn(client, "project-id", `Invalid cache content at ${cacheFile}, regenerating`)
+	}
+
+	// Generate project ID from git root commit
+	try {
+		const proc = Bun.spawn(["git", "rev-list", "--max-parents=0", "--all"], {
+			cwd: projectRoot,
+			stdout: "pipe",
+			stderr: "pipe",
+			env: { ...process.env, GIT_DIR: undefined, GIT_WORK_TREE: undefined },
+		})
+
+		// 5 second timeout to prevent hangs on network filesystems
+		const timeoutMs = 5000
+		const exitCode = await withTimeout(proc.exited, timeoutMs, `git rev-list timed out`).catch(
+			(e) => {
+				if (e instanceof TimeoutError) {
+					proc.kill()
+				}
+				return 1 // Treat timeout/errors as failure, fall back to path hash
+			},
+		)
+
+		if (exitCode === 0) {
+			const output = await new Response(proc.stdout).text()
+			const roots = output
+				.split("\n")
+				.filter(Boolean)
+				.map((x) => x.trim())
+				.sort()
+
+			if (roots.length > 0 && /^[a-f0-9]{40}$/i.test(roots[0])) {
+				const projectId = roots[0]
+				// Cache the result
+				try {
+					await Bun.write(cacheFile, projectId)
+				} catch (e) {
+					logWarn(client, "project-id", `Failed to cache project ID: ${e}`)
+				}
+				return projectId
+			}
+		} else {
+			const stderr = await new Response(proc.stderr).text()
+			logWarn(client, "project-id", `git rev-list failed (${exitCode}): ${stderr.trim()}`)
+		}
+	} catch (error) {
+		logWarn(client, "project-id", `git command failed: ${error}`)
+	}
+
+	// Fallback to path hash
+	return hashPath(projectRoot)
+}