@pixora-dev-ai/dev-sentinel/README.md

🛡️ Enterprise-grade observability SDK for React applications. Real-time diagnostics with 14+ specialized packs: Network Intelligence, Security Guards, Privacy Protection, Code Quality Analysis, Device Monitoring, and more.

# 🛡️ Dev-Sentinel

[![npm version](https://img.shields.io/npm/v/@prepilot/dev-sentinel.svg)](https://www.npmjs.com/package/@prepilot/dev-sentinel)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.8+-blue.svg)](https://www.typescriptlang.org/)

> **Enterprise-grade observability SDK for React applications**  
> Real-time diagnostics, intelligent monitoring, and advanced debugging tools for modern web applications.

---

## 🚀 Why Dev-Sentinel?

Dev-Sentinel is not just another logging library. It's a **comprehensive observability platform** that gives you:

✅ **14+ Specialized Monitoring Packs** - Network, Security, Privacy, Performance, Testing, and more  
✅ **Zero Runtime Overhead in Production** - Only runs in development mode  
✅ **Smart AI-Assisted Analysis** - Detect code smells, patterns, and anti-patterns automatically  
✅ **Visual Dev Panel** - Beautiful UI to inspect all diagnostics in real-time  
✅ **Export & Share** - Download logs as JSON for debugging with your team  
✅ **Framework Agnostic Core** - Works with React, Vite, and modern build tools  
✅ **Privacy-First** - Built-in PII redaction and sensitive data protection  

---

## 📦 Installation

```bash
# npm
npm install @prepilot/dev-sentinel

# yarn
yarn add @prepilot/dev-sentinel

# pnpm
pnpm add @prepilot/dev-sentinel
```

---

## ⚡ Quick Start

### 1. Basic Setup

```typescript
import { devSentinel } from '@prepilot/dev-sentinel';

// Log an event
devSentinel.log('network_request', {
  url: '/api/users',
  method: 'GET',
  status: 200,
  duration: 234
});

// Subscribe to events
const unsubscribe = devSentinel.subscribe((event) => {
  console.log('New event:', event);
});
```

### 2. With React Components

```tsx
import { useEffect } from 'react';
import { devSentinel } from '@prepilot/dev-sentinel';

function App() {
  useEffect(() => {
    // Hydrate logs from IndexedDB
    devSentinel.hydrateFromDb();
    
    // Subscribe to runtime events
    const unsubscribe = devSentinel.subscribe((event) => {
      console.log('Event logged:', event);
    });
    
    return () => unsubscribe();
  }, []);
  
  return <YourApp />;
}
```

### 3. Enable Privacy Protection

```typescript
import { 
  devSentinel, 
  configureDevSentinelRedaction,
  defaultDevSentinelRedactor 
} from '@prepilot/dev-sentinel';

// Use default redactor (removes emails, tokens, passwords, etc.)
configureDevSentinelRedaction(defaultDevSentinelRedactor);

// Or create custom redactor
import { createRedactor } from '@prepilot/dev-sentinel';

const customRedactor = createRedactor({
  piiPatterns: [
    /\b\d{3}-\d{2}-\d{4}\b/g, // SSN
    /\b\d{16}\b/g // Credit cards
  ],
  tokenPatterns: [
    /Bearer\s+[\w-]+/gi,
    /api[_-]?key[\s:=]+[\w-]+/gi
  ]
});

configureDevSentinelRedaction(customRedactor);
```

---

## 📊 Available Packs

Dev-Sentinel organizes monitoring capabilities into specialized **Packs**:

| Pack | Description | Key Features |
|------|-------------|--------------|
| 🌐 **Network Pack** | API monitoring & diagnostics | Endpoint health, waterfall analysis, retry tracking |
| 🧪 **Testing Pack** | Runtime test intelligence | Flaky tests, race conditions, coverage gaps |
| 🎨 **Design Pack** | UI/UX quality monitoring | Layout shifts, responsive issues, contrast errors |
| 🔐 **Secure-UI Pack** | Fraud & abuse detection | Click injection, autofill abuse, brute-force detection |
| 🔒 **Privacy Guard Pack** | PII protection | Console leaks, storage issues, analytics protection |
| 📱 **Device Pack** | Hardware diagnostics | CPU throttling, memory pressure, battery saver |
| 🌍 **Environment Pack** | Runtime environment tracking | OS detection, browser info, WebView detection |
| 🧠 **Code Smell Pack** | AI-powered code analysis | Duplicate logic, props explosion, anti-patterns |
| 🔄 **Regression Pack** | Issue tracking & history | Novel issues, fingerprints, frequency spikes |
| 🔑 **Auth & Session Pack** | Authentication flow monitoring | Token issues, logout problems, multi-tab sync |
| 🤖 **AI Agent Pack** | LLM interaction monitoring | Prompt tracking, hallucination detection, context overhead |
| 📈 **SaaS Metrics Pack** | Product analytics | Funnel analysis, friction detection, time-to-value |
| ♿ **A11y Interaction Pack** | Accessibility UX tracking | Rage clicks, dead taps, small tap targets |
| 🚩 **Feature Flag Pack** | Flag management monitoring | Misconfigurations, conflicts, flag drift |

---

## 🎯 Core API

### Logging Events

```typescript
// Basic logging
await devSentinel.log('network_request', payload);

// Network-specific
await devSentinel.log('endpoint_health_update', { 
  endpoint: '/api/users',
  health: 'degraded' 
});

// Security events
await devSentinel.log('secure_ui_brute_force_indicator', {
  attempts: 5,
  ip: '192.168.1.1'
});

// Privacy events
await devSentinel.log('privacy_console_pii_leak', {
  message: 'User email detected in console'
});
```

### Retrieving Logs

```typescript
// Get all logs
const allLogs = await devSentinel.get();

// Get specific event type
const networkLogs = await devSentinel.getNetwork('network_request');
const securityLogs = await devSentinel.getSecureUi('secure_ui_click_injection_pattern');
const privacyLogs = await devSentinel.getPrivacy('privacy_storage_pii_issue');
const deviceLogs = await devSentinel.getDevice('device_issue');
```

### Subscribing to Events

```typescript
// Subscribe to all events
const unsubAll = devSentinel.subscribe((event) => {
  console.log('Event:', event);
});

// Subscribe to network events only
const unsubNetwork = devSentinel.subscribeNetwork((event) => {
  console.log('Network event:', event);
});

// Subscribe to security events
const unsubSecurity = devSentinel.subscribeSecureUi((event) => {
  console.log('Security event:', event);
});

// Subscribe to privacy events
const unsubPrivacy = devSentinel.subscribePrivacy((event) => {
  console.log('Privacy event:', event);
});

// Clean up
unsubAll();
unsubNetwork();
```

### Clearing Logs

```typescript
// Clear all design logs
await devSentinel.clear();

// Clear specific event type
await devSentinel.clearNetwork('network_request');
await devSentinel.clearSecureUi('secure_ui_brute_force_indicator');
await devSentinel.clearPrivacy('privacy_console_pii_leak');
```

---

## 🎨 Dev Panel Integration

Dev-Sentinel includes a beautiful **Dev Panel** component for visualizing diagnostics:

```tsx
import { DevPanel } from '@prepilot/dev-sentinel/ui';

function App() {
  return (
    <>
      <YourApp />
      {import.meta.env.DEV && <DevPanel />}
    </>
  );
}
```

**Features:**
- 📊 Real-time event streaming
- 🔍 Advanced filtering by pack and event type
- 📥 Export logs as JSON
- 🎯 Click to inspect detailed payloads
- 🎨 Beautiful UI with syntax highlighting
- 🌙 Dark mode support

---

## 🔧 Advanced Usage

### Custom Event Types

```typescript
import type { StoredLog } from '@prepilot/dev-sentinel';

interface CustomPayload {
  userId: string;
  action: string;
  metadata: Record<string, unknown>;
}

await devSentinel.log('custom_event_type' as any, {
  userId: 'user-123',
  action: 'clicked_button',
  metadata: { page: 'dashboard' }
} as CustomPayload);
```

### Hydration from IndexedDB

```typescript
// Hydrate all stores on app init
await Promise.all([
  devSentinel.hydrateFromDb(),
  devSentinel.hydrateCodeSmellFromDb(),
  devSentinel.hydrateSecureUiFromDb(),
  devSentinel.hydratePrivacyFromDb(),
  devSentinel.hydrateDeviceFromDb(),
  devSentinel.hydrateEnvFromDb()
]);
```

### TypeScript Support

Full TypeScript support with comprehensive type definitions:

```typescript
import type {
  NetworkEventType,
  TestingEventType,
  CodeSmellEventType,
  SecureUiEventType,
  PrivacyEventType,
  DeviceEventType,
  EnvironmentEventType,
  StoredLog
} from '@prepilot/dev-sentinel';
```

---

## 🏗️ Architecture

Dev-Sentinel uses a **modular store architecture**:

```
devSentinel (main)
├── SentinelStore (design events)
├── NetworkEventStore (network events)
├── CodeSmellStore (code quality events)
├── SecureUiStore (security events)
├── PrivacyStore (privacy events)
├── DeviceEventStore (device events)
└── EnvironmentEventStore (environment events)
```

Each store:
- ✅ Persists to **IndexedDB** automatically
- ✅ Provides **reactive subscriptions**
- ✅ Supports **filtering and clearing**
- ✅ Implements **hydration** from storage

---

## 🔒 Privacy & Security

Dev-Sentinel takes privacy seriously:

- 🚫 **Never runs in production** (checks `import.meta.env.DEV`)
- 🔐 **Built-in PII redaction** for emails, tokens, passwords
- 🛡️ **Customizable redaction rules**
- 📊 **Local-only storage** (IndexedDB, no external calls)
- 🔍 **Privacy Guard Pack** detects accidental PII leaks

---

## 📖 Documentation

Comprehensive documentation for each pack:

- [Network Pack Guide](./docs/Network_Pack_Overview.md)
- [Testing Pack Guide](./docs/Testing_Pack_Overview.md)
- [Secure-UI Pack Guide](./docs/SecureUI_Pack_Overview.md)
- [Privacy Guard Guide](./docs/Privacy_Guard_Overview.md)
- [Code Smell Pack Guide](./docs/CodeSmell_Pack_Overview.md)
- [Device & Environment Pack Guide](./docs/Device_Environment_Pack.md)
- [Regression Pack Guide](./docs/Regression_Pack_Overview.md)
- [Integration Guide](./docs/INTEGRATION_GUIDE.md)

---

## 🤝 Contributing

We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details.

---

## 📝 License

MIT © PrePilot Team

---

## 🙏 Acknowledgments

Built with:
- React Error Boundary
- IndexedDB
- TypeScript
- Zod (for schema validation)

---

## 📧 Support

- 🐛 [Report Issues](https://github.com/prepilot/dev-sentinel/issues)
- 💬 [Discussions](https://github.com/prepilot/dev-sentinel/discussions)
- 📖 [Documentation](https://github.com/prepilot/dev-sentinel/wiki)

---

<div align="center">
  <strong>Made with ❤️ by the PrePilot Team</strong>
  <br />
  <sub>Elevating developer experience, one diagnostic at a time.</sub>
</div>