@xano/cli 1.2.0 → 1.3.0

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

@@ -1,9 +1,9 @@
 import { Flags } from '@oclif/core';
-import * as fs from 'node:fs';
-import * as path from 'node:path';
 import snakeCase from 'lodash.snakecase';
+import * as fs from 'node:fs';
+import path from 'node:path';
 import BaseCommand from '../../../base-command.js';
-import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+import { buildApiGroupFolderResolver, buildChannelServerResolver, parseDocument, resolveDocumentPath, } from '../../../utils/document-parser.js';
 import { fetchKnowledge, writeKnowledge } from '../../../utils/knowledge-sync.js';
 export default class Pull extends BaseCommand {
     static description = 'Pull a workspace multidoc from the Xano Metadata API and split into individual files';
@@ -36,14 +36,14 @@ Pulled 58 documents
             description: 'Output directory for pulled documents (defaults to current directory)',
             required: false,
         }),
-        env: Flags.boolean({
+        draft: Flags.boolean({
             default: false,
-            description: 'Include environment variables',
+            description: 'Include draft versions',
             required: false,
         }),
-        draft: Flags.boolean({
+        env: Flags.boolean({
             default: false,
-            description: 'Include draft versions',
+            description: 'Include environment variables',
             required: false,
         }),
         records: Flags.boolean({
@@ -134,96 +134,19 @@ Pulled 58 documents
         // Resolve api_group names to unique folder names, disambiguating collisions
         // where different names produce the same snakeCase (e.g., "Authentication" vs "authentication")
         const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
+        // Resolve a realtime v2 channel path -> owning realtime_server name, so
+        // messages can nest under their channel's server (see resolver docs).
+        const getChannelServer = buildChannelServerResolver(documents);
         // 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}`;
-                }
-            }
+            const { baseName, typeDir } = resolveDocumentPath(doc, outputDir, {
+                getApiGroupFolder,
+                getChannelServer,
+                join: path.join,
+                snakeCase,
+            });
             fs.mkdirSync(typeDir, { recursive: true });
             // Track duplicates per directory
             const dirKey = path.relative(outputDir, typeDir);
@@ -234,8 +157,7 @@ Pulled 58 documents
             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 filename = count === 0 ? `${baseName}.xs` : `${baseName}_${count + 1}.xs`;
             const filePath = path.join(typeDir, filename);
             fs.writeFileSync(filePath, doc.content, 'utf8');
             writtenCount++;
@@ -252,12 +174,4 @@ Pulled 58 documents
             parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
         this.log(`Pulled ${parts.join(' + ')} 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/help.js

@@ -45,7 +45,9 @@ export default class Help extends BaseHelp {
             if (this.config.topicSeparator !== ':')
                 c.id = c.id.replaceAll(':', this.config.topicSeparator);
             const summary = this.summary(c);
-            return [c.id, summary ? summary.replace(/\u001B\[\d+m/g, '') : ''];
+            // Strip ANSI colour codes from the summary so the help table aligns.
+            // eslint-disable-next-line no-control-regex -- matching the escape char is the point
+            return [c.id, summary ? summary.replaceAll(/\u001B\[\d+m/g, '') : ''];
         });
         // Only add promoted commands at the root level, not within a specific topic
         if (isRootHelp) {
@@ -59,6 +61,6 @@ export default class Help extends BaseHelp {
             spacer: '\n',
             stripAnsi: this.opts.stripAnsi,
         });
-        return this.section('COMMANDS', body + `\n\n\x1b[2mSee xano <topic> --help for all commands in a topic.\x1b[0m`);
+        return this.section('COMMANDS', body + `\n\n\u001B[2mSee xano <topic> --help for all commands in a topic.\u001B[0m`);
     }
 }

package/dist/update-check.d.ts

@@ -5,4 +5,4 @@ export declare function clearUpdateCache(): void;
  *
  * The check hits npm at most once every 24 hours and caches the result.
  */
-export declare function checkForUpdate(currentVersion: string, forceCheck?: boolean): string | null;
+export declare function checkForUpdate(currentVersion: string, forceCheck?: boolean): null | string;

package/dist/update-check.js

@@ -1,7 +1,7 @@
 import { execSync } from 'node:child_process';
 import * as fs from 'node:fs';
-import * as path from 'node:path';
 import * as os from 'node:os';
+import path from 'node:path';
 const UPDATE_CHECK_FILE = path.join(os.homedir(), '.xano', 'update-check.json');
 const CHECK_INTERVAL_MS = 8 * 60 * 60 * 1000; // 8 hours
 function isBeta(version) {

package/dist/utils/document-parser.d.ts

@@ -1,9 +1,13 @@
 export interface ParsedDocument {
     apiGroup?: string;
     canonical?: string;
+    /** Owning channel path for realtime v2 `message` documents. */
+    channel?: string;
     content: string;
     guid?: string;
     name: string;
+    /** Owning realtime_server name for realtime v2 `channel` documents. */
+    server?: string;
     type: string;
     verb?: string;
 }
@@ -12,6 +16,87 @@ export interface ParsedDocument {
  * Skips leading comment lines (starting with //) to find the first meaningful line.
  */
 export declare function parseDocument(content: string): null | ParsedDocument;
+/**
+ * Map a realtime v2 channel path onto directory segments.
+ *
+ * A channel name IS a path template — "rooms/{room_id}" — so the directory tree
+ * mirrors it rather than flattening it. That is the whole reason messages nest
+ * under channels: the tree should show the structure, and
+ * "channel/rooms/[room_id]/post.xs" says immediately that `post` lives on a
+ * parameterized rooms channel.
+ *
+ *   "rooms"                    -> ["rooms"]
+ *   "rooms/{room_id}"          -> ["rooms", "[room_id]"]
+ *   "org/{org_id}/room/{id}"   -> ["org", "[org_id]", "room", "[id]"]
+ *
+ * Braces become brackets because "{" and "}" are awkward in shells, while "["
+ * and "]" are legal on every filesystem. They are still glob character classes,
+ * so scripting against a checkout needs the path quoted.
+ *
+ * Escaping the braces rather than dropping them is what keeps a parameterized
+ * channel distinct from a literal one: without it, "rooms/{room_id}" and a
+ * literal channel named "rooms/room_id" collide on the same directory.
+ *
+ * Mirrors Vfs::channelSegment() on the server.
+ */
+export declare function channelPathSegments(name: string, snakeCaseFn: (s: string) => string): string[];
+/**
+ * Build a map of realtime v2 channel path -> owning realtime_server name.
+ *
+ * This is the cross-document lookup the on-disk nesting needs: a `message`
+ * document names its channel (`channel = "..."`), while a `channel` document
+ * names its server (`realtime_server = "..."`). To place a message under
+ * `realtime/server/<server>/channel/<path>/...` we resolve the message's channel
+ * to that channel's server — which the channel document carries. (Messages now
+ * also carry `realtime_server` directly, but resolving via the channel keeps a
+ * single source of truth for the channel→server mapping.)
+ *
+ * Because every pull path parses the WHOLE multidoc into memory before writing,
+ * we can build this map from the `channel` docs in the same batch (a two-pass
+ * resolve), keyed by the channel's own name (its path). A channel with no
+ * `realtime_server` (e.g. a pre-server export) simply isn't in the map, and
+ * callers fall back accordingly.
+ */
+export declare function buildChannelServerResolver(documents: ParsedDocument[]): (channelName: string) => string | undefined;
+/**
+ * Sanitize a document name for use as a single on-disk filename segment.
+ * Strips quotes and snake_cases the rest. Mirrors the per-command
+ * `sanitizeFilename` the pull commands used to each define privately.
+ */
+export declare function sanitizeDocumentName(name: string, snakeCaseFn: (s: string) => string): string;
+/**
+ * The directory + base filename (no extension, no duplicate suffix) a document
+ * is written to on disk. `resolveDocumentPath` returns this; callers append the
+ * `.xs` extension and any `_N` duplicate suffix.
+ */
+export interface DocumentPlacement {
+    baseName: string;
+    typeDir: string;
+}
+/**
+ * Resolve where a parsed document lands on disk — the SINGLE source of truth for
+ * the pull layout, shared by every pull command (workspace, tenant, release,
+ * sandbox, ephemeral). Previously each command inlined a ~130-line copy of this
+ * decision; the copies drifted (the realtime v2 realtime_server/channel/message
+ * branches existed only in workspace/tenant), so an ephemeral pull dumped v2
+ * objects into flat top-level channel/, message/ and realtime_server/ folders —
+ * detaching messages from their channels and risking name collisions (message
+ * names are unique only WITHIN a channel).
+ *
+ * @param doc - the parsed document
+ * @param outputDir - the resolved pull output root
+ * @param deps - injected dependencies
+ * @param deps.getApiGroupFolder - resolves an api_group name to its unique folder
+ * @param deps.getChannelServer - resolves a v2 channel path to its owning realtime_server
+ * @param deps.join - the path.join implementation (injectable for testing)
+ * @param deps.snakeCase - the snakeCase implementation the caller uses
+ */
+export declare function resolveDocumentPath(doc: ParsedDocument, outputDir: string, deps: {
+    getApiGroupFolder: (groupName: string) => string;
+    getChannelServer: (channelName: string) => string | undefined;
+    join: (...parts: string[]) => string;
+    snakeCase: (s: string) => string;
+}): DocumentPlacement;
 /**
  * Build a unique key for a document based on its type, name, verb, and api_group.
  * Used to match server GUID map entries back to local files.
@@ -37,3 +122,34 @@ export declare function findFilesWithGuid(entries: Array<{
     content: string;
     filePath: string;
 }>, guid: string): string[];
+/**
+ * Split a multi-document XanoScript blob (documents joined by `\n---\n`) into
+ * parsed documents, skipping empties and any fragment that fails to parse.
+ *
+ * This is the same split the pull commands apply to the server's multidoc
+ * response. A hand-authored bundle is one file of many `---`-separated
+ * documents; this turns it back into the per-document units every downstream
+ * step (placement, GUID writeback, partial-diff matching) assumes.
+ */
+export declare function splitMultidoc(blob: string): ParsedDocument[];
+/** A document's resolved on-disk location relative to the output root, plus its content. */
+export interface PlacedDocument {
+    content: string;
+    /** POSIX-style path relative to the output root, e.g. "api/pdf/documents_GET.xs". */
+    relPath: string;
+}
+/**
+ * Compute where each document lands on disk — a PURE function (no filesystem)
+ * mirroring the split-and-place loop the pull commands run. It resolves each
+ * document via `resolveDocumentPath`, appends `.xs`, and disambiguates
+ * collisions within a directory with a `_N` suffix (the second file named
+ * `say.xs` in a dir becomes `say_2.xs`), exactly as the pull writer does.
+ *
+ * Kept filesystem-free so it can be unit-tested and reused by both the pull
+ * commands and `flatten` without duplicating the placement rules.
+ */
+export declare function placeDocuments(documents: ParsedDocument[], deps: {
+    join: (...parts: string[]) => string;
+    relative: (from: string, to: string) => string;
+    snakeCase: (s: string) => string;
+}): PlacedDocument[];