@xano/cli 1.0.4-beta.3 → 1.0.4

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

@@ -0,0 +1,86 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import BaseCommand from '../../../base-command.js';
+import { fetchKnowledgeList, safeKnowledgePath } from '../../../utils/knowledge-sync.js';
+export default class KnowledgePull extends BaseCommand {
+    static description = 'Pull knowledge files from a workspace. Each knowledge item name is a path (e.g. "some/thing/CLAUDE.md") and its content is written to that path under the output directory.';
+    static examples = [
+        `$ xano knowledge pull
+Pulled 4 knowledge files to current directory
+`,
+        `$ xano knowledge pull -d ./knowledge
+Pulled 4 knowledge files to ./knowledge
+`,
+        `$ xano knowledge pull -d ./knowledge -w 40`,
+        `$ xano knowledge pull -b dev`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            char: 'b',
+            description: 'Branch name (optional if set in profile, defaults to live)',
+            required: false,
+        }),
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: 'Output directory for pulled knowledge files (defaults to current directory)',
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(KnowledgePull);
+        const { profile, profileName } = this.resolveProfile(flags);
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano knowledge pull -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        const branch = flags.branch || profile.branch || '';
+        let items;
+        try {
+            items = await fetchKnowledgeList({
+                accessToken: profile.access_token,
+                branch,
+                instanceOrigin: profile.instance_origin,
+                verboseFetch: this.verboseFetch.bind(this),
+                workspaceId,
+            }, flags.verbose);
+        }
+        catch (error) {
+            this.error(`Failed to fetch knowledge: ${error.message}`);
+        }
+        if (items.length === 0) {
+            this.log('No knowledge found in workspace');
+            return;
+        }
+        const outputDir = resolve(flags.directory);
+        fs.mkdirSync(outputDir, { recursive: true });
+        let writtenCount = 0;
+        for (const item of items) {
+            const filePath = safeKnowledgePath(outputDir, item.name);
+            if (!filePath) {
+                this.warn(`Skipping knowledge "${item.name}": name is not a safe relative path`);
+                continue;
+            }
+            fs.mkdirSync(dirname(filePath), { recursive: true });
+            fs.writeFileSync(filePath, item.content ?? '', 'utf8');
+            writtenCount++;
+        }
+        this.log(`Pulled ${writtenCount} knowledge files to ${flags.directory}`);
+    }
+}

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

@@ -0,0 +1,20 @@
+import BaseCommand from '../../../base-command.js';
+export default class KnowledgePush extends BaseCommand {
+    static description: string;
+    static examples: string[];
+    static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, 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>;
+        exclude: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        include: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        sync: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        profile: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        verbose: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<void>;
+}

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

@@ -0,0 +1,126 @@
+import { Flags } from '@oclif/core';
+import * as fs from 'node:fs';
+import { resolve } from 'node:path';
+import BaseCommand from '../../../base-command.js';
+import { executeKnowledgePush } from '../../../utils/knowledge-sync.js';
+export default class KnowledgePush extends BaseCommand {
+    static description = '[IMPORTANT] ALWAYS run --dry-run first and show the user the output before pushing. Push local knowledge files to a workspace. Each file becomes a knowledge item named by its relative path (e.g. "some/thing/CLAUDE.md"). By default, only changed files are pushed (partial mode). Use --sync to compare all files (required for --delete). Shows a preview of changes before pushing unless --force is specified. Use --dry-run to preview only.';
+    static examples = [
+        `$ xano knowledge push
+Push from current directory (default partial mode)
+`,
+        `$ xano knowledge push -d ./knowledge
+Push from a specific directory
+`,
+        `$ xano knowledge push --dry-run
+Preview changes without pushing
+`,
+        `$ xano knowledge push --sync --delete
+Push all files and delete remote knowledge not included
+`,
+        `$ xano knowledge push --force
+Skip preview and push immediately (for CI/CD)
+`,
+        `$ xano knowledge push -i "guides/*"
+Push only files matching the glob pattern
+`,
+        `$ xano knowledge push -e "**/README.md"
+Push all files except READMEs
+`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            char: 'b',
+            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 remote knowledge not included in the push (requires --sync).',
+            required: false,
+        }),
+        directory: Flags.string({
+            char: 'd',
+            default: '.',
+            description: 'Directory containing knowledge files to push (defaults to current directory)',
+            required: false,
+        }),
+        'dry-run': Flags.boolean({
+            default: false,
+            description: 'Show preview of changes without pushing (exit after preview)',
+            required: false,
+        }),
+        exclude: Flags.string({
+            char: 'e',
+            description: 'Glob pattern to exclude files (e.g. "**/README.md"). Matched against relative paths from the push directory.',
+            multiple: true,
+            required: false,
+        }),
+        force: Flags.boolean({
+            default: false,
+            description: '[CRITICAL] NEVER run without explicit user confirmation. Skips preview and confirmation prompt (for CI/CD pipelines).',
+            required: false,
+        }),
+        include: Flags.string({
+            char: 'i',
+            description: 'Glob pattern to include files (e.g. "guides/*"). Matched against relative paths from the push directory.',
+            multiple: true,
+            required: false,
+        }),
+        sync: Flags.boolean({
+            default: false,
+            description: 'Full push — compare all files, not just changed ones. Required for --delete.',
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { flags } = await this.parse(KnowledgePush);
+        const { profile, profileName } = this.resolveProfile(flags);
+        // Determine workspace_id from flag or profile
+        let workspaceId;
+        if (flags.workspace) {
+            workspaceId = flags.workspace;
+        }
+        else if (profile.workspace) {
+            workspaceId = profile.workspace;
+        }
+        else {
+            this.error(`Workspace ID is required. Either:\n` +
+                `  1. Provide it as a flag: xano knowledge push -w <workspace_id>\n` +
+                `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+        }
+        const inputDir = resolve(flags.directory);
+        if (!fs.existsSync(inputDir)) {
+            this.error(`Directory not found: ${inputDir}`);
+        }
+        if (!fs.statSync(inputDir).isDirectory()) {
+            this.error(`Not a directory: ${inputDir}`);
+        }
+        const branch = flags.branch || profile.branch || '';
+        const pushFlags = {
+            delete: flags.delete,
+            'dry-run': flags['dry-run'],
+            exclude: flags.exclude,
+            force: flags.force,
+            include: flags.include,
+            sync: flags.sync,
+            verbose: flags.verbose,
+        };
+        await executeKnowledgePush({
+            accessToken: profile.access_token,
+            branch,
+            cliVersion: this.config.version,
+            command: this,
+            inputDir,
+            instanceOrigin: profile.instance_origin,
+            verboseFetch: this.verboseFetch.bind(this),
+            workspaceId,
+        }, pushFlags);
+    }
+}

package/dist/commands/static_host/build/create/index.d.ts

@@ -1,12 +1,5 @@
 import BaseCommand from '../../../../base-command.js';
-/**
- * Generate a default build name from a compact timestamp: `YYYYMMDD-HHmmss`
- * (e.g. `20260531-143022`). Sortable, distinct down to the second, and uses
- * local time so it lines up with when the user ran the command.
- */
-export declare function generateBuildName(date?: Date): string;
 export default class StaticHostBuildCreate extends BaseCommand {
-    static hidden: boolean;
     static args: {
         static_host: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
@@ -15,8 +8,7 @@ export default class StaticHostBuildCreate extends BaseCommand {
     static flags: {
         description: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         file: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
-        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
-        'no-wait': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        name: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/static_host/build/create/index.js

@@ -2,42 +2,20 @@ import { Args, Flags } from '@oclif/core';
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import BaseCommand from '../../../../base-command.js';
-const pad2 = (n) => String(n).padStart(2, '0');
-/**
- * Generate a default build name from a compact timestamp: `YYYYMMDD-HHmmss`
- * (e.g. `20260531-143022`). Sortable, distinct down to the second, and uses
- * local time so it lines up with when the user ran the command.
- */
-export function generateBuildName(date = new Date()) {
-    const y = date.getFullYear();
-    const mo = pad2(date.getMonth() + 1);
-    const d = pad2(date.getDate());
-    const h = pad2(date.getHours());
-    const mi = pad2(date.getMinutes());
-    const s = pad2(date.getSeconds());
-    return `${y}${mo}${d}-${h}${mi}${s}`;
-}
 export default class StaticHostBuildCreate extends BaseCommand {
-    static hidden = true;
     static args = {
         static_host: Args.string({
             description: 'Static Host name',
             required: true,
         }),
     };
-    static description = '[Deprecated: use "static_host build push -f <file>" instead] Create a new build from a zip file';
+    static description = 'Create a new build for a static host';
     static examples = [
         `$ xano static_host:build:create default -f ./build.zip -n "v1.0.0"
 Build created successfully!
 ID: 123
 Name: v1.0.0
 Status: pending
-`,
-        `$ xano static_host:build:create default -f ./build.zip
-Build created successfully!
-ID: 123
-Name: 20260531-143022
-Status: pending
 `,
         `$ xano static_host:build:create default -w 40 -f ./dist.zip -n "production" -d "Production build"
 Build created successfully!
@@ -67,13 +45,8 @@ Description: Production build
         }),
         name: Flags.string({
             char: 'n',
-            description: 'Build name (auto-generated from the current timestamp if omitted)',
-            required: false,
-        }),
-        'no-wait': Flags.boolean({
-            default: false,
-            description: 'Return immediately after upload instead of waiting for the build to finish',
-            required: false,
+            description: 'Build name',
+            required: true,
         }),
         output: Flags.string({
             char: 'o',
@@ -89,7 +62,6 @@ Description: Production build
         }),
     };
     async run() {
-        this.warn('`static_host build create` is deprecated. Use `static_host build push -f <file>` instead.');
         const { args, flags } = await this.parse(StaticHostBuildCreate);
         const { profile, profileName } = this.resolveProfile(flags);
         // Determine workspace_id from flag or profile
@@ -130,10 +102,7 @@ Description: Production build
         const fileBuffer = fs.readFileSync(filePath);
         const blob = new Blob([fileBuffer], { type: 'application/zip' });
         formData.append('file', blob, path.basename(filePath));
-        // Name is optional — fall back to a timestamped name so builds can be
-        // created without thinking up a label each time.
-        const buildName = flags.name ?? generateBuildName();
-        formData.append('name', buildName);
+        formData.append('name', flags.name);
         if (flags.description) {
             formData.append('description', flags.description);
         }
@@ -172,25 +141,6 @@ Description: Production build
                     this.log(`Description: ${flags.description}`);
                 }
             }
-            // Async (package.json) builds keep running after upload. Unless --no-wait,
-            // poll until the build finishes so the CLI mirrors the UI's progress.
-            const inProgress = result.status !== undefined && !['error', 'ok'].includes(result.status);
-            if (inProgress && !flags['no-wait']) {
-                const finalStatus = await this.waitForBuild({
-                    buildId: result.id,
-                    profile,
-                    quiet: flags.output === 'json',
-                    staticHost: args.static_host,
-                    verbose: flags.verbose,
-                    workspaceId,
-                });
-                if (finalStatus === 'error') {
-                    this.error(`Build ${result.id} failed (status: error). Check the build log with: xano static_host build get ${args.static_host} --build_id ${result.id}`);
-                }
-            }
-            if (flags.output !== 'json') {
-                await this.logStaticHostUrls({ profile, staticHost: args.static_host, verbose: flags.verbose, workspaceId });
-            }
         }
         catch (error) {
             if (error instanceof Error) {

package/dist/commands/static_host/build/get/index.d.ts

@@ -1,12 +1,12 @@
 import BaseCommand from '../../../../base-command.js';
 export default class StaticHostBuildGet extends BaseCommand {
     static args: {
+        build_id: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
         static_host: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
     };
     static description: string;
     static examples: string[];
     static flags: {
-        build_id: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         workspace: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
         config: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;

package/dist/commands/static_host/build/get/index.js

@@ -2,6 +2,10 @@ import { Args, Flags } from '@oclif/core';
 import BaseCommand from '../../../../base-command.js';
 export default class StaticHostBuildGet extends BaseCommand {
     static args = {
+        build_id: Args.string({
+            description: 'Build ID',
+            required: true,
+        }),
         static_host: Args.string({
             description: 'Static Host name',
             required: true,
@@ -9,24 +13,24 @@ export default class StaticHostBuildGet extends BaseCommand {
     };
     static description = 'Get details of a specific build for a static host';
     static examples = [
-        `$ xano static_host:build:get default --build_id 52
+        `$ xano static_host:build:get default 52
 Build Details:
 ID: 52
 Name: v1.0.0
 Status: completed
 `,
-        `$ xano static_host:build:get default --build_id 52 -w 40
+        `$ xano static_host:build:get default 52 -w 40
 Build Details:
 ID: 52
 Name: v1.0.0
 Status: completed
 `,
-        `$ xano static_host:build:get myhost --build_id 123 --profile production
+        `$ xano static_host:build:get myhost 123 --profile production
 Build Details:
 ID: 123
 Name: production-build
 `,
-        `$ xano static_host:build:get default --build_id 52 -o json
+        `$ xano static_host:build:get default 52 -o json
 {
   "id": 52,
   "name": "v1.0.0",
@@ -36,10 +40,6 @@ Name: production-build
     ];
     static flags = {
         ...BaseCommand.baseFlags,
-        build_id: Flags.string({
-            description: 'Build ID',
-            required: true,
-        }),
         output: Flags.string({
             char: 'o',
             default: 'summary',
@@ -66,11 +66,11 @@ Name: production-build
         }
         else {
             this.error(`Workspace ID is required. Either:\n` +
-                `  1. Provide it as a flag: xano static_host:build:get <static_host> --build_id <id> -w <workspace_id>\n` +
+                `  1. Provide it as a flag: xano static_host:build:get <static_host> <build_id> -w <workspace_id>\n` +
                 `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
         }
         // Construct the API URL
-        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${args.static_host}/build/${flags.build_id}`;
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/static_host/${args.static_host}/build/${args.build_id}`;
         // Fetch build from the API
         try {
             const response = await this.verboseFetch(apiUrl, {
@@ -104,12 +104,6 @@ Name: production-build
                 if (build.status) {
                     this.log(`Status: ${build.status}`);
                 }
-                if (typeof build.file_count === 'number') {
-                    this.log(`Files: ${build.file_count}`);
-                }
-                if (typeof build.file_bytes === 'number') {
-                    this.log(`Size: ${build.file_bytes} bytes`);
-                }
                 if (build.created_at) {
                     this.log(`Created: ${build.created_at}`);
                 }

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

@@ -0,0 +1,108 @@
+import { Command } from '@oclif/core';
+/** A knowledge record as returned by the Metadata API list endpoint. */
+export interface KnowledgeItem {
+    branch?: {
+        id: number;
+    };
+    content?: string;
+    description?: string;
+    enabled?: boolean;
+    id: number;
+    knowledge_type?: string;
+    mode?: string;
+    name: string;
+    references?: string[];
+    scope?: string;
+    tag?: string[];
+}
+/** A local knowledge file: its API name (relative path) and content. */
+export interface LocalKnowledgeEntry {
+    content: string;
+    filePath: string;
+    name: string;
+}
+export interface KnowledgePlan {
+    creates: LocalKnowledgeEntry[];
+    deletes: KnowledgeItem[];
+    unchanged: Array<{
+        entry: LocalKnowledgeEntry;
+        remote: KnowledgeItem;
+    }>;
+    updates: Array<{
+        entry: LocalKnowledgeEntry;
+        remote: KnowledgeItem;
+    }>;
+}
+export interface KnowledgePushFlags {
+    delete: boolean;
+    'dry-run': boolean;
+    exclude?: string[];
+    force: boolean;
+    include?: string[];
+    sync: boolean;
+    verbose: boolean;
+}
+export interface KnowledgeApiContext {
+    accessToken: string;
+    /** Branch name ('' = live branch) */
+    branch: string;
+    instanceOrigin: string;
+    verboseFetch: (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
+    workspaceId: string;
+}
+export interface KnowledgePushContext extends KnowledgeApiContext {
+    cliVersion: string;
+    command: Command;
+    inputDir: string;
+}
+export declare const MAX_NAME_LENGTH = 200;
+/**
+ * Validate a knowledge name (a relative path like "some/thing/CLAUDE.md")
+ * against the Metadata API's accepted character set and length.
+ * Returns null when valid, otherwise a human-readable reason.
+ */
+export declare function validateKnowledgeName(name: string): null | string;
+/**
+ * Resolve a knowledge name to a local file path inside baseDir, rejecting
+ * names that would escape it (absolute paths, "..", etc.).
+ * Returns null when the name is unsafe.
+ */
+export declare function safeKnowledgePath(baseDir: string, name: null | string | undefined): null | string;
+/**
+ * Infer the knowledge_type for a newly created knowledge item from its
+ * filename. AGENTS.md and SKILL.md are special-cased; everything else is a doc.
+ */
+export declare function inferKnowledgeType(name: string): string;
+/**
+ * Recursively collect all files under a directory, skipping hidden files,
+ * hidden directories, and node_modules. Sorted for deterministic ordering.
+ */
+export declare function collectKnowledgeFiles(dir: string): string[];
+/**
+ * Read local files into knowledge entries. The knowledge name is the path
+ * relative to inputDir, using forward slashes.
+ */
+export declare function readKnowledgeEntries(files: string[], inputDir: string): LocalKnowledgeEntry[];
+/**
+ * Compute the create/update/delete plan by matching local entries against
+ * remote knowledge items by name.
+ */
+export declare function buildKnowledgePlan(localEntries: LocalKnowledgeEntry[], remoteItems: KnowledgeItem[]): KnowledgePlan;
+export declare function renderKnowledgePreview(plan: KnowledgePlan, opts: {
+    cliVersion: string;
+    instanceOrigin: string;
+    label: string;
+    partial: boolean;
+    willDelete: boolean;
+}, log: (msg: string) => void): void;
+/**
+ * Fetch all knowledge items (with content) for a workspace/branch.
+ */
+export declare function fetchKnowledgeList(ctx: KnowledgeApiContext, verbose: boolean): Promise<KnowledgeItem[]>;
+/**
+ * Execute a knowledge push: collect local files, diff against remote by name,
+ * preview, confirm, then apply creates/updates/deletes through the Metadata API.
+ * Mirrors the UX of `workspace push` (partial by default, --sync for full,
+ * --delete to remove remote-only items, --dry-run / --force).
+ */
+export declare function executeKnowledgePush(ctx: KnowledgePushContext, flags: KnowledgePushFlags): Promise<void>;