@xano/cli 1.3.2 → 1.3.4

package/dist/commands/workspace/push/index.js

@@ -1,7 +1,8 @@
 import { Flags } from '@oclif/core';
 import * as fs from 'node:fs';
-import { resolve } from 'node:path';
+import { basename, relative, resolve } from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { formatWorkspacePushDefaultsBanner, resolvePushDefaults } from '../../../utils/local-config.js';
 import { executePush } from '../../../utils/multidoc-push.js';
 export default class Push extends BaseCommand {
     static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local documents to a workspace. By default, only changed files are pushed (partial mode). Use --sync to push all files. Shows a preview of changes before pushing unless --force is specified. Use --dry-run to preview only.';
@@ -23,6 +24,18 @@ Preview changes without pushing
 `,
         `$ xano workspace push --force
 Skip preview and push immediately (for CI/CD)
+`,
+        `$ xano workspace push --fast
+Push only files that changed since the last sync, and write .xano/sync_state.json
+`,
+        `$ xano workspace push --fast --refresh
+Re-compare local files against the server export, then push changes
+`,
+        `$ xano workspace push --no-fast
+Push without --fast even when profile.yaml sets fast: true
+`,
+        `$ xano workspace push --writeback
+Push and write server-formatted XanoScript back to local files
 `,
         `$ xano workspace push -d ./output -w 40
 Pushed 15 documents from ./output
@@ -95,6 +108,11 @@ Full sync including knowledge files; removes server objects not present locally
             multiple: true,
             required: false,
         }),
+        fast: Flags.boolean({
+            allowNo: true,
+            description: 'Skip files whose contents match .xano/sync_state.json, and write or update that record. Without a record, compares against the server export once. Can be set as `fast: true` in profile.yaml.',
+            required: false,
+        }),
         force: Flags.boolean({
             default: false,
             description: '[CRITICAL] NEVER run without explicit user confirmation. Skips preview and confirmation prompt (for CI/CD pipelines).',
@@ -117,6 +135,11 @@ Full sync including knowledge files; removes server objects not present locally
             description: '[CRITICAL] STOP and ALWAYS run --dry-run first to show the user a preview before pushing live table records. Includes table records in import.',
             required: false,
         }),
+        refresh: Flags.boolean({
+            default: false,
+            description: 'With --fast, re-compare local files against the server export even when a sync record exists',
+            required: false,
+        }),
         sync: Flags.boolean({
             default: false,
             description: 'Full push — send all files, not just changed ones. Required for --delete.',
@@ -138,6 +161,15 @@ Full sync including knowledge files; removes server objects not present locally
             description: 'Workspace ID (optional if set in profile)',
             required: false,
         }),
+        writeback: Flags.boolean({
+            allowNo: true,
+            description: 'After a successful push, write server-formatted XanoScript back to the files that were pushed. Can be set as `writeback: true` in profile.yaml.',
+            required: false,
+        }),
+        'writeback-diff': Flags.string({
+            description: 'With --writeback, save local vs server copies of rewritten files under this directory',
+            required: false,
+        }),
     };
     async run() {
         const { flags } = await this.parse(Push);
@@ -164,6 +196,17 @@ Full sync including knowledge files; removes server objects not present locally
         }
         const branch = flags.branch || profile.branch || '';
         const baseUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}`;
+        const pushDefaults = resolvePushDefaults({
+            flagFast: flags.fast,
+            flagWriteback: flags.writeback,
+            localFast: this.localProfile?.config.fast,
+            localWriteback: this.localProfile?.config.writeback,
+            sync: flags.sync,
+        });
+        if (pushDefaults.fromLocal.length > 0 && this.localProfile) {
+            const relativePath = relative(process.cwd(), this.localProfile.path) || basename(this.localProfile.path);
+            this.log(formatWorkspacePushDefaultsBanner(pushDefaults.fromLocal, relativePath));
+        }
         const target = {
             buildDryRunUrl: (params) => `${baseUrl}/multidoc/dry-run?${params.toString()}`,
             buildPushUrl: (params) => `${baseUrl}/multidoc?${params.toString()}`,
@@ -178,14 +221,19 @@ Full sync including knowledge files; removes server objects not present locally
             'dry-run': flags['dry-run'],
             env: flags.env,
             exclude: flags.exclude,
+            fast: pushDefaults.fast,
             force: flags.force,
             guids: flags.guids,
             include: flags.include,
             records: flags.records,
+            refresh: flags.refresh,
             sync: flags.sync,
             transaction: flags.transaction,
             truncate: flags.truncate,
             verbose: flags.verbose,
+            writeback: pushDefaults.writeback,
+            writebackDiff: flags['writeback-diff'],
+            writebackObjectLimit: this.localProfile?.config.writeback_object_limit,
         };
         await executePush({
             accessToken: profile.access_token,
@@ -196,6 +244,11 @@ Full sync including knowledge files; removes server objects not present locally
                 listUrl: () => `${baseUrl}/knowledge/sync`,
                 rootDir: inputDir,
             },
+            syncTarget: {
+                instanceOrigin: profile.instance_origin,
+                kind: 'workspace',
+                workspace: workspaceId,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
     }

package/dist/utils/export-compare.d.ts

@@ -0,0 +1,52 @@
+import { type ParsedDocument } from './document-parser.js';
+export declare const ITEMS_BLOCK_REGEX: RegExp;
+/**
+ * Split a GET /multidoc response into parsed documents, skipping empty or invalid segments.
+ */
+export declare function parseExportDocuments(multidoc: string): ParsedDocument[];
+/**
+ * Reinsert a local table `items = [...]` block when the server export omitted records.
+ * If the export already has an items block, the server copy wins.
+ */
+export declare function preserveLocalTableRecords(localContent: string, serverContent: string): string;
+export interface DocumentIndex {
+    byGuid: Map<string, string>;
+    byKey: Map<string, string>;
+    byKeyLower: Map<string, string>;
+}
+/**
+ * Index local files by document key (and GUID) so an export document can be paired
+ * with the file it belongs to. Ambiguous case-insensitive keys are marked empty
+ * rather than guessed.
+ */
+export declare function indexLocalDocuments(files: Map<string, string>, localContents: Map<string, string>): DocumentIndex;
+export declare function resolveMatchedPath(doc: ParsedDocument, index: DocumentIndex): string | undefined;
+export declare function selectWritebacks(exported: ParsedDocument[], pushedFiles: Map<string, string>, localContents: Map<string, string>, options: {
+    includeRecords: boolean;
+}): Array<{
+    content: string;
+    filePath: string;
+}>;
+export interface ExportCompareResult {
+    candidates: Array<{
+        content: string;
+        filePath: string;
+        relPath: string;
+    }>;
+    identical: Array<{
+        content: string;
+        filePath: string;
+        relPath: string;
+    }>;
+    serverOnly: ParsedDocument[];
+    unmatchedLocal: Array<{
+        content: string;
+        filePath: string;
+        relPath: string;
+    }>;
+}
+export declare function compareLocalToExport(localEntries: Array<{
+    content: string;
+    filePath: string;
+    relPath: string;
+}>, exported: ParsedDocument[]): ExportCompareResult;

package/dist/utils/export-compare.js

@@ -0,0 +1,134 @@
+import { buildDocumentKey, parseDocument } from './document-parser.js';
+export const ITEMS_BLOCK_REGEX = /^([ \t]*)items\s*=\s*\[[\s\S]*?\n\1\]/m;
+/**
+ * Split a GET /multidoc response into parsed documents, skipping empty or invalid segments.
+ */
+export function parseExportDocuments(multidoc) {
+    const documents = [];
+    for (const raw of multidoc.split('\n---\n')) {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            continue;
+        const parsed = parseDocument(trimmed);
+        if (parsed)
+            documents.push(parsed);
+    }
+    return documents;
+}
+/**
+ * Reinsert a local table `items = [...]` block when the server export omitted records.
+ * If the export already has an items block, the server copy wins.
+ */
+export function preserveLocalTableRecords(localContent, serverContent) {
+    if (ITEMS_BLOCK_REGEX.test(serverContent)) {
+        return serverContent;
+    }
+    const localMatch = localContent.match(ITEMS_BLOCK_REGEX);
+    if (!localMatch) {
+        return serverContent;
+    }
+    const lines = serverContent.split('\n');
+    let insertIndex = -1;
+    for (let i = lines.length - 1; i >= 0; i--) {
+        if (lines[i].trim() === '}') {
+            insertIndex = i;
+            break;
+        }
+    }
+    if (insertIndex === -1) {
+        return serverContent;
+    }
+    lines.splice(insertIndex, 0, ...localMatch[0].split('\n'));
+    return lines.join('\n');
+}
+/**
+ * Index local files by document key (and GUID) so an export document can be paired
+ * with the file it belongs to. Ambiguous case-insensitive keys are marked empty
+ * rather than guessed.
+ */
+export function indexLocalDocuments(files, localContents) {
+    const byKey = new Map(files);
+    const byKeyLower = new Map();
+    for (const [key, filePath] of files) {
+        const lower = key.toLowerCase();
+        if (byKeyLower.has(lower) && byKeyLower.get(lower) !== filePath) {
+            byKeyLower.set(lower, '');
+        }
+        else if (!byKeyLower.has(lower)) {
+            byKeyLower.set(lower, filePath);
+        }
+    }
+    const byGuid = new Map();
+    for (const [filePath, local] of localContents) {
+        const parsed = parseDocument(local);
+        if (parsed?.guid)
+            byGuid.set(parsed.guid, filePath);
+    }
+    return { byGuid, byKey, byKeyLower };
+}
+export function resolveMatchedPath(doc, index) {
+    const key = buildDocumentKey(doc.type, doc.name, doc.verb, doc.apiGroup);
+    return index.byKey.get(key) || index.byKeyLower.get(key.toLowerCase()) || (doc.guid ? index.byGuid.get(doc.guid) : undefined);
+}
+export function selectWritebacks(exported, pushedFiles, localContents, options) {
+    const result = [];
+    const index = indexLocalDocuments(pushedFiles, localContents);
+    for (const doc of exported) {
+        const filePath = resolveMatchedPath(doc, index);
+        if (!filePath)
+            continue;
+        const local = localContents.get(filePath) ?? '';
+        let { content } = doc;
+        if (!options.includeRecords && doc.type === 'table') {
+            content = preserveLocalTableRecords(local, content);
+        }
+        if (local.trim() === content.trim())
+            continue;
+        result.push({ content, filePath });
+    }
+    return result;
+}
+export function compareLocalToExport(localEntries, exported) {
+    const pushedFiles = new Map();
+    const localContents = new Map();
+    const byPath = new Map();
+    for (const entry of localEntries) {
+        const parsed = parseDocument(entry.content);
+        if (!parsed)
+            continue;
+        const key = buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup);
+        pushedFiles.set(key, entry.filePath);
+        localContents.set(entry.filePath, entry.content);
+        byPath.set(entry.filePath, entry);
+    }
+    const index = indexLocalDocuments(pushedFiles, localContents);
+    const matchedLocal = new Set();
+    const candidates = [];
+    const identical = [];
+    const serverOnly = [];
+    for (const doc of exported) {
+        const filePath = resolveMatchedPath(doc, index);
+        if (!filePath) {
+            serverOnly.push(doc);
+            continue;
+        }
+        matchedLocal.add(filePath);
+        const local = byPath.get(filePath);
+        if (!local)
+            continue;
+        if (local.content.trim() === doc.content.trim()) {
+            identical.push(local);
+        }
+        else {
+            candidates.push(local);
+        }
+    }
+    const unmatchedLocal = [];
+    for (const entry of localEntries) {
+        if (matchedLocal.has(entry.filePath))
+            continue;
+        unmatchedLocal.push(entry);
+        candidates.push(entry);
+    }
+    return { candidates, identical, serverOnly, unmatchedLocal };
+}

package/dist/utils/local-config.d.ts

@@ -4,9 +4,12 @@ export declare const LOCAL_PROFILE_FILENAME = "profile.yaml";
 export interface LocalProfileConfig {
     account_origin?: string;
     branch?: string;
+    fast?: boolean;
     instance_origin?: string;
     profile?: string;
     workspace?: string;
+    writeback?: boolean;
+    writeback_object_limit?: number;
 }
 /**
  * Parse the raw contents of a profile.yaml.
@@ -34,8 +37,28 @@ export declare function resolveProfileSelection(params: {
     applyLocal: boolean;
     profileName: string;
 };
+export type WorkspacePushDefaultKey = 'fast' | 'writeback';
+/**
+ * Resolve push --fast/--writeback from the explicit flag, then
+ * profile.yaml, then false. `--sync` ignores a profile.yaml `fast: true`
+ * instead of erroring; an explicit `--fast --sync` is left as-is for executePush.
+ * Used by both workspace push and sandbox push.
+ */
+export declare function resolvePushDefaults(args: {
+    flagFast?: boolean;
+    flagWriteback?: boolean;
+    localFast?: boolean;
+    localWriteback?: boolean;
+    sync: boolean;
+}): {
+    fast: boolean;
+    fromLocal: WorkspacePushDefaultKey[];
+    writeback: boolean;
+};
 /** Format the one-line banner shown when a local profile.yaml is in effect. */
 export declare function formatLocalProfileBanner(profileName: string, workspace: string | undefined, relativePath: string): string;
+/** Format the one-line banner when profile.yaml turns on workspace push flags. */
+export declare function formatWorkspacePushDefaultsBanner(fromLocal: WorkspacePushDefaultKey[], relativePath: string): string;
 /**
  * Walk up from `startDir` to the filesystem root, returning the path of the
  * first profile.yaml found, or null if none exists.

package/dist/utils/local-config.js

@@ -2,7 +2,9 @@ import * as yaml from 'js-yaml';
 import * as fs from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 export const LOCAL_PROFILE_FILENAME = 'profile.yaml';
-const RECOGNIZED_KEYS = ['profile', 'workspace', 'instance_origin', 'account_origin', 'branch'];
+const RECOGNIZED_STRING_KEYS = ['profile', 'workspace', 'instance_origin', 'account_origin', 'branch'];
+const RECOGNIZED_BOOLEAN_KEYS = ['fast', 'writeback'];
+const RECOGNIZED_NON_NEGATIVE_INTEGER_KEYS = ['writeback_object_limit'];
 /**
  * Fields that may be layered onto a resolved profile (everything except the profile pointer).
  * NOTE: `insecure` is intentionally NOT listed here — a project file must never silently
@@ -26,11 +28,28 @@ export function parseLocalProfile(raw) {
             `Tokens belong in credentials.yaml — reference a profile by name instead.`);
     }
     const config = {};
-    for (const key of RECOGNIZED_KEYS) {
+    for (const key of RECOGNIZED_STRING_KEYS) {
         if (obj[key] !== undefined && obj[key] !== null) {
             config[key] = String(obj[key]);
         }
     }
+    for (const key of RECOGNIZED_BOOLEAN_KEYS) {
+        if (obj[key] === undefined || obj[key] === null)
+            continue;
+        if (typeof obj[key] !== 'boolean') {
+            throw new TypeError(`profile.yaml: ${key} must be a boolean`);
+        }
+        config[key] = obj[key];
+    }
+    for (const key of RECOGNIZED_NON_NEGATIVE_INTEGER_KEYS) {
+        if (obj[key] === undefined || obj[key] === null)
+            continue;
+        const value = obj[key];
+        if (typeof value !== 'number' || !Number.isInteger(value) || value < 0) {
+            throw new TypeError(`profile.yaml: ${key} must be a non-negative integer`);
+        }
+        config[key] = value;
+    }
     if (Object.keys(config).length === 0) {
         return null;
     }
@@ -63,11 +82,52 @@ export function resolveProfileSelection(params) {
     }
     return { applyLocal: false, profileName: params.defaultProfile };
 }
+/**
+ * Resolve push --fast/--writeback from the explicit flag, then
+ * profile.yaml, then false. `--sync` ignores a profile.yaml `fast: true`
+ * instead of erroring; an explicit `--fast --sync` is left as-is for executePush.
+ * Used by both workspace push and sandbox push.
+ */
+export function resolvePushDefaults(args) {
+    const fromLocal = [];
+    let fast;
+    if (args.flagFast !== undefined) {
+        fast = args.flagFast;
+    }
+    else if (args.sync) {
+        fast = false;
+    }
+    else if (args.localFast === undefined) {
+        fast = false;
+    }
+    else {
+        fast = args.localFast;
+        if (args.localFast)
+            fromLocal.push('fast');
+    }
+    let writeback;
+    if (args.flagWriteback !== undefined) {
+        writeback = args.flagWriteback;
+    }
+    else if (args.localWriteback === undefined) {
+        writeback = false;
+    }
+    else {
+        writeback = args.localWriteback;
+        if (args.localWriteback)
+            fromLocal.push('writeback');
+    }
+    return { fast, fromLocal, writeback };
+}
 /** Format the one-line banner shown when a local profile.yaml is in effect. */
 export function formatLocalProfileBanner(profileName, workspace, relativePath) {
     const workspaceClause = workspace ? ` (workspace ${workspace})` : '';
     return `Using profile '${profileName}'${workspaceClause} · ${relativePath}`;
 }
+/** Format the one-line banner when profile.yaml turns on workspace push flags. */
+export function formatWorkspacePushDefaultsBanner(fromLocal, relativePath) {
+    return `Using ${fromLocal.map((key) => `--${key}`).join(' ')} · ${relativePath}`;
+}
 /**
  * Walk up from `startDir` to the filesystem root, returning the path of the
  * first profile.yaml found, or null if none exists.

package/dist/utils/multidoc-push.d.ts

@@ -1,18 +1,24 @@
 import { Command } from '@oclif/core';
 import { type BadIndex, type BadReference } from './reference-checker.js';
+import { type SyncFileEntry, type SyncTargetIdentity, type SyncTargetState } from './sync-state.js';
 export interface PushFlags {
     delete: boolean;
     'dry-run': boolean;
     env: boolean;
     exclude?: string[];
+    fast?: boolean;
     force: boolean;
     guids: boolean;
     include?: string[];
     records: boolean;
+    refresh?: boolean;
     sync: boolean;
     transaction: boolean;
     truncate: boolean;
     verbose: boolean;
+    writeback?: boolean;
+    writebackDiff?: string;
+    writebackObjectLimit?: number;
 }
 export interface PushTarget {
     /** Build the dry-run URL. Return null if dry-run is not supported for this target. */
@@ -47,6 +53,15 @@ export interface KnowledgeConfig {
     /** Root directory containing the `knowledge/` folder. */
     rootDir: string;
 }
+export type PushSyncTarget = {
+    instanceOrigin: string;
+    kind: 'sandbox';
+    markerDir: string;
+} | {
+    instanceOrigin: string;
+    kind: 'workspace';
+    workspace: string;
+};
 export interface PushContext {
     accessToken: string;
     branch: string;
@@ -54,8 +69,16 @@ export interface PushContext {
     inputDir: string;
     /** Optional knowledge sync config. Only workspace push sets this. */
     knowledge?: KnowledgeConfig;
+    /** Optional sync-record target. Workspace and sandbox push set this when they want a record. */
+    syncTarget?: PushSyncTarget;
     verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
 }
+/** The fetch fields writeback reads. */
+export interface WritebackHttpResponse {
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+}
 /**
  * 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.
@@ -144,10 +167,12 @@ export declare function deletesHittingFilteredOut(operations: Array<{
     relPath: string;
     type: string;
 }>;
+export declare function pathMatchesFilters(relPath: string, inputDir: string, include: string[] | undefined, exclude: string[] | undefined): boolean;
 /**
- * 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 declare function readDocuments(files: string[]): Array<{
+export declare function readDocuments(files: string[], raw?: Map<string, string>): Array<{
     content: string;
     filePath: string;
 }>;
@@ -193,6 +218,45 @@ export declare function confirm(message: string): Promise<boolean>;
  * Shared by both sandbox:push and workspace:push commands.
  */
 export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<void>;
+export interface WritebackResult {
+    elapsedMs: number;
+    /** Object ids resolved by per-object writeback, keyed by relative path. */
+    ids: Record<string, SyncFileEntry>;
+    /** The exact bytes written to each rewritten file. */
+    written: Array<{
+        content: string;
+        filePath: string;
+    }>;
+}
+export declare function writeBackFormattedDocuments(args: {
+    accessToken: string;
+    branch: string;
+    command: Command;
+    includeEnv: boolean;
+    includeRecords: boolean;
+    inputDir?: string;
+    isLiveBranch?: boolean;
+    /**
+     * The bytes each file held when it was pushed (after GUID sync). A file whose disk content
+     * no longer matches was edited during the push, so writeback leaves it alone.
+     */
+    pushedBytes?: Map<string, string>;
+    pushedEntries: Array<{
+        content: string;
+        filePath: string;
+    }>;
+    resolvedTarget?: null | SyncTargetIdentity;
+    syncState?: null | SyncTargetState;
+    target: PushTarget;
+    verbose: boolean;
+    verboseFetch: (url: string, options: {
+        headers?: Record<string, string>;
+        method?: string;
+    }, verbose: boolean, authToken?: string) => Promise<WritebackHttpResponse>;
+    workspaceId?: string;
+    writebackDiff?: string;
+    writebackObjectLimit?: number;
+}): Promise<WritebackResult>;
 /**
  * Turn a thrown fetch/network error into an actionable message.
  *
@@ -207,3 +271,4 @@ export declare function executePush(ctx: PushContext, target: PushTarget, flags:
  * signal of a server-side or proxy timeout rather than a local network blip.
  */
 export declare function describeNetworkError(error: unknown, url: string, elapsedMs?: number): string;
+export { parseExportDocuments, preserveLocalTableRecords, selectWritebacks } from './export-compare.js';