@diffenderfer-games/hub 2.0.0-next.0 → 2.0.0-next.2

package/src/daily/page-daily.ts

@@ -1,36 +1,36 @@
-/**
- * The page's one daily-challenge system (plan §4.4): the first bundle to
- * create it wins, so the menu starts days on the instance the game defined.
- */
-import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
-import { claimSingleton } from '../globals';
-import { hasMethods } from '../realtime/cross-bundle';
-import { DailySystem } from './daily-system';
-import type { DailyHost } from './types';
-
-/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
-export const DAILY_SINGLETON_API = 1;
-
-/** Whether `candidate` is some bundle's daily system (v1 copies included). */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
-export function isDailySystem(candidate: unknown): candidate is DailySystem {
-  return hasMethods(candidate, ['define', 'startAndPlay', 'complete', 'cancel', 'status', 'all']);
-}
-
-let claimedDaily: DailySystem | null = null;
-
-/**
- * The page-wide daily system, created with `host` if no bundle has made one
- * yet. On a shape mismatch the registered one is kept and this bundle gets a
- * private instance. The answer is kept for this bundle.
- */
-export function getDaily(host: DailyHost): DailySystem {
-  claimedDaily ??= claimSingleton({
-    name: 'daily',
-    version: HUB_CLIENT_VERSION,
-    api: DAILY_SINGLETON_API,
-    create: () => new DailySystem(host),
-    isInstance: isDailySystem,
-  });
-  return claimedDaily;
-}
+/**
+ * The page's one daily-challenge system (plan §4.4): the first bundle to
+ * create it wins, so the menu starts days on the instance the game defined.
+ */
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { claimSingleton } from '../globals';
+import { hasMethods } from '../realtime/cross-bundle';
+import { DailySystem } from './daily-system';
+import type { DailyHost } from './types';
+
+/** The cross-bundle shape number of the `daily` singleton. Bump only on an incompatible change. */
+export const DAILY_SINGLETON_API = 1;
+
+/** Whether `candidate` is some bundle's daily system (v1 copies included). */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the instance may come from another bundle
+export function isDailySystem(candidate: unknown): candidate is DailySystem {
+  return hasMethods(candidate, ['define', 'startAndPlay', 'complete', 'cancel', 'status', 'all']);
+}
+
+let claimedDaily: DailySystem | null = null;
+
+/**
+ * The page-wide daily system, created with `host` if no bundle has made one
+ * yet. On a shape mismatch the registered one is kept and this bundle gets a
+ * private instance. The answer is kept for this bundle.
+ */
+export function getDaily(host: DailyHost): DailySystem {
+  claimedDaily ??= claimSingleton({
+    name: 'daily',
+    version: HUB_CLIENT_VERSION,
+    api: DAILY_SINGLETON_API,
+    create: () => new DailySystem(host),
+    isInstance: isDailySystem,
+  });
+  return claimedDaily;
+}

package/src/daily/types.ts

@@ -1,67 +1,68 @@
-/**
- * Daily challenge shapes: what a game's `play` receives, and the hub's
- * answers (typed from the contract's daily endpoints).
- */
-import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
-import type { SchemaOutput } from '../realtime/wire-types';
-
-/** The response type of a daily endpoint. */
-type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
-
-/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
-export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
-
-/** Every daily game and the global standings (`GET /daily`). */
-export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
-
-/** One game's row in {@link DailyAll}. */
-export type DailyGameStatus = DailyAll['games'][number];
-
-/** The answer to starting a day: its seed and the signed token to present on completion. */
-export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
-
-/** The answer to completing a day: the player's new completion count and rank. */
-export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
-
-/** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
-export interface DailyChallenge {
-  /** The day, `YYYY-MM-DD`. */
-  day: string;
-  /** Deterministic per game and day. */
-  seed: number;
-  /** The signed token `complete` presents. */
-  token: string;
-  /** The player already completed this day (a replay). */
-  alreadyCompleted?: boolean;
-}
-
-/** What `hub.daily.define` takes. */
-export interface DailyDefinition {
-  /** Start this challenge now. */
-  play: (challenge: DailyChallenge) => void;
-}
-
-/** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
-export type DailyCompletionMeta = Record<string, Json>;
-
-/** What the daily system needs from the hub client: the REST calls and its window events. */
-export interface DailyHost {
-  /** This page's game slug. */
-  readonly slug: string | null;
-  /** `GET /games/:slug/daily`. */
-  status(): Promise<DailyStatus>;
-  /** `GET /daily`. */
-  all(): Promise<DailyAll>;
-  /** `POST /games/:slug/daily/:day/start`. */
-  start(day: string): Promise<DailyStartResponse>;
-  /** `POST /games/:slug/daily/:day/complete`. */
-  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse>;
-  /** Fire a `hub:*` window event (the menu listens). */
-  emit(name: string, detail: DailyEventDetail): void;
-}
-
-/** The detail of the `hub:daily-*` window events. */
-export type DailyEventDetail =
-  | { day: string; seed: number; alreadyCompleted: boolean }
-  | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
-  | { day: string; error: string };
+/**
+ * Daily challenge shapes: what a game's `play` receives, and the hub's
+ * answers (typed from the contract's daily endpoints).
+ */
+import type { dailyEndpoints, Json } from '@diffenderfer-games/hub-contract';
+import type { SchemaOutput } from '../realtime/wire-types';
+
+/** The response type of a daily endpoint. */
+type DailyResponse<Name extends keyof typeof dailyEndpoints> = SchemaOutput<(typeof dailyEndpoints)[Name]['cfg']['response']>;
+
+/** This game's daily window and the player's completions (`GET /games/:slug/daily`). */
+export type DailyStatus = DailyResponse<'getGameDailyChallenges'>;
+
+/** Every daily game and the global standings (`GET /daily`). */
+export type DailyAll = DailyResponse<'listDailyChallengesForAllGames'>;
+
+/** One game's row in {@link DailyAll}. */
+export type DailyGameStatus = DailyAll['games'][number];
+
+/** The answer to starting a day: its seed and the signed token to present on completion. */
+export type DailyStartResponse = DailyResponse<'startDailyChallenge'>;
+
+/** The answer to completing a day: the player's new completion count and rank. */
+export type DailyCompleteResponse = DailyResponse<'completeDailyChallenge'>;
+
+/** The challenge a game's `play` receives: set up and start exactly this day (derive the level from `seed`). */
+export interface DailyChallenge {
+  /** The day, `YYYY-MM-DD`. */
+  day: string;
+  /** Deterministic per game and day. */
+  seed: number;
+  /** The signed token `complete` presents. */
+  token: string;
+  /** The player already completed this day (a replay). */
+  alreadyCompleted?: boolean;
+}
+
+/** What `hub.daily.define` takes. */
+export interface DailyDefinition {
+  /** Start this challenge now. */
+  play: (challenge: DailyChallenge) => void;
+}
+
+/** Metadata a game records with a completion (`{ score, difficulty, timeMs, … }`). */
+export type DailyCompletionMeta = Record<string, Json>;
+
+/** What the daily system needs from the hub client: the REST calls and its window events. */
+export interface DailyHost {
+  /** This page's game slug. */
+  readonly slug: string | null;
+  /** `GET /games/:slug/daily`. */
+  status(): Promise<DailyStatus>;
+  /** `GET /daily`. */
+  all(): Promise<DailyAll>;
+  /** `POST /games/:slug/daily/:day/start`. */
+  start(day: string): Promise<DailyStartResponse>;
+  /** `POST /games/:slug/daily/:day/complete`; `null` when it was queued offline, to replay when the hub is back. */
+  complete(day: string, token: string, meta: DailyCompletionMeta): Promise<DailyCompleteResponse | null>;
+  /** Fire a `hub:*` window event (the menu listens). */
+  emit(name: string, detail: DailyEventDetail): void;
+}
+
+/** The detail of the `hub:daily-*` window events. */
+export type DailyEventDetail =
+  | { day: string; seed: number; alreadyCompleted: boolean }
+  | { day: string; count: number; rank: number | null; meta: DailyCompletionMeta }
+  | { day: string; queued: true; meta: DailyCompletionMeta }
+  | { day: string; error: string };

package/src/daily.ts

@@ -1,10 +1,10 @@
-/**
- * `@diffenderfer-games/hub/daily`: daily challenges (`hub.daily`): the
- * {@link DailySystem} and the page-wide {@link getDaily}.
- *
- * @packageDocumentation
- */
-export { DAILY_START_EVENT, DailySystem } from './daily/daily-system';
-export { DAILY_SINGLETON_API, getDaily, isDailySystem } from './daily/page-daily';
-export type * from './daily/types';
-export type { DailyCompletion, DailyCompletions } from '@diffenderfer-games/hub-contract';
+/**
+ * `@diffenderfer-games/hub/daily`: daily challenges (`hub.daily`): the
+ * {@link DailySystem} and the page-wide {@link getDaily}.
+ *
+ * @packageDocumentation
+ */
+export { DAILY_START_EVENT, DailySystem } from './daily/daily-system';
+export { DAILY_SINGLETON_API, getDaily, isDailySystem } from './daily/page-daily';
+export type * from './daily/types';
+export type { DailyCompletion, DailyCompletions } from '@diffenderfer-games/hub-contract';

package/src/doctor/checks.ts

@@ -1,76 +1,86 @@
-/**
- * The checks `hub-doctor` runs on a game (plan §4.3.7). Each returns
- * findings; an `error` finding fails the run (and the game's CI).
- */
-import { existsSync } from 'node:fs';
-import { join } from 'node:path';
-import { GamePackageJson, type HubVersion } from '@diffenderfer-games/hub-contract';
-import { clientSupport } from '../core/version/hub-version';
-
-/** How serious a finding is: `error` fails the run, `warning` and `info` only report. */
-export type FindingLevel = 'error' | 'warning' | 'info';
-
-/** One thing the doctor found. */
-export interface Finding {
-  /** How serious it is. */
-  readonly level: FindingLevel;
-  /** Which check found it: `version`, `vendored` or `manifest`. */
-  readonly check: 'version' | 'vendored' | 'manifest';
-  /** What to tell the developer, with the fix. */
-  readonly message: string;
-}
-
-/** The fix for an old or unsupported client. */
-const UPDATE_FIX = 'run `npm update @diffenderfer-games/hub`';
-
-/**
- * The installed client against the hub's `/_api/version`: outside
- * `supported` is an error, `deprecated` a warning. `null` (a hub from before
- * versioning) and an unreachable hub are only reported.
- */
-export function checkClientVersion(installedVersion: string, hubVersion: HubVersion | null | Error): Finding[] {
-  if (hubVersion instanceof Error) {
-    return [{ level: 'warning', check: 'version', message: `could not read the hub's version (${hubVersion.message}); the client version was not checked` }];
-  }
-  switch (clientSupport(hubVersion, installedVersion)) {
-    case 'unsupported':
-      return [{ level: 'error', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is not supported by the hub (supported: ${hubVersion?.supported ?? '?'}): ${UPDATE_FIX}` }];
-    case 'deprecated':
-      return [{ level: 'warning', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is deprecated (deprecated: ${hubVersion?.deprecated ?? '?'}): ${UPDATE_FIX}` }];
-    case 'unknown':
-      return [{ level: 'info', check: 'version', message: 'the hub predates versioning (no /_api/version); the client version was not checked' }];
-    case 'supported':
-      return [{ level: 'info', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is supported (hub ${hubVersion?.server ?? '?'})` }];
-  }
-}
-
-/** Leftovers of the v1 vendored client, relative to the game's folder. */
-const VENDORED_LEFTOVERS = [
-  'src/hub/hub.ts',
-  'src/hub/input.ts',
-  'client/src/hub/hub.ts',
-  'scripts/sync-hub.mjs',
-] as const;
-
-/** A stale vendored `src/hub/` copy or its sync script (the package replaces both). */
-export function checkVendoredCopies(gameDir: string): Finding[] {
-  return VENDORED_LEFTOVERS.filter((leftover) => existsSync(join(gameDir, leftover))).map((leftover) => ({
-    level: 'warning',
-    check: 'vendored',
-    message: `${leftover} is a vendored copy of the v1 client: import from '@diffenderfer-games/hub' instead and delete it`,
-  }));
-}
-
-/** The `package.json` `game.*` block against the contract's manifest schema. */
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's package.json, parsed by GamePackageJson next
-export function checkManifest(packageJson: unknown): Finding[] {
-  const parsed = GamePackageJson.safeParse(packageJson);
-  if (parsed.success) {
-    return [{ level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` }];
-  }
-  return parsed.error.issues.map((issue) => ({
-    level: 'error',
-    check: 'manifest',
-    message: `${issue.path.length === 0 ? '(package.json)' : issue.path.join('.')}: ${issue.message}`,
-  }));
-}
+/**
+ * The checks `hub-doctor` runs on a game (plan §4.3.7). Each returns
+ * findings; an `error` finding fails the run (and the game's CI).
+ */
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { GAME_LABELS, GamePackageJson, splitGameLabels, type HubVersion } from '@diffenderfer-games/hub-contract';
+import { clientSupport } from '../core/version/hub-version';
+import { isHubUnreachable, type HubUnreachable } from './hub-version-fetch';
+
+/** How serious a finding is: `error` fails the run, `warning` and `info` only report. */
+export type FindingLevel = 'error' | 'warning' | 'info';
+
+/** One thing the doctor found. */
+export interface Finding {
+  /** How serious it is. */
+  readonly level: FindingLevel;
+  /** Which check found it: `version`, `vendored` or `manifest`. */
+  readonly check: 'version' | 'vendored' | 'manifest';
+  /** What to tell the developer, with the fix. */
+  readonly message: string;
+}
+
+/** The fix for an old or unsupported client. */
+const UPDATE_FIX = 'run `npm update @diffenderfer-games/hub`';
+
+/**
+ * The installed client against the hub's `/_api/version`: outside
+ * `supported` is an error, `deprecated` a warning, `null` (a hub from before
+ * versioning) is only reported. An unreachable or slow hub is an error, so a
+ * game's CI notices (`--offline` skips the check).
+ */
+export function checkClientVersion(installedVersion: string, hubVersion: HubVersion | null | HubUnreachable): Finding[] {
+  if (isHubUnreachable(hubVersion)) {
+    return [{ level: 'error', check: 'version', message: `hub unreachable at ${hubVersion.unreachableUrl} (${hubVersion.reason}); check --hub, or pass --offline to skip the version check` }];
+  }
+  switch (clientSupport(hubVersion, installedVersion)) {
+    case 'unsupported':
+      return [{ level: 'error', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is not supported by the hub (supported: ${hubVersion?.supported ?? '?'}): ${UPDATE_FIX}` }];
+    case 'deprecated':
+      return [{ level: 'warning', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is deprecated (deprecated: ${hubVersion?.deprecated ?? '?'}): ${UPDATE_FIX}` }];
+    case 'unknown':
+      return [{ level: 'info', check: 'version', message: 'the hub predates versioning (no /_api/version); the client version was not checked' }];
+    case 'supported':
+      return [{ level: 'info', check: 'version', message: `@diffenderfer-games/hub ${installedVersion} is supported (hub ${hubVersion?.server ?? '?'})` }];
+  }
+}
+
+/** Leftovers of the v1 vendored client, relative to the game's folder. */
+const VENDORED_LEFTOVERS = [
+  'src/hub/hub.ts',
+  'src/hub/input.ts',
+  'client/src/hub/hub.ts',
+  'scripts/sync-hub.mjs',
+] as const;
+
+/** A stale vendored `src/hub/` copy or its sync script (the package replaces both). */
+export function checkVendoredCopies(gameDir: string): Finding[] {
+  return VENDORED_LEFTOVERS.filter((leftover) => existsSync(join(gameDir, leftover))).map((leftover) => ({
+    level: 'warning',
+    check: 'vendored',
+    message: `${leftover} is a vendored copy of the v1 client: import from '@diffenderfer-games/hub' instead and delete it`,
+  }));
+}
+
+/** The `package.json` `game.*` block against the contract's manifest schema. */
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: the game's package.json, parsed by GamePackageJson next
+export function checkManifest(packageJson: unknown): Finding[] {
+  const parsed = GamePackageJson.safeParse(packageJson);
+  if (parsed.success) {
+    const unknownLabels = splitGameLabels(parsed.data.game.labels ?? []).unknown;
+    return [
+      { level: 'info', check: 'manifest', message: `the game.* block is valid (${parsed.data.game.type})` },
+      ...unknownLabels.map((label): Finding => ({
+        level: 'warning',
+        check: 'manifest',
+        message: `game.labels: "${label}" is not a known label (the catalog ignores it); use any of ${GAME_LABELS.join(', ')}`,
+      })),
+    ];
+  }
+  return parsed.error.issues.map((issue) => ({
+    level: 'error',
+    check: 'manifest',
+    message: `${issue.path.length === 0 ? '(package.json)' : issue.path.join('.')}: ${issue.message}`,
+  }));
+}

package/src/doctor/cli.ts

@@ -1,106 +1,98 @@
-#!/usr/bin/env node
-/**
- * `hub-doctor`: checks a game against the hub (plan §4.3.7). Run it in a
- * game's folder, in CI and before pushing:
- *
- * ```sh
- * npx hub-doctor [--dir <game folder>] [--hub <url>] [--offline] [--json]
- * ```
- *
- * - the installed `@diffenderfer-games/hub` against the hub's
- *   `/_api/version` (`--hub`, default `https://diffenderfer.games`): outside
- *   `supported` fails, `deprecated` warns (`--offline` skips this check);
- * - a stale vendored `src/hub/` copy or `scripts/sync-hub.mjs` warns;
- * - the `package.json` `game.*` block must match the contract's schema.
- *
- * Exits 1 when any check fails.
- */
-import { readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
-import { parseArgs } from 'node:util';
-import { HubVersion } from '@diffenderfer-games/hub-contract';
-import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
-import { checkClientVersion, checkManifest, checkVendoredCopies, type Finding } from './checks';
-
-const DEFAULT_HUB_URL = 'https://diffenderfer.games';
-
-/** The command line, parsed. */
-interface DoctorOptions {
-  readonly gameDir: string;
-  readonly hubUrl: string;
-  readonly isOffline: boolean;
-  readonly isJson: boolean;
-}
-
-function readOptions(): DoctorOptions {
-  const { values } = parseArgs({
-    options: {
-      dir: { type: 'string' },
-      hub: { type: 'string' },
-      offline: { type: 'boolean', default: false },
-      json: { type: 'boolean', default: false },
-    },
-  });
-  return { gameDir: resolve(values.dir ?? '.'), hubUrl: values.hub ?? DEFAULT_HUB_URL, isOffline: values.offline, isJson: values.json };
-}
-
-// eslint-disable-next-line no-restricted-syntax -- trust boundary: a JSON file from disk, parsed by the caller's schema
-function readJsonFile(path: string): unknown {
-  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, parsed by the caller's schema
-  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
-  return parsed;
-}
-
-/** The client version the game has installed (its `node_modules` copy), else this doctor's own. */
-function installedClientVersion(gameDir: string): string {
-  try {
-    const installed = readJsonFile(join(gameDir, 'node_modules', '@diffenderfer-games', 'hub', 'package.json'));
-    if (typeof installed === 'object' && installed !== null && 'version' in installed && typeof installed.version === 'string') {
-      return installed.version;
-    }
-  } catch {
-    // Not installed in the game: report this doctor's own version.
-  }
-  return HUB_CLIENT_VERSION;
-}
-
-/** The hub's `/_api/version`: `null` for a hub without it, an `Error` when unreachable. */
-async function fetchHubVersion(hubUrl: string): Promise<HubVersion | null | Error> {
-  try {
-    const response = await fetch(new URL('/_api/version', hubUrl));
-    if (response.status === 404) {
-      return null;
-    }
-    if (!response.ok) {
-      return new Error(`HTTP ${String(response.status)}`);
-    }
-    return HubVersion.parse(await response.json());
-  } catch (failure) {
-    return failure instanceof Error ? failure : new Error(String(failure));
-  }
-}
-
-async function runDoctor(options: DoctorOptions): Promise<Finding[]> {
-  const findings: Finding[] = [];
-  if (!options.isOffline) {
-    findings.push(...checkClientVersion(installedClientVersion(options.gameDir), await fetchHubVersion(options.hubUrl)));
-  }
-  findings.push(...checkVendoredCopies(options.gameDir));
-  try {
-    findings.push(...checkManifest(readJsonFile(join(options.gameDir, 'package.json'))));
-  } catch (failure) {
-    findings.push({ level: 'error', check: 'manifest', message: `could not read package.json: ${failure instanceof Error ? failure.message : String(failure)}` });
-  }
-  return findings;
-}
-
-const options = readOptions();
-const findings = await runDoctor(options);
-if (options.isJson) {
-  process.stdout.write(`${JSON.stringify({ findings }, null, 2)}\n`);
-} else {
-  for (const finding of findings) {
-    process.stdout.write(`${finding.level.padEnd(7)} ${finding.check}: ${finding.message}\n`);
-  }
-}
-process.exitCode = findings.some((finding) => finding.level === 'error') ? 1 : 0;
+#!/usr/bin/env node
+/**
+ * `hub-doctor`: checks a game against the hub (plan §4.3.7). Run it in a
+ * game's folder, in CI and before pushing:
+ *
+ * ```sh
+ * npx hub-doctor [--dir <game folder>] [--hub <url>] [--timeout <ms>] [--offline] [--json]
+ * ```
+ *
+ * - the installed `@diffenderfer-games/hub` against the hub's
+ *   `/_api/version` (`--hub`, default `https://diffenderfer.games`): outside
+ *   `supported` fails, `deprecated` warns (`--offline` skips this check);
+ * - a stale vendored `src/hub/` copy or `scripts/sync-hub.mjs` warns;
+ * - the `package.json` `game.*` block must match the contract's schema.
+ *
+ * Exits 1 when any check fails.
+ */
+import { readFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+import { HUB_CLIENT_VERSION } from '../core/version/client-version.gen';
+import { checkClientVersion, checkManifest, checkVendoredCopies, type Finding } from './checks';
+import { DEFAULT_HUB_TIMEOUT_MS, fetchHubVersion } from './hub-version-fetch';
+
+const DEFAULT_HUB_URL = 'https://diffenderfer.games';
+
+/** The command line, parsed. */
+interface DoctorOptions {
+  readonly gameDir: string;
+  readonly hubUrl: string;
+  /** How long to wait for the hub, ms (`--timeout`). */
+  readonly timeoutMs: number;
+  readonly isOffline: boolean;
+  readonly isJson: boolean;
+}
+
+function readOptions(): DoctorOptions {
+  const { values } = parseArgs({
+    options: {
+      dir: { type: 'string' },
+      hub: { type: 'string' },
+      timeout: { type: 'string' },
+      offline: { type: 'boolean', default: false },
+      json: { type: 'boolean', default: false },
+    },
+  });
+  const timeoutMs = values.timeout === undefined ? DEFAULT_HUB_TIMEOUT_MS : Number(values.timeout);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    process.stderr.write('hub-doctor: --timeout must be a positive number of milliseconds\n');
+    process.exit(2);
+  }
+  return { gameDir: resolve(values.dir ?? '.'), hubUrl: values.hub ?? DEFAULT_HUB_URL, timeoutMs, isOffline: values.offline, isJson: values.json };
+}
+
+// eslint-disable-next-line no-restricted-syntax -- trust boundary: a JSON file from disk, parsed by the caller's schema
+function readJsonFile(path: string): unknown {
+  // eslint-disable-next-line no-restricted-syntax -- trust boundary: JSON.parse's result, parsed by the caller's schema
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'));
+  return parsed;
+}
+
+/** The client version the game has installed (its `node_modules` copy), else this doctor's own. */
+function installedClientVersion(gameDir: string): string {
+  try {
+    const installed = readJsonFile(join(gameDir, 'node_modules', '@diffenderfer-games', 'hub', 'package.json'));
+    if (typeof installed === 'object' && installed !== null && 'version' in installed && typeof installed.version === 'string') {
+      return installed.version;
+    }
+  } catch {
+    // Not installed in the game: report this doctor's own version.
+  }
+  return HUB_CLIENT_VERSION;
+}
+
+async function runDoctor(options: DoctorOptions): Promise<Finding[]> {
+  const findings: Finding[] = [];
+  if (!options.isOffline) {
+    findings.push(...checkClientVersion(installedClientVersion(options.gameDir), await fetchHubVersion(options.hubUrl, options.timeoutMs)));
+  }
+  findings.push(...checkVendoredCopies(options.gameDir));
+  try {
+    findings.push(...checkManifest(readJsonFile(join(options.gameDir, 'package.json'))));
+  } catch (failure) {
+    findings.push({ level: 'error', check: 'manifest', message: `could not read package.json: ${failure instanceof Error ? failure.message : String(failure)}` });
+  }
+  return findings;
+}
+
+const options = readOptions();
+const findings = await runDoctor(options);
+if (options.isJson) {
+  process.stdout.write(`${JSON.stringify({ findings }, null, 2)}\n`);
+} else {
+  for (const finding of findings) {
+    process.stdout.write(`${finding.level.padEnd(7)} ${finding.check}: ${finding.message}\n`);
+  }
+}
+process.exitCode = findings.some((finding) => finding.level === 'error') ? 1 : 0;