@tailglow/cli 0.7.1 → 0.9.4

package/src/index.js

@@ -20,6 +20,7 @@ import {
   renderResourceHelp,
   renderRootHelp
 } from "./help.js";
+import { IMPORT_PARSER_OPTIONS } from "./import-options.js";
 import {
   createLoginContext,
   runLoginCommand,
@@ -35,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" };
@@ -60,7 +62,11 @@ const LOGIN_PARSER_OPTIONS = {
   new: { type: "boolean" }
 };
 
-const PARSER_OPTIONS = { ...LOGIN_PARSER_OPTIONS, ...buildParserOptions(CLI_COMMANDS) };
+const PARSER_OPTIONS = {
+  ...LOGIN_PARSER_OPTIONS,
+  ...IMPORT_PARSER_OPTIONS,
+  ...buildParserOptions(CLI_COMMANDS)
+};
 
 /** @param {string[]} argv */
 export function parseFlags(argv) {
@@ -206,6 +212,10 @@ async function confirmDestructive(command, flags) {
  */
 export async function run(argv, login_context = createLoginContext()) {
   const { values: flags, positionals } = parseFlags(argv);
+  if (positionals[0] === "import") {
+    const { runImportCommand } = await import("./import-command.js");
+    return runImportCommand(argv);
+  }
 
   try {
     normalizeSwitches(flags);
@@ -411,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.
@@ -426,7 +439,10 @@ if (isEntrypoint()) {
         ["login", "logout", "whoami"].includes(positionals[0]) ||
         (positionals[0] === "config" && ["set", "unset"].includes(positionals[1])));
     process.exitCode = result.code;
-    writeCommandResult(result, { json, message });
+    if (positionals[0] === "import" && json) {
+      // Import reports include partial delivery state, so scripts always receive one stdout JSON document.
+      process.stdout.write(result.output + "\n");
+    } else writeCommandResult(result, { json, message });
   } catch (err) {
     process.exitCode = 1;
     const message = err instanceof Error ? err.message : String(err);
@@ -435,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;
+  }
+}