@flight-framework/devtools 0.0.1

package/package.json

@@ -0,0 +1,39 @@
+{
+    "name": "@flight-framework/devtools",
+    "version": "0.0.1",
+    "description": "Development tools and debugging panel for Flight Framework",
+    "type": "module",
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./panel": {
+            "types": "./dist/panel.d.ts",
+            "import": "./dist/panel.js"
+        },
+        "./instrumentation": {
+            "types": "./dist/instrumentation.d.ts",
+            "import": "./dist/instrumentation.js"
+        }
+    },
+    "scripts": {
+        "build": "tsc",
+        "dev": "tsc --watch"
+    },
+    "peerDependencies": {
+        "@flight-framework/core": ">=0.0.1"
+    },
+    "devDependencies": {
+        "typescript": "^5.7.0"
+    },
+    "keywords": [
+        "flight",
+        "devtools",
+        "debugging",
+        "development"
+    ],
+    "license": "MIT"
+}

package/src/index.ts

@@ -0,0 +1,273 @@
+/**
+ * @flight-framework/devtools - Development Tools
+ * 
+ * Provides debugging tools for Flight applications during development.
+ * Automatically disabled in production builds.
+ * 
+ * @example
+ * ```typescript
+ * // In your flight.config.ts or main entry
+ * import { enableDevTools } from '@flight-framework/devtools';
+ * 
+ * if (process.env.NODE_ENV === 'development') {
+ *     enableDevTools({
+ *         port: 3001,
+ *         showRoutes: true,
+ *         showRequests: true,
+ *         showCache: true,
+ *     });
+ * }
+ * ```
+ */
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface DevToolsOptions {
+    /** WebSocket port for DevTools communication (default: 3001) */
+    port?: number;
+    /** Show registered routes */
+    showRoutes?: boolean;
+    /** Show incoming requests */
+    showRequests?: boolean;
+    /** Show cache status */
+    showCache?: boolean;
+    /** Show connected adapters */
+    showAdapters?: boolean;
+    /** Custom panel position */
+    position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
+}
+
+export interface RouteInfo {
+    method: string;
+    path: string;
+    type: 'page' | 'api';
+    filePath: string;
+    slot?: string;
+    interceptInfo?: {
+        level: number;
+        target: string;
+    };
+}
+
+export interface RequestInfo {
+    id: string;
+    method: string;
+    path: string;
+    status: number;
+    duration: number;
+    timestamp: number;
+}
+
+export interface CacheInfo {
+    key: string;
+    size: number;
+    hits: number;
+    lastAccessed: number;
+}
+
+export interface AdapterInfo {
+    name: string;
+    type: 'db' | 'auth' | 'storage' | 'email' | 'payments' | 'realtime' | 'other';
+    status: 'connected' | 'disconnected' | 'error';
+}
+
+export interface DevToolsState {
+    routes: RouteInfo[];
+    requests: RequestInfo[];
+    cache: CacheInfo[];
+    adapters: AdapterInfo[];
+}
+
+// ============================================================================
+// DevTools Manager
+// ============================================================================
+
+let devToolsInstance: DevToolsManager | null = null;
+
+class DevToolsManager {
+    private options: Required<DevToolsOptions>;
+    private state: DevToolsState;
+    private subscribers: Set<(state: DevToolsState) => void>;
+    private isEnabled: boolean;
+
+    constructor(options: DevToolsOptions) {
+        this.options = {
+            port: options.port ?? 3001,
+            showRoutes: options.showRoutes ?? true,
+            showRequests: options.showRequests ?? true,
+            showCache: options.showCache ?? true,
+            showAdapters: options.showAdapters ?? true,
+            position: options.position ?? 'bottom-right',
+        };
+
+        this.state = {
+            routes: [],
+            requests: [],
+            cache: [],
+            adapters: [],
+        };
+
+        this.subscribers = new Set();
+        this.isEnabled = process.env.NODE_ENV === 'development';
+    }
+
+    /**
+     * Register routes for display in DevTools
+     */
+    registerRoutes(routes: RouteInfo[]): void {
+        if (!this.isEnabled) return;
+        this.state.routes = routes;
+        this.notify();
+    }
+
+    /**
+     * Log a request
+     */
+    logRequest(info: Omit<RequestInfo, 'id' | 'timestamp'>): void {
+        if (!this.isEnabled || !this.options.showRequests) return;
+
+        const request: RequestInfo = {
+            ...info,
+            id: crypto.randomUUID(),
+            timestamp: Date.now(),
+        };
+
+        // Keep last 100 requests
+        this.state.requests = [request, ...this.state.requests].slice(0, 100);
+        this.notify();
+    }
+
+    /**
+     * Update cache info
+     */
+    updateCache(cache: CacheInfo[]): void {
+        if (!this.isEnabled || !this.options.showCache) return;
+        this.state.cache = cache;
+        this.notify();
+    }
+
+    /**
+     * Register an adapter
+     */
+    registerAdapter(adapter: AdapterInfo): void {
+        if (!this.isEnabled || !this.options.showAdapters) return;
+
+        const existing = this.state.adapters.findIndex(a => a.name === adapter.name);
+        if (existing >= 0) {
+            this.state.adapters[existing] = adapter;
+        } else {
+            this.state.adapters.push(adapter);
+        }
+        this.notify();
+    }
+
+    /**
+     * Subscribe to state changes
+     */
+    subscribe(callback: (state: DevToolsState) => void): () => void {
+        this.subscribers.add(callback);
+        callback(this.state); // Initial state
+        return () => this.subscribers.delete(callback);
+    }
+
+    /**
+     * Get current state
+     */
+    getState(): DevToolsState {
+        return this.state;
+    }
+
+    /**
+     * Get options
+     */
+    getOptions(): Required<DevToolsOptions> {
+        return this.options;
+    }
+
+    private notify(): void {
+        for (const callback of this.subscribers) {
+            callback(this.state);
+        }
+    }
+}
+
+// ============================================================================
+// Public API
+// ============================================================================
+
+/**
+ * Enable DevTools for the application
+ */
+export function enableDevTools(options: DevToolsOptions = {}): DevToolsManager {
+    if (process.env.NODE_ENV !== 'development') {
+        console.warn('[Flight DevTools] DevTools are disabled in production');
+        return devToolsInstance as DevToolsManager;
+    }
+
+    if (!devToolsInstance) {
+        devToolsInstance = new DevToolsManager(options);
+        console.log(`[Flight DevTools] Enabled on port ${options.port ?? 3001}`);
+    }
+
+    return devToolsInstance;
+}
+
+/**
+ * Get the DevTools instance
+ */
+export function getDevTools(): DevToolsManager | null {
+    return devToolsInstance;
+}
+
+/**
+ * Check if DevTools are enabled
+ */
+export function isDevToolsEnabled(): boolean {
+    return devToolsInstance !== null && process.env.NODE_ENV === 'development';
+}
+
+// ============================================================================
+// Instrumentation Helpers
+// ============================================================================
+
+/**
+ * Middleware to log requests to DevTools
+ */
+export function devToolsMiddleware() {
+    return async (
+        context: { request: Request },
+        next: () => Promise<Response>
+    ): Promise<Response> => {
+        if (!devToolsInstance) return next();
+
+        const start = performance.now();
+        const { request } = context;
+
+        try {
+            const response = await next();
+            const duration = performance.now() - start;
+
+            devToolsInstance.logRequest({
+                method: request.method,
+                path: new URL(request.url).pathname,
+                status: response.status,
+                duration: Math.round(duration),
+            });
+
+            return response;
+        } catch (error) {
+            const duration = performance.now() - start;
+
+            devToolsInstance.logRequest({
+                method: request.method,
+                path: new URL(request.url).pathname,
+                status: 500,
+                duration: Math.round(duration),
+            });
+
+            throw error;
+        }
+    };
+}

package/src/instrumentation.ts

@@ -0,0 +1,146 @@
+/**
+ * @flight-framework/devtools/instrumentation - Auto-instrumentation
+ * 
+ * Automatically instruments Flight apps to send data to DevTools.
+ */
+
+import { getDevTools, type RouteInfo, type AdapterInfo } from './index.js';
+
+// ============================================================================
+// Route Instrumentation
+// ============================================================================
+
+/**
+ * Instrument file router to report routes to DevTools
+ */
+export function instrumentFileRouter(routes: unknown[]): void {
+    const devTools = getDevTools();
+    if (!devTools) return;
+
+    const routeInfos: RouteInfo[] = (routes as any[]).map(route => ({
+        method: route.method || 'GET',
+        path: route.path || '/',
+        type: route.type || 'page',
+        filePath: route.filePath || '',
+        slot: route.slot,
+        interceptInfo: route.interceptInfo,
+    }));
+
+    devTools.registerRoutes(routeInfos);
+}
+
+// ============================================================================
+// Adapter Instrumentation
+// ============================================================================
+
+/**
+ * Instrument an adapter to report to DevTools
+ */
+export function instrumentAdapter(
+    adapter: { name: string },
+    type: AdapterInfo['type']
+): void {
+    const devTools = getDevTools();
+    if (!devTools) return;
+
+    devTools.registerAdapter({
+        name: adapter.name,
+        type,
+        status: 'connected',
+    });
+}
+
+/**
+ * Report adapter error to DevTools
+ */
+export function reportAdapterError(adapterName: string): void {
+    const devTools = getDevTools();
+    if (!devTools) return;
+
+    const state = devTools.getState();
+    const adapter = state.adapters.find(a => a.name === adapterName);
+
+    if (adapter) {
+        devTools.registerAdapter({
+            ...adapter,
+            status: 'error',
+        });
+    }
+}
+
+// ============================================================================
+// Cache Instrumentation
+// ============================================================================
+
+/**
+ * Instrument a cache to report to DevTools
+ */
+export function instrumentCache(cache: Map<string, unknown>): void {
+    const devTools = getDevTools();
+    if (!devTools) return;
+
+    const cacheInfos = Array.from(cache.entries()).map(([key, value]) => ({
+        key,
+        size: JSON.stringify(value).length,
+        hits: 0,
+        lastAccessed: Date.now(),
+    }));
+
+    devTools.updateCache(cacheInfos);
+}
+
+// ============================================================================
+// Auto-Instrumentation
+// ============================================================================
+
+/**
+ * Auto-instrument common Flight patterns
+ * Call this once during app initialization
+ */
+export function autoInstrument(): void {
+    if (process.env.NODE_ENV !== 'development') return;
+
+    console.log('[Flight DevTools] Auto-instrumentation enabled');
+
+    // Instrument fetch for request logging
+    if (typeof globalThis.fetch !== 'undefined') {
+        const originalFetch = globalThis.fetch;
+
+        globalThis.fetch = async (input, init) => {
+            const devTools = getDevTools();
+            const start = performance.now();
+
+            try {
+                const response = await originalFetch(input, init);
+
+                if (devTools) {
+                    const url = typeof input === 'string'
+                        ? input
+                        : input instanceof URL
+                            ? input.pathname
+                            : (input as Request).url;
+
+                    devTools.logRequest({
+                        method: init?.method || 'GET',
+                        path: new URL(url, 'http://localhost').pathname,
+                        status: response.status,
+                        duration: Math.round(performance.now() - start),
+                    });
+                }
+
+                return response;
+            } catch (error) {
+                if (devTools) {
+                    const url = typeof input === 'string' ? input : (input as Request)?.url || '/';
+                    devTools.logRequest({
+                        method: init?.method || 'GET',
+                        path: new URL(url, 'http://localhost').pathname,
+                        status: 0,
+                        duration: Math.round(performance.now() - start),
+                    });
+                }
+                throw error;
+            }
+        };
+    }
+}

package/src/panel.ts

@@ -0,0 +1,288 @@
+/**
+ * @flight-framework/devtools/panel - DevTools Panel UI
+ * 
+ * React component for the DevTools floating panel.
+ * Automatically injected into pages during development.
+ */
+
+import { getDevTools, type DevToolsState, type RouteInfo, type RequestInfo } from './index.js';
+
+// ============================================================================
+// Panel Component (Plain JS for framework-agnostic use)
+// ============================================================================
+
+/**
+ * Inject the DevTools panel into the page
+ * Call this in your app's entry point during development
+ */
+export function injectDevToolsPanel(): void {
+    if (typeof document === 'undefined') return;
+
+    const devTools = getDevTools();
+    if (!devTools) return;
+
+    // Create container
+    const container = document.createElement('div');
+    container.id = 'flight-devtools';
+    document.body.appendChild(container);
+
+    // Inject styles
+    const styles = document.createElement('style');
+    styles.textContent = getDevToolsStyles();
+    document.head.appendChild(styles);
+
+    // Initial render
+    let isOpen = false;
+    let currentTab = 'routes';
+
+    function render(state: DevToolsState): void {
+        const options = devTools!.getOptions();
+
+        container.innerHTML = `
+            <div class="flight-devtools ${options.position} ${isOpen ? 'open' : ''}">
+                <button class="flight-devtools-toggle" onclick="window.__flightToggleDevTools()">
+                    ${isOpen ? 'X' : 'Flight'}
+                </button>
+                ${isOpen ? renderPanel(state, currentTab) : ''}
+            </div>
+        `;
+    }
+
+    function renderPanel(state: DevToolsState, tab: string): string {
+        return `
+            <div class="flight-devtools-panel">
+                <div class="flight-devtools-header">
+                    <span>Flight DevTools</span>
+                </div>
+                <div class="flight-devtools-tabs">
+                    <button class="${tab === 'routes' ? 'active' : ''}" onclick="window.__flightSetTab('routes')">
+                        Routes (${state.routes.length})
+                    </button>
+                    <button class="${tab === 'requests' ? 'active' : ''}" onclick="window.__flightSetTab('requests')">
+                        Requests (${state.requests.length})
+                    </button>
+                    <button class="${tab === 'adapters' ? 'active' : ''}" onclick="window.__flightSetTab('adapters')">
+                        Adapters (${state.adapters.length})
+                    </button>
+                </div>
+                <div class="flight-devtools-content">
+                    ${tab === 'routes' ? renderRoutes(state.routes) : ''}
+                    ${tab === 'requests' ? renderRequests(state.requests) : ''}
+                    ${tab === 'adapters' ? renderAdapters(state) : ''}
+                </div>
+            </div>
+        `;
+    }
+
+    function renderRoutes(routes: RouteInfo[]): string {
+        if (routes.length === 0) {
+            return '<div class="flight-devtools-empty">No routes registered</div>';
+        }
+
+        const dots = (level: number) => '.'.repeat(level);
+
+        return `
+            <div class="flight-devtools-list">
+                ${routes.map(route => `
+                    <div class="flight-devtools-item">
+                        <span class="method ${route.method.toLowerCase()}">${route.method}</span>
+                        <span class="path">${route.path}</span>
+                        <span class="type">${route.type}</span>
+                        ${route.slot ? `<span class="slot">@${route.slot}</span>` : ''}
+                        ${route.interceptInfo ? `<span class="intercept">(${dots(route.interceptInfo.level)})</span>` : ''}
+                    </div>
+                `).join('')}
+            </div>
+        `;
+    }
+
+    function renderRequests(requests: RequestInfo[]): string {
+        if (requests.length === 0) {
+            return '<div class="flight-devtools-empty">No requests yet</div>';
+        }
+
+        return `
+            <div class="flight-devtools-list">
+                ${requests.slice(0, 20).map(req => `
+                    <div class="flight-devtools-item">
+                        <span class="method ${req.method.toLowerCase()}">${req.method}</span>
+                        <span class="path">${req.path}</span>
+                        <span class="status status-${Math.floor(req.status / 100)}xx">${req.status}</span>
+                        <span class="duration">${req.duration}ms</span>
+                    </div>
+                `).join('')}
+            </div>
+        `;
+    }
+
+    function renderAdapters(state: DevToolsState): string {
+        if (state.adapters.length === 0) {
+            return '<div class="flight-devtools-empty">No adapters registered</div>';
+        }
+
+        return `
+            <div class="flight-devtools-list">
+                ${state.adapters.map(adapter => `
+                    <div class="flight-devtools-item">
+                        <span class="adapter-type">${adapter.type}</span>
+                        <span class="adapter-name">${adapter.name}</span>
+                        <span class="adapter-status status-${adapter.status}">${adapter.status}</span>
+                    </div>
+                `).join('')}
+            </div>
+        `;
+    }
+
+    // Global functions for onclick handlers
+    (window as any).__flightToggleDevTools = () => {
+        isOpen = !isOpen;
+        render(devTools!.getState());
+    };
+
+    (window as any).__flightSetTab = (tab: string) => {
+        currentTab = tab;
+        render(devTools!.getState());
+    };
+
+    // Subscribe to state changes
+    devTools.subscribe(render);
+}
+
+// ============================================================================
+// Styles
+// ============================================================================
+
+function getDevToolsStyles(): string {
+    return `
+        #flight-devtools {
+            font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
+            font-size: 12px;
+        }
+
+        .flight-devtools {
+            position: fixed;
+            z-index: 99999;
+        }
+
+        .flight-devtools.bottom-right {
+            bottom: 16px;
+            right: 16px;
+        }
+
+        .flight-devtools.bottom-left {
+            bottom: 16px;
+            left: 16px;
+        }
+
+        .flight-devtools-toggle {
+            width: 48px;
+            height: 48px;
+            border-radius: 50%;
+            border: none;
+            background: #32CD32;
+            color: white;
+            font-weight: bold;
+            cursor: pointer;
+            box-shadow: 0 4px 12px rgba(0,0,0,0.3);
+        }
+
+        .flight-devtools.open .flight-devtools-toggle {
+            border-radius: 50%;
+            position: absolute;
+            top: 8px;
+            right: 8px;
+            width: 32px;
+            height: 32px;
+            font-size: 14px;
+        }
+
+        .flight-devtools-panel {
+            position: absolute;
+            bottom: 60px;
+            right: 0;
+            width: 400px;
+            max-height: 500px;
+            background: #1a1a1a;
+            border-radius: 12px;
+            overflow: hidden;
+            box-shadow: 0 8px 32px rgba(0,0,0,0.4);
+        }
+
+        .flight-devtools-header {
+            padding: 12px 16px;
+            background: #32CD32;
+            color: white;
+            font-weight: 600;
+        }
+
+        .flight-devtools-tabs {
+            display: flex;
+            border-bottom: 1px solid #333;
+        }
+
+        .flight-devtools-tabs button {
+            flex: 1;
+            padding: 8px;
+            border: none;
+            background: transparent;
+            color: #888;
+            cursor: pointer;
+        }
+
+        .flight-devtools-tabs button.active {
+            color: #32CD32;
+            border-bottom: 2px solid #32CD32;
+        }
+
+        .flight-devtools-content {
+            max-height: 350px;
+            overflow-y: auto;
+        }
+
+        .flight-devtools-list {
+            padding: 8px;
+        }
+
+        .flight-devtools-item {
+            display: flex;
+            gap: 8px;
+            padding: 8px;
+            border-radius: 4px;
+            color: #ccc;
+        }
+
+        .flight-devtools-item:hover {
+            background: #252525;
+        }
+
+        .flight-devtools-item .method {
+            width: 50px;
+            font-weight: 600;
+        }
+
+        .flight-devtools-item .method.get { color: #4CAF50; }
+        .flight-devtools-item .method.post { color: #2196F3; }
+        .flight-devtools-item .method.put { color: #FF9800; }
+        .flight-devtools-item .method.delete { color: #f44336; }
+
+        .flight-devtools-item .path {
+            flex: 1;
+            font-family: monospace;
+        }
+
+        .flight-devtools-item .status-2xx { color: #4CAF50; }
+        .flight-devtools-item .status-3xx { color: #FF9800; }
+        .flight-devtools-item .status-4xx { color: #f44336; }
+        .flight-devtools-item .status-5xx { color: #9C27B0; }
+
+        .flight-devtools-item .duration {
+            color: #888;
+        }
+
+        .flight-devtools-empty {
+            padding: 32px;
+            text-align: center;
+            color: #666;
+        }
+    `;
+}

package/tsconfig.json

@@ -0,0 +1,17 @@
+{
+    "extends": "../../tsconfig.json",
+    "compilerOptions": {
+        "outDir": "./dist",
+        "rootDir": "./src",
+        "declaration": true,
+        "declarationMap": true,
+        "jsx": "react-jsx"
+    },
+    "include": [
+        "src/**/*"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}