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>

scripts/build-assets.mjs

@@ -0,0 +1,54 @@
+// The two bundles and the two static files.
+//
+// tsc compiles the main process, where CommonJS and `require` are fine. The preload
+// and the renderer cannot work that way: a sandboxed preload may not require its own
+// modules, and a module script over file:// is blocked by the page's own origin
+// rules. So both are bundled into one file each — the layering stays in src/, the
+// window gets a single script.
+import { build } from 'esbuild'
+import { copyFile, mkdir } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = dirname(dirname(fileURLToPath(import.meta.url)))
+const outDir = join(root, 'build')
+
+const bundles = [
+  {
+    label: 'preload',
+    entryPoints: [join(root, 'src/preload/preload.ts')],
+    outfile: join(outDir, 'preload/preload.js'),
+    platform: 'node',
+    format: 'cjs',
+    // Provided by Electron at runtime; bundling it would break the sandbox.
+    external: ['electron']
+  },
+  {
+    label: 'renderer',
+    entryPoints: [join(root, 'src/renderer/main.ts')],
+    outfile: join(outDir, 'renderer/app.js'),
+    platform: 'browser',
+    format: 'iife',
+    external: []
+  }
+]
+
+for (const bundle of bundles) {
+  await build({
+    entryPoints: bundle.entryPoints,
+    outfile: bundle.outfile,
+    bundle: true,
+    platform: bundle.platform,
+    format: bundle.format,
+    external: bundle.external,
+    target: 'es2023',
+    logLevel: 'warning'
+  })
+  console.log(`bundled ${bundle.label} -> ${bundle.outfile.replace(`${root}/`, '')}`)
+}
+
+await mkdir(join(outDir, 'renderer'), { recursive: true })
+for (const asset of ['index.html', 'style.css']) {
+  await copyFile(join(root, 'src/renderer', asset), join(outDir, 'renderer', asset))
+  console.log(`copied ${asset}`)
+}

scripts/smoke.js

@@ -1,128 +0,0 @@
-#!/usr/bin/env node
-'use strict'
-// Drives the bridge without Electron: no window, no packaging, just the part
-// that talks to the store. This is where an integration mistake shows up first,
-// so it is the check to run after touching lib/store.js or the CLI.
-//
-//   npm run smoke                       the store installed on this machine
-//   SMOKE_HOME=/path/to/store-home npm run smoke     a sandbox store
-
-const path = require('node:path')
-const fs = require('node:fs')
-const store = require('../lib/store')
-const bootstrap = require('../lib/bootstrap')
-const i18n = require('../lib/i18n')
-
-function ok (label, value) {
-  console.log(`  ok    ${label}${value === undefined ? '' : `: ${value}`}`)
-}
-function bad (label, value) {
-  console.log(`  FAIL  ${label}${value === undefined ? '' : `: ${value}`}`)
-  process.exitCode = 1
-}
-
-async function main () {
-  console.log('warp-engine-desktop-gui smoke test')
-
-  const python = store.findPython()
-  if (python) ok('python', python.version)
-  else return bad('python', 'not found — the store cannot run')
-
-  for (const lang of i18n.languages) {
-    const dict = i18n.dict(lang)
-    const missing = Object.keys(i18n.STRINGS[i18n.FALLBACK]).filter((k) => !dict[k])
-    if (missing.length) bad(`strings:${lang}`, `missing ${missing.join(', ')}`)
-    else ok(`strings:${lang}`, `${Object.keys(dict).length} keys`)
-  }
-
-  // The registry is what decides which stores exist, so it is checked before
-  // anything that depends on one being installed.
-  try {
-    const stores = await bootstrap.registry()
-    if (!stores.length) bad('registry', `${bootstrap.REGISTRY_URL} returned no stores`)
-    else {
-      ok('registry', `${stores.length} store(s) from ${bootstrap.REGISTRY_URL}`)
-      for (const store of stores) {
-        ok(`  ${store.name}`, `${store.catalogUrl} · ${bootstrap.storeId(store)}`)
-        const url = bootstrap.configUrl(store.storeRepositoryUrl)
-        try {
-          const config = JSON.parse(await bootstrap.fetchText(url))
-          ok('  config.json', `${Object.keys(config).length} sections`)
-        } catch (err) {
-          // Not fatal: the engine merges onto its defaults, so a store without a
-          // config file still installs.
-          ok('  config.json', `absent (${err.statusCode || err.message}) — defaults would be used`)
-        }
-      }
-    }
-  } catch (err) {
-    bad('registry', `${bootstrap.REGISTRY_URL}: ${err.message}`)
-  }
-
-  let target = null
-  if (process.env.SMOKE_HOME) {
-    const home = path.resolve(process.env.SMOKE_HOME)
-    target = {
-      engine: 'desktop',
-      id: path.basename(home).replace(/-desktop$/, ''),
-      home,
-      script: path.join(home, 'desktop_store.py'),
-      config: path.join(home, 'config.json')
-    }
-    for (const file of [target.script, target.config]) {
-      if (!fs.existsSync(file)) return bad('SMOKE_HOME', `${file} is missing`)
-    }
-    ok('store (SMOKE_HOME)', target.home)
-  } else {
-    const stores = store.findStores()
-    if (!stores.length) {
-      console.log('  skip  no store installed — run the app once, or set SMOKE_HOME')
-      console.log(`        it would be installed in ${store.defaultHome()}`)
-      return
-    }
-    target = stores[0]
-    ok('store found', `${target.id} in ${target.home}`)
-  }
-
-  const logs = []
-  const paths = await store.paths(target, { onLog: (l) => logs.push(l) })
-  if (paths.os && paths.store_folder) ok('paths', `${paths.os} → ${paths.store_folder}`)
-  else bad('paths', JSON.stringify(paths))
-
-  const listing = await store.list(target, { onLog: (l) => logs.push(l) })
-  const games = listing.games || []
-  if (!games.length) return bad('list', 'no games came back')
-
-  const modes = games.reduce((acc, g) => {
-    acc[g.mode] = (acc[g.mode] || 0) + 1
-    return acc
-  }, {})
-  ok('list', `${games.length} titles (${Object.entries(modes).map(([m, n]) => `${m}:${n}`).join(', ')})`)
-
-  const required = ['name', 'title', 'platform', 'version', 'mode', 'kind', 'installed', 'update_available']
-  const broken = games.filter((g) => required.some((k) => g[k] === undefined))
-  if (broken.length) bad('game shape', `${broken.length} entries miss a field`)
-  else ok('game shape', required.join(', '))
-
-  const hosted = games.filter((g) => g.mode === 'web')
-  if (hosted.length && !hosted.every((g) => /^https?:\/\//.test(g.url || ''))) {
-    bad('hosted urls', 'a web title has no usable url')
-  } else if (hosted.length) {
-    ok('hosted urls', hosted[0].url)
-  }
-
-  const installed = games.filter((g) => g.installed)
-  ok('installed', `${installed.length} of ${games.length}`)
-  if (installed.length) {
-    const withTarget = installed.filter((g) => g.menu_entry || g.exe || g.url)
-    if (withTarget.length !== installed.length) bad('launch targets', 'an installed title has nothing to launch')
-    else ok('launch targets', 'every installed title has one')
-  }
-
-  if (logs.length) ok('stderr log', `${logs.length} lines (kept off stdout)`)
-}
-
-main().catch((err) => {
-  console.log(`  FAIL  ${err && err.code ? err.code : 'error'}: ${err && err.message ? err.message : err}`)
-  process.exitCode = 1
-})