@xano/cli 1.0.4 → 1.0.6-beta.0

package/dist/utils/knowledge-sync.js

@@ -1,380 +1,433 @@
-import { ux } from '@oclif/core';
+/* eslint-disable camelcase -- knowledge_type / dry_run / guid_map are external Metadata API field names */
+import * as yaml from 'js-yaml';
+import snakeCase from 'lodash.snakecase';
+import { minimatch } from 'minimatch';
 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;
+import { dirname, join, relative, sep } from 'node:path';
+// ── Types ────────────────────────────────────────────────────────────────────
+//
+// Knowledge mirrors the multidoc model: the server returns self-describing
+// *objects* and the CLI owns the on-disk folder layout + YAML frontmatter
+// (see workspace/pull for the equivalent `.xs` mapping). We deliberately do NOT
+// let the server dictate file paths.
+export const KNOWLEDGE_DIR = 'knowledge';
+// ── Frontmatter ──────────────────────────────────────────────────────────────
+const FRONTMATTER_ORDER = ['name', 'description', 'knowledge_type', 'scope', 'inclusion', 'enabled', 'guid'];
 /**
- * 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.
+ * Build a primary `.md` file body: YAML frontmatter (built from the object's
+ * structured fields) followed by the markdown content.
  */
-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;
+export function buildPrimaryContent(obj) {
+    const meta = {};
+    meta.name = obj.name;
+    if (obj.description !== undefined)
+        meta.description = obj.description;
+    meta.knowledge_type = obj.knowledge_type;
+    if (obj.scope !== undefined)
+        meta.scope = obj.scope;
+    if (obj.mode !== undefined)
+        meta.inclusion = modeToInclusion(obj.mode);
+    if (obj.enabled !== undefined)
+        meta.enabled = obj.enabled;
+    if (obj.guid !== undefined)
+        meta.guid = obj.guid;
+    // Emit keys in a stable, human-friendly order.
+    const ordered = {};
+    for (const key of FRONTMATTER_ORDER) {
+        if (key in meta)
+            ordered[key] = meta[key];
+    }
+    const fm = yaml.dump(ordered, { lineWidth: -1 }).trimEnd();
+    const body = obj.content ?? '';
+    return `---\n${fm}\n---\n${body}`;
 }
 /**
- * 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.
+ * Split a primary `.md` file into its frontmatter fields and markdown body.
+ * Returns `{meta: {}, body: <raw>}` when there is no leading `---` block.
  */
-export function safeKnowledgePath(baseDir, name) {
-    // Normalize: knowledge names always use forward slashes
-    if (!name || name.startsWith('/') || name.includes('\\')) {
-        return null;
+export function parsePrimaryContent(raw) {
+    const lines = raw.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return { body: raw, meta: {} };
+    let close = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            close = i;
+            break;
+        }
     }
-    const segments = name.split('/');
-    if (segments.some((s) => s === '' || s === '.' || s === '..')) {
-        return null;
+    if (close === -1)
+        return { body: raw, meta: {} };
+    const fmText = lines.slice(1, close).join('\n');
+    const body = lines.slice(close + 1).join('\n');
+    let meta = {};
+    try {
+        meta = yaml.load(fmText) ?? {};
     }
-    const base = resolve(baseDir);
-    const target = resolve(base, ...segments);
-    if (target !== base && !target.startsWith(base + sep)) {
-        return null;
+    catch {
+        meta = {};
     }
-    return target;
+    return { body, meta };
 }
+/** Read just `guid`/`name` from frontmatter (used by GUID matching). */
+export function parseFrontmatter(content) {
+    const { meta } = parsePrimaryContent(content);
+    const result = {};
+    if (typeof meta.guid === 'string')
+        result.guid = meta.guid;
+    if (typeof meta.name === 'string')
+        result.name = meta.name;
+    return result;
+}
+// ── Mode normalization ───────────────────────────────────────────────────────
 /**
- * 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.
+ * The API only accepts the backend `mode` enum (`auto` | `referenced` | `always`),
+ * but on disk (and in the Xano UI) this is the `inclusion` field with values
+ * "on demand" / "manual" / "always" — see `modeToInclusion` for the pull-side
+ * mapping. Hand-authored frontmatter (or content copied from the UI) commonly
+ * uses the display label instead, which the API rejects with e.g. `Input
+ * "on demand" is not one of the allowable values.` (DEV-7380/DEV-7382).
+ * Normalize known aliases before every push so the backend enum value is
+ * always what's sent.
  */
-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';
+const MODE_ALIASES = {
+    'always included': 'always',
+    'manual': 'referenced',
+    'on demand': 'auto',
+};
+function normalizeMode(mode) {
+    return MODE_ALIASES[mode.trim().toLowerCase()] ?? mode;
+}
+/** Map the backend `mode` enum to the `inclusion:` frontmatter value shown in the Xano UI. */
+const MODE_TO_INCLUSION = {
+    always: 'always',
+    auto: 'on demand',
+    referenced: 'manual',
+};
+function modeToInclusion(mode) {
+    return MODE_TO_INCLUSION[mode] ?? mode;
 }
-// ── File Collection ─────────────────────────────────────────────────────────
-const SKIPPED_DIRECTORIES = new Set(['node_modules']);
+// ── Path mapping (CLI-owned layout) ────────────────────────────────────────────
 /**
- * Recursively collect all files under a directory, skipping hidden files,
- * hidden directories, and node_modules. Sorted for deterministic ordering.
+ * Allocate a unique snake_case folder/file segment per call, suffixing
+ * collisions with `_2`, `_3`, … . Each object instance gets its own segment —
+ * we deliberately do NOT memoize by name, because two distinct objects can
+ * share a name (identity travels via the frontmatter `guid`, not the path), and
+ * collapsing them onto one path would silently overwrite files.
  */
-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));
+function makeNameResolver() {
+    const taken = new Set();
+    return (name) => {
+        const base = snakeCase(name) || 'untitled';
+        let candidate = base;
+        let n = 2;
+        while (taken.has(candidate)) {
+            candidate = `${base}_${n}`;
+            n++;
+        }
+        taken.add(candidate);
+        return candidate;
+    };
+}
+/** POSIX path (relative to `knowledge/`) of an object's primary `.md` file. */
+function primaryRelPath(obj, resolvers) {
+    switch (obj.knowledge_type) {
+        case 'agents.md': {
+            return 'agents.md';
+        }
+        case 'doc': {
+            return `docs/${resolvers.doc(obj.name)}.md`;
         }
-        else if (entry.isFile()) {
-            files.push(fullPath);
+        case 'skill': {
+            return `skills/${resolvers.skill(obj.name)}/SKILL.md`;
         }
     }
-    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('/'),
-    }));
+/** Infer the knowledge type from a primary file's POSIX path. */
+function inferType(posixPath) {
+    if (posixPath.startsWith('skills/'))
+        return 'skill';
+    if (posixPath.startsWith('docs/'))
+        return 'doc';
+    return 'agents.md';
 }
-// ── Diff Plan ───────────────────────────────────────────────────────────────
+// ── Pull: write objects to disk ────────────────────────────────────────────────
 /**
- * Compute the create/update/delete plan by matching local entries against
- * remote knowledge items by name.
+ * 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 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);
+export function writeKnowledge(objects, outputDir) {
+    const resolvers = { doc: makeNameResolver(), skill: makeNameResolver() };
+    let count = 0;
+    for (const obj of objects) {
+        const rel = primaryRelPath(obj, resolvers);
+        const primaryAbs = join(outputDir, KNOWLEDGE_DIR, ...rel.split('/'));
+        fs.mkdirSync(dirname(primaryAbs), { recursive: true });
+        fs.writeFileSync(primaryAbs, buildPrimaryContent(obj), 'utf8');
+        count++;
+        if (obj.knowledge_type === 'skill' && obj.files?.length) {
+            const refsDir = join(dirname(primaryAbs), 'references');
+            for (const file of obj.files) {
+                const refAbs = join(refsDir, ...file.name.split('/'));
+                fs.mkdirSync(dirname(refAbs), { recursive: true });
+                fs.writeFileSync(refAbs, file.content, 'utf8');
+                count++;
+            }
         }
     }
-    return plan;
+    return count;
 }
-// ── 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}`);
+// ── Push: collect objects from disk ────────────────────────────────────────────
+function listFilesRecursive(baseDir, currentDir, out) {
+    for (const item of fs.readdirSync(currentDir, { withFileTypes: true })) {
+        const fullPath = join(currentDir, item.name);
+        if (item.isDirectory()) {
+            listFilesRecursive(baseDir, fullPath, out);
         }
-        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}`);
+        else if (item.isFile()) {
+            out.push(relative(baseDir, fullPath).split(sep).join('/'));
         }
     }
-    // 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}`));
+}
+/** True if `posixPath` is a primary file (not a reference). */
+function isPrimary(posixPath) {
+    if (posixPath === 'agents.md')
+        return true;
+    if (/^skills\/[^/]+\/SKILL\.md$/.test(posixPath))
+        return true;
+    if (/^docs\/[^/]+\.md$/.test(posixPath))
+        return true;
+    return false;
+}
+/**
+ * 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 function collectKnowledgeObjects(inputDir, include, exclude) {
+    const knowledgeDir = join(inputDir, KNOWLEDGE_DIR);
+    if (!fs.existsSync(knowledgeDir))
+        return [];
+    const allPaths = [];
+    listFilesRecursive(knowledgeDir, knowledgeDir, allPaths);
+    const allowed = (posixPath) => {
+        const rel = `${KNOWLEDGE_DIR}/${posixPath}`;
+        if (include?.length && !include.some((p) => minimatch(rel, p, { matchBase: true })))
+            return false;
+        if (exclude?.length && exclude.some((p) => minimatch(rel, p, { matchBase: true })))
+            return false;
+        return true;
+    };
+    const objects = [];
+    for (const posixPath of allPaths.sort()) {
+        if (!isPrimary(posixPath) || !allowed(posixPath))
+            continue;
+        const absPath = join(knowledgeDir, ...posixPath.split('/'));
+        const raw = fs.readFileSync(absPath, 'utf8');
+        const { body, meta } = parsePrimaryContent(raw);
+        const knowledgeType = meta.knowledge_type === 'agents.md' || meta.knowledge_type === 'doc' || meta.knowledge_type === 'skill'
+            ? meta.knowledge_type
+            : inferType(posixPath);
+        // The API requires description/scope/mode/enabled on every item, so default
+        // them when a hand-authored file omits them (pulled files always carry them).
+        // `mode` is read from the on-disk `inclusion:` field (see modeToInclusion).
+        const obj = {
+            content: body,
+            description: typeof meta.description === 'string' ? meta.description : '',
+            enabled: typeof meta.enabled === 'boolean' ? meta.enabled : true,
+            filePath: absPath,
+            knowledge_type: knowledgeType,
+            mode: typeof meta.inclusion === 'string' ? normalizeMode(meta.inclusion) : 'auto',
+            name: typeof meta.name === 'string' ? meta.name : deriveName(posixPath),
+            scope: typeof meta.scope === 'string' ? meta.scope : 'workspace',
+        };
+        if (typeof meta.guid === 'string')
+            obj.guid = meta.guid;
+        if (knowledgeType === 'skill') {
+            const skillFolder = posixPath.slice('skills/'.length, posixPath.indexOf('/SKILL.md'));
+            const refPrefix = `skills/${skillFolder}/references/`;
+            const files = [];
+            for (const candidate of allPaths) {
+                if (candidate.startsWith(refPrefix) && allowed(candidate)) {
+                    files.push({
+                        content: fs.readFileSync(join(knowledgeDir, ...candidate.split('/')), 'utf8'),
+                        name: candidate.slice(refPrefix.length),
+                    });
+                }
+            }
+            if (files.length > 0)
+                obj.files = files;
         }
-        log('');
-        log(ux.colorize('dim', `  Use --delete to remove these ${plan.deletes.length} item(s) from remote.`));
+        objects.push(obj);
     }
-    log('');
+    return objects;
 }
-// ── API Calls ───────────────────────────────────────────────────────────────
-function knowledgeUrl(ctx, suffix = '') {
-    return `${ctx.instanceOrigin}/api:meta/workspace/${ctx.workspaceId}/knowledge${suffix}`;
+function deriveName(posixPath) {
+    if (posixPath === 'agents.md')
+        return 'agents.md';
+    const parts = posixPath.split('/');
+    if (posixPath.startsWith('skills/'))
+        return parts[1];
+    return parts.at(-1).replace(/\.md$/, '');
 }
-function jsonHeaders(accessToken) {
-    return {
-        accept: 'application/json',
-        Authorization: `Bearer ${accessToken}`,
-        'Content-Type': 'application/json',
-    };
+/** Strip the local-only `filePath` before sending objects to the API. */
+export function toPushItems(objects) {
+    return objects.map(({ filePath: _filePath, ...rest }) => rest);
 }
+// ── API calls ──────────────────────────────────────────────────────────────────
 /**
- * Fetch all knowledge items (with content) for a workspace/branch.
+ * GET workspace knowledge objects (with content). Returns `[]` on 404 (instance
+ * without the feature) or any network error, so pull degrades gracefully.
  */
-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}`);
+export async function fetchKnowledge(baseUrl, branch, accessToken, verboseFetch, verbose) {
+    const params = new URLSearchParams({ branch });
+    const url = `${baseUrl}?${params.toString()}`;
+    try {
+        const response = await verboseFetch(url, { headers: { accept: 'application/json', Authorization: `Bearer ${accessToken}` }, method: 'GET' }, verbose, accessToken);
+        if (!response.ok)
+            return [];
+        const json = (await response.json());
+        if (Array.isArray(json))
+            return json;
+        return json.items ?? [];
     }
-    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');
+    catch {
+        return [];
     }
-    // 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).
+ * 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 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;
+export async function pushKnowledge(url, accessToken, verboseFetch, verbose, body) {
+    const response = await verboseFetch(url, {
+        body: JSON.stringify(body),
+        headers: {
+            accept: 'application/json',
+            Authorization: `Bearer ${accessToken}`,
+            'Content-Type': 'application/json',
+        },
+        method: 'POST',
+    }, verbose, accessToken);
+    if (!response.ok) {
+        const errorText = await response.text();
+        let msg = `Knowledge push failed (${response.status})`;
+        try {
+            const json = JSON.parse(errorText);
+            if (json.message)
+                msg += `: ${json.message}`;
+        }
+        catch {
+            msg += `\n${errorText}`;
+        }
+        throw new Error(msg);
     }
-    // ── Apply ─────────────────────────────────────────────────────────────
-    const startTime = Date.now();
-    let applied = '';
     try {
-        applied = await applyKnowledgePlan(ctx, plan, shouldDelete, flags.verbose);
+        return (await response.json());
     }
-    catch (error) {
-        command.error(`Push failed: ${error.message}`);
+    catch {
+        return {};
     }
-    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;
+// ── Preview (client-side diff fallback) ─────────────────────────────────────────
+/** Canonical form for change detection: content + description + metadata + references. */
+function canonical(obj) {
+    const files = (obj.files ?? [])
+        .map((f) => ({ content: f.content, name: f.name }))
+        .sort((a, b) => a.name.localeCompare(b.name));
+    return JSON.stringify({
+        content: obj.content,
+        description: obj.description ?? '',
+        enabled: obj.enabled ?? null,
+        files,
+        mode: obj.mode ?? '',
+        scope: obj.scope ?? '',
+    });
 }
 /**
- * Prompt for confirmation before pushing. Errors out in non-interactive
- * environments (matching `workspace push`), where --force must be used instead.
+ * 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.
  */
-async function confirmKnowledgePush(command, hasDestructive) {
-    if (!process.stdin.isTTY) {
-        command.error('Non-interactive environment detected. Use --force to skip confirmation.');
+export function knowledgePreview(local, server, willDelete) {
+    const operations = [];
+    const summary = {};
+    const ensure = (type) => {
+        summary[type] ??= { created: 0, deleted: 0, unchanged: 0, updated: 0 };
+    };
+    const serverByGuid = new Map();
+    const serverByName = new Map();
+    for (const s of server) {
+        if (s.guid)
+            serverByGuid.set(s.guid, s);
+        serverByName.set(s.name, s);
+    }
+    const matched = new Set();
+    for (const obj of local) {
+        const type = obj.knowledge_type;
+        ensure(type);
+        const match = (obj.guid ? serverByGuid.get(obj.guid) : undefined) ?? serverByName.get(obj.name);
+        if (match) {
+            matched.add(match);
+            if (canonical(match) === canonical(obj)) {
+                summary[type].unchanged++;
+            }
+            else {
+                operations.push({ action: 'update', name: obj.name, type });
+                summary[type].updated++;
+            }
+        }
+        else {
+            operations.push({ action: 'create', name: obj.name, type });
+            summary[type].created++;
+        }
+    }
+    if (willDelete) {
+        for (const s of server) {
+            if (!matched.has(s)) {
+                const type = s.knowledge_type;
+                ensure(type);
+                operations.push({ action: 'delete', name: s.name, type });
+                summary[type].deleted++;
+            }
+        }
     }
-    const message = hasDestructive
-        ? 'Proceed with push? This includes DESTRUCTIVE operations listed above.'
-        : 'Proceed with push?';
-    return confirm(message);
+    return { operations, summary };
 }
+// ── GUID writeback ──────────────────────────────────────────────────────────────
 /**
- * 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.
+ * Set or update `guid:` in a primary `.md` file's YAML frontmatter.
+ * Returns true if the file was modified.
  */
-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()})`);
+export function syncGuidToFrontmatter(filePath, guid) {
+    const content = fs.readFileSync(filePath, 'utf8');
+    const lines = content.split('\n');
+    if (lines[0]?.trim() !== '---')
+        return false;
+    let close = -1;
+    for (let i = 1; i < lines.length; i++) {
+        if (lines[i].trim() === '---') {
+            close = i;
+            break;
         }
-    };
-    /* 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++;
+    if (close === -1)
+        return false;
+    for (let i = 1; i < close; i++) {
+        const match = lines[i].match(/^guid\s*:\s*(.+)$/);
+        if (match) {
+            const existing = match[1].trim().replaceAll(/^["']|["']$/g, '');
+            if (existing === guid)
+                return false;
+            lines[i] = `guid: ${guid}`;
+            fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+            return true;
         }
     }
-    /* eslint-enable no-await-in-loop */
-    return describeApplied();
+    lines.splice(close, 0, `guid: ${guid}`);
+    fs.writeFileSync(filePath, lines.join('\n'), 'utf8');
+    return true;
 }