@getxflow/cli 0.14.0 → 0.14.2

package/dist/api.js

@@ -12,21 +12,20 @@ class ApiError extends Error {
     code;
     status;
     hint;
-    /** Check violations, e.g. why a build was rejected. */
     issues;
-    /** Set when a plan limit was hit. */
     limit;
-    /** Cloud functions a build would delete, with code `confirm_required`. */
     removing;
-    constructor(message, code, status, hint, issues, limit, removing) {
+    request;
+    constructor(message, code, status, hint, details = {}) {
         super(message);
         this.name = 'ApiError';
         this.code = code;
         this.status = status;
         this.hint = hint;
-        this.issues = issues;
-        this.limit = limit;
-        this.removing = removing;
+        this.issues = details.issues;
+        this.limit = details.limit;
+        this.removing = details.removing;
+        this.request = details.request;
     }
 }
 exports.ApiError = ApiError;
@@ -127,7 +126,7 @@ async function readError(response, client) {
     const text = await response.text().catch(() => '');
     try {
         const parsed = JSON.parse(text);
-        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed.issues, parsed.limit, parsed.removing);
+        return new ApiError(parsed.error || `Request rejected (${response.status})`, parsed.code || 'unknown', response.status, parsed.hint, parsed);
     }
     catch {
         return notAnAnswer(response.status, client.apiUrl, text);

package/dist/commands/connections.js

@@ -164,9 +164,6 @@ function head(text) {
 /**
  * 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');
@@ -174,8 +171,18 @@ function shownHeaders(headers) {
         .filter(([name]) => wanted(name.toLowerCase()))
         .map(([name, value]) => `${name}: ${value}`);
 }
-function allHeaders(headers) {
-    return Object.entries(headers).map(([name, value]) => `${name}: ${value}`);
+/**
+ * The request as it went out, printed on the answer and on a refusal alike. On a refusal it
+ * is the whole point: the host of a connector comes from the connection, not from what was
+ * typed, so "check the address" is unfollowable while the address is nowhere on screen.
+ *
+ * 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 showRequest(request) {
+    (0, ui_1.note)((0, ui_1.dim)(`  ${request.method} ${request.url}`));
+    for (const [name, value] of Object.entries(request.headers))
+        (0, ui_1.note)((0, ui_1.dim)(`  ${name}: ${value}`));
 }
 /** Headers typed as JSON. Values may carry {NAME} placeholders, the platform fills those in. */
 function headerArg(args) {
@@ -223,28 +230,32 @@ async function connectionsCall(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));
-        }
-    }
+    if (body && looksJson(headers))
+        (0, json_arg_1.assertJson)('data', body);
     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,
-            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,
-    });
+    let data;
+    try {
+        data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/connections/call`, {
+            method: 'POST',
+            body: {
+                connection,
+                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,
+        });
+    }
+    catch (e) {
+        // Before the refusal itself, in the order of the answer: what went out, then what came of
+        // it. Only the other side's refusals carry it, the rest never assembled an address.
+        if (e instanceof api_1.ApiError && e.request)
+            showRequest(e.request);
+        throw e;
+    }
     if ((0, args_1.flagBool)(args, 'json')) {
         (0, ui_1.out)(JSON.stringify(data, null, 2));
         return;
@@ -254,9 +265,7 @@ async function connectionsCall(args) {
     // service under the same name, the alias is the only thing the caller already knew.
     if (!data.alias)
         (0, ui_1.note)((0, ui_1.dim)(`  ${data.label} (${data.connection_id}), not linked to this project`));
-    (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}`));
+    showRequest(request);
     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))

package/dist/flags.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.KNOWN = void 0;
+exports.WORKING_COPY = exports.KNOWN = void 0;
 exports.checkFlags = checkFlags;
 const args_1 = require("./args");
 const errors_1 = require("./errors");
@@ -19,8 +19,8 @@ const help_1 = require("./help");
  *
  * `--project` is a flag like any other here, and it is written against a command
  * only when that command can answer without the working copy. The ones that cannot
- * (deploy, pull, status, db migrate, env check, env set, connections unlink) have
- * a folder to stand in, and naming a project they cannot read would be a lie.
+ * have a folder to stand in, and naming a project they cannot read would be a lie;
+ * they are listed in WORKING_COPY below, each with what it reads from that folder.
  * `db status` sits halfway: named by id it answers with the applied history alone,
  * without the comparison against migrations/.
  *
@@ -87,6 +87,27 @@ exports.KNOWN = {
     deployments: ['project'],
     update: [],
 };
+/**
+ * What each of those commands reads from the working copy, in its own words.
+ *
+ * `has no flag --project` alone leaves the reader one dead end short of the answer:
+ * the next try, without the flag, ends at the missing xflow.json, and neither line
+ * tells a rule from an oversight. Naming the file the command would have to read
+ * does, and it also says when the errand needs no folder at all.
+ *
+ * Keys are the commands KNOWN keeps `--project` from, and flags.test.ts holds the
+ * two lists against each other: a command that later gains the flag has to lose its
+ * line here, or a refusal nobody prints any more stays behind as a lie.
+ */
+exports.WORKING_COPY = {
+    deploy: 'it sends the sources next to it',
+    pull: 'it writes the sources next to it',
+    status: 'it compares the folder with the revision on the platform',
+    'db migrate': 'it applies the files of migrations/',
+    'env check': 'it looks for the variables the code of the functions reads',
+    'env set': 'it names the functions that need a deploy for the value to arrive',
+    'connections unlink': 'it reads functions/ to name the functions that would lose the variables. Only trying an API out? That needs no link: xflow connections call',
+};
 /** Answered everywhere: both are handled before the command runs. */
 const GLOBAL = new Set(['help', 'version']);
 /**
@@ -118,6 +139,15 @@ function commandOf(words) {
     }
     return Object.hasOwn(exports.KNOWN, first) ? first : null;
 }
+function hintFor(command, flag, allowed, page) {
+    const reads = exports.WORKING_COPY[command];
+    if (flag === 'project' && reads !== undefined) {
+        return `It works in the project folder: ${reads}. Which commands take --project: xflow help project`;
+    }
+    return allowed.length > 0
+        ? `It takes ${allowed.map((name) => `--${name}`).join(', ')}. What each one does: ${page}`
+        : `It takes no flags. What it does: ${page}`;
+}
 function checkFlags(args) {
     const command = commandOf(args.words);
     if (command === null)
@@ -131,9 +161,7 @@ function checkFlags(args) {
         if (GLOBAL.has(name))
             continue;
         if (!allowed.includes(name)) {
-            throw new errors_1.CliError(`xflow ${command} has no flag --${name}`, allowed.length > 0
-                ? `It takes ${allowed.map((flag) => `--${flag}`).join(', ')}. What each one does: ${page}`
-                : `It takes no flags. What it does: ${page}`);
+            throw new errors_1.CliError(`xflow ${command} has no flag --${name}`, hintFor(command, name, allowed, page));
         }
         // The value went missing, so the flag arrived as a bare switch. Left alone it
         // would mean the default, which is never what the person typing it wanted.

package/dist/help.js

@@ -254,7 +254,7 @@ About destructive ones. The platform keeps no database history and makes no back
 so ${(0, ui_1.bold)('DROP TABLE')}, ${(0, ui_1.bold)('DROP COLUMN')}, ${(0, ui_1.bold)('TRUNCATE')} and ${(0, ui_1.bold)('DELETE FROM')} without a
 condition need two things at once: this flag, and the right to destroy data on the
 access key. That right is off by default, and only its owner turns it on, in the
-platform settings under Developers: a flag is something an agent adds by itself, a
+platform settings, where the key permissions live: a flag is something an agent adds by itself, a
 right is not. With both in place, the contents of the affected tables are dumped and
 kept for 7 days: that is a "caught it right away" safety net, not a backup.
 ${(0, ui_1.bold)('DROP DATABASE')} is never allowed, because the database is shared across the
@@ -321,8 +321,8 @@ Dot entries and symbolic links are skipped, and ${(0, ui_1.bold)('.xflowignore')
 those are the rules for the sources, and a media folder is exactly what one is
 asked to put there so it stays out of the archive.
 
-${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')} in the Developers section of the
-platform), off by default. The reason is the neighbourhood: whatever the users of
+${(0, ui_1.bold)('rm')} needs a right of its own (${(0, ui_1.bold)('Delete files')}, where the key permissions live in
+the platform settings), off by default. The reason is the neighbourhood: whatever the users of
 the application uploaded lives in the same folders, and there is no undo. A folder
 first answers with the number of files it holds and deletes only on ${(0, ui_1.bold)('--yes')}.
 
@@ -381,7 +381,9 @@ of the same service under one name; then the command prints their identifiers an
 for one of those instead of guessing.
 
 ${(0, ui_1.bold)('unlink')} refuses while a function still reads one of the variables and names
-those functions; ${(0, ui_1.bold)('--force')} goes through anyway.
+those functions; ${(0, ui_1.bold)('--force')} goes through anyway. Seeing them needs the sources,
+which is why ${(0, ui_1.bold)('unlink')} works in the project folder and takes no ${(0, ui_1.bold)('--project')}
+while ${(0, ui_1.bold)('link')} takes it: only one of the two reads your code.
 
 Variables are named after the alias: an OAuth connection called ${(0, ui_1.bold)('YANDEX_METRIKA')}
 gives ${(0, ui_1.bold)('YANDEX_METRIKA_TOKEN')}, a key-based one gives a variable per field. They
@@ -390,7 +392,7 @@ run ${(0, ui_1.bold)('xflow deploy')}. A token close to expiry is renewed by any
 a revoked one is not renewed by anything until a human reconnects the account.
 
 Linking needs a right on the key, ${(0, ui_1.bold)('connections:link')}. Keys are issued with it,
-and a person can take it away in the platform settings under Developers; a key cannot give
+and a person can take it away in the platform settings, where the key permissions live; a key cannot give
 it back to itself. Losing it is what the refusal says, and the answer is to ask a person,
 not to look for another route. Either way only the accounts granted to you personally can
 be linked at all: that rule holds whatever the key is allowed to do.

package/dist/json-arg.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.jsonProblem = jsonProblem;
 exports.jsonHint = jsonHint;
 exports.bodyArg = bodyArg;
+exports.assertJson = assertJson;
 exports.jsonArg = jsonArg;
 const node_fs_1 = require("node:fs");
 const args_1 = require("./args");
@@ -30,15 +31,19 @@ function jsonProblem(raw) {
         return e instanceof Error ? e.message : String(e);
     }
 }
-/** Where to look, and on a stripped value the shell is the first suspect. */
+/**
+ * Where to look, and on a stripped value the shell is the first suspect.
+ *
+ * No file is offered here: not every JSON flag has that twin, and --header used to be sent
+ * to --header-file, which the flag check refuses one line later. A hint has to survive being
+ * followed, so the offer lives in assertJson, the one path that reads a file.
+ */
 function jsonHint(flag, raw) {
-    const file = `--${flag}-file body.json`;
     if (quotesStripped(raw.trim())) {
         return (`Not one double quote survived: the shell removed them, PowerShell does this to ` +
-            `native calls. Escape them: --${flag} '{\\"key\\":\\"value\\"}', or keep the body ` +
-            `in a file: ${file}`);
+            `native calls. Escape them: --${flag} '{\\"key\\":\\"value\\"}'`);
     }
-    return `A single JSON value is expected, or keep the body in a file: ${file}`;
+    return 'A single JSON value is expected';
 }
 /**
  * The body from --<flag> or --<flag>-file, whatever it is.
@@ -65,15 +70,23 @@ function bodyArg(args, flag) {
         throw new errors_1.CliError(`--${flag} needs a value`, `For example: --${flag} '{"mode":"full"}'`);
     return { text: String(inline).trim(), fromFile: null };
 }
+/**
+ * Refuse a body that is not JSON. Takes what bodyArg returned, and only this path names
+ * --<flag>-file: a flag read through bodyArg has that twin by construction.
+ */
+function assertJson(flag, body) {
+    const problem = jsonProblem(body.text);
+    if (!problem)
+        return;
+    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)}, or keep the body in a file: --${flag}-file body.json`);
+}
 /** 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));
+    assertJson(flag, body);
+    return 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.14.0';
+exports.CLI_VERSION = '0.14.2';
 /** 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.14.0",
+  "version": "0.14.2",
   "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.14.0. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.14.2. 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.
 
@@ -360,13 +360,14 @@ unavailable: the account you need is often connected already, one link away.
 
 `xflow connections link "Яндекс Метрика" --as YANDEX_METRIKA` is that link and
 `xflow connections unlink YANDEX_METRIKA` undoes it; `xflow help connections` has the
-naming rules and the flags. Unlink refuses while a function still reads one of the
-variables and names those functions, so read that list before reaching for `--force`.
+naming rules and the flags. Unlink reads `functions/`, so it runs in the project folder:
+it refuses while a function still reads one of the variables and names those functions,
+so read that list before reaching for `--force`.
 
 Linking needs the `connections:link` right on the key, and only accounts granted to the
 owner of the key personally can be linked at all; the same right covers calling an unlinked
 account. If the right was taken away, say so and
-ask the person to turn it back on in the platform settings under Developers: a key cannot
+ask the person to turn it back on where the key permissions live in the platform settings: 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
@@ -388,7 +389,7 @@ one by its name: **linking first is not needed to look**, so do not ask a person
 something. To use the account in code, link it and deploy.
 
 Two refusals do need a person, and different ones: `connections:link` right — the owner of the
-key grants it under Developers; `not granted to you` — ask whoever connected the account.
+key grants it where the key permissions live; `not granted to you` — ask whoever connected the account.
 
 `{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
@@ -448,8 +449,8 @@ fills those in itself, and your value under one of them would shadow the real on
 The platform keeps no database history and no backups, so anything that destroys data
 (`DROP TABLE`, `DROP COLUMN`, `TRUNCATE`, `DELETE FROM` without a condition) needs two
 things at once: the `--allow-destructive` flag, and the right to destroy data on the key.
-That right is off by default and only its owner turns it on, under Developers in the
-platform settings. When the refusal is about the right rather than the flag, adding the flag
+That right is off by default and only its owner turns it on, where the key permissions live in
+the platform settings. When the refusal is about the right rather than the flag, adding the flag
 changes nothing: say what needs deleting and why, and let the person decide. With both in
 place the affected tables are dumped first and kept for 7 days. Check with `--dry-run` first.
 
@@ -488,8 +489,8 @@ whose size differs. An address belongs to the record rather than to the bytes, s
 replacement keeps it and the links in your code and tables keep working. Put those addresses
 into the code or into a table: there is no command that fetches files back to a machine.
 
-Deleting needs a right of its own, off by default (**Delete files** in the Developers
-section of the platform), so `xflow storage rm` may answer that the key was not granted it.
+Deleting needs a right of its own, off by default (**Delete files**, where the key permissions
+live in the platform settings), so `xflow storage rm` may answer that the key was not granted it.
 Ask the person to switch it on, and do not look for a way around: whatever the users of the
 application uploaded lives in the same folders, and there is no undo. A folder first tells
 you how many files it holds and deletes them only with `--yes`.