Web kshana.dev

web/ je strom, který GitHub Pages poskytuje jako https://kshana.dev: stránky (index.html, missions.html, capabilities.html, evidence.html, developers.html, editions.html), dokumentace v docs/ a Kshana Studio v studio/ (dostupné na https://kshana.dev/studio/), aplikace, která spouští engine v prohlížeči jako WebAssembly (WASM) bez výpočtů na straně serveru a bez čehokoli nahrávaného. Studio má dva pohledy na jeden engine: jednoduchý pohled (studio/index.html, nejprve odpověď prostými slovy) a pokročilý pohled (studio/advanced/index.html, úplný panel), který s jednoduchým pohledem sdílí engine, worker, moduly a data přes <base href="../">.

Od verze 0.35.0 má Studio čtyři další pohledy, každý jako samostatnou stránku s <base href="../">, bez indexování vyhledávači a s adresářem syntetických vzorků, které čte jeho test:

• studio/trust/: námořní pohled na důvěru, skóre důvěryhodnosti přijímače pro proud poloh plavidla, s ukázkovou stopou v trust/demo/.
• studio/training/: rozbor tréninku posádky, přehrávání syntetického NMEA s událostí rušení, odtažení, podvržení času nebo přehrání (training/demo/).
• studio/interference/: mapa interference a expozice trasy (interference/demo/).
• studio/tools/: jedna stránka karet nástrojů s příklady (tools/examples/, tools/samples/), včetně podepsaných balíčků důkazů (#evidence), exportu pro testovací stolici (#bench), mapování compliance (#compliance), ověřování Galileo OSNMA (#osnma) a kanálů asistenta AI (#ai).

Odkud soubory pocházejí#

Žijí zde tři druhy souborů a mění se třemi různými způsoby.

1. Přenesené soubory. Stránky, docs/, css/, js/, assets/, data webu v data/ (land.json, search.json, series.json) a vše v studio/ zapisuje web/tools/port_site.py ze sestavení webu a ze zdroje Studia. PORT-MANIFEST.json uvádí každý z nich s kontrolním součtem SHA-256 (Secure Hash Algorithm, 256 bitů). Neupravujte je zde: site.test.mjs selže při ruční úpravě. Změňte zdroj a spusťte přenos znovu:

   python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder>
   python3 web/tools/port_site.py --site <built site folder> --studio <Studio folder> --check

   Přenos je deterministický: druhý běh nezapíše nic a --check skončí s kódem 1, pokud web/ neodpovídá tomu, co by přenos zapsal. Beze změny přebírá soubory pro procházení ze sestavení webu (kanonické, sociální karty a značky schema.org každé stránky, robots.txt, sitemap.xml, llms.txt, llms-full.txt), kontroluje je, zapisuje legacy-redirects.js, 404.html a přesměrovací stránku na staré adrese Studia (playground/index.html, na /studio/) a každou stránku nasměruje na místní písma a skriptové knihovny (viz níže).

2. Soubory, které vlastní web/. Jsou to samostatné zdroje a přenos se jich nikdy nedotkne:

   • capabilities.json je strukturovaný zdroj pro karty schopností a mřížku standardů. Upravujte jej, nikoli HTML.
   • data/verification-matrix.json se generuje (cargo run --bin gen_validation_artifacts) a je zajištěn testem tests/verification_artifacts_doc_sync.rs; neupravujte jej ručně. data/card-matrix-map.json, data/oracle-references.json a data/standards-matrix-map.json jsou ručně udržovaná mapování, která tentýž test kontroluje proti vygenerované matici. Kopie Studia v studio/data/ jsou tyto soubory, bajt po bajtu.
   • og-card.svg, og-card.png a og-card.rendered-from.json tvoří sociální kartu (python3 tools/gen_og_card.py).
   • CNAME, .well-known/security.txt, favicon.svg.
   • fonts/ a vendor/: soubory písem a skriptová knihovna, které stránky používají, jednou stažené pomocí tools/fetch_third_party.py a commitnuté (viz „Žádné požadavky na třetí strany“).
   • build.sh, smoke.mjs, site.test.mjs, legacy-urls.test.mjs a tools/.

3. Výstupy sestavení, ignorované gitem a vytvářené pomocí build.sh: pkg/ (balíček wasm-pack, z něhož se sestavuje i balíček npm), studio/pkg/ (týž balíček tam, kde jej Studio importuje) a scenarios/ (každý referenční scénář na adrese, ze které je dřívější jednostránkový web poskytoval).

Sestavení a lokální provoz#

./web/build.sh                     # compiles the WASM module and stages it for the Studio
python3 -m http.server -d web 8000 # serve over HTTP (required for WASM)
# open http://localhost:8000/

Bez nástrojů WASM KSHANA_WASM_PKG=<a built pkg folder> ./web/build.sh místo kompilace připraví existující balíček. Workflow Pages to nikdy nepoužívá.

Testy#

node web/smoke.mjs                 # the WASM bindings (needs web/pkg)
node web/site.test.mjs             # the ported tree: manifest, version, counts, links, inline JSON
node web/tools/inline-json.test.mjs  # the guard for corrupt inline page data (an unescaped version bump)
node web/legacy-urls.test.mjs      # every old kshana.dev address still resolves
for f in web/studio/lib/*.test.mjs; do node "$f"; done   # the Studio's modules

Každý modul v studio/lib/ je čistá logika s odpovídajícím *.test.mjs; ovladače DOM (Document Object Model, strom prvků stránky) Studia jsou studio/app.js (jednoduchý pohled) a studio/advanced.js (pokročilý pohled). Kontinuální integrace spouští každý z nich jako samostatný krok a selže, pokud testovací soubor v web/ nemá krok.

Žádné požadavky na třetí strany#

kshana.dev poskytuje vlastní písma, styly a skripty. Stránka nevysílá žádný požadavek na hostitele písem ani skriptů, takže adresa návštěvníka není žádnému z nich předána.

Web a Studio jsou psány pro Google Fonts a hostitele skriptů. Přenos nahradí odkaz na Google Fonts na každé stránce odpovídající šablonou stylů v fonts/ (stejná pravidla @font-face a stejné soubory písem, každá podmnožina, takže se text vykresluje jako dříve) a každou adresu hostitele skriptů souborem v vendor/. fonts/FONTS.json a vendor/VENDOR.json zaznamenávají, odkud každý soubor pochází, a jeho kontrolní součet; písma jsou pod licencí SIL Open Font License (fonts/OFL-*.txt) a three.js pod licencí MIT (vendor/three@…/LICENSE).

tools/fetch_third_party.py --from <site folder> --from <Studio folder> je jediný krok, který používá síť. Spusťte jej znovu, až když stránka žádá sadu písem nebo verzi knihovny, která zde není: přenos odmítne a oznámí to. site.test.mjs selže, pokud kterákoli přenesená stránka, šablona stylů nebo skript uvádí hostitele písem nebo načítá cokoli z jiného hostitele.

Stránka 404#

GitHub Pages odpovídá na chybějící adresu stránkou /404.html a stavem 404. Přenos tuto stránku vytvoří z vlastního rámce domovské stránky (navigace, patička, hledání) kolem krátké zprávy s odkazy na Domů, Dokumentaci a Studio. Každá adresa v ní je psána od kořene webu, protože se poskytuje v libovolné hloubce.

Staré adresy#

Do v0.28.0 byl web jedinou stránkou a vše žilo za fragmentem na / (/#playground, /#ledger, sdílené odkazy jako /#s=…, vložení jako /?embed=1&…; starý název karty v odkazu vložení, například tab=fom, otevře kartu Studia, která ji nahradila). tools/legacy-urls.json uvádí každou takovou adresu, kterou zveřejněné materiály používají, a kam dnes vede; domovská stránka načítá legacy-redirects.js, vygenerovaný z tohoto seznamu, aby je tam odeslala. Před vyřazením jakékoli adresy přidejte do seznamu případ.

Nasazení#

Workflow GitHub Actions pages nasazuje značku vydání, nikoli main: release.yml jej spustí po zveřejnění vydání a ruční spuštění znovu nasadí pojmenovanou značku. Spouští build.sh, připraví web/ bez testů, skriptu sestavení, tools/, manifestu a tohoto souboru a výsledek publikuje na GitHub Pages.