@getxflow/cli 0.12.0 → 0.13.0

package/dist/api.js

@@ -94,7 +94,7 @@ async function send(client, path, options = {}) {
     }
     catch (e) {
         const reason = e instanceof Error ? e.message : String(e);
-        throw new ApiError(`The platform is unreachable: ${reason}`, 'network', 0, `Check the connection and the address ${client.apiUrl}`);
+        throw new ApiError(`The platform is unreachable: ${reason}`, 'network', 0, `Check the connection and the address ${client.apiUrl}. Inside an agent sandbox the network is usually switched off: then the command belongs to a person in their own terminal`);
     }
     assertProtocol(response);
     return response;

package/dist/bin.js

@@ -133,11 +133,15 @@ async function run(args) {
                 await (0, connections_1.connectionsUnlink)(rest);
                 return;
             }
+            if (second === 'call') {
+                await (0, connections_1.connectionsCall)(rest);
+                return;
+            }
             if (second === undefined || second === 'list') {
                 await (0, connections_1.connectionsList)(rest);
                 return;
             }
-            throw new errors_1.CliError(`Unknown command: connections ${second}`, 'Available: list, link and unlink');
+            throw new errors_1.CliError(`Unknown command: connections ${second}`, 'Available: list, link, unlink and call');
         case 'schedules':
             if (second === 'set') {
                 await (0, schedules_1.schedulesSet)(rest);

package/dist/commands/connections.js

@@ -3,10 +3,12 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.connectionsList = connectionsList;
 exports.connectionsLink = connectionsLink;
 exports.connectionsUnlink = connectionsUnlink;
+exports.connectionsCall = connectionsCall;
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
+const json_arg_1 = require("../json-arg");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
 const env_1 = require("./env");
@@ -135,3 +137,135 @@ async function connectionsUnlink(args) {
     (0, ui_1.ok)(`${(0, ui_1.bold)(row.label)} unlinked, ${result.alias} is gone`);
     (0, ui_1.note)((0, ui_1.dim)('  Functions already deployed keep the values until their next deploy'));
 }
+/** Budget for the shown body. Enough to read the shape of an answer, cheap in context. */
+const SHOWN_CHARS = 8000;
+/**
+ * Head of the body, cut on a line boundary so JSON is never sliced mid-structure. Only the
+ * head is kept: a stitched head and tail would read as one answer and invite conclusions the
+ * data does not support.
+ */
+function head(text) {
+    if (text.length <= SHOWN_CHARS)
+        return { text, cut: false };
+    const kept = [];
+    let used = 0;
+    for (const line of text.split('\n')) {
+        if (used + line.length + 1 > SHOWN_CHARS)
+            break;
+        kept.push(line);
+        used += line.length + 1;
+    }
+    // One minified line longer than the whole budget: cut it by characters, there is no
+    // boundary to respect.
+    if (kept.length === 0)
+        return { text: text.slice(0, SHOWN_CHARS), cut: true };
+    return { text: kept.join('\n'), cut: true };
+}
+/**
+ * Response headers worth a line each: rate limits, the type, and where a redirect points.
+ * A CDN adds two dozen more, and on every call that is noise.
+ *
+ * Request headers are not filtered: there are a few, they are yours, and seeing them is how
+ * a `{NAME}` the connection does not have shows itself.
+ */
+function shownHeaders(headers) {
+    const wanted = (name) => name === 'content-type' || name === 'retry-after' || name === 'location' || name.startsWith('x-ratelimit');
+    return Object.entries(headers)
+        .filter(([name]) => wanted(name.toLowerCase()))
+        .map(([name, value]) => `${name}: ${value}`);
+}
+function allHeaders(headers) {
+    return Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+}
+/** Headers typed as JSON. Values may carry {NAME} placeholders, the platform fills those in. */
+function headerArg(args) {
+    const raw = (0, args_1.flagString)(args, 'header');
+    if (raw === undefined)
+        return undefined;
+    const problem = (0, json_arg_1.jsonProblem)(raw);
+    if (problem)
+        throw new errors_1.CliError(`--header is not valid JSON: ${raw}`, (0, json_arg_1.jsonHint)('header', raw));
+    const parsed = JSON.parse(raw);
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        throw new errors_1.CliError('--header takes an object', 'For example: --header \'{"Client-Id":"{CLIENT_ID}"}\'');
+    }
+    const headers = {};
+    for (const [name, value] of Object.entries(parsed)) {
+        if (typeof value !== 'string') {
+            throw new errors_1.CliError(`The value of ${name} has to be a string`, 'Header values are text');
+        }
+        headers[name] = value;
+    }
+    return headers;
+}
+/** Is the body meant to be JSON? A form content-type says it is not, and then it goes as typed. */
+function looksJson(headers) {
+    for (const [name, value] of Object.entries(headers ?? {})) {
+        if (name.toLowerCase() === 'content-type')
+            return /json/i.test(value);
+    }
+    return true;
+}
+/**
+ * One-off call to the API behind a connected account, with the platform attaching the
+ * credentials. For looking at what an API returns without deploying a function for it.
+ */
+async function connectionsCall(args) {
+    const alias = args.words[1];
+    const path = args.words[2];
+    if (!alias) {
+        throw new errors_1.CliError('A connection is required', 'Its alias in this project: xflow connections');
+    }
+    if (!path) {
+        throw new errors_1.CliError('A path is required', 'For example: xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01');
+    }
+    const headers = headerArg(args);
+    const body = (0, json_arg_1.bodyArg)(args, 'data');
+    // Judged before anything goes over the network, the same as in functions invoke: a broken
+    // body is the caller's own line. A form body is not judged at all, it is text by design.
+    if (body && looksJson(headers)) {
+        const problem = (0, json_arg_1.jsonProblem)(body.text);
+        if (problem) {
+            throw body.fromFile
+                ? new errors_1.CliError(`${body.fromFile} is not valid JSON: ${problem}`, 'The file has to hold one JSON value')
+                : new errors_1.CliError(`--data is not valid JSON: ${body.text}`, (0, json_arg_1.jsonHint)('data', body.text));
+        }
+    }
+    const { projectId, client } = await (0, session_1.projectTarget)(args);
+    const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/connections/call`, {
+        method: 'POST',
+        body: {
+            connection: alias,
+            path,
+            method: (0, args_1.flagString)(args, 'method') ?? (body ? 'POST' : 'GET'),
+            ...(body ? { body: body.text } : {}),
+            ...(headers ? { headers } : {}),
+        },
+        // Past the platform's own cap on the call, so a slow API reads as a slow API and not as
+        // an unreachable platform.
+        timeoutMs: 60_000,
+    });
+    if ((0, args_1.flagBool)(args, 'json')) {
+        (0, ui_1.out)(JSON.stringify(data, null, 2));
+        return;
+    }
+    const { request, response } = data;
+    (0, ui_1.note)((0, ui_1.dim)(`  ${request.method} ${request.url}`));
+    for (const line of allHeaders(request.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${line}`));
+    const size = response.truncated ? `at least ${(0, ui_1.formatBytes)(response.bytes)}` : (0, ui_1.formatBytes)(response.bytes);
+    (0, ui_1.note)((0, ui_1.dim)(`  ${response.status} in ${data.elapsed_ms} ms, ${size}`));
+    for (const line of shownHeaders(response.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${line}`));
+    const text = typeof response.body === 'string' ? response.body : JSON.stringify(response.body, null, 2);
+    const shown = head(text);
+    if (shown.text)
+        (0, ui_1.out)(shown.text);
+    if (shown.cut || response.truncated) {
+        (0, ui_1.note)((0, ui_1.dim)('  This is the head of the answer, not all of it. Narrow the request with the API own ' +
+            'parameters (a limit, a shorter period), or process the whole set in a cloud function'));
+    }
+    if (!response.ok) {
+        throw new errors_1.CliError(`The API answered ${response.status}`, 'The answer above is theirs, not the platform own');
+    }
+}

package/dist/commands/skills.js

@@ -73,13 +73,29 @@ function skillPath(base, agent, global) {
 function installed(base, agent, global) {
     return (0, node_fs_1.existsSync)(skillPath(base, agent, global));
 }
+/**
+ * A refused write turned into an answer. Agent sandboxes keep `.agents`, `.codex` and
+ * `.git` read-only precisely so that an agent cannot rewrite its own instructions, so
+ * this is the ordinary outcome of an agent running the command, not a broken machine.
+ */
+function writeRefused(path, e) {
+    const code = e instanceof Error ? e.code : undefined;
+    if (code !== 'EACCES' && code !== 'EPERM' && code !== 'EROFS')
+        return e;
+    return new errors_1.CliError(`No permission to write ${path}`, 'An agent sandbox usually keeps .agents, .codex and .git read-only. Ask the person to run this command in their own terminal');
+}
 /** Writes only when the content differs. */
 function writeIfChanged(path, content) {
     const before = (0, node_fs_1.existsSync)(path) ? (0, node_fs_1.readFileSync)(path, 'utf-8') : null;
     if (before === content)
         return null;
-    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
-    (0, node_fs_1.writeFileSync)(path, content, 'utf-8');
+    try {
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, content, 'utf-8');
+    }
+    catch (e) {
+        throw writeRefused(path, e);
+    }
     return before === null ? 'new' : 'updated';
 }
 /**
@@ -118,7 +134,12 @@ function writePointer(base, create) {
     }
     if (before === next)
         return null;
-    (0, node_fs_1.writeFileSync)(path, next, 'utf-8');
+    try {
+        (0, node_fs_1.writeFileSync)(path, next, 'utf-8');
+    }
+    catch (e) {
+        throw writeRefused(path, e);
+    }
     return { path, state: before === null ? 'new' : 'updated' };
 }
 function install(base, ids, global) {
@@ -268,8 +289,11 @@ function installSkillQuietly(base) {
         }
         return true;
     }
-    catch {
-        (0, ui_1.note)((0, ui_1.dim)('  Could not lay out the AI agent instructions: xflow skills'));
+    catch (e) {
+        // The reason travels with the failure: a refused write is fixed by a person running
+        // the command, and "try xflow skills" alone sends the agent round the same wall.
+        (0, ui_1.note)((0, ui_1.dim)(`  Could not lay out the AI agent instructions: ${e instanceof Error ? e.message : e}`));
+        (0, ui_1.note)((0, ui_1.dim)(`  ${e instanceof errors_1.CliError && e.hint ? e.hint : 'Try again: xflow skills'}`));
         return false;
     }
 }

package/dist/flags.js

@@ -61,6 +61,7 @@ exports.KNOWN = {
     'connections list': ['project'],
     'connections link': ['as', 'project'],
     'connections unlink': ['force'],
+    'connections call': ['method', 'data', 'data-file', 'header', 'json', 'project'],
     schedules: ['project'],
     'schedules list': ['project'],
     'schedules set': ['payload', 'payload-file', 'project'],

package/dist/help.js

@@ -367,6 +367,8 @@ the platform into the function.
   xflow connections link <name> --as ALIAS
                                    hand its credentials to the functions
   xflow connections unlink <ALIAS> take them away again
+  xflow connections call <ALIAS> <path>
+                                   ask that API something, once, without deploying
 
 Every row says whether the connection is linked to this project (its alias) and what
 state the access is in. ${(0, ui_1.bold)('available, not linked')} is the useful one: the account
@@ -394,7 +396,41 @@ not to look for another route. Either way only the accounts granted to you perso
 be linked at all: that rule holds whatever the key is allowed to do.
 
 Connecting a new account and switching one off stay with a person, in the platform
-interface. There is no command for either.`,
+interface. There is no command for either.
+
+${(0, ui_1.bold)('call')} answers the question an API only answers by being asked: what does this
+endpoint actually return, and is the field you need in it. The platform attaches the
+credentials of the connected account and makes the request itself, so nothing has to be
+deployed to find out, and the key never reaches you.
+
+  xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
+  xflow connections call AMO /api/v4/leads --method POST --data '{"name":"Test"}'
+  xflow connections call OZON /v1/product/list --method POST --data '{}' \\
+      --header '{"Client-Id":"{CLIENT_ID}"}'
+
+The path is written after the address of the connector, query string and all, or given in
+full as ${(0, ui_1.bold)('https://...')}. Only the hosts of that connector are reachable, and a
+refusal lists them. ${(0, ui_1.bold)('--method')} defaults to GET, or to POST when there is a body.
+
+${(0, ui_1.bold)('{NAME}')} in the path or in a header value is filled in by the platform from the
+fields of the connection. That is how the two-header APIs are called: Ozon wants
+${(0, ui_1.bold)('Client-Id')} beside its key, Yandex Direct wants ${(0, ui_1.bold)('Client-Login')} for an
+agency account, and you never see those values. The names are the ones ${(0, ui_1.bold)('xflow env')}
+shows without the alias in front: ${(0, ui_1.bold)('OZON_CLIENT_ID')} is written ${(0, ui_1.bold)('{CLIENT_ID}')}.
+A name the connection does not have is left in the text as you typed it, so a typo shows up
+in the printed request instead of failing somewhere far away.
+
+The answer is printed head first, at most a few kilobytes, and it says so when there is
+more. Ask for the shape, not the volume: one day and ${(0, ui_1.bold)('limit=1')} tells you what the
+fields are called, while the whole dataset belongs in a cloud function. ${(0, ui_1.bold)('--json')}
+prints the envelope for a pipe: ${(0, ui_1.bold)("--json | jq '.response.body | keys'")} gives the
+field names without the body ever entering your context.
+
+Only an account already linked to this project can be called, because its credentials
+already reach the functions of that project: the command saves a deploy, it does not widen
+what you may touch. An account that is merely available has to be linked first, and that is
+a separate right and a personal grant. The call also goes out for real: ${(0, ui_1.bold)('POST')} and
+${(0, ui_1.bold)('DELETE')} change things in somebody's live account, and no flag will undo that.`,
     schedules: `${(0, ui_1.bold)('xflow schedules')}: running functions on a timer
 
 A schedule is a Yandex timer trigger: it calls the function itself, with no

package/dist/json-arg.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonProblem = jsonProblem;
 exports.jsonHint = jsonHint;
+exports.bodyArg = bodyArg;
 exports.jsonArg = jsonArg;
 const node_fs_1 = require("node:fs");
 const args_1 = require("./args");
@@ -39,8 +40,13 @@ function jsonHint(flag, raw) {
     }
     return `A single JSON value is expected, or keep the body in a file: ${file}`;
 }
-/** The body from --<flag> or --<flag>-file, already known to be JSON. */
-function jsonArg(args, flag) {
+/**
+ * The body from --<flag> or --<flag>-file, whatever it is.
+ *
+ * Not every body is JSON: a connector call carrying a form body sends the text as typed, and
+ * judging it as JSON there would refuse a correct request.
+ */
+function bodyArg(args, flag) {
     const fileFlag = `${flag}-file`;
     const inline = args.flags[flag];
     const path = (0, args_1.flagString)(args, fileFlag);
@@ -49,21 +55,25 @@ function jsonArg(args, flag) {
     }
     if (path !== undefined) {
         if (!(0, node_fs_1.existsSync)(path)) {
-            throw new errors_1.CliError(`No file ${path}`, `--${fileFlag} takes the path to a file with one JSON value`);
+            throw new errors_1.CliError(`No file ${path}`, `--${fileFlag} takes the path to a file with the body`);
         }
-        const text = (0, node_fs_1.readFileSync)(path, 'utf-8').trim();
-        const problem = jsonProblem(text);
-        if (problem)
-            throw new errors_1.CliError(`${path} is not valid JSON: ${problem}`, 'The file has to hold one JSON value');
-        return text;
+        return { text: (0, node_fs_1.readFileSync)(path, 'utf-8').trim(), fromFile: path };
     }
     if (inline === undefined)
         return undefined;
     if (inline === true)
         throw new errors_1.CliError(`--${flag} needs a value`, `For example: --${flag} '{"mode":"full"}'`);
-    const raw = String(inline).trim();
-    const problem = jsonProblem(raw);
-    if (problem)
-        throw new errors_1.CliError(`--${flag} is not valid JSON: ${raw}`, jsonHint(flag, raw));
-    return raw;
+    return { text: String(inline).trim(), fromFile: null };
+}
+/** The body from --<flag> or --<flag>-file, already known to be JSON. */
+function jsonArg(args, flag) {
+    const body = bodyArg(args, flag);
+    if (body === undefined)
+        return undefined;
+    const problem = jsonProblem(body.text);
+    if (!problem)
+        return body.text;
+    throw body.fromFile
+        ? new errors_1.CliError(`${body.fromFile} is not valid JSON: ${problem}`, 'The file has to hold one JSON value')
+        : new errors_1.CliError(`--${flag} is not valid JSON: ${body.text}`, jsonHint(flag, body.text));
 }

package/dist/version.js

@@ -2,6 +2,6 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_API_URL = exports.CLI_VERSION = void 0;
 /** Keep in sync with cli/package.json. */
-exports.CLI_VERSION = '0.12.0';
+exports.CLI_VERSION = '0.13.0';
 /** Overridden by XFLOW_API_URL or the `api` field in xflow.json. */
 exports.DEFAULT_API_URL = 'https://app.getxflow.com';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getxflow/cli",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -24,7 +24,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.12.0. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.13.0. They travel inside the package, so the copy
 you are reading can be older than the CLI answering your commands, and nothing about that
 is visible in the text itself.
 
@@ -368,6 +368,36 @@ owner of the key personally can be linked at all. If the right was taken away, s
 ask the person to turn it back on in the platform settings under Developers: a key cannot
 grant it to itself. Connecting a new account and switching one off stay with a person too.
 
+### Asking an API what it returns
+
+Before writing a function against an unfamiliar API, find out what it actually answers:
+
+```
+xflow connections call WB /api/v1/supplier/stocks?dateFrom=2026-09-01
+xflow connections call OZON /v1/product/list --method POST --data '{}' \
+    --header '{"Client-Id":"{CLIENT_ID}"}'
+```
+
+The platform attaches the credentials and makes the request itself, so no deploy is needed
+and the key never reaches you. Only an account already linked to this project can be called:
+its credentials already reach that project's functions, so this saves a deploy rather than
+widening what you may touch. An account that is only `available, not linked` has to be linked
+first, and that stays a decision for a person.
+
+`{NAME}` in the path or in a header value is filled in from the fields of the connection: the
+names are what `xflow env` shows without the alias in front, so `OZON_CLIENT_ID` is written
+`{CLIENT_ID}`. That is how APIs wanting a second header are called, and you never see the
+value. Only the hosts of that connector are reachable and a refusal lists them.
+
+**Ask for the shape, not the volume.** One day and `limit=1` is enough to learn what the
+fields are called; the answer is printed head first and says when there is more. The whole
+dataset belongs in a cloud function, which is where you were going anyway. `--json | jq
+'.response.body | keys'` gives the field names without the body entering your context at all.
+
+The call goes out for real, against a live account: `POST` and `DELETE` change things there,
+and nothing undoes that. Read the method of the endpoint before calling it, and ask the
+person first when the endpoint is not clearly a read.
+
 ## Schedules
 
 `xflow schedules set report "0 3 ? * * *"` runs a function daily at 03:00. Six fields, UTC,