@hexah/create-skin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hexah Team
+
+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,34 @@
+# @hexah/create-skin
+
+Scaffolder skórki Hexah — generuje projekt **zdalnej skórki Module Federation** (rspack +
+`@hexah/skin-sdk`) z gotowym workflowem dev (HMR) i podłączeniem do hosta na środowisku
+testowym.
+
+## Użycie
+
+```bash
+npm create @hexah/skin moja-skorka     # albo: npx @hexah/create-skin moja-skorka
+cd moja-skorka
+npm install
+npm run dev        # rspack serve z HMR
+```
+
+Następnie podłącz remote do hosta na teście (instrukcja w wygenerowanym `README.md` skórki):
+`localStorage["hexah.skinRemote"]` + motyw „SDK Remote (zdalna skórka)".
+
+## Co generuje
+
+Starter (`template/`) z placeholderami `__SKIN_NAME__` / `__SKIN_FEDERATION_NAME__`:
+
+- `rspack.config.js` — `ModuleFederationPlugin` wystawiający `./ReportScreen`, paczki
+  współdzielone z hostem (`import: false`), dev server na `:3001` z CORS.
+- `src/ReportScreen.jsx` — przykładowy ekran na `@hexah/skin-sdk`.
+- `package.json`, `.gitignore`, `README.md`.
+
+Nazwa kontenera MF jest sanityzowana z nazwy katalogu (`toFederationName` — identyfikator JS).
+
+## Status
+
+POC etapu C. Publikowany jako `@hexah/create-skin` (licencja MIT) przez ręczny workflow —
+patrz `docs/skin-sdk/publishing.md`. Przed publikacją działa tylko z repo
+(`node packages/create-hexah-skin/index.js <katalog>`). Pełne demo wymaga środowiska testowego.

package/index.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+"use strict";
+
+/**
+ * create-hexah-skin — scaffolder skórki Hexah (zdalny kontener Module Federation).
+ * Użycie: `npx create-hexah-skin <katalog>` (lub `node index.js <katalog>`).
+ *
+ * Tworzy projekt skórki ze startera (rspack + MF + `@hexah/skin-sdk`) i wypisuje kolejne
+ * kroki: `npm run dev` (rspack serve z HMR) oraz jak podłączyć remote do hosta na teście.
+ */
+
+const fs = require("fs");
+const path = require("path");
+const { toFederationName, copyTemplate } = require("./lib/scaffold");
+
+/** @param {string[]} argv @returns {number} kod wyjścia */
+function main(argv) {
+  const target = argv[2];
+  if (!target) {
+    console.error("Użycie: create-hexah-skin <katalog>");
+    return 1;
+  }
+  const destDir = path.resolve(process.cwd(), target);
+  if (fs.existsSync(destDir) && fs.readdirSync(destDir).length > 0) {
+    console.error(`Katalog „${target}" istnieje i nie jest pusty — przerywam.`);
+    return 1;
+  }
+
+  const skinName = path.basename(destDir);
+  const federationName = toFederationName(skinName);
+  const templateDir = path.join(__dirname, "template");
+  copyTemplate(templateDir, destDir, { skinName, federationName });
+
+  console.log(`✓ Skórka „${skinName}" utworzona w ${target}`);
+  console.log("");
+  console.log("Dalej:");
+  console.log(`  cd ${target}`);
+  console.log("  npm install");
+  console.log("  npm run dev        # rspack serve z HMR (np. http://localhost:3001/remoteEntry.js)");
+  console.log("");
+  console.log("Podłączenie do hosta (środowisko testowe) — w konsoli przeglądarki:");
+  console.log(
+    `  localStorage.setItem('hexah.skinRemote', JSON.stringify({ name: '${federationName}',`,
+  );
+  console.log(
+    "    entry: 'http://localhost:3001/remoteEntry.js', template: 'sdkremote',",
+  );
+  console.log("    screens: { report: './ReportScreen' }, apiVersion: '0.2.0' }))");
+  console.log("Następnie w Ustawieniach Gry wybierz motyw „SDK Remote (zdalna skórka)\".");
+  return 0;
+}
+
+if (require.main === module) {
+  process.exit(main(process.argv));
+}
+
+module.exports = { main };

package/lib/scaffold.js

@@ -0,0 +1,75 @@
+"use strict";
+
+/**
+ * Czyste funkcje scaffoldu skórki — łatwe do testu, bez efektów sieciowych.
+ * CLI (`../index.js`) tylko spina je z argv i FS.
+ */
+
+const fs = require("fs");
+const path = require("path");
+
+/** Pliki template'u zapisane z prefiksem `_`, by nie kolidować z narzędziami repo. */
+const RENAME = Object.freeze({
+  "_package.json": "package.json",
+  "_gitignore": ".gitignore",
+});
+
+/**
+ * Sanityzuje nazwę skórki do poprawnej nazwy kontenera Module Federation
+ * (identyfikator JS: małe litery, cyfry, `_`; nie zaczyna się od cyfry).
+ * @param {string} skinName
+ * @returns {string}
+ */
+function toFederationName(skinName) {
+  const cleaned = String(skinName)
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  const base = cleaned || "skin";
+  return /^[0-9]/.test(base) ? `skin_${base}` : base;
+}
+
+/**
+ * Podstawia placeholdery template'u.
+ * @param {string} content
+ * @param {{ skinName: string, federationName: string }} vars
+ * @returns {string}
+ */
+function applyPlaceholders(content, vars) {
+  return content
+    .replace(/__SKIN_NAME__/g, vars.skinName)
+    .replace(/__SKIN_FEDERATION_NAME__/g, vars.federationName);
+}
+
+/** @param {string} file @returns {boolean} czy traktować jako tekst (placeholdery). */
+function isTextFile(file) {
+  return /\.(js|jsx|json|md|txt)$/.test(file) || file === "_gitignore" || file === "_package.json";
+}
+
+/**
+ * Kopiuje template do katalogu docelowego, podstawiając placeholdery i zmieniając nazwy
+ * z mapy {@link RENAME}. Zwraca listę zapisanych ścieżek.
+ * @param {string} srcDir
+ * @param {string} destDir
+ * @param {{ skinName: string, federationName: string }} vars
+ * @returns {string[]}
+ */
+function copyTemplate(srcDir, destDir, vars) {
+  fs.mkdirSync(destDir, { recursive: true });
+  const written = [];
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const src = path.join(srcDir, entry.name);
+    const dest = path.join(destDir, RENAME[entry.name] || entry.name);
+    if (entry.isDirectory()) {
+      written.push(...copyTemplate(src, dest, vars));
+      continue;
+    }
+    const raw = fs.readFileSync(src, "utf8");
+    fs.writeFileSync(dest, isTextFile(entry.name) ? applyPlaceholders(raw, vars) : raw);
+    written.push(dest);
+  }
+  return written;
+}
+
+module.exports = { RENAME, toFederationName, applyPlaceholders, isTextFile, copyTemplate };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@hexah/create-skin",
+  "version": "0.1.0",
+  "description": "Scaffolder skórki Hexah (zdalny kontener Module Federation, harness dev z HMR).",
+  "bin": {
+    "create-hexah-skin": "index.js"
+  },
+  "main": "index.js",
+  "license": "MIT",
+  "author": "Hexah Team <kontakt@hexah.pl>",
+  "homepage": "https://github.com/Kroniki-Fallathanu/hexah/tree/develop/packages/create-hexah-skin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Kroniki-Fallathanu/hexah.git",
+    "directory": "packages/create-hexah-skin"
+  },
+  "keywords": [
+    "hexah",
+    "skin",
+    "create",
+    "scaffold",
+    "module-federation"
+  ],
+  "engines": {
+    "node": ">=20.16.0"
+  },
+  "files": [
+    "index.js",
+    "lib",
+    "template",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test"
+  }
+}

package/template/README.md

@@ -0,0 +1,41 @@
+# __SKIN_NAME__
+
+Skórka Hexah zbudowana jako **zdalny kontener Module Federation**. Działa na realnej
+aplikacji Hexah (host) podpiętej do środowiska testowego — bez dostępu do kodu gry.
+
+## Start
+
+```bash
+npm install
+npm run dev        # rspack serve z HMR → http://localhost:3001/remoteEntry.js
+```
+
+## Podłączenie do hosta (środowisko testowe)
+
+W konsoli przeglądarki na środowisku testowym Hexah:
+
+```js
+localStorage.setItem('hexah.skinRemote', JSON.stringify({
+  name: '__SKIN_FEDERATION_NAME__',
+  entry: 'http://localhost:3001/remoteEntry.js',
+  template: 'sdkremote',
+  screens: { report: './ReportScreen' },
+  apiVersion: '0.2.0',
+}))
+```
+
+Odśwież, w **Ustawieniach Gry** wybierz motyw **„SDK Remote (zdalna skórka)"** i wejdź na ekran
+zgłoszeń — zobaczysz swój `ReportScreen` na realnych danych. Dzięki HMR zmiany w `src/` są
+widoczne po odświeżeniu (rebuild remote'a).
+
+## Co możesz edytować
+
+- `src/ReportScreen.jsx` — Twój ekran. Importuj wyłącznie z `@hexah/skin-sdk` (+ React/MUI).
+- `rspack.config.js` → `exposes` — dołóż kolejne ekrany (klucze z `SCREEN_KEYS`).
+
+## Zasady
+
+- Importuj tylko z `@hexah/skin-sdk` — to publiczny kontrakt (stałe, typy, hooki, UI).
+- Pakiety react/jotai/@mui/@emotion/@hexah/skin-sdk są współdzielone (`import: false`) —
+  nie pakujesz ich, bierzesz instancje hosta.
+- Host ładuje skórkę tylko z dozwolonych originów i przy zgodnym `apiVersion`.

package/template/_gitignore

@@ -0,0 +1,4 @@
+node_modules
+dist
+.DS_Store
+*.log

package/template/_package.json

@@ -0,0 +1,23 @@
+{
+  "name": "__SKIN_NAME__",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Skórka Hexah (zdalny kontener Module Federation).",
+  "scripts": {
+    "build": "rspack build",
+    "dev": "rspack serve",
+    "serve": "rspack serve"
+  },
+  "dependencies": {
+    "@hexah/skin-sdk": "^0.2.0"
+  },
+  "devDependencies": {
+    "@module-federation/enhanced": "^0.9.0",
+    "@rspack/cli": "^1.1.0",
+    "@rspack/core": "^1.1.0"
+  },
+  "peerDependencies": {
+    "react": "^19",
+    "react-dom": "^19"
+  }
+}

package/template/rspack.config.js

@@ -0,0 +1,56 @@
+// @ts-nocheck
+/**
+ * Build skórki „__SKIN_NAME__" jako zdalnego kontenera Module Federation.
+ *
+ * Pakiety react/jotai/@mui/@emotion/@hexah/skin-sdk są współdzielone z `import: false` —
+ * skórka ich NIE pakuje, konsumuje instancje hosta przez shareScope (jeden React, jeden
+ * store Jotai, jeden ThemeProvider). Wynik: `dist/remoteEntry.js`.
+ */
+const { ModuleFederationPlugin } = require("@module-federation/enhanced/rspack");
+
+const singleton = (requiredVersion) => ({
+  singleton: true,
+  import: false,
+  requiredVersion,
+});
+
+module.exports = {
+  mode: "production",
+  entry: {},
+  output: { publicPath: "auto", uniqueName: "__SKIN_FEDERATION_NAME__" },
+  resolve: { extensions: [".js", ".jsx"] },
+  module: {
+    rules: [
+      {
+        test: /\.jsx?$/,
+        use: {
+          loader: "builtin:swc-loader",
+          options: {
+            jsc: {
+              parser: { syntax: "ecmascript", jsx: true },
+              transform: { react: { runtime: "automatic" } },
+            },
+          },
+        },
+      },
+    ],
+  },
+  plugins: [
+    new ModuleFederationPlugin({
+      name: "__SKIN_FEDERATION_NAME__",
+      filename: "remoteEntry.js",
+      exposes: { "./ReportScreen": "./src/ReportScreen.jsx" },
+      shared: {
+        react: singleton("^19"),
+        "react-dom": singleton("^19"),
+        jotai: singleton("^2"),
+        "@emotion/react": singleton("^11"),
+        "@emotion/styled": singleton("^11"),
+        "@mui/material": singleton("^7"),
+        "@mui/material/styles": singleton("^7"),
+        "@hexah/skin-sdk": singleton("^0.2"),
+      },
+    }),
+  ],
+  devServer: { port: 3001, headers: { "Access-Control-Allow-Origin": "*" } },
+};

package/template/src/ReportScreen.jsx

@@ -0,0 +1,71 @@
+/**
+ * Ekran skórki „__SKIN_NAME__" — importuje WYŁĄCZNIE z `@hexah/skin-sdk` (+ React/MUI jako
+ * współdzielone singletony hosta). Host ładuje go w runtime i rejestruje pod `SCREEN_KEYS.REPORT`.
+ *
+ * Edytuj swobodnie — to Twój punkt startowy. Read-modele (`useReports`…) i prymitywy UI
+ * (`PageBox`, `DataList`, `HexahChip`) dostarcza host; tu masz tylko ich kontrakt.
+ */
+import { useEffect, useMemo, useState } from "react";
+import Box from "@mui/material/Box";
+import Typography from "@mui/material/Typography";
+import {
+  PageBox,
+  DataList,
+  HexahChip,
+  useReports,
+  useSnackbar,
+  useGamePageShell,
+} from "@hexah/skin-sdk";
+
+export default function ReportScreen() {
+  const reports = useReports();
+  const { notify } = useSnackbar();
+  const [issues, setIssues] = useState([]);
+  useGamePageShell(useMemo(() => ({ title: "Zgłoszenia (__SKIN_NAME__)" }), []));
+
+  useEffect(() => {
+    reports.list({
+      page: 1,
+      pageSize: 10,
+      callback: (ret) => {
+        if (ret?.error) {
+          notify([{ severity: "error", message: ret.error }]);
+          return;
+        }
+        setIssues(ret.issues || []);
+      },
+    });
+  }, [reports, notify]);
+
+  const items = useMemo(
+    () =>
+      issues.map((issue) => ({
+        id: issue.id,
+        title: `#${issue.issueNumber} ${issue.title}`,
+        chips: (
+          <HexahChip
+            label={issue.state === "closed" ? "Zamknięte" : "Otwarte"}
+            size="small"
+          />
+        ),
+      })),
+    [issues],
+  );
+
+  return (
+    <PageBox>
+      <Box sx={{ px: { xs: 2, sm: 3 }, pt: 2 }}>
+        <Typography variant="body2" sx={{ mb: 2, opacity: 0.8 }}>
+          Skórka „__SKIN_NAME__" (Module Federation) na realnych danych test backendu hosta.
+        </Typography>
+        {items.length === 0 ? (
+          <Typography color="primary" sx={{ py: 2 }}>
+            Brak zgłoszeń do wyświetlenia.
+          </Typography>
+        ) : (
+          <DataList disableListItemAvatar itemsList={items} />
+        )}
+      </Box>
+    </PageBox>
+  );
+}