@xano/cli 1.0.6-beta.15 → 1.0.6-beta.17

package/README.md

@@ -323,6 +323,7 @@ xano function run <name> --data email=jo@x.com --data age:=30 --data active:=tru
 xano function run <name> --json @payload.json --data env=staging   # base payload + override
 echo '{"email":"jo@x.com"}' | xano function run <name> --stdin -o json | jq .result
 xano function run <name> --branch dev --logs            # run on a branch, show execution logs
+xano function run <name> --datasource test              # run against the 'test' data source
 ```
 
 Input flexibility for `function run` (assembled into one JSON `input` object):
@@ -335,6 +336,11 @@ Input flexibility for `function run` (assembled into one JSON `input` object):
 | `--json '<inline>'` / `--json @file.json` / `--json -` | a base JSON object (stdin with `-`) |
 | `--stdin` | read the JSON object from stdin (same as `--json -`) |
 
+`--datasource <label>` runs the function against a non-live data source by sending the
+`X-Data-Source` header, so table reads and writes hit that data source's tables. Omit it
+to run against `live`; an unknown label is rejected by the server with
+`Invalid data source.`
+
 Merge order is JSON base first, then `--data` overrides. Missing required inputs are
 prompted for on an interactive terminal; in a non-TTY (CI) context the command fails
 listing them. Output defaults to the raw `result` (`-o json`); the exit code is non-zero

package/dist/commands/function/run/index.d.ts

@@ -8,6 +8,7 @@ export default class FunctionRun extends BaseCommand {
     static flags: {
         branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         data: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        datasource: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         json: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         logs: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/function/run/index.js

@@ -17,6 +17,8 @@ export default class FunctionRun extends BaseCommand {
         `$ xano function:run calcScore --json @payload.json --data env=staging`,
         `$ echo '{"email":"jo@x.com"}' | xano function:run calcScore --stdin -o json | jq .result`,
         `$ xano function:run calcScore --branch dev --logs`,
+        `$ xano function:run calcScore --datasource test
+# Runs against the 'test' data source instead of 'live'`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
@@ -30,6 +32,10 @@ export default class FunctionRun extends BaseCommand {
             multiple: true,
             required: false,
         }),
+        datasource: Flags.string({
+            description: 'Data source to run against, e.g. test (defaults to live)',
+            required: false,
+        }),
         json: Flags.string({
             description: "Input as a JSON object: inline, @file.json, or '-' for stdin",
             exclusive: ['stdin'],
@@ -106,13 +112,21 @@ export default class FunctionRun extends BaseCommand {
         const body = { input, name: functionName };
         if (branch)
             body.branch = branch;
+        const headers = {
+            'accept': 'application/json',
+            'Authorization': `Bearer ${profile.access_token}`,
+            'Content-Type': 'application/json',
+        };
+        // The Metadata API resolves the workspace's tables against the data source
+        // named by X-Data-Source (defaulting to `live`), so the run reads and writes
+        // the same tables a request carrying that header would. An unknown label is
+        // rejected server-side with "Invalid data source."
+        const dataSource = flags.datasource?.trim();
+        if (dataSource)
+            headers['X-Data-Source'] = dataSource;
         const response = await this.verboseFetch(apiUrl, {
             body: JSON.stringify(body),
-            headers: {
-                'accept': 'application/json',
-                'Authorization': `Bearer ${profile.access_token}`,
-                'Content-Type': 'application/json',
-            },
+            headers,
             method: 'POST',
         }, flags.verbose, profile.access_token);
         if (!response.ok) {

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

@@ -89,7 +89,61 @@ export declare function collectFiles(dir: string): string[];
  * 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 declare function normalizeFilterPattern(pattern: string, inputDir: string): string;
 export declare function applyFilters(files: string[], inputDir: string, include: string[] | undefined, exclude: string[] | undefined, log: (msg: string) => void): string[];
+/** A document the filter removed from the push, and therefore must protect. */
+export interface FilteredOutDocument {
+    guid?: string;
+    key: string;
+    name: string;
+    relPath: string;
+    type: string;
+}
+/**
+ * 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 declare function describeFilteredOut(allFiles: string[], keptFiles: string[], inputDir: string): FilteredOutDocument[];
+/**
+ * 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 declare function deletesHittingFilteredOut(operations: Array<{
+    action: string;
+    name: string;
+    type: string;
+}>, filteredOut: FilteredOutDocument[]): Array<{
+    name: string;
+    relPath: string;
+    type: string;
+}>;
 /**
  * Read .xs files into document entries, skipping empty files.
  */

package/dist/utils/multidoc-push.js

@@ -66,30 +66,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.
  */
@@ -174,7 +295,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;
@@ -238,6 +359,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) {
@@ -300,6 +432,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.
@@ -341,6 +479,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,
@@ -398,6 +562,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
@@ -504,6 +670,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',
@@ -535,7 +712,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) {
@@ -773,6 +989,7 @@ export async function executePush(ctx, target, flags) {
                     }
                 }
                 let updatedCount = 0;
+                let canonicalCount = 0;
                 for (const entry of guidMap) {
                     if (!entry.guid)
                         continue;
@@ -799,10 +1016,23 @@ 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;
         }