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

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

@@ -2,6 +2,7 @@ import { Flags } from '@oclif/core';
 import snakeCase from 'lodash.snakecase';
 import BaseCommand from '../../../base-command.js';
 import { buildApiGroupFolderResolver, parseDocument } from '../../../utils/document-parser.js';
+import { fetchKnowledge, writeKnowledge } from '../../../utils/knowledge-sync.js';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 export default class SandboxPull extends BaseCommand {
@@ -87,7 +88,6 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
         }
         if (documents.length === 0) {
             this.log('No documents found in response');
-            return;
         }
         const outputDir = path.resolve(flags.directory);
         fs.mkdirSync(outputDir, { recursive: true });
@@ -182,7 +182,17 @@ Pulled 42 documents from sandbox environment to ./my-sandbox
             fs.writeFileSync(filePath, doc.content, 'utf8');
             writtenCount++;
         }
-        this.log(`Pulled ${writtenCount} documents from sandbox environment to ${flags.directory}`);
+        // ── Pull knowledge ────────────────────────────────────────────────────
+        const knowledgeUrl = `${profile.instance_origin}/api:meta/sandbox/knowledge/sync`;
+        const knowledgeObjects = await fetchKnowledge(knowledgeUrl, '', profile.access_token, this.verboseFetch.bind(this), flags.verbose);
+        let knowledgeCount = 0;
+        if (knowledgeObjects.length > 0) {
+            knowledgeCount = writeKnowledge(knowledgeObjects, outputDir);
+        }
+        const parts = [`${writtenCount} documents`];
+        if (knowledgeCount > 0)
+            parts.push(`${knowledgeCount} knowledge file${knowledgeCount === 1 ? '' : 's'}`);
+        this.log(`Pulled ${parts.join(' + ')} from sandbox environment to ${flags.directory}`);
     }
     sanitizeFilename(name) {
         return snakeCase(name.replaceAll('"', ''));

package/dist/commands/sandbox/push/index.d.ts

@@ -19,6 +19,6 @@ export default class SandboxPush extends BaseCommand {
         verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
     };
     run(): Promise<void>;
-    private openReview;
     private getFrontendUrl;
+    private openReview;
 }

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

@@ -130,12 +130,29 @@ Push and open sandbox review in the browser
             branch: '',
             command: this,
             inputDir,
+            knowledge: {
+                listUrl: () => `${baseUrl}/knowledge/sync`,
+                rootDir: inputDir,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
         if (flags.review) {
             await this.openReview(profile.instance_origin, profile.access_token, flags.verbose);
         }
     }
+    getFrontendUrl(instanceOrigin) {
+        try {
+            const url = new URL(instanceOrigin);
+            if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
+                url.port = '4200';
+                return url.origin;
+            }
+        }
+        catch {
+            // fall through
+        }
+        return instanceOrigin;
+    }
     async openReview(instanceOrigin, accessToken, verbose) {
         const response = await this.verboseFetch(`${instanceOrigin}/api:meta/sandbox/impersonate`, {
             headers: {
@@ -158,17 +175,4 @@ Push and open sandbox review in the browser
         this.log('Opening sandbox review...');
         await open(reviewUrl);
     }
-    getFrontendUrl(instanceOrigin) {
-        try {
-            const url = new URL(instanceOrigin);
-            if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
-                url.port = '4200';
-                return url.origin;
-            }
-        }
-        catch {
-            // fall through
-        }
-        return instanceOrigin;
-    }
 }

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

@@ -4,11 +4,12 @@ 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 { 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';
     static examples = [
         `$ xano workspace pull
-Pulled 42 documents to current directory
+Pulled 42 documents + 5 knowledge files to current directory
 `,
         `$ xano workspace pull -d ./my-workspace
 Pulled 42 documents to ./my-workspace
@@ -239,7 +240,17 @@ Pulled 58 documents
             fs.writeFileSync(filePath, doc.content, 'utf8');
             writtenCount++;
         }
-        this.log(`Pulled ${writtenCount} documents to ${flags.directory}`);
+        // ── Pull knowledge ────────────────────────────────────────────────────
+        const knowledgeUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/knowledge/sync`;
+        const knowledgeObjects = await fetchKnowledge(knowledgeUrl, branch, profile.access_token, this.verboseFetch.bind(this), flags.verbose);
+        let knowledgeCount = 0;
+        if (knowledgeObjects.length > 0) {
+            knowledgeCount = writeKnowledge(knowledgeObjects, outputDir);
+        }
+        const parts = [`${writtenCount} documents`];
+        if (knowledgeCount > 0)
+            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.

package/dist/commands/workspace/push/index.d.ts

@@ -4,8 +4,8 @@ export default class Push extends BaseCommand {
     static examples: string[];
     static flags: {
         branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         delete: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        directory: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         env: import("@oclif/core/interfaces").BooleanFlag<boolean>;
         exclude: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;

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

@@ -53,6 +53,12 @@ Push all files except tables
 `,
         `$ xano workspace push -i "function/*" -e "**/test*"
 Push functions but exclude test files
+`,
+        `$ xano workspace push -i "knowledge/**"
+Push only knowledge files (agents.md / skills / docs)
+`,
+        `$ xano workspace push --sync --delete
+Full sync including knowledge files; removes server objects not present locally
 `,
     ];
     static flags = {
@@ -62,17 +68,17 @@ Push functions but exclude test files
             description: 'Branch name (optional if set in profile, defaults to live)',
             required: false,
         }),
+        delete: Flags.boolean({
+            default: false,
+            description: '[CRITICAL] STOP and confirm with the user before running. Delete workspace objects not included in the push (requires --sync).',
+            required: false,
+        }),
         directory: Flags.string({
             char: 'd',
             default: '.',
             description: 'Directory containing documents to push (defaults to current directory)',
             required: false,
         }),
-        delete: Flags.boolean({
-            default: false,
-            description: '[CRITICAL] STOP and confirm with the user before running. Delete workspace 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)',
@@ -186,6 +192,10 @@ Push functions but exclude test files
             branch,
             command: this,
             inputDir,
+            knowledge: {
+                listUrl: () => `${baseUrl}/knowledge/sync`,
+                rootDir: inputDir,
+            },
             verboseFetch: this.verboseFetch.bind(this),
         }, target, pushFlags);
     }

package/dist/utils/knowledge-sync.d.ts

@@ -0,0 +1,113 @@
+export declare const KNOWLEDGE_DIR = "knowledge";
+export type KnowledgeType = 'agents.md' | 'doc' | 'skill';
+/** A reference file attached to a skill (knowledge_file). */
+export interface KnowledgeFile {
+    content: string;
+    /** Path relative to the skill's `references/` folder, POSIX-separated. */
+    name: string;
+}
+/** A workspace-scoped knowledge object as exchanged with the API. */
+export interface KnowledgeObject {
+    content: string;
+    description?: string;
+    enabled?: boolean;
+    files?: KnowledgeFile[];
+    guid?: string;
+    knowledge_type: KnowledgeType;
+    mode?: string;
+    name: string;
+    scope?: string;
+}
+/** A locally-collected object that also remembers its primary file on disk (for GUID writeback). */
+export interface LocalKnowledgeObject extends KnowledgeObject {
+    filePath: string;
+}
+export interface KnowledgePushBody {
+    branch?: string;
+    delete?: boolean;
+    dry_run?: boolean;
+    force?: boolean;
+    items: KnowledgeObject[];
+}
+export interface KnowledgePushResult {
+    deleted?: number;
+    guid_map?: Array<{
+        guid: string;
+        name: string;
+    }>;
+    imported?: number;
+    operations?: KnowledgeDryRunOperation[];
+    summary?: Record<string, KnowledgeDryRunSummary>;
+}
+export interface KnowledgeDryRunOperation {
+    action: string;
+    name: string;
+    type: string;
+}
+export interface KnowledgeDryRunSummary {
+    created: number;
+    deleted: number;
+    unchanged: number;
+    updated: number;
+}
+export interface KnowledgeDryRunResult {
+    operations: KnowledgeDryRunOperation[];
+    summary: Record<string, KnowledgeDryRunSummary>;
+}
+type VerboseFetch = (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
+/**
+ * Build a primary `.md` file body: YAML frontmatter (built from the object's
+ * structured fields) followed by the markdown content.
+ */
+export declare function buildPrimaryContent(obj: KnowledgeObject): string;
+/**
+ * Split a primary `.md` file into its frontmatter fields and markdown body.
+ * Returns `{meta: {}, body: <raw>}` when there is no leading `---` block.
+ */
+export declare function parsePrimaryContent(raw: string): {
+    body: string;
+    meta: Record<string, unknown>;
+};
+/** Read just `guid`/`name` from frontmatter (used by GUID matching). */
+export declare function parseFrontmatter(content: string): {
+    guid?: string;
+    name?: string;
+};
+/**
+ * Write knowledge objects under `<outputDir>/knowledge/`, building frontmatter
+ * and laying out skill reference files under `<skill>/references/`.
+ * Returns the number of files written (primaries + references).
+ */
+export declare function writeKnowledge(objects: KnowledgeObject[], outputDir: string): number;
+/**
+ * Walk `<inputDir>/knowledge/`, reconstructing structured knowledge objects from
+ * primary `.md` files (frontmatter → fields, body → content) and attaching each
+ * skill's `references/` files. Include/exclude globs are matched against
+ * `knowledge/<path>` (relative to inputDir), consistent with multidoc filtering.
+ * Returns `[]` when the directory is absent.
+ */
+export declare function collectKnowledgeObjects(inputDir: string, include?: string[], exclude?: string[]): LocalKnowledgeObject[];
+/** Strip the local-only `filePath` before sending objects to the API. */
+export declare function toPushItems(objects: LocalKnowledgeObject[]): KnowledgeObject[];
+/**
+ * GET workspace knowledge objects (with content). Returns `[]` on 404 (instance
+ * without the feature) or any network error, so pull degrades gracefully.
+ */
+export declare function fetchKnowledge(baseUrl: string, branch: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean): Promise<KnowledgeObject[]>;
+/**
+ * POST knowledge objects to the workspace. Throws on non-2xx. When `body.dry_run`
+ * is set the result may carry `operations`/`summary` instead of `imported`.
+ */
+export declare function pushKnowledge(url: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean, body: KnowledgePushBody): Promise<KnowledgePushResult>;
+/**
+ * Compute a dry-run-style preview by diffing local objects against server
+ * objects (match by `guid`, then `name`). Used when the server doesn't honor
+ * the `dry_run` flag.
+ */
+export declare function knowledgePreview(local: KnowledgeObject[], server: KnowledgeObject[], willDelete: boolean): KnowledgeDryRunResult;
+/**
+ * Set or update `guid:` in a primary `.md` file's YAML frontmatter.
+ * Returns true if the file was modified.
+ */
+export declare function syncGuidToFrontmatter(filePath: string, guid: string): boolean;
+export {};