@xano/cli 1.0.4-beta.8 → 1.0.4-beta.9

package/README.md

@@ -255,7 +255,34 @@ xano function edit <function_id> -f new.xs              # Update from file
 xano function edit <function_id> -f new.xs --edit       # Open in $EDITOR before updating
 cat function.xs | xano function edit <function_id> --stdin  # Update from stdin
 xano function edit <function_id> --no-publish           # Edit without publishing
-```
+
+# Run (execute) a function by name
+xano function run <name>                                # Prompts for declared inputs (on a TTY)
+xano function run <name> --data email=jo@x.com --data age:=30 --data active:=true
+xano function run <name> --json @payload.json --data env=staging   # base payload + override
+echo '{"email":"jo@x.com"}' | xano function run <name> --stdin -o json | jq .result
+xano function run <name> --branch dev --logs            # run on a branch, show execution logs
+```
+
+Input flexibility for `function run` (assembled into one JSON `input` object):
+
+| Form | Meaning |
+| --- | --- |
+| `--data key=value` | string field |
+| `--data key:=<json>` | raw JSON field (`age:=30`, `active:=true`, `tags:='["a","b"]'`) |
+| `--data key@file` | field value read from a file |
+| `--json '<inline>'` / `--json @file.json` / `--json -` | a base JSON object (stdin with `-`) |
+| `--stdin` | read the JSON object from stdin (same as `--json -`) |
+
+Merge order is JSON base first, then `--data` overrides. Missing required inputs are
+prompted for on an interactive terminal; in a non-TTY (CI) context the command fails
+listing them. Output defaults to the raw `result` (`-o json`); the exit code is non-zero
+when the function returns an error status.
+
+> **Permissions:** running a function requires **Function** (read) plus the **run/debug**
+> action on your workspace role. If your access token's role lacks run/debug, the call is
+> denied with an access error — grant run/debug to the role (or use a token whose role has
+> it). `function list`/`get`/`create`/`edit` only need the Function permission.
 
 ### Releases
 

package/dist/commands/function/run/index.d.ts

@@ -0,0 +1,40 @@
+import BaseCommand from '../../../base-command.js';
+export default class FunctionRun extends BaseCommand {
+    static args: {
+        name: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    static flags: {
+        branch: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        data: import("@oclif/core/interfaces").OptionFlag<string[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        json: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        logs: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'no-input-check': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        output: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
+        stdin: 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>;
+    private emitResult;
+    /**
+     * Fetch a single function record by name via the list endpoint's search,
+     * returning the exact-name match (so `calc` doesn't accidentally match
+     * `calcScore`). Best-effort: returns undefined and warns on any failure so a
+     * transient introspection problem never blocks an otherwise-valid run.
+     */
+    private fetchFunctionByName;
+    /**
+     * Prompt for each missing required input on an interactive TTY. Values are
+     * read as raw JSON when they parse as such (so numbers/bools/objects work),
+     * otherwise treated as a string — mirroring the `key:=`/`key=` distinction.
+     * Non-TTY: fail fast with the list of missing params (never hang on a prompt).
+     */
+    private promptForMissing;
+    private readStdinSync;
+    private resolveWorkspaceId;
+}

package/dist/commands/function/run/index.js

@@ -0,0 +1,244 @@
+import { Args, Flags } from '@oclif/core';
+import { readFileSync } from 'node:fs';
+import BaseCommand from '../../../base-command.js';
+import { assembleInput, loadJsonSource, parseDataPairs, validateAgainstSchema, } from '../../../utils/function-input.js';
+export default class FunctionRun extends BaseCommand {
+    static args = {
+        name: Args.string({
+            description: 'Name of the function to run (interactive if omitted with --name unset)',
+            required: false,
+        }),
+    };
+    static description = 'Run (execute) a named function in a workspace and print its result';
+    static examples = [
+        `$ xano function:run calcScore -w 40
+# Prompts for any declared inputs, then runs the function`,
+        `$ xano function:run calcScore --data email=jo@x.com --data age:=30 --data active:=true`,
+        `$ xano function:run calcScore --json @payload.json --data env=staging`,
+        `$ echo '{"email":"jo@x.com"}' | xano function:run calcScore --stdin -o json | jq .result`,
+        `$ xano function:run calcScore --branch dev --logs`,
+    ];
+    static flags = {
+        ...BaseCommand.baseFlags,
+        branch: Flags.string({
+            description: 'Branch to run from (defaults to profile branch, then main)',
+            required: false,
+        }),
+        data: Flags.string({
+            char: 'd',
+            description: 'Input field as key=value (string), key:=json (raw JSON), or key@file (file contents). Repeatable.',
+            multiple: true,
+            required: false,
+        }),
+        json: Flags.string({
+            description: "Input as a JSON object: inline, @file.json, or '-' for stdin",
+            exclusive: ['stdin'],
+            required: false,
+        }),
+        logs: Flags.boolean({
+            default: false,
+            description: 'Print the execution logs returned by the debugger',
+            required: false,
+        }),
+        'name': Flags.string({
+            char: 'n',
+            description: 'Name of the function to run (alternative to the positional argument)',
+            required: false,
+        }),
+        'no-input-check': Flags.boolean({
+            default: false,
+            description: 'Skip local schema validation and interactive prompting; send the payload as-is',
+            required: false,
+        }),
+        output: Flags.string({
+            char: 'o',
+            default: 'json',
+            description: 'Output format',
+            options: ['json', 'summary'],
+            required: false,
+        }),
+        stdin: Flags.boolean({
+            char: 's',
+            default: false,
+            description: "Read the input JSON object from stdin (same as --json -)",
+            exclusive: ['json'],
+            required: false,
+        }),
+        workspace: Flags.string({
+            char: 'w',
+            description: 'Workspace ID (optional if set in profile)',
+            required: false,
+        }),
+    };
+    async run() {
+        const { args, flags } = await this.parse(FunctionRun);
+        const { profile, profileName } = this.resolveProfile(flags);
+        const functionName = args.name ?? flags.name;
+        if (!functionName) {
+            this.error('A function name is required. Provide it as an argument or with --name.');
+        }
+        const workspaceId = this.resolveWorkspaceId(flags, profile, profileName);
+        const branch = flags.branch ?? profile.branch ?? '';
+        // 1) Assemble the input object from JSON base + --data overrides.
+        const jsonSource = flags.stdin ? '-' : flags.json;
+        const jsonBase = loadJsonSource(jsonSource, { stdin: () => this.readStdinSync() });
+        let input = assembleInput({ dataPairs: parseDataPairs(flags.data ?? []), jsonBase });
+        // 2) Introspect the function's declared inputs (best-effort) to validate,
+        //    warn on obvious mismatches, and prompt for missing required params.
+        if (!flags['no-input-check']) {
+            const fn = await this.fetchFunctionByName({
+                branch,
+                name: functionName,
+                profile,
+                verbose: flags.verbose,
+                workspaceId,
+            });
+            const schema = fn?.input;
+            const { missingRequired, warnings } = validateAgainstSchema(input, schema);
+            for (const w of warnings)
+                this.warn(w);
+            if (missingRequired.length > 0) {
+                input = await this.promptForMissing(input, missingRequired);
+            }
+        }
+        // 3) Execute via the meta run endpoint.
+        const apiUrl = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/function/run`;
+        const body = { input, name: functionName };
+        if (branch)
+            body.branch = branch;
+        const response = await this.verboseFetch(apiUrl, {
+            body: JSON.stringify(body),
+            headers: {
+                'accept': 'application/json',
+                'Authorization': `Bearer ${profile.access_token}`,
+                'Content-Type': 'application/json',
+            },
+            method: 'POST',
+        }, flags.verbose, profile.access_token);
+        if (!response.ok) {
+            const message = await this.parseApiError(response, 'Failed to run function');
+            this.error(message);
+        }
+        const result = (await response.json());
+        this.emitResult(result, flags.output, flags.logs);
+        // 4) Compose in scripts/CI: non-zero exit when the function errored.
+        if (result.status && result.status !== 'ok') {
+            this.exit(1);
+        }
+    }
+    emitResult(result, output, showLogs) {
+        if (output === 'json') {
+            // Raw result object so `| jq .result` works predictably.
+            this.log(JSON.stringify(result.result ?? null, null, 2));
+        }
+        else {
+            const status = result.status ?? 'ok';
+            this.log(`Status: ${status}`);
+            this.log('Result:');
+            this.log(JSON.stringify(result.result ?? null, null, 2));
+        }
+        if (showLogs && Array.isArray(result.logs) && result.logs.length > 0) {
+            this.log('');
+            this.log('Logs:');
+            for (const entry of result.logs) {
+                this.log(typeof entry === 'string' ? entry : JSON.stringify(entry));
+            }
+        }
+    }
+    /**
+     * Fetch a single function record by name via the list endpoint's search,
+     * returning the exact-name match (so `calc` doesn't accidentally match
+     * `calcScore`). Best-effort: returns undefined and warns on any failure so a
+     * transient introspection problem never blocks an otherwise-valid run.
+     */
+    async fetchFunctionByName(opts) {
+        const { branch, name, profile, verbose, workspaceId } = opts;
+        // eslint-disable-next-line camelcase -- external Metadata API query param
+        const params = new URLSearchParams({ per_page: '100', search: name });
+        if (branch)
+            params.set('branch', branch);
+        const url = `${profile.instance_origin}/api:meta/workspace/${workspaceId}/function?${params.toString()}`;
+        try {
+            const response = await this.verboseFetch(url, { headers: { accept: 'application/json', Authorization: `Bearer ${profile.access_token}` }, method: 'GET' }, verbose, profile.access_token);
+            if (!response.ok)
+                return undefined;
+            const page = (await response.json());
+            const items = Array.isArray(page) ? page : (page.items ?? []);
+            const exact = items.filter((f) => f.name === name);
+            if (exact.length > 1) {
+                this.warn(`Multiple functions named '${name}' found; skipping input validation.`);
+                return undefined;
+            }
+            return exact[0];
+        }
+        catch {
+            // Introspection is a convenience, not a requirement.
+            return undefined;
+        }
+    }
+    /**
+     * Prompt for each missing required input on an interactive TTY. Values are
+     * read as raw JSON when they parse as such (so numbers/bools/objects work),
+     * otherwise treated as a string — mirroring the `key:=`/`key=` distinction.
+     * Non-TTY: fail fast with the list of missing params (never hang on a prompt).
+     */
+    async promptForMissing(input, missing) {
+        if (!process.stdout.isTTY || !process.stdin.isTTY) {
+            const names = missing.map((p) => `${p.name}${p.type ? ` (${p.type})` : ''}`).join(', ');
+            this.error(`Missing required input: ${names}. ` +
+                `Provide via --data/--json, or run interactively in a terminal.`);
+        }
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (message) => new Promise((resolve) => {
+            rl.question(message, resolve);
+        });
+        const filled = { ...input };
+        try {
+            for (const param of missing) {
+                const hint = [param.type, param.description].filter(Boolean).join(' — ');
+                // eslint-disable-next-line no-await-in-loop
+                const raw = await ask(`${param.name}${hint ? ` (${hint})` : ''}: `);
+                filled[param.name] = coercePromptValue(raw, param);
+            }
+        }
+        finally {
+            rl.close();
+        }
+        return filled;
+    }
+    readStdinSync() {
+        // Synchronous read of all of stdin (fd 0); used for --json - / --stdin.
+        try {
+            return readFileSync(0, 'utf8');
+        }
+        catch (error) {
+            this.error(`Failed to read from stdin: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    resolveWorkspaceId(flags, profile, profileName) {
+        if (flags.workspace)
+            return flags.workspace;
+        if (profile.workspace)
+            return profile.workspace;
+        this.error(`Workspace ID is required. Either:\n` +
+            `  1. Provide it as a flag: xano function:run <name> -w <workspace_id>\n` +
+            `  2. Set it in your profile using: xano profile:edit ${profileName} -w <workspace_id>`);
+    }
+}
+/**
+ * Coerce a prompted string into the value the parameter likely expects. Non-text
+ * params attempt a JSON parse (so `30`, `true`, `["a"]` become typed values);
+ * text params keep the raw string. Falls back to the raw string on parse errors.
+ */
+function coercePromptValue(raw, param) {
+    const isTextLike = !param.type || param.type === 'text' || param.type === 'uuid';
+    if (isTextLike)
+        return raw;
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}

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}`);
+    }
+}