@workadventure/map-starter-kit-core 1.1.0 → 1.1.1

package/README.md

@@ -0,0 +1,165 @@
+# @workadventure/map-starter-kit-core
+
+Core app, HTML pages and static assets for the **WorkAdventure Map Starter Kit**. Update this package to get new UI and server features without touching your maps or config.
+
+## Features
+
+- **Web UI** – Step-by-step wizard (Git, hosting, steps, validation) for setting up and validating your map project
+- **Map listing** – Discovers `.tmj` maps on disk with properties (name, description, image, copyright, size, last modified)
+- **Uploader** – Configure and run map uploads to [map-storage](https://github.com/workadventure/map-storage); list maps from map-storage for self-hosted flows
+- **Static assets** – Serves public assets, tilesets, and compiled JS; transforms and serves TypeScript under `/src` (esbuild) for browser scripts
+- **Express app** – CORS, JSON body parsing, cache headers; can be mounted in another app or run standalone via Vite
+
+## Installation
+
+```bash
+npm install @workadventure/map-starter-kit-core
+```
+
+**Peer / consumer:** The built server expects `express` to be available at runtime. For TypeScript consumers, `@types/express` is used for the exported `Application` type.
+
+## Usage
+
+### As a dependency (programmatic)
+
+Use the built Express app in your own server:
+
+```ts
+import core from "@workadventure/map-starter-kit-core/dist/server.js";
+
+const app = core.default;  // or core.viteNodeApp
+
+// Mount or start your server
+app.listen(3000, () => console.log("Listening on 3000"));
+```
+
+Types are provided: `core` is typed as `{ default: Application; viteNodeApp: Application }` (see `types/server.d.ts`).
+
+### Development server (standalone)
+
+From the **map-starter-kit** repo (or a project that uses this package as the core):
+
+```bash
+npm run dev
+```
+
+Runs the Vite dev server with vite-plugin-node (Express). Opens the app at the configured host (e.g. `http://localhost:5173/`).
+
+### Build for production
+
+```bash
+npm run build
+```
+
+- Runs `tsc` (type-check only; `noEmit: true` in tsconfig)
+- Builds the server bundle with Vite into `dist/server.js`
+- Copies `types/server.d.ts` to `dist/server.d.ts` for published types
+
+## Project structure
+
+```
+map-starter-kit-core/
+├── src/
+│   ├── server.ts              # Express app entry (CORS, static, routes)
+│   ├── getCoreRoot.ts         # Resolve core package root (cwd vs package dir)
+│   ├── controllers/
+│   │   ├── FrontController.ts # HTML pages (Mustache): /, step1-git, step2-hosting, step3-*, step4-*
+│   │   ├── MapController.ts   # /maps/list – list .tmj maps with properties
+│   │   └── UploaderController.ts  # /uploader/* – configure, status, maps-storage-list, upload
+│   └── views/                 # Mustache HTML templates
+│       ├── index.html
+│       ├── step1-git.html … step4-validated-selfhosted.html
+├── public/                    # Static assets (images, styles, etc.)
+├── types/
+│   └── server.d.ts            # Module declaration for dist/server.js (copied to dist on build)
+├── dist/                      # Build output (server.js, server.d.ts, assets)
+├── vite.config.ts
+├── tsconfig.json
+└── package.json
+```
+
+## API / Routes
+
+| Method | Path | Description |
+|--------|------|-------------|
+| **Front (HTML)** | | |
+| GET | `/` | Home (index) |
+| GET | `/step1-git` | Step 1 – Git |
+| GET | `/step2-hosting` | Step 2 – Hosting |
+| GET | `/step3-steps` | Step 3 – Steps |
+| GET | `/step3-steps-selfhosted` | Step 3 – Self-hosted |
+| GET | `/step4-validated` | Step 4 – Validated |
+| GET | `/step4-validated-selfhosted` | Step 4 – Validated (self-hosted) |
+| **Maps** | | |
+| GET | `/maps/list` | List `.tmj` maps with properties (path, mapName, mapImage, size, lastModified, etc.) |
+| **Uploader** | | |
+| POST | `/uploader/configure` | Configure MAP_STORAGE (body: `mapStorageUrl`, `mapStorageApiKey`, `uploadDirectory`) |
+| GET | `/uploader/status` | Current config status (e.g. presence of `.env.secret`) |
+| GET | `/uploader/maps-storage-list` | List maps from map-storage (for self-hosted step 4) |
+| POST | `/uploader/upload` | Run the upload (uses config from `.env.secret`) |
+
+Static and special paths:
+
+- `/public/*` – Static files from core’s `public/`
+- `/assets/*` – From project’s `dist/assets/`
+- `/tilesets/*` – From project’s `tilesets/`
+- `/src/*.ts` – Served as compiled JS (esbuild), e.g. for browser scripts using WorkAdventure APIs
+
+## Configuration
+
+### Uploader (MAP_STORAGE)
+
+Configure via **POST `/uploader/configure`** with:
+
+- `mapStorageUrl` – map-storage base URL
+- `mapStorageApiKey` – API key for map-storage
+- `uploadDirectory` – Local directory to upload from
+
+This writes (or updates) a secret file (e.g. `.env.secret` or `src/.env.secret` depending on route) used by the upload and maps-storage-list endpoints. Do not commit this file.
+
+### Core root
+
+`getCoreRoot()` resolves the root of the core package:
+
+- When run from the **project root** (e.g. map-starter-kit): `process.cwd()`
+- When run from **packages/map-starter-kit-core** or **node_modules**: the package directory
+
+So templates and `public` are always loaded from the core package, while maps, `.env`, and `tilesets` stay in the project root.
+
+## Scripts
+
+| Script | Command | Description |
+|--------|---------|-------------|
+| `dev` | `vite` | Start dev server (Express via vite-plugin-node) |
+| `build` | `tsc && vite build && node -e "…"` | Type-check, build server to `dist/`, copy `server.d.ts` |
+
+## Releasing
+
+Releases are automated with **semantic-release** and **GitHub Actions**:
+
+- **Workflow:** `.github/workflows/release.yml`
+- **Trigger:** Push to `main` or `master`
+- **Conventions:** [Conventional Commits](https://www.conventionalcommits.org/) (`feat:`, `fix:`, `BREAKING CHANGE:`) determine the next version; a release is published only when there are relevant commits.
+- **Artifacts:** GitHub Release + **npm** publish of `@workadventure/map-starter-kit-core`.
+
+**npm auth (after classic token deprecation):**
+
+- **Recommended:** [Trusted Publishing (OIDC)](https://docs.npmjs.com/trusted-publishers) for this repo and workflow (no long-lived token).
+- **Alternative:** Create a **granular access token** on [npm](https://www.npmjs.com/settings/~/tokens), then set the **NPM_TOKEN** secret in the repo.
+
+## Tech stack
+
+- **Runtime:** Node.js, Express 5
+- **Build:** TypeScript 5, Vite 7, vite-plugin-node
+- **Templates:** Mustache
+- **Release:** semantic-release
+
+## License
+
+MIT. See [LICENSE](LICENSE).
+
+## Links
+
+- **Repository:** [github.com/workadventure/map-starter-kit-core](https://github.com/workadventure/map-starter-kit-core)
+- **Issues:** [github.com/workadventure/map-starter-kit-core/issues](https://github.com/workadventure/map-starter-kit-core/issues)
+- **npm:** [@workadventure/map-starter-kit-core](https://www.npmjs.com/package/@workadventure/map-starter-kit-core)

package/dist/assets/views/index.html

@@ -0,0 +1,168 @@
+<!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 build your map</title>
+    <link rel="icon" href="public/images/favicon.svg" type="image/svg+xml">
+    <script type="module">
+        document.addEventListener("DOMContentLoaded", (event) => {
+            // Load index.js to have access to getMapsList
+            import('/public/assets/js/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>

package/dist/assets/views/step1-git.html

@@ -0,0 +1,154 @@
+<!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 build your map</title>
+    <link rel="icon" href="public/images/favicon.svg" type="image/svg+xml">
+    <script type="module">
+        document.addEventListener("DOMContentLoaded", (event) => {
+            // Load index.js to have access to getMapsList
+            import('/public/assets/js/index.js').then(() => {
+                window.createBackgroundImageFade();
+            });
+        });
+    </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>
+        <section class="form-center">
+            <h1>
+                How do you want to publish your map?
+            </h1>
+            <div class="sub-heading">
+                Choose the workflow that best fits your team and your way of working.
+            </div>
+            <div class="radio-wrapper">
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio">
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            Advanced publishing
+                        </h2>
+                        <div>
+                            <strong>Designed for teams using Git and file versioning.</strong>
+                            Full control over your files and collaboration workflow.
+                        </div>
+                    </div>
+                </label>
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio" checked>
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            Recommended publishing
+                        </h2>
+                        <div>
+                            <strong>The easiest and fastest way to publish your map.</strong>
+                            No technical setup required. Ideal for getting started quickly.
+                        </div>
+                    </div>
+                </label>
+            </div>
+
+        </section>
+    </main>
+    <div class="button-wrapper">
+        <div>
+            <a href="/" class="btn btn-ghost">
+                Previous
+            </a>
+        </div>
+        <div style="flex-grow: 1;">
+        </div>
+        <div>
+            <a href="step2-hosting" class="btn btn-secondary">
+                Start configuration
+            </a>
+        </div>
+    </div>
+</div>
+<div class="bg"></div>
+<script>
+    // Get radio buttons by finding the label containing "Advanced publishing"
+    const radioButtons = document.querySelectorAll('input[name="advanced"]');
+    const startConfigButton = document.querySelector('a[href="step2-hosting"]');
+    const docUrl = "https://docs.workadventu.re/map-building/tiled-editor/publish/wa-hosted";
+
+    // Find Advanced publishing radio button by checking parent label text
+    let advancedPublishingRadio = null;
+    radioButtons.forEach(radio => {
+        const label = radio.closest('label');
+        if (label && label.textContent.includes('Advanced publishing')) {
+            advancedPublishingRadio = radio;
+        }
+    });
+
+    // Function to update button href based on selection
+    function updateButtonHref() {
+        // Check if Advanced publishing is selected
+        if (advancedPublishingRadio && advancedPublishingRadio.checked) {
+            startConfigButton.href = docUrl;
+            startConfigButton.target = "_blank";
+        } else {
+            startConfigButton.href = "step2-hosting";
+            startConfigButton.removeAttribute("target");
+        }
+    }
+
+    // Add event listeners to all radio buttons
+    radioButtons.forEach(radio => {
+        radio.addEventListener('change', updateButtonHref);
+    });
+
+    // Initialize on page load
+    updateButtonHref();
+</script>
+</body>
+
+</html>

package/dist/assets/views/step2-hosting.html

@@ -0,0 +1,153 @@
+<!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 build your map</title>
+    <link rel="icon" href="public/images/favicon.svg" type="image/svg+xml">
+</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="#" class="btn btn-light">Talk to the community</a>
+            <a href="#" class="btn">Documentation</a>
+        </div>
+        <script type="module">
+            document.addEventListener("DOMContentLoaded", (event) => {
+                // Load index.js to have access to getMapsList
+                import('/public/assets/js/index.js').then(() => {
+                    window.createBackgroundImageFade();
+                });
+            });
+        </script>
+    </header>
+    <main>
+        <section class="form-center">
+            <h1>
+                Which version of WorkAdventure do you use?
+            </h1>
+            <div class="sub-heading">
+                Choose the setup that matches how your WorkAdventure instance is running. This will help us adapt the publishing process to your setup.
+            </div>
+            <div class="radio-wrapper">
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio">
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            I use self-hosted
+                        </h2>
+                        <div>
+                            Your map is published on your own WorkAdventure instance.
+                            <strong>You manage the hosting, configuration, and updates yourself.</strong>
+                        </div>
+                    </div>
+                </label>
+                <label class="radio-card">
+                    <input name="advanced" class="radio" type="radio">
+                    <div class="card-details">
+                        <svg width="39" height="39" viewBox="0 0 39 39" fill="none" xmlns="http://www.w3.org/2000/svg">
+                            <path d="M8.125 19.5L16.25 27.625L32.5 11.375" stroke="#4156F6" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"/>
+                        </svg>
+
+                        <h2>
+                            I use SaaS version
+                        </h2>
+                        <div>
+                            Your map is published on the WorkAdventure platform.
+                            <strong>We handle hosting, updates, and infrastructure for you.</strong>
+                        </div>
+                    </div>
+                </label>
+            </div>
+
+        </section>
+    </main>
+    <div class="button-wrapper">
+        <div>
+            <a href="step1-git" class="btn btn-ghost">
+                Previous
+            </a>
+        </div>
+        <div style="flex-grow: 1;">
+        </div>
+        <div>
+            <a href="step3-steps" class="btn btn-secondary">
+                Configure
+            </a>
+        </div>
+    </div>
+</div>
+<div class="bg"></div>
+<script>
+    // Get radio buttons by finding the label containing "I use self-hosted"
+    const radioButtons = document.querySelectorAll('input[name="advanced"]');
+    const configureButton = document.querySelector('a[href="step3-steps"]');
+
+    // Find "I use self-hosted" radio button by checking parent label text
+    let selfHostedRadio = null;
+    radioButtons.forEach(radio => {
+        const label = radio.closest('label');
+        if (label && label.textContent.includes('I use self-hosted')) {
+            selfHostedRadio = radio;
+        }
+    });
+
+    // Function to update button href based on selection
+    function updateButtonHref() {
+        // Check if "I use self-hosted" is selected
+        if (selfHostedRadio && selfHostedRadio.checked) {
+            configureButton.href = "step3-steps-selfhosted";
+            configureButton.removeAttribute("target");
+        } else {
+            configureButton.href = "step3-steps";
+            configureButton.removeAttribute("target");
+        }
+    }
+
+    // Add event listeners to all radio buttons
+    radioButtons.forEach(radio => {
+        radio.addEventListener('change', updateButtonHref);
+    });
+
+    // Initialize on page load
+    updateButtonHref();
+</script>
+</body>
+
+</html>