@xano/cli 0.0.63 → 0.0.65

package/dist/commands/release/pull/index.d.ts

@@ -15,12 +15,6 @@ export default class ReleasePull extends BaseCommand {
     };
     run(): Promise<void>;
     private loadCredentials;
-    /**
-     * Parse a single document to extract its type, name, and optional verb.
-     * Skips leading comment lines (starting with //) to find the first
-     * meaningful line containing the type keyword and name.
-     */
-    private parseDocument;
     private resolveReleaseName;
     /**
      * Sanitize a document name for use as a filename.

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

@@ -5,6 +5,7 @@ import * as os from 'node:os';
 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 ReleasePull extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -122,7 +123,7 @@ Pulled 58 documents from release 'v1.0' to ./backup
             if (!trimmed) {
                 continue;
             }
-            const parsed = this.parseDocument(trimmed);
+            const parsed = parseDocument(trimmed);
             if (parsed) {
                 documents.push(parsed);
             }
@@ -135,6 +136,8 @@ Pulled 58 documents from release 'v1.0' to ./backup
         const outputDir = path.resolve(args.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;
@@ -192,14 +195,14 @@ Pulled 58 documents from release 'v1.0' to ./backup
                 baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'api_group') {
-                // api_group "test" → api/test/api_group.xs
-                const groupFolder = snakeCase(doc.name);
+                // api_group "test" → api/{resolved_folder}/{name}.xs
+                const groupFolder = getApiGroupFolder(doc.name);
                 typeDir = path.join(outputDir, 'api', groupFolder);
-                baseName = 'api_group';
+                baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'query' && doc.apiGroup) {
-                // query in group "test" → api/test/{query_name}.xs
-                const groupFolder = snakeCase(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));
@@ -258,62 +261,12 @@ Pulled 58 documents from release 'v1.0' to ./backup
             this.error(`Failed to parse credentials file: ${error}`);
         }
     }
-    /**
-     * Parse a single document to extract its type, name, and optional verb.
-     * Skips leading comment lines (starting with //) to find the first
-     * meaningful line containing the type keyword and name.
-     */
-    parseDocument(content) {
-        const lines = content.split('\n');
-        // Find the first non-comment line
-        let firstLine = null;
-        for (const line of lines) {
-            const trimmedLine = line.trim();
-            if (trimmedLine && !trimmedLine.startsWith('//')) {
-                firstLine = trimmedLine;
-                break;
-            }
-        }
-        if (!firstLine) {
-            return null;
-        }
-        // Parse the type keyword and name from the first meaningful line
-        // Expected formats:
-        //   type name {
-        //   type name verb=GET {
-        //   type "name with spaces" {
-        //   type "name with spaces" verb=PATCH {
-        const match = firstLine.match(/^(\w+)\s+("(?:[^"\\]|\\.)*"|\S+)(?:\s+(.*))?/);
-        if (!match) {
-            return null;
-        }
-        const type = match[1];
-        let name = match[2];
-        const rest = match[3] || '';
-        // Strip surrounding quotes from the name
-        if (name.startsWith('"') && name.endsWith('"')) {
-            name = name.slice(1, -1);
-        }
-        // Extract verb if present (e.g., verb=GET)
-        let verb;
-        const verbMatch = rest.match(/verb=(\S+)/);
-        if (verbMatch) {
-            verb = verbMatch[1];
-        }
-        // Extract api_group if present (e.g., api_group = "test")
-        let apiGroup;
-        const apiGroupMatch = content.match(/api_group\s*=\s*"([^"]*)"/);
-        if (apiGroupMatch) {
-            apiGroup = apiGroupMatch[1];
-        }
-        return { apiGroup, content, name, type, verb };
-    }
     async resolveReleaseName(profile, workspaceId, releaseName, verbose) {
         const listUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/release`;
         const response = await this.verboseFetch(listUrl, {
             headers: {
-                'accept': 'application/json',
-                'Authorization': `Bearer ${profile.access_token}`,
+                accept: 'application/json',
+                Authorization: `Bearer ${profile.access_token}`,
             },
             method: 'GET',
         }, verbose, profile.access_token);
@@ -321,15 +274,15 @@ Pulled 58 documents from release 'v1.0' to ./backup
             const errorText = await response.text();
             this.error(`Failed to list releases: ${response.status} ${response.statusText}\n${errorText}`);
         }
-        const data = await response.json();
+        const data = (await response.json());
         const releases = Array.isArray(data)
             ? data
-            : (data && typeof data === 'object' && 'items' in data && Array.isArray(data.items))
+            : data && typeof data === 'object' && 'items' in data && Array.isArray(data.items)
                 ? data.items
                 : [];
-        const match = releases.find(r => r.name === releaseName);
+        const match = releases.find((r) => r.name === releaseName);
         if (!match) {
-            const available = releases.map(r => r.name).join(', ');
+            const available = releases.map((r) => r.name).join(', ');
             this.error(`Release '${releaseName}' not found.${available ? ` Available releases: ${available}` : ''}`);
         }
         return match.id;

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

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { findFilesWithGuid } from '../../../utils/document-parser.js';
 export default class ReleasePush extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -117,18 +118,18 @@ Output release details as JSON
         if (files.length === 0) {
             this.error(`No .xs files found in ${args.directory}`);
         }
-        // Read each file and join with --- separator
-        const documents = [];
+        // Read each file and track file path alongside content
+        const documentEntries = [];
         for (const filePath of files) {
             const content = fs.readFileSync(filePath, 'utf8').trim();
             if (content) {
-                documents.push(content);
+                documentEntries.push({ content, filePath });
             }
         }
-        if (documents.length === 0) {
+        if (documentEntries.length === 0) {
             this.error(`All .xs files in ${args.directory} are empty`);
         }
-        const multidoc = documents.join('\n---\n');
+        const multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         // Construct the API URL with query params
         const queryParams = new URLSearchParams({
             description: flags.description,
@@ -164,6 +165,15 @@ Output release details as JSON
                 catch {
                     errorMessage += `\n${errorText}`;
                 }
+                // Surface local files involved in duplicate GUID errors
+                const guidMatch = errorMessage.match(/Duplicate \w+ guid: (\S+)/);
+                if (guidMatch) {
+                    const dupeFiles = findFilesWithGuid(documentEntries, guidMatch[1]);
+                    if (dupeFiles.length > 0) {
+                        const relPaths = dupeFiles.map((f) => path.relative(inputDir, f));
+                        errorMessage += `\n  Local files with this GUID:\n${relPaths.map((f) => `    ${f}`).join('\n')}`;
+                    }
+                }
                 this.error(errorMessage);
             }
             const release = (await response.json());
@@ -179,7 +189,7 @@ Output release details as JSON
                 if (release.description)
                     this.log(`  Description: ${release.description}`);
                 const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-                this.log(`  Documents: ${documents.length}`);
+                this.log(`  Documents: ${documentEntries.length}`);
                 this.log(`  Time: ${elapsed}s`);
             }
         }

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

@@ -107,6 +107,9 @@ Created tenant: Production (production) - ID: 42
             body.platform_id = flags.platform_id;
         if (flags.domain)
             body.domain = flags.domain;
+        if (flags.license === 'tier2' || flags.license === 'tier3' || flags.cluster_id) {
+            this.warn('This may take a few minutes. Please be patient.');
+        }
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant`;
         try {
             const response = await this.verboseFetch(apiUrl, {

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

@@ -59,6 +59,7 @@ Deployed platform 5 to tenant: My Tenant (my-tenant)
         const tenantName = args.tenant_name;
         const platformId = flags.platform_id;
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/platform/deploy`;
+        this.warn('This may take a few minutes. Please be patient.');
         const startTime = Date.now();
         try {
             const response = await this.verboseFetch(apiUrl, {

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

@@ -60,6 +60,7 @@ Deployed release "v1.0" to tenant: My Tenant (my-tenant)
         const releaseName = flags.release;
         const tenantName = args.tenant_name;
         const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/tenant/${tenantName}/deploy`;
+        this.warn('This may take a few minutes. Please be patient.');
         const startTime = Date.now();
         try {
             const response = await this.verboseFetch(apiUrl, {

package/dist/commands/tenant/pull/index.d.ts

@@ -16,12 +16,6 @@ export default class Pull extends BaseCommand {
     };
     run(): Promise<void>;
     private loadCredentials;
-    /**
-     * Parse a single document to extract its type, name, and optional verb.
-     * Skips leading comment lines (starting with //) to find the first
-     * meaningful line containing the type keyword and name.
-     */
-    private parseDocument;
     /**
      * Sanitize a document name for use as a filename.
      * Strips quotes, replaces spaces with underscores, and removes

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

@@ -5,6 +5,7 @@ import * as os from 'node:os';
 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 Pull extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -130,7 +131,7 @@ Pulled 42 documents from tenant my-tenant to ./my-tenant
             if (!trimmed) {
                 continue;
             }
-            const parsed = this.parseDocument(trimmed);
+            const parsed = parseDocument(trimmed);
             if (parsed) {
                 documents.push(parsed);
             }
@@ -143,6 +144,8 @@ Pulled 42 documents from tenant my-tenant to ./my-tenant
         const outputDir = path.resolve(args.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;
@@ -200,14 +203,14 @@ Pulled 42 documents from tenant my-tenant to ./my-tenant
                 baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'api_group') {
-                // api_group "test" → api/test/api_group.xs
-                const groupFolder = snakeCase(doc.name);
+                // api_group "test" → api/{resolved_folder}/{name}.xs
+                const groupFolder = getApiGroupFolder(doc.name);
                 typeDir = path.join(outputDir, 'api', groupFolder);
-                baseName = 'api_group';
+                baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'query' && doc.apiGroup) {
-                // query in group "test" → api/test/{query_name}.xs
-                const groupFolder = snakeCase(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));
@@ -266,56 +269,6 @@ Pulled 42 documents from tenant my-tenant to ./my-tenant
             this.error(`Failed to parse credentials file: ${error}`);
         }
     }
-    /**
-     * Parse a single document to extract its type, name, and optional verb.
-     * Skips leading comment lines (starting with //) to find the first
-     * meaningful line containing the type keyword and name.
-     */
-    parseDocument(content) {
-        const lines = content.split('\n');
-        // Find the first non-comment line
-        let firstLine = null;
-        for (const line of lines) {
-            const trimmedLine = line.trim();
-            if (trimmedLine && !trimmedLine.startsWith('//')) {
-                firstLine = trimmedLine;
-                break;
-            }
-        }
-        if (!firstLine) {
-            return null;
-        }
-        // Parse the type keyword and name from the first meaningful line
-        // Expected formats:
-        //   type name {
-        //   type name verb=GET {
-        //   type "name with spaces" {
-        //   type "name with spaces" verb=PATCH {
-        const match = firstLine.match(/^(\w+)\s+("(?:[^"\\]|\\.)*"|\S+)(?:\s+(.*))?/);
-        if (!match) {
-            return null;
-        }
-        const type = match[1];
-        let name = match[2];
-        const rest = match[3] || '';
-        // Strip surrounding quotes from the name
-        if (name.startsWith('"') && name.endsWith('"')) {
-            name = name.slice(1, -1);
-        }
-        // Extract verb if present (e.g., verb=GET)
-        let verb;
-        const verbMatch = rest.match(/verb=(\S+)/);
-        if (verbMatch) {
-            verb = verbMatch[1];
-        }
-        // Extract api_group if present (e.g., api_group = "test")
-        let apiGroup;
-        const apiGroupMatch = content.match(/api_group\s*=\s*"([^"]*)"/);
-        if (apiGroupMatch) {
-            apiGroup = apiGroupMatch[1];
-        }
-        return { apiGroup, content, name, type, verb };
-    }
     /**
      * Sanitize a document name for use as a filename.
      * Strips quotes, replaces spaces with underscores, and removes

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

@@ -4,6 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import BaseCommand from '../../../base-command.js';
+import { findFilesWithGuid } from '../../../utils/document-parser.js';
 export default class Push extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -142,18 +143,18 @@ Truncate all table records before importing
         if (files.length === 0) {
             this.error(`No .xs files found in ${args.directory}`);
         }
-        // Read each file and join with --- separator
-        const documents = [];
+        // Read each file and track file path alongside content
+        const documentEntries = [];
         for (const filePath of files) {
             const content = fs.readFileSync(filePath, 'utf8').trim();
             if (content) {
-                documents.push(content);
+                documentEntries.push({ content, filePath });
             }
         }
-        if (documents.length === 0) {
+        if (documentEntries.length === 0) {
             this.error(`All .xs files in ${args.directory} are empty`);
         }
-        const multidoc = documents.join('\n---\n');
+        const multidoc = documentEntries.map((d) => d.content).join('\n---\n');
         // Construct the API URL
         const queryParams = new URLSearchParams({
             env: flags.env.toString(),
@@ -187,11 +188,20 @@ Truncate all table records before importing
                 catch {
                     errorMessage += `\n${errorText}`;
                 }
+                // Surface local files involved in duplicate GUID errors
+                const guidMatch = errorMessage.match(/Duplicate \w+ guid: (\S+)/);
+                if (guidMatch) {
+                    const dupeFiles = findFilesWithGuid(documentEntries, guidMatch[1]);
+                    if (dupeFiles.length > 0) {
+                        const relPaths = dupeFiles.map((f) => path.relative(inputDir, f));
+                        errorMessage += `\n  Local files with this GUID:\n${relPaths.map((f) => `    ${f}`).join('\n')}`;
+                    }
+                }
                 this.error(errorMessage);
             }
-            // Log the response if any
+            // Parse the response (suppress raw output; only show in verbose mode)
             const responseText = await response.text();
-            if (responseText && responseText !== 'null') {
+            if (responseText && responseText !== 'null' && flags.verbose) {
                 this.log(responseText);
             }
         }
@@ -204,7 +214,7 @@ Truncate all table records before importing
             }
         }
         const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-        this.log(`Pushed ${documents.length} documents to tenant ${tenantName} from ${args.directory} in ${elapsed}s`);
+        this.log(`Pushed ${documentEntries.length} documents to tenant ${tenantName} from ${args.directory} in ${elapsed}s`);
     }
     /**
      * Recursively collect all .xs files from a directory, sorted by

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 from '../../../../base-command.js';
-import { parseDocument } from '../../../../utils/document-parser.js';
+import { buildApiGroupFolderResolver, parseDocument } from '../../../../utils/document-parser.js';
 export default class GitPull extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -95,10 +95,11 @@ export default class GitPull extends BaseCommand {
             }
             // Write documents to output directory using the same file tree logic as workspace pull
             fs.mkdirSync(outputDir, { recursive: true });
+            const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
             const filenameCounters = new Map();
             let writtenCount = 0;
             for (const doc of documents) {
-                const { baseName, typeDir } = this.resolveOutputPath(outputDir, doc);
+                const { baseName, typeDir } = this.resolveOutputPath(outputDir, doc, getApiGroupFolder);
                 fs.mkdirSync(typeDir, { recursive: true });
                 // Track duplicates per directory
                 const dirKey = path.relative(outputDir, typeDir);
@@ -323,7 +324,7 @@ export default class GitPull extends BaseCommand {
      * Resolve the output directory and base filename for a parsed document.
      * Uses the same type-to-directory mapping as workspace pull.
      */
-    resolveOutputPath(outputDir, doc) {
+    resolveOutputPath(outputDir, doc, getApiGroupFolder) {
         let typeDir;
         let baseName;
         if (doc.type === 'workspace') {
@@ -367,12 +368,12 @@ export default class GitPull extends BaseCommand {
             baseName = this.sanitizeFilename(doc.name);
         }
         else if (doc.type === 'api_group') {
-            const groupFolder = snakeCase(doc.name);
+            const groupFolder = getApiGroupFolder(doc.name);
             typeDir = path.join(outputDir, 'api', groupFolder);
-            baseName = 'api_group';
+            baseName = this.sanitizeFilename(doc.name);
         }
         else if (doc.type === 'query' && doc.apiGroup) {
-            const groupFolder = snakeCase(doc.apiGroup);
+            const groupFolder = getApiGroupFolder(doc.apiGroup);
             const nameParts = doc.name.split('/');
             const leafName = nameParts.pop();
             const folderParts = nameParts.map((part) => snakeCase(part));

package/dist/commands/workspace/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 from '../../../base-command.js';
-import { parseDocument } from '../../../utils/document-parser.js';
+import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
 export default class Pull extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -149,6 +149,9 @@ Pulled 42 documents to ./my-workspace
         const outputDir = path.resolve(args.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
+        // where different names produce the same snakeCase (e.g., "Authentication" vs "authentication")
+        const getApiGroupFolder = buildApiGroupFolderResolver(documents, snakeCase);
         // Track filenames per type to handle duplicates
         const filenameCounters = new Map();
         let writtenCount = 0;
@@ -206,14 +209,14 @@ Pulled 42 documents to ./my-workspace
                 baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'api_group') {
-                // api_group "test" → api/test/api_group.xs
-                const groupFolder = snakeCase(doc.name);
+                // api_group "test" → api/{resolved_folder}/{name}.xs
+                const groupFolder = getApiGroupFolder(doc.name);
                 typeDir = path.join(outputDir, 'api', groupFolder);
-                baseName = 'api_group';
+                baseName = this.sanitizeFilename(doc.name);
             }
             else if (doc.type === 'query' && doc.apiGroup) {
-                // query in group "test" → api/test/{query_name}.xs
-                const groupFolder = snakeCase(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));

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

@@ -4,7 +4,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import BaseCommand from '../../../base-command.js';
-import { buildDocumentKey, parseDocument } from '../../../utils/document-parser.js';
+import { buildDocumentKey, findFilesWithGuid, parseDocument } from '../../../utils/document-parser.js';
 export default class Push extends BaseCommand {
     static args = {
         directory: Args.string({
@@ -201,6 +201,15 @@ Push schema only, skip records and environment variables
                 catch {
                     errorMessage += `\n${errorText}`;
                 }
+                // Surface local files involved in duplicate GUID errors
+                const guidMatch = errorMessage.match(/Duplicate \w+ guid: (\S+)/);
+                if (guidMatch) {
+                    const dupeFiles = findFilesWithGuid(documentEntries, guidMatch[1]);
+                    if (dupeFiles.length > 0) {
+                        const relPaths = dupeFiles.map((f) => path.relative(inputDir, f));
+                        errorMessage += `\n  Local files with this GUID:\n${relPaths.map((f) => `    ${f}`).join('\n')}`;
+                    }
+                }
                 this.error(errorMessage);
             }
             // Parse the response for GUID map

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

@@ -1,6 +1,8 @@
 export interface ParsedDocument {
     apiGroup?: string;
+    canonical?: string;
     content: string;
+    guid?: string;
     name: string;
     type: string;
     verb?: string;
@@ -15,3 +17,23 @@ export declare function parseDocument(content: string): null | ParsedDocument;
  * Used to match server GUID map entries back to local files.
  */
 export declare function buildDocumentKey(type: string, name: string, verb?: string, apiGroup?: string): string;
+/**
+ * Build a map of api_group name → unique folder name for a set of documents.
+ *
+ * When two api_groups produce the same snakeCase folder (e.g., "Authentication" and
+ * "authentication" both → "authentication"), the first group keeps the base name
+ * and subsequent groups get a numeric suffix (authentication_2, authentication_3, etc.).
+ *
+ * @param documents - Parsed documents (only api_group type docs are considered)
+ * @param snakeCaseFn - The snakeCase function to use for folder name generation
+ * @returns A function that resolves an api_group name to its unique folder name
+ */
+export declare function buildApiGroupFolderResolver(documents: ParsedDocument[], snakeCaseFn: (s: string) => string): (groupName: string) => string;
+/**
+ * Find local .xs files that contain a specific GUID.
+ * Used to surface which files are involved when the server reports a duplicate GUID error.
+ */
+export declare function findFilesWithGuid(entries: Array<{
+    content: string;
+    filePath: string;
+}>, guid: string): string[];

package/dist/utils/document-parser.js

@@ -45,7 +45,19 @@ export function parseDocument(content) {
     if (apiGroupMatch) {
         apiGroup = apiGroupMatch[1];
     }
-    return { apiGroup, content, name, type, verb };
+    // Extract canonical if present (e.g., canonical = "abc123")
+    let canonical;
+    const canonicalMatch = content.match(/canonical\s*=\s*"([^"]*)"/);
+    if (canonicalMatch) {
+        canonical = canonicalMatch[1];
+    }
+    // Extract guid if present (e.g., guid = "abc123")
+    let guid;
+    const guidMatch = content.match(/guid\s*=\s*"([^"]*)"/);
+    if (guidMatch) {
+        guid = guidMatch[1];
+    }
+    return { apiGroup, canonical, content, guid, name, type, verb };
 }
 /**
  * Build a unique key for a document based on its type, name, verb, and api_group.
@@ -59,3 +71,44 @@ export function buildDocumentKey(type, name, verb, apiGroup) {
         parts.push(apiGroup);
     return parts.join(':');
 }
+/**
+ * Build a map of api_group name → unique folder name for a set of documents.
+ *
+ * When two api_groups produce the same snakeCase folder (e.g., "Authentication" and
+ * "authentication" both → "authentication"), the first group keeps the base name
+ * and subsequent groups get a numeric suffix (authentication_2, authentication_3, etc.).
+ *
+ * @param documents - Parsed documents (only api_group type docs are considered)
+ * @param snakeCaseFn - The snakeCase function to use for folder name generation
+ * @returns A function that resolves an api_group name to its unique folder name
+ */
+export function buildApiGroupFolderResolver(documents, snakeCaseFn) {
+    const apiGroupFolderMap = new Map();
+    const folderClaims = new Map();
+    for (const doc of documents) {
+        if (doc.type !== 'api_group')
+            continue;
+        const folder = snakeCaseFn(doc.name);
+        const names = folderClaims.get(folder) ?? [];
+        if (!names.includes(doc.name)) {
+            names.push(doc.name);
+        }
+        folderClaims.set(folder, names);
+    }
+    for (const [folder, names] of folderClaims) {
+        apiGroupFolderMap.set(names[0], folder);
+        for (let i = 1; i < names.length; i++) {
+            apiGroupFolderMap.set(names[i], `${folder}_${i + 1}`);
+        }
+    }
+    return (groupName) => {
+        return apiGroupFolderMap.get(groupName) ?? snakeCaseFn(groupName);
+    };
+}
+/**
+ * Find local .xs files that contain a specific GUID.
+ * Used to surface which files are involved when the server reports a duplicate GUID error.
+ */
+export function findFilesWithGuid(entries, guid) {
+    return entries.filter((e) => e.content.includes(guid)).map((e) => e.filePath);
+}