@getxflow/cli 0.22.0 → 0.24.0

package/dist/commands/deploy.js

@@ -26,7 +26,9 @@ function reportIssues(e) {
         (0, ui_1.out)(`  ${(0, ui_1.bold)(issue.code)} ${where}`);
         (0, ui_1.note)((0, ui_1.dim)(`    ${issue.message}`));
     }
-    throw new errors_1.CliError(e.message, e.hint);
+    // Not the platform hint: it names its own JSON field, and a terminal has no field,
+    // it has the list printed right above.
+    throw new errors_1.CliError(e.message, 'Fix what is listed above and retry: the build did not start');
 }
 /** Poll the build until it finishes, printing phases. */
 async function waitForBuild(client, projectId, started) {

package/dist/commands/dev.js

@@ -38,7 +38,14 @@ async function dev() {
     // Ctrl+C reaches the server on its own; staying alive until it is gone is what
     // hands its exit code back instead of leaving it to print over the prompt.
     process.on('SIGINT', () => { });
-    const result = (0, spawn_1.run)('npm', ['run', 'dev'], { stdio: 'inherit', cwd: root, env });
+    // Appended last, so it beats the --host of the dev script: the server holds the key
+    // of the project and answers this machine alone. By number, not by name: proxies of
+    // older templates cut the Host at ':' and so never match [::1].
+    const result = (0, spawn_1.run)('npm', ['run', 'dev', '--', '--host', '127.0.0.1'], {
+        stdio: 'inherit',
+        cwd: root,
+        env,
+    });
     if (result.error) {
         throw new errors_1.CliError(`Could not start npm run dev: ${result.error.message}`, 'npm ships with Node.js: check that npm works in this terminal');
     }

package/dist/commands/functions.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.functionsList = functionsList;
+exports.failureHint = failureHint;
 exports.functionsInvoke = functionsInvoke;
 const api_1 = require("../api");
 const args_1 = require("../args");
@@ -38,6 +39,37 @@ function prettyBody(text) {
         return text;
     }
 }
+/**
+ * Refusals the wrapper writes itself, before the handler runs. Nothing about them
+ * reaches the logs, and the answer already names the cause.
+ *
+ * Matched by value and not by the presence of the field, because a handler is free to
+ * put a reason of its own into the body it returns, and that one did run.
+ *
+ * Keep in sync with lib/yandex-functions/call-outcome.ts, which the MCP tool calls:
+ * this package ships without dependencies and cannot reach into the platform. One test
+ * holds the two halves together.
+ */
+const WRAPPER_REASONS = ['no_pass', 'invalid', 'expired', 'no_access', 'unavailable', 'role'];
+/** What to look at next, when the function did not answer with a success. */
+function failureHint(name, status, body) {
+    let reason;
+    try {
+        reason = JSON.parse(body).reason;
+    }
+    catch {
+        reason = undefined;
+    }
+    const logs = `The stack and console output: xflow functions logs ${name}`;
+    if (typeof reason !== 'string' || !WRAPPER_REASONS.includes(reason))
+        return logs;
+    if (reason !== 'role' || status < 500)
+        return undefined;
+    // Two different answers wear this one: a threshold the platform cannot read, refused
+    // before the handler and so absent from the logs, and a handler that answered 5xx with
+    // a reason of that name itself, which is logged. Emptiness there tells them apart.
+    return `${logs}. Nothing there means the declared minRole is the problem: fix functions/${name}/index.ts`;
+}
 /** Call a function the same way the application does. */
 async function functionsInvoke(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);
@@ -95,6 +127,6 @@ async function functionsInvoke(args) {
     if (text)
         (0, ui_1.out)((0, args_1.flagBool)(args, 'json') ? text : prettyBody(text));
     if (!response.ok) {
-        throw new errors_1.CliError(`The function answered ${response.status}`, `The stack and console output: xflow functions logs ${name}`);
+        throw new errors_1.CliError(`The function answered ${response.status}`, failureHint(name, response.status, text));
     }
 }

package/dist/commands/schedules.js

@@ -8,6 +8,13 @@ const errors_1 = require("../errors");
 const json_arg_1 = require("../json-arg");
 const session_1 = require("../session");
 const ui_1 = require("../ui");
+/**
+ * The payload is kept as it was written, and `--payload-file` takes a file a person
+ * formatted: its newlines would break a row of a table into several.
+ */
+function oneLine(payload) {
+    return (payload ?? '').replace(/\s+/g, ' ').trim();
+}
 async function schedulesList(args) {
     const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/schedules`);
@@ -16,12 +23,18 @@ async function schedulesList(args) {
         (0, ui_1.note)((0, ui_1.dim)('  To run a function on a timer: xflow schedules set <function> "0 3 ? * * *"'));
         return;
     }
-    (0, ui_1.table)(data.schedules.map((row) => [
-        row.function,
-        row.cron,
-        row.description === row.cron ? '' : row.description,
-        row.status === 'active' ? '' : (row.error ?? row.status),
-    ]));
+    (0, ui_1.table)(data.schedules.map((row) => {
+        // The body the timer sends. Nothing else printed it, so a schedule said when a
+        // function runs and never what it gets.
+        const payload = oneLine(row.payload);
+        return [
+            row.function,
+            row.cron,
+            row.description === row.cron ? '' : row.description,
+            payload.length > 40 ? `${payload.slice(0, 39)}…` : payload,
+            row.status === 'active' ? '' : (row.error ?? row.status),
+        ];
+    }));
 }
 async function schedulesSet(args) {
     const functionName = args.words[1];
@@ -36,6 +49,8 @@ async function schedulesSet(args) {
         body: { function: functionName, cron, payload },
     });
     (0, ui_1.ok)(`${(0, ui_1.bold)(row.function)} runs ${row.description}`);
+    if (row.payload)
+        (0, ui_1.note)((0, ui_1.dim)(`  The timer sends: ${oneLine(row.payload)}`));
     (0, ui_1.note)((0, ui_1.dim)(`  The time is UTC. To check by hand: xflow functions invoke ${row.function}`));
 }
 async function schedulesRemove(args) {

package/dist/commands/sources.js

@@ -75,21 +75,27 @@ async function pushSources(root, config, client, options) {
     const tree = prepareTree(root, config);
     const state = (0, config_1.readState)(root);
     const server = await latestRevision(client, config.projectId);
-    if (server && server.tree_hash === tree.hash) {
-        (0, config_1.writeState)(root, {
-            treeHash: server.tree_hash,
-            organizationId: client.organizationId ?? undefined,
-        });
-        (0, ui_1.ok)(`No changes, revision ${server.revision}`);
-        return { revision: server.revision, status: 'unchanged' };
-    }
-    // Asked before the upload, so a doomed archive never leaves the machine.
-    if (server && server.tree_hash !== state.treeHash && !options.force) {
-        throw new errors_1.CliError(`The server holds revision ${server.revision}, and this folder does not stand on it`, 'Someone deployed before you, or this folder worked on a different project. ' +
-            'Fetch the server copy alongside and compare: xflow pull --into ./server-copy');
-    }
-    if (options.force && server && server.tree_hash !== tree.hash) {
-        await confirmForce(client, config.projectId, server, tree.files);
+    if (server) {
+        const relation = (0, tree_1.syncState)(tree.hash, server.tree_hash, state.treeHash);
+        if (relation === 'matches') {
+            (0, config_1.writeState)(root, {
+                treeHash: server.tree_hash,
+                organizationId: client.organizationId ?? undefined,
+            });
+            (0, ui_1.ok)(`No changes, revision ${server.revision}`);
+            return { revision: server.revision, status: 'unchanged' };
+        }
+        // Asked before the upload, so a doomed archive never leaves the machine.
+        if (relation === 'diverged' && !options.force) {
+            throw new errors_1.CliError(`The server holds revision ${server.revision}, and this folder does not stand on it`, 'Someone deployed before you, or this folder worked on a different project. ' +
+                'Fetch the server copy alongside and compare: xflow pull --into ./server-copy');
+        }
+        if (options.force) {
+            await confirmForce(client, config.projectId, server, tree.files);
+        }
+        else if (relation === 'unrecorded') {
+            (0, ui_1.warn)(`This folder has no record of the server revision: the code goes up on top of revision ${server.revision}`);
+        }
     }
     (0, ui_1.step)(`Sending ${tree.files.length} files (${(0, ui_1.formatBytes)(tree.archive.length)})`);
     const headers = {};
@@ -161,13 +167,10 @@ async function pull(args) {
             'xflow pull --into ./server-copy, or overwrite the folder completely: xflow pull --force');
     }
     const { info, files } = await downloadRevision(client, config.projectId, target, (0, args_1.flagNumber)(args, 'revision'));
-    // Only the working folder tracks revisions; a side copy (--into) must not reset them.
-    if (!into) {
-        (0, config_1.writeState)(root, {
-            treeHash: info.tree_hash,
-            organizationId: client.organizationId ?? undefined,
-        });
-    }
+    (0, config_1.writeState)(target, {
+        treeHash: info.tree_hash,
+        organizationId: client.organizationId ?? undefined,
+    });
     (0, ui_1.ok)(`Revision ${info.revision}: ${files} files in ${target}`);
 }
 async function status() {
@@ -191,13 +194,18 @@ async function status() {
     }
     else {
         (0, ui_1.out)(`On the server: revision ${server.revision}, ${server.file_count} files, ${(0, ui_1.formatAge)(server.created_at)}`);
-        if (server.tree_hash === tree.hash) {
+        const relation = (0, tree_1.syncState)(tree.hash, server.tree_hash, state.treeHash);
+        if (relation === 'matches') {
             (0, ui_1.out)('State: matches the server');
         }
-        else if (server.tree_hash !== state.treeHash) {
+        else if (relation === 'diverged') {
             (0, ui_1.out)(`State: ${(0, ui_1.bold)('diverged')}, the server holds a version this folder has not seen`);
             (0, ui_1.note)((0, ui_1.dim)('  Fetch the server copy alongside: xflow pull --into ./server-copy'));
         }
+        else if (relation === 'unrecorded') {
+            (0, ui_1.out)(`State: ${(0, ui_1.bold)('differs')}, this folder has no record of the server revision`);
+            (0, ui_1.note)((0, ui_1.dim)(`  xflow deploy sends this code on top of revision ${server.revision}; to compare first: xflow pull --into ./server-copy`));
+        }
         else {
             (0, ui_1.out)(`State: ${(0, ui_1.bold)('local changes')}`);
             (0, ui_1.note)((0, ui_1.dim)('  Send and build them: xflow deploy'));

package/dist/help.js

@@ -40,7 +40,7 @@ ${(0, ui_1.bold)('Getting started')}
   xflow init [dir]                new project from the platform template
   xflow templates                 which templates are available
   xflow link <id>                 link this folder to a project, an empty one also gets the sources
-  xflow dev                       run the app on localhost:3000, cloud functions included
+  xflow dev                       run the app on 127.0.0.1:3000, cloud functions included
   xflow skills                    pick the agents that get the platform instructions
   xflow mcp install               give the agent platform access without a terminal
 
@@ -465,6 +465,9 @@ how Yandex works. ${(0, ui_1.bold)('The time is always UTC')}, local time is not
   --payload '{"mode":"full"}'      the body the function will receive
   --payload-file body.json         the same body from a file
 
+${(0, ui_1.bold)('list')} prints that body next to the schedule, so what a timer sends can be read
+back without setting it again.
+
 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
 has to be deployed already, since the schedule points at it and not the other way round.
@@ -538,7 +541,7 @@ is always read by the agent, which is why the pointer is appended there, at the
 the file and once. ${(0, ui_1.bold)('CLAUDE.md')} is left alone: Claude Code reads .claude/skills anyway.`,
     dev: `${(0, ui_1.bold)('xflow dev')}: run the application on this machine
 
-Runs ${(0, ui_1.bold)('npm run dev')} in the project folder (localhost:3000) with the access key of the
+Runs ${(0, ui_1.bold)('npm run dev')} in the project folder (127.0.0.1:3000) with the access key of the
 organization that holds the project. The dev server trades that key for a visitor pass,
 so the cloud functions answer here the way they do on the platform. The key is picked
 as for every other command (${(0, ui_1.bold)('xflow help org')}): with several organizations signed
@@ -551,7 +554,11 @@ The platform address comes from the CLI too, not from .env, so the key goes to t
 platform that issued it and nowhere else. It never reaches the browser: the page gets
 only the ${(0, ui_1.bold)('VITE_')} variables. The project token and the function addresses are
 fetched on every start as well: a function someone else shipped answers here without a
-deploy of yours.`,
+deploy of yours.
+
+The server listens on 127.0.0.1 and nowhere else, because it holds that key: on a
+shared network, anything else would let a neighbour call the functions of the project
+as you. A phone on the same Wi-Fi therefore cannot open it either.`,
     pull: `${(0, ui_1.bold)('xflow pull')}: fetch the sources
 
 By default it fetches the latest revision into the project folder and refuses to write
@@ -580,7 +587,9 @@ ignore field of xflow.json.
 If the server holds a revision newer than the one you worked from, the sources are
 rejected and the build does not start. That means somebody deployed before you: fetch
 their changes alongside (${(0, ui_1.bold)('xflow pull --into ./server-copy')}), merge them in git on
-your side, and retry. ${(0, ui_1.bold)('--force')} overwrites the server revision, and before that the
+your side, and retry. A folder with no record of the server revision (a fresh clone, a CI
+checkout) is not rejected: its first deploy goes on top of the current revision and says
+so, the check applies from the next one. ${(0, ui_1.bold)('--force')} overwrites the server revision, and before that the
 CLI shows whose work you are about to destroy and asks for confirmation by typing the
 project name. In a non-interactive run (CI, an agent) there is no way to confirm: a
 version conflict has to fail the build rather than silently destroy somebody else's work.

package/dist/template.js

@@ -18,7 +18,7 @@ An application on XFlow.
 
 \`\`\`bash
 npm install       # dependencies
-xflow dev         # develop on localhost:3000
+xflow dev         # develop on 127.0.0.1:3000
 xflow deploy      # send the code and build it on the platform
 xflow publish     # show the dev version to visitors
 \`\`\`

package/dist/tree.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isSkillCopy = isSkillCopy;
 exports.loadIgnoreRules = loadIgnoreRules;
 exports.collectFiles = collectFiles;
+exports.syncState = syncState;
 exports.treeHash = treeHash;
 exports.heaviest = heaviest;
 const node_crypto_1 = require("node:crypto");
@@ -130,6 +131,17 @@ function collectFiles(root, rules) {
     files.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     return { files, skippedLinks };
 }
+/**
+ * How the folder stands against the server tree. A folder with no record (a fresh
+ * clone, a CI checkout) has not diverged: nothing is known about what it started from.
+ */
+function syncState(local, server, remembered) {
+    if (local === server)
+        return 'matches';
+    if (remembered === undefined)
+        return 'unrecorded';
+    return remembered === server ? 'local-changes' : 'diverged';
+}
 /** Computed identically on the server. */
 function treeHash(files) {
     const parts = files.map((file) => `${file.path}\0${(0, node_crypto_1.createHash)('sha256').update(file.content).digest('hex')}`);

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.22.0';
+exports.CLI_VERSION = '0.24.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.22.0",
+  "version": "0.24.0",
   "description": "CLI for the XFlow platform: source sync, deployment and publishing of applications",
   "license": "UNLICENSED",
   "engines": {

package/skills/xflow/SKILL.md

@@ -22,7 +22,7 @@ contains the fix.
 
 ## Keeping these instructions current
 
-These instructions ship with xflow CLI 0.22.0, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.24.0, so the copy you are reading can be older than
 the CLI answering your commands.
 
 When the CLI says this file does not match it, run `xflow skills --refresh` and then **read
@@ -108,7 +108,9 @@ one exception is the very first version of a project, which publishes automatica
 `xflow status` says how the local copy differs from the server revision. A deploy rejected
 before the build starts means the server holds a version this folder has never seen: somebody
 deployed first, or the folder was linked elsewhere. Fetch it next to yours (`xflow pull --into
-./server-copy`), merge in git, deploy again. `--force` destroys that work.
+./server-copy`), merge in git, deploy again. `--force` destroys that work. A folder with no
+record of the server revision (a fresh clone, a CI checkout) is not rejected: its first deploy
+goes on top of the current revision and says so, the check applies from the next one.
 
 **Only pages are versioned.** Cloud functions and the database are one per project: they
 are not versioned, and dev and live share them. So `xflow deploy` changes the running
@@ -600,7 +602,9 @@ own devtools.
 
 Run the app locally with `xflow dev`, not a bare `npm run dev`: it hands the dev server
 the key of the project's organization, which cloud functions need to answer, and their
-current addresses, including functions someone else deployed.
+current addresses, including functions someone else deployed. The server answers
+`127.0.0.1` alone, because it holds that key: a phone on the same network cannot open it,
+and neither can anybody else on that network.
 
 ## Environment