@principal-ade/repository-monitoring-server

Electron-based repository monitoring server with git watching and package detection. This package provides a multi-process architecture for monitoring Git repositories, detecting packages, and tracking file changes in Electron applications.

Features

• Git Watching: Real-time monitoring of git state changes (commits, branch switches, merges)
• File Tree Management: Git-aware file tree structures with .gitignore support
• Package Detection: Automatic discovery of packages in monorepos and single-package repositories
• Cache Management: Event-driven caching system with SHA-based invalidation
• Quality Metrics: On-demand quality analysis for detected packages
• Multi-Process Architecture: Runs in a separate utility process for better performance

Installation

npm install @principal-ade/repository-monitoring-server

Architecture

The package uses a multi-process architecture:

┌─────────────────────┐
│  Renderer Process   │
│  (UI Layer)         │
└──────────┬──────────┘
           │ IPC
┌──────────▼──────────┐
│   Main Process      │
│  (Electron Main)    │
└──────────┬──────────┘
           │ Utility Process Fork
┌──────────▼──────────┐
│  Repository         │
│  Monitoring Server  │
│  (Worker Process)   │
└─────────────────────┘

Usage

Basic Setup (Main Process)

import {
  RepositoryMonitoringManager,
  registerRepositoryMonitoringHandlers,
} from '@principal-ade/repository-monitoring-server';

// Initialize the monitoring manager
const manager = new RepositoryMonitoringManager({
  autoStart: true,
  restartOnCrash: true,
  maxRestartAttempts: 3,
  logLevel: 'info',
});

// Register IPC handlers
registerRepositoryMonitoringHandlers({ manager });

// Register a repository
await manager.registerRepository('/path/to/repo');

// Start git watching
await manager.enableGitWatching('/path/to/repo');

With Dependency Injection

If your application has services like Alexandria Registry, User Preferences, or Quality Lens Service, you can inject them:

import {
  RepositoryMonitoringManager,
  registerRepositoryMonitoringHandlers,
  RepositoryRegistrationManager,
  type IAlexandriaRegistryService,
  type IUserPreferencesHandler,
  type IQualityLensService,
} from '@principal-ade/repository-monitoring-server';

// Your app's services (must implement the interfaces)
const alexandriaService: IAlexandriaRegistryService = AlexandriaRegistryService.getInstance();
const preferencesHandler: IUserPreferencesHandler = UserPreferencesHandler.getInstance();
const qualityLensService: IQualityLensService = QualityLensService.getInstance();

// Initialize manager
const manager = new RepositoryMonitoringManager({
  autoStart: true,
  restartOnCrash: true,
  maxRestartAttempts: 3,
  logLevel: 'info',
});

// Register IPC handlers with quality lens service
registerRepositoryMonitoringHandlers({
  manager,
  qualityLensService,
});

// Auto-register all repositories from Alexandria
const registrationManager = RepositoryRegistrationManager.getInstance({
  monitoringManager: manager,
  alexandriaRegistryService: alexandriaService,
  userPreferencesHandler: preferencesHandler,
});

await registrationManager.initialize();

Using the Manager

// Get file tree for a repository
const fileTree = await manager.getFileTree('/path/to/repo');

// Get packages
const { packages, summary } = await manager.getPackages('/path/to/repo');

// Get git status
const gitStatus = await manager.getGitStatus('/path/to/repo');

// Get git remote info
const remoteInfo = await manager.getGitRemote('/path/to/repo');

// Get monitoring status
const status = await manager.getStatus('/path/to/repo');

// Disable git watching
await manager.disableGitWatching('/path/to/repo');

// Unregister repository
await manager.unregisterRepository('/path/to/repo');

Renderer Process (IPC Communication)

In your renderer process, communicate via IPC:

import { RepositoryMonitoringAPIEvent } from '@principal-ade/repository-monitoring-server';

// Get file tree
const fileTree = await window.electron.ipcRenderer.invoke(
  RepositoryMonitoringAPIEvent.GET_FILE_TREE,
  '/path/to/repo'
);

// Get packages
const result = await window.electron.ipcRenderer.invoke(
  RepositoryMonitoringAPIEvent.GET_PACKAGES,
  '/path/to/repo'
);

// Listen for cache updates
window.electron.ipcRenderer.on(
  RepositoryMonitoringAPIEvent.CACHE_SYNC,
  (event, data) => {
    console.log('Cache updated:', data);
  }
);

// Listen for git state events
window.electron.ipcRenderer.on(
  RepositoryMonitoringAPIEvent.GIT_STATE_EVENT,
  (event, payload) => {
    console.log('Git state changed:', payload.event.type);
  }
);

Dependency Injection Interfaces

The package defines interfaces for optional services:

IAlexandriaRegistryService

interface IAlexandriaRegistryService {
  getRepositories(): Promise<AlexandriaEntry[]>;
}

IUserPreferencesHandler

interface IUserPreferencesHandler {
  getUserPreferences(): Promise<{
    enableGitWatchingOnStartup?: boolean;
    [key: string]: any;
  }>;
}

IQualityLensService

interface IQualityLensService {
  executeToolForPackage(request: ToolExecutionRequest): Promise<ToolExecutionResponse>;
}

Events

The monitoring server emits the following IPC events:

• REPO_MONITORING_CACHE_SYNC - Cache updates for file trees, packages, git status, or git remote
• REPO_MONITORING_GIT_STATE_EVENT - Git state changes (commit, branch-switch, merge, dirty-state-change)
• REPO_MONITORING_WORKSPACE_CHANGED - File changes in the workspace (add, change, unlink)
• REPO_MONITORING_GIT_STATUS_CHANGED - Git status updates (staged, unstaged, branch info)

Cache Slices

The system maintains 4 cache slices per repository:

1. fileTree - Git-aware file tree with .gitignore support
2. packages - Detected packages and their metadata
3. gitStatus - Current git status with file lists
4. gitRemote - Remote URL and branch information

Caches are automatically invalidated and rebuilt when relevant changes occur.

Configuration Options

RepositoryMonitoringManager Options

interface RepositoryMonitoringManagerConfig {
  autoStart?: boolean;           // Auto-start worker process (default: true)
  restartOnCrash?: boolean;      // Restart worker on crash (default: true)
  maxRestartAttempts?: number;   // Max restart attempts (default: 3)
  logLevel?: 'debug' | 'info' | 'warn' | 'error';
}

Development

Building

npm run build

Testing

npm test

License

PROPRIETARY - Private package for Principal AI

Support

For issues and questions, please contact the Principal AI development team.