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

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, the repository defines itself as a Swift package building a macOS executable product. The source entry point at Sources/Vorssaint/main.swift confirms this is a standalone application, not a library exposing JavaScript bindings. There is no index.ts, no 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)

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 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.

// 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 for complete removal. After Homebrew installation, reference this script from 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 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:

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

// 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 — Defines the Swift executable product Vorssaint, confirming no JavaScript export capability
• Sources/Vorssaint/main.swift — Application entry point; determines the process name for pgrep/killall targeting
• Tools/uninstall.sh — Shell script referenced for programmatic removal
• 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 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, Sources/Vorssaint/main.swift, and 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 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 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').

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}