residoo 0.24.0 → 0.26.0

package/README.md

@@ -206,6 +206,17 @@ brew install residoo
 The Homebrew formula installs the exact tarball published to npm (sha256
 verified): same bits, not a second build.
 
+**macOS, no terminal needed for install or uninstall:** download
+`residoo-<version>.pkg` from the
+[latest release](https://github.com/dandovdub/residoo/releases/latest)
+and double-click it to install, `residoo-uninstall-<version>.pkg` to
+remove it. Both are unsigned (no Apple Developer ID -- right-click >
+Open once to get past Gatekeeper's "unidentified developer" warning),
+and installing still needs Node.js present on the machine (it runs
+`npm install -g residoo` on your behalf, it doesn't bundle a Node
+runtime) -- see [packaging/macos-pkg](packaging/macos-pkg/README.md) for
+exactly what each one does and how both were verified.
+
 Requires Node.js 18+ (22.5+ for the SQLite-backed sources listed in
 [docs/sources.md](docs/sources.md); residoo still runs fine without it).
 Zero runtime dependencies: check `package.json` rather than take that on

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "residoo",
-  "version": "0.24.0",
+  "version": "0.26.0",
   "description": "Find secrets leaking through your AI coding agent's session history. Zero network calls in the scan path, zero dependencies.",
   "license": "MIT",
   "author": "CloudRoam (https://cloudroam.io)",

package/src/cli.js

@@ -13,6 +13,7 @@ const {
 } = require("./rotation");
 const { startWatch, isTailable } = require("./watch");
 const { startDashboardServer, openBrowser } = require("./dashboard");
+const { startWindowsTray } = require("./notify");
 const { startMcpServer } = require("./mcp");
 const { buildTools } = require("./mcpTools");
 const { runGuard: runGuardEngine, buildHookConfig } = require("./guard");
@@ -216,8 +217,17 @@ Watch:
                           nobody is watching a terminal for needs more than
                           a printed line. Never fires for a re-exposure of
                           something already seen, and never in --json mode.
-  Ctrl+C stops cleanly and prints a session summary (skipped with --json,
-  where the same information is one final NDJSON event).
+  --tray                  Windows only: a persistent "residoo is watching"
+                          tray icon for the life of this session, separate
+                          from --no-notify's own per-finding balloon-tip
+                          alerts (which still fire independently). No
+                          equivalent stock mechanism exists on macOS/Linux
+                          yet -- disclosed with a one-line message there,
+                          not silently ignored. Right-click > Hide icon to
+                          dismiss it without stopping the watch itself.
+  Ctrl+C stops cleanly, closes the tray icon if one was shown, and prints a
+  session summary (skipped with --json, where the same information is one
+  final NDJSON event).
 
 Dashboard:
   residoo dashboard        the exact "scan --html" report, served live at
@@ -823,6 +833,7 @@ async function runWatch(args) {
   const includePii = args.includes("--include-pii");
   const includeInjection = args.includes("--include-injection");
   const noNotify = args.includes("--no-notify");
+  const wantsTray = args.includes("--tray");
 
   let intervalSeconds = 5;
   const intervalArg = argValue(args, "--interval");
@@ -846,6 +857,22 @@ async function runWatch(args) {
 
   if (!wantsJson) printWatchBanner(sources);
 
+  // --tray: a PERSISTENT status-presence icon, deliberately decoupled from
+  // the per-finding balloon-tip alerts --no-notify already controls (see
+  // notify.js's startWindowsTray docstring for why merging them would need
+  // real inter-process communication this project has no way to verify).
+  // Windows-only, disclosed rather than silently ignored elsewhere: a real
+  // stock mechanism exists there (PowerShell + .NET's own NotifyIcon); macOS
+  // has none without a compiled app, and this flag doesn't attempt one.
+  let trayProcess = null;
+  if (wantsTray) {
+    if (process.platform === "win32") {
+      trayProcess = startWindowsTray("residoo is watching");
+    } else if (!wantsJson) {
+      process.stderr.write("--tray is Windows-only (no equivalent stock mechanism on this platform yet) -- ignored on this run.\n");
+    }
+  }
+
   const { promise, stop } = startWatch({
     sources,
     options: { includeNoisy, includeSuppressed, verify, noColor, includePii, includeInjection, noNotify, json: wantsJson, pollMs: intervalSeconds * 1000 },
@@ -863,6 +890,10 @@ async function runWatch(args) {
   const onSignal = () => {
     if (signalled) return;
     signalled = true;
+    // Not .unref()'d when spawned (see startWindowsTray's own docstring),
+    // specifically so this kill() can still reach it here -- a spawned
+    // child Node has already lost its handle to can never be stopped again.
+    if (trayProcess) trayProcess.kill();
     printFinalSummary(stop());
   };
   process.once("SIGINT", onSignal);
@@ -871,6 +902,7 @@ async function runWatch(args) {
   const stats = await promise;
   process.removeListener("SIGINT", onSignal);
   process.removeListener("SIGTERM", onSignal);
+  if (trayProcess && !signalled) trayProcess.kill();
   // promise can also resolve because something ELSE called stop() (not
   // possible from outside this function today, but the contract allows
   // it) -- print the summary exactly once regardless of which path got here.

package/src/notify.js

@@ -97,4 +97,89 @@ function notifyWindows(title, message) {
   child.unref();
 }
 
-module.exports = { notifyDesktop };
+/**
+ * A PERSISTENT Windows tray icon -- genuinely different from `notifyWindows`
+ * above, not a variant of it: that function is fire-and-forget (one balloon,
+ * then the process disposes itself and exits); this one stays alive and
+ * visible for as long as the CALLER wants it to (`residoo watch --tray`,
+ * the standing-presence "residoo is watching" indicator this project's own
+ * platform-scope.md records as a real, scoped follow-up). The two are
+ * deliberately DECOUPLED, not merged into one mechanism: this function only
+ * shows a static icon + tooltip; actual per-finding alerts keep firing
+ * through the existing, already-proven `notifyWindows` balloon-tip path,
+ * completely independently. Combining them into one process would mean
+ * finding a way to push live UPDATES into an already-running PowerShell
+ * process (a named pipe, a polled state file) -- real inter-process-
+ * communication complexity this project has no way to verify without a
+ * real Windows machine, so it was deliberately left out of scope rather
+ * than shipped unverified. A static presence icon needs no such channel.
+ *
+ * API surface verified directly against Microsoft's own current docs
+ * (learn.microsoft.com, fetched 2026-09-07), the same bar every other
+ * Windows-specific function in this project holds to, and likewise NOT
+ * live-tested against a real Windows install:
+ *   - `NotifyIcon.ContextMenuStrip` (not the older, pre-.NET-2.0
+ *     `ContextMenu`/`MenuItem` classes) is the current, non-deprecated
+ *     property, listed through the windowsdesktop-11.0 moniker.
+ *   - `SystemIcons.Shield` is a real, current static property ("an Icon
+ *     object that contains the shield icon") -- used here instead of
+ *     bundling a custom .ico file, matching zero-dependency the same way
+ *     `notifyWindows` reuses `SystemIcons.Information`.
+ *   - `NotifyIcon.Text` (the tooltip) has a REAL, documented, THROWING
+ *     limit: Microsoft's own docs give an exact table -- 63 characters
+ *     for .NET Framework and .NET 5/Core 3.0-3.1, 127 for .NET 6+. Windows
+ *     PowerShell (`powershell.exe`, what this project shells out to
+ *     everywhere, never `pwsh.exe`) runs on .NET Framework, so 63 is the
+ *     applicable limit, and exceeding it throws `ArgumentException` --
+ *     not a cosmetic detail, a real crash this function truncates against
+ *     before it can happen.
+ *
+ * Lifecycle, the one place this genuinely departs from every other spawn
+ * in this file: NOT `.unref()`'d, because the caller (`watch.js`) needs
+ * to `.kill()` this exact child process on its own SIGINT/SIGTERM
+ * shutdown -- an unref'd handle a caller has already discarded can't be
+ * reached again later. `[System.Windows.Forms.Application]::Run()` blocks
+ * the spawned PowerShell process in its own message loop for as long as
+ * the icon should stay visible; the "Hide icon" context-menu item calls
+ * `Application.Exit()` so a user can dismiss it independently of whether
+ * `residoo watch` itself keeps running.
+ */
+function startWindowsTray(tooltip) {
+  if (process.platform !== "win32") return null;
+  // Unlike notifyDesktop's callers, nothing wraps a call to this function
+  // in an outer try/catch -- runWatch calls it directly, and this returns
+  // a real value (the child, or null) callers branch on, so the "never
+  // throw" contract has to be enforced right here, not borrowed from a
+  // caller the way notifyWindows borrows notifyDesktop's. The whole body
+  // is inside this one try, not just the spawn call: `String(tooltip)`
+  // itself can throw -- an object whose own `toString` property isn't a
+  // function fails JavaScript's ToPrimitive coercion before anything else
+  // runs, the exact real (fast-check-found, not hypothetical) shape
+  // cve.js's parseVersion hit and was fixed for earlier this same
+  // project -- confirmed directly here too before shipping, not assumed
+  // fixed by analogy.
+  try {
+    const esc = (s) => String(s).replace(/'/g, "''");
+    const truncated = String(tooltip).slice(0, 63); // NotifyIcon.Text's real, throwing limit on .NET Framework -- see docstring
+    const script =
+      "Add-Type -AssemblyName System.Windows.Forms; " +
+      "Add-Type -AssemblyName System.Drawing; " +
+      "$ni = New-Object System.Windows.Forms.NotifyIcon; " +
+      "$ni.Icon = [System.Drawing.SystemIcons]::Shield; " +
+      `$ni.Text = '${esc(truncated)}'; ` +
+      "$ni.Visible = $true; " +
+      "$menu = New-Object System.Windows.Forms.ContextMenuStrip; " +
+      "$hideItem = New-Object System.Windows.Forms.ToolStripMenuItem 'Hide icon'; " +
+      "$hideItem.add_Click({ $ni.Visible = $false; $ni.Dispose(); [System.Windows.Forms.Application]::Exit() }); " +
+      "[void]$menu.Items.Add($hideItem); " +
+      "$ni.ContextMenuStrip = $menu; " +
+      "[System.Windows.Forms.Application]::Run()";
+    const child = cp.spawn("powershell.exe", ["-NoProfile", "-NonInteractive", "-WindowStyle", "Hidden", "-Command", script], { stdio: "ignore" });
+    child.on("error", () => {}); // binary missing or spawn failed: never throw
+    return child;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = { notifyDesktop, startWindowsTray };