@l10nmonster/server 3.0.0-alpha.1 → 3.0.0-alpha.11

package/README.md

@@ -2,6 +2,19 @@
 
 L10n Monster Manager UI - Web-based interface for managing localization projects and translation workflows.
 
+## How It Works
+
+The L10n Monster server is implemented as an **action** in the L10n Monster CLI. When you run `l10n serve --ui`, it:
+
+1. **Starts an Express server** that connects to the current L10n Monster project
+2. **Serves real-time data** from your project's translation memory and source files
+3. **Optionally serves the web UI** (when `--ui` flag is used) from pre-built static files
+
+### Important: This is NOT a standalone server
+- The server must be run from within a L10n Monster project directory (where `l10nmonster.config.mjs` exists)
+- It accesses the project's MonsterManager instance (`mm`) to fetch real translation data
+- The API endpoints return actual project data, not mock data
+
 ## Installation
 
 ```bash
@@ -10,76 +23,128 @@ npm install @l10nmonster/server
 
 ## Usage
 
-Start the server with API only:
+### From within a L10n Monster project:
 
 ```bash
-l10n serve --port 9691
+# Navigate to your l10nmonster project directory
+cd samples/CardboardSDK/l10nmonster
+
+# Start the server with API only
+npx l10n serve --port 9691
+
+# Start the server with web UI
+npx l10n serve --port 9691 --ui
 ```
 
-Start the server with web UI:
+## Building the UI
+
+The UI must be built before it can be served:
 
 ```bash
-l10n serve --port 9691 --ui
+cd server
+npm install
+npm run build
 ```
 
+This creates the `ui/dist` directory with the built static files.
+
 ## Features
 
 ### Web UI
 
 Modern React-based interface built with:
-- **Material-UI**: Professional design system
+- **Chakra UI 3.0**: Modern component library with excellent performance
+- **React 19**: Latest React with improved performance
+- **TypeScript**: Type-safe development
 - **React Router**: Client-side routing
 - **Vite**: Fast development and build tooling
 - **Responsive Design**: Works on desktop and mobile
 
 ### API Endpoints
 
-- `GET /api/status` - Translation status and project overview
-- `GET /api/untranslated/:sourceLang/:targetLang` - Untranslated content for language pairs
-- `GET /api/tm/stats/:sourceLang/:targetLang` - Translation memory statistics
+All endpoints return **real project data** from the MonsterManager instance:
+
+- `GET /api/status` - Real-time translation status from `mm.getTranslationStatus()`
+- `GET /api/untranslated/:sourceLang/:targetLang` - Actual untranslated content (currently using mock data, needs implementation)
+- `GET /api/tm/stats/:sourceLang/:targetLang` - Translation memory statistics (currently using mock data, needs implementation)
 
 ### Pages
 
-- **Home**: Project overview and status dashboard
+- **Home**: Project overview with real translation status
 - **Untranslated**: Browse untranslated content by language pair
-- **Translation Memory**: View and manage translation memory statistics
+- **Translation Memory**: View translation memory statistics
 - **404**: Error handling for unknown routes
 
 ## Development
 
-### Start Development Server
+### Prerequisites
 
+1. Build the UI first:
 ```bash
-npm run dev
+cd server
+npm install
+npm run build
 ```
 
+2. Run from a L10n Monster project:
+```bash
+cd your-project/l10nmonster
+npx l10n serve --ui
+```
+
+### Development Mode
+
+For UI development with hot reload:
+
+```bash
+cd server
+npm run dev  # Runs Vite dev server on port 5173
+```
+
+Note: In development mode, the Vite dev server proxies API calls to `http://localhost:9691`, so you need the L10n Monster server running.
+
 ### Build for Production
 
 ```bash
+cd server
 npm run build
 ```
 
-### Preview Production Build
+### Run Tests
 
 ```bash
-npm run preview
+# Frontend tests
+npm run test
+
+# Server tests  
+npm run test:server
+
+# Test coverage
+npm run test:coverage
 ```
 
 ## Configuration
 
 The server supports:
-- **Custom Port**: Specify listening port with `--port` option
+- **Custom Port**: Specify listening port with `--port` option (default: 9691)
 - **UI Toggle**: Enable/disable web interface with `--ui` flag
 - **CORS**: Cross-Origin Resource Sharing enabled for API access
-- **Static Serving**: Production-ready static file serving
+- **Static Serving**: Production-ready static file serving from `ui/dist`
 
 ## Architecture
 
-- **Express.js**: Backend API server
+### Backend (index.js)
+- Implemented as a L10n Monster action class
+- Receives MonsterManager instance (`mm`) with access to project data
+- Express.js server with API routes
+- Serves static UI files when `--ui` flag is used
+
+### Frontend (ui/)
 - **React 19**: Modern frontend framework
-- **Material-UI v7**: Component library and theming
+- **Chakra UI 3.0**: High-performance component library
+- **TypeScript**: Type safety throughout
+- **Vite**: Build tool and development server
 - **Client-Side Routing**: Single-page application with React Router
-- **Mock Data**: Development-friendly mock data system
 
 ## Dependencies
 
@@ -89,13 +154,15 @@ The server supports:
 - `open`: Automatic browser launching
 
 ### Frontend
-- `react` & `react-dom`: Core React libraries
-- `@mui/material` & `@mui/icons-material`: Material Design components
-- `@emotion/react` & `@emotion/styled`: CSS-in-JS styling
+- `react` & `react-dom`: Core React libraries (v19)
+- `@chakra-ui/react`: Chakra UI 3.0 components
+- `lucide-react`: Modern icon library
 - `react-router-dom`: Client-side routing
+- `typescript`: Type-safe development
 
 ### Development
 - `vite`: Build tool and development server
 - `@vitejs/plugin-react`: React integration for Vite
 - `vitest`: Testing framework
-- `@testing-library/*`: React testing utilities
+- `@testing-library/*`: React testing utilities
+- `eslint` & `prettier`: Code quality tools

package/index.js

@@ -2,19 +2,31 @@ import express from 'express';
 import cors from 'cors';
 import path from 'path';
 import open from 'open';
-import * as mockData from './mockData.js'; // Import named exports, add .js extension
+import os from 'os';
+import { readFileSync } from 'fs';
+import { setupInfoRoute } from './routes/info.js';
+import { setupStatusRoute } from './routes/status.js';
+import { setupActiveContentStatsRoute } from './routes/sources.js';
+import { setupTmRoutes } from './routes/tm.js';
+import { setupProviderRoute } from './routes/providers.js';
+import { setupDispatcherRoutes } from './routes/dispatcher.js';
+
+const serverPackage = JSON.parse(readFileSync(path.join(import.meta.dirname, 'package.json'), 'utf-8'));
 
 export default class serve {
     static help = {
         description: 'starts the L10n Monster server.',
         options: [
-            [ '--port <number>', 'listen to specified port' ],
+            [ '--host <address>', 'hostname/IP to bind to and open in browser (default: all interfaces)' ],
+            [ '--port <number>', 'listen to specified port (default: 9691)' ],
             [ '--ui', 'also serve a web frontend' ],
+            [ '--open', 'open browser with web frontend' ],
         ]
     };
 
     static async action(mm, options) {
         const port = options.port ?? 9691;
+        const host = options.host; // undefined means listen on all interfaces
         const app = express();
 
         // === Middleware ===
@@ -23,47 +35,113 @@ export default class serve {
 
         // === API Routes ===
         const apiRouter = express.Router();
-
-        // GET /api/status
-        apiRouter.get('/status', async (req, res) => {
-            try {
-                const status = await mm.getTranslationStatus()
-                res.json(status);
-            } catch (error) {
-                console.error('Error fetching status: ', error);
-                res.status(500).json({ message: 'Problems fetching status data' });
-            }
-        });
-
-        // GET /api/untranslated/:sourceLang/:targetLang
-        apiRouter.get('/untranslated/:sourceLang/:targetLang', (req, res) => {
-            const { sourceLang, targetLang } = req.params;
-            const pairKey = `${sourceLang}_${targetLang}`;
-            const content = mockData.untranslatedContent[pairKey] || [];
-            res.json(content);
-        });
-
-        // GET /api/tm/stats/:sourceLang/:targetLang
-        apiRouter.get('/tm/stats/:sourceLang/:targetLang', (req, res) => {
-            const { sourceLang, targetLang } = req.params;
-            const pairKey = `${sourceLang}_${targetLang}`;
-            const tmInfo = mockData.tmData[pairKey] || { summary: { totalUnits: 0, lastUpdated: 'N/A' }, units: [] };
-            res.json(tmInfo);
-        });
+    
+        // Setup routes from separate files
+        setupInfoRoute(apiRouter, mm, serverPackage);
+        setupStatusRoute(apiRouter, mm);
+        setupActiveContentStatsRoute(apiRouter, mm);
+        setupTmRoutes(apiRouter, mm);
+        setupProviderRoute(apiRouter, mm);
+        setupDispatcherRoutes(apiRouter, mm);
 
         // Mount the API router under the /api prefix
         app.use('/api', apiRouter);
 
-        if (options.ui) {
+        // API 404 handler - must come before the UI catch-all
+        app.use('/api/*splat', (req, res) => {
+            res.status(404).json({
+                error: 'API endpoint not found',
+                path: req.path,
+                method: req.method
+            });
+        });
+
+        if (options.ui || options.open) {
             const uiDistPath = path.join(import.meta.dirname, 'ui', 'dist');
             app.use(express.static(uiDistPath)); // rest of dist files
             app.get('/*splat', (req, res) => res.sendFile(path.join(uiDistPath, 'index.html'))); // fallback for Client-Side Routing
         }
 
         // === Start Server ===
-        app.listen(port, async () => {
-            console.log(`🚀 L10n Monster Server listening on port ${port}`);
-            options.ui && await open(`http://localhost:${port}`);
+        const listenArgs = [port];
+        if (host) {
+            listenArgs.push(host);
+        }
+        
+        const server = app.listen(...listenArgs, async () => {
+            const address = server.address();
+            
+            console.log(`🚀 L10n Monster Server v${serverPackage.version} started\n`);
+            
+            // Handle Unix domain sockets (string) vs TCP sockets (AddressInfo)
+            if (typeof address === 'string') {
+                console.log('  Listening on Unix socket:');
+                console.log(`  - ${address}`);
+                
+                if (options.open && options.ui) {
+                    console.log('\n  ⚠️  Cannot open browser for Unix domain socket. Please access the server manually.');
+                }
+            } else {
+                const boundPort = address.port;
+                const boundAddress = address.address;
+                
+                console.log('  Available at:');
+                
+                // Determine what URLs to show and what to open
+                let openHost = host || 'localhost'; // Default to localhost for opening
+                
+                // If listening on all interfaces (0.0.0.0 or ::)
+                if (!host || boundAddress === '0.0.0.0' || boundAddress === '::') {
+                    // Show localhost first
+                    console.log(`  - http://localhost:${boundPort}`);
+                    console.log(`  - http://127.0.0.1:${boundPort}`);
+                    
+                    // Get all network interfaces
+                    const interfaces = os.networkInterfaces();
+                    for (const [name, addresses] of Object.entries(interfaces)) {
+                        for (const addr of addresses) {
+                            // Skip internal interfaces and IPv6 link-local addresses
+                            if (!addr.internal && addr.family === 'IPv4') {
+                                console.log(`  - http://${addr.address}:${boundPort} (${name})`);
+                            }
+                        }
+                    }
+                } else {
+                    // Specific address was bound
+                    openHost = boundAddress; // Use the bound address for opening
+                    console.log(`  - http://${boundAddress}:${boundPort}`);
+                    
+                    // Also show localhost if we bound to 127.0.0.1
+                    if (boundAddress === '127.0.0.1') {
+                        console.log(`  - http://localhost:${boundPort}`);
+                    }
+                }
+                
+                if (options.open) {
+                    const openUrl = `http://${openHost}:${boundPort}`;
+                    console.log('');
+                    console.log(`  Opening browser at: ${openUrl}`);
+                    await open(openUrl);
+                }
+            }
+            console.log('');
         });
+
+        // Handle server binding errors
+        server.on('error', (error) => {
+            if (error.code === 'EADDRINUSE') {
+                const addressStr = host ? `${host}:${port}` : `port ${port}`;
+                throw new Error(`Failed to bind server: Address ${addressStr} is already in use`);
+            } else if (error.code === 'EACCES') {
+                const addressStr = host ? `${host}:${port}` : `port ${port}`;
+                throw new Error(`Failed to bind server: Permission denied for ${addressStr}`);
+            } else if (error.code === 'EADDRNOTAVAIL') {
+                throw new Error(`Failed to bind server: Address ${host} is not available on this system`);
+            } else {
+                throw new Error(`Failed to bind server: ${error.message}`);
+            }
+        });
+
+        return server;
     }
 }

package/package.json

@@ -1,22 +1,22 @@
 {
     "name": "@l10nmonster/server",
-    "version": "3.0.0-alpha.1",
-    "description": "L10n Monster Manager UI",
+    "version": "3.0.0-alpha.11",
+    "description": "L10n Monster Manager",
     "type": "module",
     "main": "index.js",
     "dependencies": {
+        "@chakra-ui/react": "^3.2.0",
         "@emotion/react": "^11.14.0",
-        "@emotion/styled": "^11.14.0",
-        "@mui/icons-material": "^7.0.2",
-        "@mui/material": "^7.0.2",
-        "@testing-library/dom": "^10.4.0",
-        "@testing-library/user-event": "^14",
+        "@tanstack/react-query": "^5.85.5",
         "cors": "^2.8.5",
-        "dotenv": "^16.5.0",
+        "dotenv": "^17",
         "express": "^5.1.0",
+        "lucide-react": "^0.525.0",
+        "next-themes": "^0.4.6",
         "open": "^10.1.1",
         "react": "^19.1.0",
         "react-dom": "^19.1.0",
+        "react-icons": "^5.5.0",
         "react-router-dom": "^7.5.2",
         "web-vitals": "^5"
     },
@@ -24,7 +24,15 @@
         "dev": "vite",
         "build": "vite build",
         "preview": "vite preview",
-        "test": "node --test"
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "test:ui": "vitest --ui",
+        "test:coverage": "vitest run --coverage",
+        "test:server": "node --test test/*.js",
+        "lint": "eslint .",
+        "lint:fix": "eslint . --fix",
+        "format": "prettier --write \"ui/src/**/*.{js,jsx,ts,tsx,json,css,md}\"",
+        "type-check": "tsc --noEmit"
     },
     "eslintConfig": {
         "extends": [
@@ -45,11 +53,31 @@
         ]
     },
     "devDependencies": {
+        "@testing-library/dom": "^10.4.0",
         "@testing-library/jest-dom": "^6.6.3",
         "@testing-library/react": "^16.3.0",
+        "@testing-library/user-event": "^14.5.2",
+        "@types/react": "^19.0.6",
+        "@types/react-dom": "^19.0.2",
+        "@typescript-eslint/eslint-plugin": "^8.0.0",
+        "@typescript-eslint/parser": "^8.0.0",
         "@vitejs/plugin-react": "^4.4.1",
+        "@vitest/coverage-v8": "^3.1.2",
+        "@vitest/ui": "^3.1.2",
+        "eslint": "^9",
+        "eslint-config-prettier": "^10",
+        "eslint-plugin-prettier": "^5.0.0",
+        "eslint-plugin-react": "^7.35.0",
+        "eslint-plugin-react-hooks": "^5",
         "jsdom": "^26.1.0",
-        "vite": "^6.3.3",
+        "prettier": "^3.5.0",
+        "supertest": "^7.0.0",
+        "typescript": "^5.7.3",
+        "vite": "^7",
+        "vite-tsconfig-paths": "^5.1.4",
         "vitest": "^3.1.2"
+    },
+    "engines": {
+        "node": ">=22.11.0"
     }
 }

package/routes/dispatcher.js

@@ -0,0 +1,77 @@
+import { logInfo, logVerbose } from '@l10nmonster/core';
+
+export function setupDispatcherRoutes(router, mm) {
+    router.post('/dispatcher/createJobs', async (req, res) => {
+        logInfo`/dispatcher/createJobs`;
+        
+        try {
+            const { sourceLang, targetLang, tus, providerList } = req.body;
+            
+            // Validate required parameters
+            if (!sourceLang || !targetLang || !tus || !providerList) {
+                return res.status(400).json({
+                    error: 'Missing required parameters: sourceLang, targetLang, tus, providerList'
+                });
+            }
+            
+            // Validate that tus is an array
+            if (!Array.isArray(tus)) {
+                return res.status(400).json({
+                    error: 'tus must be an array'
+                });
+            }
+            
+            // Validate that providerList is an array
+            if (!Array.isArray(providerList)) {
+                return res.status(400).json({
+                    error: 'providerList must be an array'
+                });
+            }
+            
+            logVerbose`Creating jobs for ${tus.length} TUs with providers: ${providerList.join(', ')}`;
+            
+            // Call the MonsterManager dispatcher
+            const result = await mm.dispatcher.createJobs({ sourceLang, targetLang, tus }, { providerList, skipQualityCheck: true, skipGroupCheck: true });
+            
+            logVerbose`Created ${result?.length || 0} jobs successfully`;
+            res.json(result);
+            
+        } catch (error) {
+            logInfo`Error creating jobs: ${error.message}`;
+            res.status(500).json({
+                error: 'Failed to create jobs',
+                message: error.message
+            });
+        }
+    });
+
+    router.post('/dispatcher/startJobs', async (req, res) => {
+        logInfo`/dispatcher/startJobs`;
+        
+        try {
+            const { jobs, instructions } = req.body;
+            
+            // Validate required parameters
+            if (!jobs || !Array.isArray(jobs)) {
+                return res.status(400).json({
+                    error: 'Missing or invalid jobs parameter (must be an array)'
+                });
+            }
+            
+            logVerbose`Starting ${jobs.length} jobs with instructions: ${instructions || 'none'}`;
+            
+            // Call the MonsterManager dispatcher
+            const result = await mm.dispatcher.startJobs(jobs, { instructions });
+            
+            logVerbose`Started jobs, returned ${result?.length || 0} job statuses`;
+            res.json(result);
+            
+        } catch (error) {
+            logInfo`Error starting jobs: ${error.message}`;
+            res.status(500).json({
+                error: 'Failed to start jobs',
+                message: error.message
+            });
+        }
+    });
+}

package/routes/info.js

@@ -0,0 +1,24 @@
+import { logInfo, getBaseDir } from '@l10nmonster/core';
+import path from 'path';
+
+export function setupInfoRoute(router, mm, serverPackage) {
+    router.get('/info', async (req, res) => {
+        logInfo`/info`;
+        res.json({
+            version: serverPackage.version,
+            description: serverPackage.description,
+            baseDir: path.resolve(getBaseDir()),
+            providers: mm.dispatcher.providers.map(p => p.id),
+            channels: Object.keys(mm.rm.channels),
+            tmStores: mm.getTmStoreIds().map(id => {
+                const tmStore = mm.getTmStore(id);
+                return {
+                    id: tmStore.id,
+                    type: tmStore.constructor.name,
+                    access: tmStore.access,
+                    partitioning: tmStore.partitioning,
+                };
+            }),
+        });
+    });
+}

package/routes/providers.js

@@ -0,0 +1,19 @@
+import { logInfo, logVerbose } from '@l10nmonster/core';
+
+export function setupProviderRoute(apiRouter, mm) {
+  apiRouter.get('/providers', async (req, res) => {
+    logInfo`/providers`;
+    try {
+      const providers = {};
+      for (const provider of mm.dispatcher.providers) {
+        const { id, ...info } = await provider.info();
+        providers[id] = { properties: provider, info };
+      }
+      logVerbose`Returned provider info for ${Object.keys(providers).length} providers`;
+      res.json(providers);
+    } catch (error) {
+      console.error('Error fetching provider data:', error);
+      res.status(500).json({ error: 'Failed to fetch provider data' });
+    }
+  });
+}

package/routes/sources.js

@@ -0,0 +1,14 @@
+import { logInfo, logVerbose } from '@l10nmonster/core';
+
+export function setupActiveContentStatsRoute(router, mm) {
+    router.get('/activeContentStats', async (req, res) => {
+        logInfo`/activeContentStats`;
+        const sources = {};
+        for (const channelId of Object.keys(mm.rm.channels)) {
+            const channelStats = await mm.rm.getActiveContentStats(channelId);
+            sources[channelId] = channelStats;
+        }
+        logVerbose`Returned active content stats for ${Object.keys(sources).length} channels`;
+        res.json(sources);
+    });
+} 

package/routes/status.js

@@ -0,0 +1,30 @@
+import { logInfo, logVerbose } from '@l10nmonster/core';
+
+export function setupStatusRoute(router, mm) {
+    router.get('/status', async (req, res) => {
+        logInfo`/status`;
+        try {
+            const status = await mm.getTranslationStatus();
+            // source_lang -> target_lang -> channel -> project -> data
+            logVerbose`Returned translation status`;
+            res.json(status);
+        } catch (error) {
+            console.error('Error fetching status: ', error);
+            res.status(500).json({ message: 'Problems fetching status data' });
+        }
+    });
+
+    router.get('/status/:sourceLang/:targetLang', async (req, res) => {
+        const { sourceLang, targetLang } = req.params;
+        logInfo`/status/${sourceLang}/${targetLang}`;
+        try {
+            const tm = mm.tmm.getTM(sourceLang, targetLang);
+            const tus = tm.getUntranslatedContent();
+            logVerbose`Returned ${tus.length} untranslated TUs for ${sourceLang}->${targetLang}`;
+            res.json(tus);
+        } catch (error) {
+            logInfo`Error: ${error.message}`;
+            res.status(500).json({ error: error.message });
+        }
+    });
+}