@getxflow/cli 0.21.0 → 0.23.0

package/dist/commands/db.js

@@ -13,6 +13,7 @@ const args_1 = require("../args");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
+const text_file_1 = require("../text-file");
 const ui_1 = require("../ui");
 /** Migration files live in the repo; the applied history lives in the database. */
 const MIGRATIONS_DIR = 'migrations';
@@ -92,12 +93,18 @@ async function dbStatus(args) {
         (0, ui_1.warn)('A changed file will not be applied again: write a new migration');
     }
 }
+function attachedProjects(database) {
+    const names = database.projects.map((project) => project.name);
+    if (database.hidden_projects > 0)
+        names.push(`+${database.hidden_projects} without access`);
+    return names.length === 0 ? 'no projects' : names.join(', ');
+}
 /**
  * Logical databases of the organization, and who is attached to them.
  *
  * The identifier is what `xflow init --database <id>` asks for, and the list of
- * projects is not decoration: a database is shared, so a migration written for
- * one application lands in the others too.
+ * projects is not decoration: a database can be shared, so a migration written
+ * for one application lands in the others too.
  */
 async function dbList() {
     const client = (0, session_1.connect)((0, config_1.localConfig)());
@@ -111,13 +118,15 @@ async function dbList() {
         database.name,
         database.id,
         database.schema ?? '-',
-        database.projects.length === 0
-            ? 'no projects'
-            : database.projects.map((project) => project.name).join(', '),
+        attachedProjects(database),
     ]));
     if (data.truncated)
         (0, ui_1.note)((0, ui_1.dim)(`  Shown ${data.databases.length} of ${data.total}`));
-    (0, ui_1.note)((0, ui_1.dim)('  One database is shared across projects: a migration affects all of them'));
+    for (const database of data.databases) {
+        const attached = database.projects.length + database.hidden_projects;
+        if (attached > 1)
+            (0, ui_1.note)((0, ui_1.dim)(`  ${database.name} is shared by ${attached} projects: a migration affects all of them`));
+    }
 }
 /** Long values would tear the columns apart; the cut is marked, never silent. */
 const CELL_LIMIT = 60;
@@ -179,9 +188,13 @@ async function dbSchema(args) {
  * database itself rather than by us guessing at the text of the SQL.
  */
 async function dbQuery(args) {
-    const sql = args.words.join(' ').trim();
+    const typed = args.words.join(' ').trim();
+    const sql = /\.sql$/i.test(typed)
+        ? (0, text_file_1.readTextFile)(typed, 'An argument ending in .sql is read as a file: check the path, or end the query with ;')
+        : typed;
     if (!sql) {
-        throw new errors_1.CliError('A query is required', 'For example: xflow db query "select * from orders order by created_at desc limit 20"');
+        throw new errors_1.CliError(typed ? `${typed} is empty` : 'A query is required', 'For example: xflow db query "select * from orders order by created_at desc limit 20", ' +
+            'or a long one from a file outside the project: xflow db query ../report.sql');
     }
     const { projectId, client } = await (0, session_1.projectTarget)(args);
     const data = await (0, api_1.apiJson)(client, `/api/v1/projects/${projectId}/db/query`, {

package/dist/commands/deploy.js

@@ -171,17 +171,20 @@ async function deploy(args) {
     (0, ui_1.out)(build.project_url);
     // 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.
+    let functions = null;
     try {
-        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(', ')}`));
-        }
+        functions = await refreshPlatformEnv(root, client, config.projectId);
     }
     catch {
         (0, ui_1.warn)('Could not refresh the function addresses in .env, the build itself is fine');
     }
-    (0, ui_1.note)((0, ui_1.dim)('  The cloud functions of this build are already live: they are one per project'));
-    (0, ui_1.note)((0, ui_1.dim)('  and are not held back by publishing'));
+    if (functions === null) {
+        (0, ui_1.note)((0, ui_1.dim)('  The cloud functions of this build are already live: publishing does not hold them back'));
+    }
+    else if (functions.length > 0) {
+        (0, ui_1.note)((0, ui_1.dim)(`  Cloud functions live now: ${functions.join(', ')}`));
+        (0, ui_1.note)((0, ui_1.dim)('  There is one copy per project, publishing does not hold them back'));
+    }
     (0, ui_1.note)((0, ui_1.dim)('  Show the new pages to visitors: xflow publish'));
 }
 async function publish(args) {

package/dist/commands/dev.js

@@ -2,11 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.dev = dev;
 const node_os_1 = require("node:os");
+const api_1 = require("../api");
 const config_1 = require("../config");
 const errors_1 = require("../errors");
 const session_1 = require("../session");
 const spawn_1 = require("../spawn");
 const template_1 = require("../template");
+const ui_1 = require("../ui");
 /**
  * The local dev server, handed the key this CLI picks for the project. The template
  * proxy trades it for a pass on every function call, so which organization holds the
@@ -24,6 +26,15 @@ async function dev() {
         // .env: pinned here, the key goes only to the platform that issued it.
         VITE_XFLOW_API_URL: (0, template_1.envApiUrl)(client.apiUrl),
     };
+    // .env only moves on link and deploy: a function someone else shipped, or a new
+    // project token, would reach this run only after one of them.
+    try {
+        const card = await (0, api_1.apiJson)(client, `/api/v1/projects/${config.projectId}`);
+        Object.assign(env, (0, template_1.platformEnv)(card.project_token, client.apiUrl, card.functions));
+    }
+    catch (e) {
+        (0, ui_1.warn)(`The function addresses were not fetched (${e instanceof Error ? e.message : String(e)}): the ones in .env are used`);
+    }
     // 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', () => { });

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

@@ -232,6 +232,7 @@ will work.`,
   xflow db schema [table]          tables of the project, or the columns of one
   xflow db query "select ..."      read data (--limit N: 50 by default, 300 at most;
                                    --json prints the values whole)
+  xflow db query <file>.sql        the same, the query read from a file
   xflow db migrate                 apply migrations/*.sql
 
 ${(0, ui_1.bold)('list')} is about the organization, not about this project: it names the logical
@@ -241,7 +242,9 @@ attached to each one. That last column is the one to read before a migration.
 ${(0, ui_1.bold)('schema')} answers a different question than the ${(0, ui_1.bold)('migrations/')} directory: one logical
 database is shared by several projects, so the files say what you did, and the schema
 says what is actually in there. ${(0, ui_1.bold)('query')} runs inside a READ ONLY transaction, so
-writes are rejected by the database itself, not by us reading your SQL. Its table cuts
+writes are rejected by the database itself, not by us reading your SQL. A query with
+double quotes goes in a .sql file outside the project: Windows PowerShell strips them from
+arguments, and a file in migrations/ would be taken for a migration. Its table cuts
 long values to keep the columns readable; ${(0, ui_1.bold)('--json')} prints them whole, together with
 the applied limit and its ceiling. ${(0, ui_1.bold)('status')} named by id (${(0, ui_1.bold)('--project')}) answers with
 the applied history alone: comparing against ${(0, ui_1.bold)('migrations/')} needs the folder.
@@ -546,7 +549,9 @@ calls fail, or go out under the key of whichever organization is active.
 
 The platform address comes from the CLI too, not from .env, so the key goes to the
 platform that issued it and nowhere else. It never reaches the browser: the page gets
-only the ${(0, ui_1.bold)('VITE_')} variables.`,
+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.`,
     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
@@ -575,7 +580,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/json-arg.js

@@ -5,9 +5,9 @@ exports.jsonHint = jsonHint;
 exports.bodyArg = bodyArg;
 exports.assertJson = assertJson;
 exports.jsonArg = jsonArg;
-const node_fs_1 = require("node:fs");
 const args_1 = require("./args");
 const errors_1 = require("./errors");
+const text_file_1 = require("./text-file");
 /**
  * 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
@@ -59,10 +59,7 @@ function bodyArg(args, flag) {
         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 the body`);
-        }
-        return { text: (0, node_fs_1.readFileSync)(path, 'utf-8').trim(), fromFile: path };
+        return { text: (0, text_file_1.readTextFile)(path, `--${fileFlag} takes the path to a file with the body`), fromFile: path };
     }
     if (inline === undefined)
         return undefined;

package/dist/template.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.envApiUrl = envApiUrl;
+exports.platformEnv = platformEnv;
 exports.writePlatformEnv = writePlatformEnv;
 exports.scaffoldFiles = scaffoldFiles;
 const node_fs_1 = require("node:fs");
@@ -43,14 +44,22 @@ function functionsEnvValue(functions) {
 function envApiUrl(apiUrl) {
     return apiUrl.replace(/^https?:\/\//, '');
 }
+/** The variables that point a local run at the project: written to .env, handed to xflow dev. */
+function platformEnv(projectToken, apiUrl, functions = []) {
+    return {
+        VITE_XFLOW_PROJECT_TOKEN: projectToken ?? '',
+        VITE_XFLOW_API_URL: envApiUrl(apiUrl),
+        [FUNCTIONS_ENV_KEY]: functionsEnvValue(functions),
+    };
+}
 /**
  * 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', envApiUrl(apiUrl));
-    writeEnvValue(root, FUNCTIONS_ENV_KEY, functionsEnvValue(functions));
+    for (const [key, value] of Object.entries(platformEnv(projectToken, apiUrl, functions))) {
+        writeEnvValue(root, key, value);
+    }
 }
 /** Update one variable in .env without touching the rest of the file. */
 function writeEnvValue(root, key, value) {

package/dist/text-file.js

@@ -0,0 +1,23 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readTextFile = readTextFile;
+const node_fs_1 = require("node:fs");
+const node_util_1 = require("node:util");
+const errors_1 = require("./errors");
+/**
+ * A file the agent wrote, whatever the shell saved it in. Windows PowerShell 5.1 writes
+ * UTF-16 with `>` and Out-File, and the code page with Set-Content: read as UTF-8, the
+ * first is garbage and the second turns non-latin text into U+FFFD without a word.
+ */
+function readTextFile(path, missingHint) {
+    if (!(0, node_fs_1.statSync)(path, { throwIfNoEntry: false })?.isFile())
+        throw new errors_1.CliError(`No file ${path}`, missingHint);
+    const bytes = (0, node_fs_1.readFileSync)(path);
+    const encoding = bytes[0] === 0xff && bytes[1] === 0xfe ? 'utf-16le' : 'utf-8';
+    try {
+        return new node_util_1.TextDecoder(encoding, { fatal: true }).decode(bytes).trim();
+    }
+    catch {
+        throw new errors_1.CliError(`${path} is not UTF-8`, 'Save it as UTF-8, in Windows PowerShell: Set-Content -Encoding utf8');
+    }
+}

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.21.0';
+exports.CLI_VERSION = '0.23.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.21.0",
+  "version": "0.23.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.21.0, so the copy you are reading can be older than
+These instructions ship with xflow CLI 0.23.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
@@ -270,7 +272,7 @@ the interface, not a check.
 A function that changes data should say so instead of checking the role by hand:
 
 ```js
-exports.minRole = 'admin'   // 'member' | 'developer' | 'admin' | 'owner'
+exports.minRole = 'developer'   // 'member' | 'developer' | 'owner'
 ```
 
 The wrapper refuses anything below that role before your code runs. Without the line every
@@ -429,8 +431,9 @@ do not see: `xflow db status` lists applied migrations with no file in your repo
 somebody else's project), and `xflow db list` names who else is on yours. For the same reason
 `migrations/` is not the schema. It says what you did; `xflow db schema [table]` says what is in
 the database right now, and `xflow db query "select ..."` reads it inside a READ ONLY
-transaction (50 rows by default, `--limit` up to 300; `--json` prints long values whole). Look
-before you write a migration against a shared database.
+transaction (50 rows by default, `--limit` up to 300; `--json` prints long values whole). A query
+with double quotes goes in a `.sql` file outside the project, `xflow db query ../q.sql`: PowerShell
+strips them from arguments. Look before you write a migration against a shared database.
 
 ## File storage
 
@@ -598,7 +601,8 @@ A local run does not report anything: these logs exist for what you cannot open
 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.
+the key of the project's organization, which cloud functions need to answer, and their
+current addresses, including functions someone else deployed.
 
 ## Environment