win_toaster 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 21777567d049b3c1e516133d5f876e82f90d0ca1b44953b82f4161c01d982a55
+  data.tar.gz: 1dd039962e19df0c0e5bb849b5ea8a5afd907b2b9deea04d98d6e6d0becb637e
+SHA512:
+  metadata.gz: 1493bcb149010cf4b85d85763f3898585580830de78622194f12afdc1acbe7d94ecf8072f70b1151e2b344d4aed03d8d5f6308033dfdf009991768c23bacee19
+  data.tar.gz: f5f2ed18c74f7155310b622a2efa4f91f5b249a712a64c87a5e063cd13b112d6768f0abd5ed5fd71dcf366e7e85b40f315667edd9b0fd2ad4f8fb8ae40e6820d

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2026-06-19
+
+- Initial release

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of Conduct
+
+"win_toaster" follows [The Ruby Community Conduct Guideline](https://www.ruby-lang.org/en/conduct) in all "collaborative space", which is defined as community communications channels (such as mailing lists, submitted patches, commit comments, etc.):
+
+* Participants will be tolerant of opposing views.
+* Participants must ensure that their language and actions are free of personal attacks and disparaging personal remarks.
+* When interpreting the words and actions of others, participants should always assume good intentions.
+* Behaviour which can be reasonably considered harassment will not be tolerated.
+
+If you have any concerns about behaviour within this project, please contact us at ["yuuji.yaginuma@gmail.com"](mailto:"yuuji.yaginuma@gmail.com").

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 Yuji Yaginuma
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,129 @@
+# WinToaster
+
+Show native Windows toast notifications from **WSL** or **Windows**.
+
+`win_toaster` invokes Windows PowerShell (`powershell.exe`) and uses the
+`Windows.UI.Notifications` API to display a toast. It works both from WSL and
+from Ruby running on Windows directly, since it only needs `powershell.exe` on
+`PATH`. The notification text and the PowerShell script are Base64-encoded before
+being handed to PowerShell, so non-ASCII text and shell metacharacters are passed
+through safely.
+
+## Requirements
+
+- Windows 10 / 11 with `powershell.exe` available on `PATH`, either:
+  - inside WSL (`powershell.exe` is reachable via WSL interop), or
+  - on Windows directly
+- Ruby >= 3.2
+
+## Installation
+
+Install the gem:
+
+```bash
+gem install win_toaster
+```
+
+Or add it to your `Gemfile`:
+
+```ruby
+gem "win_toaster"
+```
+
+## Usage
+
+### Ruby
+
+```ruby
+require "win_toaster"
+
+WinToaster.notify(title: "Build finished", message: "All tests are green")
+
+# An optional third line, images, and a custom AppUserModelId:
+WinToaster.notify(
+  title:   "Deploy finished",
+  message: "Production has been updated",
+  detail:  "took 3m",
+  image:   "/mnt/c/Users/me/Pictures/icon.png",  # small icon (appLogoOverride)
+  hero:    "/mnt/c/Users/me/Pictures/banner.png", # large banner image
+  app_id:  '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
+)
+```
+
+`WinToaster.notify` returns `true` on success and raises `WinToaster::Error`
+on failure (e.g. when `powershell.exe` cannot be found).
+
+#### Images
+
+`image:` is shown as the small icon (`appLogoOverride`) and `hero:` as the large
+banner image. Both take a file path. From WSL you can pass a Linux/WSL path
+(e.g. `/mnt/c/...` or `/home/...`); it is converted to a Windows path with
+`wslpath -w` automatically. On native Windows the path is used as-is. The path
+must be absolute and point to a file Windows can read; an unreadable path is
+silently dropped by Windows (the rest of the toast still shows).
+
+### CLI
+
+```bash
+win_toaster "Build finished" "All tests are green"
+win_toaster "Build finished" "All green" --detail "took 3m"
+win_toaster "Deploy finished" "Production updated" --image /mnt/c/Users/me/Pictures/icon.png
+win_toaster --help
+```
+
+## Default AppId
+
+When you don't pass `app_id`, win_toaster uses Windows PowerShell's AppUserModelId:
+
+```
+{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe
+```
+
+A toast can only be displayed under an AppUserModelId (AUMID) that is registered
+with the system via a Start menu shortcut — `CreateToastNotifier` fails to show
+the toast otherwise. Windows ships with such a shortcut for Windows PowerShell,
+so this AUMID is already registered and works out of the box without you having
+to register an application of your own. Notifications then appear attributed to
+"Windows PowerShell". The leading GUID `{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}`
+is the well-known `FOLDERID_System` known-folder id (the `System32` folder); it
+is a public constant, not a secret.
+
+To show notifications under your own app name/icon, register a custom AUMID and
+pass it via `app_id:` (or `--app-id`).
+
+References (official Microsoft docs):
+
+- [How to enable desktop toast notifications through an AppUserModelID](https://learn.microsoft.com/en-us/windows/win32/shell/enable-desktop-toast-with-appusermodelid)
+  — a Start-menu shortcut carrying an AUMID is required to raise a toast.
+- [ToastNotificationManager.CreateToastNotifier](https://learn.microsoft.com/en-us/uwp/api/windows.ui.notifications.toastnotificationmanager.createtoastnotifier)
+  — the API used here; the AUMID must match the shortcut or the toast is not shown.
+- [KNOWNFOLDERID](https://learn.microsoft.com/en-us/windows/win32/shell/knownfolderid)
+  — `FOLDERID_System` is defined as `{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}`.
+
+## How it works
+
+1. Builds the toast XML (`ToastGeneric` template), XML-escaping each text node.
+2. Base64-encodes the XML and embeds it in a small PowerShell script.
+3. Base64-encodes the whole script (UTF-16LE) and runs
+   `powershell.exe -NoProfile -NonInteractive -EncodedCommand <script>`.
+
+Using `-EncodedCommand` avoids shell-quoting problems and the UNC-path warning
+that `-File` triggers when launched from a WSL working directory. The same
+encoded invocation works whether PowerShell is reached through WSL interop or
+run on Windows directly.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then run
+`rake test` to run the tests. The test suite stubs out PowerShell, so it runs on
+any platform (no `powershell.exe` required).
+
+To install this gem onto your local machine, run `bundle exec rake install`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/y-yagi/win_toaster.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "minitest/test_task"
+
+Minitest::TestTask.create
+
+task default: :test

data/exe/win_toaster

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "win_toaster"
+require "win_toaster/cli"
+
+exit WinToaster::CLI.run(ARGV)

data/lib/win_toaster/cli.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "optparse"
+require_relative "../win_toaster"
+
+module WinToaster
+  # Command-line front-end for win_toaster.
+  #
+  #   win_toaster TITLE MESSAGE [--detail DETAIL] [--app-id APP_ID]
+  class CLI
+    # Runs the CLI and returns the process exit code.
+    def self.run(argv)
+      new.run(argv)
+    end
+
+    def run(argv)
+      options = { detail: nil, image: nil, hero: nil, app_id: Notifier::DEFAULT_APP_ID }
+
+      parser = OptionParser.new do |o|
+        o.banner = "Usage: win_toaster TITLE MESSAGE [options]"
+        o.on("-d", "--detail DETAIL", "Third line shown below the message") { |v| options[:detail] = v }
+        o.on("-i", "--image PATH", "Icon image (appLogoOverride)") { |v| options[:image] = v }
+        o.on("--hero PATH", "Hero (large banner) image") { |v| options[:hero] = v }
+        o.on("-a", "--app-id APP_ID", "AppUserModelId the toast is shown under") { |v| options[:app_id] = v }
+        o.on("-v", "--version", "Show version and exit") do
+          puts WinToaster::VERSION
+          return 0
+        end
+        o.on("-h", "--help", "Show this help and exit") do
+          puts o
+          return 0
+        end
+      end
+
+      title, message = parser.parse(argv)
+
+      if title.nil? || message.nil?
+        warn parser.banner
+        return 1
+      end
+
+      WinToaster.notify(
+        title: title, message: message, detail: options[:detail],
+        image: options[:image], hero: options[:hero], app_id: options[:app_id]
+      )
+      0
+    rescue OptionParser::ParseError, WinToaster::Error => e
+      warn "win_toaster: #{e.message}"
+      1
+    end
+  end
+end

data/lib/win_toaster/notifier.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module WinToaster
+  # Builds a Windows toast notification and shows it by invoking Windows
+  # PowerShell (powershell.exe) from WSL. The toast XML and the PowerShell
+  # script are Base64-encoded so that arbitrary text (including Japanese and
+  # shell metacharacters) survives the WSL -> Windows boundary without any
+  # quoting or injection concerns.
+  class Notifier
+    # Default AppUserModelId. This is Windows PowerShell's registered id, taken
+    # from the reference article. Toasts shown under it appear as coming from
+    # "Windows PowerShell". Override via +app_id+ to use your own.
+    DEFAULT_APP_ID = '{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\WindowsPowerShell\v1.0\powershell.exe'
+
+    # The Windows PowerShell executable, resolved from PATH inside WSL.
+    POWERSHELL = "powershell.exe"
+
+    attr_reader :title, :message, :detail, :image, :hero, :app_id
+
+    # +image+ is shown as the small icon (appLogoOverride) and +hero+ as the
+    # large banner image. Both take a file path; from WSL a Linux/WSL path
+    # (e.g. /mnt/c/... or /home/...) is accepted and converted to a Windows
+    # path automatically.
+    def initialize(title:, message:, detail: nil, image: nil, hero: nil, app_id: DEFAULT_APP_ID)
+      @title = title
+      @message = message
+      @detail = detail
+      @image = image
+      @hero = hero
+      @app_id = app_id
+    end
+
+    # Builds the toast XML using the ToastGeneric template. Text nodes are
+    # XML-escaped. The +detail+ line and image nodes are omitted when nil.
+    def build_xml
+      nodes = [title, message, detail].compact.map { |t| "<text>#{escape_xml(t)}</text>" }
+      nodes << image_node("appLogoOverride", image) if image
+      nodes << image_node("hero", hero) if hero
+      %(<toast><visual><binding template="ToastGeneric">#{nodes.join}</binding></visual></toast>)
+    end
+
+    # The PowerShell script that decodes the XML and shows the toast.
+    def powershell_script
+      xml_b64 = [build_xml.encode("UTF-8")].pack("m0")
+      app_id_literal = app_id.gsub("'", "''")
+      <<~PS
+        $ErrorActionPreference = 'Stop'
+        [Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+        [Windows.UI.Notifications.ToastNotification, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+        [Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom, ContentType = WindowsRuntime] | Out-Null
+        $xmlText = [System.Text.Encoding]::UTF8.GetString([System.Convert]::FromBase64String('#{xml_b64}'))
+        $xml = New-Object Windows.Data.Xml.Dom.XmlDocument
+        $xml.LoadXml($xmlText)
+        $toast = [Windows.UI.Notifications.ToastNotification]::new($xml)
+        [Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('#{app_id_literal}').Show($toast)
+      PS
+    end
+
+    # The argv used to launch PowerShell with the script as an EncodedCommand.
+    # Using -EncodedCommand avoids shell quoting issues and the UNC-path warning
+    # that -File triggers when run from a WSL working directory.
+    def powershell_command
+      encoded = [powershell_script.encode("UTF-16LE")].pack("m0")
+      [POWERSHELL, "-NoProfile", "-NonInteractive", "-EncodedCommand", encoded]
+    end
+
+    # Builds and shows the toast. Returns true on success and raises
+    # WinToaster::Error on any failure.
+    def deliver
+      _stdout, stderr, status = Open3.capture3(*powershell_command)
+      unless status.success?
+        raise Error, "failed to show toast (exit #{status.exitstatus}): #{stderr.strip}"
+      end
+
+      true
+    rescue Errno::ENOENT
+      raise Error, "#{POWERSHELL} not found. win_toaster requires Windows PowerShell, " \
+                   "so run it from WSL or from Ruby on Windows."
+    end
+
+    private
+
+    def image_node(placement, path)
+      %(<image placement="#{placement}" src="#{escape_xml(windows_path(path))}"/>)
+    end
+
+    # Converts a file path to a Windows path that the toast can load. From WSL,
+    # `wslpath -w` maps the path (e.g. /mnt/c/... or /home/...) to its Windows
+    # form. On native Windows wslpath is absent, so the absolute path is used
+    # as-is.
+    def windows_path(path)
+      expanded = File.expand_path(path)
+      out, _err, status = Open3.capture3("wslpath", "-w", expanded)
+      status.success? ? out.strip : expanded
+    rescue Errno::ENOENT
+      expanded
+    end
+
+    def escape_xml(text)
+      text.to_s
+          .gsub("&", "&amp;")
+          .gsub("<", "&lt;")
+          .gsub(">", "&gt;")
+          .gsub('"', "&quot;")
+          .gsub("'", "&apos;")
+    end
+  end
+end

data/lib/win_toaster/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module WinToaster
+  VERSION = "0.1.0"
+end

data/lib/win_toaster.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "win_toaster/version"
+
+module WinToaster
+  class Error < StandardError; end
+
+  # Show a Windows toast notification from WSL.
+  #
+  #   WinToaster.notify(title: "Build finished", message: "All green")
+  #
+  # +image+ (small icon) and +hero+ (large banner) take a file path; from WSL a
+  # Linux/WSL path is accepted and converted to a Windows path automatically.
+  #
+  # Returns true on success and raises WinToaster::Error on failure.
+  def self.notify(title:, message:, detail: nil, image: nil, hero: nil, app_id: Notifier::DEFAULT_APP_ID)
+    Notifier.new(
+      title: title, message: message, detail: detail,
+      image: image, hero: hero, app_id: app_id
+    ).deliver
+  end
+end
+
+require_relative "win_toaster/notifier"

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: win_toaster
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Yuji Yaginuma
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: win_toaster shows native Windows toast notifications by invoking Windows
+  PowerShell and the Windows.UI.Notifications API. It works both from WSL and from
+  Ruby running on Windows directly.
+email:
+- yuuji.yaginuma@gmail.com
+executables:
+- win_toaster
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- exe/win_toaster
+- lib/win_toaster.rb
+- lib/win_toaster/cli.rb
+- lib/win_toaster/notifier.rb
+- lib/win_toaster/version.rb
+homepage: https://github.com/y-yagi/win_toaster
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/y-yagi/win_toaster
+  source_code_uri: https://github.com/y-yagi/win_toaster
+  changelog_uri: https://github.com/y-yagi/win_toaster/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.14
+specification_version: 4
+summary: Show Windows toast notifications from WSL or native Windows.
+test_files: []