station-master/scripts/build-web.ts

/**
 * Build the static solitaire site into `dist/`.
 *
 * Everything here is BUILD-time. The output is plain files on disk — upload them anywhere that
 * serves static content and the game runs entirely in the visitor's browser. No server, no API, no
 * network call at runtime.
 *
 * The one thing a browser cannot do is run TypeScript: Node 22's type-stripping is a Node feature.
 * So `tsc` emits ES2022 modules, rewriting the `.ts` import extensions the engine uses into `.js`.
 */

import { execFileSync } from 'node:child_process';
import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

import { DOC_PAGES, docPage } from './docs-page.ts';
import { renderMarkdown } from './markdown.ts';

const root = join(dirname(fileURLToPath(import.meta.url)), '..');
/**
 * Overridable so a test can point the build at an isolated directory instead of the shared
 * `dist/` the rest of the suite reads — see `test/web.test.ts`'s "builds, and needs nothing but a
 * static host". Must be a sibling of `dist/`, not nested inside it: this script's own `rmSync`
 * below wipes the whole directory it is given, so nesting one inside the other would still race.
 */
const dist = join(root, process.env['BUILD_DIST_DIR'] ?? 'dist');

rmSync(dist, { recursive: true, force: true });
mkdirSync(dist, { recursive: true });

execFileSync(
  'npx',
  [
    'tsc',
    '--ignoreConfig',
    'src/web/main.ts',
    'src/web/splash.ts',
    'src/web/replays.ts',
    '--outDir', dist,
    '--rootDir', 'src',
    '--target', 'es2022',
    '--module', 'es2022',
    '--moduleResolution', 'bundler',
    '--lib', 'es2022,dom',
    '--types', '',
    '--strict',
    '--allowImportingTsExtensions',
    '--rewriteRelativeImportExtensions',
  ],
  { cwd: root, stdio: 'inherit' },
);

/**
 * Stamp the build into the page.
 *
 * Once this is published, "what is actually deployed?" stops being answerable by looking at the
 * source. The stamp is written into index.html at copy time rather than generated into `src/`, so
 * no generated file has to be ignored, imported, or kept in step.
 *
 * `-dirty` marks a build made from an uncommitted tree — the honest state of most test deploys, and
 * exactly the thing you want to know when a fix appears to have had no effect.
 */
function buildStamp(): string {
  const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { version: string };
  /**
   * THE FALLBACK HAS TO BE UNIQUE PER BUILD, because this string is also the cache-bust key.
   *
   * It used to be the literal `nogit`, which is exactly what the `.s9pk` build produces — the
   * Dockerfile copies the working tree in without `.git`, so `git rev-parse` fails there every time.
   * Every packaged release therefore published `?v=nogit`, byte-identical to the release before it,
   * and a returning player's browser had no reason to refetch a single module. v0.7.5's setup screen
   * and v0.7.6's fix to it both shipped correctly to `phoenix.local` and neither reached the browser
   * that asked for them (Jesse, twice, 2026-08-29 — "setup did not work").
   *
   * A marker plus the build's own timestamp is always distinct, needs nothing from the environment,
   * and stays honest: two builds of the same commit ARE two deploys, and a cache key that says so
   * costs one refetch, while one that lies costs a release nobody receives.
   *
   * NOT THE VERSION, which is what this used to lead with. The stamp below already begins with
   * `v${pkg.version}`, so on exactly the builds that take this path — every `.s9pk`, which has no
   * `.git` — the header read "v0.8.0.10 · 0.8.0.10-mfq2p1 · …" and the version appeared twice
   * (Jesse, playtest 2026-09-16). The timestamp alone carries the uniqueness; the version is
   * already said once, properly, at the front.
   */
  let git = `nogit-${Date.now().toString(36)}`;
  try {
    const sha = execFileSync('git', ['rev-parse', '--short', 'HEAD'], { cwd: root })
      .toString()
      .trim();
    const dirty =
      execFileSync('git', ['status', '--porcelain'], { cwd: root }).toString().trim().length > 0;
    git = sha + (dirty ? '-dirty' : '');
  } catch {
    // A build from a tarball with no git history is still a valid build.
  }
  const when = new Date().toISOString().replace('T', ' ').slice(0, 16);
  return `v${pkg.version} · ${git} · ${when}Z`;
}

const stamp = buildStamp();

/**
 * Cache-bust every module.
 *
 * A returning visitor gets a fresh index.html and STALE JavaScript, because a static host caches
 * .js and the filenames never change. That is not a cosmetic staleness: it mixes new HTML with old
 * code, and the first mismatch is fatal. It happened on the first real deploy — index.html had
 * dropped an element that the cached main.js still asked for, so the page threw
 * `missing element: target` and the game never started.
 *
 * Appending the build tag to every relative import makes each deploy a new set of URLs, so a
 * browser cannot serve half of one build and half of another.
 */
const tag = encodeURIComponent(stamp.split(' · ')[1] ?? stamp);

function bustImports(dir: string): number {
  let count = 0;
  for (const entry of readdirSync(dir, { withFileTypes: true })) {
    const full = join(dir, entry.name);
    if (entry.isDirectory()) {
      count += bustImports(full);
      continue;
    }
    if (!entry.name.endsWith('.js')) continue;
    const src = readFileSync(full, 'utf8');
    const next = src.replace(
      /^(\s*(?:import|export)[^'"\n]*?from\s+['"])(\.[^'"]+\.js)(['"])/gm,
      (_m, head: string, spec: string, tail: string) => `${head}${spec}?v=${tag}${tail}`,
    );
    if (next !== src) {
      writeFileSync(full, next);
      count++;
    }
  }
  return count;
}

const busted = bustImports(dist);

// Three pages now: the splash, the game, and the replay directory. Each is stamped and each has
// its entry script cache-busted, or a returning visitor gets new HTML against old modules.
for (const name of ['index.html', 'play.html', 'replays.html']) {
  const page = readFileSync(join(root, 'src/web', name), 'utf8')
    .replaceAll('__BUILD__', stamp)
    .replace(/(<script type="module" src="[^"]+?\.js)(")/, `$1?v=${tag}$2`);
  writeFileSync(join(dist, name), page);
}

/**
 * Publish whatever replays are in `public/replays/`, plus an index of them.
 *
 * Static hosting cannot list a directory, so the page needs a manifest. A replay is a save — seed
 * plus moves — so these are a few hundred bytes each, not megabytes.
 */
const replaySrc = join(root, 'public/replays');
const replayOut = join(dist, 'replays');
mkdirSync(replayOut, { recursive: true });
const manifest: { file: string; title: string; note?: string; seed?: number }[] = [];
if (existsSync(replaySrc)) {
  for (const f of readdirSync(replaySrc).filter((n) => n.endsWith('.json') && n !== 'manifest.json')) {
    const raw = readFileSync(join(replaySrc, f), 'utf8');
    try {
      const save = JSON.parse(raw) as { seed?: number; title?: string; note?: string; history?: unknown[] };
      if (typeof save.seed !== 'number' || !Array.isArray(save.history)) {
        console.warn(`  skipped ${f} — not a Station Master save`);
        continue;
      }
      writeFileSync(join(replayOut, f), raw);
      manifest.push({
        file: f,
        title: save.title ?? f.replace(/\.json$/, ''),
        ...(save.note ? { note: save.note } : {}),
        seed: save.seed,
      });
    } catch {
      console.warn(`  skipped ${f} — could not be parsed`);
    }
  }
}
writeFileSync(join(replayOut, 'manifest.json'), JSON.stringify(manifest, null, 1));

/**
 * Static images — the splash artwork and whatever joins it. Copied verbatim, unlike the replays
 * above: an image needs no validation, only a place in `dist/` to be served from.
 */
const imageSrc = join(root, 'public/images');
if (existsSync(imageSrc)) {
  const imageOut = join(dist, 'images');
  mkdirSync(imageOut, { recursive: true });
  for (const f of readdirSync(imageSrc)) copyFileSync(join(imageSrc, f), join(imageOut, f));
}

/**
 * The player-facing documentation, RENDERED and published beside the game.
 *
 * MARKDOWN IS STILL THE ONE COPY. `docs/*.md` is what is written and reviewed; this turns it into
 * a page at build time. A hand-written HTML twin would drift from it on the first edit, which is
 * the whole lesson of TODO #15a and of the documentation pass that found four references a month
 * out of date.
 *
 * WHY RENDER AT ALL. They were served as `text/plain`, which is honest and unreadable: a card
 * reference is mostly tables, and as plain text a table is rows of pipes. That was TODO #109, taken
 * deliberately as the short version to get the references in front of testers for one round.
 *
 * NO MARKDOWN LIBRARY. `scripts/markdown.ts` covers the subset these five documents use, and this
 * project has no runtime dependencies at all — one would be a poor first.
 *
 * THE `.md` IS PUBLISHED TOO, beside the page. It costs nothing, it is what a reader who wants the
 * source or a diff actually wants, and it keeps every link that was handed out while the documents
 * were served as text working rather than 404ing.
 */
const GUIDE_DOCS: readonly string[] = DOC_PAGES.map((d) => `${d.slug}.md`);

/** `rules.md` → `rules.html`, so a link between documents lands on the rendered page. */
const docLink = (href: string): string =>
  /^https?:/.test(href) || href.startsWith('#') ? href : href.replace(/\.md(#|$)/, '.html$1');

/**
 * The title and version line, lifted out of the Markdown body.
 *
 * The documents open with `# Title` then `**Version x.y.z** · date`, and the page draws both in its
 * own header — so rendering them again in the body would print each twice. Taken by pattern rather
 * than by line count, and the body is only trimmed where the pattern actually matched.
 */
function splitHead(src: string): { title: string; version: string; body: string } {
  const m = /^#\s+(.+?)\n+\*\*Version\s+([^*]+)\*\*\s*·\s*([^\n]+)\n/.exec(src);
  if (!m) return { title: 'Station Master', version: '', body: src };
  return {
    title: m[1]!.replace(/^Station Master\s*[—-]\s*/, '').trim(),
    version: `<b>Version ${m[2]!.trim()}</b> · ${m[3]!.trim()}`,
    body: src.slice(m[0].length),
  };
}

for (const rel of GUIDE_DOCS) {
  const src = join(root, 'docs', rel);
  if (!existsSync(src)) {
    // Loud rather than silent: a missing document is a broken link on a page already published, and
    // the build is the only place that can still notice.
    console.error(`WARNING: docs/${rel} is missing — a published link will 404`);
    continue;
  }
  const md = readFileSync(src, 'utf8');
  const out = join(dist, rel);
  mkdirSync(dirname(out), { recursive: true });
  writeFileSync(out, md);

  const { title, version, body } = splitHead(md);
  const { html, headings } = renderMarkdown(body, docLink);
  writeFileSync(
    join(dist, rel.replace(/\.md$/, '.html')),
    docPage({ slug: rel.replace(/\.md$/, ''), title, version, body: html, headings }),
  );
}

// A tiny note for whoever unzips this later and wonders what it needs.
writeFileSync(
  join(dist, 'README.txt'),
  [
    'Station Master — solitaire, static build.',
    '',
    'Upload the contents of this folder to any static host and open index.html.',
    'There is no server component. The game runs entirely in the browser and saves',
    'to localStorage. Add ?seed=1234 to the URL for a reproducible deal.',
    '',
    'Note: ES modules require the files to be SERVED over http(s). Opening',
    'index.html directly from the filesystem will be blocked by the browser.',
    'To try it locally:  npx http-server dist   (or any static file server)',
    '',
  ].join('\n'),
);

console.log(
  `built -> ${dist}\n       ${stamp}\n       cache-busted ${busted} modules with ?v=${tag}` +
    `\n       ${manifest.length} replay(s) published`,
);