@trygocode/notify 0.3.4 → 0.5.0

package/dist/src/desktop_notify.js

@@ -0,0 +1,584 @@
+// `desktop_notify` — BRANDED native desktop notifications on the dev machine
+// (GOCODE_NOTIFY_DESKTOP PRD §2). The companion to the phone push: when the
+// agent finishes a turn / errors / a loop completes, the SAME event that pings
+// your phone via FCM also raises a real OS banner on the computer you're sitting
+// at — so you get told whether you're at your desk or away.
+//
+// SCOPE OF THIS MODULE: take a resolved {title, body, kind, sound} and raise ONE
+// native banner on whatever OS we're on, BRANDED as "GoCode" with the GoCode
+// icon. It owns the per-platform mechanics + the one-time branding setup; the
+// DECISION of whether to fire (settings gating) lives in `on_stop.ts` / the CLI,
+// exactly like the phone `send` path.
+//
+// Contract (mirrors `send.ts` — PRD §0.5 "Never block the agent"):
+//   - Hard timeout (default 5s) — a wedged osascript/PowerShell can never hang a
+//     hook's turn. Best-effort: NEVER throws, NEVER rejects; always resolves to a
+//     {@link DesktopResult}. A failed banner must never block or fail the agent.
+//   - Failures are appended to `~/.gocode/notify.log` (shared with the sender).
+//
+// BRANDING — the whole point of this module (zero new npm deps, OS tools only):
+//   • macOS  → we `osacompile` a tiny "GoCode.app" AppleScript bundle ONCE into
+//     `~/.gocode/desktop/GoCode.app`, drop the bundled GoCode `.icns`/PNG into
+//     it, and invoke its `applet` binary. macOS attributes the banner to the
+//     SENDING app bundle, so the notification shows "GoCode" + our icon (a bare
+//     `osascript display notification` would show "Script Editor"). `osacompile`
+//     ships with every macOS — no Xcode, no Swift, no Homebrew.
+//   • Windows → we ensure a Start-Menu `.lnk` shortcut carrying our
+//     AppUserModelID ("GoCode.Notify") exists ONCE, then raise a WinRT
+//     `ToastGeneric` toast bound to that AUMID via inline PowerShell. Windows
+//     keys the toast's app name + icon off the AUMID's shortcut, so the toast
+//     reads "GoCode". PowerShell + WinRT ship with Windows 10/11 — no deps.
+//   • Linux  → `notify-send -a GoCode -i <icon>` (the `-a` app-name + `-i` icon
+//     flags brand it). libnotify is present on essentially every desktop distro.
+//
+// Zero runtime deps — Node built-ins only (child_process / fs / os / path / url),
+// matching the package's zero-dependency rule.
+import { spawn } from "node:child_process";
+import { promises as fs } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendLog } from "./send.js";
+import { gocodeDir } from "./creds.js";
+/** Default banner timeout (PRD §2.4: 5s hard cap, same as the phone `send`). */
+export const DEFAULT_DESKTOP_TIMEOUT_MS = 5000;
+/** The Windows AppUserModelID the branded toast binds to (PRD §2.3). */
+export const WINDOWS_AUMID = "GoCode.Notify";
+/** The app/bundle display name every platform brands the banner with. */
+export const APP_NAME = "GoCode";
+/**
+ * Version of the compiled macOS helper bundle. BUMP this whenever the applet's
+ * AppleScript changes (e.g. the click handler added in 0.5.0) so an existing
+ * install's stale `GoCode.app` is recompiled once instead of silently reused.
+ * Tracked via a `~/.gocode/desktop/.bundle-v<N>` marker file.
+ */
+export const MAC_BUNDLE_VERSION = 2;
+/**
+ * Env var that hard-disables ALL desktop banners regardless of settings — a
+ * machine-level opt-out for headless servers, CI, SSH sessions, or any box where
+ * a native banner makes no sense. Treated as truthy for any value other than the
+ * usual falsy strings. Checked first thing in {@link notifyDesktop} so it can
+ * never spawn a banner process. (The test suite also sets it so unit tests never
+ * raise real OS banners.)
+ */
+export const DISABLE_DESKTOP_ENV = "GOCODE_NOTIFY_NO_DESKTOP";
+/** True when {@link DISABLE_DESKTOP_ENV} is set to a truthy value. */
+export function desktopDisabledByEnv(env = process.env) {
+    const raw = env[DISABLE_DESKTOP_ENV];
+    if (raw == null)
+        return false;
+    const v = raw.trim().toLowerCase();
+    return v !== "" && v !== "0" && v !== "false" && v !== "no" && v !== "off";
+}
+/**
+ * Default OS-command runner: spawn `cmd args`, optionally feed `input` on stdin,
+ * capture stdout/stderr, and resolve with the exit code. NEVER rejects — a spawn
+ * error (binary missing) resolves to a non-zero code so the flow treats it as a
+ * skip, not a throw. A hard timeout kills a wedged child so a hook never hangs.
+ */
+export const defaultRunner = (cmd, args, opts) => new Promise((resolve) => {
+    let settled = false;
+    const finish = (r) => {
+        if (settled)
+            return;
+        settled = true;
+        resolve(r);
+    };
+    let child;
+    try {
+        child = spawn(cmd, args, {
+            stdio: ["pipe", "pipe", "pipe"],
+            env: opts.env ? { ...process.env, ...opts.env } : process.env,
+        });
+    }
+    catch (err) {
+        finish({ code: 127, stdout: "", stderr: String(err) });
+        return;
+    }
+    let stdout = "";
+    let stderr = "";
+    child.stdout?.setEncoding("utf8");
+    child.stderr?.setEncoding("utf8");
+    child.stdout?.on("data", (c) => (stdout += c));
+    child.stderr?.on("data", (c) => (stderr += c));
+    const timer = setTimeout(() => {
+        try {
+            child.kill("SIGKILL");
+        }
+        catch {
+            // ignore
+        }
+        finish({ code: 124, stdout, stderr: stderr || "timeout" });
+    }, opts.timeoutMs);
+    child.on("error", (err) => {
+        clearTimeout(timer);
+        finish({ code: 127, stdout, stderr: stderr || String(err) });
+    });
+    child.on("close", (code) => {
+        clearTimeout(timer);
+        finish({ code: code ?? 1, stdout, stderr });
+    });
+    if (opts.input !== undefined) {
+        try {
+            child.stdin?.end(opts.input);
+        }
+        catch {
+            // a broken pipe must not throw
+        }
+    }
+    else {
+        try {
+            child.stdin?.end();
+        }
+        catch {
+            // ignore
+        }
+    }
+});
+/** Directory under `~/.gocode/` holding the branding helper (the .app / marker). */
+export function desktopDir(opts) {
+    return path.join(gocodeDir(opts), "desktop");
+}
+/**
+ * Resolve the bundled GoCode icon shipped in the package's `assets/` dir. The
+ * compiled module lives at `dist/src/desktop_notify.js`, so `assets/` is two
+ * levels up (`dist/src/.. /.. /assets`). Returns the platform-appropriate file
+ * (PNG everywhere; `.ico` is only meaningful to Windows but we ship PNG too).
+ * Returns undefined when the asset can't be located (then we brand by name only).
+ */
+export function bundledIconPath(ext = "png") {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url)); // dist/src
+        const candidate = path.resolve(here, "..", "..", "assets", `gocode-icon.${ext}`);
+        return candidate;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Escape a string for safe embedding inside an AppleScript double-quoted literal. */
+export function escapeAppleScript(s) {
+    return s.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+}
+/** Escape a string for safe embedding inside a PowerShell single-quoted literal. */
+export function escapePowerShellSingleQuoted(s) {
+    return s.replace(/'/g, "''");
+}
+/** Escape text for safe embedding inside toast XML (the 5 XML entities). */
+export function escapeXml(s) {
+    return s
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&apos;");
+}
+/**
+ * Raise ONE branded native desktop banner for `payload`. Best-effort + total:
+ * NEVER throws, NEVER rejects; always resolves to a {@link DesktopResult}, and
+ * the caller can treat any result as "exit 0". Branding setup is one-time and
+ * cached; if it fails the banner still fires unbranded (degrade, never block).
+ */
+export async function notifyDesktop(payload, opts = {}) {
+    const platform = (opts.platform ?? process.platform);
+    const timeoutMs = opts.timeoutMs ?? DEFAULT_DESKTOP_TIMEOUT_MS;
+    const run = opts.run ?? defaultRunner;
+    const logLine = async (line) => {
+        try {
+            if (opts.log)
+                await opts.log(line);
+            else
+                await appendLog(`DESKTOP: ${line}`, { home: opts.home, timestamp: opts.timestamp });
+        }
+        catch {
+            // logging must never block the flow
+        }
+    };
+    // Machine-level hard opt-out (headless / CI / SSH). Never spawn anything.
+    // Honour a per-call `opts.env` override too (consistency with the runner,
+    // which merges opts.env into the child env) — falling back to process.env.
+    if (desktopDisabledByEnv({ ...process.env, ...(opts.env ?? {}) })) {
+        await logLine(`disabled via ${DISABLE_DESKTOP_ENV} — skipped`);
+        return { ok: false, platform: "unsupported", error: `disabled via ${DISABLE_DESKTOP_ENV}` };
+    }
+    const title = (payload.title ?? APP_NAME).trim() || APP_NAME;
+    const body = (payload.body ?? "").trim();
+    const sound = payload.sound !== false; // default ON (PRD §2.1)
+    const click = payload.click;
+    try {
+        if (platform === "darwin") {
+            return await notifyMac({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        if (platform === "win32") {
+            return await notifyWindows({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        if (platform === "linux") {
+            return await notifyLinux({ title, body, sound, click }, { ...opts, run, timeoutMs, log: logLine });
+        }
+        await logLine(`no desktop banner path for platform "${platform}" — skipped`);
+        return { ok: false, platform: "unsupported", error: `unsupported platform ${platform}` };
+    }
+    catch (err) {
+        // Defence in depth: this module must never throw. Surface the real message
+        // (platform-specific integrations are fragile — keep the breadcrumb).
+        const msg = err instanceof Error ? err.message : String(err);
+        await logLine(`unexpected error on ${platform} — treated as no-op: ${msg}`);
+        return { ok: false, platform: "unsupported", error: `unexpected error: ${msg}` };
+    }
+}
+// ── macOS ────────────────────────────────────────────────────────────────────
+/** Path to the branded helper app bundle under `~/.gocode/desktop/GoCode.app`. */
+export function macAppPath(opts) {
+    return path.join(desktopDir(opts), "GoCode.app");
+}
+/**
+ * Path to the click-target state file the applet reads when a banner is clicked
+ * (PRD §3.6). Holds a single `"<app>\t<projectPath>"` line written just before
+ * the most recent banner is posted; the applet's click handler opens that IDE.
+ * Single-file (last-write-wins) is fine: the user clicks the banner they just
+ * saw, and a banner only stays clickable while it's the latest.
+ */
+export function macClickTargetPath(opts) {
+    return path.join(desktopDir(opts), "click-target.tsv");
+}
+/**
+ * Ensure the branded `GoCode.app` AppleScript bundle exists under
+ * `~/.gocode/desktop/`. Compiled ONCE with `osacompile` (ships with macOS), then
+ * the bundled GoCode icon is dropped in as `applet.icns` so the banner shows our
+ * icon + "GoCode". Idempotent: a second call no-ops when the bundle is present.
+ *
+ * The bundle's AppleScript reads the banner text from env vars
+ * (GOCODE_NOTIFY_TITLE / GOCODE_NOTIFY_MESSAGE / GOCODE_NOTIFY_SOUND) so we never
+ * recompile per banner — we just set env + invoke the `applet` binary directly
+ * (the only invocation that actually works headless; `open -a` silently no-ops
+ * for AppleScript applets).
+ *
+ * CLICK-THROUGH (PRD §3.6): clicking a banner posted by an AppleScript applet
+ * sends a fresh `run` event back to THIS applet (documented macOS behaviour). We
+ * distinguish the two run modes by the presence of GOCODE_NOTIFY_TITLE:
+ *   • env var SET   → we're posting a banner (the normal invoke).
+ *   • env var EMPTY → we were re-run by a notification CLICK → read the last
+ *     click-target file and `open -a <ide> <projectPath>` to focus the IDE.
+ * This keeps click-through ZERO-dependency (pure osacompile/AppleScript) — no
+ * Swift, no signed binary, no extra npm dep.
+ *
+ * Returns the applet binary path on success, or undefined when branding could
+ * not be set up (caller then falls back to a plain unbranded `osascript`).
+ */
+export async function ensureMacBrandedApp(ctx) {
+    const appPath = macAppPath(ctx);
+    const appletBin = path.join(appPath, "Contents", "MacOS", "applet");
+    const versionMarker = path.join(desktopDir(ctx), `.bundle-v${MAC_BUNDLE_VERSION}`);
+    try {
+        // Already built AND at the CURRENT bundle version? → reuse. The version
+        // marker lets a package update (e.g. adding the click handler) force a
+        // one-time recompile of a stale bundle from an older install.
+        await fs.access(appletBin);
+        await fs.access(versionMarker);
+        return appletBin;
+    }
+    catch {
+        // need to (re)build it — missing applet OR stale/absent version marker
+    }
+    try {
+        await fs.mkdir(desktopDir(ctx), { recursive: true, mode: 0o700 });
+        // The applet reads the banner text from the environment so we compile ONCE.
+        // The same applet handles a notification CLICK (a second `run` with NO env)
+        // by opening the IDE recorded in the click-target file (see header).
+        const clickFile = macClickTargetPath(ctx);
+        const script = [
+            'on run',
+            '  set theTitle to (system attribute "GOCODE_NOTIFY_TITLE")',
+            '  if theTitle is "" then',
+            '    -- No banner env → this run came from a notification CLICK. Open the',
+            '    -- IDE recorded by the last post (format: "<app>\\t<projectPath>").',
+            '    my handleClick()',
+            '    return',
+            '  end if',
+            '  set theMsg to (system attribute "GOCODE_NOTIFY_MESSAGE")',
+            '  set theSound to (system attribute "GOCODE_NOTIFY_SOUND")',
+            '  if theSound is "1" then',
+            '    display notification theMsg with title theTitle sound name "Glass"',
+            '  else',
+            '    display notification theMsg with title theTitle',
+            '  end if',
+            'end run',
+            '',
+            'on handleClick()',
+            '  try',
+            `    set p to "${escapeAppleScript(clickFile)}"`,
+            '    set f to POSIX file p',
+            '    set raw to (read f as «class utf8»)',
+            '    if raw is "" then return',
+            '    set AppleScript\'s text item delimiters to tab',
+            '    set parts to text items of raw',
+            '    set AppleScript\'s text item delimiters to ""',
+            '    if (count of parts) < 2 then return',
+            '    set ideApp to item 1 of parts',
+            '    set projPath to item 2 of parts',
+            '    -- strip any trailing newline from projPath',
+            '    if projPath ends with linefeed then set projPath to text 1 thru -2 of projPath',
+            '    if projPath ends with return then set projPath to text 1 thru -2 of projPath',
+            '    do shell script "open -a " & quoted form of ideApp & " " & quoted form of projPath',
+            '  end try',
+            'end handleClick',
+        ].join("\n");
+        const scptPath = path.join(desktopDir(ctx), "gocode-notify.applescript");
+        await fs.writeFile(scptPath, script, "utf8");
+        // Remove any stale/partial bundle so osacompile writes a clean one.
+        await fs.rm(appPath, { recursive: true, force: true }).catch(() => { });
+        const compiled = await ctx.run("osacompile", ["-o", appPath, scptPath], {
+            timeoutMs: ctx.timeoutMs,
+        });
+        if (compiled.code !== 0) {
+            await ctx.log(`osacompile failed (code ${compiled.code}): ${compiled.stderr.trim()} — falling back to unbranded`);
+            return undefined;
+        }
+        // Drop the GoCode icon into the bundle so the banner is branded with it.
+        // The applet's icon file is Contents/Resources/applet.icns. We convert the
+        // bundled PNG → icns via `sips` (ships with macOS); if that fails the banner
+        // is still branded by NAME ("GoCode") which is the important part.
+        await brandMacIcon(appPath, ctx).catch(() => { });
+        // Stamp the version marker so we don't recompile until the bundle changes.
+        // Clear any older `.bundle-v*` markers first so the dir doesn't accumulate.
+        try {
+            const dir = desktopDir(ctx);
+            for (const entry of await fs.readdir(dir)) {
+                if (entry.startsWith(".bundle-v")) {
+                    await fs.rm(path.join(dir, entry), { force: true }).catch(() => { });
+                }
+            }
+            await fs.writeFile(versionMarker, "", { encoding: "utf8", mode: 0o600 });
+        }
+        catch {
+            // marker is an optimization — a failed write just means we recompile next
+            // time (correct, just slightly wasteful). Never fail the banner over it.
+        }
+        return appletBin;
+    }
+    catch (err) {
+        await ctx.log(`branded app setup error: ${err instanceof Error ? err.message : String(err)} — falling back to unbranded`);
+        return undefined;
+    }
+}
+/** Best-effort: convert the bundled PNG to icns and replace the applet icon. */
+async function brandMacIcon(appPath, ctx) {
+    const png = bundledIconPath("png");
+    if (!png)
+        return;
+    try {
+        await fs.access(png);
+    }
+    catch {
+        return; // asset missing — keep the default applet icon (still name-branded)
+    }
+    const icnsTarget = path.join(appPath, "Contents", "Resources", "applet.icns");
+    const res = await ctx.run("sips", ["-s", "format", "icns", png, "--out", icnsTarget], {
+        timeoutMs: ctx.timeoutMs,
+    });
+    if (res.code !== 0) {
+        await ctx.log(`icon conversion skipped (sips code ${res.code}) — banner is name-branded only`);
+    }
+}
+/**
+ * Write (or clear) the click-target file the applet reads on a banner click
+ * (PRD §3.6). When `click` is set we write a single tab-separated line
+ * `"<app>\t<projectPath>"`; when it's undefined we truncate the file to empty so
+ * a click on this banner no-ops rather than re-opening a STALE target from a
+ * previous banner. Best-effort — the caller swallows any error.
+ */
+export async function writeMacClickTarget(click, opts) {
+    const file = macClickTargetPath(opts);
+    await fs.mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    // Strip tabs/newlines from fields so the single-line TSV format can't be
+    // broken by a weird app name or path (paths with tabs are not a thing we hit,
+    // but defend anyway). Empty content when no target → click no-ops.
+    const content = click
+        ? `${oneLine(click.app)}\t${oneLine(click.projectPath)}\n`
+        : "";
+    await fs.writeFile(file, content, { encoding: "utf8", mode: 0o600 });
+}
+/** Collapse tabs/newlines to spaces so a value is safe in the single-line TSV. */
+function oneLine(s) {
+    return s.replace(/[\t\r\n]+/g, " ").trim();
+}
+async function notifyMac(banner, ctx) {
+    // Branded path: invoke the compiled GoCode.app applet so the banner is
+    // attributed to "GoCode" (+ our icon) instead of "Script Editor".
+    if (!ctx.skipBranding) {
+        const applet = await ensureMacBrandedApp(ctx);
+        if (applet) {
+            // Record the click target BEFORE posting, so a click on the banner we're
+            // about to show opens the right IDE/project (last-write-wins — the user
+            // clicks the banner they just saw). We ONLY write when THIS banner has a
+            // click target: a later display-only banner (no IDE source, e.g. a webhook
+            // ping) must NOT clear an earlier clickable banner's target, or clicking
+            // that still-visible earlier banner would no-op. Best-effort: a failed
+            // write just means the click no-ops (the banner still shows). (macOS only
+            // surfaces one process-wide applet, so this is a single shared file; the
+            // window between two clickable banners that target DIFFERENT projects is
+            // the known limit of the zero-dep applet approach — see header.)
+            if (banner.click) {
+                await writeMacClickTarget(banner.click, ctx).catch(() => { });
+            }
+            // The compiled applet reads the banner text from the environment (via
+            // AppleScript `system attribute`), so we pass it as env vars rather than
+            // recompiling per banner.
+            const res = await ctx.run(applet, [], {
+                timeoutMs: ctx.timeoutMs,
+                env: {
+                    ...(ctx.env ?? {}),
+                    GOCODE_NOTIFY_TITLE: banner.title,
+                    GOCODE_NOTIFY_MESSAGE: banner.body,
+                    GOCODE_NOTIFY_SOUND: banner.sound ? "1" : "0",
+                },
+            });
+            if (res.code === 0) {
+                await ctx.log(`branded banner shown (${banner.title})`);
+                return { ok: true, platform: "darwin" };
+            }
+            await ctx.log(`branded applet failed (code ${res.code}): ${res.stderr.trim()} — falling back to osascript`);
+        }
+    }
+    // Fallback: plain unbranded osascript (shows "Script Editor" but still works).
+    const t = escapeAppleScript(banner.title);
+    const b = escapeAppleScript(banner.body);
+    const soundClause = banner.sound ? ' sound name "Glass"' : "";
+    const script = `display notification "${b}" with title "${t}"${soundClause}`;
+    const res = await ctx.run("osascript", ["-e", script], { timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`unbranded banner shown (${banner.title})`);
+        return { ok: true, platform: "darwin" };
+    }
+    await ctx.log(`osascript failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "darwin", error: res.stderr.trim() || `osascript exit ${res.code}` };
+}
+// ── Windows ──────────────────────────────────────────────────────────────────
+/**
+ * Build the inline PowerShell that (1) ensures a Start-Menu shortcut carrying
+ * our AUMID exists so Windows brands the toast "GoCode", then (2) raises a WinRT
+ * ToastGeneric toast bound to that AUMID. Pure PowerShell + WinRT — no modules.
+ */
+export function buildWindowsToastScript(banner, opts = {}) {
+    const aumid = opts.aumid ?? WINDOWS_AUMID;
+    const title = escapeXml(banner.title);
+    const body = escapeXml(banner.body);
+    const iconLine = opts.iconPath
+        ? `<image placement="appLogoOverride" hint-crop="circle" src="${escapeXml(opts.iconPath)}"/>`
+        : "";
+    const audioLine = banner.sound ? "" : '<audio silent="true"/>';
+    // The shortcut-ensure block creates a .lnk in the user's Start Menu with the
+    // System.AppUserModel.ID property = our AUMID (required for an unpackaged app
+    // to brand a toast). Idempotent: skipped when the shortcut already exists.
+    return [
+        "$ErrorActionPreference = 'Stop'",
+        `$AppId = '${escapePowerShellSingleQuoted(aumid)}'`,
+        "$AppName = 'GoCode'",
+        "$startMenu = [Environment]::GetFolderPath('Programs')",
+        "$lnk = Join-Path $startMenu 'GoCode.lnk'",
+        // Ensure a Start-Menu shortcut whose AppUserModelID = our AUMID exists. An
+        // unpackaged app MUST have such a shortcut for Windows to brand its toast
+        // (name + icon) off the AUMID. Done once; skipped when already present.
+        "if (-not (Test-Path $lnk)) {",
+        "  try {",
+        "    $ws = New-Object -ComObject WScript.Shell",
+        "    $s = $ws.CreateShortcut($lnk)",
+        "    $s.TargetPath = (Join-Path $env:SystemRoot 'System32\\\\cmd.exe')",
+        "    $s.Arguments = '/c rem GoCode Notify'",
+        "    $s.IconLocation = (Join-Path $env:SystemRoot 'System32\\\\cmd.exe') + ',0'",
+        "    $s.Save()",
+        // Stamp System.AppUserModel.ID onto the shortcut via the Windows property
+        // store (the ONLY thing that actually links the .lnk to our AUMID).
+        "    $code = @'",
+        "using System;",
+        "using System.Runtime.InteropServices;",
+        "public static class GoCodeLnk {",
+        "  [ComImport, Guid(\"00021401-0000-0000-C000-000000000046\")] public class CShellLink {}",
+        "  [ComImport, Guid(\"000214F9-0000-0000-C000-000000000046\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IShellLinkW {",
+        "    void GetPath([Out] System.Text.StringBuilder f, int c, IntPtr d, int g); void GetIDList(out IntPtr p); void SetIDList(IntPtr p);",
+        "    void GetDescription(System.Text.StringBuilder n, int c); void SetDescription(string n); void GetWorkingDirectory(System.Text.StringBuilder d, int c);",
+        "    void SetWorkingDirectory(string d); void GetArguments(System.Text.StringBuilder a, int c); void SetArguments(string a);",
+        "    void GetHotkey(out short h); void SetHotkey(short h); void GetShowCmd(out int s); void SetShowCmd(int s);",
+        "    void GetIconLocation(System.Text.StringBuilder p, int c, out int i); void SetIconLocation(string p, int i);",
+        "    void SetRelativePath(string p, int r); void Resolve(IntPtr h, int f); void SetPath(string p);",
+        "  }",
+        "  [ComImport, Guid(\"45e2b4ae-b1c3-11d0-b92f-00a0c90312e1\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IShellLinkDataList { void AddDataBlock(IntPtr d); void CopyDataBlock(uint s, out IntPtr d); void RemoveDataBlock(uint s); void GetFlags(out uint f); void SetFlags(uint f); }",
+        "  [StructLayout(LayoutKind.Sequential)] public struct PROPERTYKEY { public Guid fmtid; public uint pid; }",
+        "  [ComImport, Guid(\"886d8eeb-8cf2-4446-8d02-cdba1dbdcf99\"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]",
+        "  public interface IPropertyStore { void GetCount(out uint c); void GetAt(uint i, out PROPERTYKEY k); void GetValue(ref PROPERTYKEY k, out PROPVARIANT v); void SetValue(ref PROPERTYKEY k, ref PROPVARIANT v); void Commit(); }",
+        "  [StructLayout(LayoutKind.Explicit)] public struct PROPVARIANT { [FieldOffset(0)] public ushort vt; [FieldOffset(8)] public IntPtr p; }",
+        "  [DllImport(\"ole32.dll\")] public static extern int PropVariantClear(ref PROPVARIANT pv);",
+        "  [DllImport(\"shell32.dll\", CharSet=CharSet.Unicode)] public static extern IntPtr SHStrDupW(string s, out IntPtr o);",
+        "  public static void SetAumid(string lnk, string aumid) {",
+        "    var link = (IShellLinkW)new CShellLink(); var pf = (System.Runtime.InteropServices.ComTypes.IPersistFile)link; pf.Load(lnk, 0);",
+        "    var ps = (IPropertyStore)link; var key = new PROPERTYKEY { fmtid = new Guid(\"9F4C2855-9F79-4B39-A8D0-E1D42DE1D5F3\"), pid = 5 };",
+        "    var pv = new PROPVARIANT { vt = 31 }; IntPtr str; SHStrDupW(aumid, out str); pv.p = str;",
+        "    ps.SetValue(ref key, ref pv); ps.Commit(); pf.Save(lnk, true); PropVariantClear(ref pv);",
+        "  }",
+        "}",
+        "'@",
+        "    Add-Type -TypeDefinition $code -Language CSharp | Out-Null",
+        "    [GoCodeLnk]::SetAumid($lnk, $AppId)",
+        "  } catch {}",
+        "}",
+        "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime] | Out-Null",
+        "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType=WindowsRuntime] | Out-Null",
+        "$template = @\"",
+        "<toast>",
+        "  <visual>",
+        '    <binding template="ToastGeneric">',
+        `      <text>${title}</text>`,
+        `      <text>${body}</text>`,
+        `      ${iconLine}`,
+        "    </binding>",
+        "  </visual>",
+        `  ${audioLine}`,
+        "</toast>",
+        "\"@",
+        "$xml = New-Object Windows.Data.Xml.Dom.XmlDocument",
+        "$xml.LoadXml($template)",
+        "$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)",
+        "$notifier = [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier($AppId)",
+        "$notifier.Show($toast)",
+    ].join("\n");
+}
+async function notifyWindows(banner, ctx) {
+    const iconPath = bundledIconPath("png");
+    const script = buildWindowsToastScript(banner, {
+        aumid: WINDOWS_AUMID,
+        iconPath: ctx.skipBranding ? undefined : iconPath,
+    });
+    // Run via powershell with stdin so we never hit cmd-line length / quoting limits.
+    const res = await ctx.run("powershell", ["-NoProfile", "-NonInteractive", "-ExecutionPolicy", "Bypass", "-Command", "-"], { input: script, timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`toast shown (${banner.title})`);
+        return { ok: true, platform: "win32" };
+    }
+    await ctx.log(`powershell toast failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "win32", error: res.stderr.trim() || `powershell exit ${res.code}` };
+}
+// ── Linux ────────────────────────────────────────────────────────────────────
+async function notifyLinux(banner, ctx) {
+    const icon = bundledIconPath("png");
+    const args = ["-a", APP_NAME];
+    if (icon && !ctx.skipBranding)
+        args.push("-i", icon);
+    // Best-effort sound control: there is no portable notify-send sound flag, but
+    // the freedesktop `suppress-sound` hint is honoured by GNOME/KDE daemons, so
+    // map `sound:false` → suppress. (Daemons that ignore the hint just play their
+    // default — no portable way to force-silence those, hence "best effort".)
+    if (!banner.sound)
+        args.push("-h", "int:suppress-sound:1");
+    // notify-send positional args: <summary> [body]
+    args.push(banner.title);
+    if (banner.body)
+        args.push(banner.body);
+    const res = await ctx.run("notify-send", args, { timeoutMs: ctx.timeoutMs });
+    if (res.code === 0) {
+        await ctx.log(`notify-send banner shown (${banner.title})`);
+        return { ok: true, platform: "linux" };
+    }
+    await ctx.log(`notify-send failed (code ${res.code}): ${res.stderr.trim()}`);
+    return { ok: false, platform: "linux", error: res.stderr.trim() || `notify-send exit ${res.code}` };
+}