dondon-notify 0.1.0

package/src/plugin/kdco-primitives/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Shared primitives for kdco registry plugins.
+ *
+ * This module provides common utilities extracted from multiple plugin files
+ * to eliminate duplication and ensure consistent behavior across plugins.
+ *
+ * @module kdco-primitives
+ */
+
+// Project identification
+export { getProjectId } from "./get-project-id"
+
+// Logging
+export { logWarn } from "./log-warn"
+// Concurrency
+export { Mutex } from "./mutex"
+// Shell escaping
+export { assertShellSafe, escapeAppleScript, escapeBash, escapeBatch } from "./shell"
+// Temp directory
+export { getTempDir } from "./temp"
+// Terminal detection
+export { isInsideTmux } from "./terminal-detect"
+// Types
+export type { OpencodeClient } from "./types"
+// Timeout handling
+export { TimeoutError, withTimeout } from "./with-timeout"

package/src/plugin/kdco-primitives/log-warn.ts

@@ -0,0 +1,51 @@
+/**
+ * Warning logger for kdco registry plugins.
+ *
+ * Provides a unified interface for logging warnings that works with
+ * both the OpenCode client (when available) and console fallback.
+ *
+ * @module kdco-primitives/log-warn
+ */
+
+import type { OpencodeClient } from "./types"
+
+/**
+ * Log a warning message via OpenCode client or console fallback.
+ *
+ * Uses the OpenCode logging API when a client is available, which integrates
+ * with the OpenCode UI log panel. Falls back to console.warn for CLI contexts
+ * or when no client is provided.
+ *
+ * @param client - Optional OpenCode client for proper logging integration
+ * @param service - Service name for log categorization (e.g., "worktree", "delegation")
+ * @param message - Warning message to log
+ *
+ * @example
+ * ```ts
+ * // With client - logs to OpenCode UI
+ * logWarn(client, "delegation", "Task timed out after 30s")
+ *
+ * // Without client - logs to console
+ * logWarn(undefined, "delegation", "Task timed out after 30s")
+ * ```
+ */
+export function logWarn(
+	client: OpencodeClient | undefined,
+	service: string,
+	message: string,
+): void {
+	// Guard: No client available, use console fallback (Law 1: Early Exit)
+	if (!client) {
+		console.warn(`[${service}] ${message}`)
+		return
+	}
+
+	// Happy path: Use OpenCode logging API
+	client.app
+		.log({
+			body: { service, level: "warn", message },
+		})
+		.catch(() => {
+			// Silently ignore logging failures - don't disrupt caller
+		})
+}

package/src/plugin/kdco-primitives/mutex.ts

@@ -0,0 +1,122 @@
+/**
+ * Promise-based mutex for serializing async operations.
+ *
+ * Provides a simple lock mechanism using native Promise mechanics.
+ * No external dependencies required.
+ *
+ * @module kdco-primitives/mutex
+ */
+
+/**
+ * Simple promise-based mutex for serializing async operations.
+ *
+ * Uses a queue of pending waiters to ensure fair ordering.
+ * Each waiter is resolved in FIFO order when the lock is released.
+ *
+ * @example
+ * ```ts
+ * const mutex = new Mutex()
+ *
+ * // Option 1: Manual acquire/release (use try-finally!)
+ * await mutex.acquire()
+ * try {
+ *   await criticalSection()
+ * } finally {
+ *   mutex.release()
+ * }
+ *
+ * // Option 2: Automatic acquire/release (preferred)
+ * const result = await mutex.runExclusive(async () => {
+ *   return await criticalSection()
+ * })
+ * ```
+ */
+export class Mutex {
+	private locked = false
+	private queue: (() => void)[] = []
+
+	/**
+	 * Acquire the mutex lock.
+	 *
+	 * If the mutex is unlocked, immediately acquires and returns.
+	 * If locked, waits in queue until released by current holder.
+	 *
+	 * @returns Promise that resolves when lock is acquired
+	 *
+	 * @example
+	 * ```ts
+	 * await mutex.acquire()
+	 * try {
+	 *   // Critical section - only one caller at a time
+	 * } finally {
+	 *   mutex.release() // Always release in finally!
+	 * }
+	 * ```
+	 */
+	async acquire(): Promise<void> {
+		// Fast path: lock is available (Law 1: Early Exit)
+		if (!this.locked) {
+			this.locked = true
+			return
+		}
+
+		// Slow path: wait in queue for lock release
+		return new Promise<void>((resolve) => {
+			this.queue.push(resolve)
+		})
+	}
+
+	/**
+	 * Release the mutex lock.
+	 *
+	 * If waiters are queued, passes the lock to the next waiter (FIFO).
+	 * Otherwise, marks the mutex as unlocked.
+	 *
+	 * @example
+	 * ```ts
+	 * mutex.release() // Must be called after acquire()
+	 * ```
+	 */
+	release(): void {
+		const next = this.queue.shift()
+		if (next) {
+			// Pass lock to next waiter (stays locked)
+			next()
+		} else {
+			// No waiters, unlock
+			this.locked = false
+		}
+	}
+
+	/**
+	 * Execute a function exclusively under mutex protection.
+	 *
+	 * Automatically acquires the lock before execution and releases
+	 * after completion, even if the function throws an error.
+	 * This is the preferred way to use the mutex.
+	 *
+	 * @param fn - Async function to execute exclusively
+	 * @returns The function's return value
+	 *
+	 * @example
+	 * ```ts
+	 * // Serialize tmux commands to prevent socket races
+	 * const result = await tmuxMutex.runExclusive(async () => {
+	 *   return await execTmuxCommand(["list-windows"])
+	 * })
+	 *
+	 * // Serialize database writes
+	 * await dbMutex.runExclusive(async () => {
+	 *   await db.update(record)
+	 * })
+	 * ```
+	 */
+	async runExclusive<T>(fn: () => Promise<T>): Promise<T> {
+		await this.acquire()
+		try {
+			return await fn()
+		} finally {
+			this.release()
+		}
+	}
+}

package/src/plugin/kdco-primitives/shell.ts

@@ -0,0 +1,138 @@
+/**
+ * Shell escaping utilities for cross-platform terminal commands.
+ *
+ * Provides safe escaping functions for Bash, Windows Batch, and AppleScript.
+ * All functions validate input for forbidden characters before escaping.
+ *
+ * @module kdco-primitives/shell
+ */
+
+/**
+ * Characters that cannot be safely escaped in any shell.
+ * Null bytes (\x00) cannot be represented in C strings and must be rejected.
+ */
+// biome-ignore lint/suspicious/noControlCharactersInRegex: Null byte detection is intentional for security
+const SHELL_FORBIDDEN_CHARS = /[\x00]/
+
+/**
+ * Assert that a string is safe for shell escaping.
+ *
+ * Null bytes cannot be escaped in any shell and must be rejected outright.
+ * This is the first line of defense before any escaping is attempted.
+ *
+ * @param value - String to validate
+ * @param context - Description for error message (e.g., "Bash argument")
+ * @throws {Error} if string contains forbidden characters
+ *
+ * @example
+ * ```ts
+ * assertShellSafe(userInput, "Bash argument")
+ * // Throws: "Bash argument contains null bytes..."
+ *
+ * assertShellSafe(filePath, "Script path")
+ * // Throws: "Script path contains null bytes..."
+ * ```
+ */
+export function assertShellSafe(value: string, context: string): void {
+	// Law 4: Fail Fast - reject invalid input immediately with clear message
+	if (SHELL_FORBIDDEN_CHARS.test(value)) {
+		throw new Error(
+			`${context} contains null bytes which cannot be safely escaped for shell execution`,
+		)
+	}
+}
+
+/**
+ * Escape a string for safe use in bash double-quoted strings.
+ *
+ * Handles all shell metacharacters including:
+ * - Backslash (\), double quote ("), dollar ($), backtick (`)
+ * - Exclamation mark (!) for history expansion
+ * - Newlines and carriage returns (replaced with spaces)
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for bash double-quoted context
+ * @throws {Error} if string contains null bytes
+ *
+ * @example
+ * ```ts
+ * const path = '/home/user/my "project"'
+ * const cmd = `cd "${escapeBash(path)}"`
+ * // Result: cd "/home/user/my \"project\""
+ *
+ * const var = '$HOME/file'
+ * const cmd = `echo "${escapeBash(var)}"`
+ * // Result: echo "\$HOME/file"
+ * ```
+ */
+export function escapeBash(str: string): string {
+	assertShellSafe(str, "Bash argument")
+	return str
+		.replace(/\\/g, "\\\\") // Backslash first (order matters!)
+		.replace(/"/g, '\\"') // Double quotes
+		.replace(/\$/g, "\\$") // Dollar sign (variable expansion)
+		.replace(/`/g, "\\`") // Backticks (command substitution)
+		.replace(/!/g, "\\!") // History expansion
+		.replace(/\n/g, " ") // Newlines -> spaces
+		.replace(/\r/g, " ") // Carriage returns -> spaces
+}
+
+/**
+ * Escape a string for safe use in AppleScript double-quoted strings.
+ *
+ * AppleScript uses different escaping rules than POSIX shells.
+ * Only backslash and double quote need escaping.
+ * Newlines are replaced with spaces (AppleScript doesn't support \n escapes).
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for AppleScript double-quoted context
+ * @throws {Error} if string contains null bytes
+ *
+ * @example
+ * ```ts
+ * const path = '/Users/name/my "project"'
+ * const script = `tell application "Terminal" to write text "${escapeAppleScript(path)}"`
+ * // Result: ... write text "/Users/name/my \"project\""
+ * ```
+ */
+export function escapeAppleScript(str: string): string {
+	assertShellSafe(str, "AppleScript argument")
+	return str
+		.replace(/\\/g, "\\\\") // Backslash
+		.replace(/"/g, '\\"') // Double quotes
+		.replace(/\n/g, " ") // Newlines -> spaces
+		.replace(/\r/g, " ") // Carriage returns -> spaces
+}
+
+/**
+ * Escape a string for safe use in Windows batch files.
+ *
+ * Handles batch metacharacters:
+ * - Percent (%), caret (^), ampersand (&)
+ * - Less than (<), greater than (>), pipe (|)
+ *
+ * @param str - String to escape
+ * @returns Escaped string safe for batch file context
+ * @throws {Error} if string contains null bytes
+ *
+ * @example
+ * ```ts
+ * const path = 'C:\\Users\\name\\project & files'
+ * const cmd = `cd /d "${escapeBatch(path)}"`
+ * // Result: cd /d "C:\Users\name\project ^& files"
+ *
+ * const var = '100%'
+ * const cmd = `echo ${escapeBatch(var)}`
+ * // Result: echo 100%%
+ * ```
+ */
+export function escapeBatch(str: string): string {
+	assertShellSafe(str, "Batch argument")
+	return str
+		.replace(/%/g, "%%") // Percent (double to escape)
+		.replace(/\^/g, "^^") // Caret (escape character itself)
+		.replace(/&/g, "^&") // Ampersand
+		.replace(/</g, "^<") // Less than
+		.replace(/>/g, "^>") // Greater than
+		.replace(/\|/g, "^|") // Pipe
+}

package/src/plugin/kdco-primitives/temp.ts

@@ -0,0 +1,36 @@
+/**
+ * Temp directory utilities.
+ *
+ * Provides a reliable temp directory path that resolves symlinks,
+ * which is critical on macOS where os.tmpdir() returns a symlink.
+ *
+ * @module kdco-primitives/temp
+ */
+
+import * as fsSync from "node:fs"
+import * as os from "node:os"
+
+/**
+ * Get the real temp directory path, resolving symlinks.
+ *
+ * This is critical for macOS where `os.tmpdir()` returns `/var/folders/...`
+ * which is actually a symlink to `/private/var/folders/...`. Many tools
+ * (including Bun's test harness, VS Code, and Eclipse Theia) need the
+ * resolved real path for proper file watching and path comparisons.
+ *
+ * @returns The real (resolved) temp directory path
+ *
+ * @example
+ * ```ts
+ * const tempDir = getTempDir()
+ * // macOS: "/private/var/folders/xx/xxxxx/T" (resolved)
+ * // Linux: "/tmp" (usually not a symlink)
+ * // Windows: "C:\\Users\\name\\AppData\\Local\\Temp"
+ *
+ * // Use for creating temp files
+ * const tempFile = path.join(getTempDir(), `script-${Date.now()}.sh`)
+ * ```
+ */
+export function getTempDir(): string {
+	return fsSync.realpathSync.native(os.tmpdir())
+}

package/src/plugin/kdco-primitives/terminal-detect.ts

@@ -0,0 +1,34 @@
+/**
+ * Terminal detection utilities.
+ *
+ * Provides functions to detect the current terminal environment,
+ * particularly useful for choosing terminal-specific behaviors.
+ *
+ * @module kdco-primitives/terminal-detect
+ */
+
+/**
+ * Check if the current process is running inside a tmux session.
+ *
+ * Detects tmux by checking the TMUX environment variable, which tmux
+ * sets to the socket path and session info when spawning child processes.
+ *
+ * @returns `true` if running inside tmux, `false` otherwise
+ *
+ * @example
+ * ```ts
+ * if (isInsideTmux()) {
+ *   // Use tmux-specific commands (new-window, split-pane, etc.)
+ *   await openTmuxWindow({ windowName: "dev", cwd: projectDir })
+ * } else {
+ *   // Fall back to platform-specific terminal
+ *   await openPlatformTerminal(projectDir)
+ * }
+ * ```
+ */
+export function isInsideTmux(): boolean {
+	// Law 1: Early Exit - simple boolean check, no complex parsing needed
+	// The TMUX env var contains socket info like "/tmp/tmux-1000/default,12345,0"
+	// We only care if it's set (truthy), not its contents
+	return !!process.env.TMUX
+}

package/src/plugin/kdco-primitives/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Shared types for kdco registry plugins.
+ *
+ * @module kdco-primitives/types
+ */
+
+import type { createOpencodeClient } from "@opencode-ai/sdk"
+
+/**
+ * OpenCode client instance type.
+ * Derived from the factory function return type for type safety.
+ */
+export type OpencodeClient = ReturnType<typeof createOpencodeClient>

package/src/plugin/kdco-primitives/with-timeout.ts

@@ -0,0 +1,84 @@
+/**
+ * Promise timeout utility for kdco registry plugins.
+ *
+ * Provides a clean wrapper around Promise.race for timeout handling,
+ * replacing inline timeout patterns throughout the codebase.
+ *
+ * @module kdco-primitives/with-timeout
+ */
+
+/**
+ * Error thrown when a promise times out.
+ * Extends Error for proper instanceof checks and stack traces.
+ */
+export class TimeoutError extends Error {
+	readonly name = "TimeoutError" as const
+	readonly timeoutMs: number
+
+	constructor(message: string, timeoutMs: number) {
+		super(message)
+		this.timeoutMs = timeoutMs
+	}
+}
+
+/**
+ * Wraps a promise with a timeout.
+ *
+ * Uses Promise.race to implement timeout semantics. If the wrapped promise
+ * doesn't resolve within the specified time, throws a TimeoutError.
+ *
+ * **Important:** This does NOT abort the underlying promise - it continues
+ * running in the background. Use AbortController for true cancellation.
+ *
+ * @param promise - The promise to wrap
+ * @param ms - Timeout in milliseconds
+ * @param message - Optional error message (defaults to "Operation timed out")
+ * @returns The resolved value from the promise
+ * @throws {TimeoutError} When the timeout expires before the promise resolves
+ *
+ * @example
+ * ```ts
+ * // Basic usage
+ * const result = await withTimeout(
+ *   fetchData(),
+ *   5000,
+ *   "Data fetch timed out"
+ * )
+ *
+ * // Handling timeout
+ * try {
+ *   const result = await withTimeout(slowOperation(), 1000)
+ * } catch (error) {
+ *   if (error instanceof TimeoutError) {
+ *     console.log(`Timed out after ${error.timeoutMs}ms`)
+ *   }
+ * }
+ * ```
+ */
+export async function withTimeout<T>(
+	promise: Promise<T>,
+	ms: number,
+	message = "Operation timed out",
+): Promise<T> {
+	// Guard: Invalid timeout value (Law 1: Early Exit, Law 4: Fail Fast)
+	if (typeof ms !== "number" || ms < 0) {
+		throw new Error(`withTimeout: timeout must be a non-negative number, got ${ms}`)
+	}
+
+	// Guard: Zero timeout means immediate rejection
+	if (ms === 0) {
+		throw new TimeoutError(message, ms)
+	}
+
+	// Race between the promise and a timeout
+	// Clear timer when promise resolves to prevent leaks
+	let timeoutId: Timer
+	return Promise.race([
+		promise.finally(() => clearTimeout(timeoutId)),
+		new Promise<never>((_, reject) => {
+			timeoutId = setTimeout(() => {
+				reject(new TimeoutError(message, ms))
+			}, ms)
+		}),
+	])
+}

package/test/test-kitty.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+
+/**
+ * Test script for Kitty notification improvements
+ * This script will test the Kitty-specific features we've added
+ */
+
+const { execSync } = require('child_process')
+
+console.log('Testing Kitty notification improvements...\n')
+
+// Test 1: Check if we're in Kitty
+const isKitty = process.env.TERM?.toLowerCase().includes('kitty') || 
+               process.env.TERMINAL?.toLowerCase().includes('kitty') ||
+               'kitty'
+
+console.log('1. Kitty Detection:')
+console.log(`   TERM: ${process.env.TERM || 'undefined'}`)
+console.log(`   TERMINAL: ${process.env.TERMINAL || 'undefined'}`)
+console.log(`   Detected as Kitty: ${isKitty ? 'Yes' : 'No'}`)
+
+// Test 2: Check WINDOWID (Kitty specific)
+const windowId = process.env.WINDOWID
+console.log('\n2. Kitty Window ID:')
+console.log(`   WINDOWID: ${windowId || 'undefined'}`)
+
+// Test 3: Test xprop availability (for focus detection)
+try {
+  const xpropVersion = execSync('xprop -version', { encoding: 'utf8' })
+  console.log('\n3. xprop availability:')
+  console.log(`   Available: Yes`)
+  console.log(`   Version: ${xpropVersion.split('\n')[0]}`)
+} catch (error) {
+  console.log('\n3. xprop availability:')
+  console.log(`   Available: No (this is expected on macOS)`)
+}
+
+// Test 4: Test environment detection
+console.log('\n4. Platform Detection:')
+console.log(`   Platform: ${process.platform}`)
+console.log(`   Architecture: ${process.arch}`)
+
+// Test 5: Test if we can detect focus (simplified)
+console.log('\n5. Focus Detection Test:')
+if (process.platform === 'linux' && windowId) {
+  console.log(`   Would test focus detection for Kitty window ${windowId}`)
+  console.log(`   (This would use xprop to check _NET_ACTIVE_WINDOW)`)
+} else if (process.platform === 'darwin') {
+  console.log(`   Would use macOS Applescript for focus detection`)
+} else {
+  console.log(`   Focus detection not available on this platform`)
+}
+
+console.log('\n6. Kitty Notification Test:')
+if (isKitty && process.platform === 'linux') {
+  console.log('   Sending test notification via Kitty OSC 99...')
+  
+  try {
+    // Send a test Kitty notification
+    const title = 'OpenCode Notify Test'
+    const message = 'Kitty notification integration working!'
+    const escapeSequence = `\x1b]99;i=1:d=1;p=title;${title}\x1b\\\x1b]99;i=1:d=1;p=body;${message}\x1b\\`
+    
+    process.stdout.write(escapeSequence)
+    console.log('   ✓ Test notification sent!')
+  } catch (error) {
+    console.log(`   ✗ Failed to send test notification: ${error.message}`)
+  }
+} else {
+  console.log('   Skipping - not in Kitty on Linux')
+}
+
+console.log('\nTest completed!')