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

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

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;