# FSKit Module Installation Guide

## Date: 2026-05-26
## Version: 1.0

---

## Overview

**FSKit Module System-Level Installation**

FSKit Modules need to be installed at system level to be loaded by macOS FSKit framework.

---

## FSKit Module Architecture

### FSKit Module Components

| Component | Type | Description |
|-----------|------|-------------|
| **Bundle Type** | `XFSK` | FSKit Module Bundle (defined in project.yml) |
| **Bundle ID** | `com.accusys.markbase.fskitmodule` | Unique identifier |
| **Module Class** | `MarkBaseFSModule` | FSUnaryFileSystemOperations implementation |
| **Volume Class** | `MarkBaseFSVolumeFSKit` | FSVolume implementation |

---

## Installation Methods

### Method 1: Manual Bundle Installation (POC)

**Step 1: Build FSKit Module Bundle**

```bash
cd /Users/accusys/markbase/MarkBaseFS
xcodebuild -project MarkBaseFS.xcodeproj \
    -target MarkBaseFSFSKitModule \
    -configuration Debug \
    build
```

**Expected Output:**
- Bundle location: `build/Debug/MarkBaseFSFSKitModule.bundle`
- Bundle type: `XFSK` (FSKit Module Bundle)

**Step 2: Install Bundle to System Directory**

```bash
# Create filesystems directory (if not exists)
sudo mkdir -p /Library/Filesystems

# Copy FSKit Module bundle to system directory
sudo cp -R build/Debug/MarkBaseFSFSKitModule.bundle \
    /Library/Filesystems/MarkBaseFSFSKitModule.bundle

# Set proper permissions
sudo chmod 755 /Library/Filesystems/MarkBaseFSFSKitModule.bundle
sudo chown root:wheel /Library/Filesystems/MarkBaseFSFSKitModule.bundle
```

**Step 3: Restart FSKit Service**

```bash
# Restart FSKit service (requires macOS restart or specific command)
# This step may require further research
sudo launchctl unload /System/Library/LaunchDaemons/com.apple.fskit.plist
sudo launchctl load /System/Library/LaunchDaemons/com.apple.fskit.plist
```

---

### Method 2: System Extension API (Recommended)

**FSKit Module may be installed via System Extension API**

**Research Required:**
- `SystemExtension` framework for FSKit Module installation
- `OSSystemExtensionRequest` for requesting installation
- Requires user approval via System Preferences

**Hypothesis:**
FSKit Modules may be installed similar to System Extensions:
1. Application requests installation via System Extension API
2. macOS prompts user for approval
3. User approves installation via System Preferences
4. FSKit Module installed to system directory

---

### Method 3: FSKit Client API (Unknown)

**FSClient.fetchInstalledExtensions() can retrieve installed modules**

**Unknown:**
- How to install FSKit Module via FSClient API
- No public API for module installation found yet

---

## Verification Methods

### Method 1: FSClient.fetchInstalledExtensions()

```swift
import FSKit

let client = FSClient.shared
client.fetchInstalledExtensions { modules, error in
    if let modules = modules {
        for module in modules {
            print("Module: \(module.bundleIdentifier)")
            print("  URL: \(module.url)")
            print("  Enabled: \(module.enabled)")
        }
    }
}
```

### Method 2: Check System Directory

```bash
# Check if bundle exists in system directory
ls -la /Library/Filesystems/

# Expected output:
# MarkBaseFSFSKitModule.bundle (if installed)
```

---

## Current Status

### POC Status

| Status | Description |
|--------|-------------|
| ✅ FSKit Module Build | MarkBaseFSFSKitModule.bundle compiled successfully |
| ⏳ System Installation | Manual installation method tested (POC) |
| ⏳ FSKit Service Restart | Requires further research |
| ⏳ Module Loading | Requires FSKit framework to load module |

---

## Next Steps

### Research Required

1. **FSKit Module Installation API**
   - Search Apple Developer Documentation
   - Search WWDC videos for FSKit demos
   - Search Apple Developer Forums

2. **System Extension Integration**
   - Research System Extension framework
   - Test System Extension installation for FSKit Module

3. **FSKit Service Management**
   - Research how to restart FSKit service
   - Research how to force FSKit to reload modules

---

## Known Limitations

### POC Limitations

- Manual installation may not be persistent
- FSKit service restart may not be supported
- Module loading requires macOS FSKit framework cooperation

---

## References

- `/Applications/Xcode.app/Contents/Developer/Platforms/MacOSX.platform/Developer/SDKs/MacOSX.sdk/System/Library/Frameworks/FSKit.framework/`
- `FSModuleIdentity.h` - Installed module representation
- `FSClient.h` - Module management API
- `FSUnaryFileSystem.h` - File system module entry point

---

**Last Updated: 2026-05-26**