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

package/src/daily/types.ts

@@ -1,67 +1,67 @@
-/**
- * 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`. */
+  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 };

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,78 @@
-/**
- * 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 { GamePackageJson, 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) {
+    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}`,
+  }));
+}

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;

package/src/doctor/hub-version-fetch.ts

@@ -0,0 +1,43 @@
+/**
+ * Reading the hub's `GET /_api/version` for `hub-doctor`, with a timeout so a
+ * hung or unreachable hub fails a game's CI quickly instead of stalling it.
+ */
+import { HubVersion } from '@diffenderfer-games/hub-contract';
+
+/** How long the doctor waits for the hub by default, ms. */
+export const DEFAULT_HUB_TIMEOUT_MS = 10_000;
+
+/** The hub could not be asked: down, slow, or answering with an error. */
+export interface HubUnreachable {
+  /** The URL that was asked. */
+  readonly unreachableUrl: string;
+  /** Why, for the message (`timed out after 10000 ms`, `HTTP 502`, a network error). */
+  readonly reason: string;
+}
+
+/** Whether a version lookup failed. */
+export function isHubUnreachable(lookup: HubVersion | null | HubUnreachable): lookup is HubUnreachable {
+  return lookup !== null && 'unreachableUrl' in lookup;
+}
+
+/**
+ * The hub's version: `null` for a hub from before versioning (404), a
+ * {@link HubUnreachable} when it can't be read within `timeoutMs`.
+ */
+export async function fetchHubVersion(hubUrl: string, timeoutMs: number = DEFAULT_HUB_TIMEOUT_MS): Promise<HubVersion | null | HubUnreachable> {
+  const url = new URL('/_api/version', hubUrl).toString();
+  try {
+    const response = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+    if (response.status === 404) {
+      return null;
+    }
+    if (!response.ok) {
+      return { unreachableUrl: url, reason: `HTTP ${String(response.status)}` };
+    }
+    return HubVersion.parse(await response.json());
+  } catch (failure) {
+    const isTimeout = failure instanceof Error && (failure.name === 'TimeoutError' || failure.name === 'AbortError');
+    const reason = isTimeout ? `timed out after ${String(timeoutMs)} ms` : failure instanceof Error ? failure.message : String(failure);
+    return { unreachableUrl: url, reason };
+  }
+}

package/src/doctor/tsconfig.json

@@ -1,12 +1,12 @@
-{
-  "extends": "../../tsconfig.json",
-  "compilerOptions": {
-    "types": [
-      "node"
-    ]
-  },
-  "include": [
-    "."
-  ],
-  "exclude": []
-}
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "."
+  ],
+  "exclude": []
+}