@xano/cli 1.0.6-beta.1 → 1.0.6-beta.2

package/README.md

@@ -594,6 +594,7 @@ xano ephemeral push <tenant_name> -d ./my-ephemeral
 # Open in the browser (or print the URL)
 xano ephemeral impersonate <tenant_name>
 xano ephemeral impersonate <tenant_name> --url-only
+xano ephemeral impersonate <tenant_name> --guest       # read-only session (browse only)
 ```
 
 #### Static hosting for an ephemeral tenant

package/dist/commands/ephemeral/impersonate/index.d.ts

@@ -6,6 +6,7 @@ export default class EphemeralImpersonate extends BaseCommand {
     static description: string;
     static examples: string[];
     static flags: {
+        guest: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'url-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -15,9 +15,16 @@ Opening browser...
 Impersonation successful!
 `,
         `$ xano ephemeral impersonate e4f2-9ab1-xyz1 -o json`,
+        `$ xano ephemeral impersonate e4f2-9ab1-xyz1 --guest --url-only`,
     ];
     static flags = {
         ...BaseCommand.baseFlags,
+        guest: Flags.boolean({
+            char: 'g',
+            default: false,
+            description: 'Mint a read-only guest session (browse only; no schema/data/config changes)',
+            required: false,
+        }),
         output: Flags.string({
             char: 'o',
             default: 'summary',
@@ -46,7 +53,7 @@ Impersonation successful!
         }
         const tenantName = args.tenant_name;
         try {
-            const response = await this.getImpersonateResponse(profile, workspaceId, tenantName);
+            const response = await this.getImpersonateResponse(profile, workspaceId, tenantName, flags.guest);
             if (flags.output === 'json') {
                 this.log(JSON.stringify(response, null, 2));
             }
@@ -76,8 +83,9 @@ Impersonation successful!
             }
         }
     }
-    async getImpersonateResponse(profile, workspaceId, tenantName) {
-        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(tenantName)}/impersonate`;
+    async getImpersonateResponse(profile, workspaceId, tenantName, guest = false) {
+        const query = guest ? '?guest_read_only=true' : '';
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${encodeURIComponent(tenantName)}/impersonate${query}`;
         const { verbose } = await this.parse(EphemeralImpersonate).then((r) => r.flags);
         const response = await this.verboseFetch(apiUrl, {
             headers: {

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

@@ -3,7 +3,7 @@ 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';
+import { buildApiGroupFolderResolver, channelPathSegments, parseDocument, } from '../../../utils/document-parser.js';
 export default class Pull extends BaseCommand {
     static description = 'Pull a tenant multidoc from the Xano Metadata API and split into individual files';
     static examples = [
@@ -190,6 +190,17 @@ Pulled 58 documents from tenant my-tenant
                 typeDir = path.join(outputDir, 'realtime', 'trigger');
                 baseName = this.sanitizeFilename(doc.name);
             }
+            else if (doc.type === 'channel') {
+                // Realtime v2 — see workspace/pull for the full rationale.
+                // channel "rooms/{room_id}" → channel/rooms/[room_id]/_channel.xs
+                typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.name, snakeCase));
+                baseName = '_channel';
+            }
+            else if (doc.type === 'message' && doc.channel) {
+                // Realtime v2 message → channel/{channel_path}/{message_name}.xs
+                typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.channel, snakeCase));
+                baseName = this.sanitizeFilename(doc.name);
+            }
             else if (doc.type === 'api_group') {
                 // api_group "test" → api/{resolved_folder}/{name}.xs
                 const groupFolder = getApiGroupFolder(doc.name);

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

@@ -5,7 +5,7 @@ import * as os from 'node:os';
 import * as path from 'node:path';
 import snakeCase from 'lodash.snakecase';
 import BaseCommand, { buildUserAgent } from '../../../../base-command.js';
-import { buildApiGroupFolderResolver, parseDocument } from '../../../../utils/document-parser.js';
+import { buildApiGroupFolderResolver, channelPathSegments, parseDocument, } from '../../../../utils/document-parser.js';
 export default class GitPull extends BaseCommand {
     static description = 'Pull XanoScript files from a git repository into a local directory';
     static examples = [
@@ -373,6 +373,15 @@ export default class GitPull extends BaseCommand {
             typeDir = path.join(outputDir, 'realtime', 'trigger');
             baseName = this.sanitizeFilename(doc.name);
         }
+        else if (doc.type === 'channel') {
+            // Realtime v2 — see workspace/pull for the full rationale.
+            typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.name, snakeCase));
+            baseName = '_channel';
+        }
+        else if (doc.type === 'message' && doc.channel) {
+            typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.channel, snakeCase));
+            baseName = this.sanitizeFilename(doc.name);
+        }
         else if (doc.type === 'api_group') {
             const groupFolder = getApiGroupFolder(doc.name);
             typeDir = path.join(outputDir, 'api', groupFolder);

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

@@ -3,7 +3,7 @@ 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';
+import { buildApiGroupFolderResolver, channelPathSegments, parseDocument, } 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';
@@ -195,6 +195,26 @@ Pulled 58 documents
                 typeDir = path.join(outputDir, 'realtime', 'trigger');
                 baseName = this.sanitizeFilename(doc.name);
             }
+            else if (doc.type === 'channel') {
+                // Realtime v2. The channel owns a directory mirroring its path and its
+                // messages live inside it, so ownership is visible in the tree.
+                //   channel "rooms/{room_id}" → channel/rooms/[room_id]/_channel.xs
+                //
+                // The document uses a FIXED "_channel.xs" leaf: naming it after the
+                // last segment yields "[room_id].xs", which names the parameter rather
+                // than the channel. A fixed leaf also sorts first, making "the channel
+                // vs its messages" obvious.
+                typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.name, snakeCase));
+                baseName = '_channel';
+            }
+            else if (doc.type === 'message' && doc.channel) {
+                // Realtime v2 message → channel/{channel_path}/{message_name}.xs
+                // Nesting matters beyond tidiness: message names are unique only WITHIN
+                // a channel, so a flat message/ directory would collide when two
+                // channels both define e.g. "say".
+                typeDir = path.join(outputDir, 'channel', ...channelPathSegments(doc.channel, snakeCase));
+                baseName = this.sanitizeFilename(doc.name);
+            }
             else if (doc.type === 'api_group') {
                 // api_group "test" → api/{resolved_folder}/{name}.xs
                 const groupFolder = getApiGroupFolder(doc.name);

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

@@ -1,6 +1,8 @@
 export interface ParsedDocument {
     apiGroup?: string;
     canonical?: string;
+    /** Owning channel path for realtime v2 `message` documents. */
+    channel?: string;
     content: string;
     guid?: string;
     name: string;
@@ -12,6 +14,30 @@ 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 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.

package/dist/utils/document-parser.js

@@ -45,6 +45,14 @@ export function parseDocument(content) {
     if (apiGroupMatch) {
         apiGroup = apiGroupMatch[1];
     }
+    // Extract channel if present (e.g., channel = "rooms/{room_id}").
+    // Realtime v2 messages reference their owning channel by PATH, which is what
+    // nests them under it on disk.
+    let channel;
+    const channelMatch = content.match(/^\s*channel\s*=\s*"([^"]*)"/m);
+    if (channelMatch) {
+        channel = channelMatch[1];
+    }
     // Extract canonical if present (e.g., canonical = "abc123")
     let canonical;
     const canonicalMatch = content.match(/canonical\s*=\s*"([^"]*)"/);
@@ -57,7 +65,36 @@ export function parseDocument(content) {
     if (guidMatch) {
         guid = guidMatch[1];
     }
-    return { apiGroup, canonical, content, guid, name, type, verb };
+    return { apiGroup, canonical, channel, content, guid, name, type, verb };
+}
+/**
+ * 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 function channelPathSegments(name, snakeCaseFn) {
+    // A parameter keeps the author's name verbatim so it matches the `input`
+    // block; only the delimiters are swapped.
+    const isParam = /^\{.*\}$/;
+    return name.split('/').map((segment) => (isParam.test(segment) ? `[${segment.slice(1, -1)}]` : snakeCaseFn(segment)));
 }
 /**
  * Build a unique key for a document based on its type, name, verb, and api_group.