@xano/cli 1.0.3 → 1.0.4-beta.10

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/function-input.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Input assembly for `xano function run`.
+ *
+ * A run's `input` is a single JSON object sent to the Metadata API. Users can
+ * build that object from several sources, which this module normalizes and
+ * merges:
+ *
+ *   --json <inline | @file | ->   a base JSON object
+ *   --data key=value              a string field (httpie convention)
+ *   --data key:=<json>            a raw-JSON field (numbers, bools, arrays, ...)
+ *   --data key@<file>             a field whose value is a file's contents (string)
+ *
+ * Merge order is: JSON base first, then --data pairs override — so the common
+ * "reuse a payload file, tweak one field" flow works without editing the file.
+ *
+ * Everything here is pure and free of oclif/network deps so it is unit-testable
+ * in isolation; the command layer handles fetching, prompting and output.
+ */
+export type JsonObject = Record<string, unknown>;
+/** A single declared function input parameter, as returned by the meta API. */
+export interface FunctionInputParam {
+    children?: FunctionInputParam[];
+    default?: unknown;
+    description?: string;
+    name: string;
+    nullable?: boolean;
+    required?: boolean;
+    style?: {
+        type?: string;
+    };
+    type?: string;
+    values?: unknown[];
+}
+/**
+ * Split a `--data` token into its key, operator and value.
+ * Recognizes, in priority order: `:=` (raw json), `@` (file), `=` (string).
+ * The operator is the FIRST occurrence scanned left-to-right, but `:=` is
+ * detected before a bare `=` at the same position so `k:=1` is raw-json, not
+ * a string key `k:` set to `=1`.
+ */
+export declare function splitDataToken(token: string): {
+    key: string;
+    op: ':=' | '=' | '@';
+    value: string;
+};
+/**
+ * Parse `--data` tokens into an object, applying httpie-style typing.
+ * Later tokens override earlier ones with the same key.
+ */
+export declare function parseDataPairs(pairs: string[], readFile?: (p: string) => string): JsonObject;
+/**
+ * Load the `--json` source: inline JSON, `@file`, or `-` (stdin, supplied by
+ * the caller via `stdin`). Must parse to a plain object; arrays/scalars are
+ * rejected because a function's input is always a keyed object.
+ */
+export declare function loadJsonSource(source: string | undefined, opts?: {
+    readFile?: (p: string) => string;
+    stdin?: () => string;
+}): JsonObject | undefined;
+/**
+ * Merge a JSON base with --data overrides into the final input object.
+ * Precedence: base first, then dataPairs override (shallow).
+ */
+export declare function assembleInput(opts: {
+    dataPairs?: JsonObject;
+    jsonBase?: JsonObject;
+}): JsonObject;
+/**
+ * Validate a supplied input object against a function's declared input schema.
+ * Non-destructive: returns lists the caller can act on (prompt for missing
+ * required params on a TTY, warn on enum mismatches, etc.). The server remains
+ * the source of truth, so type mismatches are warnings, not hard failures.
+ */
+export declare function validateAgainstSchema(input: JsonObject, schema: FunctionInputParam[] | undefined): {
+    missingRequired: FunctionInputParam[];
+    warnings: string[];
+};

package/dist/utils/function-input.js

@@ -0,0 +1,148 @@
+import * as fs from 'node:fs';
+/**
+ * Split a `--data` token into its key, operator and value.
+ * Recognizes, in priority order: `:=` (raw json), `@` (file), `=` (string).
+ * The operator is the FIRST occurrence scanned left-to-right, but `:=` is
+ * detected before a bare `=` at the same position so `k:=1` is raw-json, not
+ * a string key `k:` set to `=1`.
+ */
+export function splitDataToken(token) {
+    // Find the earliest `=` and `@`; `:=` is an `=` preceded by `:`.
+    const eq = token.indexOf('=');
+    const at = token.indexOf('@');
+    // Neither operator present -> invalid.
+    if (eq === -1 && at === -1) {
+        throw new Error(`Invalid --data '${token}'. Expected key=value, key:=json, or key@file.`);
+    }
+    // Choose whichever operator appears first. On a tie an '=' can't tie with '@'
+    // at the same index, so a simple "smallest index wins" is unambiguous.
+    const useAt = at !== -1 && (eq === -1 || at < eq);
+    if (useAt) {
+        const key = token.slice(0, at);
+        if (!key)
+            throw new Error(`Invalid --data '${token}': missing key before '@'.`);
+        return { key, op: '@', value: token.slice(at + 1) };
+    }
+    // `=` path — check for the `:=` raw-json form (a ':' immediately before '=').
+    if (eq > 0 && token[eq - 1] === ':') {
+        const key = token.slice(0, eq - 1);
+        if (!key)
+            throw new Error(`Invalid --data '${token}': missing key before ':='.`);
+        return { key, op: ':=', value: token.slice(eq + 1) };
+    }
+    const key = token.slice(0, eq);
+    if (!key)
+        throw new Error(`Invalid --data '${token}': missing key before '='.`);
+    return { key, op: '=', value: token.slice(eq + 1) };
+}
+/**
+ * Parse `--data` tokens into an object, applying httpie-style typing.
+ * Later tokens override earlier ones with the same key.
+ */
+export function parseDataPairs(pairs, readFile = defaultReadFile) {
+    const out = {};
+    for (const token of pairs) {
+        const { key, op, value } = splitDataToken(token);
+        switch (op) {
+            case ':=': {
+                try {
+                    out[key] = JSON.parse(value);
+                }
+                catch (error) {
+                    throw new Error(`Invalid JSON for --data '${key}:=': ${error.message}`);
+                }
+                break;
+            }
+            case '@': {
+                out[key] = readFile(value);
+                break;
+            }
+            default: {
+                out[key] = value;
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Load the `--json` source: inline JSON, `@file`, or `-` (stdin, supplied by
+ * the caller via `stdin`). Must parse to a plain object; arrays/scalars are
+ * rejected because a function's input is always a keyed object.
+ */
+export function loadJsonSource(source, opts = {}) {
+    if (source === undefined)
+        return undefined;
+    const readFile = opts.readFile ?? defaultReadFile;
+    let raw;
+    if (source === '-') {
+        if (!opts.stdin)
+            throw new Error('stdin reader not available for --json -');
+        raw = opts.stdin();
+    }
+    else if (source.startsWith('@')) {
+        raw = readFile(source.slice(1));
+    }
+    else {
+        raw = source;
+    }
+    if (raw.trim() === '')
+        return undefined;
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (error) {
+        throw new Error(`Invalid JSON input: ${error.message}`);
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new Error('Function input must be a JSON object (e.g. {"name":"..."}), not an array or scalar.');
+    }
+    return parsed;
+}
+/**
+ * Merge a JSON base with --data overrides into the final input object.
+ * Precedence: base first, then dataPairs override (shallow).
+ */
+export function assembleInput(opts) {
+    return { ...opts.jsonBase, ...opts.dataPairs };
+}
+/**
+ * Validate a supplied input object against a function's declared input schema.
+ * Non-destructive: returns lists the caller can act on (prompt for missing
+ * required params on a TTY, warn on enum mismatches, etc.). The server remains
+ * the source of truth, so type mismatches are warnings, not hard failures.
+ */
+export function validateAgainstSchema(input, schema) {
+    const missingRequired = [];
+    const warnings = [];
+    if (!schema)
+        return { missingRequired, warnings };
+    for (const param of schema) {
+        const present = Object.hasOwn(input, param.name);
+        if (!present) {
+            // A required param with no default must be supplied.
+            if (param.required && param.default === undefined) {
+                missingRequired.push(param);
+            }
+            continue;
+        }
+        const value = input[param.name];
+        if (value === null && param.nullable === false) {
+            warnings.push(`Input '${param.name}' is null but the parameter is not nullable.`);
+        }
+        // Enum membership check (only for non-null scalar values).
+        if (Array.isArray(param.values) && param.values.length > 0 && value !== null && !param.values.includes(value)) {
+            warnings.push(`Input '${param.name}' = ${JSON.stringify(value)} is not one of the allowed values: ` +
+                param.values.map((v) => JSON.stringify(v)).join(', '));
+        }
+    }
+    return { missingRequired, warnings };
+}
+function defaultReadFile(p) {
+    try {
+        return fs.readFileSync(p, 'utf8');
+    }
+    catch (error) {
+        throw new Error(`Failed to read file '${p}': ${error.message}`);
+    }
+}

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 {};