@pi-unipi/unipi 2.0.2 → 2.0.4

package/packages/notify/platforms/focus.ts

@@ -0,0 +1,33 @@
+/**
+ * @pi-unipi/notify — Focus detection abstraction
+ *
+ * Unified interface for checking whether the terminal window is the
+ * foreground (active) window. Platform-specific implementations are
+ * dispatched based on process.platform.
+ *
+ * Currently implemented:
+ *   - Windows (win32): calls focus-win.ts
+ *
+ * Unimplemented platforms always return false (no suppression).
+ */
+
+import { isWindowFocusedOnWindows } from "./focus-win.js";
+
+/**
+ * Check whether the current terminal/console window is the foreground
+ * (active) window. Used by sendNativeNotification to optionally
+ * suppress notifications when the user is already looking at the screen.
+ *
+ * @returns true if the terminal is the foreground window, false otherwise.
+ *          On unimplemented platforms, always returns false.
+ */
+export async function isWindowFocused(): Promise<boolean> {
+  switch (process.platform) {
+    case "win32":
+      return await isWindowFocusedOnWindows();
+    // TODO: macOS — use osascript to check frontmost application
+    // TODO: Linux — use xdotool (X11) or per-compositor tool (Wayland)
+    default:
+      return false;
+  }
+}

package/packages/notify/platforms/native.ts

@@ -8,22 +8,54 @@
  */
 
 import notifier from "node-notifier";
+import { isWindowFocused } from "./focus.js";
 
 /** Options for native notification */
 export interface NativeNotificationOptions {
   /** Windows appID to show instead of "SnoreToast" */
   windowsAppId?: string;
+  /**
+   * When true, suppresses the notification if the terminal window is
+   * the foreground (active) window. Only effective on platforms where
+   * `isWindowFocused` is implemented (currently Windows).
+   */
+  suppressWhenFocused?: boolean;
+}
+
+/**
+ * Thrown by sendNativeNotification when the notification was suppressed
+ * because suppressWhenFocused is set and the terminal window is focused.
+ *
+ * Callers should catch this and treat it as intentional suppression,
+ * NOT as a send failure.
+ */
+export class SuppressedError extends Error {
+  constructor() {
+    super("Notification suppressed: terminal window is focused");
+    this.name = "SuppressedError";
+  }
 }
 
 /**
  * Send a native OS notification.
- * Resolves when notification is shown, rejects on error.
+ *
+ * When `suppressWhenFocused` is true and `isWindowFocused()` returns true
+ * (i.e. the terminal is the foreground window), the notification is
+ * suppressed and the promise rejects with SuppressedError.
+ *
+ * Resolves when notification is shown, rejects with SuppressedError on
+ * suppression or with a standard Error on failure.
  */
 export async function sendNativeNotification(
   title: string,
   message: string,
   options?: NativeNotificationOptions
 ): Promise<void> {
+  // Suppress if the terminal window is currently focused
+  if (options?.suppressWhenFocused && await isWindowFocused()) {
+    throw new SuppressedError();
+  }
+
   return new Promise((resolve, reject) => {
     notifier.notify(
       {

package/packages/notify/settings.ts

@@ -30,6 +30,7 @@ export const DEFAULT_CONFIG: NotifyConfig = {
   },
   native: {
     enabled: true,
+    suppressWhenFocused: false,
   },
   gotify: {
     enabled: false,

package/packages/notify/tui/settings-overlay.ts

@@ -85,7 +85,7 @@ export class NotifySettingsOverlay implements Component {
   }
 
   private get maxItems(): number {
-    if (this.section === "platforms") return 4; // native, gotify, telegram, ntfy
+    if (this.section === "platforms") return 5; // native, gotify, telegram, ntfy + suppress option
     if (this.section === "recap") return 1; // toggle
     return Object.keys(this.config.events).length;
   }
@@ -98,12 +98,17 @@ export class NotifySettingsOverlay implements Component {
         "telegram",
         "ntfy",
       ];
-      const key = platforms[this.selectedIndex];
-      if (key === "ntfy") {
-        // ntfy toggle updates the resolved ntfy config
-        this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
-      } else if (key) {
-        this.config[key].enabled = !this.config[key].enabled;
+      if (this.selectedIndex < platforms.length) {
+        const key = platforms[this.selectedIndex];
+        if (key === "ntfy") {
+          // ntfy toggle updates the resolved ntfy config
+          this.ntfyConfig.enabled = !this.ntfyConfig.enabled;
+        } else if (key) {
+          this.config[key].enabled = !this.config[key].enabled;
+        }
+      } else {
+        // suppressWhenFocused toggle (index 4)
+        this.config.native.suppressWhenFocused = !this.config.native.suppressWhenFocused;
       }
     } else if (this.section === "recap") {
       this.config.recap.enabled = !this.config.recap.enabled;
@@ -273,6 +278,27 @@ export class NotifySettingsOverlay implements Component {
         )
       );
     }
+
+    // suppressWhenFocused toggle (index 4)
+    {
+      const i = platforms.length;
+      const isSelected = i === this.selectedIndex;
+      const isEnabled = this.config.native.suppressWhenFocused === true;
+      const toggleOn = this.fg("success", "●");
+      const toggleOff = this.fg("dim", "○");
+      const toggle = isEnabled ? toggleOn : toggleOff;
+      const label = isSelected
+        ? this.bold("Suppress when focused")
+        : this.fg("dim", "Suppress when focused");
+      const detail = this.fg("dim", isEnabled ? "Windows only — terminal in foreground → skip" : "Windows only");
+
+      lines.push(
+        this.frameLine(
+          `${isSelected ? this.fg("accent", "▸") : " "} ${toggle} ${label}  ${detail}`,
+          innerWidth
+        )
+      );
+    }
   }
 
   private renderEvents(lines: string[], innerWidth: number): void {

package/packages/notify/types.ts

@@ -19,6 +19,12 @@ export interface NativeConfig {
   enabled: boolean;
   /** Windows appID to show instead of "SnoreToast" */
   windowsAppId?: string;
+  /**
+   * When true, suppresses the notification if the terminal window is the
+   * foreground (active) window. Only effective on supported platforms
+   * (currently Windows). Default: false.
+   */
+  suppressWhenFocused?: boolean;
 }
 
 /** Gotify notification platform config */
@@ -101,6 +107,8 @@ export interface NotifyResult {
   platform: NotifyPlatform;
   /** Whether the send succeeded */
   success: boolean;
+  /** True when the notification was intentionally suppressed (e.g. window focused) */
+  suppressed?: boolean;
   /** Error message if failed */
   error?: string;
 }

package/packages/workflow/README.md

@@ -97,6 +97,8 @@ For small tasks that skip the full flow:
 /unipi:worktree-merge feat/new-feature
 ```
 
+Worktree command arguments autocomplete from `.unipi/worktrees`. Suggestions are cached after the first scan in a Pi session so large worktree directories do not slow down repeated `/unipi:worktree-merge` completions.
+
 ## Special Triggers
 
 Workflow skills detect installed packages and enhance their behavior automatically. This is the coexists system — each package adds capabilities without requiring configuration.

package/packages/workflow/commands.ts

@@ -10,6 +10,8 @@ import { readFileSync, readdirSync, existsSync, statSync } from "fs";
 import { join, basename } from "path";
 import { UNIPI_PREFIX, WORKFLOW_COMMANDS, getToolsForCommand, getSandboxLevel, type SandboxLevel } from "@pi-unipi/core";
 
+type CompletionItem = { value: string; label: string; description: string };
+
 /** Options for command registration */
 export interface WorkflowCommandOptions {
   /** Check if ralph module is detected */
@@ -36,7 +38,7 @@ interface WorkflowCommand {
 /**
  * Suggest spec files from .unipi/docs/specs/ for plan command.
  */
-function suggestSpecFiles(prefix: string): { value: string; label: string; description: string }[] {
+function suggestSpecFiles(prefix: string): CompletionItem[] {
   const specsDir = join(process.cwd(), ".unipi", "docs", "specs");
   if (!existsSync(specsDir)) return [];
 
@@ -61,7 +63,7 @@ function suggestSpecFiles(prefix: string): { value: string; label: string; descr
 /**
  * Suggest plan files from .unipi/docs/plans/ for work and review-work commands.
  */
-function suggestPlanFiles(prefix: string): { value: string; label: string; description: string }[] {
+function suggestPlanFiles(prefix: string): CompletionItem[] {
   const plansDir = join(process.cwd(), ".unipi", "docs", "plans");
   if (!existsSync(plansDir)) return [];
 
@@ -86,7 +88,7 @@ function suggestPlanFiles(prefix: string): { value: string; label: string; descr
 /**
  * Suggest debug files from .unipi/docs/debug/ for fix command.
  */
-function suggestDebugFiles(prefix: string): { value: string; label: string; description: string }[] {
+function suggestDebugFiles(prefix: string): CompletionItem[] {
   const debugDir = join(process.cwd(), ".unipi", "docs", "debug");
   if (!existsSync(debugDir)) return [];
 
@@ -111,7 +113,7 @@ function suggestDebugFiles(prefix: string): { value: string; label: string; desc
 /**
  * Suggest chore files from .unipi/docs/chore/ for chore-execute command.
  */
-function suggestChoreFiles(prefix: string): { value: string; label: string; description: string }[] {
+function suggestChoreFiles(prefix: string): CompletionItem[] {
   const choreDir = join(process.cwd(), ".unipi", "docs", "chore");
   if (!existsSync(choreDir)) return [];
 
@@ -133,16 +135,29 @@ function suggestChoreFiles(prefix: string): { value: string; label: string; desc
   }
 }
 
+/** Cached per-cwd worktree suggestions. Worktree autocomplete can be invoked on every
+ * keystroke, so the recursive scan is intentionally paid only once per session/cwd.
+ */
+let worktreeSuggestionsCache: { cwd: string; items: CompletionItem[] } | null = null;
+
 /**
  * Suggest existing worktree names for merge/list commands.
  * Recursively scans for actual git worktrees (directories containing .git files).
  */
-function suggestWorktrees(): { value: string; label: string; description: string }[] {
-  const worktreesDir = join(process.cwd(), ".unipi", "worktrees");
-  if (!existsSync(worktreesDir)) return [];
+function suggestWorktrees(): CompletionItem[] {
+  const cwd = process.cwd();
+  if (worktreeSuggestionsCache?.cwd === cwd) {
+    return worktreeSuggestionsCache.items;
+  }
+
+  const worktreesDir = join(cwd, ".unipi", "worktrees");
+  if (!existsSync(worktreesDir)) {
+    worktreeSuggestionsCache = { cwd, items: [] };
+    return worktreeSuggestionsCache.items;
+  }
 
   try {
-    const results: { value: string; label: string; description: string }[] = [];
+    const results: CompletionItem[] = [];
 
     /**
      * Recursively find worktree directories (those containing a .git file).
@@ -176,9 +191,11 @@ function suggestWorktrees(): { value: string; label: string; description: string
     }
 
     findWorktrees(worktreesDir, "");
-    return results;
+    worktreeSuggestionsCache = { cwd, items: results };
+    return worktreeSuggestionsCache.items;
   } catch {
-    return [];
+    worktreeSuggestionsCache = { cwd, items: [] };
+    return worktreeSuggestionsCache.items;
   }
 }
 
@@ -334,7 +351,7 @@ export function registerWorkflowCommands(
     pi.registerCommand(fullCommand, {
       description: cmd.description,
       getArgumentCompletions: (prefix: string) => {
-        let items: { value: string; label: string; description: string }[] | null = null;
+        let items: CompletionItem[] | null = null;
 
         // Plan command: suggest spec files
         if (cmd.name === WORKFLOW_COMMANDS.PLAN) {