@bussolabs/closeyourit-cli 0.13.0 → 0.14.0

package/dist/base.d.ts

@@ -43,4 +43,15 @@ export declare abstract class BaseCommand extends Command {
      * swallowed (empty stdout, exit looks like a silent success) for machine consumers (CYCL-1).
      */
     protected catch(error: Interfaces.CommandError): Promise<unknown>;
+    /**
+     * After a successful human-mode command, print the pagination footer once. Every list command
+     * renders a single backend page; reading `this.api.lastMeta` (saved by CliApi on the last response)
+     * here keeps the "there are more pages" hint in one place instead of in all 30 of them (CYCL-11).
+     *
+     * Gated on the command actually exposing `--page`: on a download, a lookup, or a `statuses`/`tokens`
+     * list without that flag, `lastMeta` may be stale (e.g. left by `resolveProjectId`) or from a
+     * collection the reader cannot page, and "Use --page N" would point at a flag that does not exist.
+     * Also suppressed on error and in `--json` mode, so machine output stays exact.
+     */
+    protected finally(err: Error | undefined): Promise<unknown>;
 }

package/dist/base.js

@@ -4,6 +4,7 @@ exports.BaseCommand = exports.pageFlag = exports.environmentFlag = exports.proje
 const core_1 = require("@oclif/core");
 const config_1 = require("./lib/config");
 const api_1 = require("./lib/api");
+const output_1 = require("./lib/output");
 const error_codes_1 = require("./errors/error-codes");
 exports.UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 /** Shared `--project <id|key>` flag (required). */
@@ -110,5 +111,23 @@ class BaseCommand extends core_1.Command {
         }
         return super.catch(error);
     }
+    /**
+     * After a successful human-mode command, print the pagination footer once. Every list command
+     * renders a single backend page; reading `this.api.lastMeta` (saved by CliApi on the last response)
+     * here keeps the "there are more pages" hint in one place instead of in all 30 of them (CYCL-11).
+     *
+     * Gated on the command actually exposing `--page`: on a download, a lookup, or a `statuses`/`tokens`
+     * list without that flag, `lastMeta` may be stale (e.g. left by `resolveProjectId`) or from a
+     * collection the reader cannot page, and "Use --page N" would point at a flag that does not exist.
+     * Also suppressed on error and in `--json` mode, so machine output stays exact.
+     */
+    async finally(err) {
+        if (!err && !this.jsonEnabled() && 'page' in (this.ctor.flags ?? {})) {
+            const footer = (0, output_1.paginationFooter)(this.api?.lastMeta);
+            if (footer)
+                this.log(footer);
+        }
+        return super.finally(err);
+    }
 }
 exports.BaseCommand = BaseCommand;

package/dist/lib/api.d.ts

@@ -25,6 +25,13 @@ export interface UploadFile {
 type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE';
 export declare class CliApi {
     private readonly config;
+    /**
+     * Meta of the most recent successful response envelope (`{page, per, total, total_pages}`, or
+     * undefined for non-paginated responses). `BaseCommand.finally` reads it to print the "there are
+     * more pages" footer once per command, instead of threading the envelope through all 30 list
+     * commands (CYCL-11). The instance is per-command, so this is that command's last response.
+     */
+    lastMeta?: Record<string, unknown>;
     constructor(config: CliConfig);
     request<T = unknown>(method: HttpMethod, path: string, opts?: RequestOptions): Promise<Envelope<T>>;
     /**

package/dist/lib/api.js

@@ -18,6 +18,13 @@ class ApiRequestError extends Error {
 exports.ApiRequestError = ApiRequestError;
 class CliApi {
     config;
+    /**
+     * Meta of the most recent successful response envelope (`{page, per, total, total_pages}`, or
+     * undefined for non-paginated responses). `BaseCommand.finally` reads it to print the "there are
+     * more pages" footer once per command, instead of threading the envelope through all 30 list
+     * commands (CYCL-11). The instance is per-command, so this is that command's last response.
+     */
+    lastMeta;
     constructor(config) {
         this.config = config;
     }
@@ -97,7 +104,9 @@ class CliApi {
             const error = envelope.error ?? {};
             throw new ApiRequestError(res.status, error.code ?? `C${res.status}-API-000`, error.message ?? res.statusText ?? `Request failed (${res.status})`, error.details);
         }
-        return (json ?? {});
+        const envelope = (json ?? {});
+        this.lastMeta = envelope.meta;
+        return envelope;
     }
     get(path, opts) {
         return this.request('GET', path, opts);
@@ -132,6 +141,10 @@ class CliApi {
             await this.handleResponse(res); // always throws: maps the JSON error envelope
             throw new ApiRequestError(res.status, `C${res.status}-API-000`, `Download failed (${res.status})`);
         }
+        // A binary payload is not a paginated collection; clear any meta a prior lookup (e.g.
+        // resolveProjectId) left behind so it cannot leak into the pagination footer (CYCL-11). The
+        // success path bypasses handleResponse, so this reset must be explicit.
+        this.lastMeta = undefined;
         const data = new Uint8Array(await res.arrayBuffer());
         const disposition = res.headers.get('content-disposition') ?? '';
         const match = /filename\*?=(?:UTF-8''|")?([^";]+)/i.exec(disposition);

package/dist/lib/output.d.ts

@@ -15,6 +15,14 @@ export declare function sanitizeMultiline(value: unknown): string;
 export declare function displayWidth(value: string): number;
 /** Minimal dependency-free table renderer for human output. */
 export declare function renderTable(headers: string[], rows: string[][]): string;
+/**
+ * Footer line telling the reader that the human table is only one backend page of a larger set:
+ * without it, page 1 reads as the whole collection and a 900-ticket project looks like 10 (CYCL-11).
+ * Returns undefined when nothing more follows — a single page, the last page, or a collection already
+ * aggregated by `fetchAllPages` (whose last saved meta has `page === total_pages`) — so complete
+ * output stays clean. Callers gate on `!jsonEnabled()`, so machine output never sees this.
+ */
+export declare function paginationFooter(meta: unknown): string | undefined;
 /**
  * Status dots make problems scannable at a glance. Four fixed-width circles (no variation
  * selectors, so table columns stay aligned): down=🔴, warn=🟡, ok=🟢, neutral=⚪.

package/dist/lib/output.js

@@ -4,6 +4,7 @@ exports.sanitize = sanitize;
 exports.sanitizeMultiline = sanitizeMultiline;
 exports.displayWidth = displayWidth;
 exports.renderTable = renderTable;
+exports.paginationFooter = paginationFooter;
 exports.statusDot = statusDot;
 exports.statusCell = statusCell;
 exports.section = section;
@@ -72,6 +73,25 @@ function renderTable(headers, rows) {
     const separator = widths.map((width) => '-'.repeat(width));
     return [line(safeHeaders), line(separator), ...safeRows.map(line)].join('\n');
 }
+/**
+ * Footer line telling the reader that the human table is only one backend page of a larger set:
+ * without it, page 1 reads as the whole collection and a 900-ticket project looks like 10 (CYCL-11).
+ * Returns undefined when nothing more follows — a single page, the last page, or a collection already
+ * aggregated by `fetchAllPages` (whose last saved meta has `page === total_pages`) — so complete
+ * output stays clean. Callers gate on `!jsonEnabled()`, so machine output never sees this.
+ */
+function paginationFooter(meta) {
+    if (!meta || typeof meta !== 'object')
+        return undefined;
+    const { page, total, total_pages: totalPages } = meta;
+    const current = Number(page);
+    const last = Number(totalPages);
+    if (!Number.isInteger(current) || !Number.isInteger(last) || current < 1 || current >= last)
+        return undefined;
+    const count = Number(total);
+    const totalPart = Number.isFinite(count) ? ` — ${count} items total` : '';
+    return `Showing page ${current} of ${last}${totalPart}. Use --page ${current + 1} to see more.`;
+}
 const TONE_DOT = {
     down: '🔴',
     neutral: '⚪',