@tailglow/cli 0.8.1 → 0.9.5

package/src/import-command.js

@@ -23,7 +23,6 @@ const HELP_NOTES = [
   "Upload previews a bounded sample, then validates records while sending bounded batches.",
   "--validate-first copies a private snapshot and checks it fully before upload; it needs temporary disk space approximately equal to the input size.",
   "Default upload reads one open file and stops if it detects changes. Do not edit it during import.",
-  "Selected timestamps must exist and be unambiguous. Distinct times may produce small batches.",
   "Only HTTP 202 acknowledges a batch. Delivery uncertainty stops upload without retrying.",
   "Ctrl-C reports accepted rows and any uncertain batch. Retrying a partial import may duplicate rows."
 ];
@@ -35,7 +34,6 @@ const HELP = [
   "",
   "--format auto|xml|jsonl|json|csv|tsv",
   "--record-path /root/item   Optional XML filter; imports all top-level entries by default.",
-  "--timestamp-field FIELD  JSON pointer or exact top-level name; never selected automatically.",
   "--workers auto|0|N       XML worker threads for full reads; auto uses 2 from 32 MiB.",
   "--validate-first         Check a private snapshot completely before uploading it.",
   "--ingest-url URL         Explicit ingest URL, including its key. Keep this credential private.",
@@ -256,7 +254,6 @@ async function resolveDestination(flags, signal, request, read_config) {
     }
   }
   url.searchParams.set("collection", String(flags.collection));
-  url.searchParams.delete("ts");
   return { url, project_id };
 }
 
@@ -474,9 +471,6 @@ export async function runImportCommand(argv, context = {}) {
     const options = Object.freeze({
       format: detection.format,
       ...(typeof flags["record-path"] === "string" ? { record_path: flags["record-path"] } : {}),
-      ...(typeof flags["timestamp-field"] === "string"
-        ? { timestamp_field: flags["timestamp-field"] }
-        : {}),
       workers,
       create_worker: () => createNodeImportWorker(IMPORT_WORKER_URL),
       onworkers,
@@ -502,7 +496,6 @@ export async function runImportCommand(argv, context = {}) {
       throw new Error("The full file check did not finish.");
     total_rows = report.is_complete && !report.is_sampled ? report.row_count : null;
     outcome = "destination_failed";
-    const batch_options = Object.freeze({ timestamp_field: options.timestamp_field });
     const destination = await resolveDestination(
       flags,
       signal,
@@ -513,14 +506,10 @@ export async function runImportCommand(argv, context = {}) {
     const readiness = await getJson(destination.url, {}, signal, request);
     if (readiness?.status !== "ready" || readiness.project_id !== destination.project_id)
       throw new Error("The ingest endpoint is not ready for the expected project.");
-    if (options.timestamp_field)
-      stderr.write("Preserving selected timestamps; distinct values may produce small batches.\n");
     outcome = "validation_failed";
-    for await (const batch of createImportBatches(readImportRows(source, options), batch_options)) {
+    for await (const batch of createImportBatches(readImportRows(source, options))) {
       checkAbort(signal);
       await input.assertUnchanged();
-      const target = new URL(destination.url);
-      if (batch.timestamp) target.searchParams.set("ts", batch.timestamp);
       affected_batch = {
         index: batch.index,
         first_row: batch.rows[0].index,
@@ -530,7 +519,7 @@ export async function runImportCommand(argv, context = {}) {
       outcome = "uncertain_delivery";
       const linked = requestSignal(signal, 30_000);
       try {
-        const response = await request(target, {
+        const response = await request(destination.url, {
           method: "POST",
           headers: { "Content-Type": "application/x-ndjson" },
           body: batch.body,

package/src/import-options.js

@@ -6,7 +6,6 @@
 export const IMPORT_PARSER_OPTIONS = {
   format: { type: "string" },
   "record-path": { type: "string" },
-  "timestamp-field": { type: "string" },
   "ingest-url": { type: "string" },
   collection: { type: "string" },
   "project-id": { type: "string" },

package/src/import-worker.generated.js

@@ -1254,6 +1254,27 @@ class ImportRowError extends Error {
   }
 }
 
+// packages/import/src/batch.js
+var encoder2 = new TextEncoder;
+function serializeImportRow(row) {
+  const line = JSON.stringify(row.record);
+  if (line === undefined || line.length + 1 > IMPORT_BATCH_BYTES)
+    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
+  const bytes = encoder2.encode(line).byteLength + 1;
+  if (bytes > IMPORT_BATCH_BYTES)
+    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
+  return { row, line, bytes };
+}
+
+// packages/import/src/row.js
+function createImportRow(record, index) {
+  if (!record || typeof record !== "object" || Array.isArray(record))
+    throw new ImportRowError(index, " must be a JSON object.");
+  const row = { index, record };
+  serializeImportRow(row);
+  return row;
+}
+
 // packages/import/src/timestamp.js
 function getImportField(record, path) {
   if (!path.startsWith("/"))
@@ -1325,41 +1346,6 @@ function parseImportTimestamp(value) {
 function isAmbiguousTimestamp(value) {
   return typeof value === "string" && (/^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?$/.test(value) || /-00:?00$/.test(value));
 }
-function getRowTimestamp(row, timestamp_field) {
-  if (!timestamp_field)
-    return null;
-  const value = getImportField(row.record, timestamp_field);
-  const timestamp = parseImportTimestamp(value);
-  if (!timestamp)
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is missing, invalid or timezone-ambiguous. Choose an explicit timezone or a different field.`);
-  const milliseconds = Date.parse(timestamp);
-  if (milliseconds < 0)
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is before 1970-01-01T00:00:00Z and cannot be used as an import timestamp.`);
-  if (milliseconds > Date.now())
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is in the future and cannot be used as an import timestamp.`);
-  return timestamp;
-}
-
-// packages/import/src/batch.js
-var encoder2 = new TextEncoder;
-function serializeImportRow(row) {
-  const line = JSON.stringify(row.record);
-  if (line === undefined || line.length + 1 > IMPORT_BATCH_BYTES)
-    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
-  const bytes = encoder2.encode(line).byteLength + 1;
-  if (bytes > IMPORT_BATCH_BYTES)
-    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
-  return { row, line, bytes };
-}
-
-// packages/import/src/row.js
-function createImportRow(record, index) {
-  if (!record || typeof record !== "object" || Array.isArray(record))
-    throw new ImportRowError(index, " must be a JSON object.");
-  const row = { index, record };
-  serializeImportRow(row);
-  return row;
-}
 
 // packages/import/src/scan-profile.js
 var IMPORT_PROFILE_FIELDS = 256;
@@ -1367,7 +1353,7 @@ var MAX_DEPTH = 16;
 var MAX_PATH_CHARS = 4096;
 var MAX_VISITED_FIELDS = 2048;
 var PREVIEW_ROWS = 12;
-function createScanProfile({ timestamp_field, max_fields = IMPORT_PROFILE_FIELDS } = {}) {
+function createScanProfile({ max_fields = IMPORT_PROFILE_FIELDS } = {}) {
   const fields = new Map;
   const preview = [];
   let rows = 0;
@@ -1470,7 +1456,6 @@ function createScanProfile({ timestamp_field, max_fields = IMPORT_PROFILE_FIELDS
     },
     add(row) {
       const entry = serializeImportRow(row);
-      getRowTimestamp(row, timestamp_field);
       rows++;
       max_row_bytes = Math.max(max_row_bytes, entry.bytes);
       if (preview.length < PREVIEW_ROWS)
@@ -1575,10 +1560,7 @@ var IMPORT_XML_TASK = {
         }
       };
     }
-    const createProfile = () => createScanProfile({
-      timestamp_field: options.timestamp_field,
-      max_fields: PARTIAL_PROFILE_FIELDS
-    });
+    const createProfile = () => createScanProfile({ max_fields: PARTIAL_PROFILE_FIELDS });
     let profile = createProfile();
     return {
       add(record) {

package/src/import.generated.d.ts

@@ -104,12 +104,8 @@ export interface ImportReport {
 }
 export interface ImportScanOptions extends ImportOptions {
   is_full?: boolean;
-  /** Selected timestamps must be valid, explicit-zone values between the Unix epoch and now. */
-  timestamp_field?: string;
 }
 export interface ImportBatchOptions {
-  /** Selected timestamps must be valid, explicit-zone values between the Unix epoch and now. */
-  timestamp_field?: string;
   max_bytes?: number;
   max_rows?: number;
 }
@@ -118,7 +114,6 @@ export interface ImportBatch {
   body: string;
   bytes: number;
   rows: ImportRow[];
-  timestamp: string | null;
 }
 export const IMPORT_BATCH_BYTES: number;
 export const IMPORT_BATCH_ROWS: number;

package/src/import.generated.js

@@ -3913,6 +3913,61 @@ class ImportRowError extends Error {
   }
 }
 
+// packages/import/src/batch.js
+var encoder2 = new TextEncoder;
+function serializeImportRow(row) {
+  const line = JSON.stringify(row.record);
+  if (line === undefined || line.length + 1 > IMPORT_BATCH_BYTES)
+    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
+  const bytes = encoder2.encode(line).byteLength + 1;
+  if (bytes > IMPORT_BATCH_BYTES)
+    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
+  return { row, line, bytes };
+}
+async function* createImportBatches(rows, options = {}) {
+  const max_bytes = options.max_bytes ?? IMPORT_BATCH_BYTES;
+  const max_rows = options.max_rows ?? IMPORT_BATCH_ROWS;
+  if (!Number.isSafeInteger(max_bytes) || max_bytes < 1 || max_bytes > IMPORT_BATCH_BYTES)
+    throw new RangeError("max_bytes must be between 1 and 1048576.");
+  if (!Number.isSafeInteger(max_rows) || max_rows < 1 || max_rows > IMPORT_BATCH_ROWS)
+    throw new RangeError("max_rows must be between 1 and 500.");
+  let batch_rows = [];
+  let body = "";
+  let bytes = 0;
+  let index = 0;
+  function finish() {
+    const batch = { index: ++index, body, bytes, rows: batch_rows };
+    batch_rows = [];
+    body = "";
+    bytes = 0;
+    return batch;
+  }
+  for await (const row of rows) {
+    const entry = serializeImportRow(row);
+    if (entry.bytes > max_bytes)
+      throw new Error(`Row ${row.index} exceeds max_bytes (${max_bytes}).`);
+    if (batch_rows.length && bytes + entry.bytes > max_bytes)
+      yield finish();
+    batch_rows.push(row);
+    body += entry.line + `
+`;
+    bytes += entry.bytes;
+    if (batch_rows.length === max_rows || bytes === max_bytes)
+      yield finish();
+  }
+  if (batch_rows.length)
+    yield finish();
+}
+
+// packages/import/src/row.js
+function createImportRow(record, index) {
+  if (!record || typeof record !== "object" || Array.isArray(record))
+    throw new ImportRowError(index, " must be a JSON object.");
+  const row = { index, record };
+  serializeImportRow(row);
+  return row;
+}
+
 // packages/import/src/timestamp.js
 function getImportField(record, path) {
   if (!path.startsWith("/"))
@@ -3984,78 +4039,6 @@ function parseImportTimestamp(value) {
 function isAmbiguousTimestamp(value) {
   return typeof value === "string" && (/^\d{4}-\d{2}-\d{2}(?:[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?)?$/.test(value) || /-00:?00$/.test(value));
 }
-function getRowTimestamp(row, timestamp_field) {
-  if (!timestamp_field)
-    return null;
-  const value = getImportField(row.record, timestamp_field);
-  const timestamp = parseImportTimestamp(value);
-  if (!timestamp)
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is missing, invalid or timezone-ambiguous. Choose an explicit timezone or a different field.`);
-  const milliseconds = Date.parse(timestamp);
-  if (milliseconds < 0)
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is before 1970-01-01T00:00:00Z and cannot be used as an import timestamp.`);
-  if (milliseconds > Date.now())
-    throw new ImportRowError(row.index, `: timestamp field ${JSON.stringify(timestamp_field)} is in the future and cannot be used as an import timestamp.`);
-  return timestamp;
-}
-
-// packages/import/src/batch.js
-var encoder2 = new TextEncoder;
-function serializeImportRow(row) {
-  const line = JSON.stringify(row.record);
-  if (line === undefined || line.length + 1 > IMPORT_BATCH_BYTES)
-    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
-  const bytes = encoder2.encode(line).byteLength + 1;
-  if (bytes > IMPORT_BATCH_BYTES)
-    throw new ImportRowError(row.index, " exceeds the 1 MiB record limit.");
-  return { row, line, bytes };
-}
-async function* createImportBatches(rows, options = {}) {
-  const max_bytes = options.max_bytes ?? IMPORT_BATCH_BYTES;
-  const max_rows = options.max_rows ?? IMPORT_BATCH_ROWS;
-  if (!Number.isSafeInteger(max_bytes) || max_bytes < 1 || max_bytes > IMPORT_BATCH_BYTES)
-    throw new RangeError("max_bytes must be between 1 and 1048576.");
-  if (!Number.isSafeInteger(max_rows) || max_rows < 1 || max_rows > IMPORT_BATCH_ROWS)
-    throw new RangeError("max_rows must be between 1 and 500.");
-  let batch_rows = [];
-  let body = "";
-  let bytes = 0;
-  let index = 0;
-  let timestamp = null;
-  function finish() {
-    const batch = { index: ++index, body, bytes, rows: batch_rows, timestamp };
-    batch_rows = [];
-    body = "";
-    bytes = 0;
-    return batch;
-  }
-  for await (const row of rows) {
-    const entry = serializeImportRow(row);
-    const next_timestamp = getRowTimestamp(row, options.timestamp_field);
-    if (entry.bytes > max_bytes)
-      throw new Error(`Row ${row.index} exceeds max_bytes (${max_bytes}).`);
-    if (batch_rows.length && (bytes + entry.bytes > max_bytes || timestamp !== next_timestamp))
-      yield finish();
-    timestamp = next_timestamp;
-    batch_rows.push(row);
-    body += entry.line + `
-`;
-    bytes += entry.bytes;
-    if (batch_rows.length === max_rows || bytes === max_bytes)
-      yield finish();
-  }
-  if (batch_rows.length)
-    yield finish();
-}
-
-// packages/import/src/row.js
-function createImportRow(record, index) {
-  if (!record || typeof record !== "object" || Array.isArray(record))
-    throw new ImportRowError(index, " must be a JSON object.");
-  const row = { index, record };
-  serializeImportRow(row);
-  return row;
-}
 
 // packages/import/src/scan-profile.js
 var IMPORT_PROFILE_FIELDS = 256;
@@ -4063,7 +4046,7 @@ var MAX_DEPTH = 16;
 var MAX_PATH_CHARS = 4096;
 var MAX_VISITED_FIELDS = 2048;
 var PREVIEW_ROWS = 12;
-function createScanProfile({ timestamp_field, max_fields = IMPORT_PROFILE_FIELDS } = {}) {
+function createScanProfile({ max_fields = IMPORT_PROFILE_FIELDS } = {}) {
   const fields = new Map;
   const preview = [];
   let rows = 0;
@@ -4166,7 +4149,6 @@ function createScanProfile({ timestamp_field, max_fields = IMPORT_PROFILE_FIELDS
     },
     add(row) {
       const entry = serializeImportRow(row);
-      getRowTimestamp(row, timestamp_field);
       rows++;
       max_row_bytes = Math.max(max_row_bytes, entry.bytes);
       if (preview.length < PREVIEW_ROWS)
@@ -4286,10 +4268,7 @@ var IMPORT_XML_TASK = {
         }
       };
     }
-    const createProfile = () => createScanProfile({
-      timestamp_field: options.timestamp_field,
-      max_fields: PARTIAL_PROFILE_FIELDS
-    });
+    const createProfile = () => createScanProfile({ max_fields: PARTIAL_PROFILE_FIELDS });
     let profile = createProfile();
     return {
       add(record) {
@@ -4405,11 +4384,8 @@ async function* readXmlRowsWithWorkers(source, options, requested) {
 }
 async function scanXmlWithWorkers(source, options, requested) {
   const state = { status: { requested, actual: 0 } };
-  const profile = createScanProfile({ timestamp_field: options.timestamp_field });
-  for await (const event of readImportXmlSegments(source, options, requested, {
-    kind: "scan",
-    timestamp_field: options.timestamp_field
-  })) {
+  const profile = createScanProfile();
+  for await (const event of readImportXmlSegments(source, options, requested, { kind: "scan" })) {
     if (!reportWorkerEvent(event, state, options))
       return null;
     if (event.type !== "records")
@@ -4657,8 +4633,6 @@ async function scanImport(source, options = {}) {
     report.warnings.push("Schema discovery was truncated (256 fields, 16 levels, 4096 characters per path or 2048 visited fields per row). Counts cover scanned rows only.");
   if (report.is_sampled)
     report.warnings.push("This bounded sample does not certify full file validity or schema coverage. Records must be validated as they are imported.");
-  if (options.timestamp_field)
-    report.warnings.push("The selected timestamp is sent at request level. Changes between rows split batches and may produce many small requests.");
   options.onprogress?.({
     bytes_read: report.bytes_read,
     total_bytes: source.size,
@@ -4684,7 +4658,7 @@ async function scanSequentially(source, options, format, report) {
       }
     }
   };
-  const profile = createScanProfile({ timestamp_field: options.timestamp_field });
+  const profile = createScanProfile();
   report.bytes_read = 0;
   try {
     for await (const row of readImportRows(scanned_source, {

package/src/index.js

@@ -36,6 +36,7 @@ import {
   writeCommandResult
 } from "./output.js";
 import { requestAllPages, requestApi } from "./request.js";
+import { readUpdateNotice } from "./update-check.js";
 
 /** Path parameters people refer to by the shorter name they actually type. */
 const PATH_ALIASES = { project_id: "project", team_id: "team" };
@@ -420,6 +421,9 @@ function isEntrypoint() {
 }
 
 if (isEntrypoint()) {
+  // Started first so it runs alongside the command, and printed to stderr after the result.
+  const update_notice = readUpdateNotice();
+
   // `process.exit` discards whatever is still buffered for a pipe, and a pipe's buffer is 64 KB.
   // `tglow records list --all --json | jq` would receive a JSON document cut off mid-value, which
   // is exactly the invariant this CLI sells. Set the code and let the write drain instead.
@@ -447,4 +451,14 @@ if (isEntrypoint()) {
       { json }
     );
   }
+
+  // A failed command in JSON mode answers with one JSON document on stderr, so it gets no notice.
+  // Nothing about the notice may fail a finished command, a closed stderr included.
+  const notice = await update_notice;
+  if (notice && !(json && process.exitCode !== 0)) {
+    process.stderr.on("error", () => {});
+    try {
+      process.stderr.write(`${notice}\n`);
+    } catch {}
+  }
 }

package/src/request.js

@@ -25,17 +25,25 @@ const LOGIN_REFUSAL_ADVICE = {
 
 /**
  * Headers every request carries. The team header picks which of a person's teams a CLI session acts
- * on; an API key belongs to one team and ignores it.
+ * on; an API key belongs to one team and ignores it. The terminal and platform name the device in
+ * the team's authentication log, since the CLI has no browser user agent to read it from.
  *
- * @param {{ secret: string | null; team_id: string | null }} options
+ * @param {{ secret: string | null; team_id: string | null; env?: NodeJS.ProcessEnv }} options
  */
-export async function buildRequestHeaders({ secret, team_id }) {
+export async function buildRequestHeaders({ secret, team_id, env = process.env }) {
   /** @type {Record<string, string>} */
   const headers = {
     "Content-Type": "application/json",
     "x-tailglow-client": "cli",
-    "x-tailglow-client-version": await readCliVersion()
+    "x-tailglow-client-version": await readCliVersion(),
+    "x-tailglow-client-platform": process.platform
   };
+
+  // fetch throws on some header characters, such as a line break, so only a plain name is sent.
+  const terminal = env.TERM_PROGRAM?.trim();
+  if (terminal && /^[\w .+-]{1,32}$/.test(terminal)) {
+    headers["x-tailglow-client-terminal"] = terminal;
+  }
   if (secret) headers.Authorization = `Bearer ${secret}`;
   if (team_id) headers["x-tailglow-team-id"] = team_id;
   return headers;

package/src/update-check.js

@@ -0,0 +1,137 @@
+import { constants } from "node:fs";
+import fs from "node:fs/promises";
+import https from "node:https";
+import { CLI_CONFIGS, readCliVersion, saveConfig } from "./config.js";
+
+/** @typedef {{ checked_at: number; latest_version: string | null }} UpdateCheck */
+
+/** @param {string} version */
+function parseVersion(version) {
+  return /^(\d+)\.(\d+)\.(\d+)$/.exec(version)?.slice(1).map(Number) ?? null;
+}
+
+/**
+ * Whether `candidate` is a later release than `installed`. Only plain `x.y.z` versions compare;
+ * anything else never counts as newer.
+ *
+ * @param {string} candidate
+ * @param {string} installed
+ */
+export function isNewerVersion(candidate, installed) {
+  const next = parseVersion(candidate);
+  const current = parseVersion(installed);
+  if (!next || !current) return false;
+  for (let index = 0; index < 3; index += 1) {
+    if (next[index] !== current[index]) return next[index] > current[index];
+  }
+  return false;
+}
+
+/**
+ * The stored check, when the path holds a small regular file. Opened without blocking, so a pipe
+ * left at the path cannot hang the command.
+ *
+ * @param {string} path
+ * @returns {Promise<UpdateCheck | null>}
+ */
+async function readUpdateCheck(path) {
+  /** @type {import("node:fs/promises").FileHandle | null} */
+  let handle = null;
+  try {
+    handle = await fs.open(path, constants.O_RDONLY | constants.O_NONBLOCK);
+    const stats = await handle.stat();
+    if (!stats.isFile() || stats.size > CLI_CONFIGS.UPDATE_CHECK_MAX_BYTES) return null;
+    const stored = JSON.parse(await handle.readFile("utf-8"));
+    if (typeof stored?.checked_at !== "number") return null;
+    const latest_version = typeof stored.latest_version === "string" ? stored.latest_version : null;
+    return { checked_at: stored.checked_at, latest_version };
+  } catch {
+    return null;
+  } finally {
+    await handle?.close().catch(() => {});
+  }
+}
+
+/** @param {string} body */
+function readManifestVersion(body) {
+  try {
+    const manifest = JSON.parse(body);
+    return typeof manifest?.version === "string" ? manifest.version : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The version npm tags `latest`, or null. `node:https` rather than fetch: an aborted Node fetch
+ * keeps a stalled connection, and with it the process, alive for about ten more seconds, while an
+ * aborted request here closes its socket.
+ *
+ * @returns {Promise<string | null>}
+ */
+function fetchLatestVersion() {
+  return new Promise((resolve) => {
+    const request = https.get(
+      CLI_CONFIGS.UPDATE_CHECK_URL,
+      { signal: AbortSignal.timeout(CLI_CONFIGS.UPDATE_CHECK_TIMEOUT_MS) },
+      (response) => {
+        let body = "";
+        response.setEncoding("utf-8");
+        response.on("data", (chunk) => {
+          body += chunk;
+          if (body.length > CLI_CONFIGS.UPDATE_CHECK_MAX_BYTES) request.destroy();
+        });
+        response.on("end", () =>
+          resolve(response.statusCode === 200 ? readManifestVersion(body) : null)
+        );
+        // Settles an aborted or destroyed response; after `end` the promise has already resolved.
+        response.on("close", () => resolve(null));
+      }
+    );
+    request.on("error", () => resolve(null));
+    // A request can also end with no response and no error, such as an upgrade nothing accepts.
+    request.on("close", () => resolve(null));
+  });
+}
+
+/**
+ * The line to print when a newer release is published, or null. npm is asked at most once a day,
+ * failed attempts included, so an offline machine is not slowed down on every command. Never
+ * throws: a missing answer only means no notice.
+ *
+ * @param {{
+ *   env?: NodeJS.ProcessEnv;
+ *   fetch_latest_version?: () => Promise<string | null>;
+ *   now?: number;
+ *   path?: string;
+ * }} [options]
+ * @returns {Promise<string | null>}
+ */
+export async function readUpdateNotice({
+  env = process.env,
+  fetch_latest_version = fetchLatestVersion,
+  now = Date.now(),
+  path = CLI_CONFIGS.UPDATE_CHECK_PATH
+} = {}) {
+  if (env.CI || env.TAILGLOW_NO_UPDATE_CHECK) return null;
+  try {
+    let check = await readUpdateCheck(path);
+    if (!check || now - check.checked_at >= CLI_CONFIGS.UPDATE_CHECK_INTERVAL_MS) {
+      const previous = check?.latest_version ?? null;
+      // Recorded before npm is asked: an attempt that cannot be recorded is not made, so a machine
+      // that cannot write the file is never slowed down on every command.
+      await saveConfig({ checked_at: now, latest_version: previous }, path);
+      check = { checked_at: now, latest_version: (await fetch_latest_version()) ?? previous };
+      if (check.latest_version !== previous) await saveConfig(check, path);
+    }
+
+    const installed = await readCliVersion();
+    if (!check.latest_version || !isNewerVersion(check.latest_version, installed)) return null;
+    return (
+      `tglow ${check.latest_version} is available (you have ${installed}). ` +
+      "Update with `npm install -g @tailglow/cli@latest`, or run `npx @tailglow/cli@latest`."
+    );
+  } catch {
+    return null;
+  }
+}