winos

A zero-dependency, lightweight Node.js library providing local scripts, CLI tools, and automation pipelines with native access to Windows OS components. By leveraging secure, under-the-hood PowerShell execution and the Windows Runtime (WinRT), winos eliminates the need for compiling heavy C++ native addons or distributing unverified prebuilt binaries.

Table of Contents

• winos
  • Table of Contents
  • Key Philosophy
  • Installation
  • Quick Start
  • API Reference
    • Input Module (winos-utils/input)
      • selectFile
      • selectFolder
    • Clipboard Module (winos-utils/clipboard)
      • write
      • read
      • readHistory
      • clear
    • Notify Module (winos-utils/notify)
      • push
    • System Module (winos-utils/system)
      • openFolder
      • openBrowser
      • showMessage
  • Security Model
  • License

Key Philosophy

• Zero Dependencies: Keeps the installation size negligible. Installs instantly without the risk of nested dependency vulnerabilities.
• No C++ Compilation or Prebuilt Executables: Traditional native Windows integration in Node.js relies on C++ compilation (via node-gyp) or shipping heavy precompiled .exe/.dll binary blobs. winos runs using standard Windows PowerShell processes and the .NET / WinRT assemblies already present on every Windows 10/11 system.
• Security First: Spawning processes is vulnerable to shell command injection. winos serializes all parameters as JSON objects and pipes them to PowerShell via standard input (stdin). Data is never evaluated as code, rendering command injection impossible.
• TypeScript Built-in: Full TypeScript typings and JSDoc documentation are included, providing auto-completion and compile-time verification out of the box.

Installation

npm install winos-utils

Ensure you are executing on a Windows 10 or Windows 11 host.

Quick Start

const win = require('winos-utils');

async function main() {
  // Clear clipboard, write a string, and read it back
  await win.clipboard.clear();
  await win.clipboard.write('Hello from winos');
  const value = await win.clipboard.read();
  console.log(value); // 'Hello from winos'

  // Push a native Windows toast notification with the warning symbol
  await win.notify.push({
    title: 'Deployment Agent',
    message: 'Task completed successfully',
    icon: 'info',
    sound: 'default'
  });
}

main().catch(console.error);

API Reference

Input Module (winos-utils/input)

Used to launch native Windows File and Folder picker dialogs.

selectFile

Launches a native Windows Open File Dialog box.

• Signature: selectFile(options?: FileDialogOptions): Promise<FileDialogResult>
• Options (FileDialogOptions):
  • title (string, optional): Title of the dialog window.
  • initialDirectory (string, optional): Folder path where the dialog should start.
  • multiSelect (boolean, optional): Set to true to allow choosing multiple files. Defaults to false.
  • filters (array or string, optional): Restricts file extensions. Can be a raw filter string or an array of FileFilter objects:

    interface FileFilter {
      name: string;      // e.g., 'Images'
      extensions: string[]; // e.g., ['png', 'jpg', 'gif']
    }

• Returns (FileDialogResult):
  • canceled (boolean): true if the dialog was closed without selecting a file.
  • files (string[]): Absolute paths of selected files. Empty if canceled.

selectFolder

Launches a native Windows Folder Browser Dialog box.

• Signature: selectFolder(options?: FolderDialogOptions): Promise<FolderDialogResult>
• Options (FolderDialogOptions):
  • title (string, optional): Description text displayed inside the folder dialog window.
  • initialDirectory (string, optional): Directory path where the dialog should start.
  • showNewFolderButton (boolean, optional): Set to true to show the 'New Folder' action. Defaults to true.
• Returns (FolderDialogResult):
  • canceled (boolean): true if the dialog was closed without selection.
  • folder (string): Absolute path of the selected folder. Empty string if canceled.

Clipboard Module (winos-utils/clipboard)

Manipulates the native clipboard. Supports reading the Windows Clipboard History.

write

Copies a plain text string to the system clipboard.

• Signature: write(text: string): Promise<void>

read

Reads the active plain text content stored in the clipboard.

• Signature: read(): Promise<string>
• Returns: Current clipboard text. Returns an empty string if clipboard is empty.

readHistory

Retrieves previous clipboard entries from the Windows Clipboard History queue.

• Signature: readHistory(): Promise<string[]>
• Returns: Array of previously copied text items, ordered from newest to oldest.
• Note: Requires the "Clipboard history" feature to be toggled on under Settings > System > Clipboard. If disabled, it prints a developer warning and returns an empty array [].

clear

Completely empties both the active clipboard value and the clipboard history queue.

• Signature: clear(): Promise<void>

Notify Module (winos-utils/notify)

push

Displays a native visual Windows Toast Notification to the user.

• Signature: push(options: ToastOptions): Promise<void>
• Options (ToastOptions):
  • title (string, required): Bold title header text.
  • message (string, required): Body message text.
  • icon (string, optional): Absolute/relative path to a local image, or a system icon preset: 'info', 'warning', 'error', 'question', or 'shield'. If omitted, no icon is shown.
  • silent (boolean, optional): Set to true to mute the notification alert sound. Defaults to false.
  • sound (string, optional): Alias mapping to system notifications: 'default', 'im', 'mail', 'reminder', 'sms', 'alarm', or 'call'. Defaults to 'default'.
  • duration (string or number, optional): 'short', 'long', or a number in milliseconds (durations < 10000ms map to short, >= 10000ms map to long). Defaults to 'short'.
  • appId (string, optional): Application User Model ID (AUMID) representing the source application. Defaults to standard PowerShell AUMID.

System Module (winos-utils/system)

openFolder

Launches Windows Explorer and opens a local directory.

• Signature: openFolder(folderPath: string): Promise<void>
• Note: Resolves relative paths automatically and verifies the folder exists before launching explorer.

openBrowser

Opens the default system web browser to the specified URL.

• Signature: openBrowser(url: string): Promise<void>
• Note: Restricts schemes to http: and https: to prevent command execution bypasses.

showMessage

Displays a native Windows Forms MessageBox dialog. Blocks JavaScript execution until dismissed.

• Signature: showMessage(message: string, options?: MessageDialogOptions): Promise<MessageDialogResult>
• Options (MessageDialogOptions):
  • title (string, optional): Title bar text. Defaults to 'winos'.
  • icon (string, optional): Graphic symbol: 'info', 'warning', 'error', 'question', or 'none'. Defaults to 'none'.
  • buttons (string, optional): Layout configuration: 'ok', 'ok-cancel', or 'yes-no'. Defaults to 'ok'.
• Returns: String representing the button clicked: 'ok', 'cancel', 'yes', or 'no'.

Security Model

Process execution in desktop scripting is susceptible to command injection attacks. Under the hood, winos mitigates this vector completely:

1. Standard Input Piping: Arguments are never passed as command-line script arguments (-Arg value). Parameters are serialized into JSON in Node.js, and piped directly through the child process's standard input stream (stdin).
2. Strict Deserialization: The executing PowerShell scripts retrieve and deserialize the JSON payload safely using ConvertFrom-Json in memory. This separates instructions from user data entirely.
3. URL Protocol Locking: The openBrowser function rejects any protocol schemes that are not explicitly http: or https:, blocking access to file:/// and administrative schema execution.

License

This project is licensed under the MIT License. See LICENSE for details.