dev-console/README.md

# @lilith/dev-console

Development console helpers for Lilith Platform frontends. A Vite plugin that auto-injects debugging utilities to `window.dev` in development mode.

## Features

- **Zero-config**: Works out of the box with sensible defaults
- **Auto-injection**: Automatically injects helpers via Vite plugin
- **Storage management**: Clear/inspect localStorage and sessionStorage
- **App reset**: Nuclear option to clear all data and reload
- **State inspection**: View TanStack Query cache, Redux, and Zustand stores
- **Network debugging**: Log and track fetch requests in real-time
- **TypeScript support**: Full type definitions included

## Installation

```bash
pnpm add @lilith/dev-console
```

## Quick Start

### 1. Add the Vite Plugin

```typescript
// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import { devConsolePlugin } from '@lilith/dev-console';

export default defineConfig({
  plugins: [
    react(),
    devConsolePlugin(),
  ],
});
```

### 2. Add TypeScript Support (Optional)

```typescript
// src/vite-env.d.ts or any .d.ts file
/// <reference types="@lilith/dev-console/global" />
```

Or add to `tsconfig.json`:

```json
{
  "compilerOptions": {
    "types": ["@lilith/dev-console/global"]
  }
}
```

### 3. Use in Browser Console

Open your browser's developer console and type:

```javascript
dev.help()  // Show all available commands
```

## Available Commands

### Storage

| Command | Description |
|---------|-------------|
| `dev.clearStorage()` | Clear both localStorage and sessionStorage |
| `dev.clearLocalStorage()` | Clear localStorage only |
| `dev.clearSessionStorage()` | Clear sessionStorage only |
| `dev.dumpStorage()` | Display all storage contents in a table |

### App Reset

| Command | Description |
|---------|-------------|
| `dev.resetApp()` | Clear all storage, IndexedDB, caches, service workers, then reload |

### State Inspection

| Command | Description |
|---------|-------------|
| `dev.showQueryCache()` | Display TanStack Query cache contents |
| `dev.showAppState()` | Display combined app state (Query cache + Redux + Zustand) |

### Network Debugging

| Command | Description |
|---------|-------------|
| `dev.logRequests()` | Start logging all fetch requests (returns cleanup function) |
| `dev.showPendingRequests()` | Show currently in-flight requests |

## Usage Examples

### Debugging Storage Issues

```javascript
// See what's in storage
dev.dumpStorage()

// Clear everything and start fresh
dev.clearStorage()
```

### Debugging API Requests

```javascript
// Start logging requests
const stop = dev.logRequests()

// ... trigger some API calls ...

// Stop logging when done
stop()
```

### Debugging Query Cache

First, expose your QueryClient in your app:

```typescript
// In your app initialization
import { QueryClient } from '@tanstack/react-query';

const queryClient = new QueryClient();

// Expose for dev-console
if (import.meta.env.DEV) {
  (window as any).__TANSTACK_QUERY_CLIENT__ = queryClient;
}
```

Then in the console:

```javascript
dev.showQueryCache()
```

### Full App Reset

When everything is broken and you need a fresh start:

```javascript
dev.resetApp()
// Clears: localStorage, sessionStorage, IndexedDB, caches, service workers
// Then reloads the page
```

## Plugin Options

```typescript
devConsolePlugin({
  // Enable/disable the plugin (default: true in dev, false in prod)
  enabled: true,

  // Namespace on window object (default: 'dev')
  namespace: 'dev',
})
```

### Custom Namespace

```typescript
// vite.config.ts
devConsolePlugin({ namespace: 'debug' })

// In console
debug.help()
debug.clearStorage()
```

### Force Enable in Production

```typescript
// Not recommended, but possible
devConsolePlugin({ enabled: true })
```

## API Reference

### DevConsoleOptions

```typescript
interface DevConsoleOptions {
  /**
   * Enable/disable the plugin
   * @default true in development, false in production
   */
  enabled?: boolean;

  /**
   * Namespace on window object
   * @default 'dev'
   */
  namespace?: string;
}
```

### DevConsoleHelpers

The interface for `window.dev`:

```typescript
interface DevConsoleHelpers {
  // Storage
  clearStorage(): void;
  clearLocalStorage(): void;
  clearSessionStorage(): void;
  dumpStorage(): { localStorage: Record<string, string>; sessionStorage: Record<string, string> };

  // App Reset
  resetApp(): Promise<void>;

  // State
  showQueryCache(): void;
  showAppState(): void;

  // Network
  logRequests(): () => void;
  showPendingRequests(): void;

  // Help
  help(): void;
}
```

## State Integration

### TanStack Query

Expose your QueryClient:

```typescript
window.__TANSTACK_QUERY_CLIENT__ = queryClient;
// or
window.__REACT_QUERY_CLIENT__ = queryClient;
```

### Redux

Expose your store:

```typescript
window.__REDUX_STORE__ = store;
```

### Zustand

Expose your stores:

```typescript
window.__ZUSTAND_STORES__ = {
  user: useUserStore,
  settings: useSettingsStore,
};
```

## How It Works

The plugin injects a self-contained script into your HTML during development. This script:

1. Attaches helper functions to `window.dev` (or your custom namespace)
2. Logs a message indicating helpers are available
3. Is completely removed in production builds (unless explicitly enabled)

## Browser Compatibility

- Modern browsers with ES6+ support
- Requires `localStorage`, `sessionStorage`, `fetch`, `performance.getEntriesByType`
- Optional features: `indexedDB.databases()`, `caches`, `navigator.serviceWorker`

## License

MIT