@xano/cli 1.0.6-beta.2 → 1.0.6-beta.20

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';
 /**
@@ -65,30 +66,151 @@ export function collectFiles(dir) {
  * Apply include/exclude glob filters to a file list. Logs filter results.
  * Returns the filtered file list.
  */
+/**
+ * Normalize a filter pattern into one minimatch can actually match against a
+ * repo-relative FILE path.
+ *
+ * minimatch has no notion of "this pattern names a directory", and the two
+ * spellings a person reaches for first both silently match NOTHING:
+ *
+ *   "table/"  a trailing slash is not directory syntax; it matches nothing
+ *   "table"   no slash, so `matchBase` compares it to the file's BASENAME,
+ *             i.e. it asks "is this file called `table`", not "is it under
+ *             `table/`"
+ *
+ * Silently matching nothing is the dangerous half of this: combined with
+ * `--delete`, a filter that fails open pushes more than intended, and a filter
+ * that succeeds deletes what it was meant to protect. So a pattern that names a
+ * real directory is expanded to `<dir>/**` rather than left to match nothing.
+ */
+export function normalizeFilterPattern(pattern, inputDir) {
+    const trimmed = pattern.replace(/[/\\]+$/, '');
+    if (trimmed === '')
+        return pattern;
+    // Anything with a glob character is taken exactly as written.
+    if (trimmed.includes('*') || trimmed.includes('?') || trimmed.includes('[')) {
+        return trimmed === pattern ? pattern : trimmed;
+    }
+    // A trailing slash is an unambiguous "this is a directory".
+    if (trimmed !== pattern)
+        return `${trimmed}/**`;
+    try {
+        if (fs.statSync(join(inputDir, trimmed)).isDirectory())
+            return `${trimmed}/**`;
+    }
+    catch {
+        // Not a path in this tree - leave it alone (it may be a bare filename,
+        // which matchBase handles).
+    }
+    return pattern;
+}
 export function applyFilters(files, inputDir, include, exclude, log) {
     let filtered = files;
     const totalCount = files.length;
+    // Report each pattern's own match count. The aggregate line alone hides a dead
+    // pattern among live ones: a run with three -e patterns where one is a typo
+    // still prints a plausible number and says nothing about which one matched
+    // nothing.
+    const describe = (patterns, rels) => patterns
+        .map((raw) => {
+        const pattern = normalizeFilterPattern(raw, inputDir);
+        const hits = rels.filter((rel) => minimatch(rel, pattern, { matchBase: true })).length;
+        const shown = pattern === raw ? raw : `${raw} -> ${pattern}`;
+        return hits === 0
+            ? `${ux.colorize('yellow', shown)} ${ux.colorize('yellow', '(matched 0 files)')}`
+            : `${ux.colorize('cyan', shown)} ${ux.colorize('dim', `(${hits})`)}`;
+    })
+        .join(', ');
     if (include && include.length > 0) {
+        const rels = filtered.map((f) => relative(inputDir, f));
+        const patterns = include.map((p) => normalizeFilterPattern(p, inputDir));
+        log('');
+        log(`  ${ux.colorize('dim', 'Include:')} ${describe(include, rels)}`);
         filtered = filtered.filter((f) => {
             const rel = relative(inputDir, f);
-            return include.some((pattern) => minimatch(rel, pattern, { matchBase: true }));
+            return patterns.some((pattern) => minimatch(rel, pattern, { matchBase: true }));
         });
-        log('');
-        log(`  ${ux.colorize('dim', 'Include:')} ${include.map((p) => ux.colorize('cyan', p)).join(', ')}`);
         log(`  ${ux.colorize('dim', 'Matched:')} ${ux.colorize('bold', String(filtered.length))} of ${totalCount} files`);
     }
     if (exclude && exclude.length > 0) {
         const beforeCount = filtered.length;
+        const rels = filtered.map((f) => relative(inputDir, f));
+        const patterns = exclude.map((p) => normalizeFilterPattern(p, inputDir));
+        log('');
+        log(`  ${ux.colorize('dim', 'Exclude:')} ${describe(exclude, rels)}`);
         filtered = filtered.filter((f) => {
             const rel = relative(inputDir, f);
-            return !exclude.some((pattern) => minimatch(rel, pattern, { matchBase: true }));
+            return !patterns.some((pattern) => minimatch(rel, pattern, { matchBase: true }));
         });
-        log('');
-        log(`  ${ux.colorize('dim', 'Exclude:')} ${exclude.map((p) => ux.colorize('cyan', p)).join(', ')}`);
         log(`  ${ux.colorize('dim', 'Kept:')}    ${ux.colorize('bold', String(filtered.length))} of ${beforeCount} files (excluded ${beforeCount - filtered.length})`);
     }
     return filtered;
 }
+/**
+ * Describe the documents a --include/--exclude filter removed.
+ *
+ * These are the objects the user asked NOT to touch, and they are exactly the
+ * ones a `--delete` sweep would remove: a filtered-out document never reaches
+ * the payload, so the server reads it as deleted from the tree. Their GUIDs are
+ * sent as `protect_guids` so the server spares them, and their keys are used to
+ * VERIFY the server actually did.
+ */
+export function describeFilteredOut(allFiles, keptFiles, inputDir) {
+    const kept = new Set(keptFiles);
+    const out = [];
+    for (const filePath of allFiles) {
+        if (kept.has(filePath))
+            continue;
+        let content;
+        try {
+            content = fs.readFileSync(filePath, 'utf8').trim();
+        }
+        catch {
+            continue;
+        }
+        if (!content)
+            continue;
+        const parsed = parseDocument(content);
+        if (!parsed)
+            continue;
+        const opName = parsed.verb ? `${parsed.name} ${parsed.verb}` : parsed.name;
+        out.push({
+            guid: parsed.guid,
+            // The preview buckets every trigger subtype under the generic `trigger`
+            // type, so key triggers that way to match (DEV-7084, same as
+            // filterChangedEntries).
+            key: `${parsed.type.endsWith('_trigger') ? 'trigger' : parsed.type}:${opName}`,
+            name: opName,
+            relPath: relative(inputDir, filePath),
+            type: parsed.type,
+        });
+    }
+    return out;
+}
+/**
+ * Delete operations that would remove something the filter excluded.
+ *
+ * This is the guard's actual test, and it is deliberately performed against the
+ * dry-run the SERVER returned rather than trusting that `protect_guids` was
+ * honoured: an older instance ignores the parameter entirely, and a document
+ * with no GUID cannot be protected at all. Either way the answer here is the
+ * truth about what the push is about to do.
+ */
+export function deletesHittingFilteredOut(operations, filteredOut) {
+    if (filteredOut.length === 0)
+        return [];
+    const byKey = new Map(filteredOut.map((d) => [d.key, d]));
+    const hits = [];
+    for (const op of operations) {
+        if (op.action !== 'delete' && op.action !== 'cascade_delete')
+            continue;
+        const match = byKey.get(`${op.type}:${op.name}`);
+        if (match) {
+            hits.push({ name: op.name, relPath: match.relPath, type: op.type });
+        }
+    }
+    return hits;
+}
 /**
  * Read .xs files into document entries, skipping empty files.
  */
@@ -102,6 +224,58 @@ 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;
+}
+/**
+ * Return every `workspace` document in the push set, with the name it declares.
+ *
+ * A tree must carry at most ONE. The server applies the first workspace
+ * document it encounters to the workspace being pushed into and silently
+ * discards the rest, with no check that the document actually describes that
+ * workspace — so a second one renames the destination to a foreign name while
+ * leaving its content untouched, and which name wins flips with the contents of
+ * the pushed set.
+ *
+ * Trees accumulate a second one easily, because `pull` names the file after the
+ * workspace's own name (`workspace/{name}.xs`): pulling a different workspace
+ * into the same directory ADDS a file rather than overwriting, and renaming a
+ * workspace leaves the old-name file behind.
+ */
+export function findWorkspaceEntries(entries) {
+    const found = [];
+    for (const entry of entries) {
+        const parsed = parseDocument(entry.content);
+        // Exact match: `workspace_trigger` is a different document type that also
+        // lives under workspace/ and must not be counted here.
+        if (parsed && parsed.type === 'workspace') {
+            found.push({ filePath: entry.filePath, name: parsed.name });
+        }
+    }
+    return found;
+}
 // ── Validation Rendering ────────────────────────────────────────────────────
 export function renderBadReferences(badRefs, log) {
     log(ux.colorize('yellow', ux.colorize('bold', '=== Unresolved References ===')));
@@ -148,7 +322,7 @@ const TYPE_LABELS = {
     workflow_test: 'Workflow Tests',
     workspace: 'Workspace Settings',
 };
-function renderPreview(result, willDelete, target, verbose, partial, log) {
+function renderPreview(result, willDelete, target, verbose, partial, log, filteredOutCount = 0) {
     log('');
     log(ux.colorize('bold', `=== Push Preview: ${target.label} ===`));
     let instanceHost = target.instanceOrigin;
@@ -212,6 +386,17 @@ function renderPreview(result, willDelete, target, verbose, partial, log) {
     // Split destructive ops by category
     const deleteOps = destructive.filter((op) => op.action === 'delete' || op.action === 'cascade_delete');
     const alwaysDestructive = destructive.filter((op) => op.action === 'truncate' || op.action === 'drop_field' || op.action === 'alter_field');
+    // --include/--exclude and --delete interact in a way the preview cannot show
+    // on its own: a filtered-out document is absent from the payload, so without
+    // the protection the push declares, the sweep would read it as removed. The
+    // objects it defines are spared (and the push is refused outright if they
+    // cannot be), but anything ELSE missing from the tree is still deleted below,
+    // which is worth saying while a filter is active.
+    if (willDelete && filteredOutCount > 0 && deleteOps.length > 0) {
+        log('');
+        log(ux.colorize('yellow', `  Note: ${filteredOutCount} file(s) were filtered out by --include/--exclude, and --delete is on.`));
+        log(ux.colorize('yellow', '  What they define is protected from the sweep; the deletes below are objects missing from the tree entirely.'));
+    }
     // Show destructive operations (deletes only when --delete, truncates/drop_field always)
     const shownDestructive = [...(willDelete ? deleteOps : []), ...alwaysDestructive];
     if (shownDestructive.length > 0) {
@@ -274,6 +459,12 @@ export async function confirm(message) {
     });
 }
 // ── GUID Sync ───────────────────────────────────────────────────────────────
+/**
+ * Ceiling for the `protect_guids` query parameter. The whole request LINE must
+ * fit in one nginx buffer (8k by default), and the URL already carries the rest
+ * of the push parameters, so stay well inside it.
+ */
+const PROTECT_GUIDS_MAX_CHARS = 4000;
 const GUID_REGEX = /guid\s*=\s*(["'])([^"']*)\1/;
 /**
  * Sync a GUID into a local .xs file. Returns true if the file was modified.
@@ -315,6 +506,32 @@ function syncGuidToFile(filePath, guid) {
     fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
     return true;
 }
+const CANONICAL_REGEX = /canonical\s*=\s*(["'])([^"']*)\1/;
+/**
+ * Sync a server-assigned `canonical` into a local .xs file. Returns true if the
+ * file was modified.
+ *
+ * Like the GUID, a canonical is minted by the instance and the document can only
+ * ASK for one: it is unique across every workspace on the instance, so a tree
+ * cloned from another workspace names canonicals that are already taken and the
+ * import keeps the existing value instead. Without this writeback the local file
+ * kept asking for a value the server kept refusing, so every push reported the
+ * same objects as changed forever.
+ *
+ * Unlike the GUID this NEVER inserts a missing line: only the container kinds
+ * (api_group, realtime_server, mcp_server/agent/toolset) have the field, and the
+ * server omits the key for everything else, so an absent line means "this kind
+ * has no canonical" rather than "not yet assigned".
+ */
+function syncCanonicalToFile(filePath, canonical) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const existingMatch = content.match(CANONICAL_REGEX);
+    if (!existingMatch || existingMatch[2] === canonical) {
+        return false;
+    }
+    fs.writeFileSync(filePath, content.replace(CANONICAL_REGEX, `canonical = "${canonical}"`), 'utf8');
+    return true;
+}
 // ── Knowledge Preview Helpers ─────────────────────────────────────────────────
 /**
  * Compute a knowledge change preview: prefer the server's `dry_run` response,
@@ -372,6 +589,8 @@ export async function executePush(ctx, target, flags) {
     // ── Collect and filter .xs files ──────────────────────────────────────
     const allFiles = collectFiles(inputDir);
     const files = applyFilters(allFiles, inputDir, flags.include, flags.exclude, log);
+    const filteredOut = describeFilteredOut(allFiles, files, inputDir);
+    const filteredOutCount = allFiles.length - files.length;
     const knowledgeOnly = files.length === 0 && (knowledgeObjects.length > 0 || ctx.knowledge !== undefined);
     if (files.length === 0 && !knowledgeOnly) {
         command.error(flags.include || flags.exclude
@@ -387,6 +606,91 @@ 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.');
+            }
+        }
+        // ── Refuse a tree carrying more than one workspace document ───────────
+        // The server applies the FIRST workspace document it sees to the workspace
+        // being pushed into and silently drops the rest, with no check that the
+        // document describes that workspace. A second one therefore renames the
+        // destination to a foreign name while leaving all of its content intact,
+        // and which name wins flips with whatever happens to be in the pushed set.
+        //
+        // Checked against the WHOLE tree rather than the partial changed-set, because
+        // the flip-flop case is exactly the one where only the foreign document is
+        // "changed" and would be the sole workspace document actually sent.
+        //
+        // No --force escape and no auto-fix: unlike the multi-doc bundle above there
+        // is no safe repair, since only the user knows which workspace this tree is
+        // meant to be. Picking one is the bug.
+        const workspaceDocs = findWorkspaceEntries(documentEntries);
+        if (workspaceDocs.length > 1) {
+            const list = workspaceDocs
+                .map((w) => `    ${relative(inputDir, w.filePath) || w.filePath}  →  workspace "${w.name}"`)
+                .join('\n');
+            command.error(`${inputDir} holds ${workspaceDocs.length} workspace documents:\n${list}\n\n` +
+                'A push targets one workspace, and the server applies only the first of these and ' +
+                'silently discards the rest — renaming the destination to a foreign name while leaving ' +
+                'its content untouched.\n\n' +
+                'Delete the ones that do not describe the workspace you are pushing to, keeping a single ' +
+                'workspace/*.xs. (`pull` names this file after the workspace, so pulling a different ' +
+                'workspace into this tree, or renaming one, leaves the old file behind.)');
+        }
         multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         // ── Build document key → file path map (for GUID writeback) ─────────
         for (const entry of documentEntries) {
@@ -420,6 +724,17 @@ export async function executePush(ctx, target, flags) {
     if (target.sourceWorkspaceId) {
         queryParams.set('source_workspace_id', target.sourceWorkspaceId);
     }
+    // Tell the server which objects the filter put out of scope, so its delete
+    // sweep spares them. Only meaningful with --delete; without it nothing is
+    // swept. The parameter travels in the query string (the body is the multidoc
+    // itself), so it has a length ceiling: past PROTECT_GUIDS_MAX_CHARS we send
+    // nothing and let the verification below refuse the push rather than issue a
+    // request the server may truncate or reject.
+    const protectableGuids = filteredOut.map((d) => d.guid).filter((g) => typeof g === 'string' && g.length > 0);
+    const protectGuidsParam = protectableGuids.join(',');
+    if (shouldDelete && protectGuidsParam && protectGuidsParam.length <= PROTECT_GUIDS_MAX_CHARS) {
+        queryParams.set('protect_guids', protectGuidsParam);
+    }
     // ── Request headers ───────────────────────────────────────────────────
     const requestHeaders = {
         accept: 'application/json',
@@ -451,7 +766,46 @@ export async function executePush(ctx, target, flags) {
                         const knowledgeDryRun = await computeKnowledgePreview(ctx.knowledge.listUrl(), knowledgeObjects, ctx.branch, shouldDelete, accessToken, verboseFetch, flags.verbose);
                         mergeKnowledgePreview(preview, knowledgeDryRun);
                     }
-                    renderPreview(preview, shouldDelete, target, flags.verbose, isPartial, log);
+                    renderPreview(preview, shouldDelete, target, flags.verbose, isPartial, log, filteredOutCount);
+                    // GUARD: --include/--exclude must never cost you the objects it
+                    // filtered out.
+                    //
+                    // A filtered-out document is absent from the payload, so a --delete
+                    // sweep reads it as removed from the tree and deletes it - the exact
+                    // opposite of what -e means to the person typing it. The server is
+                    // told to spare them (protect_guids above), but this checks the
+                    // SERVER'S OWN preview rather than assuming that worked: an older
+                    // instance ignores the parameter, a document that has never been
+                    // pushed has no GUID to protect, and a very large filter exceeds what
+                    // the query string can carry. In every one of those cases the push is
+                    // refused rather than allowed to delete.
+                    if (shouldDelete) {
+                        const endangered = deletesHittingFilteredOut(preview.operations, filteredOut);
+                        if (endangered.length > 0) {
+                            log('');
+                            log(ux.colorize('red', '--- Refusing to push ---'));
+                            log('');
+                            log(`  --delete would remove ${endangered.length} object(s) that --include/--exclude filtered out:`);
+                            log('');
+                            for (const hit of endangered.slice(0, 10)) {
+                                log(`  ${ux.colorize('red', 'DELETE'.padEnd(8))} ${hit.type.padEnd(18)} ${hit.name}  ${ux.colorize('dim', `(${hit.relPath})`)}`);
+                            }
+                            if (endangered.length > 10) {
+                                log(ux.colorize('dim', `  ... and ${endangered.length - 10} more`));
+                            }
+                            log('');
+                            const unprotectable = filteredOut.filter((d) => !d.guid).length;
+                            if (unprotectable > 0) {
+                                log(ux.colorize('dim', `  ${unprotectable} filtered-out document(s) have no guid yet, so the server cannot be told to spare them.`));
+                            }
+                            if (protectGuidsParam.length > PROTECT_GUIDS_MAX_CHARS) {
+                                log(ux.colorize('dim', '  Too many filtered-out documents to declare in one request.'));
+                            }
+                            log(ux.colorize('dim', '  This instance may also predate protected pushes.'));
+                            log('');
+                            command.error('Re-run without --delete, or without the --include/--exclude filter.');
+                        }
+                    }
                     // Check for bad cross-references using dry-run operations to avoid false positives
                     const badRefs = checkReferences(documentEntries, preview.operations);
                     if (badRefs.length > 0) {
@@ -689,6 +1043,7 @@ export async function executePush(ctx, target, flags) {
                     }
                 }
                 let updatedCount = 0;
+                let canonicalCount = 0;
                 for (const entry of guidMap) {
                     if (!entry.guid)
                         continue;
@@ -715,10 +1070,23 @@ export async function executePush(ctx, target, flags) {
                     catch (error) {
                         command.warn(`Failed to sync GUID to ${filePath}: ${error.message}`);
                     }
+                    if (entry.canonical) {
+                        try {
+                            const updated = syncCanonicalToFile(filePath, entry.canonical);
+                            if (updated)
+                                canonicalCount++;
+                        }
+                        catch (error) {
+                            command.warn(`Failed to sync canonical to ${filePath}: ${error.message}`);
+                        }
+                    }
                 }
                 if (updatedCount > 0) {
                     log(`Synced ${updatedCount} GUIDs to local files`);
                 }
+                if (canonicalCount > 0) {
+                    log(`Synced ${canonicalCount} canonicals to local files (the instance assigned its own)`);
+                }
             }
             pushedDocCount = multidoc.split('\n---\n').length;
         }
@@ -820,6 +1188,7 @@ export function describeNetworkError(error, url, elapsedMs) {
         ETIMEDOUT: `Connection to ${host} timed out. Check your network or VPN, then retry.`,
         UND_ERR_CONNECT_TIMEOUT: `Connection to ${host} timed out. Check your network or VPN, then retry.`,
         UND_ERR_HEADERS_TIMEOUT: `${host} accepted the connection but did not respond in time. The push may be too large; try splitting it or retrying.`,
+        UND_ERR_INVALID_ARG: `Your Node runtime rejected the CLI's HTTP dispatcher. Update the CLI, or run it under Node 24 (see DEV-7773).`,
     };
     let base;
     if (code && hints[code]) {

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 {};