TypeScript, in layers, with a strict linter

The client was one main.js, one preload.js, three files in lib/ and one renderer
script. It is now a typed application whose imports point inward: domain (models,
ports, errors) knows nothing about Electron, Node or Python; application orchestrates
it through those ports; infrastructure holds the adapters — the Python CLI, HTTP, the
filesystem, Electron itself — and main, preload and renderer sit on top as hosts.

STRUCTURE.md is the map, and the deliverable as much as the code is: every layer, every
pattern in use (ports and adapters, repository vs gateway, service, DTO and mapper,
composition root, controller and router, single flight, observer streams, state store
with unidirectional flow, passive view, coded error hierarchy, frozen constant tables,
untrusted-data readers) and the naming rules — files, classes, and a verb vocabulary
for methods where find/require/read/list/apply/render/handle each state a contract.

Two properties fell out of the move, and they are why it was worth doing:

  - The catalog can be driven with no window and no Electron at all. The smoke test
    assembles the same services against the same ports in a plain Node process; it used
    to be a script that reimplemented the bridge.
  - The window never receives a filesystem path. A title crosses the bridge without
    one, and launching is asked for by name, resolved in the main process from the
    store's own state. Verified with a fake launcher: an unknown name answers false, a
    native title resolves to its menu entry, a hosted one to its catalog URL.

Types are mandatory, including where inference would manage: explicit return,
parameter and property types, strict plus noUncheckedIndexedAccess,
exactOptionalPropertyTypes, noImplicitOverride and noPropertyAccessFromIndexSignature,
typescript-eslint strictTypeChecked and stylisticTypeChecked, exhaustive switches, no
any, no non-null assertions, and no casts on foreign data — engine stdout and the
registry go through readers that turn unknown into typed values. naming-convention
enforces the patterns rather than trusting them.

Two rule conflicts had to be decided rather than papered over. typedef and
no-inferrable-types disagree about `fallback: string = ''`: the annotation wins, since a
signature states its types. erasableSyntaxOnly is off, because it forbids constructor
parameter properties, which are how dependencies are declared here.

The preload and the renderer are bundled by esbuild into one file each: a sandboxed
preload may not require its own modules, and a module script over file:// is blocked by
the page's own origin rules. tsc compiles the rest. The package ships build/** and
package.json — 111 entries, no sources, no toolchain.

New targets: build, typecheck, lint, lint-fix, and check — typecheck, lint, then both
test suites, cheapest failure first. Every script that runs the app builds first, so a
stale bundle cannot be tested.

Nothing about the window changed: same side menu, same categories, same switcher, same
two languages. make check is clean, both test suites pass with one store and with two,
the packaged 1.3.0 bundle drives the real store, and the window was photographed before
and after — the two are the same picture.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

src/shared/contracts/BridgeApi.ts

@@ -0,0 +1,46 @@
+import type { AppStateDto } from './dto/AppStateDto'
+import type { CatalogListingDto } from './dto/CatalogListingDto'
+import type { InstalledStoreDto } from './dto/InstalledStoreDto'
+import type { LocaleSelectionDto } from './dto/LocaleSelectionDto'
+import type { RegistryResultDto } from './dto/RegistryResultDto'
+import type { RegistryStoreDto } from './dto/RegistryStoreDto'
+import type { StorePathsDto } from './dto/StorePathsDto'
+import type { StoreSelectionDto } from './dto/StoreSelectionDto'
+import type { SyncEventDto } from './dto/SyncEventDto'
+
+/** A stream the main process pushes; the window subscribes and never replies. */
+export type StreamListener<TPayload> = (payload: TPayload) => void
+
+/**
+ * The entire surface the window gets.
+ *
+ * Nothing else reaches it: no Node, no filesystem, no child processes. Both sides
+ * compile against this interface, so a method the preload does not expose is a
+ * compile error in the renderer rather than an `undefined is not a function` at
+ * runtime.
+ */
+export interface BridgeApi {
+  readState: () => Promise<AppStateDto>
+  updateLocale: (locale: string) => Promise<LocaleSelectionDto>
+  updateNavOpen: (open: boolean) => Promise<boolean>
+
+  listGames: () => Promise<CatalogListingDto>
+  readPaths: () => Promise<StorePathsDto>
+  syncGames: (names: readonly string[]) => Promise<void>
+  removeGame: (name: string) => Promise<void>
+  launchGame: (name: string) => Promise<boolean>
+
+  listRegistryStores: () => Promise<RegistryResultDto>
+  installStore: (store: RegistryStoreDto) => Promise<InstalledStoreDto>
+  selectStore: (home: string) => Promise<StoreSelectionDto>
+
+  openFolder: (directory: string) => Promise<boolean>
+  openUrl: (url: string) => Promise<boolean>
+
+  onLog: (listener: StreamListener<string>) => void
+  onSyncEvent: (listener: StreamListener<SyncEventDto>) => void
+  onBusyChanged: (listener: StreamListener<boolean>) => void
+}
+
+/** The name the bridge is published under on `window`. */
+export const BRIDGE_GLOBAL_NAME = 'storeApi'

src/shared/contracts/IpcChannels.ts

@@ -0,0 +1,32 @@
+/**
+ * Every channel name, in one frozen table.
+ *
+ * The pattern is `<domain>:<verb><Subject>` — the same verbs the services use, so
+ * a channel, the bridge method it backs and the service call behind it read as one
+ * sentence. Renderer and main both import this table; a typo cannot make a channel
+ * that only one side knows about.
+ */
+export const IPC_CHANNELS = {
+  appReadState: 'app:readState',
+  appUpdateLocale: 'app:updateLocale',
+  appUpdateNavOpen: 'app:updateNavOpen',
+  appOpenFolder: 'app:openFolder',
+  appOpenUrl: 'app:openUrl',
+
+  catalogListGames: 'catalog:listGames',
+  catalogReadPaths: 'catalog:readPaths',
+  catalogSyncGames: 'catalog:syncGames',
+  catalogRemoveGame: 'catalog:removeGame',
+  catalogLaunchGame: 'catalog:launchGame',
+
+  storeListRegistry: 'store:listRegistry',
+  storeInstallStore: 'store:installStore',
+  storeSelectStore: 'store:selectStore',
+
+  /** Main to renderer, one way. */
+  streamLog: 'stream:log',
+  streamSyncEvent: 'stream:syncEvent',
+  streamBusyChanged: 'stream:busyChanged'
+} as const
+
+export type IpcChannel = (typeof IPC_CHANNELS)[keyof typeof IPC_CHANNELS]

src/shared/contracts/dto/AppStateDto.ts

@@ -0,0 +1,21 @@
+import type { Locale } from '../../i18n/MessageBundle'
+import type { MessageBundle } from '../../i18n/MessageBundle'
+import type { EngineVersionDto } from './EngineVersionDto'
+import type { InstalledStoreDto } from './InstalledStoreDto'
+
+/** Everything the window needs before it can paint anything. */
+export interface AppStateDto {
+  readonly locale: Locale
+  readonly locales: readonly Locale[]
+  readonly messages: MessageBundle
+  readonly navigationOpen: boolean
+  /** The Python 3 version string, or null when there is none to drive the store. */
+  readonly pythonVersion: string | null
+  readonly currentStore: InstalledStoreDto | null
+  readonly stores: readonly InstalledStoreDto[]
+  readonly engine: EngineVersionDto | null
+  readonly minimumEngineVersion: string
+  readonly registryUrl: string
+  readonly defaultStoreRoot: string
+  readonly appVersion: string
+}

src/shared/contracts/dto/CatalogListingDto.ts

@@ -0,0 +1,9 @@
+import type { GameDto } from './GameDto'
+import type { StorePathsDto } from './StorePathsDto'
+
+/** One `listGames` answer: what the catalog offers, and what was left out. */
+export interface CatalogListingDto {
+  readonly games: readonly GameDto[]
+  readonly skipped: readonly string[]
+  readonly paths: StorePathsDto | null
+}

src/shared/contracts/dto/EngineVersionDto.ts

@@ -0,0 +1,5 @@
+/** The installed engine's version, and whether this client can drive it. */
+export interface EngineVersionDto {
+  readonly text: string
+  readonly supported: boolean
+}

src/shared/contracts/dto/GameDto.ts

@@ -0,0 +1,26 @@
+/** How a title runs: unpacked on this machine, or served as a web build. */
+export type GameModeDto = 'app' | 'web'
+
+/**
+ * A catalog entry as the window needs it.
+ *
+ * Deliberately free of filesystem paths: what to launch is resolved in the main
+ * process from the store's own state, so the window never learns where anything
+ * lives and cannot be talked into opening it.
+ */
+export interface GameDto {
+  readonly name: string
+  readonly title: string
+  readonly platform: string
+  readonly version: string
+  readonly mode: GameModeDto
+  readonly kind: string
+  readonly description: string
+  readonly author: string
+  /** Absolute, already resolved against the catalog's base URL. */
+  readonly imageUrl: string | null
+  readonly installed: boolean
+  readonly updateAvailable: boolean
+  readonly installedVersion: string | null
+  readonly launchable: boolean
+}

src/shared/contracts/dto/InstalledStoreDto.ts

@@ -0,0 +1,7 @@
+/** A store on this machine, as the switcher lists it. */
+export interface InstalledStoreDto {
+  readonly id: string
+  readonly name: string
+  readonly home: string
+  readonly engine: string
+}

src/shared/contracts/dto/LocaleSelectionDto.ts

@@ -0,0 +1,7 @@
+import type { Locale, MessageBundle } from '../../i18n/MessageBundle'
+
+/** The answer to a language change: what was stored, and the strings for it. */
+export interface LocaleSelectionDto {
+  readonly locale: Locale
+  readonly messages: MessageBundle
+}

src/shared/contracts/dto/RegistryResultDto.ts

@@ -0,0 +1,14 @@
+import type { RegistryStoreDto } from './RegistryStoreDto'
+
+/**
+ * The registry lookup, failure included.
+ *
+ * The window has to say *why* there is nothing to install — an unreachable site
+ * and an empty list need different words — so the error travels as data rather
+ * than as a rejected promise.
+ */
+export interface RegistryResultDto {
+  readonly stores: readonly RegistryStoreDto[]
+  readonly sourceUrl: string
+  readonly error: string | null
+}

src/shared/contracts/dto/RegistryStoreDto.ts

@@ -0,0 +1,8 @@
+/** A store the registry offers, before anything is installed. */
+export interface RegistryStoreDto {
+  readonly name: string
+  readonly catalogUrl: string
+  readonly storeRepositoryUrl: string
+  /** Derived from the repository name, so the picker can show what it will become. */
+  readonly storeId: string
+}

src/shared/contracts/dto/StorePathsDto.ts

@@ -0,0 +1,10 @@
+/** Where a store puts things on this machine, as the log drawer reports it. */
+export interface StorePathsDto {
+  readonly operatingSystem: string
+  readonly architecture: string
+  readonly storeFolder: string
+  readonly menuGroup: string
+  readonly catalogBaseUrl: string
+  readonly storeName: string
+  readonly storeId: string
+}

src/shared/contracts/dto/StoreSelectionDto.ts

@@ -0,0 +1,8 @@
+import type { EngineVersionDto } from './EngineVersionDto'
+import type { InstalledStoreDto } from './InstalledStoreDto'
+
+/** The answer to a store switch: which store is open, and can it be driven. */
+export interface StoreSelectionDto {
+  readonly store: InstalledStoreDto
+  readonly engine: EngineVersionDto | null
+}

src/shared/contracts/dto/SyncEventDto.ts

@@ -0,0 +1,15 @@
+/**
+ * One line of the engine's progress stream.
+ *
+ * The engine emits JSONL on stdout; these are the events the window reacts to.
+ * `plan` gives the count, `begin`/`installed` drive the counter, and the rest end
+ * up in the log drawer.
+ */
+export type SyncEventDto =
+  | { readonly event: 'plan'; readonly count: number }
+  | { readonly event: 'begin'; readonly name: string; readonly title: string }
+  | { readonly event: 'installed'; readonly name: string; readonly title: string; readonly changed: boolean }
+  | { readonly event: 'failed'; readonly name: string; readonly error: string }
+  | { readonly event: 'removed'; readonly name: string }
+  | { readonly event: 'pruned'; readonly name: string }
+  | { readonly event: 'finished'; readonly installed: number; readonly failed: number }

src/shared/i18n/EnglishMessages.ts

@@ -0,0 +1,63 @@
+/**
+ * The English message bundle, and the source of the key set.
+ *
+ * Every other language is typed against these keys, so a missing or misspelled
+ * translation is a compile error rather than a blank label at runtime.
+ */
+export const ENGLISH_MESSAGES = {
+  appName: 'WarpEngine Store',
+  syncAll: 'Install all',
+  refresh: 'Refresh',
+  install: 'Install',
+  update: 'Update',
+  play: 'Play',
+  open: 'Open',
+  remove: 'Remove',
+  installed: 'installed',
+  native: 'native',
+  hosted: 'hosted',
+  hostedHint: 'Opens in your browser — needs the network',
+  nativeHint: 'Installed on this machine — works offline',
+  updateAvailable: 'update available',
+  log: 'Log',
+  menu: 'Menu',
+  stores: 'Stores',
+  addStore: 'Add a store…',
+  switchFailed: 'That store could not be opened',
+  actions: 'Actions',
+  categories: 'Categories',
+  catAll: 'Everything',
+  catInstalled: 'Installed',
+  catUpdates: 'Updates',
+  catAvailable: 'Not installed',
+  catPlatform: 'Platform',
+  catMode: 'Kind',
+  language: 'Language',
+  noGames: 'No installable titles in the catalog.',
+  noMatch: 'Nothing in this category.',
+  setupTitle: 'Set up a store',
+  setupBody: 'No store on this machine yet. Pick one and it will be downloaded — the same files the shell installer would place, in the same folder.',
+  setupAction: 'Download the store',
+  setupWorking: 'Setting up…',
+  setupChoose: 'Store',
+  registryFailed: 'The list of stores could not be fetched',
+  registryEmpty: 'The list of stores came back empty. Nothing to install from yet.',
+  registryRetry: 'Try again',
+  oldEngineTitle: 'The store needs refreshing',
+  oldEngineBody: 'The store engine on this machine is older than this client can drive. Refreshing it downloads the current engine and keeps your settings and installed games.',
+  oldEngineAction: 'Refresh the store',
+  noPythonTitle: 'Python 3 is required',
+  noPythonBody: 'The store is a Python program, so Python 3 has to be installed. Install it, then reopen this window.',
+  pythonLink: 'python.org/downloads',
+  paths: 'Where things go',
+  openStoreFolder: 'Open the store folder',
+  openMenuFolder: 'Open the menu folder',
+  busy: 'Working…',
+  failed: 'failed',
+  removed: 'removed',
+  upToDate: 'Everything is up to date.',
+  of: 'of'
+} as const
+
+/** Every string the window can show, by key. */
+export type MessageKey = keyof typeof ENGLISH_MESSAGES

src/shared/i18n/HungarianMessages.ts

@@ -0,0 +1,60 @@
+import type { MessageBundle } from './MessageBundle'
+
+/**
+ * Hungarian. Catalog text — titles, descriptions — is never translated here: it
+ * arrives from the store as it was published.
+ */
+export const HUNGARIAN_MESSAGES: MessageBundle = {
+  appName: 'WarpEngine Store',
+  syncAll: 'Mind telepítése',
+  refresh: 'Frissítés',
+  install: 'Telepítés',
+  update: 'Frissítés',
+  play: 'Indítás',
+  open: 'Megnyitás',
+  remove: 'Eltávolítás',
+  installed: 'telepítve',
+  native: 'natív',
+  hosted: 'hosztolt',
+  hostedHint: 'A böngészőben nyílik meg — internet kell hozzá',
+  nativeHint: 'Erre a gépre telepítve — internet nélkül is megy',
+  updateAvailable: 'frissítés elérhető',
+  log: 'Napló',
+  menu: 'Menü',
+  stores: 'Store-ok',
+  addStore: 'Store hozzáadása…',
+  switchFailed: 'Ez a store nem nyitható meg',
+  actions: 'Műveletek',
+  categories: 'Kategóriák',
+  catAll: 'Minden',
+  catInstalled: 'Telepítve',
+  catUpdates: 'Frissítés',
+  catAvailable: 'Nincs telepítve',
+  catPlatform: 'Platform',
+  catMode: 'Fajta',
+  language: 'Nyelv',
+  noGames: 'Nincs telepíthető cím a katalógusban.',
+  noMatch: 'Ebben a kategóriában nincs semmi.',
+  setupTitle: 'Store beállítása',
+  setupBody: 'Ezen a gépen még nincs store. Válassz egyet, és letöltöm — ugyanazokat a fájlokat, ugyanabba a könyvtárba, ahová a shell-telepítő tenné.',
+  setupAction: 'Store letöltése',
+  setupWorking: 'Beállítás…',
+  setupChoose: 'Store',
+  registryFailed: 'A store-ok listája nem érhető el',
+  registryEmpty: 'A store-ok listája üresen jött vissza. Egyelőre nincs miből telepíteni.',
+  registryRetry: 'Újra',
+  oldEngineTitle: 'A store frissítésre vár',
+  oldEngineBody: 'A gépen lévő store-motor régebbi, mint amit ez a kliens vezérelni tud. A frissítés letölti a mostani motort, a beállításaid és a telepített játékok pedig megmaradnak.',
+  oldEngineAction: 'Store frissítése',
+  noPythonTitle: 'Python 3 kell hozzá',
+  noPythonBody: 'A store egy Python program, tehát Python 3 kell a gépre. Telepítsd, majd nyisd meg újra ezt az ablakot.',
+  pythonLink: 'python.org/downloads',
+  paths: 'Hova kerül',
+  openStoreFolder: 'Store könyvtár megnyitása',
+  openMenuFolder: 'Menü könyvtár megnyitása',
+  busy: 'Dolgozom…',
+  failed: 'hiba',
+  removed: 'eltávolítva',
+  upToDate: 'Minden naprakész.',
+  of: '/'
+}

src/shared/i18n/MessageBundle.ts

@@ -0,0 +1,9 @@
+import type { MessageKey } from './EnglishMessages'
+
+/** One complete language. Partial bundles are not a thing: the type forbids them. */
+export type MessageBundle = Readonly<Record<MessageKey, string>>
+
+/** The languages the window speaks. The public site has the same two. */
+export const LOCALES = ['en', 'hu'] as const
+
+export type Locale = (typeof LOCALES)[number]

src/shared/i18n/TranslationCatalog.ts

@@ -0,0 +1,30 @@
+import { ENGLISH_MESSAGES } from './EnglishMessages'
+import { HUNGARIAN_MESSAGES } from './HungarianMessages'
+import { LOCALES, type Locale, type MessageBundle } from './MessageBundle'
+
+const BUNDLES: Readonly<Record<Locale, MessageBundle>> = {
+  en: ENGLISH_MESSAGES,
+  hu: HUNGARIAN_MESSAGES
+}
+
+const FALLBACK_LOCALE: Locale = 'en'
+
+/**
+ * Which language, and its strings.
+ *
+ * Used on both sides of the bridge: the main process resolves the locale and
+ * ships the bundle, the window renders from it.
+ */
+export class TranslationCatalog {
+  public readonly locales: readonly Locale[] = LOCALES
+
+  /** A system locale like `hu-HU`, or anything at all, mapped onto a language. */
+  public resolveLocale (candidate: string | null | undefined): Locale {
+    const short = (candidate ?? '').slice(0, 2).toLowerCase()
+    return LOCALES.find((locale: Locale): boolean => locale === short) ?? FALLBACK_LOCALE
+  }
+
+  public readBundle (candidate: string | null | undefined): MessageBundle {
+    return BUNDLES[this.resolveLocale(candidate)]
+  }
+}