@tailglow/cli 0.2.0

package/src/output.js

@@ -0,0 +1,148 @@
+/**
+ * Whether to emit machine-readable output.
+ *
+ * `--json` is explicit, but a pipe is treated as the same request: `tglow metrics list | jq` should
+ * work without anyone remembering a flag, and an agent capturing stdout gets JSON by default rather
+ * than a table it has to unpick. A TTY is the only place a human is watching, so it is the only
+ * place a table is the right answer.
+ *
+ * @param {{ json?: unknown }} flags
+ * @param {{ isTTY?: boolean }} [stream]
+ */
+export function shouldEmitJson(flags, stream = process.stdout) {
+  return Boolean(flags.json) || !stream.isTTY;
+}
+
+/**
+ * Renders control characters visibly instead of letting a terminal act on them.
+ *
+ * Every string here came from the API, which means it came from whoever named the resource. A
+ * project named with an embedded newline forges a row in someone elses table, and one carrying an
+ * ANSI erase-display sequence clears their screen. JSON output escapes these already; the human
+ * table is the path that has to do it itself.
+ *
+ * The range covers C1 as well as C0, because a terminal in 8-bit mode reads U+009B as CSI and will
+ * act on it exactly as it acts on the two-character escape form.
+ *
+ * @param {string} value
+ */
+export function sanitizeText(value) {
+  /** @type {Record<string, string>} */
+  const escapes = { "\n": "\\n", "\r": "\\r", "\t": "\\t" };
+
+  return value.replaceAll(/[\u0000-\u001f\u007f-\u009f]/g, (character) => {
+    if (escapes[character]) return escapes[character];
+    return `\\u${character.charCodeAt(0).toString(16).padStart(4, "0")}`;
+  });
+}
+
+/** @param {unknown} value */
+function toCell(value) {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return sanitizeText(value);
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
+  if (Array.isArray(value)) return `${value.length} item${value.length === 1 ? "" : "s"}`;
+  return "{...}";
+}
+
+/**
+ * Columns worth showing first, when a row has them. A generated CLI has no per-resource opinion, so
+ * this is the one piece of presentation the registry cannot supply: every resource shares an id and
+ * most share a name, and those are what someone scanning a list is looking for.
+ */
+const PREFERRED_COLUMNS = ["id", "name", "slug", "status", "object"];
+
+/** @param {Record<string, unknown>[]} rows */
+function selectColumns(rows) {
+  const present = new Set(rows.flatMap((row) => Object.keys(row)));
+  const preferred = PREFERRED_COLUMNS.filter((column) => present.has(column));
+  const remaining = [...present].filter(
+    (column) => !preferred.includes(column) && !column.endsWith("_at")
+  );
+
+  return [...preferred, ...remaining].slice(0, 6);
+}
+
+/**
+ * @param {unknown} data
+ * @returns {string}
+ */
+export function formatTable(data) {
+  const rows = Array.isArray(data) ? data : [data];
+  if (rows.length === 0) return "No results.";
+  if (rows.some((row) => typeof row !== "object" || row === null)) {
+    return rows.map((row) => sanitizeText(String(row))).join("\n");
+  }
+
+  const columns = selectColumns(/** @type {Record<string, unknown>[]} */ (rows));
+  const header = columns.map((column) => sanitizeText(column.toUpperCase()));
+  const body = rows.map((row) =>
+    columns.map((column) => toCell(/** @type {Record<string, unknown>} */ (row)[column]))
+  );
+  const widths = header.map((_, index) =>
+    Math.max(header[index].length, ...body.map((cells) => cells[index].length))
+  );
+
+  return [header, ...body]
+    .map((cells) =>
+      cells
+        .map((cell, index) => cell.padEnd(widths[index]))
+        .join("  ")
+        .trimEnd()
+    )
+    .join("\n");
+}
+
+/**
+ * Renders one API response.
+ *
+ * JSON mode emits the payload exactly as the API sent it, envelope and all. That is what makes a
+ * scripted follow-up possible: the pagination cursors and the message travel with the data instead
+ * of being thrown away on the way to stdout. A terminal gets the part a person came for, or the
+ * message when the call returns no data at all, which is how a delete reports itself.
+ *
+ * @param {{ data?: unknown; message?: unknown } | null} payload
+ * @param {{ json?: unknown }} flags
+ * @param {{ isTTY?: boolean }} [stream]
+ */
+export function renderResponse(payload, flags, stream = process.stdout) {
+  if (shouldEmitJson(flags, stream)) return JSON.stringify(payload, null, 2);
+
+  const data = payload && "data" in payload ? payload.data : payload;
+  if (data === null || data === undefined) {
+    return typeof payload?.message === "string" ? sanitizeText(payload.message) : "Done.";
+  }
+
+  return formatTable(data);
+}
+
+/**
+ * Renders a `--all` run, including whether it stopped early.
+ *
+ * The truncation notice cannot be appended to JSON as prose: `--all --max=1 | jq` would receive a
+ * valid document followed by a sentence, and fail exactly when a caller pulling large results needs
+ * the continuation cursor most. So machine output carries it as fields instead.
+ *
+ * @param {{
+ *   data: unknown[];
+ *   truncated: boolean;
+ *   next_cursor: string | null;
+ *   resume_command: string;
+ * }} result
+ * @param {{ json?: unknown }} flags
+ * @param {{ isTTY?: boolean }} [stream]
+ */
+export function renderPagedResult(
+  { data, truncated, next_cursor, resume_command },
+  flags,
+  stream = process.stdout
+) {
+  if (shouldEmitJson(flags, stream)) {
+    return JSON.stringify({ data, truncated, next_cursor }, null, 2);
+  }
+
+  const table = formatTable(data);
+  if (!truncated) return table;
+
+  return `${table}\n\nStopped at the result cap. Continue with:\n  ${sanitizeText(resume_command)}`;
+}

package/src/request.js

@@ -0,0 +1,212 @@
+import { CLI_CONFIGS, resolveApiKey, resolveApiUrl } from "./config.js";
+import { sanitizeText } from "./output.js";
+
+/**
+ * Renders a field-level validation failure as lines instead of a wall of escaped JSON.
+ *
+ * The API reports these as a zod issue array serialised INTO the message string, so the default
+ * rendering is a single line of `[\n {\n \"code\": ...` that a reader has to decode by eye. Every
+ * reviewer who hit one said the same thing: the information was right there and unreadable.
+ *
+ * @param {string} message
+ * @returns {string | null}
+ */
+export function formatValidationIssues(message) {
+  if (!message.trimStart().startsWith("[")) return null;
+
+  /** @type {unknown} */
+  let issues;
+  try {
+    issues = JSON.parse(message);
+  } catch {
+    return null;
+  }
+  if (!Array.isArray(issues) || issues.length === 0) return null;
+
+  // Each piece is sanitized on its own, because the assembled string carries real newlines that the
+  // reader is meant to see. Sanitizing the whole thing afterwards would escape those too.
+  const lines = issues.map((issue) => {
+    const where =
+      Array.isArray(issue?.path) && issue.path.length > 0
+        ? sanitizeText(issue.path.join("."))
+        : null;
+    const detail = sanitizeText(
+      typeof issue?.message === "string" ? issue.message : JSON.stringify(issue)
+    );
+    return where ? `  ${where}: ${detail}` : `  ${detail}`;
+  });
+
+  return ["The API rejected these fields:", ...lines].join("\n");
+}
+
+/**
+ * What went wrong, said in a way that names the next move.
+ *
+ * A bare "The requested resource was not found" cannot tell you WHICH id was wrong, which matters
+ * most on nested paths where either the parent or the child could be the miss. The address answers
+ * that without the CLI having to know anything about id formats.
+ *
+ * @param {{ status: number; message: unknown; method: string; url: URL }} failure
+ */
+function describeFailure({ status, message, method, url }) {
+  // Parsed BEFORE sanitizing: escaping the newlines the API embedded would stop it parsing at all,
+  // which is how the first attempt at this silently fell through to the raw dump.
+  const issues = formatValidationIssues(String(message));
+  if (issues) return `${status} ${issues}`;
+
+  const text = sanitizeText(String(message));
+  if (status === 404) {
+    return `${status} ${text}\nNothing answers ${method} ${sanitizeText(url.pathname)}.`;
+  }
+
+  return `${status} ${text}`;
+}
+
+/**
+ * Reads a response body as the API's envelope.
+ *
+ * `JSON.parse` returns an unknown shape, so the runtime check below is what makes the type true: an
+ * array or a bare scalar is not an envelope and reads as no body at all.
+ *
+ * @param {string} text
+ * @returns {import("./types.d.ts").ApiResponse | null}
+ */
+function readEnvelope(text) {
+  /** @type {unknown} */
+  const value = JSON.parse(text);
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+
+  return /** @type {import("./types.d.ts").ApiResponse} */ (value);
+}
+
+/**
+ * @param {{
+ *   method: string;
+ *   path: string;
+ *   query?: Record<string, unknown>;
+ *   body?: Record<string, unknown>;
+ *   flags?: Record<string, unknown>;
+ *   config?: Record<string, string>;
+ * }} options
+ * @returns {Promise<import("./types.d.ts").ApiResponse | null>}
+ */
+export async function requestApi({ method, path, query = {}, body = {}, flags = {}, config = {} }) {
+  const url = new URL(path, resolveApiUrl({ flags, config }));
+  for (const [key, value] of Object.entries(query)) {
+    if (value === undefined || value === null) continue;
+    url.searchParams.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
+  }
+
+  const response = await fetch(url, {
+    method,
+    headers: {
+      Authorization: `Bearer ${resolveApiKey({ flags, config })}`,
+      "Content-Type": "application/json"
+    },
+    body: method === "GET" ? undefined : JSON.stringify(body)
+  });
+
+  const body_text = await response.text();
+
+  /** @type {import("./types.d.ts").ApiResponse | null} */
+  let payload = null;
+  let parsed = true;
+  if (body_text.trim() !== "") {
+    try {
+      payload = readEnvelope(body_text);
+    } catch {
+      parsed = false;
+    }
+  }
+
+  if (!response.ok) {
+    const message = payload?.error?.message || payload?.message || response.statusText;
+    throw new Error(describeFailure({ status: response.status, message, method, url }));
+  }
+
+  // A 2xx body that is not JSON means something between here and the API answered instead: a proxy
+  // error page, a truncated response. Treating it as `null` would print an empty result and exit 0,
+  // which under `--all` reads as "that is everything".
+  if (!parsed) {
+    throw new Error(`${response.status} response was not JSON. Check --api-url.`);
+  }
+
+  return payload;
+}
+
+/**
+ * Follows `pagination.next_cursor` until the API runs out or the cap is reached.
+ *
+ * The cap is the point. Records and collection documents are unbounded in this product, so an
+ * uncapped follow would happily pull millions of rows into a terminal. It is deliberately NOT a
+ * per-resource rule: the registry does not know which resources are large, and a hand-maintained
+ * list of dangerous ones is exactly the sort of thing that drifts out of date.
+ *
+ * Every request asks for at most the rows still allowed under the cap, so the run always stops on a
+ * page boundary. That is what makes the reported cursor exact: fetching a full page and discarding
+ * its tail would hand back a cursor positioned before rows that were never shown, and resuming from
+ * it would repeat them.
+ *
+ * Stopping is always reported with the cursor to resume from, because a silent truncation reads as
+ * "this is everything", which is how a partial set becomes a wrong conclusion.
+ *
+ * @param {{
+ *   method: string;
+ *   path: string;
+ *   query?: Record<string, unknown>;
+ *   flags?: Record<string, unknown>;
+ *   config?: Record<string, string>;
+ *   max?: number;
+ * }} options
+ * @returns {Promise<{ data: unknown[]; truncated: boolean; next_cursor: string | null }>}
+ */
+export async function requestAllPages({
+  method,
+  path,
+  query = {},
+  flags = {},
+  config = {},
+  max = CLI_CONFIGS.DEFAULT_MAX_RECORDS
+}) {
+  /** @type {unknown[]} */
+  const collected = [];
+  /** @type {string | null} */
+  let cursor = typeof query.after === "string" ? query.after : null;
+  /** @type {Set<string>} */
+  const seen_cursors = new Set(cursor ? [cursor] : []);
+
+  for (;;) {
+    const payload = await requestApi({
+      method,
+      path,
+      query: {
+        ...query,
+        limit: Math.min(max - collected.length, CLI_CONFIGS.PAGE_SIZE),
+        ...(cursor ? { after: cursor } : {})
+      },
+      flags,
+      config
+    });
+
+    const page = Array.isArray(payload?.data) ? payload.data : [];
+    collected.push(...page);
+
+    const next = payload?.pagination?.next_cursor ?? null;
+    if (!next || page.length === 0) return { data: collected, truncated: false, next_cursor: null };
+
+    // Checked BEFORE the cap. A page that both reaches the cap and hands back a cursor already used
+    // would otherwise be reported as resumable, and the continuation printed for it re-fetches the
+    // same rows forever.
+    if (seen_cursors.has(next)) {
+      throw new Error(
+        `Pagination stopped advancing after ${collected.length} results: the API returned a cursor ` +
+          "that was already used. Nothing was lost, but the run is incomplete."
+      );
+    }
+
+    if (collected.length >= max) return { data: collected, truncated: true, next_cursor: next };
+
+    seen_cursors.add(next);
+    cursor = next;
+  }
+}

package/src/types.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The shape of `commands.generated.js`.
+ *
+ * Declared by hand and asserted onto the generated module, so a change to the generator's output
+ * fails the type check here rather than at the first flag someone tries to pass.
+ */
+
+/**
+ * The envelope every API route returns.
+ *
+ * Declared rather than inferred from `Response.json()`, whose type differs between the `@types/bun`
+ * versions this package is checked under: on its own, and again through `apps/api`'s config when
+ * the end-to-end test imports it.
+ */
+export interface ApiResponse {
+  data?: unknown;
+  message?: string;
+  pagination?: { next_cursor?: string | null } | null;
+  error?: { message?: string } | null;
+}
+
+/** One value an operation accepts, in whichever of the three places it belongs. */
+export interface CliField {
+  /** Snake_case, as the API names it. `--flag-name` is this with underscores swapped for hyphens. */
+  name: string;
+  /** The wire type, which decides how a flag string is coerced. `object`-prefixed types take JSON. */
+  type: string;
+  required: boolean;
+  /** Customer-facing copy from the reference. Empty when the field documents itself. */
+  description: string;
+  /** Populated for enum-typed fields. Empty when the field accepts open values. */
+  allowed_values: string[];
+  /** The replacement to use instead, when the field is on its way out. */
+  deprecated: string | null;
+}
+
+/** One API operation, addressed as `<resource> <command>`. */
+export interface CliCommand {
+  resource: string;
+  command: string;
+  /** Stable machine identity, unique across the whole API. */
+  operation_id: string;
+  summary: string;
+  description: string;
+  method: string;
+  path: string;
+  /** Equivalent paths the same operation answers on, usually a nested form of `path`. */
+  alternate_paths: string[];
+  scopes: string[];
+  /** Behaviour the field table cannot express, from the route's `@docs` tags. */
+  notes: string[];
+  path_params: CliField[];
+  query_params: CliField[];
+  body_fields: CliField[];
+}