@xano/cli 1.0.4 → 1.0.5

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

@@ -1,108 +1,113 @@
-import { Command } from '@oclif/core';
-/** A knowledge record as returned by the Metadata API list endpoint. */
-export interface KnowledgeItem {
-    branch?: {
-        id: number;
-    };
-    content?: string;
+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;
-    id: number;
-    knowledge_type?: string;
+    files?: KnowledgeFile[];
+    guid?: string;
+    knowledge_type: KnowledgeType;
     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;
+/** A locally-collected object that also remembers its primary file on disk (for GUID writeback). */
+export interface LocalKnowledgeObject extends KnowledgeObject {
     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 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 KnowledgePushFlags {
-    delete: boolean;
-    'dry-run': boolean;
-    exclude?: string[];
-    force: boolean;
-    include?: string[];
-    sync: boolean;
-    verbose: boolean;
+export interface KnowledgeDryRunOperation {
+    action: string;
+    name: string;
+    type: string;
 }
-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 KnowledgeDryRunSummary {
+    created: number;
+    deleted: number;
+    unchanged: number;
+    updated: number;
 }
-export interface KnowledgePushContext extends KnowledgeApiContext {
-    cliVersion: string;
-    command: Command;
-    inputDir: string;
+export interface KnowledgeDryRunResult {
+    operations: KnowledgeDryRunOperation[];
+    summary: Record<string, KnowledgeDryRunSummary>;
 }
-export declare const MAX_NAME_LENGTH = 200;
+type VerboseFetch = (url: string, options: RequestInit, verbose: boolean, authToken?: string) => Promise<Response>;
 /**
- * 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 declare function validateKnowledgeName(name: string): null | string;
+export declare function buildPrimaryContent(obj: KnowledgeObject): 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.
+ * 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 safeKnowledgePath(baseDir: string, name: null | string | undefined): null | string;
+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;
+};
 /**
- * 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.
+ * 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 inferKnowledgeType(name: string): string;
+export declare function writeKnowledge(objects: KnowledgeObject[], outputDir: string): number;
 /**
- * Recursively collect all files under a directory, skipping hidden files,
- * hidden directories, and node_modules. Sorted for deterministic ordering.
+ * 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 collectKnowledgeFiles(dir: string): string[];
+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[];
 /**
- * Read local files into knowledge entries. The knowledge name is the path
- * relative to inputDir, using forward slashes.
+ * GET workspace knowledge objects (with content). Returns `[]` on 404 (instance
+ * without the feature) or any network error, so pull degrades gracefully.
  */
-export declare function readKnowledgeEntries(files: string[], inputDir: string): LocalKnowledgeEntry[];
+export declare function fetchKnowledge(baseUrl: string, branch: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean): Promise<KnowledgeObject[]>;
 /**
- * Compute the create/update/delete plan by matching local entries against
- * remote knowledge items by name.
+ * 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 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;
+export declare function pushKnowledge(url: string, accessToken: string, verboseFetch: VerboseFetch, verbose: boolean, body: KnowledgePushBody): Promise<KnowledgePushResult>;
 /**
- * Fetch all knowledge items (with content) for a workspace/branch.
+ * 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 fetchKnowledgeList(ctx: KnowledgeApiContext, verbose: boolean): Promise<KnowledgeItem[]>;
+export declare function knowledgePreview(local: KnowledgeObject[], server: KnowledgeObject[], willDelete: boolean): KnowledgeDryRunResult;
 /**
- * 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).
+ * Set or update `guid:` in a primary `.md` file's YAML frontmatter.
+ * Returns true if the file was modified.
  */
-export declare function executeKnowledgePush(ctx: KnowledgePushContext, flags: KnowledgePushFlags): Promise<void>;
+export declare function syncGuidToFrontmatter(filePath: string, guid: string): boolean;
+export {};