@xano/cli 1.3.3 → 1.3.5-beta.0

package/dist/utils/multidoc-push.js

@@ -1,11 +1,27 @@
-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 { compareLocalToExport, indexLocalDocuments, parseExportDocuments, resolveMatchedPath, selectWritebacks, } from './export-compare.js';
 import { flattenBundleFile } from './flatten.js';
 import { collectKnowledgeObjects, fetchKnowledge, knowledgePreview, pushKnowledge, syncGuidToFrontmatter, toPushItems, } from './knowledge-sync.js';
+import { fetchFormattedObjects, } from './object-fetch.js';
+import { PushPolicyGateError } from './policy/push-gate.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
+import { invalidateSandboxMarkerForOrigin, readMarkerToken, sandboxMarkerExists, writeMarkerToken, } from './sandbox-marker.js';
+import { hashBytes, hashFile, instanceHost, loadSyncState, recordEntriesForContents, resolveTarget, sandboxTargetIdentity, saveSyncState, syncStateExists, toRelPath, } from './sync-state.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.
@@ -44,6 +60,10 @@ export function filterChangedEntries(entries, operations, includeRecords) {
         return false;
     });
 }
+/** True for a table document carrying an `items = [...]` block (records). */
+function isTableWithRecords(content) {
+    return /^table\s+/m.test(content) && /\bitems\s*=\s*\[/m.test(content);
+}
 // ── File Collection ─────────────────────────────────────────────────────────
 /**
  * Recursively collect all .xs files from a directory, sorted for deterministic ordering.
@@ -211,15 +231,117 @@ export function deletesHittingFilteredOut(operations, filteredOut) {
     }
     return hits;
 }
+export function pathMatchesFilters(relPath, inputDir, include, exclude) {
+    if (include && include.length > 0) {
+        const patterns = include.map((pattern) => normalizeFilterPattern(pattern, inputDir));
+        if (!patterns.some((pattern) => minimatch(relPath, pattern, { matchBase: true }))) {
+            return false;
+        }
+    }
+    if (exclude && exclude.length > 0) {
+        const patterns = exclude.map((pattern) => normalizeFilterPattern(pattern, inputDir));
+        if (patterns.some((pattern) => minimatch(relPath, pattern, { matchBase: true }))) {
+            return false;
+        }
+    }
+    return true;
+}
+function commitSyncRecordWithSandbox(ctx, inputDir, target, entries, options, warn) {
+    if (!target) {
+        warn('Skipped writing sync record; could not resolve sandbox/workspace identity');
+        return;
+    }
+    let sandboxToken;
+    if (ctx.syncTarget?.kind === 'sandbox') {
+        try {
+            sandboxToken = writeMarkerToken(ctx.syncTarget.markerDir, target.instance_host, target.branch_created_at);
+        }
+        catch (error) {
+            warn(`Skipped writing sandbox sync marker: ${error.message}`);
+        }
+    }
+    trySaveSyncState(inputDir, target, entries, { ...options, sandboxToken }, warn);
+}
+function trySaveSyncState(inputDir, target, entries, options, warn) {
+    try {
+        saveSyncState(inputDir, target, entries, options);
+    }
+    catch (error) {
+        warn(`Skipped writing .xano/sync_state.json: ${error.message}`);
+    }
+}
+async function resolveSyncTarget(ctx, flags) {
+    if (!ctx.syncTarget) {
+        return { isLiveBranch: !ctx.branch, liveBranch: ctx.branch, target: null };
+    }
+    const origin = ctx.syncTarget.instanceOrigin.replace(/\/$/, '');
+    const fetchJson = async (pathname) => {
+        const response = await ctx.verboseFetch(`${origin}/api:meta${pathname}`, {
+            headers: {
+                accept: 'application/json',
+                Authorization: `Bearer ${ctx.accessToken}`,
+            },
+            method: 'GET',
+        }, flags.verbose, ctx.accessToken);
+        if (!response.ok) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        return response.json();
+    };
+    if (ctx.syncTarget.kind === 'sandbox') {
+        try {
+            const me = await fetchJson('/sandbox/me');
+            if (!me ||
+                typeof me !== 'object' ||
+                Array.isArray(me) ||
+                typeof me.created_at !== 'string' ||
+                typeof me.id !== 'number') {
+                return { isLiveBranch: true, liveBranch: '', target: null };
+            }
+            return {
+                isLiveBranch: true,
+                liveBranch: '',
+                target: sandboxTargetIdentity(instanceHost(ctx.syncTarget.instanceOrigin), {
+                    created_at: me.created_at,
+                    id: me.id,
+                }),
+            };
+        }
+        catch {
+            return { isLiveBranch: true, liveBranch: '', target: null };
+        }
+    }
+    const target = await resolveTarget(ctx.syncTarget.instanceOrigin, ctx.syncTarget.workspace, ctx.branch, fetchJson);
+    return {
+        isLiveBranch: Boolean(target && target.branch === target.live_branch),
+        liveBranch: target?.live_branch ?? ctx.branch,
+        target,
+    };
+}
+function maybeInvalidateSandboxMarker(ctx, persistRecord, warn) {
+    if (ctx.syncTarget?.kind !== 'sandbox')
+        return;
+    if (!persistRecord && !sandboxMarkerExists(ctx.syncTarget.markerDir))
+        return;
+    try {
+        invalidateSandboxMarkerForOrigin(ctx.syncTarget.markerDir, ctx.syncTarget.instanceOrigin);
+    }
+    catch (error) {
+        warn(`Skipped invalidating sandbox sync marker: ${error.message}`);
+    }
+}
 /**
- * Read .xs files into document entries, skipping empty files.
+ * Read .xs files into document entries, skipping empty files. When `raw` is given, the
+ * untrimmed bytes of each returned file are stored in it, keyed by file path.
  */
-export function readDocuments(files) {
+export function readDocuments(files, raw) {
     const entries = [];
     for (const filePath of files) {
-        const content = fs.readFileSync(filePath, 'utf8').trim();
+        const bytes = fs.readFileSync(filePath, 'utf8');
+        const content = bytes.trim();
         if (content) {
             entries.push({ content, filePath });
+            raw?.set(filePath, bytes);
         }
     }
     return entries;
@@ -470,15 +592,22 @@ const GUID_REGEX = /guid\s*=\s*(["'])([^"']*)\1/;
  * Sync a GUID into a local .xs file. Returns true if the file was modified.
  */
 function syncGuidToFile(filePath, guid) {
-    const content = fs.readFileSync(filePath, 'utf8');
+    const updated = withGuid(fs.readFileSync(filePath, 'utf8'), guid);
+    if (updated === null)
+        return false;
+    fs.writeFileSync(filePath, updated, 'utf8');
+    return true;
+}
+/**
+ * Return `content` with its GUID set to `guid`, or null when nothing changes.
+ */
+function withGuid(content, guid) {
     const existingMatch = content.match(GUID_REGEX);
     if (existingMatch) {
         if (existingMatch[2] === guid) {
-            return false;
+            return null;
         }
-        const updated = content.replace(GUID_REGEX, `guid = "${guid}"`);
-        fs.writeFileSync(filePath, updated, 'utf8');
-        return true;
+        return content.replace(GUID_REGEX, `guid = "${guid}"`);
     }
     // No GUID line exists — insert before the final closing brace
     const lines = content.split('\n');
@@ -490,7 +619,7 @@ function syncGuidToFile(filePath, guid) {
         }
     }
     if (insertIndex === -1) {
-        return false;
+        return null;
     }
     let indent = '  ';
     for (let i = insertIndex - 1; i >= 0; i--) {
@@ -503,8 +632,7 @@ function syncGuidToFile(filePath, guid) {
         }
     }
     lines.splice(insertIndex, 0, `${indent}guid = "${guid}"`);
-    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
-    return true;
+    return lines.join('\n');
 }
 const CANONICAL_REGEX = /canonical\s*=\s*(["'])([^"']*)\1/;
 /**
@@ -524,13 +652,30 @@ const CANONICAL_REGEX = /canonical\s*=\s*(["'])([^"']*)\1/;
  * has no canonical" rather than "not yet assigned".
  */
 function syncCanonicalToFile(filePath, canonical) {
-    const content = fs.readFileSync(filePath, 'utf8');
+    const updated = withCanonical(fs.readFileSync(filePath, 'utf8'), canonical);
+    if (updated === null)
+        return false;
+    fs.writeFileSync(filePath, updated, 'utf8');
+    return true;
+}
+/**
+ * Return `content` with its canonical set to `canonical`, or null when nothing changes.
+ */
+function withCanonical(content, canonical) {
     const existingMatch = content.match(CANONICAL_REGEX);
     if (!existingMatch || existingMatch[2] === canonical) {
-        return false;
+        return null;
     }
-    fs.writeFileSync(filePath, content.replace(CANONICAL_REGEX, `canonical = "${canonical}"`), 'utf8');
-    return true;
+    return content.replace(CANONICAL_REGEX, `canonical = "${canonical}"`);
+}
+/** Apply a GUID/canonical rewrite to the in-memory copy of what was pushed. */
+function updateSnapshot(snapshots, filePath, rewrite) {
+    const content = snapshots.get(filePath);
+    if (content === undefined)
+        return;
+    const updated = rewrite(content);
+    if (updated !== null)
+        snapshots.set(filePath, updated);
 }
 // ── Knowledge Preview Helpers ─────────────────────────────────────────────────
 /**
@@ -579,7 +724,15 @@ 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 });
+    if (flags.fast && flags.sync) {
+        command.error('--fast cannot be used with --sync');
+    }
+    if (flags.refresh && !flags.fast) {
+        command.error('--refresh requires --fast');
+    }
     // ── Collect knowledge entries (before file check so knowledge-only push works) ─
     let knowledgeObjects = [];
     if (ctx.knowledge) {
@@ -600,8 +753,12 @@ export async function executePush(ctx, target, flags) {
     let documentEntries = [];
     let multidoc = '';
     const documentFileMap = new Map();
+    // The exact bytes of each document as read for this push (then as rewritten by GUID sync
+    // and writeback). The sync record hashes these, never a later re-read of the file, so an
+    // edit made while the push runs is not recorded as synced.
+    const pushedBytes = new Map();
     if (!knowledgeOnly) {
-        documentEntries = readDocuments(files);
+        documentEntries = readDocuments(files, pushedBytes);
         if (documentEntries.length === 0) {
             command.error(`All .xs files in ${inputDir} are empty`);
         }
@@ -638,7 +795,7 @@ export async function executePush(ctx, target, flags) {
                 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;
+                    return stop('cancelled');
                 }
             }
             else {
@@ -657,7 +814,8 @@ export async function executePush(ctx, target, flags) {
             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, () => { }));
+            pushedBytes.clear();
+            const refreshed = readDocuments(applyFilters(collectFiles(inputDir), inputDir, flags.include, flags.exclude, () => { }), pushedBytes);
             documentEntries = refreshed;
             if (documentEntries.length === 0) {
                 command.error('After flattening, no .xs documents remain to push.');
@@ -700,12 +858,175 @@ export async function executePush(ctx, target, flags) {
             }
         }
     }
+    const allDocumentEntries = [...documentEntries];
+    let recordSourceEntries = [...documentEntries];
+    let exportRebuild = false;
+    const pendingRecordEntries = {};
+    // Filled after writeback; the second persist() picks up the ids through recordEntriesFor.
+    const writebackIds = {};
+    const recordEntriesFor = (filePaths) => {
+        const snapshots = filePaths.flatMap((filePath) => {
+            const content = pushedBytes.get(filePath);
+            return content === undefined ? [] : [{ content, filePath }];
+        });
+        const entries = { ...pendingRecordEntries, ...recordEntriesForContents(inputDir, snapshots) };
+        for (const [relPath, found] of Object.entries(writebackIds)) {
+            const entry = entries[relPath];
+            if (entry && entry.key === found.key && found.id !== undefined) {
+                entries[relPath] = { ...entry, id: found.id };
+            }
+        }
+        return entries;
+    };
+    // An export rebuild re-derives the whole record, unless -i/-e limited it to part of the tree.
+    // An untrusted sandbox record is always replaced: entries outside the filter describe a
+    // sandbox that may since have been reset, and the new token would vouch for them.
+    const replaceRecord = () => exportRebuild && (sandboxUntrusted || (!flags.include && !flags.exclude));
+    // Under --records a table with items is always sent, as filterChangedEntries does without
+    // --fast: the record does not say whether its rows were imported.
+    const alwaysSend = (content) => flags.records && isTableWithRecords(content);
+    const persistRecord = !flags['dry-run'] && Boolean(ctx.syncTarget) && (Boolean(flags.fast) || syncStateExists(inputDir));
+    const resolved = flags.fast || flags.writeback || persistRecord
+        ? await resolveSyncTarget(ctx, flags)
+        : { isLiveBranch: !ctx.branch, liveBranch: ctx.branch, target: null };
+    const resolvedTarget = resolved.target;
+    let loadedState = null;
+    if (resolvedTarget) {
+        loadedState = loadSyncState(inputDir, resolvedTarget, (message) => command.warn(message));
+    }
+    else if (ctx.syncTarget && flags.fast) {
+        command.warn('Could not resolve sync target fingerprints; comparing against the server export');
+    }
+    let sandboxUntrusted = false;
+    if (ctx.syncTarget?.kind === 'sandbox' && resolvedTarget && loadedState) {
+        const markerToken = readMarkerToken(ctx.syncTarget.markerDir, resolvedTarget.instance_host, resolvedTarget.branch_created_at);
+        if (!loadedState.sandbox_token || loadedState.sandbox_token !== markerToken) {
+            sandboxUntrusted = true;
+            loadedState = null;
+        }
+    }
+    if (flags.fast && flags.env && ctx.syncTarget && !knowledgeOnly) {
+        log(ux.colorize('dim', '--env: the sync record does not track environment variables; comparing every file with the dry-run'));
+    }
+    if (flags.fast && !flags.env && ctx.syncTarget && !knowledgeOnly) {
+        const useExport = Boolean(flags.refresh) || !resolvedTarget || !loadedState;
+        if (useExport) {
+            let exportReason = 'No sync record for this workspace/branch; comparing against the server export';
+            if (flags.refresh) {
+                exportReason = 'Refreshing sync record from the server export';
+            }
+            else if (sandboxUntrusted) {
+                exportReason =
+                    'Sandbox changed since this directory\'s last push (reset, delete, or another directory); comparing against the sandbox export';
+            }
+            log(exportReason);
+            const exportParams = new URLSearchParams({
+                env: 'false',
+                include_draft: 'false',
+                records: flags.records.toString(),
+            });
+            if (target.supportsBranches) {
+                exportParams.set('branch', ctx.branch);
+            }
+            try {
+                const exportResponse = await verboseFetch(target.buildPushUrl(exportParams), {
+                    headers: {
+                        accept: 'application/json',
+                        Authorization: `Bearer ${accessToken}`,
+                    },
+                    method: 'GET',
+                }, flags.verbose, accessToken);
+                if (!exportResponse.ok) {
+                    throw new Error(`HTTP ${exportResponse.status}`);
+                }
+                const exported = parseExportDocuments(await exportResponse.text());
+                const compared = compareLocalToExport(allDocumentEntries.map((entry) => ({
+                    ...entry,
+                    relPath: toRelPath(inputDir, entry.filePath),
+                })), exported);
+                if (compared.serverOnly.length > 0) {
+                    log(ux.colorize('dim', `${compared.serverOnly.length} object${compared.serverOnly.length === 1 ? '' : 's'} exist on the server but not locally; pull to get them, or --sync --delete to remove them`));
+                }
+                exportRebuild = true;
+                const candidates = [...compared.candidates];
+                const identical = [];
+                for (const entry of compared.identical) {
+                    if (alwaysSend(entry.content))
+                        candidates.push(entry);
+                    else
+                        identical.push(entry);
+                }
+                Object.assign(pendingRecordEntries, recordEntriesFor(identical.map((entry) => entry.filePath)));
+                if (candidates.length === 0 && knowledgeObjects.length === 0) {
+                    if (resolvedTarget && !flags['dry-run']) {
+                        commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, pendingRecordEntries, { replace: replaceRecord() }, (message) => command.warn(message));
+                    }
+                    log('');
+                    log('No changes to push.');
+                    return stop('no-changes');
+                }
+                documentEntries = candidates;
+                recordSourceEntries = [...documentEntries];
+                multidoc = documentEntries.map((entry) => entry.content).join('\n---\n');
+                documentFileMap.clear();
+                for (const entry of documentEntries) {
+                    const parsed = parseDocument(entry.content);
+                    if (parsed) {
+                        documentFileMap.set(buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup), entry.filePath);
+                    }
+                }
+            }
+            catch (error) {
+                command.warn(`Failed to download the server export for --fast (${error.message}); falling back to a full dry-run`);
+                exportRebuild = false;
+            }
+        }
+        else if (resolvedTarget && loadedState) {
+            const allHashes = collectFiles(inputDir).map((filePath) => {
+                const content = pushedBytes.get(filePath);
+                return {
+                    alwaysSend: content !== undefined && alwaysSend(content),
+                    relPath: toRelPath(inputDir, filePath),
+                    sha256: content === undefined ? hashFile(filePath) : hashBytes(content),
+                };
+            });
+            const { candidates, deletedLocally } = {
+                candidates: allHashes.filter((file) => {
+                    const recorded = loadedState.files[file.relPath];
+                    return file.alwaysSend || !recorded || recorded.sha256 !== file.sha256;
+                }),
+                deletedLocally: Object.entries(loadedState.files)
+                    .filter(([relPath]) => !allHashes.some((file) => file.relPath === relPath))
+                    .filter(([relPath]) => pathMatchesFilters(relPath, inputDir, flags.include, flags.exclude))
+                    .map(([relPath, entry]) => ({ key: entry.key, relPath })),
+            };
+            if (deletedLocally.length > 0) {
+                log(ux.colorize('dim', `${deletedLocally.length} file${deletedLocally.length === 1 ? '' : 's'} deleted locally since last sync; use --sync --delete to remove them remotely`));
+            }
+            const candidatePaths = new Set(candidates.map((file) => file.relPath));
+            documentEntries = allDocumentEntries.filter((entry) => candidatePaths.has(toRelPath(inputDir, entry.filePath)));
+            recordSourceEntries = [...documentEntries];
+            if (documentEntries.length === 0 && knowledgeObjects.length === 0) {
+                log('No local changes since last sync');
+                return stop('no-changes');
+            }
+            multidoc = documentEntries.map((entry) => entry.content).join('\n---\n');
+            documentFileMap.clear();
+            for (const entry of documentEntries) {
+                const parsed = parseDocument(entry.content);
+                if (parsed) {
+                    documentFileMap.set(buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup), entry.filePath);
+                }
+            }
+        }
+    }
     // ── Resolve push mode ─────────────────────────────────────────────────
     const isPartial = !flags.sync;
     if (flags.delete && isPartial) {
         command.error('Cannot use --delete without --sync');
     }
     const shouldDelete = isPartial ? false : flags.delete;
+    const pruneMissing = shouldDelete && !knowledgeOnly;
     // ── Build query params ────────────────────────────────────────────────
     const queryParams = new URLSearchParams({
         delete: shouldDelete.toString(),
@@ -741,7 +1062,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);
@@ -806,7 +1126,7 @@ export async function executePush(ctx, target, flags) {
                         }
                     }
                     // Check for bad cross-references using dry-run operations to avoid false positives
-                    const badRefs = checkReferences(documentEntries, preview.operations);
+                    const badRefs = checkReferences(allDocumentEntries, preview.operations, documentEntries);
                     if (badRefs.length > 0) {
                         renderBadReferences(badRefs, log);
                     }
@@ -833,7 +1153,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.'));
                     }
@@ -842,7 +1162,7 @@ export async function executePush(ctx, target, flags) {
                     // Detect local records
                     const tablesWithRecords = flags.records
                         ? documentEntries
-                            .filter((d) => /^table\s+/m.test(d.content) && /\bitems\s*=\s*\[/m.test(d.content))
+                            .filter((d) => isTableWithRecords(d.content))
                             .map((d) => {
                             const nameMatch = d.content.match(/^table\s+(\S+)/m);
                             const itemsMatch = d.content.match(/\bitems\s*=\s*\[([\s\S]*?)\n\s*\]/);
@@ -863,10 +1183,13 @@ export async function executePush(ctx, target, flags) {
                     if (!hasChanges && !hasLocalRecords) {
                         log('');
                         log('No changes to push.');
-                        return;
+                        if (persistRecord) {
+                            commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(recordSourceEntries.map((entry) => entry.filePath)), { pruneMissing, replace: replaceRecord() }, (message) => command.warn(message));
+                        }
+                        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
@@ -884,7 +1207,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;
                         }
@@ -905,7 +1228,7 @@ export async function executePush(ctx, target, flags) {
                             const confirmed = await confirm(message);
                             if (!confirmed) {
                                 log('Push cancelled.');
-                                return;
+                                return stop('cancelled');
                             }
                         }
                         else {
@@ -922,15 +1245,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) {
@@ -961,16 +1286,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 {
@@ -979,24 +1304,43 @@ export async function executePush(ctx, target, flags) {
     }
     // ── Show bad references in force mode (preview mode shows them inline) ─
     if (flags.force && !knowledgeOnly) {
-        const badRefs = checkReferences(documentEntries);
+        const badRefs = checkReferences(allDocumentEntries, undefined, documentEntries);
         if (badRefs.length > 0) {
             log('');
             renderBadReferences(badRefs, log);
         }
     }
     // ── 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 (persistRecord) {
+                commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(recordSourceEntries.map((entry) => entry.filePath)), { pruneMissing: false, replace: replaceRecord() }, (message) => command.warn(message));
+            }
+            return stop('no-changes');
         }
-        multidoc = filteredEntries.length > 0 ? filteredEntries.map((d) => d.content).join('\n---\n') : '';
+        multidoc = sent.map((d) => d.content).join('\n---\n');
     }
+    const persist = () => {
+        if (!persistRecord || !ctx.syncTarget)
+            return;
+        const paths = [
+            ...recordSourceEntries.map((entry) => entry.filePath),
+            ...sent.map((entry) => entry.filePath),
+        ];
+        commitSyncRecordWithSandbox(ctx, inputDir, resolvedTarget, recordEntriesFor(paths), { pruneMissing, replace: replaceRecord() }, (message) => command.warn(message));
+    };
     // ── Execute the actual push ───────────────────────────────────────────
+    const willMutate = (!knowledgeOnly && Boolean(multidoc)) ||
+        Boolean(ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete));
+    if (willMutate && !flags['dry-run']) {
+        maybeInvalidateSandboxMarker(ctx, persistRecord, (message) => command.warn(message));
+    }
     const startTime = Date.now();
     let pushedDocCount = 0;
+    let pushResponse;
     if (!knowledgeOnly && multidoc) {
         const apiUrl = target.buildPushUrl(queryParams);
         try {
@@ -1006,14 +1350,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;
                     }
@@ -1039,7 +1388,7 @@ 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);
@@ -1060,15 +1409,18 @@ export async function executePush(ctx, target, flags) {
                         const updated = syncGuidToFile(filePath, entry.guid);
                         if (updated)
                             updatedCount++;
+                        updateSnapshot(pushedBytes, filePath, (content) => withGuid(content, entry.guid));
                     }
                     catch (error) {
                         command.warn(`Failed to sync GUID to ${filePath}: ${error.message}`);
                     }
                     if (entry.canonical) {
+                        const { canonical } = entry;
                         try {
-                            const updated = syncCanonicalToFile(filePath, entry.canonical);
+                            const updated = syncCanonicalToFile(filePath, canonical);
                             if (updated)
                                 canonicalCount++;
+                            updateSnapshot(pushedBytes, filePath, (content) => withCanonical(content, canonical));
                         }
                         catch (error) {
                             command.warn(`Failed to sync canonical to ${filePath}: ${error.message}`);
@@ -1085,15 +1437,54 @@ export async function executePush(ctx, target, flags) {
             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;
             command.error(`Failed to push multidoc: ${describeNetworkError(error, apiUrl, elapsedMs)}`);
         }
     }
+    // Write the marker/record before writeback. Writeback is another full export, and
+    // a failure or Ctrl+C there must not drop --fast state from an already-successful push.
+    persist();
+    let writebackMs = 0;
+    if (flags.writeback && pushedDocCount > 0) {
+        const writeback = await writeBackFormattedDocuments({
+            accessToken,
+            branch: ctx.branch,
+            command,
+            includeEnv: flags.env,
+            includeRecords: flags.records,
+            inputDir,
+            isLiveBranch: resolved.isLiveBranch,
+            log,
+            pushedBytes,
+            pushedEntries: sent,
+            resolvedTarget,
+            syncState: loadedState,
+            target,
+            verbose: flags.verbose,
+            verboseFetch,
+            workspaceId: ctx.syncTarget?.kind === 'workspace' ? ctx.syncTarget.workspace : undefined,
+            writebackDiff: flags.writebackDiff,
+            writebackObjectLimit: flags.writebackObjectLimit,
+        });
+        writebackMs = writeback.elapsedMs;
+        Object.assign(writebackIds, writeback.ids);
+        for (const { content, filePath } of writeback.written) {
+            pushedBytes.set(filePath, content);
+        }
+    }
     // ── 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 {
@@ -1131,10 +1522,13 @@ 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);
+    const elapsed = (Math.max(0, Date.now() - startTime - writebackMs) / 1000).toFixed(1);
     const parts = [];
     if (!knowledgeOnly)
         parts.push(`${pushedDocCount} documents`);
@@ -1144,7 +1538,198 @@ export async function executePush(ctx, target, flags) {
             kParts.push(`${knowledgeDeleted} deleted`);
         parts.push(kParts.join(', '));
     }
+    persist();
     log(`Pushed ${parts.join(' + ')} to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
+    return pushed();
+}
+export async function writeBackFormattedDocuments(args) {
+    const started = Date.now();
+    const { accessToken, branch, command, includeEnv, includeRecords, inputDir, isLiveBranch = !branch, pushedBytes, resolvedTarget, syncState, target, verbose, verboseFetch, workspaceId, writebackDiff, writebackObjectLimit, } = args;
+    const log = args.log ?? command.log.bind(command);
+    const elapsedLabel = () => ` (${((Date.now() - started) / 1000).toFixed(1)}s)`;
+    const ids = {};
+    const written = [];
+    const done = () => ({ elapsedMs: Date.now() - started, ids, written });
+    const relPathOf = (filePath) => (inputDir ? toRelPath(inputDir, filePath) : filePath);
+    const localContents = new Map();
+    const pushedFiles = new Map();
+    const unchangedEntries = [];
+    for (const entry of args.pushedEntries) {
+        const parsed = parseDocument(entry.content);
+        if (!parsed)
+            continue;
+        let local;
+        try {
+            local = fs.readFileSync(entry.filePath, 'utf8');
+        }
+        catch {
+            local = entry.content;
+        }
+        const sent = pushedBytes?.get(entry.filePath);
+        if (sent !== undefined && local !== sent) {
+            command.warn(`Writeback: skipped ${relPathOf(entry.filePath)}; it changed after it was read for the push`);
+            continue;
+        }
+        const key = buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup);
+        pushedFiles.set(key, entry.filePath);
+        localContents.set(entry.filePath, local);
+        unchangedEntries.push(entry);
+    }
+    if (unchangedEntries.length === 0)
+        return done();
+    let exportedDocs = [];
+    let pathLabel = 'export';
+    if (resolvedTarget && workspaceId && writebackObjectLimit !== 0) {
+        const get = async (pathname, query = {}) => {
+            const params = new URLSearchParams(query);
+            const origin = target.instanceOrigin.replace(/\/$/, '');
+            const url = `${origin}/api:meta${pathname}${params.toString() ? `?${params.toString()}` : ''}`;
+            const response = await verboseFetch(url, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${accessToken}`,
+                },
+                method: 'GET',
+            }, verbose, accessToken);
+            const text = await response.text();
+            let json = text;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                // keep text
+            }
+            return { json, ok: response.ok, status: response.status };
+        };
+        let fetched;
+        try {
+            fetched = await fetchFormattedObjects({
+                get,
+                isLiveBranch,
+                limit: writebackObjectLimit,
+                pushed: unchangedEntries.map((entry) => ({
+                    content: localContents.get(entry.filePath) ?? entry.content,
+                    filePath: entry.filePath,
+                    relPath: relPathOf(entry.filePath),
+                })),
+                state: syncState ?? null,
+                target: resolvedTarget,
+                workspaceId,
+            });
+        }
+        catch (error) {
+            fetched = { ok: false, reason: error.message };
+        }
+        if (fetched.ok) {
+            Object.assign(ids, fetched.ids);
+            exportedDocs = [];
+            for (const result of fetched.results) {
+                const parsed = parseDocument(result.content);
+                if (!parsed) {
+                    command.warn(`Writeback: skipped ${result.filePath}; fetched document did not parse`);
+                    continue;
+                }
+                exportedDocs.push({ ...parsed, content: result.content });
+            }
+            pathLabel = 'per-object';
+        }
+        else {
+            command.warn(`Per-object writeback unavailable (${fetched.reason}); using full export`);
+        }
+    }
+    if (exportedDocs.length === 0) {
+        const exportParams = new URLSearchParams({
+            env: includeEnv.toString(),
+            records: includeRecords.toString(),
+        });
+        exportParams.set('include_draft', 'false');
+        if (target.supportsBranches) {
+            exportParams.set('branch', branch);
+        }
+        const exportUrl = target.buildPushUrl(exportParams);
+        let response;
+        try {
+            response = await verboseFetch(exportUrl, {
+                headers: {
+                    accept: 'application/json',
+                    Authorization: `Bearer ${accessToken}`,
+                },
+                method: 'GET',
+            }, verbose, accessToken);
+        }
+        catch (error) {
+            command.warn(`Failed to fetch server-formatted documents for writeback: ${error.message}`);
+            return done();
+        }
+        if (!response.ok) {
+            command.warn(`Failed to fetch server-formatted documents for writeback (${response.status})`);
+            return done();
+        }
+        const responseText = await response.text();
+        exportedDocs = parseExportDocuments(responseText);
+        pathLabel = 'export';
+        if (exportedDocs.length === 0) {
+            const preview = responseText.trim().slice(0, 200).replaceAll('\n', String.raw `\n`);
+            command.warn(`Writeback: export contained no XanoScript documents (${pushedFiles.size} pushed). Response starts with: ${preview || '(empty)'}`);
+            return done();
+        }
+    }
+    const matcher = indexLocalDocuments(pushedFiles, localContents);
+    const matched = new Set();
+    for (const doc of exportedDocs) {
+        const filePath = resolveMatchedPath(doc, matcher);
+        if (filePath)
+            matched.add(filePath);
+    }
+    const writebacks = selectWritebacks(exportedDocs, pushedFiles, localContents, { includeRecords });
+    if (writebackDiff) {
+        for (const { content, filePath } of writebacks) {
+            const local = localContents.get(filePath) ?? '';
+            const rel = inputDir ? relPathOf(filePath) : filePath.split(/[\\/]/).pop() || 'file.xs';
+            const destBase = join(writebackDiff, rel);
+            try {
+                fs.mkdirSync(join(destBase, '..'), { recursive: true });
+                fs.writeFileSync(`${destBase}.local.xs`, local, 'utf8');
+                fs.writeFileSync(`${destBase}.server.xs`, content.trim(), 'utf8');
+            }
+            catch (error) {
+                command.warn(`Failed to write writeback-diff for ${filePath}: ${error.message}`);
+            }
+        }
+    }
+    for (const { content, filePath } of writebacks) {
+        // Same bytes `pull` writes: the trimmed document, no trailing newline.
+        const bytes = content.trim();
+        // Re-check right before writing: the fetch above can take minutes.
+        let current = null;
+        try {
+            current = fs.readFileSync(filePath, 'utf8');
+        }
+        catch {
+            // Treated as changed below.
+        }
+        if (current !== localContents.get(filePath)) {
+            command.warn(`Writeback: skipped ${relPathOf(filePath)}; it changed after it was read for the push`);
+            continue;
+        }
+        try {
+            fs.writeFileSync(filePath, bytes, 'utf8');
+            written.push({ content: bytes, filePath });
+        }
+        catch (error) {
+            command.warn(`Failed to write formatted document to ${filePath}: ${error.message}`);
+        }
+    }
+    if (written.length > 0) {
+        log(`Wrote ${written.length} formatted file${written.length === 1 ? '' : 's'} (${pathLabel}${elapsedLabel()})`);
+        return done();
+    }
+    if (matched.size === 0) {
+        command.warn(`Writeback: fetched ${exportedDocs.length} documents, but none matched the ${pushedFiles.size} pushed file${pushedFiles.size === 1 ? '' : 's'}${elapsedLabel()}`);
+        return done();
+    }
+    log(`Writeback: ${matched.size} pushed file${matched.size === 1 ? '' : 's'} already match the server export${elapsedLabel()}`);
+    return done();
 }
 // ── Error Handlers ──────────────────────────────────────────────────────────
 /**
@@ -1223,10 +1808,37 @@ 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, message === body ? undefined : message);
+    // 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) {
@@ -1244,7 +1856,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);
@@ -1267,8 +1878,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));
         }
     }
@@ -1323,3 +1943,4 @@ function handlePushError(response, errorText, documentEntries, inputDir, command
     }
     command.error(errorMessage);
 }
+export { parseExportDocuments, preserveLocalTableRecords, selectWritebacks } from './export-compare.js';