@getxflow/cli 0.10.2 → 0.10.3

package/dist/args.js

@@ -1,22 +1,22 @@
 "use strict";
 /** Argument parsing, dependency-free. */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.BOOLEAN_FLAGS = void 0;
 exports.parseArgs = parseArgs;
 exports.flagString = flagString;
 exports.flagBool = flagBool;
 exports.flagNumber = flagNumber;
 /** Flags that never take a value, so `--force ./dir` keeps the path as a word. */
-const BOOLEAN_FLAGS = new Set([
+exports.BOOLEAN_FLAGS = new Set([
     'force',
     'yes',
     'json',
+    'replace',
     'help',
     'version',
     'global',
     'refresh',
-    'live',
     'no-push',
-    'skip-build',
     'all',
     'dry-run',
     'allow-destructive',
@@ -40,7 +40,7 @@ function parseArgs(argv) {
                 continue;
             }
             const next = argv[i + 1];
-            if (BOOLEAN_FLAGS.has(body) || next === undefined || next.startsWith('-')) {
+            if (exports.BOOLEAN_FLAGS.has(body) || next === undefined || next.startsWith('-')) {
                 flags[body] = true;
             }
             else {

package/dist/bin.js

@@ -6,6 +6,7 @@ const args_1 = require("./args");
 const config_1 = require("./config");
 const credentials_1 = require("./credentials");
 const errors_1 = require("./errors");
+const flags_1 = require("./flags");
 const help_1 = require("./help");
 const limits_1 = require("./limits");
 const state_1 = require("./state");
@@ -255,6 +256,7 @@ async function main() {
     // carries the same advice in its hint.
     let quiet = args.words[0] === 'update';
     try {
+        (0, flags_1.checkFlags)(args);
         await run(args);
         return 0;
     }

package/dist/commands/env.js

@@ -164,7 +164,10 @@ async function envSet(args) {
     const value = pair.slice(pair.indexOf('=') + 1);
     const result = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/env`, {
         method: 'POST',
-        body: { name, value, scope: (0, args_1.flagString)(args, 'scope') === 'project' ? 'project' : 'organization' },
+        // The word goes to the platform as typed: it knows the two scopes and
+        // refuses a third. Guessing here would have made --scope proj mean the
+        // whole organization, which is the opposite of what such a typo means.
+        body: { name, value, scope: (0, args_1.flagString)(args, 'scope') },
     });
     (0, ui_1.ok)(`${(0, ui_1.bold)(result.name)} stored (${result.scope === 'project' ? 'this project only' : 'the whole organization'})`);
     // Values reach a function on its next deploy.

package/dist/commands/functions.js

@@ -6,6 +6,7 @@ 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");
 /** Who can call the function: inside the app only, or an outside service holding a key. */
@@ -46,6 +47,11 @@ async function functionsInvoke(args) {
     const name = args.words[1];
     if (!name)
         throw new errors_1.CliError('A function name is required', 'What is deployed: xflow functions list');
+    // The body is judged before anything goes over the network: a broken one is the
+    // user's own line, and it costs nothing to say so at once.
+    const data = (0, json_arg_1.jsonArg)(args, 'data');
+    const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
+    const sendsBody = method !== 'GET' && method !== 'HEAD';
     const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}`);
     const fn = card.functions.find((item) => item.name === name);
     if (!fn || !fn.invoke_url) {
@@ -53,9 +59,6 @@ async function functionsInvoke(args) {
             ? `Deployed: ${card.functions.map((item) => item.name).join(', ')}`
             : 'Functions ship with the build: xflow deploy');
     }
-    const data = (0, args_1.flagString)(args, 'data');
-    const method = ((0, args_1.flagString)(args, 'method') ?? (data ? 'POST' : 'GET')).toUpperCase();
-    const sendsBody = method !== 'GET' && method !== 'HEAD';
     // A pass for the person who owns the key: the project token alone is not an
     // identity, and a project built with the current template refuses without one.
     // A read-only key cannot get a pass, so the call still goes out without it.

package/dist/commands/schedules.js

@@ -4,9 +4,9 @@ exports.schedulesList = schedulesList;
 exports.schedulesSet = schedulesSet;
 exports.schedulesRemove = schedulesRemove;
 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");
 async function schedulesList() {
@@ -33,9 +33,10 @@ async function schedulesSet(args) {
     if (!functionName || !cron) {
         throw new errors_1.CliError('A function name and a schedule are required', 'For example: xflow schedules set nightly-report "0 3 ? * * *" runs every day at 03:00 UTC');
     }
+    const payload = (0, json_arg_1.jsonArg)(args, 'payload') ?? null;
     const row = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}/schedules`, {
         method: 'POST',
-        body: { function: functionName, cron, payload: (0, args_1.flagString)(args, 'payload') ?? null },
+        body: { function: functionName, cron, payload },
     });
     (0, ui_1.ok)(`${(0, ui_1.bold)(row.function)} runs ${row.description}`);
     (0, ui_1.note)((0, ui_1.dim)(`  The time is UTC. To check by hand: xflow functions invoke ${row.function}`));

package/dist/flags.js

@@ -0,0 +1,129 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkFlags = checkFlags;
+const args_1 = require("./args");
+const errors_1 = require("./errors");
+const help_1 = require("./help");
+/**
+ * Which flags each command answers to.
+ *
+ * An unknown flag used to pass in silence, and one written before a word ate that
+ * word: `functions logs --nosuch flows` answered for every function instead of the
+ * one asked for, and the answer looked truthful. A mistyped switch is worse still:
+ * `db migrate --dryrun` applied the migrations for real.
+ *
+ * Keys are the command as it is typed. A command that is not here is not checked,
+ * so a new one keeps working until it is added, and the list also drives the hint:
+ * whoever is at the keyboard gets the flags of this very command back.
+ */
+const KNOWN = {
+    help: [],
+    login: [],
+    logout: ['all'],
+    whoami: [],
+    org: [],
+    'org list': [],
+    'org switch': [],
+    templates: [],
+    init: ['name', 'template', 'database'],
+    link: [],
+    projects: [],
+    'projects list': [],
+    'projects get': [],
+    skills: ['refresh', 'global', 'agent', 'yes'],
+    mcp: ['show-token'],
+    'mcp install': ['show-token'],
+    functions: [],
+    'functions list': [],
+    'functions invoke': ['data', 'data-file', 'method'],
+    'functions logs': ['limit'],
+    logs: ['limit'],
+    env: [],
+    'env list': [],
+    'env set': ['scope'],
+    'env rm': [],
+    'env remove': [],
+    'env check': [],
+    connections: [],
+    'connections list': [],
+    'connections link': ['as'],
+    'connections unlink': ['force'],
+    schedules: [],
+    'schedules list': [],
+    'schedules set': ['payload', 'payload-file'],
+    'schedules rm': [],
+    'schedules remove': [],
+    db: [],
+    'db status': [],
+    'db schema': [],
+    'db query': ['limit'],
+    'db migrate': ['dry-run', 'allow-destructive'],
+    storage: ['json'],
+    'storage ls': ['json'],
+    'storage list': ['json'],
+    'storage push': ['to', 'replace', 'json'],
+    'storage rm': ['folder', 'yes'],
+    'storage remove': ['folder', 'yes'],
+    status: [],
+    pull: ['into', 'force', 'revision'],
+    deploy: ['no-push', 'force', 'allow-removals'],
+    publish: [],
+    rollback: [],
+    deployments: [],
+    update: [],
+};
+/** Answered everywhere: both are handled before the command runs. */
+const GLOBAL = new Set(['help', 'version']);
+/**
+ * Commands whose second word is a subcommand rather than a value. An unknown one
+ * belongs to the dispatcher, which names it and lists the real ones: complaining
+ * about a flag of a command that does not exist would send the reader the wrong way.
+ */
+const NAMESPACES = new Set([
+    'org',
+    'projects',
+    'functions',
+    'env',
+    'connections',
+    'schedules',
+    'db',
+    'storage',
+    'mcp',
+]);
+/** The command these words name, as far as the table knows it. */
+function commandOf(words) {
+    const [first, second] = words;
+    if (!first)
+        return null;
+    if (second !== undefined) {
+        if (Object.hasOwn(KNOWN, `${first} ${second}`))
+            return `${first} ${second}`;
+        if (NAMESPACES.has(first))
+            return null;
+    }
+    return Object.hasOwn(KNOWN, first) ? first : null;
+}
+function checkFlags(args) {
+    const command = commandOf(args.words);
+    if (command === null)
+        return;
+    const allowed = KNOWN[command];
+    const topic = command.split(' ')[0];
+    // Not every command has a page, and sending the reader to "No page for login"
+    // would be a second dead end in the same breath as the first.
+    const page = (0, help_1.hasHelpPage)(topic) ? `xflow help ${topic}` : 'xflow help';
+    for (const [name, value] of Object.entries(args.flags)) {
+        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}`);
+        }
+        // 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.
+        if (value === true && !args_1.BOOLEAN_FLAGS.has(name)) {
+            throw new errors_1.CliError(`--${name} needs a value`, `Put it after the flag, or write --${name}=value when the value starts with a dash`);
+        }
+    }
+}

package/dist/help.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasHelpPage = hasHelpPage;
 exports.help = help;
 const ui_1 = require("./ui");
 const version_1 = require("./version");
@@ -14,6 +15,10 @@ const ALIASES = {
     deployments: 'rollback',
 };
 /** Help text. For agents this is the reference documentation. */
+/** Whether `xflow help <topic>` has a page: a hint that sends nowhere is a second dead end. */
+function hasHelpPage(topic) {
+    return Object.hasOwn(TOPICS, ALIASES[topic] ?? topic);
+}
 function help(topic) {
     if (topic) {
         const page = TOPICS[ALIASES[topic] ?? topic];
@@ -259,7 +264,11 @@ the function. So keep your own copy wherever you got it from.
   xflow env set SMTP_PASSWORD=…    store
   xflow env rm SMTP_PASSWORD       delete
 
-  --scope project                  visible to this project only, not the whole organization
+  --scope project                  visible to this project only
+  --scope organization             visible to every project of the organization (the default)
+
+Those two words are the whole list: a third is refused rather than read as the default,
+because a value meant for one project would have gone out to all of them.
 
 ${(0, ui_1.bold)('check')} reads the sources in ${(0, ui_1.bold)('functions/')} and looks for ${(0, ui_1.bold)('process.env.NAME')}
 references. The same rule applies on deploy: a function receives only the variables it
@@ -326,6 +335,7 @@ the day-of-month and day-of-week fields has to be ${(0, ui_1.bold)('?')}, which
 how Yandex works. ${(0, ui_1.bold)('The time is always UTC')}, local time is not understood.
 
   --payload '{"mode":"full"}'      the body the function will receive
+  --payload-file body.json         the same body from a file
 
 A scheduled run arrives at the handler as a POST with no headers, and the project
 token is not checked on it: such an event cannot be forged from outside. The function
@@ -339,8 +349,13 @@ Calls it exactly the way the application does: the project token plus a visitor
 for the person who owns the key, so the function sees a real caller and its role.
 Both are taken from the platform, no local .env is needed.
 
-  --data '{"a":1}'   request body (the method becomes POST by default)
-  --method GET       a different method
+  --data '{"a":1}'        request body (the method becomes POST by default)
+  --data-file body.json   the same body from a file
+  --method GET            a different method
+
+The body has to be JSON, and it is checked before the call goes out: PowerShell
+strips double quotes from a native call, so ${(0, ui_1.bold)('--data')} needs them escaped there
+(${(0, ui_1.bold)('--data \'{\\"a\\":1}\'')}) and a file needs nothing.
 
 Prints the status, the response time and the body. A non-zero exit code on 4xx and
 5xx: in CI such a call has to fail the step. The cause of a crash is shown by

package/dist/json-arg.js

@@ -0,0 +1,69 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.jsonProblem = jsonProblem;
+exports.jsonHint = jsonHint;
+exports.jsonArg = jsonArg;
+const node_fs_1 = require("node:fs");
+const args_1 = require("./args");
+const errors_1 = require("./errors");
+/**
+ * A JSON body typed on the command line: --data for a call, --payload for a
+ * schedule. Checked here, before it leaves: PowerShell strips the double quotes
+ * out of a native call, and an unchecked body arrives at the function as garbage,
+ * so a shell problem looks like a crash in the project's own code.
+ */
+/** No quote left where JSON needs them: a shell ate them, this is not a typo. */
+function quotesStripped(raw) {
+    return !raw.includes('"') && /^[{[]/.test(raw);
+}
+/** What the parser says about the text, or null when it is JSON. */
+function jsonProblem(raw) {
+    const text = raw.trim();
+    if (!text)
+        return 'the value is empty';
+    try {
+        JSON.parse(text);
+        return null;
+    }
+    catch (e) {
+        return e instanceof Error ? e.message : String(e);
+    }
+}
+/** Where to look, and on a stripped value the shell is the first suspect. */
+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}`);
+    }
+    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) {
+    const fileFlag = `${flag}-file`;
+    const inline = args.flags[flag];
+    const path = (0, args_1.flagString)(args, fileFlag);
+    if (inline !== undefined && path !== undefined) {
+        throw new errors_1.CliError(`--${flag} and --${fileFlag} cannot be used together`, 'Give the body once');
+    }
+    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`);
+        }
+        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;
+    }
+    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;
+}

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.10.2';
+exports.CLI_VERSION = '0.10.3';
 /** 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.10.2",
+  "version": "0.10.3",
   "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.10.2. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.10.3. 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.
 
@@ -234,10 +234,15 @@ you to delete. Put the directories back instead, and if the removal really is in
 which functions are about to go and let the user answer.
 
 Debugging a deployed function is two commands: `xflow functions invoke <name>` calls it
-the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body),
-and `xflow functions logs <name>` shows the failures, each with its stack and the console
-output of that call. Only failed calls are logged, so an empty output means the function
-never crashed, not that logging is broken.
+the way the app does and prints status, timing and body (`--data '{"a":1}'` sends a body,
+`--data-file body.json` sends the same from a file), and `xflow functions logs <name>` shows
+the failures, each with its stack and the console output of that call. Only failed calls are
+logged, so an empty output means the function never crashed, not that logging is broken.
+
+The body has to be JSON and the CLI checks it before calling. In PowerShell the double
+quotes never reach the CLI: `--data '{"a":1}'` arrives as `{a:1}`, so escape them
+(`--data '{\"a\":1}'`) or pass a file. This is a shell habit, not a bug in the function, and
+it bites `--payload` of a schedule the same way.
 
 From the app, call a function through `src/lib/xflow.ts`:
 `await xflow.functions.invoke('send-mail', { body: { to } })`. It carries the credentials
@@ -303,6 +308,11 @@ writes one, `xflow env` lists the names, `xflow env check` tells you which varia
 functions read but the platform does not have. Values never come back out — the only place
 they exist is inside the running function.
 
+A variable goes to the whole organization unless you say otherwise: `--scope project` keeps it
+to this project alone, `--scope organization` is the default, and a third word is refused
+rather than read as the default. Pick the narrow one for anything that belongs to one
+application.
+
 These commands see only what this project can see: variables shared across the organization
 and the ones bound to this project. A variable bound to another project is invisible here, so
 `env rm` reports it as missing even though names are unique within the organization.
@@ -342,7 +352,9 @@ grant it to itself. Connecting a new account and switching one off stay with a p
 `xflow schedules set report "0 3 ? * * *"` runs a function daily at 03:00. Six fields, UTC,
 and exactly one of day-of-month / day-of-week must be `?` — that is how Yandex wants it.
 A scheduled run reaches the handler as a POST with no headers, and `--payload '{"mode":"full"}'`
-is how it gets a body. How often a schedule may run is a plan limit, see **Plan limits**.
+(or `--payload-file body.json`) is how it gets a body. The payload has to be JSON: a broken one
+is refused when the schedule is set, not at three in the morning with nobody watching. How often
+a schedule may run is a plan limit, see **Plan limits**.
 
 The pieces line up in one pass. From a new function to a verified schedule: