Cross-Platform CLI Setup

​

Overview

The @unhook/cli package has been enhanced to work seamlessly across all major platforms (macOS, Windows, Linux, ARM/x64) using a hybrid approach that downloads platform-specific binaries during installation.

​

Architecture

​

Build System

• GitHub Actions: Builds binaries for all supported platforms
• Release Assets: Uploads binaries to GitHub releases with standardized naming
• Platforms Supported:
  • linux-x64 (glibc)
  • linux-arm64 (glibc)
  • linux-x64-musl (Alpine Linux)
  • linux-arm64-musl (Alpine Linux ARM64)
  • darwin-x64 (macOS Intel)
  • darwin-arm64 (macOS Apple Silicon)
  • win32-x64 (Windows 64-bit)

​

Installation Flow

​

Runtime Flow

​

File Structure

apps/cli/
├── bin/
│   └── cli.cjs                 # CommonJS CLI wrapper
├── scripts/
│   └── install.cjs             # Installation script
├── tests/
│   └── integration/
│       └── cross-platform.test.ts  # Integration tests
├── package.json                # Updated configuration
└── README.md                   # User documentation

​

Implementation Details

​

Platform Detection

The CLI intelligently detects the target platform and architecture:

const platformMap = { win32: 'win32', darwin: 'darwin', linux: 'linux' };
const archMap = { x64: 'x64', arm64: 'arm64' };

// Linux-specific: Detect musl vs glibc
if (platform === 'linux') {
  if (fs.existsSync('/lib/ld-musl-x86_64.so.1') || 
      fs.existsSync('/lib/ld-musl-aarch64.so.1')) {
    targetArch = `${arch}-musl`;
  }
}

​

Binary Naming Convention

Binaries follow this pattern: unhook-{platform}-{arch}[.exe]

​

Version Management

• Binaries are stored in versioned directories: ~/.unhook/bin/{version}/
• Old versions are automatically cleaned up during installation
• Multiple versions can coexist temporarily during upgrades

​

Edge Cases & Robustness

​

Network Issues

​

Platform-Specific Handling

// Remove quarantine attribute
execSync(`xattr -d com.apple.quarantine "${binPath}"`, { stdio: 'ignore' });

// Remove quarantine attribute
execSync(`xattr -d com.apple.quarantine "${binPath}"`, { stdio: 'ignore' });

// Detect musl by checking for loader
if (fs.existsSync('/lib/ld-musl-x86_64.so.1')) {
  targetArch = `${arch}-musl`;
}

const ext = os.platform() === 'win32' ? '.exe' : '';

​

CI/CD Environments

Problem: CI systems shouldn’t download binaries during installation

Solution:

// Skip installation in CI
if (require('is-ci')) {
  process.exit(0);
}

​

Testing Strategy

​

Integration Tests

Comprehensive test suite covering:

1. Platform Detection: Verify correct platform/arch identification
2. URL Construction: Ensure proper download URLs
3. Error Handling: Test failure scenarios
4. Package Configuration: Validate package.json settings
5. Platform-Specific Behavior: Test OS-specific features

​

Test Execution

# Run all integration tests
bun test tests/integration/cross-platform.test.ts

# Run with coverage
bun test --coverage tests/integration/

​

Troubleshooting

​

Performance Considerations

​

Security Considerations

• Verified Downloads: Binaries downloaded from official GitHub releases only
• Code Signing: macOS binaries are signed and notarized
• No Build Tools Required: Users don’t need compilers or build chains
• Quarantine Removal: Automatic handling of macOS security restrictions

​

Future Enhancements

1. Checksum Verification: Verify binary integrity using SHA checksums
2. Delta Updates: Only download changed parts of binaries
3. Mirror Support: Allow alternative download sources
4. Offline Mode: Bundle common binaries with the package
5. Auto-updates: Automatic binary updates when package is updated

​

Contributing

When adding support for new platforms:

​

References

• GitHub Releases API
• Node.js os module
• npm postinstall hooks
• Bun build targets