Fix pagination parsing and strip ansi from normalized logs

Author: pweiskircher

API.md

@@ -94,7 +94,8 @@ List commands must fill `pagination`.
 }
 ```
 
-Buildkite pagination details come from response headers. If a value is unavailable, set it to `null`.
+Buildkite pagination details come from response headers, primarily the `Link` header.
+If a value is unavailable, set it to `null`.
 
 ## Raw mode
 
@@ -242,6 +243,9 @@ Get one build and include a flattened job summary.
 
 Fetch one job log.
 
+In normalized mode, `data.content` has ANSI and Buildkite control sequences removed.
+Use `--raw` to keep exact Buildkite payloads.
+
 ### Request
 
 ```json

README.md

@@ -51,4 +51,5 @@ bkci annotations list --org ORG --pipeline PIPELINE --build BUILD_NUMBER
 ## Notes
 
 - Use `--raw` on any command to return raw Buildkite payloads inside the envelope.
-- Pagination metadata is included for list endpoints when available.
+- `jobs log get` strips ANSI/control sequences in normalized mode for cleaner LLM output.
+- Pagination metadata is parsed from Buildkite `Link` headers for list endpoints.

src/cli/execute-command.ts

@@ -136,9 +136,16 @@ function mapAnnotation(annotation: unknown): Record<string, unknown> {
   };
 }
 
-function getPaginationOrNull(commandName: ParsedCommand["name"], headers: Headers): Pagination | null {
-  if (commandName === "builds.list") {
-    return parsePagination(headers);
+function getPaginationOrNull(options: {
+  readonly command: ParsedCommand;
+  readonly headers: Headers;
+}): Pagination | null {
+  if (options.command.name === "builds.list") {
+    return parsePagination({
+      headers: options.headers,
+      requestedPage: options.command.args.page,
+      requestedPerPage: options.command.args.perPage,
+    });
   }
   return null;
 }
@@ -254,7 +261,7 @@ export async function executeCommand(options: {
       return {
         request,
         summary: {},
-        pagination: getPaginationOrNull(options.command.name, response.headers),
+        pagination: getPaginationOrNull({ command: options.command, headers: response.headers }),
         data: response.data,
       };
     }
@@ -266,7 +273,7 @@ export async function executeCommand(options: {
         count: builds.length,
         states: getSummaryStates(builds),
       },
-      pagination: getPaginationOrNull(options.command.name, response.headers),
+      pagination: getPaginationOrNull({ command: options.command, headers: response.headers }),
       data: builds,
     };
   }
@@ -326,6 +333,7 @@ export async function executeCommand(options: {
       rawContent,
       maxBytes: options.command.args.maxBytes,
       tailLineCount: options.command.args.tailLines,
+      stripAnsi: true,
     });
 
     return {

src/core/logs.test.ts

@@ -8,6 +8,7 @@ test("transformLogContent applies tail lines first", () => {
     rawContent: "line-1\nline-2\nline-3\nline-4",
     maxBytes: null,
     tailLineCount: 2,
+    stripAnsi: false,
   });
 
   assert.equal(result.content, "line-3\nline-4");
@@ -20,8 +21,25 @@ test("transformLogContent truncates by bytes when maxBytes is set", () => {
     rawContent: "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
     maxBytes: 8,
     tailLineCount: null,
+    stripAnsi: false,
   });
 
   assert.equal(Buffer.byteLength(result.content, "utf8") <= 8, true);
   assert.equal(result.truncated, true);
 });
+
+test("transformLogContent strips ansi and buildkite control sequences", () => {
+  const raw =
+    "\u001b_bk;t=1770510296903\u0007\u001b[38;5;48mINFO\u001b[0m hello\r\nnext-line\u001b[0m";
+
+  const result = transformLogContent({
+    rawContent: raw,
+    maxBytes: null,
+    tailLineCount: null,
+    stripAnsi: true,
+  });
+
+  assert.equal(result.content.includes("\u001b"), false);
+  assert.equal(result.content.includes("\r"), false);
+  assert.equal(result.content.includes("INFO hello"), true);
+});

src/core/logs.ts

@@ -32,14 +32,27 @@ function truncateToMaxBytes(value: string, maxBytes: number): { readonly content
   return { content, truncated: true };
 }
 
+export function stripAnsiAndControlSequences(value: string): string {
+  return value
+    .replace(/\u001b\[[0-9;?]*[ -/]*[@-~]/g, "")
+    .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "")
+    .replace(/\u001b_[^\u0007\u001b]*(?:\u0007|\u001b\\)/g, "")
+    .replace(/\r/g, "");
+}
+
 export function transformLogContent(options: {
   readonly rawContent: string;
   readonly maxBytes: number | null;
   readonly tailLineCount: number | null;
+  readonly stripAnsi: boolean;
 }): LogTransformResult {
+  const sanitized = options.stripAnsi
+    ? stripAnsiAndControlSequences(options.rawContent)
+    : options.rawContent;
+
   const tailed = options.tailLineCount === null
-    ? options.rawContent
-    : tailLines(options.rawContent, options.tailLineCount);
+    ? sanitized
+    : tailLines(sanitized, options.tailLineCount);
 
   const truncated = options.maxBytes === null
     ? { content: tailed, truncated: false }

src/core/pagination.test.ts

@@ -0,0 +1,60 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import { parsePagination } from "./pagination.js";
+
+test("parsePagination derives values from Link header on first page", () => {
+  const headers = new Headers({
+    link: '<https://api.buildkite.com/v2/organizations/acme/pipelines/web/builds?page=2&per_page=3>; rel="next", <https://api.buildkite.com/v2/organizations/acme/pipelines/web/builds?page=42&per_page=3>; rel="last"',
+  });
+
+  const pagination = parsePagination({
+    headers,
+    requestedPage: null,
+    requestedPerPage: 3,
+  });
+
+  assert.deepEqual(pagination, {
+    page: 1,
+    perPage: 3,
+    nextPage: 2,
+    prevPage: null,
+    hasMore: true,
+  });
+});
+
+test("parsePagination uses prev relation to infer current page", () => {
+  const headers = new Headers({
+    link: '<https://api.buildkite.com/v2/organizations/acme/pipelines/web/builds?page=2&per_page=10>; rel="prev", <https://api.buildkite.com/v2/organizations/acme/pipelines/web/builds?page=4&per_page=10>; rel="next"',
+  });
+
+  const pagination = parsePagination({
+    headers,
+    requestedPage: null,
+    requestedPerPage: null,
+  });
+
+  assert.deepEqual(pagination, {
+    page: 3,
+    perPage: 10,
+    nextPage: 4,
+    prevPage: 2,
+    hasMore: true,
+  });
+});
+
+test("parsePagination honors explicit requested page when no headers exist", () => {
+  const pagination = parsePagination({
+    headers: new Headers(),
+    requestedPage: 5,
+    requestedPerPage: 25,
+  });
+
+  assert.deepEqual(pagination, {
+    page: 5,
+    perPage: 25,
+    nextPage: null,
+    prevPage: null,
+    hasMore: false,
+  });
+});

src/core/pagination.ts

@@ -1,21 +1,174 @@
 import type { Pagination } from "./types.js";
 
-function parseNumberHeader(value: string | null): number | null {
-  if (!value) {
+type LinkRelations = {
+  readonly next: URL | null;
+  readonly prev: URL | null;
+  readonly first: URL | null;
+  readonly last: URL | null;
+};
+
+function parseNumber(value: string | null): number | null {
+  if (value === null) {
     return null;
   }
+
   const parsed = Number.parseInt(value, 10);
   if (!Number.isFinite(parsed)) {
     return null;
   }
+
   return parsed;
 }
 
-export function parsePagination(headers: Headers): Pagination {
-  const page = parseNumberHeader(headers.get("x-page"));
-  const perPage = parseNumberHeader(headers.get("x-per-page"));
-  const nextPage = parseNumberHeader(headers.get("x-next-page"));
-  const prevPage = parseNumberHeader(headers.get("x-prev-page"));
+function parseLinkRelations(linkHeader: string | null): LinkRelations {
+  if (linkHeader === null || linkHeader.trim().length === 0) {
+    return {
+      next: null,
+      prev: null,
+      first: null,
+      last: null,
+    };
+  }
+
+  const result: {
+    next: URL | null;
+    prev: URL | null;
+    first: URL | null;
+    last: URL | null;
+  } = {
+    next: null,
+    prev: null,
+    first: null,
+    last: null,
+  };
+
+  const parts = linkHeader.split(",");
+  for (const part of parts) {
+    const match = part.match(/<([^>]+)>\s*;\s*rel="([a-z]+)"/i);
+    if (!match) {
+      continue;
+    }
+
+    const [, href, relation] = match;
+    if (!href || !relation) {
+      continue;
+    }
+
+    try {
+      const parsedUrl = new URL(href);
+      if (relation === "next") {
+        result.next = parsedUrl;
+      } else if (relation === "prev") {
+        result.prev = parsedUrl;
+      } else if (relation === "first") {
+        result.first = parsedUrl;
+      } else if (relation === "last") {
+        result.last = parsedUrl;
+      }
+    } catch {
+      // Ignore malformed URL in link relation.
+    }
+  }
+
+  return result;
+}
+
+function readPageFromUrl(url: URL | null): number | null {
+  if (url === null) {
+    return null;
+  }
+  return parseNumber(url.searchParams.get("page"));
+}
+
+function readPerPageFromUrl(url: URL | null): number | null {
+  if (url === null) {
+    return null;
+  }
+  return parseNumber(url.searchParams.get("per_page"));
+}
+
+function deriveCurrentPage(options: {
+  readonly fromHeader: number | null;
+  readonly requestedPage: number | null;
+  readonly nextPage: number | null;
+  readonly prevPage: number | null;
+  readonly firstPage: number | null;
+}): number | null {
+  if (options.fromHeader !== null) {
+    return options.fromHeader;
+  }
+  if (options.requestedPage !== null) {
+    return options.requestedPage;
+  }
+  if (options.prevPage !== null) {
+    return options.prevPage + 1;
+  }
+  if (options.nextPage !== null && options.nextPage > 1) {
+    return options.nextPage - 1;
+  }
+  if (options.firstPage !== null) {
+    return options.firstPage;
+  }
+  if (options.nextPage !== null) {
+    return 1;
+  }
+  return null;
+}
+
+function derivePerPage(options: {
+  readonly fromHeader: number | null;
+  readonly requestedPerPage: number | null;
+  readonly links: LinkRelations;
+}): number | null {
+  if (options.fromHeader !== null) {
+    return options.fromHeader;
+  }
+  if (options.requestedPerPage !== null) {
+    return options.requestedPerPage;
+  }
+
+  const fromNext = readPerPageFromUrl(options.links.next);
+  if (fromNext !== null) {
+    return fromNext;
+  }
+
+  const fromPrev = readPerPageFromUrl(options.links.prev);
+  if (fromPrev !== null) {
+    return fromPrev;
+  }
+
+  const fromFirst = readPerPageFromUrl(options.links.first);
+  if (fromFirst !== null) {
+    return fromFirst;
+  }
+
+  return readPerPageFromUrl(options.links.last);
+}
+
+export function parsePagination(options: {
+  readonly headers: Headers;
+  readonly requestedPage: number | null;
+  readonly requestedPerPage: number | null;
+}): Pagination {
+  const links = parseLinkRelations(options.headers.get("link"));
+
+  const nextPage = parseNumber(options.headers.get("x-next-page")) ?? readPageFromUrl(links.next);
+  const prevPage = parseNumber(options.headers.get("x-prev-page")) ?? readPageFromUrl(links.prev);
+  const firstPage = readPageFromUrl(links.first);
+
+  const page = deriveCurrentPage({
+    fromHeader: parseNumber(options.headers.get("x-page")),
+    requestedPage: options.requestedPage,
+    nextPage,
+    prevPage,
+    firstPage,
+  });
+
+  const perPage = derivePerPage({
+    fromHeader: parseNumber(options.headers.get("x-per-page")),
+    requestedPerPage: options.requestedPerPage,
+    links,
+  });
 
   return {
     page,