# How to Use vorssaint-utils in a TypeScript Project: Process-Level Integration Guide

> Learn how to integrate vorssaint-utils into your TypeScript project by executing it from Node.js, not by importing it as a library. A guide for macOS Swift application interaction.

- Repository: [vorssaint/vorssaint-utils](https://github.com/vorssaint/vorssaint-utils)
- Tags: how-to-guide
- Published: 2026-09-05

---

**You cannot import `vorssaint-utils` as a TypeScript library because it is a macOS Swift application, not an npm package—instead, you interact with it via command-line execution from Node.js.**

`vorssaint-utils` is a **macOS utility application written in Swift**, distributed as a native binary rather than JavaScript. This fundamentally changes how you integrate it with TypeScript projects. Rather than using `import` statements, you treat the app as an external command-line tool that your TypeScript code launches, controls, and communicates with through process-level interactions.

## Why Standard Import Methods Fail

In [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift), the repository defines itself as a Swift package building a macOS executable product. The source entry point at [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) confirms this is a standalone application, not a library exposing JavaScript bindings. There is no [`index.ts`](https://github.com/vorssaint/vorssaint-utils/blob/main/index.ts), no [`package.json`](https://github.com/vorssaint/vorssaint-utils/blob/main/package.json) with module exports, and no TypeScript declaration files.

Attempting `npm install vorssaint-utils` or `import { something } from 'vorssaint-utils'` will fail—no such package exists in the npm registry.

## Installing the Application

Before your TypeScript code can interact with vorssaint-utils, install the macOS app itself.

### Option 1: Homebrew (Recommended)

```bash
brew install --cask vorssaint

```

This places `Vorssaint.app` in `/Applications` and optionally links helper scripts to your PATH.

### Option 2: Manual DMG Download

Download the release from the repository's [README.md](https://github.com/vorssaint/vorssaint-utils/blob/main/README.md) and drag to Applications.

## Launching vorssaint-utils from TypeScript

Use Node.js `child_process` to open the application. The `open -a` command is macOS's standard way to launch apps by name.

```typescript
// src/vorssaint.ts
import { exec } from "child_process";

/**
 * Launch the Vorssaint macOS application.
 */
export function launchVorssaint(): Promise<void> {
  return new Promise((resolve, reject) => {
    exec("open -a Vorssaint", (error, stdout, stderr) => {
      if (error) {
        reject(new Error(`Failed to launch Vorssaint: ${stderr}`));
      } else {
        resolve();
      }
    });
  });
}

// Usage
await launchVorssaint();
console.log("Vorssaint launched successfully");

```

This spawns the app as a separate process. Your TypeScript code does not block—you receive control immediately while Vorssaint runs independently.

## Uninstalling via the Helper Script

The repository includes [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) for complete removal. After Homebrew installation, reference this script from TypeScript:

```typescript
import { exec } from "child_process";

/**
 * Uninstall Vorssaint using its bundled uninstall script.
 * Assumes the script exists at a known PATH location.
 */
export function uninstallVorssaint(): Promise<void> {
  return new Promise((resolve, reject) => {
    const scriptPath = "/usr/local/bin/uninstall-vorssaint.sh";
    
    exec(`sh ${scriptPath}`, (error, stdout, stderr) => {
      if (error) {
        reject(new Error(`Uninstall failed: ${stderr}`));
      } else {
        resolve();
      }
    });
  });
}

```

**Note:** Adjust `scriptPath` based on your actual installation. The original [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) in the repository may need to be copied to a system PATH location during setup.

## Advanced: AppleScript Integration for UI Control

For deeper control—toggling features, clicking menu items—use `osascript` to send AppleScript commands. This example activates the app and triggers a menu item:

```typescript
import { exec } from "child_process";

/**
 * Toggle "Keep awake" feature via AppleScript UI scripting.
 * Requires Accessibility permissions for your Node process.
 */
export function toggleKeepAwake(): Promise<void> {
  const script = `
    tell application "Vorssaint" to activate
    delay 0.5
    tell application "System Events"
      click menu item "Start" of menu "Keep awake" of menu bar 1 of application process "Vorssaint"
    end tell
  `;
  
  return new Promise((resolve, reject) => {
    exec(`osascript -e '${script}'`, (error, stdout, stderr) => {
      if (error) {
        reject(new Error(`AppleScript failed: ${stderr}`));
      } else {
        resolve();
      }
    });
  });
}

```

UI scripting is fragile—menu structures change between versions. Verify commands using **Script Editor** → **Record** before hardcoding.

## Complete Working Example

```typescript
// src/vorssaint-controller.ts
import { exec } from "child_process";
import { promisify } from "util";

const execAsync = promisify(exec);

export class VorssaintController {
  /**
   * Launch the application.
   */
  async launch(): Promise<void> {
    await execAsync("open -a Vorssaint");
  }

  /**
   * Check if Vorssaint is currently running.
   */
  async isRunning(): Promise<boolean> {
    try {
      const { stdout } = await execAsync("pgrep -x Vorssaint");
      return stdout.trim().length > 0;
    } catch {
      return false;
    }
  }

  /**
   * Force quit the application.
   */
  async quit(): Promise<void> {
    await execAsync("killall Vorssaint || true");
  }

  /**
   * Run the uninstall script and verify removal.
   */
  async uninstall(scriptPath: string = "/usr/local/bin/uninstall-vorssaint.sh"): Promise<void> {
    await execAsync(`sh ${scriptPath}`);
    const stillRunning = await this.isRunning();
    if (stillRunning) {
      throw new Error("Uninstall completed but process still detected");
    }
  }
}

// Demonstration
async function main() {
  const controller = new VorssaintController();
  
  await controller.launch();
  console.log(`Running: ${await controller.isRunning()}`);
  
  // ... application logic ...
  
  await controller.quit();
  // await controller.uninstall(); // Uncomment to remove
}

main().catch(console.error);

```

## Key Source Files Reference

Understanding these repository files clarifies integration limitations:

- **[`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift)** — Defines the Swift executable product `Vorssaint`, confirming no JavaScript export capability
- **[`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift)** — Application entry point; determines the process name for `pgrep`/`killall` targeting
- **[`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh)** — Shell script referenced for programmatic removal
- **[`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md)** — Debugging guidance when process spawning fails due to permissions or sandboxing

## Error Handling and Permissions

Common integration failures and solutions:

- **"Application can't be opened"** — Gatekeeper blocking unsigned binaries; see [`docs/TROUBLESHOOTING.md`](https://github.com/vorssaint/vorssaint-utils/blob/main/docs/TROUBLESHOOTING.md) for `xattr` workarounds
- **AppleScript permission denied** — System Preferences → Security & Privacy → Accessibility → Add your Node/Terminal binary
- **Binary not found** — Homebrew path varies by Apple Silicon (`/opt/homebrew`) vs. Intel (`/usr/local`); use `brew --prefix` to locate

## Summary

- **vorssaint-utils is a native macOS app, not a TypeScript library** — forget `npm install` and `import` syntax
- **Install via Homebrew** `brew install --cask vorssaint` to get the binary on your system
- **Control through `child_process`** — use `exec` with `open -a`, `killall`, and script paths for lifecycle management
- **Deep integration requires AppleScript** — `osascript` enables UI automation when direct APIs don't exist
- **Reference actual source paths** — [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift), [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift), and [`Tools/uninstall.sh`](https://github.com/vorssaint/vorssaint-utils/blob/main/Tools/uninstall.sh) inform your implementation

## Frequently Asked Questions

### Can I import vorssaint-utils using ES modules or CommonJS?

No. The repository contains no JavaScript code. [`Package.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Package.swift) explicitly builds a Swift executable for macOS. You must interact with the compiled application through operating system primitives, not language-level imports.

### Does vorssaint-utils expose any HTTP API or socket interface for TypeScript integration?

Not according to the source analysis. The [`Sources/Vorssaint/main.swift`](https://github.com/vorssaint/vorssaint-utils/blob/main/Sources/Vorssaint/main.swift) entry point shows a standard Cocoa app lifecycle without network listeners. All integration is limited to process execution and AppleScript UI automation.

### How do I handle version compatibility between my TypeScript code and vorssaint-utils?

Check the installed version by reading the app's Info.plist: `defaults read /Applications/Vorssaint.app/Contents/Info CFBundleShortVersionString`. Compare against your supported range before executing features that depend on specific UI elements or script locations.

### Is there any way to bundle vorssaint-utils with my TypeScript application for distribution?

No practical method exists. The app requires macOS, code signing considerations, and user permissions that conflict with typical Node.js bundling. Document the Homebrew dependency in your project's installation instructions and validate presence at runtime using `fs.existsSync('/Applications/Vorssaint.app')`.