@xano/cli 1.3.3 → 1.3.5-beta.0

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 { Command, Errors } 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. */
@@ -21,6 +27,11 @@ export interface PushTarget {
     buildPushUrl: (queryParams: URLSearchParams) => string;
     /** CLI version string */
     cliVersion: string;
+    /**
+     * Guidance for a refusal this target recognises, given the HTTP status and the server's payload.
+     * A preview or import refused that way stops with the message and this guidance appended.
+     */
+    explainRefusal?: (status: number, payload: unknown) => string | undefined;
     /** Instance origin URL (e.g., "https://x123-abcd-1234.xano.io") */
     instanceOrigin: string;
     /** Human-readable label for log messages (e.g., "sandbox environment", "workspace 40") */
@@ -47,6 +58,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 +74,64 @@ export interface PushContext {
     inputDir: string;
     /** Optional knowledge sync config. Only workspace push sets this. */
     knowledge?: KnowledgeConfig;
+    /** Where progress and diagnostics go; defaults to the command's stdout. */
+    log?: (message: string) => void;
+    /** 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>;
+}
+export interface DryRunSummary {
+    created: number;
+    deleted: number;
+    truncated: number;
+    unchanged: number;
+    updated: number;
+}
+export interface DryRunOperation {
+    action: string;
+    details: string;
+    name: string;
+    reason?: string;
+    type: string;
+}
+export interface DryRunResult {
+    operations: DryRunOperation[];
+    /** True when the sandbox currently holds a different source workspace than the one being pushed. */
+    source_workspace_mismatch?: boolean;
+    summary: Record<string, DryRunSummary>;
+    workspace_name?: string;
+}
+/** What a push did, for the calling command to report. */
+export interface PushResult {
+    knowledge: {
+        deleted: number;
+        imported: number;
+    };
+    preview: DryRunResult | null;
+    /** The multidoc import's response body; absent when no multidoc was imported. */
+    response?: Record<string, unknown>;
+    /** The documents the multidoc import carried. */
+    sent: Array<{
+        content: string;
+        filePath: string;
+    }>;
+    /** Why the push stopped before writing anything, when it did. */
+    stopped?: 'blocked' | 'cancelled' | 'dry-run' | 'no-changes';
+}
+/**
+ * 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 declare class FailedAfterImportError extends Errors.CLIError {
+    readonly imported: PushResult;
+    constructor(message: string, imported: PushResult);
+}
 /**
  * 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 +220,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;
 }>;
@@ -192,7 +270,48 @@ export declare function confirm(message: string): Promise<boolean>;
  * Execute a multidoc push with preview, validation, partial mode, and GUID sync.
  * Shared by both sandbox:push and workspace:push commands.
  */
-export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<void>;
+export declare function executePush(ctx: PushContext, target: PushTarget, flags: PushFlags): Promise<PushResult>;
+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;
+    /** Where progress goes; defaults to the command's stdout. */
+    log?: (message: string) => void;
+    /**
+     * 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 +326,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';