@superdangerous/app-framework 4.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 SuperDangerous
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,652 @@
+# SuperDangerous App Framework
+
+A comprehensive, production-ready framework for building enterprise internal tools and applications with TypeScript, React, and real-time capabilities.
+
+## 📋 Documentation
+
+### Core Guides
+
+- **[API](./docs/API.md)** - Complete API documentation with best practices
+- **[Development](./docs/DEVELOPMENT.md)** - How to build applications with the framework
+- **[Architecture](./docs/ARCHITECTURE.md)** - System design and structure
+
+### Features
+
+- **[WebSocket](./docs/WEBSOCKET.md)** - Real-time communication implementation
+- **[Desktop](./docs/DESKTOP.md)** - Desktop application support with Tauri
+- **[Bundling](./docs/BUNDLING.md)** - Desktop bundling guide
+- **[AI](./docs/AI.md)** - AI service integration
+- **[Patterns](./docs/PATTERNS.md)** - Proven architectural patterns
+
+### Configuration & Testing
+
+- **[Testing](./docs/TESTING.md)** - Testing guidelines and patterns
+- **[Logging](./docs/LOGGING.md)** - Logging system documentation
+- **[Theme](./docs/THEME.md)** - Theme system and customization
+- **[Ports](./docs/PORTS.md)** - Port configuration standards
+- **[CORS](./docs/CORS.md)** - Dynamic CORS middleware
+
+#### Test Suite Overview
+
+The framework includes extensive test coverage:
+
+- **Unit Tests**: 362+ tests covering all core modules
+- **Integration Tests**: API and service integration testing
+- **TestServer**: Built-in test server for application testing
+- **Mock Services**: Comprehensive mocking utilities
+
+#### Running Tests
+
+```bash
+# Run all tests
+npm test
+
+# Run with coverage
+npm run test:coverage
+
+# Run specific suites
+npm run test:unit
+npm run test:integration
+
+# Type checking
+npm run typecheck
+```
+
+#### Test Infrastructure
+
+- Jest with TypeScript support
+- Built-in TestServer class for app testing
+- Mock implementations for all services
+- Async operation handling
+- Port management utilities
+
+## 🚀 Quick Start
+
+```bash
+# Install framework
+npm install @superdangerous/app-framework
+
+# Create your app
+mkdir my-app && cd my-app
+npm init -y
+npm install @superdangerous/app-framework
+```
+
+### Minimal Application
+
+```typescript
+import { StandardServer } from "@superdangerous/app-framework";
+
+const server = new StandardServer({
+  appName: "My App",
+  appVersion: "1.0.0",
+  port: 8080,
+  enableWebSocket: true,
+  onInitialize: async (app) => {
+    app.get("/health", (req, res) => res.json({ status: "ok" }));
+  },
+});
+
+await server.initialize();
+await server.start();
+```
+
+## ✨ Core Features
+
+### 🖥️ Server Management
+
+- **StandardServer** - Simplified server setup with Express
+- **Request Correlation** - Automatic request IDs with structured request logging
+- **Safer Defaults** - Request body limits, trust proxy, and sane HTTP timeouts
+- **Port Management** - Automatic port conflict resolution
+- **Graceful Shutdown** - Clean resource cleanup
+- **Health Checks** - Real system metrics (CPU, memory, disk) - informational only
+- **Startup Banner** - Professional application startup display
+
+### 📝 Logging System
+
+- **Dual Logger System** - Simple console + production file logging
+- **Enhanced Logger** - File rotation, compression, archiving
+- **Category-based Logging** - Organize logs by service/module
+- **Log Management** - Statistics, cleanup, migration utilities
+- **Flat Structure** - All logs in `/data/logs` for easy backup/restore
+
+### 🔌 Real-Time Communication
+
+- **WebSocketManager** - Unified Socket.IO management with namespace support
+- **Redis Adapter** - Optional Redis adapter for scaling
+- **Room Management** - Built-in room join/leave handlers
+- **Client Tracking** - Track connected clients across namespaces
+- **Broadcast Options** - Selective broadcasting with compression/volatile options
+- **React Hooks** - `useSocketIO`, `useConnectionStatus`
+- **Connection Status** - Monitor connection health
+
+### 🔒 Security & Authentication
+
+- **Session Management** - Express sessions with Redis support
+- **Authentication Middleware** - Role-based access control
+- **Input Validation** - Zod/Joi schema validation
+- **File Security** - Safe file operations with validation
+- **CORS Configuration** - Cross-origin resource sharing
+
+### ⚙️ Configuration & Settings
+
+- **Settings Service** - Dynamic settings with UI generation
+- **Environment Merging** Automatic env variable merging
+- **File Watching** Auto-reload on config file changes
+- **Change Events** EventEmitter for config change tracking
+- **Common Schemas** Pre-built Zod schemas for common configs
+
+### 📊 Health Monitoring
+
+- **HealthCheckService** Real system metrics collection
+- **CPU Metrics** Real CPU usage with history tracking
+- **Memory Metrics** Memory usage percentage and details
+- **Disk Metrics** Disk space monitoring (platform-aware)
+- **Process Metrics** Node.js process statistics
+- **Custom Health Checks** Extensible health check framework
+- **Dependency Checks** Monitor external service health
+- **Informational Only** Never interrupts service operation
+
+### 🔧 Services & Utilities
+
+- **Queue Service** - Background job processing with persistence
+- **AI Service** - Multi-provider AI integration (OpenAI, Claude)
+- **Port Utilities** - Port availability checking and management
+- **File Handler** - Secure file operations with MIME validation
+- **Network Service** - Network interface discovery
+- **System Monitor** - System resource monitoring
+
+### 🎨 UI Components Library
+
+#### Base Components (20+)
+
+- **Forms** - Input, Select, Checkbox, Radio, Switch, Textarea
+- **Layout** - Card, Dialog, Tabs, Accordion, Separator
+- **Data Display** - Table, Badge, Alert, Progress, Avatar
+- **Navigation** - Button, Dropdown, Context Menu, Navigation Menu
+- **Feedback** - Toast, Tooltip, Popover, Alert Dialog
+
+#### Advanced Components
+
+- **SettingsFramework** - Complete settings UI with validation
+- **LogViewer** - Real-time log display with filtering, stack coalescing, ANSI stripping, auto-refresh, archives, and per-level badges
+- **ConnectionStatus** - WebSocket connection monitoring
+- **AppLayout** - Standard application layout with navigation
+- **RealtimeDataTable** - Live updating data tables
+- **DashboardStats** - Metric display cards
+- **UpdateNotification** - Application update notifications
+
+> UI bundle note: the UI package bundles ESM-heavy dependencies (`react-markdown`, `remark-gfm`, `react-syntax-highlighter`) for better Jest/Node compatibility. The LogViewer is now single-source and virtualized; legacy variants have been removed.
+
+### 🧪 Testing Utilities
+
+- **TestServer** - Standardized test server for integration tests
+- **Test Utilities** - Request helpers, WebSocket testing
+- **Mock Services** - Pre-configured mocks for services
+
+### 📊 Middleware
+
+- **Validation** - Request/response validation
+- **Error Handling** - Centralized error management
+- **File Upload** - Secure file upload handling
+- **OpenAPI** - Automatic API documentation
+- **Health Checks** - Liveness/readiness probes
+- **Rate Limiting** - API rate limiting
+
+## 📦 Installation
+
+### Full Framework (Backend + Frontend)
+
+```bash
+npm install @superdangerous/app-framework
+```
+
+### Import Examples
+
+```javascript
+// Backend
+import { StandardServer, createLogger } from "@superdangerous/app-framework";
+
+// Frontend UI components
+import {
+  Button,
+  Card,
+  useSocketIO,
+  useConnectionStatus,
+} from "@superdangerous/app-framework/ui";
+```
+
+````
+
+## 💡 Usage Examples
+
+### REST API with Database
+
+```typescript
+import { StandardServer, validate, createLogger } from '@superdangerous/app-framework';
+import { z } from 'zod';
+
+const logger = createLogger('API');
+
+const server = new StandardServer({
+  appName: 'REST API',
+  appVersion: '1.0.0',
+  onInitialize: async (app) => {
+    // Validation middleware
+    const userSchema = z.object({
+      name: z.string(),
+      email: z.string().email()
+    });
+
+    app.post('/api/users', validate(userSchema), async (req, res) => {
+      // Validated request body
+      const user = await createUser(req.body);
+      res.json({ success: true, data: user });
+    });
+  }
+});
+````
+
+### Real-Time Dashboard
+
+```typescript
+import { StandardServer, getWebSocketServer } from "@superdangerous/app-framework";
+
+const server = new StandardServer({
+  appName: "Dashboard",
+  appVersion: "1.0.0",
+  enableWebSocket: true,
+  onStart: async () => {
+    const ws = getWebSocketServer();
+
+    // Stream metrics every second
+    setInterval(() => {
+      const metrics = collectMetrics();
+      ws.broadcast("metrics:update", metrics);
+    }, 1000);
+  },
+});
+```
+
+### React WebSocket Integration
+
+```tsx
+import { useSocketIO, useConnectionStatus } from "@superdangerous/app-framework/ui";
+
+function Dashboard() {
+  const [state, actions] = useSocketIO();
+  const { connected } = useConnectionStatus();
+  const [metrics, setMetrics] = useState([]);
+
+  useEffect(() => {
+    if (!connected) return;
+    const handler = (data) => setMetrics(data);
+    actions.on("metrics:update", handler);
+    return () => actions.off("metrics:update", handler);
+  }, [connected, actions]);
+
+  return <MetricsDisplay data={metrics} />;
+}
+```
+
+### Background Job Processing
+
+```typescript
+import { QueueService } from "@superdangerous/app-framework";
+
+const queue = new QueueService({
+  concurrent: 5,
+  persistent: true,
+});
+
+queue.registerHandler("send-email", async (job) => {
+  await sendEmail(job.data);
+});
+
+await queue.addJob("send-email", {
+  to: "user@example.com",
+  subject: "Welcome!",
+});
+```
+
+### Settings Management
+
+```typescript
+import { SettingsService } from '@superdangerous/app-framework';
+
+const settings = new SettingsService();
+
+settings.registerCategory({
+  id: 'general',
+  label: 'General Settings',
+  settings: [{
+    key: 'app.theme',
+    label: 'Theme',
+    type: 'select',
+    options: ['light', 'dark', 'auto'],
+    defaultValue: 'auto'
+  }]
+});
+
+// React component
+<SettingsFramework
+  categories={settings.getUISchema()}
+  onSave={async (values) => settings.update(values)}
+/>
+```
+
+### Health Monitoring
+
+```typescript
+import {
+  createHealthCheckRouter,
+  getHealthCheckService,
+} from "@superdangerous/app-framework";
+
+// Add health check endpoints
+const healthRouter = createHealthCheckRouter({
+  version: "1.0.0",
+  customChecks: [
+    {
+      name: "database",
+      check: async () => ({
+        name: "database",
+        status: (await db.ping()) ? "healthy" : "unhealthy",
+      }),
+    },
+  ],
+});
+
+app.use("/api", healthRouter);
+
+// Get real-time metrics
+const healthService = getHealthCheckService();
+const metrics = await healthService.getMetrics();
+console.log(
+  `CPU: ${metrics.cpu.usage}%, Memory: ${metrics.memory.percentage}%`,
+);
+```
+
+### Settings Management
+
+```typescript
+import {
+  SettingsService,
+  CommonSettingsCategories,
+} from "@superdangerous/app-framework";
+
+// Initialize settings service
+const settings = new SettingsService({
+  filePath: "./settings.json",
+  categories: CommonSettingsCategories,
+  onSettingChange: async (key, value) => {
+    console.log(`Setting ${key} changed to ${value}`);
+  },
+});
+
+await settings.initialize();
+
+// Get setting value
+const port = await settings.get("server.port");
+
+// Update setting
+await settings.set("server.port", 8080);
+```
+
+### WebSocket Manager
+
+```typescript
+import { getWebSocketManager } from "@superdangerous/app-framework";
+
+// Initialize WebSocket manager
+const wsManager = getWebSocketManager({
+  cors: { origin: "http://localhost:3000" },
+  adapter: "redis", // Optional Redis scaling
+  redisUrl: process.env.REDIS_URL,
+});
+
+await wsManager.initialize(httpServer);
+
+// Register namespace with handlers
+wsManager.registerNamespace("/dashboard", {
+  subscribe: (socket, topic) => {
+    socket.join(`topic:${topic}`);
+    socket.emit("subscribed", { topic });
+  },
+  unsubscribe: (socket, topic) => {
+    socket.leave(`topic:${topic}`);
+  },
+});
+
+// Broadcast to specific rooms
+wsManager.broadcast("update", data, {
+  namespace: "/dashboard",
+  room: "topic:metrics",
+  compress: true,
+});
+
+// Get connection stats
+const stats = wsManager.getStats();
+console.log(`Connected clients: ${stats.totalClients}`);
+```
+
+## 🏗️ Architecture
+
+```
+Framework Structure:
+├── Core Layer
+│   ├── StandardServer      # Server management
+│   ├── Logger System       # Logging infrastructure
+│   ├── Port Utilities      # Port management
+│   └── File Handler        # Secure file operations
+├── Service Layer
+│   ├── WebSocket Server    # Real-time communication
+│   ├── Configuration       # Config management
+│   ├── Queue Service       # Job processing
+│   ├── AI Service          # AI integration
+│   └── Settings Service    # Settings management
+├── Middleware Layer
+│   ├── Authentication      # Auth & sessions
+│   ├── Validation         # Input validation
+│   ├── Error Handling     # Error management
+│   └── Health Checks      # Health monitoring
+└── UI Layer
+    ├── Base Components    # Core UI elements
+    ├── Advanced Components # Complex UI patterns
+    ├── Hooks              # React hooks
+    └── Utilities          # UI helpers
+```
+
+## 🔧 Configuration
+
+### Environment Variables
+
+```bash
+# Server
+NODE_ENV=production
+PORT=8080
+HOST=0.0.0.0
+
+# Logging
+LOG_LEVEL=info
+LOG_DIR=./logs
+
+# Session
+SESSION_SECRET=your-secret-key
+
+# Database
+DATABASE_URL=postgresql://...
+
+# Redis
+REDIS_HOST=localhost
+REDIS_PORT=6379
+
+# AI Services (optional)
+OPENAI_API_KEY=sk-...
+CLAUDE_API_KEY=sk-ant-...
+
+# WebSocket
+WS_PING_INTERVAL=25000
+WS_PING_TIMEOUT=60000
+```
+
+### Configuration Files
+
+```json
+// data/config/app.json
+{
+  "server": {
+    "port": 8080,
+    "cors": {
+      "origins": ["http://localhost:3000"]
+    }
+  },
+  "features": {
+    "enableWebSocket": true,
+    "enableMetrics": true
+  }
+}
+```
+
+## 📚 TypeScript Support
+
+Full TypeScript support with comprehensive type definitions:
+
+```typescript
+import type {
+  StandardServerConfig,
+  Logger,
+  WebSocketClient,
+  JobStatus,
+  SettingType,
+  ApiResponse,
+  ValidationSchema,
+} from "@superdangerous/app-framework";
+
+import type {
+  ButtonProps,
+  TableColumn,
+  SettingCategory,
+  WebSocketHook,
+} from "@superdangerous/app-framework/ui";
+```
+
+## 🧪 Testing
+
+```typescript
+import { TestServer, setupTestServer } from "@superdangerous/app-framework";
+
+describe("API Tests", () => {
+  let server: TestServer;
+
+  beforeAll(async () => {
+    server = await setupTestServer({
+      setupApp: (app) => {
+        app.get("/test", (req, res) => res.json({ ok: true }));
+      },
+    });
+  });
+
+  test("endpoint works", async () => {
+    const res = await server.request("/test");
+    expect(res.body.ok).toBe(true);
+  });
+});
+```
+
+## 🚀 Production Deployment
+
+### Docker
+
+```dockerfile
+FROM node:18-alpine
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci --only=production
+COPY dist/ ./dist/
+ENV NODE_ENV=production
+HEALTHCHECK CMD curl -f http://localhost:8080/health || exit 1
+CMD ["node", "dist/index.js"]
+```
+
+### PM2
+
+```javascript
+module.exports = {
+  apps: [
+    {
+      name: "my-app",
+      script: "./dist/index.js",
+      instances: "max",
+      exec_mode: "cluster",
+      env: {
+        NODE_ENV: "production",
+      },
+    },
+  ],
+};
+```
+
+## 🛠️ Development Tools
+
+- **Hot Reload** - Automatic restart on changes
+- **TypeScript** - Full type safety
+- **ESLint** - Code quality enforcement
+- **Prettier** - Code formatting
+- **Jest** - Testing framework
+- **Nodemon** - Development server
+
+## 📖 For AI Assistants
+
+This framework is designed to be AI-friendly. When building applications:
+
+1. **Always use StandardServer** - Never use deprecated StartupOrchestrator
+2. **Validate all inputs** - Use zod schemas for validation
+3. **Handle errors properly** - Use try-catch and error middleware
+4. **Use TypeScript** - Define interfaces for all data structures
+5. **Follow the patterns** - See [Development Guide](./docs/DEVELOPMENT.md)
+
+## 🔒 Security
+
+- Input validation on all endpoints
+- Secure session management
+- File upload restrictions
+- Rate limiting support
+- CORS configuration
+- Environment variable secrets
+
+## 🛠️ Development Tools
+
+### Node Process Monitor
+
+Monitor and manage all your running framework apps from the macOS menu bar.
+
+- **Real-time monitoring** of all processes started with `dev-server`
+- **Grouped by app** with hierarchical view of backend/frontend/websocket processes
+- **Resource tracking** - CPU, memory, uptime for each process
+- **Easy management** - Kill individual processes or entire apps
+- **Lightweight** - Built in Rust for minimal overhead
+
+#### Installation
+
+```bash
+# Quick install (macOS)
+curl -sSL https://raw.githubusercontent.com/EPISENSOR/epi-node-process-monitor/main/install.sh | bash
+```
+
+Learn more: [github.com/SuperDangerous/epi-node-process-monitor](https://github.com/SuperDangerous/epi-node-process-monitor)
+
+## 📄 License
+
+MIT License - see [LICENSE](./LICENSE) for details
+
+## 🤝 Support
+
+- **Documentation**: See `/docs` folder for all guides
+- **Issues**: Internal issue tracker
+- **Examples**: Check example applications using this framework
+
+---
+
+Built with ❤️ by SuperDangerous

package/dist/api/logsRouter.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Standardized Logging API Router
+ * Provides consistent logging endpoints for all SuperDangerous applications
+ */
+declare const router: import("express-serve-static-core").Router;
+export interface LogEntry {
+    timestamp: string;
+    level: string;
+    message: string;
+    source?: string;
+    metadata?: any;
+}
+export interface LogFile {
+    name: string;
+    size: number;
+    modified: string;
+    path?: string;
+}
+export default router;
+//# sourceMappingURL=logsRouter.d.ts.map

package/dist/api/logsRouter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logsRouter.d.ts","sourceRoot":"","sources":["../../src/api/logsRouter.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAQH,QAAA,MAAM,MAAM,4CAAmB,CAAC;AAEhC,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AA6jBD,eAAe,MAAM,CAAC"}