@xano/cli 1.2.0 → 1.3.1-beta.0

package/dist/utils/multidoc-push.js

@@ -1,10 +1,24 @@
-import { ux } from '@oclif/core';
+import { Errors, ux } from '@oclif/core';
 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 { policyWeakeningGuidance, WEAKENING_REFUSAL } from './policy/permission.js';
+import { PushPolicyGateError } from './policy/push-gate.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
+/**
+ * A push that failed after its multidoc import landed. The import is not rolled back, so the error
+ * carries what it did for the calling command to report beside the failure.
+ */
+export class FailedAfterImportError extends Errors.CLIError {
+    imported;
+    constructor(message, imported) {
+        super(message);
+        this.imported = imported;
+    }
+}
 /**
  * Filter document entries down to the ones the dry-run preview reports as changed,
  * used to send only the changed documents during a partial (non-`--sync`) push.
@@ -65,30 +79,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 +237,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 +335,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 +399,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 +472,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 +519,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,
@@ -327,7 +557,6 @@ async function computeKnowledgePreview(listUrl, objects, branch, shouldDelete, a
         const serverResult = await pushKnowledge(listUrl, accessToken, verboseFetch, verbose, {
             branch,
             delete: shouldDelete,
-            // eslint-disable-next-line camelcase -- external Metadata API field name
             dry_run: true,
             items,
         });
@@ -363,7 +592,9 @@ function mergeKnowledgePreview(preview, knowledge) {
  */
 export async function executePush(ctx, target, flags) {
     const { accessToken, command, inputDir, verboseFetch } = ctx;
-    const log = command.log.bind(command);
+    const log = ctx.log ?? command.log.bind(command);
+    let dryRunPreview = null;
+    const stop = (stopped) => ({ knowledge: { deleted: 0, imported: 0 }, preview: dryRunPreview, sent: [], stopped });
     // ── Collect knowledge entries (before file check so knowledge-only push works) ─
     let knowledgeObjects = [];
     if (ctx.knowledge) {
@@ -372,6 +603,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 +620,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 stop('cancelled');
+                }
+            }
+            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 +738,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',
@@ -427,7 +756,6 @@ export async function executePush(ctx, target, flags) {
         'Content-Type': 'text/x-xanoscript',
     };
     // ── Dry-run / Preview ─────────────────────────────────────────────────
-    let dryRunPreview = null;
     const dryRunUrl = knowledgeOnly ? null : target.buildDryRunUrl(queryParams);
     if (dryRunUrl && (flags['dry-run'] || !flags.force)) {
         const dryRunParams = new URLSearchParams(queryParams);
@@ -451,7 +779,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) {
@@ -480,7 +847,7 @@ export async function executePush(ctx, target, flags) {
                         log('');
                         log(ux.colorize('red', `Push blocked: ${criticalOps.length} critical error(s) found.`));
                         if (!flags.force) {
-                            return;
+                            return stop('blocked');
                         }
                         log(ux.colorize('yellow', 'Proceeding anyway due to --force flag.'));
                     }
@@ -510,10 +877,10 @@ export async function executePush(ctx, target, flags) {
                     if (!hasChanges && !hasLocalRecords) {
                         log('');
                         log('No changes to push.');
-                        return;
+                        return stop('no-changes');
                     }
                     if (flags['dry-run']) {
-                        return;
+                        return stop('dry-run');
                     }
                     // Warn when the sandbox currently holds a different source workspace than the one being
                     // pushed. The backend compares the source workspace id we sent against the id stored on
@@ -531,7 +898,7 @@ export async function executePush(ctx, target, flags) {
                             const proceed = await confirm('Continue with push anyway?');
                             if (!proceed) {
                                 log('Push cancelled. Run `xano sandbox reset` then retry.');
-                                return;
+                                return stop('cancelled');
                             }
                             mismatchConfirmed = true;
                         }
@@ -552,7 +919,7 @@ export async function executePush(ctx, target, flags) {
                             const confirmed = await confirm(message);
                             if (!confirmed) {
                                 log('Push cancelled.');
-                                return;
+                                return stop('cancelled');
                             }
                         }
                         else {
@@ -569,15 +936,17 @@ export async function executePush(ctx, target, flags) {
                 }
             }
             else {
-                await handleDryRunError(dryRunResponse, command, flags, target);
+                await handleDryRunError(dryRunResponse, command, target, { log, verbose: flags.verbose });
                 // If we get here, the user confirmed to proceed without preview
             }
         }
         catch (error) {
             // Ctrl+C or SIGINT
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error.name === 'AbortError' || error.code === 'ERR_USE_AFTER_CLOSE') {
                 log('\nPush cancelled.');
-                return;
+                return stop('cancelled');
             }
             // Re-throw oclif errors
             if (error instanceof Error && 'oclif' in error) {
@@ -608,16 +977,16 @@ export async function executePush(ctx, target, flags) {
         if (!hasChanges) {
             log('');
             log('No changes to push.');
-            return;
+            return stop('no-changes');
         }
         if (flags['dry-run']) {
-            return;
+            return stop('dry-run');
         }
         if (process.stdin.isTTY) {
             const confirmed = await confirm('Proceed with push?');
             if (!confirmed) {
                 log('Push cancelled.');
-                return;
+                return stop('cancelled');
             }
         }
         else {
@@ -633,22 +1002,19 @@ export async function executePush(ctx, target, flags) {
         }
     }
     // ── Partial push: filter to changed documents only ────────────────────
+    let sent = documentEntries;
     if (!knowledgeOnly && isPartial && dryRunPreview) {
-        const filteredEntries = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
-        if (filteredEntries.length === 0 && knowledgeObjects.length === 0) {
+        sent = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
+        if (sent.length === 0 && knowledgeObjects.length === 0) {
             log('No changes to push.');
-            return;
-        }
-        if (filteredEntries.length > 0) {
-            multidoc = filteredEntries.map((d) => d.content).join('\n---\n');
-        }
-        else {
-            multidoc = '';
+            return stop('no-changes');
         }
+        multidoc = sent.map((d) => d.content).join('\n---\n');
     }
     // ── Execute the actual push ───────────────────────────────────────────
     const startTime = Date.now();
     let pushedDocCount = 0;
+    let pushResponse;
     if (!knowledgeOnly && multidoc) {
         const apiUrl = target.buildPushUrl(queryParams);
         try {
@@ -658,14 +1024,19 @@ export async function executePush(ctx, target, flags) {
                 method: 'POST',
             }, flags.verbose, accessToken);
             if (!response.ok) {
-                handlePushError(response, await response.text(), documentEntries, inputDir, command);
+                const errorText = await response.text();
+                refuseIfExplained(command, target, response.status, errorText);
+                handlePushError(response, errorText, documentEntries, inputDir, command);
             }
             // Parse response for GUID map
             const responseText = await response.text();
             let guidMap = [];
+            pushResponse = {};
             if (responseText && responseText !== 'null') {
                 try {
                     const responseJson = JSON.parse(responseText);
+                    if (responseJson && typeof responseJson === 'object')
+                        pushResponse = responseJson;
                     if (responseJson?.guid_map && Array.isArray(responseJson.guid_map)) {
                         guidMap = responseJson.guid_map;
                     }
@@ -689,8 +1060,9 @@ export async function executePush(ctx, target, flags) {
                     }
                 }
                 let updatedCount = 0;
+                let canonicalCount = 0;
                 for (const entry of guidMap) {
-                    if (!entry.guid)
+                    if (!entry.guid || entry.type === 'policy')
                         continue;
                     const key = buildDocumentKey(entry.type, entry.name, entry.verb, entry.api_group);
                     let filePath = documentFileMap.get(key);
@@ -715,14 +1087,29 @@ 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;
         }
         catch (error) {
+            if (error instanceof PushPolicyGateError)
+                throw error;
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
@@ -732,6 +1119,12 @@ export async function executePush(ctx, target, flags) {
     // ── Push knowledge ────────────────────────────────────────────────────
     let knowledgeImported = 0;
     let knowledgeDeleted = 0;
+    const pushed = () => ({
+        knowledge: { deleted: knowledgeDeleted, imported: knowledgeImported },
+        preview: dryRunPreview,
+        response: pushResponse,
+        sent: pushResponse ? sent : [],
+    });
     if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
         const listUrl = ctx.knowledge.listUrl();
         try {
@@ -769,7 +1162,10 @@ export async function executePush(ctx, target, flags) {
             if (error instanceof Error && 'oclif' in error)
                 throw error;
             const elapsedMs = Date.now() - startTime;
-            command.error(`Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`);
+            const message = `Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`;
+            if (pushResponse)
+                throw new FailedAfterImportError(message, pushed());
+            command.error(message);
         }
     }
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
@@ -783,6 +1179,7 @@ export async function executePush(ctx, target, flags) {
         parts.push(kParts.join(', '));
     }
     log(`Pushed ${parts.join(' + ')} to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
+    return pushed();
 }
 // ── Error Handlers ──────────────────────────────────────────────────────────
 /**
@@ -820,6 +1217,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]) {
@@ -860,10 +1258,43 @@ function formatFailureDuration(elapsedMs) {
         ? ` (failed after ~${human}, near a common ${boundaries.find((b) => Math.abs(totalSeconds - b) <= b * 0.05)}s timeout — likely a server or proxy cutoff)`
         : ` (failed after ${human})`;
 }
-async function handleDryRunError(response, command, flags, target) {
-    const log = command.log.bind(command);
+/** Stop with the target's own guidance when it recognises this refusal. */
+function refuseIfExplained(command, target, status, body) {
+    let message = body;
+    let payload;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed?.message === 'string')
+            message = parsed.message;
+        payload = parsed?.payload;
+    }
+    catch {
+        // Not JSON
+    }
+    const refusal = payload;
+    if (status === 403 && refusal?.code === 'policy_gate')
+        throw new PushPolicyGateError(refusal);
+    // Policy files that weaken a mandatory policy of the live branch, from a credential without
+    // workspace:policy update: a permission refusal (exit 1), not a blocking finding. The platform's
+    // sentence already reads "Push refused: … Nothing was imported.", so it is printed as it is.
+    if (status === 403 && refusal?.code === WEAKENING_REFUSAL) {
+        command.error(`${message}${target.explainRefusal?.(status, payload) ?? policyWeakeningGuidance(payload, [], true)}`);
+    }
+    // The plan's policy cap: the platform's message names the plan, its cap and the remedy, and the
+    // push itself would be refused the same way, so the preview stops here rather than skipping.
+    if (status === 403 && refusal?.code === 'policy_plan_limit')
+        command.error(`Push refused (${status}): ${message}`);
+    if (refusal?.code === 'policy_gate_transaction_required') {
+        command.error('Push refused: the live branch policy gate requires a transaction. Remove --no-transaction and retry. Nothing was imported.');
+    }
+    const guidance = target.explainRefusal?.(status, payload);
+    if (guidance)
+        command.error(`Push refused (${status}): ${message}${guidance}`);
+}
+async function handleDryRunError(response, command, target, { log, verbose }) {
+    const errorText = await response.text();
+    refuseIfExplained(command, target, response.status, errorText);
     if (response.status === 404) {
-        const errorText = await response.text();
         try {
             const errorJson = JSON.parse(errorText);
             if (errorJson.message) {
@@ -881,7 +1312,6 @@ async function handleDryRunError(response, command, flags, target) {
         log('');
     }
     else {
-        const errorText = await response.text();
         // Check if push is disabled
         try {
             const errorJson = JSON.parse(errorText);
@@ -904,8 +1334,17 @@ async function handleDryRunError(response, command, flags, target) {
         catch {
             // Not JSON, fall through
         }
-        command.warn(`Push preview failed (${response.status}). Skipping preview.`);
-        if (flags.verbose) {
+        let reason = '';
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (typeof errorJson?.message === 'string' && errorJson.message.trim())
+                reason = `: ${errorJson.message.trim().replace(/\.$/, '')}`;
+        }
+        catch {
+            // Not JSON
+        }
+        command.warn(`Push preview failed (${response.status})${reason}. Skipping preview.`);
+        if (verbose) {
             log(ux.colorize('dim', errorText));
         }
     }