@xano/cli 0.0.95-beta.10 → 0.0.95-beta.11

package/dist/base-command.d.ts

@@ -63,6 +63,11 @@ export default abstract class BaseCommand extends Command {
         profile: ProfileConfig;
         profileName: string;
     };
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    protected parseApiError(response: Response, fallbackPrefix: string): Promise<string>;
     /**
      * Make an HTTP request with optional verbose logging.
      * Use this for all Metadata API calls to support the --verbose flag.

package/dist/base-command.js

@@ -117,8 +117,8 @@ export default class BaseCommand extends Command {
             method: 'GET',
         }, verbose, profile.access_token);
         if (!response.ok) {
-            const errorText = await response.text();
-            this.error(`Failed to get sandbox environment: ${response.status} ${response.statusText}\n${errorText}`);
+            const message = await this.parseApiError(response, 'Failed to get sandbox environment');
+            this.error(message);
         }
         return (await response.json());
     }
@@ -140,6 +140,30 @@ export default class BaseCommand extends Command {
         }
         return { profile, profileName };
     }
+    /**
+     * Parse an API error response and return a clean error message.
+     * Extracts the message from JSON responses and adds context for common errors.
+     */
+    async parseApiError(response, fallbackPrefix) {
+        const errorText = await response.text();
+        let message = `${fallbackPrefix} (${response.status})`;
+        try {
+            const errorJson = JSON.parse(errorText);
+            if (errorJson.message) {
+                message = errorJson.message;
+            }
+        }
+        catch {
+            if (errorText) {
+                message += `\n${errorText}`;
+            }
+        }
+        // Provide guidance when sandbox access is denied (free plan restriction)
+        if (response.status === 500 && message === 'Access Denied.') {
+            message = 'Sandbox is not available on the Free plan. Upgrade your plan to use sandbox features.';
+        }
+        return message;
+    }
     /**
      * Make an HTTP request with optional verbose logging.
      * Use this for all Metadata API calls to support the --verbose flag.

package/dist/commands/sandbox/env/delete/index.js

@@ -52,8 +52,8 @@ Environment variable 'DATABASE_URL' deleted
                 method: 'DELETE',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             if (flags.output === 'json') {
                 this.log(JSON.stringify({ deleted: true, env_name: envName }, null, 2));

package/dist/commands/sandbox/env/get/index.js

@@ -37,8 +37,8 @@ postgres://localhost:5432/mydb
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const envVar = (await response.json());
             if (flags.output === 'json') {

package/dist/commands/sandbox/env/get_all/index.js

@@ -46,8 +46,8 @@ Environment variables saved to env_<tenant>.yaml
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const envMap = (await response.json());
             if (flags.output === 'json') {

package/dist/commands/sandbox/env/list/index.js

@@ -33,8 +33,8 @@ Environment variables for sandbox environment:
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const data = (await response.json());
             if (flags.output === 'json') {

package/dist/commands/sandbox/env/set/index.js

@@ -49,8 +49,8 @@ Environment variable 'DATABASE_URL' set
                 method: 'PATCH',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             if (flags.output === 'json') {
                 const result = await response.json();

package/dist/commands/sandbox/env/set_all/index.js

@@ -57,8 +57,8 @@ Reads from env_<tenant>.yaml
                 method: 'PUT',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             if (flags.output === 'json') {
                 const result = await response.json();

package/dist/commands/sandbox/license/get/index.js

@@ -45,8 +45,8 @@ License saved to license_<tenant>.yaml
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const license = await response.json();
             const licenseContent = typeof license === 'string' ? license : JSON.stringify(license, null, 2);

package/dist/commands/sandbox/license/set/index.js

@@ -66,8 +66,8 @@ Reads from license_<tenant>.yaml
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const result = await response.json();
             if (flags.output === 'json') {

package/dist/commands/sandbox/pull/index.js

@@ -55,8 +55,8 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             responseText = await response.text();
         }

package/dist/commands/sandbox/push/index.d.ts

@@ -15,4 +15,5 @@ export default class SandboxPush extends BaseCommand {
     };
     run(): Promise<void>;
     private collectFiles;
+    private renderBadReferences;
 }

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

@@ -1,8 +1,9 @@
-import { Args, Flags } from '@oclif/core';
-import BaseCommand from '../../../base-command.js';
-import { findFilesWithGuid } from '../../../utils/document-parser.js';
+import { Args, Flags, ux } from '@oclif/core';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
+import BaseCommand from '../../../base-command.js';
+import { findFilesWithGuid } from '../../../utils/document-parser.js';
+import { checkReferences } from '../../../utils/reference-checker.js';
 export default class SandboxPush extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -66,6 +67,11 @@ Pushed 42 documents to sandbox environment from ./my-workspace
         if (documentEntries.length === 0) {
             this.error(`All .xs files in ${args.directory} are empty`);
         }
+        // Check for bad cross-references within the local file set
+        const badRefs = checkReferences(documentEntries);
+        if (badRefs.length > 0) {
+            this.renderBadReferences(badRefs);
+        }
         const multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         const queryParams = new URLSearchParams({
             env: flags.env.toString(),
@@ -98,6 +104,10 @@ Pushed 42 documents to sandbox environment from ./my-workspace
                 catch {
                     errorMessage += `\n${errorText}`;
                 }
+                // Provide guidance when sandbox access is denied (free plan restriction)
+                if (response.status === 500 && errorMessage.includes('Access Denied')) {
+                    this.error('Sandbox is not available on the Free plan. Upgrade your plan to use sandbox features.');
+                }
                 const guidMatch = errorMessage.match(/Duplicate \w+ guid: (\S+)/);
                 if (guidMatch) {
                     const dupeFiles = findFilesWithGuid(documentEntries, guidMatch[1]);
@@ -138,4 +148,17 @@ Pushed 42 documents to sandbox environment from ./my-workspace
         }
         return files.sort();
     }
+    renderBadReferences(badRefs) {
+        this.log('');
+        this.log(ux.colorize('yellow', ux.colorize('bold', '=== Unresolved References ===')));
+        this.log('');
+        this.log(ux.colorize('yellow', "The following references point to objects that don't exist in this push or on the server."));
+        this.log(ux.colorize('yellow', 'These will become placeholder statements after import.'));
+        this.log('');
+        for (const ref of badRefs) {
+            this.log(`  ${ux.colorize('yellow', 'WARNING'.padEnd(16))} ${ref.sourceType.padEnd(18)} ${ref.source}`);
+            this.log(`  ${' '.repeat(16)} ${' '.repeat(18)} ${ux.colorize('dim', `${ref.statementType} → ${ref.targetType} "${ref.target}" does not exist`)}`);
+        }
+        this.log('');
+    }
 }

package/dist/commands/sandbox/reset/index.js

@@ -39,8 +39,8 @@ Sandbox environment has been reset.
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             this.log('Sandbox environment has been reset.');
         }

package/dist/commands/sandbox/review/index.js

@@ -40,8 +40,8 @@ Review session started!
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const result = (await response.json());
             if (!result._ti) {

package/dist/commands/sandbox/unit_test/list/index.js

@@ -48,8 +48,8 @@ Unit tests:
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const data = (await response.json());
             let tests;

package/dist/commands/sandbox/unit_test/run/index.js

@@ -42,8 +42,8 @@ Result: PASS
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const result = (await response.json());
             if (flags.output === 'json') {

package/dist/commands/sandbox/workflow_test/delete/index.js

@@ -37,8 +37,8 @@ Deleted workflow test 42
                 method: 'DELETE',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             if (flags.output === 'json') {
                 this.log(JSON.stringify({ deleted: true, workflow_test_id: args.workflow_test_id }, null, 2));

package/dist/commands/sandbox/workflow_test/get/index.js

@@ -32,8 +32,8 @@ export default class SandboxWorkflowTestGet extends BaseCommand {
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const test = await response.json();
             if (flags.output === 'json') {

package/dist/commands/sandbox/workflow_test/list/index.js

@@ -41,8 +41,8 @@ Workflow tests:
                 method: 'GET',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const data = (await response.json());
             let tests;

package/dist/commands/sandbox/workflow_test/run/index.js

@@ -42,8 +42,8 @@ Result: PASS (0.25s)
                 method: 'POST',
             }, flags.verbose, profile.access_token);
             if (!response.ok) {
-                const errorText = await response.text();
-                this.error(`API request failed with status ${response.status}: ${response.statusText}\n${errorText}`);
+                const message = await this.parseApiError(response, 'API request failed');
+                this.error(message);
             }
             const result = (await response.json());
             if (flags.output === 'json') {

package/dist/commands/workspace/push/index.d.ts

@@ -30,5 +30,6 @@ export default class Push extends BaseCommand {
      * type subdirectory name then filename for deterministic ordering.
      */
     private collectFiles;
+    private renderBadReferences;
     private loadCredentials;
 }

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

@@ -6,6 +6,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import BaseCommand from '../../../base-command.js';
 import { buildDocumentKey, findFilesWithGuid, parseDocument } from '../../../utils/document-parser.js';
+import { checkReferences } from '../../../utils/reference-checker.js';
 export default class Push extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -250,10 +251,10 @@ Push functions but exclude test files
         let dryRunPreview = null;
         if (flags['dry-run'] || !flags.force) {
             const dryRunParams = new URLSearchParams(queryParams);
-            // Request delete info in dry-run so we can show remote-only items (skip for partial)
-            if (!isPartial) {
-                dryRunParams.set('delete', 'true');
-            }
+            // Always request delete info in dry-run so we can:
+            // 1. Show remote-only items (in --sync mode)
+            // 2. Know what exists on the server (to filter unresolved reference warnings)
+            dryRunParams.set('delete', 'true');
             const dryRunUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/multidoc/dry-run?${dryRunParams.toString()}`;
             try {
                 const dryRunResponse = await this.verboseFetch(dryRunUrl, {
@@ -325,6 +326,11 @@ Push functions but exclude test files
                     // Check if the server returned a valid dry-run response
                     if (preview && preview.summary) {
                         this.renderPreview(preview, shouldDelete, workspaceId, flags.verbose, isPartial);
+                        // Check for bad cross-references, using dry-run operations to avoid false positives
+                        const badRefs = checkReferences(documentEntries, preview.operations);
+                        if (badRefs.length > 0) {
+                            this.renderBadReferences(badRefs);
+                        }
                         // Check for critical errors that must block the push
                         const criticalOps = preview.operations.filter((op) => op.details?.includes('exception:') || op.details?.includes('mvp:placeholder'));
                         if (criticalOps.length > 0) {
@@ -443,6 +449,14 @@ Push functions but exclude test files
                 }
             }
         }
+        // Show bad references in force mode (preview mode shows them inline)
+        if (flags.force) {
+            const badRefs = checkReferences(documentEntries);
+            if (badRefs.length > 0) {
+                this.log('');
+                this.renderBadReferences(badRefs);
+            }
+        }
         // For partial pushes, filter to only changed documents
         if (isPartial && dryRunPreview) {
             const changedKeys = new Set(dryRunPreview.operations
@@ -737,6 +751,18 @@ Push functions but exclude test files
         }
         return files.sort();
     }
+    renderBadReferences(badRefs) {
+        this.log(ux.colorize('yellow', ux.colorize('bold', '=== Unresolved References ===')));
+        this.log('');
+        this.log(ux.colorize('yellow', "The following references point to objects that don't exist in this push or on the server."));
+        this.log(ux.colorize('yellow', 'These will become placeholder statements after import.'));
+        this.log('');
+        for (const ref of badRefs) {
+            this.log(`  ${ux.colorize('yellow', 'WARNING'.padEnd(16))} ${ref.sourceType.padEnd(18)} ${ref.source}`);
+            this.log(`  ${' '.repeat(16)} ${' '.repeat(18)} ${ux.colorize('dim', `${ref.statementType} → ${ref.targetType} "${ref.target}" does not exist`)}`);
+        }
+        this.log('');
+    }
     loadCredentials() {
         const configDir = path.join(os.homedir(), '.xano');
         const credentialsPath = path.join(configDir, 'credentials.yaml');

package/dist/utils/reference-checker.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A reference from one document to another (e.g., function.run "bad" references function "bad").
+ */
+export interface BadReference {
+    /** Name of the source document containing the reference */
+    source: string;
+    /** Type of the source document (e.g., "function") */
+    sourceType: string;
+    /** The statement type that creates the reference (e.g., "function.run") */
+    statementType: string;
+    /** The referenced name that doesn't exist */
+    target: string;
+    /** The target type being referenced (e.g., "function") */
+    targetType: string;
+}
+/**
+ * Build a registry of all defined object names from parsed documents.
+ * Returns a Map of type → Set of names.
+ */
+export declare function buildRegistry(documents: Array<{
+    content: string;
+}>): Map<string, Set<string>>;
+/**
+ * Build a registry of server-known object names from dry-run operations.
+ * Any object that appears in the dry-run (create, update, unchanged, delete) exists
+ * either locally or on the server.
+ */
+export declare function buildServerRegistry(operations: Array<{
+    name: string;
+    type: string;
+}>): Map<string, Set<string>>;
+/**
+ * Check all documents for cross-references that point to names not in the registry.
+ *
+ * When serverOperations is provided (from dry-run), references are checked against
+ * both local files AND server-known objects, eliminating false positives for objects
+ * that exist on the server but aren't in the push set.
+ */
+export declare function checkReferences(documents: Array<{
+    content: string;
+    filePath: string;
+}>, serverOperations?: Array<{
+    name: string;
+    type: string;
+}>): BadReference[];

package/dist/utils/reference-checker.js

@@ -0,0 +1,137 @@
+import { parseDocument } from './document-parser.js';
+/**
+ * All known cross-reference patterns in XanoScript.
+ *
+ * Each pattern matches a statement keyword followed by a quoted or unquoted name.
+ * The first capture group extracts the name (stripping quotes if present).
+ */
+const REFERENCE_PATTERNS = [
+    { keyword: 'function.run', regex: /^\s*function\.run\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'function' },
+    { keyword: 'function.call', regex: /^\s*function\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'function' },
+    { keyword: 'addon.call', regex: /^\s*addon\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'addon' },
+    { keyword: 'task.call', regex: /^\s*task\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'task' },
+    { keyword: 'tool.call', regex: /^\s*tool\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'tool' },
+    { keyword: 'middleware.call', regex: /^\s*middleware\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'middleware' },
+    { keyword: 'ai.agent.run', regex: /^\s*ai\.agent\.run\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'agent' },
+    { keyword: 'trigger.call', regex: /^\s*trigger\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'trigger' },
+    { keyword: 'action.call', regex: /^\s*action\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm, targetType: 'action' },
+    {
+        keyword: 'workflow_test.call',
+        regex: /^\s*workflow_test\.call\s+("(?:[^"\\]|\\.)*"|[^\s{]+)/gm,
+        targetType: 'workflow_test',
+    },
+];
+/**
+ * Strip surrounding quotes from a name if present.
+ */
+function stripQuotes(name) {
+    if (name.startsWith('"') && name.endsWith('"')) {
+        return name.slice(1, -1);
+    }
+    return name;
+}
+/**
+ * Map from XanoScript document types to the canonical type used in the registry.
+ * Some types are aliases (agent, mcp_server → toolset bucket, but referenced as "agent").
+ */
+/* eslint-disable camelcase */
+const TYPE_ALIASES = {
+    agent: 'agent',
+    mcp_server: 'agent',
+    toolset: 'agent',
+};
+/* eslint-enable camelcase */
+/**
+ * Normalize a document type to its canonical registry type.
+ */
+function normalizeType(type) {
+    return TYPE_ALIASES[type] ?? type;
+}
+/**
+ * Build a registry of all defined object names from parsed documents.
+ * Returns a Map of type → Set of names.
+ */
+export function buildRegistry(documents) {
+    const registry = new Map();
+    for (const doc of documents) {
+        const parsed = parseDocument(doc.content);
+        if (!parsed)
+            continue;
+        const type = normalizeType(parsed.type);
+        if (!registry.has(type)) {
+            registry.set(type, new Set());
+        }
+        registry.get(type).add(parsed.name);
+    }
+    return registry;
+}
+/**
+ * Build a registry of server-known object names from dry-run operations.
+ * Any object that appears in the dry-run (create, update, unchanged, delete) exists
+ * either locally or on the server.
+ */
+export function buildServerRegistry(operations) {
+    const registry = new Map();
+    for (const op of operations) {
+        const type = normalizeType(op.type);
+        if (!registry.has(type)) {
+            registry.set(type, new Set());
+        }
+        // Operation names for queries include the verb (e.g., "path/{id} DELETE")
+        // but references use just the name, so strip the verb suffix
+        const name = op.name.replace(/\s+(?:GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)$/, '');
+        registry.get(type).add(name);
+    }
+    return registry;
+}
+/**
+ * Check all documents for cross-references that point to names not in the registry.
+ *
+ * When serverOperations is provided (from dry-run), references are checked against
+ * both local files AND server-known objects, eliminating false positives for objects
+ * that exist on the server but aren't in the push set.
+ */
+export function checkReferences(documents, serverOperations) {
+    const registry = buildRegistry(documents);
+    // Merge server-known names into the registry
+    if (serverOperations) {
+        const serverRegistry = buildServerRegistry(serverOperations);
+        for (const [type, names] of serverRegistry) {
+            if (!registry.has(type)) {
+                registry.set(type, new Set());
+            }
+            for (const name of names) {
+                registry.get(type).add(name);
+            }
+        }
+    }
+    const badRefs = [];
+    for (const doc of documents) {
+        const parsed = parseDocument(doc.content);
+        if (!parsed)
+            continue;
+        for (const pattern of REFERENCE_PATTERNS) {
+            // Reset regex state for each document
+            pattern.regex.lastIndex = 0;
+            let match;
+            while ((match = pattern.regex.exec(doc.content)) !== null) {
+                const rawName = stripQuotes(match[1]);
+                // Skip empty names (e.g., action.call "" is valid for integration actions)
+                if (!rawName)
+                    continue;
+                const { targetType } = pattern;
+                const knownNames = registry.get(targetType);
+                if (!knownNames || !knownNames.has(rawName)) {
+                    badRefs.push({
+                        source: parsed.name,
+                        sourceType: parsed.type,
+                        statementType: pattern.keyword,
+                        target: rawName,
+                        targetType,
+                    });
+                }
+            }
+        }
+    }
+    return badRefs;
+}