@xano/cli 1.0.4 → 1.0.6-beta.0

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

@@ -0,0 +1,248 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import snakeCase from 'lodash.snakecase';
+import BaseCommand from '../../../base-command.js';
+import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+export default class EphemeralPull extends BaseCommand {
+    static description = 'Pull an ephemeral tenant multidoc from the Xano Metadata API and split into individual files';
+    static examples = [
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1
+Pulled 42 documents from tenant e4f2-9ab1-xyz1 to current directory
+`,
+        `$ xano ephemeral pull -d ./my-tenant -t e4f2-9ab1-xyz1
+Pulled 42 documents from tenant e4f2-9ab1-xyz1 to ./my-tenant
+`,
+        `$ xano ephemeral pull -d ./output -t e4f2-9ab1-xyz1 -w 40
+Pulled 15 documents from tenant e4f2-9ab1-xyz1 to ./output
+`,
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --profile production --env --records
+Pulled 58 documents from tenant e4f2-9ab1-xyz1
+`,
+        `$ xano ephemeral pull -t e4f2-9ab1-xyz1 --draft`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: 'Output directory for pulled documents (defaults to current directory)',
+            required: false,
+        }),
+        draft: Flags.boolean({
+            default: false,
+            description: 'Include draft versions',
+            required: false,
+        }),
+        env: Flags.boolean({
+            default: false,
+            description: 'Include environment variables',
+            required: false,
+        }),
+        records: Flags.boolean({
+            default: false,
+            description: 'Include records',
+            required: false,
+        }),
+        tenant: Flags.string({
+            char: 't',
+            description: 'Ephemeral tenant name to pull from',
+            required: true,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EphemeralPull);
+        const { profileName, profile } = this.resolveProfile(flags);
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano ephemeral pull -t <tenant_name> -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        const tenantName = flags.tenant;
+        // Build query parameters
+        const queryParams = new URLSearchParams({
+            env: flags.env.toString(),
+            include_draft: flags.draft.toString(),
+            records: flags.records.toString(),
+        });
+        // Construct the API URL
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/multidoc?${queryParams.toString()}`;
+        // Fetch multidoc from the API
+        let responseText;
+        const requestHeaders = {
+            accept: 'application/json',
+            Authorization: `Bearer ${profile.access_token}`,
+        };
+        try {
+            const response = await this.verboseFetch(apiUrl, {
+                headers: requestHeaders,
+                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}`);
+            }
+            responseText = await response.text();
+        }
+        catch (error) {
+            if (error instanceof Error) {
+                this.error(`Failed to fetch multidoc: ${error.message}`);
+            }
+            else {
+                this.error(`Failed to fetch multidoc: ${String(error)}`);
+            }
+        }
+        // Split the response into individual documents
+        const rawDocuments = responseText.split('\n---\n');
+        // Parse each document
+        const documents = [];
+        for (const raw of rawDocuments) {
+            const trimmed = raw.trim();
+            if (!trimmed) {
+                continue;
+            }
+            const parsed = parseDocument(trimmed);
+            if (parsed) {
+                documents.push(parsed);
+            }
+        }
+        if (documents.length === 0) {
+            this.log('No documents found in response');
+            return;
+        }
+        // Resolve the output directory
+        const outputDir = path.resolve(flags.directory);
+        // Create the output directory if it doesn't exist
+        fs.mkdirSync(outputDir, { recursive: true });
+        // Resolve api_group names to unique folder names, disambiguating collisions
+        const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
+        // Track filenames per type to handle duplicates
+        const filenameCounters = new Map();
+        let writtenCount = 0;
+        for (const doc of documents) {
+            let typeDir;
+            let baseName;
+            if (doc.type === 'workspace') {
+                // workspace → workspace/{name}.xs
+                typeDir = path.join(outputDir, 'workspace');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'workspace_trigger') {
+                // workspace_trigger → workspace/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'workspace', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'error_trigger') {
+                // error_trigger → workspace/trigger/{name}.xs (singleton, colocated with workspace triggers)
+                typeDir = path.join(outputDir, 'workspace', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'agent') {
+                // agent → ai/agent/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'agent');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'mcp_server') {
+                // mcp_server → ai/mcp_server/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'mcp_server');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'tool') {
+                // tool → ai/tool/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'tool');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'agent_trigger') {
+                // agent_trigger → ai/agent/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'agent', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'mcp_server_trigger') {
+                // mcp_server_trigger → ai/mcp_server/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'ai', 'mcp_server', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'table_trigger') {
+                // table_trigger → table/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'table', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'realtime_channel') {
+                // realtime_channel → realtime/channel/{name}.xs
+                typeDir = path.join(outputDir, 'realtime', 'channel');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'realtime_trigger') {
+                // realtime_trigger → realtime/trigger/{name}.xs
+                typeDir = path.join(outputDir, 'realtime', 'trigger');
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'api_group') {
+                // api_group "test" → api/{resolved_folder}/{name}.xs
+                const groupFolder = getApiGroupFolder(doc.name);
+                typeDir = path.join(outputDir, 'api', groupFolder);
+                baseName = this.sanitizeFilename(doc.name);
+            }
+            else if (doc.type === 'query' && doc.apiGroup) {
+                // query in group "test" → api/{resolved_folder}/{query_name}.xs
+                const groupFolder = getApiGroupFolder(doc.apiGroup);
+                const nameParts = doc.name.split('/');
+                const leafName = nameParts.pop();
+                const folderParts = nameParts.map((part) => snakeCase(part));
+                typeDir = path.join(outputDir, 'api', groupFolder, ...folderParts);
+                baseName = this.sanitizeFilename(leafName);
+                if (doc.verb) {
+                    baseName = `${baseName}_${doc.verb}`;
+                }
+            }
+            else {
+                // Default: split folder path from name
+                const nameParts = doc.name.split('/');
+                const leafName = nameParts.pop();
+                const folderParts = nameParts.map((part) => snakeCase(part));
+                typeDir = path.join(outputDir, doc.type, ...folderParts);
+                baseName = this.sanitizeFilename(leafName);
+                if (doc.verb) {
+                    baseName = `${baseName}_${doc.verb}`;
+                }
+            }
+            fs.mkdirSync(typeDir, { recursive: true });
+            // Track duplicates per directory
+            const dirKey = path.relative(outputDir, typeDir);
+            if (!filenameCounters.has(dirKey)) {
+                filenameCounters.set(dirKey, new Map());
+            }
+            const typeCounters = filenameCounters.get(dirKey);
+            const count = typeCounters.get(baseName) || 0;
+            typeCounters.set(baseName, count + 1);
+            // Append numeric suffix for duplicates
+            let filename;
+            filename = count === 0 ? `${baseName}.xs` : `${baseName}_${count + 1}.xs`;
+            const filePath = path.join(typeDir, filename);
+            fs.writeFileSync(filePath, doc.content, 'utf8');
+            writtenCount++;
+        }
+        this.log(`Pulled ${writtenCount} documents from tenant ${tenantName} to ${flags.directory}`);
+    }
+    /**
+     * Sanitize a document name for use as a filename.
+     * Strips quotes, replaces spaces with underscores, and removes
+     * characters that are unsafe in filenames.
+     */
+    sanitizeFilename(name) {
+        return snakeCase(name.replaceAll('"', ''));
+    }
+}

package/dist/commands/{knowledge → ephemeral}/push/index.d.ts

@@ -1,16 +1,19 @@
 import BaseCommand from '../../../base-command.js';
-export default class KnowledgePush extends BaseCommand {
+export default class EphemeralPush extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
-        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        exclude: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
-        include: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        guids: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        records: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        tenant: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        transaction: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        truncate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -0,0 +1,143 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+import BaseCommand from '../../../base-command.js';
+import { executePush } from '../../../utils/multidoc-push.js';
+export default class EphemeralPush extends BaseCommand {
+    static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local documents to an ephemeral tenant via multidoc import. 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.';
+    static examples = [
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1
+Push from current directory (default partial mode)
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 -d ./my-workspace
+Push from a specific directory
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --sync
+Push all files to the ephemeral tenant
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --sync --delete
+Push all files and delete remote objects not included
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --dry-run
+Preview changes without pushing
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --force
+Skip preview and push immediately
+`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --records --env`,
+        `$ xano ephemeral push -t e4f2-9ab1-xyz1 --truncate`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: 'Directory containing documents to push (defaults to current directory)',
+            required: false,
+        }),
+        delete: Flags.boolean({
+            default: false,
+            description: 'Delete remote objects not included in the push (requires --sync)',
+            required: false,
+        }),
+        'dry-run': Flags.boolean({
+            default: false,
+            description: 'Show preview of changes without pushing (exit after preview)',
+            required: false,
+        }),
+        env: Flags.boolean({
+            default: false,
+            description: 'Include environment variables in import',
+            required: false,
+        }),
+        force: Flags.boolean({
+            default: false,
+            description: 'Skip preview and confirmation prompt (for CI/CD pipelines)',
+            required: false,
+        }),
+        guids: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: 'Write server-assigned GUIDs back to local files (use --no-guids to skip)',
+            required: false,
+        }),
+        records: Flags.boolean({
+            default: false,
+            description: 'Include records in import',
+            required: false,
+        }),
+        sync: Flags.boolean({
+            default: false,
+            description: 'Full push — send all files, not just changed ones. Required for --delete.',
+            required: false,
+        }),
+        tenant: Flags.string({
+            char: 't',
+            description: 'Ephemeral tenant name to push to',
+            required: true,
+        }),
+        transaction: Flags.boolean({
+            allowNo: true,
+            default: true,
+            description: '[CRITICAL] DO NOT run with --no-transaction without explicit user confirmation; this disables rollback. Wraps import in a database transaction (use --no-transaction for debugging purposes).',
+            required: false,
+        }),
+        truncate: Flags.boolean({
+            default: false,
+            description: '[CRITICAL] STOP and confirm with the user; this truncates live tables before importing.',
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (uses profile workspace if not provided)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(EphemeralPush);
+        const { profile } = this.resolveProfile(flags);
+        const workspaceId = flags.workspace || profile.workspace;
+        if (!workspaceId) {
+            this.error('No workspace ID provided. Ephemeral tenants require a workspace — use --workspace or set one in your profile.');
+        }
+        const inputDir = resolve(flags.directory);
+        if (!fs.existsSync(inputDir)) {
+            this.error(`Directory not found: ${inputDir}`);
+        }
+        if (!fs.statSync(inputDir).isDirectory()) {
+            this.error(`Not a directory: ${inputDir}`);
+        }
+        const tenantName = flags.tenant;
+        const baseUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}`;
+        const target = {
+            buildDryRunUrl: (params) => `${baseUrl}/multidoc/dry-run?${params.toString()}`,
+            buildPushUrl: (params) => `${baseUrl}/multidoc?${params.toString()}`,
+            cliVersion: this.config.version,
+            instanceOrigin: profile.instance_origin,
+            label: `ephemeral tenant ${tenantName}`,
+            sourceWorkspaceId: profile.workspace,
+            supportsBranches: false,
+            supportsPartial: true,
+            warnOnWorkspaceMismatch: false,
+        };
+        const pushFlags = {
+            delete: flags.delete,
+            'dry-run': flags['dry-run'],
+            env: flags.env,
+            force: flags.force,
+            guids: flags.guids,
+            records: flags.records,
+            sync: flags.sync,
+            transaction: flags.transaction,
+            truncate: flags.truncate,
+            verbose: flags.verbose,
+        };
+        await executePush({
+            accessToken: profile.access_token,
+            branch: '',
+            command: this,
+            inputDir,
+            verboseFetch: this.verboseFetch.bind(this),
+        }, target, pushFlags);
+    }
+}

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

@@ -0,0 +1,40 @@
+import BaseCommand from '../../../base-command.js';
+export default class FunctionRun extends BaseCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    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>;
+        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>;
+        'no-input-check': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        stdin: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+    private emitResult;
+    /**
+     * Fetch a single function record by name via the list endpoint's search,
+     * returning the exact-name match (so `calc` doesn't accidentally match
+     * `calcScore`). Best-effort: returns undefined and warns on any failure so a
+     * transient introspection problem never blocks an otherwise-valid run.
+     */
+    private fetchFunctionByName;
+    /**
+     * Prompt for each missing required input on an interactive TTY. Values are
+     * read as raw JSON when they parse as such (so numbers/bools/objects work),
+     * otherwise treated as a string — mirroring the `key:=`/`key=` distinction.
+     * Non-TTY: fail fast with the list of missing params (never hang on a prompt).
+     */
+    private promptForMissing;
+    private readStdinSync;
+    private resolveWorkspaceId;
+}