@xano/cli 1.0.4-beta.3 → 1.0.4-beta.4

package/dist/utils/multidoc-push.js

@@ -3,6 +3,7 @@ import { minimatch } from 'minimatch';
 import * as fs from 'node:fs';
 import { join, relative } from 'node:path';
 import { buildDocumentKey, findFilesWithGuid, parseDocument } from './document-parser.js';
+import { collectKnowledgeObjects, fetchKnowledge, knowledgePreview, pushKnowledge, syncGuidToFrontmatter, toPushItems, } from './knowledge-sync.js';
 import { checkReferences, checkTableIndexes } from './reference-checker.js';
 // Minimum total operations before a workspace mismatch is treated as worth interrupting for.
 // Small change sets (e.g., editing a single function) aren't worth a reset prompt.
@@ -140,12 +141,15 @@ export function renderBadIndexes(badIndexes, log) {
 const TYPE_LABELS = {
     addon: 'Addons',
     agent: 'Agents',
+    'agents.md': 'Knowledge: agents.md',
     api_group: 'API Groups',
+    doc: 'Knowledge: Docs',
     function: 'Functions',
     mcp_server: 'MCP Servers',
     middleware: 'Middleware',
     query: 'API Endpoints',
     realtime_channel: 'Realtime Channels',
+    skill: 'Knowledge: Skills',
     table: 'Tables',
     task: 'Tasks',
     tool: 'Tools',
@@ -329,6 +333,47 @@ function syncGuidToFile(filePath, guid) {
     fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
     return true;
 }
+// ── Knowledge Preview Helpers ─────────────────────────────────────────────────
+/**
+ * Compute a knowledge change preview: prefer the server's `dry_run` response,
+ * and fall back to a client-side diff (fetch current objects → compare) when the
+ * server doesn't support it — mirroring how multidoc tolerates a missing dry-run.
+ */
+async function computeKnowledgePreview(listUrl, objects, branch, shouldDelete, accessToken, verboseFetch, verbose) {
+    const items = toPushItems(objects);
+    try {
+        const serverResult = await pushKnowledge(listUrl, accessToken, verboseFetch, verbose, {
+            branch,
+            delete: shouldDelete,
+            // eslint-disable-next-line camelcase -- external Metadata API field name
+            dry_run: true,
+            items,
+        });
+        if (serverResult.operations && serverResult.summary) {
+            return { operations: serverResult.operations, summary: serverResult.summary };
+        }
+    }
+    catch {
+        // Server doesn't support dry_run yet; fall through to local diff.
+    }
+    const serverObjects = await fetchKnowledge(listUrl, branch, accessToken, verboseFetch, verbose);
+    return knowledgePreview(items, serverObjects, shouldDelete);
+}
+/** Fold a knowledge preview's summary + operations into the multidoc DryRunResult. */
+function mergeKnowledgePreview(preview, knowledge) {
+    for (const [type, counts] of Object.entries(knowledge.summary)) {
+        preview.summary[type] = {
+            created: counts.created,
+            deleted: counts.deleted,
+            truncated: 0,
+            unchanged: counts.unchanged,
+            updated: counts.updated,
+        };
+    }
+    for (const op of knowledge.operations) {
+        preview.operations.push({ action: op.action, details: '', name: op.name, type: op.type });
+    }
+}
 // ── Main Push Logic ─────────────────────────────────────────────────────────
 /**
  * Execute a multidoc push with preview, validation, partial mode, and GUID sync.
@@ -337,27 +382,37 @@ function syncGuidToFile(filePath, guid) {
 export async function executePush(ctx, target, flags) {
     const { accessToken, command, inputDir, verboseFetch } = ctx;
     const log = command.log.bind(command);
-    // ── Collect and filter files ──────────────────────────────────────────
+    // ── Collect knowledge entries (before file check so knowledge-only push works) ─
+    let knowledgeObjects = [];
+    if (ctx.knowledge) {
+        knowledgeObjects = collectKnowledgeObjects(ctx.knowledge.rootDir, flags.include, flags.exclude);
+    }
+    // ── Collect and filter .xs files ──────────────────────────────────────
     const allFiles = collectFiles(inputDir);
     const files = applyFilters(allFiles, inputDir, flags.include, flags.exclude, log);
-    if (files.length === 0) {
+    const knowledgeOnly = files.length === 0 && (knowledgeObjects.length > 0 || ctx.knowledge !== undefined);
+    if (files.length === 0 && !knowledgeOnly) {
         command.error(flags.include || flags.exclude
             ? `No .xs files remain after ${[flags.include ? `include ${flags.include.join(', ')}` : '', flags.exclude ? `exclude ${flags.exclude.join(', ')}` : ''].filter(Boolean).join(' and ')} in ${inputDir}`
             : `No .xs files found in ${inputDir}`);
     }
     // ── Read documents ────────────────────────────────────────────────────
-    const documentEntries = readDocuments(files);
-    if (documentEntries.length === 0) {
-        command.error(`All .xs files in ${inputDir} are empty`);
-    }
-    let multidoc = documentEntries.map((d) => d.content).join('\n---\n');
-    // ── Build document key → file path map (for GUID writeback) ───────────
+    let documentEntries = [];
+    let multidoc = '';
     const documentFileMap = new Map();
-    for (const entry of documentEntries) {
-        const parsed = parseDocument(entry.content);
-        if (parsed) {
-            const key = buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup);
-            documentFileMap.set(key, entry.filePath);
+    if (!knowledgeOnly) {
+        documentEntries = readDocuments(files);
+        if (documentEntries.length === 0) {
+            command.error(`All .xs files in ${inputDir} are empty`);
+        }
+        multidoc = documentEntries.map((d) => d.content).join('\n---\n');
+        // ── Build document key → file path map (for GUID writeback) ─────────
+        for (const entry of documentEntries) {
+            const parsed = parseDocument(entry.content);
+            if (parsed) {
+                const key = buildDocumentKey(parsed.type, parsed.name, parsed.verb, parsed.apiGroup);
+                documentFileMap.set(key, entry.filePath);
+            }
         }
     }
     // ── Resolve push mode ─────────────────────────────────────────────────
@@ -388,7 +443,7 @@ export async function executePush(ctx, target, flags) {
     };
     // ── Dry-run / Preview ─────────────────────────────────────────────────
     let dryRunPreview = null;
-    const dryRunUrl = target.buildDryRunUrl(queryParams);
+    const dryRunUrl = knowledgeOnly ? null : target.buildDryRunUrl(queryParams);
     if (dryRunUrl && (flags['dry-run'] || !flags.force)) {
         const dryRunParams = new URLSearchParams(queryParams);
         // Always request delete info in dry-run to show remote-only items
@@ -401,15 +456,16 @@ export async function executePush(ctx, target, flags) {
                 headers: requestHeaders,
                 method: 'POST',
             }, flags.verbose, accessToken);
-            if (!dryRunResponse.ok) {
-                await handleDryRunError(dryRunResponse, command, flags, target);
-                // If we get here, the user confirmed to proceed without preview
-            }
-            else {
+            if (dryRunResponse.ok) {
                 const dryRunText = await dryRunResponse.text();
                 const preview = JSON.parse(dryRunText);
                 dryRunPreview = preview;
                 if (preview && preview.summary) {
+                    // ── Merge knowledge preview into the combined DryRunResult ──────
+                    if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
+                        const knowledgeDryRun = await computeKnowledgePreview(ctx.knowledge.listUrl(), knowledgeObjects, ctx.branch, shouldDelete, accessToken, verboseFetch, flags.verbose);
+                        mergeKnowledgePreview(preview, knowledgeDryRun);
+                    }
                     renderPreview(preview, shouldDelete, target, flags.verbose, isPartial, log);
                     // Check for bad cross-references using dry-run operations to avoid false positives
                     const badRefs = checkReferences(documentEntries, preview.operations);
@@ -443,7 +499,7 @@ export async function executePush(ctx, target, flags) {
                         }
                         log(ux.colorize('yellow', 'Proceeding anyway due to --force flag.'));
                     }
-                    // Check for actual changes
+                    // Check for actual changes (multidoc + knowledge combined)
                     const hasChanges = Object.values(preview.summary).some((c) => c.created > 0 || c.updated > 0 || (shouldDelete && c.deleted > 0) || c.truncated > 0);
                     // Detect local records
                     const tablesWithRecords = flags.records
@@ -531,6 +587,10 @@ export async function executePush(ctx, target, flags) {
                     await confirmOrAbort(command, log);
                 }
             }
+            else {
+                await handleDryRunError(dryRunResponse, command, flags, target);
+                // If we get here, the user confirmed to proceed without preview
+            }
         }
         catch (error) {
             // Ctrl+C or SIGINT
@@ -552,8 +612,39 @@ export async function executePush(ctx, target, flags) {
             await confirmOrAbort(command, log);
         }
     }
+    else if (knowledgeOnly && (flags['dry-run'] || !flags.force)) {
+        // ── Knowledge-only dry-run / preview ──────────────────────────────────
+        const kPreview = await computeKnowledgePreview(ctx.knowledge.listUrl(), knowledgeObjects, ctx.branch, shouldDelete, accessToken, verboseFetch, flags.verbose);
+        const syntheticResult = {
+            operations: kPreview.operations.map((op) => ({ action: op.action, details: '', name: op.name, type: op.type })),
+            summary: Object.fromEntries(Object.entries(kPreview.summary).map(([type, counts]) => [
+                type,
+                { created: counts.created, deleted: counts.deleted, truncated: 0, unchanged: counts.unchanged, updated: counts.updated },
+            ])),
+        };
+        renderPreview(syntheticResult, shouldDelete, target, flags.verbose, true, log);
+        const hasChanges = Object.values(syntheticResult.summary).some((c) => c.created > 0 || c.updated > 0 || (shouldDelete && c.deleted > 0));
+        if (!hasChanges) {
+            log('');
+            log('No changes to push.');
+            return;
+        }
+        if (flags['dry-run']) {
+            return;
+        }
+        if (process.stdin.isTTY) {
+            const confirmed = await confirm('Proceed with push?');
+            if (!confirmed) {
+                log('Push cancelled.');
+                return;
+            }
+        }
+        else {
+            command.error('Non-interactive environment detected. Use --force to skip confirmation.');
+        }
+    }
     // ── Show bad references in force mode (preview mode shows them inline) ─
-    if (flags.force) {
+    if (flags.force && !knowledgeOnly) {
         const badRefs = checkReferences(documentEntries);
         if (badRefs.length > 0) {
             log('');
@@ -561,96 +652,156 @@ export async function executePush(ctx, target, flags) {
         }
     }
     // ── Partial push: filter to changed documents only ────────────────────
-    if (isPartial && dryRunPreview) {
+    if (!knowledgeOnly && isPartial && dryRunPreview) {
         const filteredEntries = filterChangedEntries(documentEntries, dryRunPreview.operations, flags.records);
-        if (filteredEntries.length === 0) {
+        if (filteredEntries.length === 0 && knowledgeObjects.length === 0) {
             log('No changes to push.');
             return;
         }
-        multidoc = filteredEntries.map((d) => d.content).join('\n---\n');
+        if (filteredEntries.length > 0) {
+            multidoc = filteredEntries.map((d) => d.content).join('\n---\n');
+        }
+        else {
+            multidoc = '';
+        }
     }
     // ── Execute the actual push ───────────────────────────────────────────
-    const apiUrl = target.buildPushUrl(queryParams);
     const startTime = Date.now();
-    try {
-        const response = await verboseFetch(apiUrl, {
-            body: multidoc,
-            headers: requestHeaders,
-            method: 'POST',
-        }, flags.verbose, accessToken);
-        if (!response.ok) {
-            handlePushError(response, await response.text(), documentEntries, inputDir, command);
-        }
-        // Parse response for GUID map
-        const responseText = await response.text();
-        let guidMap = [];
-        if (responseText && responseText !== 'null') {
-            try {
-                const responseJson = JSON.parse(responseText);
-                if (responseJson?.guid_map && Array.isArray(responseJson.guid_map)) {
-                    guidMap = responseJson.guid_map;
-                }
-            }
-            catch {
-                if (flags.verbose) {
-                    log(`Server response is not JSON; skipping GUID sync\n${responseText}`);
-                }
+    let pushedDocCount = 0;
+    if (!knowledgeOnly && multidoc) {
+        const apiUrl = target.buildPushUrl(queryParams);
+        try {
+            const response = await verboseFetch(apiUrl, {
+                body: multidoc,
+                headers: requestHeaders,
+                method: 'POST',
+            }, flags.verbose, accessToken);
+            if (!response.ok) {
+                handlePushError(response, await response.text(), documentEntries, inputDir, command);
             }
-        }
-        // Write GUIDs back to local files
-        if (flags.guids && guidMap.length > 0) {
-            const baseKeyMap = new Map();
-            for (const [key, fp] of documentFileMap) {
-                const baseKey = key.split(':').slice(0, 2).join(':');
-                if (baseKeyMap.has(baseKey)) {
-                    baseKeyMap.set(baseKey, ''); // Mark as ambiguous
+            // Parse response for GUID map
+            const responseText = await response.text();
+            let guidMap = [];
+            if (responseText && responseText !== 'null') {
+                try {
+                    const responseJson = JSON.parse(responseText);
+                    if (responseJson?.guid_map && Array.isArray(responseJson.guid_map)) {
+                        guidMap = responseJson.guid_map;
+                    }
                 }
-                else {
-                    baseKeyMap.set(baseKey, fp);
+                catch {
+                    if (flags.verbose) {
+                        log('Server response is not JSON; skipping GUID sync');
+                    }
                 }
             }
-            let updatedCount = 0;
-            for (const entry of guidMap) {
-                if (!entry.guid)
-                    continue;
-                const key = buildDocumentKey(entry.type, entry.name, entry.verb, entry.api_group);
-                let filePath = documentFileMap.get(key);
-                if (!filePath) {
-                    const baseKey = `${entry.type}:${entry.name}`;
-                    const basePath = baseKeyMap.get(baseKey);
-                    if (basePath) {
-                        filePath = basePath;
+            // Write GUIDs back to local files
+            if (flags.guids && guidMap.length > 0) {
+                const baseKeyMap = new Map();
+                for (const [key, fp] of documentFileMap) {
+                    const baseKey = key.split(':').slice(0, 2).join(':');
+                    if (baseKeyMap.has(baseKey)) {
+                        baseKeyMap.set(baseKey, ''); // Mark as ambiguous
                     }
-                }
-                if (!filePath) {
-                    if (flags.verbose) {
-                        log(`  No local file found for ${entry.type} "${entry.name}", skipping GUID sync`);
+                    else {
+                        baseKeyMap.set(baseKey, fp);
                     }
-                    continue;
                 }
-                try {
-                    const updated = syncGuidToFile(filePath, entry.guid);
-                    if (updated)
-                        updatedCount++;
+                let updatedCount = 0;
+                for (const entry of guidMap) {
+                    if (!entry.guid)
+                        continue;
+                    const key = buildDocumentKey(entry.type, entry.name, entry.verb, entry.api_group);
+                    let filePath = documentFileMap.get(key);
+                    if (!filePath) {
+                        const baseKey = `${entry.type}:${entry.name}`;
+                        const basePath = baseKeyMap.get(baseKey);
+                        if (basePath) {
+                            filePath = basePath;
+                        }
+                    }
+                    if (!filePath) {
+                        if (flags.verbose) {
+                            log(`  No local file found for ${entry.type} "${entry.name}", skipping GUID sync`);
+                        }
+                        continue;
+                    }
+                    try {
+                        const updated = syncGuidToFile(filePath, entry.guid);
+                        if (updated)
+                            updatedCount++;
+                    }
+                    catch (error) {
+                        command.warn(`Failed to sync GUID to ${filePath}: ${error.message}`);
+                    }
                 }
-                catch (error) {
-                    command.warn(`Failed to sync GUID to ${filePath}: ${error.message}`);
+                if (updatedCount > 0) {
+                    log(`Synced ${updatedCount} GUIDs to local files`);
                 }
             }
-            if (updatedCount > 0) {
-                log(`Synced ${updatedCount} GUIDs to local files`);
-            }
+            pushedDocCount = multidoc.split('\n---\n').length;
+        }
+        catch (error) {
+            if (error instanceof Error && 'oclif' in error)
+                throw error;
+            const elapsedMs = Date.now() - startTime;
+            command.error(`Failed to push multidoc: ${describeNetworkError(error, apiUrl, elapsedMs)}`);
         }
     }
-    catch (error) {
-        if (error instanceof Error && 'oclif' in error)
-            throw error;
-        const elapsedMs = Date.now() - startTime;
-        command.error(`Failed to push multidoc: ${describeNetworkError(error, apiUrl, elapsedMs)}`);
+    // ── Push knowledge ────────────────────────────────────────────────────
+    let knowledgeImported = 0;
+    let knowledgeDeleted = 0;
+    if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
+        const listUrl = ctx.knowledge.listUrl();
+        try {
+            const result = await pushKnowledge(listUrl, accessToken, verboseFetch, flags.verbose, {
+                branch: ctx.branch,
+                delete: shouldDelete,
+                force: false,
+                items: toPushItems(knowledgeObjects),
+            });
+            knowledgeImported = result.imported ?? 0;
+            knowledgeDeleted = result.deleted ?? 0;
+            // Write GUIDs back into local frontmatter, matching server entries by name.
+            if (flags.guids && result.guid_map && result.guid_map.length > 0) {
+                const fileByName = new Map(knowledgeObjects.map((o) => [o.name, o.filePath]));
+                let kGuidCount = 0;
+                for (const entry of result.guid_map) {
+                    const filePath = entry.guid && entry.name ? fileByName.get(entry.name) : undefined;
+                    if (!filePath)
+                        continue;
+                    try {
+                        const updated = syncGuidToFrontmatter(filePath, entry.guid);
+                        if (updated)
+                            kGuidCount++;
+                    }
+                    catch (error) {
+                        command.warn(`Failed to sync knowledge GUID to ${filePath}: ${error.message}`);
+                    }
+                }
+                if (kGuidCount > 0) {
+                    log(`Synced ${kGuidCount} knowledge GUIDs to local files`);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof Error && 'oclif' in error)
+                throw error;
+            const elapsedMs = Date.now() - startTime;
+            command.error(`Failed to push knowledge: ${describeNetworkError(error, listUrl, elapsedMs)}`);
+        }
     }
     const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
-    const pushedCount = multidoc.split('\n---\n').length;
-    log(`Pushed ${pushedCount} documents to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
+    const parts = [];
+    if (!knowledgeOnly)
+        parts.push(`${pushedDocCount} documents`);
+    if (ctx.knowledge && (knowledgeObjects.length > 0 || shouldDelete)) {
+        const kParts = [`${knowledgeImported} knowledge file${knowledgeImported === 1 ? '' : 's'}`];
+        if (shouldDelete && knowledgeDeleted > 0)
+            kParts.push(`${knowledgeDeleted} deleted`);
+        parts.push(kParts.join(', '));
+    }
+    log(`Pushed ${parts.join(' + ')} to ${target.label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s`);
 }
 // ── Error Handlers ──────────────────────────────────────────────────────────
 /**
@@ -666,7 +817,7 @@ export async function executePush(ctx, target, flags) {
  * failing — a failure landing near a round boundary (e.g. ~300s) is a strong
  * signal of a server-side or proxy timeout rather than a local network blip.
  */
-function describeNetworkError(error, url, elapsedMs) {
+export function describeNetworkError(error, url, elapsedMs) {
     if (!(error instanceof Error))
         return String(error);
     let host = url;