@workadventure/map-starter-kit-core 0.0.1

package/src/controllers/UploaderController.ts

@@ -0,0 +1,333 @@
+import express from 'express';
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { exec } from "node:child_process";
+import { promisify } from "node:util";
+
+const execAsync = promisify(exec);
+
+/** Metadata returned by map-storage for each map (WAM file). */
+export interface MapStorageMetadata {
+    copyright?: string;
+    description?: string;
+    name?: string;
+    thumbnail?: string;
+}
+
+/** Single map entry returned by map-storage GET /maps/ (value in the map). */
+export interface MapStorageEntry {
+    mapUrl: string;
+    wamFileUrl?: string;
+    metadata?: MapStorageMetadata;
+}
+
+/** Response shape: Map<wamfile, { mapUrl, metadata }>. In JSON this is a plain object. */
+export interface MapStorageListResponse {
+    [wamFile: string]: MapStorageEntry;
+}
+
+/** Hydrated map item returned by our API to the frontend. */
+export interface MapListItem {
+    wamFileUrl: string;
+    filename: string;
+    mapName: string | null;
+    mapDescription?: string;
+    mapCopyright?: string;
+    mapImage: string | null;
+    mapUrl: string;
+}
+
+/**
+ * Converts the map-storage response (Map<wamfile, entry>) into a list of MapListItem.
+ */
+export function hydrateMapStorageList(
+    raw: MapStorageListResponse,
+    mapStorageBaseUrl: string
+): MapListItem[] {
+    const list: MapListItem[] = [];
+    const baseUrl = mapStorageBaseUrl.replace(/\/$/, '');
+
+    for (const [wamFile, entry] of Object.entries(raw)) {
+        if (!entry || typeof entry !== 'object') continue;
+
+        const rawWamFileUrl = entry.wamFileUrl ?? wamFile;
+        const wamFileUrlNormalized = rawWamFileUrl.startsWith('http')
+            ? new URL(rawWamFileUrl).pathname.replace(/^\//, '')
+            : rawWamFileUrl.replace(/^\//, '');
+
+        const filename = wamFileUrlNormalized.split('/').pop() ?? wamFileUrlNormalized;
+        const nameFromFile = filename.replace(/\.(tmj|wam)$/i, '');
+
+        const meta = entry.metadata ?? {};
+        const mapUrl = entry.mapUrl ?? (entry as unknown as { mapUrl?: string }).mapUrl ?? '';
+
+        let mapImage: string | null = null;
+        if (meta.thumbnail) {
+            if (meta.thumbnail.startsWith('http')) {
+                mapImage = meta.thumbnail;
+            } else {
+                const thumbFile = meta.thumbnail.replace(/^\//, '');
+                const wamDir = wamFileUrlNormalized.includes('/')
+                    ? wamFileUrlNormalized.replace(/\/[^/]*$/, '')
+                    : '';
+                const thumbPath = wamDir ? `${wamDir}/${thumbFile}` : thumbFile;
+                mapImage = `${baseUrl}/${thumbPath}`;
+            }
+        }
+
+        list.push({
+            wamFileUrl: wamFileUrlNormalized,
+            filename,
+            mapName: meta.name ?? nameFromFile,
+            mapDescription: meta.description,
+            mapCopyright: meta.copyright,
+            mapImage,
+            mapUrl: mapUrl.startsWith('http') ? mapUrl : `${baseUrl}/${mapUrl.replace(/^\//, '')}`,
+        });
+    }
+
+    return list;
+}
+
+export class UploaderController {
+    private router: express.Router;
+    private app: express.Application;
+
+    constructor(app: express.Application) {
+        this.app = app;
+        this.router = express.Router();
+        this.setupMiddleware();
+        this.setupRoutes();
+        // Register the router on the application with the "/uploader" prefix
+        this.app.use('/uploader', this.router);
+    }
+
+    private setupMiddleware() {
+        // Middleware to parse JSON bodies
+        this.router.use(express.json());
+    }
+
+    private setupRoutes() {
+        // Route to configure MAP_STORAGE mode
+        this.router.post('/configure', async (req, res) => {
+            try {
+                const { mapStorageUrl, mapStorageApiKey, uploadDirectory } = req.body;
+
+                // Validate required fields
+                if (!mapStorageUrl || !mapStorageApiKey || !uploadDirectory) {
+                    return res.status(400).json({
+                        error: 'Missing required fields',
+                        required: ['mapStorageUrl', 'mapStorageApiKey', 'uploadDirectory']
+                    });
+                }
+
+                // Create or update .env.secret file
+                await this.createEnvSecretFile({
+                    mapStorageUrl,
+                    mapStorageApiKey,
+                    uploadDirectory
+                });
+
+                return res.json({
+                    success: true,
+                    message: 'Configuration updated successfully'
+                });
+            } catch (error) {
+                console.error('Error configuring uploader:', error);
+                return res.status(500).json({
+                    error: 'Error configuring uploader',
+                    message: error instanceof Error ? error.message : 'Unknown error'
+                });
+            }
+        });
+
+        // Route to get current configuration status
+        this.router.get('/status', async (_, res) => {
+            try {
+                const envSecretPath = path.join(process.cwd(), 'src/.env.secret');
+
+                const hasSecretFile = await fs.promises.access(envSecretPath)
+                    .then(() => true)
+                    .catch(() => false);
+
+                let secretConfig: {
+                    mapStorageUrl: string | null;
+                    mapStorageApiKey: string | null;
+                    uploadDirectory: string | null;
+                } | null = null;
+                if (hasSecretFile) {
+                    const secretContent = await fs.promises.readFile(envSecretPath, 'utf-8');
+                    const mapStorageUrl = secretContent.match(/MAP_STORAGE_URL=(.+)/)?.[1]?.trim();
+                    const mapStorageApiKey = secretContent.match(/MAP_STORAGE_API_KEY=(.+)/)?.[1]?.trim();
+                    const uploadDirectory = secretContent.match(/UPLOAD_DIRECTORY=(.+)/)?.[1]?.trim();
+
+                    secretConfig = {
+                        mapStorageUrl: mapStorageUrl || null,
+                        mapStorageApiKey: mapStorageApiKey || null, // Hide the actual key
+                        uploadDirectory: uploadDirectory || null
+                    };
+                }
+
+                res.json({
+                    hasSecretFile,
+                    secretConfig
+                });
+            } catch (error) {
+                console.error('Error getting uploader status:', error);
+                res.status(500).json({
+                    error: 'Error getting uploader status',
+                    message: error instanceof Error ? error.message : 'Unknown error'
+                });
+            }
+        });
+
+        // Route to get list of maps from map-storage (for self-hosted step4)
+        this.router.get('/maps-storage-list', async (_, res) => {
+            try {
+                const envSecretPath = path.join(process.cwd(), '.env.secret');
+                const hasSecretFile = await fs.promises.access(envSecretPath)
+                    .then(() => true)
+                    .catch(() => false);
+
+                if (!hasSecretFile) {
+                    return res.status(400).json({
+                        error: 'Configuration not found',
+                        message: 'Please configure the upload settings first.'
+                    });
+                }
+
+                const secretContent = await fs.promises.readFile(envSecretPath, 'utf-8');
+                const mapStorageUrl = secretContent.match(/MAP_STORAGE_URL=(.+)/)?.[1]?.trim();
+                const mapStorageApiKey = secretContent.match(/MAP_STORAGE_API_KEY=(.+)/)?.[1]?.trim();
+
+                if (!mapStorageUrl || !mapStorageApiKey) {
+                    return res.status(400).json({
+                        error: 'Missing map-storage configuration',
+                        message: 'MAP_STORAGE_URL and MAP_STORAGE_API_KEY must be set in .env.secret.'
+                    });
+                }
+
+                const baseUrl = mapStorageUrl.replace(/\/$/, '');
+                const listUrl = `${baseUrl}/maps/`;
+
+                const response = await fetch(listUrl, {
+                    method: 'GET',
+                    headers: {
+                        'Authorization': `Bearer ${mapStorageApiKey}`,
+                        'Content-Type': 'application/json'
+                    }
+                });
+
+                if (!response.ok) {
+                    const text = await response.text();
+                    console.error('Map-storage list error:', response.status, text);
+                    return res.status(response.status).json({
+                        error: 'Map-storage request failed',
+                        message: response.status === 401
+                            ? 'Invalid API key. Check MAP_STORAGE_API_KEY in your .env.secret.'
+                            : `Map-storage returned ${response.status}: ${text.slice(0, 200)}`
+                    });
+                }
+
+                const data = await response.json();
+                // Map-storage returns Map<wamfile, { mapUrl, metadata }> (as a plain object in JSON)
+                const raw = typeof data === 'object' && data !== null ? data : {};
+                const rawMap: MapStorageListResponse = !Array.isArray(raw) && typeof raw.maps === 'object' && raw.maps !== null
+                    ? (raw.maps as MapStorageListResponse)
+                    : !Array.isArray(raw)
+                    ? (raw as MapStorageListResponse)
+                    : {};
+                const maps = hydrateMapStorageList(rawMap, baseUrl);
+                const playBaseUrl = secretContent.match(/PLAY_BASE_URL=(.+)/)?.[1]?.trim() || null;
+                return res.json({ maps, mapStorageUrl: baseUrl, playBaseUrl });
+            } catch (error) {
+                console.error('Error fetching maps from map-storage:', error);
+                return res.status(500).json({
+                    error: 'Error fetching maps list',
+                    message: error instanceof Error ? error.message : 'Unknown error'
+                });
+            }
+        });
+
+        // Route to upload map
+        this.router.post('/upload', async (_, res) => {
+            try {
+                // Verify that configuration exists
+                const envSecretPath = path.join(process.cwd(), '.env.secret');
+
+                // Check if .env.secret exists
+                const hasSecretFile = await fs.promises.access(envSecretPath)
+                    .then(() => true)
+                    .catch(() => false);
+
+                if (!hasSecretFile) {
+                    return res.status(400).json({
+                        error: 'Configuration not found',
+                        message: 'Please configure the upload settings first using /uploader/configure'
+                    });
+                }
+
+                // Execute upload
+                await this.runUpload();
+
+                return res.json({
+                    success: true,
+                    message: 'Map uploaded successfully'
+                });
+            } catch (error) {
+                console.error('Error uploading map:', error);
+                return res.status(500).json({
+                    error: 'Error uploading map',
+                    message: error instanceof Error ? error.message : 'Unknown error'
+                });
+            }
+        });
+    }
+
+    private async runUpload(): Promise<void> {
+        const projectRoot = process.cwd();
+        
+        try {
+            // Execute npm run upload-only
+            // The command will read environment variables from .env and .env.secret
+            const { stdout, stderr } = await execAsync('npm run upload', {
+                cwd: projectRoot,
+                env: {
+                    ...process.env,
+                    // Ensure we're using the current process environment
+                    NODE_ENV: process.env.NODE_ENV || 'development'
+                },
+                maxBuffer: 10 * 1024 * 1024 // 10MB buffer for output
+            });
+
+            if (stderr && !stderr.includes('warning')) {
+                console.warn('Upload stderr:', stderr);
+            }
+            
+            console.info('Upload stdout:', stdout);
+            console.info('Upload completed successfully');
+        } catch (error) {
+            console.error('Error executing upload-only:', error);
+            throw error;
+        }
+    }
+
+    private async createEnvSecretFile(config: {
+        mapStorageUrl: string;
+        mapStorageApiKey: string;
+        uploadDirectory: string;
+    }): Promise<void> {
+        const envSecretPath = path.join(process.cwd(), '.env.secret');
+
+        // Create the .env.secret file with the provided configuration
+        const secretContent = `# Secret configuration file for MAP_STORAGE upload mode
+# This file is not committed to git (see .gitignore)
+
+MAP_STORAGE_URL=${config.mapStorageUrl}
+MAP_STORAGE_API_KEY=${config.mapStorageApiKey}
+UPLOAD_DIRECTORY=${config.uploadDirectory}
+`;
+
+        await fs.promises.writeFile(envSecretPath, secretContent, 'utf-8');
+    }
+}

package/src/getCoreRoot.ts

@@ -0,0 +1,40 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+
+let coreRoot: string | null = null;
+
+/**
+ * Returns the root directory of the "core" package (app + templates + public).
+ * - When running from the project root: returns process.cwd().
+ * - When running from packages/map-starter-kit-core or node_modules: returns the package directory.
+ * Allows updating the core package without touching user files (maps, .env, tilesets).
+ */
+export function getCoreRoot(): string {
+    if (coreRoot !== null) {
+        return coreRoot;
+    }
+    try {
+        const dir = path.dirname(fileURLToPath(import.meta.url));
+        const candidate = path.dirname(dir);
+        const packagePath = path.join(candidate, "package.json");
+        if (fs.existsSync(packagePath)) {
+            const pkg = JSON.parse(fs.readFileSync(packagePath, "utf-8"));
+            if (pkg.name === "@workadventure/map-starter-kit-core") {
+                coreRoot = candidate;
+                return coreRoot;
+            }
+        }
+    } catch {
+        // ignore
+    }
+    coreRoot = process.cwd();
+    return coreRoot;
+}
+
+/**
+ * Override the core root (e.g. for tests or custom layout).
+ */
+export function setCoreRoot(root: string): void {
+    coreRoot = root;
+}

package/src/server.ts

@@ -0,0 +1,124 @@
+import express from 'express';
+import * as path from "node:path";
+import * as fs from "node:fs";
+import cors from 'cors';
+import { getCoreRoot } from './getCoreRoot.js';
+import { FrontController } from './controllers/FrontController.js';
+import { MapController } from './controllers/MapController.js';
+import { UploaderController } from './controllers/UploaderController.js';
+
+const app = express();
+
+const corsOptions = {
+    credentials: true, // Allow sending cookies
+    methods: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH', 'OPTIONS'],
+    allowedHeaders: [
+        'Content-Type',
+        'Authorization',
+        'X-Requested-With',
+        'Accept',
+        'Origin',
+        'Access-Control-Request-Method',
+        'Access-Control-Request-Headers'
+    ],
+    exposedHeaders: ['Content-Length', 'Content-Type'],
+    maxAge: 86400, // Cache the OPTIONS requests for 24 hours
+};
+
+// Apply the CORS middleware
+// The CORS middleware automatically handles the OPTIONS requests (preflight)
+app.use(cors(corsOptions));
+
+// Parse JSON bodies
+app.use(express.json());
+
+// Configure the static assets for Express
+const staticOptions = {
+    maxAge: '1d', // Cache the files for 1 day
+    etag: true, // Enable ETag for cache validation
+    lastModified: true, // Enable Last-Modified header
+};
+
+// Serve dist/assets FIRST with explicit MIME type configuration
+// This ensures compiled JavaScript files from getMapsScripts are served correctly
+// This route must be before express.static('.') to take precedence
+app.use('/assets', express.static(path.join(process.cwd(), 'dist', 'assets'), staticOptions));
+// Serve the public folder from core (project root or package root for easy updates)
+app.use('/public', express.static(path.join(getCoreRoot(), 'public'), staticOptions));
+// Serve the tilesets folder with a longer cache (rarely modified)
+app.use('/tilesets', express.static(path.join(process.cwd(), 'tilesets'), {
+    maxAge: '7d',
+    etag: true,
+    lastModified: true,
+}));
+
+// Middleware to exclude /src from express.static - let Vite handle TypeScript transformation
+// VitePluginNode will automatically add Vite middleware that transforms TypeScript files
+const staticMiddleware = express.static('.', staticOptions);
+
+// Middleware to transform and serve TypeScript files as JavaScript
+// This bundles the file with its dependencies to resolve npm imports
+app.use('/src', async (req, res, next) => {
+    // Only handle .ts and .tsx files - transform them to JavaScript
+    if (req.path.endsWith('.ts') || req.path.endsWith('.tsx')) {
+        try {
+            // req.path includes /src/, so we need to join it correctly
+            const filePath = path.join(process.cwd(), 'src', req.path.startsWith('/') ? req.path.slice(1) : req.path);
+            
+            // Check if file exists
+            if (!fs.existsSync(filePath)) {
+                return res.status(404).send('File not found');
+            }
+            
+            // Use dynamic import to get esbuild (available via Vite)
+            const esbuild = await import('esbuild');
+            
+            // Bundle the TypeScript file with its dependencies
+            // This resolves npm imports like @workadventure/scripting-api-extra
+            const result = await esbuild.build({
+                entryPoints: [filePath],
+                bundle: true,
+                format: 'esm',
+                target: 'esnext',
+                write: false,
+                platform: 'browser',
+                sourcemap: false,
+                // Externalize WorkAdventure global API (available in the browser)
+                external: ['WA'],
+            });
+            
+            res.setHeader('Content-Type', 'application/javascript; charset=utf-8');
+            return res.send(result.outputFiles[0].text);
+        } catch (error) {
+            console.error('Error transforming TypeScript file:', error);
+            return next(error);
+        }
+    }
+    // For non-TypeScript files in /src, pass to next middleware
+    next();
+});
+
+// Serve static files, but skip /src (handled above)
+app.use((req, res, next) => {
+    // Skip /src requests - they are handled by the transformation middleware above
+    if (req.path.startsWith('/src/')) {
+        return next(); // Let the transformation middleware handle it or pass to Vite
+    }
+    // For other files, use express.static
+    staticMiddleware(req, res, next);
+});
+
+const controllers = [
+    new MapController(app),
+    new FrontController(app),
+    new UploaderController(app),
+];
+
+// Verify and log all controllers created
+controllers.forEach(controller => {
+    console.info(`Controller started: ${controller.constructor.name}`);
+});
+
+export default app;
+// Export for VitePluginNode compatibility
+export const viteNodeApp = app;

package/src/views/index.html

@@ -0,0 +1,169 @@
+<!DOCTYPE html>
+<html lang="en">
+
+<head>
+    <meta charset="UTF-8">
+    <meta http-equiv="X-UA-Compatible" content="IE=edge">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta name="robots" content="noindex">
+    <meta name="title" content="WorkAdventure Starter Kit">
+
+    <link href="public/styles/styles.css" rel="stylesheet">
+
+    <title>WorkAdventure test map</title>
+    <link rel="icon" href="/images/favicon.svg" type="image/svg+xml">
+    <script src="https://cdn.jsdelivr.net/npm/mustache@4.2.0/mustache.min.js"></script>
+    <script type="module">
+        document.addEventListener("DOMContentLoaded", (event) => {
+            // Load index.js to have access to getMapsList
+            import('/public/assets/index.js').then(() => {
+                loadTMJ();
+            });
+        });
+
+        async function loadTMJ() {
+            try {
+                // Get the list of maps from the API
+                const maps = await window.getMapsList();
+                
+                // Retrieve map images for background fade
+                const mapImages = maps
+                    .map(map => {
+                        if (map.mapImage) {
+                            return map.mapImage.startsWith('http') ? map.mapImage : `/${map.mapImage}`;
+                        }
+                        return null;
+                    })
+                    .filter(img => img !== null);
+                
+                // Create background image fade
+                if (mapImages.length > 0) {
+                    await window.createBackgroundImageFade(mapImages);
+                }
+                
+                // Mustache template for a map card
+                const cardTemplate = `
+                    <div class="map-cover" style="background-image: url('{{mapImageUrl}}');"></div>
+                    <div class="map-date">
+                        Last edit: {{lastModifiedFormatted}}
+                    </div>
+                    <div class="map-name">
+                        {{mapName}}
+                    </div>
+                    <div class="map-detail">
+                        <div class="map-file">
+                            <strong>{{filename}}</strong>.tmj
+                        </div>
+                        <div class="map-weight">
+                            <strong>{{size}}</strong>
+                            <span style="opacity: .5">Mo</span>
+                        </div>
+                    </div>
+                    <div class="map-desc">
+                        {{mapDescription}}
+                    </div>
+                    <div class="map-testurl">
+                        <a href="#" class="btn" data-map-path="{{path}}">Test my map</a>
+                    </div>
+                `;
+
+                // Prepare data for Mustache
+                const mapsData = maps.map(map => {
+                    // Build the image URL - use the first available image or a default image
+                    const mapImageUrl = map.mapImage 
+                        ? (map.mapImage.startsWith('http') ? map.mapImage : `/${map.mapImage}`)
+                        : (mapImages.length > 0 ? mapImages[0] : 'data:image/svg+xml,<svg xmlns="http://www.w3.org/2000/svg" width="1620" height="1024"><rect fill="%231b2a41" width="100%" height="100%"/></svg>');
+                    
+                    return {
+                        ...map,
+                        mapImageUrl: mapImageUrl,
+                        mapDescription: map.mapDescription || 'No description available'
+                    };
+                });
+
+                // Render each map with Mustache and inject them into the container
+                const mainElement = document.querySelector('main');
+                if (mainElement) {
+                    // Clear existing content
+                    mainElement.innerHTML = '';
+                    
+                    // Create a section for each map
+                    mapsData.forEach(map => {
+                        const section = document.createElement('section');
+                        section.className = 'card-map';
+                        section.innerHTML = Mustache.render(cardTemplate, map);
+                        
+                        // Add an event handler for the "Test my map" button
+                        const testBtn = section.querySelector('.map-testurl a');
+                        if (testBtn) {
+                            testBtn.addEventListener('click', (e) => {
+                                e.preventDefault();
+                                const host = window.location.host;
+                                let path = window.location.pathname;
+                                if (path.endsWith('index.html')) {
+                                    path = path.substr(0, path.length - 'index.html'.length);
+                                }
+                                const instanceId = Math.random().toString(36).substring(2, 15);
+                                const url = `https://play.workadventu.re/_/${instanceId}/${host}${path}${map.path}`;
+                                window.open(url, '_blank');
+                            });
+                        }
+                        
+                        mainElement.appendChild(section);
+                    });
+                }
+            } catch (error) {
+                console.error('Error loading maps:', error);
+            }
+        }
+    </script>
+</head>
+
+<body>
+<div class="content">
+    <header>
+        <div class="logo">
+            <a href="https://workadventu.re/" target="_blank" title="Workadventure">
+                <img src="public/images/logo.svg" alt="Workadventure logo" height="36" />
+            </a>
+        </div>
+        <div style="flex-grow: 1;"></div>
+        <div class="socials">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" title="discord">
+                <img src="/public/images/brand-discord.svg" alt="discord">
+            </a>
+            <a href="https://github.com/thecodingmachine/workadventure" target="_blank" title="github">
+                <img src="/public/images/brand-github.svg" alt="github">
+            </a>
+            <a href="https://www.youtube.com/channel/UCXJ9igV-kb9gw1ftR33y5tA" target="_blank" title="youtube">
+                <img src="/public/images/brand-youtube.svg" alt="youtube">
+            </a>
+            <a href="https://twitter.com/Workadventure_" target="_blank" title="twitter">
+                <img src="/public/images/brand-x.svg" alt="X">
+            </a>
+            <a href="https://www.linkedin.com/company/workadventu-re" target="_blank" title="linkedin">
+                <img src="/public/images/brand-linkedin.svg" alt="linkedin">
+            </a>
+        </div>
+        <div class="btn-header-wrapper">
+            <a href="https://discord.gg/G6Xh9ZM9aR" target="_blank" class="btn btn-light">Talk to the community</a>
+            <a href="https://docs.workadventu.re/map-building/" target="_blank" class="btn">Documentation</a>
+        </div>
+    </header>
+    <main>
+        <!-- Map cards will be injected here dynamically by Mustache -->
+    </main>
+    <div class="button-wrapper">
+        <div style="flex-grow: 1;">
+        </div>
+        <div>
+            <a href="step1-git">
+                Publish
+            </a>
+        </div>
+    </div>
+</div>
+<div class="bg"></div>
+</body>
+
+</html>