@tailglow/cli 0.5.1 → 0.6.1

package/src/config-command.js

@@ -3,9 +3,9 @@ import {
   CONFIG_KEYS,
   isSecretSetting,
   loadConfig,
-  loadConfigForWrite,
+  readStoredLogin,
   redactSetting,
-  saveConfig
+  updateConfig
 } from "./config.js";
 import { RESERVED_FLAGS } from "./flags.js";
 import { shouldEmitJson } from "./output.js";
@@ -107,7 +107,7 @@ export async function runConfigCommand(words, flags) {
     const stored = await loadConfig();
     const entries = Object.keys(CONFIG_KEYS)
       .filter((name) => typeof stored[name] === "string")
-      .map((name) => [name, redactSetting(name, stored[name])]);
+      .map((name) => [name, redactSetting(name, String(stored[name]))]);
 
     if (json) return { output: JSON.stringify(Object.fromEntries(entries), null, 2), code: 0 };
     if (entries.length === 0) {
@@ -149,19 +149,23 @@ export async function runConfigCommand(words, flags) {
 
   if (action === "set") {
     if (!value) return fail(`Missing a value for ${key}.`, flags);
-    const stored = await loadConfigForWrite();
-    await saveConfig({ ...stored, [key]: value });
+    const next = await updateConfig((stored) => ({ ...stored, [key]: value }));
+
+    // A `tglow login` credential outranks a stored key, so setting one would otherwise look like it
+    // took effect when every command keeps using the login.
+    const outranked = key === "api_key" && readStoredLogin(next) !== null;
+    const note = outranked
+      ? "\nYou are signed in with `tglow login`, which is used first. Run `tglow logout` to use this key."
+      : "";
     return succeed(
-      `Set ${key} to ${redactSetting(key, value)}.`,
-      { ok: true, key, value: redactSetting(key, value) },
+      `Set ${key} to ${redactSetting(key, value)}.${note}`,
+      { ok: true, key, value: redactSetting(key, value), outranked_by_login: outranked },
       flags
     );
   }
 
   if (action === "unset") {
-    const stored = await loadConfigForWrite();
-    const { [key]: _removed, ...rest } = stored;
-    await saveConfig(rest);
+    await updateConfig(({ [key]: _removed, ...rest }) => rest);
     return succeed(`Removed ${key}.`, { ok: true, key, removed: true }, flags);
   }
 

package/src/config.js

@@ -1,9 +1,12 @@
+import { randomUUID } from "node:crypto";
 import fs from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 export const CLI_CONFIGS = {
   DEFAULT_API_URL: "https://api.tailglow.io",
+  DOCS_URL: "https://docs.tailglow.io",
   CONFIG_PATH: join(homedir(), ".tailglow", "config.json"),
   // The API caps a page at 200, so the default is 50 requests. Deliberately a guardrail rather than
   // a ceiling: `--max` moves it, and hitting it always prints the cursor to continue from.
@@ -11,7 +14,25 @@ export const CLI_CONFIGS = {
   PAGE_SIZE: 200,
   // Nobody else may read the file: it holds an API key. 0700 on the directory for the same reason.
   FILE_MODE: 0o600,
-  DIRECTORY_MODE: 0o700
+  DIRECTORY_MODE: 0o700,
+  LOCK_RETRY_MS: 50,
+  // The lock covers one small read and write, so waiting this long means its holder stopped.
+  LOCK_TIMEOUT_MS: 10_000
+};
+
+export const LOGIN_CONFIGS = {
+  /** `tglow login --wait` stops starting polls after this long and exits with `EXIT_PENDING`. */
+  WAIT_BUDGET_MS: 60_000,
+  /** Fallback lifetime for pending sign-ins saved before the API expiry was stored. */
+  INTERACTIVE_BUDGET_MS: 10 * 60 * 1_000,
+  REQUEST_TIMEOUT_MS: 30_000,
+  DEFAULT_INTERVAL_MS: 5_000,
+  /** Added to the interval each time the server answers `slow_down`. */
+  SLOW_DOWN_STEP_MS: 5_000,
+  /** A waiting sign-in the server never answered for is forgotten after this long. */
+  PENDING_FORGET_MS: 60 * 60 * 1_000,
+  /** EX_TEMPFAIL: still waiting, so a script can tell "run it again" apart from a failure. */
+  EXIT_PENDING: 75
 };
 
 /**
@@ -35,6 +56,17 @@ export function isSecretSetting(key) {
   return SECRET_KEYS.has(key);
 }
 
+/** @type {Promise<string> | null} */
+let version_read = null;
+
+/** The installed CLI's version, read once. */
+export function readCliVersion() {
+  version_read ??= fs
+    .readFile(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf-8")
+    .then((manifest) => String(JSON.parse(manifest).version));
+  return version_read;
+}
+
 /**
  * Reads the stored config, if there is one.
  *
@@ -43,7 +75,7 @@ export function isSecretSetting(key) {
  * another way. That includes a file holding a bare `null`, which parses fine and is not an object.
  *
  * @param {string} [path]
- * @returns {Promise<Record<string, string>>}
+ * @returns {Promise<import("./types.d.ts").CliConfig>}
  */
 export async function loadConfig(path = CLI_CONFIGS.CONFIG_PATH) {
   try {
@@ -63,7 +95,7 @@ export async function loadConfig(path = CLI_CONFIGS.CONFIG_PATH) {
  * whatever the file actually held, which for a file holding an API key is silent credential loss.
  *
  * @param {string} [path]
- * @returns {Promise<Record<string, string>>}
+ * @returns {Promise<import("./types.d.ts").CliConfig>}
  */
 export async function loadConfigForWrite(path = CLI_CONFIGS.CONFIG_PATH) {
   /** @type {string} */
@@ -93,7 +125,7 @@ export async function loadConfigForWrite(path = CLI_CONFIGS.CONFIG_PATH) {
     );
   }
 
-  return /** @type {Record<string, string>} */ (parsed);
+  return /** @type {import("./types.d.ts").CliConfig} */ (parsed);
 }
 
 /**
@@ -104,7 +136,7 @@ export async function loadConfigForWrite(path = CLI_CONFIGS.CONFIG_PATH) {
  * and chmodding afterwards leaves a window where the key is on disk and readable; a temp file
  * created at 0600 and renamed into place never has one.
  *
- * @param {Record<string, string>} values
+ * @param {import("./types.d.ts").CliConfig} values
  * @param {string} [path]
  */
 export async function saveConfig(values, path = CLI_CONFIGS.CONFIG_PATH) {
@@ -112,7 +144,7 @@ export async function saveConfig(values, path = CLI_CONFIGS.CONFIG_PATH) {
   await fs.mkdir(directory, { recursive: true, mode: CLI_CONFIGS.DIRECTORY_MODE });
   await fs.chmod(directory, CLI_CONFIGS.DIRECTORY_MODE);
 
-  const staged = `${path}.${process.pid}.tmp`;
+  const staged = `${path}.${process.pid}.${Date.now()}.tmp`;
   try {
     await fs.writeFile(staged, `${JSON.stringify(values, null, 2)}\n`, {
       mode: CLI_CONFIGS.FILE_MODE,
@@ -126,6 +158,79 @@ export async function saveConfig(values, path = CLI_CONFIGS.CONFIG_PATH) {
   }
 }
 
+/**
+ * Removes the lock if it still holds `token`. Only its holder writes a token and nothing else
+ * removes a lock, so a matching token means the lock is still this process's.
+ *
+ * @param {string} lock_path
+ * @param {string} token
+ */
+async function releaseLock(lock_path, token) {
+  if ((await fs.readFile(lock_path, "utf-8").catch(() => null)) === token) {
+    await fs.rm(lock_path, { force: true });
+  }
+}
+
+/**
+ * Runs `callback` holding the config lock: a file created with O_EXCL next to the config, so a
+ * `tglow login --wait` finishing while `tglow config set` runs cannot lose either write. A lock is
+ * never taken over: one left by a process that stopped mid-write makes the next change wait, then
+ * name the file to delete.
+ *
+ * @template T
+ * @param {() => Promise<T>} callback
+ * @param {string} [path]
+ * @param {{ timeout_ms?: number }} [options]
+ * @returns {Promise<T>}
+ */
+export async function withConfigLock(
+  callback,
+  path = CLI_CONFIGS.CONFIG_PATH,
+  { timeout_ms = CLI_CONFIGS.LOCK_TIMEOUT_MS } = {}
+) {
+  const lock_path = `${path}.lock`;
+  const token = `${process.pid}:${randomUUID()}`;
+  await fs.mkdir(dirname(path), { recursive: true, mode: CLI_CONFIGS.DIRECTORY_MODE });
+
+  const started_at = Date.now();
+  while (true) {
+    try {
+      await fs.writeFile(lock_path, token, { flag: "wx", mode: CLI_CONFIGS.FILE_MODE });
+      break;
+    } catch (err) {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code !== "EEXIST") throw err;
+      if (Date.now() - started_at > timeout_ms) {
+        throw new Error(
+          `Another tglow process is changing ${path}, or one stopped while changing it. ` +
+            `If no tglow is running, delete ${lock_path} and try again.`
+        );
+      }
+      await new Promise((resolve) => setTimeout(resolve, CLI_CONFIGS.LOCK_RETRY_MS));
+    }
+  }
+
+  try {
+    return await callback();
+  } finally {
+    await releaseLock(lock_path, token);
+  }
+}
+
+/**
+ * Read-modify-write of the config under the lock. `mutate` receives what the file holds NOW, not
+ * what the caller read earlier, and returns the complete next contents.
+ *
+ * @param {(current: import("./types.d.ts").CliConfig) => import("./types.d.ts").CliConfig} mutate
+ * @param {string} [path]
+ */
+export async function updateConfig(mutate, path = CLI_CONFIGS.CONFIG_PATH) {
+  return withConfigLock(async () => {
+    const next = mutate(await loadConfigForWrite(path));
+    await saveConfig(next, path);
+    return next;
+  }, path);
+}
+
 /**
  * @param {string} key
  * @param {string} value
@@ -135,6 +240,46 @@ export function redactSetting(key, value) {
   return value.length <= 8 ? "********" : `${value.slice(0, 4)}...${value.slice(-4)}`;
 }
 
+/** @param {unknown} value */
+function isNonEmptyString(value) {
+  return typeof value === "string" && value.length > 0;
+}
+
+/**
+ * The credential `tglow login` stored, when the file holds a complete one.
+ *
+ * @param {import("./types.d.ts").CliConfig} config
+ * @returns {import("./types.d.ts").StoredLogin | null}
+ */
+export function readStoredLogin(config) {
+  const login = config.login;
+  if (!login || typeof login !== "object" || Array.isArray(login)) return null;
+  const fields = /** @type {Record<string, unknown>} */ (login);
+  if (fields.type !== "session" && fields.type !== "api_key") return null;
+  for (const name of ["secret", "id", "api_url", "team_id", "user_id", "email"]) {
+    if (!isNonEmptyString(fields[name])) return null;
+  }
+  return /** @type {import("./types.d.ts").StoredLogin} */ (login);
+}
+
+/**
+ * The sign-in `tglow login` started and is waiting to collect, when the file holds one.
+ *
+ * @param {import("./types.d.ts").CliConfig} config
+ * @returns {import("./types.d.ts").PendingLogin | null}
+ */
+export function readPendingLogin(config) {
+  const pending = config.pending_login;
+  if (!pending || typeof pending !== "object" || Array.isArray(pending)) return null;
+  const fields = /** @type {Record<string, unknown>} */ (pending);
+  if (fields.method !== "account" && fields.method !== "api_key") return null;
+  for (const name of ["id", "poll_secret", "user_code", "verification_url", "api_url"]) {
+    if (!isNonEmptyString(fields[name])) return null;
+  }
+  if (typeof fields.started_at !== "number") return null;
+  return /** @type {import("./types.d.ts").PendingLogin} */ (pending);
+}
+
 /**
  * Resolves one setting.
  *
@@ -146,7 +291,7 @@ export function redactSetting(key, value) {
  * @param {{
  *   flags?: Record<string, unknown>;
  *   env?: NodeJS.ProcessEnv;
- *   config?: Record<string, string>;
+ *   config?: import("./types.d.ts").CliConfig;
  * }} [sources]
  * @returns {string | null}
  */
@@ -161,22 +306,71 @@ export function resolveSetting(name, { flags = {}, env = process.env, config = {
   return typeof stored === "string" && stored.length > 0 ? stored : null;
 }
 
-/** @param {{ flags?: Record<string, unknown>; config?: Record<string, string> }} [options] */
+/**
+ * @param {{
+ *   flags?: Record<string, unknown>;
+ *   env?: NodeJS.ProcessEnv;
+ *   config?: import("./types.d.ts").CliConfig;
+ * }} [options]
+ */
 export function resolveApiUrl(options = {}) {
   return resolveSetting("api_url", options) ?? CLI_CONFIGS.DEFAULT_API_URL;
 }
 
 /**
- * @param {{ flags?: Record<string, unknown>; config?: Record<string, string> }} [options]
- * @returns {string}
+ * Whether two API URLs name the same API, compared as origins so a trailing slash or a path does
+ * not make them differ.
+ *
+ * @param {string} first
+ * @param {string} second
+ */
+export function isSameApiUrl(first, second) {
+  try {
+    return new URL(first).origin === new URL(second).origin;
+  } catch {
+    return first === second;
+  }
+}
+
+/**
+ * The credential a command authenticates with.
+ *
+ * `--api-key` beats `TAILGLOW_API_KEY`, which beats the `tglow login` credential, which beats a
+ * stored `api_key`. A login credential is only ever sent to the API that issued it: pointing
+ * `--api-url` elsewhere needs an explicit key rather than handing the login to another host.
+ *
+ * @param {{
+ *   flags?: Record<string, unknown>;
+ *   env?: NodeJS.ProcessEnv;
+ *   config?: import("./types.d.ts").CliConfig;
+ * }} [options]
+ * @returns {import("./types.d.ts").ResolvedCredential}
  */
-export function resolveApiKey(options = {}) {
-  const key = resolveSetting("api_key", options);
-  if (!key) {
+export function resolveCredential({ flags = {}, env = process.env, config = {} } = {}) {
+  const flag = flags["api-key"];
+  if (isNonEmptyString(flag)) return { secret: String(flag), source: "flag", login: null };
+
+  const from_env = env.TAILGLOW_API_KEY;
+  if (isNonEmptyString(from_env)) return { secret: String(from_env), source: "env", login: null };
+
+  const login = readStoredLogin(config);
+  const api_url = resolveApiUrl({ flags, env, config });
+  if (login && isSameApiUrl(login.api_url, api_url)) {
+    return { secret: login.secret, source: "login", login };
+  }
+
+  const stored = config.api_key;
+  if (isNonEmptyString(stored)) return { secret: String(stored), source: "config", login: null };
+
+  if (login) {
     throw new Error(
-      "No API key. Set TAILGLOW_API_KEY, or run `tglow config set api_key <key>`.\n" +
-        "Create a key in the dashboard under Team settings."
+      `You are signed in to ${login.api_url}, not ${api_url}, and a sign-in is never sent to ` +
+        "another API. Pass --api-key for this one, or run `tglow login --api-url " +
+        `${api_url}\`.`
     );
   }
-  return key;
+  throw new Error(
+    "Not signed in. Run `tglow login`, or set TAILGLOW_API_KEY to an API key.\n" +
+      "Create a key in the dashboard under Team settings."
+  );
 }

package/src/docs-command.js

@@ -0,0 +1,139 @@
+import { CLI_CONFIGS } from "./config.js";
+import { DOCS_INDEX, DOCS_PAGES } from "./docs.generated.js";
+import { RESERVED_FLAGS } from "./flags.js";
+
+/**
+ * @param {string} message
+ * @param {boolean} json
+ */
+function fail(message, json) {
+  return { output: json ? JSON.stringify({ error: message }) : message, code: 1 };
+}
+
+/**
+ * Reduces whatever was copied out of the index or the docs site to a page key, so
+ * `/guides/sdk.md#installation`, `https://docs.tailglow.io/guides/sdk` and `guides/sdk` all read
+ * the same page.
+ *
+ * @param {string} reference
+ */
+export function toDocsPath(reference) {
+  return reference
+    .replace(/^https?:\/\/[^/]+/, "")
+    .replace(/[#?].*$/, "")
+    .replace(/^\/+|\/+$/g, "")
+    .replace(/\.md$/, "");
+}
+
+/** @param {string} path */
+function findSimilarPaths(path) {
+  const name = (path.split("/").pop() ?? path).toLowerCase();
+  if (!name) return [];
+
+  return Object.keys(DOCS_PAGES)
+    .filter((candidate) => {
+      const candidate_name = (candidate.split("/").pop() ?? candidate).toLowerCase();
+      return candidate_name.includes(name) || name.includes(candidate_name);
+    })
+    .slice(0, 5);
+}
+
+function renderDocsHelp() {
+  return [
+    "tglow docs: every guide and API reference page, as markdown",
+    "",
+    "Usage:",
+    "  tglow docs          The index: every page, with the link to read it by",
+    "  tglow docs <path>   One page: tglow docs guides/sdk, or any link from the index",
+    "",
+    "Pages print as markdown even when piped. --json returns { path, url, content } for a page,",
+    "or { index, pages, online } for the index.",
+    "The pages ship with this version of the CLI, so they describe the commands it has.",
+    `The latest copies are online at ${CLI_CONFIGS.DOCS_URL}/llms.txt.`
+  ].join("\n");
+}
+
+/**
+ * `tglow docs [path]` prints the documentation the CLI was built with, so an agent working in a
+ * terminal never has to leave it to learn the product.
+ *
+ * Markdown unless `--json` is passed, even into a pipe: every other command switches to JSON there,
+ * but the reader of a docs page is almost always an agent, and a page wrapped in a JSON string
+ * arrives with every newline escaped.
+ *
+ * @param {string[]} words
+ * @param {Record<string, unknown>} flags
+ * @returns {{ output: string; code: number }}
+ */
+export function runDocsCommand(words, flags) {
+  const [reference, ...rest] = words.filter((word) => word !== undefined);
+  const json = Boolean(flags.json);
+
+  const unknown = Object.keys(flags).filter((flag) => !RESERVED_FLAGS.has(flag));
+  if (unknown.length > 0) {
+    return fail(
+      `Unknown flag${unknown.length === 1 ? "" : "s"}: ${unknown.map((flag) => `--${flag}`).join(", ")}.`,
+      json
+    );
+  }
+  if (rest.length > 0) {
+    return fail(`Unexpected argument${rest.length === 1 ? "" : "s"}: ${rest.join(", ")}.`, json);
+  }
+
+  if (flags.help) {
+    return {
+      output: json
+        ? JSON.stringify(
+            {
+              usage: "tglow docs [path]",
+              description: "Print the documentation index, or one page of it, as markdown.",
+              pages: Object.keys(DOCS_PAGES).length,
+              online: `${CLI_CONFIGS.DOCS_URL}/llms.txt`
+            },
+            null,
+            2
+          )
+        : renderDocsHelp(),
+      code: 0
+    };
+  }
+
+  if (!reference) {
+    if (json) {
+      return {
+        output: JSON.stringify(
+          {
+            index: DOCS_INDEX,
+            pages: Object.keys(DOCS_PAGES),
+            online: `${CLI_CONFIGS.DOCS_URL}/llms.txt`
+          },
+          null,
+          2
+        ),
+        code: 0
+      };
+    }
+
+    return {
+      output: `${DOCS_INDEX.trimEnd()}\n\nRead a page with \`tglow docs <link>\`, for example \`tglow docs /guides/agents.md\`.`,
+      code: 0
+    };
+  }
+
+  const path = toDocsPath(reference);
+  const content = Object.hasOwn(DOCS_PAGES, path) ? DOCS_PAGES[path] : null;
+
+  if (content === null) {
+    const similar = findSimilarPaths(path);
+    const hint =
+      similar.length > 0
+        ? ` Did you mean ${similar.map((candidate) => `\`${candidate}\``).join(", ")}?`
+        : "";
+    return fail(`No docs page "${reference}".${hint} Run \`tglow docs\` for the index.`, json);
+  }
+
+  const url = `${CLI_CONFIGS.DOCS_URL}/${path}.md`;
+  if (json) return { output: JSON.stringify({ path, url, content }, null, 2), code: 0 };
+
+  return { output: `${content.trimEnd()}\n\nLatest version online: ${url}`, code: 0 };
+}