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

package/dist/utils/paging.js

@@ -0,0 +1,199 @@
+/* eslint-disable camelcase */
+import { Flags } from '@oclif/core';
+function makePageFlag(description) {
+    return Flags.integer({ default: 1, description, required: false });
+}
+function makePerPageFlag(defaultValue, description) {
+    return Flags.integer({ default: defaultValue, description, required: false });
+}
+export function pagingFlags(tier, options = {}) {
+    if (tier === 'none') {
+        return {};
+    }
+    if (tier === 'page-only-envelope') {
+        const fixed = options.fixedPerPage;
+        return {
+            page: makePageFlag(fixed
+                ? `Page number for pagination (page size is fixed at ${fixed} by the API)`
+                : 'Page number for pagination'),
+        };
+    }
+    return {
+        page: makePageFlag('Page number for pagination'),
+        per_page: makePerPageFlag(50, options.maxPerPage
+            ? `Number of results per page (max ${options.maxPerPage})`
+            : 'Number of results per page'),
+    };
+}
+/**
+ * Translate parsed paging flags into query-string entries, emitting only the
+ * params the endpoint actually declares.
+ */
+export function buildPagingParams(flags, tier) {
+    if (tier === 'none') {
+        return [];
+    }
+    const { page, per_page: perPage } = flags;
+    const params = [];
+    if (page !== undefined) {
+        params.push(['page', String(page)]);
+    }
+    if (tier === 'envelope' && perPage !== undefined) {
+        params.push(['per_page', String(perPage)]);
+    }
+    return params;
+}
+/** Coerce a possibly-null numeric paging field to a number or undefined. */
+function optionalNumber(value) {
+    return typeof value === 'number' ? value : undefined;
+}
+/**
+ * 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 function normalizeListResponse(data, resourceKeys = []) {
+    if (Array.isArray(data)) {
+        return { items: data };
+    }
+    if (data && typeof data === 'object') {
+        const record = data;
+        if (Array.isArray(record.items)) {
+            return {
+                curPage: optionalNumber(record.curPage),
+                items: record.items,
+                itemsTotal: optionalNumber(record.itemsTotal),
+                nextPage: optionalNumber(record.nextPage),
+                prevPage: optionalNumber(record.prevPage),
+            };
+        }
+        for (const key of resourceKeys) {
+            if (Array.isArray(record[key])) {
+                return {
+                    curPage: optionalNumber(record.curPage),
+                    items: record[key],
+                    itemsTotal: optionalNumber(record.itemsTotal),
+                    nextPage: optionalNumber(record.nextPage),
+                    prevPage: optionalNumber(record.prevPage),
+                };
+            }
+        }
+    }
+    const accepted = ['an array', 'an object with an items array', ...resourceKeys.map((k) => `an object with a ${k} array`)];
+    throw new Error(`Unexpected API response format. Expected ${accepted.join(', ')}.`);
+}
+/** Page size used when the CLI pages an endpoint on the user's behalf. */
+export 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 async function collectAllPages(fetchPage, options = {}) {
+    const maxPages = options.maxPages ?? 100;
+    const items = [];
+    for (let page = 1; page <= maxPages; page++) {
+        // eslint-disable-next-line no-await-in-loop
+        const list = await fetchPage(page);
+        items.push(...list.items);
+        if (list.items.length === 0 || list.nextPage === undefined) {
+            return items;
+        }
+    }
+    options.onTruncate?.(items.length);
+    return items;
+}
+/**
+ * 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 function buildPagingJson(list, options) {
+    const payload = { items: list.items };
+    if (options.tier === 'none') {
+        return payload;
+    }
+    const hasPositionEvidence = list.curPage !== undefined ||
+        list.nextPage !== undefined ||
+        list.prevPage !== undefined ||
+        list.itemsTotal !== undefined;
+    // Same rule as the footer: with no metadata we cannot assert a position.
+    if (!hasPositionEvidence) {
+        return payload;
+    }
+    const curPage = list.curPage ?? options.page;
+    if (curPage !== undefined)
+        payload.curPage = curPage;
+    if (options.tier === 'envelope' && options.perPage !== undefined)
+        payload.perPage = options.perPage;
+    if (list.nextPage !== undefined)
+        payload.nextPage = list.nextPage;
+    if (list.prevPage !== undefined)
+        payload.prevPage = list.prevPage;
+    if (list.itemsTotal !== undefined)
+        payload.itemsTotal = list.itemsTotal;
+    return payload;
+}
+const SEPARATOR = ' · ';
+/**
+ * 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 function formatPagingFooter(list, options) {
+    const count = list.items.length;
+    const plural = options.nounPlural ?? `${options.noun}s`;
+    const countPhrase = `${count} ${count === 1 ? options.noun : plural}`;
+    // A paged tier whose response carried no metadata at all tells us nothing
+    // about position — the endpoint may have ignored `page` entirely. Reporting
+    // the requested page here would state the user's wish as a server fact, so
+    // fall back to the bare count.
+    const hasPositionEvidence = list.curPage !== undefined ||
+        list.nextPage !== undefined ||
+        list.prevPage !== undefined ||
+        list.itemsTotal !== undefined;
+    if (options.tier === 'none' || !hasPositionEvidence) {
+        return count === 0 ? null : countPhrase;
+    }
+    // An empty page past the end is worth reporting when we know the true total —
+    // otherwise `--page 99` on a populated workspace is indistinguishable from an
+    // empty one.
+    if (count === 0 && list.itemsTotal === undefined) {
+        return null;
+    }
+    const page = list.curPage ?? options.page ?? 1;
+    const parts = [`Page ${page}`, `${count} shown`];
+    if (options.tier === 'envelope' && list.nextPage !== undefined) {
+        // Server-computed. Null/absent on the last page, so following it can never
+        // land on an empty result. Page fullness is never consulted here.
+        parts.push(`next: --page ${list.nextPage}`);
+    }
+    if (options.tier === 'page-only-envelope' && list.itemsTotal !== undefined) {
+        parts.push(`${list.itemsTotal} total`);
+    }
+    return parts.join(SEPARATOR);
+}

package/dist/utils/reference-checker.js

@@ -28,6 +28,16 @@ const REFERENCE_PATTERNS = [
     },
     // Schema foreign key references: table = "name" inside field definitions
     { keyword: 'table (FK)', regex: /\btable\s*=\s*"([^"]*)"/gm, targetType: 'table' },
+    // Realtime v2: a channel references its owning realtime_server by name via a
+    // top-level `realtime_server = "..."` (renamed from a bare `server` to match
+    // the api_group/mcp_server convention). The full keyword is unambiguous, so no
+    // false-match against another object type's `server` field.
+    {
+        keyword: 'channel (realtime_server)',
+        regex: /^\s*realtime_server\s*=\s*"([^"]*)"/gm,
+        sourceType: 'channel',
+        targetType: 'realtime_server',
+    },
 ];
 /**
  * Strip surrounding quotes from a name if present.
@@ -119,6 +129,9 @@ export function checkReferences(documents, serverOperations) {
         if (!parsed)
             continue;
         for (const pattern of REFERENCE_PATTERNS) {
+            // Skip patterns scoped to a different source document type.
+            if (pattern.sourceType && pattern.sourceType !== parsed.type)
+                continue;
             // Reset regex state for each document
             pattern.regex.lastIndex = 0;
             let match;