@getxflow/cli 0.16.0 → 0.18.0

package/dist/commands/connections.js

@@ -32,6 +32,14 @@ function state(row) {
             return 'linked';
     }
 }
+/**
+ * The names of a connection as they are written in a call, braces and all. Ready to paste:
+ * guessing one costs a real request to somebody's live account, since an unknown name is
+ * left in the text and the request still goes out.
+ */
+function placeholders(row) {
+    return (row.substitutes ?? []).map((name) => `{${name}}`).join(' ');
+}
 function endpoint(projectId) {
     return `/api/v1/projects/${projectId}/connections`;
 }
@@ -69,6 +77,7 @@ async function connectionsList(args) {
         row.label,
         row.connector_key ?? '-',
         row.alias ?? '-',
+        placeholders(row) || '-',
         state(row),
     ]));
     const variables = data.connections.flatMap((row) => row.env);
@@ -76,6 +85,9 @@ async function connectionsList(args) {
         (0, ui_1.note)((0, ui_1.dim)(`  The functions get: ${variables.join(', ')}`));
         (0, ui_1.note)((0, ui_1.dim)('  A change reaches a function on its next deploy: xflow deploy'));
     }
+    if (data.connections.some((row) => placeholders(row))) {
+        (0, ui_1.note)((0, ui_1.dim)('  The fourth column is what a call fills in: xflow connections call <name> <path>'));
+    }
     if (data.connections.some((row) => !row.alias)) {
         (0, ui_1.note)((0, ui_1.dim)('  To link one: xflow connections link <name> --as ALIAS'));
     }

package/dist/commands/deploy.js

@@ -4,8 +4,6 @@ exports.deploy = deploy;
 exports.publish = publish;
 exports.rollback = rollback;
 exports.deployments = deployments;
-const node_fs_1 = require("node:fs");
-const node_path_1 = require("node:path");
 const api_1 = require("../api");
 const args_1 = require("../args");
 const config_1 = require("../config");
@@ -47,21 +45,15 @@ async function waitForBuild(client, projectId, started) {
     throw new errors_1.CliError('The build is taking longer than expected', `To check the state: xflow deployments. Version ${started.deploy_id}`);
 }
 /**
- * Write the function addresses into the local .env.
+ * Point the local .env at this project, function addresses included.
  *
  * The build bakes its own copy of the map into the bundle, this one is for
  * `npm run dev`: without it the local run calls a function that it has no
  * address for.
  */
-async function refreshFunctionsEnv(root, client, projectId) {
+async function refreshPlatformEnv(root, client, projectId) {
     const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}`);
-    // No .env at all (fresh clone): recreate it fully, like link does.
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(root, '.env')) && card.project_token) {
-        (0, node_fs_1.writeFileSync)((0, node_path_1.join)(root, '.env'), (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions), 'utf-8');
-    }
-    else {
-        (0, template_1.writeEnvValue)(root, template_1.FUNCTIONS_ENV_KEY, (0, template_1.functionsEnvValue)(card.functions));
-    }
+    (0, template_1.writePlatformEnv)(root, card.project_token, client.apiUrl, card.functions);
     return card.functions.filter((fn) => fn.invoke_url).map((fn) => fn.name);
 }
 /**
@@ -180,7 +172,7 @@ async function deploy(args) {
     // The functions were shipped by the build itself, so their addresses are known
     // only now. A failure here does not undo a finished build: warn and stop there.
     try {
-        const functions = await refreshFunctionsEnv(root, client, config.projectId);
+        const functions = await refreshPlatformEnv(root, client, config.projectId);
         if (functions.length > 0) {
             (0, ui_1.note)((0, ui_1.dim)(`  Functions in .env: ${functions.join(', ')}`));
         }

package/dist/commands/projects.js

@@ -77,7 +77,7 @@ async function init(args) {
             write(target, file.path, titleFromProject(file.path, file.content, name));
         for (const file of (0, template_1.scaffoldFiles)(name))
             write(target, file.path, file.content);
-        write(target, '.env', (0, template_1.envFile)(project.project_token ?? '', client.apiUrl));
+        (0, template_1.writePlatformEnv)(target, project.project_token, client.apiUrl);
         const config = {
             projectId: project.id,
             build: { command: 'npm run build', dir: 'dist' },
@@ -159,11 +159,8 @@ async function link(args) {
     (0, config_1.ignoreStateInGit)(dir);
     if (client.organizationId)
         (0, config_1.writeState)(dir, { organizationId: client.organizationId });
-    // A fresh clone has no .env: recreate it, never overwrite an existing one.
-    if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, '.env')) && card.project_token) {
-        write(dir, '.env', (0, template_1.envFile)(card.project_token, client.apiUrl, card.functions));
-        (0, ui_1.note)((0, ui_1.dim)('  Created .env with the project token and the function addresses'));
-    }
+    (0, template_1.writePlatformEnv)(dir, card.project_token, client.apiUrl, card.functions);
+    (0, ui_1.note)((0, ui_1.dim)('  .env now points at this project'));
     const skillReady = (0, skills_1.installSkillQuietly)(dir);
     (0, ui_1.ok)(`The folder is linked to the project "${card.name}"`);
     (0, ui_1.note)((0, ui_1.dim)(`  ${(0, node_path_1.join)(dir, config_1.CONFIG_FILE)}`));
@@ -176,7 +173,7 @@ async function link(args) {
     // compare against and stops.
     try {
         const { info, files } = await (0, sources_1.downloadRevision)(client, card.id, dir);
-        (0, config_1.writeState)(dir, { revision: info.revision, treeHash: info.tree_hash });
+        (0, config_1.writeState)(dir, { treeHash: info.tree_hash });
         (0, ui_1.ok)(`Revision ${info.revision}: ${files} files`);
     }
     catch (e) {

package/dist/commands/sources.js

@@ -74,33 +74,32 @@ async function confirmForce(client, projectId, server, local) {
 async function pushSources(root, config, client, options) {
     const tree = prepareTree(root, config);
     const state = (0, config_1.readState)(root);
-    (0, ui_1.step)(`Sending ${tree.files.length} files (${(0, ui_1.formatBytes)(tree.archive.length)})`);
     const server = await latestRevision(client, config.projectId);
-    // Unknown base revision (fresh clone): a matching hash just syncs,
-    // a mismatch must not overwrite silently.
-    if (server && state.revision === undefined && !options.force) {
-        if (server.tree_hash === tree.hash) {
-            (0, config_1.writeState)(root, {
-                revision: server.revision,
-                treeHash: server.tree_hash,
-                organizationId: client.organizationId ?? undefined,
-            });
-            (0, ui_1.ok)(`Already in sync, revision ${server.revision}`);
-            return { revision: server.revision, status: 'unchanged' };
-        }
-        throw new errors_1.CliError(`The server holds revision ${server.revision} while this folder does not remember which version it worked from`, 'Fetch the server copy alongside and compare: xflow pull --into ./server-copy');
+    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);
     }
+    (0, ui_1.step)(`Sending ${tree.files.length} files (${(0, ui_1.formatBytes)(tree.archive.length)})`);
     const headers = {};
-    if (state.revision !== undefined)
-        headers['X-Base-Revision'] = String(state.revision);
+    // Just read from this project: the header only guards the gap until the upload lands.
+    if (server)
+        headers['X-Base-Revision'] = String(server.revision);
     if (options.force)
         headers['X-Force'] = 'true';
     const result = await (0, api_1.apiUpload)(client, `/api/v1/projects/${config.projectId}/push`, tree.archive, headers);
     (0, config_1.writeState)(root, {
-        revision: result.revision,
         treeHash: result.tree_hash,
         organizationId: client.organizationId ?? undefined,
     });
@@ -165,7 +164,6 @@ async function pull(args) {
     // Only the working folder tracks revisions; a side copy (--into) must not reset them.
     if (!into) {
         (0, config_1.writeState)(root, {
-            revision: info.revision,
             treeHash: info.tree_hash,
             organizationId: client.organizationId ?? undefined,
         });
@@ -196,8 +194,8 @@ async function status() {
         if (server.tree_hash === tree.hash) {
             (0, ui_1.out)('State: matches the server');
         }
-        else if (state.revision !== undefined && state.revision < server.revision) {
-            (0, ui_1.out)(`State: ${(0, ui_1.bold)('diverged')}, the server is newer (you worked from ${state.revision})`);
+        else if (server.tree_hash !== state.treeHash) {
+            (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 {

package/dist/config.js

@@ -82,7 +82,9 @@ function readState(root) {
     if (!(0, node_fs_1.existsSync)(path))
         return {};
     try {
-        return JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+        // Read by field, so that keys older versions wrote leave the file on the next write.
+        const { treeHash, organizationId } = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf-8'));
+        return { treeHash, organizationId };
     }
     catch {
         return {};

package/dist/help.js

@@ -372,9 +372,10 @@ the platform into the function.
   xflow connections call <name> <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
-exists in the organization, but this project gets nothing from it yet: link it.
+Every row says whether the connection is linked to this project (its alias), which of
+its fields a call can fill in (${(0, ui_1.bold)('{CLIENT_ID}')} and the like) and what state the
+access is in. ${(0, ui_1.bold)('available, not linked')} is the useful one: the account exists in
+the organization, but this project gets nothing from it yet: link it.
 
 Both commands take the name of the connection, the first column of the list, and both
 also take its identifier. ${(0, ui_1.bold)('unlink')} takes the alias as well, and prefers it: the
@@ -420,10 +421,12 @@ refusal lists them. ${(0, ui_1.bold)('--method')} defaults to GET, or to POST wh
 ${(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.
+agency account, and you never see those values. Which names a connection has is the fourth
+column of ${(0, ui_1.bold)('xflow connections')}, printed in braces and the same whether the account
+is linked or not. Do not derive them from ${(0, ui_1.bold)('xflow env')}: that list is the variables
+of a link, and it names both more and less than this one. A name the connection does not
+have is left in the text as you typed it and the request still goes out, so an invented
+name reaches somebody's live account as text.
 
 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

package/dist/template.js

@@ -1,9 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FUNCTIONS_ENV_KEY = void 0;
-exports.functionsEnvValue = functionsEnvValue;
-exports.envFile = envFile;
-exports.writeEnvValue = writeEnvValue;
+exports.writePlatformEnv = writePlatformEnv;
 exports.scaffoldFiles = scaffoldFiles;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
@@ -32,7 +29,7 @@ tokens from \`src/index.css\` break that consistency.
 Useful: \`xflow status\` for what is on the server, \`xflow deployments\` for version history.
 `;
 /** Function name → URL map, one JSON line. */
-exports.FUNCTIONS_ENV_KEY = 'VITE_XFLOW_FUNCTIONS';
+const FUNCTIONS_ENV_KEY = 'VITE_XFLOW_FUNCTIONS';
 function functionsEnvValue(functions) {
     const map = {};
     for (const fn of functions) {
@@ -41,14 +38,14 @@ function functionsEnvValue(functions) {
     }
     return JSON.stringify(map);
 }
-/** .env is never pushed; xflow link recreates it in a fresh clone. */
-function envFile(projectToken, apiUrl, functions = []) {
-    return [
-        `VITE_XFLOW_PROJECT_TOKEN=${projectToken}`,
-        `VITE_XFLOW_API_URL=${apiUrl.replace(/^https?:\/\//, '')}`,
-        `${exports.FUNCTIONS_ENV_KEY}=${functionsEnvValue(functions)}`,
-        '',
-    ].join('\n');
+/**
+ * Point .env at the current project: written on every link and deploy, so that `npm run dev`
+ * never keeps talking to the previous one. Variables of your own are left alone.
+ */
+function writePlatformEnv(root, projectToken, apiUrl, functions = []) {
+    writeEnvValue(root, 'VITE_XFLOW_PROJECT_TOKEN', projectToken ?? '');
+    writeEnvValue(root, 'VITE_XFLOW_API_URL', apiUrl.replace(/^https?:\/\//, ''));
+    writeEnvValue(root, FUNCTIONS_ENV_KEY, functionsEnvValue(functions));
 }
 /** Update one variable in .env without touching the rest of the file. */
 function writeEnvValue(root, key, value) {

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.16.0';
+exports.CLI_VERSION = '0.18.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.16.0",
+  "version": "0.18.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.16.0. They travel inside the package, so the copy
+These instructions ship with xflow CLI 0.18.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.
 
@@ -122,9 +122,10 @@ the very first version of a project: it publishes automatically, since there is
 live version to protect yet.
 
 `xflow status` says how the local copy differs from the server revision. When a deploy is
-rejected before the build starts, the server revision is newer: somebody deployed first.
-Fetch their work next to yours (`xflow pull --into ./server-copy`), merge it in git, deploy
-again. `--force` destroys their work, a last resort rather than a way around the error.
+rejected before the build starts, the server holds a version this folder has never seen:
+somebody deployed first, or the folder was linked to a different project along the way.
+Fetch the server work next to yours (`xflow pull --into ./server-copy`), merge it in git,
+deploy again. `--force` destroys that work, a last resort rather than a way around the error.
 
 **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
@@ -395,10 +396,11 @@ 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 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
-`{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.
+`{NAME}` in the path or in a header value is filled in from the fields of the connection.
+**Take the names from `xflow connections`**, which prints them in braces for every account,
+linked or not: an invented name is left in the text as you typed it and the request goes out
+anyway, into somebody's live account. `xflow env` is not that list. 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