@xano/cli 1.0.4-beta.2 → 1.0.4

package/dist/utils/knowledge-sync.js

@@ -0,0 +1,380 @@
+import { ux } from '@oclif/core';
+import * as fs from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { applyFilters, confirm } from './multidoc-push.js';
+// ── Name & Path Safety ──────────────────────────────────────────────────────
+// Mirrors the Metadata API's name filter: text|min(1)|max(200)|alphaOk|digitOk|ok("/_-{}. ")
+const NAME_PATTERN = /^[\w/{}. -]+$/;
+export 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 function validateKnowledgeName(name) {
+    if (!name || name.trim() === '') {
+        return 'name is empty';
+    }
+    if (name.length > MAX_NAME_LENGTH) {
+        return `name exceeds ${MAX_NAME_LENGTH} characters`;
+    }
+    if (!NAME_PATTERN.test(name)) {
+        return 'name contains unsupported characters (allowed: letters, digits, "/_-{}. ")';
+    }
+    return null;
+}
+/**
+ * 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 function safeKnowledgePath(baseDir, name) {
+    // Normalize: knowledge names always use forward slashes
+    if (!name || name.startsWith('/') || name.includes('\\')) {
+        return null;
+    }
+    const segments = name.split('/');
+    if (segments.some((s) => s === '' || s === '.' || s === '..')) {
+        return null;
+    }
+    const base = resolve(baseDir);
+    const target = resolve(base, ...segments);
+    if (target !== base && !target.startsWith(base + sep)) {
+        return null;
+    }
+    return target;
+}
+/**
+ * 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 function inferKnowledgeType(name) {
+    const basename = name.split('/').pop()?.toLowerCase() ?? '';
+    if (basename === 'agents.md')
+        return 'agents.md';
+    if (basename === 'skill.md')
+        return 'skill';
+    return 'doc';
+}
+// ── File Collection ─────────────────────────────────────────────────────────
+const SKIPPED_DIRECTORIES = new Set(['node_modules']);
+/**
+ * Recursively collect all files under a directory, skipping hidden files,
+ * hidden directories, and node_modules. Sorted for deterministic ordering.
+ */
+export function collectKnowledgeFiles(dir) {
+    const files = [];
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.name.startsWith('.'))
+            continue;
+        const fullPath = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (SKIPPED_DIRECTORIES.has(entry.name))
+                continue;
+            files.push(...collectKnowledgeFiles(fullPath));
+        }
+        else if (entry.isFile()) {
+            files.push(fullPath);
+        }
+    }
+    return files.sort();
+}
+/**
+ * Read local files into knowledge entries. The knowledge name is the path
+ * relative to inputDir, using forward slashes.
+ */
+export function readKnowledgeEntries(files, inputDir) {
+    return files.map((filePath) => ({
+        content: fs.readFileSync(filePath, 'utf8'),
+        filePath,
+        name: relative(inputDir, filePath).split(sep).join('/'),
+    }));
+}
+// ── Diff Plan ───────────────────────────────────────────────────────────────
+/**
+ * Compute the create/update/delete plan by matching local entries against
+ * remote knowledge items by name.
+ */
+export function buildKnowledgePlan(localEntries, remoteItems) {
+    const remoteByName = new Map();
+    for (const item of remoteItems) {
+        remoteByName.set(item.name, item);
+    }
+    const plan = { creates: [], deletes: [], unchanged: [], updates: [] };
+    const localNames = new Set();
+    for (const entry of localEntries) {
+        localNames.add(entry.name);
+        const remote = remoteByName.get(entry.name);
+        if (!remote) {
+            plan.creates.push(entry);
+        }
+        else if ((remote.content ?? '') === entry.content) {
+            plan.unchanged.push({ entry, remote });
+        }
+        else {
+            plan.updates.push({ entry, remote });
+        }
+    }
+    for (const item of remoteItems) {
+        if (!localNames.has(item.name)) {
+            plan.deletes.push(item);
+        }
+    }
+    return plan;
+}
+// ── Preview Rendering ───────────────────────────────────────────────────────
+export function renderKnowledgePreview(plan, opts, log) {
+    log('');
+    log(ux.colorize('bold', `=== Push Preview: ${opts.label} ===`));
+    let instanceHost = opts.instanceOrigin;
+    try {
+        instanceHost = new URL(opts.instanceOrigin).hostname;
+    }
+    catch { }
+    log(ux.colorize('dim', `  instance: ${instanceHost}  |  cli: v${opts.cliVersion}`));
+    log('');
+    const parts = [];
+    if (plan.creates.length > 0) {
+        parts.push(ux.colorize('green', `+${plan.creates.length} created`));
+    }
+    if (plan.updates.length > 0) {
+        parts.push(ux.colorize('yellow', `~${plan.updates.length} updated`));
+    }
+    if (opts.willDelete && plan.deletes.length > 0) {
+        parts.push(ux.colorize('red', `-${plan.deletes.length} deleted`));
+    }
+    if (parts.length > 0) {
+        log(`  ${'Knowledge'.padEnd(20)} ${parts.join('  ')}`);
+    }
+    if (plan.creates.length > 0 || plan.updates.length > 0) {
+        log('');
+        log(ux.colorize('bold', '--- Changes ---'));
+        log('');
+        for (const entry of plan.creates) {
+            log(`  ${ux.colorize('green', 'CREATE'.padEnd(16))} ${'knowledge'.padEnd(18)} ${entry.name}`);
+        }
+        for (const { entry } of plan.updates) {
+            log(`  ${ux.colorize('yellow', 'UPDATE'.padEnd(16))} ${'knowledge'.padEnd(18)} ${entry.name}`);
+        }
+    }
+    if (opts.willDelete && plan.deletes.length > 0) {
+        log('');
+        log(ux.colorize('bold', '--- Destructive Operations ---'));
+        log('');
+        for (const item of plan.deletes) {
+            log(`  ${ux.colorize('red', 'DELETE'.padEnd(16))} ${'knowledge'.padEnd(18)} ${item.name}`);
+        }
+    }
+    // Show remote-only items when not deleting (full sync only, to match workspace push)
+    if (!opts.willDelete && !opts.partial && plan.deletes.length > 0) {
+        log('');
+        log(ux.colorize('dim', '--- Remote Only (not included in push) ---'));
+        log('');
+        for (const item of plan.deletes) {
+            log(ux.colorize('dim', `  ${'knowledge'.padEnd(18)} ${item.name}`));
+        }
+        log('');
+        log(ux.colorize('dim', `  Use --delete to remove these ${plan.deletes.length} item(s) from remote.`));
+    }
+    log('');
+}
+// ── API Calls ───────────────────────────────────────────────────────────────
+function knowledgeUrl(ctx, suffix = '') {
+    return `${ctx.instanceOrigin}/api:meta/workspace/${ctx.workspaceId}/knowledge${suffix}`;
+}
+function jsonHeaders(accessToken) {
+    return {
+        accept: 'application/json',
+        Authorization: `Bearer ${accessToken}`,
+        'Content-Type': 'application/json',
+    };
+}
+/**
+ * Fetch all knowledge items (with content) for a workspace/branch.
+ */
+export async function fetchKnowledgeList(ctx, verbose) {
+    // eslint-disable-next-line camelcase
+    const queryParams = new URLSearchParams({ include_content: 'true' });
+    if (ctx.branch) {
+        queryParams.set('branch', ctx.branch);
+    }
+    const response = await ctx.verboseFetch(`${knowledgeUrl(ctx)}?${queryParams.toString()}`, { headers: jsonHeaders(ctx.accessToken), method: 'GET' }, verbose, ctx.accessToken);
+    if (!response.ok) {
+        const errorText = await response.text();
+        throw new Error(`failed to list knowledge (${response.status}): ${errorText}`);
+    }
+    const data = (await response.json());
+    const items = Array.isArray(data) ? data : data && Array.isArray(data.items) ? data.items : null;
+    if (!items) {
+        throw new Error('unexpected response format from knowledge list endpoint');
+    }
+    // Records without a name can't be matched to a local file path, so they are
+    // invisible to push/pull (the API also rejects updates/deletes on them).
+    return items.filter((item) => typeof item.name === 'string' && item.name !== '');
+}
+// ── Main Push Logic ─────────────────────────────────────────────────────────
+/**
+ * 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 async function executeKnowledgePush(ctx, flags) {
+    const { command, inputDir } = ctx;
+    const log = command.log.bind(command);
+    // ── Resolve push mode ─────────────────────────────────────────────────
+    const isPartial = !flags.sync;
+    if (flags.delete && isPartial) {
+        command.error('Cannot use --delete without --sync');
+    }
+    const shouldDelete = isPartial ? false : flags.delete;
+    // ── Collect, filter, and validate local files ─────────────────────────
+    const entries = collectLocalKnowledge(command, inputDir, flags);
+    // ── Diff against remote ───────────────────────────────────────────────
+    let remoteItems = [];
+    try {
+        remoteItems = await fetchKnowledgeList(ctx, flags.verbose);
+    }
+    catch (error) {
+        command.error(`Failed to fetch remote knowledge: ${error.message}`);
+    }
+    const plan = buildKnowledgePlan(entries, remoteItems);
+    const label = `knowledge in workspace ${ctx.workspaceId}`;
+    // ── Preview & confirm ─────────────────────────────────────────────────
+    if (flags['dry-run'] || !flags.force) {
+        renderKnowledgePreview(plan, {
+            cliVersion: ctx.cliVersion,
+            instanceOrigin: ctx.instanceOrigin,
+            label,
+            partial: isPartial,
+            willDelete: shouldDelete,
+        }, log);
+    }
+    const hasChanges = plan.creates.length > 0 || plan.updates.length > 0 || (shouldDelete && plan.deletes.length > 0);
+    if (!hasChanges) {
+        log('No changes to push.');
+        return;
+    }
+    if (flags['dry-run']) {
+        return;
+    }
+    if (!flags.force && !(await confirmKnowledgePush(command, shouldDelete && plan.deletes.length > 0))) {
+        log('Push cancelled.');
+        return;
+    }
+    // ── Apply ─────────────────────────────────────────────────────────────
+    const startTime = Date.now();
+    let applied = '';
+    try {
+        applied = await applyKnowledgePlan(ctx, plan, shouldDelete, flags.verbose);
+    }
+    catch (error) {
+        command.error(`Push failed: ${error.message}`);
+    }
+    const elapsed = ((Date.now() - startTime) / 1000).toFixed(1);
+    log(`Pushed knowledge to ${label} from ${relative(process.cwd(), inputDir) || inputDir} in ${elapsed}s (${applied}, ${plan.unchanged.length} unchanged)`);
+}
+/**
+ * Collect local knowledge files, apply include/exclude filters, and validate
+ * names against the API's accepted character set. Errors out on empty or
+ * invalid input.
+ */
+function collectLocalKnowledge(command, inputDir, flags) {
+    const allFiles = collectKnowledgeFiles(inputDir);
+    const files = applyFilters(allFiles, inputDir, flags.include, flags.exclude, command.log.bind(command));
+    if (files.length === 0) {
+        command.error(flags.include || flags.exclude
+            ? `No knowledge files remain after include/exclude filters in ${inputDir}`
+            : `No knowledge files found in ${inputDir}`);
+    }
+    const entries = readKnowledgeEntries(files, inputDir);
+    const invalid = entries
+        .map((entry) => ({ entry, reason: validateKnowledgeName(entry.name) }))
+        .filter((item) => item.reason !== null);
+    if (invalid.length > 0) {
+        const lines = invalid.map(({ entry, reason }) => `  ${entry.name} — ${reason}`);
+        command.error(`Cannot push: ${invalid.length} file(s) have unsupported names:\n${lines.join('\n')}`);
+    }
+    return entries;
+}
+/**
+ * Prompt for confirmation before pushing. Errors out in non-interactive
+ * environments (matching `workspace push`), where --force must be used instead.
+ */
+async function confirmKnowledgePush(command, hasDestructive) {
+    if (!process.stdin.isTTY) {
+        command.error('Non-interactive environment detected. Use --force to skip confirmation.');
+    }
+    const message = hasDestructive
+        ? 'Proceed with push? This includes DESTRUCTIVE operations listed above.'
+        : 'Proceed with push?';
+    return confirm(message);
+}
+/**
+ * Apply a knowledge plan against the Metadata API: POST creates, PUT updates
+ * (content only, so other metadata is preserved), and DELETE removals when
+ * shouldDelete is set. Returns a "2 created, 1 updated" style summary.
+ * Throws on the first failed request, noting what was applied so far.
+ */
+async function applyKnowledgePlan(ctx, plan, shouldDelete, verbose) {
+    let created = 0;
+    let updated = 0;
+    let deleted = 0;
+    const describeApplied = () => {
+        const counts = [];
+        if (created > 0)
+            counts.push(`${created} created`);
+        if (updated > 0)
+            counts.push(`${updated} updated`);
+        if (deleted > 0)
+            counts.push(`${deleted} deleted`);
+        return counts.join(', ') || 'no changes applied';
+    };
+    // eslint-disable-next-line no-undef
+    const request = async (action, name, url, init) => {
+        const response = await ctx.verboseFetch(url, init, verbose, ctx.accessToken);
+        if (!response.ok) {
+            throw new Error(`failed to ${action} "${name}" (${response.status}): ${await response.text()} (after ${describeApplied()})`);
+        }
+    };
+    /* eslint-disable no-await-in-loop */
+    for (const entry of plan.creates) {
+        const body = {
+            content: entry.content,
+            // eslint-disable-next-line camelcase
+            knowledge_type: inferKnowledgeType(entry.name),
+            name: entry.name,
+        };
+        if (ctx.branch) {
+            body.branch = ctx.branch;
+        }
+        await request('create', entry.name, knowledgeUrl(ctx), {
+            body: JSON.stringify(body),
+            headers: jsonHeaders(ctx.accessToken),
+            method: 'POST',
+        });
+        created++;
+    }
+    for (const { entry, remote } of plan.updates) {
+        // name is included because the server requires it on edit; other metadata
+        // (description, mode, enabled, tags, ...) is left untouched.
+        await request('update', entry.name, knowledgeUrl(ctx, `/${remote.id}`), {
+            body: JSON.stringify({ content: entry.content, name: entry.name }),
+            headers: jsonHeaders(ctx.accessToken),
+            method: 'PUT',
+        });
+        updated++;
+    }
+    if (shouldDelete) {
+        for (const item of plan.deletes) {
+            await request('delete', item.name, knowledgeUrl(ctx, `/${item.id}`), {
+                headers: jsonHeaders(ctx.accessToken),
+                method: 'DELETE',
+            });
+            deleted++;
+        }
+    }
+    /* eslint-enable no-await-in-loop */
+    return describeApplied();
+}

package/dist/utils/multidoc-push.js

@@ -476,7 +476,6 @@ export async function executePush(ctx, target, flags) {
                     }
                     // Warn when the sandbox currently holds a different workspace than the one being
                     // pushed and the change set is large enough that stale state is a real risk.
-                    let mismatchConfirmed = false;
                     if (target.warnOnWorkspaceMismatch && preview.workspace_name) {
                         const localWorkspaceName = findLocalWorkspaceName(documentEntries);
                         const totalChanges = countSummaryChanges(preview.summary, shouldDelete);
@@ -495,33 +494,30 @@ export async function executePush(ctx, target, flags) {
                                     log('Push cancelled. Run `xano sandbox reset` then retry.');
                                     return;
                                 }
-                                mismatchConfirmed = true;
                             }
                             else {
                                 command.error('Workspace mismatch detected in non-interactive mode. Run `xano sandbox reset` first to start clean.');
                             }
                         }
                     }
-                    // Confirm with user (skip if workspace mismatch prompt already obtained confirmation)
-                    if (!mismatchConfirmed) {
-                        const hasDestructive = preview.operations.some((op) => (shouldDelete && (op.action === 'delete' || op.action === 'cascade_delete')) ||
-                            op.action === 'truncate' ||
-                            op.action === 'drop_field' ||
-                            op.action === 'alter_field');
-                        const message = hasDestructive
-                            ? 'Proceed with push? This includes DESTRUCTIVE operations listed above.'
-                            : 'Proceed with push?';
-                        if (process.stdin.isTTY) {
-                            const confirmed = await confirm(message);
-                            if (!confirmed) {
-                                log('Push cancelled.');
-                                return;
-                            }
-                        }
-                        else {
-                            command.error('Non-interactive environment detected. Use --force to skip confirmation.');
+                    // Confirm with user
+                    const hasDestructive = preview.operations.some((op) => (shouldDelete && (op.action === 'delete' || op.action === 'cascade_delete')) ||
+                        op.action === 'truncate' ||
+                        op.action === 'drop_field' ||
+                        op.action === 'alter_field');
+                    const message = hasDestructive
+                        ? 'Proceed with push? This includes DESTRUCTIVE operations listed above.'
+                        : 'Proceed with push?';
+                    if (process.stdin.isTTY) {
+                        const confirmed = await confirm(message);
+                        if (!confirmed) {
+                            log('Push cancelled.');
+                            return;
                         }
                     }
+                    else {
+                        command.error('Non-interactive environment detected. Use --force to skip confirmation.');
+                    }
                 }
                 else {
                     // Server returned unexpected response
@@ -593,7 +589,7 @@ export async function executePush(ctx, target, flags) {
             }
             catch {
                 if (flags.verbose) {
-                    log(`Server response is not JSON; skipping GUID sync\n${responseText}`);
+                    log('Server response is not JSON; skipping GUID sync');
                 }
             }
         }

package/dist/utils/reference-checker.js

@@ -170,8 +170,8 @@ export function checkTableIndexes(documents) {
     return badIndexes;
 }
 function extractSchemaFields(content) {
-    // id, created_at, and xdo are system fields not declared in the schema
-    const fields = new Set(['id', 'created_at', 'xdo']);
+    // id and created_at are auto-added during import
+    const fields = new Set(['id', 'created_at']);
     // Find the schema block by matching braces
     const schemaStart = content.match(/\bschema\s*\{/);
     if (!schemaStart || schemaStart.index === undefined)