gloomberb 0.15.2 → 0.15.4

package/src/updater/index.ts

@@ -0,0 +1,472 @@
+import { compareSemver } from "../utils/semver";
+import { GITHUB_LATEST_RELEASE_API_URL } from "./github-releases";
+
+function getRuntimeProcess(): Pick<NodeJS.Process, "platform" | "arch" | "argv" | "execPath"> | null {
+  return (globalThis as { process?: NodeJS.Process }).process ?? null;
+}
+
+export interface ReleaseInfo {
+  version: string;
+  tagName: string;
+  downloadUrl: string;
+  publishedAt: string;
+  updateAction: UpdateAction;
+  compressed?: boolean;
+  /** SHA-256 of the downloaded GitHub release asset. */
+  checksum?: string;
+}
+
+export interface UpdateProgress {
+  phase: "downloading" | "replacing" | "done" | "error";
+  percent?: number;
+  error?: string;
+  message?: string;
+}
+
+export type UpdateAction =
+  | { kind: "self" }
+  | { kind: "desktop" }
+  | { kind: "manual"; command: string }
+  /**
+   * A standalone binary this process cannot overwrite: a Nix store path, a
+   * distro package under /usr/bin, anything installed by root. Whatever put it
+   * there updates it; trying ourselves ended in "EROFS: read-only file system"
+   * in the header (#684).
+   */
+  | { kind: "managed"; reason: string };
+
+export type UpdateCheckResult =
+  | { kind: "available"; release: ReleaseInfo }
+  | { kind: "current" }
+  | { kind: "disabled" }
+  | { kind: "error"; error: string };
+
+export interface UpdateHost {
+  checkForUpdateDetailed(currentVersion: string): Promise<UpdateCheckResult>;
+  performUpdate(release: ReleaseInfo, onProgress: (p: UpdateProgress) => void): Promise<void>;
+}
+
+let updateHost: UpdateHost | null = null;
+
+export function setUpdateHost(host: UpdateHost | null): void {
+  updateHost = host;
+}
+
+export function getAssetBaseNameForRuntime(
+  runtimeProcess: Pick<NodeJS.Process, "platform" | "arch"> | null = getRuntimeProcess(),
+): string {
+  const os = runtimeProcess?.platform === "darwin"
+    ? "darwin"
+    : runtimeProcess?.platform === "win32"
+      ? "windows"
+      : "linux";
+  // Always update to the architecture the current runtime actually is. macOS
+  // only publishes arm64 today, so an x64 macOS runtime resolves no asset and
+  // reports that instead of overwriting itself with an unrunnable binary.
+  const arch = runtimeProcess?.arch === "arm64" ? "arm64" : "x64";
+  const extension = os === "windows" ? ".exe" : "";
+  return `gloomberb-${os}-${arch}${extension}`;
+}
+
+function getAssetBaseName(): string {
+  return getAssetBaseNameForRuntime();
+}
+
+function parseAssetDigest(digest: string | undefined): string | undefined {
+  return /^sha256:([a-f\d]{64})$/i.exec(digest ?? "")?.[1]?.toLowerCase();
+}
+
+function resolveReleaseAsset(
+  assets: { name: string; browser_download_url: string; digest?: string }[],
+): { name: string; browser_download_url: string; compressed: boolean; checksum?: string } | null {
+  const assetBaseName = getAssetBaseName();
+  const gzAsset = assets.find((asset) => asset.name === `${assetBaseName}.gz`);
+  if (gzAsset) {
+    const { name, browser_download_url, digest } = gzAsset;
+    return { name, browser_download_url, compressed: true, checksum: parseAssetDigest(digest) };
+  }
+
+  const rawAsset = assets.find((asset) => asset.name === assetBaseName);
+  if (rawAsset) {
+    const { name, browser_download_url, digest } = rawAsset;
+    return { name, browser_download_url, compressed: false, checksum: parseAssetDigest(digest) };
+  }
+
+  return null;
+}
+
+function normalizePath(value: string): string {
+  return value.replace(/\\/g, "/").toLowerCase();
+}
+
+function basename(value: string): string {
+  const normalized = value.replace(/\\/g, "/");
+  return normalized.slice(normalized.lastIndexOf("/") + 1);
+}
+
+const runtimeExecutables = new Set([
+  "bun",
+  "bun.exe",
+  "bunx",
+  "bunx.exe",
+  "node",
+  "node.exe",
+  "nodejs",
+  "nodejs.exe",
+  "npm",
+  "npm.cmd",
+  "npm.exe",
+  "npx",
+  "npx.cmd",
+  "npx.exe",
+  "pnpm",
+  "pnpm.cmd",
+  "pnpm.exe",
+  "yarn",
+  "yarn.cmd",
+  "yarn.exe",
+]);
+
+function resolveEntrypointPath(argv = process.argv): string {
+  return argv[1] ?? "";
+}
+
+function isSourceEntrypoint(entrypoint: string): boolean {
+  const sourceEntrypointPattern = /\.(c|m)?jsx?$/;
+  const tsEntrypointPattern = /\.(c|m)?tsx?$/;
+  return sourceEntrypointPattern.test(entrypoint) || tsEntrypointPattern.test(entrypoint);
+}
+
+function isMacAppBundleExecutable(execPath: string): boolean {
+  return normalizePath(execPath).includes(".app/contents/macos/");
+}
+
+function isBundledDesktopTuiRuntime(execPath: string, argv: string[]): boolean {
+  const normalizedExecPath = normalizePath(execPath);
+  const entrypoint = normalizePath(resolveEntrypointPath(argv));
+  if (!entrypoint.endsWith("/resources/gloomberb-tui/tui-entry.js")) return false;
+  return normalizedExecPath.endsWith("/contents/macos/bun")
+    || normalizedExecPath.endsWith("/bin/bun")
+    || normalizedExecPath.endsWith("/bin/bun.exe");
+}
+
+export function resolveSelfUpdateTargetPath(
+  execPath = getRuntimeProcess()?.execPath ?? "",
+  argv = getRuntimeProcess()?.argv ?? [],
+): string | null {
+  const resolvedExecPath = execPath;
+  const normalizedExecPath = normalizePath(resolvedExecPath);
+  if (isMacAppBundleExecutable(resolvedExecPath)) return null;
+
+  const execBase = basename(normalizedExecPath);
+  if (runtimeExecutables.has(execBase)) return null;
+  if (normalizedExecPath.includes("/.bun/bin/")) return null;
+
+  const entrypoint = normalizePath(resolveEntrypointPath(argv));
+  if (isSourceEntrypoint(entrypoint)) return null;
+
+  return resolvedExecPath;
+}
+
+/**
+ * Why this process could not replace its own binary, or null when it can (or
+ * when that cannot be told, as for a path that does not exist).
+ *
+ * `fs` is reached through a variable so the browser bundles, which share this
+ * module, do not try to resolve it; they never get here because they have no
+ * `process.execPath` to begin with.
+ */
+export function describeUnwritableInstall(execPath: string): string | null {
+  if (!execPath || typeof require !== "function") return null;
+  const normalized = normalizePath(execPath);
+  const directory = normalized.slice(0, Math.max(0, normalized.lastIndexOf("/"))) || "/";
+  try {
+    const fsModulePath = "fs";
+    const fs = require(fsModulePath) as typeof import("fs");
+    fs.accessSync(execPath, fs.constants.W_OK);
+    fs.accessSync(directory, fs.constants.W_OK);
+    return null;
+  } catch (error) {
+    const code = (error as { code?: string } | null)?.code;
+    if (code === "EROFS") return "the install is on a read-only file system";
+    if (code === "EACCES" || code === "EPERM") return "the install directory is not writable";
+    return null;
+  }
+}
+
+export function detectUpdateAction(
+  execPath = getRuntimeProcess()?.execPath ?? "",
+  argv = getRuntimeProcess()?.argv ?? [],
+): UpdateAction | null {
+  if (isMacAppBundleExecutable(execPath)) return null;
+  if (isBundledDesktopTuiRuntime(execPath, argv)) return null;
+
+  const normalizedExecPath = normalizePath(execPath);
+  const execBase = basename(normalizedExecPath);
+  const entrypoint = normalizePath(resolveEntrypointPath(argv));
+  if (execBase === "gloomberb.exe") return null;
+
+  if (resolveSelfUpdateTargetPath(execPath, argv)) {
+    const reason = describeUnwritableInstall(execPath);
+    return reason ? { kind: "managed", reason } : { kind: "self" };
+  }
+
+  if (!entrypoint || isSourceEntrypoint(entrypoint)) return null;
+
+  if (
+    execBase === "bun"
+    || execBase === "bun.exe"
+    || execBase === "bunx"
+    || execBase === "bunx.exe"
+    || normalizedExecPath.includes("/.bun/bin/")
+    || entrypoint.includes("/.bun/install/")
+    || entrypoint.includes("/install/global/")
+  ) {
+    return { kind: "manual", command: "bun install -g gloomberb@latest" };
+  }
+
+  if (
+    execBase === "node"
+    || execBase === "node.exe"
+    || execBase === "nodejs"
+    || execBase === "nodejs.exe"
+    || execBase === "npm"
+    || execBase === "npm.cmd"
+    || execBase === "npm.exe"
+    || execBase === "npx"
+    || execBase === "npx.cmd"
+    || execBase === "npx.exe"
+    || execBase === "pnpm"
+    || execBase === "pnpm.cmd"
+    || execBase === "pnpm.exe"
+    || execBase === "yarn"
+    || execBase === "yarn.cmd"
+    || execBase === "yarn.exe"
+    || entrypoint.includes("/lib/node_modules/")
+    || entrypoint.includes("/node_modules/")
+  ) {
+    return { kind: "manual", command: "npm install -g gloomberb@latest" };
+  }
+
+  return null;
+}
+
+export function canSelfUpdate(release: Pick<ReleaseInfo, "updateAction"> | null | undefined): boolean {
+  return release?.updateAction.kind === "self" || release?.updateAction.kind === "desktop";
+}
+
+export async function checkForUpdateDetailed(
+  currentVersion: string,
+): Promise<UpdateCheckResult> {
+  if (updateHost) {
+    return updateHost.checkForUpdateDetailed(currentVersion);
+  }
+
+  const updateAction = detectUpdateAction();
+  if (!updateAction) {
+    return { kind: "disabled" };
+  }
+
+  let timeout: ReturnType<typeof setTimeout> | undefined;
+  try {
+    const controller = new AbortController();
+    timeout = setTimeout(() => controller.abort(), 5000);
+
+    const res = await fetch(GITHUB_LATEST_RELEASE_API_URL, {
+      signal: controller.signal,
+      headers: { Accept: "application/vnd.github+json" },
+    });
+
+    if (!res.ok) {
+      return { kind: "error", error: `GitHub returned ${res.status}` };
+    }
+
+    const data = (await res.json()) as {
+      tag_name: string;
+      published_at: string;
+      assets: { name: string; browser_download_url: string; digest?: string }[];
+    };
+
+    const version = data.tag_name.replace(/^v/, "");
+    // A tag that does not parse as a version is not an update.
+    if ((compareSemver(version, currentVersion) ?? 0) <= 0) {
+      return { kind: "current" };
+    }
+
+    const asset = resolveReleaseAsset(data.assets);
+    if (!asset) {
+      return {
+        kind: "error",
+        error: `No compatible release asset found for ${getAssetBaseName()}`,
+      };
+    }
+    if (!asset.checksum) {
+      return {
+        kind: "error",
+        error: `Release asset ${asset.name} is missing a valid SHA-256 digest`,
+      };
+    }
+
+    return {
+      kind: "available",
+      release: {
+        version,
+        tagName: data.tag_name,
+        downloadUrl: asset.browser_download_url,
+        publishedAt: data.published_at,
+        updateAction,
+        compressed: asset.compressed,
+        ...(asset.checksum ? { checksum: asset.checksum } : {}),
+      },
+    };
+  } catch (error: unknown) {
+    if (error instanceof Error && error.name === "AbortError") {
+      return { kind: "error", error: "Update check timed out" };
+    }
+    return {
+      kind: "error",
+      error: error instanceof Error ? error.message : "Update check failed",
+    };
+  } finally {
+    if (timeout) clearTimeout(timeout);
+  }
+}
+
+export async function checkForUpdate(
+  currentVersion: string,
+): Promise<ReleaseInfo | null> {
+  const result = await checkForUpdateDetailed(currentVersion);
+  return result.kind === "available" ? result.release : null;
+}
+
+export async function performUpdate(
+  release: ReleaseInfo,
+  onProgress: (p: UpdateProgress) => void,
+): Promise<void> {
+  if (updateHost) {
+    await updateHost.performUpdate(release, onProgress);
+    return;
+  }
+
+  if (!canSelfUpdate(release)) {
+    const action = release.updateAction;
+    onProgress({
+      phase: "error",
+      error: action.kind === "manual"
+        ? `Run ${action.command}`
+        : action.kind === "managed"
+          ? `Update through the package manager that installed Gloomberb: ${action.reason}.`
+          : "This update type is unavailable in the current runtime.",
+    });
+    return;
+  }
+
+  if (release.updateAction.kind === "desktop") {
+    onProgress({
+      phase: "error",
+      error: "Desktop updates are unavailable outside the packaged desktop app.",
+    });
+    return;
+  }
+
+  const execPath = resolveSelfUpdateTargetPath();
+  if (!execPath) {
+    onProgress({
+      phase: "error",
+      error: "Self-update is unavailable when running from source or via Bun/Node. Relaunch the packaged gloomberb binary to update.",
+    });
+    return;
+  }
+
+  const checksum = /^[a-f\d]{64}$/i.exec(release.checksum ?? "")?.[0].toLowerCase();
+  if (!checksum) {
+    onProgress({ phase: "error", error: "Self-update requires a valid SHA-256 checksum." });
+    return;
+  }
+
+  const updatePath = execPath + ".update";
+  const oldPath = execPath + ".old";
+  let unlinkUpdatePath: ((path: string) => void) | null = null;
+
+  try {
+    const fsModulePath = "fs";
+    const zlibModulePath = "zlib";
+    const cryptoModulePath = "crypto";
+    const {
+      renameSync,
+      unlinkSync,
+      chmodSync,
+    } = await import(fsModulePath) as typeof import("fs");
+    unlinkUpdatePath = unlinkSync;
+    const { gunzipSync } = await import(zlibModulePath) as typeof import("zlib");
+    const { createHash } = await import(cryptoModulePath) as typeof import("crypto");
+
+    onProgress({ phase: "downloading", percent: 0 });
+
+    const res = await fetch(release.downloadUrl);
+    if (!res.ok || !res.body) {
+      throw new Error(`Download failed: ${res.status}`);
+    }
+
+    const contentLength = Number(res.headers.get("content-length") || 0);
+    const reader = res.body.getReader();
+    const chunks: Uint8Array[] = [];
+    let received = 0;
+
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      chunks.push(value);
+      received += value.length;
+      if (contentLength > 0) {
+        onProgress({
+          phase: "downloading",
+          percent: Math.round((received / contentLength) * 100),
+        });
+      }
+    }
+
+    const downloaded = new Uint8Array(received);
+    let offset = 0;
+    for (const chunk of chunks) {
+      downloaded.set(chunk, offset);
+      offset += chunk.byteLength;
+    }
+    const actual = createHash("sha256").update(downloaded).digest("hex");
+    if (actual !== checksum) {
+      throw new Error(`Checksum mismatch: expected ${checksum}, got ${actual}`);
+    }
+    const nextBinary = release.compressed
+      ? new Uint8Array(gunzipSync(downloaded))
+      : downloaded;
+    await Bun.write(updatePath, nextBinary);
+    chmodSync(updatePath, 0o755);
+
+    // Swap binaries
+    onProgress({ phase: "replacing" });
+    try {
+      unlinkSync(oldPath);
+    } catch {}
+    renameSync(execPath, oldPath);
+    try {
+      renameSync(updatePath, execPath);
+    } catch (error) {
+      renameSync(oldPath, execPath);
+      throw error;
+    }
+    try {
+      unlinkSync(oldPath);
+    } catch {}
+
+    onProgress({ phase: "done" });
+  } catch (err: unknown) {
+    // Clean up temp file on failure
+    try {
+      unlinkUpdatePath?.(updatePath);
+    } catch {}
+    onProgress({
+      phase: "error",
+      error: err instanceof Error ? err.message : "Update failed",
+    });
+  }
+}

package/src/utils/async-deadline.ts

@@ -24,3 +24,37 @@ export function withDeadline<T>(
     if (timer) clearTimeout(timer);
   });
 }
+
+/**
+ * The promise's value, or null once it rejects or `timeoutMs` passes. For
+ * optional sources that must neither fail nor hold up the caller.
+ */
+export function settleWithin<T>(promise: Promise<T>, timeoutMs: number): Promise<T | null> {
+  return new Promise<T | null>((resolve) => {
+    const timer = setTimeout(() => resolve(null), timeoutMs);
+    promise.then(
+      (value) => { clearTimeout(timer); resolve(value); },
+      () => { clearTimeout(timer); resolve(null); },
+    );
+  });
+}
+
+/** The error fetch and other cancellable work reject with once aborted. */
+export function abortError(message: string): DOMException {
+  return new DOMException(message, "AbortError");
+}
+
+/**
+ * Settles with the promise, or rejects with an AbortError carrying `message`
+ * as soon as the signal fires. The work itself keeps running, so one consumer
+ * can stop waiting without cancelling a request it shares with others.
+ */
+export function abortable<T>(promise: Promise<T>, signal: AbortSignal | undefined, message: string): Promise<T> {
+  if (!signal) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const abort = () => reject(abortError(message));
+    if (signal.aborted) { abort(); return; }
+    signal.addEventListener("abort", abort, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", abort));
+  });
+}

package/src/utils/calendar-date.ts

@@ -9,3 +9,23 @@ export function calendarMonthsBefore(date: Date, months: number): Date {
   result.setUTCDate(Math.min(day, last.getUTCDate()));
   return result;
 }
+
+/** The UTC calendar date `years` and `days` before `now`, as YYYY-MM-DD; a day that does not exist rolls forward. */
+function isoDateBefore(now: Date, years: number, days: number): string {
+  return new Date(Date.UTC(now.getUTCFullYear() - years, now.getUTCMonth(), now.getUTCDate() - days))
+    .toISOString()
+    .slice(0, 10);
+}
+
+/** Today's UTC calendar date as YYYY-MM-DD. */
+export function isoDateToday(now = new Date()): string {
+  return isoDateBefore(now, 0, 0);
+}
+
+export function isoDateDaysAgo(days: number, now = new Date()): string {
+  return isoDateBefore(now, 0, days);
+}
+
+export function isoDateYearsAgo(years: number, now = new Date()): string {
+  return isoDateBefore(now, years, 0);
+}

package/src/utils/csv.ts

@@ -1,15 +1,32 @@
 export const EXCEL_CSV_BOM = "\uFEFF";
 
+/**
+ * A number as a spreadsheet reads it: optional sign, digits with or without
+ * thousands commas, decimals, an exponent and a trailing percent.
+ */
+const NUMERIC_TEXT = /^[+-]?(?=\.?\d)(?:\d{1,3}(?:,\d{3})+|\d*)(?:\.\d+)?(?:e[+-]?\d+)?%?$/i;
+
+/**
+ * Excel and Sheets run a cell that starts with one of these as a formula.
+ * Leading spaces do not stop them.
+ */
+const FORMULA_START = /^(?:[\t\r]| *[=+\-@])/;
+
+function isNumericCsvText(text: string): boolean {
+  return NUMERIC_TEXT.test(text.trim());
+}
+
 function normalizeCsvCell(value: unknown): string {
   if (value == null) return "";
-  if (value instanceof Date) return value.toISOString();
+  if (value instanceof Date) return Number.isNaN(value.getTime()) ? "" : value.toISOString();
   if (typeof value === "object") return JSON.stringify(value);
   return String(value);
 }
 
 function escapeCsvCell(value: unknown, excelCompatible: boolean): string {
   const normalized = normalizeCsvCell(value);
-  const text = excelCompatible && /^[\t\r ]*[=+\-@]/.test(normalized)
+  // A signed number is data, not a formula: "-2.10" must stay a number.
+  const text = excelCompatible && FORMULA_START.test(normalized) && !isNumericCsvText(normalized)
     ? `'${normalized}`
     : normalized;
   if (!/[",\n\r]/.test(text)) return text;

package/src/utils/datetime-format.ts

@@ -1,3 +1,5 @@
+import { toTimestampMillis } from "./timestamp";
+
 export type DisplayDateValue = Date | string | number | null | undefined;
 
 export function parseDisplayDate(value: DisplayDateValue): Date | null {
@@ -6,21 +8,116 @@ export function parseDisplayDate(value: DisplayDateValue): Date | null {
   return Number.isNaN(date.getTime()) ? null : date;
 }
 
+/**
+ * Whole minutes, hours or days in an age, the one ladder every relative-time
+ * label reads from. Null under a minute, which includes a time in the future.
+ */
+function elapsedUnits(ageMs: number): { count: number; unit: "m" | "h" | "d" } | null {
+  if (!(ageMs >= 60_000)) return null;
+  const minutes = Math.floor(ageMs / 60_000);
+  if (minutes < 60) return { count: minutes, unit: "m" };
+  const hours = Math.floor(minutes / 60);
+  if (hours < 24) return { count: hours, unit: "h" };
+  return { count: Math.floor(hours / 24), unit: "d" };
+}
+
+/** Age for a narrow column: "<1m", "5m", "3h", "2d". */
 export function formatRelativeTime(value: DisplayDateValue, now = Date.now(), fallback = "-"): string {
   const date = parseDisplayDate(value);
   if (!date) return fallback;
 
   const ms = now - date.getTime();
   if (!Number.isFinite(ms)) return fallback;
-  if (ms < 60_000) return "<1m";
+  const elapsed = elapsedUnits(ms);
+  return elapsed ? `${elapsed.count}${elapsed.unit}` : "<1m";
+}
 
-  const min = Math.floor(ms / 60_000);
-  if (min < 60) return `${min}m`;
+/** Age of an epoch-ms timestamp: "just now", "5m ago", "3h ago", "2d ago"; `empty` when unset. */
+export function formatRelativeAge(timestamp: number | undefined, now = Date.now(), empty = "never"): string {
+  if (!timestamp) return empty;
+  const elapsed = elapsedUnits(now - timestamp);
+  return elapsed ? `${elapsed.count}${elapsed.unit} ago` : "just now";
+}
+
+/**
+ * Relative time that turns into a date ("1/5/26") after a week, for feeds read
+ * by recency: "just now", "5m ago", "3h ago", "2d ago". `short` drops the
+ * "ago" for a narrow column ("<1m", "5m").
+ */
+export function formatTimeAgo(date: Date | string, { short = false }: { short?: boolean } = {}): string {
+  const ts = toTimestampMillis(date);
+  if (Number.isNaN(ts)) return "unknown";
+  const elapsed = elapsedUnits(Date.now() - ts);
+  if (!elapsed) return short ? "<1m" : "just now";
+  if (elapsed.unit === "d" && elapsed.count >= 7) {
+    return new Date(ts).toLocaleDateString("en-US", { month: "numeric", day: "numeric", year: "2-digit" });
+  }
+  return `${elapsed.count}${elapsed.unit}${short ? "" : " ago"}`;
+}
+
+export interface ShortDateOptions {
+  /** "Jan 5, 2026" (the default), "Jan 5, 26", or no year at all ("Jan 5"). */
+  year?: "numeric" | "2-digit" | false;
+  /** "2-digit" pads the day so dates line up in a column ("Jan 05"). */
+  day?: "numeric" | "2-digit";
+  /** Read the day in UTC, for date-only values that name a calendar day rather than an instant. */
+  utc?: boolean;
+  /** Shown when the value is missing or does not parse. */
+  fallback?: string;
+}
 
-  const hr = Math.floor(min / 60);
-  if (hr < 24) return `${hr}h`;
+const shortDateFormatters = new Map<string, Intl.DateTimeFormat>();
 
-  return `${Math.floor(hr / 24)}d`;
+/** A month-name date such as "Jan 5, 2026", in local time unless `utc` is set. */
+export function formatShortDate(value: DisplayDateValue, options: ShortDateOptions = {}): string {
+  const date = parseDisplayDate(value);
+  if (!date) return options.fallback ?? "-";
+  const { year = "numeric", day = "numeric", utc = false } = options;
+  const key = `${year}:${day}:${utc}`;
+  let formatter = shortDateFormatters.get(key);
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat("en-US", {
+      month: "short",
+      day,
+      year: year || undefined,
+      timeZone: utc ? "UTC" : undefined,
+    });
+    shortDateFormatters.set(key, formatter);
+  }
+  return formatter.format(date);
+}
+
+const clockFormatter = new Intl.DateTimeFormat("en-US", {
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+});
+const weekdayClockFormatter = new Intl.DateTimeFormat("en-US", {
+  weekday: "short",
+  hour: "2-digit",
+  minute: "2-digit",
+  hourCycle: "h23",
+});
+
+function localMidnight(date: Date): number {
+  return new Date(date.getFullYear(), date.getMonth(), date.getDate()).getTime();
+}
+
+/**
+ * When a feed item was published, in local time, as a newswire prints it:
+ * the time today ("14:32"), the weekday and time over the six days before
+ * ("Mon 09:10"), and the date for anything older ("Sep 18", or "Sep 18, 25"
+ * in another year). A weekday never names a day a week or more back.
+ */
+export function formatFeedTime(value: DisplayDateValue, now = Date.now(), fallback = "-"): string {
+  const date = parseDisplayDate(value);
+  if (!date) return fallback;
+  const today = new Date(now);
+  // Rounded, since a day with a DST change is 23 or 25 hours long.
+  const daysAgo = Math.round((localMidnight(today) - localMidnight(date)) / 86_400_000);
+  if (daysAgo === 0) return clockFormatter.format(date);
+  if (daysAgo > 0 && daysAgo < 7) return weekdayClockFormatter.format(date).replace(",", "");
+  return formatShortDate(date, { year: date.getFullYear() === today.getFullYear() ? false : "2-digit" });
 }
 
 export function formatDetailDate(value: DisplayDateValue, fallback = "-"): string {