@xano/cli 1.0.6-beta.0 → 1.0.6-beta.10

package/dist/utils/flatten.d.ts

@@ -0,0 +1,36 @@
+/** Outcome of flattening one bundle file. */
+export interface FlattenResult {
+    /** True when the original bundle was removed. */
+    removedSource: boolean;
+    /** Why the file was skipped, if it was (empty / single-document). */
+    skipped?: 'empty' | 'single';
+    /** Absolute paths written (or that would be written, in dry-run). */
+    written: string[];
+}
+export interface FlattenOptions {
+    /** Preview only — compute the plan and write nothing, delete nothing. */
+    dryRun?: boolean;
+    /** Overwrite existing destination files instead of throwing on a clash. */
+    force?: boolean;
+    /** Keep the original bundle file (default: delete after a successful split). */
+    keepSource?: boolean;
+    /** Optional line logger (e.g. command.log) for a per-file plan. */
+    log?: (msg: string) => void;
+    /** Output root (default: the bundle file's own directory). */
+    outputDir?: string;
+}
+/**
+ * Split ONE multi-document `.xs` bundle (documents joined by `---`) into the
+ * standard per-document tree — the exact layout `pull` produces — using the
+ * shared `placeDocuments` placement so the two never drift.
+ *
+ * Filesystem-touching, but self-contained: it reads the bundle, resolves every
+ * document's destination, checks for collisions, writes, and (unless
+ * `keepSource`) removes the original. Throws on a destination collision when
+ * `force` is not set, and never deletes the source when a written document
+ * landed on the source's own path.
+ *
+ * Shared by the `flatten` command and the push-time prompt, so a user who
+ * confirms "flatten now?" gets byte-identical output to running `xano flatten`.
+ */
+export declare function flattenBundleFile(bundleFile: string, opts?: FlattenOptions): FlattenResult;

package/dist/utils/flatten.js

@@ -0,0 +1,68 @@
+import snakeCase from 'lodash.snakecase';
+import * as fs from 'node:fs';
+import { basename, dirname, join, relative, resolve } from 'node:path';
+import { placeDocuments, splitMultidoc } from './document-parser.js';
+/**
+ * Split ONE multi-document `.xs` bundle (documents joined by `---`) into the
+ * standard per-document tree — the exact layout `pull` produces — using the
+ * shared `placeDocuments` placement so the two never drift.
+ *
+ * Filesystem-touching, but self-contained: it reads the bundle, resolves every
+ * document's destination, checks for collisions, writes, and (unless
+ * `keepSource`) removes the original. Throws on a destination collision when
+ * `force` is not set, and never deletes the source when a written document
+ * landed on the source's own path.
+ *
+ * Shared by the `flatten` command and the push-time prompt, so a user who
+ * confirms "flatten now?" gets byte-identical output to running `xano flatten`.
+ */
+export function flattenBundleFile(bundleFile, opts = {}) {
+    const { dryRun = false, force = false, keepSource = false, log } = opts;
+    const content = fs.readFileSync(bundleFile, 'utf8').trim();
+    const documents = splitMultidoc(content);
+    if (documents.length === 0)
+        return { removedSource: false, skipped: 'empty', written: [] };
+    if (documents.length === 1)
+        return { removedSource: false, skipped: 'single', written: [] };
+    const outputDir = opts.outputDir ? resolve(opts.outputDir) : dirname(bundleFile);
+    const placed = placeDocuments(documents, { join, relative, snakeCase });
+    // Pre-check destination collisions (unless --force / dry-run). A written file
+    // landing on the source's own path is not a clash — it replaces the bundle.
+    if (!dryRun && !force) {
+        const clashes = placed
+            .map((p) => join(outputDir, p.relPath))
+            .filter((abs) => fs.existsSync(abs) && resolve(abs) !== resolve(bundleFile));
+        if (clashes.length > 0) {
+            throw new Error(`Destination file(s) already exist (use --force to overwrite):\n` +
+                clashes.map((c) => `    ${relative(process.cwd(), c) || c}`).join('\n'));
+        }
+    }
+    const written = [];
+    for (const p of placed) {
+        const abs = join(outputDir, p.relPath);
+        if (log)
+            log(`  WRITE  ${relative(process.cwd(), abs) || p.relPath}`);
+        if (!dryRun) {
+            fs.mkdirSync(dirname(abs), { recursive: true });
+            fs.writeFileSync(abs, p.content.endsWith('\n') ? p.content : `${p.content}\n`, 'utf8');
+        }
+        written.push(abs);
+    }
+    // Remove the original bundle unless asked to keep it, and never when a split
+    // document was written over the source's own path.
+    let removedSource = false;
+    if (!dryRun && !keepSource) {
+        const wroteOverSource = placed.some((p) => resolve(join(outputDir, p.relPath)) === resolve(bundleFile));
+        if (wroteOverSource) {
+            if (log)
+                log(`  (source ${basename(bundleFile)} was overwritten by a split document; not deleting)`);
+        }
+        else {
+            fs.rmSync(bundleFile);
+            removedSource = true;
+            if (log)
+                log(`  removed ${relative(process.cwd(), bundleFile) || bundleFile}`);
+        }
+    }
+    return { removedSource, written };
+}

package/dist/utils/knowledge-sync.d.ts

@@ -17,6 +17,7 @@ export interface KnowledgeObject {
     mode?: string;
     name: string;
     scope?: string;
+    tag?: string[];
 }
 /** A locally-collected object that also remembers its primary file on disk (for GUID writeback). */
 export interface LocalKnowledgeObject extends KnowledgeObject {

package/dist/utils/knowledge-sync.js

@@ -12,7 +12,7 @@ import { dirname, join, relative, sep } from 'node:path';
 // let the server dictate file paths.
 export const KNOWLEDGE_DIR = 'knowledge';
 // ── Frontmatter ──────────────────────────────────────────────────────────────
-const FRONTMATTER_ORDER = ['name', 'description', 'knowledge_type', 'scope', 'inclusion', 'enabled', 'guid'];
+const FRONTMATTER_ORDER = ['name', 'description', 'knowledge_type', 'inclusion', 'tags', 'guid'];
 /**
  * Build a primary `.md` file body: YAML frontmatter (built from the object's
  * structured fields) followed by the markdown content.
@@ -23,12 +23,10 @@ export function buildPrimaryContent(obj) {
     if (obj.description !== undefined)
         meta.description = obj.description;
     meta.knowledge_type = obj.knowledge_type;
-    if (obj.scope !== undefined)
-        meta.scope = obj.scope;
     if (obj.mode !== undefined)
         meta.inclusion = modeToInclusion(obj.mode);
-    if (obj.enabled !== undefined)
-        meta.enabled = obj.enabled;
+    if (obj.tag !== undefined && obj.tag.length > 0)
+        meta.tags = obj.tag;
     if (obj.guid !== undefined)
         meta.guid = obj.guid;
     // Emit keys in a stable, human-friendly order.
@@ -107,6 +105,10 @@ const MODE_TO_INCLUSION = {
 function modeToInclusion(mode) {
     return MODE_TO_INCLUSION[mode] ?? mode;
 }
+/** Parse the on-disk `tags:` frontmatter value into a string array, or `undefined` if absent/malformed. */
+function parseTags(tags) {
+    return Array.isArray(tags) && tags.every((t) => typeof t === 'string') ? tags : undefined;
+}
 // ── Path mapping (CLI-owned layout) ────────────────────────────────────────────
 /**
  * Allocate a unique snake_case folder/file segment per call, suffixing
@@ -246,6 +248,9 @@ export function collectKnowledgeObjects(inputDir, include, exclude) {
         };
         if (typeof meta.guid === 'string')
             obj.guid = meta.guid;
+        const tags = parseTags(meta.tags);
+        if (tags)
+            obj.tag = tags;
         if (knowledgeType === 'skill') {
             const skillFolder = posixPath.slice('skills/'.length, posixPath.indexOf('/SKILL.md'));
             const refPrefix = `skills/${skillFolder}/references/`;
@@ -345,6 +350,7 @@ function canonical(obj) {
         files,
         mode: obj.mode ?? '',
         scope: obj.scope ?? '',
+        tag: [...(obj.tag ?? [])].sort(),
     });
 }
 /**

package/dist/utils/microservice-wait.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Poll a tenant's microservice deployment status until every auto-deployed
+ * microservice settles (ok/error) or a timeout elapses. Backs `ephemeral push
+ * --wait`: after a multidoc push auto-deploys microservices (tenant_deploy=
+ * "auto"), the CLI waits here for them to become Ready and reports the outcome.
+ *
+ * The backend route (GET .../tenant/{name}/microservice, statement
+ * mvp:microservice_status_all) returns one entry per microservice with a live
+ * k8s readiness read. `manual`/`disabled` microservices are reported but not
+ * waited on (they were never deployed by the push).
+ */
+/** One microservice's status as returned by the tenant status route. */
+export interface MicroserviceStatusEntry {
+    desired?: number;
+    detail?: string;
+    microservice_id: number;
+    name: string;
+    ready?: number;
+    status: string;
+    tenant_deploy?: string;
+}
+export interface WaitOptions {
+    /** Bearer token for the authed status GET. */
+    accessToken: string;
+    /** Called once per poll with the latest entries, for progress rendering. */
+    onPoll?: (entries: MicroserviceStatusEntry[], elapsedMs: number) => void;
+    /** Poll cadence in ms (default 2000). */
+    pollIntervalMs?: number;
+    /** Absolute URL of the tenant microservice status route. */
+    statusUrl: string;
+    /** Overall wait budget in ms (default 300000 = 300s). */
+    timeoutMs?: number;
+    /** Authed fetch (command.verboseFetch bound), so TLS/dispatcher settings apply. */
+    verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
+    /** Verbose request logging passthrough. */
+    verbose?: boolean;
+}
+export interface WaitResult {
+    /** The final status entries observed. */
+    entries: MicroserviceStatusEntry[];
+    /** True if any awaited (auto) microservice ended in "error". */
+    hadError: boolean;
+    /** True if the wait budget elapsed before all awaited microservices settled. */
+    timedOut: boolean;
+}
+/** An awaited microservice is one that was auto-deployed and is not skipped/disabled. */
+export declare function isAwaited(entry: MicroserviceStatusEntry): boolean;
+/**
+ * Poll until all awaited microservices settle or the timeout elapses. Transient
+ * poll failures (network blips, a brief 5xx while a pod restarts) are tolerated —
+ * they don't abort the wait; only the overall timeout does.
+ */
+export declare function waitForMicroservices(opts: WaitOptions): Promise<WaitResult>;

package/dist/utils/microservice-wait.js

@@ -0,0 +1,83 @@
+/**
+ * Poll a tenant's microservice deployment status until every auto-deployed
+ * microservice settles (ok/error) or a timeout elapses. Backs `ephemeral push
+ * --wait`: after a multidoc push auto-deploys microservices (tenant_deploy=
+ * "auto"), the CLI waits here for them to become Ready and reports the outcome.
+ *
+ * The backend route (GET .../tenant/{name}/microservice, statement
+ * mvp:microservice_status_all) returns one entry per microservice with a live
+ * k8s readiness read. `manual`/`disabled` microservices are reported but not
+ * waited on (they were never deployed by the push).
+ */
+/** Statuses that mean an awaited microservice has settled (no longer in flight). */
+const SETTLED = new Set(['ok', 'error']);
+/** Statuses that mean we don't wait on this microservice at all. */
+const NOT_AWAITED = new Set(['skipped', 'disabled']);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** An awaited microservice is one that was auto-deployed and is not skipped/disabled. */
+export function isAwaited(entry) {
+    return !NOT_AWAITED.has(entry.status) && (entry.tenant_deploy ?? 'auto') !== 'manual';
+}
+/** True once every awaited microservice has settled (ok/error). */
+function allSettled(entries) {
+    const awaited = entries.filter((e) => isAwaited(e));
+    // No auto microservices at all → nothing to wait for.
+    if (awaited.length === 0)
+        return true;
+    return awaited.every((e) => SETTLED.has(e.status));
+}
+/**
+ * Fetch the status route once. Throws on a non-2xx so the caller can decide
+ * whether a transient failure is fatal (it isn't — we keep polling).
+ */
+async function fetchStatus(opts) {
+    const res = await opts.verboseFetch(opts.statusUrl, { headers: { Authorization: `Bearer ${opts.accessToken}` }, method: 'GET' }, opts.verbose ?? false, opts.accessToken);
+    if (!res.ok) {
+        throw new Error(`status ${res.status} ${res.statusText}`);
+    }
+    const body = (await res.json());
+    if (!Array.isArray(body)) {
+        throw new Error('unexpected status response shape');
+    }
+    return body;
+}
+/**
+ * Poll until all awaited microservices settle or the timeout elapses. Transient
+ * poll failures (network blips, a brief 5xx while a pod restarts) are tolerated —
+ * they don't abort the wait; only the overall timeout does.
+ */
+export async function waitForMicroservices(opts) {
+    const pollIntervalMs = opts.pollIntervalMs ?? 2000;
+    const timeoutMs = opts.timeoutMs ?? 300000;
+    const start = Date.now();
+    let entries = [];
+    let consecutiveErrors = 0;
+    // Poll loop. We always do at least one fetch so `--wait` reports even when the
+    // deployment already settled between the push returning and the first poll.
+    for (;;) {
+        const elapsed = Date.now() - start;
+        try {
+            entries = await fetchStatus(opts);
+            consecutiveErrors = 0;
+            opts.onPoll?.(entries, elapsed);
+            if (allSettled(entries)) {
+                return { entries, hadError: entries.some((e) => isAwaited(e) && e.status === 'error'), timedOut: false };
+            }
+        }
+        catch {
+            // A transient status read failure is non-fatal — keep polling until the
+            // overall timeout. (Mirrors the frontend poller's tolerate-with-cap.) We
+            // don't surface each blip; the timeout is the real failure signal.
+            consecutiveErrors++;
+        }
+        if (Date.now() - start + pollIntervalMs > timeoutMs) {
+            // Out of budget. Report whatever we last saw as timed out.
+            return {
+                entries,
+                hadError: entries.some((e) => isAwaited(e) && e.status === 'error'),
+                timedOut: true,
+            };
+        }
+        await sleep(pollIntervalMs);
+    }
+}

package/dist/utils/multidoc-push.d.ts

@@ -97,6 +97,18 @@ export declare function readDocuments(files: string[]): Array<{
     content: string;
     filePath: string;
 }>;
+/**
+ * Return the entries whose file holds more than one document (a `---`
+ * separator). Used to refuse multi-doc files before the push pipeline's
+ * single-doc-per-file assumptions can drop or corrupt them.
+ */
+export declare function findMultiDocEntries(entries: Array<{
+    content: string;
+    filePath: string;
+}>): Array<{
+    count: number;
+    filePath: string;
+}>;
 export declare function renderBadReferences(badRefs: BadReference[], log: (msg: string) => void): void;
 export declare function renderBadIndexes(badIndexes: BadIndex[], log: (msg: string) => void): void;
 export declare function confirm(message: string): Promise<boolean>;

package/dist/utils/multidoc-push.js

@@ -3,6 +3,7 @@ import { minimatch } from 'minimatch';
 import * as fs from 'node:fs';
 import { join, relative } from 'node:path';
 import { buildDocumentKey, findFilesWithGuid, parseDocument } from './document-parser.js';
+import { flattenBundleFile } from './flatten.js';
 import { collectKnowledgeObjects, fetchKnowledge, knowledgePreview, pushKnowledge, syncGuidToFrontmatter, toPushItems, } from './knowledge-sync.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
 /**
@@ -102,6 +103,31 @@ export function readDocuments(files) {
     }
     return entries;
 }
+/**
+ * A `.xs` document separator: a line that is exactly `---`. The whole push
+ * pipeline (partial-diff filtering, the document→file map, and GUID writeback)
+ * assumes ONE document per file — it only ever parses the first document in a
+ * file and rewrites the first `guid =` line. A multi-document file therefore
+ * silently drops on a partial push and corrupts GUIDs on a full one, so it is
+ * refused up front (with a pointer to `xano flatten`).
+ */
+const DOC_SEPARATOR = /^---$/m;
+/**
+ * Return the entries whose file holds more than one document (a `---`
+ * separator). Used to refuse multi-doc files before the push pipeline's
+ * single-doc-per-file assumptions can drop or corrupt them.
+ */
+export function findMultiDocEntries(entries) {
+    const offenders = [];
+    for (const entry of entries) {
+        if (DOC_SEPARATOR.test(entry.content)) {
+            // Count documents = separators + 1 (trailing/empty fragments don't change the "multi" verdict).
+            const count = entry.content.split('\n').filter((l) => l.trim() === '---').length + 1;
+            offenders.push({ count, filePath: entry.filePath });
+        }
+    }
+    return offenders;
+}
 // ── Validation Rendering ────────────────────────────────────────────────────
 export function renderBadReferences(badRefs, log) {
     log(ux.colorize('yellow', ux.colorize('bold', '=== Unresolved References ===')));
@@ -387,6 +413,64 @@ export async function executePush(ctx, target, flags) {
         if (documentEntries.length === 0) {
             command.error(`All .xs files in ${inputDir} are empty`);
         }
+        // ── Handle multi-document files ───────────────────────────────────────
+        // The push pipeline assumes one document per file: the partial-diff filter
+        // and GUID-writeback both parse only the first document in a file, so a
+        // bundle like a single hand-authored multidoc.xs silently pushes nothing
+        // (partial) or clobbers a single guid line across every document (full).
+        // Rather than fail, offer to flatten each bundle in place into the
+        // per-document layout `pull` produces, then re-read and continue the push.
+        const multiDocFiles = findMultiDocEntries(documentEntries);
+        if (multiDocFiles.length > 0) {
+            const list = multiDocFiles
+                .map((f) => `    ${relative(inputDir, f.filePath) || f.filePath} (${f.count} documents)`)
+                .join('\n');
+            log('');
+            log(ux.colorize('yellow', ux.colorize('bold', '=== Multi-document file(s) detected ===')));
+            log('');
+            log(ux.colorize('yellow', 'These .xs files hold more than one document:'));
+            log(list);
+            log('');
+            log(ux.colorize('dim', 'Push needs one document per file (partial diff + GUID writeback operate per file),\n' +
+                'so a multi-doc bundle silently pushes nothing or corrupts GUIDs. I can split each\n' +
+                'into the standard per-document layout (the same tree `pull` produces) and continue.'));
+            log('');
+            // Flattening DELETES the source bundle, so never do it unattended without an
+            // explicit opt-in. --force means "just do it"; an interactive TTY gets a
+            // prompt; a bare non-interactive run refuses (rather than silently rewriting
+            // and deleting the user's files in CI).
+            if (flags.force) {
+                log(ux.colorize('dim', 'Flattening (--force)…'));
+            }
+            else if (process.stdin.isTTY) {
+                const doFlatten = await confirm('Flatten these file(s) in place and continue the push?');
+                if (!doFlatten) {
+                    log('Push cancelled. Run `xano flatten <file>` yourself, or re-run to be prompted again.');
+                    return;
+                }
+            }
+            else {
+                command.error('Multi-document .xs file(s) cannot be pushed. Run `xano flatten <file>` to split them ' +
+                    'into the standard per-document layout first, or re-run with --force to flatten automatically.');
+            }
+            for (const offender of multiDocFiles) {
+                try {
+                    const result = flattenBundleFile(offender.filePath, { log: (m) => flags.verbose && log(ux.colorize('dim', m)) });
+                    log(ux.colorize('dim', `  flattened ${relative(inputDir, offender.filePath) || offender.filePath} → ${result.written.length} files`));
+                }
+                catch (error) {
+                    command.error(`Failed to flatten ${offender.filePath}: ${error.message}`);
+                }
+            }
+            log('');
+            // Re-collect and re-read: the bundle files are gone, replaced by the split
+            // per-document tree, so the rest of the push sees a clean one-doc-per-file set.
+            const refreshed = readDocuments(applyFilters(collectFiles(inputDir), inputDir, flags.include, flags.exclude, () => { }));
+            documentEntries = refreshed;
+            if (documentEntries.length === 0) {
+                command.error('After flattening, no .xs documents remain to push.');
+            }
+        }
         multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         // ── Build document key → file path map (for GUID writeback) ─────────
         for (const entry of documentEntries) {

package/dist/utils/paging.d.ts

@@ -0,0 +1,145 @@
+/**
+ * How much paging information the backing Metadata API endpoint gives us.
+ *
+ * The Metadata API pages unevenly, and what the CLI can honestly tell the user
+ * depends entirely on what the response carries:
+ *
+ * - `envelope`            accepts page + per_page and returns
+ *                         {curPage, nextPage, prevPage, items[]}. `nextPage` is
+ *                         server-computed and null on the last page, so it is the
+ *                         one place a "there is more" hint is guaranteed correct.
+ * - `page-only-envelope`  accepts page only (per_page is hardcoded server-side)
+ *                         and returns an object carrying `itemsTotal`. A true
+ *                         total, so we can say where the user sits — but we offer
+ *                         no next-page affordance.
+ * - `none`                no server-side paging at all. The full set comes back,
+ *                         so the item count IS the total.
+ *
+ * There is deliberately no tier for endpoints that page but return a bare array
+ * with no metadata (tenants, releases, platforms, clusters, ephemerals, tenant
+ * backups). Those commands are left alone: the only has-more signal available
+ * would be "the page came back full", which is a guaranteed false positive when
+ * the result set is an exact multiple of the page size — sending the user to an
+ * empty page. Better to offer nothing than to offer a lie.
+ */
+export type PagingTier = 'envelope' | 'none' | 'page-only-envelope';
+export interface PagingFlagValues {
+    page?: number;
+    per_page?: number;
+}
+export interface NormalizedList<T> {
+    curPage?: number;
+    items: T[];
+    itemsTotal?: number;
+    nextPage?: number;
+    prevPage?: number;
+}
+export interface PagingFlagOptions {
+    /** Page size the endpoint hardcodes server-side; surfaced in the page flag description. */
+    fixedPerPage?: number;
+    /** Maximum per_page the endpoint accepts; surfaced in the per_page flag description. */
+    maxPerPage?: number;
+}
+declare function makePageFlag(description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+declare function makePerPageFlag(defaultValue: number, description: string): import("@oclif/core/interfaces").OptionFlag<number, import("@oclif/core/interfaces").CustomOptions>;
+type PageFlag = ReturnType<typeof makePageFlag>;
+type PerPageFlag = ReturnType<typeof makePerPageFlag>;
+/**
+ * Build the oclif flag definitions appropriate to an endpoint's paging tier.
+ * Spread the result into a command's `static flags`.
+ *
+ * A flag the server ignores is worse than no flag, so `per_page` is only
+ * produced for tiers whose endpoint actually accepts it. The overloads keep
+ * oclif's flag-type inference intact so `flags.page` stays typed at call sites.
+ */
+export declare function pagingFlags(tier: 'envelope', options?: PagingFlagOptions): {
+    page: PageFlag;
+    per_page: PerPageFlag;
+};
+export declare function pagingFlags(tier: 'page-only-envelope', options?: PagingFlagOptions): {
+    page: PageFlag;
+};
+export declare function pagingFlags(tier: 'none', options?: PagingFlagOptions): Record<string, never>;
+export declare function pagingFlags(tier: PagingTier, options?: PagingFlagOptions): Record<string, unknown>;
+/**
+ * Translate parsed paging flags into query-string entries, emitting only the
+ * params the endpoint actually declares.
+ */
+export declare function buildPagingParams(flags: PagingFlagValues | Record<string, unknown>, tier: PagingTier): Array<[string, string]>;
+/**
+ * Absorb the response shapes the Metadata API returns for list endpoints:
+ * a bare array, a paging envelope keyed on `items`, or an object keyed on the
+ * resource name (e.g. `{workspaces: [...]}`).
+ *
+ * `resourceKeys` names any resource-keyed fallbacks to check, in order.
+ */
+export declare function normalizeListResponse<T>(data: unknown, resourceKeys?: string[]): NormalizedList<T>;
+/** Page size used when the CLI pages an endpoint on the user's behalf. */
+export declare const INTERNAL_PAGE_SIZE = 100;
+/**
+ * Walk an envelope-tier endpoint page by page and collect every item.
+ *
+ * Termination is the server's own `nextPage`, never "the page came back full" —
+ * the same rule the footer follows. An empty page also stops the walk, which
+ * covers an endpoint that omits `nextPage` entirely rather than looping forever.
+ *
+ * `maxPages` is a runaway backstop, not a limit users are expected to hit; when
+ * it trips, `onTruncate` fires so the caller can say so out loud instead of
+ * silently processing a subset.
+ */
+export declare function collectAllPages<T>(fetchPage: (page: number) => Promise<NormalizedList<T>>, options?: {
+    maxPages?: number;
+    onTruncate?: (collected: number) => void;
+}): Promise<T[]>;
+export interface PagingJson<T> {
+    curPage?: number;
+    items: T[];
+    itemsTotal?: number;
+    nextPage?: number;
+    perPage?: number;
+    prevPage?: number;
+}
+/**
+ * Build the `--output json` payload for a list command.
+ *
+ * Field names mirror the Metadata API envelope exactly — `curPage`, `nextPage`,
+ * `prevPage`, `itemsTotal`, `items` — so a script can move between the CLI and
+ * the raw API without a translation layer. `perPage` is the one field the CLI
+ * injects: the API never echoes it back, and it is otherwise invisible when the
+ * user leaves the flag at its default.
+ *
+ * Emits only fields the response actually proves, mirroring the footer's
+ * honesty rule: `itemsTotal` appears only when the server sent it, `nextPage`
+ * only when the server computed it.
+ *
+ * Without this envelope, a script driving `--output json` sees a bare array and
+ * its only available stop condition is `length < perPage` — precisely the
+ * page-fullness inference this module refuses to make in the footer.
+ */
+export declare function buildPagingJson<T>(list: NormalizedList<T>, options: {
+    page?: number;
+    perPage?: number;
+    tier: PagingTier;
+}): PagingJson<T>;
+export interface PagingFooterOptions {
+    /** Singular noun for the listed resource, used by the `none` tier. */
+    noun: string;
+    /** Plural form; defaults to `noun + 's'`. */
+    nounPlural?: string;
+    /** Page the user requested, used when the response omits `curPage`. */
+    page?: number;
+    /** Page size the user requested. Recorded for context; never used to infer a next page. */
+    perPage?: number;
+    tier: PagingTier;
+}
+/**
+ * Render the paging footer for a list command, reporting only facts the response
+ * actually proves. Returns null when there is nothing worth saying — an empty
+ * result set already prints its own "No X found" line.
+ *
+ * Deliberately asymmetric across tiers: `envelope` shows a next-page hint but no
+ * total, `page-only-envelope` shows a total but no next-page hint, and `none`
+ * shows a bare count. See PagingTier for why.
+ */
+export declare function formatPagingFooter<T>(list: NormalizedList<T>, options: PagingFooterOptions): null | string;
+export {};